Loading...
Searching...
No Matches
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:
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 couple of 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 conf/janus.plugin.streaming.jcfg and includes a stream of every type.
To add more streams or modify the existing ones, you can use the following syntax:
stream-name: {
[settings]
}
with the allowed settings listed below:
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
analysis 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
analysis 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)
h264sps = if using H.264 as a video codec, value of the sprop-parameter-sets
that would normally be sent via SDP, but that we'll use to instead
manually ingest SPS and PPS packets via RTP for streams that miss it
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
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_quirk = Some RTSP servers offer the stream using only the path, instead of the fully qualified URL.
If set true, this boolean informs Janus that we should try a path-only DESCRIBE request if the initial request returns 404.
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)
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.
list , info , create , destroy , recording , edit , enable and disable are synchronous requests, which means you'll get a response directly within the context of the transaction. list lists all the available streams; create allows you to create a new mountpoint dynamically, as an alternative to using the configuration file; destroy removes a mountpoint and destroys it; recording instructs the plugin on whether or not a live RTP stream should be recorded while it's broadcasted; enable and disable respectively enable and disable a mountpoint, that is decide whether or not a mountpoint should be available to users without destroying it. edit allows you to dynamically edit some mountpoint properties (e.g., the PIN);
The watch , start , configure , pause , switch and stop requests instead are all asynchronous, which means you'll get a notification about their success or failure in an event. watch asks the plugin to prepare the playout of one of the available streams; start starts the actual playout; pause allows you to pause a playout without tearing down the PeerConnection; 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; 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 admin_key in the plugin settings. When configured, only "create" requests that include the correct admin_key value in an "admin_key" property will succeed, and will be rejected otherwise.
To list the available Streaming mountpoints (both those created via configuration file and those created via API), you can use the list request:
{
"request" : "list"
}
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 is_private set to yes/true will be skipped. The response will be formatted like this:
{
"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>,
"audio_age_ms" : <how much time passed since we last received audio; optional, available for RTP mountpoints only>,
"video_age_ms" : <how much time passed since we last received video; optional, available for RTP mountpoints only>
},
{
"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>",
"audio_age_ms" : <how much time passed since we last received audio; optional, available for RTP mountpoints only>,
"video_age_ms" : <how much time passed since we last received video; optional, available for RTP mountpoints only>
},
...
]
}
As you can see, the list request only returns very generic info on each mounpoint. In case you're interested in learning more details about a specific mountpoint, you can use the info request instead, which returns more information, or all of it if the mountpoint secret is provided in the request. An info request must be formatted like this:
{
"request" : "info"
"id" : <unique ID of mountpoint to query>,
"secret" : <mountpoint secret; optional, can be used to return more info>"
}
If successful, this will have the plugin return an object containing more info on the mountpoint:
{
"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>,
"audio" : <true, only present if the mountpoint contains audio>,
"audiopt" : <audio payload type, only present if configured and the mountpoint contains audio>,
"audiortpmap" : "<audio SDP rtpmap value, only present if configured and the mountpoint contains audio>",
"audiofmtp" : "<audio SDP fmtp value, only present if configured and the mountpoint contains audio>",
"video" : <true, only present if the mountpoint contains video>,
"videopt" : <video payload type, only present if configured and the mountpoint contains video>,
"videortpmap" : "<video SDP rtpmap value, only present if configured and the mountpoint contains video>",
"videofmtp" : "<video SDP fmtp value, only present if configured and the mountpoint contains video>",
...
}
}
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 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 create request. Most importantly, you can also choose whether or not a 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 create requests is the following:
{
"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>,
"audio" : <true|false, whether the mountpoint will have audio; false by default>,
"video" : <true|false, whether the mountpoint will have video; false by default>,
"data" : <true|false, whether the mountpoint will have datachannels; false by default>,
"permanent" : <true|false, whether the mountpoint should be saved to configuration file or not; false by default>,
...
}
Of course, different mountpoint types will have different properties you can specify in a 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., audiofmtp or videofmtp ).
A successful create will result in a created response:
{
"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>,
...
}
}
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 created request will contain. If you want to double check everything in your create request went as expected, you may want to issue a followup info request to compare the results.
Once you created a mountpoint, you can modify some (not all) of its properties via an 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 edit request requires the right secret to be provided, if the mountpoint has one, or will return an error instead. The edit request must be formatted like this:
{
"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>
}
A successful edit will result in an edited response:
{
"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>
}
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 destroy request must be formatted as follows:
{
"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>
}
If successful, the result will be confirmed in a destroyed event:
{
"streaming" : "destroyed",
"id" : <unique ID of the just destroyed mountpoint>
}
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 enable and disable requests is the same, and looks like the following:
{
"request" : "enable",
"id" : <unique ID of the mountpoint to enable; mandatory>,
"secret" : "<secret to enable the mountpoint; mandatory if configured>"
}
If successful, a generic ok is returned:
{
"streaming" : "ok"
}
{
"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>"
}
If successful, a generic ok is returned:
{
"streaming" : "ok"
}
Finally, you can record a mountpoint to the internal Janus .mjr format using the 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.
To start recording a new mountpoint, the request should be formatted like this:
{
"request" : "recording",
"action" : "start",
"id" : <unique ID of the mountpoint to manipulate; mandatory>,
"audio" : "<enable audio recording, and use this base path/filename; optional>",
"video" : "<enable video recording, and use this base path/filename; optional>",
"data" : "<enable data recording, and use this base path/filename; optional>"
}
To stop a recording, instead, this is the request syntax:
{
"request" : "recording",
"action" : "stop",
"id" : <unique ID of the mountpoint to manipulate; mandatory>,
"audio" : <true|false; whether or not audio recording should be stopped>,
"video" : <true|false; whether or not video recording should be stopped>,
"data" : <true|false; whether or not datachannel recording should be stopped>
}
As you can notice, when you want to start a recording the audio , video and 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. Notice that, as with all APIs that wrap .mjr recordings, the filename you specify here is not the actual filename: an .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 ok response:
{
"streaming" : "ok"
}
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 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 watch request must be formatted like this:
{
"request" : "watch",
"id" : <unique ID of the mountpoint to subscribe to; mandatory>,
"pin" : "<PIN required to access the mountpoint; mandatory if configured>",
"offer_audio" : <true|false; whether or not audio should be negotiated; true by default if the mountpoint has audio>,
"offer_video" : <true|false; whether or not video should be negotiated; true by default if the mountpoint has video>,
"offer_data" : <true|false; whether or not datachannels should be negotiated; true by default if the mountpoint has datachannels>
}
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 offer_audio , offer_video and offer_data are also particularly interesting, though, as they allow you to only subscribe to a subset of the mountpoint media. By default, in fact, a 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.
As anticipated, if successful this request will generate a new JSEP SDP offer, which will be attached to a preparing status event:
{
"status" : "preparing"
}
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 start request, which in this case MUST be associated with a JSEP SDP answer but otherwise requires no arguments:
{
"request" : "start"
}
If successful this request returns a starting status event:
{
"status" : "starting"
}
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 (watch request, followed by JSEP offer by the plugin, followed by 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 pause and, again, 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:
{
"request" : "pause"
}
{
"request" : "start"
}
Unsurprisingly, they just result in, respectively, pausing and starting events:
{
"status" : "pausing"
}
{
"status" : "starting"
}
For more drill-down manipulations of a subscription, a 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 configure request must be formatted as follows:
{
"request" : "configure",
"audio" : <true|false, depending on whether audio should be relayed or not; optional>,
"video" : <true|false, depending on whether video should be relayed or not; optional>,
"data" : <true|false, depending on whether datachannel messages 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>
}
As you can see, the audio , video and data properties can be used as a media-level pause/resume functionality, whereas pause and start simply pause and resume all streams at the same time. The substream and temporal properties, instead, 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 spatial_layer and 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.
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 switch request must be formatted like this:
{
"request" : "switch",
"id" : <unique ID of the new mountpoint to switch to; mandatory>
}
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:
{
"switched" : "ok",
"id" : <unique ID of the new mountpoint>
}
Finally, to stop the subscription to the mountpoint and tear down the related PeerConnection, you can use the stop request. Since context is implicit, no other argument is required:
{
"request" : "stop"
}
If successful, the plugin will attempt to tear down the PeerConnection, and will send back a stopping status event:
{
"status" : "stopping"
}
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.