apple guide

AirPlay Overview

Contents

About AirPlay 4At a Glance 4

Choose the Best Option for Media Playback 4You Can Opt Into or Out of AirPlay for Video 5Provide a Great AirPlay User Experience in Your App 5Protect Your Media Using Encryption and Authentication 6

See Also 6

Preparing Your Media and Server for AirPlay 7Preparing Your Media 7Providing AC3 Audio and High-Definition Video 8Configuring Your Server 8

Opting Into or Out of AirPlay 10Enabling or Disabling AirPlay on Your Website 10Enabling or Disabling AirPlay in Your App 11

If Your App Uses AVPlayer 11If Your App Uses MPMoviePlayerController 12If Your App Uses UIWebView 12

Enriching the AirPlay Experience in Your App 13Provide an AirPlay Picker 14Send Audio Where It Belongs 15Provide Audio Metadata 15Respond to Remote Events 16

Encryption and Authentication 18Encryption for Media Downloads 18Authentication for Encryption Key Downloads 18

Document Revision History 20

2012-09-19 | © 2012 Apple Inc. All Rights Reserved.

2

Figures, Tables, and Listings

Preparing Your Media and Server for AirPlay 7Table 1-1 File extensions and MIME types 9

Opting Into or Out of AirPlay 10Listing 2-1 Allowing AirPlay to use your video 10Listing 2-2 Disallowing AirPlay to use your video 11

Enriching the AirPlay Experience in Your App 13Figure 3-1 System AirPlay picker 14


3

If you provide audio or video content from a website, or display audio or video content within your iOS app,you should learn about AirPlay. AirPlay lets users stream your audio and video to high-definition displays andhigh-fidelity audio systems. Using AirPlay, users redirect audio and video from iTunes or an iOS-based deviceto either an Apple TV (and from there to a home theater system) or to an AirPlay-enabled sound system. AirPlaycan stream media coming live from the Internet, media already stored in iTunes, or media stored on an iOS-baseddevice. AirPlay can stream Internet-based media when it is playing in iOS apps, in the Safari browser oniOS-based devices, or in iTunes on any platform.

AirPlay is supported on iOS 4.3 or later and iTunes 10.2 or later on OS X and Windows.

At a GlanceUsing AirPlay, users redirect audio and video to either an Apple TV or to an AirPlay-enabled sound system orremote speakers. AirPlay is user controlled. As a content provider, your primary role is to ensure that yourmedia is AirPlay compatible and that your app or website works correctly with AirPlay. You might also wantto provide high-definition video or surround-sound audio when your content is being redirected to a hometheater system.

As an app developer, you can enhance the user’s AirPlay experience in several ways:

● Provide an AirPlay output device picker.

● Provide audio metadata that the AirPlay-enabled output device can display.

● Listen for and respond to remote events from the AirPlay output device, such as play/pause.

● Use the iOS-based device’s built-in display independently when a second display is active.

Choose the Best Option for Media PlaybackYou can deliver AirPlay-compatible audio and video to iOS-based devices in four distinct ways:

● Embed audio or video in your website using the HTML5 <audio> and <video> tags. Media delivered thisway works on iOS-based devices through the Safari browser or in apps that use a web view.

● Stream audio and video directly to your app, playing the media using AV Foundation, the MPMoviePlayerclass, or the UIWebView class.


4

About AirPlay

● Store the media locally on an iOS-based device.

● Make your content available through iTunes, either commercially or as a podcast.

AirPlay is compatible with media delivered by progressive downloading or HTTP Live Streaming, but HTTP LiveStreaming is preferred. To prepare your media for playback through AirPlay, make sure that it’s in a supportedformat—for example, H.264 video and AAC or MP3 audio. No special server configuration is required, apartfrom associating the correct MIME types with the file extensions used to send the media. To enrich the user’sAirPlay experience, you can also provide alternative audio and video streams that take advantage of a hometheater system’s capabilities.

Relevant chapter: “Preparing Your Media and Server for AirPlay” (page 7)

You Can Opt Into or Out of AirPlay for VideoAirPlay is user initiated and, generally speaking, user controlled. Audio content (other than system sounds)can always be redirected by the user to an AirPlay-enabled sound system, and so can iTunes content, whetheraudio or video. If you provide video from your website or display it from within your app, however, you canchoose to opt into AirPlay, enabling user redirection, or opt out of AirPlay, restricting your video to the deviceon which it is received.

