Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Composition Hooks


(warning)

Warning

This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.


Overview

overview page anchor

The Twilio Composition Hooks REST API lets you automate the creation of Compositions. A Composition Hook is a template that specifies how Group Room video recordings should be composed. Using this API you will be able to:

  • Create and manage Composition Hooks.
  • Monitor the Compositions created by Hooks.

Composition Hooks work per-account (i.e. project). Hence, when a Group Room is completed, all enabled Composition Hooks in the account will be executed against that room recordings.

This API is located beneath the following base URL:


_10
https://video.twilio.com



These are the URI schemes for the Composition Hooks REST API and the supported methods:

  • /v1/CompositionHooks
    • GET : Lists Composition Hook resources.
    • POST : Creates new Composition Hook resources.
  • /v1/CompositionHooks/{CompositionHookSid}
    • GET : Retrieves a Composition Hook instance.
    • POST : Updates a Composition Hook instance.
    • DELETE : Deletes a Composition Hook instance.

Composition Hook instance resource

composition-hook-instance-resource page anchor

The Composition Hook instance resource represents a template that specifies how Group Room recordings should be composed.

Resource URI

hk-uri page anchor

_10
/v1/CompositionHooks/{CompositionHookSid}

Resource Properties

hk-properties page anchor

A Composition Hook Instance Resource has the following properties:

Resource properties
account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the CompositionHook resource.


friendly_nametype: stringNot PII

The string that you assigned to describe the resource. Can be up to 100 characters long and must be unique within the account.


enabledtype: booleanNot PII

Whether the CompositionHook is active. When true, the CompositionHook is triggered for every completed Group Room on the account. When false, the CompositionHook is never triggered.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


sidtype: SID<HK>Not PII

The unique string that we created to identify the CompositionHook resource.


audio_sourcestype: string[]PII MTL: 30 days

The array of track names to include in the compositions created by the composition hook. A composition triggered by the composition hook includes all audio sources specified in audio_sources except those specified in audio_sources_excluded. The track names in this property can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, student* includes tracks named student as well as studentTeam. Please, be aware that either video_layout or audio_sources have to be provided to get a valid creation request


audio_sources_excludedtype: string[]PII MTL: 30 days

The array of track names to exclude from the compositions created by the composition hook. A composition triggered by the composition hook includes all audio sources specified in audio_sources except for those specified in audio_sources_excluded. The track names in this property can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, student* excludes student as well as studentTeam. This parameter can also be empty.


video_layouttype: objectPII MTL: 30 days

A JSON object that describes the video layout of the composition in terms of regions as specified in the HTTP POST request that created the CompositionHook resource. See POST Parameters(link takes you to an external page) for more information. Please, be aware that either video_layout or audio_sources have to be provided to get a valid creation request


resolutiontype: stringNot PII

The dimensions of the video image in pixels expressed as columns (width) and rows (height). The string's format is {width}x{height}, such as 640x480.


trimtype: booleanNot PII

Whether intervals with no media are clipped, as specified in the POST request that created the CompositionHook resource. Compositions with trim enabled are shorter when the Room is created and no Participant joins for a while as well as if all the Participants leave the room and join later, because those gaps will be removed. See Specifying Video Layouts(link takes you to an external page) for more info.


formattype: enum<STRING>Not PII

The container format of the media files used by the compositions created by the composition hook. If mp4 or webm, audio_sources must have one or more tracks and/or a video_layout element must contain a valid video_sources list, otherwise an error occurs.

Possible values:
mp4webm

status_callbacktype: string<URI>Not PII

The URL we call using the status_callback_method to send status information to your application.


status_callback_methodtype: enum<HTTP METHOD>Not PII

The HTTP method we should use to call status_callback. Can be POST or GET and defaults to POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

urltype: string<URI>Not PII

The absolute URL of the resource.

Returns the single Composition Hook instance identified by {CompositionHookSid}.

Updates the Composition Hook instance identified by {CompositionHookSid}. Be aware that partial updates are not supported. This means that when updating you must specify all the POST parameters, even for properties that don't change. Any optional parameter that is not explicitly specified will be reset (i.e. set to its default value)

The following parameters are supported:

