From 373dc625f82b47096893add42c4472e4a57ab7eb Mon Sep 17 00:00:00 2001 From: Aki Date: Wed, 9 Feb 2022 22:23:03 +0100 Subject: Moved third-party libraries to a separate subdirectory --- contrib/vorbis/doc/vorbisenc/Makefile.am | 11 + contrib/vorbis/doc/vorbisenc/changes.html | 104 ++++++ contrib/vorbis/doc/vorbisenc/examples.html | 133 +++++++ contrib/vorbis/doc/vorbisenc/index.html | 40 +++ .../doc/vorbisenc/ovectl_ratemanage2_arg.html | 92 +++++ .../doc/vorbisenc/ovectl_ratemanage_arg.html | 92 +++++ contrib/vorbis/doc/vorbisenc/overview.html | 382 +++++++++++++++++++++ contrib/vorbis/doc/vorbisenc/reference.html | 54 +++ contrib/vorbis/doc/vorbisenc/style.css | 7 + .../vorbis/doc/vorbisenc/vorbis_encode_ctl.html | 183 ++++++++++ .../vorbis/doc/vorbisenc/vorbis_encode_init.html | 88 +++++ .../doc/vorbisenc/vorbis_encode_init_vbr.html | 81 +++++ .../doc/vorbisenc/vorbis_encode_setup_init.html | 88 +++++ .../doc/vorbisenc/vorbis_encode_setup_managed.html | 102 ++++++ .../doc/vorbisenc/vorbis_encode_setup_vbr.html | 90 +++++ 15 files changed, 1547 insertions(+) create mode 100644 contrib/vorbis/doc/vorbisenc/Makefile.am create mode 100644 contrib/vorbis/doc/vorbisenc/changes.html create mode 100644 contrib/vorbis/doc/vorbisenc/examples.html create mode 100644 contrib/vorbis/doc/vorbisenc/index.html create mode 100644 contrib/vorbis/doc/vorbisenc/ovectl_ratemanage2_arg.html create mode 100644 contrib/vorbis/doc/vorbisenc/ovectl_ratemanage_arg.html create mode 100644 contrib/vorbis/doc/vorbisenc/overview.html create mode 100644 contrib/vorbis/doc/vorbisenc/reference.html create mode 100644 contrib/vorbis/doc/vorbisenc/style.css create mode 100644 contrib/vorbis/doc/vorbisenc/vorbis_encode_ctl.html create mode 100644 contrib/vorbis/doc/vorbisenc/vorbis_encode_init.html create mode 100644 contrib/vorbis/doc/vorbisenc/vorbis_encode_init_vbr.html create mode 100644 contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_init.html create mode 100644 contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_managed.html create mode 100644 contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_vbr.html (limited to 'contrib/vorbis/doc/vorbisenc') diff --git a/contrib/vorbis/doc/vorbisenc/Makefile.am b/contrib/vorbis/doc/vorbisenc/Makefile.am new file mode 100644 index 0000000..bbab3c5 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/Makefile.am @@ -0,0 +1,11 @@ +## Process this file with automake to produce Makefile.in + +docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)/vorbisenc + +doc_DATA = changes.html examples.html index.html ovectl_ratemanage2_arg.html \ + ovectl_ratemanage_arg.html overview.html reference.html style.css\ + vorbis_encode_ctl.html vorbis_encode_init.html vorbis_encode_setup_init.html \ + vorbis_encode_setup_managed.html vorbis_encode_setup_vbr.html \ + vorbis_encode_init_vbr.html + +EXTRA_DIST = $(doc_DATA) diff --git a/contrib/vorbis/doc/vorbisenc/changes.html b/contrib/vorbis/doc/vorbisenc/changes.html new file mode 100644 index 0000000..eb8460e --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/changes.html @@ -0,0 +1,104 @@ + + + +libvorbisenc - Documentation + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

Libvorbisenc API changes 1.0 through 1.1

+ +This document describes API additions to libvorbisenc between release +1.0 and 1.1. + +

1.0.1

+ +The programming API and binary application ABI are unchanged and fully +forward/backward compatible between release 1.0 and 1.0.1. Libvorbis, +libvorbisenc and libvorbisfile must match versions amongst themselves, +however. + +

1.1

+ +The binary ABI from release 1.0.1 to 1.1 is backward compatible; +applications linked against libvorbis/libvorbisenc 1.0 and 1.0.1 will +continue to function correctly when upgrading the libvorbis and +libvorbisenc dynamic libraries without re-linking.

+ +Release 1.1 adds several possible requests to the libvorbisenc vorbis_encode_ctl() call in order to +reflect the shift to bit-reservoir style +bitrate management. In addition, several vorbis_encode_ctl() requests are +deprecated (but functional) as they are redered semantically obsolete +by the new bitrate management.

+ +

Deprecated in 1.1

