To enable the Video Stitcher API for your project, please reach out to your Account Representative or contact Sales to learn more.

Create a VOD session

Stay organized with collections Save and categorize content based on your preferences.

Using the Video Stitcher API, you create a video-on-demand (VOD) session each time you dynamically insert ads prior to delivery to client devices. When you create a session, the response specifies the playback URL, as well as information about the ads that you inserted into the video.

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

Define a session

When you create a VOD session, the following parameters are required:

  • sourceUri
  • adTagUri

The sourceUri is the URL to the video asset to insert the ads into. The Video Stitcher API returns an HLS playback URL if the provided URL references an HLS manifest; likewise, a DASH playback URL is returned if this field references a DASH manifest.

The adTagUri is the URL of the ad server that returns the ad metadata.

By default, ad impressions trigger on the server side when client devices fetch the ad video segments.

When you create a VOD session, the following parameters are optional:

  • clientAdTracking
  • manifestOptions

The clientAdTracking parameter is a flag to enable client-side ad tracking. By default, a live session uses server-side ad tracking. For more information, see Handle live client ad tracking.

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.

The following example JSON defines a session:

{
  "sourceUri": "VOD_URI",
  "adTagUri": "AD_TAG_URI"
}

Create a session

To create a session for an ad-stitched video, use the projects.locations.vodSessions.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
  • VOD_URI: The URI of the media to stitch. This URI must reference either an MPEG-DASH manifest (.mpd) file or an M3U playlist manifest (.m3u8) file. Use a public URI or an unsigned URI for which you registered a CDN key.
  • AD_TAG_URI: the public URI of the ad tag; if you don't have one, you can use a VMAP Pre-roll sample

Request JSON body: 

{
  "sourceUri": "VOD_URI",
  "adTagUri": "AD_TAG_URI"
}

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/vodSessions/SESSION_ID",
  "interstitials": {
    "sessionContent": {
      "duration": "15s"
    }
  },
  "playUri": "PLAY_URI", # This is the ad-stitched VOD URI
  "sourceUri": "VOD_URI",
  "adTagUri": "AD_TAG_URI",
  "assetId": "ASSET_ID"
}

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

An ad must be encoded before it can be stitched into a VOD 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. If it has, the JSON response will indicate ad break events. 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.

Look at the JSON response. This response indicates that an ad was not stitched into the session. If this is the case, wait 5 minutes (for ad encoding) and then re-run the create session command. The response should now be similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID",
  "interstitials": {
    "adBreaks": [
      {
        "progressEvents": [
          {
            "timeOffset": "0s",
            "events": [
              {
                "type": "IMPRESSION",
                "uri": "https://securepubads.g.doubleclick.net/pcs/view..."
              },
              {
                "type": "START",
                "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
              },
              ...
            ]
          },
          ...
        ],
        "ads": [
          {
            "duration": "10s",
            "activityEvents": [
              {
                "type": "ERROR",
                "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
              },
              {
                "type": "CLICK_THROUGH",
                "uri": "https://pubads.g.doubleclick.net/pcs/click...",
                "id": "GDFP"
              },
              ...
            ]
          }
        ],
        "endTimeOffset": "10s",
        "startTimeOffset": "0s"
      }
    ],
    "sessionContent": {
      "duration": "25s"
    }
  },
  "playUri": "PLAY_URI",
  "sourceUri": "VOD_URI",
  "adTagUri": "AD_TAG_URI",
  "assetId": "ASSET_ID"
}

The response is a VodSession object. The interstitials field contains metadata about the ads that were inserted (see the ad metadata concepts). The playUri is the URL the client device uses to play the conditioned video asset.

If you're generating a session on behalf of your customers' devices, 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 result in 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]

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

