Vonage Video API Node SDK

The Node SDK provides methods for:

NPM helps manage dependencies for node projects. Find more info here: http://npmjs.org

Run this command to install the package and adding it to your package.json:

npm install @vonage/server-sdk

Usage

Initializing

Import the module to get a constructor function for a video object, then call it with new to instantiate a video object with your own App ID and private key.

const { Auth } = require('@vonage/auth');
const { Vonage } = require('@vonage/server-sdk');
const { MediaMode } = require('@vonage/video');

const credentials = new Auth({
    applicationId: 'APP_ID',
    privateKey: 'PRIVATE_KEY_PATH',
});

const vonage = new Vonage(credentials);

Creating Sessions

To create a session, use the createSession(properties) method. The properties parameter is an optional object used to specify whether the session uses the Media Router, to specify a location hint, and to specify whether the session will be automatically archived or . The session returned is an instance of session. Session objects have a sessionId property that is useful to be saved to a persistent store (such as a database).

// Create a session that will attempt to transmit streams directly between
// clients. If clients cannot connect, the session uses the Vonage TURN server:
try {
    const session = await vonage.video.createSession();
    // save the sessionId
    db.save("session", session.sessionId, done);
} catch(error) {
    console.error("Error creating session: ", error);
}

// The session will use the Vonage Media Router:
try {
    const session = await vonage.video.createSession({ mediaMode: MediaMode.ROUTED });
    // save the sessionId
    db.save("session", session.sessionId, done);
} catch(error) {
    console.error("Error creating session: ", error);
}

// A Session with a location hint
try {
    const session = await vonage.video.createSession({ location: "12.34.56.78" });
    // save the sessionId
    db.save("session", session.sessionId, done);
} catch(error) {
    console.error("Error creating session: ", error);
}

// A Session with an automatic archiving
try {
    const session = await vonage.video.createSession({ mediaMode: MediaMode.ROUTED, archiveMode: "always" });
    // save the sessionId
    db.save("session", session.sessionId, done);
} catch(error) {
    console.error("Error creating session: ", error);
}

Generating Tokens

Once a Session is created, you can start generating Tokens for clients to use when connecting to it. You can generate a token by calling the generateClientToken(sessionId) method.

For layout control in archives and broadcasts, the initial layout class list of streams published from connections using this token can be set as well.

// Generate a Token from just a sessionId (fetched from a database)
const options = {
    role: "moderator",
    expireTime: new Date().getTime() / 1000 + 7 * 24 * 60 * 60, // in one week
    data: "name=Johnny",
    initialLayoutClassList: ["focus"]
}
const token = vonage.video.generateClientToken(sessionId, options);

Working with archives

You can start the recording of a session using the startArchive(sessionId, options) method. The options parameter is an optional object used to set the name of the Archive. The archive returned is an instance of Archive.

Note that you can only start an archive on a Session with connected clients.

try {
    const archive = await vonage.video.startArchive(sessionId);
    // The id property is useful to save off into a database
    console.log("new archive:", archive.id);
} catch(error) {
    console.error("Error starting archive: ", error);
}

You can also disable audio or video recording by setting the hasAudio or hasVideo property of the options parameter to false:

const archiveOptions = {
  name: "Important Presentation",
  hasVideo: false, // Record audio only
};
try {
    const archive = await vonage.video.startArchive(sessionId, archiveOptions);
    // The id property is useful to save off into a database
    console.log("new archive:", archive.id);
} catch(error) {
    console.error("Error starting archive: ", error);
}

By default, all streams are recorded to a single (composed) file. You can record the different streams in the session to individual files (instead of a single composed file) by setting the outputMode option to 'individual' when you call the startArchive() method:

const archiveOptions = {
  name: "Important Presentation",
  outputMode: "individual",
};
try {
    const archive = await vonage.video.startArchive(sessionId, archiveOptions);
    // The id property is useful to save off into a database
    console.log("new archive:", archive.id);
} catch(error) {
    console.error("Error starting archive: ", error);
}

You can stop the recording of a started Archive using the stopArchive(archiveId) method. The archive returned in the callback is an instance of Archive.

try {
    const archiveResponse = await vonage.video.stopArchive(archiveId);
    console.log("Successfully stopped archive:", archiveResponse.id);
} catch(error) {
    console.error("Error stopping archive: ", error);
}

To get an Archive instance (and all the information about it) from an archiveId, use the getArchive(archiveId) method.

