This guide is intended for applications developers that perform bitstream-level editing of Dolby Digital Plus with Dolby Atmos (DD+ JOC) streams on Android mobile devices.

NOTE: Bitstream-level editing means that the audio bitstream is modified in the bitstream domain, without decoding to baseband prior to editing and re-encoding after the edit. Therefore only a limited number of editing operations are supported.

This guide focuses on the following operations:

1. Trimming Dolby Digital Plus with Dolby Atmos content
2. Concatenating multiple clips with Dolby Digital Plus with Dolby Atmos content
3. Previewing the content during the editing process
4. MP4 muxing after editing

Before reading further, we recommend reviewing the following resources:

• Dolby Digital Plus Specs Overview
• What is Dolby Digital Plus JOC? (Joint Object Coding)

Trimming a Dolby Digital Plus with Dolby Atmos track

Trimming a Dolby Digital Plus with Dolby Atmos audio track means extracting a contiguous segment of the bitstream that corresponds to a specified time range. The process relies on two fundamental properties of the Dolby Digital Plus format:

• Constant sample size: Each encoded frame in the stream occupies the same number of bytes. The exact frame size depends on the encoder's bit rate setting, but it remains fixed within a given file. As a result, the relationship between time and byte position can be calculated linearly, without variable-length parsing.
• Frame independence: Each frame carries enough information to be decoded independently. As there are no inter-frame dependencies that require context from preceding frames, any frame boundary can serve as a valid cut point while preserving audio quality and avoiding re-encoding.

The trimming process contains three stages: Metadata extraction, time to byte offset conversion, and bitstream trimming and remultiplexing.

Metadata extraction

Read the MP4 container metadata to obtain the parameters needed for the time to byte offset conversion. The relevant values are spread across the following track boxes:

MP4 Box	Field to read	Purpose
TimeToSampleBox	SampleDelta	The number of time units per sample. The value is 1536 for Dolby Digital Plus with Dolby Atmos bitstreams.
TimeToSampleBox	SampleCount	The total number of samples in the track.
SampleSizeBox	SampleSize	The byte size of each sample in the track. If non-zero, this constant value applies to all samples; if zero, individual per-sample sizes are stored in the entry_size table within the same box.
MediaHeaderBox	TimeScale	The number of time units per second for this track

As a consistency check, the ec-3 sample entry (AudioSampleEntry with the ec-3 four-character code) should also be inspected to verify that the handler type is ec-3 and that the SampleRate field is consistent with the timescale read from MediaHeaderBox. The EC3SpecificBox (dec3) nested within the ec-3 sample entry indicates the presence of Dolby Atmos metadata (JOC) when ec3_extension_type_a is set to 1.

Time to byte offset conversion

First, convert the desired start and end times (in seconds) into sample indexes using the following formula:

number_sample = time_in_seconds × samples_per_second

where,

samples_per_second  = TimeScale / SampleDelta

For example, if the start time is 5 seconds and the end time is 10 seconds in a 48 kHz audio stream. The sample offsets are as follows:

start_sample = floor( 5 × (48000 / 1536)) = floor(156.25) = 156

end_sample = floor( 10 × (48000 / 1536)) = floor(312.5) = 312

Validate that both sample offsets fall within the valid range [0 to (SampleCount - 1)].

Then, multiply the sample indexes by the sample size to obtain the corresponding byte offsets within the raw ec-3 bitstream. For constant bit rate encoding, all samples have the same size. The byte offsets of the start and end samples are calculated as follows:

start_byte_offset = start_sample × SampleSize

end_byte_offset = end_sample × SampleSize

Bitstream trimming and remultiplexing

After calculating the byte offsets, extract the raw ec3 bitstream from the MP4 container and copy the bytes in the range [start_byte_offset, end_byte_offset] to a new output buffer. This operation is a binary copy; no decoding, re-encoding, or frame inspection is required. As a result, the audio quality of the extracted segment is identical to that of the corresponding source segment. 

Write the extracted frames to an .ec3 file, then mux it into a new MP4 container using any compliant MP4 multiplexer. The multiplexer generates new track boxes for the trimmed content.

