LiveBroadcasts

A liveBroadcast resource represents an event that will be streamed, via live video, on YouTube.

Methods

The API supports the following methods for liveBroadcasts resources:

list: Returns a list of YouTube broadcasts that match the API request parameters. Try it now.
insert: Creates a broadcast. Try it now.
update: Updates a broadcast. For example, you could modify the broadcast settings defined in the liveBroadcast resource's contentDetails object. Try it now.
delete: Deletes a broadcast. Try it now.
bind: Binds a YouTube broadcast to a stream or removes an existing binding between a broadcast and a stream. A broadcast can only be bound to one video stream, though a video stream may be bound to more than one broadcast. Try it now.
transition: Changes the status of a YouTube live broadcast and initiates any processes associated with the new status. For example, when you transition a broadcast's status to testing, YouTube starts to transmit video to that broadcast's monitor stream. Before calling this method, you should confirm that the value of the status.streamStatus property for the stream bound to your broadcast is active. Try it now.
control: Controls the settings for a slate that can be displayed in the broadcast stream. Try it now.

Resource representation

The JSON structure below shows the format of a liveBroadcasts resource:

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string
  },
  "contentDetails": {
    "boundStreamId": string,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "enableContentEncryption": boolean,
    "startWithSlate": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean
  }
}

Properties

The following table defines the properties that appear in this resource:

