opus - Jan 2014 - Meaning of mapping[]

Hey everyone, I've added Ogg Opus support to my Adobe Premiere plug-in here:

http://github.com/fnordware/AdobeOgg


Now I'll add Opus support to me WebM plug-in too.  I've got this Opus
stuff mostly figured out, but I have a few questions.  Here's one:


What do the numbers in mapping mean?  I see that opus.h refers to the Vorbis
channel mapping order, so does mapping in Opus take that order and re-arrange
it?

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.  So does this mean that Opus is asking
for front left, rear right, center, front right, real left, LFE?  Seems a little
odd.


Brendan

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

On Jan 6, 2014, at 11:54 AM, Ralph Giles wrote:
> 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.

Ahh, I see.  Thanks for the explanation.

It's sort of the opposite of what I'd expect.  I'd expect
mapping[stream_index] = vorbis_index, but it's actually
mapping[vorbis_index] = stream_index.

And so I guess that means that the interleaved audio samples you pass into
opus_multistream_encode_float() should always be in Vorbis order, and mapping[]
just tells the encoder how to package them in the streams?


Brendan