Create and manage slates

Slates are content that can be served when there are gaps in a livestream ad break that cannot be filled with a dynamically served ad. An ad may be unavailable for a number of reasons, including but not limited to the following:

  • Errors occur while fetching assets from CDNs (content delivery networks)
  • Errors occur during the processing of assets while stitching

Before the Video Stitcher API can insert a slate, the slate video asset must be registered. Registration is needed so that the Video Stitcher API can prepare the slate asset for insertion in the absence of ads.

This document describes how to manage slates. For more details, see the REST documentation.

Register a slate

To register a slate, use the projects.locations.slates.create method.

REST

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

  • PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
  • LOCATION: the location in which to create your slate; use one of the supported regions
    Show locations
    • us-central1
    • us-east1
    • us-west1
    • asia-east1
    • asia-south1
    • asia-southeast1
    • europe-west1
    • southamerica-east1
  • SLATE_ID: A user-defined identifier for the slate. 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.
  • SLATE_URL: the public URI for an MP4 video with at least one audio track (sample video)

To send your request, expand one of these options:

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/slates/SLATE_ID",
    "verb": "create",
    "cancelRequested": false,
    "apiVersion": "v1"
  },
  "done": false
}
This command creates a long-running operation (LRO) that you can query to track progress. Copy the returned OPERATION_ID, which is the last part of the name field, to use in the next section.

C#

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.


using Google.Api.Gax.ResourceNames;
using Google.Cloud.Video.Stitcher.V1;
using Google.LongRunning;
using System.Threading.Tasks;

public class CreateSlateSample
{
    public async Task<Slate> CreateSlateAsync(
        string projectId, string location, string slateId, string slateUri)
    {
        // Create the client.
        VideoStitcherServiceClient client = VideoStitcherServiceClient.Create();

        CreateSlateRequest request = new CreateSlateRequest
        {
            ParentAsLocationName = LocationName.FromProjectLocation(projectId, location),
            SlateId = slateId,
            Slate = new Slate
            {
                Uri = slateUri
            }
        };

        // Make the request.
        Operation<Slate, OperationMetadata> response = await client.CreateSlateAsync(request);

        // Poll until the returned long-running operation is complete.
        Operation<Slate, OperationMetadata> completedResponse = await response.PollUntilCompletedAsync();

        // Retrieve the operation result.
        return completedResponse.Result;
    }
}

Go

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.

import (
	"context"
	"fmt"
	"io"

	stitcher "cloud.google.com/go/video/stitcher/apiv1"
	stitcherstreampb "cloud.google.com/go/video/stitcher/apiv1/stitcherpb"
)

// createSlate creates a slate. A slate is displayed when ads are not available.
func createSlate(w io.Writer, projectID, slateID, slateURI string) error {
	// projectID := "my-project-id"
	// slateID := "my-slate-id"
	// slateURI := "https://my-slate-uri/test.mp4"
	location := "us-central1"
	ctx := context.Background()
	client, err := stitcher.NewVideoStitcherClient(ctx)
	if err != nil {
		return fmt.Errorf("stitcher.NewVideoStitcherClient: %w", err)
	}
	defer client.Close()

	req := &stitcherstreampb.CreateSlateRequest{
		Parent:  fmt.Sprintf("projects/%s/locations/%s", projectID, location),
		SlateId: slateID,
		Slate: &stitcherstreampb.Slate{
			Uri: slateURI,
		},
	}
	// Creates the slate.
	op, err := client.CreateSlate(ctx, req)
	if err != nil {
		return fmt.Errorf("client.CreateSlate: %w", err)
	}
	response, err := op.Wait(ctx)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "Slate: %v", response.GetName())
	return nil
}

Java

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.