In iOS 5.0 and later (including Safari in iOS 5.0), AirPlay is enabled by default and you must explicitly opt outof AirPlay if you want to prevent users from redirecting your video to Apple TV.

Relevant chapter: “Opting Into or Out of AirPlay” (page 10)

Provide a Great AirPlay User Experience in Your AppYou can include an AirPlay picker in your app’s user interface, allowing the user to select an AirPlay device foroutput without leaving your app.

If your app’s audio or video is being redirected to an AirPlay-enabled device that has its own controls, you canprovide metadata—such as a song title and album artwork—to enhance the user’s experience. In additionyour app should respond to remote events, such as play/pause or next-track requests.

About AirPlayAt a Glance


5

Relevant chapter: “Enriching the AirPlay Experience in Your App” (page 13)

Protect Your Media Using Encryption and AuthenticationIf you deliver your audio and video using HTTP Live Streaming, there is built-in support for encryption, withautomatic generation of encryption keys and initialization vectors on a periodic basis (see HTTP Live StreamingOverview for details). If you deliver the keys over HTTPS and use authentication, however, your app is responsiblefor the initial authentication handshake.

Relevant chapter: “Encryption and Authentication” (page 18)

See Also ● Multiple Display Programming Guide for iOS describes how to take advantage of an external display by

mirroring the content of an iOS-based device or displaying different content on each device.

● HTTP Live Streaming Overview explains how to set up and use HTTP Live Streaming to deliver live andon-demand audio and video over HTTP from an ordinary web server.

● Safari HTML5 Audio and Video Guide explains how to embed audio and video in websites.

● AVPlayer Class Reference describes the AVPlayer class, including AirPlay-specific properties.

● MPMoviePlayerController Class Reference describes the MPMoviePlayerController class, includingAirPlay-specific properties.

● UIWebView Class Reference describes the UIWebView class, including AirPlay-specific properties.

About AirPlaySee Also


6

For your media to play over AirPlay, it needs to be playable on an iOS-based device, such as an iPhone, iPodtouch, or iPad. For your server to work with AirPlay, it needs to be configured to send audio and video overHTTP.

Preparing Your MediaWhen preparing your media for AirPlay, you should do the following:

● Encode your audio using mono or stereo AAC or MP3 compression.

● Encode your video using H.264 compression.

Use Baseline Profile 3.0 if your video is intended for playback on iPhone 3G or earlier.

For playback on iPhone 4 and later, iPod touch, iPad, and Apple TV, use Baseline Profile 3.1.

Use Main Profile 3.1 if your video is intended for playback exclusively on iPad, OS X, and Apple TV.

● Use a QuickTime reference movie or an alternate-stream playlist to provide an alternative version ofaudio/video content with an AC3 surround-sound track and high-definition video to be used when yourmedia is being played through a home theater system.

If you are using HTTP Live Streaming to provide video at multiple bandwidths, seeHTTP Live StreamingOverviewfor recommended bit rates and encoder settings.

You can package your media in .mp3, .aac, .m4a, .m4v, .mp4, and .mov files. Alternatively, you can passyour media directly to the HTTP Live Streaming media segmenter as an MPEG-2 transport stream containingAAC-compressed audio and H.264-compressed video (normally the case for live broadcast).

You can also create .m3u8 playlists, but these are typically generated automatically by the HTTP Live Streamingserver software, which also generates .ts files from the media.


7

Preparing Your Media and Server for AirPlay

Providing AC3 Audio and High-Definition VideoThe AirPlay-enabled sound system that is playing your audio media might be able to play AC3 surround-soundaudio. You can provide an alternate stream playlist that has an AC3 selection to give your app richer soundwhen the output device supports it. Similarly, the AirPlay output device might be able to display high-definitionvideo; provide a 1280 x 720 video stream alternate to give the user the richest display possible.

Alternate stream playlists are a feature of HTTP Live Streaming. Alternate streams are normally specified by bitrate, but you can also specify streams by screen resolution and required codecs, so that the AC3 audio andhigh-definition video streams are chosen only when the output device supports them.

You can specify the ability to play AC3 audio as a requirement for a stream alternate by setting the CODECSparameter in your master playlist. The string for the AC3 audio codec is "ac-3". Similarly, you can use theRESOLUTION parameter to set the minimum video resolution required for a video stream.

As an example, the following variant playlist specifies a low bandwidth stream, a high bandwidth stream, andan AirPlay stream that requires a 1280 x 720 display, AC3 audio capability, and a 1.5 Mbit/s Internet connection.

