openvidu-browser API


NOTE: all input parameters ("Parameters" columns) are listed in strict order, optional ones in italics

Class Description
OpenVidu Use it to initialize your sessions and publishers
Session Represents a video call. It can also be seen as a room where multiple users can connect. Participants who publish their videos to a session will be seen by the rest of users connected to that specific session
Publisher Packs local media streams. Users can publish it to a session
Subscriber Packs remote media streams. Users automatically receive them when others publish their streams
Stream Represents each one of the videos send and receive by a user in a session. Therefore each Publisher and Subscriber has an attribute of type Stream
Connection Represents each one of the user's connection to the session (the local one and other user's connections). Therefore each Session and Stream object has an attribute of type Connection
OpenViduError Simple object to identify errors on runtime
OpenViduErrorName OpenViduError names enum

OpenVidu

Method Returns Parameters Description
constructor OpenVidu Returns a new OpenVidu object. This is the entry point to OpenVidu in the browser
initSession Session apikey:string
sessionId:string
Returns a session with id sessionId
initPublisher Publisher parentId:string
cameraOptions:any
callback:function
Starts local video stream, appending it to parentId HTML element, with the specific cameraOptions settings and executing callback function in the end. cameraOptions is an object with the following (optional) properties:

var cameraOptions = {
audio: boolean,
video: boolean,
audioActive: boolean,
videoActive: boolean,
quality: string,
screen: boolean
}


  • audio: whether to transmit audio or not
  • video: whether to transmit video or not
  • audioActive: whether to join the session with the audio unmuted or muted. Only makes sense if property audio is set to true. You can change audio state later during the session with Publisher.publishAudio(true)
  • videoActive: whether to join the session with the video enabled or disabled. Only makes sense if property video is set to true. You can change video state later during the session with Publisher.publishVideo(true)
  • quality: quality of the video ("LOW", "MEDIUM", "HIGH")
  • screen: whether to use screen capturing as the video source instead of a camera or not
checkSystemRequirements number Returns 1 if the browser supports WebRTC, 0 otherwise
getDevices Promise callback(error, deviceInfo):function Collects information about the media input and output devices available on the system, returned in deviceInfo array
enableProdMode Disable all logging except error level

Session

Method Returns Parameters Description
connect token:string
metadata:any
callback(error):function
Connects to the session using token and executes callback in the end (error parameter null if success). metadata parameter allows you to pass extra data to share with other users when they receive streamCreated event. You can also add metadata through openvidu-backend-client when generating tokens (see TokenOptions). The structure of this string is up to you (maybe some standarized format as JSON or XML is a good idea), the only restriction is a maximum length of 1000 chars
disconnect Leaves the session, destroying all streams and deleting the user as a participant
publish publisher:Publisher Publishes the specific user's local stream contained in publisher object to the session
unpublish publisher:Publisher Unpublishes the specific user's local stream contained in publisher object
on eventName:string
callback:function
callback function will be triggered each time eventName event is recieved
once eventName:string
callback:function
callback function will be triggered once when eventName event is recieved. The listener is removed immediately
off eventName:string
eventHandler:any
Removes eventHandler handler for eventName event
subscribe Subscriber stream:Stream
htmlId:string
videoOptions:any
Subscribes to stream, appending a new HTML Video element to DOM element of htmlId id, with videoOptions settings. This method is usually called in the callback of streamCreated event
unsubscribe subscriber:Subscriber Unsubscribes from subscriber, automatically removing its HTML Video element
signal
(since v1.2.0)
signal:any Sends one signal. signal object has the following properties: {data:string, to:Connection[], type:string} (all optional properties)
All users subscribed to that signal (session.on('signal:type', ...) or session.on('signal', ...) for all signals) and whose Connection objects are in to array will receive it
Property Type Description
sessionId string The unique id of the session
Event Properties of event object Description
streamCreated stream:Stream Triggered by Session object when a new Stream (published by other client) has been created and added to it
streamDestroyed stream:Stream
preventDefault():Function
Triggered by Session object when an existing Stream (published by other client) has been destroyed. The default behaviour is the deletion of the HTML video element associated to it. To prevent it, call preventDefault() method on the event object
connectionCreated connection:Connection Triggered by Session object whenever any client has joined the session. This includes dispatching one event for each client that joins the session when you are already connected to it, one for each existing participant the first time you connect to the session and once for your own local connection
connectionDestroyed connection:Connection Triggered by Session object whenever a client (other than your own) leaves the session. This event can also mean that streamDestroyed events could be dispatched, depending on the streams associated to it
sessionDisconnected preventDefault():Function Triggered by Session object when the client disconnects from the Session. Default behaviour is the deletion of all HTML video elements. Call preventDefault() on event object to prevent it and delete them by yourself
publisherStartSpeaking
(since v1.3.0)
connection:Connection
streamId:string
Triggered by Session object when any Publisher starts speaking. connection property identifies the participant who is speaking, and streamId identifies the specific Stream for which the event has been triggered
publisherStopSpeaking
(since v1.3.0)
connection:Connection
streamId:string
Triggered by Session object when any Publisher stops speaking. connection property identifies the participant who is has stopped speaking, and streamId identifies the specific Stream for which the event has been triggered. For this event to be triggered, publisherStartSpeaking event must have been previously triggered

