New file Create Diagram file

Manage

Manage

To ensure that your submitted code identity is correctly recognized by Gitee, please execute the following command.

git config --global user.name userName git config --global user.email userEmail

When using the SSH protocol for the first time to clone or push code, follow the prompts below to complete the SSH configuration.

1 Generate RSA keys.

2 Obtain the content of the RSA public key and configure it in SSH Public Keys

To use SVN on Gitee, please visit the usage guide

When using the HTTPS protocol, the command line will prompt for account and password verification as follows. For security reasons, Gitee recommends configure and use personal access tokens instead of login passwords for cloning, pushing, and other operations.

Username for 'https://gitee.com': userName

Password for 'https://userName@gitee.com': # Private Token

New file Create Diagram file

File empty ...

doc

Makefile

README

bencode.c

bencode.h

rtpengine.c

rtpengine.h

rtpengine_funcs.c

rtpengine_funcs.h

rtpengine Module
 __________________________________________________________
 Table of Contents
 1. Admin Guide
 1.1. Overview
 1.2. Multiple RTP proxy usage
 1.3. Dependencies
 1.3.1. OpenSIPS Modules
 1.3.2. External Libraries or Applications
 1.4. Exported Parameters
 1.4.1. rtpengine_sock (string)
 1.4.2. rtpengine_disable_tout (integer)
 1.4.3. rtpengine_tout (integer)
 1.4.4. rtpengine_retr (integer)
 1.4.5. rtpengine_timer_interval (integer)
 1.4.6. notification_sock (string)
 1.4.7. extra_id_pv (string)
 1.4.8. setid_avp (string)
 1.4.9. error_pv (string)
 1.4.10. db_url (string)
 1.4.11. db_table (string)
 1.4.12. socket_column (string)
 1.4.13. set_column (string)
 1.5. Exported Functions
 1.5.1. rtpengine_use_set(setid)
 1.5.2. rtpengine_offer([flags[, sock_var[,
 sdp_pvar[, body]]]])
 1.5.3. rtpengine_answer([flags[, sock_pvar[,
 sdp_pvar[, body]]]])
 1.5.4. rtpengine_delete([flags[, sock_var]])
 1.5.5. rtpengine_manage([flags[, sock_var[,
 sdp_var[, body]]]])
 1.5.6. rtpengine_start_recording([flags [,
 sock_var]])
 1.5.7. rtpengine_stop_recording([flags [,
 sock_var]])
 1.5.8. rtpengine_play_media(flags, [duration_spec[,
 sock_var[, sockvar]]])
 1.5.9. rtpengine_stop_media([flags[, sockvar]])
 1.5.10. rtpengine_block_media([flags[, sockvar]])
 1.5.11. rtpengine_unblock_media([flags[, sockvar]])
 1.5.12. rtpengine_block_dtmf([flags[, sockvar]])
 1.5.13. rtpengine_unblock_dtmf([flags[, sockvar]])
 1.5.14. rtpengine_start_forwarding([flags[,
 sockvar]])
 1.5.15. rtpengine_stop_forwarding([flags[,
 sockvar]])
 1.5.16. rtpengine_play_dtmf(code, [flags[,
 sockvar]])
 1.6. Exported Pseudo-Variables
 1.6.1. $rtpstat
 1.6.2. $rtpstat(STAT)[index]
 1.6.3. $rtpquery
 1.7. Exported MI Functions
 1.7.1. rtpengine_enable
 1.7.2. rtpengine_show
 1.7.3. rtpengine_reload
 1.7.4. teardown
 1.8. Exported Events
 1.8.1. E_RTPENGINE_NOTIFICATION
 2. Frequently Asked Questions
 3. Contributors
 3.1. By Commit Statistics
 3.2. By Commit Activity
 4. Documentation
 4.1. Contributors
 List of Tables
 3.1. Top contributors by DevScore^(1), authored commits^(2) and
 lines added/removed^(3)
 3.2. Most recently active contributors^(1) to this module
 List of Examples
 1.1. Set rtpengine_sock parameter
 1.2. Set rtpengine_disable_tout parameter
 1.3. Set rtpengine_tout parameter
 1.4. Set rtpengine_retr parameter
 1.5. Set rtpengine_timer_interval parameter
 1.6. Set notification_sock parameter
 1.7. Set extra_id_pv parameter
 1.8. Set setid_avp parameter
 1.9. Set error_pv parameter
 1.10. Set db_url parameter
 1.11. Set db_table parameter
 1.12. Set socket_column parameter
 1.13. Set set_column parameter
 1.14. rtpengine_use_set usage
 1.15. rtpengine_offer usage
 1.16. rtpengine_offer usage with body replace
 1.17. rtpengine_offer usage with call recording
 1.18. rtpengine_offer usage for transcoding
 1.19. rtpengine_answer usage
 1.20. rtpengine_delete usage
 1.21. rtpengine_manage usage
 1.22. rtpengine_start_recording usage
 1.23. rtpengine_stop_recording usage
 1.24. Ringback tone using rtpengine_play_media
 1.25. Manage music on hold using rtpengine_play_media
 1.26. Ringback tone stop using rtpengine_stop_media
 1.27. Example of rtpengine_block_media usage
 1.28. Example of rtpengine_unblock_media usage
 1.29. Example of rtpengine_block_dtmf usage
 1.30. Example of rtpengine_unblock_dtmf usage
 1.31. Example of rtpengine_start_forwarding usage
 1.32. Example of rtpengine_stop_forwarding usage
 1.33. Example of rtpengine_play_dtmf usage
 1.34. $rtpstat Usage
 1.35. $rtpstat(STAT)
 1.36. $rtpquery Usage
 1.37. rtpengine_enable usage
 1.38. rtpengine_show usage
 1.39. rtpengine_reload usage
 1.40. teardown usage
