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

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

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

        
        
        

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

              
              
              

              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

                    
                    
                    

                    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

                          
                          
                          

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

                                      
                                      
                                      
                                      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 Community Forums or browsing the Twilio tag on Stack Overflow.

                                            
                                            
                                            

                                            Thank you for your feedback!

                                            We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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

                                            Thanks for your feedback!

                                            Refer us and get $10 in 3 simple steps!

                                            Step 1

                                            Get link

                                            Get a free personal referral link here

                                            Step 2

                                            Give $10

                                            Your user signs up and upgrade using link

                                            Step 3

                                            Get $10

                                            1,250 free SMSes
                                            OR 1,000 free voice mins
                                            OR 12,000 chats
                                            OR more