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
Contents
- 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
|
The SID of the Account that created the CompositionHook resource. |
friendly_name
|
The string that you assigned to describe the resource. Can be up to 100 characters long and must be unique within the account. |
enabled
|
Whether the CompositionHook is active. When |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
sid
|
The unique string that we created to identify the CompositionHook resource. |
audio_sources
|
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_excluded
|
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 |
video_layout
|
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
|
The dimensions of the video image in pixels expressed as columns (width) and rows (height). The string's format is |
trim
|
Whether intervals with no media are clipped, as specified in the POST request that created the CompositionHook resource. Compositions with |
format
|
The container format of the media files used by the compositions created by the composition hook. If |
status_callback
|
The URL we call using the |
status_callback_method
|
The HTTP method we should use to call |
url
|
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
|
The SID of the CompositionHook resource to update. |
friendly_name
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. |
enabled
Optional
|
Whether the composition hook is active. When |
video_layout
Optional
|
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
|
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_excluded
Optional
|
An array of track names to exclude. A composition triggered by the composition hook includes all audio sources specified in |
trim
Optional
|
Whether to clip the intervals where there is no active media in the compositions triggered by the composition hook. The default is |
format
Optional
|
The container format of the media files used by the compositions created by the composition hook. Can be: |
resolution
Optional
|
A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to
Typical values are:
Note that the |
status_callback
Optional
|
The URL we should call using the |
status_callback_method
Optional
|
The HTTP method we should use to call |
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
|
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
|
Whether the composition hook is active. When |
video_layout
Optional
|
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
|
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_excluded
Optional
|
An array of track names to exclude. A composition triggered by the composition hook includes all audio sources specified in |
resolution
Optional
|
A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to
Typical values are:
Note that the |
format
Optional
|
The container format of the media files used by the compositions created by the composition hook. Can be: |
status_callback
Optional
|
The URL we should call using the |
status_callback_method
Optional
|
The HTTP method we should use to call |
trim
Optional
|
Whether to clip the intervals where there is no active media in the Compositions triggered by the composition hook. The default is |
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
|
Read only CompositionHook resources with an |
date_created_after
Optional
|
Read only CompositionHook resources created on or after this ISO 8601 datetime with time zone. |
date_created_before
Optional
|
Read only CompositionHook resources created before this ISO 8601 datetime with time zone. |
friendly_name
Optional
|
Read only CompositionHook resources with friendly names that match this string. The match is not case sensitive and can include asterisk |
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:
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:
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 namedscreen
. The presenter audio track, in turn, has the namepresenter-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:
Getting a Composition Hook
For executing this example you need:
- Your application credentials (
SKXXXX:your_api_key_secret
) - The Composition Hook Sid (
HKXXXX
)
Listing all enabled Composition Hooks
For executing this example you need:
- Your application credentials (
SKXXXX:your_api_key_secret
)
Updating a Composition Hook
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.
Deleting a Composition Hook
For executing this example you need:
- Your application credentials (
SKXXXX:your_api_key_secret
) - The Composition Hook Sid (
HKXXXX
)
Known Problems and Limitations
There are no known problems.
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.