Debugging HTTP Live Streaming
This document is intended for AVFoundation clients and content owners that are debugging issues when playing HTTP live streaming (HLS) content. For AVFoundation clients, this document provides an overview of the various types of errors that can be encountered during the playback of HLS content as well as an overview of the various facilities for applications to be notified of errors that occur during the playback process from the AVPlayer. For contents owners, this document provides useful information about verifying HLS content against the HTTP Live Streaming Authoring Specification for Apple Devices. This document also provides links to helpful resources and tools available for AVFoundation clients and content owners to use during debugging as well as best practices that lead to better playback experience.
Debugging HTTP Live Streaming
HTTP Live Streaming (HLS) reliably delivers media content across a variety of network and bandwidth conditions. This document discusses best practices for handling errors during playback of HLS content with AVFoundation.
Types of Errors Encountered During Playback
When an AVPlayer encounters an error during playback, the type of error typically falls into one of the following categories:
Network Errors:
All the 4XX and 5XX errors that are sent from the server as well as TCP/IP and DNS errors.
With regards to 4XX and 5XX errors, it is important to make sure that when your server encounters these errors that it sends an error that AVFoundation expects. This ensures that AVFoundation handles these errors in such a way that alternate playback options such as backup sources or lower bitrate variants are used if they are available and playback can continue smoothly.
For more information about how your server should be handling and returning errors see the following video:
Timeout Errors:
When resources such as the master playlist, media playlists, media files and content keys are requested there are timeouts defined. A failure to get a response within this timeout will cause timeout errors.
Format Errors:
Format errors occur when an incorrect format is used for the playlist, key or session data. If you are encountering this class of error, see the "Verifying Content" section below.
Live Playlist Update Errors:
In the case of a live stream, playlists need to be updated according to the published target duration and failure to update in time will result in a live playlist update error.
Discovering Errors
The AVFoundation framework provide several facilities for applications to be notified of errors that occur during the playback process from the AVPlayer.
Getting Notified When Errors Occur
To be notified of when an error occurs, the AVFoundation client or app should register for Key-Value Observing (KVO) on the AVPlayer.status and AVPlayer.currentItem.status properties. If an error occurs at any point during the playback process, the values of these properties will change to AVPlayerStatus.failed and AVPlayerItemStatus.failed respectively. For the exact error that caused the status to change to .failed, look at AVPlayerItem.error.
Listing 1 Getting notified when errors occur.
func beginPlayback () { |
let hlsAsset = AVURLAsset(url: assetURL) |
let playerItem = AVPlayerItem(asset: hlsAsset) |
player = AVPlayer(playerItem: playerItem) |
let playerObserver = player.observe(\AVPlayer.status, options: [.new, .initial]) { (player, _) in |
if player.status == .failed { |
guard let error = player.currentItem?.error else { return } |
// Handle error accordingly. |
} |
} |
let playerItemObserver = playerItem.observe(\AVPlayerItem.status, options: [.new, .initial]) { (item, _) in |
if item.status == .failed { |
guard let error = item.error else { return } |
// Handle error accordingly. |
} |
} |
} |
It is important to note that the AVPlayerItem.status property will only change to .failed after:
There are no viable alternate variants to use to continue playback.
AVPlayer has played out its current buffer.
Getting Notified When AVPlayerItem Failed To Play To Completion
Your application can also observe the AVPlayerItemFailedToPlayToEndTimeNotification to be notified if the AVPlayerItem did not play to completion. The userInfo dictionary of this notification contains the error that describes the problem that was encountered and can be retrieved using the AVPlayerItemFailedToPlayToEndTimeErrorKey key.
Listing 2 Getting notified when AVPlayerItem failed to play to completion.
... |
// Listen to notification |
NotificationCenter.default.addObserver(self, |
selector:#selector(failedToPlayToEndTime:), |
name: .AVPlayerItemFailedToPlayToEndTimeNotification, |
object: player.currentItem) |
... |
Listing 3 Responding to AVPlayerItemFailedToPlayToEndTimeNotification.
func failedToPlayToEndTime(notification: Notification) { |
guard let userInfo = notification.userInfo, let error = userInfo[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error else { |
return |
} |
// Handle Error accordingly. |
} |
Getting Detailed Error Logs
If your application needs to know all the error events that happened during the playback session for analytics or debugging then it should call AVPlayerItem.errorLog() which will return an instance of AVPlayerItemErrorLog if errors were encountered during playback.
AVPlayerItemErrorLog includes an array containing AVPlayerItemErrorLogEvent objects that represent the chronological sequence of events contained in the error log.
To be notified when a new entry has been added to the error log, add an observer for the AVPlayerItemNewErrorLogEntryNotification.
Listing 4 Getting detailed error logs.
... |
// Listen to notification |
NotificationCenter.default.addObserver(self, |
selector:#selector(newErrorLogEntry), |
name: .AVPlayerItemNewErrorLogEntry, |
object: player.currentItem) |
... |
Listing 5 Responding to new error log entries.
func newErrorLogEntry() { |
guard let errorLog = player.currentItem.errorLog() else { |
return |
} |
for event in errorLog.events { |
// Handle error events accordingly. |
} |
} |
Verifying Content
If you are encountering format errors during playback, it is important to test the validity of any playlist streams using the Media Stream Validator tool, mediastreamvalidator. This tool verifies that the index file and media segments conform to the HTTP Live Streaming Authoring Specification for Apple Devices. It performs several checks to ensure reliable streaming. If any errors or problems are found, a detailed diagnostic report is displayed. It is important to address the issues that the mediastreamvalidator finds to ensure that the AVFoundation framework handles your content in an expected way.
The Authoring Specification is Apple's advice for authoring HLS content. This is different from the HTTP Live Streaming Internet-Draft which includes only absolutely necessary requirements. The Authoring Specification, on the other hand, includes requirements that are specific to Apple's players, as well as things that, while not absolutely required, are part of best practice.
iOS or Mac Developer Program members can download the latest version of the Media Stream Validator from the Apple Developer Connection website. To download, go to Apple Developer Downloads, in the search field type "HTTP Live Streaming Tools", download and install the 'HTTP Live Streaming Tools'.
Instructions for using the tools can be found in the man pages for each tool. For example, launch the Terminal app and type man mediastreamvalidator to see these.
Once you run the mediastreamvalidator against your stream, you can run the hlsreport.py tool which is included as part of the 'HTTP Live Streaming Tools' package. What this tool does is take the JSON output of mediastreamvalidator and generates an HTML page with the contents of the report.
The document Media Stream Validator Tool Results Explained discusses any error message that may be returned from the Media Stream Validator tool.
You may also find the following resources useful in verifying that your HLS content is authored in a way that is supported by Apple devices:
Helpful Resources
General information regarding HLS on supported Apple devices and platforms:
Information regarding authoring HLS content for devices and platforms:
Information regarding error handling on the server side and with AVFoundation on supported Apple devices and platforms:
Document Revision History
| Date | Notes |
|---|---|
| 2017-08-25 | Fixed URLs referenced in this document. |
| 2017-08-04 | New document that how to debug issues related to HTTP Live Streaming. |
Copyright © 2017 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2017-08-25