spatial: expand SpatialAudioFormat enum (MPEG-H MHM1/MHA1, APAC, ASAF clarification)

[Salem874]

Summary

meedya-codecs::spatial::SpatialAudioFormat covers 9 variants (DolbyAtmos, DtsX, DtsXImax, MpegH3d, Sony360Ra, AppleSpatial, Auro3d, Iamf, Ambisonics). Consuming apps need finer-grained MPEG-H sub-variants plus 1–2 missing Apple formats. Filed in response to MeedyaManager#131 (spatial audio detection) which is blocked on these.

Parent epic: #9 (meedya-codecs detection).

Requested additions / clarifications

Definitely new

New variant	Display name	Authoritative signal	Notes
Apac	APAC (Apple Positional Audio Codec)	Codec four-CC apac in MP4 stsd (verify against tvOS 17+ / AirPods Pro 2 samples)	New Apple codec, sparse public docs. FOUR-CC needs verification before shipping.

MPEG-H sub-variant question (decide one)

Either:

(a) Keep MpegH3d as a single variant; carry MHM1 vs MHA1 in a separate MpegHContainer field on the detection result. Simpler enum; sub-variant is metadata.

OR

(b) Split into MpegH3dMhm1 (broadcast, multi-frame) and MpegH3dMha1 (file storage, single-frame). Distinct four-CCs (mhm1 vs mha1), distinct config atoms (mhmC vs mhaC).

Recommendation: (b) — distinct identifiers + distinct config atoms argue for distinct variants. Downstream apps may want to filter / route differently for broadcast streams vs stored files. Sony360Ra would still be its own variant, detected when the sub-profile signals 360RA regardless of MHM1 vs MHA1 container.

Apple Spatial Audio Format (ASAF) — clarification needed

The existing AppleSpatial variant currently means "binaural rendering of Atmos" (per the source comment). Downstream apps using the name "ASAF" may mean something different — a distinct Apple file format (possibly an MPEG-H-over-Apple-container variant in Apple Music spatial downloads).

Possible outcomes:

• (i) Confirm AppleSpatial IS what's commonly called ASAF in Apple's public messaging — document the equivalence in the doc comment and close.
• (ii) ASAF is distinct (e.g. a specific Apple-only MP4 atom layered on MPEG-H base) — add AppleAsaf as a separate variant; keep AppleSpatial as the binaural-rendering hint.
• (iii) ASAF is a marketing-only term for Atmos-via-EAC3-JOC delivery on Apple platforms — document this and prefer DolbyAtmos for detection.

Needs Apple-developer-docs cross-check. Tracked here so downstream MeedyaManager#131 has a definitive answer.

Method changes

For any new variant added:

• SpatialAudioFormat::display_name() — new strings
• is_object_based() — Apac → ? (TBD per Apple docs); MHM1/MHA1 → true (MPEG-H is object/scene hybrid)
• is_scene_based() — both MPEG-H variants → true
• requires_license() — Apac → true (Apple proprietary); MHM1/MHA1 → false (open standard but patents apply via MPEG-LA pool — call this out in the doc comment)