+ +These calls are still available to older codebases to preserve +compatability; the fields of the ovectl_ratemanage_arg argument +are mapped as closely as possible to the fields of the new ovectl_ratemanage2_arg +structure. + +
+
OV_ECTL_RATEMANAGE_GET:
Use OV_ECTL_RATEMANAGE2_GET +instead. + + +
OV_ECTL_RATEMANAGE_SET:
Use OV_ECTL_RATEMANAGE2_SET +instead. + +
OV_ECTL_RATEMANAGE_AVG:
Use OV_ECTL_RATEMANAGE2_SET +instead. + +
OV_ECTL_RATEMANAGE_HARD:
Use OV_ECTL_RATEMANAGE2_SET +instead. +
+ +

Newly added in 1.1

+ +The following calls are added in 1.1 to semantically reflect movement +to a bit-reservoir-based bitrate +management scheme by introducing the ovectl_ratemanage2_arg +structure in order to better represent the abilities of the bitrate +manager.

+ +

+
OV_ECTL_RATEMANAGE2_GET
+ +Used to query the current state of bitrate management setup. + +
OV_ECTL_RATEMANAGE2_SET
+ +Used to set or alter bitrate management settings. +
+ +

+
+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + diff --git a/contrib/vorbis/doc/vorbisenc/examples.html b/contrib/vorbis/doc/vorbisenc/examples.html new file mode 100644 index 0000000..1fcc7e0 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/examples.html @@ -0,0 +1,133 @@ + + + +libvorbisenc - Documentation + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

Libvorbisenc Setup Examples

+ +VBR is always the recommended mode for Vorbis encoding when +there's no need to impose bitrate constraints. True VBR encoding will +always produce the most consistent quality output as well as the +highest quality for a the bits used. + +

The following code examples prepare a +vorbis_info structure for encoding +use with libvorbis.

+ +

Example: encoding using a VBR quality mode

+ + +
 
+   vorbis_info_init(&vi);
+
+  /*********************************************************************
+   Encoding using a VBR quality mode.  The usable range is -.1
+   (lowest quality, smallest file) to 1.0 (highest quality, largest file).
+   Example quality mode .4: 44kHz stereo coupled, roughly 128kbps VBR 
+   *********************************************************************/
+  
+   ret = vorbis_encode_init_vbr(&vi,2,44100,.4);
+
+  /*********************************************************************
+   do not continue if setup failed; this can happen if we ask for a
+   mode that libVorbis does not support (eg, too low a quality mode, etc,
+   will return 'OV_EIMPL')
+   *********************************************************************/
+
+   if(ret) exit(1);
+
+ +

Example: encoding using average bitrate (ABR)

+ + +
 
+   vorbis_info_init(&vi);
+
+  /*********************************************************************
+   Encoding using an average bitrate mode (ABR).
+   example: 44kHz stereo coupled, average 128kbps ABR 
+   *********************************************************************/
+  
+   ret = vorbis_encode_init(&vi,2,44100,-1,128000,-1);
+
+  /*********************************************************************
+   do not continue if setup failed; this can happen if we ask for a
+   mode that libVorbis does not support (eg, too low a bitrate, etc,
+   will return 'OV_EIMPL')
+   *********************************************************************/
+
+   if(ret) exit(1);
+
+ +

Example: encoding using constant bitrate (CBR)

+ + +
 
+   vorbis_info_init(&vi);
+
+  /*********************************************************************
+   Encoding using a constant bitrate mode (CBR).
+   example: 44kHz stereo coupled, average 128kbps CBR 
+   *********************************************************************/
+  
+   ret = vorbis_encode_init(&vi,2,44100,128000,128000,128000);
+
+  /*********************************************************************
+   do not continue if setup failed; this can happen if we ask for a
+   mode that libVorbis does not support (eg, too low a bitrate, etc,
+   will return 'OV_EIMPL')
+   *********************************************************************/
+
+   if(ret) exit(1);
+
+ +

Example: encoding using VBR selected by approximate bitrate

+ + +
 
+   vorbis_info_init(&vi);
+
+  /*********************************************************************
+   Encode using a quality mode, but select that quality mode by asking for
+   an approximate bitrate.  This is not ABR, it is true VBR, but selected
+   using the bitrate interface, and then turning bitrate management off:
+   *********************************************************************/
+
+   ret = ( vorbis_encode_setup_managed(&vi,2,44100,-1,128000,-1) ||
+           vorbis_encode_ctl(&vi,OV_ECTL_RATEMANAGE2_SET,NULL) ||
+           vorbis_encode_setup_init(&vi));
+
+  /*********************************************************************
+   do not continue if setup failed; this can happen if we ask for a
+   mode that libVorbis does not support (eg, too low a bitrate, etc,
+   will return 'OV_EIMPL')
+   *********************************************************************/
+
+   if(ret) exit(1);
+
+ +

+
+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + diff --git a/contrib/vorbis/doc/vorbisenc/index.html b/contrib/vorbis/doc/vorbisenc/index.html new file mode 100644 index 0000000..ec9b988 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/index.html @@ -0,0 +1,40 @@ + + + +libvorbisenc - Documentation + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

Libvorbisenc Documentation

+ +

+Libvorbisenc is a convenient API for setting up an encoding environment using libvorbis. Libvorbisenc encapsulates the actions needed to set up the encoder properly. +