URI parameters
Sidtype: SID<HK>Not PII
Path Parameter

The SID of the CompositionHook resource to update.


Request body parameters
FriendlyNametype: stringNot PII
Required

A descriptive string that you create to describe the resource. It can be up to 100 characters long and it must be unique within the account.


Enabledtype: booleanNot PII

Whether the composition hook is active. When true, the composition hook will be triggered for every completed Group Room in the account. When false, the composition hook never triggers.


VideoLayouttype: objectPII MTL: 30 days

A JSON object that describes the video layout of the composition hook in terms of regions. See Specifying Video Layouts(link takes you to an external page) for more info.


AudioSourcestype: string[]PII MTL: 30 days

An array of track names from the same group room to merge into the compositions created by the composition hook. Can include zero or more track names. A composition triggered by the composition hook includes all audio sources specified in audio_sources except those specified in audio_sources_excluded. The track names in this parameter can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, student* includes tracks named student as well as studentTeam.


AudioSourcesExcludedtype: string[]PII MTL: 30 days

An array of track names to exclude. A composition triggered by the composition hook includes all audio sources specified in audio_sources except for those specified in audio_sources_excluded. The track names in this parameter can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, student* excludes student as well as studentTeam. This parameter can also be empty.


Trimtype: booleanNot PII

Whether to clip the intervals where there is no active media in the compositions triggered by the composition hook. The default is true. Compositions with trim enabled are shorter when the Room is created and no Participant joins for a while as well as if all the Participants leave the room and join later, because those gaps will be removed. See Specifying Video Layouts(link takes you to an external page) for more info.


Formattype: enum<STRING>Not PII

The container format of the media files used by the compositions created by the composition hook. Can be: mp4 or webm and the default is webm. If mp4 or webm, audio_sources must have one or more tracks and/or a video_layout element must contain a valid video_sources list, otherwise an error occurs.

Possible values:
mp4webm

Resolutiontype: stringNot PII

A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to 640x480. The string's format is {width}x{height} where:

  • 16 <= {width} <= 1280
  • 16 <= {height} <= 1280
  • {width} * {height} <= 921,600

Typical values are:

  • HD = 1280x720
  • PAL = 1024x576
  • VGA = 640x480
  • CIF = 320x240

Note that the resolution imposes an aspect ratio to the resulting composition. When the original video tracks are constrained by the aspect ratio, they are scaled to fit. See Specifying Video Layouts(link takes you to an external page) for more info.


StatusCallbacktype: string<URI>Not PII

The URL we should call using the status_callback_method to send status information to your application on every composition event. If not provided, status callback events will not be dispatched.


StatusCallbackMethodtype: enum<HTTP METHOD>Not PII

The HTTP method we should use to call status_callback. Can be: POST or GET and the default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

The return value is a 200 OK if the request is accepted and executed successfully. Otherwise, a 4xx is returned with detailed information about the problem.

Deletes the Composition Hook instance identified by {CompositionHookSid}.

The return value is a 204 NO CONTENT if the request is accepted and executed successfully. In this case, deletion is immediate.

Otherwise, a 4xx is returned with detailed information about the problem.


Composition Hooks list resource

compositions-hooks-list-resource page anchor

_10
/v1/CompositionHooks

Creates a new Composition Hook and registers it so that Twilio can fire it whenever a Group Room is completed.

The return value is a 201 CREATED if the request is accepted and executed successfully. Otherwise, a 4xx is returned with detailed information about the problem.

Supported POST parameters

http-post-parameters page anchor

The following table shows all the parameters that can be specified when creating a new Composition Hook.

Request body parameters
FriendlyNametype: stringNot PII
Required

A descriptive string that you create to describe the resource. It can be up to 100 characters long and it must be unique within the account.


Enabledtype: booleanNot PII

Whether the composition hook is active. When true, the composition hook will be triggered for every completed Group Room in the account. When false, the composition hook will never be triggered.


VideoLayouttype: objectPII MTL: 30 days

An object that describes the video layout of the composition hook in terms of regions. See Specifying Video Layouts(link takes you to an external page) for more info.


AudioSourcestype: string[]PII MTL: 30 days

