Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Audio and Video

watchOS supports the ability to play audio or video content from your app and the ability to record audio to a local file. Audio playback on Apple Watch is intended primarily for playing short audio clips, but you can also play longer audio files. Any audio you play is routed to a paired Bluetooth headset if one is available.

Displaying a Movie Object

The WKInterfaceMovie and WKInterfaceInlineMovie objects lets you embed short audio or video clips directly into your interface. Both movie object display a poster image that appears inline with the rest of your content, as illustrated in Figure 11-1. When the user taps the poster image, the Watch app plays the media content. You can use these objects to play audio-only clips, video-only clips, or clips with both audio and video.

Figure 11-1A movie interface object image: ../Art/movie_interface_object_2x.png

The WKInterfaceMovie and WKInterfaceInlineMovie objects mostly differ in how they present the media while it is playing.

  • The WKInterfaceMovie object presents the system’s media interface controller to handle playback of the media content.

  • The WKInterfaceInlineMovie object replaces the poster with the media content, and plays the content inline, keeping the content embedded in your apps interface.

You configure many of the movie object’s attributes in your storyboard file, including the poster image and the resizing options. You specify the media file to play from your WatchKit extension when your interface controller is initialized. The URL you specify for your media assets may refer to a local file or an asset located on a remote server. For remote assets, the movie object downloads the movie completely before playing it.

Playing Short Audio and Video Clips

You can also programmatically play media files by calling the presentMediaPlayerControllerWithURL:options:completion: method of the current interface controller. This method presents the system’s media playback interface, offering an alternative to embedding a WKInterfaceMovie object in your Watch app scene. Instead of displaying a poster image in your interface, this method lets you use buttons, table rows, and other interactive items to trigger the playback of media. The method also offers an expanded set of options for playing your content, including the ability to start playback automatically and to start playback in the middle of the clip.

Listing 11-1 demonstrates how to play a movie file located in the WatchKit extension’s bundle. Passing in the WKMediaPlayerControllerOptionsAutoplayKey option causes the movie to begin playing as soon as it’s ready. The media player handles all user interactions and provides a Done button that the user can use to dismiss the interface. You do not have to dismiss the interface explicitly in your completion handler block.

Listing 11-1Playing a movie

Objective-C

  1. NSBundle* myBundle = [NSBundle mainBundle];
  2. NSURL* movieURL = [myBundle URLForResource:@"myMovie" withExtension:@"mp4"];
  3. NSDictionary* options = @{WKMediaPlayerControllerOptionsAutoplayKey : @YES};
  4. [self presentMediaPlayerControllerWithURL:movieURL
  5. options:options
  6. completion:^(BOOL didPlayToEnd, NSTimeInterval endTime, NSError * __nullable error) {
  7. if (error)
  8. NSLog(@"Error: %@", [error description]);
  9. // Perform any other tasks.
  10. }];

Swift

  1. let myBundle = NSBundle.mainBundle()
  2. if let movieURL = myBundle.URLForResource("myMovie", withExtension: "mp4") {
  3. self.movie.setMovieURL(movieURL)
  4. self.presentMediaPlayerControllerWithURL(movieURL,
  5. options: [WKMediaPlayerControllerOptionsAutoplayKey: true],
  6. completion: { (didPlayToEnd : Bool,
  7. endTime : NSTimeInterval,
  8. error : NSError?) -> Void in
  9. if let anErrorOccurred = error {
  10. // Handle the error.
  11. }
  12. // Perform other tasks
  13. })
  14. }

Recording Short Audio Clips

To record short audio clips, use the presentAudioRecordingControllerWithOutputURL:preset:maximumDuration:actionTitle:completion: method of WKInterfaceController to display the standard audio recording interface. When presenting the interface, you specify the audio quality you want and the location for the resulting audio file. After the user has recorded the content, the user must explicitly accept the recording before it is written to disk at the URL you specified.

For information about the audio recording options, see the description of the presentAudioRecordingControllerWithOutputURL:preset:maximumDuration:actionTitle:completion: method in WKInterfaceController Class Reference.

Playing Extended Audio Content

A WatchKit extension may initiate the playback of extended audio content through a paired Bluetooth audio headset. Playing extended audio audio involves using several different objects. Some objects manage the media file itself while others manage the playback process.

To manage the audio file, create a WKAudioFileAsset object and then create a WKAudioFilePlayerItem object. An asset object manages information about the audio file itself, such as the file’s URL on disk and the meta information associated with that file. A player item object manages transient information about the audio file, such as whether the audio is currently playing and how much of the audio has been played so far. Figure 11-2 shows the relationship of these objects to each other and to the associated media file.

Figure 11-2The arrangement of an audio asset and item image: ../Art/audio_longform_asset_management_2x.png

To play a media file, pass your WKAudioFilePlayerItem object to a WKAudioFilePlayer object. A player object manages the playback of the single audio file managed by your player item object. To play a sequence of audio files, use a WKAudioFileQueuePlayer object instead.

Player objects route audio through your Watch app, which then handles playback with the help of the system. To prevent your Watch app from terminating while it is playing audio, you must add the UIBackgroundModes key with the audio value to the Info.plist file of your Watch app. Adding this key lets your Watch app continue running for the purpose of playing audio. If the key is not present, playback ends when the user stops interacting with your app.

After initiating playback of an audio file using a WKAudioFilePlayer object, use that object or the WKAudioFilePlayerItem object to monitor or change the state of playback. For example, you might use these objects to check for errors during playback. The user can also control playback using the system’s Now Playing app.

For information about the classes used to manage audio playback, see WatchKit Framework Reference.

Making Media Files Accessible to Your Watch App

Although your WatchKit extension creates the objects needed to play your media, it does not handle the playback of that media. Because movie and audio playback happens through your app’s interface, playback is handled by your Watch app interface. As a result, your Watch app must have access to any media files you play.

Specifically, when the following classes and methods use URLs that refer to local files, these files must be stored in a location that can be accessed by both the WatchKit extension and the Watch app.

When considering where to place media files in the file system, use the following guidelines:

  • Place media clips that ship with your app inside the bundle of your WatchKit extension. Your WatchKit extension is located inside your Watch app bundle, so your Watch app can access any files in the extension’s bundle directory. In your extension code, use the methods of the NSBundle class to locate the files inside your extension’s bundle.

  • Place media files that you download from the network (or transfer from your iOS app) in a shared group container. A shared group container provides common storage for your Watch app and WatchKit extension. In your extension code, create URLs for any media files inside the container, and use them to configure the media interfaces.

For information about how to set up a shared group container, see Sharing Files Between a Watch App and WatchKit Extension at Runtime.

Encoding Media Assets

Table 11-1 lists the encoding information to use when creating media files to play on a user’s Apple Watch. For audio and video assets played directly from your app, keep your clips relatively short. Short clips consume less space on disk, use less power, and take less time to download.

Table 11-1Media encoding

Media type

Recommended encoding

Video assets

Video codec: H.264 High Profile

Bit rate: 160 kpbs at up to 30 fps

Full screen resolution: 208 x 260 in portrait orientation

16:9 resolution: 320 x 180 in landscape orientation

Audio bit rate: 32 kpbs stereo

Audio-only assets

Bit rate: 32 kbps stereo

For audio recordings, use the audio presets defined by the WKAudioRecordingPreset type. The preset values give you choices based on the intended use of the resulting audio. For example, you can use the WKAudioRecordingPresetNarrowBandSpeech option for voice memos and other content that does not require high-fidelity audio. Other options provide higher quality audio options.