• Skip to Search
  • Skip to Content
  • Skip to Side Navigation
Getting StartedSDK ReferenceGlossary
  • Home
  • Getting Started
  • SDK Reference
  • Portal
  • How-To
  • Troubleshooting
  • FAQs
  • Reference
  • Glossary
REST API
Web SDK
Android SDK
iOS SDK
Unity SDK
React Native SDK
EdgeAuth SDK
  • Overview
  • Channel
  • Room
  • Stream
  • RTMP
  • Transformation
  • Reporting
  • Analytics
  • Notification
  • Live and On-Demand

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:

HTTP
1POST /pcast/composition HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 524
6Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
7
8{
9 "composition": {
10 "type": "<compositionType>",
11 "streams": [
12 {
13 "streamId": "<streamId1>",
14 "offset": {
15 "anchor": "TopLeft",
16 "x": 0,
17 "y": 0
18 },
19 "width": 640,
20 "height": 480
21 },
22 {
23 "streamId": "<streamId2>"
24 }
25 ],
26 "capabilities": ["multi-bitrate"],
27 "tags": ["<tag1>", "<tag2>"]
28 }
29}
cURL
1$ curl https://pcast.phenixrts.com/pcast/composition \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X POST \
6-d '{
7 "composition": {
8 "type": "<compositionType>",
9 "streams": [
10 {
11 "streamId": "<streamId1>",
12 "offset": {
13 "anchor": "TopLeft",
14 "x": 0,
15 "y": 0
16 },
17 "width": 640,
18 "height": 480
19 },
20 {
21 "streamId": "<streamId2>"
22 }
23 ],
24 "capabilities": ["multi-bitrate"],
25 "tags": ["<tag1>", "<tag2>"]
26 }
27 }'

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

FieldDescription
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

FieldDescription
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.
capabilitiesSee Composition Capabilities below

Composition Types

FieldDescription
PictureInPictureMain 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

FieldDescription
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

FieldDescription
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

ValueDescription
TopLeftAnchor relative to top left corner.
TopRightAnchor relative to top right corner.
BottomLeftAnchor relative to bottom left corner.
BottomRightAnchor relative to bottom right corner.
CenterAnchor relative to the center.

Composition Capabilities

ValueDescription
prefer-h264Output H.264 stream if possible
prefer-vp8Output VP8 stream if possible
multi-bitrateMulti bitrate stream
multi-bitrate-codec=vp8Multi bitrate VP8 stream
multi-bitrate-codec=h264Multi bitrate H.264 stream
uldOutput Ultra low definition - 80kbps stream
vldOutput Very low definition - 350kbps stream
ldOutput Low definition - 520kbps stream
sdOutput Standard definition - 830kbps - default stream
hdOutput High definition - 1600kbps stream
fhdOutput Full high definition - 3000kbps stream
xhdOutput Extended high definition - 5500kbps stream
uhdOutput Ultra high definition - 8500kbps 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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 85
4
5{"status":"ok","compositionId":"us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV"}
cURL
1{
2 "status":"ok",
3 "compositionId":"us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV"
4}

Create Composition API Response fields

FieldDescription
statusSee status codes below
compositionIdID of the composed stream

Create Composition API Status Codes

HTTPStatusRetryDescription
200 OKokneverComposition was successfully created.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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:

HTTP
1PUT /pcast/composition/<compositionId> HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 319
6Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
7
8{
9 "streams": [
10 {
11 "streamId": "<streamId1>",
12 "offset": {
13 "anchor": "TopLeft",
14 "x": 0,
15 "y": 0
16 },
17 "width": 640,
18 "height": 480
19 },
20 {
21 "streamId": "<streamId2>"
22 }
23 ]
24}
cURL
1$ curl https://pcast.phenixrts.com/pcast/composition/<compositionId> \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X PUT \
6-d '{
7 "streams": [
8 {
9 "streamId": "<streamId1>",
10 "offset": {
11 "anchor": "TopLeft",
12 "x": 0,
13 "y": 0
14 },
15 "width": 640,
16 "height": 480
17 },
18 {
19 "streamId": "<streamId2>"
20 }
21 ]
22 }'

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

FieldDescription
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

FieldDescription
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

FieldDescription
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

