Fork me on GitHub
Loading...
Searching...
No Matches
VideoCall plugin documentation

This is a simple video call plugin for Janus, allowing two WebRTC peers to call each other through the Janus core. The idea is to provide a similar service as the well known AppRTC demo (https://apprtc.appspot.com), but with the media flowing through a server rather than being peer-to-peer.

The plugin provides a simple fake registration mechanism. A peer attaching to the plugin needs to specify a username, which acts as a "phone number": if the username is free, it is associated with the peer, which means he/she can be "called" using that username by another peer. Peers can either "call" another peer, by specifying their username, or wait for a call. The approach used by this plugin is similar to the one employed by the echo test one: all frames (RTP/RTCP) coming from one peer are relayed to the other.

Just as in the janus_videocall.c plugin, there are knobs to control whether audio and/or video should be muted or not, and if the bitrate of the peer needs to be capped by means of REMB messages.

Video Call API

All requests you can send in the Video Call API are asynchronous, which means all responses (successes and errors) will be delivered as events with the same transaction.

The supported requests are list , register , call , accept , set and hangup . list allows you to get a list of all the registered peers; register can be used to register a username to call and be called; call is used to start a video call with somebody through the plugin, while accept is used to accept the call in case one is invited instead of inviting; set can be used to configure some call-related settings (e.g., a cap on the send bandwidth); finally, hangup can be used to terminate the communication at any time, either to hangup an ongoing call or to cancel/decline a call that hasn't started yet.

The list request has to be formatted as follows:

{
        "request" : "list"
}

A successful request will result in an array of peers to be returned:

{
        "videocall" : "event",
        "result" : {
                "list": [       // Array of peers
                        "alice78",
                        "bob51",
                        // others
                ]
        }
}

An error instead (and the same applies to all other requests, so this won't be repeated) would provide both an error code and a more verbose description of the cause of the issue:

{
        "videocall" : "event",
        "error_code" : <numeric ID, check Macros below>,
        "error" : "<error description as a string>"
}

To register a username to call and be called, the register request can be used. This works on a "first come, first served" basis: there's no authentication involved, you just specify the username you'd like to use and, if free, it's assigned to you. Notice that there's no way to unregister: you have to close the handle to free the username. The register request has to be formatted as follows:

{
        "request" : "register",
        "username" : "<desired unique username>"
}

If successful, this will result in a registered event:

{
        "videocall" : "event",
        "result" : {
                "event" : "registered",
                "username" : "<same username, registered>"
        }
}

Once you're registered, you can either start a new call or wait to be called by someone else who knows your username. To start a new call, the call request can be used: this request must be attached to a JSEP offer containing the WebRTC-related info to setup a new media session. A call request has to be formatted as follows:

{
        "request" : "call",
        "username" : "<username to call>"
}

If successful, this will result in a calling event:

{
        "videocall" : "event",
        "result" : {
                "event" : "calling",
                "username" : "<same username, registered>"
        }
}

At the same time, the user being called will receive an incomingcall event

{
        "videocall" : "event",
        "result" : {
                "event" : "incomingcall",
                "username" : "<your username>"
        }
}

To accept the call, the accept request can be used. This request must be attached to a JSEP answer containing the WebRTC-related information to complete the actual PeerConnection setup. A accept request has to be formatted as follows:

{
        "request" : "accept"
}

If successful, both the caller and the callee will receive an accepted event to notify them about the success of the signalling:

{
        "videocall" : "event",
        "result" : {
                "event" : "accepted",
                "username" : "<caller username>"
        }
}

At this point, the media-related settings of the call can be modified on either side by means of a set request, which acts pretty much as the one in the Echo Test API . The set request has to be formatted as follows. All the attributes (except request) are optional, so any request can contain a subset of them:

{
        "request" : "set",
        "audio" : true|false,
        "video" : true|false,
        "bitrate" : <numeric bitrate value>,
        "record" : true|false,
        "filename" : <base path/filename to use for the recording>,
        "substream" : <substream to receive (0-2), in case simulcasting is enabled>,
        "temporal" : <temporal layers to receive (0-2), in case simulcasting is enabled>,
        "fallback" : <How much time (in us, default 250000) without receiving packets will make us drop to the substream below>
}

audio instructs the plugin to do or do not relay audio frames; video does the same for video; bitrate caps the bandwidth to force on the browser encoding side (e.g., 128000 for 128kbps); record enables or disables the recording of this peer; in case recording is enabled, filename allows to specify a base path/filename to use for the files (-audio.mjr, -video.mjr and -data.mjr are automatically appended). Beware that enabling the recording only records this user's contribution, and not the whole call: to record both sides, you need to enable recording for both the peers in the call. Finally, in case the call uses simulcasting, substream and temporal can be used to manually pick which substream and/or temporal layer should be received from the peer.

A successful request will result in a set event:

{
        "videocall" : "event",
        "result" : {
                "event" : "set"
        }
}

Notice that the set request is also what you use when you want to renegotiate a session, e.g., for the purpose of adding/removing media streams or forcing an ICE restart. In that case, even an empty set request is fine, as long as it accompanies a new JSEP offer or answer (depending on who originated the session update). The user receiving the updated JSEP offer/answer will get an update event:

{
        "videocall" : "event",
        "result" : {
                "event" : "update",
        }
}

To decline an incoming call, cancel an attempt to call or simply hangup an ongoing conversation, the hangup request can be used, which has to be formatted as follows:

{
        "request" : "hangup"
}

Whatever the reason of a call being closed (e.g., a hangup request, a PeerConnection being closed, or something else), both parties in the communication will receive a hangup event:

{
        "videocall" : "event",
        "result" : {
                "event" : "hangup",
                "username" : "<username of who closed the communication>",
                "reason" : "<description of what happened>"
        }
}