Chapter 1. Admin Guide
1.1. Overview
 This is a module that enables media streams to be proxied via
 an RTP proxy. The only RTP proxy currently known to work with
 this module is the Sipwise rtpengine
 https://github.com/sipwise/rtpengine. The rtpengine module is a
 modified version of the original rtpproxy module using a new
 control protocol. The module is designed to be a drop-in
 replacement for the old module from a configuration file point
 of view, however due to the incompatible control protocol, it
 only works with RTP proxies which specifically support it.
1.2. Multiple RTP proxy usage
 The rtpengine module can support multiple RTP proxies for
 balancing/distribution and control/selection purposes.
 The module allows definition of several sets of rtpengines.
 Load-balancing will be performed over a set and the admin has
 the ability to choose what set should be used. The set is
 selected via its id - the id being defined with the set. Refer
 to the "rtpengine_sock" module parameter definition for syntax
 description.
 The balancing inside a set is done automatically by the module
 based on the weight of each RTP proxy from the set.
 The selection of the set is done from script prior using
 rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
 functions - see the rtpengine_use_set() function.
 Another way to select the set is to define setid_avp module
 parameter and assign setid to the defined avp before calling
 rtpengine_offer() or rtpengine_manage() function. If forwarding
 of the requests fails and there is another branch to try,
 remember to unset the avp after calling rtpengine_delete()
 function.
 For backward compatibility reasons, a set with no id take by
 default the id 0. Also if no set is explicitly set before
 rtpengine_delete(), rtpengine_offer() or rtpengine_answer() the
 0 id set will be used.
 IMPORTANT: if you use multiple sets, take care and use the same
 set for both rtpengine_offer()/rtpengine_answer() and
 rtpengine_delete()!! If the set was selected using setid_avp,
 the avp needs to be set only once before rtpengine_offer() or
 rtpengine_manage() call.
1.3. Dependencies
1.3.1. OpenSIPS Modules
 The following modules must be loaded before this module:
 * tm module - (optional) if you want to have
 rtpengine_manage() fully functional
1.3.2. External Libraries or Applications
 The following libraries or applications must be installed
 before running OpenSIPS with this module loaded:
 * None.
1.4. Exported Parameters
1.4.1. rtpengine_sock (string)
 Definition of socket(s) used to connect to (a set) RTP proxy.
 It may specify a UNIX socket or an IPv4/IPv6 UDP socket.
 Default value is "NONE" (disabled).
 Example 1.1. Set rtpengine_sock parameter
...
# single rtproxy
modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
# multiple rtproxies for LB
modparam("rtpengine", "rtpengine_sock",
 "udp:localhost:12221 udp:localhost:12222")
# multiple sets of multiple rtproxies
modparam("rtpengine", "rtpengine_sock",
 "1 == udp:localhost:12221 udp:localhost:12222")
modparam("rtpengine", "rtpengine_sock",
 "2 == udp:localhost:12225")
...
1.4.2. rtpengine_disable_tout (integer)
 Once an RTP proxy was found unreachable and marked as disabled,
 the rtpengine module will not attempt to establish
 communication to that RTP proxy for rtpengine_disable_tout
 seconds.
 Default value is "60".
 Example 1.2. Set rtpengine_disable_tout parameter
...
modparam("rtpengine", "rtpengine_disable_tout", 20)
...
1.4.3. rtpengine_tout (integer)
 Timeout value in waiting for reply from RTP proxy.
 Default value is "1".
 Example 1.3. Set rtpengine_tout parameter
...
modparam("rtpengine", "rtpengine_tout", 2)
...
1.4.4. rtpengine_retr (integer)
 How many times the module should retry to send and receive
 after timeout was generated.
 Default value is "5".
 Example 1.4. Set rtpengine_retr parameter
...
modparam("rtpengine", "rtpengine_retr", 2)
...
1.4.5. rtpengine_timer_interval (integer)
 Frequency to scan rtpengine sets for disabled node probing.
 Probing is done outside the SIP processing context and in a
 separate timer routine. Disabled nodes are probed for
 re-enablement after rtpengine_disable_tout seconds. Setting
 this value too high can lead to unexpectedly large disabled
 interval as the max interval before probing is
 (rtpengine_timer_interval + rtpengine_disable_tout) seconds.
 Default value is "5".
 Example 1.5. Set rtpengine_timer_interval parameter
...
modparam("rtpengine", "rtpengine_timer_interval", 1)
...
1.4.6. notification_sock (string)
 An UDP socket formatted as IP:port that indicates the listening
 IP and port OpenSIPS will bind for to receive notifications
 (such as DTMF events) from RTPengine.
 Every notification received from RTPengine will trigger an
 E_RTPENGINE_NOTIFICATION event.
 Default value is "none" - notifications are ignored.
 Example 1.6. Set notification_sock parameter
...
modparam("rtpengine", "notification_sock", "127.0.0.1:9999")
...
1.4.7. extra_id_pv (string)
 The parameter sets the PV definition to use when the
 "via-branch=extra" option is used on the rtpengine_delete(),
 rtpengine_offer(), rtpengine_answer() or rtpengine_manage()
 commands.
 Default is empty, the "via-branch=extra" option may not be used
 then.
 Example 1.7. Set extra_id_pv parameter
...
modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
...
1.4.8. setid_avp (string)
 The parameter defines an AVP that, if set, determines which RTP
 proxy set rtpengine_offer(), rtpengine_answer(),
 rtpengine_delete(), and rtpengine_manage() functions use.
 There is no default value.
 Example 1.8. Set setid_avp parameter
...
modparam("rtpengine", "setid_avp", "$avp(setid)")
...
1.4.9. error_pv (string)
 The parameter defines a variable that shall be populated by RTP
 when one of the rtpengine_* functions fail.
 There is no default value.
 Example 1.9. Set error_pv parameter