Concatenating a Dolby Digital Plus with Dolby Atmos track

Concatenate two or more bitstreams into a single continuous stream by appending them sequentially, without decoding or re-encoding the audio.

When the source files use the same encoder configuration, concatenating two bitstreams at the byte level produces a valid combined bitstream because ec-3 frames are self-contained and fixed in size within a given stream. No frame-boundary alignment is required, as the frame sync words embedded in the bitstream enable any compliant decoder to re-synchronize at the join point.

NOTE: For concatenation to produce a valid output, all source streams must have identical encoding parameters: sample rate, bit rate, and channel configuration. Mismatched parameters might result in a malformed or unplayable output. Your application must enforce this constraint before concatenation.

The concatenating workflow is as follows:

1. Validate compatibility.
   Confirm that all input streams have the same sample rate, bit rate, and channel configuration before proceeding.
2. Extract and concatenate bitstreams.
   Extract the raw ec3 bitstreams from the MP4 containers. Append the bitstreams sequentially in the desired order.
3. Multiplexing into an MP4.
   Package the resulting .ec3 file into a new MP4 container using a compliant MP4 multiplexer. The multiplexer generates new track boxes for the concatenated content.

Editing on Android-based devices

Use Android MediaExtractor and MediaCodec APIs to detect, trim, and concatenate Dolby Digital Plus with Dolby Atmos audio tracks on Android-based devices.

Detecting a Dolby Digital Plus with Dolby Atmos track in an asset

To determine whether an asset contains a Dolby Digital Plus with Dolby Atmos track, iterate through MediaExtractor audio tracks, select only audio/eac3 candidates and check for Dolby Atmos metadata signalization in the dec3 box. The logic can be implemented using the same bit-parsing approach as Media3 Ac3Util.parseEAc3AnnexFFormat.

The following example outlines the general approach.

MediaExtractor extractor = new MediaExtractor();
MediaFormat selectedFormat = null;

extractor.setDataSource(filePath);

for (int i = 0; i < extractor.getTrackCount(); i++) {
    MediaFormat format = extractor.getTrackFormat(i);
    String mime = format.getString(MediaFormat.KEY_MIME);

    if (MediaFormat.MIMETYPE_AUDIO_EAC3.equals(mime)) {
        // Parse EC3SpecificBox (dec3) and read flag_ec3_extension_type_a.
        // Parsing logic is equivalent to Media3 Ac3Util.parseEAc3AnnexFFormat.
        boolean isDDPJoc = hasJocMetadata(format, filePath);

        if (isDDPJoc) {
            selectedFormat = format;
            extractor.selectTrack(i);
            break;
        }
    }
}

Detecting Dolby Digital Plus with Dolby Atmos decoder capability

In an editing workflow, decoder capability detection determines whether the current device can render a Dolby Digital Plus with Dolby Atmos preview. Use MediaCodecList.findDecoderForFormat() to check whether a compatible decoder is available on the device.

The following example outlines the general approach.

import android.media.MediaCodec;
import android.media.MediaCodecList;
import android.media.MediaFormat;

...

MediaCodecList mediaCodecList = new MediaCodecList(MediaCodecList.ALL_CODECS);

final MediaFormat format =
        MediaFormat.createAudioFormat(MediaFormat.MIMETYPE_AUDIO_EAC3_JOC,
                                      48000 /* sample rate */,
                                      2 /* channels */);

final String decoderName = mediaCodecList.findDecoderForFormat(format);
MediaCodec decoder = null;
try {
    decoder = MediaCodec.createByCodecName(decoderName);
} catch (IOException | IllegalArgumentException | NullPointerException e) {
    // Unable to find Dolby Digital Plus with Dolby Atmos MediaCodec decoder component
}
// Device supports MediaCodec decoding of Dolby Digital Plus with Dolby Atmos

Editing preview

For bitstream-level trimming operations on Dolby Digital Plus with Dolby Atmos content, the editing preview plays back a selected time range of the source asset. No re-encoding occurs.

