Google+ Hangouts API

Controlling Video Feeds

There are many ways to control video streams in Hangouts. Although the thumbnails are fixed, you can change what's displayed in the large video window above the thumbnails (which we will call "main video" for clarity), the VideoCanvas, and the Hangout On Air broadcast stream. In this article, we will discuss the Hangouts API methods that relate to these streams.

Default video feed behavior

You have probably already experienced the default video feed behavior, which switches the main video rapidly to show you the most-recently-speaking participant who is not local. In a two-person Hangout, this means you will always see the other participant; in a 10-person Hangout, you will switch between speakers.

"Sticky" video feeds

In the Hangouts UI, you can click on a participant in the thumbnails, that participant will appear in the main video and stay always active. A visible highlight border will appear around the thumbnail you have selected.

If you open a main area application, any selected participant is deselected.

VideoCanvas

Using the Hangouts API, you can display a video canvas over your app.

var id = gapi.hangout.getLocalParticipantId();
var canvas = gapi.hangout.layout.getVideoCanvas();

canvas.setWidth(600);
canvas.setPosition(300, 50);
canvas.setVisible(true);

By default, that canvas shows the DefaultVideoFeed, which is the same as the default video feed behavior above. You can then override that behavior by manually setting the feed for the participant:

var id = gapi.hangout.getLocalParticipantId();

var feed = gapi.hangout.layout.createParticipantVideoFeed(id);
var canvas = gapi.hangout.layout.getVideoCanvas();

// Set the feed
canvas.setVideoFeed(feed);

This will only affect the VideoCanvas; if you hide your app, your choice will not appear in the main video.

Overriding the default feed

You can override who is the displayed participant in the DefaultVideo feed:

var id = gapi.hangout.getLocalParticipantId();

// Get the default video feed.
var feed = gapi.hangout.layout.getDefaultVideoFeed();

// Set the local participant to be sticky.
// Note that this will close any main area app.
feed.setDisplayedParticipant(id);

This is equivalent to clicking on a participant's video thumbnail, which will hide the main area app. Thus, this functionality is more useful in extensions.

Hangouts On Air broadcast

Hangoust On Air has a privileged user called the 'broadcaster" who is the participant that started the Hangout On Air. The broadcaster can choose who is being broadcast to all participants, as opposed to who is being shown in the broadcaster's local main video.

You can set who is being broadcast with this snippet:

var id = gapi.hangout.getLocalParticipantId();
// Set the local participant to be sticky.
gapi.hangout.onair.setDisplayedParticipantInBroadcast(id);

Changing who is being broadcast does not change what you see. These calls will fail if you are not the broadcaster.

You can revert to normal broadcast selection by clearing your selection:

gapi.hangout.onair.clearDisplayedParticipantInBroadcast();

This means the broadcast will switch to either the default video behavior or the currently-selected local video.

Because you can run two applications, an extension and a main area app, more than one application can set the broadcaster. This is why we provide callbacks to let you track who the currently-broadcast participant is.

var currentGuyId = gapi.hangout.onair.getDisplayedParticipantInBroadcast();

function onParticipantChanged(event) {
  var newGuyId = event.displayedParticipant;
  var participant = gapi.hangout.getParticipantById(newGuyId);
}

// Listen for changes to the broadcast participant
gapi.hangout.onair.onDisplayedParticipantInBroadcastChanged.add(onParticipantChanged);

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.