+libvorbisenc api overview
+libvorbisenc api reference
+libvorbisenc api changes from 1.0 and 1.0.1
+libvorbisenc encode setup examples
+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + diff --git a/contrib/vorbis/doc/vorbisenc/ovectl_ratemanage2_arg.html b/contrib/vorbis/doc/vorbisenc/ovectl_ratemanage2_arg.html new file mode 100644 index 0000000..3d9d417 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/ovectl_ratemanage2_arg.html @@ -0,0 +1,92 @@ + + + +vorbis - datatype - ovectl_ratemanage2_arg + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

ovectl_ratemanage2_arg

+ +

declared in "vorbis/vorbisenc.h"

+ +

+ +The ovectl_ratemanage2_arg structure is used with vorbis_encode_ctl() and the OV_ECTL_RATEMANAGE2_GET and +OV_ECTL_RATEMANAGE2_SET calls in order to query and modify specifics +of the encoder's bitrate management configuration. + +

+ + + + + +
+
struct ovectl_ratemanage2_arg {
+  int    management_active;
+
+  long   bitrate_limit_min_kbps;
+  long   bitrate_limit_max_kbps;
+  long   bitrate_limit_reservoir_bits;
+  double bitrate_limit_reservoir_bias;
+
+  long   bitrate_average_kbps;
+  double bitrate_average_damping;
+};
+
+ +

Relevant Struct Members

+
+
management_active
+
nonzero if bitrate management is active
+ +
bitrate_limit_min_kbps
+
Lower allowed bitrate limit in kilobits per second
+
bitrate_limit_max_kbps
+
Upper allowed bitrate limit in kilobits per second
+
bitrate_limit_reservoir_bits
+
Size of the bitrate reservoir in bits
+
bitrate_limit_reservoir_bias
+ +
Regulates the bitrate reservoir's preferred fill level in a range +from 0.0 to 1.0; 0.0 tries to bank bits to buffer against future +bitrate spikes, 1.0 buffers against future sudden drops in +instantaneous bitrate. Default is 0.1
+ +
bitrate_average_kbps
+
Average bitrate setting in kilobits per second
+ +
bitrate_average_damping
Slew rate limit setting +for average bitrate adjustment; sets the minimum time in seconds the +bitrate tracker may swing from one extreme to the other when boosting +or damping average bitrate.
+ + + +
+ + +

+
+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + diff --git a/contrib/vorbis/doc/vorbisenc/ovectl_ratemanage_arg.html b/contrib/vorbis/doc/vorbisenc/ovectl_ratemanage_arg.html new file mode 100644 index 0000000..48f5a62 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/ovectl_ratemanage_arg.html @@ -0,0 +1,92 @@ + + + +vorbis - datatype - ovectl_ratemanage_arg + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

ovectl_ratemanage_arg

+ +

declared in "vorbis/vorbisenc.h"

+ +

+ +The ovectl_ratemanage_arg structure is used with vorbis_encode_ctl() and the OV_ECTL_RATEMANAGE_GET, +OV_ECTL_RATEMANAGE_SET, OV_ECTL_RATEMANAGE_AVG, +OV_ECTL_RATEMANAGE_HARD calls in order to query and modify specifics +of the encoder's bitrate management configuration. Note that this is +a deprecated interface; please use vorbis_encode_ctl() with the ovectl_ratemanage2_arg struct +and OV_ECTL_RATEMANAGE2_GET and OV_ECTL_RATEMANAGE2_SET calls in new +code. + +

+ + + + + +
+
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;
+};
+
+ +

Relevant Struct Members

+
+ +
management_active
+
nonzero if bitrate management is active
+ +
bitrate_hard_min
+
hard lower limit (in kilobits per second) below which the stream bitrate will never be allowed for any given bitrate_hard_window seconds of time.
+
bitrate_hard_max
+
hard upper limit (in kilobits per second) above which the stream bitrate will never be allowed for any given bitrate_hard_window seconds of time.
+
bitrate_hard_window
+
the window period (in seconds) used to regulate the hard bitrate minimum and maximum
+ +
bitrate_av_lo
+
soft lower limit (in kilobits per second) below which the average bitrate tracker will start nudging the bitrate higher.
+
bitrate_av_hi
+
soft upper limit (in kilobits per second) above which the average bitrate tracker will start nudging the bitrate lower.
+
bitrate_av_window
+
the window period (in seconds) used to regulate the average bitrate minimum and maximum.
+
bitrate_av_window_center
+
Regulates the relative centering of the average and hard windows; in libvorbis 1.0 and 1.0.1, the hard window regulation overlapped but followed the average window regulation. In libvorbis 1.1 a bit-reservoir interface replaces the old windowing interface; the older windowing interface is simulated and this field has no effect.
+ +
+ + +

+
+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + diff --git a/contrib/vorbis/doc/vorbisenc/overview.html b/contrib/vorbis/doc/vorbisenc/overview.html new file mode 100644 index 0000000..51af7b5 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/overview.html @@ -0,0 +1,382 @@ + + + +libvorbisenc - API Overview + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

