On this page

Multiple Playback IDs

Introduction

A Playback ID is a unique identifier used to access a specific version of a live stream. Playback IDs are vital for controlling access, tracking, and the customization of live streaming content.

Types of Access Policies

Access Policies for Playback IDs allow for precise control over who can access the live stream.

Type	Description
Public	The content is freely accessible to anyone with the Playback ID.
Authenticated	The content is restricted. Access is granted only to authorized users.

Benefits

Access Control

Use Multiple Playback IDs to configure complex rules for viewer access based on geography, membership status, or special permissions.

Personalization

Modify streams to match viewer preferences, devices, and other factors for an optimal experience.

Better Insights

Provides additional segmentation options to analyze audience growth, user behavior, and refined ad targeting.

1
Generating a new Playback ID

The first step is to generate a new Playback ID for your live stream. You can do this by following these steps:

Step 1Preparing the API Request

To add a playback ID to your stream:

Use the POST method with the endpoint: /v1/live-streams/<stream_id>/playback-ids
Replace <stream_id> with your specific stream's ID.

Step 2Specifying Playback Policy

In your request, you need to define the playback policy. This policy dictates how your stream can be accessed:

Public: No authentication is required to view the stream.
Authenticated: Viewers must provide a JWT token in the 'auth' parameter of the playback URL query string.

Include the policy in the JSON object of your request data.

Step 3Sending the Request

Here's an example of how to send your request using curl:

curl -X POST 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/playback-ids' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
--data-raw '{
  "policy": "public" # or "authenticated"
}'

Replace $STREAM_ID with your stream ID and $ACCESS_TOKEN with your access token.

Step 4Understanding the Response

Upon a successful request, you will receive a response containing the updated stream object. This object includes all attributes of your stream, such as:

Stream status and details
Playback IDs with their respective policies
Stream keys and server URLs

Response Example:

{
  "stream": {
      "status": {
          "timestamp": "2023-06-02 13:19:40",
          "name": "created"
      },
      "name": "Stream_N3B47YML",
      "stream_key": "a49c85c5-513a-4cea-8c66-f98e2019aab0",
      "created_at": "2023-06-02 13:19:40",
      "server_urls": {
          "rtmps": "rtmps://rtmp-live.qencode.com/qlive",
          "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
      },
      "params": {
          "input_format": "rtmp",
          "output_format": "hls",
          "framerate": 0,
          "mode": "auto",
          "callback_url": null,
          "dvr": {
              "max_file_duration": 14400,
              "destination": null,
              "enabled": false,
              "stream_source": "auto",
              "format": "mp4"
          }
      },
      "playback_ids": [
          {
              "policy": "public",
              "created": "2023-06-02 13:19:40",
              "id": "Av22X1p8h5",
              "playback_url": "https://play-Av22X1p8h5.qencode.com/qhls/qlive/playlist.m3u8"
          },
          {
              "policy": "authenticated",
              "id": "5yxn1iz6vj4g",
              "playback_url": "https://play-5yxn1iz6vj4g.qencode.com/qhls/qlive/playlist.m3u8",
              "created": "2023-06-02 16:15:54"
          }
      ],
      "id": "92727a3d-5b14-491d-9479-a9269d8e76e1"
  }
}

Navigate to the Streams page, and click on the name of the stream you want to add a Playback ID for.
In the Playback IDs section, click Add playback ID and select an Access Policy. There are two types of Access Policies available for you to select from:

Select Public to allow this Playback ID to be viewable by everyone.
Select Authenticated to restrict access to authorized users only.

Note

By default, each stream comes with a single Playback ID with Policy set to public.

As a side note: authenticated policy for playback IDs is not available for streams using stream.qencode.com system domain.

2
Using a Playback ID

Once the new Playback ID is createed for your live stream, you are ready to use it.

Step 1Retrieving Stream Details

Use the /v1/live-streams API method to retrieve details for all available live streams.
Alternatively, use /v1/live-streams/<stream_id> to get details for a specific live stream, where <stream_id> is the unique identifier for the stream.

Step 2Accessing Playback Information

Within the stream object obtained from the above step, there's an attribute named playback_ids. This attribute contains a list of available playback IDs.
Each playback ID object includes a playback_url attribute, which contains the URL needed for playback.

Step 3Handling Authenticated Playback IDs

For playback IDs that are associated with an authenticated policy, it's necessary to generate a signed token.
This signed token should then be attached to the playback URL to enable access to the stream within the auth param:

https://<playback_url>?auth=<token>

Alternative approach is setting a Qencode-Auth-Token signed cookie instead of specifying the auth param with signed token in the playback URL. Please see the Signed coookies tutorial for more details.

Click Copy URL to copy the URL to your clipboard.
Your Playback ID is ready to use. You can watch the stream using new Playback ID via the URL, once your stream is Live.

3
Removing a Playback ID

In case you need to delete an existing Playback ID in your live stream, you can so by following these steps:

Step 1Set Up the API Request

To delete a playback ID:

Use the DELETE method with the endpoint: /v1/live-streams/<stream_id>/playback-ids/<playback_id>
Replace <stream_id> with your stream's unique identifier and <playback_id> with the ID of the playback you wish to remove.

Step 2Sending the Delete Request

Here's how to send a delete request using curl:

curl -X DELETE 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/playback-ids/$PLAYBACK_ID'  
-H 'Authorization: Bearer $ACCESS_TOKEN'

Replace $STREAM_ID and $PLAYBACK_ID with your specific stream and playback ID, and $ACCESS_TOKEN with your authorization token.

Step 3Understanding the Response

Upon successful deletion, the API will return an updated stream object. This object reflects the current state of your stream, including any remaining playback IDs.