Google+ Hangouts API

gapi.hangout.av.effects

Provides ability to add sound effects and attach image overlays to faces.

Classes

Functions

Events

Enums

Classes in gapi.hangout.av.effects

Class Description
class AudioResource(
  onLoad
)
Object used to load an audio file which can be used to play sounds. Create an AudioResource with createAudioResource.

Jump to instance methods

Jump to instance event functions


onLoad : undefined
An event that fires when the resource loads.
class BackgroundBlur() Object used to blur the background in the video feed of the local participant. Create a BackgroundBlur instance with createBackgroundBlur.

Jump to instance methods

class BackgroundReplacement() Object used to replace the background with other images in the video feed of the local participant. The replacement background image is visible to all participants. Get a BackgroundReplacement instance using getBackgroundReplacement

Jump to instance methods

class FaceTrackingData(
  hasFace,
  leftEye,
  leftEyebrowLeft,
  leftEyebrowRight,
  lowerLip,
  mouthCenter,
  mouthLeft,
  mouthRight,
  noseRoot,
  noseTip,
  pan,
  rightEye,
  rightEyebrowLeft,
  rightEyebrowRight,
  roll,
  tilt,
  upperLip
)
The positions of points on the face detected in a video feed. The x-y origin is the center of the frame. "Left" and "right" (such as leftEye) are with respect to how others view the face. Likewise, positive x is to the right as others view the face. The width and height of the feed are each equal to 1.0 unit. Pan, roll, and tilt are specified in radians, where 0 radians is center and positive is to the right from the viewer's perspective.
hasFace : boolean
Indicates whether there is a face in the video feed.
leftEye : {x: number, y: number}
leftEyebrowLeft : {x: number, y: number}
leftEyebrowRight : {x: number, y: number}
lowerLip : {x: number, y: number}
mouthCenter : {x: number, y: number}
mouthLeft : {x: number, y: number}
mouthRight : {x: number, y: number}
noseRoot : {x: number, y: number}
noseTip : {x: number, y: number}
pan : number
rightEye : {x: number, y: number}
rightEyebrowLeft : {x: number, y: number}
rightEyebrowRight : {x: number, y: number}
roll : number
tilt : number
upperLip : {x: number, y: number}
class FaceTrackingOverlay() Object used to control one instance of an image that tracks a face and is laid over the video feed of the local participant. The image is visible to all participants. Create a FaceTrackingOverlay using createFaceTrackingOverlay or showFaceTrackingOverlay.

Jump to instance methods

class ImageResource(
  onLoad
)
Object used to load an image file which can be overlaid on the video feed.
Create an ImageResource with createImageResource.

Jump to instance methods

Jump to instance event functions


onLoad : undefined
An event that fires when the resource loads.
class Overlay() Object used to control one instance of an image laid over the video feed of the local participant and is positioned relative to the center of the video feed. The image is visible to all participants. Useful for decorations such as captions, borders, or animations that don't require face tracking. Create an Overlay using createOverlay or showOverlay.

Jump to instance methods

class ResourceLoadResult(
  isLoaded
)
Contains information about the success of a resource load.
isLoaded : boolean
True if the load successed, false otherwise.
class Sound() Object used to control one instance of a sound. Sounds played through this API will automatically be echo-cancelled. Create a Sound using createSound.

Jump to instance methods

AudioResource Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
createSound(
  opt_params
)
Sound Creates a new instance of a sound.

Note: Make sure you have the necessary rights to include audio content in Hangouts, including the broadcast of such content in Hangouts on Air, in accordance with our terms of service.
opt_params : {localOnly: boolean, loop: boolean, volume: number}
The options for the newly created sound. If the localOnly parameter is true, the sound plays only to the local participant; if false, the sound plays to all participants and, if in a Hangout On Air, to broadcast viewers.
dispose() undefined Disposes the resource and all sounds created from the resource.
getState() ResourceState Returns the state of the resource.
getUrl() string Returns the URL of the audio file for the resource.
isDisposed() boolean Returns true if the resource has been disposed.
isLoaded() boolean Returns true if the resource has successfully loaded.
play(
  opt_params
)
Sound Creates a new instance of a sound and starts it playing.

