Create a live session

Using the Video Stitcher API, you create a live session each time you start playback of a live stream in which ads are dynamically stitched during ad breaks. The response specifies the playback URL and the configuration of the live session.

This document describes how to create a live session. For more details, see the REST documentation.

Before you begin

• Create a live config

Define a live session

When you define a live session, the following field is required:

• liveConfig

When you define a live session, the following fields are optional:

• adTagMacros
• manifestOptions

The adTagMacros parameter is a list of key-value pairs for ad tag macro replacement. For details, see the ad tag macros section.

The manifestOptions parameter specifies which video renditions are generated in the stitched video manifest. It also supports the ordering of the renditions in the stitched video manifest. For more information, see the manifest options documentation.

Create a live session

To create a live session, use the projects.locations.liveSessions.create method.

REST

Before using any of the request data, make the following replacements:

• PROJECT_NUMBER: your Google Cloud project number located in the Project number field on the IAM Settings page
• LOCATION: the location in which to create your session; use one of the supported regions:
  • us-central1
  • us-east1
  • us-west1
  • asia-east1
  • asia-south1
  • asia-southeast1
  • europe-west1
  • southamerica-east1
• LIVE_CONFIG_ID: the user-defined identifier for the live config

Request JSON body:

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": "PLAY_URI",
  "sourceUri": "SOURCE_LIVESTREAM_URI",
  "adTagMap": {
    "default": {
      "uri": "AD_TAG_URI"
    }
  },
  "clientAdTracking": true,
  "defaultSlateId": "SLATE_ID",
  "stitchingPolicy": "CUT_CURRENT",
  "streamId": "STREAM_ID",
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
}

Python

Before trying this sample, follow the Python setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Python API reference documentation.

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import argparse

from google.cloud.video import stitcher_v1
from google.cloud.video.stitcher_v1.services.video_stitcher_service import (
    VideoStitcherServiceClient,
)


def create_live_session(project_id: str, location: str, live_config_id: str) -> str:
    """Creates a live session. Live sessions are ephemeral resources that expire
    after a few minutes.
    Args:
        project_id: The GCP project ID.
        location: The location in which to create the session.
        live_config_id: The user-defined live config ID."""

    client = VideoStitcherServiceClient()

    parent = f"projects/{project_id}/locations/{location}"
    live_config = (
        f"projects/{project_id}/locations/{location}/liveConfigs/{live_config_id}"
    )

    live_session = stitcher_v1.types.LiveSession(live_config=live_config)

    response = client.create_live_session(parent=parent, live_session=live_session)
    print(f"Live session: {response.name}")
    return response

The Video Stitcher API generates a unique session ID for each request. A session expires after 5 minutes.

An ad must be encoded before it can be stitched into a live session. When you create a session for an ad-stitched video, the Video Stitcher API determines if the ad has already been encoded from a previous session. The API only looks for encoded ads created by sessions associated with your Google Cloud project. For more information on this process, see the Overview.

The response is a live session object. The playUri is the URL the client device uses to play the ad stitched stream for this live session.

If you're generating a session on behalf of your customers' devices, you can set the following parameters via HTTP headers:

Parameter	HTTP Header
CLIENT_IP	x-user-ip
REFERRER_URL	referer
USER_AGENT	user-agent

You can add the following headers to the preceding curl request:

-H "x-user-ip: CLIENT_IP" \
-H "referer: REFERRER_URL" \
-H "user-agent: USER_AGENT" \

Ad tag macros

An ad tag can contain macros, which can produce a different ad tag for each session. Macros are denoted by square brackets in the ad tag, as illustrated by the following example:

AD_TAG_URI&macro=[value]

The adTagUri is defined in the live config.

To substitute the value in the ad tag macro, provide a mapping in the adTagMacros field. For example, if you want to replace the [value] macro with the string bar, you need to provide the following:

{
  ...
  "adTagMacros": {
    "value": "bar"
  },
  ...
}

When the Video Stitcher API requests the ad metadata, it uses the following ad tag:

AD_TAG_URI&macro=bar

Get a session

To get the live session, use the projects.locations.liveSessions.get method.

REST

Before using any of the request data, make the following replacements:

• PROJECT_NUMBER: your Google Cloud project number located in the Project number field on the IAM Settings page
• LOCATION: the location in which to create your session; use one of the supported regions:
  • us-central1
  • us-east1
  • us-west1
  • asia-east1
  • asia-south1
  • asia-southeast1
  • europe-west1
  • southamerica-east1
• SESSION_ID: the identifier for the live session

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": "ad-stitched-live-stream-uri",
  "defaultAdTagId": "default",
  "sourceUri": "LIVE_STREAM_URI",
  "adTagMap": {
    "default": {
      "uri": "AD_TAG_URI"
    }
  },
  "defaultSlateId": "SLATE_ID",
  "streamId": "STREAM_ID"
}

Python

Before trying this sample, follow the Python setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Python API reference documentation.

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import argparse

from google.cloud.video.stitcher_v1.services.video_stitcher_service import (
    VideoStitcherServiceClient,
)


def get_live_session(project_id: str, location: str, session_id: str) -> str:
    """Gets a live session. Live sessions are ephemeral resources that expire
    after a few minutes.
    Args:
        project_id: The GCP project ID.
        location: The location of the session.
        session_id: The ID of the live session."""

    client = VideoStitcherServiceClient()

    name = client.live_session_path(project_id, location, session_id)
    response = client.get_live_session(name=name)
    print(f"Live session: {response.name}")
    return response

Sample ad-stitched playlist

The following shows a sample source live playlist before ad-stitching:

#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:32:00Z",DURATION=60,SCTE35-OUT=0xF...
#EXTINF:10.010
segment_00007.ts
#EXTINF:10.010
segment_00008.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:39:20Z",SCTE35-IN=0xF...
#EXTINF:10.010
segment_00009.ts

The following shows a sample source live playlist after ad-stitching:

#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:10.010
segment_00009.ts