For more information on Dolby Digital Plus with Dolby Atmos playback on Android mobile devices, see Enabling Dolby Atmos and Dolby Audio in Android Mobile media apps.

Trimming a Dolby Digital Plus with Dolby Atmos track

Align trim points to the nearest Dolby Digital Plus joint object coding frame boundary before applying them to a composition to prevent misaligned cuts.

1. Snap the start and end trim points to the nearest Dolby Digital Plus with Dolby Atmos frame boundary before building the preview composition or export segment list.
   The following code snippet shows how this can be implemented.

private const val EC3_SAMPLE_RATE = 48_000L
private const val EC3_SAMPLES_PER_FRAME = 1_536L
private const val EC3_FRAME_DURATION_US = (EC3_SAMPLES_PER_FRAME * 1_000_000L) / EC3_SAMPLE_RATE // 32_000

fun snapToEc3FrameBoundary(timeUs: Long): Long {
    val frameIndex = (timeUs + EC3_FRAME_DURATION_US / 2) / EC3_FRAME_DURATION_US
    return frameIndex * EC3_FRAME_DURATION_US
}

2. Read the compressed audio samples between the snapped start and end trim points and add them to the output segment list.
3. Export the trimmed content by remuxing the compressed samples without re-encoding the audio.

NOTE: Android MediaMuxer does not support multiplexing Dolby Digital Plus with Dolby Atmos. To create an MP4 file containing Dolby Digital Plus with Dolby Atmos audio, use an alternative MP4 multiplexer.

Concatenating Dolby Digital Plus with Dolby Atmos segments

Before concatenating two or more Dolby Digital Plus with Dolby Atmos segments into a single MP4 container, all tracks must be compatible at the bitstream level. Two or more segments can be concatenated when their MIME types, sample rates, channel counts, bit rates, and flag_ec3_extension_type_a values are all identical.

1. Extract the format parameters from each segment at import time, before any edit is applied, using MediaExtractor.getTrackFormat(). Verify that the parameters of the segments are identical. The Dolby Atmos metadata signalization must be checked by explicitly reading dec3.flag_ec3_extension_type_a. The logic can be implemented using the same bit-parsing approach as Media3 Ac3Util.parseEAc3AnnexFFormat.

fun isCompatible(a: MediaFormat, b: MediaFormat): Boolean {
    if (a.getString(MediaFormat.KEY_MIME) != b.getString(MediaFormat.KEY_MIME)) return false
    if (a.getInteger(MediaFormat.KEY_SAMPLE_RATE) != b.getInteger(MediaFormat.KEY_SAMPLE_RATE)) return false
    if (a.getInteger(MediaFormat.KEY_CHANNEL_COUNT) != b.getInteger(MediaFormat.KEY_CHANNEL_COUNT)) return false
    if (a.getInteger(MediaFormat.KEY_BIT_RATE) != b.getInteger(MediaFormat.KEY_BIT_RATE)) return false
    //both must carry the same flag_ec3_extension_type_a value in the dec3 box
    if (hasJocMetadata(a, uriA) != hasJocMetadata(b, uriB)) return false
    return true
}

2. Arrange the validated source segments sequentially in the concatenation order to build the output timeline.
3. Export the concatenated content by remuxing the compressed samples without re-encoding the audio.

NOTE: Android MediaMuxer does not support multiplexing Dolby Digital Plus with Dolby Atmos. To create an MP4 file containing Dolby Digital Plus with Dolby Atmos audio, use an alternative MP4 multiplexer.

Output validation

After a trim or concatenation operation, validate the output by verifying playback and confirming that the stream parameters are correct.

For a trim, confirm that audio playback starts and ends at the expected times. For concatenation, confirm that transitions between segments are seamless, the total duration matches the sum of the input segments, and key stream parameters (such as sample rate, channel configuration, and bit rate) remain consistent and valid.

Test content

You can use the test content provided in the Dolby Digital Plus Online Delivery Kit for validation.

Test tools

The following test tools are available for validation:

• Dolby Stream Validator
• Dolby MP4 Inspector
• Dolby Reference Player 
• MediaInfo