An array of track names from the same group room to merge into the compositions created by the composition hook. Can include zero or more track names. A composition triggered by the composition hook includes all audio sources specified in audio_sources except those specified in audio_sources_excluded. The track names in this parameter can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, student* includes tracks named student as well as studentTeam.


AudioSourcesExcludedtype: string[]PII MTL: 30 days

An array of track names to exclude. A composition triggered by the composition hook includes all audio sources specified in audio_sources except for those specified in audio_sources_excluded. The track names in this parameter can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, student* excludes student as well as studentTeam. This parameter can also be empty.


Resolutiontype: stringNot PII

A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to 640x480. The string's format is {width}x{height} where:

  • 16 <= {width} <= 1280
  • 16 <= {height} <= 1280
  • {width} * {height} <= 921,600

Typical values are:

  • HD = 1280x720
  • PAL = 1024x576
  • VGA = 640x480
  • CIF = 320x240

Note that the resolution imposes an aspect ratio to the resulting composition. When the original video tracks are constrained by the aspect ratio, they are scaled to fit. See Specifying Video Layouts(link takes you to an external page) for more info.


Formattype: enum<STRING>Not PII

The container format of the media files used by the compositions created by the composition hook. Can be: mp4 or webm and the default is webm. If mp4 or webm, audio_sources must have one or more tracks and/or a video_layout element must contain a valid video_sources list, otherwise an error occurs.

Possible values:
mp4webm

StatusCallbacktype: string<URI>Not PII

The URL we should call using the status_callback_method to send status information to your application on every composition event. If not provided, status callback events will not be dispatched.


StatusCallbackMethodtype: enum<HTTP METHOD>Not PII

The HTTP method we should use to call status_callback. Can be: POST or GET and the default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

Trimtype: booleanNot PII

Whether to clip the intervals where there is no active media in the Compositions triggered by the composition hook. The default is true. Compositions with trim enabled are shorter when the Room is created and no Participant joins for a while as well as if all the Participants leave the room and join later, because those gaps will be removed. See Specifying Video Layouts(link takes you to an external page) for more info.

A Composition Hook VideoLayout describes the video layout of compositions created by that Hook. Details on how to specify such a VideoLayout can be found in the Specifying Video Layouts section on Twilio's Compositions REST API documentation. The only aspect you may take into consideration is that, when working with Composition Hooks, you don't have information about the specific SIDs of tracks, recordings and participants. Hence, you must specify layouts basing on track names and set such names appropriately in your real-time Group Rooms.

Retrieves the list Composition Hook Records belonging to the corresponding AccountSid with paging data.

Supported GET parameters
hks-get-parameters page anchor

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive

URI parameters
Enabledtype: booleanNot PII
Query Parameter

Read only CompositionHook resources with an enabled value that matches this parameter.


DateCreatedAftertype: string<DATE TIME>Not PII
Query Parameter

Read only CompositionHook resources created on or after this ISO 8601(link takes you to an external page) datetime with time zone.


DateCreatedBeforetype: string<DATE TIME>Not PII
Query Parameter

Read only CompositionHook resources created before this ISO 8601(link takes you to an external page) datetime with time zone.


FriendlyNametype: stringNot PII
Query Parameter

Read only CompositionHook resources with friendly names that match this string. The match is not case sensitive and can include asterisk * characters as wildcard match.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Not Supported


Programming with Composition Hooks is quite similar to programming with Compositions. Hence, in addition to the examples here below, you may also find useful our Recording Compositions documentation

Creating an audio mixing Composition Hook

example-audio-mixing-hk page anchor

In this example, we want to compose only the audio tracks of all completed Group Rooms. Considering that:

  • Your application credentials are ( SKXXXX:your_api_key_secret )
  • You want to mix all audio tracks

The desired Composition Hook can be created with the following code:

Create a Composition Hook mixing all room audio tracks