You can inspect the properties of the archive for more details.

try {
    const archive = await vonage.video.getArchive(archiveId);
    console.log("Successfully retrieved archive:", archive.id);
} catch(error) {
    console.error("Error retrieving archive: ", error);
}

To delete an Archive, you can call the deleteArchive(archiveId) method.

// Delete an Archive from an archiveId (fetched from database)
try {
    const archiveResponse = await vonage.video.deleteArchive(archiveId);
    console.log("Successfully deleted archive:", archiveResponse.id);
} catch(error) {
    console.error("Error deleting archive: ", error);
}

You can also get a list of all the Archives you've created (up to 1000) with your App ID. This is done using the searchArchives(filter) method. The parameter filter is an optional object used to specify a sessionId, offset and count to help you paginate through the results.

The archives returned is an array of Archive instances. The totalCount returned from the callback is the total number of archives your App ID has generated.

const filter = {
    sessionId: "2_MX2xMDB-flR1ZSBOb3YgMTkgMTE6MDk6NTggUFNUIDIwMTN-MC2zNzQxNzIxNX2"
    offset: 100,
    count: 50
}
try {
    const archives = await vonage.video.searchArchives(filter);
    console.log(`Successfully retrieved ${archives.count} archives`);
    for (let i = 0; i < archives.length; i++) {
        console.log(archives.items[i].id);
    }
} catch(error) {
    console.error("Error returning list of archives: ", error);
}

Note that you can also create an automatically archived session, by passing in 'always' as the archiveMode option when you call the createSession() method (see "Creating Sessions," above).

For composed archives, you can set change the layout dynamically, using the updateArchiveLayout(archiveId, layout) method:

const layout = {
    type: "bestFit"
}
try {
    const archiveResponse = await vonage.video.updateArchiveLayout(archiveId,layout);
    console.log("Successfully updated archive layout:", archiveResponse);
} catch(error) {
    console.error("Error deleting archive: ", error);
}

You can set the initial layout class for a client's streams by setting the layout option when you create the token for the client, using the vonage.video.generateToken() method. And you can change the layout classes for streams in a session by calling the vonage.video.setStreamClassLists(sessionId, classListArray) method.

Setting the layout of composed archives is optional. By default, composed archives use the "best fit" layout (see Customizing the video layout for composed archives).

For more information on archiving, see the archiving developer guide.

Working with live streaming broadcasts

Only routed sessions support live streaming broadcasts.

To start a live streaming broadcast of a Video session, call the vonage.video.startBroadcast() method. Pass in three parameters: the session ID for the session, options for the broadcast, and a callback function:

const broadcastOptions = {
  outputs: {
    hls: {},
    rtmp: [
      {
        id: "foo",
        serverUrl: "rtmp://myfooserver/myfooapp",
        streamName: "myfoostream",
      },
      {
        id: "bar",
        serverUrl: "rtmp://mybarserver/mybarapp",
        streamName: "mybarstream",
      },
    ],
  },
  maxDuration: 5400,
  resolution: "640x480",
  layout: {
    type: "verticalPresentation",
  },
};

vonage.video.startBroadcast(sessionId, broadcastOptions)
  .then(broadcast => {
    console.log("Broadcast started: ", broadcast.id);
  })
  .catch(error => {
    console.log(error);
  })

See the API reference for details on the options parameter.

On success, a Broadcast object is passed into the callback function as the second parameter. The Broadcast object has properties that define the broadcast, including a broadcastUrls property, which has URLs for the broadcast streams. See the API reference for details.

Call the vonage.video.stopBroadcast() method to stop a live streaming broadcast pass in the broadcast ID (the id property of the Broadcast object) as the first parameter. The second parameter is the callback function:

vonage.video.stopBroadcast(broadcastId)
  .then(broadcast => {
    console.log("Broadcast stopped: ", broadcast.id);
  })
  .catch(error => {
    console.log(error);
  })

You can also call the stop() method of the Broadcast object to stop a broadcast.

Call the vonage.video.getBroadcast() method, passing in a broadcast ID, to get a Broadcast object.

You can also get a list of all the Broadcasts you've created (up to 1000) with your API Key. This is done using the vonage.video.searchBroadcasts(options) method. The parameter options is an optional object used to specify an offset, count, and sessionId to help you paginate through the results. The callback has a signature function(err, broadcasts, totalCount). The broadcasts returned from the callback is an array of Broadcast instances. The totalCount returned from the callback is the total number of broadcasts your App ID has generated.