ValueDescription
TopLeftAnchor relative to top left corner.
TopRightAnchor relative to top right corner.
BottomLeftAnchor relative to bottom left corner.
BottomRightAnchor relative to bottom right corner.
CenterAnchor 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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 15
4
5{"status":"ok"}
cURL
1{
2 "status":"ok"
3}

Update Composition API Response fields

FieldDescription
statusSee status codes below

Update Composition API Status Codes

HTTPStatusRetryDescription
200 OKokneverComposition was successfully updated.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-foundneverThe composition stream does not exist.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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:

HTTP
1DELETE /pcast/composition/<urlEncodedCompositionId> HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 28
6Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
7
8{
9 "reason": "<reason>"
10}
cURL
1$ curl https://pcast.phenixrts.com/pcast/composition/<urlEncodedCompositionId> \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Content-Length: 28" \
5-u applicationId:secret \
6-X DELETE \
7-d '{
8 "reason": "<reason>"
9 }'
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

FieldDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 15
4
5{"status":"ok"}
cURL
1{
2 "status": "ok"
3}

Delete Composition API Response fields

FieldDescription
statusSee status codes below

Delete Composition API Status Codes

HTTPStatusRetryDescription
200 OKokneverComposition was successfully deleted.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-foundneverThe composition stream does not exist.
409 Conflictalready-deletedneverThe composition is already deleted.
410 Gonealready-deletedneverThe stream has already ended.
410 Gonealready-endedneverThe stream has already ended.
410 Goneresource-unavailableneverThe stream has already ended.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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:

HTTP
1POST /pcast/transcoding HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 210
6Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
7
8{
9 "transcoding": {
10 "type": "DASH",
11 "originStreamId": "<streamId>",
12 "onDemand": true,
13 "audioOnly": false,
14 "quality": "hd",
15 "tags": ["<tag1>", "<tag2>"]
16 }
17}
cURL
1$ curl https://pcast.phenixrts.com/pcast/transcoding \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Content-Length: 210" \
5-u applicationId:secret \
6-X PUT \
7-d '{
8 "transcoding": {
9 "type": "DASH",
10 "originStreamId": "<streamId>",
11 "onDemand": true,
12 "audioOnly": false,
13 "quality": "hd",
14 "tags": ["<tag1>", "<tag2>"]
15 }
16 }'

Request Fields

FieldDescription
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

FieldDescription
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.
quality (optional)See Transcoding qualities below
tags (optional)Tags for the Transcoded stream

Transcoding Types

FieldDescription
DASHDynamic Adaptive Streaming over HTTP
HLSHTTP Live Streaming

Transcoding Qualities

FieldDescription
uldOutput Ultra low definition - 80kbps stream
vldOutput Very low definition - 350kbps stream
ldOutput Low definition - 520kbps stream
sdOutput Standard definition - 830kbps - default stream
hdOutput High definition - 1600kbps stream
fhdOutput Full high definition - 3000kbps stream
xhdOutput Extended high definition - 5500kbps stream
uhdOutput Ultra high definition - 8500kbps 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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 85
4
5{"status":"ok","transcodingId":"us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8"}
cURL
1{
2 "status": "ok",
3 "transcodingId": "us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8"
4}

Start Transcoding API Response fields

FieldDescription
statusSee status codes below
transcodingIdID of the transcoded stream

Start Transcoding API Status Codes

HTTPStatusRetryDescription
200 OKokneverTranscoding was successfully created.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
409 Conflictalready-existsnever
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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:

HTTP
1DELETE /pcast/transcoding/<urlEncodedTranscodingId> HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 28
6Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
7
8{
9 "reason": "<reason>"
10}
cURL
1$ curl https://pcast.phenixrts.com/pcast/transcoding/<urlEncodedTranscodingId> \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Content-Length: 28" \
5-u applicationId:secret \
6-X DELETE \
7-d '{
8 "reason": "<reason>"
9 }'
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

FieldDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 15
4
5{"status":"ok"}
cURL
1{
2 "status": "ok"
3}

Stop Transcoding API Response fields

FieldDescription
statusSee status codes below

Delete Transcoding API Status Codes

HTTPStatusRetryDescription
200 OKokneverTranscoding was successfully deleted.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
409 Conflictalready-deletedneverThe Transcoding is already deleted.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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.
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10