-
Notifications
You must be signed in to change notification settings - Fork 2.5k
/
janus_streaming.c
9430 lines (9251 loc) · 395 KB
/
janus_streaming.c
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
/*! \file janus_streaming.c
* \author Lorenzo Miniero <[email protected]>
* \copyright GNU General Public License v3
* \brief Janus Streaming plugin
* \details Check the \ref streaming for more details.
*
* \ingroup plugins
* \ref plugins
*
* \page streaming Streaming plugin documentation
* This is a streaming plugin for Janus, allowing WebRTC peers
* to watch/listen to pre-recorded files or media generated by another tool.
* Specifically, the plugin currently supports three different type of streams:
*
* -# on-demand streaming of pre-recorded media files (different
* streaming context for each peer);
* -# live streaming of pre-recorded media files (shared streaming
* context for all peers attached to the stream);
* -# live streaming of media generated by another tool (shared
* streaming context for all peers attached to the stream).
*
* For what concerns types 1. and 2., considering the proof of concept
* nature of the implementation the only pre-recorded media files
* that the plugins supports right now are Opus, raw mu-Law and a-Law files:
* support is of course planned for other additional widespread formats
* as well.
*
* For what concerns type 3., instead, the plugin is configured
* to listen on a few ports for RTP: this means that the plugin
* is implemented to receive RTP on those ports and relay them to all
* peers attached to that stream. Any tool that can generate audio/video
* RTP streams and specify a destination is good for the purpose: the
* examples section contains samples that make use of GStreamer (http://gstreamer.freedesktop.org/)
* but other tools like FFmpeg (http://www.ffmpeg.org/), LibAV (http://libav.org/)
* or others are fine as well. This makes it really easy to capture and
* encode whatever you want using your favourite tool, and then have it
* transparently broadcasted via WebRTC using Janus. Notice that we recently
* added the possibility to also add a datachannel track to an RTP streaming
* mountpoint: this allows you to send, via UDP, a text-based message to
* relay via datachannels (e.g., the title of the current song, if this
* is a radio streaming channel). When using this feature, though, beware
* that you'll have to stay within the boundaries of the MTU, as each
* message will have to stay within the size of an UDP packet.
*
* Streams to make available are listed in the plugin configuration file.
* A pre-filled configuration file is provided in \c conf/janus.plugin.streaming.jcfg
* and includes some examples you can start from.
*
* To add more streams or modify the existing ones, you can use the following
* syntax:
*
* \verbatim
stream-name: {
[settings]
}
\endverbatim
*
* with the allowed settings listed below:
*
* \verbatim
type = rtp|live|ondemand|rtsp
rtp = stream originated by an external tool (e.g., gstreamer or
ffmpeg) and sent to the plugin via RTP
live = local file streamed live to multiple viewers
(multiple viewers = same streaming context)
ondemand = local file streamed on-demand to a single listener
(multiple viewers = different streaming contexts)
rtsp = stream originated by an external RTSP feed (only
available if libcurl support was compiled)
id = <unique numeric ID>
description = This is my awesome stream
metadata = An optional string that can contain any metadata (e.g., JSON)
associated with the stream you want users to receive
is_private = true|false (private streams don't appear when you do a 'list' request)
filename = path to the local file to stream (only for live/ondemand)
secret = <optional password needed for manipulating (e.g., destroying
or enabling/disabling) the stream>
pin = <optional password needed for watching the stream>
audio = true|false (do/don't stream audio)
video = true|false (do/don't stream video)
The following options are only valid for the 'rtp' type:
data = true|false (do/don't stream text via datachannels)
audioport = local port for receiving audio frames
audiortcpport = local port for receiving and sending audio RTCP feedback
audiomcast = multicast group for receiving audio frames, if any
audioiface = network interface or IP address to bind to, if any (binds to all otherwise)
audiopt = <audio RTP payload type> (e.g., 111)
audiortpmap = RTP map of the audio codec (e.g., opus/48000/2)
audiofmtp = Codec specific parameters, if any
audioskew = true|false (whether the plugin should perform skew
analisys and compensation on incoming audio RTP stream, EXPERIMENTAL)
videoport = local port for receiving video frames (only for rtp)
videortcpport = local port for receiving and sending video RTCP feedback
videomcast = multicast group for receiving video frames, if any
videoiface = network interface or IP address to bind to, if any (binds to all otherwise)
videopt = <video RTP payload type> (e.g., 100)
videortpmap = RTP map of the video codec (e.g., VP8/90000)
videofmtp = Codec specific parameters, if any
videobufferkf = true|false (whether the plugin should store the latest
keyframe and send it immediately for new viewers, EXPERIMENTAL)
videosimulcast = true|false (do|don't enable video simulcasting)
videoport2 = second local port for receiving video frames (only for rtp, and simulcasting)
videoport3 = third local port for receiving video frames (only for rtp, and simulcasting)
videoskew = true|false (whether the plugin should perform skew
analisys and compensation on incoming video RTP stream, EXPERIMENTAL)
videosvc = true|false (whether the video will have SVC support; works only for VP9-SVC, default=false)
collision = in case of collision (more than one SSRC hitting the same port), the plugin
will discard incoming RTP packets with a new SSRC unless this many milliseconds
passed, which would then change the current SSRC (0=disabled)
dataport = local port for receiving data messages to relay
datamcast = multicast group for receiving data messages, if any
dataiface = network interface or IP address to bind to, if any (binds to all otherwise)
datatype = text|binary (type of data this mountpoint will relay, default=text)
databuffermsg = true|false (whether the plugin should store the latest
message and send it immediately for new viewers)
threads = number of threads to assist with the relaying part, which can help
if you expect a lot of viewers that may cause the RTP receiving part
in the Streaming plugin to slow down and fail to catch up (default=0)
In case you want to use SRTP for your RTP-based mountpoint, you'll need
to configure the SRTP-related properties as well, namely the suite to
use for hashing (32 or 80) and the crypto information for decrypting
the stream (as a base64 encoded string the way SDES does it). Notice
that with SRTP involved you'll have to pay extra attention to what you
feed the mountpoint, as you may risk getting SRTP decrypt errors:
srtpsuite = 32
srtpcrypto = WbTBosdVUZqEb6Htqhn+m3z7wUh4RJVR8nE15GbN
The Streaming plugin can also be used to (re)stream media that has been
encrypted using something that can be consumed via Insertable Streams.
In that case, we only need to be aware of it, so that we can send the
info along with the SDP. How to decrypt the media is out of scope, and
up to the application since, again, this is end-to-end encryption and
so neither Janus nor the Streaming plugin have access to anything.
DO NOT SET THIS PROPERTY IF YOU DON'T KNOW WHAT YOU'RE DOING!
e2ee = true
To allow mountpoints to negotiate the playout-delay RTP extension,
you can set the 'playoutdelay_ext' property to true: this way, any
subscriber can customize the playout delay of incoming video streams,
assuming the browser supports the RTP extension in the first place.
playoutdelay_ext = true
The following options are only valid for the 'rtsp' type:
url = RTSP stream URL
rtsp_user = RTSP authorization username, if needed
rtsp_pwd = RTSP authorization password, if needed
rtsp_failcheck = whether an error should be returned if connecting to the RTSP server fails (default=true)
rtspiface = network interface IP address or device name to listen on when receiving RTSP streams
rtsp_reconnect_delay = after n seconds passed and no media assumed, the RTSP server has gone and schedule a reconnect (default=5s)
rtsp_session_timeout = by default the streaming plugin will check the RTSP connection with an OPTIONS query,
the value of the timeout comes from the RTSP session initializer and by default
this session timeout is the half of this value In some cases this value can be too high (for example more than one minute)
because of the media server. In that case this plugin will calculate the timeout with this
formula: timeout = min(session_timeout, rtsp_session_timeout / 2). (default=0s)
rtsp_timeout = communication timeout (CURLOPT_TIMEOUT) for cURL call gathering the RTSP information (default=10s)
rtsp_conn_timeout = connection timeout for cURL (CURLOPT_CONNECTTIMEOUT) call gathering the RTSP information (default=5s)
\endverbatim
*
* Notice that attributes like \c audioport or \c videopt only make sense
* when you're creating a mountpoint with a single audio and/or video stream,
* as the plugin in that case assumes that limitation is fine by you. In
* case you're interested in creating multistream mountpoints, that is
* mountpoints that can contain more than one audio and/or video stream
* at the same time, you HAVE to use a different syntax. Specifically,
* you'll need to use a \c media array/list, containing the different
* streams, in the right order, that you want to make available: each
* stream will then need to contain the related info, e.g., port to bind
* to, type of media, rtpmap and so on. An example is provided below:
*
\verbatim
multistream-test: {
type = "rtp"
id = 123
description = "Multistream test (1 audio, 2 video)"
media = (
{
type = "audio"
mid = "a"
label = "Audio stream"
port = 5102
pt = 111
rtpmap = "opus/48000/2"
},
{
type = "video"
mid = "v1"
label = "Video stream #1"
port = 5104
pt = 100
rtpmap = "VP8/90000"
},
{
type = "video"
mid = "v2"
label = "Video stream #2"
port = 5106
pt = 100
rtpmap = "VP8/90000"
}
)
}
\endverbatim
*
* In the above example, we're creating a mountpoint with a single audio
* stream and two different video streams: each stream has a unique \c mid
* (that you MUST provide) which is what will be used for the SDP offer
* to send to viewers, and their unique configuration properties. As you
* can see, it's much cleaner in the way you create and configure
* mountpoints: there's no hardcoded audio/video prefix for the name of
* properties, you configure media streams the same way and just add them
* to a list. Notice that of course this also works with the simple one
* audio/one video mountpoints you've used so far, and that has been
* documented before: as such, you're encouraged to start using this
* new approach as soon as possible, since in the next versions we
* might deprecate the old one.
*
* \section streamapi Streaming API
*
* The Streaming API supports several requests, some of which are
* synchronous and some asynchronous. There are some situations, though,
* (invalid JSON, invalid request) which will always result in a
* synchronous error response even for asynchronous requests.
*
* \c list , \c info , \c create , \c destroy , \c recording , \c edit ,
* \c enable and \c disable are synchronous requests, which means you'll
* get a response directly within the context of the transaction. \c list
* lists all the available streams; \c create allows you to create a new
* mountpoint dynamically, as an alternative to using the configuration
* file; \c destroy removes a mountpoint and destroys it; \c recording
* instructs the plugin on whether or not a live RTP stream should be
* recorded while it's broadcasted; \c enable and \c disable respectively
* enable and disable a mountpoint, that is decide whether or not a
* mountpoint should be available to users without destroying it.
* \c edit allows you to dynamically edit some mountpoint properties (e.g., the PIN);
*
* The \c watch , \c start , \c configure , \c pause , \c switch and \c stop requests
* instead are all asynchronous, which means you'll get a notification
* about their success or failure in an event. \c watch asks the plugin
* to prepare the playout of one of the available streams; \c start
* starts the actual playout; \c pause allows you to pause a playout
* without tearing down the PeerConnection; \c switch allows you to
* switch to a different mountpoint of the same kind (note: only live
* RTP mountpoints supported as of now) without having to stop and watch
* the new one; \c stop stops the playout and tears the PeerConnection
* down.
*
* Notice that, in general, all users can create mountpoints, no matter
* what type they are. If you want to limit this functionality, you can
* configure an admin \c admin_key in the plugin settings. When
* configured, only "create" requests that include the correct
* \c admin_key value in an "admin_key" property will succeed, and will
* be rejected otherwise.
*
* \subsection streamingsync Synchronous requests
*
* To list the available Streaming mountpoints (both those created via
* configuration file and those created via API), you can use the \c list
* request:
*
\verbatim
{
"request" : "list"
}
\endverbatim
*
* If successful, it will return an array with a list of all the mountpoints.
* Notice that only the public mountpoints will be returned: those with
* an \c is_private set to yes/true will be skipped. The response will
* be formatted like this:
*
\verbatim
{
"streaming" : "list",
"list" : [
{
"id" : <unique ID of mountpoint #1>,
"type" : "<type of mountpoint #1, in line with the types introduced above>",
"description" : "<description of mountpoint #1>",
"metadata" : "<metadata of mountpoint #1, if any>",
"enabled" : <true|false, depending on whether the mountpoint is currently enabled or not>,
"media" : [
{
"mid" : "<unique mid of this stream>",
"label" : "<unique text label of this stream>",
"type" : "<audio|video|data">,
"age_ms" : <how much time passed since we last received media for this stream; optional>,
},
{
// Other streams, if available
}
]
},
{
"id" : <unique ID of mountpoint #2>,
"type" : "<type of mountpoint #2, in line with the types introduced above>",
"description" : "<description of mountpoint #2>",
"metadata" : "<metadata of mountpoint #2, if any>",
"media" : [..]
},
...
]
}
\endverbatim
*
* As you can see, the \c list request only returns very generic info on
* each mountpoint. In case you're interested in learning more details about
* a specific mountpoint, you can use the \c info request instead, which
* returns more information, or all of it if the mountpoint secret is
* provided in the request. An \c info request must be formatted like this:
*
\verbatim
{
"request" : "info"
"id" : <unique ID of mountpoint to query>,
"secret" : <mountpoint secret; optional, can be used to return more info>"
}
\endverbatim
*
* If successful, this will have the plugin return an object containing
* more info on the mountpoint:
*
\verbatim
{
"streaming" : "info",
"info" : {
"id" : <unique ID of mountpoint>,
"name" : "<unique name of mountpoint>",
"description" : "<description of mountpoint>",
"metadata" : "<metadata of mountpoint, if any>",
"secret" : "<secret of mountpoint; only available if a valid secret was provided>",
"pin" : "<PIN to access mountpoint; only available if a valid secret was provided>",
"is_private" : <true|false, depending on whether the mountpoint is listable; only available if a valid secret was provided>,
"viewers" : <count of current subscribers, if any>,
"enabled" : <true|false, depending on whether the mountpoint is currently enabled or not>,
"type" : "<type of mountpoint>",
"media" : [
{
"mid" : "<unique mid of this stream>",
"mindex" : "<unique mindex of this stream>",
"type" : "<audio|video|data">,
"label" : "<unique text label of this stream>",
"age_ms" : <how much time passed since we last received media for this stream; optional>,
"pt" : <payload type, only present if RTP and configured>,
"rtpmap" : "<SDP rtpmap value, only present if RTP and configured>",
"fmtp" : "<audio SDP fmtp value, only present if RTP and configured>",
...
},
{
// Other streams, if available
}
]
}
}
\endverbatim
*
* Considering the different mountpoint types that you can create in this
* plugin, the nature of the rest of the returned info obviously depends
* on which mountpoint you're querying. This is especially true for RTP
* and RTSP mountpoints. Notice that info like the ports an RTP mountpoint
* is listening on will only be returned if you provide the correct secret,
* as otherwise they're treated like sensitive information and are not
* returned to generic \c info calls.
*
* We've seen how you can create a new mountpoint via configuration file,
* but you can create one via API as well, using the \c create request.
* Most importantly, you can also choose whether or not a \c create
* request should result in the mountpoint being saved to configuration
* file so that it's still available after a server restart. The common
* syntax for all \c create requests is the following:
*
\verbatim
{
"request" : "create",
"admin_key" : "<plugin administrator key; mandatory if configured>",
"type" : "<type of the mountpoint to create; mandatory>",
"id" : <unique ID to assign the mountpoint; optional, will be chosen by the server if missing>,
"name" : "<unique name for the mountpoint; optional, will be chosen by the server if missing>",
"description" : "<description of mountpoint; optional>",
"metadata" : "<metadata of mountpoint; optional>",
"secret" : "<secret to query/edit the mountpoint later; optional>",
"pin" : "<PIN required for viewers to access mountpoint; optional>",
"is_private" : <true|false, whether the mountpoint should be listable; true by default>,
"media" : [
{
"type" : "<audio|video|data>",
"mid" : "<unique mid to assign to this stream in negotiated PeerConnections>",
"port" : <port to bind to, to receive media to relay>",
...
}.
... other streams, if any ...
],
...
"permanent" : <true|false, whether the mountpoint should be saved to configuration file or not; false by default>,
...
}
\endverbatim
*
* Of course, different mountpoint types will have different properties
* you can specify in a \c create. Please refer to the documentation on
* configuration files to see the fields you can pass. The only important
* difference to highlight is that, unlike in configuration files, you will
* NOT have to escape semicolons with a trailing slash, in those properties
* where a semicolon might be needed (e.g., \c audiofmtp or \c videofmtp ).
*
* Notice that, just as we introduced the possibility of configuring multistream
* mountpoints statically with a \c media array, the same applies when using
* the API to create them: just add a \c media JSON array containing the
* list of streams to create and the related properties as you would do
* statically (that is, using generic properties like \c port, \c fmtp,
* etc., rather than the hardcoded \c audioport and the like), and it
* will work for dynamically created mountpoints as well.
*
* A successful \c create will result in a \c created response:
*
\verbatim
{
"streaming" : "created",
"create" : "<unique name of the just created mountpoint>",
"permanent" : <true|false, depending on whether the mountpoint was saved to configuration file or not>,
"stream": {
"id" : <unique ID of the just created mountpoint>,
"type" : "<type of the just created mountpoint>",
"description" : "<description of the just created mountpoint>",
"is_private" : <true|false, depending on whether the new mountpoint is listable>,
"ports" : [ // Only for RTP mountpoints
{
"type" : "<audio|video|data>",
"mid" : "<unique mid of stream #1>",
"port" : <port the plugin is listening on for this stream's media>
},
{
// Other streams, if available
}
]
...
}
}
\endverbatim
*
* Notice that additional information, namely the ports the mountpoint
* bound to, will only be added for new RTP mountpoints, otherwise this
* is all that a \c created request will contain. If you want to double
* check everything in your \c create request went as expected, you may
* want to issue a followup \c info request to compare the results.
*
* Once you created a mountpoint, you can modify some (not all) of its
* properties via an \c edit request. Namely, you can only modify generic
* properties like the mountpoint description, the secret, the PIN and
* whether or not the mountpoint should be listable. All other properties
* are considered to be immutable. Again, you can choose whether the changes
* should be permanent, e.g., saved to configuration file, or not. Notice
* that an \c edit request requires the right secret to be provided, if
* the mountpoint has one, or will return an error instead. The \c edit
* request must be formatted like this:
*
\verbatim
{
"request" : "edit",
"id" : <unique ID of the mountpoint to edit; mandatory>,
"secret" : "<secret to edit the mountpoint; mandatory if configured>",
"new_description" : "<new description for the mountpoint; optional>",
"new_metadata" : "<new metadata for the mountpoint; optional>",
"new_secret" : "<new secret for the mountpoint; optional>",
"new_pin" : "<new PIN for the mountpoint; optional>",
"new_is_private" : <true|false, depending on whether the mountpoint should be now listable; optional>,
"permanent" : <true|false, whether the mountpoint should be saved to configuration file or not; false by default>
}
\endverbatim
*
* A successful \c edit will result in an \c edited response:
*
\verbatim
{
"streaming" : "edited",
"id" : <unique ID of the just edited mountpoint>,
"permanent" : <true|false, depending on whether the changes were saved to configuration file or not>
}
\endverbatim
*
* Just as you can create and edit mountpoints, you can of course also destroy
* them. Again, this applies to all mountpoints, whether created statically
* via configuration file or dynamically via API, and the mountpoint destruction
* can be made permanent in the configuration file as well. A \c destroy
* request must be formatted as follows:
*
\verbatim
{
"request" : "destroy",
"id" : <unique ID of the mountpoint to destroy; mandatory>,
"secret" : "<secret to destroy the mountpoint; mandatory if configured>",
"permanent" : <true|false, whether the mountpoint should be removed from the configuration file or not; false by default>
}
\endverbatim
*
* If successful, the result will be confirmed in a \c destroyed event:
*
\verbatim
{
"streaming" : "destroyed",
"id" : <unique ID of the just destroyed mountpoint>
}
\endverbatim
*
* Notice that destroying a mountpoint while viewers are still subscribed
* to it will result in all viewers being removed, and their PeerConnection
* closed as a consequence.
*
* You can also dynamically enable and disable mountpoints via API. A
* disabled mountpoint is a mountpoint that exists, and still works as
* expected, but is not accessible to viewers until it's enabled again.
* This is a useful property, especially in case of mountpoints that
* need to be prepared in advance but must not be accessible until a
* specific moment, and a much better alternative to just create the
* mountpoint at the very last minute and destroy it otherwise. The
* syntax for both the \c enable and \c disable requests is the same,
* and looks like the following:
*
\verbatim
{
"request" : "enable",
"id" : <unique ID of the mountpoint to enable; mandatory>,
"secret" : "<secret to enable the mountpoint; mandatory if configured>"
}
\endverbatim
*
* If successful, a generic \c ok is returned:
*
\verbatim
{
"streaming" : "ok"
}
\endverbatim
\verbatim
{
"request" : "disable",
"id" : <unique ID of the mountpoint to disable; mandatory>,
"stop_recording" : <true|false, whether the recording should also be stopped or not; true by default>
"secret" : "<secret to disable the mountpoint; mandatory if configured>"
}
\endverbatim
*
* If successful, a generic \c ok is returned:
*
\verbatim
{
"streaming" : "ok"
}
\endverbatim
*
* Finally, you can record a mountpoint to the internal Janus .mjr format
* using the \c recording request. The same request can also be used to
* stop recording. Although the same request is used in both cases, though,
* the syntax for the two use cases differs a bit, namely in terms of the
* type of some properties. Notice that, while for backwards compatibility
* you can still use the old \c audio, \c video and \c data named properties,
* they're now deprecated and so you're highly encouraged to use the new drill-down
* \c media list instead.
*
* To start recording a new mountpoint, the request should be formatted
* like this:
*
\verbatim
{
"request" : "recording",
"action" : "start",
"id" : <unique ID of the mountpoint to manipulate; mandatory>,
"media" : [ // Drill-down recording controls
{
"mid" : "<mid of the stream to start recording>",
"filename" : "<base path/filename to use for the recording>"
},
{
// Recording controls for other streams, if provided
}
]
}
\endverbatim
*
* To stop a recording, instead, this is the request syntax:
*
\verbatim
{
"request" : "recording",
"action" : "stop",
"id" : <unique ID of the mountpoint to manipulate; mandatory>,
"media" : [ // Drill-down recording controls
{
"mid" : "<mid of the stream to stop recording>"
},
{
// Recording controls for other streams, if provided
}
]
}
\endverbatim
*
* When using the deprecated properties, when starting a recording the \c audio ,
* \c video and \c data properties are strings, and specify the base path
* to use for the recording filename; when stopping a recording, instead,
* they're interpreted as boolean properties. This is one more reason why
* you should migrate to the new \c media list instead, as it doesn't have
* this ambiguity between the two different requests. Notice that, as with all
* APIs that wrap .mjr recordings, the filename you specify here is not
* the actual filename: an \c .mjr extension is always going to be added
* by the Janus core, so you should take this into account when tracking
* the related recording files.
*
* Whether you started or stopped a recording, a successful request will
* always result in a simple \c ok response:
*
\verbatim
{
"streaming" : "ok"
}
\endverbatim
*
* \subsection streamingasync Asynchronous requests
*
* All the requests we've gone through so far are synchronous. This means
* that they return a response right away. That said, many of the requests
* this plugin supports are asynchronous instead, which means Janus will
* send an ack when they're received, and a response will only follow
* later on. This is especially true for requests dealing with the
* management and setup of mountpoint viewers, e.g., for the purpose of
* negotiating a WebRTC PeerConnection to receive media from a mountpoint.
*
* To subscribe to a specific mountpoint, an interested viewer can make
* use of the \c watch request. As suggested by the request name, this
* instructs the plugin to setup a new PeerConnection to allow the new
* viewer to watch the specified mountpoint. The \c watch request must
* be formatted like this:
*
\verbatim
{
"request" : "watch",
"id" : <unique ID of the mountpoint to subscribe to; mandatory>,
"pin" : "<PIN required to access the mountpoint; mandatory if configured>",
"media" : [
<array of mids to subscribe to, as strings; optional, missing or empty array subscribes to all mids>
]
"offer_audio" : <true|false; deprecated; whether or not audio should be negotiated; true by default if the mountpoint has audio>,
"offer_video" : <true|false; deprecated; whether or not video should be negotiated; true by default if the mountpoint has video>,
"offer_data" : <true|false; deprecated; whether or not datachannels should be negotiated; true by default if the mountpoint has datachannels>
}
\endverbatim
*
* As you can see, it's just a matter of specifying the ID of the mountpoint to
* subscribe to and, if needed, the PIN to access the mountpoint in case
* it's protected. The \c media array is particularly interesting, as it
* allows you to only subscribe to a subset of the mountpoint media, which
* you can address by the related \c mid property of each stream. By default,
* in fact, a \c watch request will result in the plugin preparing a new
* SDP offer trying to negotiate all the media streams available in the
* mountpoint; in case the viewer knows they don't support one of the
* mountpoint codecs, though (e.g., the video in the mountpoint is VP8,
* but they only support H.264), or are not interested in getting all the
* media (e.g., they're ok with just audio and not video, or don't have
* enough bandwidth for both), they can use those properties to shape the
* SDP offer to their needs. The \c media array is optional, as a missing
* or empty array will simply be interpreted as a willingness to subscribe
* to all the streams in the mountpoint, which is the default behaviour.
* Notice that the order of the mids in the \c media array is irrelevant,
* as is how many times the same mid is listed in the array: the presence
* of a mid is just interpreted as an "on" switch for that stream, meaning
* it will be offered in the SDP.
*
* \note For backwards compatibility, the deprecated \c offer_audio ,
* \c offer_video and \c offer_data properties are also available. They
* also allow you to only subscribe to a subset of the mountpoint media,
* but with a more crude approach: specifically, they dictate whether or
* not any audio, video or data stream should be offered or not.
*
* As anticipated, if successful this request will generate a new JSEP SDP
* offer, which will be attached to a \c preparing status event:
*
\verbatim
{
"status" : "preparing"
}
\endverbatim
*
* At this stage, to complete the setup of a subscription the viewer is
* supposed to send a JSEP SDP answer back to the plugin. This is done
* by means of a \c start request, which in this case MUST be associated
* with a JSEP SDP answer but otherwise requires no arguments:
*
\verbatim
{
"request" : "start"
}
\endverbatim
*
* If successful this request returns a \c starting status event:
*
\verbatim
{
"status" : "starting"
}
\endverbatim
*
* Once this is done, all that's needed is waiting for the WebRTC PeerConnection
* establishment to succeed. As soon as that happens, the Streaming plugin
* can start relaying media from the mountpoint the viewer subscribed to
* to the viewer themselves.
*
* Notice that the same exact steps we just went through (\c watch request,
* followed by JSEP offer by the plugin, followed by \c start request with
* JSEP answer by the viewer) is what you also use when renegotiations are
* needed, e.g., for the purpose of ICE restarts.
*
* As a viewer, you can temporarily pause and resume the whole media delivery
* with a \c pause and, again, \c start request (in this case without any JSEP
* SDP answer attached). Neither expect other arguments, as the context
* is implicitly derived from the handle they're sent on:
*
\verbatim
{
"request" : "pause"
}
\endverbatim
*
\verbatim
{
"request" : "start"
}
\endverbatim
*
* Unsurprisingly, they just result in, respectively, \c pausing and
* \c starting events:
*
\verbatim
{
"status" : "pausing"
}
\endverbatim
*
\verbatim
{
"status" : "starting"
}
\endverbatim
*
* For more drill-down manipulations of a subscription, a \c configure
* request can be used instead. This request allows viewers to dynamically
* change some properties associated to their media subscription, e.g.,
* in terms of what should and should not be sent at a specific time. A
* \c configure request must be formatted as follows:
*
\verbatim
{
"request" : "configure",
"mid" : <mid of the m-line to refer to for this configure request; optional>,
"send" : <true|false, depending on whether the media addressed by the above mid should be relayed or not; optional>,
"substream" : <substream to receive (0-2), in case simulcasting is enabled; optional>,
"temporal" : <temporal layers to receive (0-2), in case simulcasting is enabled; optional>,
"fallback" : <How much time (in us, default 250000) without receiving packets will make us drop to the substream below>,
"spatial_layer" : <spatial layer to receive (0-1), in case VP9-SVC is enabled; optional>,
"temporal_layer" : <temporal layers to receive (0-2), in case VP9-SVC is enabled; optional>,
"min_delay" : <minimum delay to enforce via the playout-delay RTP extension, in blocks of 10ms; optional>,
"max_delay" : <maximum delay to enforce via the playout-delay RTP extension, in blocks of 10ms; optional>
}
\endverbatim
*
* While the deprecated \c audio , \c video and \c data properties can still be
* used as a media-level pause/resume functionality, a better option is to
* specify the \c mid of the stream instead, and a \c send boolean property
* to specify if this specific stream should be relayed or not. The \c pause
* and \c start requests instead pause and resume all streams at the same time.
* The \c substream and \c temporal properties, finally, only make sense
* when the mountpoint is configured with video simulcasting support, and
* as such the viewer is interested in receiving a specific substream
* or temporal layer, rather than any other of the available ones.
* The \c spatial_layer and \c temporal_layer have exactly the same meaning,
* but within the context of VP9-SVC mountpoints, and will have no effect
* on mountpoints involving a different video codec. In both cases, make
* sure you specify the \c mid of the stream in case multiple videos are
* available in a mountpoint, or the request may have no effect.
*
* Another interesting feature in the Streaming plugin is the so-called
* mountpoint "switching". Basically, when subscribed to a specific
* mountpoint and receiving media from there, you can at any time "switch"
* to a different mountpoint, and as such start receiving media from that
* other mountpoint instead. Think of it as changing channel on a TV: you
* keep on using the same PeerConnection, the plugin simply changes the
* source of the media transparently. Of course, while powerful and effective
* this request has some limitations. First of all, it only works with RTP
* mountpoints, and not other mountpoint types; besides, the two mountpoints
* must have the same media configuration, that is, use the same codecs,
* the same payload types, etc. In fact, since the same PeerConnection is
* used for this feature, switching to a mountpoint with a different
* configuration might result in media incompatible with the PeerConnection
* setup being relayed to the viewer, and as such in no audio/video being
* played. That said, a \c switch request must be formatted like this:
*
\verbatim
{
"request" : "switch",
"id" : <unique ID of the new mountpoint to switch to; mandatory>
}
\endverbatim
*
* If successful, you'll be unsubscribed from the previous mountpoint,
* and subscribed to the new mountpoint instead. The event to confirm
* the switch was successful will look like this:
*
\verbatim
{
"switched" : "ok",
"id" : <unique ID of the new mountpoint>
}
\endverbatim
*
* Finally, to stop the subscription to the mountpoint and tear down the
* related PeerConnection, you can use the \c stop request. Since context
* is implicit, no other argument is required:
*
\verbatim
{
"request" : "stop"
}
\endverbatim
*
* If successful, the plugin will attempt to tear down the PeerConnection,
* and will send back a \c stopping status event:
*
\verbatim
{
"status" : "stopping"
}
\endverbatim
*
* Once a PeerConnection has been torn down and the subscription closed,
* as a viewer you're free to subscribe to a different mountpoint instead.
* In fact, while you can't watch more than one mountpoint at the same
* time on the same handle, there's no limit on how many mountpoints
* you can watch in sequence, again on the same handle. If you're interested
* in subscribing to multiple mountpoints at the same time, instead, you'll
* have to create multiple handles for the purpose.
*/
#include "plugin.h"
#include <errno.h>
#include <netdb.h>
#include <sys/poll.h>
#include <sys/socket.h>
#include <sys/time.h>
#include <jansson.h>
#ifdef HAVE_LIBCURL
#include <curl/curl.h>
#ifndef CURL_AT_LEAST_VERSION
#define CURL_AT_LEAST_VERSION(x,y,z) 0
#endif
#endif
#ifdef HAVE_LIBOGG
#include <ogg/ogg.h>
#endif
#include "../debug.h"
#include "../apierror.h"
#include "../config.h"
#include "../mutex.h"
#include "../rtp.h"
#include "../rtpsrtp.h"
#include "../rtcp.h"
#include "../record.h"
#include "../utils.h"
#include "../ip-utils.h"
/* Default settings */
#define JANUS_STREAMING_DEFAULT_SESSION_TIMEOUT 0 /* Overwrite the RTSP session timeout. If set to zero, the RTSP timeout is derived from a session. */
#define JANUS_STREAMING_DEFAULT_RECONNECT_DELAY 5 /* Reconnecting delay in seconds. */
#define JANUS_STREAMING_DEFAULT_CURL_TIMEOUT 10L /* Communication timeout for cURL. */
#define JANUS_STREAMING_DEFAULT_CURL_CONNECT_TIMEOUT 5L /* Connection timeout for cURL. */
/* Plugin information */
#define JANUS_STREAMING_VERSION 8
#define JANUS_STREAMING_VERSION_STRING "0.0.8"
#define JANUS_STREAMING_DESCRIPTION "This is a streaming plugin for Janus, allowing WebRTC peers to watch/listen to pre-recorded files or media generated by an external source."
#define JANUS_STREAMING_NAME "JANUS Streaming plugin"
#define JANUS_STREAMING_AUTHOR "Meetecho s.r.l."
#define JANUS_STREAMING_PACKAGE "janus.plugin.streaming"
/* Plugin methods */
janus_plugin *create(void);
int janus_streaming_init(janus_callbacks *callback, const char *config_path);
void janus_streaming_destroy(void);
int janus_streaming_get_api_compatibility(void);
int janus_streaming_get_version(void);
const char *janus_streaming_get_version_string(void);
const char *janus_streaming_get_description(void);
const char *janus_streaming_get_name(void);
const char *janus_streaming_get_author(void);
const char *janus_streaming_get_package(void);
void janus_streaming_create_session(janus_plugin_session *handle, int *error);
struct janus_plugin_result *janus_streaming_handle_message(janus_plugin_session *handle, char *transaction, json_t *message, json_t *jsep);
json_t *janus_streaming_handle_admin_message(json_t *message);
void janus_streaming_setup_media(janus_plugin_session *handle);
void janus_streaming_incoming_rtp(janus_plugin_session *handle, janus_plugin_rtp *packet);
void janus_streaming_incoming_rtcp(janus_plugin_session *handle, janus_plugin_rtcp *packet);
void janus_streaming_data_ready(janus_plugin_session *handle);
void janus_streaming_hangup_media(janus_plugin_session *handle);
void janus_streaming_destroy_session(janus_plugin_session *handle, int *error);
json_t *janus_streaming_query_session(janus_plugin_session *handle);
static int janus_streaming_get_fd_port(int fd);
/* Plugin setup */
static janus_plugin janus_streaming_plugin =
JANUS_PLUGIN_INIT (
.init = janus_streaming_init,
.destroy = janus_streaming_destroy,
.get_api_compatibility = janus_streaming_get_api_compatibility,
.get_version = janus_streaming_get_version,
.get_version_string = janus_streaming_get_version_string,
.get_description = janus_streaming_get_description,
.get_name = janus_streaming_get_name,
.get_author = janus_streaming_get_author,
.get_package = janus_streaming_get_package,
.create_session = janus_streaming_create_session,
.handle_message = janus_streaming_handle_message,
.handle_admin_message = janus_streaming_handle_admin_message,
.setup_media = janus_streaming_setup_media,
.incoming_rtp = janus_streaming_incoming_rtp,
.incoming_rtcp = janus_streaming_incoming_rtcp,
.data_ready = janus_streaming_data_ready,
.hangup_media = janus_streaming_hangup_media,
.destroy_session = janus_streaming_destroy_session,
.query_session = janus_streaming_query_session,
);
/* Plugin creator */
janus_plugin *create(void) {
JANUS_LOG(LOG_VERB, "%s created!\n", JANUS_STREAMING_NAME);
return &janus_streaming_plugin;
}
/* Parameter validation */
static struct janus_json_parameter request_parameters[] = {
{"request", JSON_STRING, JANUS_JSON_PARAM_REQUIRED}
};
static struct janus_json_parameter id_parameters[] = {
{"id", JSON_INTEGER, JANUS_JSON_PARAM_REQUIRED | JANUS_JSON_PARAM_POSITIVE}
};
static struct janus_json_parameter idopt_parameters[] = {
{"id", JSON_INTEGER, JANUS_JSON_PARAM_POSITIVE}
};
static struct janus_json_parameter idstr_parameters[] = {
{"id", JSON_STRING, JANUS_JSON_PARAM_REQUIRED}
};
static struct janus_json_parameter idstropt_parameters[] = {
{"id", JSON_STRING, 0}
};
static struct janus_json_parameter watch_parameters[] = {
{"pin", JSON_STRING, 0},
{"media", JANUS_JSON_ARRAY, 0},
{"restart", JANUS_JSON_BOOL, 0},
/* Deprecated parameters: still there only for
* backwards compatibility, but not for long */
{"offer_audio", JANUS_JSON_BOOL, 0},
{"offer_video", JANUS_JSON_BOOL, 0},
{"offer_data", JANUS_JSON_BOOL, 0},
};
static struct janus_json_parameter adminkey_parameters[] = {
{"admin_key", JSON_STRING, JANUS_JSON_PARAM_REQUIRED}
};
static struct janus_json_parameter edit_parameters[] = {
{"new_description", JSON_STRING, 0},
{"new_secret", JSON_STRING, 0},
{"new_pin", JSON_STRING, 0},
{"new_is_private", JANUS_JSON_BOOL, 0},
{"permanent", JANUS_JSON_BOOL, 0}
};
static struct janus_json_parameter create_parameters[] = {
{"name", JSON_STRING, 0},
{"description", JSON_STRING, 0},
{"metadata", JSON_STRING, 0},
{"is_private", JANUS_JSON_BOOL, 0},
{"type", JSON_STRING, JANUS_JSON_PARAM_REQUIRED},
{"secret", JSON_STRING, 0},
{"pin", JSON_STRING, 0},
{"media", JANUS_JSON_ARRAY, 0},
{"permanent", JANUS_JSON_BOOL, 0},
/* Deprecated parameters: still there only for
* backwards compatibility, but not for long */
{"audio", JANUS_JSON_BOOL, 0},
{"video", JANUS_JSON_BOOL, 0},
{"data", JANUS_JSON_BOOL, 0},
};
static struct janus_json_parameter rtp_parameters[] = {
{"collision", JSON_INTEGER, JANUS_JSON_PARAM_POSITIVE},
{"threads", JSON_INTEGER, JANUS_JSON_PARAM_POSITIVE},
{"srtpsuite", JSON_INTEGER, JANUS_JSON_PARAM_POSITIVE},
{"srtpcrypto", JSON_STRING, 0},