#EXTM3U

#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=150000

http://example.com/low/index.m3u8

#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=640000

http://example.com/high/index.m3u8

#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=1500000,RESOLUTION=1280x720,CODECS="avc1.42e01e,ac-3"

http://example.com/airplay/index.m3u8

For more information on alternate stream playlists, see HTTP Live Streaming Overview .

Configuring Your ServerYour server needs to be configured for sending audio and video over HTTP. The most important step inconfiguring your server is to associate the correct MIME type for each supported file extension. Table 1-1summarizes the MIME types and file extensions.

Preparing Your Media and Server for AirPlayProviding AC3 Audio and High-Definition Video


8

Table 1-1 File extensions and MIME types

MIME typeFile extension

application/x-mpegURL or

application/vnd.apple.mpegURL

.m3u8

video/MP2T.ts

video/quicktime.mov

audio/MPEG3.mp3

audio/aac.aac

audio/mpeg4.m4a

video/mpeg4.m4v, .mp4

Tip: If you are using HTTP Live Streaming to deliver your media, you can increase transmissionefficiency by enabling on-the-fly gzip compression of .m3u8 files from your server.

Preparing Your Media and Server for AirPlayConfiguring Your Server


9

Audio content (except for system sounds) and media played via iTunes or the Music app are always availableto AirPlay. Video playing in your app or from your website can be enabled for AirPlay or not, at your discretion.

Before iOS 5.0, you needed to opt into AirPlay to enable your media to be played over Apple TV. In appscompiled with the base SDK set to iOS 5.0 and later, AirPlay is enabled by default; if you do not want iOS-baseddevices to be able to play your video over Apple TV, you must disable AirPlay explicitly.

In iOS 5.0 and later, Safari opts in for web content by default.

Enabling or Disabling AirPlay on Your WebsiteTo enable video on your website to be viewable via AirPlay, embed it in your webpage using the HTML5<video> tag. See Safari HTML5 Audio and Video Guide for details.

To explicitly opt in to AirPlay, set the x-webkit-airplay attribute for the video tag or the airplay attributefor the embed tag to "allow", as shown in Listing 2-1.

Listing 2-1 Allowing AirPlay to use your video

<video src="myPlaylist.m3u8"

height="300" width="400"

x-webkit-airplay="allow" >

<embed airplay="allow"

src="movie.mov"

width=400

height=300

mime-type="video/quicktime">

</embed>

</video>


10

Opting Into or Out of AirPlay

To explicitly opt out of AirPlay, set x-webkit-airplay attribute for the video tag or the airplay attributefor the embed tag to "deny", as shown in Listing 2-2.

Listing 2-2 Disallowing AirPlay to use your video

<video src="myPlaylist.m3u8"

height="768" width="1024"

x-webkit-airplay="deny" >

</video>



<embed airplay="deny"

src="movie.mov"

width=320

height=240

mime-type="video/quicktime">

</embed>

Enabling or Disabling AirPlay in Your AppIn iOS 5.0 and later, AirPlay is automatically enabled for video when your app uses AV Foundation, theMPMoviePlayerController class, or the UIWebView class to display video. You should explicitly opt intoAirPlay for compatibility with earlier versions of iOS, however. Alternatively, you can explicitly disable AirPlayfor your app’s video. The exact method depends on the API you use for video playback.

If Your App Uses AVPlayer ● If your app uses the AVPlayer class to display video, you can explicitly enable AirPlay by setting the

allowsAirPlayVideo property to YES.

● To disable AirPlay, set the allowsAirPlayVideo property to NO.

● To determine whether your video is playing over AirPlay, test the state of the airPlayVideoActiveproperty.

Opting Into or Out of AirPlayEnabling or Disabling AirPlay in Your App


11

Note: The airPlayVideoActive property supports key-value observing. To configure an objectin your app to be notified of changes to this property, register the object as an observer.

If Your App Uses MPMoviePlayerController ● If your app uses the MPMoviePlayerController class to display video, you can explicitly enable AirPlay

by setting the allowsAirPlay property to YES.

● To disable AirPlay, set the allowsAirPlay property to NO.

● To determine whether your video is playing over AirPlay, test the state of the airPlayVideoActiveproperty.

Note: You can listen for changes to the airPlayVideoActive property by registering for theMPMoviePlayerIsAirPlayVideoActiveDidChangeNotification notification.

