This guide is intended for applications developers that perform bitstream-level editing of Dolby Digital Plus with Dolby Atmos (DD+ JOC) streams on iOS 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)
• Apple - iOS and iPadOS Overview

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:

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 iOS devcies

Use AVFoundation APIs to detect, trim, and concatenate Dolby Digital Plus with Dolby Atmos audio tracks on iOS-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, we recommend using CMAudioFormatDescriptionGetFormatList() to read and check the first entry in the AudioFormatList from the track's CMFormatDescription.

Note: At the time of writing this article, the publicly available Core Audio SDK does not define a named constant for ec+3 (Dolby Digital Plus with Dolby Atmos). The hexadecimal literal 0x65632B33 is the FourCC encoding of ec+3 and can be used to identify the Dolby Digital Plus with Dolby Atmos variant at the formatID level.

The following example outlines the general approach.

let fmtDescs = try await track.load(.formatDescriptions) as [CMFormatDescription]
let fmtDesc  = fmtDescs.first!
var formatListSize: size_t = 0
// CMAudioFormatDescriptionGetFormatList() returns all declared formats (richest first)
let formatListPtr = CMAudioFormatDescriptionGetFormatList(fmtDesc, sizeOut: &formatListSize)
let formatListCount = formatListSize / MemoryLayout<AudioFormatListItem>.size

guard let firstItem = formatListPtr, formatListCount > 0 else {
	return nil
}

// firstItem is always the highest format the file was encoded as (ec+3 for DD+ JOC)
// regardless of what decoders are installed on the current device
let formatID = firstItem.pointee.mASBD.mFormatID

var isEC3JOC: Bool {
  	// True when the track is E-AC-3 with Joint Object Coding (DD+ JOC / Dolby Atmos).
    // Container FourCC: `ec+3` = 0x65632B33 
    formatID == 0x65632B33
}

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. Without this check, the preview might silently fall back to a stereo or Dolby Digital Plus downmix, misrepresenting the Dolby Atmos experience to the user during playback preview.

Once the audio track is identified as ec+3, use CMAudioFormatDescriptionGetRichestDecodableFormat() to determine whether the current device has a compatible decoder. This function iterates through the track's AudioFormatList from richest to most compatible and returns a pointer to the first AudioStreamBasicDescription for which the OS provides a registered decoder. If no decoder is available, the function returns nil. Treat a nil return as indicating no Dolby Digital Plus with Dolby Atmos decode capability on the current device.

The following example outlines the general approach.

let fmtDescs = try await track.load(.formatDescriptions) as [CMFormatDescription]
let fmtDesc  = fmtDescs.first!
let richestFmt = CMAudioFormatDescriptionGetRichestDecodableFormat(fmtDesc)
let canDecodeEC3JOC = richestFmt?.pointee.mASBD.mFormatID == 0x65632B33

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. The preview is driven by AVPlayer operating on the same compressed bitstream that will be written to the output file during passthrough export.

Decoder capability detection is used to determine the quality of the preview experience: Dolby Atmos experience on devices that supports decoding of Dolby Digital Plus with Dolby Atmos content, or the Dolby Digital Plus base layer on others. However, the decoder capability does not affect the edit or the output.

Trimming a Dolby Digital Plus with Dolby Atmos track on iOS

AVFoundation does not enforce Dolby Digital Plus frame alignment during composition or export. Both AVMutableComposition and AVAssetExportSession might produce misaligned cuts unless the application explicitly aligns trim points before invoking these APIs. Trim points must be aligned to the nearest frame boundary before being applied to the composition.

Aligning cut points

Snap the start and end trim points to the nearest Dolby Digital Plus with Dolby Atmos frame boundary before passing them to insertTimeRange.

The following code snippet shows how this can be implemented.

let ec3SampleRate:      Int = 48000
let ec3SamplesPerFrame: Int = 1536

