MediaProcessors

The MediaProcessor resource provides the ability to capture content from a web application with a Twilio Media Extension to create a livestream. A MediaProcessor contains a browser runtime and a media encoder. A Twilio Media Extension is a JavaScript application that runs on a MediaProcessor and performs certain actions, such as joining a Twilio Video Room and processing the audio and video data.

Twilio hosts two Media Extensions currently: a Video Composer and an Audio Mixer. When creating a MediaProcessor, you will specify the Media Extension that you would like to use.

By default, a MediaProcessor will terminate after five minutes, which ends the livestream. You can update the MediaProcessor's maximum duration when creating the resource.

API Base URL

All URLs in the reference documentation use the following base URL:

https://media.twilio.com/v1

MediaProcessor properties

Resource Properties in REST API format
`account_sid`	sid<AC> Not PII The SID of the Account that created the MediaProcessor resource.
`sid`	sid<ZX> Not PII The unique string generated to identify the MediaProcessor resource.
`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.
`extension`	string PII MTL: 30 DAYS The Media Extension name or URL. Ex: `video-composer-v2`
`extension_context`	string Not PII The context of the Media Extension, represented as a JSON dictionary. See the documentation for the specific Media Extension you are using for more information about the context to send.
`status`	enum:status Not PII The status of the MediaProcessor. Can be: `started`, `ended` or `failed`.
`url`	url Not PII The absolute URL of the resource.
`ended_reason`	string Not PII The reason why a MediaProcessor ended. When a MediaProcessor is in progress, will be `null`. When a MediaProcessor is completed, can be `ended-via-api`, `max-duration-exceeded`, `error-loading-extension`, `error-streaming-media` or `internal-service-error`. See ended reasons for more details.
`status_callback`	url Not PII The URL to which Twilio will send asynchronous webhook requests for every MediaProcessor event. See Status Callbacks for details.
`status_callback_method`	http_method Not PII The HTTP method Twilio should use to call the `status_callback` URL. Can be `POST` or `GET` and the default is `POST`.
`max_duration`	integer Not PII The maximum time, in seconds, that the MediaProcessor can run before automatically ends. The default value is 300 seconds, and the maximum value is 90000 seconds. Once this maximum duration is reached, Twilio will end the MediaProcessor, regardless of whether media is still streaming.

MediaProcessor ended reason values

EndedReason	Status	Description
ended-via-api	ENDED	The MediaProcessor has been ended due to a REST API request.
max-duration-exceeded	ENDED	The MediaProcessor has reached its max duration and it has been ended.
error-loading-extension	FAILED	The MediaProcessor could not load the provided Media Extension.
error-streaming-media	FAILED	The MediaProcessor could not stream the media to one or more outputs.
internal-service-error	FAILED	The MediaProcessor incurred an unexpected failure.

Create a MediaProcessor

URL

# HTTP POST
https://media.twilio.com/v1/MediaProcessors

Parameters

Parameters in REST API format
`extension` Required	post string PII MTL: 30 DAYS The Media Extension name or URL. Ex: `video-composer-v2`
`extension_context` Required	post string Not PII The context of the Media Extension, represented as a JSON dictionary. See the documentation for the specific Media Extension you are using for more information about the context to send.
`extension_environment` Optional	post object Not PII User-defined environment variables for the Media Extension, represented as a JSON dictionary of key/value strings. See the documentation for the specific Media Extension you are using for more information about whether you need to provide this.
`status_callback` Optional	post url Not PII The URL to which Twilio will send asynchronous webhook requests for every MediaProcessor event. See Status Callbacks for details.
`status_callback_method` Optional	post http_method Not PII The HTTP method Twilio should use to call the `status_callback` URL. Can be `POST` or `GET` and the default is `POST`.
`max_duration` Optional	post integer Not PII The maximum time, in seconds, that the MediaProcessor can run before automatically ends. The default value is 300 seconds, and the maximum value is 90000 seconds. Once this maximum duration is reached, Twilio will end the MediaProcessor, regardless of whether media is still streaming.

Example: Create a MediaProcessor

This sample creates a MediaProcessor that will run a Video Composer and automatically terminate after five minutes (the default maximum duration).

Loading Code Sample...

Example JSON response

Create a MediaProcessor

Example: Create a MediaProcessor with a maximum duration of one hour

This example creates a MediaProcessor that will run a Video Composer and automatically terminate after an hour.

The longest allowed duration for the MediaProcessor's maximum duration is 90000 seconds (25 hours).

Loading Code Sample...

Example JSON response

Create a MediaProcessor with a 3600 second maximum duration

Example: Create a MediaProcessor and provide an Extension Environment parameter

The Twilio Live Video Composer accepts an Extension Environment parameter. The extension environment injects environment variables into the JavaScript application that the Video Composer runs.

You can modify certain aspects of the livestream's layout using the extension environment parameter. Currently, the only option for modifying the livestream's layout is to hide the participant identity overlay on each participant's video in the stream.

Loading Code Sample...

Example JSON response

Create a MediaProcessor and provide an Extension Environment parameter

Fetch a MediaProcessor

URL

# HTTP GET
https://media.twilio.com/v1/MediaProcessors/{MediaProcessorSID}

Parameters

Parameters in REST API format
`sid` Path	get sid<ZX> Not PII The SID of the MediaProcessor resource to fetch.

Parameters in REST API format

sid

Path

get sid<ZX> Not PII

The SID of the MediaProcessor resource to fetch.

Example: Fetch a MediaProcessor

Loading Code Sample...

Example JSON response

Retrieve a single MediaProcessor

Read multiple MediaProcessor resources

URL

# HTTP GET
https://media.twilio.com/v1/MediaProcessors

Parameters

Parameters in REST API format
`order` Optional	get ienum:order Not PII The sort order of the list by `date_created`. Can be: `asc` (ascending) or `desc` (descending) with `desc` as the default.
`status` Optional	get ienum:status Not PII Status to filter by, with possible values `started`, `ended` or `failed`.

Parameters in REST API format

order

Optional

get ienum:order Not PII

The sort order of the list by date_created. Can be: asc (ascending) or desc (descending) with desc as the default.

status

Optional

get ienum:status Not PII

Status to filter by, with possible values started, ended or failed.

Example: Read a list of MediaProcessors

Loading Code Sample...

Example JSON response

Retrieve a list of MediaProcessors

Example: Retrieve all started MediaProcessors

Filter by status=started to retrieve a list of all MediaProcessors that are started.

Loading Code Sample...

Example JSON response

Retrieve all started MediaProcessors

Update a MediaProcessor

URL

# HTTP POST
https://media.twilio.com/v1/MediaProcessors/{MediaProcessorSID}

Parameters

Parameters in REST API format
`sid` Path	post sid<ZX> Not PII The SID of the MediaProcessor resource to update.
`status` Required	post ienum:update_status Not PII The status of the MediaProcessor. Can be `ended`.

Parameters in REST API format

sid

Path

post sid<ZX> Not PII

The SID of the MediaProcessor resource to update.

status

Required

post ienum:update_status Not PII

The status of the MediaProcessor. Can be ended.

Example: Stop a MediaProcessor

To stop a MediaProcessor, set its status to ended.

Loading Code Sample...

Example JSON response

Stop a MediaProcessor

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 MediaProcessor

Create a MediaProcessor with a 3600 second maximum duration

Create a MediaProcessor and provide an Extension Environment parameter

Retrieve a single MediaProcessor

Retrieve a list of MediaProcessors

Retrieve all started MediaProcessors

Stop a MediaProcessor

Need some help?

Thank you for your feedback!

Thanks for your feedback!