Google+ Hangouts API

Managing Resources for Hangout Apps

The Hangouts API allows your app to modify the video and audio of a Hangout, which you can use to create rich effects. You can use the API to manage the life cycle of the resources that you use in your app. Efficiently handling resources can prevent your the Hangout from running out of memory or resulting in a poor experience.

Two types of resources can be loaded and used in your app as effects, such as overlays and sounds:

  • Images: You can load an image and place it statically or attach it to a given part of the face.
  • Audio: You can load an audio file and play it either globally or for the local participant.

Loading an image resource

From mediaStarter.js, which is part of our Media Sample app, you will see this code:

  // Allocate image resource
  var arbitraryResource = gapi.hangout.av.effects.createImageResource(
      uri);

  // Use an onLoad handler
  arbitraryResource.onLoad.add( function(event) {
    if ( !event.isLoaded ) {
      alert("Could not load your overlay.");
      arbitraryResource.dispose();
    } else {
      alert("Overlay loaded.");
    }
  });

  // Create a statically positioned overlay that will be 50% of the width
  // of the video feed.
  var arbitraryOverlay = arbitraryResource.createOverlay(
    {'scale':
      {'magnitude': 0.5,
       'reference': gapi.hangout.av.effects.ScaleReference.WIDTH}});

  // Place the text x-centered and halfway down the frame
  arbitraryOverlay.setPosition(0, 0.25);
  arbitraryOverlay.setVisible(true);

First, the script allocates a resource by using a URL. The URL can reference a PNG or JPG file, such as this transparent image from Wikipedia. The createImageResource also accepts a data URI.

Next, the script adds an onLoad handler. This callback is guaranteed to fire once, and only once, even if the resource loads faster than your script can attach the event listener.

The callback is passed a ResourceLoadResult, which indicates if the resource loaded successfully. The resource could fail to load for a number of reasons, including: bad URI, wrong image format, or timeout. If the resources fails to load, the API calls dispose() to release it.

Audio resources

Audio resources have many similar features to image resources. You first allocate the AudioResource by calling createAudioResource, then create any number of Sound instances based on the resource.

The AudioResource supports 16-bit PCM encoded WAV files.

  var gooddaySoundURL =
      'http://hangoutmediastarter.appspot.com/static/goodday.wav';

  // Allocate the audio resource and immediately create a
  // sound instance.
  var gooddaySound = gapi.hangout.av.effects.createAudioResource(
      gooddaySoundURL).createSound();

  // Note that we are playing a global audio event,
  // so other hangouts will hear it.
  function sayGoodDay() {
      gooddaySound.play({loop: false, global:true});
  }

You can play sounds locally or globally. If global is set to true, the sound is mixed into the video feed and plays for all participants.

Resource states

Resources can be in the following states:

  • LOADING: A request is out to load the resource, but it has not completed.
  • LOADED: The resource is ready for use.
  • DISPOSED: The resource has been released and no longer consumes memory in the plugin.
  • ERROR: A problem occurred with the resource.

You can check the state of your resource:

  var resource = gapi.hangout.av.effects.createImageResource(
          uri);
  // Returns a value from gapi.hangout.av.effects.ResourceState
  var state = resource.getState();

  // Convenience method to see if your resource is disposed
  var isDisposed = resource.isDisposed();

You might want to check that resources are finished loading before enabling aspects of your application.

Memory usage

Every resource that you allocate in a Hangout app consumes memory. Running out of memory will cause the Google Talk plugin to crash, which will also stop the Hangout.

Likewise, overlays and sounds also consume plugin memory, although much less than resources. For example, 1000 different ImageResource each with one Overlay consumes significantly more memory than one ImageResource that has 1000 Overlays.

The Hangouts API v1.2 introduces a new method: dispose(). You can call dispose() on both AudioResources and ImageResources:

resource.dispose();

You can also dispose Overlays and Sounds separately from their resources.

overlay.dispose();

This approach is useful if you want to retain the resource and create a new Overlay or Sound from the resource later.

Disposing a resource also deallocates any Overlays or Sounds that are associated with the resource.

You do not need to dispose resources that failed to load; however, as a best practice, you should dispose all resources when your app is done with them.

The proxy server

The images are fetched and cached by Google for security and performance reasons. In your server logs, the user-agent for these requests are listed as "Feedfetcher-Google."

You will need to host images for overlays in a publicly-visible place without firewalls or authentication.

The image proxy caches your images to provide fast load times. The image proxy uses cache-control headers to determine if an image needs to be updated.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.