Publisher

Method Returns Parameters Description
publishAudio value:boolean Enable or disable the audio track depending on whether value is true or false
publishVideo value:boolean Enable or disable the video track depending on whether value is true or false
destroy Publisher Delets the publisher object and removes it from DOM. The rest of users will trigger a streamDestroyed event
subscribeToRemote Local video will be replaced by your remote video (same stream as other clients will receive from you)
on eventName:string
callback:function
callback function will be triggered each time eventName event is recieved
Property Type Description
accessAllowed boolean true if the user has granted access to the camera, false otherwise
element Element The parent HTML Element which contains the publisher
id string The id of the HTML Video element of the publisher
stream Stream The stream object of the publisher
session Session The session to which the publisher belongs
Event Properties of event object Description
accessAllowed Triggered by Publisher object when the user has granted access to the camera/microphone
accessDenied Triggered by Publisher object when the user has rejected access to the camera/microphone
videoElementCreated element:HTMLVideoElement Triggered by Publisher object inmediately after a new video element has been added to DOM
videoPlaying element:HTMLVideoElement Triggered by Subscriber object when the video (same as videoElementCreated) starts playing. Only triggered for those Publisher objects which have NOT called their method subscribeToRemote
remoteVideoPlaying element:HTMLVideoElement Triggered by Publisher object when your looped remote video starts playing. Only triggered for those Publisher objects which have called their method subscribeToRemote

Subscriber

Method Returns Parameters Description
Property Type Description
element Element The parent HTML Element which contains the subscriber
id string The id of the HTML Video element of the subscriber
stream Stream The stream object of the subscriber
Event Properties of event object Description
videoElementCreated element:HTMLVideoElement Triggered by Subscriber object inmediately after a new video element has been added to DOM
videoPlaying element:HTMLVideoElement Triggered by Subscriber object when the video (same as videoElementCreated) starts playing

Stream

Property Type Description
connection Connection The Connection object to which the Stream belongs
streamId
(since v1.3.0)
string The unique id of the stream
hasAudio
(since v1.3.0)
boolean true if there's an audio stream, false otherwise
hasVideo
(since v1.3.0)
boolean true if there's a video stream, false otherwise
typeOfVideo
(since v1.3.0)
string "CAMERA", "SCREEN" or "" (empty string) for a Stream publishing the video of a camera (with or without audio), doing screen sharing (with or without audio) or sending only audio respectively

Connection

Property Type Description
connectionId string Unique identifier of the connection
data string Data associated to this connection (and therefore to certain user). This is an important field: it allows you to broadcast all the information you want for each user (a username, for example)
creationTime number Time when this connection was created

OpenViduError

Method Returns Parameters Description
constructor OpenViduError name:OpenViduErrorName
message:string
Returns a new OpenViduError object
Property Type Description
name OpenViduErrorName The name and unique identifier of the error
message string Further information about the error

OpenViduErrorName

(enum)

Constant
CAMERA_ACCESS_DENIED
MICROPHONE_ACCESS_DENIED
SCREEN_CAPTURE_DENIED
NO_VIDEO_DEVICE
NO_INPUT_DEVICE
SCREEN_EXTENSION_NOT_INSTALLED
GENERIC_ERROR