YouTube Live Streaming API - Life of a Broadcast

Contents

  1. Introduction
  2. Resources and resource types
  3. Creating and managing a live broadcast
    1. 1. Set up your broadcast
    2. 2. Claim your content
    3. 3. Test
    4. 4. Broadcast
    5. 5. Conclude your broadcast
    6. 6. Create a reference

Introduction

This document walks you through the life of a live broadcast on YouTube that is created and managed using the YouTube Live Streaming API and the YouTube Content ID API.

Resources and resource types

As explained in the getting started guide, a resource is an individual data entity with a unique identifier. To create and manage live events on YouTube, you will use a number of different types of resources that are defined as part of either the YouTube Data API or the YouTube Content ID API. The resources listed under the YouTube Live Streaming API header are technically defined in those other APIs but are listed separately because they are only used for live broadcasts.

YouTube Live Streaming API resources

YouTube Data API resources

YouTube Content ID API resources

Creating and managing a live broadcast

The following steps explain how to create and manage a live event on YouTube. The steps are divided into the following stages:

  1. Set up your broadcast
  2. Claim your content
  3. Test
  4. Broadcast
  5. Conclude your broadcast

Stage 1: Set up your broadcast

Step 1.1: Create your broadcast

Call the liveBroadcasts.insert method to add your broadcast to YouTube's schedule of live events. The liveBroadcast resource that you are inserting must define values for the properties listed below.

