[FFmpeg-devel] [PATCH] doc/encoders: add libvorbis doc

[Timothy Gu]

On Sun, Oct 20, 2013 at 10:38 AM, Stefano Sabatini <stefasab at gmail.com> wrote:
> On date Friday 2013-10-18 17:07:27 -0700, Timothy Gu encoded:
>> Signed-off-by: Timothy Gu <timothygu99 at gmail.com>
>> ---
>>  doc/encoders.texi | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 50 insertions(+)
>>
>> diff --git a/doc/encoders.texi b/doc/encoders.texi
>> index a96c1fc..ed61516 100644
>> --- a/doc/encoders.texi
>> +++ b/doc/encoders.texi
>> @@ -771,6 +771,56 @@ respectively. The default is 0 (cutoff disabled).
>>
>>  @end table
>>
>> + at section libvorbis
>> +
>> +libvorbis encoder wrapper.
>> +
>> +Requires the presence of the libvorbisenc headers and library during
>> +configuration. You need to explicitly configure the build with
>> + at code{--enable-libvorbis}.
>> +
>> + at subsection Options
>> +
>
>> +The following is an option mapping table describing options supported
>> +by the libvorbis wrapper, and their @command{oggenc}-equivalent
>> +in parentheses.
>
> I prefer this (simpler and more direct):
>
> The following options are supported by the libvorbis wrapper. The
> @command{oggenc}-equivalent of the options are listed in parentheses.
>
> (you can skip the first sentence)
>
>> +
>> +To get a more accurate and extensive documentation of the libvorbis
>> +options, consult the libvorbisenc's and @command{oggenc}'s documentations.
>
> Possibly provide a link to the project website,

Done

> and while at it also a link to oggenc(1) manual.

oggenc(1) doesn't have an official online manual. I just set one up
here http://timothygu.github.io/vorbis-tools/oggenc.html, but I'm not
sure if we can use it.

>
>> +
>> + at table @option
>> + at item b (@emph{-b})
>> +Set bitrate expressed in bits/s for ABR. @command{oggenc} @option{-b} is
>> +expressed in kilobits/s.
>> +
>> + at item q (@emph{-q})
>> +Set constant quality setting for VBR. The value should be a float
>> +number in the range of -1.0 to 10.0. The higher the value, the better
>> +the quality. The default value is @samp{3.0}.
>> +
>> +This option is valid only using the @command{ffmpeg} command-line tool.
>> +For library interface users, use @option{global_quality}.
>> +
>
>> + at item cutoff (@emph{--advanced-encode-option lowpass_frequency=@var{N}})
>
> I'm not sure the renderer support nested markup.

No it doesn't. Fixed.

>
>> +Set cutoff bandwidth in Hz. @command{oggenc}'s related option is
>> +expressed in kHz.The default value is @samp{0} (cutoff disabled).
>
> Nit: kHz._The...
>
> Also I prefer: Set cutoff bandwidth in Hz, a value of 0 disable
> cutoff. @command{oggenc}'s related option is expressed in kHz. The
> default value is @samp{0} (cutoff disabled).
>
>> +
>> + at item minrate (@emph{-m})
>> +Set minimum bitrate expressed in bits/s. @command{oggenc} @option{-m} is
>> +expressed in kilobits/s.
>> +
>> + at item maxrate (@emph{-M})
>> +Set maximum bitrate expressed in bits/s. @command{oggenc} @option{-M} is
>> +expressed in kilobits/s. This only has effect on ABR mode.
>> +
>
>> + at item iblock (@emph{--advanced-encode-option impulse_noisetune=@var{N}})
>
> Same here, verify that nested markup works, otherwise you can use impulse_noisetune=N
>
>> +Set noise floor bias for impulse blocks. The value is a float number from
>> +-15.0 to 0.0. A negative bias instructs the encoder to pay special attention
>> +to the crispness of transients in the encoded audio. The tradeoff for better
>> +transient response is a higher bitrate.
>> +
>> + at end table
>> +
>
> LGTM otherwise.

All other notes and nits fixed.

Timothy
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-doc-encoders-add-libvorbis-doc.patch
Type: text/x-patch
Size: 2644 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20131023/a7ddc3ba/attachment.bin>