{
  ...
  "adTagUri": "AD_TAG_URI&macro=[value]",
  "adTagMacroMap": {
    "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 session for an ad-stitched video, use the projects.locations.vodSessions.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 of 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 VOD session

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/vodSessions/SESSION_ID",
  "interstitials": {
    "adBreaks": [
      {
        "progressEvents": [
          {
            "timeOffset": "0s",
            "events": [
              {
                "type": "IMPRESSION",
                "uri": "https://securepubads.g.doubleclick.net/pcs/view..."
              },
              {
                "type": "START",
                "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
              },
              ...
            ]
          },
          ...
        ],
        "ads": [
          {
            "duration": "10s",
            "activityEvents": [
              {
                "type": "ERROR",
                "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
              },
              {
                "type": "CLICK_THROUGH",
                "uri": "https://pubads.g.doubleclick.net/pcs/click...",
                "id": "GDFP"
              },
              ...
            ]
          }
        ],
        "endTimeOffset": "10s",
        "startTimeOffset": "0s"
      }
    ],
    "sessionContent": {
      "duration": "25s"
    }
  },
  "playUri": "PLAY_URI",
  "sourceUri": "VOD_URI",
  "adTagUri": "AD_TAG_URI",
  "assetId": "ASSET_ID"
}

Sample ad-stitched playlist

The following shows a sample source VOD playlist before ad stitching:

#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:4
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-ENDLIST

The following shows a sample source VOD playlist after ad stitching with pre-roll, mid-roll, and post-roll ads:

#EXTM3U
#EXT-X-VERSION:4
#EXT-X-TARGETDURATION:6
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-DISCONTINUITY
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/preroll_ad/seg_01.ts
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/preroll_ad/seg_02.ts
#EXTINF:1.99,
https://ads.us-west1.cdn.videostitcher.goog/preroll_ad/seg_03.ts
#EXT-X-DISCONTINUITY
#EXTINF:6,
segment_01.ts
#EXTINF:6,
segment_02.ts
#EXT-X-DISCONTINUITY
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/midroll_ad/seg_01.ts
#EXTINF:0.99,
https://ads.us-west1.cdn.videostitcher.goog/midroll_ad/seg_02.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-DISCONTINUITY
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/postroll_ad/seg_01.ts
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/postroll_ad/seg_02.ts
#EXTINF:1.99,
https://ads.us-west1.cdn.videostitcher.goog/postroll_ad/seg_03.ts
#EXT-X-ENDLIST

Avoid ad-break misalignment

For VOD stitching, you should pre-condition the source video manifest for midroll ad breaks and configure the Video Multiple Ad Playlist (VMAP) ad tag to return midroll ad breaks at the pre-conditioned offset positions. Video Stitcher API takes the result of the transcoded output and inserts ads as close as possible to where you specify. Use pre-conditioned inputs for midroll ad breaks to make ad stitching behavior consistent and accurate.

For example, the following video playlist shows an ad placement opportunity at the seven second mark:

#EXTM3U

#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-TARGETDURATION:4

#EXTINF:2.0
../video/180_250000/hls/segment_0.ts
#EXTINF:2.0
../video/180_250000/hls/segment_1.ts
#EXTINF:2.0
../video/180_250000/hls/segment_2.ts
#EXTINF:1.0
../video/180_250000/hls/segment_3.ts
#EXT-X-PLACEMENT-OPPORTUNITY
#EXTINF:2.0
../video/180_250000/hls/segment_4.ts

The following audio playlist shows an ad placement opportunity at the seven second mark:

#EXTM3U

#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-TARGETDURATION:4

#EXTINF:1.99
../audio/1_stereo_128000/hls/segment_0.ts
#EXTINF:1.99
../audio/1_stereo_128000/hls/segment_1.ts
#EXTINF:1.99
../audio/1_stereo_128000/hls/segment_2.ts
#EXTINF:1.03
../audio/1_stereo_128000/hls/segment_3.ts
#EXT-X-PLACEMENT-OPPORTUNITY
#EXTINF:1.99
../audio/1_stereo_128000/hls/segment_4.ts

The following VMAP configuration specifies an ad break to occur at the seven second mark. The video and audio playlists will contain ad breaks at exactly the seven second mark:

<vmap:VMAP xmlns:vmap="http://www.iab.net/videosuite/vmap" version="1.0">
<vmap:AdBreak timeOffset="00:00:07.000" breakType="linear" breakId="midroll‑1">
<vmap:AdSource id="midroll-1‑ad‑1" allowMultipleAds="false" followRedirects="true">
<vmap:AdTagURI templateType="vast3">
<![CDATA[
https://securepubads.g.doubleclick.net/gampad/ads?...
]]>
</vmap:AdTagURI>
</vmap:AdSource>
</vmap:AdBreak>
</vmap:VMAP>

For more information on ad server formats, see Ad server compliance.