[vorbis] vbr / cbr / abr API calls

[Michael Smith]

At 01:55 PM 8/3/02 +0200, you wrote:
>Michael Smith wrote:
>
>Let me clear it up a bit, as I see a bit of confusion here with the 
>phrases used:

Yeah - understandable. You're entirely right that this is underdocumented,
hopefully we'll have this fixed for the next release. encoder_example.c
is the only really useful reference at the moment, but that doesn't
cover all the potentially interesting cases.

>thus: calling vorbis_encode_setup_managed() initializes a VBR mode 
>encoding, with quality specified by bitrate? (with the possibility to 
>set upper-lower limits).
>
>But isn't this what ABR should be about?

No, this is a VBR mode because, after configuring an ABR mode using
vorbis_encode_setup_managed(), you disable management entirely with
the call to vorbis_encode_ctl() - the reason for allowing this is so
that you can get the encoding quality available from fully VBR modes,
but with a more traditional (and perhaps more intuitive to some users)
bitrate interface.

>
>So is there a real difference between:
>
>     ret = vorbis_encode_init( &vorbisInfo,
>                               getInChannel(),
>                               getOutSampleRate(),
>                               (getOutBitrate() * 1000) * 1.1,
>                               getOutBitrate() * 1000,
>                               -1 );
>
>and:
>
>     ovectl_ratemanage_arg   ai;
>
>     // fill out ai here
>
>     ret = vorbis_encode_init_vbr( &vorbisInfo,
>                                   getInChannel(),
>                                   getOutSampleRate(),
>                                   getOutQuality() )
>        || vorbis_encode_ctl( &vorbisInfo, OV_ECTL_RATEMANAGE_SET, &ai);

If you fill out ai to turn management on, and to set nominal and maximum
bitrates to the right values (as for your call to vorbis_encode_init(),
then these should be equivalent. 

>
>also, can you elaborate on the structure ovectl_ratemanage_arg:
>
>struct ovectl_ratemanage_arg {
>   int    management_active;
>
>   long   bitrate_hard_min;
>   long   bitrate_hard_max;
>   double bitrate_hard_window;
>
>   long   bitrate_av_lo;
>   long   bitrate_av_hi;
>   double bitrate_av_window;
>   double bitrate_av_window_center;
>};
>
>it may be obvious to you, but I don't see what for example 
>bitrate_hard_window, bitrate_av_* are for, and what are the possible 
>values for management_active (e.g. is this a boolean-like member, or are 
>there different levels of management)? for bitrate_hard_min, is -1 a 
>"don't care" value?

management_active is a boolean (0 for off, 1 for on). I'm not sure what
the "don't care" value is (it's probably either -1 or 0) - if you don't
care, then you should just be not setting these (i.e. get ai using
OV_ECTL_RATEMANAGE_GET, then only change the bits you're interested in.

bitrate_av_window* are values to do with the length of the floating
window for ABR encoding (i.e. the 'average' is enforced over a window
of 4 seconds by default, or whatever else you put in this value
if you change it. Changing it to anything significantly smaller than 
it is now is NOT a good idea, since you don't leave the encoder
sufficient room to move in). I'm not sure at the moment what 
bitrate_av_{lo,hi} are for, but you shouldn't need to change them.

<p>>
>> In managed modes (ABR/CBR are subsets of that), min and max bitrate do
>> the obvious thing - they set a minimum and maximum bitrate for the
>> encoder to use.
>
>Above you said that by calling vorbis_encode_setup_managed() I actually 
>get a VBR mode. Here you associate managed mode with ABR and CBR. What 
>are managed modes then? This is a bit confusing :((

I didn't say that, see above for what I _was_ saying.

>
>> Managed modes are much slower. The encoder has to do a lot more
>> work to figure out an encoding whilst also meeting the bitrate
>> constraints. The reason 'CBR' seemed faster to you was that you weren't
>> using a CBR mode at all. It's a choice the user has to make - if they
>> need the hard constraints (which is possible, though rare, for streaming
>> purposes, and maybe for some other purposes too), then it's worth 
>> using > twice the cpu.
>
>I need such features exactly for streaming. What I'm looking for is the 
>possibility to specify a maximum bitrate, so that users with limited 
>bandwith can be sure that they can listen to the stream, so as their 
>bandwidth is not exceeded.

For this purpose, the best approach (generally speaking) is to do this:
vorbis_encode_init(&vi);
vorbis_encode_setup_vbr(&vi, ... );

Then _optionally_ (for example, my machine doesn't have sufficient cpu
to do cd-rate audio with management turned on, so I'd prefer to have
full VBR encoding, even though it's not ideal for some streaming
purposes - experience shows that it's good enough for most users), do this:

{
  struct ovectl_ratemanage_arg ai;
  vorbis_encode_ctl(&vi, OV_ECTL_RATEMANAGE_GET, &ai);
  ai.bitrate_hard_max = max_bitrate; // You only care about max, most
                                     // likely. You can also set min,
                                     // but it's probably not useful.
  ai.management_active = 1; // turn management on, so the above takes
                            // effect.
  vorbis_encode_ctl(&vi, OV_ECTL_RATEMANAGE_SET, &ai);
}

Finally,

vorbis_encode_setup_init(&vi);

will finish mode configuration. 

Michael

<p><p><p>--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'vorbis-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.