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
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>"]
    }
}

cURL
$ curl https://pcast.phenixrts.com/pcast/composition \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X POST \
-d '{
        "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
uhd	Output 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
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"}

cURL
{
   "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:

HTTP
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>"
        }
    ]
}

cURL
$ curl https://pcast.phenixrts.com/pcast/composition/<compositionId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X PUT \
-d '{
        "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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 15

{"status":"ok"}

cURL
{
   "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:

HTTP
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>"
}

cURL
$ curl https://pcast.phenixrts.com/pcast/composition/<urlEncodedCompositionId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 28" \
-u applicationId:secret \
-X DELETE \
-d '{
        "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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 15

{"status":"ok"}

cURL
{
    "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:

HTTP
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,
        "quality": "hd",
        "tags": ["<tag1>", "<tag2>"]
    }
}

cURL
$ curl https://pcast.phenixrts.com/pcast/transcoding \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 210" \
-u applicationId:secret \
-X PUT \
-d '{
        "transcoding": {
            "type": "DASH",
            "originStreamId": "<streamId>",
            "onDemand": true,
            "audioOnly": false,
            "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`.
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
uhd	Output 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
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"}

cURL
{
    "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:

HTTP
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>"
}

cURL
$ curl https://pcast.phenixrts.com/pcast/transcoding/<urlEncodedTranscodingId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 28" \
-u applicationId:secret \
-X DELETE \
-d '{
        "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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 15

{"status":"ok"}

cURL
{
    "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.

Page Content

v2023-01-31T21:25:10