Page Content
Stream API
APIs for streams let you publish, subscribe, destroy and manage streams. In addition, the APIs let you create and fetch replays.
Publishing a URI
This API allows to publish a stream from a URI.
Publishing a URI Request
Send a PUT request to the pcast/:tenancy/stream/publish/uri/:type endpoint as shown:
PUT pcast/<applicationId>/stream/publish/uri/<type> HTTP/1.1
Authorization: Bearer <edgeAuthToken>
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
{
"uri": "<uri>",
"options": [<options>]
}Request Headers
| Header | Description |
|---|---|
| Authorization (required) | Use Bearer authentication with an EdgeAuthToken. The token must include the publish-uri capability. |
Request URI
| Component | Description |
|---|---|
| applicationId (required) | The Application ID that the request belongs to |
| type (required) | The remote URI type, must be one of: mp4, m3u8, udp, srt, rtsp. |
Request Fields
| Field | Description |
|---|---|
| uri (required) | The URI to publish such as srt://103.19.109.140:4201 |
| options (optional) | For future use |
Publishing a URI Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 518
{"status":"ok","streamId":"us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz","sharedSecret":"DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=","options":[]}```Publish URI API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Stream has been successfully published. |
| 400 Bad Request | varies | never | Indicates an issue with the request. |
| 401 Unauthorized | unauthorized | never | The streaming platform was not able to authorize the provided credentials. |
| 402 Unauthorized | geo-restricted | never | The access to the content is geo-restricted. |
| 403 Unauthorized | geo-blocked | never | The access to the content is geo-blocked. |
| 409 Conflict | conflicting-capability | never | Ingest capabilities are conflicting. Only one must be specified at a time. |
| 415 Unsupported Media Type | invalid-source-uri | never | The URI to publish is not a valid URI. |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | The system is temporarily overloaded. Please try again later. |
| 504 Gateway Timeout | rate-limited | once immediately, then exponential backoff | The system is temporarily overloaded. Please try again later. |
| 5XX | varies | once immediately, then exponential backoff | A transient server error. |
Error Responses
Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Publish URI API Response fields
| Field | Description |
|---|---|
| status | See Status Codes |
| streamId | The stream ID of the ingest stream |
| sharedSecret | The shared secret used in follow on operations on the stream |
| options | For future use |
Fetching a Replay Manifest
This API allows to create and fetch replay manifests.
Fetching a Replay Manifest Request
Send a Get request to the /pcast/:tenancy/stream/replay/:type.m3u8 endpoint as shown:
GET /pcast/:tenancy/stream/replay/:type.m3u8?edgeAuthToken=<edgeAuthToken>&startTime=<startTime>&endTime=<endTime> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/jsonRequest URI
| Component | Description |
|---|---|
| applicationId (required) | The Application ID that the request belongs to. |
| type (required) | The manifest type such as primary.m3u8 for for primary manifest or xhd.m3u8 for quality manifest. |
Request Parameters
| Field | Description |
|---|---|
| edgeAuthToken (required) | EdgeAuthToken used to connect and authenticate to the platform and subscribe to a stream |
| startTime (required) | The date, formatted as 'yyyy-MM-dd'T'HH:mm:ss.SSS'Z'', from which replay should start |
| endTime (required) | The date, formatted as 'yyyy-MM-dd'T'HH:mm:ss.SSS'Z'', until which replay should last |
| apiVersion (optional) | The API version the message conforms to. Default to '0' |
| httpRoundTripTime (optional) | The round trip time |
Fetching a Replay Manifest Response
The platform will return a successful response that contains a playlist manifest. Or it will return error object with status on failure.
Success response example for primary manifest
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.mpegurl; charset=utf-8
Content-Length: 427
#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=30
xhd.m3u8?tenancy=test&edgeAuthToken=DIGEST%3AeyJhcHBsaWNhdGlvbklkIjoidGVzdCIsImRpZ2VzdCI6IjFuUU90ZnpKTmwwRUVLaHVBWGE4YWd0RGNNaGdGbEhTbksyRElsNTlTS0RTZ2xlUjc3c3NpTmRQcGdhMnZYVEhuSEJCdWIwQmdYRTQ2a3ZvbmNBcmFBPT0iLCJ0b2tlbiI6IntcImV4cGlyZXNcIjoxOTQ0MjE2MDAwMDAwLFwiY2FwYWJpbGl0aWVzXCI6W1wicmVwbGF5XCJdLFwib3JpZ2luU3RyZWFtSWRcIjpcImxvY2FsI3N0YW5kYWxvbmUuVFpkcnkwdjcuMjAyMTA5MTQuUFN5V1E2dk1cIixcInJlcXVpcmVkVGFnXCI6XCJyb29tSWQ6bG9jYWwjdGVzdCN0ZXN0Q2hhbm5lbC40UjBsVHU5Y1o3NjNcIn0ifQ%3D%3D&startTime=Tue+Sep+14+2021+08%3A05%3A52+GMT%2B0000&endTime=Tue+Sep+14+2021+08%3A06%3A02+GMT%2B0000&options=
...
Replay Manifest API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Channel has been successfully created. |
| 400 Bad Request | varies | never | Indicates an issue with the request. |
| 401 Unauthorized | unauthorized | never | The streaming platform was not able to authorize the provided credentials. |
| 402 Unauthorized | geo-restricted | never | The access to the content is geo-restricted. |
| 403 Unauthorized | geo-blocked | never | The access to the content is geo-blocked. |
| 408 Request Timeout | request-timeout | once immediately, then exponential backoff | Request timed out likely due to temporary resource or network conditions. Please try again. |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | The system is temporarily overloaded. Please try again later. |
| 504 Gateway Timeout | rate-limited | once immediately, then exponential backoff | The system is temporarily overloaded. Please try again later. |
| 5XX | varies | once immediately, then exponential backoff | A transient server error. |
Restreaming
Beta Notice
Restreaming is currently in beta testing.
Phenix has tested restreaming to YouTube, Twitch, Instagram, and Facebook. Please contact Phenix for guidance.
To restream or relay streams to endpoints other than end clients (e.g., to YouTube Live), set up publishing and output streams as detailed below.
Restreaming Modes
Phenix supports two modes of egress for restreaming content published to the Phenix platform (referred to below as the "published stream").
webm-egress
This is the default restreaming mode.
When using this mode, the published stream must have the streaming capability.
mpegts-egress
This is the low-latency mode.
When using this mode, the published stream must have the multi-bitrate, multi-bitrate-contribution,
or prefer-h264 capability; but the streaming capability is not required to enable restreaming.
Restreaming Capabilities
For restreaming, the egress capability is always required in the edgeAuth token.
-
If using default (webm-egress) mode, you can optionally include
webm-egresscapability in the edgeAuth token. -
If using low-latency egress, you must also include the
mpegts-egresscapability in the edgeAuth token.
Capability requirements based on egress mode are summarized in the table below.
| Restreaming Mode | Capabilities Required in Publish Token | Restream Token Capabilities |
|---|---|---|
| Default | streaming | egress (required), webm-egress (optional) |
| Low-Latency | multi-bitrate, multi-bitrate-contribution, or prefer-h264 capability | egress (required), mpegts-egress (required) |
Restreaming Request
The token for restreaming must have the "egress" capability and a type of "stream"
(i.e., for_streaming_only or forStreamingOnly, depending on the EdgeAuth library being used).
PUT https://pcast.phenixrts.com/pcast/<applicationId>/stream/egress/uri/<protocol>
Authorization: Bearer <edgeAuthToken>
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
{
"uri":"<restreamUrl><restream-stream-key>"
}Request Headers
| Component | Description |
|---|---|
| Authorization | A "stream" type token with the "egress" capability. |
Request URI
| Component | Description |
|---|---|
| applicationId (required) | The Application ID that the request belongs to. |
| protocol (required) | The protocol to be used for the restreaming. Currently only "rtmp" is supported. |
Request Parameters
| Field | Description |
|---|---|
| data (required) | The scheme and URL as well as the stream key to which you are restreaming. For example, "rtmp://a.rtmp.youtube.com/live2/abcd-eftj-234h-jwed". |
Restreaming Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 518
{"status":"ok","streamId":"us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz","sharedSecret":"DIGEST:eyJ...","options":[]}```{
"status": "ok",
"streamId": "us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz",
"sharedSecret": "DIGEST:eyJ...",
"options": []
}Restreaming API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Stream has been successfully published. |
| 400 Bad Request | varies | never | Indicates an issue with the request. |
| 401 Unauthorized | unauthorized | never | The streaming platform was not able to authorize the provided credentials. |
| 415 Requires Streaming | requires-streaming | never | The source stream is missing the "streaming" capability. |
Error Responses
Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Restreaming API Response fields
| Field | Description |
|---|---|
| status | See Status Codes |
| streamId | The stream ID of the ingest stream |
| sharedSecret | The shared secret used in follow on operations on the stream |
| options | For future use |
v2024-08-13T19:29:16.000Z