func snapToEC3FrameBoundary(_ time: CMTime) -> CMTime {
    let totalSamples = Int((CMTimeGetSeconds(time) * Double(ec3SampleRate)).rounded())

    // Round to the nearest frame boundary using integer arithmetic
    // Adding half the frame size before dividing shifts the threshold to the
    // midpoint, so the result rounds to whichever boundary is closest
    let frameIndex = (totalSamples + ec3SamplesPerFrame / 2) / ec3SamplesPerFrame

    return CMTime(
        value:     CMTimeValue(frameIndex * ec3SamplesPerFrame),
        timescale: CMTimeScale(ec3SampleRate)
    )
}

Exporting trimmed content

After building the composition, use AVAssetExportSession with AVAssetExportPresetPassthrough to remux into an MP4 container.

guard let exportSession = AVAssetExportSession(
    asset: composition,
    presetName: AVAssetExportPresetPassthrough
) else { return }

try await exportSession.export(to: outputURL, as: .mp4)

Concatenating Dolby Digital Plus with Dolby Atmos segments on iOS

Before concatenating two or more Dolby Digital Plus with Dolby Atmos segments into a single file, all tracks must be compatible at the bitstream level. Two bitstreams may be concatenated when their formatID, sampleRate, channelCount, and bitrate are identical.
The following sample code illustrates how to extract these parameter values from each track.

let fmtDescs = try await track.load(.formatDescriptions) as [CMFormatDescription]
let fmtDesc  = fmtDescs.first!
var formatListSize: size_t = 0
//CMAudioFormatDescriptionGetFormatList() returns all declared formats (richest first)
let formatListPtr = CMAudioFormatDescriptionGetFormatList(fmtDesc, sizeOut: &formatListSize)
let formatListCount = formatListSize / MemoryLayout<AudioFormatListItem>.size

guard let firstItem = formatListPtr, formatListCount > 0 else {
	return nil
}

// All four fields come from the ASBD of the first (richest) format list entry
let formatID:       UInt32 = firstItem.pointee.mASBD.mFormatID
let sampleRate:     Double = firstItem.pointee.mASBD.mSampleRate
let channelCount:   UInt32 = firstItem.pointee.mASBD.mChannelsPerFrame

// Reads the bitrate directly from the dec3 box data_rate field.
// NOTE: This approach is not valid for VBR streams. Frame-level parsing must be performed instead.
let bitrate = try await track.load(.estimatedDataRate)

Use either the passthrough workflow or reader/writer workflow to concatenate the source segments.

Passthrough workflow

The pipeline for this workflow is as follows:

1. Create an AVMutableComposition and add a destination audio track.
2. Insert each trimmed source segment sequentially into the composition at the advancing insertion point.

var insertionTime = CMTime.zero

for segment in segments {
    let asset    = AVURLAsset(url: segment.sourceURL)
    let srcTrack = try await asset.loadTracks(withMediaType: .audio).first!
    let range    = CMTimeRange(start: segment.startTime, end: segment.endTime)

    try audioTrack.insertTimeRange(range, of: srcTrack, at: insertionTime)
    insertionTime = CMTimeAdd(insertionTime, range.duration)
}

3. After building the composition, use AVAssetExportSession with AVAssetExportPresetPassthrough to remux into an MP4 container.

guard let exportSession = AVAssetExportSession(
    asset: composition,
    presetName: AVAssetExportPresetPassthrough
) else { return }

try await exportSession.export(to: outputURL, as: .mp4)

Reader/Writer (manual PTS retime) workflow

The pipeline for this workflow is as follows:

 

1. Create an AVAssetReader for each source segment and configure its timeRange to match the trimmed range.
2. Map each segment's PTS from the source time range to its destination position in the output timeline.
3. Keep a single AVAssetWriter open across all segments and append samples sequentially to build a contiguous output timeline.

for segment in segments {
    let reader = AVAssetReader(asset: asset)
    reader.timeRange = segment.sourceRange
    reader.startReading()

    while let sb = output.copyNextSampleBuffer() {
        let pts = CMSampleBufferGetPresentationTimeStamp(sb)
        let newPTS = pts - segment.sourceRange.start + compositionTime
        // Retime and append
        CMSampleBufferCreateCopyWithNewTiming(… newPTS …)
        writerInput.append(retimed)
    }

    compositionTime += segment.duration
}

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