...
modparam("rtpengine", "error_pv", "$var(rtpengine_error)")
...
1.4.10. db_url (string)
 Database URL, used to load RTPEngines sockets from db, instead
 of specifying them in the script (rtpengine_sock module
 parameter).
 Default value is "NULL", no database is used.
 Example 1.10. Set db_url parameter
...
modparam("rtpengine", "db_url",
 "mysql://opensips:opensipsrw@localhost/opensips")
...
1.4.11. db_table (string)
 The table where the RTPEngines sockets are stored. Used when
 Database URL is provisioned.
 Default value is "rtpengines".
 Example 1.11. Set db_table parameter
...
modparam("rtpengine", "db_table", "rtpengine_new")
...
1.4.12. socket_column (string)
 The name of the rtpengine socket column in the database table.
 Default value is "socket".
 Example 1.12. Set socket_column parameter
...
modparam("rtpengine", "socket_column", "sock")
...
1.4.13. set_column (string)
 The name of the rtpengine set column in the database table.
 Default value is "set_id".
 Example 1.13. Set set_column parameter
...
modparam("rtpengine", "set_column", "set_new")
...
1.5. Exported Functions
1.5.1. rtpengine_use_set(setid)
 Sets the ID of the RTP proxy set to be used for the next
 rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
 rtpengine_manage() command. The parameter is an integer.
 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
 BRANCH_ROUTE.
 Example 1.14. rtpengine_use_set usage
