This information is intended for developers of games and interactive applications who want to enable Dolby Atmos playback on Android Automotive OS devices.

Introduction

In your app, use the Dolby Atmos AAudio channel mask query API to detect whether the device supports Dolby Atmos playback over AAudio and to select the optimal channel configuration at runtime.

This removes the need for trial-and-error stream configuration and device-specific channel-mask hardcoding.

Detecting Dolby Atmos AAudio support

To detect whether the device supports Dolby Atmos over AAudio, query AudioManager with the DolbyAtmosAAudioChannelMask key:

val response = audioManager.getParameters("DolbyAtmosAAudioChannelMask")

The response is a key-value pair in this format: DolbyAtmosAAudioChannelMask = <CHANNEL_MASK>

The following responses indicate that the device supports Dolby Atmos playback over AAudio:

Response	Meaning
DolbyAtmosAAudioChannelMask = 0x2D03F	The device supports a 5.1.4 immersive Dolby Atmos configuration. Configure your AAudio stream for 10 channels.
DolbyAtmosAAudioChannelMask = 0x2D63F	The device supports a 7.1.4 immersive Dolby Atmos configuration. Configure your AAudio stream for 12 channels.

For any other response, use your app's stereo or non-Atmos audio path.

Playing Dolby Atmos content using AAudio

After you detect that the device supports Dolby Atmos over AAudio, use the returned channel mask to configure and open an AAudio stream.

The following Kotlin sample queries the mask, validates the response, maps it to the expected channel count, and hands the configuration to a native AAudio implementation. Splitting on = with limit = 2 handles both the <key>=<value> case and the bare-<key> unsupported case; the latter produces a single-element array and returns null at the first check.

private const val ATMOS_CHANNEL_MASK_KEY = "DolbyAtmosAAudioChannelMask" private const val MASK_5_1_4 = 0x2D03F private const val MASK_7_1_4 = 0x2D63F private data class AtmosConfiguration( val channelMask: Int, val channelCount: Int, ) private fun parseChannelMask(value: String): Int? { val normalized = value.trim().removePrefix("0x").removePrefix("0X") return normalized.toIntOrNull(16) } private fun queryAtmosConfiguration(audioManager: AudioManager): AtmosConfiguration? { val response = audioManager.getParameters(ATMOS_CHANNEL_MASK_KEY) val parts = response.split('=', limit = 2) if (parts.size != 2 || parts[0] != ATMOS_CHANNEL_MASK_KEY) { return null } val channelMask = parseChannelMask(parts[1]) ?: return null return when (channelMask) { MASK_7_1_4 -> AtmosConfiguration(channelMask, channelCount = 12) MASK_5_1_4 -> AtmosConfiguration(channelMask, channelCount = 10) else -> null } } fun startAtmosAudio(context: Context, sampleRate: Int): Boolean { val audioManager = context.getSystemService(AudioManager::class.java) ?: return false val configuration = queryAtmosConfiguration(audioManager) ?: return startNonAtmosAudio() return NativeAtmosAudio.open( channelMask = configuration.channelMask, sampleRate = sampleRate, ) }

java.lang.Integer.decode() also accepts the 0x prefix and can replace the helper above if you prefer it.

The native handoff is application-defined. Its responsibility is to configure AAudio with the selected channel mask and channel count:

object NativeAtmosAudio { external fun open(channelMask: Int, sampleRate: Int): Boolean }

Native AAudio configuration example

The native layer receives the channel mask from your app, maps it to the expected channel count, and verifies that the opened stream can deliver exactly that many hardware channels. The implementation retries with AAUDIO_FORMAT_PCM_I16 when AAUDIO_FORMAT_PCM_FLOAT cannot open or does not provide the expected number of channels.

#include <aaudio/AAudio.h> #include <android/log.h> static int getExpectedChannelCount(aaudio_channel_mask_t mask) { switch (mask) { case AAUDIO_CHANNEL_5POINT1POINT4: return 10; case AAUDIO_CHANNEL_7POINT1POINT4: return 12; default: return 0; } } AAudioStream* createOptimalAtmosStream(int channelMask, int sampleRate) { const aaudio_channel_mask_t mask = static_cast<aaudio_channel_mask_t>(channelMask); const int requestedChannelCount = getExpectedChannelCount(mask); if (requestedChannelCount == 0) { return nullptr; } const aaudio_format_t formatsToTry[] = { AAUDIO_FORMAT_PCM_FLOAT, AAUDIO_FORMAT_PCM_I16, }; for (const aaudio_format_t format : formatsToTry) { AAudioStreamBuilder* builder = nullptr; aaudio_result_t result = AAudio_createStreamBuilder(&builder); if (result != AAUDIO_OK) { return nullptr; } AAudioStreamBuilder_setDirection(builder, AAUDIO_DIRECTION_OUTPUT); AAudioStreamBuilder_setSampleRate(builder, sampleRate); AAudioStreamBuilder_setChannelMask(builder, mask); AAudioStreamBuilder_setFormat(builder, format); AAudioStreamBuilder_setSharingMode(builder, AAUDIO_SHARING_MODE_EXCLUSIVE); AAudioStreamBuilder_setPerformanceMode(builder, AAUDIO_PERFORMANCE_MODE_LOW_LATENCY); AAudioStream* stream = nullptr; result = AAudioStreamBuilder_openStream(builder, &stream); AAudioStreamBuilder_delete(builder); if (result != AAUDIO_OK) { continue; } const int32_t hardwareChannelCount = AAudioStream_getHardwareChannelCount(stream); if (hardwareChannelCount == requestedChannelCount) { return stream; } AAudioStream_close(stream); } return nullptr; }

The Kotlin call reaches the native helper through this JNI entry point:

extern "C" JNIEXPORT jboolean JNICALL Java_com_example_audio_NativeAtmosAudio_open( JNIEnv* env, jobject thiz, jint channelMask, jint sampleRate) { (void)env; (void)thiz; AAudioStream* stream = createOptimalAtmosStream(channelMask, sampleRate); if (stream == nullptr) { return JNI_FALSE; } startGeneratedAudio(stream); AAudioStream_close(stream); return JNI_TRUE; }

startGeneratedAudio(stream) represents your app's audio callback or write loop. Keep the stream open until playback finishes, then close it. The JNI class name and package must match your app's Kotlin declaration.

Channel mask and channel count mapping

The channel mask returned by the query maps to the following AAudio immersive layouts:

Response mask	Channel count	AAudio channel layout
0x2D63F	12	AAUDIO_CHANNEL_7POINT1POINT4
0x2D03F	10	AAUDIO_CHANNEL_5POINT1POINT4