Property name	Value	Description
`kind`	`string`	Identifies the API resource's type. The value will be `youtube#liveBroadcast`.
`etag`	`etag`	The Etag of this resource.
`id`	`string`	The ID that YouTube assigns to uniquely identify the broadcast.
`snippet`	`object`	The `snippet` object contains basic details about the event, including its title, description, start time, and end time.
`snippet.publishedAt`	`datetime`	The date and time that the broadcast was added to YouTube's live broadcast schedule. The value is specified in ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) format.
`snippet.channelId`	`string`	The ID that YouTube uses to uniquely identify the channel that is publishing the broadcast.
`snippet.title`	`string`	The broadcast's title. Note that the broadcast represents exactly one YouTube video. You can set this field by modifying the broadcast resource or by setting the `title` field of the corresponding video resource.
`snippet.description`	`string`	The broadcast's description. As with the `title`, you can set this field by modifying the broadcast resource or by setting the `description` field of the corresponding video resource.
`snippet.thumbnails`	`object`	A map of thumbnail images associated with the broadcast. For each nested object in this object, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail.
`snippet.thumbnails.(key)`	`object`	Valid key values are: `default` – The default thumbnail image. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall. `medium` – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall. `high` – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
`snippet.thumbnails.(key).url`	`string`	The image's URL.
`snippet.thumbnails.(key).width`	`unsigned integer`	The image's width.
`snippet.thumbnails.(key).height`	`unsigned integer`	The image's height.
`snippet.scheduledStartTime`	`datetime`	The date and time that the broadcast is scheduled to start. The value is specified in ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) format.
`snippet.scheduledEndTime`	`datetime`	The date and time that the broadcast is scheduled to end. The value is specified in ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) format. If a `liveBroadcast` resource does not specify a value for this property, then the broadcast is scheduled to continue indefinitely. Similarly, if you do not specify a value for this property, then YouTube treats the broadcast as if it will go on indefinitely.
`snippet.actualStartTime`	`datetime`	The date and time that the broadcast actually started. This information is only available once the broadcast's state is `live`. The value is specified in ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) format.
`snippet.actualEndTime`	`datetime`	The date and time that the broadcast actually ended. This information is only available once the broadcast's state is `complete`. The value is specified in ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) format.
`status`	`object`	The `status` object contains information about the event's status.
`status.lifeCycleStatus`	`string`	The broadcast's status. The status can be updated using the API's `liveBroadcasts.transition` method. Valid values for this property are: `abandoned` – This broadcast was never started. `complete` – The broadcast is finished. `created` – The broadcast has incomplete settings, so it is not ready to transition to a `live` or `testing` status, but it has been created and is otherwise valid. `live` – The broadcast is active. `liveStarting` – The broadcast is in the process of transitioning to `live` status. `ready` – The broadcast settings are complete and the broadcast can transition to a `live` or `testing` status. `reclaimed` – This broadcast has been reclaimed. `revoked` – This broadcast was removed by an admin action. `testStarting` – The broadcast is in the process of transitioning to `testing` status. `testing` – The broadcast is only visible to the partner.
`status.privacyStatus`	`string`	The broadcast's privacy status. Note that the broadcast represents exactly one YouTube video, so the privacy settings are identical to those supported for videos. In addition, you can set this field by modifying the broadcast resource or by setting the `privacyStatus` field of the corresponding video resource. Valid values for this property are: `private` `public` `unlisted`
`status.recordingStatus`	`string`	The broadcast's recording status. Valid values for this property are: `notRecording` `recorded` `recording`
`contentDetails`	`object`	The `contentDetails` object contains information about the event's video content, such as whether the content can be shown in an embedded video player or if it will be archived and therefore available for viewing after the event has concluded.
`contentDetails.boundStreamId`	`string`	This value uniquely identifies the `live stream` bound to the broadcast.
`contentDetails.monitorStream`	`object`	The `monitorStream` object contains information about the monitor stream, which the broadcaster can use to review the event content before the broadcast stream is shown publicly.
`contentDetails.monitorStream.enableMonitorStream`	`boolean`	This value determines whether the monitor stream is enabled for the broadcast. If the monitor stream is enabled, then YouTube will broadcast the event content on a special stream intended only for the broadcaster's consumption. The broadcaster can use the stream to review the event content and also to identify the optimal times to insert cuepoints. You need to set this value to `true` if you intend to have a `testing` stage for your broadcast or if you want to have a broadcast delay for your event. In addition, if this property's value is `true`, then you must transition your broadcast to the `testing` state before you can transition it to the `live` state. (If the property's value is `false`, your broadcast cannot have a `testing` stage, so you can transition the broadcast directly to the `live` state.) When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `true`. Important: This property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.monitorStream.broadcastStreamDelayMs`	`unsigned integer`	If you have set the `enableMonitorStream` property to `true`, then this property determines the length of the live broadcast delay. When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `0`. This value indicates that the broadcast does not have a broadcast delay. Note: This property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.monitorStream.embedHtml`	`string`	HTML code that embeds a player that plays the monitor stream.
`contentDetails.enableEmbed`	`boolean`	This setting indicates whether the broadcast video can be played in an embedded player. If you choose to archive the video (using the `enableArchive` property), this setting will also apply to the archived video. When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `true`. Note: This property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.enableDvr`	`boolean`	This setting determines whether viewers can access DVR controls while watching the video. DVR controls enable the viewer to control the video playback experience by pausing, rewinding, or fast forwarding content. The default value for this property is `true`. When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `true`. Important: You must set the value to `true` and also set the `enableArchive` property's value to `true` if you want to make playback available immediately after the broadcast ends. In addition, this property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.enableContentEncryption`	`boolean`	This setting indicates whether YouTube should enable content encryption for the broadcast. When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `false`. Note: This property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.startWithSlate`	`boolean`	This setting indicates whether the broadcast should automatically begin with a slate when you update the broadcast's status to `live`. After updating the status, you then need to send a `liveCuepoints.insert` request that sets the cuepoint's `eventState` to `end` to remove the slate and make your broadcast stream visible to viewers. When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `false`. Note: This property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.recordFromStart`	`boolean`	This setting indicates whether YouTube will automatically start recording the broadcast after the event's status changes to live. This property's default value is `true`, and it can only be set to `false` if the broadcasting channel is allowed to disable recordings for live broadcasts. If your channel does not have permission to disable recordings, and you attempt to insert a broadcast with the `recordFromStart` property set to `false`, the API will return a `Forbidden` error. In addition, if your channel does not have that permission and you attempt to update a broadcast to set the `recordFromStart` property to `false`, the API will return a `modificationNotAllowed` error. When you `update a broadcast`, this property must be set if your API request includes the `contentDetails` part in the `part` parameter value. However, when you `insert a broadcast`, the property is optional and has a default value of `true`. Important: You must also set the `enableDvr` property's value to `true` if you want the playback to be available immediately after the broadcast ends. If you set this property's value to `true` but do not also set the `enableDvr` property to `true`, there may be a delay of around one day before the archived video will be available for playback. Note: This property cannot be updated once the broadcast is in the `testing` or `live` state.
`contentDetails.enableClosedCaptions`	`boolean`	This setting indicates whether closed captioning is enabled for this broadcast. The `liveStream` resource that is bound to the broadcast contains the ingestion URL for the broadcast's closed captions. Note: This property can only be updated if the broadcast's status is `created` or `ready`.

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.

Last updated August 21, 2014.