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
|
The SID of the Account that created the MediaProcessor resource. |
sid
|
The unique string generated to identify the MediaProcessor resource. |
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. |
extension
|
The Media Extension name or URL. Ex: |
extension_context
|
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
|
The status of the MediaProcessor. Can be: |
url
|
The absolute URL of the resource. |
ended_reason
|
The reason why a MediaProcessor ended. When a MediaProcessor is in progress, will be |
status_callback
|
The URL to which Twilio will send asynchronous webhook requests for every MediaProcessor event. See Status Callbacks for details. |
status_callback_method
|
The HTTP method Twilio should use to call the |
max_duration
|
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
|
The Media Extension name or URL. Ex: |
extension_context
Required
|
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
|
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
|
The URL to which Twilio will send asynchronous webhook requests for every MediaProcessor event. See Status Callbacks for details. |
status_callback_method
Optional
|
The HTTP method Twilio should use to call the |
max_duration
Optional
|
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).
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).
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.
Fetch a MediaProcessor
URL
# HTTP GET
https://media.twilio.com/v1/MediaProcessors/{MediaProcessorSID}
Parameters
Parameters in REST API format | |
---|---|
sid
Path
|
The SID of the MediaProcessor resource to fetch. |
Example: Fetch a MediaProcessor
Read multiple MediaProcessor resources
URL
# HTTP GET
https://media.twilio.com/v1/MediaProcessors
Parameters
Parameters in REST API format | |
---|---|
order
Optional
|
The sort order of the list by |
status
Optional
|
Status to filter by, with possible values |
Example: Read a list of MediaProcessors
Example: Retrieve all started MediaProcessors
Filter by status=started
to retrieve a list of all MediaProcessors that are started.
Update a MediaProcessor
URL
# HTTP POST
https://media.twilio.com/v1/MediaProcessors/{MediaProcessorSID}
Parameters
Parameters in REST API format | |
---|---|
sid
Path
|
The SID of the MediaProcessor resource to update. |
status
Required
|
The status of the MediaProcessor. Can be |
Example: Stop a MediaProcessor
To stop a MediaProcessor, set its status to ended
.
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.