import com.google.cloud.video.stitcher.v1.CreateSlateRequest;
import com.google.cloud.video.stitcher.v1.LocationName;
import com.google.cloud.video.stitcher.v1.Slate;
import com.google.cloud.video.stitcher.v1.VideoStitcherServiceClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateSlate {

  private static final int TIMEOUT_IN_MINUTES = 2;

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String location = "us-central1";
    String slateId = "my-slate-id";
    String slateUri =
        "https://my-slate-uri/test.mp4"; // URI of an MP4 video with at least one audio track

    createSlate(projectId, location, slateId, slateUri);
  }

  // Creates a slate. Slates are content that can be served when there are gaps in a livestream
  // ad break that cannot be filled with a dynamically served ad. For more information, see
  // https://cloud.google.com/video-stitcher/docs/how-to/managing-slates.
  public static Slate createSlate(
      String projectId, String location, String slateId, String slateUri)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (VideoStitcherServiceClient videoStitcherServiceClient =
        VideoStitcherServiceClient.create()) {
      CreateSlateRequest createSlateRequest =
          CreateSlateRequest.newBuilder()
              .setParent(LocationName.of(projectId, location).toString())
              .setSlateId(slateId)
              .setSlate(Slate.newBuilder().setUri(slateUri).build())
              .build();

      Slate response =
          videoStitcherServiceClient
              .createSlateAsync(createSlateRequest)
              .get(TIMEOUT_IN_MINUTES, TimeUnit.MINUTES);
      System.out.println("Created new slate: " + response.getName());
      return response;
    }
  }
}

Node.js

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.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// projectId = 'my-project-id';
// location = 'us-central1';
// slateId = 'my-slate';
// slateUri = 'https://my-slate-uri/test.mp4';

// Imports the Video Stitcher library
const {VideoStitcherServiceClient} =
  require('@google-cloud/video-stitcher').v1;
// Instantiates a client
const stitcherClient = new VideoStitcherServiceClient();

async function createSlate() {
  // Construct request
  const request = {
    parent: stitcherClient.locationPath(projectId, location),
    slate: {
      uri: slateUri,
    },
    slateId: slateId,
  };
  const [operation] = await stitcherClient.createSlate(request);
  const [response] = await operation.promise();
  console.log(`response.name: ${response.name}`);
}

createSlate().catch(err => {
  console.error(err.message);
  process.exitCode = 1;
});

PHP

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.

use Google\Cloud\Video\Stitcher\V1\Client\VideoStitcherServiceClient;
use Google\Cloud\Video\Stitcher\V1\CreateSlateRequest;
use Google\Cloud\Video\Stitcher\V1\Slate;

/**
 * Creates a slate. A slate is displayed when ads are not available.
 *
 * @param string $callingProjectId     The project ID to run the API call under
 * @param string $location             The location of the slate
 * @param string $slateId              The name of the slate to be created
 * @param string $slateUri             The public URI for an MP4 video with at least one audio track
 */
function create_slate(
    string $callingProjectId,
    string $location,
    string $slateId,
    string $slateUri
): void {
    // Instantiate a client.
    $stitcherClient = new VideoStitcherServiceClient();

    $parent = $stitcherClient->locationName($callingProjectId, $location);
    $slate = new Slate();
    $slate->setUri($slateUri);

    // Run slate creation request
    $request = (new CreateSlateRequest())
        ->setParent($parent)
        ->setSlateId($slateId)
        ->setSlate($slate);
    $operationResponse = $stitcherClient->createSlate($request);
    $operationResponse->pollUntilComplete();
    if ($operationResponse->operationSucceeded()) {
        $result = $operationResponse->getResult();
        // Print results
        printf('Slate: %s' . PHP_EOL, $result->getName());
    } else {
        $error = $operationResponse->getError();
        // handleError($error)
    }
}

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.


import argparse

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


def create_slate(
    project_id: str, location: str, slate_id: str, slate_uri: str
) -> stitcher_v1.types.Slate:
    """Creates a slate.
    Args:
        project_id: The GCP project ID.
        location: The location in which to create the slate.
        slate_id: The user-defined slate ID.
        slate_uri: Uri of the video slate; must be an MP4 video with at least one audio track.

    Returns:
        The slate resource.
    """

    client = VideoStitcherServiceClient()

    parent = f"projects/{project_id}/locations/{location}"

    slate = stitcher_v1.types.Slate(
        uri=slate_uri,
    )

    operation = client.create_slate(parent=parent, slate_id=slate_id, slate=slate)
    response = operation.result()
    print(f"Slate: {response.name}")
    return response

Ruby

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.

require "google/cloud/video/stitcher"

