[FFmpeg-devel] [PATCH] doc/libswresample: Fix most spelling mistakes

[Clément Bœsch]

On Sun, Nov 11, 2012 at 03:11:02PM +0100, Stefano Sabatini wrote:
> On date Thursday 2012-11-08 00:11:05 +0100, Alexander Strasser encoded:
> > 
> > Signed-off-by: Alexander Strasser <eclipse7 at gmx.net>
> > ---
> > 
> >   This patch (relative to Stefano's patch) fixes the minimum
> > that I think is needed for pushing libswresample.texi .
> > 
> >   I would like to go a bit further like I did with the other
> > documents, but that can still be done after this is in master.
> 
> Updated (note: inline comments are better because I tend to do more
> changes to the patch, so that the patches posted here are no longer
> applicable against my local version).
> -- 
> FFmpeg = Fast Fostering Mastering Pitiful Earthshaking Gnome

> From 658c8cddebd6ee4c68f91f5842f8c823550cc9ef Mon Sep 17 00:00:00 2001
> From: Stefano Sabatini <stefasab at gmail.com>
> Date: Fri, 2 Nov 2012 12:24:04 +0100
> Subject: [PATCH] doc: add libswresample.texi
> 
> ---
>  doc/Makefile           |    1 +
>  doc/libswresample.texi |  218 ++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 219 insertions(+)
>  create mode 100644 doc/libswresample.texi
> 
> diff --git a/doc/Makefile b/doc/Makefile
> index d0b4dfc..8709b0a 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -1,4 +1,5 @@
>  DOCLIBS-$(CONFIG_AVUTIL)  += libavutil
> +DOCLIBS-$(CONFIG_SWRESAMPLE) += libswresample
>  DOCLIBS-$(CONFIG_AVCODEC) += libavcodec
>  DOCLIBS-$(CONFIG_AVFILTER) += libavfilter
>  
> diff --git a/doc/libswresample.texi b/doc/libswresample.texi
> new file mode 100644
> index 0000000..9a7178b
> --- /dev/null
> +++ b/doc/libswresample.texi
> @@ -0,0 +1,218 @@
> +\input texinfo @c -*- texinfo -*-
> +
> + at settitle Libswresample Documentation
> + at titlepage
> + at center @titlefont{Libswresample Documentation}
> + at end titlepage
> +
> + at top
> +
> + at contents
> +
> + at chapter Description
> + at c man begin DESCRIPTION
> +
> +The libswresample library is a library performing highly optimized
> +audio resampling, rematrixing and sample format conversion operations.
> +
> +The libswresample library performs the following conversions:
> +
> + at itemize
> + at item
> + at emph{Resampling} is the process of changing the audio rate, for
> +example from an high sample rate of 44100Hz to 8000Hz. Audio
> +conversion from high to low sample rate is a lossy process.  Several
> +resampling options and algorithms are available.
> +
> + at item
> + at emph{Format conversion}: it is the process of converting the type of
> +samples, for example from 16-bit signed samples to unsigned 8-bit or
> +float samples. It also handles packing conversion, when passing from
> +packed layout (all samples belonging to distinct channels interleaved
> +in the same buffer), to planar layout (all samples belonging to the
> +same channel stored in a dedicated buffer or "plane").
> +
> + at item
> + at emph{Rematrixing}: is the process of changing the channel layout, for
> +example from stereo to mono. When the input channels cannot be mapped
> +to the output streams, the process is lossy.

"...since it involves different gain factors and mixing" maybe?

> + at end itemize
> +
> +Various other conversions (e.g. stretching and padding) are enabled
> +through dedicated options.
> +
> + at c man end DESCRIPTION
> +
> + at chapter Audio Conversion Options
> + at c man begin AUDIO CONVERSION OPTIONS
> +
> +The audio converter supports the following named options.
> +
> +Options may be set by specifying - at var{option} @var{value} in the
> +FFmpeg tools, or by setting the value explicitly in the
> + at code{SwrContext} options or using the @file{libavutil/opt.h} API for
> +programmatic use.
> +
> + at table @option
> +
> + at item ich, in_channel_count
> +Set the number of input channels. Default value is 2.
> +
> + at item och, out_channel_count
> +Set the number of output channels. Default value is 2.
> +

Maybe a sentence or two about the relationship with the channel layout
option would be welcome.

> + at item uch, used_channel_count
> +Set the number of used channels. Default value is 0.
> +

OK, this one is a bit tricky. If you don't want to enter into the details,
you can explain here that this option is only for special remapping:
basically fast re-order/silencing/duplicating channels without loss.

Also, since this makes no sense without the rest of the channel mapping
documentation, I'd better just not mention it: it really has no purpose
for end users, it will just confuse them.

> + at item isr, in_sample_rate
> +Set the input sample rate. Default value is 0.
> +
> + at item osr, out_sample_rate
> +Set the output sample rate. Default value is 0.
> +
> + at item isf, in_sample_fmt
> +Specify the input sample format. Must be an integer representing the
> +corresponding sample format specified in
> + at file{libavutil/samplefmt.h} header. Default value is -1
> +(corresponding to @code{AV_SAMPLE_FMT_NONE}).
> +
> + at item osf, out_sample_fmt
> +Specify the output sample format. Must be an integer representing the
> +corresponding sample format specified in
> + at file{libavutil/samplefmt.h} header. Default value is -1
> +(corresponding to @code{AV_SAMPLE_FMT_NONE}).
> +
> + at item tsf, internal_sample_fmt
> +Set the internal sample format. Default value is -1.
> +
> + at item icl, in_channel_layout
> +Set the input channel layout.
> +
> + at item ocl, out_channel_layout
> +Set the output channel layout.
> +
> + at item clev, center_mix_level
> +Set center mix level. It is a value expressed in deciBel, and must be
> +inclusively included between -32 and +32.
> +
> + at item slev, surround_mix_level
> +Set surround mix level. It is a value expressed in deciBel, and must
> +be inclusively included between -32 and +32.
> +
> + at item lfe_mix_evel
> +Set LFE mix level.
> +
> + at item rmvol, rematrix_volume
> +Set rematrix volume. Default value is 1.0.
> +
> + at item flags, swr_flags
> +Set flags used by the converter. Default value is 0.
> +
> +It supports the following individual flags:
> + at table @option
> + at item res
> +force resampling
> + at end table
> +
> + at item dither_scale
> +Set the dither scale. Default value is 1.
> +
> + at item dither_method
> +Set dither method. Default value is 0.
> +
> +Supported values:
> + at table @samp
> + at item rectangular
> +select rectangular dither
> + at item triangular
> +select triangular dither
> + at item triangular_hp
> +select triangular dither with high pass
> + at end table
> +
> + at item filter_size
> +Set resampling filter size, default value is 16.
> +
> + at item phase_shift
> +Set resampling phase shift, default value is 10, must be included
> +between 0 and 30.
> +
> + at item linear_interp
> +Use Linear Interpolation if set to 1, default value is 0.
> +
> + at item cutoff
> +Set cutoff frequency ratio. Must be a float value between 0 and 1,
> +default value is 0.8.
> +
> + at item min_comp
> +Set minimum difference between timestamps and audio data (in seconds)
> +below which no timestamp compensation of either kind is applied.
> +Default value is @code{FLT_MAX}.

If you use @code{} for the default value, please use it in all the other
options.

> +
> + at item min_hard_comp
> +Set minimum difference between timestamps and audio data (in seconds)
> +to trigger padding/trimming the data. Must be a non-negative double,
> +default value is 0.1.
> +
> + at item comp_duration
> +Set duration (in seconds) over which data is stretched/squeezed to
> +make it match the timestamps. Must be a non-negative double float
> +value, default value is 1.0.
> +
> + at item max_soft_comp
> +Set maximum factor by which data is stretched/squeezed to make it
> +match the timestamps. Must be a non-negative double float value,
> +default value is 0.
> +
> + at item matrix_encoding
> +Select matrixed stereo encoding.
> +
> +It accepts the following values:
> + at table @samp
> + at item none
> +select none
> + at item dolby
> +select Dolby
> + at item dplii
> +select Dolby Pro Logic II
> + at end table
> +
> +Default value is @code{none}.
> +
> + at item filter_type
> +Select filter type.
> +

AFAICT, this is related to resampling only, so maybe mention it

> +It accepts the following values:
> + at table @samp
> + at item cubic
> +select cubic
> + at item blackman_nuttall
> +select Blackman Nuttall Windowed Sinc
> + at item kaiser
> +select Kaiser Windowed Sinc
> + at end table
> +
> + at item kaiser_beta
> +Set Kaiser Window Beta value. Must be an integer included between 2
> +and 16, default value is 9.
> +
> + at end table
> +
> + at c man end AUDIO CONVERSION OPTIONS
> +
> + at ignore
> +
> + at setfilename libswresample
> + at settitle audio conversion library
> +

Just like swscale, I'd add "resampling".

> + at c man begin SEEALSO
> +ffmpeg(1), ffplay(1), ffprobe(1), ffserver(1), libavutil(3)
> + at c man end
> +
> + at c man begin AUTHORS
> +See Git history (git://source.ffmpeg.org/ffmpeg)
> + at c man end
> +
> + at end ignore
> +
> + at bye

No more comment from me

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121114/1e393cf1/attachment.asc>