Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
RTPProxy Command Protocol
RTPProxy command protocol
The RTPProxy uses a simple text base command protocol to manage streams, and fetch information from the RTPProxy.
This protocol is used between SIP controllers (OpenSIPs, Kamailio, Sippy B2BUA) to set up and tear down media sessions.
Commands are case in-sensitive, but uppercase is preferred.
Commands that operate on, or create a session typically take two mandatory
to_tag and one optional
The examples in this document use dummy values as follows;
A real-world example would look something like:
Q firstname.lastname@example.org d10bce6278e01cfe2ade240aaee26385 2919213e4eb16f01d350a99d539b4428
Accessing the command channel manually
To explore the RTPP channel, you can communicate with a RTPProxy instance
either via the Unix domain socket, or via a UDP port. There are plenty of
tools to do this. The examples that follow use the netcat command
Accessing RTPProxy command channel using socket
# echo V | nc -U /var/run/RTPProxy.sock 20040170
Accessing RTPProxy command channel using udp port
This example assumes you have a running RTPProxy that was started with the
rtpproxy -s udp:127.0.0.1:22222
nc -u 127.0.0.1 22229 TOKEN V TOKEN 20040107
TOKEN string is important, and can be any alphanumeric string. It is
a transaction ID used to keep track of requests. If you are writing
a simple polling script to gather stats, then using a Unix time stamp
should suffice. If you are controlling RTPProxy from a call controller,
then you should make sure the
TOKEN is unique for each request.
The following example uses the
date command, and the
G rtpp command to
# echo "$(date +%s) G nsess_created" |nc -u 127.0.0.1 22229 1447371704 60335158 #
This example shows RTPProxy has created 6,033,5158 sessions in its lifetime.
Returns the base RTPP protocol capability level.
Returns 0 for unsupported, 1 for supported.
Example of VF where protocol is supported
echo "VF 20150616" | nc -U /var/run/rtpproxy.sock 0
Example of VF where protocol is unsupported
echo "VF 20200617" | nc -U /var/run/rtpproxy.sock 1
Create/Update a session
U[opts] call_id remote_ip remote_port from_tag [to_tag] [notify_socket notify_tag]
The U command is used to either create or update a session. This command is idempotent.
echo "U 123@abc 10.0.0.1 5000 xyz" | nc -U /var/run/rtpproxy.sock 55040
L[opts] call_id remote_ip remote_port from_tag [to_tag]
Options for U & L
E- Listen Internet Address Egress External
I- Listen Internet Address sockaddr Ingress Internal
6- Use IPv6
S- symmetric RTP
W- weak mode relates to call transfer scenarios.
Z requested_nsamples- Enables re-packetization. Value will depend on codec. Minimum is 10msec. Minimum increment is 10msec. Certain Codecs have larger min packet size. GSM increments are 30msec. G711,G729 10msec.
C- Codec payload types. integers separated by commas. See rfc3551 Table4
L- specify the local RTPProxy address to use
R- Remote address. Destination IP. A Little weird. We don't use it much. It is for the case where you receive SDP that says “My IP is”. You can use this R flag to indicate where you received this address from. Useful when the signalling and media IP address might be different. When we don’t have reliable media information in the SDP, we can use the ‘R’ flag as a hint.
Delete active session
D[w] call_id from_tag [to_tag];
Delete an active session. Typically used for Bye/Cancel/Error scenario from upstream controller.
w option stands for weak.
The following example sets up a session, and then deletes it.
echo "U 123@abc 10.0.0.1 5000 xyz" | nc -U /var/run/rtpproxy.sock 36018 echo "D 123@abc xyz" | nc -U /var/run/rtpproxy.sock 0
This example attempts to delete a session that does not exist, and an error code is returned.
echo "D dev@null this_tag_doesnt_exist" | nc -U /var/run/rtpproxy.sock E50
G [stat_name1 [stat_name2 [stat_name3 ...[stat_nameN]]]]
Get one or more stat counter by name.
The following example gets two stats,
The results are returned on a single line, separated by a space, in the same
order as the command specified.
# echo "G nsess_created nsess_destroyed" |nc -U /var/run/rtpproxy1.sock 60292534 60292341
nsess_created- Number of RTP sessions created
nsess_destroyed- Number of RTP sessions destroyed
nsess_timeout- Number of RTP sessions ended due to media timeout
nsess_complete- Number of RTP sessions fully setup
nsess_nortp- Number of sessions that had no RTP neither in nor out
nsess_owrtp- Number of sessions that had one-way RTP only
nsess_nortcp- Number of sessions that had no RTCP neither in nor out
nsess_owrtcp- Number of sessions that had one-way RTCP only
nplrs_created- Number of RTP players created
nplrs_destroyed- Number of RTP players destroyed
npkts_rcvd- Total number of RTP/RTPC packets received
npkts_played- Total number of RTP packets locally generated (played out)
npkts_relayed- Total number of RTP/RTPC packets relayed
npkts_resizer_in- Total number of RTP packets ingress into resizer (re-packetizer)
npkts_resizer_out- Total number of RTP packets egress out of resizer (re-packetizer)
npkts_resizer_discard- Total number of RTP packets dropped by the resizer (re-packetizer)
npkts_discard- Total number of RTP/RTPC packets discarded
total_duration- Cumulative duration of all sessions
ncmds_rcvd- Total number of control commands received
ncmds_rcvd_ndups- Total number of duplicate control commands received
ncmds_succd- Total number of control commands successfully processed
ncmds_errs- Total number of control commands ended up with an error
ncmds_repld- Total number of control commands that had a reply generated
rtpa_nsent- Total number of uniqie RTP packets sent to us based on SEQ tracking
rtpa_nrcvd- Total number of unique RTP packets received by us based on SEQ tracking
rtpa_ndups- Total number of duplicate RTP packets received by us based on SEQ tracking
rtpa_perrs- Total number of RTP packets that failed RTP parse routine in SEQ tracking
Get info summary
Returns a summary of sessions and packets.
# echo "I" |nc -U /var/run/rtpproxy.sock sessions created: 60293495 active sessions: 217 active streams: 403 packets received: 341220205706 packets transmitted: 348306157118
Play/Inject audio into media stream
P[n] call_id pname codecs from_tag [to_tag]
Q[v] call_id from_tag [to_tag [stat_name1 ...[stat_nameN]]]
The Query command can retrieve various stats for an in progress session.
Stats available via Q command
ttl- remaining time before timeout
npkts_ina- packets received from "answering side"
npkts_ino- packets received from "originating" side
nrelayed- packets relayed
ndropped- packets ignored (i.e. early packets no address to relay)
rtpa_nsent- derived number of packets received based on sequence number
rtpa_nrcvd- actual number of non-duplicate packets received
rtpa_ndups- number of duplicates
rtpa_nlost- derived number of lost packets
rtpa_perrs- packets cannot be parsed or not RTP
When used without any stat names specified, the command will return the following stats by default:
v stands for verbose, and causes the returned parameters
to be in name/value pairs. Without the
v flag, results will be returned
as values separated by a space in order by which they were requested.
Query Command Examples
Query example first creates a session, so we have something to query, then
it queries for the session using the
Query verbose for defaults
# echo "U 123@abc 10.0.0.1 5000 some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock 57796 # echo "Qv 123@abc some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock ttl=59 npkts_ina=0 npkts_ino=0 nrelayed=0 ndropped=0
Query verbose for specific stats
# echo "U 123@abc 10.0.0.1 5000 some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock 57796 # echo "Qv 123@abc some_to_tag some_from_tag rtpa_ndups rtpa_nlost" | nc -U /var/run/rtpproxy.sock rtpa_ndups=0 rtpa_nlost=0
Query for defaults, not verbose
# echo "U 123@abc 10.0.0.1 5000 some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock 57796 # echo "Q 123@abc some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock 53 0 0 0 0
Recording / Copy
R[s] call_id from_tag [to_tag]
C[-xxx-] call_id -XXX- from_tag [to_tag]
C - COPY is synomonous with R for RECORD
Records the media streams related to the specified call_id
rtpproxy must be started with the
-r flag set to the directory where
recordings will be written to as files.
Smerge both media streams to single file. This will only work when RTPProxy records audio in pcap format by starting it with the -P flag. Relies on the command line option
Playback / inject audio into stream
P[n] call_id pname codecs from_tag [to_tag]
Causes the referenced pre-encoded audio to be injected into the specified audio stream.
n option is a integer that will control how many times the audio should
be injected. When
n is not specified, the audio is injected once.
S call_id from_tag [to_tag]
Stops playback of audio that was started using the
Kill all sessions
Deletes all sessions.