This article provides guidance for developers of media applications running on Apple operating systems and outlines the specific and necessary updates for these applications to enable and support audio playback of Dolby Atmos and Dolby Audio content over AirPlay to supported AirPlay receivers that include Dolby technology for playing back Dolby Audio or Dolby Atmos.

Dolby Audio and Dolby Atmos are audio technologies that enable the recreation of an artist's intended sound with superior clarity, detail and dimensionality. These technologies are available in many home audio or portable devices.

AirPlay receivers that support Dolby Audio or Dolby Atmos use the Dolby Atmos for Home Audio library. This library integrates Dolby technologies such as Dolby Atmos and Dolby Audio decoding and rendering to provide immersive audio experiences during playback of streaming music or movie content, including content delivered through AirPlay.

Notes:

• Streaming Dolby Atmos and Dolby Audio content over AirPlay requires Apple devices that are running on version 18.0 or higher of a compatible operating system (iOS 18.0+, iPadOS 18+, and tvOS 18.0+)
• This article currently only targets applications running on iOS, iPadOS, and tvOS. The current version of macOS (macOS 15 Sequoia) does not support transmission of immersive audio over AirPlay.
• This article covers only the required delta for the enablement of Dolby Atmos and Dolby Audio. It assumes that the application has already integrated support for AirPlay, such as for stereo audio playback. For details about how to add general support for audio playback over AirPlay to your application, refer to these developer materials from Apple:
  • Supporting AirPlay in your application
  • Human interface guidelines for application.
• For successful transmission of Dolby Atmos over AirPlay, AirPlay receivers need to support AirPlay 2 with spatial audio.

Enabling Dolby Atmos and Dolby Audio over AirPlay

The following sequence diagram shows a high level overview of the interaction between the media application and the operating system that is required to enable Dolby Atmos and Dolby Audio over AirPlay.

Figure 1: Interaction between the media application and the operating system

Detecting Dolby Atmos and Dolby Audio playback capability in the AirPlay receiver

With version 18.0 of the supported operating systems, the AVAudioSession object has been extended with means to detect the capability for playback of multichannel or Dolby Atmos audio content and to indicate it accordingly.

The AVAudioSession object can be used to:

• Detect if the connected AirPlay receiver supports multichannel or Dolby Atmos audio output layouts and specify them.
• Indicate the currently resolved audio rendering mode (described in Badging for Dolby Atmos and Dolby Audio playback section)

Determining if the AirPlay receiver supports Dolby Atmos and Dolby Audio channel layouts

Use the AVAudioSession.supportedOutputChannelLayouts array property to determine the output channel layouts supported by the AirPlay receiver. AVAudioSession.renderingCapabilitiesChangeNotification should be observed to get notified about changes to this property. This array will be non-empty only if AVAudioSession is active.

• Presence of one of the following AudioChannelLayoutTags in this array will indicate that the connected AirPlay receiver supports a Dolby Atmos layout:
  • kAudioChannelLayoutTag_Atmos_7_1_4

  • kAudioChannelLayoutTag_Atmos_7_1_2

  • kAudioChannelLayoutTag_Atmos_5_1_4

  • kAudioChannelLayoutTag_Atmos_5_1_2

kAudioChannelLayoutTag_Atmos_9_1_6 may be supported in a future update.

• Presence of a multichannel layout in this array will indicate that the connected AirPlay receiver can support Dolby Audio. Following are examples of AudioChannelLayoutTags for multichannel layouts:  

  • kAudioChannelLayoutTag_AAC_5_1

  • kAudioChannelLayoutTag_MPEG_7_1_C

The array might also contain other layout tags, indicating support for other audio channel layouts. This information should be used in the media application to determine which audio asset variant should be used for playback.

Presence of Dolby Atmos LayoutTags in supportedOutputChannelLayouts does not guarantee that the connected AirPlay receiver includes Dolby Atmos technology. The application will not know whether the connected AirPlay receiver includes Dolby Atmos technology until the system informs it about the resolved rendering mode only after the playback has already been started.

 

Figure 2: Does the AirPlay receiver support multichannel or Dolby Atmos layouts?

Playing Dolby Atmos or Dolby Audio content

Dolby Atmos and Dolby Audio content can be played over AirPlay using two available application programming interface (API) sets for enhanced buffering:

• Using simple enhanced buffering API: AVPlayer or AVQueuePlayer Apple documentation: Implementing simple enhanced buffering for your content.
• Using flexible enhanced buffering API: AVSampleBufferAudioRenderer and AVSampleBufferRenderSynchronizer Apple documentation: Implementing flexible enhanced buffering for your content.

The application is able to choose which APIs to use, depending on the current audio route. For example, use one API for local or bluetooth playback and a different one for playback over AirPlay.

This should be handled with routeChangeNotification, and is described in this article: Apple documentation: Responding to Audio Route Changes.

Additional updates might be needed in the media application depending on whether the decoding of the Dolby Atmos and Dolby Audio content is supported natively within the operating system or happens in the application. The following sections delineate the Dolby formats that are natively supported for decoding within the operating system, as well as those that require the implementation of in-app decoding and the steps involved in achieving it.

Support for Dolby Formats

This table provides an overview about the delivery formats that are currently supported by Dolby for playback in media applications over AirPlay:

Dolby format		Playback in supported Apple operating systems
Dolby Audio (5.1, 7.1)	Dolby Digital (up to 5.1 channels)	Native decoding supported
	Dolby Digital Plus (up to 7.1 channels)	Native decoding supported
	Dolby AC-4	Currently only supported through in-app decoding
Dolby Atmos (object-based or channel-based immersive)	Dolby Digital Plus with joint object coding	Native decoding supported
	Dolby AC-4	Currently only supported through in-app decoding
Dolby Atmos (binaural and stereo speakers only)	Dolby AC-4 IMS (Immersive Stereo)	Not suitable for playback over AirPlay

Native decoding

If the decoding takes place natively in the operating system, the application should use the AVFoundation framework and the preferred API that supports enhanced buffering to provide Dolby Atmos or Dolby Audio content in a Dolby Digital Plus bitstream. The operating system will then decode and render the content to the optimal audio channel layout, based on the supported layouts of the AirPlay receiver.

The application must follow the resolved value of AVAudioSession.RenderingMode to reflect correct badging of Dolby Audio or Dolby Atmos content in the user interface (UI), as described in Badging for Dolby Atmos and Dolby Audio playback section.

In-app decoding using Dolby Audio for Applications

Some applications may rely on in-app decoding of Dolby formats using the Dolby Audio for Applications System Development Kit. This is necessary, for example, when the service is using a format to deliver content to the application that is currently not supported natively on Apple operating systems, such as Dolby AC-4. These applications must decode the content and, for immersive content, render it to one of the supported audio layouts, depending on the format of the content, as shown in the following table. See Determining if the AirPlay receiver supports Dolby Atmos and Dolby Audio channel layouts section for details.

 

Applications performing in-app decoding typically utilize the AVSampleBufferAudioRenderer and AVSampleBufferRenderSynchronizer APIs within the AVFoundation framework. The decoded and rendered pulse code modulation (PCM) audio samples that are passed to the aforementioned APIs must be tagged with a proper AudioChannelLayoutTag. Including a correct AudioChannelLayoutTag is important for the operating system to know the channel order for the associated PCM audio. Not including the channel layout tag might result in the audio getting encoded for AirPlay with an incorrect channel ordering, especially in the case of 5.1 surround sound (see Note 2 below). 

Notes: 

Note 2: The channel layout used to transmit 5.1-channel content via AirPlay is different from the channel layout output by the Dolby decoder for 5.1-channel audio. After decoding (and for some scenarios, downmixing) to 5.1 channels, the channel order of Dolby-decoded audio must be indicated to the system by using an appropriate AudioChannelLayoutTag. For any 5.1-ch content output by Dolby decoders, the kAudioChannelLayoutTag_MPEG_5_1_A tag should be used.

Note 3: In the current versions of AirPlay and the supported Apple operating systems, audio content from Dolby that is decoded in the application and provided to the operating system as decoded PCM audio samples, will not be badged correctly by the operating system in your application, because the operating system is not able to confirm that the specific source format is Dolby Atmos or Dolby Audio.

Note 4: If the AirPlay receiver indicates stereo support only, an alternative stereo version of the content may exist and should be selected instead. In the event that only a Dolby Audio or Dolby Atmos version of the content is available, this should be decoded and downmixed to stereo before AirPlay output.