Note: Make sure you have the necessary rights to include audio content in Hangouts, including the broadcast of such content in Hangouts on Air, in accordance with our terms of service.
opt_params : {localOnly: boolean, loop: boolean, volume: number}
The options for the newly created sound. If the localOnly parameter is true, the sound plays only to the local participant; if false, the sound plays to all participants and, if in a Hangout On Air, to broadcast viewers.

Instance Event Functions in gapi.hangout.av.effects.AudioResource

Event Function Description
gapi.hangout.av.effects.AudioResource#onLoad
onLoad.add(
  callback
)
Adds a callback to be called when resource loads.
callback : function(ResourceLoadResult)
The callback to add.
onLoad.remove(
  callback
)
Removes a callback previously added by onLoad.add.
callback : function(ResourceLoadResult)
The callback to remove.

BackgroundBlur Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
dispose() undefined Disposes the background blur instance.
getAlphaThreshold() number Returns the alpha map threshold for background recognition.
getBlurWindowSize() number Returns the blur window size for background blur.
isAlphaThresholdAutoUpdating() boolean Returns true if the alpha map threshold for background blur is being automatically updated.
isDisposed() boolean Returns true if the background blur has been disposed.
isVisible() boolean Returns true if the background is being blurred in the local participant's video feed, false otherwise.
setAlphaThreshold(
  alphaThreshold
)
undefined Sets the alpha map threshold for background recognition.
alphaThreshold : number
The alpha threshold for background recognition.
setAlphaThresholdAutoUpdating(
  autoUpdating
)
undefined Sets whether the alpha map threshold for background recognition should be automatically updated for every single frame.
autoUpdating : boolean
Whether to automatically update alpha map threshold.
setBlurWindowSize(
  blurWindowSize
)
undefined Sets the blur window size for background blur. Blur window size is used to control the amount of blur: for each pixel (x, y), it is blurred by taking the average color of pixels within the window (x - blurWindowSize / 2, y - blurWindowSize / 2) to (x + blurWindowSize / 2, y + blurWindowSize / 2).
blurWindowSize : number
The blur window size in pixels.
setVisible(
  visible
)
undefined Sets the blurred background to be visible or not.
visible : boolean
Whether the blurred background is visible.

BackgroundReplacement Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
getAlphaThreshold() number Returns the alpha map threshold for the background replacement. For background replacement, each pixel is rated on how likely it is to be part of the background, from 0 to 255, where 0 means certainly part of the foreground (opaque video) and 255 means certainly part of the background (transparent video). The alpha threshold indicates where you want to set the threshold for replacement. By setting the threshold low, you will aggressively replace low-confidence pixels, and by setting it close to 255, you will be conservative about which pixels to replace.
getImageResource() ImageResource Returns the ImageResource used to replace the original background.
isAlphaThresholdAutoUpdating() boolean Returns true if the alpha map threshold is being updated automatically.
isModelUpdating() boolean Returns true if the background model is being updated, false otherwise.
isVisible() boolean Returns true if the background is being replaced with given image in the local participant's video feed, false otherwise.
resetModel() undefined Resets the internal background model for the background replacement.
setAlphaThreshold(
  alphaThreshold
)
undefined Sets the alpha map threshold for the background replacement.
alphaThreshold : number
The alpha map threshold for background replacement.
setAlphaThresholdAutoUpdating(
  autoUpdating
)
undefined Sets whether alpha map threshold should be automatically updated for every single frame.
autoUpdating : boolean
Whether to automatically update alpha map threshold.
setImageResource(
  resource
)
undefined Sets the ImageResource used to replace the original background.
resource : ImageResource
The image resource used to replace the original background.
setModelUpdating(
  updateModel
)
undefined Sets whether to update the background model for every single frame. By default, the background model adapts to the video feed and is updated continuously. With still background, the model can be stabilized after a short amount of time (about 30 seconds). An option is given to stop updating background model for better performance.
updateModel : boolean
Whether to update the background model.
setVisible(
  visible
)
undefined Sets the replaced background to be visible or not.
visible : boolean
Whether the replaced background is visible.