create-a-composition-hook-mixing-all-room-audio-tracks page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_24
// NOTE: This example uses the next generation Twilio helper library - for more
_24
// information on how to download and install this version, visit
_24
// https://www.twilio.com/docs/libraries/node
_24
_24
// Find your credentials at twilio.com/console
_24
// To set up environmental variables, see http://twil.io/secure
_24
const API_KEY_SID = process.env.TWILIO_API_KEY;
_24
const API_KEY_SECRET = process.env.TWILIO_API_KEY_SECRET;
_24
const ACCOUNT_SID = process.env.TWILIO_ACCOUNT_SID;
_24
_24
const Twilio = require('twilio');
_24
_24
const client = new Twilio(API_KEY_SID, API_KEY_SECRET, {accountSid: ACCOUNT_SID});
_24
_24
client.video.compositionHooks.
_24
create({
_24
friendlyName: 'MixingAllRoomAudiosHook',
_24
audioSources: '*',
_24
statusCallback: 'http://my.server.org/callbacks',
_24
format: 'mp4'
_24
})
_24
.then(compositionHook =>{
_24
console.log('Created Composition Hook with SID=' + compositionHook.sid);
_24
});

Output

_19
{
_19
"account_sid": "ACXXXX",
_19
"sid": "HKXXXX",
_19
"friendly_name": "MixingAllRoomAudiosHook",
_19
"enabled": true,
_19
"date_created": "2018-12-19T16:22:13Z",
_19
"date_updated": null,
_19
"audio_sources": [
_19
"*"
_19
],
_19
"audio_sources_excluded": [],
_19
"video_layout": {},
_19
"format": "mp4",
_19
"trim": true,
_19
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_19
"resolution": "640x480",
_19
"status_callback_method": "POST",
_19
"status_callback": "http://my.server.org/callbacks"
_19
}

Creating a simple video mixing Composition Hook

example-grid-mixing-hk page anchor

In this example, we create a Composition Hook for composing all tracks of a Group Room using a simple grid layout for video.

Considering that:

  • Your application credentials are ( SKXXXX:your_api_key_secret )
  • You want to use mp4 as target format
  • You want to use VGA resolution ( 640x480 )

You can create the desired Composition Hook using the following:

Create a Composition Hook composing rooms in a grid

create-a-composition-hook-composing-rooms-in-a-grid page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_29
// NOTE: This example uses the next generation Twilio helper library - for more
_29
// information on how to download and install this version, visit
_29
// https://www.twilio.com/docs/libraries/node
_29
_29
// Find your credentials at twilio.com/console
_29
// To set up environmental variables, see http://twil.io/secure
_29
const API_KEY_SID = process.env.TWILIO_API_KEY;
_29
const API_KEY_SECRET = process.env.TWILIO_API_KEY_SECRET;
_29
const ACCOUNT_SID = process.env.TWILIO_ACCOUNT_SID;
_29
_29
const Twilio = require('twilio');
_29
_29
const client = new Twilio(API_KEY_SID, API_KEY_SECRET, {accountSid: ACCOUNT_SID});
_29
_29
client.video.compositionHooks.
_29
create({
_29
friendlyName: 'MyFirstCompositionHook',
_29
audioSources: '*',
_29
videoLayout: {
_29
grid : {
_29
video_sources: ['*']
_29
}
_29
},
_29
statusCallback: 'http://my.server.org/callbacks',
_29
format: 'mp4'
_29
})
_29
.then(compositionHook =>{
_29
console.log('Created Composition Hook with SID=' + compositionHook.sid);
_29
});

Output

_35
{
_35
"account_sid": "ACXXXX",
_35
"sid": "HKXXXX",
_35
"friendly_name": "MyFirstCompositionHook",
_35
"enabled": true,
_35
"date_created": "2018-12-19T16:04:11Z",
_35
"date_updated": null,
_35
"audio_sources": [
_35
"*"
_35
],
_35
"audio_sources_excluded": [],
_35
"video_layout": {
_35
"grid": {
_35
"z_pos": 0,
_35
"reuse": "show_oldest",
_35
"x_pos": 0,
_35
"max_columns": null,
_35
"cells_excluded": [],
_35
"video_sources_excluded": [],
_35
"height": null,
_35
"width": null,
_35
"max_rows": null,
_35
"y_pos": 0,
_35
"video_sources": [
_35
"*"
_35
]
_35
}
_35
},
_35
"format": "mp4",
_35
"trim": true,
_35
"resolution": "640x480",
_35
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_35
"status_callback_method": "POST",
_35
"status_callback": "http://my.server.org/callbacks"
_35
}

