Skip to main content

Delivering Live Video via HLS

This document explains how to set up your live HLS (HTTP Live Streaming) protocol used when streaming live video to Twitter's Media Studio and LiveCut services.

 

This article is intended for partners who want Twitter’s infrastructure to ingest live media by pulling from existing live HLS sources. It’s also intended to guide HLS live-streaming service vendors who wish to make their streams interoperate with Twitter’s live HLS ingest feature.


Twitter’s live HLS ingest infrastructure requires that playlists and segments conform to the specifications listed in the HTTP Live Streaming RFC as shown here.

Twitter’s Media Studio HLS Requirements:

 
 

URL Structure & Requirements

When specifying an HLS stream URL in Twitter’s Media Studio, you are specifying a URL to a playlist.

 

 

Playlists Types

A Media Playlist is a listing of media segments in the order that they should be played. For live HLS streams, the list is updated at the server every few seconds with a newly created segment added to the list and the oldest segment removed from the list. We call the segments that appear in the list at a given time the “live window.”

 

A Main Playlist is a list of Media Playlists. The Main Playlist generally contains Media Playlists for several variants of the stream, each encoded at a different bitrate and resolution, allowing a client to adaptively choose a variant appropriate for its display and bandwidth constraints. The Main Playlist might also contain several audio tracks, for example, if multiple languages are supported.

 

Main Playlist Rules

If you provide a Main Playlist, Twitter will automatically select a video variant and, if audio is not multiplexed together with video, audio rendition Media Playlists from your Main Playlist. Twitter’s infra will choose:

 

  • The video variant with highest bitrate and resolution such that the resolution is 720p or lower, unless the only video variants available are above 720p video, where the variant closest to 720p will be chosen.
  • If audio and video are multiplexed together and separate audio renditions are provided, we will use the audio in the chosen video variant. 
  • If multiple AAC audio tracks are provided, we choose the audio track included in the rendition with the highest bandwidth.
 

Media Playlist Rules

Whether you provide a Media Playlist URL directly or you provide a Main Playlist so that Twitter Infrastructure automatically selects Media Playlists from it, Media Playlists need to conform to the following rules:

 

  • The live window (the set of media segments listed in each update of the media playlist) should contain at least five segments and not more than 100 segments. 
  • If the live window is shorter, it’s possible that due to network latencies a segment may leave the window before our infrastructure has a chance to download it. This will cause the broadcast shown on Twitter to skip the portion of your stream corresponding to the missed segment. 
  • If the window is much larger, for example if it is an Event Playlist where the new segments are appended to an ever-growing list, it increases the probability that a failure to download a new version of the playlist will cause an interruption in the stream.

 

Example live Media Playlist with window length three (not recommended):

 

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:5
#EXT-X-MEDIA-SEQUENCE:2680
#EXTINF:5,
https://priv.example.com/fileSequence2680.ts
#EXTINF:5,
https://priv.example.com/fileSequence2681.ts
#EXTINF:5,
https://priv.example.com/fileSequence2682.ts

 

 

Example live Media Playlist with window length five (minimum recommended length)

 

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:5
#EXT-X-MEDIA-SEQUENCE:2680

#EXTINF:5,
https://priv.example.com/fileSequence2680.ts
#EXTINF:5,
https://priv.example.com/fileSequence2681.ts
#EXTINF:5,
https://priv.example.com/fileSequence2682.ts
#EXTINF:5,
https://priv.example.com/fileSequence2683.ts
#EXTINF:5,
https://priv.example.com/fileSequence2684.ts

  • The Media Playlists should show only segments that are multiplexed as M2TS (.ts) files. We do not currently support CMAF.

 

 

Media Segment Requirements and Specifications

 

  • Must be in M2TS (.ts) format. CMAF is not supported.
  • For segments containing video:
    • Must only contain H.264-encoded video
    • Must only contain video encoded with closed GOPs
    • Recommended to have a key frame interval between two and five seconds
    • Recommended to have segment duration between two and five seconds
    • Closed captions (608/708) may be embedded in the video
    • Recommended frame rate is 30fps, though up to 60fps is supported
  • For segments containing audio:
    • Must contain AAC-encoded audio
    • Must contain mono or stereo audio, not multichannel

Note: Please reference the Live Video Specifications for HLS below for additional information about the current recommendations for live broadcasts on Twitter.

 

Closed Caption Requirements

608/708 closed captions must be embedded in the video elementary stream of segments containing H.264 video.

 

Live Video Specifications for HLS

 

Video codec:

 

  • H.264/AVC

 

 

Video bitrate:

 

  • 9Mbps (recommended)
  • 12Mbps (maximum)

 

 