FaceTrackingOverlay Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
dispose() undefined Disposes the overlay. This function does not dispose of the underlying ImageResource.
getImageResource() ImageResource Returns the ImageResource used to create this object.
getOffset() {x: number, y: number} Returns the offset of the image overlay from the feature. See setOffset for a description of the x and y values.
getRotateWithFace() boolean Returns true if the image will rotate as the face rotates, false otherwise.
getRotation() number Returns the base rotation of an image in radians. This does not include any rotation occurring because of the getRotateWithFace flag.
getScale() number Returns the scale in relation to the natural image size of the overlay. This does not include any scaling occurring because of the getScaleWithFace flag. Example: a scale of 2 would cause the image to be twice its natural size.
getScaleWithFace() boolean Returns true if the size of the image will scale with the size of the face that is being tracked, false otherwise.
getTrackingFeature() FaceTrackingFeature Returns the feature of the face that the image overlay is attached to.
isDisposed() boolean Returns true if the overlay has been disposed.
isVisible() boolean Returns true if the image overlay is currently visible in the local participant's video feed, false otherwise.
setOffset(
  value,
  opt_y
)
undefined Sets the offset of the image overlay from the feature of the face being tracked. With an offset of (0,0), the overlay is centered on the feature.

The x offset ranges from -1 to 1, where 1 is the width of the video feed, and positive values move the overlay toward the right. The y offset also ranges from -1 to 1, where 1 is the height of the video feed, and postive values move the overlay toward the bottom.
value : number|{x: number, y: number}
Either a single number representing the x offset, or an object with the x, y offset.
opt_y : number
The y offset (this parameter is ignored if value is an object.)
setRotateWithFace(
  shouldRotate
)
undefined Sets whether the image should rotate as the face rotates.
shouldRotate : boolean
Whether the image should rotate with the face.
setRotation(
  rotation
)
undefined Sets the rotation for an image. This will be in addition to any rotation caused by setRotateWithFace.
rotation : number
The angle of rotation for the image, in radians.
setScale(
  scale
)
undefined Sets the amount an image should be scaled.
scale : number
The amount an image should be scaled relative to it's normal size.
setScaleWithFace(
  shouldScale
)
undefined Sets whether an image should scale as the face being tracked gets larger or smaller.
shouldScale : boolean
Whether the image should scale with the face.
setTrackingFeature(
  feature
)
undefined Sets the face feature that the image overlay is attached to.
feature : FaceTrackingFeature
The feature to track.
setVisible(
  visible
)
undefined Sets the image overlay to be visible or not.
visible : boolean
Whether the overlay is visible.

ImageResource Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
createFaceTrackingOverlay(
  opt_params
)
FaceTrackingOverlay Creates a new instance of a face tracking overlay with this image.
opt_params : {trackingFeature: gapi.hangout.av.effects.FaceTrackingFeature, offset: {x: number, y: number}, rotateWithFace: boolean, rotation: number, scale: number, scaleWithFace: boolean}
The options for the newly created image overlay.
createOverlay(
  opt_params
)
Overlay Creates a new instance of an overlay with this image.
opt_params : {position: {x: number, y: number}, rotation: number, scale: {magnitude: number, reference: gapi.hangout.av.effects.ScaleReference}}
The options for the newly created image overlay.
dispose() undefined Disposes the resource and all overlays created from the resource.
getState() ResourceState Returns the state of the resource.
getUrl() string The URL of the image file for the resource.
isDisposed() boolean Returns true if the resource has been disposed.
isLoaded() boolean Returns true if the resource has successfully loaded.
showFaceTrackingOverlay(
  opt_params
)
FaceTrackingOverlay Creates a new instance of a face tracking overlay with this image and displays it.
opt_params : {trackingFeature: gapi.hangout.av.effects.FaceTrackingFeature, offset: {x: number, y: number}, rotateWithFace: boolean, rotation: number, scale: number, scaleWithFace: boolean}
The options for the newly created image overlay.
showOverlay(
  opt_params
)
Overlay Creates a new instance of an overlay with this image and displays it.
opt_params : {position: {x: number, y: number}, rotation: number, scale: {magnitude: number, reference: gapi.hangout.av.effects.ScaleReference}}
The options for the newly created image overlay.