If Your App Uses UIWebView ● If your app uses the UIWebView API to display video, you can explicitly enable AirPlay by setting the

mediaPlaybackAllowsAirPlay property to YES. In addition, the content you are displaying in the webview must not disallow AirPlay.

● To disable AirPlay, set the mediaPlaybackAllowsAirPlay property to NO.

Opting Into or Out of AirPlayEnabling or Disabling AirPlay in Your App


12

There are several ways you can provide a richer experience for your users when they are using AirPlay withyour app:

● Provide an AirPlay picker in your app.

● Make sure that all of your app audio goes to the AirPlay output device, and that user interface sounds stayon the host device.

● Provide audio metadata that can be displayed on the AirPlay output device.

● Respond to remote events from the AirPlay output device.

● Take advantage of an external display by providing separate content for the iOS-based device display andthe external display (to learn how to do this, see Multiple Display Programming Guide for iOS ).

● Provide alternate data streams with high-definition video and AC3 audio (for more information, see“Providing AC3 Audio and High-Definition Video” (page 8)).


13

Enriching the AirPlay Experience in Your App

Provide an AirPlay PickerThe user can go to the system AirPlay picker in the iOS multitasking interface to select an AirPlay output, asillustrated in Figure 3-1. If an AirPlay output device is available, an AirPlay button appears next to the volumeslider; tapping the button displays a list of available devices.

Figure 3-1 System AirPlay picker

If your app plays media, you might want to provide an AirPlay output picker within your app so that the userdoesn’t have to change focus. You can add an AirPlay picker to your media playback controls by usingMPVolumeView, as shown in the following code snippet:

MPVolumeView *volumeView = [ [MPVolumeView alloc] init] ;

[view addSubview:volumeView];

If you have a custom media controller and don’t want to use the standard volume controller, you can add justthe AirPlay picker using the following code snippet:

Enriching the AirPlay Experience in Your AppProvide an AirPlay Picker


14

MPVolumeView *volumeView = [ [MPVolumeView alloc] init] ;

[volumeView setShowsVolumeSlider:NO];

[volumeView sizeToFit];

[view addSubview:volumeView];

The picker is visible only when there is an AirPlay output device available.

Send Audio Where It BelongsApps typically use two types of sound—app audio (such as ambient sounds, background music, and incidentalnoises) and system sounds (such as key clicks and alert sounds). AirPlay attempts to deliver the app audio toa remote sound system while keeping system sounds on the host, so that feedback sounds remain local to theinput device.

If your app uses system sound APIs for app audio, AirPlay does not redirect them to the AirPlay-enabled soundsystem. The result is a less-than-optimum user experience. It is important to use system sound APIs only forsystem sounds. For app audio, use APIs such as AVAudioPlayer.

Provide Audio MetadataYour audio might be playing on a big-screen home theater system or on a sound system with an LCD display.Your app gives a better user experience if you provide metadata that can be shown on the AirPlay device’sdisplay, such as the artist name, song title, and album art.

Add metadata by passing a dictionary into the setNowPlayingInfomethod of MPNowPlayingInfoCenter.The MPNowPlayingInfoCenter class is part of the MediaPlayer framework, but works with all playbackframeworks, including MediaPlayer, AVFoundation, and AudioQueue.

In addition to providing the usual song information strings, you should also pass in the playback rate, elapsedtime, and media item duration. The playback device can use the duration and playback rate to create a progressbar. Update the elapsed time and playback rate whenever the playback rate changes.

Enriching the AirPlay Experience in Your AppSend Audio Where It Belongs


15

Respond to Remote EventsWhen AirPlay is in use, your media might be playing in another room from your host device. The AirPlay outputdevice might have its own controls or respond to an Apple remote control. For the best user experience, yourapp should listen for and respond to remote events, such as play, pause, and fast-forward requests. Enablingremote events also allows your app to respond to the controls on headphones or earbuds that are pluggedinto the host device.

Use the following code snippet to receive remote events:

- (BOOL) canBecomeFirstResponder {return YES;}

- (void) viewDidAppear: (BOOL) animated {

[super viewDidAppear:animated];

[ [UIApplication sharedApplication] beginReceivingRemoteControlEvents];

[self becomeFirstResponder];

}

When your app is finished playing media, let the system know that you are no longer the receiver for remoteevents by using the following code snippet:

- (void) viewWillDisappear: (BOOL) animated {

[super viewWillDisappear:animated];

[ [UIApplication sharedApplication] endReceivingRemoteControlEvents];

[self resignFirstResponder];

}

