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:
HTTP
1PUT pcast/<applicationId>/stream/publish/uri/<type> HTTP/1.12Authorization: Bearer <edgeAuthToken>3Host: pcast.phenixrts.com4Accept: application/json5Content-Type: application/json67{8 "uri": "<uri>",9 "options": [<options>]10}
cURL
1curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/publish/uri/<type> \2-H "Authorization: Bearer <edgeAuthToken>" \3-H "Accept: application/json" \4-H "Content-Type: application/json" \5-X PUT \6-d '{7 "uri": "<uri>",8 "options": [<options>]9 }'
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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 51845{"status":"ok","streamId":"us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz","sharedSecret":"DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=","options":[]}```
cURL
1{2 "status": "ok",3 "streamId": "us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz",4 "sharedSecret": "DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=",5 "options": []6}
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:
HTTP
1GET /pcast/:tenancy/stream/replay/:type.m3u8?edgeAuthToken=<edgeAuthToken>&startTime=<startTime>&endTime=<endTime> HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json
cURL
1curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/replay/primary.m3u8?edgeAuthToken=<edgeAuthToken>&startTime=<startTime>&endTime=<endTime> \2-X GET \3-H "Accept: application/json" \4-H "Content-Type: application/json"
Request 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
1HTTP/1.1 200 OK2Content-Type: application/vnd.apple.mpegurl; charset=utf-83Content-Length: 4274#EXTM3U56#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=307xhd.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=8...
cURL
1#EXTM3U23#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=304xhd.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
Restreaming is currently in beta testing.
Phenix has tested restreaming to YouTube, Twitch, and Facebook. Please contact Phenix for guidance.
Phenix has tested restreaming to YouTube, Twitch, 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.
Publishing for Restreaming
When setting up publishing for restreaming, include the "streaming" capability.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).
HTTP
1PUT https://pcast.phenixrts.com/pcast/<applicationId>/stream/egress/uri/<protocol>2Authorization: Bearer <edgeAuthToken>3Host: pcast.phenixrts.com4Accept: application/json5Content-Type: application/json67{8 "uri":"<restreamUrl><restream-stream-key>"9}
cURL
1curl --connect-timeout 3 \2 -H "Authorization: Bearer <edgeAuthToken>" \3 -H "Accept: application/json" \4 -H "Content-Type: application/json" \5 -X PUT --data '{6 "uri":"<restreamUrl><restream-stream-key>"7 }' \8 https://pcast.phenixrts.com/pcast/<applicationId>/stream/egress/uri/<protocol>
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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 51845{"status":"ok","streamId":"us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz","sharedSecret":"DIGEST:eyJ...","options":[]}```
cURL
1{2 "status": "ok",3 "streamId": "us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz",4 "sharedSecret": "DIGEST:eyJ...",5 "options": []6}
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. |
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 |
v2023-09-12T20:09:36.000Z