Instance Event Functions in gapi.hangout.av.effects.ImageResource

Event Function Description
gapi.hangout.av.effects.ImageResource#onLoad
onLoad.add(
  callback
)
Adds a callback to be called when resource loads.
callback : function(ResourceLoadResult)
The callback to add.
onLoad.remove(
  callback
)
Removes a callback previously added by onLoad.add.
callback : function(ResourceLoadResult)
The callback to remove.

Overlay Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
dispose() undefined Disposes the overlay.
getImageResource() ImageResource Returns the ImageResource used to create this object.
getPosition() {x: number, y: number} Returns the position of the image overlay. See setPosition for a description of the x and y values.
getRotation() number Returns the rotation of an image in radians.
getScale() {magnitude: number, reference: gapi.hangout.av.effects.ScaleReference} Returns the scale of the overlay. Example: a scale of {magnitude: 1, reference: gapi.hangout.av.effects.ScaleReference.WIDTH} would indicate that the image will be scaled so its width is the same as the video feed.
isDisposed() boolean Returns true if the overlay has been disposed.
isVisible() boolean Returns true if the image overlay is currently visible in the local participant's video feed, false otherwise.
setPosition(
  value,
  opt_y
)
undefined Sets the position of the image overlay. With an offset of (0,0), the overlay is centered on the video feed.

Positive x values move the overlay toward the right and a value of 1 is equal to the width of the video feed. Positive y values move the overlay toward the bottom and a value of 1 is equal to the height of the video feed. Example: an x of -0.5 and a y of 0.5 would position the overlay in the bottom left corner of the video feed.
value : number|{x: number, y: number}
Either a single number representing the x position, or an object with the x, y position.
opt_y : number
The y position (this parameter is ignored if value is an object.)
setRotation(
  rotation
)
undefined Sets the rotation for an image.
rotation : number
The angle of rotation for the image, in radians.
setScale(
  value,
  opt_reference
)
undefined Sets the amount an image should be scaled.
value : number|{magnitude: number, reference: gapi.hangout.av.effects.ScaleReference}
Either a single number representing amount the image should be scaled, or an object with the magnitude and reference.
opt_reference : ScaleReference
The aspect of the video feed which the image is scaled relative to.
setVisible(
  visible
)
undefined Sets the image overlay to be visible or not.
visible : boolean
Whether the overlay is visible.

Sound Instance Methods in gapi.hangout.av.effects

Instance Method Returns Description & Parameter
getAudioResource() AudioResource The AudioResource used to create this Sound.
getVolume() number The volume, in the range 0-1, of the sound.
dispose() undefined Disposes the sound. This function does not dispose of the underlying AudioResource.
isDisposed() boolean Returns true if the sound has been disposed.
isLocalOnly() boolean Returns true if the sound plays only to the local participant. Returns false if the sound plays to all participants and, if in a Hangout On Air, to broadcast viewers.
isLooped() boolean Returns true if the sound will repeat, false otherwise.
play() undefined Starts playing the sound.
setLoop(
  loop
)
undefined Sets whether the sound will repeat or not, false otherwise.
loop : boolean
Whether the sound will repeat.
setVolume(
  volume
)
undefined Sets the volume of the sound.
volume : number
The desired volume of the sound, in the range 0-1.
stop() undefined Stops the sound if it is currently playing.

Functions in gapi.hangout.av.effects

