ライブ セッションを作成する

Video Stitcher API では、ライブ ストリームの再生を開始するたびにライブ セッションを作成し、ミッドロール挿入点で広告が動的に合成されます。 レスポンスで、再生 URL とライブ セッションの構成を指定します。

このドキュメントでは、ライブ セッションの作成方法について説明します。詳細については、REST のドキュメントをご覧ください。

始める前に

ライブ セッションを定義する

ライブ セッションを定義する場合は、次のフィールドに値を入力する必要があります。

  • liveConfig

ライブ セッションを定義する場合、次のフィールドは省略可能です。

  • adTagMacros
  • manifestOptions

adTagMacros パラメータは、広告タグマクロの置換用の Key-Value ペアのリストです。詳しくは、広告タグのマクロのセクションをご覧ください。

manifestOptions パラメータは、合成された動画マニフェストで生成される動画レンダリングを指定します。合成された動画マニフェストのレンダリング順序もサポートされています。詳細については、マニフェスト オプションのドキュメントをご覧ください。

ライブ セッションを作成する

ライブ セッションを作成するには、projects.locations.liveSessions.create メソッドを使用します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_NUMBER: IAM 設定ページの [プロジェクト番号] フィールドにある Google Cloud プロジェクト番号
  • LOCATION: セッションを作成するロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • us-west1
    • asia-east1
    • asia-south1
    • asia-southeast1
    • europe-west1
    • southamerica-east1
  • LIVE_CONFIG_ID: ライブ構成ファイルのユーザー定義の識別子。

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

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

このサンプルを試す前に、クライアント ライブラリを使用した Video Stitcher API クイックスタートにある Python の設定手順を実施してください。詳細については、Video Stitcher API Python API リファレンス ドキュメントをご覧ください。

Video Stitcher API への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。


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

Video Stitcher API は、リクエストごとに一意のセッション ID を生成します。セッションは 5 分後に期限切れになります。

ライブ セッションに広告を合成する前にエンコードする必要があります。広告合成されが動画のセッションを作成すると、Video Stitcher API によって、前のセッションから取得した広告がすでにエンコードされているかどうかが判断されます。この API は、Google Cloud プロジェクトに関連付けられたセッションによって作成されたエンコード済みの広告のみを検索します。このプロセスの詳細については、概要をご覧ください。

レスポンスはライブ セッション オブジェクトです。playUri は、クライアント デバイスがこのライブ セッションの広告結合されたストリームの再生に使用する URL です。

お客様のデバイスに代わってセッションを生成する場合は、HTTP ヘッダーを使用して次のパラメータを設定できます。

パラメータ HTTP ヘッダー
CLIENT_IP x-user-ip
REFERRER_URL referer
USER_AGENT user-agent

上記の curl リクエストに次のヘッダーを追加できます。

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

広告タグマクロ

広告タグには、セッションごとに異なる広告を生成するマクロを含めることが可能です。マクロは、次の例のように、角かっこで示されます。

AD_TAG_URI&macro=[value]

adTagUri は、ライブ構成で定義されています。

広告タグマクロの値と置き換えるには、adTagMacros フィールドにマッピングを指定します。たとえば、[value] マクロを文字列 bar に置き換えるには、次の値を指定する必要があります。

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

Video Stitcher API が広告メタデータをリクエストすると、次の広告タグが使用されます。

AD_TAG_URI&macro=bar

セッションを取得する

ライブ セッションを取得するには、projects.locations.liveSessions.get メソッドを使用します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_NUMBER: IAM 設定ページの [プロジェクト番号] フィールドにある Google Cloud プロジェクト番号
  • LOCATION: セッションを作成するロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • us-west1
    • asia-east1
    • asia-south1
    • asia-southeast1
    • europe-west1
    • southamerica-east1
  • SESSION_ID: ライブ セッションの ID

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

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

このサンプルを試す前に、クライアント ライブラリを使用した Video Stitcher API クイックスタートにある Python の設定手順を実施してください。詳細については、Video Stitcher API Python API リファレンス ドキュメントをご覧ください。

Video Stitcher API への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。


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

広告合成された再生リストの例

以下は、広告合成前のソースライブ再生リストのサンプルです。

#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

以下は、広告合成後のソースライブ再生リストのサンプルです。

#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