4.1.1. Constructor
4.1.1. Constructor
The PeerConnection constructor allows the application to specify global parameters for the media session, such as the STUN/TURN servers and credentials to use when gathering candidates, as well as the initial ICE candidate policy and pool size, and also the bundle policy to use.
If an ICE candidate policy is specified, it functions as described in Section 3.5.3, causing the JSEP implementation to only surface the permitted candidates (including any implementation-internal filtering) to the application and only use those candidates for connectivity checks. The set of available policies is as follows:
all: All candidates permitted by implementation policy will be gathered and used.
relay: All candidates except relay candidates will be filtered out. This obfuscates the location information that might be ascertained by the remote peer from the received candidates. Depending on how the application deploys and chooses relay servers, this could obfuscate location to a metro or possibly even global level.
The default ICE candidate policy MUST be set to "all", as this is generally the desired policy and also typically reduces the use of application TURN server resources significantly.
If a size is specified for the ICE candidate pool, this indicates the number of ICE components to pre-gather candidates for. Because pre-gathering results in utilizing STUN/TURN server resources for potentially long periods of time, this MUST only occur upon application request, and therefore the default candidate pool size MUST be zero.
The application can specify its preferred policy regarding use of bundle, the multiplexing mechanism defined in [RFC8843]. Regardless of policy, the application will always try to negotiate bundle onto a single transport and will offer a single bundle group across all "m=" sections; use of this single transport is contingent upon the answerer accepting bundle. However, by specifying a policy from the list below, the application can control exactly how aggressively it will try to bundle media streams together, which affects how it will interoperate with a non-bundle-aware endpoint. When negotiating with a non-bundle-aware endpoint, only the streams not marked as bundle-only streams will be established.
The set of available policies is as follows:
balanced: The first "m=" section of each type (audio, video, or application) will contain transport parameters, which will allow an answerer to unbundle that section. The second and any subsequent "m=" sections of each type will be marked bundle-only. The result is that if there are N distinct media types, then candidates will be gathered for N media streams. This policy balances desire to multiplex with the need to ensure that basic audio and video can still be negotiated in legacy cases. When acting as answerer, if there is no bundle group in the offer, the implementation will reject all but the first "m=" section of each type.
max-compat: All "m=" sections will contain transport parameters; none will be marked as bundle-only. This policy will allow all streams to be received by non-bundle-aware endpoints but will require separate candidates to be gathered for each media stream.
max-bundle: Only the first "m=" section will contain transport parameters; all streams other than the first will be marked as bundle-only. This policy aims to minimize candidate gathering and maximize multiplexing, at the cost of less compatibility with legacy endpoints. When acting as answerer, the implementation will reject any "m=" sections other than the first "m=" section, unless they are in the same bundle group as that "m=" section.
As it provides the best trade-off between performance and compatibility with legacy endpoints, the default bundle policy MUST be set to "balanced".
The application can specify its preferred policy regarding use of RTP/RTCP multiplexing [RFC5761] using one of the following policies:
negotiate: The JSEP implementation will gather both RTP and RTCP candidates but also will offer "a=rtcp-mux", thus allowing for compatibility with either multiplexing or non-multiplexing endpoints.
require: The JSEP implementation will only gather RTP candidates and will insert an "a=rtcp-mux-only" indication into any new "m=" sections in offers it generates. This halves the number of candidates that the offerer needs to gather. Applying a description with an "m=" section that does not contain an "a=rtcp-mux" attribute will cause an error to be returned.
The default multiplexing policy MUST be set to "require". Implementations MAY choose to reject attempts by the application to set the multiplexing policy to "negotiate".