Creating a video mixing Composition Hook with complex layout

example-complex-layout-hk page anchor

In this example, we create a Composition Hook that fires a composition with PiP (Picture-in-Picture) layout for every completed Group Room. Observe that, at Hook creation time we don't know any track or recording SIDs. Due to this, we must rely on track names. Here we assume that such names comply with the following:

  • A presenter must share a webcam track named presenter-cam as well as a screenshare track named screen . The presenter audio track, in turn, has the name presenter-audio .
  • In addition to the presenter, the room may have a special participant whose audio track we want to include in the composition. When that participant is present, her audio track has the name listener-audio .

Assuming that:

  • Your application credentials are ( SKXXXX:your_api_key_secret )
  • You want to use mp4 as target format
  • You want to use HD resolution ( 1280x720 )

The desired Composition Hook may be created as follows:

Create a Composition Hook with complex video layout

create-a-composition-hook-with-complex-video-layout page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_39
// NOTE: This example uses the next generation Twilio helper library - for more
_39
// information on how to download and install this version, visit
_39
// https://www.twilio.com/docs/libraries/node
_39
_39
// Find your credentials at twilio.com/console
_39
// To set up environmental variables, see http://twil.io/secure
_39
const API_KEY_SID = process.env.TWILIO_API_KEY;
_39
const API_KEY_SECRET = process.env.TWILIO_API_KEY_SECRET;
_39
const ACCOUNT_SID = process.env.TWILIO_ACCOUNT_SID;
_39
_39
const Twilio = require('twilio');
_39
_39
const client = new Twilio(API_KEY_SID, API_KEY_SECRET, {accountSid: ACCOUNT_SID});
_39
_39
client.video.compositionHooks.
_39
create({
_39
friendlyName: 'MyHookWithComplexVideoLayout',
_39
audioSources: ['listener-audio', 'presenter-audio'],
_39
videoLayout: {
_39
main: {
_39
z_pos: 1,
_39
video_sources: ['screen']
_39
},
_39
pip: {
_39
z_pos: 2,
_39
x_pos: 1000,
_39
y_pos: 30,
_39
width: 240,
_39
height: 180,
_39
video_sources: ['presenter-cam']
_39
}
_39
},
_39
statusCallback: 'http://my.server.org/callbacks',
_39
resolution: '1280x720',
_39
format: 'mp4'
_39
})
_39
.then(compositionHook =>{
_39
console.log('Created Composition Hook with SID=' + compositionHook.sid);
_39
});

Output

_51
{
_51
"account_sid": "ACXXXX",
_51
"sid": "HKXXXX",
_51
"friendly_name": "MyHookWithComplexVideoLayout",
_51
"enabled": true,
_51
"date_created": "2018-12-19T16:44:10Z",
_51
"date_updated": null,
_51
"audio_sources": [
_51
"listener-audio",
_51
"presenter-audio"
_51
],
_51
"audio_sources_excluded": [],
_51
"trim": true,
_51
"video_layout": {
_51
"pip": {
_51
"z_pos": 2,
_51
"reuse": "show_oldest",
_51
"x_pos": 1000,
_51
"max_columns": null,
_51
"cells_excluded": [],
_51
"video_sources_excluded": [],
_51
"height": 180,
_51
"width": 240,
_51
"max_rows": null,
_51
"y_pos": 30,
_51
"video_sources": [
_51
"presenter-cam"
_51
]
_51
},
_51
"main": {
_51
"z_pos": 1,
_51
"reuse": "show_oldest",
_51
"x_pos": 0,
_51
"max_columns": null,
_51
"cells_excluded": [],
_51
"video_sources_excluded": [],
_51
"height": null,
_51
"width": null,
_51
"max_rows": null,
_51
"y_pos": 0,
_51
"video_sources": [
_51
"screen"
_51
]
_51
}
_51
},
_51
"resolution": "1280x720",
_51
"format": "mp4",
_51
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_51
"status_callback_method": "POST",
_51
"status_callback": "http://my.server.org/callbacks"
_51
}