Libvorbisenc API Overview

+ +

Libvorbisenc is an encoding convenience library intended to +encapsulate the elaborate setup that libvorbis requires for encoding. +Libvorbisenc gives easy access to all high-level adjustments an +application may require when encoding and also exposes some low-level +tuning parameters to allow applications to make detailed adjustments +to the encoding process.

+ +All the libvorbisenc routines are declared in "vorbis/vorbisenc.h". + +Note: libvorbis and libvorbisenc always +encode in a single pass. Thus, all possible encoding setups will work +properly with live input and produce streams that decode properly when +streamed. See the subsection titled "managed bitrate +modes" for details on setting limits on bitrate usage when Vorbis +streams are used in a limited-bandwidth environment. + +

workflow

+ +

Libvorbisenc is used only during encoder setup; its function +is to automate initialization of a multitude of settings in a +vorbis_info structure which libvorbis then uses as a reference +during the encoding process. Libvorbisenc plays no part in the +encoding process after setup. + +

Encode setup using libvorbisenc consists of three steps: + +

    +
  1. high-level initialization of a vorbis_info structure by +calling one of vorbis_encode_setup_vbr() or vorbis_encode_setup_managed() +with the basic input audio parameters (rate and channels) and the +basic desired encoded audio output parameters (VBR quality or ABR/CBR +bitrate)

    + +

  2. optional adjustment of the basic setup defaults using vorbis_encode_ctl()

    + +

  3. calling vorbis_encode_setup_init() to +finalize the high-level setup into the detailed low-level reference +values needed by libvorbis to encode audio. The vorbis_info +structure is then ready to use for encoding by libvorbis.

    + +

+ +These three steps can be collapsed into a single call by using vorbis_encode_init_vbr to set up a +quality-based VBR stream or vorbis_encode_init to set up a managed +bitrate (ABR or CBR) stream.

+ +

adjustable encoding parameters

+ +

input audio parameters

+ +

+ + + + + + + + + + + + + +
parameterdescription
sampling rate +The sampling rate (in samples per second) of the input audio. Common examples are 8000 for telephony, 44100 for CD audio and 48000 for DAT. Note that a mono sample (one center value) and a stereo sample (one left value and one right value) both are a single sample. + +
channels + +The number of channels encoded in each input sample. By default, +stereo input modes (two channels) are 'coupled' by Vorbis 1.1 such +that the stereo relationship between the samples is taken into account +when encoding. Stereo coupling my be disabled by using vorbis_encode_ctl() with OV_ECTL_COUPLE_SET. + +
+ +

quality and VBR modes

+ +Vorbis is natively a VBR codec; a user requests a given constant +quality and the encoder keeps the encoding quality constant +while allowing the bitrate to vary. 'Quality' modes (Variable BitRate) +will always produce the most consistent encoding results as well as +the highest quality for the amount of bits used. + +

+ + + + + + + + + +
parameterdescription
quality +A decimal float value requesting a desired quality. Libvorbisenc 1.1 allows quality requests in the range of -0.1 (lowest quality, smallest files) through +1.0 (highest-quality, largest files). Quality -0.1 is intended as an ultra-low setting in which low bitrate is much more important than quality consistency. Quality settings 0.0 and above are intended to produce consistent results at all times. + +
+ + +

managed bitrate modes

+ +Although the Vorbis codec is natively VBR, libvorbis includes +infrastructure for 'managing' the bitrate of streams by setting +minimum and maximum usage constraints, as well as functionality for +nudging a stream toward a desired average value. These features +should only be used when there is a requirement to limit +bitrate in some way. Although the difference is usually slight, +managed bitrate modes will always produce output inferior to VBR +(given equal bitrate usage). Setting overly or impossibly tight +bitrate management requirements can affect output quality dramatically +for the worse.

+ +Beginning in libvorbis 1.1, bitrate management is implemented using a +bit-reservoir algorithm. The encoder has a fixed-size +reservoir used as a 'savings account' in encoding. When a frame is +smaller than the target rate, the unused bits go into the reservoir so +that they may be used by future frames. When a frame is larger than +target bitrate, it draws 'banked' bits out of the reservoir. Encoding +is managed so that the reservoir never goes negative (when a maximum +bitrate is specified) or fills beyond a fixed limit (when a minimum +bitrate is specified). An 'average bitrate' request is used as the +set-point in a long-range bitrate tracker which adjusts the encoder's +aggressiveness up or down depending on whether or not frames are coming +in larger or smaller than the requested average point. + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parameterdescription
maximum bitrate The maximum allowed bitrate, set in bits +per second. If the bitrate would otherwise rise such that oversized +frames would underflow the bit-reservoir by consuming banked bits, +bitrate management will force the encoder to use fewer bits per frame +by encoding with a more aggressive psychoacoustic model.