##
# Create a slate
#
# @param project_id [String] Your Google Cloud project (e.g. `my-project`)
# @param location [String] The location (e.g. `us-central1`)
# @param slate_id [String] Your slate name (e.g. `my-slate`)
# @param slate_uri [String] The URI of an MP4 video with at least one audio
#   track (e.g. `https://my-slate-uri/test.mp4`)
#
def create_slate project_id:, location:, slate_id:, slate_uri:
  # Create a Video Stitcher client.
  client = Google::Cloud::Video::Stitcher.video_stitcher_service

  # Build the resource name of the parent.
  parent = client.location_path project: project_id, location: location

  # Set the slate fields.
  new_slate = {
    uri: slate_uri
  }

  operation = client.create_slate parent: parent, slate_id: slate_id,
                                  slate: new_slate

  # The returned object is of type Gapic::Operation. You can use this
  # object to check the status of an operation, cancel it, or wait
  # for results. Here is how to block until completion:
  operation.wait_until_done!

  # Print the slate name.
  puts "Slate: #{operation.response.name}"
end

Check for the result

To check if the slate 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:

  • PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
  • LOCATION: the location of the data; use one of the supported regions
    Show locations
    • us-central1
    • us-east1
    • us-west1
    • asia-east1
    • asia-south1
    • asia-southeast1
    • europe-west1
    • southamerica-east1
  • OPERATION_ID: the identifier for the operation

To send your request, expand one of these options:

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/slates/SLATE_ID",
    "verb": "create",
    "cancelRequested": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.video.stitcher.v1.Slate",
    "name": "projects/PROJECT_NUMBER/locations/LOCATION/slates/SLATE_ID",
    "uri": "SLATE_URL"
  }
}

Get a slate

To get the details for a specific slate, use the projects.locations.slates.get method.

REST

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

  • PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
  • LOCATION: the location where your slate is located; use one of the supported regions
    Show locations
    • us-central1
    • us-east1
    • us-west1
    • asia-east1
    • asia-south1
    • asia-southeast1
    • europe-west1
    • southamerica-east1
  • SLATE_ID: a user-defined identifier for the slate

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/slates/SLATE_ID",
  "uri": "SLATE_URL"
}

C#

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.


using Google.Cloud.Video.Stitcher.V1;

public class GetSlateSample
{
    public Slate GetSlate(
        string projectId, string location, string slateId)
    {
        // Create the client.
        VideoStitcherServiceClient client = VideoStitcherServiceClient.Create();

        GetSlateRequest request = new GetSlateRequest
        {
            SlateName = SlateName.FromProjectLocationSlate(projectId, location, slateId)
        };

        // Call the API.
        Slate response = client.GetSlate(request);

        // Return the result.
        return response;
    }
}

Go

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.

import (
	"context"
	"encoding/json"
	"fmt"
	"io"

	stitcher "cloud.google.com/go/video/stitcher/apiv1"
	stitcherstreampb "cloud.google.com/go/video/stitcher/apiv1/stitcherpb"
)

// getSlate gets a previously-created slate.
func getSlate(w io.Writer, projectID, slateID string) error {
	// projectID := "my-project-id"
	// slateID := "my-slate-id"
	location := "us-central1"
	ctx := context.Background()
	client, err := stitcher.NewVideoStitcherClient(ctx)
	if err != nil {
		return fmt.Errorf("stitcher.NewVideoStitcherClient: %w", err)
	}
	defer client.Close()

	req := &stitcherstreampb.GetSlateRequest{
		Name: fmt.Sprintf("projects/%s/locations/%s/slates/%s", projectID, location, slateID),
	}

	response, err := client.GetSlate(ctx, req)
	if err != nil {
		return fmt.Errorf("client.GetSlate: %w", err)
	}
	b, err := json.MarshalIndent(response, "", " ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}

	fmt.Fprintf(w, "Slate:\n%s", string(b))
	return nil
}

Java

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.


import com.google.cloud.video.stitcher.v1.GetSlateRequest;
import com.google.cloud.video.stitcher.v1.Slate;
import com.google.cloud.video.stitcher.v1.SlateName;
import com.google.cloud.video.stitcher.v1.VideoStitcherServiceClient;
import java.io.IOException;

public class GetSlate {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String location = "us-central1";
    String slateId = "my-slate-id";

    getSlate(projectId