Getting a Composition Hook

example-get-hk page anchor

For executing this example you need:

  • Your application credentials ( SKXXXX:your_api_key_secret )
  • The Composition Hook Sid ( HKXXXX )

Fetch a Composition Hook resource

fetch-a-composition-hook-resource page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_17
// NOTE: This example uses the next generation Twilio helper library - for more
_17
// information on how to download and install this version, visit
_17
// https://www.twilio.com/docs/libraries/node
_17
_17
const apiKeySid = 'SKXXXX';
_17
const apiKeySecret = 'your_api_key_secret';
_17
// To set up environmental variables, see http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const Twilio = require('twilio');
_17
_17
const client = new Twilio(apiKeySid, apiKeySecret, {accountSid: accountSid});
_17
_17
compositionHook = client.video.compositionHooks('HKXXXX')
_17
.fetch()
_17
.then(compositionHook =>{
_17
console.log('Read Composition Hook with SID=' + compositionHook.sid);
_17
});

Output

_19
{
_19
"account_sid": "ACXXXX",
_19
"sid": "HKXXXX",
_19
"friendly_name": "MixingAllRoomAudiosHook",
_19
"enabled": true,
_19
"date_created": "2018-12-19T16:22:13Z",
_19
"date_updated": null,
_19
"audio_sources": [
_19
"*"
_19
],
_19
"audio_sources_excluded": [],
_19
"video_layout": {},
_19
"format": "mp4",
_19
"trim": true,
_19
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_19
"resolution": "640x480",
_19
"status_callback_method": "POST",
_19
"status_callback": "http://my.server.org/callbacks"
_19
}

Listing all enabled Composition Hooks

example-list-hks page anchor

For executing this example you need:

  • Your application credentials ( SKXXXX:your_api_key_secret )

List all enabled Composition Hooks

list-all-enabled-composition-hooks page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_22
// NOTE: This example uses the next generation Twilio helper library - for more
_22
// information on how to download and install this version, visit
_22
// https://www.twilio.com/docs/libraries/node
_22
_22
const apiKeySid = 'SKXXXX';
_22
const apiKeySecret = 'your_api_key_secret';
_22
// To set up environmental variables, see http://twil.io/secure
_22
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22
const Twilio = require('twilio');
_22
_22
const client = new Twilio(apiKeySid, apiKeySecret, {accountSid: accountSid});
_22
_22
client.video.compositionHooks.
_22
list({
_22
enabled: true
_22
})
_22
.then(hooks =>{
_22
console.log("Found " + hooks.length + " Composition Hooks.");
_22
hooks.forEach(function(hook){
_22
console.log('Read hook with SID=' + hook.sid);
_22
});
_22
});

Output