This +setting is a hard limit; the bitstream will never be allowed, under +any circumstances, to increase above the specified bitrate over the +average period set by the reservoir; it may momentarily rise over if +inspected on a granularity much finer than the average period across +the reservoir. Normally, the encoder will conserve bits gracefully by +using more aggressive psychoacoustics to shrink a frame when forced +to. However, if the encoder runs out of means of gracefully shrinking +a frame, it will simply take the smallest frame it can otherwise +generate and truncate it to the maximum allowed length. Note that +this is not an error and although it will obviously adversely affect +audio quality, a Vorbis decoder will be able to decode a truncated +frame into audio. + +

average bitrate + +The average desired bitrate of a stream, set +in bits per second. Average bitrate is tracked via a reservoir like +minimum and maximum bitrate, however the averaging reservior does not +impose a hard limit; it is used to nudge the bitrate toward the +desired average by slowly adjusting the psychoacoustic aggressiveness. +As such, the reservoir size does not affect the average bitrate +behavior. Because this setting alone is not used to impose hard +bitrate limits, the bitrate of a stream produced using only the +average bitrate constraint will track the average over time +but not necessarily adhere strictly to that average for any given +period. Should a strict localized average be required, average +bitrate should be used along with minimum bitrate and +maximum bitrate. +
minimum bitrate + The minimum allowed bitrate, set in bits per second. If +the bitrate would otherwise fall such that undersized frames would +overflow the bit-reservoir with unused bits, bitrate management will +force the encoder to use more bits per frame by encoding with a less +aggressive psychoacoustic model.

This setting is a hard limit; the +bitstream will never be allowed, under any circumstances, to drop +below the specified bitrate over the average period set by the +reservoir; it may momentarily fall under if inspected on a granularity +much finer than the average period across the reservoir. Normally, +the encoder will fill out undersided frames with additional useful +coding information by increasing the perceived quality of the stream. +If the encoder runs out of useful ways to consume more bits, it will +pad frames out with zeroes. +

reservoir size The size of the minimum/maximum bitrate +tracking reservoir, set in bits. The reservoir is used as a 'bit +bank' to average out localized surges and dips in bitrate while +providing predictable, guaranteed buffering behavior for streams to be +used in situations with constrained transport bandwidth. The default +setting is two seconds of average bitrate.

+ +When a single frame is larger than the maximum allowed overall +bitrate, the bits are 'borrowed' from the bitrate reservoir; if the +reservoir contains insufficient bits to cover the defecit, the encoder +must find some way to reduce the frame size.

+ +When a frame is under the minimum limit, the surplus bits are placed +into the reservoir, banking them for future use. If the reservoir is +already full of banked bits, the encoder is forced to find some way to +make the frame larger.

+ +If the frame size is between the minimum and maximum rates (thus +implying the minimum and maximum allowed rates are different), the +reservoir gravitates toward a fill point configured by the +reservoir bias setting described next. If the reservoir is +fuller than the fill point (a 'surplus of surplus'), the encoder will +consume a number bits from the reservoir equal to the number of the +bits by which the frame exceeds minimum size. If the reservoir is +emptier than the fillpoint (a 'surplus of defecit'), bits are returned +to the reservoir equaling the current frame's number of bits under the +maximum frame size. The idea of the fill point is to buffer against +both underruns and overruns, by trying to hold the reservoir to a +middle course. +

reservoir bias + +Reservoir bias is a setting between 0.0 and 1.0 that biases bitrate +management toward smoothing bitrate spikes (0.0) or bitrate peaks +(1.0); the default setting is 0.1.

+ +Using settings toward 0.0 causes the bitrate manager to hoard bits in +the bit reservoir such that there is a large pool of banked surplus to +draw upon during short spikes in bitrate. As a result, the encoder +will react less aggressively and less drastically to curtail framesize +during brief surges in bitrate.

+ +Using settings toward 1.0 causes the bitrate manager to empty the bit +reservoir such that there is a large buffer available to store surplus +bits during sudden drops in bitrate. As a result, the encoder will +react less aggressively and less drastically to support minimum frame +sizes during drops in bitrate and will tend not to store any extra +bits in the reservoir for future bitrate spikes.

+ +

average track damping + +A decimal value, in seconds, that controls how quickly the average +bitrate tracker is allowed to slew from enforcing minimum frame sizes +to maximum framesizes and vice versa. Default value is 1.5 +seconds.

+ +When the 'average bitrate' setting is in use, the average bitrate +tracker uses an unbounded reservoir to track overall bitrate-to-date +in the stream. When bitrates are too low, the tracker will try to +nudge bitrates up and when the bitrate is too high, nudge it down. +The damping value regulates the maximum strength of the nudge; it +describes, in seconds, how quickly the tracker may transition from an +extreme nudge in one direction to an extreme nudge in the other.

+ +

+ +

encoding model adjustments

+ +The vorbis_encode_ctl() call provides +a generalized interface for making encoding setup adjustments to the +basic high-level setup provided by vorbis_encode_setup_vbr() or vorbis_encode_setup_managed(). +In reality, these two calls use vorbis_encode_ctl() internally, and vorbis_encode_ctl() can be used to adjust +most of the parameters set by other calls.

