[FFmpeg-devel] [PATCH] doc/filters/apad: extend documentation

[Stefano Sabatini]

On date Monday 2014-08-18 09:25:10 -0700, Timothy Gu encoded:
> On Mon, Aug 18, 2014 at 5:53 AM, Stefano Sabatini <stefasab at gmail.com> wrote:
> > ---
> >  doc/filters.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++--
> >  1 file changed, 45 insertions(+), 2 deletions(-)
> >
> > diff --git a/doc/filters.texi b/doc/filters.texi
> > index 0ca1d6f..44eecca 100644
> > --- a/doc/filters.texi
> > +++ b/doc/filters.texi
> > @@ -742,8 +742,51 @@ Pass the audio source unchanged to the output.
> >
> >  @section apad
> >
> > -Pad the end of a audio stream with silence, this can be used together with
> > --shortest to extend audio streams to the same length as the video stream.
> > +Pad the end of an audio stream with silence.
> > +
> > +This can be used together with @command{ffmpeg} @option{-shortest} to
> > +extend audio streams to the same length as the video stream.
> > +
> 
> > +A description of the accepted parameters follows.
> 
> @subsection Options
> 
> I would also change "parameters" to "options", as it is more common in the doc.

Fixed.

> 
> > +
> > + at table @option
> > + at item packet_size
> > +Set silence packet size. Default value is 4096.
> > +
> 
> > + at item pad_len
> > +Set the number of samples of silence to add to the end. After the
> > +value is reached, the stream is terminated. This option is mutually
> > +exclusive with @option{whole_len}.
> > +
> > + at item whole_len
> 
> > +Set the target number of sample in the audio stream. After the value
> > +is reached, the stream is terminated. This option is mutually
> > +exclusive with @option{pad_len}.
> 

> How about:
> 
> Set total number of samples in the audio stream. If the value is
> longer than input audio length, silence is added to the end, until the
> value is reached.

> If it is shorter, the stream is terminated after the
> value is reached. 

Right now the filter will stop the stream with no padding *only* at the
end of the stream, that is it is not possible to cut the stream before
the end is reached. This is probably consistent with the filter
semantics, which is meant to *pad*, for padding+cutting the user can use
a combination of apad+atrim.

> This option is mutually exclusive with
> @option{pad_len}.


> What happens when neither of these are specified (like in your third example)?

The filter will pad forever. Now that I think at it I think that
pad_len=0 should not add any data, so it would be probably more
convenient to use -1 for "infinite". This is currently not documented
so changing it right should be safe. What do you think?
-- 
FFmpeg = Fostering & Foolish Mastodontic Power Enhanced Glue