vonage.video.searchBroadcasts({ offset: 100, count: 50 })
  then(response) => {
    console.log(response.totalCount + " broadcasts");
    for (let i = 0; i < response.broadcasts.length; i++) {
      console.log(response.broadcasts[i].id);
    }
  })
  .catch(error => {
    console.log("error:", error);
  })

To change the broadcast layout, call the vonage.video.updateArchiveLayout() method, passing in the broadcast ID and the layout type.

You can set the initial layout class for a client's streams by setting the layout option when you create the token for the client, using the vonage.video.generateToken() method. And you can change the layout classes for streams in a session by calling the vonage.video.setStreamClassLists(sessionId, classListArray) method.

Setting the layout of a live streaming broadcast is optional. By default, live streaming broadcasts use the "best fit" layout. -->

Sending signals

You can send a signal to all participants in a session by calling the sendSignal(payload, sessionId, connectionId) method and setting the connectionId parameter to null:

const sessionId =
  "2_MX2xMDB-flR1ZSBOb3YgMTkgMTE6MDk6NTggUFNUIDIwMTN-MC2zNzQxNzIxNX2";

try {
    const signalResponse = await vonage.video.sendSignal({ type: "chat", data: "Hello" }, sessionId);
    console.log("Successfully sent signal:", signalResponse);
} catch(error) {
    console.error("Error sending signal: ", error);
}

Or send a signal to a specific participant in the session by calling the sendSignal(payload, sessionId, connectionId) method and setting all parameters, including connectionId:

const sessionId =
  "2_MX2xMDB-flR1ZSBOb3YgMTkgMTE6MDk6NTggUFNUIDIwMTN-MC2zNzQxNzIxNX2";
const connectionId = "02e80876-02ab-47cd-8084-6ddc8887afbc";
try {
    const signalResponse = await vonage.video.sendSignal({ type: "chat", data: "Hello" }, sessionId, connectionId);
    console.log("Successfully sent signal:", signalResponse);
} catch(error) {
    console.error("Error sending signal: ", error);
}

This is the server-side equivalent to the sendSignal() method in the client SDKs. See signaling developer guide .

Disconnecting participants

You can disconnect participants from a session using the disconnectClient(sessionId, connectionId) method.

try {
    const disconnectResponse = await vonage.video.disconnectClient(sessionId, connectionId);
    console.log("Successfully disconnected client:", disconnectResponse);
} catch(error) {
    console.error("Error disconnecting client: ", error);
}

Forcing clients in a session to mute published audio

You can force the publisher of a specific stream to stop publishing audio using the muteStream(sessionId, streamId)method.

You can force the publisher of all streams in a session (except for an optional list of streams) to stop publishing audio using the forceMuteAll() method. You can then disable the mute state of the session by calling the disableForceMute() method.

Getting Stream Info

You can get information on an active stream in a session:

const sessionId =
  "2_MX6xMDB-fjE1MzE3NjQ0MTM2NzZ-cHVTcUIra3JUa0kxUlhsVU55cTBYL0Y1flB";
const streamId = "2a84cd30-3a33-917f-9150-49e454e01572";
try {
    const stream = await vonage.video.getStreamInfo(sessionId, streamId);
    console.log(stream.id); // '2a84cd30-3a33-917f-9150-49e454e01572'
    console.log(stream.videoType); // 'camera'
    console.log(stream.name); // 'Bob'
    console.log(stream.layoutClassList); // ['main']
} catch(error) {
    console.error("Error retrieving stream: ", error.message);
}

Pass a session ID and stream ID to the getStreamInfo() method. On successful completion, the stream object containing properties of the stream.

try {
    const streams = await vonage.video.getStreamInfo(sessionId);
    console.log(`Successfully retrieved ${streams.count} streams`);
    for (let i = 0; i < streams.length; i++) {
        console.log(streams.items[i].id);
    }
} catch(error) {
    console.error("Error retrieving streams: ", error);
}

Requirements

You need a Vonage App ID and private key, which you can obtain by logging into your Vonage Video API account.

The Node SDK requires Node.js 6 or higher. It may work on older versions, but they are no longer tested.

Release Notes

See the Releases page on GitHub for details about each release.

<script>
  const currentPage = 'node_sdk';
  $('#download, #samples, #github').click(function(event) {
    gaEvent(currentPage, 'top_banner: ' + event.currentTarget.id);
  });
</script>