This document explains how to use the HLS (HTTP Live Streaming) protocol to
stream live data on YouTube from an encoder. This document is intended for
encoder vendors who want to add HLS ingestion support to their products. HLS
ingestion is a good choice for premium content that requires high
quality and high resolution at a relatively higher latency. See
this document
for a brief comparison of different ingestion protocols that YouTube Live
Streaming supports.
To stream live data via HLS, the encoder should send a series of Media Playlists
and Media Segments to YouTube's HLS endpoint via
HTTP PUT
or
POST
requests.
From the encoder's perspective, the YouTube HLS endpoint appears to be a passive
HTTP server.
Each Media Segment represents the actual multimedia content for a brief portion
of the stream lasting between one and four seconds. Each Media Playlist
describes how to reassemble the Media Segments in correct stream order.
YouTube HLS ingestion has the following requirements for video and audio
content:
- Video and audio must be muxed in M2TS format.
- Supported video codecs are H.264 and HEVC.
- Frame rates up to 60fps are supported.
- Only closed GOP is supported.
- The supported audio codec is AAC, and only single-track audio is supported.
See more detailed requirements on
Media Segments
below.
HDR
High Dynamic Range (HDR) video is supported via the HEVC codec and has the
following additional requirements:
- Supported color standards are 10-bit PQ and HLG with non-constant luminance.
More specifically:
- Chroma format must be YUV 4:2:0 10-bit.
- Transfer function must be PQ (a.k.a. SMPTE ST 2084) or HLG
(a.k.a. ARIB STD-B67).
- Color primaries must be Rec. 2020.
- Matrix coefficients must be Rec. 2020 non-constant luminance.
- Both limited-range (or MPEG-range) and full-range (or JPEG-range) sample
values are supported. It is important that the range is set according to the
sample value range that the content uses. Limited-range sample values are
recommended.
Obtaining an HLS Ingestion URL
Obtaining an HLS Ingestion URL from the YouTube API
To obtain the full ingestion URL, encoders can use the
YouTube Live Streaming
API
to
insert a liveStream
resource
with the following
properties:
"cdn": {
"ingestionType": "hls",
"frameRate": "variable",
"resolution": "variable"
}
In the API response, the
cdn.ingestionInfo.ingestionAddress
field specifies
the primary ingestion URL, and
cdn.ingestionInfo.backupIngestionAddress
field
specifies the backup ingestion URL. For more details, see the documentation for
the
liveStreams
resource
.
Obtaining an HLS Ingestion URL from YouTube Creator Studio
In the
YouTube Creator Studio web interface
, after the creator clicks "Create
Stream", YouTube displays a "Stream Key" consisting of alphanumeric
characters and hyphens. This secret key identifies both the creator and the
stream to YouTube.
You can construct an HLS URL from this stream key, as follows:
https://a.upload.youtube.com/http_upload_hls?cid=$STREAM_KEY©=0&file=
... where
$STREAM_KEY
is the Stream Key displayed in the web interface.
For example:
https://a.upload.youtube.com/http_upload_hls?cid=abcd-efgh-ijkl-mnop-qrst©=0&file=
For added reliability, you can transmit a redundant second copy of the ingestion
to this backup URL:
https://b.upload.youtube.com/http_upload_hls?cid=$STREAM_KEY©=1&file=
Note the backup has two differences from the primary URL: both the hostname
and the
copy=
parameter have changed. The backup ingestion
must
send
a different
copy=
parameter value than the primary ingestion to avoid
corrupting the stream.
Completing the HLS Ingestion URL
URLs obtained via either method above are incomplete templates; each ends
with an empty
file=
query parameter. To form the final URL, the encoder must
append the filename of a Media Playlist or Media Segment to the end of the URL,
thus completing the
file=
parameter.
The following rules apply to the
file=
parameter's value:
- The encoder may construct a Media Playlist or Media Segment filename from
alphanumeric characters, underscores, forward slashes, hyphens, and periods;
no other characters are supported.
- The encoder must not URL-encode the filename.
- The encoder may include relative or absolute path components in filenames,
though this is never required. If the encoder includes a path component
within a Media Segment filename, it must reference the same path in the
corresponding playlist entry.
HLS Protocol Requirements
The Media Playlists and the Media Segments sent by the encoder must conform to
the
HTTP Live Streaming 2nd Edition
Specification
.
The HLS specification defines two types of playlist: Media Playlist and Master
Playlist. Since YouTube transcodes streamed content to different resolutions and
bitrates, the encoder does not need to send content with different bitrates to
YouTube. As a result, YouTube supports only Media Playlists for HLS ingestion,
and Master Playlists are ignored. (A Master Playlist provides a set of Variant
Streams, each of which describes a different version of the same content.)
The encoder must:
- send exactly one encoded stream with the highest resolution that you want to
serve to users (single resolution and codec)
- mux audio and video
- use HTTPS and a persistent connection for all requests
The following sections contain more specific requirements for Media Playlists
and Media Segments.
A Media Playlist contains a list of Media Segments that can be concatenated to
represent a continuous, decodable multimedia stream. The Media Playlist tells
the server which Media Segments to expect and how to order them properly in the
reassembled stream.
Requirements
The Media Playlist file name must end with either
.m3u8
or
.m3u
.
The first Media Playlist sent for a stream must start at sequence number
0
and the sequence number must increase monotonically.
The
EXT-X-MEDIA-SEQUENCE
tag must identify the sequence number of the
first Media Segment listed in the playlist.
A Media Playlist must not contain more than five outstanding segments. A
segment is outstanding if the server has not received it or acknowledged
receipt of it.
In addition to the outstanding segments, also include a few acknowledged
segments in each Media Playlist. This practice makes it less likely for a
segment to be skipped if a Media Playlist is lost on the server side. For
example, you could include up to two acknowledged segments and up to five
outstanding segments in each Media Playlist.
Note that the server acknowledges receipt of a Media Segment by returning a
200
(
OK
) or
202
(
Accepted
) response on the upload of that segment. A
202
response indicates that the server received the segment before a
playlist identifying that segment.
Send an updated Media Playlist for
every
Media Segment so that the
server can recover quickly if a Media Playlist is lost.
As the server acknowledges receipt of Media Segments, you can increment the
EXT-X-MEDIA-SEQUENCE
tag value to prevent the Media Playlist from becoming
too long. For example, if the server has already acknowledged receipt of the
first nine Media Segments, the next Media Playlist might list the eighth,
ninth, and tenth Media Segments.
EXT-X-KEY
and
EXT-X-SESSION-KEY
tags are not supported.
Examples
The list below shows an example of the files that the encoder is expected to
send:
Media Playlist file with seqnum #0
Media Segment file #0
Media Playlist file with seqnum #0-#1
Media Segment file #1
Media Playlist file with seqnum #0-#2
Media Segment file #2
Media Playlist file with seqnum #1-#3
Media Segment file #3
...
The following example shows a Media Playlist sent in the middle of a live video
stream. Since the example is from the middle of a stream, the
EXT-X-MEDIA-SEQUENCE
tag has a nonzero value.
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:4
#EXT-X-MEDIA-SEQUENCE:2680
#EXTINF:3.975,
fileSequence2680.ts
#EXTINF:3.941,
fileSequence2681.ts
#EXTINF:3.975,
fileSequence2682.ts
The list below identifies requirements for Media Segments:
- Filenames
- Media Segment file names in the URL must have the
.ts
filename
extension and must match the filenames in the playlist.
- Media Segment file names must be unique across encoder reboots and
stream restarts.
- Format
- Media Segments must be in M2TS format and should be self-initializing.
- Each M2TS Segment must contain a single MPEG-2 Program.
- The M2TS Segment must contain a PAT and a PMT, and the first two
Transport Stream packets in a Segment should be a PAT and a PMT.
- Content
- Video and audio must be muxed.
- Supported video codecs are H.264 and HEVC.
- HDR with HEVC is supported (see
HDR requirements
).
- Frame rates up to 60fps are supported.
- Only closed GOP is supported.
- The supported audio codec is AAC, and only single-track audio is
supported.
- Media Segments are recommended to have a duration between one and four
seconds, as discussed in the following section. Media Segments must not
have a duration longer than 5 seconds.
- Media segments must only be encrypted in the TLS/SSL layer with HTTPS.
Other encryption mechanisms are not supported.
We expect HLS ingestion to be used for premium content that requires high
quality and high resolution. HLS ingestion usually has higher latency than RTMP-
and WebRTC-based ingestions because HLS ingestion is segment-based.
We recommend a Media Segment duration of one to four seconds because having
smaller Media Segments can result in lower latency, albeit at a cost of a higher rebuffer rate and lower encoding efficiency. As noted in the previous section, Media Segments must not be longer than 5 seconds.
Bitrates
The
YouTube Help
Center
provides guidelines for bitrate settings.
Note that HEVC generally yields 25% to 50% more data compression at the same
video quality compared to H.264. As such, bitrate values in the lower end of the
suggested ranges can be used with HEVC to save bandwidth, which is especially
useful for 4K content.
Other Requirements
Encoders should set the
User-Agent
header in the HTTP request using the
following syntax, which includes the manufacturer's name, model name, and
version:
User-Agent: <manufacturer> / <model> / <version>
Closed captions
HLS ingestion supports two options for sending closed captions:
- Send closed captions via separate HTTP POST requests. This works for all HLS
ingestions.
- Embedded 608/708 closed captions work with HLS ingestions that use the H264
video codec but not with ingestions that use the HEVC video codec. See the
Live Caption
Requirements
in the
YouTube Help Center for more details.
HTTP response codes
The following sections explain the response codes that YouTube returns in
response to Media Segments and Media Playlists delivered via HLS.
- 200 (OK)
In response to a PUT or POST request, an HTTP 200 (OK) response indicates
that the YouTube server received an expected operation and handled it
successfully.
In response to a DELETE request, an HTTP 200 (OK) response indicates that
the YouTube server received and ignored the request. The YouTube server does
not require the client to DELETE any resource in the stream, and it ignores
DELETE requests. For performance reasons, YouTube recommends clients
do not send DELETEs.
- 202 (Accepted)
An HTTP 202 (Accepted) response indicates that the YouTube server received the
Media Segment before receiving a Media Playlist containing that Media Segment.
This indicates to the client that it should send the Media Playlist containing
that Media Segment as soon as possible to prevent a delay in processing that
segment. Note that this will not be an issue if the encoder sends an updated
Media Playlist for every Media Segment.
- 400 (Bad Request)
An HTTP 400 (Bad Request) response indicates one of the following problems
occurred:
- The URL is malformed
- The Playlist cannot be parsed or contains unsupported tags
- 401 (Unauthorized)
An HTTP 401 (Unauthorized) response indicates that the cid parameter in the
base URL for the YouTube HLS endpoint is corrupted or expired. The client
should update the
cid
parameter in order to proceed.
- 405 (Method Not Allowed)
An HTTP 405 (Method Not Allowed) response indicates that the request was
not a POST, PUT, or DELETE request.
- 500 (Internal Server Error)
An HTTP 500 (Internal Server Error) response indicates that the server was
unable to process the request. For this error, we recommend that you retry the
request with
exponential
backoff
.