-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
1300 lines (1045 loc) · 47.9 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
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. db_url (string)
1.4.10. db_table (string)
1.4.11. socket_column (string)
1.4.12. 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 db_url parameter
1.10. Set db_table parameter
1.11. Set socket_column parameter
1.12. Set set_column parameter
1.13. rtpengine_use_set usage
1.14. rtpengine_offer usage
1.15. rtpengine_offer usage with body replace
1.16. rtpengine_offer usage with call recording
1.17. rtpengine_offer usage for transcoding
1.18. rtpengine_answer usage
1.19. rtpengine_delete usage
1.20. rtpengine_manage usage
1.21. rtpengine_start_recording usage
1.22. rtpengine_stop_recording usage
1.23. Ringback tone using rtpengine_play_media
1.24. Manage music on hold using rtpengine_play_media
1.25. Ringback tone stop using rtpengine_stop_media
1.26. Example of rtpengine_block_media usage
1.27. Example of rtpengine_unblock_media usage
1.28. Example of rtpengine_block_dtmf usage
1.29. Example of rtpengine_unblock_dtmf usage
1.30. Example of rtpengine_start_forwarding usage
1.31. Example of rtpengine_stop_forwarding usage
1.32. Example of rtpengine_play_dtmf usage
1.33. $rtpstat Usage
1.34. $rtpstat(STAT)
1.35. $rtpquery Usage
1.36. rtpengine_enable usage
1.37. rtpengine_show usage
1.38. rtpengine_reload usage
1.39. 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. 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.9. Set db_url parameter
...
modparam("rtpengine", "db_url",
"mysql://opensips:opensipsrw@localhost/opensips")
...
1.4.10. db_table (string)
The table where the RTPEngines sockets are stored. Used when
Database URL is provisioned.
Default value is “rtpengines”.
Example 1.10. Set db_table parameter
...
modparam("rtpengine", "db_table", "rtpengine_new")
...
1.4.11. socket_column (string)
The name of the rtpengine socket column in the database table.
Default value is “socket”.
Example 1.11. Set socket_column parameter
...
modparam("rtpengine", "socket_column", "sock")
...
1.4.12. set_column (string)
The name of the rtpengine set column in the database table.
Default value is “set_id”.
Example 1.12. 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.13. 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.14. 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.15. 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.16. 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.17. 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.18. 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.19. 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.20. 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.21. 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.22. 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.23. Ringback tone using rtpengine_play_media
...
if (is_method("INVITE") && !has_totag())
rtpengine_play_media("file=/path/to/ringback_tone_file.wav");
...
Example 1.24. 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.25. 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.26. 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.27. 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.28. 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.29. 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.30. 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.31. 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.32. 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.33. $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