Janus VideoRoom plugin.
- Author
- Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om
- Copyright
- GNU General Public License v3
This is a plugin implementing a videoconferencing SFU (Selective Forwarding Unit) for Janus, that is an audio/video router. This means that the plugin implements a virtual conferencing room peers can join and leave at any time. This room is based on a Publish/Subscribe pattern. Each peer can publish his/her own live audio/video feeds: this feed becomes an available stream in the room the other participants can attach to. This means that this plugin allows the realization of several different scenarios, ranging from a simple webinar (one speaker, several listeners) to a fully meshed video conference (each peer sending and receiving to and from all the others).
For what concerns the subscriber side, there are two different ways to attach to a publisher's feed: a generic 'listener', which can attach to a single feed, and a more complex 'Multiplexed listener', which instead can attach to more feeds using the same PeerConnection. The generic 'listener' is the default, which means that if you want to watch more feeds at the same time, you'll need to create multiple 'listeners' to attach at any of them. The 'Multiplexed listener', instead, is a more complex alternative that exploits the so called RTCWEB 'Plan B', which multiplexes more streams on a single PeerConnection and in the SDP: while more efficient in terms of resources, though, this approach is experimental, and currently only available on Google Chrome, so use it wisely.
- Note
- As of now, work on Plan B is still going on, and as such its support in Janus is flaky to say the least. Don't try to attach as a Multiplexed listener or bad things will probably happen!
Considering that this plugin allows for several different WebRTC PeerConnections to be on at the same time for the same peer (specifically, each peer potentially has 1 PeerConnection on for publishing and N on for subscriptions from other peers), each peer may need to attach several times to the same plugin for every stream: this means that each peer needs to have at least one handle active for managing its relation with the plugin (joining a room, leaving a room, muting/unmuting, publishing, receiving events), and needs to open a new one each time he/she wants to subscribe to a feed from another participant (or a single one in case a 'Multiplexed listener is used). The handle used for a subscription, however, would be logically a "slave" to the master one used for managing the room: this means that it cannot be used, for instance, to unmute in the room, as its only purpose would be to provide a context in which creating the sendonly PeerConnection for the subscription to the active participant.
Rooms to make available are listed in the plugin configuration file. A pre-filled configuration file is provided in conf/janus.plugin.videoroom.cfg
and includes a demo room for testing. The same plugin is also used dynamically (that is, with rooms created on the fly via API) in the Screen Sharing demo as well.
To add more rooms or modify the existing one, you can use the following syntax:
[<unique room ID>]
description = This is my awesome room
is_private = yes|no (private rooms don't appear when you do a 'list' request)
secret = <optional password needed for manipulating (e.g. destroying) the room>
pin = <optional password needed for joining the room>
publishers = <max number of concurrent senders> (e.g., 6 for a video
conference or 1 for a webinar)
bitrate = <max video bitrate for senders> (e.g., 128000)
fir_freq = <send a FIR to publishers every fir_freq seconds> (0=disable)
audiocodec = opus|isac32|isac16|pcmu|pcma (audio codec to force on publishers, default=opus)
videocodec = vp8|vp9|h264 (video codec to force on publishers, default=vp8)
audiolevel_ext = yes|no (whether the ssrc-audio-level RTP extension must be
negotiated/used or not for new publishers, default=yes)
videoorientation_ext = yes|no (whether the video-orientation RTP extension must be
negotiated/used or not for new publishers, default=yes)
playoutdelay_ext = yes|no (whether the playout-delay RTP extension must be
negotiated/used or not for new publishers, default=yes)
record = true|false (whether this room should be recorded, default=false)
rec_dir = <folder where recordings should be stored, when enabled>
Note that recording will work with all codecs except iSAC.
Video Room API
The Video Room 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.
create
, destroy
, exists
, list
, allowed
, kick
and and listparticipants
are synchronous requests, which means you'll get a response directly within the context of the transaction. create
allows you to create a new video room dynamically, as an alternative to using the configuration file; destroy
removes a video room and destroys it, kicking all the users out as part of the process; exists
allows you to check whether a specific video room exists; finally, list
lists all the available rooms, while listparticipants
lists all the participants of a specific room and their details.
The join
, joinandconfigure
, configure
, publish
, unpublish
, start
, pause
, switch
, stop
, add
, remove
and leave
requests instead are all asynchronous, which means you'll get a notification about their success or failure in an event. join
allows you to join a specific video room, specifying whether that specific PeerConnection will be used for publishing or watching; configure
can be used to modify some of the participation settings (e.g., bitrate cap); joinandconfigure
combines the previous two requests in a single one (just for publishers); publish
can be used to start sending media to broadcast to the other participants, while unpublish
does the opposite; start
allows you to start receiving media from a publisher you've subscribed to previously by means of a join
, while pause
pauses the delivery of the media; the switch
request can be used to change the source of the media flowing over a specific PeerConnection (e.g., I was watching Alice, I want to watch Bob now) without having to create a new handle for that; stop
interrupts a viewer instance; add
and remove
are just used when involving "Plan B", and are used to add or remove publishers to be muxed in the single viewer PeerConnection; finally, leave
allows you to leave a video room for good.
Notice that, in general, all users can create rooms. 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.
Actual API docs: TBD.
Plugins