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
|
The SID of the Account that created the PlayerStreamer 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. |
video
|
Specifies whether the PlayerStreamer is configured to stream video. Defaults to |
links
|
The URLs of related resources. |
sid
|
The unique string generated to identify the PlayerStreamer resource. |
status
|
The status of the PlayerStreamer. Can be: |
url
|
The absolute URL of the resource. |
status_callback
|
The URL to which Twilio will send asynchronous webhook requests for every PlayerStreamer event. See Status Callbacks for more details. |
status_callback_method
|
The HTTP method Twilio should use to call the |
ended_reason
|
The reason why a PlayerStreamer ended. When a PlayerStreamer is in progress, will be |
max_duration
|
The maximum time, in seconds, that the PlayerStreamer is active ( |
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
|
Specifies whether the PlayerStreamer is configured to stream video. Defaults to |
status_callback
Optional
|
The URL to which Twilio will send asynchronous webhook requests for every PlayerStreamer event. See Status Callbacks for more details. |
status_callback_method
Optional
|
The HTTP method Twilio should use to call the |
max_duration
Optional
|
The maximum time, in seconds, that the PlayerStreamer is active ( |
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
|
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
|
The sort order of the list by |
status
Optional
|
Status to filter by, with possible values |
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
|
The SID of the PlayerStreamer resource to update. |
status
Required
|
The status the PlayerStreamer should be transitioned to. Can be: |
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 toended
(see the Status section). No retries are required from your application.
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.