+ +In Vorbis 1.1, vorbis_encode_ctl() can +adjust the following additional parameters not described elsewhere: + +

+ + + + + + + + + + + + + + + + + + + + +
parameterdescription
management mode Configures whether or not bitrate +management is in use or not. Normally, this value is set implicitly +during encoding setup; however, the supported means of selecting a +quality mode by bitrate (that is, requesting a true VBR stream, but +doing so by asking for an approximate bitrate) is to use vorbis_encode_setup_managed() +and then to explicitly turn off bitrate management by calling vorbis_encode_ctl() with OV_ECTL_RATEMANAGE2_SET +
coupling Stereo encoding (and in the future, surround +encodings) are normally encoded assuming the channels form a stereo +image and that lossy-stereo modelling is appropriate; this is called +'coupling'. Stereo coupling may be explicitly enabled or disabled. +
lowpass Sets the hard lowpass of a given encoding mode; +this may be used to conserve a few bits in high-rate audio that has +limited bandwidth, or in testing of the encoder's acoustic model. The +encoder is generally already configured with ideal lowpasses (if any +at all) for given modes; use of this parameter is strongly discouraged +if the point is to try to 'improve' a given encoding mode for general +encoding. +
impulse coding aggressiveness By default, libvorbis +attempts to compromise between preventing wide bitrate swings and +high-resolution impulse coding (which is required for the crispest +possible attacks, but also requires a relatively large momentary +bitrate increase). This parameter allows an application to tune the +compromise or eliminate it; A value of 0.0 indicates normal behavior +while a value of -15.0 requests maximum possible impulse +resolution.
+ + +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + + diff --git a/contrib/vorbis/doc/vorbisenc/reference.html b/contrib/vorbis/doc/vorbisenc/reference.html new file mode 100644 index 0000000..59d6432 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/reference.html @@ -0,0 +1,54 @@ + + + +Vorbisfile API Reference + + + + + + + + + +

vorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

Vorbisenc API Reference

+ +

Data Structures

+ +

+vorbis_info (from libvorbis)
+ovectl_ratemanage_arg
+ovectl_ratemanage2_arg
+

+ +

Encoder Setup

+ +

+vorbis_encode_ctl()
+vorbis_encode_init()
+vorbis_encode_init_vbr()
+vorbis_encode_setup_init()
+vorbis_encode_setup_managed()
+vorbis_encode_setup_vbr()
+

+ +

The actual encoding is done using the libvorbis API.

+ +
+
+
+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + diff --git a/contrib/vorbis/doc/vorbisenc/style.css b/contrib/vorbis/doc/vorbisenc/style.css new file mode 100644 index 0000000..81cf417 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/style.css @@ -0,0 +1,7 @@ +BODY { font-family: Helvetica, sans-serif } +TD { font-family: Helvetica, sans-serif } +P { font-family: Helvetica, sans-serif } +H1 { font-family: Helvetica, sans-serif } +H2 { font-family: Helvetica, sans-serif } +H4 { font-family: Helvetica, sans-serif } +P.tiny { font-size: 8pt } diff --git a/contrib/vorbis/doc/vorbisenc/vorbis_encode_ctl.html b/contrib/vorbis/doc/vorbisenc/vorbis_encode_ctl.html new file mode 100644 index 0000000..13de574 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/vorbis_encode_ctl.html @@ -0,0 +1,183 @@ + + + +libvorbisenc - function - vorbis_encode_ctl + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

vorbis_encode_ctl

+ +

declared in "vorbis/vorbisenc.h";

+ +

This function implements a generic interface to miscellaneous +encoder settings similar to the clasasic UNIX 'ioctl()' system call. +Applications may use vorbis_encode_ctl() to query or set bitrate +management or quality mode details by using one of several +request arguments detailed below. Vorbis_encode_ctl() must be +called after one of vorbis_encode_setup_managed() +or vorbis_encode_setup_vbr(). +When used to modify settings, vorbis_encode_ctl() must be called +before vorbis_encode_setup_init(). + +

+

+ + + + +
+

+extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);
+
+
+
+ +

Parameters

+
+
vi
+
Pointer to an initialized vorbis_info struct.

+

request
+
Specifies the desired action; possible request fields are detailed below.

+

arg
+
void * pointing to a data structure matching the request argument.

+

+ +

Requests

+
+ +
OV_ECTL_RATEMANAGE2_GET
+ +
Argument: struct +ovectl_ratemanage2_arg *
Used to query the current +encoder bitrate management setting. Also used to initialize fields of +an ovectl_ratemanage2_arg structure for use with +OV_ECTL_RATEMANAGE2_SET.

+ +

OV_ECTL_RATEMANAGE2_SET
+
Argument: struct +ovectl_ratemanage2_arg *
Used to set the current +encoder bitrate management settings to the values listed in the +ovectl_ratemanage2_arg. Passing a NULL pointer will disable bitrate +management. +

+ +

OV_ECTL_LOWPASS_GET
+
Argument: double *
Returns the current encoder hard-lowpass +setting (kHz) in the double pointed to by arg. +

