Menu

Expand
Rate this page:

PlayerStreamers

The PlayerStreamer resource provides the ability to send a livestream (the output of a Media Extension running on a MediaProcessor) to a JavaScript, iOS, or Android Player SDK.

API Base URL

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

https://media.twilio.com/v1/

PlayerStreamer properties

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created the PlayerStreamer 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.

video
boolean Not PII

Specifies whether the PlayerStreamer is configured to stream video. Defaults to true.

links
uri_map Not PII

The URLs of related resources.

sid
sid<VJ> Not PII

The unique string generated to identify the PlayerStreamer resource.

status
enum:status Not PII

The status of the PlayerStreamer. Can be: created, started, ended, or failed. See status for more information.

url
url Not PII

The absolute URL of the resource.

status_callback
url Not PII

The URL to which Twilio will send asynchronous webhook requests for every PlayerStreamer event. See Status Callbacks for more 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.

ended_reason
enum:ended_reason Not PII

The reason why a PlayerStreamer ended. When a PlayerStreamer is in progress, will be null. When a PlayerStreamer is completed, can be ended-via-api, max-duration-exceeded, stream-disconnected-by-source or unexpected-failure. See ended reasons for more details.

max_duration
integer Not PII

The maximum time, in seconds, that the PlayerStreamer is active (created or started) 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 PlayerStreamer, regardless of whether media is still streaming.

Ended Reason

EndedReason Status Description
ended-via-api ENDED The PlayerStreamer has been ended due to a REST API request.
max-duration-exceeded ENDED ThePlayerStreamer has reached its max duration and it has been ended.
stream-disconnected-by-source ENDED The PlayerStreamer is not receiving media anymore.
unexpected-failure FAILED The PlayerStreamer incurred an unexpected failure.

Max Duration

We have been advising Twilio Live customers to gracefully terminate all the resources associated to a finished live stream. And to ensure a correct usage of these resources, PlayerStreamers will be the automatically terminated after a fixed period of time. When a new PlayerStreamer is created it will have a default expiry period of 300 seconds, a value which you can overwrite based on your expected duration of the live stream.

Status

When you first create a PlayerStreamer via an HTTP POST request, it will have the status created. The PlayerStreamer will automatically transition into the started state once you create a MediaProcessor that connects to this PlayerStreamer; when you create a MediaProcessor, it immediately starts sending livestream data from the specified Twilio Video room using whichever Media Extension you specified when creating it.

The PlayerStreamer will then transition to ended for one of the reasons documented in the list of Ended Reasons. The transition to ended will happen automatically if the MediaProcessor stops sending data, or you can end the PlayerStreamer manually via the API.

Twilio will send you updates about any status changes if you provide a StatusCallback URL where Twilio can send the status change events.

Create a PlayerStreamer

URL

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

Parameters

Parameters in REST API format
video
Optional
post boolean Not PII

Specifies whether the PlayerStreamer is configured to stream video. Defaults to true.

status_callback
Optional
post url Not PII

The URL to which Twilio will send asynchronous webhook requests for every PlayerStreamer event. See Status Callbacks for more 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 PlayerStreamer is active (created or started) 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 PlayerStreamer, regardless of whether media is still streaming.

Example: Create a PlayerStreamer

        
        
        

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

        This example creates a PlayerStreamer that will automatically terminate after 1 hour instead of the default duration of 300 seconds (5 minutes).

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

              
              
              

              Example: Create a PlayerStreamer that is not configured for video

                    
                    
                    

                    Fetch a PlayerStreamer resource

                    URL

                    # HTTP GET
                    https://media.twilio.com/v1/PlayerStreamers/{PlayerStreamerSID}

                    Parameters

                    Parameters in REST API format
                    sid
                    Path
                    get sid<VJ> Not PII

                    The SID of the PlayerStreamer resource to fetch.

                    Example: Retrieve a PlayerStreamer

                          
                          
                          

                          Read multiple PlayerStreamer resources

                          URL

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

                          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 created, started, ended, or failed.

                          Example: Read a list of PlayerStreamers

                                
                                
                                

                                Example: Read a list of started PlayerStreamers

                                Filter by status=started to retrieve only started PlayerStreamers.

                                      
                                      
                                      

                                      Update a PlayerStreamer

                                      URL

                                      # HTTP POST
                                      https://media.twilio.com/v1/PlayerStreamers/{PlayerStreamerSID}

                                      Parameters

                                      Parameters in REST API format
                                      sid
                                      Path
                                      post sid<VJ> Not PII

                                      The SID of the PlayerStreamer resource to update.

                                      status
                                      Required
                                      post ienum:update_status Not PII

                                      The status the PlayerStreamer should be transitioned to. Can be: ended.

                                      Example: End a PlayerStreamer

                                      To stop a PlayerStreamer, set its status to ended.

                                            
                                            
                                            

                                            Known Issues

                                            • The update request can potentially return a 409 Conflict HTTP response. This happens when the PlayerStreamer is transitioned automatically to ended (see the Status section). No retries are required from your application.
                                            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.

                                                  
                                                  
                                                  

                                                  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!

                                                  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