Overview
This guide is intended for developers of API client applications that use
YouTube channels' default
liveStream
and
liveBroadcast
resources to stream
live content. It aims to help you ensure that your application gracefully
handles the deprecation of default broadcasts and default streams, and it is
relevant for you if any of the following statements apply to your application:
If your application is affected, please refer to the
Updating your
application
section, which explains the procedural
changes your application might need to make as a result of this deprecation.
That section identifies specific steps in the
Life of a broadcast
guide that your API client might not
typically follow if it currently uses the default broadcast and stream.
What is happening?
Since 2015, YouTube has automatically created a default stream and a default
broadcast for a channel when that channel was enabled for live streaming. The
default stream existed indefinitely and could not be deleted. Similarly, the
default broadcast was considered
persistent
. It always existed, did not have a
start or end time associated with it, and was not bound to a particular event.
As of the deprecation date mentioned above, YouTube will no longer create
default streams and broadcasts. This change affects client applications that
rely on those resources to broadcast live content. It will also affect
applications in which the user interface is customized to differentiate between
those default resources and other broadcasts and streams that channel owners
have created.
Instead of relying on the default resources, API clients need to create and
manage
liveBroadcast
and
liveStream
resources and to bind those resources
together.
Updating your application
To quickly review terminology, a
broadcast
represents an event that can be
watched on YouTube as it happens, and a
stream
is the mechanism for sending
the actual video content to YouTube. A broadcast can be and needs to be bound to
exactly one stream.
Migrating from default broadcasts
Prior to this deprecation, API clients could choose between using a channel's
default broadcast or creating an event-specific broadcast. The default broadcast
was a persistent resource that could be reused for multiple events, while an
event-specific broadcast resource is a single-use resource that corresponds to
exactly one YouTube video.
Your client application uses the default broadcast if it calls the
liveBroadcasts.list
method and does either of the following:
- It sets the
broadcastType
parameter value to
persistent
. This request only retrieves the default
broadcast.
- It sets the
broadcastType
parameter value to
all
, then identifies the
liveBroadcast
resource in
the API response for which the
isDefaultBroadcast
property's value is
true
.
Following the deprecation, YouTube will only support event-specific broadcasts.
This means that instead of relying on the default broadcast, client applications
need to create
liveBroadcast
resources
for each individual broadcasting event.
To create a
liveBroadcast
resource, call the
liveBroadcasts.insert
method.
This process is explained in
step 1.1 of the "Life of a broadcast" guide
.
If it does not do so already, your user interface also needs to provide
mechanisms for users to distinguish and select between upcoming event-specific
broadcasts.
Migrating from default streams
A stream enables you to transmit audio-video content to YouTube, and it defines
the settings for how you stream your content to YouTube. It is common for
broadcasters to reuse the same stream for many different broadcasts if those
broadcasts occur at different times.
Even though your application can't use the default stream, it can create a
reusable stream that can be reused for each broadcast. To create a
liveStream
resource, call the
liveStreams.insert
method, following the instructions in
step 1.2 of the "Life of a broadcast"
guide
. By
default, newly created streams are reusable. However, if you prefer, you can set the
contentDetails.isReusable
property to
false
to create single-use streams and have a one-to-one
relationship between broadcasts and streams.
The following list contains the four properties, besides the
stream title
and
stream description
,
that you can set when creating a new stream. The list shows the values that
default streams use for each property, which are likely the settings you would
want to use in a client application if you're migrating away from using default
streams.
Binding broadcasts to streams
Each
liveBroadcast
resource must be bound to exactly one stream before the
live broadcast on YouTube can actually start. (The broadcast is not bound to any
streams at the time that it's created.)
The binding process was handled automatically for the default broadcast, which
was inextricably bound to the default stream. However, after the deprecation
date, client applications need to manage that process for all broadcasts.
To bind a broadcast to a stream, call the
liveBroadcasts.bind
method as
explained in
step 1.3 of the "Life of a broadcast"
guide
.
- If you are using a reusable stream, you can create a stream once and then
bind every broadcast to that stream.
- If you are not using a reusable stream, you need to create a broadcast and a
stream, and then bind those two together.
Testing your broadcast
When you don't use the default broadcast, you have the option to test your
broadcast. To conduct a test, you embed a player that lets you preview the
broadcast video as it would appear to YouTube viewers, but the broadcast is not
visible to other viewers.
If your API client previously used the default broadcast and stream, and you
want to add a testing phase to your streaming process, see
stage 3 of the
"Life of a broadcast" guide
.
If you do want to test your stream, then when you insert a broadcast, you need
to set the
contentDetails.monitorStream.enableMonitorStream
property to
true
and the
contentDetails.enableAutoStart
property to
false
. These are the default values for both properties.
Using the auto-start and auto-stop features
The default broadcast automatically started whenever you started streaming video
on the default stream. Similarly, the default broadcast ended after you stopped
streaming video. Each streaming session using those default resources
subsequently became a video in your channel.
While the auto-start and auto-stop features were the default behavior for
default broadcasts, those features are optional and need to be enabled for other
broadcasts. If you want to use these features, then when you insert a broadcast,
you need to set the
contentDetails.enableAutoStart
and
contentDetails.enableAutoStop
property values to
true
. These features are independent, so you can choose to
use one and not the other.
If you don't enable the auto-start and auto-stop features for new broadcasts,
your API client needs to call the
liveBroadcasts.transition
method to update a broadcast's
status when you start and finish streaming video. In the "Life of a Broadcast"
guide, see
step 4.3
and
step 5.2
for instructions on managing these transitions at the beginning and end of a
broadcast.