...
rtpengine_use_set(2);
rtpengine_offer();
...
1.5.2. rtpengine_offer([flags[, sock_var[, sdp_pvar[, body]]]])
 Rewrites SDP body to ensure that media is passed through an RTP
 proxy. To be invoked on INVITE for the cases the SDPs are in
 INVITE and 200 OK and on 200 OK when SDPs are in 200 OK and
 ACK.
 Meaning of the parameters is as follows:
 * flags(string, optional) - flags to turn on some features.
 The "flags" string is a list of space-separated items. Each
 item is either an individual token, or a token in
 "key=value" format. The possible tokens are described
 below.
 When passing an option that OpenSIPS is not aware of, it
 will be blindly sent to the rtpengine daemon to be
 processed.
 + via-branch=... - Include the "branch" value of one of
 the "Via" headers in the request to the RTP proxy.
 Possible values are: "1" - use the first "Via" header;
 "2" - use the second "Via" header; "auto" - use the
 first "Via" header if this is a request, or the second
 one if this is a reply; "extra" - don't take the value
 from a header, but instead use the value of the
 "extra_id_pv" variable. This can be used to create one
 media session per branch on the RTP proxy. When
 sending a subsequent "delete" command to the RTP
 proxy, you can then stop just the session for a
 specific branch when passing the flag '1' or '2' in
 the "rtpengine_delete", or stop all sessions for a
 call when not passing one of those two flags there.
 This is especially useful if you have serially forked
 call scenarios where the RTP proxy gets an "offer"
 command for a new branch, and then a "delete" command
 for the previous branch, which would otherwise delete
 the full call, breaking the subsequent "answer" for
 the new branch. This flag is only supported by the
 Sipwise rtpengine RTP proxy at the moment!
 + call-id - provide a custom Call-ID for the session. If
 missing, the Call-Id of the request/reply is used.
 + from-tag - provide a custom from-tag for the session.
 If missing, the from-tag request is used.
 + to-tag - provide a custom to-tag of the session. If
 missing, the to-tag of the request/reply is used, is
 present.
 + asymmetric - flags that UA from which message is
 received doesn't support symmetric RTP. (automatically
 sets the 'r' flag)
 + force-answer - force "answer", that is, only rewrite
 SDP when corresponding session already exists in the
 RTP proxy. By default is on when the session is to be
 completed.
 + in-iface=..., out-iface=... - these flags specify the
 direction the SIP message. These flags only make sense
 when the RTP proxy is running in bridge mode.
 "in-iface" should indicate the proxy's inbound
 interface, and "out-iface" corresponds to the RTP
 proxy's outbound interface. You always have to specify
 two flags to define the incoming network and the
 outgoing network. For example, "in-iface=internal
 out-iface=external" should be used for SIP message
 received from the local interface and sent out on the
 external interface.
 + internal, external - these the old flags used to
 specify the direction of call. They are now obsolate,
 being replaced by the "in-iface=internal
 out-iface=external" configuration.
 + auto-bridge - this flag an alternative to the
 "internal" and "external" flags in order to do
 automatic bridging between IPv4 on the "internal
 network" and IPv6 on the "external network". Instead
 of explicitly instructing the RTP proxy to select a
 particular address family, the distinction is done by
 the given IP in the SDP body by the RTP proxy itself.
 Not supported by Sipwise rtpengine.
 + address-family=... - instructs the RTP proxy that the
 recipient of this SDP body expects to see addresses of
 a particular family. Possible values are "IP4" and
 "IP6". For example, if the SDP body contains IPv4
 addresses but the recipient only speaks IPv6, you
 would use "address-family=IP6" to bridge between the
 two address families.
 Sipwise rtpengine remembers the address family
 preference of each party after it has seen an SDP body
 from them. This means that normally it is only
 necessary to explicitly specify the address family in
 the "offer", but not in the "answer".
 Note: Please note, that this will only work properly
 with non-dual-stack user-agents or with dual-stack
 clients according to RFC6157 (which suggest ICE for
 Dual-Stack implementations). This short-cut will not
 work properly with RFC4091 (ANAT) compatible clients,
 which suggests having different m-lines with different
 IP-protocols grouped together.
 + received-from=... - sets the address from which SIP
 packet with SDP received. This flag always set
 automatically, don't use it until you have a reason
 for that.
 + force - instructs the RTP proxy to ignore marks
 inserted by another RTP proxy in transit to indicate
 that the session is already goes through another
 proxy. Allows creating a chain of proxies. Not
 supported and ignored by Sipwise rtpengine.
 + trust-address - flags that IP address in SDP should be
 trusted. Without this flag, the RTP proxy ignores
 address in the SDP and uses source address of the SIP
 message as media address which is passed to the RTP
 proxy. From rtpengine 3.8 this is the default
 behaviour.
 + SIP-source-address - the opposite of trust-address.
 Restores the old default behaviour of ignoring
 endppoint of the addresses in the SDP body.
 + replace-origin - flags that IP from the origin
 description (o=) should be also changed.
 + replace-session-connection - flags to change the
 session-level SDP connection (c=) IP if media
 description also includes connection information.
 + replace-zero-address - flags to replace zero address
 with real 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.
 + symmetric - flags that for the UA from which message
 is received, support symmetric RTP must be forced. You
 do not need to explicitly specify this value, as it is
 the default, and the behavior is only changed when the
 asymmetric is used.
 + repacketize=NN - requests the RTP proxy to perform
 re-packetization of RTP traffic coming from the UA
 which has sent the current message to increase or
 decrease payload size per each RTP packet forwarded if
 possible. The NN is the target payload size in ms, for
 the most codecs its value should be in 10ms
 increments, however for some codecs the increment
 could differ (e.g. 30ms for GSM or 20ms for G.723).
 The RTP proxy would select the closest value supported
 by the codec. This feature could be used for
 significantly reducing bandwith overhead for low
 bitrate codecs, for example with G.729 going from 10ms
 to 100ms saves two thirds of the network bandwith. Not
 supported by Sipwise rtpengine.
 + loop-protect - flag that instructs RTP to avoid
 rewriting the SDP when looping the same message.
 + ICE=... - controls the RTP proxy's behaviour regarding
 ICE attributes within the SDP body. Possible values
 are: "force" - discard any ICE attributes already
 present in the SDP body and then generate and insert
 new ICE data, leaving itself as the only ICE
 candidates; "remove" instructs the RTP proxy to
 discard any ICE attributes and not insert any new ones
 into the SDP. The default (if no "ICE=..." is given at
 all), new ICE data will only be generated if no ICE
 was present in the SDP originally; otherwise the RTP
 proxy will only insert itself as an additional ICE
 candidate. Other SDP substitutions (c=, m=, etc) are
 unaffected by this flag.
 + RTP, SRTP, AVP, AVPF - These flags control the RTP
 transport protocol that should be used towards the
 recipient of the SDP. If none of them are specified,
 the protocol given in the SDP is left untouched.
 Otherwise, the "SRTP" flag indicates that SRTP should
 be used, while "RTP" indicates that SRTP should not be
 used. "AVPF" indicates that the advanced RTCP profile
 with feedback messages should be used, and "AVP"
 indicates that the regular RTCP profile should be
 used. See also the next set of flags below.
 + RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve
 as an alternative, more explicit way to select between
 the different RTP protocols and profiles supported by
 the RTP proxy. For example, giving the flag
 "RTP/SAVPF" has the same effect as giving the two
 flags "SRTP AVPF".
 + to-tag - force inclusion of the "To" tag. Normally,
 the "To" tag is always included when present, except
 for "delete" messages. Including the "To" tag in a
 "delete" messages allows you to be more selective
 about which dialogues within a call are being torn
 down.
 + to-tag=... - use the specified string as "To" tag
 instead of the actual "To" tag from the SIP message,
 and force inclusion of the tag in the message as per
 above.
 + from-tag=... - use the specified string as "From" tag
 instead of the actual "From" tag from the SIP message.
 + call-id=... - use the specified string as "Call-ID"
 instead of the actual "Call-ID" from the SIP message.
 + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered,
 make the RTP proxy accept the offer, but not offer it
 to the recipient of this message.
 + rtcp-mux-reject - if rtcp-mux was offered, make the
 RTP proxy reject the offer, but still offer it to the
 recipient. Can be combined with "rtcp-mux-offer" to
 always offer it.
 + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to
 the recipient of this message, regardless of whether
 it was offered originally or not.
 + rtcp-mux-require - Similar to offer but pretends that
 the client has accepted rtcp-mux. This breaks RFC 5761
 and will not advertise seperate RTCP ports. This
 option is necessary for WebRTC clients.
 + rtcp-mux-accept - if rtcp-mux was offered, make the
 RTP proxy accept the offer and also offer it to the
 recipient of this message. Can be combined with
 "rtcp-mux-offer" to always offer it.
 + media-address=... - force a particular media address
 to be used in the SDP body. Address family is detected
 automatically.
 + record-call=yes/no - indicates whether rtpengine
 should record the call or not. When using this
 parameter, you may pass further information in the
 "metadata".
 + transcode-CODEC - used only for offer, indicates that
 rtpengine should transcode the CODEC towards the
 B-side. Example: transcode-PCMA will present to the
 B-side the PCMA codec.
 + codec-strip-CODEC - used only for offer, indicates
 that the A-side of the call will not end up talking
 CODEC. Example: codec-strip-PCMA will prevent the
 A-side from receiving the PCMA codec.
 + codec-mask-CODEC - used only for offer, indicates that
 the A-side will use the CODEC, but it will not be
 presented to the B-side. Example: codec-mask-PCMA will
 make the A-side receive the PCMA codec, but B-side
 will use something else.
 * sock_var(var, optional) - variable used to store the
 rtpengine socket chosen for this call.
 * sdp_var(var, optional) - variable used to store the full
 SDP received from rtpengine. You can perform any additional
 changes on this string. Important: when providing this
 variable, the message body is no longer changed, so you
 have to manually replace it!.
 * body(string, optional) - used to provide a specific body to
 the rtpengine_* function. If this parameter is missing the
 body of the current message is used.
 This function can be used from ALL_ROUTES.
 Example 1.15. rtpengine_offer usage
