X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fmuxers.texi;h=143e5950569e3dab3589b250858134ae2095c515;hb=2ec33d27127251bbc45e1f88e60691ad59cf2319;hp=e7cfc4a9bc652db713ffb6e199d1963b472a4201;hpb=0cad24ce9b02037c9cdad84cae905f96b04d7d4c;p=ffmpeg diff --git a/doc/muxers.texi b/doc/muxers.texi index e7cfc4a9bc6..143e5950569 100644 --- a/doc/muxers.texi +++ b/doc/muxers.texi @@ -1,10 +1,10 @@ @chapter Muxers @c man begin MUXERS -Muxers are configured elements in FFmpeg which allow writing +Muxers are configured elements in Libav which allow writing multimedia streams to a particular type of file. -When you configure your FFmpeg build, all the supported muxers +When you configure your Libav build, all the supported muxers are enabled by default. You can list all available muxers using the configure option @code{--list-muxers}. @@ -13,7 +13,7 @@ You can disable all the muxers with the configure option with the options @code{--enable-muxer=@var{MUXER}} / @code{--disable-muxer=@var{MUXER}}. -The option @code{-formats} of the ff* tools will display the list of +The option @code{-formats} of the av* tools will display the list of enabled muxers. A description of some of the currently available muxers follows. @@ -35,23 +35,23 @@ CRC=0x@var{CRC}, where @var{CRC} is a hexadecimal number 0-padded to For example to compute the CRC of the input, and store it in the file @file{out.crc}: @example -ffmpeg -i INPUT -f crc out.crc +avconv -i INPUT -f crc out.crc @end example You can print the CRC to stdout with the command: @example -ffmpeg -i INPUT -f crc - +avconv -i INPUT -f crc - @end example -You can select the output format of each frame with @file{ffmpeg} by +You can select the output format of each frame with @command{avconv} by specifying the audio and video codec and format. For example to compute the CRC of the input audio converted to PCM unsigned 8-bit and the input video converted to MPEG-2 video, use the command: @example -ffmpeg -i INPUT -acodec pcm_u8 -vcodec mpeg2video -f crc - +avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc - @end example -See also the @code{framecrc} muxer (@pxref{framecrc}). +See also the @ref{framecrc} muxer. @anchor{framecrc} @section framecrc @@ -71,25 +71,52 @@ number 0-padded to 8 digits containing the CRC of the decoded frame. For example to compute the CRC of each decoded frame in the input, and store it in the file @file{out.crc}: @example -ffmpeg -i INPUT -f framecrc out.crc +avconv -i INPUT -f framecrc out.crc @end example You can print the CRC of each decoded frame to stdout with the command: @example -ffmpeg -i INPUT -f framecrc - +avconv -i INPUT -f framecrc - @end example -You can select the output format of each frame with @file{ffmpeg} by +You can select the output format of each frame with @command{avconv} by specifying the audio and video codec and format. For example, to compute the CRC of each decoded input audio frame converted to PCM unsigned 8-bit and of each decoded input video frame converted to MPEG-2 video, use the command: @example -ffmpeg -i INPUT -acodec pcm_u8 -vcodec mpeg2video -f framecrc - +avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc - @end example -See also the @code{crc} muxer (@pxref{crc}). +See also the @ref{crc} muxer. +@anchor{hls} +@section hls + +Apple HTTP Live Streaming muxer that segments MPEG-TS according to +the HTTP Live Streaming specification. + +It creates a playlist file and numbered segment files. The output +filename specifies the playlist filename; the segment filenames +receive the same basename as the playlist, a sequential number and +a .ts extension. + +@example +avconv -i in.nut out.m3u8 +@end example + +@table @option +@item -hls_time @var{seconds} +Set the segment length in seconds. +@item -hls_list_size @var{size} +Set the maximum number of playlist entries. +@item -hls_wrap @var{wrap} +Set the number after which index wraps. +@item -start_number @var{number} +Start the sequence from @var{number}. +@end table + +@anchor{image2} @section image2 Image file muxer. @@ -119,26 +146,236 @@ The pattern "img%%-%d.jpg" will specify a sequence of filenames of the form @file{img%-1.jpg}, @file{img%-2.jpg}, ..., @file{img%-10.jpg}, etc. -The following example shows how to use @file{ffmpeg} for creating a +The following example shows how to use @command{avconv} for creating a sequence of files @file{img-001.jpeg}, @file{img-002.jpeg}, ..., taking one image every second from the input video: @example -ffmpeg -i in.avi -r 1 -f image2 'img-%03d.jpeg' +avconv -i in.avi -vsync 1 -r 1 -f image2 'img-%03d.jpeg' @end example -Note that with @file{ffmpeg}, if the format is not specified with the +Note that with @command{avconv}, if the format is not specified with the @code{-f} option and the output filename specifies an image file format, the image2 muxer is automatically selected, so the previous command can be written as: @example -ffmpeg -i in.avi -r 1 'img-%03d.jpeg' +avconv -i in.avi -vsync 1 -r 1 'img-%03d.jpeg' @end example Note also that the pattern must not necessarily contain "%d" or "%0@var{N}d", for example to create a single image file @file{img.jpeg} from the input video you can employ the command: @example -ffmpeg -i in.avi -f image2 -vframes 1 img.jpeg +avconv -i in.avi -f image2 -frames:v 1 img.jpeg +@end example + +@table @option +@item -start_number @var{number} +Start the sequence from @var{number}. + +@item -update @var{number} +If @var{number} is nonzero, the filename will always be interpreted as just a +filename, not a pattern, and this file will be continuously overwritten with new +images. + +@end table + +@section matroska + +Matroska container muxer. + +This muxer implements the matroska and webm container specs. + +The recognized metadata settings in this muxer are: + +@table @option + +@item title=@var{title name} +Name provided to a single track +@end table + +@table @option + +@item language=@var{language name} +Specifies the language of the track in the Matroska languages form +@end table + +@table @option + +@item STEREO_MODE=@var{mode} +Stereo 3D video layout of two views in a single video track +@table @option +@item mono +video is not stereo +@item left_right +Both views are arranged side by side, Left-eye view is on the left +@item bottom_top +Both views are arranged in top-bottom orientation, Left-eye view is at bottom +@item top_bottom +Both views are arranged in top-bottom orientation, Left-eye view is on top +@item checkerboard_rl +Each view is arranged in a checkerboard interleaved pattern, Left-eye view being first +@item checkerboard_lr +Each view is arranged in a checkerboard interleaved pattern, Right-eye view being first +@item row_interleaved_rl +Each view is constituted by a row based interleaving, Right-eye view is first row +@item row_interleaved_lr +Each view is constituted by a row based interleaving, Left-eye view is first row +@item col_interleaved_rl +Both views are arranged in a column based interleaving manner, Right-eye view is first column +@item col_interleaved_lr +Both views are arranged in a column based interleaving manner, Left-eye view is first column +@item anaglyph_cyan_red +All frames are in anaglyph format viewable through red-cyan filters +@item right_left +Both views are arranged side by side, Right-eye view is on the left +@item anaglyph_green_magenta +All frames are in anaglyph format viewable through green-magenta filters +@item block_lr +Both eyes laced in one Block, Left-eye view is first +@item block_rl +Both eyes laced in one Block, Right-eye view is first +@end table +@end table + +For example a 3D WebM clip can be created using the following command line: +@example +avconv -i sample_left_right_clip.mpg -an -c:v libvpx -metadata STEREO_MODE=left_right -y stereo_clip.webm +@end example + +This muxer supports the following options: + +@table @option + +@item reserve_index_space +By default, this muxer writes the index for seeking (called cues in Matroska +terms) at the end of the file, because it cannot know in advance how much space +to leave for the index at the beginning of the file. However for some use cases +-- e.g. streaming where seeking is possible but slow -- it is useful to put the +index at the beginning of the file. + +If this option is set to a non-zero value, the muxer will reserve a given amount +of space in the file header and then try to write the cues there when the muxing +finishes. If the available space does not suffice, muxing will fail. A safe size +for most use cases should be about 50kB per hour of video. + +Note that cues are only written if the output is seekable and this option will +have no effect if it is not. + +@end table + +@section mov, mp4, ismv + +The mov/mp4/ismv muxer supports fragmentation. Normally, a MOV/MP4 +file has all the metadata about all packets stored in one location +(written at the end of the file, it can be moved to the start for +better playback using the @command{qt-faststart} tool). A fragmented +file consists of a number of fragments, where packets and metadata +about these packets are stored together. Writing a fragmented +file has the advantage that the file is decodable even if the +writing is interrupted (while a normal MOV/MP4 is undecodable if +it is not properly finished), and it requires less memory when writing +very long files (since writing normal MOV/MP4 files stores info about +every single packet in memory until the file is closed). The downside +is that it is less compatible with other applications. + +Fragmentation is enabled by setting one of the AVOptions that define +how to cut the file into fragments: + +@table @option +@item -movflags frag_keyframe +Start a new fragment at each video keyframe. +@item -frag_duration @var{duration} +Create fragments that are @var{duration} microseconds long. +@item -frag_size @var{size} +Create fragments that contain up to @var{size} bytes of payload data. +@item -movflags frag_custom +Allow the caller to manually choose when to cut fragments, by +calling @code{av_write_frame(ctx, NULL)} to write a fragment with +the packets written so far. (This is only useful with other +applications integrating libavformat, not from @command{avconv}.) +@item -min_frag_duration @var{duration} +Don't create fragments that are shorter than @var{duration} microseconds long. +@end table + +If more than one condition is specified, fragments are cut when +one of the specified conditions is fulfilled. The exception to this is +@code{-min_frag_duration}, which has to be fulfilled for any of the other +conditions to apply. + +Additionally, the way the output file is written can be adjusted +through a few other options: + +@table @option +@item -movflags empty_moov +Write an initial moov atom directly at the start of the file, without +describing any samples in it. Generally, an mdat/moov pair is written +at the start of the file, as a normal MOV/MP4 file, containing only +a short portion of the file. With this option set, there is no initial +mdat atom, and the moov atom only describes the tracks but has +a zero duration. + +Files written with this option set do not work in QuickTime. +This option is implicitly set when writing ismv (Smooth Streaming) files. +@item -movflags separate_moof +Write a separate moof (movie fragment) atom for each track. Normally, +packets for all tracks are written in a moof atom (which is slightly +more efficient), but with this option set, the muxer writes one moof/mdat +pair for each track, making it easier to separate tracks. + +This option is implicitly set when writing ismv (Smooth Streaming) files. +@item -movflags faststart +Run a second pass moving the index (moov atom) to the beginning of the file. +This operation can take a while, and will not work in various situations such +as fragmented output, thus it is not enabled by default. +@end table + +Smooth Streaming content can be pushed in real time to a publishing +point on IIS with this muxer. Example: +@example +avconv -re @var{} -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1) +@end example + +@section mp3 + +The MP3 muxer writes a raw MP3 stream with an ID3v2 header at the beginning and +optionally an ID3v1 tag at the end. ID3v2.3 and ID3v2.4 are supported, the +@code{id3v2_version} option controls which one is used. Setting +@code{id3v2_version} to 0 will disable the ID3v2 header completely. The legacy +ID3v1 tag is not written by default, but may be enabled with the +@code{write_id3v1} option. + +The muxer may also write a Xing frame at the beginning, which contains the +number of frames in the file. It is useful for computing duration of VBR files. +The Xing frame is written if the output stream is seekable and if the +@code{write_xing} option is set to 1 (the default). + +The muxer supports writing ID3v2 attached pictures (APIC frames). The pictures +are supplied to the muxer in form of a video stream with a single packet. There +can be any number of those streams, each will correspond to a single APIC frame. +The stream metadata tags @var{title} and @var{comment} map to APIC +@var{description} and @var{picture type} respectively. See +@url{http://id3.org/id3v2.4.0-frames} for allowed picture types. + +Note that the APIC frames must be written at the beginning, so the muxer will +buffer the audio frames until it gets all the pictures. It is therefore advised +to provide the pictures as soon as possible to avoid excessive buffering. + +Examples: + +Write an mp3 with an ID3v2.3 header and an ID3v1 footer: +@example +avconv -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3 +@end example + +Attach a picture to an mp3: +@example +avconv -i input.mp3 -i cover.png -c copy -metadata:s:v title="Album cover" +-metadata:s:v comment="Cover (Front)" out.mp3 +@end example + +Write a "clean" MP3 without any extra features: +@example +avconv -i input.wav -write_xing 0 -id3v2_version 0 out.mp3 @end example @section mpegts @@ -167,11 +404,11 @@ Set the first PID for data packets (default 0x0100, max 0x0f00). The recognized metadata settings in mpegts muxer are @code{service_provider} and @code{service_name}. If they are not set the default for -@code{service_provider} is "FFmpeg" and the default for +@code{service_provider} is "Libav" and the default for @code{service_name} is "Service01". @example -ffmpeg -i file.mpg -acodec copy -vcodec copy \ +avconv -i file.mpg -c copy \ -mpegts_original_network_id 0x1122 \ -mpegts_transport_stream_id 0x3344 \ -mpegts_service_id 0x5566 \ @@ -189,19 +426,66 @@ Null muxer. This muxer does not generate any output file, it is mainly useful for testing or benchmarking purposes. -For example to benchmark decoding with @file{ffmpeg} you can use the +For example to benchmark decoding with @command{avconv} you can use the command: @example -ffmpeg -benchmark -i INPUT -f null out.null +avconv -benchmark -i INPUT -f null out.null @end example Note that the above command does not read or write the @file{out.null} -file, but specifying the output file is required by the @file{ffmpeg} +file, but specifying the output file is required by the @command{avconv} syntax. Alternatively you can write the command as: @example -ffmpeg -benchmark -i INPUT -f null - +avconv -benchmark -i INPUT -f null - +@end example + +@section ogg + +Ogg container muxer. + +@table @option +@item -page_duration @var{duration} +Preferred page duration, in microseconds. The muxer will attempt to create +pages that are approximately @var{duration} microseconds long. This allows the +user to compromise between seek granularity and container overhead. The default +is 1 second. A value of 0 will fill all segments, making pages as large as +possible. A value of 1 will effectively use 1 packet-per-page in most +situations, giving a small seek granularity at the cost of additional container +overhead. +@end table + +@section segment + +Basic stream segmenter. + +The segmenter muxer outputs streams to a number of separate files of nearly +fixed duration. Output filename pattern can be set in a fashion similar to +@ref{image2}. + +Every segment starts with a video keyframe, if a video stream is present. +The segment muxer works best with a single constant frame rate video. + +Optionally it can generate a flat list of the created segments, one segment +per line. + +@table @option +@item segment_format @var{format} +Override the inner container format, by default it is guessed by the filename +extension. +@item segment_time @var{t} +Set segment duration to @var{t} seconds. +@item segment_list @var{name} +Generate also a listfile named @var{name}. +@item segment_list_size @var{size} +Overwrite the listfile once it reaches @var{size} entries. +@item segment_wrap @var{limit} +Wrap around segment index once it reaches @var{limit}. +@end table + +@example +avconv -i in.mkv -c copy -map 0 -f segment -list out.list out%03d.nut @end example @c man end MUXERS