StreamEvent is an event that can have the type "streamCreated" or "streamDestroyed". These events are dispatched by the Session object when another client starts or stops publishing a stream to a Session. For a local client's stream, the Publisher object dispatches the event.

Example — streamCreated event dispatched by the Session object

The following code connects to a session and sets up an event listener for when a stream published by another client is created:

session.on("streamCreated", function(event) {
  subscriber = session.subscribe(event.stream, targetElement);
}).connect(token);

Example — streamDestroyed event dispatched by the Session object

The following code connects to a session and sets up an event listener for when other clients' streams end:

session.on("streamDestroyed", function(event) {
    console.log("Stream " + event.stream.name + " ended. " + event.reason);
}).connect(token);

Example — streamCreated event dispatched by a Publisher object

The following code publishes a stream and adds an event listener for when the streaming starts

var publisher = session.publish(targetElement)
  .on("streamCreated", function(event) {
    console.log("Publisher started streaming.");
  });

Example — streamDestroyed event dispatched by a Publisher object

The following code publishes a stream, and leaves the Publisher in the HTML DOM when the streaming stops:

var publisher = session.publish(targetElement)
  .on("streamDestroyed", function(event) {
    event.preventDefault();
    console.log("Publisher stopped streaming.");
  });

Properties

Name Type Description
cancelable Boolean Whether the event has a default behavior that is cancelable (true) or not (false). You can cancel the default behavior by calling the preventDefault() method of the StreamEvent object in the event listener function. The streamDestroyed event is cancelable. (See preventDefault().)
reason String For a streamDestroyed event, a description of why the stream was destroyed. This property can have one of the following values: - "clientDisconnected" — A client disconnected from the session by calling the disconnect() method of the Session object or by closing the browser. (See Session.disconnect().) - "forceDisconnected" — A moderator has disconnected the publisher of the stream from the session, by calling the forceDisconnect() method of the Session object. (See Session.forceDisconnect().) - "forceUnpublished" — A moderator has forced the publisher of the stream to stop publishing the stream, by calling the forceUnpublish() method of the Session object. (See Session.forceUnpublish().) - "mediaStopped" — The user publishing the stream has stopped sharing media. For example, the user closed the window that is a source for a screen-sharing stream. Or the user disconnected a microphone that was the audio source for an audio-only stream. Or the video and audio sources are MediaStreamTrack elements and the sources of the media are stopped or destroyed. - "networkDisconnected" — The network connection terminated abruptly (for example, the client lost their internet connection) and was detected by the Vonage Video API platform. - "reset" — A Publisher’s stream was destroyed in response to a call to its Publisher.destroy() method. - "serverRotation" — The Publisher’s stream was destroyed because the client was disconnected from the session because of Video API server rotation. Depending on the context, this description may allow the developer to refine the course of action they take in response to an event. For a streamCreated event, this string is undefined.
stream Stream A Stream object corresponding to the stream that was added (in the case of a streamCreated event) or deleted (in the case of a streamDestroyed event).
streams Array Deprecated. Use the stream property. A streamCreated or streamDestroyed event is dispatched for each stream added or destroyed.

Methods

Name Description
isDefaultPrevented() → {Boolean} Whether the default event behavior has been prevented via a call to preventDefault() (true) or not (false).
preventDefault() Prevents the default behavior associated with the event from taking place.

isDefaultPrevented() → {Boolean}

Whether the default event behavior has been prevented via a call to preventDefault() (true) or not (false). See preventDefault().

Returns:

preventDefault()

Prevents the default behavior associated with the event from taking place.

For the streamDestroyed event dispatched by the Session object, the default behavior is that all Subscriber objects that are subscribed to the stream are unsubscribed and removed from the HTML DOM. Each Subscriber object dispatches a destroyed event when the element is removed from the HTML DOM. If you call the preventDefault() method in the event listener for the streamDestroyed event, the default behavior is prevented and you can clean up Subscriber objects using your own code. See Session.getSubscribersForStream().

For the streamDestroyed event dispatched by a Publisher object, the default behavior is that the Publisher object is removed from the HTML DOM. The Publisher object dispatches a destroyed event when the element is removed from the HTML DOM. If you call the preventDefault() method in the event listener for the streamDestroyed event, the default behavior is prevented, and you can retain the Publisher for reuse or clean it up using your own code.

To see whether an event has a default behavior, check the cancelable property of the event object.

Call the preventDefault() method in the event listener function for the event.