[FFmpeg-devel] doc/bsfs: various improvements

Submitted by Moritz Barsnick on Nov. 15, 2016, 10:15 p.m.

Details

Message ID 1479248127-19895-1-git-send-email-barsnick@gmx.net
State Accepted
Commit c493a531edfd7b6956c563e19eb3a851b76797de
Headers show

Commit Message

Moritz Barsnick Nov. 15, 2016, 10:15 p.m.
- Restored alphabetical order.
- Enhanced sections aac_adtstoasc, dca_core, h264_mp4toannexb.
- Added sections hevc_mp4toannexb and vp9_superframe.
- Renamed (if required) and filled previously empty sections
  mjpegadump, mov2textsub/text2movsub, mp3decomp, and
  remove_extra.

Signed-off-by: Moritz Barsnick <barsnick@gmx.net>
---

I can also submit this as a series of smaller commits, if that's easier
to review.  My original local branch had 10 commits...

 doc/bitstream_filters.texi | 95 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 83 insertions(+), 12 deletions(-)

Comments

Lou Logan Nov. 15, 2016, 10:55 p.m.
On Tue, 15 Nov 2016 23:15:27 +0100, Moritz Barsnick wrote:

> - Restored alphabetical order.
> - Enhanced sections aac_adtstoasc, dca_core, h264_mp4toannexb.
> - Added sections hevc_mp4toannexb and vp9_superframe.
> - Renamed (if required) and filled previously empty sections
>   mjpegadump, mov2textsub/text2movsub, mp3decomp, and
>   remove_extra.

Fixes ticket #3198, but you don't need to send a new patch to mention
that.

> Signed-off-by: Moritz Barsnick <barsnick@gmx.net>
> ---
> 
> I can also submit this as a series of smaller commits, if that's easier
> to review.  My original local branch had 10 commits...

No need.

>  doc/bitstream_filters.texi | 95 ++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 83 insertions(+), 12 deletions(-)

LGTM, thanks. I'll wait a day or two if anyone else wants to comment
before I push it.
Moritz Barsnick Nov. 15, 2016, 11:11 p.m.
On Tue, Nov 15, 2016 at 13:55:56 -0900, Lou Logan wrote:
> Fixes ticket #3198, but you don't need to send a new patch to mention
> that.

Ah, I wasn't even aware. Feel free to amend the commit message.

> LGTM, thanks. I'll wait a day or two if anyone else wants to comment
> before I push it.

I couldn't wrap my head around some of the filters. Sometimes, no other
mention is even found on the web (incl. mailing lists) except for e.g.
quotes of the sources. (I did try to reverse-engineer the sources
carefully.) I reckoned some doc is better than no doc.

E.g. I couldn't figure out whether all filters are "still" useful, or
whether documenting them may confuse someone. Was the MP3 header
compression, as once created by a now-removed bitstream filter,
proprietary to ffmpeg? Was it found in the wild? Or: What is the movsub
filter pair actually useful for?

I worry too much.

Thanks for the review,
Moritz
Lou Logan Nov. 17, 2016, 8:03 p.m.
On Wed, 16 Nov 2016 00:11:50 +0100, Moritz Barsnick wrote:

> I couldn't wrap my head around some of the filters. Sometimes, no other
> mention is even found on the web (incl. mailing lists) except for e.g.
> quotes of the sources. (I did try to reverse-engineer the sources
> carefully.) I reckoned some doc is better than no doc.

Yeah, although I made the ticket and assigned it to myself what you
point out is basically why I never finished it.

> E.g. I couldn't figure out whether all filters are "still" useful, or
> whether documenting them may confuse someone. Was the MP3 header
> compression, as once created by a now-removed bitstream filter,
> proprietary to ffmpeg? Was it found in the wild?

Yes, there was once a bsf that would compress the header. Removed in
75ec40b/c6080d8. I don't know if it was anything used in the wild or
just something from FFmpeg. Michael was the author so he'll know more.

> What is the movsub filter pair actually useful for?

Good question. I looked into it once but forgot all details.

Anyway, thanks for the patch. It has been pushed.

Patch hide | download patch | download mbox

