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.

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

Loading Code Sample...

Example JSON response

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

Loading Code Sample...

Example JSON response

Create a PlayerStreamer with a 3600 second maximum duration

Example: Create a PlayerStreamer that is not configured for video

Loading Code Sample...

Example JSON response

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.

Parameters in REST API format

sid

Path

get sid<VJ> Not PII

The SID of the PlayerStreamer resource to fetch.

Example: Retrieve a PlayerStreamer

Loading Code Sample...

Example JSON response

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

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

Loading Code Sample...

Example JSON response

Read a list of PlayerStreamers

Example: Read a list of started PlayerStreamers

Filter by status=started to retrieve only started PlayerStreamers.

Loading Code Sample...

Example JSON response

Read a list of 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`.

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.

Loading Code Sample...

Example JSON response

End a PlayerStreamer

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.

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.

Create a PlayerStreamer

Create a PlayerStreamer with a 3600 second maximum duration

Create a PlayerStreamer that is not configured for video

Retrieve a PlayerStreamer

Read a list of PlayerStreamers

Read a list of started PlayerStreamers

End a PlayerStreamer

Need some help?

Thank you for your feedback!

Thanks for your feedback!