+ +

OV_ECTL_LOWPASS_SET
+
Argument: double *
Sets the encoder hard-lowpass to the value +(kHz) pointed to by arg. Valid lowpass settings range from 2 to 99. +

+ +

OV_ECTL_IBLOCK_GET
+
Argument: double *
Returns the current encoder impulse +block setting in the double pointed to by arg.

+ +

OV_ECTL_IBLOCK_SET
Argument: double *
Sets +the impulse block bias to the the value pointed to by arg; valid range +is -15.0 to 0.0 [default]. A negative impulse block bias will direct +to encoder to use more bits when incoding short blocks that contain +strong impulses, thus improving the accuracy of impulse encoding.

+ +

OV_ECTL_COUPLING_GET
+
Argument: int *
+Returns the current encoder coupling enabled/disabled +setting in the int pointed to by arg. +

+ +

OV_ECTL_COUPLING_SET
+
Argument: int *
+Enables/disables channel coupling in multichannel encoding according to arg. +*arg of zero disables all channel coupling, nonzero allows the encoder to use +coupling if a coupled mode is available for the input. At present, coupling +is available for stereo and 5.1 input modes. +

+ +

OV_ECTL_RATEMANAGE_GET [deprecated]
+
+ +Argument: struct +ovectl_ratemanage_arg *
Old interface to querying bitrate +management settings; deprecated after move to bit-reservoir style +management in 1.1 rendered this interface partially obsolete. Please +use OV_ECTL_RATEMANGE2_GET instead. + +

+ +

OV_ECTL_RATEMANAGE_SET [deprecated]
+
+Argument: struct +ovectl_ratemanage_arg *
Old interface to modifying bitrate +management settings; deprecated after move to bit-reservoir style +management in 1.1 rendered this interface partially obsolete. Please +use OV_ECTL_RATEMANGE2_SET instead. +

+ +

OV_ECTL_RATEMANAGE_AVG [deprecated]
+
+Argument: struct +ovectl_ratemanage_arg *
Old interface to setting +average-bitrate encoding mode; deprecated after move to bit-reservoir +style management in 1.1 rendered this interface partially obsolete. +Please use OV_ECTL_RATEMANGE2_SET instead. +

+ +

OV_ECTL_RATEMANAGE_HARD [deprecated]
+
+Argument: struct +ovectl_ratemanage_arg *
Old interface to setting +bounded-bitrate encoding modes; deprecated after move to bit-reservoir +style management in 1.1 rendered this interface partially obsolete. +Please use OV_ECTL_RATEMANGE2_SET instead. +

+ + +

+ + +

Return Values

vorbis_encode_ctl() returns zero on success, +placing any further return information (such as the result of a query) +into the storage pointed to by *arg. On error, +vorbis_encode_ctl() may return one of the following error codes: + +
+ +
OV_EINVAL
Invalid argument, or an attempt to modify a +setting after calling vorbis_encode_setup_init().

+ +

OV_EIMPL
Unimplemented or unknown request

+ +

+ +

+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ + + + + diff --git a/contrib/vorbis/doc/vorbisenc/vorbis_encode_init.html b/contrib/vorbis/doc/vorbisenc/vorbis_encode_init.html new file mode 100644 index 0000000..d371899 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/vorbis_encode_init.html @@ -0,0 +1,88 @@ + + + +libvorbisenc - function - vorbis_encode_init + + + + + + + + + +

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

+ +

vorbis_encode_init

+ +

declared in "vorbis/vorbisenc.h";

+ +

This is the primary function within libvorbisenc for setting up managed bitrate modes. +

Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear should be called. +

The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set constraints for the encoded file. This function uses these settings to select the appropriate encoding mode and set it up. +

+

+ + + + +
+

+extern int vorbis_encode_init(vorbis_info *vi,
+			      long channels,
+			      long rate,
+			      
+			      long max_bitrate,
+			      long nominal_bitrate,
+			      long min_bitrate);
+
+
+
+ +

Parameters

+
+
vi
+
Pointer to an initialized vorbis_info struct.
+
channels
+
The number of channels to be encoded.
+
rate
+
The sampling rate of the source audio.
+
max_bitrate
+
Desired maximum bitrate (limit). -1 indicates unset.
+
nominal_bitrate
+
Desired average, or central, bitrate. -1 indicates unset.
+
min_bitrate
+
Desired minimum bitrate. -1 indicates unset.
+
+ + +

Return Values

+
+
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + + + + + diff --git a/contrib/vorbis/doc/vorbisenc/vorbis_encode_init_vbr.html b/contrib/vorbis/doc/vorbisenc/vorbis_encode_init_vbr.html new file mode 100644 index 0000000..800d257 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/vorbis_encode_init_vbr.html @@ -0,0 +1,81 @@ + + + +libvorbisenc - function - vorbis_encode_init_vbr + + + + + + + + + +

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + +

    vorbis_encode_init_vbr

    + +

    declared in "vorbis/vorbisenc.h";

    + +

    This is the primary function within libvorbisenc for setting up variable bitrate ("quality" based) modes. +

    Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear should be called. +

    +

    + + + + +
    +
    