route {
...
 if (is_method("INVITE")) {
 if (has_body("application/sdp")) {
 if (rtpengine_offer())
 t_on_reply("1");
 } else {
 t_on_reply("2");
 }
 }
 if (is_method("ACK") && has_body("application/sdp"))
 rtpengine_answer();
...
}
onreply_route[1]
{
...
 if (has_body("application/sdp"))
 rtpengine_answer();
...
}
onreply_route[2]
{
...
 if (has_body("application/sdp"))
 rtpengine_offer();
...
}
 Example 1.16. rtpengine_offer usage with body replace
...
if (rtpengine_offer(, $var(socket), $var(body), $rb)) {
 xlog("Used rtpengine $var(socket)\n");
 # make all the changes on the resulted SDP in $var(body)
 ...
 remove_body_part();
 add_body_part($var(body), "application/sdp");
}
...
 Example 1.17. rtpengine_offer usage with call recording
...
$var(rtpengine_flags) = $var(rtpengine_flags) + " record-call=yes";
$json(recording_keys) := "{}";
$json(recording_keys/callId) = $ci;
$json(recording_keys/fromUser) = $dlg_val(recording_from_user);
$json(recording_keys/fromDomain) = $dlg_val(recording_from_domain);
$json(recording_keys/fromTag) = $dlg_val(recording_from_tag);
$json(recording_keys/toUser) = $dlg_val(recording_to_user);
$json(recording_keys/toDomain) = $dlg_val(recording_to_domain);
$var(rtpengine_flags) = $var(rtpengine_flags) + " metadata=" + $(json(re
cording_keys){s.encode.hexa});
rtpengine_offer($var(rtpengine_flags));
...
 Example 1.18. rtpengine_offer usage for transcoding
