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

Stefano Sabatini stefasab at gmail.com
Thu Nov 15 11:10:02 CET 2012


On date Wednesday 2012-11-14 00:18:45 +0100, Clément Bœsch encoded:
> 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?

Added.

> 
> > + 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.

The point is that I'm the first who doesn't know very well these
relationship. The point of the patch is having an entry-point where to
document stuff.
 
> > + 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.

Again I can't really comment (this also shows how badly we need to
extend such documentation).

But I don't believe in "no show -> no confusion" principle, a completely
undocumented option is far much confusing in my opinion.
 
> > + 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.

Well, I'm in conflict. Using @code{N} for all numerals may be
annoying, while it seems required for code snippets like
@code{FLT_MAX} to make clear that FLT_MAX is not an English word.

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

Added.
 
> > +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".

"resampling" would be limited, since the library perform also other
conversion as well (rematrixing, format conversion, repacking), which
I put under the generic label "audio conversion".

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

Patch updated. I'll push this version in a few days, comment on the
meaning and usage of the options are welcome, as well as English
rewording/grammar remarks.

But even if not perfect, we should not block this patch so that it can
be improved further once in the repository.
-- 
FFmpeg = Fast and Formidable Magnificient Programmable Exciting Gigant
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-doc-add-libswresample.texi.patch
Type: text/x-diff
Size: 6944 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121115/cd14a470/attachment.bin>


More information about the ffmpeg-devel mailing list