[opus] Meaning of mapping[]

[Ralph Giles]

On 2014-01-06 10:24 AM, Brendan Bolles wrote:

> http://github.com/fnordware/AdobeOgg

Cool!

> What do the numbers in mapping mean?

These numbers tell you how to map the decoded opus channels to
particular speakers.

> For example, opus_multistream_surround_encoder_create() sends out mapping[] = {0, 4, 1, 2, 3, 5}.
> For 6 channels the Vorbis order is front left, center, front right,
rear left, rear right, LFE.

You also need the number of coupled channels to understand mapping[].
Opus multichannel support works by bundling some combination of stereo
and mono streams. This is left flexible so the encoder can optimize it
based on application. The number of coupled channels tells the
multistream decoder how many stereo streams to configure, since a
compressed opus stream can be decoded as either mono or stereo.

Then the mapping array tells you how to map the left and right channels
of stereo stream, and then the single channels of any mono streams to
the output channel order.

In your six channel example, opus_multistream_surround_encoder_create
returns 4 for the number of streams, and 2 for the number of coupled
streams. So two of the four streams are decoded as coupled (stereo)
pairs and two as mono, giving a total of six channels. These channels
are orded with the coupled pairs first:

0 - left channel of the first coupled stream
1 - right channel of the first coupled stream
2 - left of the second stream
3 - right of the second stream
4 - sole channel of the third stream, which is the first mono stream
5 - sole channel fo the fourth, or second mono, stream

The decode channels are mapped to the vorbis surround speaker order
based on the numbers in the mapping table. The first entry, mapping[0],
describes front left and contains the value '0', so that speaker is the
left channel of the first coupled stream. mapping[1] is '4', so the
front centre speaker is given the first mono stream. mapping[2] is '1'
so the front right speaker gets the right channel of the first coupled
stream, and so on.

So we can see in your example that the encoder coupled front left/right
and rear left/right into pairs, and kept front centre and LFE as
descrete mono.

https://tools.ietf.org/html/draft-ietf-codec-oggopus has more detail
about how the coupling works.

Hope that helps,
 -r