Note 5: The Dolby Audio for Applications System Development Kit (SDK) can be downloaded from the Dolby Customer Portal under Licensing Resources (https://customer.dolby.com/licensing-resources/)

Badging for Dolby Atmos and Dolby Audio playback

With version 18.0 of the supported Apple operating systems, the current rendering mode of the audio is indicated by the AVAudioSession.renderingMode API. This will inform the application of what experience badging is appropriate, including for Dolby Audio and Dolby Atmos. The value returned by the API is based on a combination of factors: 

• The format of the audio asset that is consumed by the chosen playback API.
• The audio channel layouts supported by the AirPlay receiver.
• Whether the AirPlay receiver integrates licensed Dolby technology.

You can enable your application to register for the AVAudioSession.renderingModeChangeNotification to be notified about changes in this property.

Use the AVAudioSession.renderingMode property to check if the currently played-back content experience is indicated as Dolby Atmos or Dolby Audio, and badge it accordingly in the application UI. The appropriate assets to use for badging of Dolby Audio or Dolby Atmos can be accessed by registering at the Dolby Asset Center.

Defined rendering modes:

Input audio format vs badging

With this release, renderingMode will be set to dolbyAtmos only for scenarios in which the connected AirPlay receiver supports Dolby Atmos. In this scenario, the audio decoding and rendering is handled by the native decoder in the operating system and a Dolby Atmos bitstream is provided to the operating system.

If an application uses in-app decoding (for example, integrates Dolby Audio for Applications) and provides multichannel PCM to the playback API, the operating system will not set the rendering mode to indicate Dolby Atmos playback in the application through AVAudioSession, even if the connected AirPlay receiver integrates the Dolby Atmos technology.

Badging values in different AirPlay playback scenarios

This below tables provides the values reported by the AVAudioSession.renderingMode API under different AirPlay playback scenarios and source content formats. The table uses the following terminology:

• Dolby Atmos layout - 5.1.2, 5.1.4, 7.1.2, 7.1.4
• Multichannel layout - 5.1, 7.1
• Stereo - 2.0

Native decoding

In-app decoding

 

Figure 3: Dolby Audio or Dolby Atmos badging

Loudness management

In the current releases of the supported Apple operating systems, the playback pipeline for AirPlay lacks built-in support for active loudness management. As a result, we expect that there could be variations in playback levels between Dolby content (Dolby Atmos and Dolby Audio) and stereo content. Without active loudness management, decoded audio will be played back at the level it was mastered in the studio without automatic volume normalization.

Note that Dolby Atmos music content is typically mastered at a maximum of -18 LKFS, while stereo content can be (and often is) mastered at higher levels with less dynamic range.

For applications that leverage native decoders in the operating system, you may see some variations in playback volume between tracks or between Dolby Atmos and stereo content. We are working with Apple on improvements for this behavior. Please test with your application and service and send feedback about any issues or feature requests related to loudness management.

For applications that implement their own in-app audio decoding and processing pipeline (for example, by using Dolby Audio for Applications), we recommend that all Dolby Atmos and Dolby Audio content be normalized in the application to a target level of -20 LKFS after decoding. Matching the playback level between Dolby Atmos and stereo content is currently handled through static gain adjustment inside the AirPlay receiver.

We recommend the following best practices for including accurate loudness information and normalization for audio content:

• Measure the loudness of your stereo, Dolby Atmos, and Dolby Audio content per ITU-R BS.1770-4, including integrated (program) loudness and true-peak audio level.

• Ensure that the Dialnorm value in Dolby Atmos and Dolby Audio encoders matches the integrated (program) loudness value of the content.

• Ensure that loudness information for stereo content (including integrated (program) loudness and true-peak audio level) is delivered, either in-band or out-of-band, for use by the media application.

References and further readings

• Playing Custom Audio with Your Own Player
  • https://developer.apple.com/documentation/avfaudio/audio_engine/playing_custom_audio_with_your_own_player
• Integrating AirPlay for Long-Form Video Apps
  • https://developer.apple.com/documentation/avfoundation/streaming_and_airplay/integrating_airplay_for_long-form_video_apps
• AVFoundation framework documentation
  • https://developer.apple.com/documentation/avfoundation
• Tune up your AirPlay audio experience, 2023 Apple Worldwide Developers Conference
  • https://developer.apple.com/videos/play/wwdc2023/10238/?time=371