...
# Goal: make A-side talk PCMA and B-side talk opus
# * do not present PCMA to B-side: codec-mask-PCMA, but use it on A-side
# * do not use opus for A-side: codec-strip-opus
# * offer opus to B-side: transcode-opus
rtpengine_offer("... codec-mask-PCMA codec-strip-opus transcode-opus ...
");
...
1.5.3. rtpengine_answer([flags[, sock_pvar[, sdp_pvar[, body]]]])
 Rewrites SDP body to ensure that media is passed through an RTP
 proxy. To be invoked on 200 OK for the cases the SDPs are in
 INVITE and 200 OK and on ACK when SDPs are in 200 OK and ACK.
 See rtpengine_offer() function description above for the
 meaning of the parameters.
 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
 FAILURE_ROUTE, BRANCH_ROUTE.
 Example 1.19. rtpengine_answer usage
 See rtpengine_offer() function example above for examples.
1.5.4. rtpengine_delete([flags[, sock_var]])
 Tears down the RTPProxy session for the current call.
 See rtpengine_offer() function description above for the
 meaning of the parameters. Note that not all flags make sense
 for a "delete".
 This function can be used from ALL_ROUTES.
 Example 1.20. rtpengine_delete usage
...
rtpengine_delete();
...
1.5.5. rtpengine_manage([flags[, sock_var[, sdp_var[, body]]]])
 Manage the RTPProxy session - it combines the functionality of
 rtpengine_offer(), rtpengine_answer() and rtpengine_delete(),
 detecting internally based on message type and method which one
 to execute.
 It can take the same parameters as rtpengine_offer(). The flags
 parameter to rtpengine_manage() can be a configuration variable
 containing the flags as a string.
 Functionality:
 * If INVITE with SDP, then do rtpengine_offer()
 * If ACK with SDP, then do rtpengine_answer()
 * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then
 do rtpengine_delete()
 * If reply to INVITE with code >= 300 do rtpengine_delete()
 * If reply with SDP to INVITE having code 1xx and 2xx, then
 do rtpengine_answer() if the request had SDP or tm is not
 loaded, otherwise do rtpengine_offer()
 This function can be used from ALL_ROUTES.
 Example 1.21. rtpengine_manage usage
...
rtpengine_manage();
...
1.5.6. rtpengine_start_recording([flags [, sock_var]])
 This function will send a signal to the RTP proxy to record the
 RTP stream on the RTP proxy.
 Meaning of the parameters is as follows:
 * flags(string, optional) - flags used to change the behavior
 of the recorder. An importat value to set is the call-id
 value, which can be used to start recording a different
 call than the requested one.
 * sock_var(var, optional) - variable used to store the
 rtpengine socket chosen for this call.
 This function can be used from any route.
 Example 1.22. rtpengine_start_recording usage
...
rtpengine_start_recording();
...
1.5.7. rtpengine_stop_recording([flags [, sock_var]])
 This function will send a signal to the RTP proxy to stop
 recording the RTP stream on the RTP proxy.
 Meaning of the parameters is as follows:
 * flags(string, optional) - flags used to change the behavior
 of the recorder. An importat value to set is the call-id
 value, which can be used to start recording a different
 call than the requested one.
 * sock_var(var, optional) - variable used to store the
 rtpengine socket chosen for this call.
 This function can be used from any route.
 Example 1.23. rtpengine_stop_recording usage
...
rtpengine_stop_recording();
...
1.5.8. rtpengine_play_media(flags, [duration_spec[, sock_var[,
sockvar]]])
 This function will start playing a media file to one of the
 endpoints.
 Meaning of the parameters is as follows:
 * flags(string) - a list of flags simialar to the other
 functions. One of the file, blob or db-id parameters is
 mandatory to indicate the content of the media file to be
 played. file is a common choice for specifying rtpengine to
 get media from a file path, blob to take the content from
 an inline string and db-id to get the content from the
 database.
 The direction of the media stream is controlled by the
 from-tag parameter, address (media address from the SDP),
 or label, if the media stream contains a label. If all of
 them are missing, the media file is played to the initiator
 of the SIP request, and will work similar to a ringback
 tone.
 * duration_spec(var, optional) - a pseudo variable that will
 contain the duration of the played file. It will be set to
 -1 if the duration could not be determined.
 * sock_var(var, optional) - variable used to store the
 rtpengine socket chosen for this call.
 This function can be used from any route.
 Example 1.24. Ringback tone using rtpengine_play_media
...
if (is_method("INVITE") && !has_totag())
 rtpengine_play_media("file=/path/to/ringback_tone_file.wav");
...
 Example 1.25. Manage music on hold using rtpengine_play_media
...
if (is_method("INVITE") && has_totag()) {
 if (is_audio_on_hold()) {
 $dlg_val(on_hold) = "1";
 rtpengine_play_media("from-tag=$tt file=/path/to/moh_fil
e.wav");
 } else if ($dlg_val(on_hold) == "1") {
 $dlg_val(on_hold) = "0";
 rtpengine_stop_media("from-tag=$tt");
 }
}
...
1.5.9. rtpengine_stop_media([flags[, sockvar]])
 This function will stop playing a media file previously started
 by a rtpengine_play_media() call. The meaning of its parameters
 is similar to the previous functions. Note that this function
 should be called with similar parameters as its matching
 rtpengine_play_media() call, otherwise RTPEngine will not be
 able to stop media playing.
 This function can be used from any route.
 Example 1.26. Ringback tone stop using rtpengine_stop_media
...
if (is_method("INVITE") && $rs == 200)
 rtpengine_stop_media();
...
1.5.10. rtpengine_block_media([flags[, sockvar]])
 This function will block the media sent from one of the
 endpoints. The direction to be blocked is controled by the
 flags parameter, the from-tag value.
 This function can be used from any route.
 Example 1.27. Example of rtpengine_block_media usage
...
rtpengine_block_media();
...
1.5.11. rtpengine_unblock_media([flags[, sockvar]])
 This function will resume/unblock the media sent from one of
 the endpoints. The direction to be blocked is controled by the
 flags parameter, the from-tag value.
 This function can be used from any route.
 Example 1.28. Example of rtpengine_unblock_media usage
...
rtpengine_unblock_media();
...
1.5.12. rtpengine_block_dtmf([flags[, sockvar]])
 This function will block the DTMF media sent from one of the
 endpoints. The direction to be blocked is controled by the
 flags parameter, the from-tag value.
 This function can be used from any route.
 Example 1.29. Example of rtpengine_block_dtmf usage
...
rtpengine_block_dtmf();
...
1.5.13. rtpengine_unblock_dtmf([flags[, sockvar]])
 This function will resume/unblock the DTMF media sent from one
 of the endpoints. The direction to be blocked is controled by
 the flags parameter, the from-tag value.
 This function can be used from any route.
 Example 1.30. Example of rtpengine_unblock_dtmf usage
...
rtpengine_unblock_dtmf();
...
1.5.14. rtpengine_start_forwarding([flags[, sockvar]])
 This function will start forwarding the media to a TLS
 destination specified in the tls-send-to parmeter of RTPEngine.
 This function allows you to select the media stream to forward,
 by specifing the from-tag of the entity you want to forward the
 media. If missing, all media streams are forwarded.
 This function can be used from any route.
 Example 1.31. Example of rtpengine_start_forwarding usage
...
rtpengine_start_forwarding();
...
1.5.15. rtpengine_stop_forwarding([flags[, sockvar]])
 This function will stop forwarding of the media previously
 started using the rtpengine_start_forwarding() function.
 This function can be used from any route.
 Example 1.32. Example of rtpengine_stop_forwarding usage
...
rtpengine_stop_forwarding();
...
1.5.16. rtpengine_play_dtmf(code, [flags[, sockvar]])
 This function instructs RTP to send the DTMF code to the
 participant of the call. The code can be a digit ("0-9") or a
 special character (one of "*,#,A,B,C,D"). Additional parameters
 can be configured using the flags parameter. For more
 information, please consult the RTP documentation.
 NOTE: if you are planning to inject DTMF in a session, you have
 to specify the inject-DTMF flag when the session is created.
 This function can be used to convert SIP INFO DTMF keys to RTP
 DTMF.
 This function can be used from any route.
 Example 1.33. Example of rtpengine_play_dtmf usage
...
rtpengine_play_dtmf("0"); # send the 0 code upstream
...
1.6. Exported Pseudo-Variables
1.6.1. $rtpstat
 Returns the RTP statistics from the RTP proxy. The RTP
 statistics from the RTP proxy are provided as a string and it
 does contain several packet counters.
 Example 1.34. $rtpstat Usage
...
 append_hf("X-RTP-Statistics: $rtpstat\r\n");
...
1.6.2. $rtpstat(STAT)[index]
 Returnes one of the pre-fined statistics listed below:
 * MOS-average - without an index, it returns the average MOS
 value, expressed in an integer between 0 and 50, of all the
 RTP streams involved in the call, both caller and callee.
 If index is specified, it has to be one of the from-tag or
 to-tag involved in the call. In this case, the variable
 will return the average MOS of all the streams generated by
 that endpoint with the associated tag value. If you need
 more granular statistics, check the $rtpquery variable.
 * jitter-average - similar behavior with MOS-average, but
 returnes the average jitter.
 * roundtrip-average - similar behavior with MOS-average, but
 returnes the average roundtrip.
 * packetloss-average - similar behavior with MOS-average, but
 returnes the average packet loss.
 * MOS-min - without an index, it returns the minimum MOS
 value (integer value between 0 and 50) of all RTP streams
 involved in the call, both caller and callee. If the index
 is specified, it has the same effect as for MOS-average.
 * jitter-min - similar behavior with MOS-min, but returnes
 the minimum jitter of a leg/call.
 * roundtrip-min - similar behavior with MOS-min, but returnes
 the minimum roundtrip of a leg/call.
 * packetloss-min - similar behavior with MOS-min, but
 returnes the minimum packet loss of a leg/call.
 * MOS-max - without an index, it returns the maximum MOS
 value (integer value between 0 and 50) of all RTP streams
 involved in the call, both caller and callee. If the index
 is specified, it has the same effect as for MOS-average.
 * jitter-max - similar behavior with MOS-max, but returnes
 the maximum jitter of a leg/call.
 * roundtrip-max - similar behavior with MOS-max, but returnes
 the maximum roundtrip of a leg/call.
 * packetloss-max - similar behavior with MOS-max, but
 returnes the maximum packet loss of a leg/call.
 * MOS-min-at - without an index, it returns the time in
 seconds elapsed from the start of the call when the MOS
 value is minimum. If the index is specified, it has the
 same effect as for MOS-average.
 * jitter-min-at - similar behavior with MOS-min-at, but
 returnes the time when the minimum jitter was detected.
 * roundtrip-min-at - similar behavior with MOS-min-at, but
 returnes the time when the minimum roundtrip was detected.
 * packetloss-min-at - similar behavior with MOS-min-at, but
 returnes the time when the minimum packet loss of a
 leg/call was detected.
 * MOS-max-at - without an index, it returns the time in
 seconds elapsed from the start of the call when the MOS
 value is maximum. If the index is specified, it has the
 same effect as for MOS-average.
 * jitter-max-at - similar behavior with MOS-max-at, but
 returnes the time when the maximum value of jitter was
 detected.
 * roundtrip-max-at - similar behavior with MOS-max-at, but
 returnes the time when the maximum value of roundtrip was
 detected.
 * packetloss-min-at - similar behavior with MOS-max-at, but
 returnes the time when the maximum packet loss of a
 leg/call was detected.
 NOTE: all these statistics are computed based on the statistics
 generated by RTPEngine. Some of them might not be available for
 all the calls (i.e. MOS cannot be computed if the call is too
 short, or if the phones do not properly report RTP statistics
 over RTCP). In these cases the variable returns the NULL value.
 Example 1.35. $rtpstat(STAT)
...
 xlog("Average MOS of the entire call is $rtpstat(MOS-average)\r\n");
 xlog("Average MOS of caller is $(rtpstat(MOS-average)[$ft])\r\n");
 xlog("Average MOS of callee is $(rtpstat(MOS-average)[$tt])\r\n");
 xlog("Min MOS of caller is $(rtpstat(MOS-min)[$ft]) reported at $(rt
pstat(MOS-min-at)[$ft])\r\n");
...
1.6.3. $rtpquery
 Does a Query command to the RTP proxy and returns the answer in
 a JSON format. You can use this variable to fetch arbitrary
 data from the RTP proxy such as raw statistics about the call,
 or other indicators.
 You can use a $json() variable to parse its output and extract
 any information from the query, such as RTP statistics, or MOS
 values.
 Example 1.36. $rtpquery Usage
...
 $json(reply) := $rtpquery;
 xlog("Total RTP Stats: $json(reply/totals)\n");
...
1.7. Exported MI Functions
1.7.1. rtpengine_enable
 Enables/disables a RTP proxy.
 Parameters:
 * url - the RTP proxy url (exactly as defined in the config
 file).
 * enable - 1 - enable, 0 - disable the RTP proxy.
 NOTE: if a RTP proxy is defined multiple times (in the same or
 different set), all of its instances will be enables/disabled.
 Example 1.37. rtpengine_enable usage
...
$ opensips-cli -x mi rtpengine_enable udp:192.168.2.133:8081 0
...
1.7.2. rtpengine_show
 Displays all the RTP proxies and their information: set and
 status (disabled or not, weight and recheck_ticks).
 No parameter.
 Example 1.38. rtpengine_show usage
...
$ opensips-cli -x mi rtpengine_show
...
1.7.3. rtpengine_reload
 Reloads all rtpengine sets from the database. Used only when
 the "db_url" parameter is set.
 No parameter.
 Example 1.39. rtpengine_reload usage
...
$ opensips-cli -x mi rtpengine_reload
...
1.7.4. teardown
 Terminates the SIP dialog by the SIP Call-ID given as
 parameter.
 Parameters:
 * callid - SIP Call-ID.
 Note this is a just a wrapper function over the "dlg_end_dlg"
 MI function provided by the "dialog" module. This wrapping is
 done just to make rtpengine happy when trying to terminate SIP
 calls based on RTP timeouts.
 Example 1.40. teardown usage
...
$ opensips-cli -x mi teardown Y2IwYjQ2YmE2ZDg5MWVkNDNkZGIwZjAzNGM1ZDY0ZD
Q
...
1.8. Exported Events
1.8.1. E_RTPENGINE_NOTIFICATION
 This event is raised when a notification is received from
 RTPengine.
 Parameters represent the nodes within the Json request received
 from RTPengine. Common values are:
 * type - identifies the type of notification (i.e. DTMF)
 * callid - the callid of the call this event is triggered for
 * source_tag - from tag of the call this event is triggered
 for
 * timestamp - timestamp when the event was triggered
 For a DTMF event received, you will also get the following
 nodes:
 * source_ip - the IP that triggered the DTMF
 * event - the event/digit pressed
 * duration - how long the digit was pressed
 * volume - volume of the tone
Chapter 2. Frequently Asked Questions
 2.1.
 How do I migrate from "rtpproxy" or "rtpproxy-ng" to
 "rtpengine"?
 For the most part, only the names of the functions have
 changed, with "rtpproxy" in each name replaced with
 "rtpengine". For example, "rtpproxy_manage()" has become
 "rtpengine_manage()". A few name duplications have also been
 resolved, for example there is now a single
 "rtpengine_delete()" instead of "unforce_rtp_proxy()" and the
 identical "rtpproxy_destroy()".
 The largest difference to the old module is how flags are
 passed to "rtpengine_offer()", "rtpengine_answer()",
 "rtpengine_manage()" and "rtpengine_delete()". Instead of
 having a string of single-letter flags, they now take a string
 of space-separated items, with each item being either a single
 token (word) or a "key=value" pair.
 For example, if you had a call "rtpproxy_offer("FRWOC+PS");",
 this would then become:
rtpengine_offer("force trust-address symmetric replace-origin replace-se
ssion-connection ICE=force RTP/SAVPF");
 Finally, if you were using the second parameter (explicit media
 address) to any of these functions, this has been replaced by
 the "media-address=..." option within the first string of
 flags.
 2.2.
 Where can I find more about OpenSIPS?
 Take a look at https://opensips.org/.
 2.3.
 Where can I post a question about this module?
 First at all check if your question was already answered on one
 of our mailing lists:
 * User Mailing List -
 http://lists.opensips.org/cgi-bin/mailman/listinfo/users
 * Developer Mailing List -
 http://lists.opensips.org/cgi-bin/mailman/listinfo/devel
 E-mails regarding any stable OpenSIPS release should be sent to
 <users@lists.opensips.org> and e-mails regarding development
 versions should be sent to <devel@lists.opensips.org>.
 If you want to keep the mail private, send it to
 <users@lists.opensips.org>.
 2.4.
 How can I report a bug?
 Please follow the guidelines provided at:
 https://github.com/OpenSIPS/opensips/issues.
Chapter 3. Contributors
3.1. By Commit Statistics
 Table 3.1. Top contributors by DevScore^(1), authored
 commits^(2) and lines added/removed^(3)
 Name DevScore Commits Lines ++ Lines --
 1. Razvan Crainea (@razvancrainea) 179 86 5431 2888
 2. Bogdan-Andrei Iancu (@bogdan-iancu) 30 16 422 594
 3. Richard Fuchs 20 2 640 723
 4. Liviu Chircu (@liviuchircu) 17 13 71 135
 5. Vlad Patrascu (@rvlad-patrascu) 15 7 218 330
 6. John Burke (@john08burke) 10 6 236 67
 7. Peter Lemenkov (@lemenkov) 8 6 27 34
 8. Eric Tamme (@etamme) 7 5 42 19
 9. Nick Altmann (@nikbyte) 6 4 43 2
 10. Ovidiu Sas (@ovidiusas) 5 3 37 7
 All remaining contributors: Zero King (@l2dy), Rob Gagnon
 (@rgagnon24), Flavio E. Goncalves, Dan Pascu (@danpascu),
 Maksym Sobolyev (@sobomax), Oliver Severin Mulelid-Tynes
 (@olivermt).
 (1) DevScore = author_commits + author_lines_added /
 (project_lines_added / project_commits) + author_lines_deleted
 / (project_lines_deleted / project_commits)
 (2) including any documentation-related commits, excluding
 merge commits. Regarding imported patches/code, we do our best
 to count the work on behalf of the proper owner, as per the
 "fix_authors" and "mod_renames" arrays in
 opensips/doc/build-contrib.sh. If you identify any
 patches/commits which do not get properly attributed to you,
 please submit a pull request which extends "fix_authors" and/or
 "mod_renames".
 (3) ignoring whitespace edits, renamed files and auto-generated
 files
3.2. By Commit Activity
 Table 3.2. Most recently active contributors^(1) to this module
 Name Commit Activity
 1. Liviu Chircu (@liviuchircu) Jul 2014 - Nov 2021
 2. Razvan Crainea (@razvancrainea) Jun 2014 - Nov 2021
 3. John Burke (@john08burke) Jun 2019 - Aug 2021
 4. Nick Altmann (@nikbyte) May 2021 - May 2021
 5. Maksym Sobolyev (@sobomax) Jan 2021 - Jan 2021
 6. Flavio E. Goncalves Oct 2020 - Oct 2020
 7. Zero King (@l2dy) Mar 2020 - Sep 2020
 8. Peter Lemenkov (@lemenkov) Jun 2018 - Jul 2020
 9. Ovidiu Sas (@ovidiusas) Jun 2020 - Jun 2020
 10. Bogdan-Andrei Iancu (@bogdan-iancu) Jun 2014 - May 2020
 All remaining contributors: Vlad Patrascu (@rvlad-patrascu),
 Dan Pascu (@danpascu), Oliver Severin Mulelid-Tynes
 (@olivermt), Rob Gagnon (@rgagnon24), Eric Tamme (@etamme),
 Richard Fuchs.
 (1) including any documentation-related commits, excluding
 merge commits
Chapter 4. Documentation
4.1. Contributors
 Last edited by: Liviu Chircu (@liviuchircu), Razvan Crainea
 (@razvancrainea), John Burke (@john08burke), Nick Altmann
 (@nikbyte), Flavio E. Goncalves, Peter Lemenkov (@lemenkov),
 Vlad Patrascu (@rvlad-patrascu), Bogdan-Andrei Iancu
 (@bogdan-iancu), Richard Fuchs.
 Documentation Copyrights:
 Copyright © 2013-2014 Sipwise GmbH
 Copyright © 2010 VoIPEmbedded Inc.
 Copyright © 2009-2014 TuTPro Inc.
 Copyright © 2005 Voice Sistem SRL
 Copyright © 2003-2008 Sippy Software, Inc.

Report success

Type

Reason

取消

提交