Respond to events of the type UIEventTypeRemoteControl and the subtypes appropriate for your app.The following code snippet gives an example:

- (void) remoteControlReceivedWithEvent: (UIEvent *) receivedEvent {

if (receivedEvent.type == UIEventTypeRemoteControl) {

switch (receivedEvent.subtype) {

case UIEventSubtypeRemoteControlTogglePlayPause:

[self playPauseToggle: nil]

break;

case UIEventSubtypeRemoteControlNextTrack:

[self nextTrack: nil]

Enriching the AirPlay Experience in Your AppRespond to Remote Events


16

break;

...

See UIEvent.h for an enumeration of event subtypes.

Enriching the AirPlay Experience in Your AppRespond to Remote Events


17

If you use HTTP Live Streaming, iOS provides built-in support for media encryption, and beginning in iOS 5.0,it also provides support for authentication. If you serve the encryption key from a protected domain, your appis responsible for handling the initial authentication handshake with your server.

Encryption for Media DownloadsUsing HTTP Live Streaming, you can instruct the media segmenter software to encrypt your media. Thesegmenter generates encryption keys—and initialization vectors for those keys—at specified intervals.

The keys are used to encrypt all video for a given period. The client software retrieves the keys and uses themto decrypt the video. An initialization vector is required to use a key.

You tell the segmenter how often to change the key and how often to change the initialization vector for thecurrent key. You also give the segmenter a base URL to use for the keys and the initialization vectors. Thesegmenter includes the URLs of the keys and initialization vectors in the playlist files it generates.

The keys are normally changed infrequently, and are served over HTTPS for security. The initialization vectorsare normally changed frequently, but are served over HTTP for speedy delivery. The use of HTTP does notreduce security, because the initialization vectors are useless without the keys.

For more information, see HTTP Live Streaming Overview .

Authentication for Encryption Key DownloadsTo protect your encryption keys, your server should require video clients to authenticate themselves. Themethod of authentication varies with the app. Using AirPlay with encrypted streaming content is supportedonly in iOS 5.0 and later.

For Web-based video playing in Safari (in iOS), you need to have the user authenticate manually before playingvideo encrypted with a key served from a secure domain. The authentication can be provided in JavaScript,but not without the risk of exposing the login information. Although manual authentication works well forpay-per-view or subscription video, it is normally undesirable for advertisement-supported video because itrequires a login for viewing.


18

Encryption and Authentication

Bear in mind that if the video is playing over AirPlay, the viewer is watching on a television with no way toenter a password. In such cases, the viewer must authenticate on the device that is relaying the video viaAirPlay, which might be in another room. This situation has other implications, including how long cookies orother authentication tokens should last before expiration. You should configure your server accordingly.

For video playing in an app, there are three recommended means of authenticating key delivery:

● Serve keys from a protected HTTPS realm. Before playback begins, your app can use NSURLConnectionto authenticate itself, providing credentials that are kept hidden.

● Use cookies over HTTPS. Your app can make a connection to an HTTPS server and authenticate the appin an app-defined way. Your server can then issue a cookie that applies to the key URLs. You should setthe cookie to expire long after playback is complete. The server must then require the presence of a validsession cookie in future GET requests for the keys.

For maximum reliability, if the expiration date is in the near future, the server should update the cookie’sexpiration date in its response to future GET requests.

● Specify the keys in the .m3u8 files using an app-defined URL scheme. The app should register a customNSURLProtocol to handle requests for those URLs. The player then calls back into your app when it needsto load a key URL; your app can then obtain the key using a secure side channel and can provide it to theplayer.

For more information, see HTTP Live Streaming Overview .

Encryption and AuthenticationAuthentication for Encryption Key Downloads


19

This table describes the changes to AirPlay Overview .

NotesDate

Moved information about using an external display to Multiple DisplayProgramming Guide for iOS and made minor edits.

2012-09-19

New document that explains how to prepare video content, websites,and apps to work with AirPlay.

2011-10-12


20

Document Revision History

Apple Inc.© 2012 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, AirPlay, Apple TV, iPad,iPhone, iPod, iPod touch, iTunes, OS X, QuickTime,and Safari are trademarks of Apple Inc., registeredin the U.S. and other countries.

DEC is a trademark of Digital EquipmentCorporation.

Java is a registered trademark of Oracle and/orits affiliates.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

apple guide

Documents