Composition Hooks

Overview

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:

https://video.twilio.com

URI Schemes
Composition Hook instance resource
Composition Hooks list resource
Examples
Known Problems and Limitations

URI Schemes

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

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

Resource URI

/v1/CompositionHooks/{CompositionHookSid}

Resource Properties

A Composition Hook Instance Resource has the following properties:

Resource Properties in REST API format
`account_sid`	sid<AC> Not PII The SID of the Account that created the CompositionHook resource.
`friendly_name`	string Not PII The string that you assigned to describe the resource. Can be up to 100 characters long and must be unique within the account.
`enabled`	boolean Not 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_created`	date_time<iso8601> Not PII The date and time in GMT when the resource was created specified in ISO 8601 format.
`date_updated`	date_time<iso8601>? Not PII The date and time in GMT when the resource was last updated specified in ISO 8601 format.
`sid`	sid<HK> Not PII The unique string that we created to identify the CompositionHook resource.
`audio_sources`	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_excluded`	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_layout`	object PII 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 for more information. Please, be aware that either video_layout or audio_sources have to be provided to get a valid creation request
`resolution`	string Not 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`.
`trim`	boolean Not 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 for more info.
`format`	enum:format 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.
`status_callback`	url? Not PII The URL we call using the `status_callback_method` to send status information to your application.
`status_callback_method`	http_method Not PII The HTTP method we should use to call `status_callback`. Can be `POST` or `GET` and defaults to `POST`.
`url`	url Not PII The absolute URL of the resource.

HTTP GET

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

HTTP POST

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:

Parameters in REST API format
`sid` Path	post sid<HK> Not PII The SID of the CompositionHook resource to update.
`friendly_name` Required	post string Not PII 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.
`enabled` Optional	post boolean Not 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.
`video_layout` Optional	post object PII MTL: 30 DAYS A JSON object that describes the video layout of the composition hook in terms of regions. See Specifying Video Layouts for more info.
`audio_sources` Optional	post 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`.
`audio_sources_excluded` Optional	post 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.
`trim` Optional	post boolean Not 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 for more info.
`format` Optional	post ienum:format 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.
`resolution` Optional	post string Not 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 for more info.
`status_callback` Optional	post url 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.
`status_callback_method` Optional	post http_method Not PII The HTTP method we should use to call `status_callback`. Can be: `POST` or `GET` and the default is `POST`.

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.

HTTP DELETE

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

Resource URI

/v1/CompositionHooks

HTTP POST

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

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

Parameters in REST API format
`friendly_name` Required	post string Not PII 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.
`enabled` Optional	post boolean Not 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.
`video_layout` Optional	post object PII MTL: 30 DAYS An object that describes the video layout of the composition hook in terms of regions. See Specifying Video Layouts for more info.
`audio_sources` Optional	post 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`.
`audio_sources_excluded` Optional	post 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.
`resolution` Optional	post string Not 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 for more info.
`format` Optional	post ienum:format 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.
`status_callback` Optional	post url 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.
`status_callback_method` Optional	post http_method Not PII The HTTP method we should use to call `status_callback`. Can be: `POST` or `GET` and the default is `POST`.
`trim` Optional	post boolean Not 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 for more info.

Managing Video Layouts

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.

HTTP GET

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

Supported GET parameters

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

Parameters in REST API format
`enabled` Optional	get boolean Not PII Read only CompositionHook resources with an `enabled` value that matches this parameter.
`date_created_after` Optional	get date_time<iso8601> Not PII Read only CompositionHook resources created on or after this ISO 8601 datetime with time zone.
`date_created_before` Optional	get date_time<iso8601> Not PII Read only CompositionHook resources created before this ISO 8601 datetime with time zone.
`friendly_name` Optional	get string Not PII 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.

HTTP DELETE

Not Supported

Examples

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

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:

Loading Code Sample...

Example JSON response

Create a Composition Hook mixing all room audio tracks

Creating a simple video mixing Composition Hook

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:

Loading Code Sample...

Example JSON response

Create a Composition Hook composing rooms in a grid

Creating a video mixing Composition Hook with complex layout

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)

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Create a Composition Hook mixing all room audio tracks

Create a Composition Hook composing rooms in a grid

Create a Composition Hook with complex video layout

Fetch a Composition Hook resource

List all enabled Composition Hooks

Update a Composition Hook to disable it

Delete a Composition Hook

Need some help?

Thank you for your feedback!

Thanks for your feedback!