diff --git a/doc/bitstream_filters.texi b/doc/bitstream_filters.texi
index a85327f..e397ff9 100644
--- a/doc/bitstream_filters.texi
+++ b/doc/bitstream_filters.texi
@@ -26,19 +26,26 @@  with their parameters, if any.
 
 @section aac_adtstoasc
 
-Convert MPEG-2/4 AAC ADTS to MPEG-4 Audio Specific Configuration
-bitstream filter.
+Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration
+bitstream.
 
 This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4
 ADTS header and removes the ADTS header.
 
-This is required for example when copying an AAC stream from a raw
-ADTS AAC container to a FLV or a MOV/MP4 file.
+This filter is required for example when copying an AAC stream from a
+raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or
+to MOV/MP4 files and related formats such as 3GP or M4A. Please note
+that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats.
 
 @section chomp
 
 Remove zero padding at the end of a packet.
 
+@section dca_core
+
+Extract the core from a DCA/DTS stream, dropping extensions such as
+DTS-HD.
+
 @section dump_extra
 
 Add extradata to the beginning of the filtered packets.
@@ -67,10 +74,6 @@  the header stored in extradata to the key packets:
 ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts
 @end example
 
-@section dca_core
-
-Extract DCA core from DTS-HD streams.
-
 @section h264_mp4toannexb
 
 Convert an H.264 bitstream from length prefixed mode to start code
@@ -78,7 +81,7 @@  prefixed mode (as defined in the Annex B of the ITU-T H.264
 specification).
 
 This is required by some streaming formats, typically the MPEG-2
-transport stream format ("mpegts").
+transport stream format (muxer @code{mpegts}).
 
 For example to remux an MP4 file containing an H.264 stream to mpegts
 format with @command{ffmpeg}, you can use the command:
@@ -87,6 +90,29 @@  format with @command{ffmpeg}, you can use the command:
 ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
 @end example
 
+Please note that this filter is auto-inserted for MPEG-TS (muxer
+@code{mpegts}) and raw H.264 (muxer @code{h264}) output formats.
+
+@section hevc_mp4toannexb
+
+Convert an HEVC/H.265 bitstream from length prefixed mode to start code
+prefixed mode (as defined in the Annex B of the ITU-T H.265
+specification).
+
+This is required by some streaming formats, typically the MPEG-2
+transport stream format (muxer @code{mpegts}).
+
+For example to remux an MP4 file containing an HEVC stream to mpegts
+format with @command{ffmpeg}, you can use the command:
+
+@example
+ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
+@end example
+
+Please note that this filter is auto-inserted for MPEG-TS (muxer
+@code{mpegts}) and raw HEVC/H.265 (muxer @code{h265} or
+@code{hevc}) output formats.
+
 @section imxdump
 
 Modifies the bitstream to fit in MOV and to be usable by the Final Cut
@@ -137,11 +163,22 @@  exiftran -i -9 frame*.jpg
 ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
 @end example
 
-@section mjpega_dump_header
+@section mjpegadump
+
+Add an MJPEG A header to the bitstream, to enable decoding by
+Quicktime.
 
-@section movsub
+@anchor{mov2textsub}
+@section mov2textsub
 
-@section mp3_header_decompress
+Extract a representable text file from MOV subtitles, stripping the
+metadata header from each subtitle packet.
+
+See also the @ref{text2movsub} filter.
+
+@section mp3decomp
+
+Decompress non-standard compressed MP3 audio headers.
 
 @section mpeg4_unpack_bframes
 
@@ -181,4 +218,38 @@  applies the modification to every byte.
 
 @section remove_extra
 
+Remove extradata from packets.
+
+It accepts the following parameter:
+@table @option
+@item freq
+Set which frame types to remove extradata from.
+
+@table @samp
+@item k
+Remove extradata from non-keyframes only.
+
+@item keyframe
+Remove extradata from keyframes only.
+
+@item e, all
+Remove extradata from all frames.
+
+@end table
+@end table
+
+@anchor{text2movsub}
+@section text2movsub
+
+Convert text subtitles to MOV subtitles (as used by the @code{mov_text}
+codec) with metadata headers.
+
+See also the @ref{mov2textsub} filter.
+
+@section vp9_superframe
+
+Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This
+fixes merging of split/segmented VP9 streams where the alt-ref frame
+was split from its visible counterpart.
+
 @c man end BITSTREAM FILTERS