_188
{
_188
"composition_hooks": [
_188
{
_188
"trim": true,
_188
"video_layout": {
_188
"pip": {
_188
"z_pos": 2,
_188
"reuse": "show_oldest",
_188
"x_pos": 1000,
_188
"max_columns": null,
_188
"cells_excluded": [],
_188
"video_sources_excluded": [],
_188
"height": 180,
_188
"width": 240,
_188
"max_rows": null,
_188
"y_pos": 30,
_188
"video_sources": [
_188
"presenter-cam"
_188
]
_188
},
_188
"main": {
_188
"z_pos": 1,
_188
"reuse": "show_oldest",
_188
"x_pos": 0,
_188
"max_columns": null,
_188
"cells_excluded": [],
_188
"video_sources_excluded": [],
_188
"height": null,
_188
"width": null,
_188
"max_rows": null,
_188
"y_pos": 0,
_188
"video_sources": [
_188
"screen"
_188
]
_188
}
_188
},
_188
"audio_sources_excluded": [],
_188
"format": "mp4",
_188
"date_updated": null,
_188
"friendly_name": "MyHookWithComplexVideoLayout",
_188
"enabled": true,
_188
"account_sid": "ACXXXX",
_188
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_188
"audio_sources": [
_188
"listener-audio",
_188
"listener-video"
_188
],
_188
"sid": "HKXXXX",
_188
"date_created": "2018-12-19T16:44:10Z",
_188
"resolution": "1280x720",
_188
"status_callback_method": "POST",
_188
"status_callback": "http://my.server.org/callbacks"
_188
},
_188
{
_188
"trim": true,
_188
"video_layout": {},
_188
"audio_sources_excluded": [],
_188
"format": "mp4",
_188
"date_updated": null,
_188
"friendly_name": "MixingAllRoomAudiosHook",
_188
"enabled": true,
_188
"account_sid": "ACXXXX",
_188
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_188
"audio_sources": [
_188
"*"
_188
],
_188
"sid": "HKXXXX",
_188
"date_created": "2018-12-19T16:22:13Z",
_188
"resolution": "640x480",
_188
"status_callback_method": "POST",
_188
"status_callback": "http://my.server.org/callbacks"
_188
},
_188
{
_188
"trim": true,
_188
"video_layout": {
_188
"grid": {
_188
"z_pos": 0,
_188
"reuse": "show_oldest",
_188
"x_pos": 0,
_188
"max_columns": null,
_188
"cells_excluded": [],
_188
"video_sources_excluded": [],
_188
"height": null,
_188
"width": null,
_188
"max_rows": null,
_188
"y_pos": 0,
_188
"video_sources": [
_188
"*"
_188
]
_188
}
_188
},
_188
"audio_sources_excluded": [],
_188
"format": "mp4",
_188
"date_updated": null,
_188
"friendly_name": "MyFirstCompositionHook2",
_188
"enabled": true,
_188
"account_sid": "ACXXXX",
_188
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_188
"audio_sources": [
_188
"*"
_188
],
_188
"sid": "HKXXXX",
_188
"date_created": "2018-12-19T16:15:25Z",
_188
"resolution": "640x480",
_188
"status_callback_method": "POST",
_188
"status_callback": "http://my.server.org/callbacks"
_188
},
_188
{
_188
"trim": true,
_188
"video_layout": {
_188
"grid": {
_188
"z_pos": 0,
_188
"reuse": "show_oldest",
_188
"x_pos": 0,
_188
"max_columns": null,
_188
"cells_excluded": [],
_188
"video_sources_excluded": [],
_188
"height": null,
_188
"width": null,
_188
"max_rows": null,
_188
"y_pos": 0,
_188
"video_sources": [
_188
"*"
_188
]
_188
}
_188
},
_188
"audio_sources_excluded": [],
_188
"format": "mp4",
_188
"date_updated": null,
_188
"friendly_name": "MyFirstCompositionHook",
_188
"enabled": true,
_188
"account_sid": "ACXXXX",
_188
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_188
"audio_sources": [
_188
"*"
_188
],
_188
"sid": "HKXXXX",
_188
"date_created": "2018-12-19T16:04:11Z",
_188
"resolution": "640x480",
_188
"status_callback_method": "POST",
_188
"status_callback": "http://my.server.org/callbacks"
_188
},
_188
{
_188
"trim": true,
_188
"video_layout": {
_188
"grid": {
_188
"z_pos": 0,
_188
"reuse": "show_oldest",
_188
"x_pos": 0,
_188
"max_columns": null,
_188
"cells_excluded": [],
_188
"video_sources_excluded": [],
_188
"height": null,
_188
"width": null,
_188
"max_rows": null,
_188
"y_pos": 0,
_188
"video_sources": [
_188
"*"
_188
]
_188
}
_188
},
_188
"audio_sources_excluded": [],
_188
"format": "mp4",
_188
"date_updated": "2018-12-19T15:52:08Z",
_188
"friendly_name": "llf-composition-hook-test",
_188
"enabled": false,
_188
"account_sid": "ACXXXX",
_188
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_188
"audio_sources": [
_188
"*"
_188
],
_188
"sid": "HKXXXX",
_188
"date_created": "2018-12-19T15:09:41Z",
_188
"resolution": "640x480",
_188
"status_callback_method": "POST",
_188
"status_callback": null
_188
}
_188
],
_188
"meta": {
_188
"page": 0,
_188
"page_size": 50,
_188
"first_page_url": "https://video.twilio.com/v1/CompositionHooks?PageSize=50&Page=0",
_188
"previous_page_url": null,
_188
"url": "https://video.twilio.com/v1/CompositionHooks?PageSize=50&Page=0",
_188
"next_page_url": null,
_188
"key": "composition_hooks"
_188
}
_188
}

