Menu

Expand
Rate this page:

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

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...
        
        

        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...
              
              

              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...
                    
                    

                    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.

                    Example: Fetch a MediaProcessor

                    Loading Code Sample...
                          
                          

                          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.

                          Example: Read a list of MediaProcessors

                          Loading Code Sample...
                                
                                

                                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...
                                      
                                      

                                      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.

                                      Example: Stop a MediaProcessor

                                      To stop a MediaProcessor, set its status to ended.

                                      Loading Code Sample...
                                            
                                            

                                            Stop a MediaProcessor

                                            Rate this page:

                                            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.

                                            Loading Code Sample...
                                                  
                                                  
                                                  

                                                  Thank you for your feedback!

                                                  Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                  Sending your feedback...
                                                  🎉 Thank you for your feedback!
                                                  Something went wrong. Please try again.

                                                  Thanks for your feedback!

                                                  thanks-feedback-gif