+extern int vorbis_encode_init_vbr(vorbis_info *vi,
+			      long channels,
+			      long rate,
+			      
+			      float base_quality);
+
+
    +
    + +

    Parameters

    +
    +
    vi
    +
    Pointer to an initialized vorbis_info struct.
    +
    channels
    +
    The number of channels to be encoded.
    +
    rate
    +
    The sampling rate of the source audio.
    +
    base_quality
    +
    Desired quality level, currently from -0.1 to 1.0 (lo to hi).
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + + + + + diff --git a/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_init.html b/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_init.html new file mode 100644 index 0000000..aa2c904 --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_init.html @@ -0,0 +1,88 @@ + + + +libvorbisenc - function - vorbis_encode_setup_init + + + + + + + + + +

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + +

    vorbis_encode_setup_init

    + +

    declared in "vorbis/vorbisenc.h";

    + +

    This function performs the last stage of three-step encoding setup, as described in the API overview under managed bitrate modes. + +

    Before this function is called, the vorbis_info struct should be initialized +by using vorbis_info_init() from the libvorbis API, one of vorbis_encode_setup_managed() +or vorbis_encode_setup_vbr() +called to initialize the high-level encoding setup, and vorbis_encode_ctl() called if +necessary to make encoding setup changes. vorbis_encode_setup_init() +finalizes the highlevel encoding structure into a complete encoding +setup after which the application may make no further setup changes.

    + +After encoding, vorbis_info_clear should be called. +

    +

    + + + + +
    +
    
+extern int vorbis_encode_setup_init(vorbis_info *vi);
+
+
    +
    + +

    Parameters

    +
    +
    vi
    +
    Pointer to an initialized vorbis_info struct.
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + + + + + diff --git a/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_managed.html b/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_managed.html new file mode 100644 index 0000000..0389dde --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_managed.html @@ -0,0 +1,102 @@ + + + +libvorbisenc - function - vorbis_encode_setup_managed + + + + + + + + + +

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + +

    vorbis_encode_setup_managed

    + +

    declared in "vorbis/vorbisenc.h";

    + +

    This function performs step-one of a three-step bitrate-managed +encode setup. It functions similarly to the one-step setup performed +by vorbis_encode_init() but +allows an application to make further encode setup tweaks using vorbis_encode_ctl() before finally +calling vorbis_encode_setup_init() to +complete the setup process. + +

    Before this function is called, the vorbis_info struct should be initialized +by using vorbis_info_init() from the libvorbis API. After encoding, +vorbis_info_clear should be called. + +

    The max_bitrate, nominal_bitrate, and min_bitrate settings are used +to set constraints for the encoded file. This function uses these +settings to select the appropriate encoding mode and set it up. +

    +

    + + + + +
    +
    
+extern int vorbis_encode_init(vorbis_info *vi,
+			      long channels,
+			      long rate,
+			      
+			      long max_bitrate,
+			      long nominal_bitrate,
+			      long min_bitrate);
+
+
    +
    + +

    Parameters

    +
    +
    vi
    +
    Pointer to an initialized vorbis_info struct.
    +
    channels
    +
    The number of channels to be encoded.
    +
    rate
    +
    The sampling rate of the source audio.
    +
    max_bitrate
    +
    Desired maximum bitrate (limit). -1 indicates unset.
    +
    nominal_bitrate
    +
    Desired average, or central, bitrate. -1 indicates unset.
    +
    min_bitrate
    +
    Desired minimum bitrate. -1 indicates unset.
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + + + + + diff --git a/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_vbr.html b/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_vbr.html new file mode 100644 index 0000000..e390edf --- /dev/null +++ b/contrib/vorbis/doc/vorbisenc/vorbis_encode_setup_vbr.html @@ -0,0 +1,90 @@ + + + +libvorbisenc - function - vorbis_encode_setup_vbr + + + + + + + + + +

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + +

    vorbis_encode_setup_vbr

    + +

    declared in "vorbis/vorbisenc.h";

    + +

    This function performs step-one of a three-step variable bitrate +(quality-based) encode setup. It functions similarly to the one-step +setup performed by vorbis_encode_init_vbr() but +allows an application to make further encode setup tweaks using vorbis_encode_ctl() before finally +calling vorbis_encode_setup_init() to +complete the setup process. + +

    Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear should be called. +

    +

    + + + + +
    +
    
+extern int vorbis_encode_init_vbr(vorbis_info *vi,
+			      long channels,
+			      long rate,
+			      
+			      float base_quality);
+
+
    +
    + +

    Parameters

    +
    +
    vi
    +
    Pointer to an initialized vorbis_info struct.
    +
    channels
    +
    The number of channels to be encoded.
    +
    rate
    +
    The sampling rate of the source audio.
    +
    base_quality
    +
    Desired quality level, currently from -0.1 to 1.0 (lo to hi).
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    libvorbisenc documentation

    libvorbisenc version 1.3.2 - 20101101

    + + + + + -- cgit v1.1