Please consider the following guidelines when setting up your broadcast:

  • If you want to have a testing phase for your broadcast, when you can view your video broadcast without other viewers also being able to see the broadcast, you must set the contentDetails.streamDetails.monitorStreamEnabled property to true. (The property's default value is true when you insert a broadcast.)

  • If you want to create a reference from your recorded broadcast, you must set the broadcast's contentDetails.recordFromStart property to true. If you want to make the recorded video available for playback immediately after the broadcast ends, you must also set the contentDetails.enableDvr property to true. (Both of these properties have a default value of true.)

  • You can update any of the contentDetails properties as long as your broadcast's status is still created or ready.

  • You can update the broadcast's scheduled start time and scheduled end time as long as the broadcast's status is created, ready, or testing.

  • The broadcast's title, description, and privacy status, and other metadata fields that are part of the broadcast's video resource, can be updated at any time.

    Note: If you only want your video to be available to specific YouTube users, set the status.privacyStatus property value to either unlisted or private as appropriate to your needs.

Processing the API response

When you insert the broadcast, the API response will contain the liveBroadcast resource that you created. Your code should extract and store the id from that resource as you will need that value to identify the broadcast in future API requests. (You can also identify the video resource that corresponds to the liveBroadcast resource using the same ID.)

Step 1.2: Create your stream

A liveStream resource enables you to transmit your video to YouTube, and it describes the content that you are transmitting. Each broadcast can be and needs to be associated with exactly one stream.

Call the liveStreams.insert method to create the video stream for your event. When creating your stream, you must set values for the properties listed below. Note that these values cannot be updated after the stream is created. (If you need to change them, then you actually need to create a different stream, a process which is explained later in this document.)

You can also set a value for the snippet.description property when creating your stream. The stream's title and description can both be updated, and neither value is visible to YouTube users.

When you insert the stream, the API response will contain the liveStream resource that you created. Your code should extract and store the id from that resource as you will need that value to identify the stream in future API requests.

Step 1.3: Bind your broadcast to its stream

Having created your liveBroadcast and liveStream resources, you now need to associate the two using the liveBroadcasts.bind method. This action links the video that you will transmit to YouTube to the broadcast that the video is for.

In calling the liveBroadcasts.bind method, set the id parameter to the broadcast ID obtained in step 1.1 and the streamId parameter to the stream ID obtained in step 1.2

Stage 2: Claim your content

If you would like to show ads during your broadcast, you will need to claim the broadcast video before the event begins. The following steps explain this process. Note that all of the API calls discussed in this stage are defined in the YouTube Content ID API.

Step 2.1: Create an asset

An asset resource represents a piece of intellectual property. In this case, the asset is your broadcast. Call the assets.insert method to create your asset.

The API response will contain the asset resource that you created. Your code should extract and store the id from that resource as you will need that value to identify the asset in future API requests.

Step 2.2: Define your ownership of the asset

An asset's ownership data identifies an asset's owners as well as the territories where they own the asset. YouTube uses this data to determine where an owner can set the policy for a claimed video.

For example, if you have the right to broadcast an event in the United States, and another broadcaster owns the same rights for Canada, then you can each define different policies for the broadcast video and for user-uploaded videos that match the broadcast video. Your match policy will apply to matching user-uploaded videos in the United States, while the other owner's policy will apply to matching videos in Canada.

To define your ownership territories for the asset, call the ownership.update method. In that request, set the assetId parameter to the id that you stored in step 2.1.

Step 2.3: Set the asset's match policy

An asset's match policy explains what YouTube should do when a user uploads a video that matches a reference associated with the asset. In this case, the match policy will indicate how YouTube should handle an uploaded video that matches your live broadcast.

Note: You should set a match policy if you plan to create a reference from your broadcast video and use that reference to identify user-uploaded videos that match your broadcast. Otherwise, you can skip this step.

To set the match policy, you first need to identify the policy that you want to apply. You can retrieve a list of existing policies by calling the policies.list method, or you can define a new policy by calling the policies.insert method. In either case, you need to capture the id of the policy you want to apply.

Once you have identified the policy, call the assetMatchPolicy.update method. In that request, set the assetId parameter to the id that you stored in step 2.1.

Step 2.4: Claim your video

In this step, you create a claim, which links the video that you will broadcast to the asset that you created in step 2.1. The claim sets a policy that applies only to your broadcast video. (User-uploaded videos that match your broadcast video are covered by the match policy set in the previous step.)

To create a claim, call the claims.insert method. In the claim resource that you insert, you need to set values for the following properties:

  • assetId – You obtained this value in step 2.1.
  • videoId – This is the broadcast ID that you obtained in step 1.1.
  • policy – This is a policy resource. You can apply an existing policy by setting that resource's id property to the existing policy's ID. The previous step explains how to retrieve the ID of an existing policy.
  • contentType – Set this value to audiovisual.

Processing the API response

When you insert the claim, the API response will contain the claim resource that you created. Your code should extract and store the id from that resource. You will use that value later to create a reference from your processed video.

Step 2.5: Update the ad settings for the broadcast

You need to set the advertising options for your video if you want to either run a preroll ad when viewers start to watch your broadcast or run ads during breaks in your broadcast.

  • If you enable preroll ads for your broadcast, then all viewers will see an ad when they start to watch your broadcast even if they start watching in the middle of the broadcast.

  • If you enable midroll ads for your broadcast, then you will be able to insert ad cuepoints during the broadcast.

To enable ads, call the videoAdvertisingOptions.update method. In your request, set the videoId parameter to the broadcast id that you obtained in step 1.1. Use the videoAdvertisingOption resource's adFormats[] property to identify the ad formats (preroll, midroll, or postroll) that you want to enable.

Stage 3: Test

During this stage, you embed a player that shows the monitor stream for your broadcast so that you can test the viewing experience. The monitor stream is a private stream that lets you preview the broadcast video as it would appear to YouTube viewers. Note that you can only test your video broadcast if its monitor stream is enabled.

By default, broadcasts' monitor streams are enabled. You can disable a broadcast's monitor stream by setting the contentDetails.monitorStream.enableMonitorStream property to false when creating or updating that broadcast.

Step 3.1: Embed a monitor stream player

Retrieve your broadcast using the liveBroadcasts.list method, and extract the value of the contentDetails.streamDetails.monitorStreamEmbedHtml property. That value contains the HTML that you need to embed a YouTube player that shows your monitor stream.

Step 3.2: Start your video

Start transmitting video on your video stream.

Step 3.3: Confirm your video stream is active

Call the liveStreams.list method to retrieve the liveStream resource associated with your broadcast. Confirm that the status.streamStatus property's value is active, which indicates that YouTube servers are receiving data from your encoder correctly.

Step 3.4: Transition your broadcast's status to testing

Call the liveBroadcasts.transition method to update the broadcast's status. Set the id parameter value to the broadcast ID obtained in step 1.1, and set the broadcastStatus parameter value to testing.

After you call the liveBroadcasts.transition method, it may take several seconds, or even up to a minute, for that transition to complete. During that time, you should poll the API to check the broadcast's status. Until the transition is complete, the broadcast's status will be testingStarting.

Step 3.5: Completing your testing

If your test went smoothly, you can jump ahead to stage 4. However, in some cases, you might need to do further testing. For example, if your testing revealed that the video stream was not configured correctly, you would need to remedy that before proceeding with your broadcast.

If the video stream is not configured correctly, then you need to unbind (and delete) the existing stream and create a new stream. As an example, a stream might not be configured correctly if it specifies the wrong video format.

  1. To unbind the video stream, call the liveBroadcasts.bind method from step 1.3. In the API request, set the id parameter to the id obtained in step 1.1. Do not include the streamId parameter in the request.

  2. To delete the video stream, call the liveStreams.delete method. In the request, set the id parameter to the id obtained in step 1.2.

  3. Repeat step 1.2 to create a new, properly configured liveStream resource. Then repeat step 1.3 to bind the new stream to your broadcast and steps 3.1 to 3.3 to test the new stream.

Stage 4: Broadcast

During this stage, your broadcast video is viewable to your audience.

Step 4.1: Transition your broadcast's status to live

Important: This step makes your video visible to your audience.

Call the liveBroadcasts.transition method to update the broadcast's status. Set the id parameter value to the broadcast ID obtained in step 1.1, and set the broadcastStatus parameter value to live.

After you make this API call, it may take several seconds, or even up to a minute, for that transition to complete. During that time, you should poll the API to check the broadcast's status. Until the transition is complete, the broadcast's status will be liveStarting. The status will be live once the transition is complete, and viewers will be able to watch your broadcast from that point in your monitor stream.

Note the following effects of this command:

  • If you have enabled the monitor stream for your broadcast – see step 3.1 – you will be able to see the monitor stream in an embedded player.

  • If you had set a value for the broadcast's contentDetails.streamDetails.broadcastStreamDelayMs property, the broadcast stream, which is visible to other viewers, will be delayed by that amount of time.

  • If you had set the broadcast's contentDetails.startWithSlate property to true, then the API will display an in-stream slate in your broadcast stream.

Step 4.2: Remove the slate image

This step is only applicable to your broadcast if you had set the broadcast's contentDetails.startWithSlate property to true. In that case, viewers see a static image when you start your broadcast, and you need to remove that slate to make your broadcast video visible.

You can remove the slate image by calling the liveBroadcasts.control method and setting the displaySlate query parameter to false. You can also remove the slate through the Live Control Room for your broadcast on the YouTube website, which will be available at the following URL:

http://www.youtube.com/live_event_analytics?v=Broadcast_ID

Note: If you do start your broadcast with a slate, you could move step 4.1 earlier in the broadcasting life cycle, in which case viewers would see the static logo for a longer period of time while you complete the other prerequisite steps.

Step 4.3: Insert ads and slates into your broadcast

During your broadcast, you can insert ad breaks into your live broadcast. If you are inserting an ad break, you are encouraged to also display a slate at the same time. This approach provides you with the most control over the time that the broadcast break ends and, consequently, over the time that viewers are returned to your live broadcast.

The instructions below follow this recommendation, though you can insert an ad break without enabling a slate to display. See the Getting started guide for more information about the ways that ad breaks and slates affect the viewing experience.

These steps can be repeated if you have multiple breaks in your broadcast.

Step 4.3.1: Display a slate

To display a slate in place of your broadcast stream, call the liveBroadcasts.control method. In your request, set the displaySlate parameter's value to true. You can also set a time offset to indicate that the slate should start to display at a certain time as discussed in the Getting started guide.

After you enable the slate to display, viewers will see a slate instead of your live broadcast stream.

Step 4.3.2: Insert an ad cuepoint

To insert an ad break, call the liveCuepoints.insert method. In the liveCuepoint resource provided in the request body, set the settings.cueType property to ad and the settings.durationSecs property to the length of the ad (in seconds) that you want to show.

At this time, an ad plays in the video player for any viewers who were watching the broadcast when the ad cuepoint was inserted. When the ad ends, those viewers will again see the slate inserted in step 4.3.1. As such, you can anticipate that viewers will see the slate N seconds after the start of the ad, where N is the value that you provided for the settings.durationSecs property when inserting the cuepoint.

Note: Viewers who refresh the page where the broadcast is playing after the ad begins will see the slate from step 4.3.1 when the page reloads. Similarly, viewers who start watching the broadcast after the cuepoint was inserted will also only see the slate.

Step 4.3.3: Return to your live broadcast

When you are ready to return viewers to your live broadcast, disable the slate that you enabled in step 4.3.1. To do so, call the liveBroadcasts.control method and set the displaySlate request parameter to false.

Stage 5: Conclude your broadcast

Step 5.1: Transition your broadcast's status to complete

When you are ready to stop broadcasting, call the API's liveBroadcasts.transition method to update the broadcast's status. Set the id parameter value to the broadcast ID obtained in step 1.1, and set the broadcastStatus parameter value to complete.

If you had set the broadcast's contentDetails.enableArchive and contentDetails.enableDvr properties to true, then when the live event ends, your audience can immediately watch the live event playback.

Step 5.2: Stop streaming

This concludes your test of the YouTube live broadcast system.

Stage 6: Create a reference

Once the live recording is complete, you can create a reference from the recorded video. This action instructs YouTube to look for user-uploaded videos that match the broadcast and handle them according to the match policy that you set in step 2.3.

Important: To create the reference, you must have set the broadcast's contentDetails.recordFromStart property to true.

Step 6.1: Poll the Data API for the video's status

YouTube must finish processing a broadcast or uploaded video before you can create a reference from that video. To determine whether the video has finished processing, poll the YouTube Data API's videos.list method, setting the part parameter to status and the id parameter to the broadcast ID that you stored in step 1.1.

The API response to your polling request will contain a video resource. When the value of that resource's status.uploadStatus property is processed, proceed to step 6.2.

Step 6.2: Create a reference from the processed video

To create your reference, call the Content ID API's references.insert method and set the claimId parameter to the claim ID that you stored in step 2.4.

Live Content ID Delivery

Some YouTube partners are able to create a reference before their broadcast transitions to the testing state, but that feature is not available to all partners. In that flow, YouTube generates and continually updates the reference from your live event's broadcast stream while the broadcast in in progress. In addition, YouTube looks for matching user-uploaded videos while the broadcast is still in progress. Note that creating a reference before a broadcast begins automatically turns recording on for the broadcast, and recording cannot be turned off after the reference is created.

To enable your broadcast for live Content ID delivery, attempt the actions described in step 6.2 after claiming your video in step 2.4. If your partner account has not been approved to create a reference for a live broadcast before that broadcast occurs, the API will return a fingerprintingNotAllowed error. In that case, you need to wait until your broadcast is complete, as described in steps 6.1 and 6.2 above, before creating the reference.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.