diff --git a/README.md b/README.md index e084d6587..9c9dd99d4 100644 --- a/README.md +++ b/README.md @@ -706,242 +706,165 @@ The request dictionary must contain at least the following keys: Optionally included keys are: -* `from-tags` - - Contains a list of strings used to selected multiple existing call - participants (e.g. for the `subscribe request` message). An alternative - way to list multiple tags is by putting them into the `flags` list, - each prefixed with `from-tags-`. - -* `via-branch` - - The SIP `Via` branch as string. Used to additionally refine the matching logic between media streams - and calls and call branches. - -* `label` or `from-label` - - A custom free-form string which *rtpengine* remembers for this participating endpoint and reports - back in logs and statistics output. For some commands (e.g. `block media`) the given label is not - used to set the label of the call participant, but rather to select an existing call participant. - -* `set-label` - - Some commands (e.g. `block media`) use the given `label` to select - an existing call participant. For these commands, `set-label` instead - of `label` can be used to set the label at the same time, either for - the selected call participant (if selected via `from-tag`) or for the - newly created participant (e.g. for `subscribe request`). - -* `to-label` - - Commands that allow selection of two call participants (e.g. `block - media`) can use `label` instead of `from-tag` to select the first call - participant. The `to-label` can then be used instead of `to-tag` to - select the other call participant. - - For `subscribe request` the `to-label` is synonymous with `set-label`. - -* `flags` - - The value of the `flags` key is a list. The list contains zero or more of the following strings. - Spaces in each string may be replaced by hyphens. - - - `SIP source address` - - Ignore any IP addresses given in the SDP body and use the source address of the received - SIP message (given in `received from`) as default endpoint address. This was the default - behaviour of older versions of *rtpengine* and can still be made the default behaviour - through the `--sip-source` CLI switch. - Can be overridden through the `media address` key. - - - `trust address` - - The opposite of `SIP source address`. This is the default behaviour unless the CLI switch - `--sip-source` is active. Corresponds to the *rtpproxy* `r` flag. - Can be overridden through the `media address` key. - - - `symmetric` - - Corresponds to the *rtpproxy* `w` flag. Not used by *rtpengine* as this is the default, - unless `asymmetric` is specified. - - - `asymmetric` - - Corresponds to the *rtpproxy* `a` flag. Advertises an RTP endpoint which uses asymmetric - RTP, which disables learning of endpoint addresses (see below). - - - `unidirectional` - - When this flag is present, kernelize also one-way rtp media. - - - `strict source` - - Normally, *rtpengine* attempts to learn the correct endpoint address for every stream during - the first few seconds after signalling by observing the source address and port of incoming - packets (unless `asymmetric` is specified). Afterwards, source address and port of incoming - packets are normally ignored and packets are forwarded regardless of where they're coming from. - With the `strict source` option set, *rtpengine* will continue to inspect the source address - and port of incoming packets after the learning phase and compare them with the endpoint - address that has been learned before. If there's a mismatch, the packet will be dropped and - not forwarded. - - - `media handover` - - Similar to the `strict source` option, but instead of dropping packets when the source address - or port don't match, the endpoint address will be re-learned and moved to the new address. This - allows endpoint addresses to change on the fly without going through signalling again. Note that - this opens a security hole and potentially allows RTP streams to be hijacked, either partly or - in whole. - - - `reset` - - This causes *rtpengine* to un-learn certain aspects of the RTP endpoints involved, such as - support for ICE or support for SRTP. For example, if `ICE=force` is given, then *rtpengine* - will initially offer ICE to the remote endpoint. However, if a subsequent answer from that - same endpoint indicates that it doesn't support ICE, then no more ICE offers will be made - towards that endpoint, even if `ICE=force` is still specified. With the `reset` flag given, - this aspect will be un-learned and *rtpengine* will again offer ICE to this endpoint. - This flag is valid only in an `offer` message and is useful when the call has been - transferred to a new endpoint without change of `From` or `To` tags. +* `all` - - `port latching` + Can be set to the string `none` to disable any extra behaviour (which + is the default if this key is omitted altogether) or to one of `all`, + `offer-answer`, `except-offer-answer` or `flows`. Applicable to + certain messages only. The behaviour is explained below separately for + each affected message. - Forces *rtpengine* to retain its local ports during a signalling exchange even when the - remote endpoint changes its port. +* `address family` - - `no port latching` + A string value of either `IP4` or `IP6` to select the primary address family in the substituted SDP + body. The default is to auto-detect the address family if possible (if the receiving end is known + already) or otherwise to leave it unchanged. - Port latching is enabled by default for endpoints which speak - ICE. With this option preset, a remote port change will result - in a local port change even for endpoints which speak ICE, - which will imply an ICE restart. +* `delay-buffer` - - `record call` + Takes an integer as value. When set to non-zero, enables the delay + buffer when setting up codec handlers. The delay buffer delays all + media by the given number of milliseconds before passing it on. Once + the delay buffer is configured, it must explicitly be disabled again by + setting this value to zero. The delay buffer setting is honoured in all + messages that set up codec handlers, such as `block DTMF`. - Identical to setting `record call` to `on` (see below). +* `direction` - - `no rtcp attribute` + Contains a list of two strings and corresponds to the *rtpproxy* `e` and `i` flags. Each element must + correspond to one of the named logical interfaces configured on the + command line (through `--interface`). For example, if there is one logical interface named `pub` and + another one named `priv`, then if side A (originator of the message) is considered to be + on the private network and side B (destination of the message) on the public network, then that would + be rendered within the dictionary as: - Omit the `a=rtcp` line from the outgoing SDP. + { ..., "direction": [ "priv", "pub" ], ... } - - `full rtcp attribute` + This only needs to be done for an initial `offer`; for the `answer` and any subsequent offers (between + the same endpoints) *rtpengine* will remember the selected network interface. - Include the full version of the `a=rtcp` line (complete with network address) instead of - the short version with just the port number. + As a special case to support legacy usage of this option, if the given interface names are + `internal` or `external` and if no such interfaces have been configured, then they're understood as + selectors between IPv4 and IPv6 addresses. + However, this mechanism for selecting the address family is now obsolete + and the `address family` dictionary key should be used instead. - - `loop protect` + For legacy support, the special direction keyword `round-robin-calls` can be used to invoke the + round-robin interface selection algorithm described in the section *Interfaces configuration*. + If this special keyword is used, the round-robin selection will run over all configured + interfaces, whether or not they are configured using the `BASE:SUFFIX` interface name notation. + This special keyword is provided only for legacy support and should be considered obsolete. + It will be removed in future versions. - Inserts a custom attribute (`a=rtpengine:...`) into the outgoing SDP to prevent *rtpengine* - processing and rewriting the same SDP multiple times. This is useful if your setup - involves signalling loops and need to make sure that *rtpengine* doesn't start looping - media packets back to itself. When this flag is present and *rtpengine* sees a matching - attribute already present in the SDP, it will leave the SDP untouched and not process - the message. +* `digit` or `code` - - `always transcode` + Sets the replacement digit for `DTMF-security=DTMF`. - Legacy flag, synonymous to `codec-accept=all`. +* `drop-traffic` - - `single codec` + Contains a string, valid values are `start` or `stop`. - Using this flag in an `answer` message will leave only the first listed codec in place - and will remove all others from the list. Useful for RTP clients which get confused if - more than one codec is listed in an answer. + `start` signals to *rtpengine* that all RTP involved in this call is dropped. + Can be present either in `offer` or `answer`, the behavior is for the entire call. - - `reuse codecs` or `no codec renegotiation` + `stop` signals to *rtpengine* that all RTP involved in this call is NOT dropped anymore. + Can be present either in `offer` or `answer`, the behavior is for the entire call. - Instructs *rtpengine* to prevent endpoints from switching codecs during call run-time - if possible. Codecs that were listed as preferred in the past will be kept as preferred - even if the re-offer lists other codecs as preferred, or in a different order. Recommended - to be combined with `single codec`. + `stop` has priority over `start`, if both are present. - - `allow transcoding` +* `DTLS` - This flag is only useful in commands that provide an explicit answer SDP to *rtpengine* - (e.g. `subscribe answer`). For these commands, if the answer SDP does not accept all - codecs that were offered, the default behaviour is to reject the answer. With this flag - given, the answer will be accepted even if some codecs were rejected, and codecs will be - transcoded as required. + Contains a string and influences the behaviour of DTLS-SRTP. Possible values are: - - `all` + - `off` or `no` or `disable` - Synonymous to `all=all` (see below). + Prevents *rtpengine* from offering or acceping DTLS-SRTP when otherwise it would. The default + is to offer DTLS-SRTP when encryption is desired and to favour it over SDES when accepting + an offer. - - `pad crypto` + - `passive` - Legacy alias to SDES=pad. + Instructs *rtpengine* to prefer the passive (i.e. server) role for the DTLS + handshake. The default is to take the active (client) role if possible. This is useful in cases + where the SRTP endpoint isn't able to receive or process the DTLS handshake packets, for example + when it's behind NAT or needs to finish ICE processing first. - - `generate mid` + - `active` - Add `a=mid` attributes to the outgoing SDP if they were not already present. + Reverts the `passive` setting. Only useful if the `dtls-passive` config option is set. - - `strip extmap` +* `DTLS-reverse` - Remove `a=rtpmap` attributes from the outgoing SDP. + Contains a string and influences the behaviour of DTLS-SRTP. Unlike the regular `DTLS` flag, this one + is used to control behaviour towards DTLS that was offered to *rtpengine*. In particular, if `passive` + mode is used, it prevents *rtpengine* from prematurely sending active DTLS connection attempts. + Possible values are: - - `original sendrecv` + - `passive` - With this flag present, *rtpengine* will leave the media direction attributes - (`sendrecv`, `recvonly`, `sendonly`, and `inactive`) from the received SDP body - unchanged. Normally *rtpengine* would consume these attributes and insert its - own version of them based on other media parameters (e.g. a media section with - a zero IP address would come out as `sendonly` or `inactive`). + Instructs *rtpengine* to prefer the passive (i.e. server) role for the DTLS + handshake. The default is to take the active (client) role if possible. This is useful in cases + where the SRTP endpoint isn't able to receive or process the DTLS handshake packets, for example + when it's behind NAT or needs to finish ICE processing first. - - `inject DTMF` + - `active` - Signals to *rtpengine* that the audio streams involved in this `offer` or `answer` - (the flag should be present in both of them) are to be made available for DTMF - injection via the `play DTMF` control message. See `play DTMF` below for additional - information. + Reverts the `passive` setting. Only useful if the `dtls-passive` config option is set. - - `detect DTMF` +* `DTLS-fingerprint` - When present in a message that sets up codec handlers, enables - the DSP to detect in-band DTMF audio tones even when it - wouldn't otherwise be necessary. + Contains a string and is used to select the hashing function to generate the DTLS fingerprint + from the certificate. The default is SHA-256, or the same hashing function as was used by the + peer. Available are `SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. - - `generate RTCP` +* `DTMF-security` - Identical to setting `generate RTCP = on`. + Used in the `block DTMF` message to select the DTMF blocking mode. The + default mode is `drop` which simply drops DTMF event packets. The other + supported modes are: `silence` which replaces DTMF events with silence + audio; `tone` which replaces DTMF events with a single sine wave tone; + `random` which replaces DTMF events with random other DTMF events (both + in-band DTMF audio tones and RFC event packets); `zero` which is + similar to `random` except that a zero event is always used; `DTMF` + which is similar to `zero` except that a different DTMF digit can be + specified; `off` to disable DTMF blocking. - - `RTCP mirror` +* `DTMF-security-trigger` - Useful only for `subscribe request` message. Instructs - *rtpengine* to not only create a one-way subscription for both - RTP and RTCP from the source to the sink, but also create a - reverse subscription for RTCP only from the sink back to the - source. This makes it possible for the media source to receive - feedback from all media receivers (sinks). + Blocking mode to enable when the DTMF `trigger` (see below) is detected. - - `debug` or `debugging` +* `DTMF-security-trigger-end` - Enabled full debug logging for this call, regardless of global log level settings. + Blocking mode to enable when the DTMF `end trigger` (see below) is + detected. - - `pierce NAT` +* `DTMF-delay` - Sends empty UDP packets to the remote RTP peer as soon as an - endpoint address is available from a received SDP, for as long - as no incoming packets have been received. Useful to create an - initial NAT mapping. Not needed when ICE is in use. + Time in milliseconds to delay DTMF events (both RFC event packets and + DTMF tones) for. With this option enabled (set to non-zero), DTMF + events are initially replaced by silence and then subsequently + reproduced after the given delay. DTMF blocking modes are honoured at + the time when the DTMF events are reproduced. - - `NAT-wait` +* `endpoint-learning` - Prevents forwarding media packets to the respective endpoint - until at least one media packet has been received from that - endpoint. This is to allow a NAT binding to open in the ingress - direction before sending packets out, which could result in an - automated firewall block. + Contains one of the strings `off`, `immediate`, `delayed` or `heuristic`. This tells rtpengine which endpoint learning algorithm to use and overrides the `endpoint-learning` configuration option. This option can also be put into the `flags` list using a prefix of `endpoint-learning-`. - - `trickle ICE` +* `frequency` or `frequencies` - Useful for `offer` messages when ICE is advertised to also advertise - support for trickle ICE. + Sets the tone frequency or frequencies for `DTMF-security=tone` in Hertz. + The default is a single frequency of 400 Hz. A list of frequencies can be + given either as a list object, or as a string containing a comma-separated + list of integers. The given frequencies will be picked from the list in + order, one for each DTMF event detected, and will be repeated once the end + of the list is reached. - - `reject ICE` +* `from-tags` - Useful for `offer` messages that advertise support for ICE. - Instructs *rtpengine* to reject the offered ICE. This is - similar to using `ICE=remove` in the respective `answer`. + Contains a list of strings used to selected multiple existing call + participants (e.g. for the `subscribe request` message). An alternative + way to list multiple tags is by putting them into the `flags` list, + each prefixed with `from-tags-`. * `generate RTCP` @@ -951,101 +874,6 @@ Optionally included keys are: RTCP packets to send to the RTP peers. This flag will be effective for both sides of a call. -* `replace` - - Similar to the `flags` list. Controls which parts of the SDP body should be rewritten. - Contains zero or more of: - - - `origin` - - Replace the address found in the *origin* (o=) line of the SDP body. Corresponds - to *rtpproxy* `o` flag. - - - `session connection` or `session-connection` - - Replace the address found in the *session-level connection* (c=) line of the SDP body. - Corresponds to *rtpproxy* `c` flag. - - - `SDP version` or `SDP-version` - - Take control of the version field in the SDP and make sure it's increased every - time the SDP changes, and left unchanged if the SDP is the same. - - - `force-increment-sdp-ver` - - Force increasing the SDP version, even if the SDP hasn't been changed. - - - `username` - - Take control of the origin username field in the SDP. With this - option in use, *rtpengine* will make sure the username field in - the `o=` line always remains the same in all SDPs going to a - particular RTP endpoint. - - - `session name` or `session-name` - - Same as `username` but for the entire contents of the `s=` line. - - - `zero address` - - Using a zero endpoint address is an obsolete way to signal a - muted or sendonly stream. Streams with zero addresses are - normally flagged as sendonly and the zero address in the SDP is - passed through. With this option set, the zero address is - replaced with a real address. - -* `direction` - - Contains a list of two strings and corresponds to the *rtpproxy* `e` and `i` flags. Each element must - correspond to one of the named logical interfaces configured on the - command line (through `--interface`). For example, if there is one logical interface named `pub` and - another one named `priv`, then if side A (originator of the message) is considered to be - on the private network and side B (destination of the message) on the public network, then that would - be rendered within the dictionary as: - - { ..., "direction": [ "priv", "pub" ], ... } - - This only needs to be done for an initial `offer`; for the `answer` and any subsequent offers (between - the same endpoints) *rtpengine* will remember the selected network interface. - - As a special case to support legacy usage of this option, if the given interface names are - `internal` or `external` and if no such interfaces have been configured, then they're understood as - selectors between IPv4 and IPv6 addresses. - However, this mechanism for selecting the address family is now obsolete - and the `address family` dictionary key should be used instead. - - For legacy support, the special direction keyword `round-robin-calls` can be used to invoke the - round-robin interface selection algorithm described in the section *Interfaces configuration*. - If this special keyword is used, the round-robin selection will run over all configured - interfaces, whether or not they are configured using the `BASE:SUFFIX` interface name notation. - This special keyword is provided only for legacy support and should be considered obsolete. - It will be removed in future versions. - -* `interface` - - Contains a single string naming one of the configured interfaces, just like `direction` does. The - `interface` option is used instead of `direction` where only one interface is required (e.g. outside - of an offer/answer scenario), for example in the `publish` or `subscribe request` commands. - -* `received from` - - Contains a list of exactly two elements. The first element denotes the address family and the second - element is the SIP message's source address itself. The address family can be one of `IP4` or `IP6`. - Used if SDP addresses are neither trusted (through `SIP source address` or `--sip-source`) nor the - `media address` key is present. - -* `drop-traffic` - - Contains a string, valid values are `start` or `stop`. - - `start` signals to *rtpengine* that all RTP involved in this call is dropped. - Can be present either in `offer` or `answer`, the behavior is for the entire call. - - `stop` signals to *rtpengine* that all RTP involved in this call is NOT dropped anymore. - Can be present either in `offer` or `answer`, the behavior is for the entire call. - - `stop` has priority over `start`, if both are present. - * `ICE` Contains a string which must be one of the following values: @@ -1092,22 +920,17 @@ Optionally included keys are: The default (keyword not present at all) is to use full ICE support, or to leave the previously set "ICE lite" mode unchanged. This keyword is valid in `offer` messages only. -* `transport protocol` +* `interface` - The transport protocol specified in the SDP body is to be rewritten to the string value given here. - The media - proxy will expect to receive this protocol on the allocated ports, and will talk this protocol when - sending packets out. Translation between different transport protocols will happen as necessary. + Contains a single string naming one of the configured interfaces, just like `direction` does. The + `interface` option is used instead of `direction` where only one interface is required (e.g. outside + of an offer/answer scenario), for example in the `publish` or `subscribe request` commands. - Valid values are: `RTP/AVP`, `RTP/AVPF`, `RTP/SAVP`, `RTP/SAVPF`. +* `label` or `from-label` - Additionally the string `accept` can be given in `answer` messages to allow a special case: By - default (when no `transport-protocol` override is given) in answer messages, *rtpengine* will - use the transport protocol that was originally offered. However, an answering client may answer - with a different protocol than what was offered (e.g. offer was for `RTP/AVP` and answer comes - with `RTP/AVPF`). The default behaviour for *rtpengine* is to ignore this protocol change and - still proceed with the protocol that was originally offered. Using the `accept` option here - tells *rtpengine* to go along with this protocol change and pass it to the original offerer. + A custom free-form string which *rtpengine* remembers for this participating endpoint and reports + back in logs and statistics output. For some commands (e.g. `block media`) the given label is not + used to set the label of the call participant, but rather to select an existing call participant. * `media address` @@ -1116,11 +939,101 @@ Optionally included keys are: string. The format must be dotted-quad notation for IPv4 or RFC 5952 notation for IPv6. It's up to the RTP proxy to determine the address family type. -* `address family` +* `media echo` or `media-echo` - A string value of either `IP4` or `IP6` to select the primary address family in the substituted SDP - body. The default is to auto-detect the address family if possible (if the receiving end is known - already) or otherwise to leave it unchanged. + Contains a string to enable a special media echo mode. Recognised values are: + + - `blackhole` or `sinkhole` + + Media arriving from either side of the call is simply discarded + and not forwarded. + + - `forward` + + Enables media echo towards the receiver of this message (e.g. + the called party if the message is an `offer` from the caller). + Media arriving from that side is echoed back to its sender + (with a new SSRC if it's RTP). Media arriving from the opposite + side is discarded. + + - `backwards` + + Enables media echo towards the sender of this message (i.e. the + opposite of `forward`). Media arriving from the other side is + discarded. + + - `both` + + Enables media echo towards both the sender and the receiver of + this message. + +* `metadata` + + This is a generic metadata string. The metadata will be written to the bottom of + metadata files within `/path/to/recording_dir/metadata/` or to + `recording_metakeys` table. In the latter case, `metadata` string must + contain a list of `key:val` pairs separated by `|` character. `metadata` can be used to + record additional information about recorded calls. `metadata` values passed in + through subsequent messages will overwrite previous metadata values. + + See the `--recording-dir` option above. + +* `OSRTP` + + Similar to `SDES` but controls OSRTP behaviour. Default behaviour is to pass through + OSRTP negotiations. Supported options: + + - `offer` + + When processing a non-OSRTP offer, convert it to an OSRTP offer. Will result + in RTP/SRTP transcoding if the OSRTP offer is accepted. + + - `accept` + + When processing a non-OSRTP answer in response to an OSRTP offer, accept the + OSRTP offer anyway. Results in RTP/SRTP transcoding. + +* `ptime` + + Contains an integer. If set, changes the `a=ptime` attribute's value in the outgoing + SDP to the provided value. It also engages the transcoding engine for supported codecs + to provide repacketization functionality, even if no additional codec has actually + been requested for transcoding. Note that not all codecs support all packetization + intervals. + + The selected ptime (which represents the duration of a single media packet in milliseconds) + will be used towards the endpoint receiving this offer, even if the matching answer + prefers a different ptime. + + This option is ignored in `answer` messages. See below for the reverse. + +* `ptime-reverse` + + This is the reciprocal to `ptime`. It sets the ptime to be used towards the endpoint + who has sent the offer. It will be inserted in the `answer` SDP. This option is also + ignored in `answer` messages. + +* `received from` + + Contains a list of exactly two elements. The first element denotes the address family and the second + element is the SIP message's source address itself. The address family can be one of `IP4` or `IP6`. + Used if SDP addresses are neither trusted (through `SIP source address` or `--sip-source`) nor the + `media address` key is present. + +* `record call` + + Contains one of the strings `yes`, `no`, `on` or `off`. This tells the rtpengine + whether or not to record the call to PCAP files. If the call is recorded, it + will generate PCAP files for each stream and a metadata file for each call. + Note that rtpengine *will not* force itself into the media path, and other + flags like `ICE=force` may be necessary to ensure the call is recorded. + + See the `--recording-dir` option above. + + Enabling call recording via this option has the same effect as doing it separately + via the `start recording` message, except that this option guarantees that the + entirety of the call gets recorded, including all details such as SDP bodies + passing through *rtpengine*. * `rtcp-mux` @@ -1153,57 +1066,18 @@ Optionally included keys are: Reject rtcp-mux if it has been offered. Can be used together with `offer` to achieve the opposite effect of `demux`. -* `TOS` - - Contains an integer. If present, changes the TOS value for the entire call, i.e. the TOS value used - in outgoing RTP packets of all RTP streams in all directions. If a negative value is used, the previously - used TOS value is left unchanged. If this key is not present or its value is too large (256 or more), then - the TOS value is reverted to the default (as per `--tos` command line). - -* `DTLS` - - Contains a string and influences the behaviour of DTLS-SRTP. Possible values are: - - - `off` or `no` or `disable` - - Prevents *rtpengine* from offering or acceping DTLS-SRTP when otherwise it would. The default - is to offer DTLS-SRTP when encryption is desired and to favour it over SDES when accepting - an offer. - - - `passive` - - Instructs *rtpengine* to prefer the passive (i.e. server) role for the DTLS - handshake. The default is to take the active (client) role if possible. This is useful in cases - where the SRTP endpoint isn't able to receive or process the DTLS handshake packets, for example - when it's behind NAT or needs to finish ICE processing first. - - - `active` - - Reverts the `passive` setting. Only useful if the `dtls-passive` config option is set. - -* `DTLS-reverse` - - Contains a string and influences the behaviour of DTLS-SRTP. Unlike the regular `DTLS` flag, this one - is used to control behaviour towards DTLS that was offered to *rtpengine*. In particular, if `passive` - mode is used, it prevents *rtpengine* from prematurely sending active DTLS connection attempts. - Possible values are: - - - `passive` - - Instructs *rtpengine* to prefer the passive (i.e. server) role for the DTLS - handshake. The default is to take the active (client) role if possible. This is useful in cases - where the SRTP endpoint isn't able to receive or process the DTLS handshake packets, for example - when it's behind NAT or needs to finish ICE processing first. - - - `active` +* `via-branch` - Reverts the `passive` setting. Only useful if the `dtls-passive` config option is set. + The SIP `Via` branch as string. Used to additionally refine the matching logic between media streams + and calls and call branches. -* `DTLS-fingerprint` +* `set-label` - Contains a string and is used to select the hashing function to generate the DTLS fingerprint - from the certificate. The default is SHA-256, or the same hashing function as was used by the - peer. Available are `SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. + Some commands (e.g. `block media`) use the given `label` to select + an existing call participant. For these commands, `set-label` instead + of `label` can be used to set the label at the same time, either for + the selected call participant (if selected via `from-tag`) or for the + newly created participant (e.g. for `subscribe request`). * `SDES` @@ -1306,238 +1180,88 @@ Optionally included keys are: `=` characters used for padding should be omitted. With this flag set, these padding characters will be left in place. - - `lifetime` - - Add the key lifetime parameter `2^31` to each crypto key. - - - `static` - - Instructs *rtpengine* to skip the full SDES negotiation routine during a re-invite - (e.g. pick the first support crypto suite, look for possible SRTP passthrough) - and instead leave the previously negotiated crypto suite in place. Only useful in - subsequent `answer` messages and ignored in `offer` messages. - -* `OSRTP` - - Similar to `SDES` but controls OSRTP behaviour. Default behaviour is to pass through - OSRTP negotiations. Supported options: - - - `offer` - - When processing a non-OSRTP offer, convert it to an OSRTP offer. Will result - in RTP/SRTP transcoding if the OSRTP offer is accepted. - - - `accept` - - When processing a non-OSRTP answer in response to an OSRTP offer, accept the - OSRTP offer anyway. Results in RTP/SRTP transcoding. - -* `endpoint-learning` - - Contains one of the strings `off`, `immediate`, `delayed` or `heuristic`. This tells rtpengine which endpoint learning algorithm to use and overrides the `endpoint-learning` configuration option. This option can also be put into the `flags` list using a prefix of `endpoint-learning-`. - -* `record call` - - Contains one of the strings `yes`, `no`, `on` or `off`. This tells the rtpengine - whether or not to record the call to PCAP files. If the call is recorded, it - will generate PCAP files for each stream and a metadata file for each call. - Note that rtpengine *will not* force itself into the media path, and other - flags like `ICE=force` may be necessary to ensure the call is recorded. - - See the `--recording-dir` option above. + - `lifetime` - Enabling call recording via this option has the same effect as doing it separately - via the `start recording` message, except that this option guarantees that the - entirety of the call gets recorded, including all details such as SDP bodies - passing through *rtpengine*. + Add the key lifetime parameter `2^31` to each crypto key. -* `metadata` + - `static` - This is a generic metadata string. The metadata will be written to the bottom of - metadata files within `/path/to/recording_dir/metadata/` or to - `recording_metakeys` table. In the latter case, `metadata` string must - contain a list of `key:val` pairs separated by `|` character. `metadata` can be used to - record additional information about recorded calls. `metadata` values passed in - through subsequent messages will overwrite previous metadata values. + Instructs *rtpengine* to skip the full SDES negotiation routine during a re-invite + (e.g. pick the first support crypto suite, look for possible SRTP passthrough) + and instead leave the previously negotiated crypto suite in place. Only useful in + subsequent `answer` messages and ignored in `offer` messages. - See the `--recording-dir` option above. +* `supports` -* `codec` - - Contains a dictionary controlling various aspects of codecs (or RTP payload types). - - These options can also be put into the `flags` list using a prefix of `codec-`. For example, - to set the codec options for two variants of Opus when they're implicitly accepted, (see - the example under `set`), one would put the following into the `flags` list: - `codec-set-opus/48000/1/16000` `codec-set-opus/48000/2/32000` - - The following keys are understood: - - * `strip` - - Contains a list of strings. Each string is the name of a codec or RTP payload - type that should be removed from the SDP. Codec names are case sensitive, and - can be either from the list of codecs explicitly defined by the SDP through - an `a=rtpmap` attribute, or can be from the list of RFC-defined codecs. Examples - are `PCMU`, `opus`, or `telephone-event`. Codecs stripped using this option - are treated as if they had never been in the SDP. - - It is possible to specify codec format parameters alongside with the codec name - in the same format as they're written in SDP for codecs that support them, - for example `opus/48000` to - specify Opus with 48 kHz sampling rate and one channel (mono), or - `opus/48000/2` for stereo Opus. If any format parameters are specified, - the codec will only be stripped if all of the format parameters match, and other - instances of the same codec with different format parameters will be left - untouched. + Contains a list of strings. Each string indicates support for an additional feature + that the controlling SIP proxy supports. Currently defined values are: - As a special keyword, `all` can be used to remove all codecs, except the ones - that should explicitly offered (see below). Note that it is an error to strip - all codecs and leave none that could be offered. In this case, the original - list of codecs will be left unchanged. - - The keyword `full` can also be used, which behaves the same as `all` with the - exception listed under `transcode` below. - - * `except` - - Contains a list of strings. Each string is the name of a codec that should be - included in the list of codecs offered. This is primarily useful to block all - codecs (`strip -> all` or `mask -> all`) except the ones given in the `except` - whitelist. Codecs that were not present in the original list of codecs - offered by the client will be ignored. - - This list also supports codec format parameters as per above. - - * `offer` - - This is identical to `except` but additionally allows the codec order to be - changed. So the first codec listed in `offer` will be the primary (preferred) - codec in the output SDP, even if it wasn't originally so. - - * `transcode` - - Similar to `offer` but allows codecs to be added to the list of offered codecs - even if they were not present in the original list of codecs. In this case, - the transcoding engine will be engaged. Only codecs that are supported for both - decoding and encoding can be added in this manner. This also has the side effect - of automatically stripping all unsupported codecs from the list of offered codecs, - as *rtpengine* must expect to receive or even send in any codec that is present - in the list. + * `load limit` - Note that using this option does not necessarily always engage the transcoding - engine. If all codecs given in the `transcode` list were present in the original - list of offered codecs, then no transcoding will be done. Also note that if - transcoding takes place, in-kernel forwarding is disabled for this media stream - and all processing happens in userspace. + Indicates support for an extension to the *ng* protocol to facilitate certain load + balancing mechanisms. If *rtpengine* is configured with certain session or load + limit options enabled (such as the `max-sessions` option), then normally *rtpengine* + would reply with an error to an `offer` if one of the limits is exceeded. If support + for the `load limit` extension is indicated, then instead of replying with an error, + *rtpengine* responds with the string `load limit` in the `result` key of the response + dictionary. The response dictionary may also contain the optional key `message` with + an explanatory string. No other key is required in the response dictionary. - If no codec format parameters are specified in this list (e.g. just `opus` - instead of `opus/48000/2`), default values will be chosen for them. +* `to-label` - For codecs that support different bitrates, it can be specified by appending - another slash followed by the bitrate in bits per second, - e.g. `opus/48000/2/32000`. In this case, all format parameters (clock rate, - channels) must also be specified. + Commands that allow selection of two call participants (e.g. `block + media`) can use `label` instead of `from-tag` to select the first call + participant. The `to-label` can then be used instead of `to-tag` to + select the other call participant. - Additional options that can be appended to the codec string with additional slashes - are ptime, the `fmtp` string, and additional codec-specific options. For example - `iLBC/8000/1///mode=30` to use `mode=30` as `fmtp` string. + For `subscribe request` the `to-label` is synonymous with `set-label`. - For Opus, the string of codec-specific options is passed - directly to ffmpeg, so all ffmpeg codec options can be set. Use - space, colon, semicolon, or comma to separate individual - options. For example to set the encoding complexity (also known - as compression level by ffmpeg): - `opus/48000/2////compression_level=2` +* `TOS` - If a literal `=` cannot be used due to parsing constraints (i.e. being wrongly - interpreted as a key-value pair), it can be escaped by using two dashes instead, - e.g. `iLBC/8000/1///mode--30`. + Contains an integer. If present, changes the TOS value for the entire call, i.e. the TOS value used + in outgoing RTP packets of all RTP streams in all directions. If a negative value is used, the previously + used TOS value is left unchanged. If this key is not present or its value is too large (256 or more), then + the TOS value is reverted to the default (as per `--tos` command line). - As a special case, if the `strip=all` or `mask=all` option has been used and - the `transcode` option is used on a codec that was originally present in the offer, - then *rtpengine* will treat this codec the same as if it had been used with the - `offer` option, i.e. it will simply restore it from the list of stripped codecs and - won't actually engage transcoding for this codec. On the other hand, if a codec has - been stripped explicitly by name using the `strip` or `mask` option and then used again - with the `transcode` option, then the codec will not simply be restored from the - list of stripped codecs, but instead a new transcoded instance of the codec will - be inserted into the offer. (This special exception does not apply to `mask=full` - or `strip=full`.) - - This option is only processed in `offer` messages and ignored otherwise. - - * `mask` - - Similar to `strip` except that codecs listed here will still be accepted and - used for transcoding on the offering side. Useful only in combination with - `transcode`. For example, if an offer advertises Opus and the options - `mask=opus, transcode=G723` are given, then the rewritten outgoing offer - will contain only G.723 as offered codec, and transcoding will happen - between Opus and G.723. In contrast, if only `transcode=G723` were given, then - the rewritten outgoing offer would contain both Opus and G.723. On the other - hand, if `strip=opus, transcode=G723` were given, then Opus would be unavailable - for transcoding. - - As with the `strip` option, the special keywords `all` and `full` can be used - to mask all codecs that have been offered. - - This option is only processed in `offer` messages and ignored otherwise. - - * `consume` - - Identical to `mask` but enables the transcoding engine even if no other transcoding - related options are given. +* `transport protocol` - * `accept` + The transport protocol specified in the SDP body is to be rewritten to the string value given here. + The media + proxy will expect to receive this protocol on the allocated ports, and will talk this protocol when + sending packets out. Translation between different transport protocols will happen as necessary. - Similar to `mask` and `consume` but doesn't remove the codec from the list of - offered codecs. This means that a codec listed under `accept` will still be offered - to the remote peer, but if the remote peer rejects it, it will still be accepted - towards the original offerer and then used for transcoding. It is a more selective - version of what the `always transcode` flag does. + Valid values are: `RTP/AVP`, `RTP/AVPF`, `RTP/SAVP`, `RTP/SAVPF`. - The special string `any` can be used for the `publish` message. - See below for more details. - - * `set` - - Contains a list of strings. This list makes it possible to set codec options - (bitrate in particular) for codecs that are implicitly accepted for transcoding. - For example, if `AMR` was offered, `transcode=PCMU` was given, and the remote - ended up accepting `PCMU`, then this option can be used to set the bitrate used - for the AMR transcoding process. - - Each string must be a full codec specification as per above, including clock rate - and number of channels. Using the example above, `set=AMR/8000/1/7400` can be used - to transcode to AMR with 7.4 kbit/s. - - Codec options (bitrate) are only applied to codecs that match the given parameters - (clock rate, channels), and multiple options can be given for the same coded with - different parameters. For example, to specify different bitrates for Opus for both - mono and stereo output, one could use `set=[opus/48000/1/16000,opus/48000/2/32000]`. - - This option is only processed in `offer` messages and ignored otherwise. + Additionally the string `accept` can be given in `answer` messages to allow a special case: By + default (when no `transport-protocol` override is given) in answer messages, *rtpengine* will + use the transport protocol that was originally offered. However, an answering client may answer + with a different protocol than what was offered (e.g. offer was for `RTP/AVP` and answer comes + with `RTP/AVPF`). The default behaviour for *rtpengine* is to ignore this protocol change and + still proceed with the protocol that was originally offered. Using the `accept` option here + tells *rtpengine* to go along with this protocol change and pass it to the original offerer. -* `ptime` +* `trigger` - Contains an integer. If set, changes the `a=ptime` attribute's value in the outgoing - SDP to the provided value. It also engages the transcoding engine for supported codecs - to provide repacketization functionality, even if no additional codec has actually - been requested for transcoding. Note that not all codecs support all packetization - intervals. + A string of DTMF digits that enable a DTMF blocking mode when detected. - The selected ptime (which represents the duration of a single media packet in milliseconds) - will be used towards the endpoint receiving this offer, even if the matching answer - prefers a different ptime. +* `trigger-end` or `end trigger` - This option is ignored in `answer` messages. See below for the reverse. + A string of DTMF digits that disable DTMF blocking or enable a + different DTMF blocking mode when detected, but only after the initial + enabling `trigger` has been detected. -* `ptime-reverse` +* `trigger-end-time` - This is the reciprocal to `ptime`. It sets the ptime to be used towards the endpoint - who has sent the offer. It will be inserted in the `answer` SDP. This option is also - ignored in `answer` messages. + Time in milliseconds that a DTMF blocking mode enabled by the `trigger` + should remain active the most. After the time has expired, the blocking + mode is switched to the `trigger-end` mode. + +* `trigger-end-digits` + + Number of DTMF digits that a DTMF blocking mode enabled by the + `trigger` should remain active the most. After this number of DTMF + digits has been detected, the blocking mode is switched to the + `trigger-end` mode. * `T.38` @@ -1599,21 +1323,11 @@ Optionally included keys are: Use UDPTL FEC instead of redundancy. Only useful with `T.38=force` as it's a negotiated parameter. -* `supports` - - Contains a list of strings. Each string indicates support for an additional feature - that the controlling SIP proxy supports. Currently defined values are: - - * `load limit` +* `volume` - Indicates support for an extension to the *ng* protocol to facilitate certain load - balancing mechanisms. If *rtpengine* is configured with certain session or load - limit options enabled (such as the `max-sessions` option), then normally *rtpengine* - would reply with an error to an `offer` if one of the limits is exceeded. If support - for the `load limit` extension is indicated, then instead of replying with an error, - *rtpengine* responds with the string `load limit` in the `result` key of the response - dictionary. The response dictionary may also contain the optional key `message` with - an explanatory string. No other key is required in the response dictionary. + Sets the tone volume for `DTMF-security` modes `tone`, `zero, `DTMF`, + and `random` in negative dB. The default is -10 dB. The highest + possible volume is 0 dB and the lowest possible volume is -63 dB. * `xmlrpc-callback` @@ -1621,121 +1335,407 @@ Optionally included keys are: If specified, then this address will be used as destination address for the XMLRPC timeout callback (see `b2b-url` option). -* `media echo` or `media-echo` +**Optionally included flags are:** - Contains a string to enable a special media echo mode. Recognised values are: +The value of the `flags` key is a list. The list contains zero or more of the following strings. +Spaces in each string may be replaced by hyphens. - - `blackhole` or `sinkhole` +* `all` - Media arriving from either side of the call is simply discarded - and not forwarded. + Synonymous to `all=all` (see below). - - `forward` +* `allow transcoding` - Enables media echo towards the receiver of this message (e.g. - the called party if the message is an `offer` from the caller). - Media arriving from that side is echoed back to its sender - (with a new SSRC if it's RTP). Media arriving from the opposite - side is discarded. + This flag is only useful in commands that provide an explicit answer SDP to *rtpengine* + (e.g. `subscribe answer`). For these commands, if the answer SDP does not accept all + codecs that were offered, the default behaviour is to reject the answer. With this flag + given, the answer will be accepted even if some codecs were rejected, and codecs will be + transcoded as required. - - `backwards` +* `always transcode` - Enables media echo towards the sender of this message (i.e. the - opposite of `forward`). Media arriving from the other side is - discarded. + Legacy flag, synonymous to `codec-accept=all`. - - `both` +* `asymmetric` - Enables media echo towards both the sender and the receiver of - this message. + Corresponds to the *rtpproxy* `a` flag. Advertises an RTP endpoint which uses asymmetric + RTP, which disables learning of endpoint addresses (see below). -* `DTMF-security` +* `debug` or `debugging` - Used in the `block DTMF` message to select the DTMF blocking mode. The - default mode is `drop` which simply drops DTMF event packets. The other - supported modes are: `silence` which replaces DTMF events with silence - audio; `tone` which replaces DTMF events with a single sine wave tone; - `random` which replaces DTMF events with random other DTMF events (both - in-band DTMF audio tones and RFC event packets); `zero` which is - similar to `random` except that a zero event is always used; `DTMF` - which is similar to `zero` except that a different DTMF digit can be - specified; `off` to disable DTMF blocking. + Enabled full debug logging for this call, regardless of global log level settings. -* `DTMF-security-trigger` +* `detect DTMF` - Blocking mode to enable when the DTMF `trigger` (see below) is detected. + When present in a message that sets up codec handlers, enables + the DSP to detect in-band DTMF audio tones even when it + wouldn't otherwise be necessary. -* `DTMF-security-trigger-end` +* `full rtcp attribute` - Blocking mode to enable when the DTMF `end trigger` (see below) is - detected. + Include the full version of the `a=rtcp` line (complete with network address) instead of + the short version with just the port number. -* `trigger` +* `generate RTCP` - A string of DTMF digits that enable a DTMF blocking mode when detected. + Identical to setting `generate RTCP = on`. -* `end trigger` or `trigger-end` +* `generate mid` - A string of DTMF digits that disable DTMF blocking or enable a - different DTMF blocking mode when detected, but only after the initial - enabling `trigger` has been detected. + Add `a=mid` attributes to the outgoing SDP if they were not already present. -* `trigger-end-time` +* `inject DTMF` - Time in milliseconds that a DTMF blocking mode enabled by the `trigger` - should remain active the most. After the time has expired, the blocking - mode is switched to the `trigger-end` mode. + Signals to *rtpengine* that the audio streams involved in this `offer` or `answer` + (the flag should be present in both of them) are to be made available for DTMF + injection via the `play DTMF` control message. See `play DTMF` below for additional + information. -* `trigger-end-digits` +* `loop protect` - Number of DTMF digits that a DTMF blocking mode enabled by the - `trigger` should remain active the most. After this number of DTMF - digits has been detected, the blocking mode is switched to the - `trigger-end` mode. + Inserts a custom attribute (`a=rtpengine:...`) into the outgoing SDP to prevent *rtpengine* + processing and rewriting the same SDP multiple times. This is useful if your setup + involves signalling loops and need to make sure that *rtpengine* doesn't start looping + media packets back to itself. When this flag is present and *rtpengine* sees a matching + attribute already present in the SDP, it will leave the SDP untouched and not process + the message. -* `frequency` or `frequencies` +* `media handover` - Sets the tone frequency or frequencies for `DTMF-security=tone` in Hertz. - The default is a single frequency of 400 Hz. A list of frequencies can be - given either as a list object, or as a string containing a comma-separated - list of integers. The given frequencies will be picked from the list in - order, one for each DTMF event detected, and will be repeated once the end - of the list is reached. + Similar to the `strict source` option, but instead of dropping packets when the source address + or port don't match, the endpoint address will be re-learned and moved to the new address. This + allows endpoint addresses to change on the fly without going through signalling again. Note that + this opens a security hole and potentially allows RTP streams to be hijacked, either partly or + in whole. -* `volume` +* `NAT-wait` - Sets the tone volume for `DTMF-security` modes `tone`, `zero, `DTMF`, - and `random` in negative dB. The default is -10 dB. The highest - possible volume is 0 dB and the lowest possible volume is -63 dB. + Prevents forwarding media packets to the respective endpoint + until at least one media packet has been received from that + endpoint. This is to allow a NAT binding to open in the ingress + direction before sending packets out, which could result in an + automated firewall block. -* `digit` or `code` +* `no port latching` - Sets the replacement digit for `DTMF-security=DTMF`. + Port latching is enabled by default for endpoints which speak + ICE. With this option preset, a remote port change will result + in a local port change even for endpoints which speak ICE, + which will imply an ICE restart. -* `delay-buffer` +* `no rtcp attribute` - Takes an integer as value. When set to non-zero, enables the delay - buffer when setting up codec handlers. The delay buffer delays all - media by the given number of milliseconds before passing it on. Once - the delay buffer is configured, it must explicitly be disabled again by - setting this value to zero. The delay buffer setting is honoured in all - messages that set up codec handlers, such as `block DTMF`. + Omit the `a=rtcp` line from the outgoing SDP. -* `DTMF-delay` +* `original sendrecv` - Time in milliseconds to delay DTMF events (both RFC event packets and - DTMF tones) for. With this option enabled (set to non-zero), DTMF - events are initially replaced by silence and then subsequently - reproduced after the given delay. DTMF blocking modes are honoured at - the time when the DTMF events are reproduced. + With this flag present, *rtpengine* will leave the media direction attributes + (`sendrecv`, `recvonly`, `sendonly`, and `inactive`) from the received SDP body + unchanged. Normally *rtpengine* would consume these attributes and insert its + own version of them based on other media parameters (e.g. a media section with + a zero IP address would come out as `sendonly` or `inactive`). -* `all` +* `pad crypto` - Can be set to the string `none` to disable any extra behaviour (which - is the default if this key is omitted altogether) or to one of `all`, - `offer-answer`, `except-offer-answer` or `flows`. Applicable to - certain messages only. The behaviour is explained below separately for - each affected message. + Legacy alias to SDES=pad. + +* `pierce NAT` + + Sends empty UDP packets to the remote RTP peer as soon as an + endpoint address is available from a received SDP, for as long + as no incoming packets have been received. Useful to create an + initial NAT mapping. Not needed when ICE is in use. + +* `port latching` + + Forces *rtpengine* to retain its local ports during a signalling exchange even when the + remote endpoint changes its port. + +* `record call` + + Identical to setting `record call` to `on` (see below). + +* `reject ICE` + + Useful for `offer` messages that advertise support for ICE. + Instructs *rtpengine* to reject the offered ICE. This is + similar to using `ICE=remove` in the respective `answer`. + +* `reset` + + This causes *rtpengine* to un-learn certain aspects of the RTP endpoints involved, such as + support for ICE or support for SRTP. For example, if `ICE=force` is given, then *rtpengine* + will initially offer ICE to the remote endpoint. However, if a subsequent answer from that + same endpoint indicates that it doesn't support ICE, then no more ICE offers will be made + towards that endpoint, even if `ICE=force` is still specified. With the `reset` flag given, + this aspect will be un-learned and *rtpengine* will again offer ICE to this endpoint. + This flag is valid only in an `offer` message and is useful when the call has been + transferred to a new endpoint without change of `From` or `To` tags. + +* `reuse codecs` or `no codec renegotiation` + + Instructs *rtpengine* to prevent endpoints from switching codecs during call run-time + if possible. Codecs that were listed as preferred in the past will be kept as preferred + even if the re-offer lists other codecs as preferred, or in a different order. Recommended + to be combined with `single codec`. + +* `RTCP mirror` + + Useful only for `subscribe request` message. Instructs + *rtpengine* to not only create a one-way subscription for both + RTP and RTCP from the source to the sink, but also create a + reverse subscription for RTCP only from the sink back to the + source. This makes it possible for the media source to receive + feedback from all media receivers (sinks). + +* `single codec` + + Using this flag in an `answer` message will leave only the first listed codec in place + and will remove all others from the list. Useful for RTP clients which get confused if + more than one codec is listed in an answer. + +* `SIP source address` + + Ignore any IP addresses given in the SDP body and use the source address of the received + SIP message (given in `received from`) as default endpoint address. This was the default + behaviour of older versions of *rtpengine* and can still be made the default behaviour + through the `--sip-source` CLI switch. + Can be overridden through the `media address` key. + +* `symmetric` + + Corresponds to the *rtpproxy* `w` flag. Not used by *rtpengine* as this is the default, + unless `asymmetric` is specified. + +* `trust address` + + The opposite of `SIP source address`. This is the default behaviour unless the CLI switch + `--sip-source` is active. Corresponds to the *rtpproxy* `r` flag. + Can be overridden through the `media address` key. + +* `strip extmap` + + Remove `a=rtpmap` attributes from the outgoing SDP. + +* `strict source` + + Normally, *rtpengine* attempts to learn the correct endpoint address for every stream during + the first few seconds after signalling by observing the source address and port of incoming + packets (unless `asymmetric` is specified). Afterwards, source address and port of incoming + packets are normally ignored and packets are forwarded regardless of where they're coming from. + With the `strict source` option set, *rtpengine* will continue to inspect the source address + and port of incoming packets after the learning phase and compare them with the endpoint + address that has been learned before. If there's a mismatch, the packet will be dropped and + not forwarded. + +* `trickle ICE` + + Useful for `offer` messages when ICE is advertised to also advertise + support for trickle ICE. + +* `unidirectional` + + When this flag is present, kernelize also one-way rtp media. + +**Optionally included replace-flags are:** + +Similar to the usual `flags` list, but this one controls which parts of the SDP body should be rewritten. +Contains zero or more of: + +* `force-increment-sdp-ver` + + Force increasing the SDP version, even if the SDP hasn't been changed. + +* `origin` + + Replace the address found in the *origin* (o=) line of the SDP body. Corresponds + to *rtpproxy* `o` flag. + +* `session name` or `session-name` + + Same as `username` but for the entire contents of the `s=` line. + +* `session connection` or `session-connection` + + Replace the address found in the *session-level connection* (c=) line of the SDP body. + Corresponds to *rtpproxy* `c` flag. + +* `SDP version` or `SDP-version` + + Take control of the version field in the SDP and make sure it's increased every + time the SDP changes, and left unchanged if the SDP is the same. + +* `username` + + Take control of the origin username field in the SDP. With this + option in use, *rtpengine* will make sure the username field in + the `o=` line always remains the same in all SDPs going to a + particular RTP endpoint. + +* `zero address` + + Using a zero endpoint address is an obsolete way to signal a + muted or sendonly stream. Streams with zero addresses are + normally flagged as sendonly and the zero address in the SDP is + passed through. With this option set, the zero address is + replaced with a real address. + +**Optionally included codec manipulations:** + +`codec` contains a dictionary controlling various aspects of codecs (or RTP payload types). + +These options can also be put into the `flags` list using a prefix of `codec-`. For example, +to set the codec options for two variants of Opus when they're implicitly accepted, (see +the example under `set`), one would put the following into the `flags` list: +`codec-set-opus/48000/1/16000` `codec-set-opus/48000/2/32000` + +The following keys are understood: + +* `accept` + + Similar to `mask` and `consume` but doesn't remove the codec from the list of + offered codecs. This means that a codec listed under `accept` will still be offered + to the remote peer, but if the remote peer rejects it, it will still be accepted + towards the original offerer and then used for transcoding. It is a more selective + version of what the `always transcode` flag does. + + The special string `any` can be used for the `publish` message. + See below for more details. + +* `consume` + + Identical to `mask` but enables the transcoding engine even if no other transcoding + related options are given. + +* `except` + + Contains a list of strings. Each string is the name of a codec that should be + included in the list of codecs offered. This is primarily useful to block all + codecs (`strip -> all` or `mask -> all`) except the ones given in the `except` + whitelist. Codecs that were not present in the original list of codecs + offered by the client will be ignored. + + This list also supports codec format parameters as per above. + +* `mask` + + Similar to `strip` except that codecs listed here will still be accepted and + used for transcoding on the offering side. Useful only in combination with + `transcode`. For example, if an offer advertises Opus and the options + `mask=opus, transcode=G723` are given, then the rewritten outgoing offer + will contain only G.723 as offered codec, and transcoding will happen + between Opus and G.723. In contrast, if only `transcode=G723` were given, then + the rewritten outgoing offer would contain both Opus and G.723. On the other + hand, if `strip=opus, transcode=G723` were given, then Opus would be unavailable + for transcoding. + + As with the `strip` option, the special keywords `all` and `full` can be used + to mask all codecs that have been offered. + + This option is only processed in `offer` messages and ignored otherwise. + +* `offer` + + This is identical to `except` but additionally allows the codec order to be + changed. So the first codec listed in `offer` will be the primary (preferred) + codec in the output SDP, even if it wasn't originally so. + +* `set` + + Contains a list of strings. This list makes it possible to set codec options + (bitrate in particular) for codecs that are implicitly accepted for transcoding. + For example, if `AMR` was offered, `transcode=PCMU` was given, and the remote + ended up accepting `PCMU`, then this option can be used to set the bitrate used + for the AMR transcoding process. + + Each string must be a full codec specification as per above, including clock rate + and number of channels. Using the example above, `set=AMR/8000/1/7400` can be used + to transcode to AMR with 7.4 kbit/s. + + Codec options (bitrate) are only applied to codecs that match the given parameters + (clock rate, channels), and multiple options can be given for the same coded with + different parameters. For example, to specify different bitrates for Opus for both + mono and stereo output, one could use `set=[opus/48000/1/16000,opus/48000/2/32000]`. + + This option is only processed in `offer` messages and ignored otherwise. + +* `strip` + + Contains a list of strings. Each string is the name of a codec or RTP payload + type that should be removed from the SDP. Codec names are case sensitive, and + can be either from the list of codecs explicitly defined by the SDP through + an `a=rtpmap` attribute, or can be from the list of RFC-defined codecs. Examples + are `PCMU`, `opus`, or `telephone-event`. Codecs stripped using this option + are treated as if they had never been in the SDP. + + It is possible to specify codec format parameters alongside with the codec name + in the same format as they're written in SDP for codecs that support them, + for example `opus/48000` to + specify Opus with 48 kHz sampling rate and one channel (mono), or + `opus/48000/2` for stereo Opus. If any format parameters are specified, + the codec will only be stripped if all of the format parameters match, and other + instances of the same codec with different format parameters will be left + untouched. + + As a special keyword, `all` can be used to remove all codecs, except the ones + that should explicitly offered (see below). Note that it is an error to strip + all codecs and leave none that could be offered. In this case, the original + list of codecs will be left unchanged. + + The keyword `full` can also be used, which behaves the same as `all` with the + exception listed under `transcode` below. + +* `transcode` + + Similar to `offer` but allows codecs to be added to the list of offered codecs + even if they were not present in the original list of codecs. In this case, + the transcoding engine will be engaged. Only codecs that are supported for both + decoding and encoding can be added in this manner. This also has the side effect + of automatically stripping all unsupported codecs from the list of offered codecs, + as *rtpengine* must expect to receive or even send in any codec that is present + in the list. + + Note that using this option does not necessarily always engage the transcoding + engine. If all codecs given in the `transcode` list were present in the original + list of offered codecs, then no transcoding will be done. Also note that if + transcoding takes place, in-kernel forwarding is disabled for this media stream + and all processing happens in userspace. + + If no codec format parameters are specified in this list (e.g. just `opus` + instead of `opus/48000/2`), default values will be chosen for them. + + For codecs that support different bitrates, it can be specified by appending + another slash followed by the bitrate in bits per second, + e.g. `opus/48000/2/32000`. In this case, all format parameters (clock rate, + channels) must also be specified. + + Additional options that can be appended to the codec string with additional slashes + are ptime, the `fmtp` string, and additional codec-specific options. For example + `iLBC/8000/1///mode=30` to use `mode=30` as `fmtp` string. + + For Opus, the string of codec-specific options is passed + directly to ffmpeg, so all ffmpeg codec options can be set. Use + space, colon, semicolon, or comma to separate individual + options. For example to set the encoding complexity (also known + as compression level by ffmpeg): + `opus/48000/2////compression_level=2` + + If a literal `=` cannot be used due to parsing constraints (i.e. being wrongly + interpreted as a key-value pair), it can be escaped by using two dashes instead, + e.g. `iLBC/8000/1///mode--30`. + + As a special case, if the `strip=all` or `mask=all` option has been used and + the `transcode` option is used on a codec that was originally present in the offer, + then *rtpengine* will treat this codec the same as if it had been used with the + `offer` option, i.e. it will simply restore it from the list of stripped codecs and + won't actually engage transcoding for this codec. On the other hand, if a codec has + been stripped explicitly by name using the `strip` or `mask` option and then used again + with the `transcode` option, then the codec will not simply be restored from the + list of stripped codecs, but instead a new transcoded instance of the codec will + be inserted into the offer. (This special exception does not apply to `mask=full` + or `strip=full`.) + + This option is only processed in `offer` messages and ignored otherwise. An example of a complete `offer` request dictionary could be (SDP body abbreviated):