Question: Groups

[trevorknight]

How are audio groups intended to be used? My apologies if this is a dumb question, but why would I need both groups?

[jingbo-marquis]

Thank you for the question — it's not a dumb question at all. The audio groups design corresponds to the Sub-Mix concept in the IAMF Mix Presentation specification.

1. Corresponding to IAMF Mix Presentation Sub-Mix:

In the latest IAMF specification, a Mix Presentation contains up to two Sub-Mixes. Each Sub-Mix is a collection of audio elements that can have independent rendering parameters, loudness correction, and output gain. OAR's audio group corresponds directly to this concept — each group maps to a Sub-Mix, with independent loudness gain (oar_set_loudness) and output gain (oar_update_metadata with ck_metadata_gain).

2. Why each Sub-Mix needs to correspond to a group:

IAMF's Sub-Mix design allows different processing chains to be applied to different audio element collections within the same Mix Presentation. For example:

• Independent loudness control: Each Sub-Mix (group) has its own loudness_gain field (oar.c:45-46), allowing different loudness corrections to be applied separately. In oar_render() (oar.c:535-536), loudness gain is applied independently per group.
• Independent output gain: Each group has its own output_gain metadata queue (oar.c:44), allowing independent control of that group's output gain, corresponding to the output gain parameter of a Sub-Mix in IAMF.
• Mixed output: In oar_render() (oar.c:543-547), all groups' outputs are summed and mixed into a single output buffer, corresponding to the IAMF flow where multiple Sub-Mixes are combined into the final output.

3. Multiple groups for IAMF, single group for common use:

The multiple group design is primarily for compatibility with IAMF Mix Presentations that contain multiple Sub-Mixes. In typical usage, a single group suffices — all audio elements can be added to the same group (gid=0).

4. Current limitations:

OAR currently supports up to 2 groups (def_max_audio_group_id = 2, oar.c:38), corresponding to the IAMF limit of at most 2 Sub-Mixes per Mix Presentation. Group IDs are auto-assigned starting from 0.

Summary: Multiple groups are used for IAMF Mix Presentation scenarios containing multiple Sub-Mixes. In typical cases, a single group is sufficient.