Function Returns Description & Parameter
createAudioResource(
  url
)
AudioResource Creates a new AudioResource.

Warning: Creating an audio resource allocates memory in the plugin. Allocating too many resources without disposing them can cause the Hangout to run out of memory and halt. Dispose of audio resources by using the dispose method.

See an example of a data URI.
url : string
The URL of the sound file. Only 16 bit PCM encoded WAV files are supported and loading is supported over http, https and using data URIs.
createBackgroundBlur() BackgroundBlur Creates a new BackgroundBlur.
createImageResource(
  url,
  opt_interestRegions
)
ImageResource Creates a new gapi.hangout.av.effects.ImageResource.

Warning: Creating an image resource allocates memory in the plugin. Allocating too many resources without disposing them can cause the Hangout to run out of memory and halt. Dispose of image resources by using the dispose method.

Warning: Creating an audio or image resource will allocate memory in the plugin. At this time, you cannot release these resources, so allocating too many resources can cause the Hangout to run out of memory and halt.

See an example of a data URI.
url : string
The URL of the image. Only PNG and JPEG files are supported and loading is supported over http, https and using data URIs.
opt_interestRegions : Array.<{left: number, top: number, width: number, height: number}>
An optional array of rectangular regions of interest inside the image area. By default, to optimize the video viewing experience, the main Hangout application can reposition the cropped video stream, potentially shifting part of the main video image off-screen or obscuring it with other visual elements on the page. This parameter controls how the video layout logic interacts with the static image overlay laid over the main video stream:
  • When no interest region is explicitly specified, a default region covering the entire static image overlay is assumed.
  • When an interest region is specified, the corresponding areas in the main video will not be moved off-screen or obscured by other parts of the user interface. For example, you could define the text portion of a lower-third graphic to be an interest region.
  • The coordinates and sizes of each interest region in this array are fractions relative to the image resource, and the origin is at the center of the image. Values for left and top should be in the range [-0.5, 0.5], and values for width and height in [0, 1].
  • If either the combined width or height across the regions in this array is 0, this image resource will be ignored in video layout calculations.
getBackgroundReplacement() BackgroundReplacement Gets an instance of a background replacement if the background replacement lock has been acquired. Otherwise, returns null.
hasBackgroundReplacementLock() boolean Returns true if the lock for background replacement has been acquired, false otherwise.
requestBackgroundReplacementLock(
  callback
)
undefined Requests the lock for background replacement.
callback : function(boolean)
The callback to receive the result of the lock request.
releaseBackgroundReplacementLock() undefined Releases the lock for background replacement.

Event Functions in gapi.hangout.av.effects

Event Function Description
gapi.hangout.av.effects.onFaceTrackingDataChanged
onFaceTrackingDataChanged.add(
  callback
)
Adds a callback to be called whenever the face tracking data for the local participant changes. The argument to the callback is the current face tracking data for the local participant.
callback : function(FaceTrackingData)
The callback to add.
onFaceTrackingDataChanged.remove(
  callback
)
Removes a callback previously added by onFaceTrackingDataChanged.add
callback : function(FaceTrackingData)
The callback to remove.

Enums in gapi.hangout.av.effects

Enum Description
FaceTrackingFeature Identifiers for the features that can be tracked by a gapi.hangout.av.effects.FaceTrackingOverlay. "Left" and "right" are from how others view the face.
LEFT_EYE
LEFT_EYEBROW_LEFT
LEFT_EYEBROW_RIGHT
LOWER_LIP
MOUTH_CENTER
MOUTH_LEFT
MOUTH_RIGHT
NOSE_ROOT
NOSE_TIP
RIGHT_EYE
RIGHT_EYEBROW_LEFT
RIGHT_EYEBROW_RIGHT
UPPER_LIP
ResourceState Possible states of a resource.
DISPOSED
ERROR
LOADING
LOADED
ScaleReference Possible values for the aspect of the video feed that a gapi.hangout.av.effects.Overlay is scaled relative to.
HEIGHT
WIDTH

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.