Page Content
Transformation API
APIs for the composition and transcoding of streams
Creating a Composition
This API allows for composition of a single stream from multiple streams
Creating a Composition Request
Send a POST request to /pcast/composition endpoint as shown:
POST /pcast/composition HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 524
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"composition": {
"type": "<compositionType>",
"streams": [
{
"streamId": "<streamId1>",
"offset": {
"anchor": "TopLeft",
"x": 0,
"y": 0
},
"width": 640,
"height": 480
},
{
"streamId": "<streamId2>"
}
],
"capabilities": ["multi-bitrate"],
"tags": ["<tag1>", "<tag2>"]
}
}The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
| Field | Description |
|---|---|
| composition (required) | See Composition object below |
| tags (optional) | Tags for the Composition stream |
| credentials (optional) | The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body. |
Composition Object
| Field | Description |
|---|---|
| type (required) | Type of composition that need to be applied. See Composition types below. |
| streams (required) | Array of streams that need to be composed. See Stream Object below. |
| capabilities | See Composition Capabilities below |
Composition Types
| Field | Description |
|---|---|
| PictureInPicture | Main stream is displayed on the full screen and other streams are displayed in inset windows. The main stream is the first stream of all streams. |
Stream Object
| Field | Description |
|---|---|
| streamId (required) | The stream ID of the the input. |
| offset (optional) | The offset of the input video relative to the composition canvas. See Offset Object below. |
| width (optional) | The width of the input on the composition canvas. |
| height (optional) | The height of the input on the composition canvas. |
Offset Object
| Field | Description |
|---|---|
| anchor (optional) | The anchor for the offset. See Anchor Object below. |
| x (optional) | The horizontal offset relative to the anchor. |
| y (optional) | The vertical offset relative to the anchor. |
Anchor Object
| Value | Description |
|---|---|
| TopLeft | Anchor relative to top left corner. |
| TopRight | Anchor relative to top right corner. |
| BottomLeft | Anchor relative to bottom left corner. |
| BottomRight | Anchor relative to bottom right corner. |
| Center | Anchor relative to the center. |
Composition Capabilities
| Value | Description |
|---|---|
| prefer-h264 | Output H.264 stream if possible |
| prefer-vp8 | Output VP8 stream if possible |
| multi-bitrate | Multi bitrate stream |
| multi-bitrate-codec=vp8 | Multi bitrate VP8 stream |
| multi-bitrate-codec=h264 | Multi bitrate H.264 stream |
| uld | Output Ultra low definition - 80kbps stream |
| vld | Output Very low definition - 350kbps stream |
| ld | Output Low definition - 520kbps stream |
| sd | Output Standard definition - 830kbps - default stream |
| hd | Output High definition - 1600kbps stream |
| fhd | Output Full high definition - 3000kbps stream |
| xhd | Output Extended high definition - 5500kbps stream |
Creating a Composition 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: 85
{"status":"ok","compositionId":"us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV"}Create Composition API Response fields
| Field | Description |
|---|---|
| status | See status codes below |
| compositionId | ID of the composed stream |
Create Composition API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Composition was 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. |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | 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.
Updating a Composition
This API allows for modifying a composition created above.
Updating a Composition Request
Send a PUT request to /pcast/composition endpoint as shown:
PUT /pcast/composition/<compositionId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 319
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"streams": [
{
"streamId": "<streamId1>",
"offset": {
"anchor": "TopLeft",
"x": 0,
"y": 0
},
"width": 640,
"height": 480
},
{
"streamId": "<streamId2>"
}
]
}The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
| Field | Description |
|---|---|
| compositionId (required) | The ID of the composition. |
| streams (required) | Array of streams that need to be composed. See Stream Object below. |
| credentials (optional) | The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body. |
Stream Object
| Field | Description |
|---|---|
| streamId (required) | The stream ID of the the input. |
| offset (optional) | The offset of the input video relative to the composition canvas. See Offset Object below. |
| width (optional) | The width of the input on the composition canvas. |
| height (optional) | The height of the input on the composition canvas. |
Offset Object
| Field | Description |
|---|---|
| anchor (optional) | The anchor for the offset. See Anchor Object below. |
| x (optional) | The horizontal offset relative to the anchor. |
| y (optional) | The vertical offset relative to the anchor. |
Anchor Object
| Value | Description |
|---|---|
| TopLeft | Anchor relative to top left corner. |
| TopRight | Anchor relative to top right corner. |
| BottomLeft | Anchor relative to bottom left corner. |
| BottomRight | Anchor relative to bottom right corner. |
| Center | Anchor relative to the center. |
Updating a Composition 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: 15
{"status":"ok"}Update Composition API Response fields
| Field | Description |
|---|---|
| status | See status codes below |
Update Composition API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Composition was successfully updated. |
| 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. |
| 404 Not Found | not-found | never | The composition stream does not exist. |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | 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.
Deleting a Composition
This API allows for deletion of a composition stream
Deleting a Composition Request
Send a DELETE request to /pcast/composition/<urlEncodedCompositionlId> endpoint as shown:
DELETE /pcast/composition/<urlEncodedCompositionId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 28
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"reason": "<reason>"
}Encoding
Composition ID may contain characters that are unsafe for URLs. Be sure to
encode the CompositionlId in the URL path. For example, the URL encoding of
us-central#us-central is us-central%23us-central
Request Fields
| Field | Description |
|---|---|
| reason (optional) | Reason for deleting the composition |
| credentials (optional) | The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body. |
Deleting a Composition 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: 15
{"status":"ok"}Delete Composition API Response fields
| Field | Description |
|---|---|
| status | See status codes below |
Delete Composition API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Composition was successfully deleted. |
| 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. |
| 404 Not Found | not-found | never | The composition stream does not exist. |
| 409 Conflict | already-deleted | never | The composition is already deleted. |
| 410 Gone | already-deleted | never | The stream has already ended. |
| 410 Gone | already-ended | never | The stream has already ended. |
| 410 Gone | resource-unavailable | never | The stream has already ended. |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | 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.
Start Transcoding
This API allows for transcoding an ongoing stream.
Start Transcoding Request
Send a POST request to /pcast/transcoding endpoint as shown:
POST /pcast/transcoding HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 210
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"transcoding": {
"type": "DASH",
"originStreamId": "<streamId>",
"onDemand": true,
"audioOnly": false,
"capabilities": ["<capability1>", "<capability2>"],
"quality": "hd",
"tags": ["<tag1>", "<tag2>"]
}
}Request Fields
| Field | Description |
|---|---|
| transcoding (required) | See Transcoding object below |
| credentials (optional) | The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body. |
Transcoding Object
| Field | Description |
|---|---|
| type (required) | Format the stream will be transcoded to. See Transcoding types below. |
| originStreamId (required) | ID of the Stream that will be transcoded |
| onDemand (optional) | Persist the transcoded live stream for on-demand playback. The stream features the same capabilities as the adaptive multi-bit rate live stream and can be accessed time delayed. |
| audioOnly (optional) | Transcode audio only stream. This is mutually exclusive with videoOnly. |
| videoOnly (optional) | Transcode video only stream. This is mutually exclusive with audioOnly. |
| capabilities (optional) | Capabilities for the Transcoded stream |
| quality (optional) | See Transcoding qualities below |
| tags (optional) | Tags for the Transcoded stream |
Transcoding Types
| Field | Description |
|---|---|
| DASH | Dynamic Adaptive Streaming over HTTP |
| HLS | HTTP Live Streaming |
Transcoding Qualities
| Field | Description |
|---|---|
| uld | Output Ultra low definition - 80kbps stream |
| vld | Output Very low definition - 350kbps stream |
| ld | Output Low definition - 520kbps stream |
| sd | Output Standard definition - 830kbps - default stream |
| hd | Output High definition - 1600kbps stream |
| fhd | Output Full high definition - 3000kbps stream |
| xhd | Output Extended high definition - 5500kbps stream |
Start Transcoding 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: 85
{"status":"ok","transcodingId":"us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8"}Start Transcoding API Response fields
| Field | Description |
|---|---|
| status | See status codes below |
| transcodingId | ID of the transcoded stream |
Start Transcoding API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Transcoding was 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. |
| 409 Conflict | already-exists | never | |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | 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.
Stop Transcoding
This API allows for stopping the transcoding of a stream.
Stop Transcoding Request
Send a DELETE request to /pcast/transcoding/<urlEncodedTranscodingId> endpoint as shown:
DELETE /pcast/transcoding/<urlEncodedTranscodingId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 28
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"reason": "<reason>"
}Encoding
Transcoding ID may contain characters that are unsafe for URLs. Be sure to
encode the TranscodingId in the URL path. For example, the URL encoding of
us-central#us-central is us-central%23us-central
Request Fields
| Field | Description |
|---|---|
| reason (optional) | Reason for deleting the transcoded stream |
| credentials (optional) | The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body. |
Stop Transcoding 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: 15
{"status":"ok"}Stop Transcoding API Response fields
| Field | Description |
|---|---|
| status | See status codes below |
Delete Transcoding API Status Codes
| HTTP | Status | Retry | Description |
|---|---|---|---|
| 200 OK | ok | never | Transcoding was successfully deleted. |
| 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. |
| 409 Conflict | already-deleted | never | The Transcoding is already deleted. |
| 4XX | varies | never | Indicates an issue with the request. |
| 503 Service Unavailable | capacity | once | 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.
v2024-11-19T17:31:40.000Z