Detection-side hooks (for follow-up under #9)

Detection should populate source_signal strings:

• apac_four_cc
• mhm1_four_cc_plus_mhmC / mha1_four_cc_plus_mhaC
• mpegh_360ra_sub_profile — for 360RA detected via MPEG-H base sub-profile + Sony encoder string

Safety / false-positive avoidance (for callers)

• Sony 360 Reality Audio MUST NOT also flag as MpegH3dMha1 / MpegH3dMhm1 — once 360RA markers match (sub-profile + encoder string), suppress the generic MPEG-H label.
• IMAX Enhanced DTS:X MUST NOT also flag as plain DtsX — once IMAX signaling matches, emit DtsXImax.
• A file with Apple-Music-spatial metadata is generally Dolby Atmos via EAC3+JOC — don't auto-classify as AppleAsaf based on filename / iTunes metadata alone.

Backwards compatibility

Purely additive for Apac and MpegH3dMhm1 / MpegH3dMha1 (if we split). If we keep MpegH3d and add a separate sub-variant field, that's also non-breaking.

For ASAF: outcome (i) is non-breaking (docs only). Outcome (ii) is non-breaking (additive). Outcome (iii) is non-breaking (docs only, plus possibly deprecate AppleSpatial if the name causes confusion).

Serde rename-all (kebab-case) applies:

• apac
• mpeg-h-3d-mhm1, mpeg-h-3d-mha1 (option b)
• apple-asaf (option ii)

Acceptance

• Decision on MPEG-H sub-variant strategy (a vs b)
• Decision on ASAF (i / ii / iii) — backed by Apple docs reference
• APAC four-CC verified against actual sample
• New variants added with display_name() / is_object_based() / is_scene_based() / requires_license()
• Unit tests for classification + serde roundtrip
• Doc comments updated for any clarified existing variants

Refs MeedyaManager#131, #9

[Salem874]

Decisions confirmed by downstream stakeholder

MPEG-H — option (b): split into MpegH3dMhm1 and MpegH3dMha1

"MPEG-H MHM1/MHA1: both, all variants"

Add both as distinct enum variants. Distinct four-CCs (mhm1 vs mha1) + distinct config atoms (mhmC vs mhaC) + distinct intended use (broadcast/streaming vs file storage) justify the split. Sony360Ra stays its own variant, detected when the MPEG-H sub-profile signals 360RA regardless of underlying MHM1/MHA1 framing.

ASAF — outcome (ii): distinct from AppleSpatial, gets its own variant

Sources confirming ASAF is a real, distinct format:

• Apple WWDC session: https://developer.apple.com/videos/play/meet-with-apple/223/
• DPM Sound: https://www.dpmsound.com/apple-asaf-audio-format-explained-meet-the-new-immersive-audio-format
• Alpha Audio: https://www.alpha-audio.net/hi-fi/2025/06/apple-spatial-audio-format-asaf/
• TechRadar: https://www.techradar.com/audio/apple-quietly-just-unveiled-a-new-spatial-audio-format-that-expands-on-dolby-atmos-and-that-rivals-google-and-samsungs-eclipsa-audio

What ASAF actually is (per Apple WWDC + DPM Sound)

• ASAF = the FORMAT (Apple Spatial Audio Format). Dynamic audio format combining:
  • Higher-Order Ambisonics (HOA) up to 7th order (scene-based)
  • Object-based audio (hundreds of objects supported)
  • Rich rendering metadata
• APAC = the CODEC (Apple Positional Audio Codec) used to ENCODE ASAF content efficiently
• Container: MP4 (after HLS conversion tools)
• Bitrates: 64 kbps (head-tracked) → 768 kbps → ~1 Mbps typical (20 kbps per channel)
  • Reference compression: 5th-order Ambisonics + 15 objects = 81 Mbps PCM → ~1 Mbps APAC (~80:1 ratio)
• Platforms: all Apple platforms except watchOS
• Relationship to Dolby Atmos: ASAF can WRAP Dolby Atmos files, adding real-time environmental interactions

Recommended enum shape

Single variant AppleAsaf covering APAC-encoded ASAF files. Matches the existing pattern (one enum variant per perceptually-distinct user-facing format — same way DolbyAtmos covers EAC3-JOC + TrueHD + AC-4 without splitting per codec). APAC is the encoding mechanism, captured in source_signal strings like apac_in_asaf_mp4.

If a real-world need emerges for non-ASAF APAC encoding (theoretical — APAC was designed for ASAF), add a separate Apac variant later. Don't pre-split now.

Existing AppleSpatial retains its current meaning ("binaural rendering of Atmos") — the doc comment should be updated to explicitly disambiguate from AppleAsaf. Suggested doc:

/// Apple binaural rendering of Dolby Atmos content (head-tracked spatial
/// playback layer over Atmos source — NOT a distinct codec/format).
/// For Apple's actual distinct spatial format, see `AppleAsaf`.
AppleSpatial,

/// Apple Spatial Audio Format (HOA up to 7th order + hundreds of objects
/// + rich rendering metadata, encoded with the Apple Positional Audio
/// Codec / APAC, shipped in MP4). Source: Apple WWDC session 223.
/// Distinct from `AppleSpatial` (which is the binaural rendering layer).
AppleAsaf,

What's still UNKNOWN (open for implementer)

Neither the WWDC session nor the audio-press articles state:

• Exact four-CC code for APAC in ISOBMFF (e.g. apac, Apac, etc.) — needs sample-file inspection
• Specific sample-entry box / configuration box names
• File extension (probably .mp4 per "MP4 (APAC-encoded)" wording, but a dedicated .asaf extension may also exist)
• Supported sample rates and bit depths in encoded stream

These should be filled in during implementation via sample-file inspection (Apple Music spatial downloads on a Mac, or test files from the WWDC sample code if available). Document the discovered values in the variant doc comment as they're confirmed.

Updated acceptance for this issue

• Decision on MPEG-H sub-variant strategy → (b) split
• Decision on ASAF → (ii) distinct variant AppleAsaf
• APAC four-CC + atom names — STILL TO VERIFY against sample files (implementation-time task; not a blocker on adding the enum variant)
• All new variants added: MpegH3dMhm1, MpegH3dMha1, AppleAsaf
• display_name() / is_object_based() / is_scene_based() / requires_license() updated per variant
• AppleSpatial doc comment clarified to disambiguate from AppleAsaf
• Unit tests + serde roundtrip

[Salem874]

⚠️ Important name clash — FFmpeg's apac codec is NOT Apple's APAC

Re-checked sources https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/apac.c and https://trac.ffmpeg.org/ticket/11480 (suggested by downstream stakeholder as APAC reference material).

Critical finding from libavcodec/apac.c:

.p.name        = "apac",
CODEC_LONG_NAME("Marian's A-pac audio"),

FFmpeg's apac decoder is for "Marian's A-pac audio" — a German pro-audio company (Marian)'s codec, completely unrelated to Apple Positional Audio Codec. Stereo or mono, 8–16 bit samples, NOT spatial audio. The trac ticket #11480 is presumably about the same Marian codec (fetch failed due to Anubis protection on FFmpeg trac, but the source is unambiguous).

Consequences for ASAF / APAC detection:

1. The four-CC apac from ffprobe / FFmpeg's codec ID is AMBIGUOUS. A file flagged by FFmpeg as apac is overwhelmingly likely to be Marian's codec (not spatial), since Apple's APAC support isn't in FFmpeg as of this writing.

2. Detection ladder MUST NOT use the apac codec string from FFmpeg/ffprobe as a signal for Apple ASAF. False-positive risk: a Marian-encoded audio file would silently classify as immersive spatial.

3. Apple ASAF detection requires Apple-specific signals, NOT codec-ID matching. Candidates (need confirmation against real ASAF sample files):

   • Apple-private MP4 atoms in udta / meta / iTunMOVI indicating ASAF format
   • Brand identifier in the ftyp box (e.g. asaf major or compatible brand)
   • The actual Apple-assigned sample-entry four-CC for the APAC codec inside ASAF (which is NOT apac — that name is taken in FFmpeg)
   • HLS playlist tags signalling ASAF when delivered via Apple Music / Apple TV streaming

4. MediaInfo coverage — verify whether MediaInfo has been updated to recognize Apple ASAF specifically. If not, custom Apple-atom inspection in meedya-codecs may be the only reliable detection path until upstream tooling catches up.

Naming recommendation reinforced

The upstream enum variant should be AppleAsaf (per the format name) rather than Apac (which would clash with FFmpeg's existing apac codec ID in users' minds). This avoids:

• Mental name collision with Marian's A-pac
• Risk that someone implements detection by checking ffprobe's codec string == "apac" and gets wrong results

source_signal strings should NOT use the bare apac token — use apple_asaf_ftyp_brand, apple_asaf_atom, etc., to make the Apple-specificity explicit at every detection site.

Open implementation tasks (updated)

• Determine the actual sample-entry FOUR-CC Apple uses for APAC inside ASAF (it is NOT apac). Inspection of Apple Music spatial download files or Apple's HLS test vectors should reveal this.
• Determine whether ASAF files have a distinct ftyp brand (e.g. asaf).
• Determine file extension (likely .mp4, possibly .m4a, possibly a new dedicated extension).
• Confirm whether MediaInfo recognizes ASAF in current/future versions.

These are implementation-time tasks for the eventual #9 decoder integration, not blockers on adding the enum variant. The variant AppleAsaf can be added to the enum now with these details filled into the doc comment as they're confirmed.