This document describes how to manage live configs. Live configs are used to configure live sessions. For more details, see the REST documentation.
Before you begin
To create a live session, you must first configure a livestream encoder which generates a source HLS or DASH manifest for the Video Stitcher API. These manifests contain certain ad markers at ad break boundaries which are identified by the Video Stitcher API for ad stitching purposes. You can create a livestream with a compatible manifest by following one of the Live Stream API quickstarts.
For more details on the supported HLS and DASH ad markers, see the ad markers documentation.
Define a live config
When you define a live config, the following fields are required:
sourceUri
adTagUri
defaultSlate
adTracking
sourceUri
specifies the URL to the source livestream's HLS or DASH
manifest to insert ads into. The Video Stitcher API returns an HLS playback URL
if the provided URL references an HLS manifest and a DASH playback URL if the
provided URL references a DASH manifest.
adTagUri
specifies the URL of the ad server that returns the ad metadata.
defaultSlate
specifies the default slate to use when no slates
are specified in an ad break's ad marker SCTE-35 message. For details about
managing slates, see the slates documentation.
adTracking
determines if the client player is expected to trigger playback and
activity events or if the Video Stitcher API is expected to trigger playback events on
behalf of the client player. For more information on client-side ad tracking,
see
Handle client-side ad tracking.
The live config contains optional fields for prefetching ads and defining custom headers.
Register a live config
To register a live config, use the
projects.locations.liveConfigs.create
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location in which to create your live config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: a user-defined identifier for the live config. This ID can only contain lower-case letters, numbers, and hyphens. The first character must be a letter, the last character must be a letter or a number, and the entire ID has a 63 character maximum.LIVE_CONFIG_ID
: the URI of the livestream manifest; use a public URI or an unsigned URI for which you registered a CDN keySOURCE_LIVESTREAM_URI the public URI for the default ad tag. If you don't have one, you can use a Single Inline Linear sample.AD_TAG_URI
: the ID of the slate to use in the absence of stitched adsSLATE_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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' { "sourceUri": "SOURCE_LIVESTREAM_URI ", "adTagUri": "AD_TAG_URI ", "defaultSlate": "projects/PROJECT_NUMBER /locations/LOCATION /slates/SLATE_ID ", "adTracking": "SERVER", "stitchingPolicy": "CUT_CURRENT" } 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 /liveConfigs?liveConfigId=LIVE_CONFIG_ID "
PowerShell (Windows)
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:
@' { "sourceUri": "SOURCE_LIVESTREAM_URI ", "adTagUri": "AD_TAG_URI ", "defaultSlate": "projects/PROJECT_NUMBER /locations/LOCATION /slates/SLATE_ID ", "adTracking": "SERVER", "stitchingPolicy": "CUT_CURRENT" } '@ | 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 /liveConfigs?liveConfigId=LIVE_CONFIG_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "verb": "create", "cancelRequested": false, "apiVersion": "v1" }, "done": false }
OPERATION_ID
,
which is the last part of the name
field, to use in the next section.
Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API C# 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.
Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Go 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.
Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Java 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.
Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Node.js 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.
Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API PHP 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.
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.
Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Ruby 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.
Check for the result
To check if the live config has been created, use the
projects.locations.operations.get
method. If the response contains "done: false"
, repeat the command until the
response contains "done: true"
.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the data; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the identifier for the operationOPERATION_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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 /operations/OPERATION_ID "
PowerShell (Windows)
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 /operations/OPERATION_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "endTime":END_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "verb": "create", "cancelRequested": false, "apiVersion": "v1" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.video.stitcher.v1.LiveConfig", "name": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "sourceUri": "SOURCE_LIVESTREAM_URI ", "adTagUri": "AD_TAG_URI ", "state": "READY", "adTracking": "CLIENT", "defaultSlate": "projects/PROJECT_NUMBER /locations/LOCATION /slates/SLATE_ID ", "stitchingPolicy": "CUT_CURRENT", "defaultAdBreakDuration": "30s" } }
Get a live config
To get the details for a specific live config, use the
projects.locations.liveConfigs.get
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the live config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the user-defined identifier for the live configLIVE_CONFIG_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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 /liveConfigs/LIVE_CONFIG_ID "
PowerShell (Windows)
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 /liveConfigs/LIVE_CONFIG_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "sourceUri": "SOURCE_LIVESTREAM_URI ", "adTagUri": "AD_TAG_URI ", "state": "READY", "adTracking": "SERVER", "defaultSlate": "projects/PROJECT_NUMBER /locations/LOCATION /slates/SLATE_ID ", "stitchingPolicy": "CUT_CURRENT" }
Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API C# 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.
Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Go 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.
Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Java 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.
Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Node.js 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.
Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API PHP 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.
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.
Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Ruby 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.
Update a live config
To update a specific live config, use the
projects.locations.liveConfigs.patch
method. You can only update the
custom headers.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location in which to create your live config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the user-defined identifier for the live configLIVE_CONFIG_ID
: the key in a key-value pair used to define a custom headerKEY
: the value in a key-value pair used to define a custom headerVALUE
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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' { "sourceFetchOptions": { "headers": { "KEY ": "VALUE " } } } EOF
Then execute the following command to send your REST request:
curl -X PATCH \
-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 /liveConfigs/LIVE_CONFIG_ID ?updateMask=sourceFetchOptions.headers"
PowerShell (Windows)
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:
@' { "sourceFetchOptions": { "headers": { "KEY ": "VALUE " } } } '@ | 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 PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ?updateMask=sourceFetchOptions.headers" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "verb": "update", "cancelRequested": false, "apiVersion": "v1" }, "done": false }
List all registered live configs
To list all of the live configs registered for a given location in a project,
use the
projects.locations.liveConfigs.list
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the live configs; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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 /liveConfigs"
PowerShell (Windows)
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 /liveConfigs" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "liveConfigs": [ { "name": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "sourceUri": "SOURCE_LIVESTREAM_URI ", "adTagUri": "AD_TAG_URI ", "state": "READY", "adTracking": "SERVER", "defaultSlate": "projects/PROJECT_NUMBER /locations/LOCATION /slates/SLATE_ID ", "stitchingPolicy": "CUT_CURRENT" }, { "name": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/my-other-live-config ", "sourceUri": "my-other-live-stream-uri ", "adTagUri": "my-other-ad-tag-uri ", "state": "READY", "adTracking": "SERVER", "defaultSlate": "projects/PROJECT_NUMBER /locations/LOCATION /slates/my-other-slate ", "stitchingPolicy": "CUT_CURRENT" } }
Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API C# 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.
Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Go 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.
Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Java 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.
Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Node.js 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.
Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API PHP 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.
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.
Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Ruby 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.
Additional results
The curl
response may include a nextPageToken
, which you can use to retrieve
additional results:
{ "liveConfigs": [ ... ], "nextPageToken": "NEXT_PAGE_TOKEN " }
You can send another curl
request, including the value of
NEXT_PAGE_TOKEN, to list the additional configs. Append the following
to the URL in the preceding API call:
?pageToken=NEXT_PAGE_TOKEN
See the relevant client library for more information on using this token.
Delete a live config
If a registered live config is no longer needed, delete it using the
projects.locations.liveConfigs.delete
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the live config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the user-defined identifier for the live configLIVE_CONFIG_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID "
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /liveConfigs/LIVE_CONFIG_ID ", "verb": "delete", "cancelRequested": false, "apiVersion": "v1" }, "done": false }
Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API C# 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.
Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Go 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.
Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Java 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.
Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Node.js 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.
Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API PHP 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.
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.
Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Ruby 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.