[FFmpeg-devel] [PATCH] doc: add libswresample.texi

[Stefano Sabatini]

---
 doc/Makefile           |    2 +-
 doc/libswresample.texi |  218 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 219 insertions(+), 1 deletions(-)
 create mode 100644 doc/libswresample.texi

diff --git a/doc/Makefile b/doc/Makefile
index 09d4543..7953f5f 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,5 +1,5 @@
 ifeq ($(CONFIG_AVCODEC),yes)
-DOCLIBS += libavutil libavcodec
+DOCLIBS += libavutil libswresample libavcodec
 endif
 
 MANPAGES    = $(PROGS-yes:%=doc/%.1)    $(DOCLIBS:%=doc/%.3)
diff --git a/doc/libswresample.texi b/doc/libswresample.texi
new file mode 100644
index 0000000..1dbf2eb
--- /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
+
+libswresample is a library performing highly optimized audio
+resampling, rematrixing and sample format conversion operations.
+
+libswresample performs several audio conversions, including:
+ at itemize
+ at item
+ at emph{Resampling}: it is the process consisting of changing the audio
+rate, for example from an high samplerate of 8000Hz to 44100Hz. Audio
+conversion from high to low samplerate is a lossy process.  Several
+resampling options and algorithm are available.
+
+ at item
+ at emph{Format conversion}: it is the process consisting into 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 or "plane"), to planar layout
+(all samples belonging to the same channel stored in a dedicated
+buffer or "plane").
+
+ at item
+ at emph{Rematrixing}: it is the process consisting into 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.
+ 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, by setting the value explicitly in the @code{SwrContext}
+options or by 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_coun
+Set the number of output channels. Default value is 2.
+
+ at item uch, used_channel_count
+Set the number of used channels. Default value is 0.
+
+ 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 deciBels, 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 lfr_mix_evel
+Set LFE mix level.
+
+ at item rmvol, rematrix_volume
+Set rematrix volume. Defautl 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}.
+
+ 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
+Set matrixed stereo encoding.
+
+Accept 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
+Set filter type.
+
+Accet 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
+
+ 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
+ at c man end
+
+ at end ignore
+
+ at bye
-- 
1.7.5.4