Professional Documents
Culture Documents
Contents
About AirPlay 4
At a Glance 4 Choose the Best Option for Media Playback 4 You Can Opt Into or Out of AirPlay for Video 5 Provide a Great AirPlay User Experience in Your App 5 Protect Your Media Using Encryption and Authentication 6 See Also 6
About AirPlay
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 and high-fidelity audio systems. Using AirPlay, users redirect audio and video from iTunes or an iOS-based device to either an Apple TV (and from there to a home theater system) or to an AirPlay-enabled sound system. AirPlay can stream media coming live from the Internet, media already stored in iTunes, or media stored on an iOS-based device. AirPlay can stream Internet-based media when it is playing in iOS apps, in the Safari browser on iOS-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 Glance
Using AirPlay, users redirect audio and video to either an Apple TV or to an AirPlay-enabled sound system or remote speakers. AirPlay is user controlled. As a content provider, your primary role is to ensure that your media is AirPlay compatible and that your app or website works correctly with AirPlay. You might also want to provide high-definition video or surround-sound audio when your content is being redirected to a home theater system. As an app developer, you can enhance the users 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 devices built-in display independently when a second display is active.
Embed audio or video in your website using the HTML5 <audio> and <video> tags. Media delivered this way 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 MPMoviePlayer class, or the UIWebView class.
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 Live Streaming is preferred. To prepare your media for playback through AirPlay, make sure that its in a supported formatfor example, H.264 video and AAC or MP3 audio. No special server configuration is required, apart from associating the correct MIME types with the file extensions used to send the media. To enrich the users AirPlay experience, you can also provide alternative audio and video streams that take advantage of a home theater systems capabilities. Relevant chapter: Preparing Your Media and Server for AirPlay (page 7)
Relevant chapter: Enriching the AirPlay Experience in Your App (page 13)
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 and on-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, including AirPlay-specific properties. UIWebView Class Reference describes the UIWebView class, including AirPlay-specific properties.
For your media to play over AirPlay, it needs to be playable on an iOS-based device, such as an iPhone, iPod touch, or iPad. For your server to work with AirPlay, it needs to be configured to send audio and video over HTTP.
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 of audio/video content with an AC3 surround-sound track and high-definition video to be used when your media is being played through a home theater system.
If you are using HTTP Live Streaming to provide video at multiple bandwidths, see HTTP Live Streaming Overview for recommended bit rates and encoder settings. You can package your media in .mp3, .aac, .m4a, .m4v, .mp4, and .mov files. Alternatively, you can pass your media directly to the HTTP Live Streaming media segmenter as an MPEG-2 transport stream containing AAC-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 Streaming server software, which also generates .ts files from the media.
Preparing Your Media and Server for AirPlay Providing AC3 Audio and High-Definition Video
For more information on alternate stream playlists, see HTTP Live Streaming Overview .
Preparing Your Media and Server for AirPlay Configuring Your Server
Table 1-1
Tip: If you are using HTTP Live Streaming to deliver your media, you can increase transmission efficiency by enabling on-the-fly gzip compression of .m3u8 files from your server.
Audio content (except for system sounds) and media played via iTunes or the Music app are always available to 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 apps compiled with the base SDK set to iOS 5.0 and later, AirPlay is enabled by default; if you do not want iOS-based devices 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.
</video>
10
To explicitly opt out of AirPlay, set x-webkit-airplay attribute for the video tag or the airplay attribute for the embed tag to "deny", as shown in Listing 2-2.
Listing 2-2 Disallowing AirPlay to use your video
</video>
<!-- or -->
</embed>
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 airPlayVideoActive property.
11
Note: The airPlayVideoActive property supports key-value observing. To configure an object in your app to be notified of changes to this property, register the object as an observer.
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 airPlayVideoActive property.
Note: You can listen for changes to the airPlayVideoActive property by registering for the MPMoviePlayerIsAirPlayVideoActiveDidChangeNotification notification.
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 web view must not disallow AirPlay. To disable AirPlay, set the mediaPlaybackAllowsAirPlay property to NO.
12
There are several ways you can provide a richer experience for your users when they are using AirPlay with your 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 stay on 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 and the 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
If your app plays media, you might want to provide an AirPlay output picker within your app so that the user doesnt have to change focus. You can add an AirPlay picker to your media playback controls by using MPVolumeView, as shown in the following code snippet:
MPVolumeView *volumeView = [ [MPVolumeView alloc] init] ; [view addSubview:volumeView];
If you have a custom media controller and dont want to use the standard volume controller, you can add just the AirPlay picker using the following code snippet:
14
Enriching the AirPlay Experience in Your App Send Audio Where It Belongs
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.
15
When your app is finished playing media, let the system know that you are no longer the receiver for remote events 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]
16
break; ...
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 app is responsible for handling the initial authentication handshake with your server.
18
Bear in mind that if the video is playing over AirPlay, the viewer is watching on a television with no way to enter a password. In such cases, the viewer must authenticate on the device that is relaying the video via AirPlay, which might be in another room. This situation has other implications, including how long cookies or other 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 NSURLConnection to 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 app in an app-defined way. Your server can then issue a cookie that applies to the key URLs. You should set the cookie to expire long after playback is complete. The server must then require the presence of a valid session 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 cookies expiration 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 custom NSURLProtocol to handle requests for those URLs. The player then calls back into your app when it needs to load a key URL; your app can then obtain the key using a secure side channel and can provide it to the player.
19
Date 2012-09-19
Notes Moved information about using an external display to Multiple Display Programming Guide for iOS and made minor edits. New document that explains how to prepare video content, websites, and apps to work with AirPlay.
2011-10-12
20
Apple Inc. 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-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., registered in the U.S. and other countries. DEC is a trademark of Digital Equipment Corporation. Java is a registered trademark of Oracle and/or its affiliates. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.