Video resolution:

 

  • 1280x720 (recommended)
  • 1920x1080 (maximum)

 

 

Video frame rate:

 

  • 30 fps (recommended)
  • 60 fps (maximum)

 

 

Keyframe interval:

 

  • 24 fps = Keyframe interval of 72 frames 
  • 30 fps = Keyframe interval of 90 frames
  • 50 fps = Keyframe interval of 150 frames 
  • 60 fps = Keyframe interval of 180 frames

 

 

Audio codec:

 

  • AAC-LC

 

 

Audio bitrate:

 

  • 
128 kbps (maximum)

FAQs

Check the number of media segments set — we expect at least five. If lower than five, you will likely experience skips, or jumps, in your broadcast shown on Twitter and in LiveCut..

Live Broadcasts, our logic is as follows:

  • We ignore variants that don't work for us (bad codecs and too high bitrate).
  • We choose the variant with the highest resolution as long as it's 1280x720 or lower.

For LiveCut, our logic is as follows:

  •  The LiveCut preview window displays a lower quality still and final clips created will be saved at 1280x720 variant.

The live window (the set of media segments listed in each update of the media playlist) should contain at least five segments and not more than 100 segments.

If the live window is shorter, it’s possible that due to network latencies a segment may leave the window before our infrastructure has a chance to download it. This will cause the broadcast on Twitter to skip or stop playing the portion of your stream corresponding to the missed segment(s). Please ensure your media playlist contains a minimum of five segments and not to exceed 100.

Your stream’s HLS audio must be AAC-encoded. The audio must be mono or stereo audio, not multichannel.

HLS URLs must be in a format that more resembles https://your.media.com/live/bigbroadcast.m3u8.

Current Error 1: MALFORMED_URL

"You must enter a valid HLS URL."

What this means:

The HLS URL must start with http or https and end with an .m3u8 or .m3u extension. Your URL will look something like this: https://example.com/playlist.m3u8. At this time we do not support encrypted or tokenized streams. If you are not sure if you have a supported stream, please contact your IT or video production team.

 

Current Error 2: INVALID_SCHEME

"You must enter a valid HLS URL scheme beginning with http or https."

What this means:

The HLS URL must start with http or https and end with an .m3u8 or .m3u extension. Your URL will look something like this: https://example.com/playlist.m3u8. At this time we do not support encrypted or tokenized streams. If you are not sure if you have a supported stream, please contact your IT or video production team.

 

Current Error 3: CONNECTION_FAILURE

"The stream failed to connect."

What this means:

The stream is not accessible due to a connection failure. Ensure the HLS URL is entered correctly in the Source. If you continue to receive this error, please contact the team managing your stream.

 

Current Error 4: CERTIFICATE_VALIDATION_FAILED

"The stream could not be accessed due to certificate validation failure."

What this means:

The stream is not accessible due to a certificate validation failure. Ensure the HLS URL is entered correctly in the Source. If you continue to receive this error, please contact the team managing your stream.

 

Current Error 5: ACCESS_FORBIDDEN

"The stream is not accessible. Please check access restrictions on the stream."

What this means:

The stream is not accessible due to either geo-restrictions or authentication on your stream set by your IT team. If you continue to receive this error, please contact the team managing your stream (error 401 or 403).

 

Current Error 7: NOT_FOUND

"Please ensure the stream is on, and then attempt to create a new broadcast."

What this means:

There is currently no video detected on this stream URL. Ensure the HLS URL is entered correctly in the Source and that it is currently live. If you continue to receive this error, please contact the team managing your stream (error 404).

 

Current Error 8: BAD_PLAYLIST

"There is an issue with the stream."

What this means:

The stream is not accessible due to an issue with the HLS manifest or playlist. If you continue to receive this error, please contact the team managing your stream.

 

Current Errors 6+9:  6: SERVER_ERROR  9: OTHER

"Oops. Something went wrong." This can appear for multiple reasons, either a 500 error or reasons otherwise unknown. We have translated error messages below, but for the time being, please follow these troubleshooting steps and file a ticket so we can get engineering to see if there is a root cause they can fix.

What this error code could mean:

  • There is currently no video detected on this stream URL. Ensure the HLS URL is entered correctly in the Source and that it is currently live. If you continue to receive this error, please contact the team managing your stream (error 500).
  • The stream is not accessible due to a server error. If you continue to receive this error, please contact the team managing your stream (error 500).
  • An unexpected error has occurred. Ensure the HLS URL is entered correctly in the Source and that it is currently live. If you continue to receive this error, please contact the team managing your stream.

Related reads