Updating a Composition Hook

example-update-hk page anchor

A very important aspect that you must remember is that we do not support partial updates. This means that you must provide all POST parameters on every update operation. In other words, any optional parameter you don't provide will be reset (i.e. set to its default value) with the update.

Just for illustration, the following example updates the above-created Grid Composition Hook to disable it. Observe that we need to provide again all the properties that were set during the create operation.

Update a Composition Hook to disable it

update-a-composition-hook-to-disable-it page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_30
// NOTE: This example uses the next generation Twilio helper library - for more
_30
// information on how to download and install this version, visit
_30
// https://www.twilio.com/docs/libraries/node
_30
_30
// Find your credentials at twilio.com/console
_30
// To set up environmental variables, see http://twil.io/secure
_30
const API_KEY_SID = process.env.TWILIO_API_KEY;
_30
const API_KEY_SECRET = process.env.TWILIO_API_KEY_SECRET;
_30
const ACCOUNT_SID = process.env.TWILIO_ACCOUNT_SID;
_30
_30
const Twilio = require('twilio');
_30
_30
const client = new Twilio(API_KEY_SID, API_KEY_SECRET, {accountSid: ACCOUNT_SID});
_30
_30
client.video.compositionHooks('HKXXXX')
_30
update({
_30
friendlyName: 'MyFirstCompositionHook',
_30
enabled: false,
_30
audioSources: '*',
_30
videoLayout: {
_30
grid : {
_30
video_sources: ['*']
_30
}
_30
},
_30
statusCallback: 'http://my.server.org/callbacks',
_30
format: 'mp4'
_30
})
_30
.then(compositionHook =>{
_30
console.log('Updated Composition Hook with SID=' + compositionHook.sid);
_30
});

Output

_35
{
_35
"account_sid": "ACXXXX",
_35
"sid": "HKXXXX",
_35
"friendly_name": "MyFirstCompositionHook",
_35
"enabled": false,
_35
"date_created": "2018-12-19T16:04:11Z",
_35
"date_updated": "2018-12-19T16:55:21Z",
_35
"audio_sources": [
_35
"*"
_35
],
_35
"audio_sources_excluded": [],
_35
"video_layout": {
_35
"grid": {
_35
"z_pos": 0,
_35
"reuse": "show_oldest",
_35
"x_pos": 0,
_35
"max_columns": null,
_35
"cells_excluded": [],
_35
"video_sources_excluded": [],
_35
"height": null,
_35
"width": null,
_35
"max_rows": null,
_35
"y_pos": 0,
_35
"video_sources": [
_35
"*"
_35
]
_35
}
_35
},
_35
"format": "mp4",
_35
"trim": true,
_35
"resolution": "640x480",
_35
"url": "https://video.twilio.com/v1/CompositionHooks/HKXXXX",
_35
"status_callback_method": "POST",
_35
"status_callback": "http://my.server.org/callbacks"
_35
}

Deleting a Composition Hook

example-delete-hk page anchor

For executing this example you need:

  • Your application credentials ( SKXXXX:your_api_key_secret )
  • The Composition Hook Sid ( HKXXXX )

Delete a Composition Hook

delete-a-composition-hook page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_17
// NOTE: This example uses the next generation Twilio helper library - for more
_17
// information on how to download and install this version, visit
_17
// https://www.twilio.com/docs/libraries/node
_17
_17
const apiKeySid = 'SKXXXX';
_17
const apiKeySecret = 'your_api_key_secret';
_17
// To set up environmental variables, see http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const Twilio = require('twilio');
_17
_17
const client = new Twilio(apiKeySid, apiKeySecret, {accountSid: accountSid});
_17
_17
client.video.compositionHooks('HKXXXX').
_17
remove()
_17
.then(response =>{
_17
console.log('Composition Hook removed');
_17
});

Output

_10
A successful request returns an HTTP status code 204 and an empty body


Known Problems and Limitations

known-problems-and-limitations page anchor

There are no known problems.


Rate this page: