diff options
Diffstat (limited to 'ffmpeg/doc')
67 files changed, 9404 insertions, 5648 deletions
diff --git a/ffmpeg/doc/APIchanges b/ffmpeg/doc/APIchanges index 255f914..21a8c4c 100644 --- a/ffmpeg/doc/APIchanges +++ b/ffmpeg/doc/APIchanges @@ -4,7 +4,7 @@ since the last major version increase or the API was added. The last version increases were: libavcodec: 2013-03-xx libavdevice: 2013-03-xx -libavfilter: 2012-06-22 +libavfilter: 2013-12-xx libavformat: 2013-03-xx libavresample: 2012-10-05 libpostproc: 2011-04-18 @@ -15,16 +15,211 @@ libavutil: 2012-10-22 API changes, most recent first: -2013-03-20 - xxxxxxx - lavu 52.22.100 - opt.h +2013-12-22 - xxxxxxx - lavu 52.59.100 - avstring.h + Add av_strnlen() function. + +2013-12-xx - xxxxxxx - lavu 52.57.100 - opencl.h + Add av_opencl_benchmark() function. + +2013-11-xx - xxxxxxx - lavu 52.56.100 - ffversion.h + Moves version.h to libavutil/ffversion.h. + Install ffversion.h and make it public. + +2013-12-xx - xxxxxxx - lavc 55.28.1 - avcodec.h + av_frame_alloc(), av_frame_unref() and av_frame_free() now can and should be + used instead of avcodec_alloc_frame(), avcodec_get_frame_defaults() and + avcodec_free_frame() respectively. The latter three functions are deprecated. + +2013-11-xx - xxxxxxx- - lavu 52.20.0 - frame.h + Add AV_FRAME_DATA_STEREO3D value to the AVFrameSideDataType enum and + stereo3d.h API, that identify codec-independent stereo3d information. + +2013-11-xx - xxxxxxx- - lavu 52.19.0 - frame.h + Add AV_FRAME_DATA_A53_CC value to the AVFrameSideDataType enum, which + identifies ATSC A53 Part 4 Closed Captions data. + +2013-11-XX - xxxxxxx - lavu 52.54.100 - avstring.h + Add av_utf8_decode() function. + +2013-11-22 - fb7d70c - lavc 55.44.100 - avcodec.h + Add HEVC profiles + +2013-11-xx - xxxxxxx - lavc 55.44.100 - avcodec.h + Add av_packet_{un,}pack_dictionary() + Add AV_PKT_METADATA_UPDATE side data type, used to transmit key/value + strings between a stream and the application. + +2013-11-xx - xxxxxxx - lavu 52.18.0 - mem.h + Move av_fast_malloc() and av_fast_realloc() for libavcodec to libavutil. + +2013-10-xx - xxxxxxx - lavc 55.27.0 - avcodec.h + Deprecate AVCodecContext.error_rate, it is replaced by the 'error_rate' + private option of the mpegvideo encoder family. + +2013-11-xx - xxxxxxx - lavc 55.26.0 - vdpau.h + Add av_vdpau_get_profile(). + Add av_vdpau_alloc_context(). This function must from now on be + used for allocating AVVDPAUContext. + +2013-11-xx - xxxxxxx - lavc 55.41.100 / 55.25.0 - avcodec.h + lavu 52.51.100 - frame.h + Add ITU-R BT.2020 and other not yet included values to color primaries, + transfer characteristics and colorspaces. + +2013-11-04 - xxxxxxx - lavu 52.50.100 - avutil.h + Add av_fopen_utf8() + +2013-08-xx - xxxxxxx - lavu 52.17.0 - avframe.h + Add AVFrame.flags and AV_FRAME_FLAG_CORRUPT. + +2013-10-27 - xxxxxxx - lavc 55.39.100 - avcodec.h + Add CODEC_CAP_DELAY support to avcodec_decode_subtitle2. + +2013-10-27 - xxxxxxx - lavu 52.48.100 - parseutils.h + Add av_get_known_color_name(). + +2013-10-17 - xxxxxxx - lavu 52.47.100 - opt.h + Add AV_OPT_TYPE_CHANNEL_LAYOUT and channel layout option handlers + av_opt_get_channel_layout() and av_opt_set_channel_layout(). + +2013-10-xx - xxxxxxx -libswscale 2.5.101 - options.c + Change default scaler to bicubic + +2013-10-03 - xxxxxxx - lavc 55.34.100 - avcodec.h + Add av_codec_get_max_lowres() + +2013-10-02 - xxxxxxx - lavf 55.19.100 - avformat.h + Add audio/video/subtitle AVCodec fields to AVFormatContext to force specific + decoders + +2013-08-xx - xxxxxxx - lavfi 3.11.0 - avfilter.h + Add AVFilterGraph.execute and AVFilterGraph.opaque for custom slice threading + implementations. + +2013-09-21 - xxxxxxx - lavu 52.16.0 - pixfmt.h + Add interleaved 4:2:2 8/10-bit formats AV_PIX_FMT_NV16 and + AV_PIX_FMT_NV20. + +2013-09-16 - c74c3fb / 3feb3d6 - lavu 52.44.100 / 52.15.0 - mem.h + Add av_reallocp. + +2013-09-04 - 3e1f507 - lavc 55.31.101 - avcodec.h + avcodec_close() argument can be NULL. + +2013-09-04 - 36cd017 - lavf 55.16.101 - avformat.h + avformat_close_input() argument can be NULL and point on NULL. + +2013-08-29 - e31db62 - lavf 55.15.100 - avformat.h + Add av_format_get_probe_score(). + +2013-08-15 - 1e0e193 - lsws 2.5.100 - + Add a sws_dither AVOption, allowing to set the dither algorithm used + +2013-08-xx - xxxxxxx - lavc 55.27.100 - vdpau.h + Add a render2 alternative to the render callback function. + +2013-08-xx - xxxxxxx - lavc 55.26.100 - vdpau.h + Add allocation function for AVVDPAUContext, allowing + to extend it in the future without breaking ABI/API. + +2013-08-10 - 67a580f / 5a9a9d4 - lavc 55.25.100 / 55.16.0 - avcodec.h + Extend AVPacket API with av_packet_unref, av_packet_ref, + av_packet_move_ref, av_packet_copy_props, av_packet_free_side_data. + +2013-08-05 - 9547e3e / f824535 - lavc 55.22.100 / 55.13.0 - avcodec.h + Deprecate the bitstream-related members from struct AVVDPAUContext. + The bistream buffers no longer need to be explicitly freed. + +2013-08-05 - 3b805dc / 549294f - lavc 55.21.100 / 55.12.0 - avcodec.h + Deprecate the CODEC_CAP_HWACCEL_VDPAU codec capability. Use CODEC_CAP_HWACCEL + and select the AV_PIX_FMT_VDPAU format with get_format() instead. + +2013-08-05 - 4ee0984 / a0ad5d0 - lavu 52.41.100 / 52.14.0 - pixfmt.h + Deprecate AV_PIX_FMT_VDPAU_*. Use AV_PIX_FMT_VDPAU instead. + +2013-08-02 - 82fdfe8 / a8b1927 - lavc 55.20.100 / 55.11.0 - avcodec.h + Add output_picture_number to AVCodecParserContext. + +2013-07-23 - abc8110 - lavc 55.19.100 - avcodec.h + Add avcodec_chroma_pos_to_enum() + Add avcodec_enum_to_chroma_pos() + +2013-07-03 - 838bd73 - lavfi 3.78.100 - avfilter.h + Deprecate avfilter_graph_parse() in favor of the equivalent + avfilter_graph_parse_ptr(). + +2013-06-24 - af5f9c0 / 95d5246 - lavc 55.17.100 / 55.10.0 - avcodec.h + Add MPEG-2 AAC profiles + +2013-06-25 - af5f9c0 / 95d5246 - lavf 55.10.100 - avformat.h + Add AV_DISPOSITION_* flags to indicate text track kind. + +2013-06-15 - 99b8cd0 - lavu 52.36.100 + Add AVRIPEMD: + av_ripemd_alloc() + av_ripemd_init() + av_ripemd_update() + av_ripemd_final() + +2013-06-04 - 30b491f / fc962d4 - lavu 52.35.100 / 52.13.0 - mem.h + Add av_realloc_array and av_reallocp_array + +2013-05-30 - 682b227 - lavu 52.35.100 + Add AVSHA512: + av_sha512_alloc() + av_sha512_init() + av_sha512_update() + av_sha512_final() + +2013-05-24 - 8d4e969 / 129bb23 - lavfi 3.10.0 / 3.70.100 - avfilter.h + Add support for slice multithreading to lavfi. Filters supporting threading + are marked with AVFILTER_FLAG_SLICE_THREADS. + New fields AVFilterContext.thread_type, AVFilterGraph.thread_type and + AVFilterGraph.nb_threads (accessible directly or through AVOptions) may be + used to configure multithreading. + +2013-05-24 - fe40a9f / 2a6eaea - lavu 52.12.0 / 52.34.100 - cpu.h + Add av_cpu_count() function for getting the number of logical CPUs. + +2013-05-24 - 0c25c39 / b493847 - lavc 55.7.0 / 55.12.100 - avcodec.h + Add picture_structure to AVCodecParserContext. + +2013-05-17 - 3a751ea - lavu 52.33.100 - opt.h + Add AV_OPT_TYPE_COLOR value to AVOptionType enum. + +2013-05-13 - e398416 - lavu 52.31.100 - mem.h + Add av_dynarray2_add(). + +2013-05-12 - 1776177 - lavfi 3.65.100 + Add AVFILTER_FLAG_SUPPORT_TIMELINE* filter flags. + +2013-04-19 - 380cfce - lavc 55.4.100 + Add AV_CODEC_PROP_TEXT_SUB property for text based subtitles codec. + +2013-04-18 - 7c1a002 - lavf 55.3.100 + The matroska demuxer can now output proper verbatim ASS packets. It will + become the default starting lavf 56.0.100. + +2013-04-10 - af0d270 - lavu 25.26.100 - avutil.h,opt.h + Add av_int_list_length() + and av_opt_set_int_list(). + +2013-03-30 - 5c73645 - lavu 52.24.100 - samplefmt.h + Add av_samples_alloc_array_and_samples(). + +2013-03-29 - ef7b6b4 - lavf 55.1.100 - avformat.h + Add av_guess_frame_rate() + +2013-03-20 - 8d928a9 - lavu 52.22.100 - opt.h Add AV_OPT_TYPE_DURATION value to AVOptionType enum. -2013-03-17 - xxxxxx - lavu 52.20.100 - opt.h +2013-03-17 - 7aa9af5 - lavu 52.20.100 - opt.h Add AV_OPT_TYPE_VIDEO_RATE value to AVOptionType enum. -2013-03-07 - xxxxxx - lavu 52.18.100 - avstring.h,bprint.h +2013-03-07 - 9767ec6 - lavu 52.18.100 - avstring.h,bprint.h Add av_escape() and av_bprint_escape() API. -2013-02-24 - xxxxxx - lavfi 3.41.100 - buffersink.h +2013-02-24 - b59cd08 - lavfi 3.41.100 - buffersink.h Add sample_rates field to AVABufferSinkParams. 2013-01-17 - a1a707f - lavf 54.61.100 @@ -37,7 +232,7 @@ API changes, most recent first: Add AVFilterLink.channels, avfilter_link_get_channels() and avfilter_ref_get_channels(). -2012-12-15 - 2ada584d - lavc 54.80.100 - avcodec.h +2012-12-15 - 96d815fc - lavc 54.80.100 - avcodec.h Add pkt_size field to AVFrame. 2012-11-25 - c70ec631 - lavu 52.9.100 - opt.h @@ -150,23 +345,52 @@ API changes, most recent first: 2012-03-26 - a67d9cf - lavfi 2.66.100 Add avfilter_fill_frame_from_{audio_,}buffer_ref() functions. -2013-xx-xx - lavu 52.9.0 - pixdesc.h +2013-05-15 - ff46809 / e6c4ac7 - lavu 52.32.100 / 52.11.0 - pixdesc.h + Replace PIX_FMT_* flags with AV_PIX_FMT_FLAG_*. + +2013-04-03 - 6fc58a8 / 507b1e4 - lavc 55.7.100 / 55.4.0 - avcodec.h + Add field_order to AVCodecParserContext. + +2013-04-19 - f4b05cd / 5e83d9a - lavc 55.5.100 / 55.2.0 - avcodec.h + Add CODEC_FLAG_UNALIGNED to allow decoders to produce unaligned output. + +2013-04-11 - lavfi 3.53.100 / 3.8.0 + 231fd44 / 38f0c07 - Move all content from avfiltergraph.h to avfilter.h. Deprecate + avfilterhraph.h, user applications should include just avfilter.h + 86070b8 / bc1a985 - Add avfilter_graph_alloc_filter(), deprecate avfilter_open() and + avfilter_graph_add_filter(). + 4fde705 / 1113672 - Add AVFilterContext.graph pointing to the AVFilterGraph that contains the + filter. + 710b0aa / 48a5ada - Add avfilter_init_str(), deprecate avfilter_init_filter(). + 46de9ba / 1ba95a9 - Add avfilter_init_dict(). + 16fc24b / 7cdd737 - Add AVFilter.flags field and AVFILTER_FLAG_DYNAMIC_{INPUTS,OUTPUTS} flags. + f4db6bf / 7e8fe4b - Add avfilter_pad_count() for counting filter inputs/outputs. + 835cc0f / fa2a34c - Add avfilter_next(), deprecate av_filter_next(). + Deprecate avfilter_uninit(). + +2013-04-09 - lavfi 3.51.100 / 3.7.0 - avfilter.h + 0594ef0 / b439c99 - Add AVFilter.priv_class for exporting filter options through the + AVOptions API in the similar way private options work in lavc and lavf. + 44d4488 / 8114c10 - Add avfilter_get_class(). + Switch all filters to use AVOptions. + +2013-03-19 - 17ebef2 / 2c328a9 - lavu 52.20.100 / 52.9.0 - pixdesc.h Add av_pix_fmt_count_planes() function for counting planes in a pixel format. -2013-xx-xx - lavfi 3.6.0 +2013-03-16 - ecade98 / 42c7c61 - lavfi 3.47.100 / 3.6.0 Add AVFilterGraph.nb_filters, deprecate AVFilterGraph.filter_count. -2013-03-xx - Reference counted buffers - lavu 52.8.0, lavc 55.0.0, lavf 55.0.0, -lavd 54.0.0, lavfi 3.5.0 - xxxxxxx, xxxxxxx - add a new API for reference counted buffers and buffer +2013-03-08 - Reference counted buffers - lavu 52.8.0, lavc 55.0.100 / 55.0.0, lavf 55.0.100 / 55.0.0, +lavd 54.4.100 / 54.0.0, lavfi 3.5.0 + 36099df / 8e401db, 532f31a / 1cec062 - add a new API for reference counted buffers and buffer pools (new header libavutil/buffer.h). - xxxxxxx - add AVPacket.buf to allow reference counting for the AVPacket data. + 2653e12 / 1afddbe - add AVPacket.buf to allow reference counting for the AVPacket data. Add av_packet_from_data() function for constructing packets from av_malloc()ed data. - xxxxxxx - move AVFrame from lavc to lavu (new header libavutil/frame.h), add + c4e8821 / 7ecc2d4 - move AVFrame from lavc to lavu (new header libavutil/frame.h), add AVFrame.buf/extended_buf to allow reference counting for the AVFrame data. Add new API for working with reference-counted AVFrames. - xxxxxxx - add the refcounted_frames field to AVCodecContext to make audio and + 80e9e63 / 759001c - add the refcounted_frames field to AVCodecContext to make audio and video decoders return reference-counted frames. Add get_buffer2() callback to AVCodecContext which allocates reference-counted frames. Add avcodec_default_get_buffer2() as the default get_buffer2() @@ -184,30 +408,30 @@ lavd 54.0.0, lavfi 3.5.0 * qscale_table, qstride, qscale_type, mbskip_table, motion_val, mb_type, dct_coeff, ref_index -- mpegvideo-specific tables, which are not exported anymore. - xxxxxxx - switch libavfilter to use AVFrame instead of AVFilterBufferRef. Add + a05a44e / 7e35037 - switch libavfilter to use AVFrame instead of AVFilterBufferRef. Add av_buffersrc_add_frame(), deprecate av_buffersrc_buffer(). Add av_buffersink_get_frame() and av_buffersink_get_samples(), deprecate av_buffersink_read() and av_buffersink_read_samples(). Deprecate AVFilterBufferRef and all functions for working with it. -2013-xx-xx - xxxxxxx - lavu 52.8.0 - avstring.h +2013-03-17 - 6c17ff8 / 12c5c1d - lavu 52.19.100 / 52.8.0 - avstring.h Add av_isdigit, av_isgraph, av_isspace, av_isxdigit. -2013-xx-xx - xxxxxxx - lavfi 3.4.0 - avfiltergraph.h +2013-02-23 - 71cf094 / 9f12235 - lavfi 3.40.100 / 3.4.0 - avfiltergraph.h Add resample_lavr_opts to AVFilterGraph for setting libavresample options for auto-inserted resample filters. -2013-xx-xx - xxxxxxx - lavu 52.7.0 - dict.h +2013-01-25 - e7e14bc / 38c1466 - lavu 52.17.100 / 52.7.0 - dict.h Add av_dict_parse_string() to set multiple key/value pairs at once from a string. -2013-01-xx - xxxxxxx - lavu 52.6.0 - avstring.h +2013-01-25 - 25be630 / b85a5e8 - lavu 52.16.100 / 52.6.0 - avstring.h Add av_strnstr() -2013-01-xx - xxxxxxx - lavu 52.5.0 - hmac.h +2013-01-15 - e7e0186 / 8ee288d - lavu 52.15.100 / 52.5.0 - hmac.h Add AVHMAC. -2013-01-13 - xxxxxxx - lavc 54.87.100 / 54.36.0 - vdpau.h +2013-01-13 - 8ee7b38 / 44e065d - lavc 54.87.100 / 54.36.0 - vdpau.h Add AVVDPAUContext struct for VDPAU hardware-accelerated decoding. 2013-01-12 - dae382b / 169fb94 - lavu 52.14.100 / 52.4.0 - pixdesc.h @@ -295,7 +519,7 @@ lavd 54.0.0, lavfi 3.5.0 2012-07-29 - 7c26761 / 681ed00 - lavf 54.22.100 / 54.13.0 - avformat.h Add AVFMT_FLAG_NOBUFFER for low latency use cases. -2012-07-10 - 5fade8a - lavu 51.37.0 +2012-07-10 - fbe0245 / f3e5e6f - lavu 51.65.100 / 51.37.0 Add av_malloc_array() and av_mallocz_array() 2012-06-22 - e847f41 / d3d3a32 - lavu 51.61.100 / 51.34.0 diff --git a/ffmpeg/doc/Doxyfile b/ffmpeg/doc/Doxyfile index 7e6d0f5..6488aad 100644 --- a/ffmpeg/doc/Doxyfile +++ b/ffmpeg/doc/Doxyfile @@ -33,7 +33,7 @@ PROJECT_NAME = FFmpeg PROJECT_NUMBER = -# With the PROJECT_LOGO tag one can specify an logo or icon that is included +# With the PROJECT_LOGO tag one can specify a logo or icon that is included # in the documentation. The maximum height of the logo should not exceed 55 # pixels and the maximum width should not exceed 200 pixels. Doxygen will # copy the logo to the output directory. @@ -277,7 +277,7 @@ SUBGROUPING = YES # be useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. -TYPEDEF_HIDES_STRUCT = NO +TYPEDEF_HIDES_STRUCT = YES # The SYMBOL_CACHE_SIZE determines the size of the internal cache use to # determine which symbols to keep in memory and which to flush to disk. @@ -409,7 +409,7 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in # declaration order. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # brief documentation of file, namespace and class members alphabetically @@ -709,7 +709,7 @@ INLINE_SOURCES = NO # doxygen to hide any special comment blocks from generated source code # fragments. Normal C and C++ comments will always remain visible. -STRIP_CODE_COMMENTS = YES +STRIP_CODE_COMMENTS = NO # If the REFERENCED_BY_RELATION tag is set to YES # then for each documented function all documented diff --git a/ffmpeg/doc/Makefile b/ffmpeg/doc/Makefile index a861655..26bd9f5 100644 --- a/ffmpeg/doc/Makefile +++ b/ffmpeg/doc/Makefile @@ -6,7 +6,6 @@ LIBRARIES-$(CONFIG_AVFORMAT) += libavformat LIBRARIES-$(CONFIG_AVDEVICE) += libavdevice LIBRARIES-$(CONFIG_AVFILTER) += libavfilter -COMPONENTS-yes = $(PROGS-yes) COMPONENTS-$(CONFIG_AVUTIL) += ffmpeg-utils COMPONENTS-$(CONFIG_SWSCALE) += ffmpeg-scaler COMPONENTS-$(CONFIG_SWRESAMPLE) += ffmpeg-resampler @@ -15,9 +14,11 @@ COMPONENTS-$(CONFIG_AVFORMAT) += ffmpeg-formats ffmpeg-protocols COMPONENTS-$(CONFIG_AVDEVICE) += ffmpeg-devices COMPONENTS-$(CONFIG_AVFILTER) += ffmpeg-filters -MANPAGES = $(COMPONENTS-yes:%=doc/%.1) $(LIBRARIES-yes:%=doc/%.3) -PODPAGES = $(COMPONENTS-yes:%=doc/%.pod) $(LIBRARIES-yes:%=doc/%.pod) -HTMLPAGES = $(COMPONENTS-yes:%=doc/%.html) $(LIBRARIES-yes:%=doc/%.html) \ +MANPAGES1 = $(AVPROGS-yes:%=doc/%.1) $(AVPROGS-yes:%=doc/%-all.1) $(COMPONENTS-yes:%=doc/%.1) +MANPAGES3 = $(LIBRARIES-yes:%=doc/%.3) +MANPAGES = $(MANPAGES1) $(MANPAGES3) +PODPAGES = $(AVPROGS-yes:%=doc/%.pod) $(AVPROGS-yes:%=doc/%-all.pod) $(COMPONENTS-yes:%=doc/%.pod) $(LIBRARIES-yes:%=doc/%.pod) +HTMLPAGES = $(AVPROGS-yes:%=doc/%.html) $(AVPROGS-yes:%=doc/%-all.html) $(COMPONENTS-yes:%=doc/%.html) $(LIBRARIES-yes:%=doc/%.html) \ doc/developer.html \ doc/faq.html \ doc/fate.html \ @@ -35,6 +36,22 @@ DOCS-$(CONFIG_MANPAGES) += $(MANPAGES) DOCS-$(CONFIG_TXTPAGES) += $(TXTPAGES) DOCS = $(DOCS-yes) +DOC_EXAMPLES-$(CONFIG_DECODING_ENCODING_EXAMPLE) += decoding_encoding +DOC_EXAMPLES-$(CONFIG_DEMUXING_DECODING_EXAMPLE) += demuxing_decoding +DOC_EXAMPLES-$(CONFIG_FILTERING_AUDIO_EXAMPLE) += filtering_audio +DOC_EXAMPLES-$(CONFIG_FILTERING_VIDEO_EXAMPLE) += filtering_video +DOC_EXAMPLES-$(CONFIG_METADATA_EXAMPLE) += metadata +DOC_EXAMPLES-$(CONFIG_MUXING_EXAMPLE) += muxing +DOC_EXAMPLES-$(CONFIG_RESAMPLING_AUDIO_EXAMPLE) += resampling_audio +DOC_EXAMPLES-$(CONFIG_SCALING_VIDEO_EXAMPLE) += scaling_video +DOC_EXAMPLES-$(CONFIG_TRANSCODE_AAC_EXAMPLE) += transcode_aac +ALL_DOC_EXAMPLES_LIST = $(DOC_EXAMPLES-) $(DOC_EXAMPLES-yes) + +DOC_EXAMPLES := $(DOC_EXAMPLES-yes:%=doc/examples/%$(PROGSSUF)$(EXESUF)) +ALL_DOC_EXAMPLES := $(ALL_DOC_EXAMPLES_LIST:%=doc/examples/%$(PROGSSUF)$(EXESUF)) +ALL_DOC_EXAMPLES_G := $(ALL_DOC_EXAMPLES_LIST:%=doc/examples/%$(PROGSSUF)_g$(EXESUF)) +PROGS += $(DOC_EXAMPLES) + all-$(CONFIG_DOC): doc doc: documentation @@ -42,7 +59,9 @@ doc: documentation apidoc: doc/doxy/html documentation: $(DOCS) -TEXIDEP = awk '/^@(verbatim)?include/ { printf "$@: $(@D)/%s\n", $$2 }' <$< >$(@:%=%.d) +examples: $(DOC_EXAMPLES) + +TEXIDEP = perl $(SRC_PATH)/doc/texidep.pl $(SRC_PATH) $< $@ >$(@:%=%.d) doc/%.txt: TAG = TXT doc/%.txt: doc/%.texi @@ -59,12 +78,22 @@ $(GENTEXI): doc/avoptions_%.texi: doc/print_options$(HOSTEXESUF) doc/%.html: TAG = HTML doc/%.html: doc/%.texi $(SRC_PATH)/doc/t2h.init $(GENTEXI) $(Q)$(TEXIDEP) - $(M)texi2html -I doc -monolithic --init-file $(SRC_PATH)/doc/t2h.init --output $@ $< + $(M)texi2html -I doc -monolithic --D=config-not-all --init-file $(SRC_PATH)/doc/t2h.init --output $@ $< + +doc/%-all.html: TAG = HTML +doc/%-all.html: doc/%.texi $(SRC_PATH)/doc/t2h.init $(GENTEXI) + $(Q)$(TEXIDEP) + $(M)texi2html -I doc -monolithic --D=config-all --init-file $(SRC_PATH)/doc/t2h.init --output $@ $< doc/%.pod: TAG = POD doc/%.pod: doc/%.texi $(SRC_PATH)/doc/texi2pod.pl $(GENTEXI) $(Q)$(TEXIDEP) - $(M)perl $(SRC_PATH)/doc/texi2pod.pl -Idoc $< $@ + $(M)perl $(SRC_PATH)/doc/texi2pod.pl -Dconfig-not-all=yes -Idoc $< $@ + +doc/%-all.pod: TAG = POD +doc/%-all.pod: doc/%.texi $(SRC_PATH)/doc/texi2pod.pl $(GENTEXI) + $(Q)$(TEXIDEP) + $(M)perl $(SRC_PATH)/doc/texi2pod.pl -Dconfig-all=yes -Idoc $< $@ doc/%.1 doc/%.3: TAG = MAN doc/%.1: doc/%.pod $(GENTEXI) @@ -73,29 +102,59 @@ doc/%.3: doc/%.pod $(GENTEXI) $(M)pod2man --section=3 --center=" " --release=" " $< > $@ $(DOCS) doc/doxy/html: | doc/ +$(DOC_EXAMPLES:%=%.o): | doc/examples +OBJDIRS += doc/examples doc/doxy/html: $(SRC_PATH)/doc/Doxyfile $(INSTHEADERS) $(M)$(SRC_PATH)/doc/doxy-wrapper.sh $(SRC_PATH) $^ +install-doc: install-html install-man + +install-html: + install-man: +ifdef CONFIG_HTMLPAGES +install-progs-$(CONFIG_DOC): install-html + +install-html: $(HTMLPAGES) + $(Q)mkdir -p "$(DOCDIR)" + $(INSTALL) -m 644 $(HTMLPAGES) "$(DOCDIR)" +endif + ifdef CONFIG_MANPAGES install-progs-$(CONFIG_DOC): install-man install-man: $(MANPAGES) $(Q)mkdir -p "$(MANDIR)/man1" - $(INSTALL) -m 644 $(MANPAGES) "$(MANDIR)/man1" + $(INSTALL) -m 644 $(MANPAGES1) "$(MANDIR)/man1" + $(Q)mkdir -p "$(MANDIR)/man3" + $(INSTALL) -m 644 $(MANPAGES3) "$(MANDIR)/man3" endif -uninstall: uninstall-man +uninstall: uninstall-doc + +uninstall-doc: uninstall-html uninstall-man + +uninstall-html: + $(RM) -r "$(DOCDIR)" uninstall-man: - $(RM) $(addprefix "$(MANDIR)/man1/",$(ALLMANPAGES)) + $(RM) $(addprefix "$(MANDIR)/man1/",$(AVPROGS-yes:%=%.1) $(AVPROGS-yes:%=%-all.1) $(COMPONENTS-yes:%=%.1)) + $(RM) $(addprefix "$(MANDIR)/man3/",$(LIBRARIES-yes:%=%.3)) clean:: docclean -docclean: - $(RM) $(TXTPAGES) doc/*.html doc/*.pod doc/*.1 doc/*.3 $(CLEANSUFFIXES:%=doc/%) doc/avoptions_*.texi +distclean:: docclean + $(RM) doc/config.texi + +examplesclean: + $(RM) $(ALL_DOC_EXAMPLES) $(ALL_DOC_EXAMPLES_G) + $(RM) $(CLEANSUFFIXES:%=doc/examples/%) + +docclean: examplesclean + $(RM) $(CLEANSUFFIXES:%=doc/%) + $(RM) $(TXTPAGES) doc/*.html doc/*.pod doc/*.1 doc/*.3 doc/avoptions_*.texi $(RM) -r doc/doxy/html -include $(wildcard $(DOCS:%=%.d)) diff --git a/ffmpeg/doc/RELEASE_NOTES b/ffmpeg/doc/RELEASE_NOTES index 2faf40d..fae3a2b 100644 --- a/ffmpeg/doc/RELEASE_NOTES +++ b/ffmpeg/doc/RELEASE_NOTES @@ -1,7 +1,7 @@ Release Notes ============= -* 1.2 "Magic" March, 2013 +* 2.1 "Fourier" October, 2013 General notes diff --git a/ffmpeg/doc/avtools-common-opts.texi b/ffmpeg/doc/avtools-common-opts.texi deleted file mode 100644 index d9d0bd0..0000000 --- a/ffmpeg/doc/avtools-common-opts.texi +++ /dev/null @@ -1,211 +0,0 @@ -All the numerical options, if not specified otherwise, accept in input -a string representing a number, which may contain one of the -SI unit prefixes, for example 'K', 'M', 'G'. -If 'i' is appended after the prefix, binary prefixes are used, -which are based on powers of 1024 instead of powers of 1000. -The 'B' postfix multiplies the value by 8, and can be -appended after a unit prefix or used alone. This allows using for -example 'KB', 'MiB', 'G' and 'B' as number postfix. - -Options which do not take arguments are boolean options, and set the -corresponding value to true. They can be set to false by prefixing -with "no" the option name, for example using "-nofoo" in the -command line will set to false the boolean option with name "foo". - -@anchor{Stream specifiers} -@section Stream specifiers -Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers -are used to precisely specify which stream(s) does a given option belong to. - -A stream specifier is a string generally appended to the option name and -separated from it by a colon. E.g. @code{-codec:a:1 ac3} option contains -@code{a:1} stream specifier, which matches the second audio stream. Therefore it -would select the ac3 codec for the second audio stream. - -A stream specifier can match several streams, the option is then applied to all -of them. E.g. the stream specifier in @code{-b:a 128k} matches all audio -streams. - -An empty stream specifier matches all streams, for example @code{-codec copy} -or @code{-codec: copy} would copy all the streams without reencoding. - -Possible forms of stream specifiers are: -@table @option -@item @var{stream_index} -Matches the stream with this index. E.g. @code{-threads:1 4} would set the -thread count for the second stream to 4. -@item @var{stream_type}[:@var{stream_index}] -@var{stream_type} is one of: 'v' for video, 'a' for audio, 's' for subtitle, -'d' for data and 't' for attachments. If @var{stream_index} is given, then -matches stream number @var{stream_index} of this type. Otherwise matches all -streams of this type. -@item p:@var{program_id}[:@var{stream_index}] -If @var{stream_index} is given, then matches stream number @var{stream_index} in -program with id @var{program_id}. Otherwise matches all streams in this program. -@item #@var{stream_id} -Matches the stream by format-specific ID. -@end table - -@section Generic options - -These options are shared amongst the av* tools. - -@table @option - -@item -L -Show license. - -@item -h, -?, -help, --help [@var{arg}] -Show help. An optional parameter may be specified to print help about a specific -item. - -Possible values of @var{arg} are: -@table @option -@item decoder=@var{decoder_name} -Print detailed information about the decoder named @var{decoder_name}. Use the -@option{-decoders} option to get a list of all decoders. - -@item encoder=@var{encoder_name} -Print detailed information about the encoder named @var{encoder_name}. Use the -@option{-encoders} option to get a list of all encoders. - -@item demuxer=@var{demuxer_name} -Print detailed information about the demuxer named @var{demuxer_name}. Use the -@option{-formats} option to get a list of all demuxers and muxers. - -@item muxer=@var{muxer_name} -Print detailed information about the muxer named @var{muxer_name}. Use the -@option{-formats} option to get a list of all muxers and demuxers. - -@end table - -@item -version -Show version. - -@item -formats -Show available formats. - -The fields preceding the format names have the following meanings: -@table @samp -@item D -Decoding available -@item E -Encoding available -@end table - -@item -codecs -Show all codecs known to libavcodec. - -Note that the term 'codec' is used throughout this documentation as a shortcut -for what is more correctly called a media bitstream format. - -@item -decoders -Show available decoders. - -@item -encoders -Show all available encoders. - -@item -bsfs -Show available bitstream filters. - -@item -protocols -Show available protocols. - -@item -filters -Show available libavfilter filters. - -@item -pix_fmts -Show available pixel formats. - -@item -sample_fmts -Show available sample formats. - -@item -layouts -Show channel names and standard channel layouts. - -@item -loglevel @var{loglevel} | -v @var{loglevel} -Set the logging level used by the library. -@var{loglevel} is a number or a string containing one of the following values: -@table @samp -@item quiet -@item panic -@item fatal -@item error -@item warning -@item info -@item verbose -@item debug -@end table - -By default the program logs to stderr, if coloring is supported by the -terminal, colors are used to mark errors and warnings. Log coloring -can be disabled setting the environment variable -@env{AV_LOG_FORCE_NOCOLOR} or @env{NO_COLOR}, or can be forced setting -the environment variable @env{AV_LOG_FORCE_COLOR}. -The use of the environment variable @env{NO_COLOR} is deprecated and -will be dropped in a following FFmpeg version. - -@item -report -Dump full command line and console output to a file named -@code{@var{program}-@var{YYYYMMDD}-@var{HHMMSS}.log} in the current -directory. -This file can be useful for bug reports. -It also implies @code{-loglevel verbose}. - -Setting the environment variable @code{FFREPORT} to any value has the -same effect. If the value is a ':'-separated key=value sequence, these -options will affect the report; options values must be escaped if they -contain special characters or the options delimiter ':' (see the -``Quoting and escaping'' section in the ffmpeg-utils manual). The -following option is recognized: -@table @option -@item file -set the file name to use for the report; @code{%p} is expanded to the name -of the program, @code{%t} is expanded to a timestamp, @code{%%} is expanded -to a plain @code{%} -@end table - -Errors in parsing the environment variable are not fatal, and will not -appear in the report. - -@item -cpuflags flags (@emph{global}) -Allows setting and clearing cpu flags. This option is intended -for testing. Do not use it unless you know what you're doing. -@example -ffmpeg -cpuflags -sse+mmx ... -ffmpeg -cpuflags mmx ... -ffmpeg -cpuflags 0 ... -@end example - -@end table - -@section AVOptions - -These options are provided directly by the libavformat, libavdevice and -libavcodec libraries. To see the list of available AVOptions, use the -@option{-help} option. They are separated into two categories: -@table @option -@item generic -These options can be set for any container, codec or device. Generic options -are listed under AVFormatContext options for containers/devices and under -AVCodecContext options for codecs. -@item private -These options are specific to the given container, device or codec. Private -options are listed under their corresponding containers/devices/codecs. -@end table - -For example to write an ID3v2.3 header instead of a default ID3v2.4 to -an MP3 file, use the @option{id3v2_version} private option of the MP3 -muxer: -@example -ffmpeg -i input.flac -id3v2_version 3 out.mp3 -@end example - -All codec AVOptions are obviously per-stream, so the chapter on stream -specifiers applies to them - -Note @option{-nooption} syntax cannot be used for boolean AVOptions, -use @option{-option 0}/@option{-option 1}. - -Note2 old undocumented way of specifying per-stream AVOptions by prepending -v/a/s to the options name is now obsolete and will be removed soon. diff --git a/ffmpeg/doc/avutil.txt b/ffmpeg/doc/avutil.txt deleted file mode 100644 index 0847683..0000000 --- a/ffmpeg/doc/avutil.txt +++ /dev/null @@ -1,36 +0,0 @@ -AVUtil -====== -libavutil is a small lightweight library of generally useful functions. -It is not a library for code needed by both libavcodec and libavformat. - - -Overview: -========= -adler32.c adler32 checksum -aes.c AES encryption and decryption -fifo.c resizeable first in first out buffer -intfloat_readwrite.c portable reading and writing of floating point values -log.c "printf" with context and level -md5.c MD5 Message-Digest Algorithm -rational.c code to perform exact calculations with rational numbers -tree.c generic AVL tree -crc.c generic CRC checksumming code -integer.c 128bit integer math -lls.c -mathematics.c greatest common divisor, integer sqrt, integer log2, ... -mem.c memory allocation routines with guaranteed alignment - -Headers: -bswap.h big/little/native-endian conversion code -x86_cpu.h a few useful macros for unifying x86-64 and x86-32 code -avutil.h -common.h -intreadwrite.h reading and writing of unaligned big/little/native-endian integers - - -Goals: -====== -* Modular (few interdependencies and the possibility of disabling individual parts during ./configure) -* Small (source and object) -* Efficient (low CPU and memory usage) -* Useful (avoid useless features almost no one needs) diff --git a/ffmpeg/doc/bitstream_filters.texi b/ffmpeg/doc/bitstream_filters.texi index 2ee00c1..9bcb12c 100644 --- a/ffmpeg/doc/bitstream_filters.texi +++ b/ffmpeg/doc/bitstream_filters.texi @@ -17,9 +17,46 @@ Below is a description of the currently available bitstream filters. @section aac_adtstoasc +Convert MPEG-2/4 AAC ADTS to MPEG-4 Audio Specific Configuration +bitstream filter. + +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. + @section chomp -@section dump_extradata +Remove zero padding at the end of a packet. + +@section dump_extra + +Add extradata to the beginning of the filtered packets. + +The additional argument specifies which packets should be filtered. +It accepts the values: +@table @samp +@item a +add extradata to all key packets, but only if @var{local_header} is +set in the @option{flags2} codec context field + +@item k +add extradata to all key packets + +@item e +add extradata to all packets +@end table + +If not specified it is assumed @samp{k}. + +For example the following @command{ffmpeg} command forces a global +header (thus disabling individual packet headers) in the H.264 packets +generated by the @code{libx264} encoder, but corrects them by adding +the header stored in extradata to the key packets: +@example +ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts +@end example @section h264_mp4toannexb @@ -80,12 +117,10 @@ ffmpeg -i frame_%d.jpg -c:v copy rotated.avi @section movsub -@section mp3_header_compress - @section mp3_header_decompress @section noise -@section remove_extradata +@section remove_extra @c man end BITSTREAM FILTERS diff --git a/ffmpeg/doc/decoders.texi b/ffmpeg/doc/decoders.texi index 2d812a2..9d9f298 100644 --- a/ffmpeg/doc/decoders.texi +++ b/ffmpeg/doc/decoders.texi @@ -60,6 +60,78 @@ This decoder generates wave patterns according to predefined sequences. Its use is purely internal and the format of the data it accepts is not publicly documented. +@section libcelt + +libcelt decoder wrapper. + +libcelt allows libavcodec to decode the Xiph CELT ultra-low delay audio codec. +Requires the presence of the libcelt headers and library during configuration. +You need to explicitly configure the build with @code{--enable-libcelt}. + +@section libgsm + +libgsm decoder wrapper. + +libgsm allows libavcodec to decode the GSM full rate audio codec. Requires +the presence of the libgsm headers and library during configuration. You need +to explicitly configure the build with @code{--enable-libgsm}. + +This decoder supports both the ordinary GSM and the Microsoft variant. + +@section libilbc + +libilbc decoder wrapper. + +libilbc allows libavcodec to decode the Internet Low Bitrate Codec (iLBC) +audio codec. Requires the presence of the libilbc headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libilbc}. + +@subsection Options + +The following option is supported by the libilbc wrapper. + +@table @option +@item enhance + +Enable the enhancement of the decoded audio when set to 1. The default +value is 0 (disabled). + +@end table + +@section libopencore-amrnb + +libopencore-amrnb decoder wrapper. + +libopencore-amrnb allows libavcodec to decode the Adaptive Multi-Rate +Narrowband audio codec. Using it requires the presence of the +libopencore-amrnb headers and library during configuration. You need to +explicitly configure the build with @code{--enable-libopencore-amrnb}. + +An FFmpeg native decoder for AMR-NB exists, so users can decode AMR-NB +without this library. + +@section libopencore-amrwb + +libopencore-amrwb decoder wrapper. + +libopencore-amrwb allows libavcodec to decode the Adaptive Multi-Rate +Wideband audio codec. Using it requires the presence of the +libopencore-amrwb headers and library during configuration. You need to +explicitly configure the build with @code{--enable-libopencore-amrwb}. + +An FFmpeg native decoder for AMR-WB exists, so users can decode AMR-WB +without this library. + +@section libopus + +libopus decoder wrapper. + +libopus allows libavcodec to decode the Opus Interactive Audio Codec. +Requires the presence of the libopus headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libopus}. + @c man end AUDIO DECODERS @chapter Subtitles Decoders @@ -86,4 +158,45 @@ ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, 7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b}. @end table +@section libzvbi-teletext + +Libzvbi allows libavcodec to decode DVB teletext pages and DVB teletext +subtitles. Requires the presence of the libzvbi headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libzvbi}. + +@subsection Options + +@table @option +@item txt_page +List of teletext page numbers to decode. You may use the special * string to +match all pages. Pages that do not match the specified list are dropped. +Default value is *. +@item txt_chop_top +Discards the top teletext line. Default value is 1. +@item txt_format +Specifies the format of the decoded subtitles. The teletext decoder is capable +of decoding the teletext pages to bitmaps or to simple text, you should use +"bitmap" for teletext pages, because certain graphics and colors cannot be +expressed in simple text. You might use "text" for teletext based subtitles if +your application can handle simple text based subtitles. Default value is +bitmap. +@item txt_left +X offset of generated bitmaps, default is 0. +@item txt_top +Y offset of generated bitmaps, default is 0. +@item txt_chop_spaces +Chops leading and trailing spaces and removes empty lines from the generated +text. This option is useful for teletext based subtitles where empty spaces may +be present at the start or at the end of the lines or empty lines may be +present between the subtitle lines because of double-sized teletext charactes. +Default value is 1. +@item txt_duration +Sets the display duration of the decoded teletext pages or subtitles in +miliseconds. Default value is 30000 which is 30 seconds. +@item txt_transparent +Force transparent background of the generated teletext bitmaps. Default value +is 0 which means an opaque (black) background. +@end table + @c man end SUBTILES DECODERS diff --git a/ffmpeg/doc/default.css b/ffmpeg/doc/default.css index 77a3514..bf50200 100644 --- a/ffmpeg/doc/default.css +++ b/ffmpeg/doc/default.css @@ -1,3 +1,7 @@ +a.summary-letter { + text-decoration: none; +} + a { color: #2D6198; } @@ -13,8 +17,8 @@ a:visited { } #banner img { - padding-bottom: 1px; - padding-top: 5px; + margin-bottom: 1px; + margin-top: 5px; } #body { @@ -45,11 +49,16 @@ body { text-align: center; } -h1, h2, h3 { +h1 a, h2 a, h3 a, h4 a { + text-decoration: inherit; + color: inherit; +} + +h1, h2, h3, h4 { padding-left: 0.4em; border-radius: 4px; - padding-bottom: 0.2em; - padding-top: 0.2em; + padding-bottom: 0.25em; + padding-top: 0.25em; border: 1px solid #6A996A; } @@ -63,15 +72,22 @@ h1 { h2 { color: #313131; - font-size: 0.9em; + font-size: 1.0em; background-color: #ABE3AB; } h3 { color: #313131; + font-size: 0.9em; + margin-bottom: -6px; + background-color: #BBF3BB; +} + +h4 { + color: #313131; font-size: 0.8em; margin-bottom: -8px; - background-color: #BBF3BB; + background-color: #D1FDD1; } img { diff --git a/ffmpeg/doc/demuxers.texi b/ffmpeg/doc/demuxers.texi index fc50871..bfc0bdc 100644 --- a/ffmpeg/doc/demuxers.texi +++ b/ffmpeg/doc/demuxers.texi @@ -1,7 +1,7 @@ @chapter Demuxers @c man begin DEMUXERS -Demuxers are configured elements in FFmpeg which allow to read the +Demuxers are configured elements in FFmpeg that can read the multimedia streams from a particular type of file. When you configure your FFmpeg build, all the supported demuxers @@ -29,6 +29,17 @@ the caller can decide which variant streams to actually receive. The total bitrate of the variant that the stream belongs to is available in a metadata key named "variant_bitrate". +@section asf + +Advanced Systems Format demuxer. + +This demuxer is used to demux ASF files and MMS network streams. + +@table @option +@item -no_resync_search @var{bool} +Do not try to resynchronize by looking for a certain optional start code. +@end table + @anchor{concat} @section concat @@ -103,6 +114,42 @@ probed and 0 otherwise. @end table +@section flv + +Adobe Flash Video Format demuxer. + +This demuxer is used to demux FLV files and RTMP network streams. + +@table @option +@item -flv_metadata @var{bool} +Allocate the streams according to the onMetaData array content. +@end table + +@section libgme + +The Game Music Emu library is a collection of video game music file emulators. + +See @url{http://code.google.com/p/game-music-emu/} for more information. + +Some files have multiple tracks. The demuxer will pick the first track by +default. The @option{track_index} option can be used to select a different +track. Track indexes start at 0. The demuxer exports the number of tracks as +@var{tracks} meta data entry. + +For very large files, the @option{max_size} option may have to be adjusted. + +@section libquvi + +Play media from Internet services using the quvi project. + +The demuxer accepts a @option{format} option to request a specific quality. It +is by default set to @var{best}. + +See @url{http://quvi.sourceforge.net/} for more information. + +FFmpeg needs to be built with @code{--enable-libquvi} for this demuxer to be +enabled. + @section image2 Image file demuxer. @@ -120,7 +167,7 @@ same for all the files in the sequence. This demuxer accepts the following options: @table @option @item framerate -Set the framerate for the video stream. It defaults to 25. +Set the frame rate for the video stream. It defaults to 25. @item loop If set to 1, loop over the input. Default value is 0. @item pattern_type @@ -198,6 +245,10 @@ to read from. Default value is 0. Set the index interval range to check when looking for the first image file in the sequence, starting from @var{start_number}. Default value is 5. +@item ts_from_file +If set to 1, will set frame timestamp to modification time of image file. Note +that monotonity of timestamps is not provided: images go in the same order as +without this option. Default value is 0. @item video_size Set the video size of the images to read. If not specified the video size is guessed from the first image file in the sequence. @@ -211,23 +262,36 @@ Use @command{ffmpeg} for creating a video from the images in the file sequence @file{img-001.jpeg}, @file{img-002.jpeg}, ..., assuming an input frame rate of 10 frames per second: @example -ffmpeg -i 'img-%03d.jpeg' -r 10 out.mkv +ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv @end example @item As above, but start by reading from a file with index 100 in the sequence: @example -ffmpeg -start_number 100 -i 'img-%03d.jpeg' -r 10 out.mkv +ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv @end example @item Read images matching the "*.png" glob pattern , that is all the files terminating with the ".png" suffix: @example -ffmpeg -pattern_type glob -i "*.png" -r 10 out.mkv +ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv @end example @end itemize +@section mpegts + +MPEG-2 transport stream demuxer. + +@table @option + +@item fix_teletext_pts +Overrides teletext packet PTS and DTS values with the timestamps calculated +from the PCR of the first program which the teletext stream is part of and is +not discarded. Default value is 1, set this option to 0 if you want your +teletext packet PTS and DTS values untouched. +@end table + @section rawvideo Raw video demuxer. diff --git a/ffmpeg/doc/developer.texi b/ffmpeg/doc/developer.texi index bd3f7a7..1e1d3b8 100644 --- a/ffmpeg/doc/developer.texi +++ b/ffmpeg/doc/developer.texi @@ -11,29 +11,23 @@ @chapter Developers Guide -@section API -@itemize @bullet -@item libavcodec is the library containing the codecs (both encoding and -decoding). Look at @file{doc/examples/decoding_encoding.c} to see how to use -it. - -@item libavformat is the library containing the file format handling (mux and -demux code for several formats). Look at @file{ffplay.c} to use it in a -player. See @file{doc/examples/muxing.c} to use it to generate audio or video -streams. - -@end itemize +@section Notes for external developers -@section Integrating libavcodec or libavformat in your program +This document is mostly useful for internal FFmpeg developers. +External developers who need to use the API in their application should +refer to the API doxygen documentation in the public headers, and +check the examples in @file{doc/examples} and in the source code to +see how the public API is employed. -You can integrate all the source code of the libraries to link them -statically to avoid any version problem. All you need is to provide a -'config.mak' and a 'config.h' in the parent directory. See the defines -generated by ./configure to understand what is needed. +You can use the FFmpeg libraries in your commercial program, but you +are encouraged to @emph{publish any patch you make}. In this case the +best way to proceed is to send your patches to the ffmpeg-devel +mailing list following the guidelines illustrated in the remainder of +this document. -You can use libavcodec or libavformat in your commercial program, but -@emph{any patch you make must be published}. The best way to proceed is -to send your patches to the FFmpeg mailing list. +For more detailed legal information about the use of FFmpeg in +external programs read the @file{LICENSE} file in the source tree and +consult @url{http://ffmpeg.org/legal.html}. @section Contributing @@ -57,13 +51,16 @@ and should try to fix issues their commit causes. @subsection Code formatting conventions There are the following guidelines regarding the indentation in files: + @itemize @bullet @item Indent size is 4. + @item The TAB character is forbidden outside of Makefiles as is any form of trailing whitespace. Commits containing either will be rejected by the git repository. + @item You should try to limit your code lines to 80 characters; however, do so if and only if this improves readability. @@ -95,7 +92,7 @@ for markup commands, i.e. use @code{@@param} and not @code{\param}. * more text ... * ... */ -typedef struct Foobar@{ +typedef struct Foobar @{ int var1; /**< var1 description */ int var2; ///< var2 description /** var3 description */ @@ -117,13 +114,17 @@ int myfunc(int my_parameter) FFmpeg is programmed in the ISO C90 language with a few additional features from ISO C99, namely: + @itemize @bullet @item the @samp{inline} keyword; + @item @samp{//} comments; + @item designated struct initializers (@samp{struct s x = @{ .i = 17 @};}) + @item compound literals (@samp{x = (struct s) @{ 17, 23 @};}) @end itemize @@ -135,13 +136,17 @@ clarity and performance. All code must compile with recent versions of GCC and a number of other currently supported compilers. To ensure compatibility, please do not use additional C99 features or GCC extensions. Especially watch out for: + @itemize @bullet @item mixing statements and declarations; + @item @samp{long long} (use @samp{int64_t} instead); + @item @samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar; + @item GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}). @end itemize @@ -153,17 +158,25 @@ All names should be composed with underscores (_), not CamelCase. For example, for example structs and enums; they should always be in the CamelCase There are the following conventions for naming variables and functions: + @itemize @bullet @item For local variables no prefix is required. + @item -For variables and functions declared as @code{static} no prefix is required. +For file-scope variables and functions declared as @code{static}, no prefix +is required. + @item -For variables and functions used internally by a library an @code{ff_} -prefix should be used, e.g. @samp{ff_w64_demuxer}. +For variables and functions visible outside of file scope, but only used +internally by a library, an @code{ff_} prefix should be used, +e.g. @samp{ff_w64_demuxer}. + @item -For variables and functions used internally across multiple libraries, use -@code{avpriv_}. For example, @samp{avpriv_aac_parse_header}. +For variables and functions visible outside of file scope, used internally +across multiple libraries, use @code{avpriv_} as prefix, for example, +@samp{avpriv_aac_parse_header}. + @item Each library has its own prefix for public symbols, in addition to the commonly used @code{av_} (@code{avformat_} for libavformat, @@ -183,10 +196,12 @@ are reserved at the file level and may not be used for externally visible symbols. If in doubt, just avoid names starting with @code{_} altogether. @subsection Miscellaneous conventions + @itemize @bullet @item fprintf and printf are forbidden in libavformat and libavcodec, please use av_log() instead. + @item Casts should be used only when necessary. Unneeded parentheses should also be avoided if they don't make the code easier to understand. @@ -229,131 +244,154 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}: @enumerate @item - Contributions should be licensed under the - @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1}, - including an "or any later version" clause, or, if you prefer - a gift-style license, the - @uref{http://www.isc.org/software/license/, ISC} or - @uref{http://mit-license.org/, MIT} license. - @uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including - an "or any later version" clause is also acceptable, but LGPL is - preferred. -@item - You must not commit code which breaks FFmpeg! (Meaning unfinished but - enabled code which breaks compilation or compiles but does not work or - breaks the regression tests) - You can commit unfinished stuff (for testing etc), but it must be disabled - (#ifdef etc) by default so it does not interfere with other developers' - work. -@item - The commit message should have a short first line in the form of - a @samp{topic: short description} as a header, separated by a newline - from the body consisting of an explanation of why the change is necessary. - If the commit fixes a known bug on the bug tracker, the commit message - should include its bug ID. Referring to the issue on the bug tracker does - not exempt you from writing an excerpt of the bug in the commit message. -@item - You do not have to over-test things. If it works for you, and you think it - should work for others, then commit. If your code has problems - (portability, triggers compiler bugs, unusual environment etc) they will be - reported and eventually fixed. -@item - Do not commit unrelated changes together, split them into self-contained - pieces. Also do not forget that if part B depends on part A, but A does not - depend on B, then A can and should be committed first and separate from B. - Keeping changes well split into self-contained parts makes reviewing and - understanding them on the commit log mailing list easier. This also helps - in case of debugging later on. - Also if you have doubts about splitting or not splitting, do not hesitate to - ask/discuss it on the developer mailing list. -@item - Do not change behavior of the programs (renaming options etc) or public - API or ABI without first discussing it on the ffmpeg-devel mailing list. - Do not remove functionality from the code. Just improve! - - Note: Redundant code can be removed. -@item - Do not commit changes to the build system (Makefiles, configure script) - which change behavior, defaults etc, without asking first. The same - applies to compiler warning fixes, trivial looking fixes and to code - maintained by other developers. We usually have a reason for doing things - the way we do. Send your changes as patches to the ffmpeg-devel mailing - list, and if the code maintainers say OK, you may commit. This does not - apply to files you wrote and/or maintain. -@item - We refuse source indentation and other cosmetic changes if they are mixed - with functional changes, such commits will be rejected and removed. Every - developer has his own indentation style, you should not change it. Of course - if you (re)write something, you can use your own style, even though we would - prefer if the indentation throughout FFmpeg was consistent (Many projects - force a given indentation style - we do not.). If you really need to make - indentation changes (try to avoid this), separate them strictly from real - changes. - - NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code, - then either do NOT change the indentation of the inner part within (do not - move it to the right)! or do so in a separate commit -@item - Always fill out the commit log message. Describe in a few lines what you - changed and why. You can refer to mailing list postings if you fix a - particular bug. Comments such as "fixed!" or "Changed it." are unacceptable. - Recommended format: - area changed: Short 1 line description - - details describing what and why and giving references. -@item - Make sure the author of the commit is set correctly. (see git commit --author) - If you apply a patch, send an - answer to ffmpeg-devel (or wherever you got the patch from) saying that - you applied the patch. -@item - When applying patches that have been discussed (at length) on the mailing - list, reference the thread in the log message. -@item - Do NOT commit to code actively maintained by others without permission. - Send a patch to ffmpeg-devel instead. If no one answers within a reasonable - timeframe (12h for build failures and security fixes, 3 days small changes, - 1 week for big patches) then commit your patch if you think it is OK. - Also note, the maintainer can simply ask for more time to review! -@item - Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits - are sent there and reviewed by all the other developers. Bugs and possible - improvements or general questions regarding commits are discussed there. We - expect you to react if problems with your code are uncovered. -@item - Update the documentation if you change behavior or add features. If you are - unsure how best to do this, send a patch to ffmpeg-devel, the documentation - maintainer(s) will review and commit your stuff. -@item - Try to keep important discussions and requests (also) on the public - developer mailing list, so that all developers can benefit from them. -@item - Never write to unallocated memory, never write over the end of arrays, - always check values read from some untrusted source before using them - as array index or other risky things. -@item - Remember to check if you need to bump versions for the specific libav* - parts (libavutil, libavcodec, libavformat) you are changing. You need - to change the version integer. - Incrementing the first component means no backward compatibility to - previous versions (e.g. removal of a function from the public API). - Incrementing the second component means backward compatible change - (e.g. addition of a function to the public API or extension of an - existing data structure). - Incrementing the third component means a noteworthy binary compatible - change (e.g. encoder bug fix that matters for the decoder). The third - component always starts at 100 to distinguish FFmpeg from Libav. -@item - Compiler warnings indicate potential bugs or code with bad style. If a type of - warning always points to correct and clean code, that warning should - be disabled, not the code changed. - Thus the remaining warnings can either be bugs or correct code. - If it is a bug, the bug has to be fixed. If it is not, the code should - be changed to not generate a warning unless that causes a slowdown - or obfuscates the code. -@item - If you add a new file, give it a proper license header. Do not copy and - paste it from a random place, use an existing file as template. +Contributions should be licensed under the +@uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1}, +including an "or any later version" clause, or, if you prefer +a gift-style license, the +@uref{http://opensource.org/licenses/isc-license.txt, ISC} or +@uref{http://mit-license.org/, MIT} license. +@uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including +an "or any later version" clause is also acceptable, but LGPL is +preferred. +If you add a new file, give it a proper license header. Do not copy and +paste it from a random place, use an existing file as template. + +@item +You must not commit code which breaks FFmpeg! (Meaning unfinished but +enabled code which breaks compilation or compiles but does not work or +breaks the regression tests) +You can commit unfinished stuff (for testing etc), but it must be disabled +(#ifdef etc) by default so it does not interfere with other developers' +work. + +@item +The commit message should have a short first line in the form of +a @samp{topic: short description} as a header, separated by a newline +from the body consisting of an explanation of why the change is necessary. +If the commit fixes a known bug on the bug tracker, the commit message +should include its bug ID. Referring to the issue on the bug tracker does +not exempt you from writing an excerpt of the bug in the commit message. + +@item +You do not have to over-test things. If it works for you, and you think it +should work for others, then commit. If your code has problems +(portability, triggers compiler bugs, unusual environment etc) they will be +reported and eventually fixed. + +@item +Do not commit unrelated changes together, split them into self-contained +pieces. Also do not forget that if part B depends on part A, but A does not +depend on B, then A can and should be committed first and separate from B. +Keeping changes well split into self-contained parts makes reviewing and +understanding them on the commit log mailing list easier. This also helps +in case of debugging later on. +Also if you have doubts about splitting or not splitting, do not hesitate to +ask/discuss it on the developer mailing list. + +@item +Do not change behavior of the programs (renaming options etc) or public +API or ABI without first discussing it on the ffmpeg-devel mailing list. +Do not remove functionality from the code. Just improve! + +Note: Redundant code can be removed. + +@item +Do not commit changes to the build system (Makefiles, configure script) +which change behavior, defaults etc, without asking first. The same +applies to compiler warning fixes, trivial looking fixes and to code +maintained by other developers. We usually have a reason for doing things +the way we do. Send your changes as patches to the ffmpeg-devel mailing +list, and if the code maintainers say OK, you may commit. This does not +apply to files you wrote and/or maintain. + +@item +We refuse source indentation and other cosmetic changes if they are mixed +with functional changes, such commits will be rejected and removed. Every +developer has his own indentation style, you should not change it. Of course +if you (re)write something, you can use your own style, even though we would +prefer if the indentation throughout FFmpeg was consistent (Many projects +force a given indentation style - we do not.). If you really need to make +indentation changes (try to avoid this), separate them strictly from real +changes. + +NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code, +then either do NOT change the indentation of the inner part within (do not +move it to the right)! or do so in a separate commit + +@item +Always fill out the commit log message. Describe in a few lines what you +changed and why. You can refer to mailing list postings if you fix a +particular bug. Comments such as "fixed!" or "Changed it." are unacceptable. +Recommended format: +area changed: Short 1 line description + +details describing what and why and giving references. + +@item +Make sure the author of the commit is set correctly. (see git commit --author) +If you apply a patch, send an +answer to ffmpeg-devel (or wherever you got the patch from) saying that +you applied the patch. + +@item +When applying patches that have been discussed (at length) on the mailing +list, reference the thread in the log message. + +@item +Do NOT commit to code actively maintained by others without permission. +Send a patch to ffmpeg-devel instead. If no one answers within a reasonable +timeframe (12h for build failures and security fixes, 3 days small changes, +1 week for big patches) then commit your patch if you think it is OK. +Also note, the maintainer can simply ask for more time to review! + +@item +Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits +are sent there and reviewed by all the other developers. Bugs and possible +improvements or general questions regarding commits are discussed there. We +expect you to react if problems with your code are uncovered. + +@item +Update the documentation if you change behavior or add features. If you are +unsure how best to do this, send a patch to ffmpeg-devel, the documentation +maintainer(s) will review and commit your stuff. + +@item +Try to keep important discussions and requests (also) on the public +developer mailing list, so that all developers can benefit from them. + +@item +Never write to unallocated memory, never write over the end of arrays, +always check values read from some untrusted source before using them +as array index or other risky things. + +@item +Remember to check if you need to bump versions for the specific libav* +parts (libavutil, libavcodec, libavformat) you are changing. You need +to change the version integer. +Incrementing the first component means no backward compatibility to +previous versions (e.g. removal of a function from the public API). +Incrementing the second component means backward compatible change +(e.g. addition of a function to the public API or extension of an +existing data structure). +Incrementing the third component means a noteworthy binary compatible +change (e.g. encoder bug fix that matters for the decoder). The third +component always starts at 100 to distinguish FFmpeg from Libav. + +@item +Compiler warnings indicate potential bugs or code with bad style. If a type of +warning always points to correct and clean code, that warning should +be disabled, not the code changed. +Thus the remaining warnings can either be bugs or correct code. +If it is a bug, the bug has to be fixed. If it is not, the code should +be changed to not generate a warning unless that causes a slowdown +or obfuscates the code. + +@item +Make sure that no parts of the codebase that you maintain are missing from the +@file{MAINTAINERS} file. If something that you want to maintain is missing add it with +your name after it. +If at some point you no longer want to maintain some code, then please help +finding a new maintainer and also don't forget updating the @file{MAINTAINERS} file. @end enumerate We think our rules are not too hard. If you have comments, contact us. @@ -408,40 +446,51 @@ send a reminder by email. Your patch should eventually be dealt with. @enumerate @item - Did you use av_cold for codec initialization and close functions? +Did you use av_cold for codec initialization and close functions? + @item - Did you add a long_name under NULL_IF_CONFIG_SMALL to the AVCodec or - AVInputFormat/AVOutputFormat struct? +Did you add a long_name under NULL_IF_CONFIG_SMALL to the AVCodec or +AVInputFormat/AVOutputFormat struct? + @item - Did you bump the minor version number (and reset the micro version - number) in @file{libavcodec/version.h} or @file{libavformat/version.h}? +Did you bump the minor version number (and reset the micro version +number) in @file{libavcodec/version.h} or @file{libavformat/version.h}? + @item - Did you register it in @file{allcodecs.c} or @file{allformats.c}? +Did you register it in @file{allcodecs.c} or @file{allformats.c}? + @item - Did you add the AVCodecID to @file{avcodec.h}? - When adding new codec IDs, also add an entry to the codec descriptor - list in @file{libavcodec/codec_desc.c}. +Did you add the AVCodecID to @file{avcodec.h}? +When adding new codec IDs, also add an entry to the codec descriptor +list in @file{libavcodec/codec_desc.c}. + @item - If it has a FourCC, did you add it to @file{libavformat/riff.c}, - even if it is only a decoder? +If it has a FourCC, did you add it to @file{libavformat/riff.c}, +even if it is only a decoder? + @item - Did you add a rule to compile the appropriate files in the Makefile? - Remember to do this even if you're just adding a format to a file that is - already being compiled by some other rule, like a raw demuxer. +Did you add a rule to compile the appropriate files in the Makefile? +Remember to do this even if you're just adding a format to a file that is +already being compiled by some other rule, like a raw demuxer. + @item - Did you add an entry to the table of supported formats or codecs in - @file{doc/general.texi}? +Did you add an entry to the table of supported formats or codecs in +@file{doc/general.texi}? + @item - Did you add an entry in the Changelog? +Did you add an entry in the Changelog? + @item - If it depends on a parser or a library, did you add that dependency in - configure? +If it depends on a parser or a library, did you add that dependency in +configure? + @item - Did you @code{git add} the appropriate files before committing? +Did you @code{git add} the appropriate files before committing? + @item - Did you make sure it compiles standalone, i.e. with - @code{configure --disable-everything --enable-decoder=foo} - (or @code{--enable-demuxer} or whatever your component is)? +Did you make sure it compiles standalone, i.e. with +@code{configure --disable-everything --enable-decoder=foo} +(or @code{--enable-demuxer} or whatever your component is)? @end enumerate @@ -449,82 +498,109 @@ send a reminder by email. Your patch should eventually be dealt with. @enumerate @item - Does @code{make fate} pass with the patch applied? +Does @code{make fate} pass with the patch applied? + @item - Was the patch generated with git format-patch or send-email? +Was the patch generated with git format-patch or send-email? + @item - Did you sign off your patch? (git commit -s) - See @url{http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/SubmittingPatches} for the meaning - of sign off. +Did you sign off your patch? (git commit -s) +See @url{http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/SubmittingPatches} for the meaning +of sign off. + @item - Did you provide a clear git commit log message? +Did you provide a clear git commit log message? + @item - Is the patch against latest FFmpeg git master branch? +Is the patch against latest FFmpeg git master branch? + @item - Are you subscribed to ffmpeg-devel? - (the list is subscribers only due to spam) +Are you subscribed to ffmpeg-devel? +(the list is subscribers only due to spam) + @item - Have you checked that the changes are minimal, so that the same cannot be - achieved with a smaller patch and/or simpler final code? +Have you checked that the changes are minimal, so that the same cannot be +achieved with a smaller patch and/or simpler final code? + @item - If the change is to speed critical code, did you benchmark it? +If the change is to speed critical code, did you benchmark it? + @item - If you did any benchmarks, did you provide them in the mail? +If you did any benchmarks, did you provide them in the mail? + @item - Have you checked that the patch does not introduce buffer overflows or - other security issues? +Have you checked that the patch does not introduce buffer overflows or +other security issues? + @item - Did you test your decoder or demuxer against damaged data? If no, see - tools/trasher, the noise bitstream filter, and - @uref{http://caca.zoy.org/wiki/zzuf, zzuf}. Your decoder or demuxer - should not crash, end in a (near) infinite loop, or allocate ridiculous - amounts of memory when fed damaged data. +Did you test your decoder or demuxer against damaged data? If no, see +tools/trasher, the noise bitstream filter, and +@uref{http://caca.zoy.org/wiki/zzuf, zzuf}. Your decoder or demuxer +should not crash, end in a (near) infinite loop, or allocate ridiculous +amounts of memory when fed damaged data. + @item - Does the patch not mix functional and cosmetic changes? +Does the patch not mix functional and cosmetic changes? + @item - Did you add tabs or trailing whitespace to the code? Both are forbidden. +Did you add tabs or trailing whitespace to the code? Both are forbidden. + @item - Is the patch attached to the email you send? +Is the patch attached to the email you send? + @item - Is the mime type of the patch correct? It should be text/x-diff or - text/x-patch or at least text/plain and not application/octet-stream. +Is the mime type of the patch correct? It should be text/x-diff or +text/x-patch or at least text/plain and not application/octet-stream. + @item - If the patch fixes a bug, did you provide a verbose analysis of the bug? +If the patch fixes a bug, did you provide a verbose analysis of the bug? + @item - If the patch fixes a bug, did you provide enough information, including - a sample, so the bug can be reproduced and the fix can be verified? - Note please do not attach samples >100k to mails but rather provide a - URL, you can upload to ftp://upload.ffmpeg.org +If the patch fixes a bug, did you provide enough information, including +a sample, so the bug can be reproduced and the fix can be verified? +Note please do not attach samples >100k to mails but rather provide a +URL, you can upload to ftp://upload.ffmpeg.org + @item - Did you provide a verbose summary about what the patch does change? +Did you provide a verbose summary about what the patch does change? + @item - Did you provide a verbose explanation why it changes things like it does? +Did you provide a verbose explanation why it changes things like it does? + @item - Did you provide a verbose summary of the user visible advantages and - disadvantages if the patch is applied? +Did you provide a verbose summary of the user visible advantages and +disadvantages if the patch is applied? + @item - Did you provide an example so we can verify the new feature added by the - patch easily? +Did you provide an example so we can verify the new feature added by the +patch easily? + @item - If you added a new file, did you insert a license header? It should be - taken from FFmpeg, not randomly copied and pasted from somewhere else. +If you added a new file, did you insert a license header? It should be +taken from FFmpeg, not randomly copied and pasted from somewhere else. + @item - You should maintain alphabetical order in alphabetically ordered lists as - long as doing so does not break API/ABI compatibility. +You should maintain alphabetical order in alphabetically ordered lists as +long as doing so does not break API/ABI compatibility. + @item - Lines with similar content should be aligned vertically when doing so - improves readability. +Lines with similar content should be aligned vertically when doing so +improves readability. + @item - Consider to add a regression test for your code. +Consider to add a regression test for your code. + @item - If you added YASM code please check that things still work with --disable-yasm +If you added YASM code please check that things still work with --disable-yasm + @item - Make sure you check the return values of function and return appropriate - error codes. Especially memory allocation functions like @code{av_malloc()} - are notoriously left unchecked, which is a serious problem. +Make sure you check the return values of function and return appropriate +error codes. Especially memory allocation functions like @code{av_malloc()} +are notoriously left unchecked, which is a serious problem. + @item - Test your code with valgrind and or Address Sanitizer to ensure it's free - of leaks, out of array accesses, etc. +Test your code with valgrind and or Address Sanitizer to ensure it's free +of leaks, out of array accesses, etc. @end enumerate @section Patch review process @@ -577,6 +653,46 @@ message or introductionary message for the patch series that you post to the ffmpeg-devel mailing list, a direct link to download the sample media. +@subsection Visualizing Test Coverage + +The FFmpeg build system allows visualizing the test coverage in an easy +manner with the coverage tools @code{gcov}/@code{lcov}. This involves +the following steps: + +@enumerate +@item + Configure to compile with instrumentation enabled: + @code{configure --toolchain=gcov}. + +@item + Run your test case, either manually or via FATE. This can be either + the full FATE regression suite, or any arbitrary invocation of any + front-end tool provided by FFmpeg, in any combination. + +@item + Run @code{make lcov} to generate coverage data in HTML format. + +@item + View @code{lcov/index.html} in your preferred HTML viewer. +@end enumerate + +You can use the command @code{make lcov-reset} to reset the coverage +measurements. You will need to rerun @code{make lcov} after running a +new test. + +@subsection Using Valgrind + +The configure script provides a shortcut for using valgrind to spot bugs +related to memory handling. Just add the option +@code{--toolchain=valgrind-memcheck} or @code{--toolchain=valgrind-massif} +to your configure line, and reasonable defaults will be set for running +FATE under the supervision of either the @strong{memcheck} or the +@strong{massif} tool of the valgrind suite. + +In case you need finer control over how valgrind is invoked, use the +@code{--target-exec='valgrind <your_custom_valgrind_options>} option in +your configure line instead. + @anchor{Release process} @section Release process @@ -590,12 +706,13 @@ There are two kinds of releases: @enumerate @item - @strong{Major releases} always include the latest and greatest - features and functionality. +@strong{Major releases} always include the latest and greatest +features and functionality. + @item - @strong{Point releases} are cut from @strong{release} branches, - which are named @code{release/X}, with @code{X} being the release - version number. +@strong{Point releases} are cut from @strong{release} branches, +which are named @code{release/X}, with @code{X} being the release +version number. @end enumerate Note that we promise to our users that shared libraries from any FFmpeg @@ -616,15 +733,18 @@ inclusion into a point release: @enumerate @item - Fixes a security issue, preferably identified by a @strong{CVE - number} issued by @url{http://cve.mitre.org/}. +Fixes a security issue, preferably identified by a @strong{CVE +number} issued by @url{http://cve.mitre.org/}. + @item - Fixes a documented bug in @url{https://ffmpeg.org/trac/ffmpeg}. +Fixes a documented bug in @url{https://trac.ffmpeg.org}. + @item - Improves the included documentation. +Improves the included documentation. + @item - Retains both source code and binary compatibility with previous - point releases of the same release branch. +Retains both source code and binary compatibility with previous +point releases of the same release branch. @end enumerate The order for checking the rules is (1 OR 2 OR 3) AND 4. @@ -636,33 +756,42 @@ The release process involves the following steps: @enumerate @item - Ensure that the @file{RELEASE} file contains the version number for - the upcoming release. +Ensure that the @file{RELEASE} file contains the version number for +the upcoming release. + @item - Add the release at @url{https://ffmpeg.org/trac/ffmpeg/admin/ticket/versions}. +Add the release at @url{https://trac.ffmpeg.org/admin/ticket/versions}. + @item - Announce the intent to do a release to the mailing list. +Announce the intent to do a release to the mailing list. + @item - Make sure all relevant security fixes have been backported. See - @url{https://ffmpeg.org/security.html}. +Make sure all relevant security fixes have been backported. See +@url{https://ffmpeg.org/security.html}. + @item - Ensure that the FATE regression suite still passes in the release - branch on at least @strong{i386} and @strong{amd64} - (cf. @ref{Regression tests}). +Ensure that the FATE regression suite still passes in the release +branch on at least @strong{i386} and @strong{amd64} +(cf. @ref{Regression tests}). + @item - Prepare the release tarballs in @code{bz2} and @code{gz} formats, and - supplementing files that contain @code{gpg} signatures +Prepare the release tarballs in @code{bz2} and @code{gz} formats, and +supplementing files that contain @code{gpg} signatures + @item - Publish the tarballs at @url{http://ffmpeg.org/releases}. Create and - push an annotated tag in the form @code{nX}, with @code{X} - containing the version number. +Publish the tarballs at @url{http://ffmpeg.org/releases}. Create and +push an annotated tag in the form @code{nX}, with @code{X} +containing the version number. + @item - Propose and send a patch to the @strong{ffmpeg-devel} mailing list - with a news entry for the website. +Propose and send a patch to the @strong{ffmpeg-devel} mailing list +with a news entry for the website. + @item - Publish the news entry. +Publish the news entry. + @item - Send announcement to the mailing list. +Send announcement to the mailing list. @end enumerate @bye diff --git a/ffmpeg/doc/doxy-wrapper.sh b/ffmpeg/doc/doxy-wrapper.sh index 6650e38..a6c54dd 100755 --- a/ffmpeg/doc/doxy-wrapper.sh +++ b/ffmpeg/doc/doxy-wrapper.sh @@ -8,7 +8,4 @@ shift 2 doxygen - <<EOF @INCLUDE = ${DOXYFILE} INPUT = $@ -HTML_HEADER = ${SRC_PATH}/doc/doxy/header.html -HTML_FOOTER = ${SRC_PATH}/doc/doxy/footer.html -HTML_STYLESHEET = ${SRC_PATH}/doc/doxy/doxy_stylesheet.css EOF diff --git a/ffmpeg/doc/doxy/doxy_stylesheet.css b/ffmpeg/doc/doxy/doxy_stylesheet.css index 63238a2..d6dadde 100644 --- a/ffmpeg/doc/doxy/doxy_stylesheet.css +++ b/ffmpeg/doc/doxy/doxy_stylesheet.css @@ -214,6 +214,10 @@ code { background-color: #f7f7f9; border: 1px solid #e1e1e8; } +.fragment .line { + padding-left: 2em; + white-space: pre; +} pre { display: block; padding: 9.5px; @@ -222,7 +226,6 @@ pre { line-height: 20px; word-break: break-all; word-wrap: break-word; - white-space: pre; white-space: pre-wrap; background-color: #f5f5f5; border: 1px solid #ccc; @@ -260,6 +263,10 @@ pre code { -moz-border-radius: 9px; border-radius: 9px; } + +.label a { + color:#ffffff; +} a.label:hover, a.badge:hover { color: #ffffff; @@ -1514,7 +1521,6 @@ table.memberdecls { -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); -webkit-border-top-right-radius: 8px; -webkit-border-top-left-radius: 8px; - background-image:url('nav_f.png'); background-repeat:repeat-x; background-color: #E2F2E2; @@ -1745,7 +1751,6 @@ table.fieldtable { } .fieldtable th { - background-image:url('nav_f.png'); background-repeat:repeat-x; background-color: #E2F2E2; font-size: 90%; @@ -1767,7 +1772,6 @@ table.fieldtable { top: 0px; left: 10px; height: 36px; - background-image: url('tab_b.png'); z-index: 101; overflow: hidden; font-size: 13px; @@ -1776,7 +1780,6 @@ table.fieldtable { .tablistpath ul { font-size: 11px; - background-image:url('tab_b.png'); background-repeat:repeat-x; height:30px; line-height:30px; @@ -1793,7 +1796,6 @@ table.fieldtable { float:left; padding-left:10px; padding-right:15px; - background-image:url('bc_s.png'); background-repeat:no-repeat; background-position:right; color:#367C36; diff --git a/ffmpeg/doc/encoders.texi b/ffmpeg/doc/encoders.texi index 07343eb..ea5b3e4 100644 --- a/ffmpeg/doc/encoders.texi +++ b/ffmpeg/doc/encoders.texi @@ -25,6 +25,88 @@ enabled encoders. A description of some of the currently available audio encoders follows. +@anchor{aacenc} +@section aac + +Advanced Audio Coding (AAC) encoder. + +This encoder is an experimental FFmpeg-native AAC encoder. Currently only the +low complexity (AAC-LC) profile is supported. To use this encoder, you must set +@option{strict} option to @samp{experimental} or lower. + +As this encoder is experimental, unexpected behavior may exist from time to +time. For a more stable AAC encoder, see @ref{libvo-aacenc}. However, be warned +that it has a worse quality reported by some users. + +@c todo @ref{libaacplus} +See also @ref{libfdk-aac-enc,,libfdk_aac} and @ref{libfaac}. + +@subsection Options + +@table @option +@item b +Set bit rate in bits/s. Setting this automatically activates constant bit rate +(CBR) mode. + +@item q +Set quality for variable bit rate (VBR) mode. This option is valid only using +the @command{ffmpeg} command-line tool. For library interface users, use +@option{global_quality}. + +@item stereo_mode +Set stereo encoding mode. Possible values: + +@table @samp +@item auto +Automatically selected by the encoder. + +@item ms_off +Disable middle/side encoding. This is the default. + +@item ms_force +Force middle/side encoding. +@end table + +@item aac_coder +Set AAC encoder coding method. Possible values: + +@table @samp +@item faac +FAAC-inspired method. + +This method is a simplified reimplementation of the method used in FAAC, which +sets thresholds proportional to the band energies, and then decreases all the +thresholds with quantizer steps to find the appropriate quantization with +distortion below threshold band by band. + +The quality of this method is comparable to the two loop searching method +descibed below, but somewhat a little better and slower. + +@item anmr +Average noise to mask ratio (ANMR) trellis-based solution. + +This has a theoretic best quality out of all the coding methods, but at the +cost of the slowest speed. + +@item twoloop +Two loop searching (TLS) method. + +This method first sets quantizers depending on band thresholds and then tries +to find an optimal combination by adding or subtracting a specific value from +all quantizers and adjusting some individual quantizer a little. + +This method produces similar quality with the FAAC method and is the default. + +@item fast +Constant quantizer method. + +This method sets a constant quantizer for all bands. This is the fastest of all +the methods, yet produces the worst quality. + +@end table + +@end table + @section ac3 and ac3_fixed AC-3 audio encoders. @@ -412,6 +494,685 @@ Selected by Encoder (default) @end table +@anchor{libfaac} +@section libfaac + +libfaac AAC (Advanced Audio Coding) encoder wrapper. + +Requires the presence of the libfaac headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libfaac --enable-nonfree}. + +This encoder is considered to be of higher quality with respect to the +@ref{aacenc,,the native experimental FFmpeg AAC encoder}. + +For more information see the libfaac project at +@url{http://www.audiocoding.com/faac.html/}. + +@subsection Options + +The following shared FFmpeg codec options are recognized. + +The following options are supported by the libfaac wrapper. The +@command{faac}-equivalent of the options are listed in parentheses. + +@table @option +@item b (@emph{-b}) +Set bit rate in bits/s for ABR (Average Bit Rate) mode. If the bit rate +is not explicitly specified, it is automatically set to a suitable +value depending on the selected profile. @command{faac} bitrate is +expressed in kilobits/s. + +Note that libfaac does not support CBR (Constant Bit Rate) but only +ABR (Average Bit Rate). + +If VBR mode is enabled this option is ignored. + +@item ar (@emph{-R}) +Set audio sampling rate (in Hz). + +@item ac (@emph{-c}) +Set the number of audio channels. + +@item cutoff (@emph{-C}) +Set cutoff frequency. If not specified (or explicitly set to 0) it +will use a value automatically computed by the library. Default value +is 0. + +@item profile +Set audio profile. + +The following profiles are recognized: +@table @samp +@item aac_main +Main AAC (Main) + +@item aac_low +Low Complexity AAC (LC) + +@item aac_ssr +Scalable Sample Rate (SSR) + +@item aac_ltp +Long Term Prediction (LTP) +@end table + +If not specified it is set to @samp{aac_low}. + +@item flags +qscale +Set constant quality VBR (Variable Bit Rate) mode. + +@item global_quality +Set quality in VBR mode as an integer number of lambda units. + +Only relevant when VBR mode is enabled with @code{flags +qscale}. The +value is converted to QP units by dividing it by @code{FF_QP2LAMBDA}, +and used to set the quality value used by libfaac. A reasonable range +for the option value in QP units is [10-500], the higher the value the +higher the quality. + +@item q (@emph{-q}) +Enable VBR mode when set to a non-negative value, and set constant +quality value as a double floating point value in QP units. + +The value sets the quality value used by libfaac. A reasonable range +for the option value is [10-500], the higher the value the higher the +quality. + +This option is valid only using the @command{ffmpeg} command-line +tool. For library interface users, use @option{global_quality}. +@end table + +@subsection Examples + +@itemize +@item +Use @command{ffmpeg} to convert an audio file to ABR 128 kbps AAC in an M4A (MP4) +container: +@example +ffmpeg -i input.wav -codec:a libfaac -b:a 128k -output.m4a +@end example + +@item +Use @command{ffmpeg} to convert an audio file to VBR AAC, using the +LTP AAC profile: +@example +ffmpeg -i input.wav -c:a libfaac -profile:a aac_ltp -q:a 100 output.m4a +@end example +@end itemize + +@anchor{libfdk-aac-enc} +@section libfdk_aac + +libfdk-aac AAC (Advanced Audio Coding) encoder wrapper. + +The libfdk-aac library is based on the Fraunhofer FDK AAC code from +the Android project. + +Requires the presence of the libfdk-aac headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libfdk-aac}. The library is also incompatible with GPL, +so if you allow the use of GPL, you should configure with +@code{--enable-gpl --enable-nonfree --enable-libfdk-aac}. + +This encoder is considered to be of higher quality with respect to +both @ref{aacenc,,the native experimental FFmpeg AAC encoder} and +@ref{libfaac}. + +VBR encoding, enabled through the @option{vbr} or @option{flags ++qscale} options, is experimental and only works with some +combinations of parameters. + +For more information see the fdk-aac project at +@url{http://sourceforge.net/p/opencore-amr/fdk-aac/}. + +@subsection Options + +The following options are mapped on the shared FFmpeg codec options. + +@table @option +@item b +Set bit rate in bits/s. If the bitrate is not explicitly specified, it +is automatically set to a suitable value depending on the selected +profile. + +In case VBR mode is enabled the option is ignored. + +@item ar +Set audio sampling rate (in Hz). + +@item channels +Set the number of audio channels. + +@item flags +qscale +Enable fixed quality, VBR (Variable Bit Rate) mode. +Note that VBR is implicitly enabled when the @option{vbr} value is +positive. + +@item cutoff +Set cutoff frequency. If not specified (or explicitly set to 0) it +will use a value automatically computed by the library. Default value +is 0. + +@item profile +Set audio profile. + +The following profiles are recognized: +@table @samp +@item aac_low +Low Complexity AAC (LC) + +@item aac_he +High Efficiency AAC (HE-AAC) + +@item aac_he_v2 +High Efficiency AAC version 2 (HE-AACv2) + +@item aac_ld +Low Delay AAC (LD) + +@item aac_eld +Enhanced Low Delay AAC (ELD) +@end table + +If not specified it is set to @samp{aac_low}. +@end table + +The following are private options of the libfdk_aac encoder. + +@table @option +@item afterburner +Enable afterburner feature if set to 1, disabled if set to 0. This +improves the quality but also the required processing power. + +Default value is 1. + +@item eld_sbr +Enable SBR (Spectral Band Replication) for ELD if set to 1, disabled +if set to 0. + +Default value is 0. + +@item signaling +Set SBR/PS signaling style. + +It can assume one of the following values: +@table @samp +@item default +choose signaling implicitly (explicit hierarchical by default, +implicit if global header is disabled) + +@item implicit +implicit backwards compatible signaling + +@item explicit_sbr +explicit SBR, implicit PS signaling + +@item explicit_hierarchical +explicit hierarchical signaling +@end table + +Default value is @samp{default}. + +@item latm +Output LATM/LOAS encapsulated data if set to 1, disabled if set to 0. + +Default value is 0. + +@item header_period +Set StreamMuxConfig and PCE repetition period (in frames) for sending +in-band configuration buffers within LATM/LOAS transport layer. + +Must be a 16-bits non-negative integer. + +Default value is 0. + +@item vbr +Set VBR mode, from 1 to 5. 1 is lowest quality (though still pretty +good) and 5 is highest quality. A value of 0 will disable VBR, and CBR +(Constant Bit Rate) is enabled. + +Currently only the @samp{aac_low} profile supports VBR encoding. + +VBR modes 1-5 correspond to roughly the following average bit rates: + +@table @samp +@item 1 +32 kbps/channel +@item 2 +40 kbps/channel +@item 3 +48-56 kbps/channel +@item 4 +64 kbps/channel +@item 5 +about 80-96 kbps/channel +@end table + +Default value is 0. +@end table + +@subsection Examples + +@itemize +@item +Use @command{ffmpeg} to convert an audio file to VBR AAC in an M4A (MP4) +container: +@example +ffmpeg -i input.wav -codec:a libfdk_aac -vbr 3 output.m4a +@end example + +@item +Use @command{ffmpeg} to convert an audio file to CBR 64k kbps AAC, using the +High-Efficiency AAC profile: +@example +ffmpeg -i input.wav -c:a libfdk_aac -profile:a aac_he -b:a 64k output.m4a +@end example +@end itemize + +@anchor{libmp3lame} +@section libmp3lame + +LAME (Lame Ain't an MP3 Encoder) MP3 encoder wrapper. + +Requires the presence of the libmp3lame headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libmp3lame}. + +See @ref{libshine} for a fixed-point MP3 encoder, although with a +lower quality. + +@subsection Options + +The following options are supported by the libmp3lame wrapper. The +@command{lame}-equivalent of the options are listed in parentheses. + +@table @option +@item b (@emph{-b}) +Set bitrate expressed in bits/s for CBR or ABR. LAME @code{bitrate} is +expressed in kilobits/s. + +@item q (@emph{-V}) +Set constant quality setting for VBR. This option is valid only +using the @command{ffmpeg} command-line tool. For library interface +users, use @option{global_quality}. + +@item compression_level (@emph{-q}) +Set algorithm quality. Valid arguments are integers in the 0-9 range, +with 0 meaning highest quality but slowest, and 9 meaning fastest +while producing the worst quality. + +@item reservoir +Enable use of bit reservoir when set to 1. Default value is 1. LAME +has this enabled by default, but can be overriden by use +@option{--nores} option. + +@item joint_stereo (@emph{-m j}) +Enable the encoder to use (on a frame by frame basis) either L/R +stereo or mid/side stereo. Default value is 1. + +@item abr (@emph{--abr}) +Enable the encoder to use ABR when set to 1. The @command{lame} +@option{--abr} sets the target bitrate, while this options only +tells FFmpeg to use ABR still relies on @option{b} to set bitrate. + +@end table + +@section libopencore-amrnb + +OpenCORE Adaptive Multi-Rate Narrowband encoder. + +Requires the presence of the libopencore-amrnb headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libopencore-amrnb --enable-version3}. + +This is a mono-only encoder. Officially it only supports 8000Hz sample rate, +but you can override it by setting @option{strict} to @samp{unofficial} or +lower. + +@subsection Options + +@table @option + +@item b +Set bitrate in bits per second. Only the following bitrates are supported, +otherwise libavcodec will round to the nearest valid bitrate. + +@table @option +@item 4750 +@item 5150 +@item 5900 +@item 6700 +@item 7400 +@item 7950 +@item 10200 +@item 12200 +@end table + +@item dtx +Allow discontinuous transmission (generate comfort noise) when set to 1. The +default value is 0 (disabled). + +@end table + +@anchor{libshine} +@section libshine + +Shine Fixed-Point MP3 encoder wrapper. + +Shine is a fixed-point MP3 encoder. It has a far better performance on +platforms without an FPU, e.g. armel CPUs, and some phones and tablets. +However, as it is more targeted on performance than quality, it is not on par +with LAME and other production-grade encoders quality-wise. Also, according to +the project's homepage, this encoder may not be free of bugs as the code was +written a long time ago and the project was dead for at least 5 years. + +This encoder only supports stereo and mono input. This is also CBR-only. + +The original project (last updated in early 2007) is at +@url{http://sourceforge.net/projects/libshine-fxp/}. We only support the +updated fork by the Savonet/Liquidsoap project at @url{https://github.com/savonet/shine}. + +Requires the presence of the libshine headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libshine}. + +See also @ref{libmp3lame}. + +@subsection Options + +The following options are supported by the libshine wrapper. The +@command{shineenc}-equivalent of the options are listed in parentheses. + +@table @option +@item b (@emph{-b}) +Set bitrate expressed in bits/s for CBR. @command{shineenc} @option{-b} option +is expressed in kilobits/s. + +@end table + +@section libtwolame + +TwoLAME MP2 encoder wrapper. + +Requires the presence of the libtwolame headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libtwolame}. + +@subsection Options + +The following options are supported by the libtwolame wrapper. The +@command{twolame}-equivalent options follow the FFmpeg ones and are in +parentheses. + +@table @option +@item b (@emph{-b}) +Set bitrate expressed in bits/s for CBR. @command{twolame} @option{b} +option is expressed in kilobits/s. Default value is 128k. + +@item q (@emph{-V}) +Set quality for experimental VBR support. Maximum value range is +from -50 to 50, useful range is from -10 to 10. The higher the +value, the better the quality. This option is valid only using the +@command{ffmpeg} command-line tool. For library interface users, +use @option{global_quality}. + +@item mode (@emph{--mode}) +Set the mode of the resulting audio. Possible values: + +@table @samp +@item auto +Choose mode automatically based on the input. This is the default. +@item stereo +Stereo +@item joint_stereo +Joint stereo +@item dual_channel +Dual channel +@item mono +Mono +@end table + +@item psymodel (@emph{--psyc-mode}) +Set psychoacoustic model to use in encoding. The argument must be +an integer between -1 and 4, inclusive. The higher the value, the +better the quality. The default value is 3. + +@item energy_levels (@emph{--energy}) +Enable energy levels extensions when set to 1. The default value is +0 (disabled). + +@item error_protection (@emph{--protect}) +Enable CRC error protection when set to 1. The default value is 0 +(disabled). + +@item copyright (@emph{--copyright}) +Set MPEG audio copyright flag when set to 1. The default value is 0 +(disabled). + +@item original (@emph{--original}) +Set MPEG audio original flag when set to 1. The default value is 0 +(disabled). + +@end table + +@anchor{libvo-aacenc} +@section libvo-aacenc + +VisualOn AAC encoder. + +Requires the presence of the libvo-aacenc headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libvo-aacenc --enable-version3}. + +This encoder is considered to be worse than the +@ref{aacenc,,native experimental FFmpeg AAC encoder}, according to +multiple sources. + +@subsection Options + +The VisualOn AAC encoder only support encoding AAC-LC and up to 2 +channels. It is also CBR-only. + +@table @option + +@item b +Set bit rate in bits/s. + +@end table + +@section libvo-amrwbenc + +VisualOn Adaptive Multi-Rate Wideband encoder. + +Requires the presence of the libvo-amrwbenc headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libvo-amrwbenc --enable-version3}. + +This is a mono-only encoder. Officially it only supports 16000Hz sample +rate, but you can override it by setting @option{strict} to +@samp{unofficial} or lower. + +@subsection Options + +@table @option + +@item b +Set bitrate in bits/s. Only the following bitrates are supported, otherwise +libavcodec will round to the nearest valid bitrate. + +@table @samp +@item 6600 +@item 8850 +@item 12650 +@item 14250 +@item 15850 +@item 18250 +@item 19850 +@item 23050 +@item 23850 +@end table + +@item dtx +Allow discontinuous transmission (generate comfort noise) when set to 1. The +default value is 0 (disabled). + +@end table + +@section libopus + +libopus Opus Interactive Audio Codec encoder wrapper. + +Requires the presence of the libopus headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libopus}. + +@subsection Option Mapping + +Most libopus options are modeled after the @command{opusenc} utility from +opus-tools. The following is an option mapping chart describing options +supported by the libopus wrapper, and their @command{opusenc}-equivalent +in parentheses. + +@table @option + +@item b (@emph{bitrate}) +Set the bit rate in bits/s. FFmpeg's @option{b} option is +expressed in bits/s, while @command{opusenc}'s @option{bitrate} in +kilobits/s. + +@item vbr (@emph{vbr}, @emph{hard-cbr}, and @emph{cvbr}) +Set VBR mode. The FFmpeg @option{vbr} option has the following +valid arguments, with the their @command{opusenc} equivalent options +in parentheses: + +@table @samp +@item off (@emph{hard-cbr}) +Use constant bit rate encoding. + +@item on (@emph{vbr}) +Use variable bit rate encoding (the default). + +@item constrained (@emph{cvbr}) +Use constrained variable bit rate encoding. +@end table + +@item compression_level (@emph{comp}) +Set encoding algorithm complexity. Valid options are integers in +the 0-10 range. 0 gives the fastest encodes but lower quality, while 10 +gives the highest quality but slowest encoding. The default is 10. + +@item frame_duration (@emph{framesize}) +Set maximum frame size, or duration of a frame in milliseconds. The +argument must be exactly the following: 2.5, 5, 10, 20, 40, 60. Smaller +frame sizes achieve lower latency but less quality at a given bitrate. +Sizes greater than 20ms are only interesting at fairly low bitrates. +The default is 20ms. + +@item packet_loss (@emph{expect-loss}) +Set expected packet loss percentage. The default is 0. + +@item application (N.A.) +Set intended application type. Valid options are listed below: + +@table @samp +@item voip +Favor improved speech intelligibility. +@item audio +Favor faithfulness to the input (the default). +@item lowdelay +Restrict to only the lowest delay modes. +@end table + +@item cutoff (N.A.) +Set cutoff bandwidth in Hz. The argument must be exactly one of the +following: 4000, 6000, 8000, 12000, or 20000, corresponding to +narrowband, mediumband, wideband, super wideband, and fullband +respectively. The default is 0 (cutoff disabled). + +@end table + +@section libvorbis + +libvorbis encoder wrapper. + +Requires the presence of the libvorbisenc headers and library during +configuration. You need to explicitly configure the build with +@code{--enable-libvorbis}. + +@subsection Options + +The following options are supported by the libvorbis wrapper. The +@command{oggenc}-equivalent of the options are listed in parentheses. + +To get a more accurate and extensive documentation of the libvorbis +options, consult the libvorbisenc's and @command{oggenc}'s documentations. +See @url{http://xiph.org/vorbis/}, +@url{http://wiki.xiph.org/Vorbis-tools}, and oggenc(1). + +@table @option +@item b (@emph{-b}) +Set bitrate expressed in bits/s for ABR. @command{oggenc} @option{-b} is +expressed in kilobits/s. + +@item q (@emph{-q}) +Set constant quality setting for VBR. The value should be a float +number in the range of -1.0 to 10.0. The higher the value, the better +the quality. The default value is @samp{3.0}. + +This option is valid only using the @command{ffmpeg} command-line tool. +For library interface users, use @option{global_quality}. + +@item cutoff (@emph{--advanced-encode-option lowpass_frequency=N}) +Set cutoff bandwidth in Hz, a value of 0 disables cutoff. @command{oggenc}'s +related option is expressed in kHz. The default value is @samp{0} (cutoff +disabled). + +@item minrate (@emph{-m}) +Set minimum bitrate expressed in bits/s. @command{oggenc} @option{-m} is +expressed in kilobits/s. + +@item maxrate (@emph{-M}) +Set maximum bitrate expressed in bits/s. @command{oggenc} @option{-M} is +expressed in kilobits/s. This only has effect on ABR mode. + +@item iblock (@emph{--advanced-encode-option impulse_noisetune=N}) +Set noise floor bias for impulse blocks. The value is a float number from +-15.0 to 0.0. A negative bias instructs the encoder to pay special attention +to the crispness of transients in the encoded audio. The tradeoff for better +transient response is a higher bitrate. + +@end table + +@section libwavpack + +A wrapper providing WavPack encoding through libwavpack. + +Only lossless mode using 32-bit integer samples is supported currently. +The @option{compression_level} option can be used to control speed vs. +compression tradeoff, with the values mapped to libwavpack as follows: + +@table @option + +@item 0 +Fast mode - corresponding to the wavpack @option{-f} option. + +@item 1 +Normal (default) settings. + +@item 2 +High quality - corresponding to the wavpack @option{-h} option. + +@item 3 +Very high quality - corresponding to the wavpack @option{-hh} option. + +@item 4-8 +Same as 3, but with extra processing enabled - corresponding to the wavpack +@option{-x} option. I.e. 4 is the same as @option{-x2} and 8 is the same as +@option{-x6}. + +@end table + @c man end AUDIO ENCODERS @chapter Video Encoders @@ -422,12 +1183,15 @@ follows. @section libtheora -Theora format supported through libtheora. +libtheora Theora encoder wrapper. Requires the presence of the libtheora headers and library during configuration. You need to explicitly configure the build with @code{--enable-libtheora}. +For more informations about the libtheora project see +@url{http://www.theora.org/}. + @subsection Options The following global options are mapped to internal libtheora options @@ -435,11 +1199,11 @@ which affect the quality and the bitrate of the encoded stream. @table @option @item b -Set the video bitrate, only works if the @code{qscale} flag in -@option{flags} is not enabled. +Set the video bitrate in bit/s for CBR (Constant Bit Rate) mode. In +case VBR (Variable Bit Rate) mode is enabled this option is ignored. @item flags -Used to enable constant quality mode encoding through the +Used to enable constant quality mode (VBR) encoding through the @option{qscale} flag, and to enable the @code{pass1} and @code{pass2} modes. @@ -447,18 +1211,40 @@ modes. Set the GOP size. @item global_quality -Set the global quality in lambda units, only works if the -@code{qscale} flag in @option{flags} is enabled. The value is clipped -in the [0 - 10*@code{FF_QP2LAMBDA}] range, and then multiplied for 6.3 -to get a value in the native libtheora range [0-63]. A higher value -corresponds to a higher quality. - -For example, to set maximum constant quality encoding with -@command{ffmpeg}: +Set the global quality as an integer in lambda units. + +Only relevant when VBR mode is enabled with @code{flags +qscale}. The +value is converted to QP units by dividing it by @code{FF_QP2LAMBDA}, +clipped in the [0 - 10] range, and then multiplied by 6.3 to get a +value in the native libtheora range [0-63]. A higher value corresponds +to a higher quality. + +@item q +Enable VBR mode when set to a non-negative value, and set constant +quality value as a double floating point value in QP units. + +The value is clipped in the [0-10] range, and then multiplied by 6.3 +to get a value in the native libtheora range [0-63]. + +This option is valid only using the @command{ffmpeg} command-line +tool. For library interface users, use @option{global_quality}. +@end table + +@subsection Examples + +@itemize +@item +Set maximum constant quality (VBR) encoding with @command{ffmpeg}: @example -ffmpeg -i INPUT -flags:v qscale -global_quality:v "10*QP2LAMBDA" -codec:v libtheora OUTPUT.ogg +ffmpeg -i INPUT -codec:v libtheora -q:v 10 OUTPUT.ogg @end example -@end table + +@item +Use @command{ffmpeg} to convert a CBR 1000 kbps Theora video stream: +@example +ffmpeg -i INPUT -codec:v libtheora -b:v 1000k OUTPUT.ogg +@end example +@end itemize @section libvpx @@ -579,182 +1365,388 @@ g_error_resilient For more information about libvpx see: @url{http://www.webmproject.org/} + +@section libwebp + +libwebp WebP Image encoder wrapper + +libwebp is Google's official encoder for WebP images. It can encode in either +lossy or lossless mode. Lossy images are essentially a wrapper around a VP8 +frame. Lossless images are a separate codec developed by Google. + +@subsection Pixel Format + +Currently, libwebp only supports YUV420 for lossy and RGB for lossless due +to limitations of the format and libwebp. Alpha is supported for either mode. +Because of API limitations, if RGB is passed in when encoding lossy or YUV is +passed in for encoding lossless, the pixel format will automatically be +converted using functions from libwebp. This is not ideal and is done only for +convenience. + +@subsection Options + +@table @option + +@item -lossless @var{boolean} +Enables/Disables use of lossless mode. Default is 0. + +@item -compression_level @var{integer} +For lossy, this is a quality/speed tradeoff. Higher values give better quality +for a given size at the cost of increased encoding time. For lossless, this is +a size/speed tradeoff. Higher values give smaller size at the cost of increased +encoding time. More specifically, it controls the number of extra algorithms +and compression tools used, and varies the combination of these tools. This +maps to the @var{method} option in libwebp. The valid range is 0 to 6. +Default is 4. + +@item -qscale @var{float} +For lossy encoding, this controls image quality, 0 to 100. For lossless +encoding, this controls the effort and time spent at compressing more. The +default value is 75. Note that for usage via libavcodec, this option is called +@var{global_quality} and must be multiplied by @var{FF_QP2LAMBDA}. + +@item -preset @var{type} +Configuration preset. This does some automatic settings based on the general +type of the image. +@table @option +@item none +Do not use a preset. +@item default +Use the encoder default. +@item picture +Digital picture, like portrait, inner shot +@item photo +Outdoor photograph, with natural lighting +@item drawing +Hand or line drawing, with high-contrast details +@item icon +Small-sized colorful images +@item text +Text-like +@end table + +@end table + @section libx264 -x264 H.264/MPEG-4 AVC encoder wrapper +x264 H.264/MPEG-4 AVC encoder wrapper. -Requires the presence of the libx264 headers and library during -configuration. You need to explicitly configure the build with +This encoder requires the presence of the libx264 headers and library +during configuration. You need to explicitly configure the build with @code{--enable-libx264}. -x264 supports an impressive number of features, including 8x8 and 4x4 adaptive -spatial transform, adaptive B-frame placement, CAVLC/CABAC entropy coding, -interlacing (MBAFF), lossless mode, psy optimizations for detail retention -(adaptive quantization, psy-RD, psy-trellis). +libx264 supports an impressive number of features, including 8x8 and +4x4 adaptive spatial transform, adaptive B-frame placement, CAVLC/CABAC +entropy coding, interlacing (MBAFF), lossless mode, psy optimizations +for detail retention (adaptive quantization, psy-RD, psy-trellis). -The FFmpeg wrapper provides a mapping for most of them using global options -that match those of the encoders and provides private options for the unique -encoder options. Additionally an expert override is provided to directly pass -a list of key=value tuples as accepted by x264_param_parse. +Many libx264 encoder options are mapped to FFmpeg global codec +options, while unique encoder options are provided through private +options. Additionally the @option{x264opts} and @option{x264-params} +private options allows to pass a list of key=value tuples as accepted +by the libx264 @code{x264_param_parse} function. -@subsection Option Mapping +The x264 project website is at +@url{http://www.videolan.org/developers/x264.html}. + +@subsection Options + +The following options are supported by the libx264 wrapper. The +@command{x264}-equivalent options or values are listed in parentheses +for easy migration. + +To reduce the duplication of documentation, only the private options +and some others requiring special attention are documented here. For +the documentation of the undocumented generic options, see +@ref{codec-options,,the Codec Options chapter}. + +To get a more accurate and extensive documentation of the libx264 +options, invoke the command @command{x264 --full-help} or consult +the libx264 documentation. + +@table @option +@item b (@emph{bitrate}) +Set bitrate in bits/s. Note that FFmpeg's @option{b} option is +expressed in bits/s, while @command{x264}'s @option{bitrate} is in +kilobits/s. + +@item bf (@emph{bframes}) + +@item g (@emph{keyint}) + +@item qmax (@emph{qpmax}) + +@item qmin (@emph{qpmin}) + +@item qdiff (@emph{qpstep}) + +@item qblur (@emph{qblur}) + +@item qcomp (@emph{qcomp}) + +@item refs (@emph{ref}) + +@item sc_threshold (@emph{scenecut}) + +@item trellis (@emph{trellis}) + +@item nr (@emph{nr}) + +@item me_range (@emph{merange}) + +@item me_method (@emph{me}) +Set motion estimation method. Possible values in the decreasing order +of speed: + +@table @samp +@item dia (@emph{dia}) +@item epzs (@emph{dia}) +Diamond search with radius 1 (fastest). @samp{epzs} is an alias for +@samp{dia}. +@item hex (@emph{hex}) +Hexagonal search with radius 2. +@item umh (@emph{umh}) +Uneven multi-hexagon search. +@item esa (@emph{esa}) +Exhaustive search. +@item tesa (@emph{tesa}) +Hadamard exhaustive search (slowest). +@end table + +@item subq (@emph{subme}) -The following options are supported by the x264 wrapper, the x264-equivalent -options follow the FFmpeg ones. - -@multitable @columnfractions .2 .2 -@item b @tab bitrate -FFmpeg @code{b} option is expressed in bits/s, x264 @code{bitrate} in kilobits/s. -@item bf @tab bframes -Maximum number of B-frames. -@item g @tab keyint -Maximum GOP size. -@item qmin @tab qpmin -@item qmax @tab qpmax -@item qdiff @tab qpstep -@item qblur @tab qblur -@item qcomp @tab qcomp -@item refs @tab ref -@item sc_threshold @tab scenecut -@item trellis @tab trellis -@item nr @tab nr -Noise reduction. -@item me_range @tab merange -@item me_method @tab me -@item subq @tab subme -@item b_strategy @tab b-adapt -@item keyint_min @tab keyint-min -@item coder @tab cabac -Set coder to @code{ac} to use CABAC. -@item cmp @tab chroma-me -Set to @code{chroma} to use chroma motion estimation. -@item threads @tab threads -@item thread_type @tab sliced_threads -Set to @code{slice} to use sliced threading instead of frame threading. -@item flags -cgop @tab open-gop -Set @code{-cgop} to use recovery points to close GOPs. -@item rc_init_occupancy @tab vbv-init -Initial buffer occupancy. -@end multitable - -@subsection Private Options -@table @option -@item -preset @var{string} -Set the encoding preset (cf. x264 --fullhelp). -@item -tune @var{string} -Tune the encoding params (cf. x264 --fullhelp). -@item -profile @var{string} -Set profile restrictions (cf. x264 --fullhelp). -@item -fastfirstpass @var{integer} -Use fast settings when encoding first pass. -@item -crf @var{float} -Select the quality for constant quality mode. -@item -crf_max @var{float} +@item b_strategy (@emph{b-adapt}) + +@item keyint_min (@emph{min-keyint}) + +@item coder +Set entropy encoder. Possible values: + +@table @samp +@item ac +Enable CABAC. + +@item vlc +Enable CAVLC and disable CABAC. It generates the same effect as +@command{x264}'s @option{--no-cabac} option. +@end table + +@item cmp +Set full pixel motion estimation comparation algorithm. Possible values: + +@table @samp +@item chroma +Enable chroma in motion estimation. + +@item sad +Ignore chroma in motion estimation. It generates the same effect as +@command{x264}'s @option{--no-chroma-me} option. +@end table + +@item threads (@emph{threads}) + +@item thread_type +Set multithreading technique. Possible values: + +@table @samp +@item slice +Slice-based multithreading. It generates the same effect as +@command{x264}'s @option{--sliced-threads} option. +@item frame +Frame-based multithreading. +@end table + +@item flags +Set encoding flags. It can be used to disable closed GOP and enable +open GOP by setting it to @code{-cgop}. The result is similar to +the behavior of @command{x264}'s @option{--open-gop} option. + +@item rc_init_occupancy (@emph{vbv-init}) + +@item preset (@emph{preset}) +Set the encoding preset. + +@item tune (@emph{tune}) +Set tuning of the encoding params. + +@item profile (@emph{profile}) +Set profile restrictions. + +@item fastfirstpass +Enable fast settings when encoding first pass, when set to 1. When set +to 0, it has the same effect of @command{x264}'s +@option{--slow-firstpass} option. + +@item crf (@emph{crf}) +Set the quality for constant quality mode. + +@item crf_max (@emph{crf-max}) In CRF mode, prevents VBV from lowering quality beyond this point. -@item -qp @var{integer} -Constant quantization parameter rate control method. -@item -aq-mode @var{integer} -AQ method -Possible values: +@item qp (@emph{qp}) +Set constant quantization rate control method parameter. + +@item aq-mode (@emph{aq-mode}) +Set AQ method. Possible values: + @table @samp -@item none +@item none (@emph{0}) +Disabled. -@item variance +@item variance (@emph{1}) Variance AQ (complexity mask). -@item autovariance + +@item autovariance (@emph{2}) Auto-variance AQ (experimental). @end table -@item -aq-strength @var{float} -AQ strength, reduces blocking and blurring in flat and textured areas. -@item -psy @var{integer} -Use psychovisual optimizations. -@item -psy-rd @var{string} -Strength of psychovisual optimization, in <psy-rd>:<psy-trellis> format. -@item -rc-lookahead @var{integer} -Number of frames to look ahead for frametype and ratecontrol. -@item -weightb @var{integer} -Weighted prediction for B-frames. -@item -weightp @var{integer} -Weighted prediction analysis method. -Possible values: -@table @samp -@item none +@item aq-strength (@emph{aq-strength}) +Set AQ strength, reduce blocking and blurring in flat and textured areas. -@item simple +@item psy +Use psychovisual optimizations when set to 1. When set to 0, it has the +same effect as @command{x264}'s @option{--no-psy} option. -@item smart +@item psy-rd (@emph{psy-rd}) +Set strength of psychovisual optimization, in +@var{psy-rd}:@var{psy-trellis} format. -@end table -@item -ssim @var{integer} -Calculate and print SSIM stats. -@item -intra-refresh @var{integer} -Use Periodic Intra Refresh instead of IDR frames. -@item -b-bias @var{integer} -Influences how often B-frames are used. -@item -b-pyramid @var{integer} -Keep some B-frames as references. +@item rc-lookahead (@emph{rc-lookahead}) +Set number of frames to look ahead for frametype and ratecontrol. + +@item weightb +Enable weighted prediction for B-frames when set to 1. When set to 0, +it has the same effect as @command{x264}'s @option{--no-weightb} option. + +@item weightp (@emph{weightp}) +Set weighted prediction method for P-frames. Possible values: -Possible values: @table @samp -@item none +@item none (@emph{0}) +Disabled +@item simple (@emph{1}) +Enable only weighted refs +@item smart (@emph{2}) +Enable both weighted refs and duplicates +@end table + +@item ssim (@emph{ssim}) +Enable calculation and printing SSIM stats after the encoding. -@item strict +@item intra-refresh (@emph{intra-refresh}) +Enable the use of Periodic Intra Refresh instead of IDR frames when set +to 1. + +@item bluray-compat (@emph{bluray-compat}) +Configure the encoder to be compatible with the bluray standard. +It is a shorthand for setting "bluray-compat=1 force-cfr=1". + +@item b-bias (@emph{b-bias}) +Set the influence on how often B-frames are used. + +@item b-pyramid (@emph{b-pyramid}) +Set method for keeping of some B-frames as references. Possible values: + +@table @samp +@item none (@emph{none}) +Disabled. +@item strict (@emph{strict}) Strictly hierarchical pyramid. -@item normal +@item normal (@emph{normal}) Non-strict (not Blu-ray compatible). @end table -@item -mixed-refs @var{integer} -One reference per partition, as opposed to one reference per macroblock. -@item -8x8dct @var{integer} -High profile 8x8 transform. -@item -fast-pskip @var{integer} -@item -aud @var{integer} -Use access unit delimiters. -@item -mbtree @var{integer} -Use macroblock tree ratecontrol. -@item -deblock @var{string} -Loop filter parameters, in <alpha:beta> form. -@item -cplxblur @var{float} -Reduce fluctuations in QP (before curve compression). -@item -partitions @var{string} -A comma-separated list of partitions to consider, possible values: p8x8, p4x4, b8x8, i8x8, i4x4, none, all. -@item -direct-pred @var{integer} -Direct MV prediction mode -Possible values: -@table @samp -@item none +@item mixed-refs +Enable the use of one reference per partition, as opposed to one +reference per macroblock when set to 1. When set to 0, it has the +same effect as @command{x264}'s @option{--no-mixed-refs} option. -@item spatial +@item 8x8dct +Enable adaptive spatial transform (high profile 8x8 transform) +when set to 1. When set to 0, it has the same effect as +@command{x264}'s @option{--no-8x8dct} option. -@item temporal +@item fast-pskip +Enable early SKIP detection on P-frames when set to 1. When set +to 0, it has the same effect as @command{x264}'s +@option{--no-fast-pskip} option. -@item auto +@item aud (@emph{aud}) +Enable use of access unit delimiters when set to 1. + +@item mbtree +Enable use macroblock tree ratecontrol when set to 1. When set +to 0, it has the same effect as @command{x264}'s +@option{--no-mbtree} option. + +@item deblock (@emph{deblock}) +Set loop filter parameters, in @var{alpha}:@var{beta} form. + +@item cplxblur (@emph{cplxblur}) +Set fluctuations reduction in QP (before curve compression). +@item partitions (@emph{partitions}) +Set partitions to consider as a comma-separated list of. Possible +values in the list: + +@table @samp +@item p8x8 +8x8 P-frame partition. +@item p4x4 +4x4 P-frame partition. +@item b8x8 +4x4 B-frame partition. +@item i8x8 +8x8 I-frame partition. +@item i4x4 +4x4 I-frame partition. +(Enabling @samp{p4x4} requires @samp{p8x8} to be enabled. Enabling +@samp{i8x8} requires adaptive spatial transform (@option{8x8dct} +option) to be enabled.) +@item none (@emph{none}) +Do not consider any partitions. +@item all (@emph{all}) +Consider every partition. @end table -@item -slice-max-size @var{integer} -Limit the size of each slice in bytes. -@item -stats @var{string} -Filename for 2 pass stats. -@item -nal-hrd @var{integer} -Signal HRD information (requires vbv-bufsize; cbr not allowed in .mp4). -Possible values: +@item direct-pred (@emph{direct}) +Set direct MV prediction mode. Possible values: + @table @samp -@item none +@item none (@emph{none}) +Disable MV prediction. +@item spatial (@emph{spatial}) +Enable spatial predicting. +@item temporal (@emph{temporal}) +Enable temporal predicting. +@item auto (@emph{auto}) +Automatically decided. +@end table -@item vbr +@item slice-max-size (@emph{slice-max-size}) +Set the limit of the size of each slice in bytes. If not specified +but RTP payload size (@option{ps}) is specified, that is used. + +@item stats (@emph{stats}) +Set the file name for multi-pass stats. -@item cbr +@item nal-hrd (@emph{nal-hrd}) +Set signal HRD information (requires @option{vbv-bufsize} to be set). +Possible values: +@table @samp +@item none (@emph{none}) +Disable HRD information signaling. +@item vbr (@emph{vbr}) +Variable bit rate. +@item cbr (@emph{cbr}) +Constant bit rate (not allowed in MP4 container). @end table -@item x264opts @var{options} -Allow to set any x264 option, see @code{x264 --fullhelp} for a list. +@item x264opts (N.A.) +Set any x264 option, see @command{x264 --fullhelp} for a list. -@var{options} is a list of @var{key}=@var{value} couples separated by +Argument is a list of @var{key}=@var{value} couples separated by ":". In @var{filter} and @var{psy-rd} options that use ":" as a separator themselves, use "," instead. They accept it as well since long ago but this is kept undocumented for some reason. @@ -764,17 +1756,265 @@ For example to specify libx264 encoding options with @command{ffmpeg}: ffmpeg -i foo.mpg -vcodec libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv @end example -For more information about libx264 and the supported options see: -@url{http://www.videolan.org/developers/x264.html} +@item x264-params (N.A.) +Override the x264 configuration using a :-separated list of key=value +parameters. -@item -x264-params @var{string} -Override the x264 configuration using a :-separated list of key=value parameters. +This option is functionally the same as the @option{x264opts}, but is +duplicated for compability with the Libav fork. + +For example to specify libx264 encoding options with @command{ffmpeg}: @example --x264-params level=30:bframes=0:weightp=0:cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:no-fast-pskip=1:subq=6:8x8dct=0:trellis=0 +ffmpeg -i INPUT -c:v libx264 -x264-params level=30:bframes=0:weightp=0:\ +cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:\ +no-fast-pskip=1:subq=6:8x8dct=0:trellis=0 OUTPUT @end example @end table -Encoding avpresets for common usages are provided so they can be used with the -general presets system (e.g. passing the @code{-pre} option). +Encoding ffpresets for common usages are provided so they can be used with the +general presets system (e.g. passing the @option{pre} option). + +@section libxvid + +Xvid MPEG-4 Part 2 encoder wrapper. + +This encoder requires the presence of the libxvidcore headers and library +during configuration. You need to explicitly configure the build with +@code{--enable-libxvid --enable-gpl}. + +The native @code{mpeg4} encoder supports the MPEG-4 Part 2 format, so +users can encode to this format without this library. + +@subsection Options + +The following options are supported by the libxvid wrapper. Some of +the following options are listed but are not documented, and +correspond to shared codec options. See @ref{codec-options,,the Codec +Options chapter} for their documentation. The other shared options +which are not listed have no effect for the libxvid encoder. + +@table @option +@item b + +@item g + +@item qmin + +@item qmax + +@item mpeg_quant + +@item threads + +@item bf + +@item b_qfactor + +@item b_qoffset + +@item flags +Set specific encoding flags. Possible values: + +@table @samp + +@item mv4 +Use four motion vector by macroblock. + +@item aic +Enable high quality AC prediction. + +@item gray +Only encode grayscale. + +@item gmc +Enable the use of global motion compensation (GMC). + +@item qpel +Enable quarter-pixel motion compensation. + +@item cgop +Enable closed GOP. + +@item global_header +Place global headers in extradata instead of every keyframe. + +@end table + +@item trellis + +@item me_method +Set motion estimation method. Possible values in decreasing order of +speed and increasing order of quality: + +@table @samp +@item zero +Use no motion estimation (default). + +@item phods +@item x1 +@item log +Enable advanced diamond zonal search for 16x16 blocks and half-pixel +refinement for 16x16 blocks. @samp{x1} and @samp{log} are aliases for +@samp{phods}. + +@item epzs +Enable all of the things described above, plus advanced diamond zonal +search for 8x8 blocks, half-pixel refinement for 8x8 blocks, and motion +estimation on chroma planes. + +@item full +Enable all of the things described above, plus extended 16x16 and 8x8 +blocks search. +@end table + +@item mbd +Set macroblock decision algorithm. Possible values in the increasing +order of quality: + +@table @samp +@item simple +Use macroblock comparing function algorithm (default). + +@item bits +Enable rate distortion-based half pixel and quarter pixel refinement for +16x16 blocks. + +@item rd +Enable all of the things described above, plus rate distortion-based +half pixel and quarter pixel refinement for 8x8 blocks, and rate +distortion-based search using square pattern. +@end table + +@item lumi_aq +Enable lumi masking adaptive quantization when set to 1. Default is 0 +(disabled). + +@item variance_aq +Enable variance adaptive quantization when set to 1. Default is 0 +(disabled). + +When combined with @option{lumi_aq}, the resulting quality will not +be better than any of the two specified individually. In other +words, the resulting quality will be the worse one of the two +effects. + +@item ssim +Set structural similarity (SSIM) displaying method. Possible values: + +@table @samp +@item off +Disable displaying of SSIM information. + +@item avg +Output average SSIM at the end of encoding to stdout. The format of +showing the average SSIM is: + +@example +Average SSIM: %f +@end example + +For users who are not familiar with C, %f means a float number, or +a decimal (e.g. 0.939232). + +@item frame +Output both per-frame SSIM data during encoding and average SSIM at +the end of encoding to stdout. The format of per-frame information +is: + +@example + SSIM: avg: %1.3f min: %1.3f max: %1.3f +@end example + +For users who are not familiar with C, %1.3f means a float number +rounded to 3 digits after the dot (e.g. 0.932). + +@end table + +@item ssim_acc +Set SSIM accuracy. Valid options are integers within the range of +0-4, while 0 gives the most accurate result and 4 computes the +fastest. + +@end table + +@section png + +PNG image encoder. + +@subsection Private options + +@table @option +@item dpi @var{integer} +Set physical density of pixels, in dots per inch, unset by default +@item dpm @var{integer} +Set physical density of pixels, in dots per meter, unset by default +@end table + +@section ProRes + +Apple ProRes encoder. + +FFmpeg contains 2 ProRes encoders, the prores-aw and prores-ks encoder. +The used encoder can be choosen with the @code{-vcodec} option. + +@subsection Private Options for prores-ks + +@table @option +@item profile @var{integer} +Select the ProRes profile to encode +@table @samp +@item proxy +@item lt +@item standard +@item hq +@item 4444 +@end table + +@item quant_mat @var{integer} +Select quantization matrix. +@table @samp +@item auto +@item default +@item proxy +@item lt +@item standard +@item hq +@end table +If set to @var{auto}, the matrix matching the profile will be picked. +If not set, the matrix providing the highest quality, @var{default}, will be +picked. + +@item bits_per_mb @var{integer} +How many bits to allot for coding one macroblock. Different profiles use +between 200 and 2400 bits per macroblock, the maximum is 8000. + +@item mbs_per_slice @var{integer} +Number of macroblocks in each slice (1-8); the default value (8) +should be good in almost all situations. + +@item vendor @var{string} +Override the 4-byte vendor ID. +A custom vendor ID like @var{apl0} would claim the stream was produced by +the Apple encoder. + +@item alpha_bits @var{integer} +Specify number of bits for alpha component. +Possible values are @var{0}, @var{8} and @var{16}. +Use @var{0} to disable alpha plane coding. + +@end table + +@subsection Speed considerations + +In the default mode of operation the encoder has to honor frame constraints +(i.e. not produc frames with size bigger than requested) while still making +output picture as good as possible. +A frame containing a lot of small details is harder to compress and the encoder +would spend more time searching for appropriate quantizers for each slice. + +Setting a higher @option{bits_per_mb} limit will improve the speed. + +For the fastest encoding speed set the @option{qscale} parameter (4 is the +recommended value) and do not set a size constraint. @c man end VIDEO ENCODERS diff --git a/ffmpeg/doc/eval.texi b/ffmpeg/doc/eval.texi deleted file mode 100644 index e1a5c0a..0000000 --- a/ffmpeg/doc/eval.texi +++ /dev/null @@ -1,299 +0,0 @@ -@chapter Expression Evaluation -@c man begin EXPRESSION EVALUATION - -When evaluating an arithmetic expression, FFmpeg uses an internal -formula evaluator, implemented through the @file{libavutil/eval.h} -interface. - -An expression may contain unary, binary operators, constants, and -functions. - -Two expressions @var{expr1} and @var{expr2} can be combined to form -another expression "@var{expr1};@var{expr2}". -@var{expr1} and @var{expr2} are evaluated in turn, and the new -expression evaluates to the value of @var{expr2}. - -The following binary operators are available: @code{+}, @code{-}, -@code{*}, @code{/}, @code{^}. - -The following unary operators are available: @code{+}, @code{-}. - -The following functions are available: -@table @option -@item abs(x) -Compute absolute value of @var{x}. - -@item acos(x) -Compute arccosine of @var{x}. - -@item asin(x) -Compute arcsine of @var{x}. - -@item atan(x) -Compute arctangent of @var{x}. - -@item bitand(x, y) -@item bitor(x, y) -Compute bitwise and/or operation on @var{x} and @var{y}. - -The results of the evaluation of @var{x} and @var{y} are converted to -integers before executing the bitwise operation. - -Note that both the conversion to integer and the conversion back to -floating point can lose precision. Beware of unexpected results for -large numbers (usually 2^53 and larger). - -@item ceil(expr) -Round the value of expression @var{expr} upwards to the nearest -integer. For example, "ceil(1.5)" is "2.0". - -@item cos(x) -Compute cosine of @var{x}. - -@item cosh(x) -Compute hyperbolic cosine of @var{x}. - -@item eq(x, y) -Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise. - -@item exp(x) -Compute exponential of @var{x} (with base @code{e}, the Euler's number). - -@item floor(expr) -Round the value of expression @var{expr} downwards to the nearest -integer. For example, "floor(-1.5)" is "-2.0". - -@item gauss(x) -Compute Gauss function of @var{x}, corresponding to -@code{exp(-x*x/2) / sqrt(2*PI)}. - -@item gcd(x, y) -Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and -@var{y} are 0 or either or both are less than zero then behavior is undefined. - -@item gt(x, y) -Return 1 if @var{x} is greater than @var{y}, 0 otherwise. - -@item gte(x, y) -Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise. - -@item hypot(x, y) -This function is similar to the C function with the same name; it returns -"sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a -right triangle with sides of length @var{x} and @var{y}, or the distance of the -point (@var{x}, @var{y}) from the origin. - -@item if(x, y) -Evaluate @var{x}, and if the result is non-zero return the result of -the evaluation of @var{y}, return 0 otherwise. - -@item if(x, y, z) -Evaluate @var{x}, and if the result is non-zero return the evaluation -result of @var{y}, otherwise the evaluation result of @var{z}. - -@item ifnot(x, y) -Evaluate @var{x}, and if the result is zero return the result of the -evaluation of @var{y}, return 0 otherwise. - -@item ifnot(x, y, z) -Evaluate @var{x}, and if the result is zero return the evaluation -result of @var{y}, otherwise the evaluation result of @var{z}. - -@item isinf(x) -Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise. - -@item isnan(x) -Return 1.0 if @var{x} is NAN, 0.0 otherwise. - -@item ld(var) -Allow to load the value of the internal variable with number -@var{var}, which was previously stored with st(@var{var}, @var{expr}). -The function returns the loaded value. - -@item log(x) -Compute natural logarithm of @var{x}. - -@item lt(x, y) -Return 1 if @var{x} is lesser than @var{y}, 0 otherwise. - -@item lte(x, y) -Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise. - -@item max(x, y) -Return the maximum between @var{x} and @var{y}. - -@item min(x, y) -Return the maximum between @var{x} and @var{y}. - -@item mod(x, y) -Compute the remainder of division of @var{x} by @var{y}. - -@item not(expr) -Return 1.0 if @var{expr} is zero, 0.0 otherwise. - -@item pow(x, y) -Compute the power of @var{x} elevated @var{y}, it is equivalent to -"(@var{x})^(@var{y})". - -@item print(t) -@item print(t, l) -Print the value of expression @var{t} with loglevel @var{l}. If -@var{l} is not specified then a default log level is used. -Returns the value of the expression printed. - -Prints t with loglevel l - -@item random(x) -Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the -internal variable which will be used to save the seed/state. - -@item root(expr, max) -Find an input value for which the function represented by @var{expr} -with argument @var{ld(0)} is 0 in the interval 0..@var{max}. - -The expression in @var{expr} must denote a continuous function or the -result is undefined. - -@var{ld(0)} is used to represent the function input value, which means -that the given expression will be evaluated multiple times with -various input values that the expression can access through -@code{ld(0)}. When the expression evaluates to 0 then the -corresponding input value will be returned. - -@item sin(x) -Compute sine of @var{x}. - -@item sinh(x) -Compute hyperbolic sine of @var{x}. - -@item sqrt(expr) -Compute the square root of @var{expr}. This is equivalent to -"(@var{expr})^.5". - -@item squish(x) -Compute expression @code{1/(1 + exp(4*x))}. - -@item st(var, expr) -Allow to store the value of the expression @var{expr} in an internal -variable. @var{var} specifies the number of the variable where to -store the value, and it is a value ranging from 0 to 9. The function -returns the value stored in the internal variable. -Note, Variables are currently not shared between expressions. - -@item tan(x) -Compute tangent of @var{x}. - -@item tanh(x) -Compute hyperbolic tangent of @var{x}. - -@item taylor(expr, x) -@item taylor(expr, x, id) -Evaluate a Taylor series at @var{x}, given an expression representing -the @code{ld(id)}-th derivative of a function at 0. - -When the series does not converge the result is undefined. - -@var{ld(id)} is used to represent the derivative order in @var{expr}, -which means that the given expression will be evaluated multiple times -with various input values that the expression can access through -@code{ld(id)}. If @var{id} is not specified then 0 is assumed. - -Note, when you have the derivatives at y instead of 0, -@code{taylor(expr, x-y)} can be used. - -@item time(0) -Return the current (wallclock) time in seconds. - -@item trunc(expr) -Round the value of expression @var{expr} towards zero to the nearest -integer. For example, "trunc(-1.5)" is "-1.0". - -@item while(cond, expr) -Evaluate expression @var{expr} while the expression @var{cond} is -non-zero, and returns the value of the last @var{expr} evaluation, or -NAN if @var{cond} was always false. -@end table - -The following constants are available: -@table @option -@item PI -area of the unit disc, approximately 3.14 -@item E -exp(1) (Euler's number), approximately 2.718 -@item PHI -golden ratio (1+sqrt(5))/2, approximately 1.618 -@end table - -Assuming that an expression is considered "true" if it has a non-zero -value, note that: - -@code{*} works like AND - -@code{+} works like OR - -For example the construct: -@example -if (A AND B) then C -@end example -is equivalent to: -@example -if(A*B, C) -@end example - -In your C code, you can extend the list of unary and binary functions, -and define recognized constants, so that they are available for your -expressions. - -The evaluator also recognizes the International System unit prefixes. -If 'i' is appended after the prefix, binary prefixes are used, which -are based on powers of 1024 instead of powers of 1000. -The 'B' postfix multiplies the value by 8, and can be appended after a -unit prefix or used alone. This allows using for example 'KB', 'MiB', -'G' and 'B' as number postfix. - -The list of available International System prefixes follows, with -indication of the corresponding powers of 10 and of 2. -@table @option -@item y -10^-24 / 2^-80 -@item z -10^-21 / 2^-70 -@item a -10^-18 / 2^-60 -@item f -10^-15 / 2^-50 -@item p -10^-12 / 2^-40 -@item n -10^-9 / 2^-30 -@item u -10^-6 / 2^-20 -@item m -10^-3 / 2^-10 -@item c -10^-2 -@item d -10^-1 -@item h -10^2 -@item k -10^3 / 2^10 -@item K -10^3 / 2^10 -@item M -10^6 / 2^20 -@item G -10^9 / 2^30 -@item T -10^12 / 2^40 -@item P -10^15 / 2^40 -@item E -10^18 / 2^50 -@item Z -10^21 / 2^60 -@item Y -10^24 / 2^70 -@end table - -@c man end diff --git a/ffmpeg/doc/examples/Makefile b/ffmpeg/doc/examples/Makefile index c849daa..f085532 100644 --- a/ffmpeg/doc/examples/Makefile +++ b/ffmpeg/doc/examples/Makefile @@ -7,24 +7,26 @@ FFMPEG_LIBS= libavdevice \ libswscale \ libavutil \ -CFLAGS += -Wall -O2 -g +CFLAGS += -Wall -g CFLAGS := $(shell pkg-config --cflags $(FFMPEG_LIBS)) $(CFLAGS) LDLIBS := $(shell pkg-config --libs $(FFMPEG_LIBS)) $(LDLIBS) EXAMPLES= decoding_encoding \ - demuxing \ + demuxing_decoding \ filtering_video \ filtering_audio \ metadata \ muxing \ resampling_audio \ scaling_video \ + transcode_aac \ OBJS=$(addsuffix .o,$(EXAMPLES)) # the following examples make explicit use of the math library decoding_encoding: LDLIBS += -lm muxing: LDLIBS += -lm +resampling_audio: LDLIBS += -lm .phony: all clean-test clean diff --git a/ffmpeg/doc/examples/README b/ffmpeg/doc/examples/README index a461813..c1ce619 100644 --- a/ffmpeg/doc/examples/README +++ b/ffmpeg/doc/examples/README @@ -5,14 +5,19 @@ Both following use cases rely on pkg-config and make, thus make sure that you have them installed and working on your system. -1) Build the installed examples in a generic read/write user directory +Method 1: build the installed examples in a generic read/write user directory Copy to a read/write user directory and just use "make", it will link to the libraries on your system, assuming the PKG_CONFIG_PATH is correctly configured. -2) Build the examples in-tree +Method 2: build the examples in-tree Assuming you are in the source FFmpeg checkout directory, you need to build -FFmpeg (no need to make install in any prefix). Then you can go into the -doc/examples and run a command such as PKG_CONFIG_PATH=pc-uninstalled make. +FFmpeg (no need to make install in any prefix). Then just run "make examples". +This will build the examples using the FFmpeg build system. You can clean those +examples using "make examplesclean" + +If you want to try the dedicated Makefile examples (to emulate the first +method), go into doc/examples and run a command such as +PKG_CONFIG_PATH=pc-uninstalled make. diff --git a/ffmpeg/doc/examples/decoding_encoding.c b/ffmpeg/doc/examples/decoding_encoding.c index ae1057c..08e8b92 100644 --- a/ffmpeg/doc/examples/decoding_encoding.c +++ b/ffmpeg/doc/examples/decoding_encoding.c @@ -79,7 +79,7 @@ static int select_channel_layout(AVCodec *codec) { const uint64_t *p; uint64_t best_ch_layout = 0; - int best_nb_channells = 0; + int best_nb_channels = 0; if (!codec->channel_layouts) return AV_CH_LAYOUT_STEREO; @@ -88,9 +88,9 @@ static int select_channel_layout(AVCodec *codec) while (*p) { int nb_channels = av_get_channel_layout_nb_channels(*p); - if (nb_channels > best_nb_channells) { + if (nb_channels > best_nb_channels) { best_ch_layout = *p; - best_nb_channells = nb_channels; + best_nb_channels = nb_channels; } p++; } @@ -156,7 +156,7 @@ static void audio_encode_example(const char *filename) } /* frame containing input raw audio */ - frame = avcodec_alloc_frame(); + frame = av_frame_alloc(); if (!frame) { fprintf(stderr, "Could not allocate audio frame\n"); exit(1); @@ -170,6 +170,10 @@ static void audio_encode_example(const char *filename) * we calculate the size of the samples buffer in bytes */ buffer_size = av_samples_get_buffer_size(NULL, c->channels, c->frame_size, c->sample_fmt, 0); + if (buffer_size < 0) { + fprintf(stderr, "Could not get sample buffer size\n"); + exit(1); + } samples = av_malloc(buffer_size); if (!samples) { fprintf(stderr, "Could not allocate %d bytes for samples buffer\n", @@ -227,7 +231,7 @@ static void audio_encode_example(const char *filename) fclose(f); av_freep(&samples); - avcodec_free_frame(&frame); + av_frame_free(&frame); avcodec_close(c); av_free(c); } @@ -287,12 +291,11 @@ static void audio_decode_example(const char *outfilename, const char *filename) int got_frame = 0; if (!decoded_frame) { - if (!(decoded_frame = avcodec_alloc_frame())) { + if (!(decoded_frame = av_frame_alloc())) { fprintf(stderr, "Could not allocate audio frame\n"); exit(1); } - } else - avcodec_get_frame_defaults(decoded_frame); + } len = avcodec_decode_audio4(c, decoded_frame, &got_frame, &avpkt); if (len < 0) { @@ -329,7 +332,7 @@ static void audio_decode_example(const char *outfilename, const char *filename) avcodec_close(c); av_free(c); - avcodec_free_frame(&decoded_frame); + av_frame_free(&decoded_frame); } /* @@ -386,7 +389,7 @@ static void video_encode_example(const char *filename, int codec_id) exit(1); } - frame = avcodec_alloc_frame(); + frame = av_frame_alloc(); if (!frame) { fprintf(stderr, "Could not allocate video frame\n"); exit(1); @@ -467,7 +470,7 @@ static void video_encode_example(const char *filename, int codec_id) avcodec_close(c); av_free(c); av_freep(&frame->data[0]); - avcodec_free_frame(&frame); + av_frame_free(&frame); printf("\n"); } @@ -565,7 +568,7 @@ static void video_decode_example(const char *outfilename, const char *filename) exit(1); } - frame = avcodec_alloc_frame(); + frame = av_frame_alloc(); if (!frame) { fprintf(stderr, "Could not allocate video frame\n"); exit(1); @@ -609,7 +612,7 @@ static void video_decode_example(const char *outfilename, const char *filename) avcodec_close(c); av_free(c); - avcodec_free_frame(&frame); + av_frame_free(&frame); printf("\n"); } diff --git a/ffmpeg/doc/examples/demuxing.c b/ffmpeg/doc/examples/demuxing.c deleted file mode 100644 index 8a1b69b..0000000 --- a/ffmpeg/doc/examples/demuxing.c +++ /dev/null @@ -1,342 +0,0 @@ -/* - * Copyright (c) 2012 Stefano Sabatini - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - * THE SOFTWARE. - */ - -/** - * @file - * libavformat demuxing API use example. - * - * Show how to use the libavformat and libavcodec API to demux and - * decode audio and video data. - * @example doc/examples/demuxing.c - */ - -#include <libavutil/imgutils.h> -#include <libavutil/samplefmt.h> -#include <libavutil/timestamp.h> -#include <libavformat/avformat.h> - -static AVFormatContext *fmt_ctx = NULL; -static AVCodecContext *video_dec_ctx = NULL, *audio_dec_ctx; -static AVStream *video_stream = NULL, *audio_stream = NULL; -static const char *src_filename = NULL; -static const char *video_dst_filename = NULL; -static const char *audio_dst_filename = NULL; -static FILE *video_dst_file = NULL; -static FILE *audio_dst_file = NULL; - -static uint8_t *video_dst_data[4] = {NULL}; -static int video_dst_linesize[4]; -static int video_dst_bufsize; - -static uint8_t **audio_dst_data = NULL; -static int audio_dst_linesize; -static int audio_dst_bufsize; - -static int video_stream_idx = -1, audio_stream_idx = -1; -static AVFrame *frame = NULL; -static AVPacket pkt; -static int video_frame_count = 0; -static int audio_frame_count = 0; - -static int decode_packet(int *got_frame, int cached) -{ - int ret = 0; - - if (pkt.stream_index == video_stream_idx) { - /* decode video frame */ - ret = avcodec_decode_video2(video_dec_ctx, frame, got_frame, &pkt); - if (ret < 0) { - fprintf(stderr, "Error decoding video frame\n"); - return ret; - } - - if (*got_frame) { - printf("video_frame%s n:%d coded_n:%d pts:%s\n", - cached ? "(cached)" : "", - video_frame_count++, frame->coded_picture_number, - av_ts2timestr(frame->pts, &video_dec_ctx->time_base)); - - /* copy decoded frame to destination buffer: - * this is required since rawvideo expects non aligned data */ - av_image_copy(video_dst_data, video_dst_linesize, - (const uint8_t **)(frame->data), frame->linesize, - video_dec_ctx->pix_fmt, video_dec_ctx->width, video_dec_ctx->height); - - /* write to rawvideo file */ - fwrite(video_dst_data[0], 1, video_dst_bufsize, video_dst_file); - } - } else if (pkt.stream_index == audio_stream_idx) { - /* decode audio frame */ - ret = avcodec_decode_audio4(audio_dec_ctx, frame, got_frame, &pkt); - if (ret < 0) { - fprintf(stderr, "Error decoding audio frame\n"); - return ret; - } - - if (*got_frame) { - printf("audio_frame%s n:%d nb_samples:%d pts:%s\n", - cached ? "(cached)" : "", - audio_frame_count++, frame->nb_samples, - av_ts2timestr(frame->pts, &audio_dec_ctx->time_base)); - - ret = av_samples_alloc(audio_dst_data, &audio_dst_linesize, av_frame_get_channels(frame), - frame->nb_samples, frame->format, 1); - if (ret < 0) { - fprintf(stderr, "Could not allocate audio buffer\n"); - return AVERROR(ENOMEM); - } - - /* TODO: extend return code of the av_samples_* functions so that this call is not needed */ - audio_dst_bufsize = - av_samples_get_buffer_size(NULL, av_frame_get_channels(frame), - frame->nb_samples, frame->format, 1); - - /* copy audio data to destination buffer: - * this is required since rawaudio expects non aligned data */ - av_samples_copy(audio_dst_data, frame->data, 0, 0, - frame->nb_samples, av_frame_get_channels(frame), frame->format); - - /* write to rawaudio file */ - fwrite(audio_dst_data[0], 1, audio_dst_bufsize, audio_dst_file); - av_freep(&audio_dst_data[0]); - } - } - - return ret; -} - -static int open_codec_context(int *stream_idx, - AVFormatContext *fmt_ctx, enum AVMediaType type) -{ - int ret; - AVStream *st; - AVCodecContext *dec_ctx = NULL; - AVCodec *dec = NULL; - - ret = av_find_best_stream(fmt_ctx, type, -1, -1, NULL, 0); - if (ret < 0) { - fprintf(stderr, "Could not find %s stream in input file '%s'\n", - av_get_media_type_string(type), src_filename); - return ret; - } else { - *stream_idx = ret; - st = fmt_ctx->streams[*stream_idx]; - - /* find decoder for the stream */ - dec_ctx = st->codec; - dec = avcodec_find_decoder(dec_ctx->codec_id); - if (!dec) { - fprintf(stderr, "Failed to find %s codec\n", - av_get_media_type_string(type)); - return ret; - } - - if ((ret = avcodec_open2(dec_ctx, dec, NULL)) < 0) { - fprintf(stderr, "Failed to open %s codec\n", - av_get_media_type_string(type)); - return ret; - } - } - - return 0; -} - -static int get_format_from_sample_fmt(const char **fmt, - enum AVSampleFormat sample_fmt) -{ - int i; - struct sample_fmt_entry { - enum AVSampleFormat sample_fmt; const char *fmt_be, *fmt_le; - } sample_fmt_entries[] = { - { AV_SAMPLE_FMT_U8, "u8", "u8" }, - { AV_SAMPLE_FMT_S16, "s16be", "s16le" }, - { AV_SAMPLE_FMT_S32, "s32be", "s32le" }, - { AV_SAMPLE_FMT_FLT, "f32be", "f32le" }, - { AV_SAMPLE_FMT_DBL, "f64be", "f64le" }, - }; - *fmt = NULL; - - for (i = 0; i < FF_ARRAY_ELEMS(sample_fmt_entries); i++) { - struct sample_fmt_entry *entry = &sample_fmt_entries[i]; - if (sample_fmt == entry->sample_fmt) { - *fmt = AV_NE(entry->fmt_be, entry->fmt_le); - return 0; - } - } - - fprintf(stderr, - "sample format %s is not supported as output format\n", - av_get_sample_fmt_name(sample_fmt)); - return -1; -} - -int main (int argc, char **argv) -{ - int ret = 0, got_frame; - - if (argc != 4) { - fprintf(stderr, "usage: %s input_file video_output_file audio_output_file\n" - "API example program to show how to read frames from an input file.\n" - "This program reads frames from a file, decodes them, and writes decoded\n" - "video frames to a rawvideo file named video_output_file, and decoded\n" - "audio frames to a rawaudio file named audio_output_file.\n" - "\n", argv[0]); - exit(1); - } - src_filename = argv[1]; - video_dst_filename = argv[2]; - audio_dst_filename = argv[3]; - - /* register all formats and codecs */ - av_register_all(); - - /* open input file, and allocate format context */ - if (avformat_open_input(&fmt_ctx, src_filename, NULL, NULL) < 0) { - fprintf(stderr, "Could not open source file %s\n", src_filename); - exit(1); - } - - /* retrieve stream information */ - if (avformat_find_stream_info(fmt_ctx, NULL) < 0) { - fprintf(stderr, "Could not find stream information\n"); - exit(1); - } - - if (open_codec_context(&video_stream_idx, fmt_ctx, AVMEDIA_TYPE_VIDEO) >= 0) { - video_stream = fmt_ctx->streams[video_stream_idx]; - video_dec_ctx = video_stream->codec; - - video_dst_file = fopen(video_dst_filename, "wb"); - if (!video_dst_file) { - fprintf(stderr, "Could not open destination file %s\n", video_dst_filename); - ret = 1; - goto end; - } - - /* allocate image where the decoded image will be put */ - ret = av_image_alloc(video_dst_data, video_dst_linesize, - video_dec_ctx->width, video_dec_ctx->height, - video_dec_ctx->pix_fmt, 1); - if (ret < 0) { - fprintf(stderr, "Could not allocate raw video buffer\n"); - goto end; - } - video_dst_bufsize = ret; - } - - if (open_codec_context(&audio_stream_idx, fmt_ctx, AVMEDIA_TYPE_AUDIO) >= 0) { - int nb_planes; - - audio_stream = fmt_ctx->streams[audio_stream_idx]; - audio_dec_ctx = audio_stream->codec; - audio_dst_file = fopen(audio_dst_filename, "wb"); - if (!audio_dst_file) { - fprintf(stderr, "Could not open destination file %s\n", video_dst_filename); - ret = 1; - goto end; - } - - nb_planes = av_sample_fmt_is_planar(audio_dec_ctx->sample_fmt) ? - audio_dec_ctx->channels : 1; - audio_dst_data = av_mallocz(sizeof(uint8_t *) * nb_planes); - if (!audio_dst_data) { - fprintf(stderr, "Could not allocate audio data buffers\n"); - ret = AVERROR(ENOMEM); - goto end; - } - } - - /* dump input information to stderr */ - av_dump_format(fmt_ctx, 0, src_filename, 0); - - if (!audio_stream && !video_stream) { - fprintf(stderr, "Could not find audio or video stream in the input, aborting\n"); - ret = 1; - goto end; - } - - frame = avcodec_alloc_frame(); - if (!frame) { - fprintf(stderr, "Could not allocate frame\n"); - ret = AVERROR(ENOMEM); - goto end; - } - - /* initialize packet, set data to NULL, let the demuxer fill it */ - av_init_packet(&pkt); - pkt.data = NULL; - pkt.size = 0; - - if (video_stream) - printf("Demuxing video from file '%s' into '%s'\n", src_filename, video_dst_filename); - if (audio_stream) - printf("Demuxing audio from file '%s' into '%s'\n", src_filename, audio_dst_filename); - - /* read frames from the file */ - while (av_read_frame(fmt_ctx, &pkt) >= 0) { - decode_packet(&got_frame, 0); - av_free_packet(&pkt); - } - - /* flush cached frames */ - pkt.data = NULL; - pkt.size = 0; - do { - decode_packet(&got_frame, 1); - } while (got_frame); - - printf("Demuxing succeeded.\n"); - - if (video_stream) { - printf("Play the output video file with the command:\n" - "ffplay -f rawvideo -pix_fmt %s -video_size %dx%d %s\n", - av_get_pix_fmt_name(video_dec_ctx->pix_fmt), video_dec_ctx->width, video_dec_ctx->height, - video_dst_filename); - } - - if (audio_stream) { - const char *fmt; - - if ((ret = get_format_from_sample_fmt(&fmt, audio_dec_ctx->sample_fmt)) < 0) - goto end; - printf("Play the output audio file with the command:\n" - "ffplay -f %s -ac %d -ar %d %s\n", - fmt, audio_dec_ctx->channels, audio_dec_ctx->sample_rate, - audio_dst_filename); - } - -end: - if (video_dec_ctx) - avcodec_close(video_dec_ctx); - if (audio_dec_ctx) - avcodec_close(audio_dec_ctx); - avformat_close_input(&fmt_ctx); - if (video_dst_file) - fclose(video_dst_file); - if (audio_dst_file) - fclose(audio_dst_file); - av_free(frame); - av_free(video_dst_data[0]); - av_free(audio_dst_data); - - return ret < 0; -} diff --git a/ffmpeg/doc/examples/filtering_audio.c b/ffmpeg/doc/examples/filtering_audio.c index 456a1c9..1d66ca3 100644 --- a/ffmpeg/doc/examples/filtering_audio.c +++ b/ffmpeg/doc/examples/filtering_audio.c @@ -36,9 +36,10 @@ #include <libavfilter/avcodec.h> #include <libavfilter/buffersink.h> #include <libavfilter/buffersrc.h> +#include <libavutil/opt.h> -const char *filter_descr = "aresample=8000,aconvert=s16:mono"; -const char *player = "ffplay -f s16le -ar 8000 -ac 1 -"; +static const char *filter_descr = "aresample=8000,aformat=sample_fmts=s16:channel_layouts=mono"; +static const char *player = "ffplay -f s16le -ar 8000 -ac 1 -"; static AVFormatContext *fmt_ctx; static AVCodecContext *dec_ctx; @@ -70,6 +71,7 @@ static int open_input_file(const char *filename) } audio_stream_index = ret; dec_ctx = fmt_ctx->streams[audio_stream_index]->codec; + av_opt_set_int(dec_ctx, "refcounted_frames", 1, 0); /* init the audio decoder */ if ((ret = avcodec_open2(dec_ctx, dec, NULL)) < 0) { @@ -83,17 +85,22 @@ static int open_input_file(const char *filename) static int init_filters(const char *filters_descr) { char args[512]; - int ret; + int ret = 0; AVFilter *abuffersrc = avfilter_get_by_name("abuffer"); AVFilter *abuffersink = avfilter_get_by_name("abuffersink"); AVFilterInOut *outputs = avfilter_inout_alloc(); AVFilterInOut *inputs = avfilter_inout_alloc(); - const enum AVSampleFormat sample_fmts[] = { AV_SAMPLE_FMT_S16, -1 }; - AVABufferSinkParams *abuffersink_params; + static const enum AVSampleFormat out_sample_fmts[] = { AV_SAMPLE_FMT_S16, -1 }; + static const int64_t out_channel_layouts[] = { AV_CH_LAYOUT_MONO, -1 }; + static const int out_sample_rates[] = { 8000, -1 }; const AVFilterLink *outlink; AVRational time_base = fmt_ctx->streams[audio_stream_index]->time_base; filter_graph = avfilter_graph_alloc(); + if (!outputs || !inputs || !filter_graph) { + ret = AVERROR(ENOMEM); + goto end; + } /* buffer audio source: the decoded frames from the decoder will be inserted here. */ if (!dec_ctx->channel_layout) @@ -106,18 +113,36 @@ static int init_filters(const char *filters_descr) args, NULL, filter_graph); if (ret < 0) { av_log(NULL, AV_LOG_ERROR, "Cannot create audio buffer source\n"); - return ret; + goto end; } /* buffer audio sink: to terminate the filter chain. */ - abuffersink_params = av_abuffersink_params_alloc(); - abuffersink_params->sample_fmts = sample_fmts; ret = avfilter_graph_create_filter(&buffersink_ctx, abuffersink, "out", - NULL, abuffersink_params, filter_graph); - av_free(abuffersink_params); + NULL, NULL, filter_graph); if (ret < 0) { av_log(NULL, AV_LOG_ERROR, "Cannot create audio buffer sink\n"); - return ret; + goto end; + } + + ret = av_opt_set_int_list(buffersink_ctx, "sample_fmts", out_sample_fmts, -1, + AV_OPT_SEARCH_CHILDREN); + if (ret < 0) { + av_log(NULL, AV_LOG_ERROR, "Cannot set output sample format\n"); + goto end; + } + + ret = av_opt_set_int_list(buffersink_ctx, "channel_layouts", out_channel_layouts, -1, + AV_OPT_SEARCH_CHILDREN); + if (ret < 0) { + av_log(NULL, AV_LOG_ERROR, "Cannot set output channel layout\n"); + goto end; + } + + ret = av_opt_set_int_list(buffersink_ctx, "sample_rates", out_sample_rates, -1, + AV_OPT_SEARCH_CHILDREN); + if (ret < 0) { + av_log(NULL, AV_LOG_ERROR, "Cannot set output sample rate\n"); + goto end; } /* Endpoints for the filter graph. */ @@ -131,12 +156,12 @@ static int init_filters(const char *filters_descr) inputs->pad_idx = 0; inputs->next = NULL; - if ((ret = avfilter_graph_parse(filter_graph, filters_descr, - &inputs, &outputs, NULL)) < 0) - return ret; + if ((ret = avfilter_graph_parse_ptr(filter_graph, filters_descr, + &inputs, &outputs, NULL)) < 0) + goto end; if ((ret = avfilter_graph_config(filter_graph, NULL)) < 0) - return ret; + goto end; /* Print summary of the sink buffer * Note: args buffer is reused to store channel layout string */ @@ -147,7 +172,11 @@ static int init_filters(const char *filters_descr) (char *)av_x_if_null(av_get_sample_fmt_name(outlink->format), "?"), args); - return 0; +end: + avfilter_inout_free(&inputs); + avfilter_inout_free(&outputs); + + return ret; } static void print_frame(const AVFrame *frame) @@ -167,7 +196,7 @@ static void print_frame(const AVFrame *frame) int main(int argc, char **argv) { int ret; - AVPacket packet; + AVPacket packet0, packet; AVFrame *frame = av_frame_alloc(); AVFrame *filt_frame = av_frame_alloc(); int got_frame; @@ -191,9 +220,14 @@ int main(int argc, char **argv) goto end; /* read all packets */ + packet0.data = NULL; + packet.data = NULL; while (1) { - if ((ret = av_read_frame(fmt_ctx, &packet)) < 0) - break; + if (!packet0.data) { + if ((ret = av_read_frame(fmt_ctx, &packet)) < 0) + break; + packet0 = packet; + } if (packet.stream_index == audio_stream_index) { avcodec_get_frame_defaults(frame); @@ -203,10 +237,12 @@ int main(int argc, char **argv) av_log(NULL, AV_LOG_ERROR, "Error decoding audio\n"); continue; } + packet.size -= ret; + packet.data += ret; if (got_frame) { /* push the audio data from decoded frame into the filtergraph */ - if (av_buffersrc_add_frame_flags(buffersrc_ctx, frame, AV_BUFFERSRC_FLAG_KEEP_REF) < 0) { + if (av_buffersrc_add_frame_flags(buffersrc_ctx, frame, 0) < 0) { av_log(NULL, AV_LOG_ERROR, "Error while feeding the audio filtergraph\n"); break; } @@ -214,29 +250,31 @@ int main(int argc, char **argv) /* pull filtered audio from the filtergraph */ while (1) { ret = av_buffersink_get_frame(buffersink_ctx, filt_frame); - if(ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) + if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) break; - if(ret < 0) + if (ret < 0) goto end; print_frame(filt_frame); av_frame_unref(filt_frame); } } + + if (packet.size <= 0) + av_free_packet(&packet0); + } else { + /* discard non-wanted packets */ + av_free_packet(&packet0); } - av_free_packet(&packet); } end: avfilter_graph_free(&filter_graph); - if (dec_ctx) - avcodec_close(dec_ctx); + avcodec_close(dec_ctx); avformat_close_input(&fmt_ctx); av_frame_free(&frame); av_frame_free(&filt_frame); if (ret < 0 && ret != AVERROR_EOF) { - char buf[1024]; - av_strerror(ret, buf, sizeof(buf)); - fprintf(stderr, "Error occurred: %s\n", buf); + fprintf(stderr, "Error occurred: %s\n", av_err2str(ret)); exit(1); } diff --git a/ffmpeg/doc/examples/filtering_video.c b/ffmpeg/doc/examples/filtering_video.c index daa3966..790c641 100644 --- a/ffmpeg/doc/examples/filtering_video.c +++ b/ffmpeg/doc/examples/filtering_video.c @@ -36,6 +36,7 @@ #include <libavfilter/avcodec.h> #include <libavfilter/buffersink.h> #include <libavfilter/buffersrc.h> +#include <libavutil/opt.h> const char *filter_descr = "scale=78:24"; @@ -70,6 +71,7 @@ static int open_input_file(const char *filename) } video_stream_index = ret; dec_ctx = fmt_ctx->streams[video_stream_index]->codec; + av_opt_set_int(dec_ctx, "refcounted_frames", 1, 0); /* init the video decoder */ if ((ret = avcodec_open2(dec_ctx, dec, NULL)) < 0) { @@ -83,15 +85,18 @@ static int open_input_file(const char *filename) static int init_filters(const char *filters_descr) { char args[512]; - int ret; + int ret = 0; AVFilter *buffersrc = avfilter_get_by_name("buffer"); AVFilter *buffersink = avfilter_get_by_name("buffersink"); AVFilterInOut *outputs = avfilter_inout_alloc(); AVFilterInOut *inputs = avfilter_inout_alloc(); enum AVPixelFormat pix_fmts[] = { AV_PIX_FMT_GRAY8, AV_PIX_FMT_NONE }; - AVBufferSinkParams *buffersink_params; filter_graph = avfilter_graph_alloc(); + if (!outputs || !inputs || !filter_graph) { + ret = AVERROR(ENOMEM); + goto end; + } /* buffer video source: the decoded frames from the decoder will be inserted here. */ snprintf(args, sizeof(args), @@ -104,18 +109,22 @@ static int init_filters(const char *filters_descr) args, NULL, filter_graph); if (ret < 0) { av_log(NULL, AV_LOG_ERROR, "Cannot create buffer source\n"); - return ret; + goto end; } /* buffer video sink: to terminate the filter chain. */ - buffersink_params = av_buffersink_params_alloc(); - buffersink_params->pixel_fmts = pix_fmts; ret = avfilter_graph_create_filter(&buffersink_ctx, buffersink, "out", - NULL, buffersink_params, filter_graph); - av_free(buffersink_params); + NULL, NULL, filter_graph); if (ret < 0) { av_log(NULL, AV_LOG_ERROR, "Cannot create buffer sink\n"); - return ret; + goto end; + } + + ret = av_opt_set_int_list(buffersink_ctx, "pix_fmts", pix_fmts, + AV_PIX_FMT_NONE, AV_OPT_SEARCH_CHILDREN); + if (ret < 0) { + av_log(NULL, AV_LOG_ERROR, "Cannot set output pixel format\n"); + goto end; } /* Endpoints for the filter graph. */ @@ -129,13 +138,18 @@ static int init_filters(const char *filters_descr) inputs->pad_idx = 0; inputs->next = NULL; - if ((ret = avfilter_graph_parse(filter_graph, filters_descr, + if ((ret = avfilter_graph_parse_ptr(filter_graph, filters_descr, &inputs, &outputs, NULL)) < 0) - return ret; + goto end; if ((ret = avfilter_graph_config(filter_graph, NULL)) < 0) - return ret; - return 0; + goto end; + +end: + avfilter_inout_free(&inputs); + avfilter_inout_free(&outputs); + + return ret; } static void display_frame(const AVFrame *frame, AVRational time_base) @@ -228,22 +242,20 @@ int main(int argc, char **argv) display_frame(filt_frame, buffersink_ctx->inputs[0]->time_base); av_frame_unref(filt_frame); } + av_frame_unref(frame); } } av_free_packet(&packet); } end: avfilter_graph_free(&filter_graph); - if (dec_ctx) - avcodec_close(dec_ctx); + avcodec_close(dec_ctx); avformat_close_input(&fmt_ctx); av_frame_free(&frame); av_frame_free(&filt_frame); if (ret < 0 && ret != AVERROR_EOF) { - char buf[1024]; - av_strerror(ret, buf, sizeof(buf)); - fprintf(stderr, "Error occurred: %s\n", buf); + fprintf(stderr, "Error occurred: %s\n", av_err2str(ret)); exit(1); } diff --git a/ffmpeg/doc/examples/muxing.c b/ffmpeg/doc/examples/muxing.c index 7305cc6..4cd3f65 100644 --- a/ffmpeg/doc/examples/muxing.c +++ b/ffmpeg/doc/examples/muxing.c @@ -34,9 +34,11 @@ #include <string.h> #include <math.h> +#include <libavutil/opt.h> #include <libavutil/mathematics.h> #include <libavformat/avformat.h> #include <libswscale/swscale.h> +#include <libswresample/swresample.h> /* 5 seconds stream duration */ #define STREAM_DURATION 200.0 @@ -46,13 +48,6 @@ static int sws_flags = SWS_BICUBIC; -/**************************************************************/ -/* audio output */ - -static float t, tincr, tincr2; -static int16_t *samples; -static int audio_input_frame_size; - /* Add an output stream. */ static AVStream *add_stream(AVFormatContext *oc, AVCodec **codec, enum AVCodecID codec_id) @@ -78,8 +73,7 @@ static AVStream *add_stream(AVFormatContext *oc, AVCodec **codec, switch ((*codec)->type) { case AVMEDIA_TYPE_AUDIO: - st->id = 1; - c->sample_fmt = AV_SAMPLE_FMT_S16; + c->sample_fmt = AV_SAMPLE_FMT_FLTP; c->bit_rate = 64000; c->sample_rate = 44100; c->channels = 2; @@ -127,8 +121,17 @@ static AVStream *add_stream(AVFormatContext *oc, AVCodec **codec, /* audio output */ static float t, tincr, tincr2; -static int16_t *samples; -static int audio_input_frame_size; + +static uint8_t **src_samples_data; +static int src_samples_linesize; +static int src_nb_samples; + +static int max_dst_nb_samples; +uint8_t **dst_samples_data; +int dst_samples_linesize; +int dst_samples_size; + +struct SwrContext *swr_ctx = NULL; static void open_audio(AVFormatContext *oc, AVCodec *codec, AVStream *st) { @@ -150,17 +153,54 @@ static void open_audio(AVFormatContext *oc, AVCodec *codec, AVStream *st) /* increment frequency by 110 Hz per second */ tincr2 = 2 * M_PI * 110.0 / c->sample_rate / c->sample_rate; - if (c->codec->capabilities & CODEC_CAP_VARIABLE_FRAME_SIZE) - audio_input_frame_size = 10000; - else - audio_input_frame_size = c->frame_size; - samples = av_malloc(audio_input_frame_size * - av_get_bytes_per_sample(c->sample_fmt) * - c->channels); - if (!samples) { - fprintf(stderr, "Could not allocate audio samples buffer\n"); + src_nb_samples = c->codec->capabilities & CODEC_CAP_VARIABLE_FRAME_SIZE ? + 10000 : c->frame_size; + + ret = av_samples_alloc_array_and_samples(&src_samples_data, &src_samples_linesize, c->channels, + src_nb_samples, AV_SAMPLE_FMT_S16, 0); + if (ret < 0) { + fprintf(stderr, "Could not allocate source samples\n"); exit(1); } + + /* compute the number of converted samples: buffering is avoided + * ensuring that the output buffer will contain at least all the + * converted input samples */ + max_dst_nb_samples = src_nb_samples; + + /* create resampler context */ + if (c->sample_fmt != AV_SAMPLE_FMT_S16) { + swr_ctx = swr_alloc(); + if (!swr_ctx) { + fprintf(stderr, "Could not allocate resampler context\n"); + exit(1); + } + + /* set options */ + av_opt_set_int (swr_ctx, "in_channel_count", c->channels, 0); + av_opt_set_int (swr_ctx, "in_sample_rate", c->sample_rate, 0); + av_opt_set_sample_fmt(swr_ctx, "in_sample_fmt", AV_SAMPLE_FMT_S16, 0); + av_opt_set_int (swr_ctx, "out_channel_count", c->channels, 0); + av_opt_set_int (swr_ctx, "out_sample_rate", c->sample_rate, 0); + av_opt_set_sample_fmt(swr_ctx, "out_sample_fmt", c->sample_fmt, 0); + + /* initialize the resampling context */ + if ((ret = swr_init(swr_ctx)) < 0) { + fprintf(stderr, "Failed to initialize the resampling context\n"); + exit(1); + } + + ret = av_samples_alloc_array_and_samples(&dst_samples_data, &dst_samples_linesize, c->channels, + max_dst_nb_samples, c->sample_fmt, 0); + if (ret < 0) { + fprintf(stderr, "Could not allocate destination samples\n"); + exit(1); + } + } else { + dst_samples_data = src_samples_data; + } + dst_samples_size = av_samples_get_buffer_size(NULL, c->channels, max_dst_nb_samples, + c->sample_fmt, 0); } /* Prepare a 16 bit dummy audio frame of 'frame_size' samples and @@ -184,19 +224,45 @@ static void write_audio_frame(AVFormatContext *oc, AVStream *st) { AVCodecContext *c; AVPacket pkt = { 0 }; // data and size must be 0; - AVFrame *frame = avcodec_alloc_frame(); - int got_packet, ret; + AVFrame *frame = av_frame_alloc(); + int got_packet, ret, dst_nb_samples; av_init_packet(&pkt); c = st->codec; - get_audio_frame(samples, audio_input_frame_size, c->channels); - frame->nb_samples = audio_input_frame_size; + get_audio_frame((int16_t *)src_samples_data[0], src_nb_samples, c->channels); + + /* convert samples from native format to destination codec format, using the resampler */ + if (swr_ctx) { + /* compute destination number of samples */ + dst_nb_samples = av_rescale_rnd(swr_get_delay(swr_ctx, c->sample_rate) + src_nb_samples, + c->sample_rate, c->sample_rate, AV_ROUND_UP); + if (dst_nb_samples > max_dst_nb_samples) { + av_free(dst_samples_data[0]); + ret = av_samples_alloc(dst_samples_data, &dst_samples_linesize, c->channels, + dst_nb_samples, c->sample_fmt, 0); + if (ret < 0) + exit(1); + max_dst_nb_samples = dst_nb_samples; + dst_samples_size = av_samples_get_buffer_size(NULL, c->channels, dst_nb_samples, + c->sample_fmt, 0); + } + + /* convert to destination format */ + ret = swr_convert(swr_ctx, + dst_samples_data, dst_nb_samples, + (const uint8_t **)src_samples_data, src_nb_samples); + if (ret < 0) { + fprintf(stderr, "Error while converting\n"); + exit(1); + } + } else { + dst_nb_samples = src_nb_samples; + } + + frame->nb_samples = dst_nb_samples; avcodec_fill_audio_frame(frame, c->channels, c->sample_fmt, - (uint8_t *)samples, - audio_input_frame_size * - av_get_bytes_per_sample(c->sample_fmt) * - c->channels, 1); + dst_samples_data[0], dst_samples_size, 0); ret = avcodec_encode_audio2(c, &pkt, frame, &got_packet); if (ret < 0) { @@ -205,7 +271,7 @@ static void write_audio_frame(AVFormatContext *oc, AVStream *st) } if (!got_packet) - return; + goto freeframe; pkt.stream_index = st->index; @@ -216,14 +282,19 @@ static void write_audio_frame(AVFormatContext *oc, AVStream *st) av_err2str(ret)); exit(1); } - avcodec_free_frame(&frame); +freeframe: + av_frame_free(&frame); } static void close_audio(AVFormatContext *oc, AVStream *st) { avcodec_close(st->codec); - - av_free(samples); + if (dst_samples_data != src_samples_data) { + av_free(dst_samples_data[0]); + av_free(dst_samples_data); + } + av_free(src_samples_data[0]); + av_free(src_samples_data); } /**************************************************************/ @@ -246,7 +317,7 @@ static void open_video(AVFormatContext *oc, AVCodec *codec, AVStream *st) } /* allocate and init a re-usable frame */ - frame = avcodec_alloc_frame(); + frame = av_frame_alloc(); if (!frame) { fprintf(stderr, "Could not allocate video frame\n"); exit(1); @@ -388,7 +459,7 @@ int main(int argc, char **argv) AVFormatContext *oc; AVStream *audio_st, *video_st; AVCodec *audio_codec, *video_codec; - double audio_pts, video_pts; + double audio_time, video_time; int ret; /* Initialize libavcodec, and register all codecs and formats. */ @@ -461,23 +532,15 @@ int main(int argc, char **argv) frame->pts = 0; for (;;) { /* Compute current audio and video time. */ - if (audio_st) - audio_pts = (double)audio_st->pts.val * audio_st->time_base.num / audio_st->time_base.den; - else - audio_pts = 0.0; - - if (video_st) - video_pts = (double)video_st->pts.val * video_st->time_base.num / - video_st->time_base.den; - else - video_pts = 0.0; - - if ((!audio_st || audio_pts >= STREAM_DURATION) && - (!video_st || video_pts >= STREAM_DURATION)) + audio_time = audio_st ? audio_st->pts.val * av_q2d(audio_st->time_base) : 0.0; + video_time = video_st ? video_st->pts.val * av_q2d(video_st->time_base) : 0.0; + + if ((!audio_st || audio_time >= STREAM_DURATION) && + (!video_st || video_time >= STREAM_DURATION)) break; /* write interleaved audio and video frames */ - if (!video_st || (video_st && audio_st && audio_pts < video_pts)) { + if (!video_st || (video_st && audio_st && audio_time < video_time)) { write_audio_frame(oc, audio_st); } else { write_video_frame(oc, video_st); diff --git a/ffmpeg/doc/examples/pc-uninstalled/libavcodec.pc b/ffmpeg/doc/examples/pc-uninstalled/libavcodec.pc index 787d687..a87ded7 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libavcodec.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libavcodec.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libavcodec Description: FFmpeg codec library -Version: 55.1.100 -Requires: libavutil = 52.22.100 +Version: 55.46.100 +Requires: libavutil = 52.59.100 Conflicts: -Libs: -L${libdir} -lavcodec +Libs: -L${libdir} -Wl,-rpath,${libdir} -lavcodec Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libavdevice.pc b/ffmpeg/doc/examples/pc-uninstalled/libavdevice.pc index 89ef046..7f05a29 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libavdevice.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libavdevice.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libavdevice Description: FFmpeg device handling library -Version: 55.0.100 -Requires: libavfilter = 3.48.100, libavformat = 55.0.100 +Version: 55.5.102 +Requires: libavfilter = 4.0.103, libavformat = 55.22.100 Conflicts: -Libs: -L${libdir} -lavdevice +Libs: -L${libdir} -Wl,-rpath,${libdir} -lavdevice Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libavfilter.pc b/ffmpeg/doc/examples/pc-uninstalled/libavfilter.pc index aacaf0a..b42f95d 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libavfilter.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libavfilter.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libavfilter Description: FFmpeg audio/video filtering library -Version: 3.48.100 -Requires: libpostproc = 52.2.100, libswresample = 0.17.102, libswscale = 2.2.100, libavformat = 55.0.100, libavcodec = 55.1.100, libavutil = 52.22.100 +Version: 4.0.103 +Requires: libpostproc = 52.3.100, libswresample = 0.17.104, libswscale = 2.5.101, libavformat = 55.22.100, libavcodec = 55.46.100, libavutil = 52.59.100 Conflicts: -Libs: -L${libdir} -lavfilter +Libs: -L${libdir} -Wl,-rpath,${libdir} -lavfilter Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libavformat.pc b/ffmpeg/doc/examples/pc-uninstalled/libavformat.pc index 8f27151..8bab324 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libavformat.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libavformat.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libavformat Description: FFmpeg container format library -Version: 55.0.100 -Requires: libavcodec = 55.1.100 +Version: 55.22.100 +Requires: libavcodec = 55.46.100 Conflicts: -Libs: -L${libdir} -lavformat +Libs: -L${libdir} -Wl,-rpath,${libdir} -lavformat Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libavutil.pc b/ffmpeg/doc/examples/pc-uninstalled/libavutil.pc index 8a95064..85df0f0 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libavutil.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libavutil.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libavutil Description: FFmpeg utility library -Version: 52.22.100 +Version: 52.59.100 Requires: Conflicts: -Libs: -L${libdir} -lavutil +Libs: -L${libdir} -Wl,-rpath,${libdir} -lavutil Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libpostproc.pc b/ffmpeg/doc/examples/pc-uninstalled/libpostproc.pc index 5e87c13..94da503 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libpostproc.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libpostproc.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libpostproc Description: FFmpeg postprocessing library -Version: 52.2.100 -Requires: libavutil = 52.22.100 +Version: 52.3.100 +Requires: libavutil = 52.59.100 Conflicts: -Libs: -L${libdir} -lpostproc +Libs: -L${libdir} -Wl,-rpath,${libdir} -lpostproc Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libswresample.pc b/ffmpeg/doc/examples/pc-uninstalled/libswresample.pc index 873f39d..45bfa4a 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libswresample.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libswresample.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libswresample Description: FFmpeg audio resampling library -Version: 0.17.102 -Requires: libavutil = 52.22.100 +Version: 0.17.104 +Requires: libavutil = 52.59.100 Conflicts: -Libs: -L${libdir} -lswresample +Libs: -L${libdir} -Wl,-rpath,${libdir} -lswresample Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/pc-uninstalled/libswscale.pc b/ffmpeg/doc/examples/pc-uninstalled/libswscale.pc index 764a10c..8693580 100644 --- a/ffmpeg/doc/examples/pc-uninstalled/libswscale.pc +++ b/ffmpeg/doc/examples/pc-uninstalled/libswscale.pc @@ -5,8 +5,8 @@ includedir=${pcfiledir}/../../.. Name: libswscale Description: FFmpeg image rescaling library -Version: 2.2.100 -Requires: libavutil = 52.22.100 +Version: 2.5.101 +Requires: libavutil = 52.59.100 Conflicts: -Libs: -L${libdir} -lswscale +Libs: -L${libdir} -Wl,-rpath,${libdir} -lswscale Cflags: -I${includedir} diff --git a/ffmpeg/doc/examples/resampling_audio.c b/ffmpeg/doc/examples/resampling_audio.c index dd128e8..a15e042 100644 --- a/ffmpeg/doc/examples/resampling_audio.c +++ b/ffmpeg/doc/examples/resampling_audio.c @@ -62,7 +62,7 @@ static int get_format_from_sample_fmt(const char **fmt, /** * Fill dst buffer with nb_samples, generated starting from t. */ -void fill_samples(double *dst, int nb_samples, int nb_channels, int sample_rate, double *t) +static void fill_samples(double *dst, int nb_samples, int nb_channels, int sample_rate, double *t) { int i, j; double tincr = 1.0 / sample_rate, *dstp = dst; @@ -78,18 +78,6 @@ void fill_samples(double *dst, int nb_samples, int nb_channels, int sample_rate, } } -int alloc_samples_array_and_data(uint8_t ***data, int *linesize, int nb_channels, - int nb_samples, enum AVSampleFormat sample_fmt, int align) -{ - int nb_planes = av_sample_fmt_is_planar(sample_fmt) ? nb_channels : 1; - - *data = av_malloc(sizeof(*data) * nb_planes); - if (!*data) - return AVERROR(ENOMEM); - return av_samples_alloc(*data, linesize, nb_channels, - nb_samples, sample_fmt, align); -} - int main(int argc, char **argv) { int64_t src_ch_layout = AV_CH_LAYOUT_STEREO, dst_ch_layout = AV_CH_LAYOUT_SURROUND; @@ -149,8 +137,8 @@ int main(int argc, char **argv) /* allocate source and destination samples buffers */ src_nb_channels = av_get_channel_layout_nb_channels(src_ch_layout); - ret = alloc_samples_array_and_data(&src_data, &src_linesize, src_nb_channels, - src_nb_samples, src_sample_fmt, 0); + ret = av_samples_alloc_array_and_samples(&src_data, &src_linesize, src_nb_channels, + src_nb_samples, src_sample_fmt, 0); if (ret < 0) { fprintf(stderr, "Could not allocate source samples\n"); goto end; @@ -164,8 +152,8 @@ int main(int argc, char **argv) /* buffer is going to be directly written to a rawaudio file, no alignment */ dst_nb_channels = av_get_channel_layout_nb_channels(dst_ch_layout); - ret = alloc_samples_array_and_data(&dst_data, &dst_linesize, dst_nb_channels, - dst_nb_samples, dst_sample_fmt, 0); + ret = av_samples_alloc_array_and_samples(&dst_data, &dst_linesize, dst_nb_channels, + dst_nb_samples, dst_sample_fmt, 0); if (ret < 0) { fprintf(stderr, "Could not allocate destination samples\n"); goto end; @@ -196,6 +184,10 @@ int main(int argc, char **argv) } dst_bufsize = av_samples_get_buffer_size(&dst_linesize, dst_nb_channels, ret, dst_sample_fmt, 1); + if (dst_bufsize < 0) { + fprintf(stderr, "Could not get sample buffer size\n"); + goto end; + } printf("t:%f in:%d out:%d\n", t, src_nb_samples, ret); fwrite(dst_data[0], 1, dst_bufsize, dst_file); } while (t < 10); diff --git a/ffmpeg/doc/faq.texi b/ffmpeg/doc/faq.texi index ebf21f5..c47d9d9 100644 --- a/ffmpeg/doc/faq.texi +++ b/ffmpeg/doc/faq.texi @@ -105,7 +105,7 @@ For example, img1.jpg, img2.jpg, img3.jpg,... Then you may run: @example - ffmpeg -f image2 -i img%d.jpg /tmp/a.mpg +ffmpeg -f image2 -i img%d.jpg /tmp/a.mpg @end example Notice that @samp{%d} is replaced by the image number. @@ -118,7 +118,7 @@ the sequence. This is useful if your sequence does not start with example will start with @file{img100.jpg}: @example - ffmpeg -f image2 -start_number 100 -i img%d.jpg /tmp/a.mpg +ffmpeg -f image2 -start_number 100 -i img%d.jpg /tmp/a.mpg @end example If you have large number of pictures to rename, you can use the @@ -128,7 +128,7 @@ that match @code{*jpg} to the @file{/tmp} directory in the sequence of @file{img001.jpg}, @file{img002.jpg} and so on. @example - x=1; for i in *jpg; do counter=$(printf %03d $x); ln -s "$i" /tmp/img"$counter".jpg; x=$(($x+1)); done +x=1; for i in *jpg; do counter=$(printf %03d $x); ln -s "$i" /tmp/img"$counter".jpg; x=$(($x+1)); done @end example If you want to sequence them by oldest modified first, substitute @@ -137,7 +137,7 @@ If you want to sequence them by oldest modified first, substitute Then run: @example - ffmpeg -f image2 -i /tmp/img%03d.jpg /tmp/a.mpg +ffmpeg -f image2 -i /tmp/img%03d.jpg /tmp/a.mpg @end example The same logic is used for any image format that ffmpeg reads. @@ -145,7 +145,7 @@ The same logic is used for any image format that ffmpeg reads. You can also use @command{cat} to pipe images to ffmpeg: @example - cat *.jpg | ffmpeg -f image2pipe -c:v mjpeg -i - output.mpg +cat *.jpg | ffmpeg -f image2pipe -c:v mjpeg -i - output.mpg @end example @section How do I encode movie to single pictures? @@ -153,7 +153,7 @@ You can also use @command{cat} to pipe images to ffmpeg: Use: @example - ffmpeg -i movie.mpg movie%d.jpg +ffmpeg -i movie.mpg movie%d.jpg @end example The @file{movie.mpg} used as input will be converted to @@ -169,7 +169,7 @@ to force the encoding. Applying that to the previous example: @example - ffmpeg -i movie.mpg -f image2 -c:v mjpeg menu%d.jpg +ffmpeg -i movie.mpg -f image2 -c:v mjpeg menu%d.jpg @end example Beware that there is no "jpeg" codec. Use "mjpeg" instead. @@ -227,15 +227,15 @@ then you may use any file that DirectShow can read as input. Just create an "input.avs" text file with this single line ... @example - DirectShowSource("C:\path to your file\yourfile.asf") +DirectShowSource("C:\path to your file\yourfile.asf") @end example ... and then feed that text file to ffmpeg: @example - ffmpeg -i input.avs +ffmpeg -i input.avs @end example -For ANY other help on Avisynth, please visit the -@uref{http://www.avisynth.org/, Avisynth homepage}. +For ANY other help on AviSynth, please visit the +@uref{http://www.avisynth.org/, AviSynth homepage}. @section How can I join video files? @@ -393,17 +393,17 @@ Appending @code{:v} to it will do exactly that. Use @option{-dumpgraph -} to find out exactly where the channel layout is lost. -Most likely, it is through @code{auto-inserted aconvert}. Try to understand +Most likely, it is through @code{auto-inserted aresample}. Try to understand why the converting filter was needed at that place. Just before the output is a likely place, as @option{-f lavfi} currently only support packed S16. -Then insert the correct @code{aconvert} explicitly in the filter graph, +Then insert the correct @code{aformat} explicitly in the filtergraph, specifying the exact format. @example -aconvert=s16:stereo:packed +aformat=sample_fmts=s16:channel_layouts=stereo @end example @section Why does FFmpeg not see the subtitles in my VOB file? @@ -475,9 +475,10 @@ read @uref{http://www.tux.org/lkml/#s15, "Programming Religion"}. @section Why are the ffmpeg programs devoid of debugging symbols? -The build process creates ffmpeg_g, ffplay_g, etc. which contain full debug -information. Those binaries are stripped to create ffmpeg, ffplay, etc. If -you need the debug information, use the *_g versions. +The build process creates @command{ffmpeg_g}, @command{ffplay_g}, etc. which +contain full debug information. Those binaries are stripped to create +@command{ffmpeg}, @command{ffplay}, etc. If you need the debug information, use +the *_g versions. @section I do not like the LGPL, can I contribute code under the GPL instead? @@ -497,7 +498,7 @@ An easy way to get the full list of required libraries in dependency order is to use @code{pkg-config}. @example - c99 -o program program.c $(pkg-config --cflags --libs libavformat libavcodec) +c99 -o program program.c $(pkg-config --cflags --libs libavformat libavcodec) @end example See @file{doc/example/Makefile} and @file{doc/example/pc-uninstalled} for @@ -521,10 +522,6 @@ to use them you have to append -D__STDC_CONSTANT_MACROS to your CXXFLAGS You have to create a custom AVIOContext using @code{avio_alloc_context}, see @file{libavformat/aviobuf.c} in FFmpeg and @file{libmpdemux/demux_lavf.c} in MPlayer or MPlayer2 sources. -@section Where can I find libav* headers for Pascal/Delphi? - -see @url{http://www.iversenit.dk/dev/ffmpeg-headers/} - @section Where is the documentation about ffv1, msmpeg4, asv1, 4xm? see @url{http://www.ffmpeg.org/~michael/} @@ -537,11 +534,12 @@ In this specific case please look at RFC 4629 to see how it should be done. @section AVStream.r_frame_rate is wrong, it is much larger than the frame rate. -r_frame_rate is NOT the average frame rate, it is the smallest frame rate +@code{r_frame_rate} is NOT the average frame rate, it is the smallest frame rate that can accurately represent all timestamps. So no, it is not wrong if it is larger than the average! -For example, if you have mixed 25 and 30 fps content, then r_frame_rate -will be 150. +For example, if you have mixed 25 and 30 fps content, then @code{r_frame_rate} +will be 150 (it is the least common multiple). +If you are looking for the average frame rate, see @code{AVStream.avg_frame_rate}. @section Why is @code{make fate} not running all tests? diff --git a/ffmpeg/doc/fate.texi b/ffmpeg/doc/fate.texi index 4c2ba4d..4e5cbd7 100644 --- a/ffmpeg/doc/fate.texi +++ b/ffmpeg/doc/fate.texi @@ -27,7 +27,7 @@ by visiting this website: This is especially recommended for all people contributing source code to FFmpeg, as it can be seen if some test on some platform broke -with there recent contribution. This usually happens on the platforms +with their recent contribution. This usually happens on the platforms the developers could not test on. The second part of this document describes how you can run FATE to @@ -131,7 +131,12 @@ of the server and to accept its host key. This can usually be achieved by running your SSH client manually and killing it after you accepted the key. The FATE server's fingerprint is: - b1:31:c8:79:3f:04:1d:f8:f2:23:26:5a:fd:55:fa:92 +@table @option +@item RSA + d3:f1:83:97:a4:75:2b:a6:fb:d6:e8:aa:81:93:97:51 +@item ECDSA + 76:9f:68:32:04:1e:d5:d4:ec:47:3f:dc:fc:18:17:86 +@end table If you have problems connecting to the FATE server, it may help to try out the @command{ssh} command with one or more @option{-v} options. You should @@ -148,20 +153,20 @@ the synchronisation of the samples directory. @table @option @item fate-rsync - Download/synchronize sample files to the configured samples directory. +Download/synchronize sample files to the configured samples directory. @item fate-list - Will list all fate/regression test targets. +Will list all fate/regression test targets. @item fate - Run the FATE test suite (requires the fate-suite dataset). +Run the FATE test suite (requires the fate-suite dataset). @end table @section Makefile variables @table @option @item V - Verbosity level, can be set to 0, 1 or 2. +Verbosity level, can be set to 0, 1 or 2. @itemize @item 0: show just the test arguments @item 1: show just the command used in the test @@ -169,22 +174,28 @@ the synchronisation of the samples directory. @end itemize @item SAMPLES - Specify or override the path to the FATE samples at make time, it has a - meaning only while running the regression tests. +Specify or override the path to the FATE samples at make time, it has a +meaning only while running the regression tests. @item THREADS - Specify how many threads to use while running regression tests, it is - quite useful to detect thread-related regressions. +Specify how many threads to use while running regression tests, it is +quite useful to detect thread-related regressions. + @item THREAD_TYPE - Specify which threading strategy test, either @var{slice} or @var{frame}, - by default @var{slice+frame} +Specify which threading strategy test, either @var{slice} or @var{frame}, +by default @var{slice+frame} + @item CPUFLAGS - Specify CPU flags. +Specify CPU flags. + @item TARGET_EXEC - Specify or override the wrapper used to run the tests. - The @var{TARGET_EXEC} option provides a way to run FATE wrapped in - @command{valgrind}, @command{qemu-user} or @command{wine} or on remote targets - through @command{ssh}. +Specify or override the wrapper used to run the tests. +The @var{TARGET_EXEC} option provides a way to run FATE wrapped in +@command{valgrind}, @command{qemu-user} or @command{wine} or on remote targets +through @command{ssh}. + +@item GEN +Set to @var{1} to generate the missing or mismatched references. @end table @section Examples diff --git a/ffmpeg/doc/fate_config.sh.template b/ffmpeg/doc/fate_config.sh.template index f7bd625..1487c1d 100644 --- a/ffmpeg/doc/fate_config.sh.template +++ b/ffmpeg/doc/fate_config.sh.template @@ -4,16 +4,20 @@ samples= # path to samples directory workdir= # directory in which to do all the work #fate_recv="ssh -T fate@fate.ffmpeg.org" # command to submit report comment= # optional description +build_only= # set to "yes" for a compile-only instance that skips tests # the following are optional and map to configure options arch= cpu= cross_prefix= +as= cc= +ld= target_os= sysroot= target_exec= target_path= +target_samples= extra_cflags= extra_ldflags= extra_libs= diff --git a/ffmpeg/doc/ffmpeg-codecs.texi b/ffmpeg/doc/ffmpeg-codecs.texi index 8f807c1..6f8f5a3 100644 --- a/ffmpeg/doc/ffmpeg-codecs.texi +++ b/ffmpeg/doc/ffmpeg-codecs.texi @@ -17,1075 +17,7 @@ the libavcodec library. @c man end DESCRIPTION -@chapter Codec Options -@c man begin CODEC OPTIONS - -libavcodec provides some generic global options, which can be set on -all the encoders and decoders. In addition each codec may support -so-called private options, which are specific for a given codec. - -Sometimes, a global option may only affect a specific kind of codec, -and may be unsensical or ignored by another, so you need to be aware -of the meaning of the specified options. Also some options are -meant only for decoding or encoding. - -Options may be set by specifying -@var{option} @var{value} in the -FFmpeg tools, or by setting the value explicitly in the -@code{AVCodecContext} options or using the @file{libavutil/opt.h} API -for programmatic use. - -The list of supported options follow: - -@table @option -@item b @var{integer} (@emph{encoding,audio,video}) -Set bitrate in bits/s. Default value is 200K. - -@item ab @var{integer} (@emph{encoding,audio}) -Set audio bitrate (in bits/s). Default value is 128K. - -@item bt @var{integer} (@emph{encoding,video}) -Set video bitrate tolerance (in bits/s). In 1-pass mode, bitrate -tolerance specifies how far ratecontrol is willing to deviate from the -target average bitrate value. This is not related to min/max -bitrate. Lowering tolerance too much has an adverse effect on quality. - -@item flags @var{flags} (@emph{decoding/encoding,audio,video,subtitles}) -Set generic flags. - -Possible values: -@table @samp -@item mv4 -Use four motion vector by macroblock (mpeg4). -@item qpel -Use 1/4 pel motion compensation. -@item loop -Use loop filter. -@item qscale -Use fixed qscale. -@item gmc -Use gmc. -@item mv0 -Always try a mb with mv=<0,0>. -@item input_preserved - -@item pass1 -Use internal 2pass ratecontrol in first pass mode. -@item pass2 -Use internal 2pass ratecontrol in second pass mode. -@item gray -Only decode/encode grayscale. -@item emu_edge -Do not draw edges. -@item psnr -Set error[?] variables during encoding. -@item truncated - -@item naq -Normalize adaptive quantization. -@item ildct -Use interlaced DCT. -@item low_delay -Force low delay. -@item global_header -Place global headers in extradata instead of every keyframe. -@item bitexact -Use only bitexact stuff (except (I)DCT). -@item aic -Apply H263 advanced intra coding / mpeg4 ac prediction. -@item cbp -Deprecated, use mpegvideo private options instead. -@item qprd -Deprecated, use mpegvideo private options instead. -@item ilme -Apply interlaced motion estimation. -@item cgop -Use closed gop. -@end table - -@item sub_id @var{integer} -Deprecated, currently unused. - -@item me_method @var{integer} (@emph{encoding,video}) -Set motion estimation method. - -Possible values: -@table @samp -@item zero -zero motion estimation (fastest) -@item full -full motion estimation (slowest) -@item epzs -EPZS motion estimation (default) -@item esa -esa motion estimation (alias for full) -@item tesa -tesa motion estimation -@item dia -dia motion estimation (alias for epzs) -@item log -log motion estimation -@item phods -phods motion estimation -@item x1 -X1 motion estimation -@item hex -hex motion estimation -@item umh -umh motion estimation -@item iter -iter motion estimation -@end table - -@item extradata_size @var{integer} -Set extradata size. - -@item time_base @var{rational number} -Set codec time base. - -It is the fundamental unit of time (in seconds) in terms of which -frame timestamps are represented. For fixed-fps content, timebase -should be 1/framerate and timestamp increments should be identically -1. - -@item g @var{integer} (@emph{encoding,video}) -Set the group of picture size. Default value is 12. - -@item ar @var{integer} (@emph{decoding/encoding,audio}) -Set audio sampling rate (in Hz). - -@item ac @var{integer} (@emph{decoding/encoding,audio}) -Set number of audio channels. - -@item cutoff @var{integer} (@emph{encoding,audio}) -Set cutoff bandwidth. - -@item frame_size @var{integer} (@emph{encoding,audio}) -Set audio frame size. - -Each submitted frame except the last must contain exactly frame_size -samples per channel. May be 0 when the codec has -CODEC_CAP_VARIABLE_FRAME_SIZE set, in that case the frame size is not -restricted. It is set by some decoders to indicate constant frame -size. - -@item frame_number @var{integer} -Set the frame number. - -@item delay @var{integer} - -@item qcomp @var{float} (@emph{encoding,video}) -Set video quantizer scale compression (VBR). It is used as a constant -in the ratecontrol equation. Recommended range for default rc_eq: -0.0-1.0. - -@item qblur @var{float} (@emph{encoding,video}) -Set video quantizer scale blur (VBR). - -@item qmin @var{integer} (@emph{encoding,video}) -Set min video quantizer scale (VBR). Must be included between -1 and -69, default value is 2. - -@item qmax @var{integer} (@emph{encoding,video}) -Set max video quantizer scale (VBR). Must be included between -1 and -1024, default value is 31. - -@item qdiff @var{integer} (@emph{encoding,video}) -Set max difference between the quantizer scale (VBR). - -@item bf @var{integer} (@emph{encoding,video}) -Set max number of B frames. - -@item b_qfactor @var{float} (@emph{encoding,video}) -Set qp factor between P and B frames. - -@item rc_strategy @var{integer} (@emph{encoding,video}) -Set ratecontrol method. - -@item b_strategy @var{integer} (@emph{encoding,video}) -Set strategy to choose between I/P/B-frames. - -@item ps @var{integer} (@emph{encoding,video}) -Set RTP payload size in bytes. - -@item mv_bits @var{integer} -@item header_bits @var{integer} -@item i_tex_bits @var{integer} -@item p_tex_bits @var{integer} -@item i_count @var{integer} -@item p_count @var{integer} -@item skip_count @var{integer} -@item misc_bits @var{integer} -@item frame_bits @var{integer} -@item codec_tag @var{integer} -@item bug @var{flags} (@emph{decoding,video}) -Workaround not auto detected encoder bugs. - -Possible values: -@table @samp -@item autodetect - -@item old_msmpeg4 -some old lavc generated msmpeg4v3 files (no autodetection) -@item xvid_ilace -Xvid interlacing bug (autodetected if fourcc==XVIX) -@item ump4 -(autodetected if fourcc==UMP4) -@item no_padding -padding bug (autodetected) -@item amv - -@item ac_vlc -illegal vlc bug (autodetected per fourcc) -@item qpel_chroma - -@item std_qpel -old standard qpel (autodetected per fourcc/version) -@item qpel_chroma2 - -@item direct_blocksize -direct-qpel-blocksize bug (autodetected per fourcc/version) -@item edge -edge padding bug (autodetected per fourcc/version) -@item hpel_chroma - -@item dc_clip - -@item ms -Workaround various bugs in microsoft broken decoders. -@item trunc -trancated frames -@end table - -@item lelim @var{integer} (@emph{encoding,video}) -Set single coefficient elimination threshold for luminance (negative -values also consider DC coefficient). - -@item celim @var{integer} (@emph{encoding,video}) -Set single coefficient elimination threshold for chrominance (negative -values also consider dc coefficient) - -@item strict @var{integer} (@emph{decoding/encoding,audio,video}) -Specify how strictly to follow the standards. - -Possible values: -@table @samp -@item very -strictly conform to a older more strict version of the spec or reference software -@item strict -strictly conform to all the things in the spec no matter what consequences -@item normal - -@item unofficial -allow unofficial extensions -@item experimental -allow non standardized experimental things -@end table - -@item b_qoffset @var{float} (@emph{encoding,video}) -Set QP offset between P and B frames. - -@item err_detect @var{flags} (@emph{decoding,audio,video}) -Set error detection flags. - -Possible values: -@table @samp -@item crccheck -verify embedded CRCs -@item bitstream -detect bitstream specification deviations -@item buffer -detect improper bitstream length -@item explode -abort decoding on minor error detection -@item careful -consider things that violate the spec and have not been seen in the wild as errors -@item compliant -consider all spec non compliancies as errors -@item aggressive -consider things that a sane encoder should not do as an error -@end table - -@item has_b_frames @var{integer} - -@item block_align @var{integer} - -@item mpeg_quant @var{integer} (@emph{encoding,video}) -Use MPEG quantizers instead of H.263. - -@item qsquish @var{float} (@emph{encoding,video}) -How to keep quantizer between qmin and qmax (0 = clip, 1 = use -differentiable function). - -@item rc_qmod_amp @var{float} (@emph{encoding,video}) -Set experimental quantizer modulation. - -@item rc_qmod_freq @var{integer} (@emph{encoding,video}) -Set experimental quantizer modulation. - -@item rc_override_count @var{integer} - -@item rc_eq @var{string} (@emph{encoding,video}) -Set rate control equation. When computing the expression, besides the -standard functions defined in the section 'Expression Evaluation', the -following functions are available: bits2qp(bits), qp2bits(qp). Also -the following constants are available: iTex pTex tex mv fCode iCount -mcVar var isI isP isB avgQP qComp avgIITex avgPITex avgPPTex avgBPTex -avgTex. - -@item maxrate @var{integer} (@emph{encoding,audio,video}) -Set max bitrate tolerance (in bits/s). Requires bufsize to be set. - -@item minrate @var{integer} (@emph{encoding,audio,video}) -Set min bitrate tolerance (in bits/s). Most useful in setting up a CBR -encode. It is of little use elsewise. - -@item bufsize @var{integer} (@emph{encoding,audio,video}) -Set ratecontrol buffer size (in bits). - -@item rc_buf_aggressivity @var{float} (@emph{encoding,video}) -Currently useless. - -@item i_qfactor @var{float} (@emph{encoding,video}) -Set QP factor between P and I frames. - -@item i_qoffset @var{float} (@emph{encoding,video}) -Set QP offset between P and I frames. - -@item rc_init_cplx @var{float} (@emph{encoding,video}) -Set initial complexity for 1-pass encoding. - -@item dct @var{integer} (@emph{encoding,video}) -Set DCT algorithm. - -Possible values: -@table @samp -@item auto -autoselect a good one (default) -@item fastint -fast integer -@item int -accurate integer -@item mmx - -@item altivec - -@item faan -floating point AAN DCT -@end table - -@item lumi_mask @var{float} (@emph{encoding,video}) -Compress bright areas stronger than medium ones. - -@item tcplx_mask @var{float} (@emph{encoding,video}) -Set temporal complexity masking. - -@item scplx_mask @var{float} (@emph{encoding,video}) -Set spatial complexity masking. - -@item p_mask @var{float} (@emph{encoding,video}) -Set inter masking. - -@item dark_mask @var{float} (@emph{encoding,video}) -Compress dark areas stronger than medium ones. - -@item idct @var{integer} (@emph{decoding/encoding,video}) -Select IDCT implementation. - -Possible values: -@table @samp -@item auto - -@item int - -@item simple - -@item simplemmx - -@item libmpeg2mmx - -@item mmi - -@item arm - -@item altivec - -@item sh4 - -@item simplearm - -@item simplearmv5te - -@item simplearmv6 - -@item simpleneon - -@item simplealpha - -@item h264 - -@item vp3 - -@item ipp - -@item xvidmmx - -@item faani -floating point AAN IDCT -@end table - -@item slice_count @var{integer} - -@item ec @var{flags} (@emph{decoding,video}) -Set error concealment strategy. - -Possible values: -@table @samp -@item guess_mvs -iterative motion vector (MV) search (slow) -@item deblock -use strong deblock filter for damaged MBs -@end table - -@item bits_per_coded_sample @var{integer} - -@item pred @var{integer} (@emph{encoding,video}) -Set prediction method. - -Possible values: -@table @samp -@item left - -@item plane - -@item median - -@end table - -@item aspect @var{rational number} (@emph{encoding,video}) -Set sample aspect ratio. - -@item debug @var{flags} (@emph{decoding/encoding,audio,video,subtitles}) -Print specific debug info. - -Possible values: -@table @samp -@item pict -picture info -@item rc -rate control -@item bitstream - -@item mb_type -macroblock (MB) type -@item qp -per-block quantization parameter (QP) -@item mv -motion vector -@item dct_coeff - -@item skip - -@item startcode - -@item pts - -@item er -error recognition -@item mmco -memory management control operations (H.264) -@item bugs - -@item vis_qp -visualize quantization parameter (QP), lower QP are tinted greener -@item vis_mb_type -visualize block types -@item buffers -picture buffer allocations -@item thread_ops -threading operations -@end table - -@item vismv @var{integer} (@emph{decoding,video}) -Visualize motion vectors (MVs). - -Possible values: -@table @samp -@item pf -forward predicted MVs of P-frames -@item bf -forward predicted MVs of B-frames -@item bb -backward predicted MVs of B-frames -@end table - -@item cmp @var{integer} (@emph{encoding,video}) -Set full pel me compare function. - -Possible values: -@table @samp -@item sad -sum of absolute differences, fast (default) -@item sse -sum of squared errors -@item satd -sum of absolute Hadamard transformed differences -@item dct -sum of absolute DCT transformed differences -@item psnr -sum of squared quantization errors (avoid, low quality) -@item bit -number of bits needed for the block -@item rd -rate distortion optimal, slow -@item zero -0 -@item vsad -sum of absolute vertical differences -@item vsse -sum of squared vertical differences -@item nsse -noise preserving sum of squared differences -@item w53 -5/3 wavelet, only used in snow -@item w97 -9/7 wavelet, only used in snow -@item dctmax - -@item chroma - -@end table - -@item subcmp @var{integer} (@emph{encoding,video}) -Set sub pel me compare function. - -Possible values: -@table @samp -@item sad -sum of absolute differences, fast (default) -@item sse -sum of squared errors -@item satd -sum of absolute Hadamard transformed differences -@item dct -sum of absolute DCT transformed differences -@item psnr -sum of squared quantization errors (avoid, low quality) -@item bit -number of bits needed for the block -@item rd -rate distortion optimal, slow -@item zero -0 -@item vsad -sum of absolute vertical differences -@item vsse -sum of squared vertical differences -@item nsse -noise preserving sum of squared differences -@item w53 -5/3 wavelet, only used in snow -@item w97 -9/7 wavelet, only used in snow -@item dctmax - -@item chroma - -@end table - -@item mbcmp @var{integer} (@emph{encoding,video}) -Set macroblock compare function. - -Possible values: -@table @samp -@item sad -sum of absolute differences, fast (default) -@item sse -sum of squared errors -@item satd -sum of absolute Hadamard transformed differences -@item dct -sum of absolute DCT transformed differences -@item psnr -sum of squared quantization errors (avoid, low quality) -@item bit -number of bits needed for the block -@item rd -rate distortion optimal, slow -@item zero -0 -@item vsad -sum of absolute vertical differences -@item vsse -sum of squared vertical differences -@item nsse -noise preserving sum of squared differences -@item w53 -5/3 wavelet, only used in snow -@item w97 -9/7 wavelet, only used in snow -@item dctmax - -@item chroma - -@end table - -@item ildctcmp @var{integer} (@emph{encoding,video}) -Set interlaced dct compare function. - -Possible values: -@table @samp -@item sad -sum of absolute differences, fast (default) -@item sse -sum of squared errors -@item satd -sum of absolute Hadamard transformed differences -@item dct -sum of absolute DCT transformed differences -@item psnr -sum of squared quantization errors (avoid, low quality) -@item bit -number of bits needed for the block -@item rd -rate distortion optimal, slow -@item zero -0 -@item vsad -sum of absolute vertical differences -@item vsse -sum of squared vertical differences -@item nsse -noise preserving sum of squared differences -@item w53 -5/3 wavelet, only used in snow -@item w97 -9/7 wavelet, only used in snow -@item dctmax - -@item chroma - -@end table - -@item dia_size @var{integer} (@emph{encoding,video}) -Set diamond type & size for motion estimation. - -@item last_pred @var{integer} (@emph{encoding,video}) -Set amount of motion predictors from the previous frame. - -@item preme @var{integer} (@emph{encoding,video}) -Set pre motion estimation. - -@item precmp @var{integer} (@emph{encoding,video}) -Set pre motion estimation compare function. - -Possible values: -@table @samp -@item sad -sum of absolute differences, fast (default) -@item sse -sum of squared errors -@item satd -sum of absolute Hadamard transformed differences -@item dct -sum of absolute DCT transformed differences -@item psnr -sum of squared quantization errors (avoid, low quality) -@item bit -number of bits needed for the block -@item rd -rate distortion optimal, slow -@item zero -0 -@item vsad -sum of absolute vertical differences -@item vsse -sum of squared vertical differences -@item nsse -noise preserving sum of squared differences -@item w53 -5/3 wavelet, only used in snow -@item w97 -9/7 wavelet, only used in snow -@item dctmax - -@item chroma - -@end table - -@item pre_dia_size @var{integer} (@emph{encoding,video}) -Set diamond type & size for motion estimation pre-pass. - -@item subq @var{integer} (@emph{encoding,video}) -Set sub pel motion estimation quality. - -@item dtg_active_format @var{integer} - -@item me_range @var{integer} (@emph{encoding,video}) -Set limit motion vectors range (1023 for DivX player). - -@item ibias @var{integer} (@emph{encoding,video}) -Set intra quant bias. - -@item pbias @var{integer} (@emph{encoding,video}) -Set inter quant bias. - -@item color_table_id @var{integer} - -@item global_quality @var{integer} (@emph{encoding,audio,video}) - -@item coder @var{integer} (@emph{encoding,video}) - -Possible values: -@table @samp -@item vlc -variable length coder / huffman coder -@item ac -arithmetic coder -@item raw -raw (no encoding) -@item rle -run-length coder -@item deflate -deflate-based coder -@end table - -@item context @var{integer} (@emph{encoding,video}) -Set context model. - -@item slice_flags @var{integer} - -@item xvmc_acceleration @var{integer} - -@item mbd @var{integer} (@emph{encoding,video}) -Set macroblock decision algorithm (high quality mode). - -Possible values: -@table @samp -@item simple -use mbcmp (default) -@item bits -use fewest bits -@item rd -use best rate distortion -@end table - -@item stream_codec_tag @var{integer} - -@item sc_threshold @var{integer} (@emph{encoding,video}) -Set scene change threshold. - -@item lmin @var{integer} (@emph{encoding,video}) -Set min lagrange factor (VBR). - -@item lmax @var{integer} (@emph{encoding,video}) -Set max lagrange factor (VBR). - -@item nr @var{integer} (@emph{encoding,video}) -Set noise reduction. - -@item rc_init_occupancy @var{integer} (@emph{encoding,video}) -Set number of bits which should be loaded into the rc buffer before -decoding starts. - -@item inter_threshold @var{integer} (@emph{encoding,video}) - -@item flags2 @var{flags} (@emph{decoding/encoding,audio,video}) - -Possible values: -@table @samp -@item fast -allow non spec compliant speedup tricks -@item sgop -Deprecated, use mpegvideo private options instead -@item noout -skip bitstream encoding -@item local_header -place global headers at every keyframe instead of in extradata -@item chunks -Frame data might be split into multiple chunks -@item showall -Show all frames before the first keyframe -@item skiprd -Deprecated, use mpegvideo private options instead -@end table - -@item error @var{integer} (@emph{encoding,video}) - -@item qns @var{integer} (@emph{encoding,video}) -Deprecated, use mpegvideo private options instead. - -@item threads @var{integer} (@emph{decoding/encoding,video}) - -Possible values: -@table @samp -@item auto -detect a good number of threads -@end table - -@item me_threshold @var{integer} (@emph{encoding,video}) -Set motion estimation threshold. - -@item mb_threshold @var{integer} (@emph{encoding,video}) -Set macroblock threshold. - -@item dc @var{integer} (@emph{encoding,video}) -Set intra_dc_precision. - -@item nssew @var{integer} (@emph{encoding,video}) -Set nsse weight. - -@item skip_top @var{integer} (@emph{decoding,video}) -Set number of macroblock rows at the top which are skipped. - -@item skip_bottom @var{integer} (@emph{decoding,video}) -Set number of macroblock rows at the bottom which are skipped. - -@item profile @var{integer} (@emph{encoding,audio,video}) - -Possible values: -@table @samp -@item unknown - -@item aac_main - -@item aac_low - -@item aac_ssr - -@item aac_ltp - -@item aac_he - -@item aac_he_v2 - -@item aac_ld - -@item aac_eld - -@item dts - -@item dts_es - -@item dts_96_24 - -@item dts_hd_hra - -@item dts_hd_ma - -@end table - -@item level @var{integer} (@emph{encoding,audio,video}) - -Possible values: -@table @samp -@item unknown - -@end table - -@item lowres @var{integer} (@emph{decoding,audio,video}) -Decode at 1= 1/2, 2=1/4, 3=1/8 resolutions. - -@item skip_threshold @var{integer} (@emph{encoding,video}) -Set frame skip threshold. - -@item skip_factor @var{integer} (@emph{encoding,video}) -Set frame skip factor. - -@item skip_exp @var{integer} (@emph{encoding,video}) -Set frame skip exponent. - -@item skipcmp @var{integer} (@emph{encoding,video}) -Set frame skip compare function. - -Possible values: -@table @samp -@item sad -sum of absolute differences, fast (default) -@item sse -sum of squared errors -@item satd -sum of absolute Hadamard transformed differences -@item dct -sum of absolute DCT transformed differences -@item psnr -sum of squared quantization errors (avoid, low quality) -@item bit -number of bits needed for the block -@item rd -rate distortion optimal, slow -@item zero -0 -@item vsad -sum of absolute vertical differences -@item vsse -sum of squared vertical differences -@item nsse -noise preserving sum of squared differences -@item w53 -5/3 wavelet, only used in snow -@item w97 -9/7 wavelet, only used in snow -@item dctmax - -@item chroma - -@end table - -@item border_mask @var{float} (@emph{encoding,video}) -Increase the quantizer for macroblocks close to borders. - -@item mblmin @var{integer} (@emph{encoding,video}) -Set min macroblock lagrange factor (VBR). - -@item mblmax @var{integer} (@emph{encoding,video}) -Set max macroblock lagrange factor (VBR). - -@item mepc @var{integer} (@emph{encoding,video}) -Set motion estimation bitrate penalty compensation (1.0 = 256). - -@item skip_loop_filter @var{integer} (@emph{decoding,video}) -@item skip_idct @var{integer} (@emph{decoding,video}) -@item skip_frame @var{integer} (@emph{decoding,video}) - -Make decoder discard processing depending on the frame type selected -by the option value. - -@option{skip_loop_filter} skips frame loop filtering, @option{skip_idct} -skips frame IDCT/dequantization, @option{skip_frame} skips decoding. - -Possible values: -@table @samp -@item none -Discard no frame. - -@item default -Discard useless frames like 0-sized frames. - -@item noref -Discard all non-reference frames. - -@item bidir -Discard all bidirectional frames. - -@item nokey -Discard all frames excepts keyframes. - -@item all -Discard all frames. -@end table - -Default value is @samp{default}. - -@item bidir_refine @var{integer} (@emph{encoding,video}) -Refine the two motion vectors used in bidirectional macroblocks. - -@item brd_scale @var{integer} (@emph{encoding,video}) -Downscale frames for dynamic B-frame decision. - -@item keyint_min @var{integer} (@emph{encoding,video}) -Set minimum interval between IDR-frames. - -@item refs @var{integer} (@emph{encoding,video}) -Set reference frames to consider for motion compensation. - -@item chromaoffset @var{integer} (@emph{encoding,video}) -Set chroma qp offset from luma. - -@item trellis @var{integer} (@emph{encoding,audio,video}) -Set rate-distortion optimal quantization. - -@item sc_factor @var{integer} (@emph{encoding,video}) -Set value multiplied by qscale for each frame and added to -scene_change_score. - -@item mv0_threshold @var{integer} (@emph{encoding,video}) -@item b_sensitivity @var{integer} (@emph{encoding,video}) -Adjust sensitivity of b_frame_strategy 1. - -@item compression_level @var{integer} (@emph{encoding,audio,video}) -@item min_prediction_order @var{integer} (@emph{encoding,audio}) -@item max_prediction_order @var{integer} (@emph{encoding,audio}) -@item timecode_frame_start @var{integer} (@emph{encoding,video}) -Set GOP timecode frame start number, in non drop frame format. - -@item request_channels @var{integer} (@emph{decoding,audio}) -Set desired number of audio channels. - -@item bits_per_raw_sample @var{integer} -@item channel_layout @var{integer} (@emph{decoding/encoding,audio}) - -Possible values: -@table @samp -@end table -@item request_channel_layout @var{integer} (@emph{decoding,audio}) - -Possible values: -@table @samp -@end table -@item rc_max_vbv_use @var{float} (@emph{encoding,video}) -@item rc_min_vbv_use @var{float} (@emph{encoding,video}) -@item ticks_per_frame @var{integer} (@emph{decoding/encoding,audio,video}) -@item color_primaries @var{integer} (@emph{decoding/encoding,video}) -@item color_trc @var{integer} (@emph{decoding/encoding,video}) -@item colorspace @var{integer} (@emph{decoding/encoding,video}) -@item color_range @var{integer} (@emph{decoding/encoding,video}) -@item chroma_sample_location @var{integer} (@emph{decoding/encoding,video}) - -@item log_level_offset @var{integer} -Set the log level offset. - -@item slices @var{integer} (@emph{encoding,video}) -Number of slices, used in parallelized encoding. - -@item thread_type @var{flags} (@emph{decoding/encoding,video}) -Select multithreading type. - -Possible values: -@table @samp -@item slice - -@item frame - -@end table -@item audio_service_type @var{integer} (@emph{encoding,audio}) -Set audio service type. - -Possible values: -@table @samp -@item ma -Main Audio Service -@item ef -Effects -@item vi -Visually Impaired -@item hi -Hearing Impaired -@item di -Dialogue -@item co -Commentary -@item em -Emergency -@item vo -Voice Over -@item ka -Karaoke -@end table - -@item request_sample_fmt @var{sample_fmt} (@emph{decoding,audio}) -Set sample format audio decoders should prefer. Default value is -@code{none}. - -@item pkt_timebase @var{rational number} - -@item sub_charenc @var{encoding} (@emph{decoding,subtitles}) -Set the input subtitles character encoding. -@end table - -@c man end CODEC OPTIONS - -@include decoders.texi -@include encoders.texi +@include codecs.texi @chapter See Also diff --git a/ffmpeg/doc/ffmpeg-devices.texi b/ffmpeg/doc/ffmpeg-devices.texi index 9e004d5..b44bd72 100644 --- a/ffmpeg/doc/ffmpeg-devices.texi +++ b/ffmpeg/doc/ffmpeg-devices.texi @@ -17,27 +17,7 @@ libavdevice library. @c man end DESCRIPTION -@chapter Device Options -@c man begin DEVICE OPTIONS - -The libavdevice library provides the same interface as -libavformat. Namely, an input device is considered like a demuxer, and -an output device like a muxer, and the interface and generic device -options are the same provided by libavformat (see the ffmpeg-formats -manual). - -In addition each input or output device may support so-called private -options, which are specific for that component. - -Options may be set by specifying -@var{option} @var{value} in the -FFmpeg tools, or by setting the value explicitly in the device -@code{AVFormatContext} options or using the @file{libavutil/opt.h} API -for programmatic use. - -@c man end DEVICE OPTIONS - -@include indevs.texi -@include outdevs.texi +@include devices.texi @chapter See Also diff --git a/ffmpeg/doc/ffmpeg-formats.texi b/ffmpeg/doc/ffmpeg-formats.texi index db9215c..e205caa 100644 --- a/ffmpeg/doc/ffmpeg-formats.texi +++ b/ffmpeg/doc/ffmpeg-formats.texi @@ -17,147 +17,7 @@ provided by the libavformat library. @c man end DESCRIPTION -@chapter Format Options -@c man begin FORMAT OPTIONS - -The libavformat library provides some generic global options, which -can be set on all the muxers and demuxers. In addition each muxer or -demuxer may support so-called private options, which are specific for -that component. - -Options may be set by specifying -@var{option} @var{value} in the -FFmpeg tools, or by setting the value explicitly in the -@code{AVFormatContext} options or using the @file{libavutil/opt.h} API -for programmatic use. - -The list of supported options follows: - -@table @option -@item avioflags @var{flags} (@emph{input/output}) -Possible values: -@table @samp -@item direct -Reduce buffering. -@end table - -@item probesize @var{integer} (@emph{input}) -Set probing size in bytes, i.e. the size of the data to analyze to get -stream information. A higher value will allow to detect more -information in case it is dispersed into the stream, but will increase -latency. Must be an integer not lesser than 32. It is 5000000 by default. - -@item packetsize @var{integer} (@emph{output}) -Set packet size. - -@item fflags @var{flags} (@emph{input/output}) -Set format flags. - -Possible values: -@table @samp -@item ignidx -Ignore index. -@item genpts -Generate PTS. -@item nofillin -Do not fill in missing values that can be exactly calculated. -@item noparse -Disable AVParsers, this needs @code{+nofillin} too. -@item igndts -Ignore DTS. -@item discardcorrupt -Discard corrupted frames. -@item sortdts -Try to interleave output packets by DTS. -@item keepside -Do not merge side data. -@item latm -Enable RTP MP4A-LATM payload. -@item nobuffer -Reduce the latency introduced by optional buffering -@end table - -@item analyzeduration @var{integer} (@emph{input}) -Specify how many microseconds are analyzed to probe the input. A -higher value will allow to detect more accurate information, but will -increase latency. It defaults to 5,000,000 microseconds = 5 seconds. - -@item cryptokey @var{hexadecimal string} (@emph{input}) -Set decryption key. - -@item indexmem @var{integer} (@emph{input}) -Set max memory used for timestamp index (per stream). - -@item rtbufsize @var{integer} (@emph{input}) -Set max memory used for buffering real-time frames. - -@item fdebug @var{flags} (@emph{input/output}) -Print specific debug info. - -Possible values: -@table @samp -@item ts -@end table - -@item max_delay @var{integer} (@emph{input/output}) -Set maximum muxing or demuxing delay in microseconds. - -@item fpsprobesize @var{integer} (@emph{input}) -Set number of frames used to probe fps. - -@item audio_preload @var{integer} (@emph{output}) -Set microseconds by which audio packets should be interleaved earlier. - -@item chunk_duration @var{integer} (@emph{output}) -Set microseconds for each chunk. - -@item chunk_size @var{integer} (@emph{output}) -Set size in bytes for each chunk. - -@item err_detect, f_err_detect @var{flags} (@emph{input}) -Set error detection flags. @code{f_err_detect} is deprecated and -should be used only via the @command{ffmpeg} tool. - -Possible values: -@table @samp -@item crccheck -Verify embedded CRCs. -@item bitstream -Detect bitstream specification deviations. -@item buffer -Detect improper bitstream length. -@item explode -Abort decoding on minor error detection. -@item careful -Consider things that violate the spec and have not been seen in the -wild as errors. -@item compliant -Consider all spec non compliancies as errors. -@item aggressive -Consider things that a sane encoder should not do as an error. -@end table - -@item use_wallclock_as_timestamps @var{integer} (@emph{input}) -Use wallclock as timestamps. - -@item avoid_negative_ts @var{integer} (@emph{output}) -Shift timestamps to make them positive. A value of 1 enables shifting, -a value of 0 disables it, the default value of -1 enables shifting -when required by the target format. - -When shifting is enabled, all output timestamps are shifted by the -same amount. Audio, video, and subtitles desynching and relative -timestamp differences are preserved compared to how they would have -been without shifting. - -Also note that this affects only leading negative timestamps, and not -non-monotonic negative timestamps. -@end table - -@c man end FORMAT OPTIONS - -@include demuxers.texi -@include muxers.texi -@include metadata.texi +@include formats.texi @chapter See Also diff --git a/ffmpeg/doc/ffmpeg-resampler.texi b/ffmpeg/doc/ffmpeg-resampler.texi index 525907a..69767a2 100644 --- a/ffmpeg/doc/ffmpeg-resampler.texi +++ b/ffmpeg/doc/ffmpeg-resampler.texi @@ -12,235 +12,14 @@ @chapter Description @c man begin DESCRIPTION -The FFmpeg resampler provides an high-level interface to the +The FFmpeg resampler provides a high-level interface to the libswresample library audio resampling utilities. In particular it allows to perform audio resampling, audio channel layout rematrixing, and convert audio format and packing layout. @c man end DESCRIPTION -@chapter Resampler Options -@c man begin RESAMPLER OPTIONS - -The audio resampler supports the following named options. - -Options may be set by specifying -@var{option} @var{value} in the -FFmpeg tools, @var{option}=@var{value} for the aresample filter, -by setting the value explicitly in the -@code{SwrContext} options or using the @file{libavutil/opt.h} API for -programmatic use. - -@table @option - -@item ich, in_channel_count -Set the number of input channels. Default value is 0. Setting this -value is not mandatory if the corresponding channel layout -@option{in_channel_layout} is set. - -@item och, out_channel_count -Set the number of output channels. Default value is 0. Setting this -value is not mandatory if the corresponding channel layout -@option{out_channel_layout} is set. - -@item uch, used_channel_count -Set the number of used input channels. Default value is 0. This option is -only used for special remapping. - -@item isr, in_sample_rate -Set the input sample rate. Default value is 0. - -@item osr, out_sample_rate -Set the output sample rate. Default value is 0. - -@item isf, in_sample_fmt -Specify the input sample format. It is set by default to @code{none}. - -@item osf, out_sample_fmt -Specify the output sample format. It is set by default to @code{none}. - -@item tsf, internal_sample_fmt -Set the internal sample format. Default value is @code{none}. -This will automatically be chosen when it is not explicitly set. - -@item icl, in_channel_layout -Set the input channel layout. - -@item ocl, out_channel_layout -Set the output channel layout. - -@item clev, center_mix_level -Set the center mix level. It is a value expressed in deciBel, and must be -in the interval [-32,32]. - -@item slev, surround_mix_level -Set the surround mix level. It is a value expressed in deciBel, and must -be in the interval [-32,32]. - -@item lfe_mix_level -Set LFE mix into non LFE level. It is used when there is a LFE input but no -LFE output. It is a value expressed in deciBel, and must -be in the interval [-32,32]. - -@item rmvol, rematrix_volume -Set rematrix volume. Default value is 1.0. - -@item flags, swr_flags -Set flags used by the converter. Default value is 0. - -It supports the following individual flags: -@table @option -@item res -force resampling, this flag forces resampling to be used even when the -input and output sample rates match. -@end table - -@item dither_scale -Set the dither scale. Default value is 1. - -@item dither_method -Set dither method. Default value is 0. - -Supported values: -@table @samp -@item rectangular -select rectangular dither -@item triangular -select triangular dither -@item triangular_hp -select triangular dither with high pass -@item lipshitz -select lipshitz noise shaping dither -@item shibata -select shibata noise shaping dither -@item low_shibata -select low shibata noise shaping dither -@item high_shibata -select high shibata noise shaping dither -@item f_weighted -select f-weighted noise shaping dither -@item modified_e_weighted -select modified-e-weighted noise shaping dither -@item improved_e_weighted -select improved-e-weighted noise shaping dither - -@end table - -@item resampler -Set resampling engine. Default value is swr. - -Supported values: -@table @samp -@item swr -select the native SW Resampler; filter options precision and cheby are not -applicable in this case. -@item soxr -select the SoX Resampler (where available); compensation, and filter options -filter_size, phase_shift, filter_type & kaiser_beta, are not applicable in this -case. -@end table - -@item filter_size -For swr only, set resampling filter size, default value is 32. - -@item phase_shift -For swr only, set resampling phase shift, default value is 10, and must be in -the interval [0,30]. - -@item linear_interp -Use Linear Interpolation if set to 1, default value is 0. - -@item cutoff -Set cutoff frequency (swr: 6dB point; soxr: 0dB point) ratio; must be a float -value between 0 and 1. Default value is 0.97 with swr, and 0.91 with soxr -(which, with a sample-rate of 44100, preserves the entire audio band to 20kHz). - -@item precision -For soxr only, the precision in bits to which the resampled signal will be -calculated. The default value of 20 (which, with suitable dithering, is -appropriate for a destination bit-depth of 16) gives SoX's 'High Quality'; a -value of 28 gives SoX's 'Very High Quality'. - -@item cheby -For soxr only, selects passband rolloff none (Chebyshev) & higher-precision -approximation for 'irrational' ratios. Default value is 0. - -@item async -For swr only, simple 1 parameter audio sync to timestamps using stretching, -squeezing, filling and trimming. Setting this to 1 will enable filling and -trimming, larger values represent the maximum amount in samples that the data -may be stretched or squeezed for each second. -Default value is 0, thus no compensation is applied to make the samples match -the audio timestamps. - -@item first_pts -For swr only, assume the first pts should be this value. The time unit is 1 / sample rate. -This allows for padding/trimming at the start of stream. By default, no -assumption is made about the first frame's expected pts, so no padding or -trimming is done. For example, this could be set to 0 to pad the beginning with -silence if an audio stream starts after the video stream or to trim any samples -with a negative pts due to encoder delay. - -@item min_comp -For swr only, set the minimum difference between timestamps and audio data (in -seconds) to trigger stretching/squeezing/filling or trimming of the -data to make it match the timestamps. The default is that -stretching/squeezing/filling and trimming is disabled -(@option{min_comp} = @code{FLT_MAX}). - -@item min_hard_comp -For swr only, set the minimum difference between timestamps and audio data (in -seconds) to trigger adding/dropping samples to make it match the -timestamps. This option effectively is a threshold to select between -hard (trim/fill) and soft (squeeze/stretch) compensation. Note that -all compensation is by default disabled through @option{min_comp}. -The default is 0.1. - -@item comp_duration -For swr only, 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. - -@item max_soft_comp -For swr only, 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. - -@item matrix_encoding -Select matrixed stereo encoding. - -It accepts the following values: -@table @samp -@item none -select none -@item dolby -select Dolby -@item dplii -select Dolby Pro Logic II -@end table - -Default value is @code{none}. - -@item filter_type -For swr only, select resampling filter type. This only affects resampling -operations. - -It accepts the following values: -@table @samp -@item cubic -select cubic -@item blackman_nuttall -select Blackman Nuttall Windowed Sinc -@item kaiser -select Kaiser Windowed Sinc -@end table - -@item kaiser_beta -For swr only, set Kaiser Window Beta value. Must be an integer in the -interval [2,16], default value is 9. - -@end table - -@c man end RESAMPLER OPTIONS +@include resampler.texi @chapter See Also diff --git a/ffmpeg/doc/ffmpeg-scaler.texi b/ffmpeg/doc/ffmpeg-scaler.texi index 1110c69..1eb8cd6 100644 --- a/ffmpeg/doc/ffmpeg-scaler.texi +++ b/ffmpeg/doc/ffmpeg-scaler.texi @@ -12,111 +12,13 @@ @chapter Description @c man begin DESCRIPTION -The FFmpeg rescaler provides an high-level interface to the libswscale +The FFmpeg rescaler provides a high-level interface to the libswscale library image conversion utilities. In particular it allows to perform image rescaling and pixel format conversion. @c man end DESCRIPTION -@chapter Scaler Options -@c man begin SCALER OPTIONS - -The video scaler supports the following named options. - -Options may be set by specifying -@var{option} @var{value} in the -FFmpeg tools. For programmatic use, they can be set explicitly in the -@code{SwsContext} options or through the @file{libavutil/opt.h} API. - -@table @option - -@item sws_flags -Set the scaler flags. This is also used to set the scaling -algorithm. Only a single algorithm should be selected. - -It accepts the following values: -@table @samp -@item fast_bilinear -Select fast bilinear scaling algorithm. - -@item bilinear -Select bilinear scaling algorithm. - -@item bicubic -Select bicubic scaling algorithm. - -@item experimental -Select experimental scaling algorithm. - -@item neighbor -Select nearest neighbor rescaling algorithm. - -@item area -Select averaging area rescaling algorithm. - -@item bicubiclin -Select bicubic scaling algorithm for the luma component, bilinear for -chroma components. - -@item gauss -Select Gaussian rescaling algorithm. - -@item sinc -Select sinc rescaling algorithm. - -@item lanczos -Select lanczos rescaling algorithm. - -@item spline -Select natural bicubic spline rescaling algorithm. - -@item print_info -Enable printing/debug logging. - -@item accurate_rnd -Enable accurate rounding. - -@item full_chroma_int -Enable full chroma interpolation. - -@item full_chroma_inp -Select full chroma input. - -@item bitexact -Enable bitexact output. -@end table - -@item srcw -Set source width. - -@item srch -Set source height. - -@item dstw -Set destination width. - -@item dsth -Set destination height. - -@item src_format -Set source pixel format (must be expressed as an integer). - -@item dst_format -Set destination pixel format (must be expressed as an integer). - -@item src_range -Select source range. - -@item dst_range -Select destination range. - -@item param0, param1 -Set scaling algorithm parameters. The specified values are specific of -some scaling algorithms and ignored by others. The specified values -are floating point number values. - -@end table - -@c man end SCALER OPTIONS +@include scaler.texi @chapter See Also diff --git a/ffmpeg/doc/ffmpeg-utils.texi b/ffmpeg/doc/ffmpeg-utils.texi index c5822a8..581e2ea 100644 --- a/ffmpeg/doc/ffmpeg-utils.texi +++ b/ffmpeg/doc/ffmpeg-utils.texi @@ -17,8 +17,7 @@ by the libavutil library. @c man end DESCRIPTION -@include syntax.texi -@include eval.texi +@include utils.texi @chapter See Also diff --git a/ffmpeg/doc/ffmpeg.texi b/ffmpeg/doc/ffmpeg.texi index ca5d652..0a930ce 100644 --- a/ffmpeg/doc/ffmpeg.texi +++ b/ffmpeg/doc/ffmpeg.texi @@ -16,26 +16,26 @@ ffmpeg [@var{global_options}] @{[@var{input_file_options}] -i @file{input_file}@ @chapter Description @c man begin DESCRIPTION -ffmpeg is a very fast video and audio converter that can also grab from +@command{ffmpeg} is a very fast video and audio converter that can also grab from a live audio/video source. It can also convert between arbitrary sample rates and resize video on the fly with a high quality polyphase filter. -ffmpeg reads from an arbitrary number of input "files" (which can be regular +@command{ffmpeg} reads from an arbitrary number of input "files" (which can be regular files, pipes, network streams, grabbing devices, etc.), specified by the @code{-i} option, and writes to an arbitrary number of output "files", which are specified by a plain output filename. Anything found on the command line which cannot be interpreted as an option is considered to be an output filename. -Each input or output file can in principle contain any number of streams of -different types (video/audio/subtitle/attachment/data). Allowed number and/or -types of streams can be limited by the container format. Selecting, which -streams from which inputs go into output, is done either automatically or with -the @code{-map} option (see the Stream selection chapter). +Each input or output file can, in principle, contain any number of streams of +different types (video/audio/subtitle/attachment/data). The allowed number and/or +types of streams may be limited by the container format. Selecting which +streams from which inputs will go into which output is either done automatically +or with the @code{-map} option (see the Stream selection chapter). To refer to input files in options, you must use their indices (0-based). E.g. -the first input file is @code{0}, the second is @code{1} etc. Similarly, streams +the first input file is @code{0}, the second is @code{1}, etc. Similarly, streams within a file are referred to by their indices. E.g. @code{2:3} refers to the -fourth stream in the third input file. See also the Stream specifiers chapter. +fourth stream in the third input file. Also see the Stream specifiers chapter. As a general rule, options are applied to the next specified file. Therefore, order is important, and you can have the same @@ -50,7 +50,7 @@ options apply ONLY to the next input or output file and are reset between files. @itemize @item -To set the video bitrate of the output file to 64kbit/s: +To set the video bitrate of the output file to 64 kbit/s: @example ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi @end example @@ -96,14 +96,14 @@ tracking lowest timestamp on any active input stream. Encoded packets are then passed to the decoder (unless streamcopy is selected for the stream, see further for a description). The decoder produces uncompressed frames (raw video/PCM audio/...) which can be processed further by -filtering (see next section). After filtering the frames are passed to the -encoder, which encodes them and outputs encoded packets again. Finally those are +filtering (see next section). After filtering, the frames are passed to the +encoder, which encodes them and outputs encoded packets. Finally those are passed to the muxer, which writes the encoded packets to the output file. @section Filtering Before encoding, @command{ffmpeg} can process raw audio and video frames using filters from the libavfilter library. Several chained filters form a filter -graph. @command{ffmpeg} distinguishes between two types of filtergraphs - +graph. @command{ffmpeg} distinguishes between two types of filtergraphs: simple and complex. @subsection Simple filtergraphs @@ -139,7 +139,7 @@ only sets timestamps and otherwise passes the frames unchanged. @subsection Complex filtergraphs Complex filtergraphs are those which cannot be described as simply a linear -processing chain applied to one stream. This is the case e.g. when the graph has +processing chain applied to one stream. This is the case, for example, when the graph has more than one input and/or output, or when output stream type is different from input. They can be represented with the following diagram: @@ -164,7 +164,7 @@ input. They can be represented with the following diagram: @end example Complex filtergraphs are configured with the @option{-filter_complex} option. -Note that this option is global, since a complex filtergraph by its nature +Note that this option is global, since a complex filtergraph, by its nature, cannot be unambiguously associated with a single stream or file. The @option{-lavfi} option is equivalent to @option{-filter_complex}. @@ -178,7 +178,7 @@ Stream copy is a mode selected by supplying the @code{copy} parameter to the @option{-codec} option. It makes @command{ffmpeg} omit the decoding and encoding step for the specified stream, so it does only demuxing and muxing. It is useful for changing the container format or modifying container-level metadata. The -diagram above will in this case simplify to this: +diagram above will, in this case, simplify to this: @example _______ ______________ ________ @@ -190,7 +190,7 @@ diagram above will in this case simplify to this: @end example Since there is no decoding or encoding, it is very fast and there is no quality -loss. However it might not work in some cases because of many factors. Applying +loss. However, it might not work in some cases because of many factors. Applying filters is obviously also impossible, since filters work on uncompressed data. @c man end DETAILED DESCRIPTION @@ -198,14 +198,14 @@ filters is obviously also impossible, since filters work on uncompressed data. @chapter Stream selection @c man begin STREAM SELECTION -By default ffmpeg includes only one stream of each type (video, audio, subtitle) +By default, @command{ffmpeg} includes only one stream of each type (video, audio, subtitle) present in the input files and adds them to each output file. It picks the -"best" of each based upon the following criteria; for video it is the stream -with the highest resolution, for audio the stream with the most channels, for -subtitle it's the first subtitle stream. In the case where several streams of -the same type rate equally, the lowest numbered stream is chosen. +"best" of each based upon the following criteria: for video, it is the stream +with the highest resolution, for audio, it is the stream with the most channels, for +subtitles, it is the first subtitle stream. In the case where several streams of +the same type rate equally, the stream with the lowest index is chosen. -You can disable some of those defaults by using @code{-vn/-an/-sn} options. For +You can disable some of those defaults by using the @code{-vn/-an/-sn} options. For full manual control, use the @code{-map} option, which disables the defaults just described. @@ -214,7 +214,7 @@ described. @chapter Options @c man begin OPTIONS -@include avtools-common-opts.texi +@include fftools-common-opts.texi @section Main options @@ -222,7 +222,7 @@ described. @item -f @var{fmt} (@emph{input/output}) Force input or output file format. The format is normally auto detected for input -files and guessed from file extension for output files, so this option is not +files and guessed from the file extension for output files, so this option is not needed in most cases. @item -i @var{filename} (@emph{input}) @@ -232,7 +232,8 @@ input file name Overwrite output files without asking. @item -n (@emph{global}) -Do not overwrite output files but exit if file exists. +Do not overwrite output files, and exit immediately if a specified +output file already exists. @item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream}) @itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream}) @@ -271,9 +272,15 @@ Set the file size limit, expressed in bytes. @item -ss @var{position} (@emph{input/output}) When used as an input option (before @code{-i}), seeks in this input file to -@var{position}. When used as an output option (before an output filename), -decodes but discards input until the timestamps reach @var{position}. This is -slower, but more accurate. +@var{position}. Note the in most formats it is not possible to seek exactly, so +@command{ffmpeg} will seek to the closest seek point before @var{position}. +When transcoding and @option{-accurate_seek} is enabled (the default), this +extra segment between the seek point and @var{position} will be decoded and +discarded. When doing stream copy or when @option{-noaccurate_seek} is used, it +will be preserved. + +When used as an output option (before an output filename), decodes but discards +input until the timestamps reach @var{position}. @var{position} may be either in seconds or in @code{hh:mm:ss[.xxx]} form. @@ -341,23 +348,33 @@ Stop writing to the stream after @var{framecount} frames. @item -q[:@var{stream_specifier}] @var{q} (@emph{output,per-stream}) @itemx -qscale[:@var{stream_specifier}] @var{q} (@emph{output,per-stream}) -Use fixed quality scale (VBR). The meaning of @var{q} is +Use fixed quality scale (VBR). The meaning of @var{q}/@var{qscale} is codec-dependent. +If @var{qscale} is used without a @var{stream_specifier} then it applies only +to the video stream, this is to maintain compatibility with previous behavior +and as specifying the same codec specific value to 2 different codecs that is +audio and video generally is not what is intended when no stream_specifier is +used. @anchor{filter_option} -@item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream}) -Create the filter graph specified by @var{filter_graph} and use it to +@item -filter[:@var{stream_specifier}] @var{filtergraph} (@emph{output,per-stream}) +Create the filtergraph specified by @var{filtergraph} and use it to filter the stream. -@var{filter_graph} is a description of the filter graph to apply to +@var{filtergraph} is a description of the filtergraph to apply to the stream, and must have a single input and a single output of the -same type of the stream. In the filter graph, the input is associated +same type of the stream. In the filtergraph, the input is associated to the label @code{in}, and the output to the label @code{out}. See the ffmpeg-filters manual for more information about the filtergraph syntax. See the @ref{filter_complex_option,,-filter_complex option} if you -want to create filter graphs with multiple inputs and/or outputs. +want to create filtergraphs with multiple inputs and/or outputs. + +@item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream}) +This option is similar to @option{-filter}, the only difference is that its +argument is the name of the file from which a filtergraph description is to be +read. @item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream}) Specify the preset for matching stream(s). @@ -462,6 +479,10 @@ form @var{num}:@var{den}, where @var{num} and @var{den} are the numerator and denominator of the aspect ratio. For example "4:3", "16:9", "1.3333", and "1.7777" are valid argument values. +If used together with @option{-vcodec copy}, it will affect the aspect ratio +stored at container level, but not the aspect ratio stored in encoded +frames, if it exists. + @item -vn (@emph{output}) Disable video recording. @@ -490,8 +511,8 @@ stream @item -vlang @var{code} Set the ISO 639 language code (3 letters) of the current video stream. -@item -vf @var{filter_graph} (@emph{output}) -Create the filter graph specified by @var{filter_graph} and use it to +@item -vf @var{filtergraph} (@emph{output}) +Create the filtergraph specified by @var{filtergraph} and use it to filter the stream. This is an alias for @code{-filter:v}, see the @ref{filter_option,,-filter option}. @@ -507,7 +528,7 @@ If the selected pixel format can not be selected, ffmpeg will print a warning and select the best pixel format supported by the encoder. If @var{pix_fmt} is prefixed by a @code{+}, ffmpeg will exit with an error if the requested pixel format can not be selected, and automatic conversions -inside filter graphs are disabled. +inside filtergraphs are disabled. If @var{pix_fmt} is a single @code{+}, ffmpeg selects the same pixel format as the input (or graph output) and automatic conversions are disabled. @@ -522,10 +543,6 @@ list separated with slashes. Two first values are the beginning and end frame numbers, last one is quantizer to use if positive, or quality factor if negative. -@item -deinterlace -Deinterlace pictures. -This option is deprecated since the deinterlacing is very low quality. -Use the yadif filter with @code{-filter:v yadif}. @item -ilme Force interlacing support in encoder (MPEG-2 and MPEG-4 only). Use this option if your input file is interlaced and you want @@ -604,6 +621,42 @@ would be more efficient. @item -copyinkf[:@var{stream_specifier}] (@emph{output,per-stream}) When doing stream copy, copy also non-key frames found at the beginning. + +@item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream}) +Use hardware acceleration to decode the matching stream(s). The allowed values +of @var{hwaccel} are: +@table @option +@item none +Do not use any hardware acceleration (the default). + +@item auto +Automatically select the hardware acceleration method. + +@item vdpau +Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration. +@end table + +This option has no effect if the selected hwaccel is not available or not +supported by the chosen decoder. + +Note that most acceleration methods are intended for playback and will not be +faster than software decoding on modern CPUs. Additionally, @command{ffmpeg} +will usually need to copy the decoded frames from the GPU memory into the system +memory, resulting in further performance loss. This option is thus mainly +useful for testing. + +@item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream}) +Select a device to use for hardware acceleration. + +This option only makes sense when the @option{-hwaccel} option is also +specified. Its exact meaning depends on the specific hardware acceleration +method chosen. + +@table @option +@item vdpau +For VDPAU, this option specifies the X11 display/screen to use. If this option +is not specified, the value of the @var{DISPLAY} environment variable is used +@end table @end table @section Audio Options @@ -631,8 +684,8 @@ Set the audio codec. This is an alias for @code{-codec:a}. Set the audio sample format. Use @code{-sample_fmts} to get a list of supported sample formats. -@item -af @var{filter_graph} (@emph{output}) -Create the filter graph specified by @var{filter_graph} and use it to +@item -af @var{filtergraph} (@emph{output}) +Create the filtergraph specified by @var{filtergraph} and use it to filter the stream. This is an alias for @code{-filter:a}, see the @ref{filter_option,,-filter option}. @@ -865,13 +918,12 @@ Dump each input packet to stderr. When dumping packets, also dump the payload. @item -re (@emph{input}) Read input at native frame rate. Mainly used to simulate a grab device. +or live input stream (e.g. when reading from a file). Should not be used +with actual grab devices or live input streams (where it can cause packet +loss). By default @command{ffmpeg} attempts to read the input(s) as fast as possible. This option will slow down the reading of the input(s) to the native frame rate -of the input(s). It is useful for real-time output (e.g. live streaming). If -your input(s) is coming from some other live streaming source (through HTTP or -UDP for example) the server might already be in real-time, thus the option will -likely not be required. On the other hand, this is meaningful if your input(s) -is a file you are trying to push in real-time. +of the input(s). It is useful for real-time output (e.g. live streaming). @item -loop_input Loop over the input stream. Currently it works only for image streams. This option is used for automatic FFserver testing. @@ -890,7 +942,7 @@ Newly added values will have to be specified as strings always. Each frame is passed with its timestamp from the demuxer to the muxer. @item 1, cfr Frames will be duplicated and dropped to achieve exactly the requested -constant framerate. +constant frame rate. @item 2, vfr Frames are passed through with their timestamp or dropped so as to prevent 2 frames from having the same timestamp. @@ -999,10 +1051,10 @@ ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg @anchor{filter_complex_option} @item -filter_complex @var{filtergraph} (@emph{global}) -Define a complex filter graph, i.e. one with arbitrary number of inputs and/or +Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or outputs. For simple graphs -- those with one input and one output of the same type -- see the @option{-filter} options. @var{filtergraph} is a description of -the filter graph, as described in the ``Filtergraph syntax'' section of the +the filtergraph, as described in the ``Filtergraph syntax'' section of the ffmpeg-filters manual. Input link labels must refer to input streams using the @@ -1046,9 +1098,30 @@ ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv @end example @item -lavfi @var{filtergraph} (@emph{global}) -Define a complex filter graph, i.e. one with arbitrary number of inputs and/or +Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or outputs. Equivalent to @option{-filter_complex}. +@item -filter_complex_script @var{filename} (@emph{global}) +This option is similar to @option{-filter_complex}, the only difference is that +its argument is the name of the file from which a complex filtergraph +description is to be read. + +@item -accurate_seek (@emph{input}) +This option enables or disables accurate seeking in input files with the +@option{-ss} option. It is enabled by default, so seeking is accurate when +transcoding. Use @option{-noaccurate_seek} to disable it, which may be useful +e.g. when copying some streams and transcoding the others. + +@item -override_ffserver (@emph{global}) +Overrides the input specifications from @command{ffserver}. Using this +option you can map any input stream to @command{ffserver} and control +many aspects of the encoding from @command{ffmpeg}. Without this +option @command{ffmpeg} will transmit to @command{ffserver} what is +requested by @command{ffserver}. + +The option is intended for cases where features are needed that cannot be +specified to @command{ffserver} but can be to @command{ffmpeg}. + @end table As a special exception, you can use a bitmap subtitle stream as input: it @@ -1106,7 +1179,7 @@ then it will search for the file @file{libvpx-1080p.ffpreset}. @itemize @item -For streaming at very low bitrate application, use a low frame rate +For streaming at very low bitrates, use a low frame rate and a small GOP size. This is especially true for RealVideo where the Linux player does not seem to be very fast, so it can miss frames. An example is: @@ -1185,14 +1258,14 @@ standard mixer. Grab the X11 display with ffmpeg via @example -ffmpeg -f x11grab -s cif -r 25 -i :0.0 /tmp/out.mpg +ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0 /tmp/out.mpg @end example 0.0 is display.screen number of your X11 server, same as the DISPLAY environment variable. @example -ffmpeg -f x11grab -s cif -r 25 -i :0.0+10,20 /tmp/out.mpg +ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0+10,20 /tmp/out.mpg @end example 0.0 is display.screen number of your X11 server, same as the DISPLAY environment @@ -1351,9 +1424,42 @@ ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext @end itemize @c man end EXAMPLES +@include config.texi +@ifset config-all +@ifset config-avutil +@include utils.texi +@end ifset +@ifset config-avcodec +@include codecs.texi +@include bitstream_filters.texi +@end ifset +@ifset config-avformat +@include formats.texi +@include protocols.texi +@end ifset +@ifset config-avdevice +@include devices.texi +@end ifset +@ifset config-swresample +@include resampler.texi +@end ifset +@ifset config-swscale +@include scaler.texi +@end ifset +@ifset config-avfilter +@include filters.texi +@end ifset +@end ifset + @chapter See Also @ifhtml +@ifset config-all +@url{ffmpeg.html,ffmpeg} +@end ifset +@ifset config-not-all +@url{ffmpeg-all.html,ffmpeg-all}, +@end ifset @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe}, @url{ffserver.html,ffserver}, @url{ffmpeg-utils.html,ffmpeg-utils}, @url{ffmpeg-scaler.html,ffmpeg-scaler}, @@ -1367,6 +1473,12 @@ ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext @end ifhtml @ifnothtml +@ifset config-all +ffmpeg(1), +@end ifset +@ifset config-not-all +ffmpeg-all(1), +@end ifset ffplay(1), ffprobe(1), ffserver(1), ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1), ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1), diff --git a/ffmpeg/doc/ffplay.texi b/ffmpeg/doc/ffplay.texi index ee160a0..54b6f19 100644 --- a/ffmpeg/doc/ffplay.texi +++ b/ffmpeg/doc/ffplay.texi @@ -24,7 +24,7 @@ various FFmpeg APIs. @chapter Options @c man begin OPTIONS -@include avtools-common-opts.texi +@include fftools-common-opts.texi @section Main options @@ -73,19 +73,19 @@ Default value is "video", if video is not present or cannot be played You can interactively cycle through the available show modes by pressing the key @key{w}. -@item -vf @var{filter_graph} -Create the filter graph specified by @var{filter_graph} and use it to +@item -vf @var{filtergraph} +Create the filtergraph specified by @var{filtergraph} and use it to filter the video stream. -@var{filter_graph} is a description of the filter graph to apply to +@var{filtergraph} is a description of the filtergraph to apply to the stream, and must have a single video input and a single video -output. In the filter graph, the input is associated to the label +output. In the filtergraph, the input is associated to the label @code{in}, and the output to the label @code{out}. See the ffmpeg-filters manual for more information about the filtergraph syntax. -@item -af @var{filter_graph} -@var{filter_graph} is a description of the filter graph to apply to +@item -af @var{filtergraph} +@var{filtergraph} is a description of the filtergraph to apply to the input audio. Use the option "-filters" to show all the available filters (including sources and sinks). @@ -174,13 +174,16 @@ Toggle full screen. Pause. @item a -Cycle audio channel. +Cycle audio channel in the curret program. @item v Cycle video channel. @item t -Cycle subtitle channel. +Cycle subtitle channel in the current program. + +@item c +Cycle program. @item w Show audio waves. @@ -201,9 +204,42 @@ Seek to percentage in file corresponding to fraction of width. @c man end +@include config.texi +@ifset config-all +@ifset config-avutil +@include utils.texi +@end ifset +@ifset config-avcodec +@include codecs.texi +@include bitstream_filters.texi +@end ifset +@ifset config-avformat +@include formats.texi +@include protocols.texi +@end ifset +@ifset config-avdevice +@include devices.texi +@end ifset +@ifset config-swresample +@include resampler.texi +@end ifset +@ifset config-swscale +@include scaler.texi +@end ifset +@ifset config-avfilter +@include filters.texi +@end ifset +@end ifset + @chapter See Also @ifhtml +@ifset config-all +@url{ffplay.html,ffplay}, +@end ifset +@ifset config-not-all +@url{ffplay-all.html,ffmpeg-all}, +@end ifset @url{ffmpeg.html,ffmpeg}, @url{ffprobe.html,ffprobe}, @url{ffserver.html,ffserver}, @url{ffmpeg-utils.html,ffmpeg-utils}, @url{ffmpeg-scaler.html,ffmpeg-scaler}, @@ -217,6 +253,12 @@ Seek to percentage in file corresponding to fraction of width. @end ifhtml @ifnothtml +@ifset config-all +ffplay(1), +@end ifset +@ifset config-not-all +ffplay-all(1), +@end ifset ffmpeg(1), ffprobe(1), ffserver(1), ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1), ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1), diff --git a/ffmpeg/doc/ffprobe.texi b/ffmpeg/doc/ffprobe.texi index 6e30b2f..75d1e72 100644 --- a/ffmpeg/doc/ffprobe.texi +++ b/ffmpeg/doc/ffprobe.texi @@ -44,14 +44,15 @@ name (which may be shared by other sections), and an unique name. See the output of @option{sections}. Metadata tags stored in the container or in the streams are recognized -and printed in the corresponding "FORMAT" or "STREAM" section. +and printed in the corresponding "FORMAT", "STREAM" or "PROGRAM_STREAM" +section. @c man end @chapter Options @c man begin OPTIONS -@include avtools-common-opts.texi +@include fftools-common-opts.texi @section Main options @@ -112,7 +113,7 @@ ffprobe -show_packets -select_streams v:1 INPUT @end example @item -show_data -Show payload data, as an hexadecimal and ASCII dump. Coupled with +Show payload data, as a hexadecimal and ASCII dump. Coupled with @option{-show_packets}, it will dump the packets' data. Coupled with @option{-show_streams}, it will dump the codec extradata. @@ -196,11 +197,11 @@ The information for each single packet is printed within a dedicated section with name "PACKET". @item -show_frames -Show information about each frame contained in the input multimedia -stream. +Show information about each frame and subtitle contained in the input +multimedia stream. The information for each single frame is printed within a dedicated -section with name "FRAME". +section with name "FRAME" or "SUBTITLE". @item -show_streams Show information about each media stream contained in the input @@ -209,6 +210,18 @@ multimedia stream. Each media stream information is printed within a dedicated section with name "STREAM". +@item -show_programs +Show information about programs and their streams contained in the input +multimedia stream. + +Each media stream information is printed within a dedicated section +with name "PROGRAM_STREAM". + +@item -show_chapters +Show information about chapters stored in the format. + +Each chapter is printed within a dedicated section with name "CHAPTER". + @item -count_frames Count the number of frames per stream and report it in the corresponding stream section. @@ -217,6 +230,70 @@ corresponding stream section. Count the number of packets per stream and report it in the corresponding stream section. +@item -read_intervals @var{read_intervals} + +Read only the specified intervals. @var{read_intervals} must be a +sequence of interval specifications separated by ",". +@command{ffprobe} will seek to the interval starting point, and will +continue reading from that. + +Each interval is specified by two optional parts, separated by "%". + +The first part specifies the interval start position. It is +interpreted as an abolute position, or as a relative offset from the +current position if it is preceded by the "+" character. If this first +part is not specified, no seeking will be performed when reading this +interval. + +The second part specifies the interval end position. It is interpreted +as an absolute position, or as a relative offset from the current +position if it is preceded by the "+" character. If the offset +specification starts with "#", it is interpreted as the number of +packets to read (not including the flushing packets) from the interval +start. If no second part is specified, the program will read until the +end of the input. + +Note that seeking is not accurate, thus the actual interval start +point may be different from the specified position. Also, when an +interval duration is specified, the absolute end time will be computed +by adding the duration to the interval start point found by seeking +the file, rather than to the specified start value. + +The formal syntax is given by: +@example +@var{INTERVAL} ::= [@var{START}|+@var{START_OFFSET}][%[@var{END}|+@var{END_OFFSET}]] +@var{INTERVALS} ::= @var{INTERVAL}[,@var{INTERVALS}] +@end example + +A few examples follow. +@itemize +@item +Seek to time 10, read packets until 20 seconds after the found seek +point, then seek to position @code{01:30} (1 minute and thirty +seconds) and read packets until position @code{01:45}. +@example +10%+20,01:30%01:45 +@end example + +@item +Read only 42 packets after seeking to position @code{01:23}: +@example +01:23%+#42 +@end example + +@item +Read only the first 20 seconds from the start: +@example +%+20 +@end example + +@item +Read from the start until position @code{02:30}: +@example +%02:30 +@end example +@end itemize + @item -show_private_data, -private Show private data, that is data depending on the format of the particular shown element. @@ -260,6 +337,39 @@ A writer may accept one or more arguments, which specify the options to adopt. The options are specified as a list of @var{key}=@var{value} pairs, separated by ":". +All writers support the following options: + +@table @option +@item string_validation, sv +Set string validation mode. + +The following values are accepted. +@table @samp +@item fail +The writer will fail immediately in case an invalid string (UTF-8) +sequence or code point is found in the input. This is especially +useful to validate input metadata. + +@item ignore +Any validation error will be ignored. This will result in possibly +broken output, especially with the json or xml writer. + +@item replace +The writer will substitute invalid UTF-8 sequences or code points with +the string specified with the @option{string_validation_replacement}. +@end table + +Default value is @samp{replace}. + +@item string_validation_replacement, svr +Set replacement string to use in case @option{string_validation} is +set to @samp{replace}. + +In case the option is not specified, the writer will assume the empty +string, that is it will remove the invalid sequences from the input +strings. +@end table + A description of the currently available writers follows. @section default @@ -274,8 +384,8 @@ keyN=valN [/SECTION] @end example -Metadata tags are printed as a line in the corresponding FORMAT or -STREAM section, and are prefixed by the string "TAG:". +Metadata tags are printed as a line in the corresponding FORMAT, STREAM or +PROGRAM_STREAM section, and are prefixed by the string "TAG:". A description of the accepted options follows. @@ -487,10 +597,43 @@ DV, GXF and AVI timecodes are available in format metadata @end itemize @c man end TIMECODE +@include config.texi +@ifset config-all +@ifset config-avutil +@include utils.texi +@end ifset +@ifset config-avcodec +@include codecs.texi +@include bitstream_filters.texi +@end ifset +@ifset config-avformat +@include formats.texi +@include protocols.texi +@end ifset +@ifset config-avdevice +@include devices.texi +@end ifset +@ifset config-swresample +@include resampler.texi +@end ifset +@ifset config-swscale +@include scaler.texi +@end ifset +@ifset config-avfilter +@include filters.texi +@end ifset +@end ifset + @chapter See Also @ifhtml -@url{ffplay.html,ffmpeg}, @url{ffprobe.html,ffprobe}, @url{ffserver.html,ffserver}, +@ifset config-all +@url{ffprobe.html,ffprobe}, +@end ifset +@ifset config-not-all +@url{ffprobe-all.html,ffprobe-all}, +@end ifset +@url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffserver.html,ffserver}, @url{ffmpeg-utils.html,ffmpeg-utils}, @url{ffmpeg-scaler.html,ffmpeg-scaler}, @url{ffmpeg-resampler.html,ffmpeg-resampler}, @@ -503,6 +646,12 @@ DV, GXF and AVI timecodes are available in format metadata @end ifhtml @ifnothtml +@ifset config-all +ffprobe(1), +@end ifset +@ifset config-not-all +ffprobe-all(1), +@end ifset ffmpeg(1), ffplay(1), ffserver(1), ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1), ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1), diff --git a/ffmpeg/doc/ffprobe.xsd b/ffmpeg/doc/ffprobe.xsd index eab97fb..1bc1fb5 100644 --- a/ffmpeg/doc/ffprobe.xsd +++ b/ffmpeg/doc/ffprobe.xsd @@ -11,6 +11,8 @@ <xsd:element name="packets" type="ffprobe:packetsType" minOccurs="0" maxOccurs="1" /> <xsd:element name="frames" type="ffprobe:framesType" minOccurs="0" maxOccurs="1" /> <xsd:element name="streams" type="ffprobe:streamsType" minOccurs="0" maxOccurs="1" /> + <xsd:element name="programs" type="ffprobe:programsType" minOccurs="0" maxOccurs="1" /> + <xsd:element name="chapters" type="ffprobe:chaptersType" minOccurs="0" maxOccurs="1" /> <xsd:element name="format" type="ffprobe:formatType" minOccurs="0" maxOccurs="1" /> <xsd:element name="error" type="ffprobe:errorType" minOccurs="0" maxOccurs="1" /> <xsd:element name="program_version" type="ffprobe:programVersionType" minOccurs="0" maxOccurs="1" /> @@ -26,7 +28,10 @@ <xsd:complexType name="framesType"> <xsd:sequence> - <xsd:element name="frame" type="ffprobe:frameType" minOccurs="0" maxOccurs="unbounded"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element name="frame" type="ffprobe:frameType" minOccurs="0" maxOccurs="unbounded"/> + <xsd:element name="subtitle" type="ffprobe:subtitleType" minOccurs="0" maxOccurs="unbounded"/> + </xsd:choice> </xsd:sequence> </xsd:complexType> @@ -56,6 +61,8 @@ <xsd:attribute name="pkt_pts_time" type="xsd:float"/> <xsd:attribute name="pkt_dts" type="xsd:long" /> <xsd:attribute name="pkt_dts_time" type="xsd:float"/> + <xsd:attribute name="best_effort_timestamp" type="xsd:long" /> + <xsd:attribute name="best_effort_timestamp_time" type="xsd:float" /> <xsd:attribute name="pkt_duration" type="xsd:long" /> <xsd:attribute name="pkt_duration_time" type="xsd:float"/> <xsd:attribute name="pkt_pos" type="xsd:long" /> @@ -80,12 +87,28 @@ <xsd:attribute name="repeat_pict" type="xsd:int" /> </xsd:complexType> + <xsd:complexType name="subtitleType"> + <xsd:attribute name="media_type" type="xsd:string" fixed="subtitle" use="required"/> + <xsd:attribute name="pts" type="xsd:long" /> + <xsd:attribute name="pts_time" type="xsd:float"/> + <xsd:attribute name="format" type="xsd:int" /> + <xsd:attribute name="start_display_time" type="xsd:int" /> + <xsd:attribute name="end_display_time" type="xsd:int" /> + <xsd:attribute name="num_rects" type="xsd:int" /> + </xsd:complexType> + <xsd:complexType name="streamsType"> <xsd:sequence> <xsd:element name="stream" type="ffprobe:streamType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> + <xsd:complexType name="programsType"> + <xsd:sequence> + <xsd:element name="program" type="ffprobe:programType" minOccurs="0" maxOccurs="unbounded"/> + </xsd:sequence> + </xsd:complexType> + <xsd:complexType name="streamDispositionType"> <xsd:attribute name="default" type="xsd:int" use="required" /> <xsd:attribute name="dub" type="xsd:int" use="required" /> @@ -102,8 +125,8 @@ <xsd:complexType name="streamType"> <xsd:sequence> - <xsd:element name="tag" type="ffprobe:tagType" minOccurs="0" maxOccurs="unbounded"/> <xsd:element name="disposition" type="ffprobe:streamDispositionType" minOccurs="0" maxOccurs="1"/> + <xsd:element name="tag" type="ffprobe:tagType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="index" type="xsd:int" use="required"/> @@ -130,6 +153,7 @@ <xsd:attribute name="sample_fmt" type="xsd:string"/> <xsd:attribute name="sample_rate" type="xsd:int"/> <xsd:attribute name="channels" type="xsd:int"/> + <xsd:attribute name="channel_layout" type="xsd:string"/> <xsd:attribute name="bits_per_sample" type="xsd:int"/> <xsd:attribute name="id" type="xsd:string"/> @@ -146,6 +170,23 @@ <xsd:attribute name="nb_read_packets" type="xsd:int"/> </xsd:complexType> + <xsd:complexType name="programType"> + <xsd:sequence> + <xsd:element name="tag" type="ffprobe:tagType" minOccurs="0" maxOccurs="unbounded"/> + <xsd:element name="streams" type="ffprobe:streamsType" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + + <xsd:attribute name="program_id" type="xsd:int" use="required"/> + <xsd:attribute name="program_num" type="xsd:int" use="required"/> + <xsd:attribute name="nb_streams" type="xsd:int" use="required"/> + <xsd:attribute name="start_time" type="xsd:float"/> + <xsd:attribute name="start_pts" type="xsd:long"/> + <xsd:attribute name="end_time" type="xsd:float"/> + <xsd:attribute name="end_pts" type="xsd:long"/> + <xsd:attribute name="pmt_pid" type="xsd:int" use="required"/> + <xsd:attribute name="pcr_pid" type="xsd:int" use="required"/> + </xsd:complexType> + <xsd:complexType name="formatType"> <xsd:sequence> <xsd:element name="tag" type="ffprobe:tagType" minOccurs="0" maxOccurs="unbounded"/> @@ -153,12 +194,14 @@ <xsd:attribute name="filename" type="xsd:string" use="required"/> <xsd:attribute name="nb_streams" type="xsd:int" use="required"/> + <xsd:attribute name="nb_programs" type="xsd:int" use="required"/> <xsd:attribute name="format_name" type="xsd:string" use="required"/> <xsd:attribute name="format_long_name" type="xsd:string"/> <xsd:attribute name="start_time" type="xsd:float"/> <xsd:attribute name="duration" type="xsd:float"/> <xsd:attribute name="size" type="xsd:long"/> <xsd:attribute name="bit_rate" type="xsd:long"/> + <xsd:attribute name="probe_score" type="xsd:int"/> </xsd:complexType> <xsd:complexType name="tagType"> @@ -181,6 +224,25 @@ <xsd:attribute name="configuration" type="xsd:string" use="required"/> </xsd:complexType> + <xsd:complexType name="chaptersType"> + <xsd:sequence> + <xsd:element name="chapter" type="ffprobe:chapterType" minOccurs="0" maxOccurs="unbounded"/> + </xsd:sequence> + </xsd:complexType> + + <xsd:complexType name="chapterType"> + <xsd:sequence> + <xsd:element name="tag" type="ffprobe:tagType" minOccurs="0" maxOccurs="unbounded"/> + </xsd:sequence> + + <xsd:attribute name="id" type="xsd:int" use="required"/> + <xsd:attribute name="time_base" type="xsd:string" use="required"/> + <xsd:attribute name="start" type="xsd:int" use="required"/> + <xsd:attribute name="start_time" type="xsd:float"/> + <xsd:attribute name="end" type="xsd:int" use="required"/> + <xsd:attribute name="end_time" type="xsd:float" use="required"/> + </xsd:complexType> + <xsd:complexType name="libraryVersionType"> <xsd:attribute name="name" type="xsd:string" use="required"/> <xsd:attribute name="major" type="xsd:int" use="required"/> diff --git a/ffmpeg/doc/ffserver.conf b/ffmpeg/doc/ffserver.conf index 0f5922c..094c093 100644 --- a/ffmpeg/doc/ffserver.conf +++ b/ffmpeg/doc/ffserver.conf @@ -235,7 +235,7 @@ StartSendOnKey #<Stream test.ogg> #Feed feed1.ffm -#Title "Stream title" +#Metadata title "Stream title" #AudioBitRate 64 #AudioChannels 2 #AudioSampleRate 44100 @@ -280,10 +280,10 @@ StartSendOnKey #<Stream file.asf> #File "/usr/local/httpd/htdocs/test.asf" #NoAudio -#Author "Me" -#Copyright "Super MegaCorp" -#Title "Test stream from disk" -#Comment "Test comment" +#Metadata author "Me" +#Metadata copyright "Super MegaCorp" +#Metadata title "Test stream from disk" +#Metadata comment "Test comment" #</Stream> diff --git a/ffmpeg/doc/ffserver.texi b/ffmpeg/doc/ffserver.texi index f1b7599..ed538c1 100644 --- a/ffmpeg/doc/ffserver.texi +++ b/ffmpeg/doc/ffserver.texi @@ -16,11 +16,14 @@ ffserver [@var{options}] @chapter Description @c man begin DESCRIPTION -@command{ffserver} is a streaming server for both audio and video. It -supports several live feeds, streaming from files and time shifting on -live feeds (you can seek to positions in the past on each live feed, -provided you specify a big enough feed storage in -@file{ffserver.conf}). +@command{ffserver} is a streaming server for both audio and video. +It supports several live feeds, streaming from files and time shifting +on live feeds. You can seek to positions in the past on each live +feed, provided you specify a big enough feed storage. + +@command{ffserver} is configured through a configuration file, which +is read at startup. If not explicitly specified, it will read from +@file{/etc/ffserver.conf}. @command{ffserver} receives prerecorded files or FFM streams from some @command{ffmpeg} instance as input, then streams them over @@ -39,10 +42,118 @@ For each feed you can have different output streams in various formats, each one specified by a @code{<Stream>} section in the configuration file. +@chapter Detailed description + +@command{ffserver} works by forwarding streams encoded by +@command{ffmpeg}, or pre-recorded streams which are read from disk. + +Precisely, @command{ffserver} acts as an HTTP server, accepting POST +requests from @command{ffmpeg} to acquire the stream to publish, and +serving HTTP clients GET requests with the stream media content. + +A feed is an @ref{FFM} stream created by @command{ffmpeg}, and sent to +a port where @command{ffserver} is listening. + +Each feed is identified by a unique name, corresponding to the name +of the resource published on @command{ffserver}, and is configured by +a dedicated @code{Feed} section in the configuration file. + +The feed publish URL is given by: +@example +http://@var{ffserver_ip_address}:@var{http_port}/@var{feed_name} +@end example + +where @var{ffserver_ip_address} is the IP address of the machine where +@command{ffserver} is installed, @var{http_port} is the port number of +the HTTP server (configured through the @option{Port} option), and +@var{feed_name} is the name of the corresponding feed defined in the +configuration file. + +Each feed is associated to a file which is stored on disk. This stored +file is used to allow to send pre-recorded data to a player as fast as +possible when new content is added in real-time to the stream. + +A "live-stream" or "stream" is a resource published by +@command{ffserver}, and made accessible through the HTTP protocol to +clients. + +A stream can be connected to a feed, or to a file. In the first case, +the published stream is forwarded from the corresponding feed +generated by a running instance of @command{ffmpeg}, in the second +case the stream is read from a pre-recorded file. + +Each stream is identified by a unique name, corresponding to the name +of the resource served by @command{ffserver}, and is configured by +a dedicated @code{Stream} section in the configuration file. + +The stream access URL is given by: +@example +http://@var{ffserver_ip_address}:@var{http_port}/@var{stream_name}[@var{options}] +@end example + +@var{stream_name} is the name of the corresponding stream defined in +the configuration file. @var{options} is a list of options specified +after the URL which affects how the stream is served by +@command{ffserver}. + +In case the stream is associated to a feed, the encoding parameters +must be configured in the stream configuration. They are sent to +@command{ffmpeg} when setting up the encoding. This allows +@command{ffserver} to define the encoding parameters used by +the @command{ffmpeg} encoders. + +The @command{ffmpeg} @option{override_ffserver} commandline option +allows to override the encoding parameters set by the server. + +Multiple streams can be connected to the same feed. + +For example, you can have a situation described by the following +graph: +@example + _________ __________ + | | | | +ffmpeg 1 -----| feed 1 |-----| stream 1 | + \ |_________|\ |__________| + \ \ + \ \ __________ + \ \ | | + \ \| stream 2 | + \ |__________| + \ + \ _________ __________ + \ | | | | + \| feed 2 |-----| stream 3 | + |_________| |__________| + + _________ __________ + | | | | +ffmpeg 2 -----| feed 3 |-----| stream 4 | + |_________| |__________| + + _________ __________ + | | | | + | file 1 |-----| stream 5 | + |_________| |__________| +@end example + +@anchor{FFM} +@section FFM, FFM2 formats + +FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of +video and audio streams and encoding options, and can store a moving time segment +of an infinite movie or a whole movie. + +FFM is version specific, and there is limited compatibility of FFM files +generated by one version of ffmpeg/ffserver and another version of +ffmpeg/ffserver. It may work but it is not guaranteed to work. + +FFM2 is extensible while maintaining compatibility and should work between +differing versions of tools. FFM2 is the default. + @section Status stream -ffserver supports an HTTP interface which exposes the current status -of the server. +@command{ffserver} supports an HTTP interface which exposes the +current status of the server. Simply point your browser to the address of the special status stream specified in the configuration file. @@ -61,27 +172,8 @@ ACL allow 192.168.0.0 192.168.255.255 then the server will post a page with the status information when the special stream @file{status.html} is requested. -@section What can this do? - -When properly configured and running, you can capture video and audio in real -time from a suitable capture card, and stream it out over the Internet to -either Windows Media Player or RealAudio player (with some restrictions). - -It can also stream from files, though that is currently broken. Very often, a -web server can be used to serve up the files just as well. - -It can stream prerecorded video from .ffm files, though it is somewhat tricky -to make it work correctly. - @section How do I make it work? -First, build the kit. It *really* helps to have installed LAME first. Then when -you run the ffserver ./configure, make sure that you have the -@code{--enable-libmp3lame} flag turned on. - -LAME is important as it allows for streaming audio to Windows Media Player. -Don't ask why the other audio types do not work. - As a simple test, just run the following two command lines where INPUTFILE is some file which you can decode with ffmpeg: @@ -109,35 +201,6 @@ You should edit the ffserver.conf file to suit your needs (in terms of frame rates etc). Then install ffserver and ffmpeg, write a script to start them up, and off you go. -@section Troubleshooting - -@subsection I don't hear any audio, but video is fine. - -Maybe you didn't install LAME, or got your ./configure statement wrong. Check -the ffmpeg output to see if a line referring to MP3 is present. If not, then -your configuration was incorrect. If it is, then maybe your wiring is not -set up correctly. Maybe the sound card is not getting data from the right -input source. Maybe you have a really awful audio interface (like I do) -that only captures in stereo and also requires that one channel be flipped. -If you are one of these people, then export 'AUDIO_FLIP_LEFT=1' before -starting ffmpeg. - -@subsection The audio and video lose sync after a while. - -Yes, they do. - -@subsection After a long while, the video update rate goes way down in WMP. - -Yes, it does. Who knows why? - -@subsection WMP 6.4 behaves differently to WMP 7. - -Yes, it does. Any thoughts on this would be gratefully received. These -differences extend to embedding WMP into a web page. [There are two -object IDs that you can use: The old one, which does not play well, and -the new one, which does (both tested on the same system). However, -I suspect that the new one is not available unless you have installed WMP 7]. - @section What else can it do? You can replay video from .ffm files that was recorded earlier. @@ -177,9 +240,6 @@ specify a time. In addition, ffserver will skip frames until a key_frame is found. This further reduces the startup delay by not transferring data that will be discarded. -* You may want to adjust the MaxBandwidth in the ffserver.conf to limit -the amount of bandwidth consumed by live streams. - @section Why does the ?buffer / Preroll stop working after a time? It turns out that (on my machine at least) the number of frames successfully @@ -213,43 +273,588 @@ You use this by adding the ?date= to the end of the URL for the stream. For example: @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}. @c man end -@section What is FFM, FFM2 - -FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of -video and audio streams and encoding options, and can store a moving time segment -of an infinite movie or a whole movie. - -FFM is version specific, and there is limited compatibility of FFM files -generated by one version of ffmpeg/ffserver and another version of -ffmpeg/ffserver. It may work but it is not guaranteed to work. - -FFM2 is extensible while maintaining compatibility and should work between -differing versions of tools. FFM2 is the default. - @chapter Options @c man begin OPTIONS -@include avtools-common-opts.texi +@include fftools-common-opts.texi @section Main options @table @option @item -f @var{configfile} -Use @file{configfile} instead of @file{/etc/ffserver.conf}. +Read configuration file @file{configfile}. If not specified it will +read by default from @file{/etc/ffserver.conf}. + @item -n -Enable no-launch mode. This option disables all the Launch directives -within the various <Stream> sections. Since ffserver will not launch -any ffmpeg instances, you will have to launch them manually. +Enable no-launch mode. This option disables all the @code{Launch} +directives within the various @code{<Feed>} sections. Since +@command{ffserver} will not launch any @command{ffmpeg} instances, you +will have to launch them manually. + @item -d -Enable debug mode. This option increases log verbosity, directs log -messages to stdout. +Enable debug mode. This option increases log verbosity, and directs +log messages to stdout. When specified, the @option{CustomLog} option +is ignored. +@end table + +@chapter Configuration file syntax + +@command{ffserver} reads a configuration file containing global +options and settings for each stream and feed. + +The configuration file consists of global options and dedicated +sections, which must be introduced by "<@var{SECTION_NAME} +@var{ARGS}>" on a separate line and must be terminated by a line in +the form "</@var{SECTION_NAME}>". @var{ARGS} is optional. + +Currently the following sections are recognized: @samp{Feed}, +@samp{Stream}, @samp{Redirect}. + +A line starting with @code{#} is ignored and treated as a comment. + +Name of options and sections are case-insensitive. + +@section ACL syntax +An ACL (Access Control List) specifies the address which are allowed +to access a given stream, or to write a given feed. + +It accepts the folling forms +@itemize +@item +Allow/deny access to @var{address}. +@example +ACL ALLOW <address> +ACL DENY <address> +@end example + +@item +Allow/deny access to ranges of addresses from @var{first_address} to +@var{last_address}. +@example +ACL ALLOW <first_address> <last_address> +ACL DENY <first_address> <last_address> +@end example +@end itemize + +You can repeat the ACL allow/deny as often as you like. It is on a per +stream basis. The first match defines the action. If there are no matches, +then the default is the inverse of the last ACL statement. + +Thus 'ACL allow localhost' only allows access from localhost. +'ACL deny 1.0.0.0 1.255.255.255' would deny the whole of network 1 and +allow everybody else. + +@section Global options +@table @option +@item Port @var{port_number} +@item RTSPPort @var{port_number} + +Set TCP port number on which the HTTP/RTSP server is listening. You +must select a different port from your standard HTTP web server if it +is running on the same computer. + +If not specified, no corresponding server will be created. + +@item BindAddress @var{ip_address} +@item RTSPBindAddress @var{ip_address} +Set address on which the HTTP/RTSP server is bound. Only useful if you +have several network interfaces. + +@item MaxHTTPConnections @var{n} +Set number of simultaneous HTTP connections that can be handled. It +has to be defined @emph{before} the @option{MaxClients} parameter, +since it defines the @option{MaxClients} maximum limit. + +Default value is 2000. + +@item MaxClients @var{n} +Set number of simultaneous requests that can be handled. Since +@command{ffserver} is very fast, it is more likely that you will want +to leave this high and use @option{MaxBandwidth}. + +Default value is 5. + +@item MaxBandwidth @var{kbps} +Set the maximum amount of kbit/sec that you are prepared to consume +when streaming to clients. + +Default value is 1000. + +@item CustomLog @var{filename} +Set access log file (uses standard Apache log file format). '-' is the +standard output. + +If not specified @command{ffserver} will produce no log. + +In case the commandline option @option{-d} is specified this option is +ignored, and the log is written to standard output. + +@item NoDaemon +Set no-daemon mode. This option is currently ignored since now +@command{ffserver} will always work in no-daemon mode, and is +deprecated. +@end table + +@section Feed section + +A Feed section defines a feed provided to @command{ffserver}. + +Each live feed contains one video and/or audio sequence coming from an +@command{ffmpeg} encoder or another @command{ffserver}. This sequence +may be encoded simultaneously with several codecs at several +resolutions. + +A feed instance specification is introduced by a line in the form: +@example +<Feed FEED_FILENAME> +@end example + +where @var{FEED_FILENAME} specifies the unique name of the FFM stream. + +The following options are recognized within a Feed section. + +@table @option +@item File @var{filename} +@item ReadOnlyFile @var{filename} +Set the path where the feed file is stored on disk. + +If not specified, the @file{/tmp/FEED.ffm} is assumed, where +@var{FEED} is the feed name. + +If @option{ReadOnlyFile} is used the file is marked as read-only and +it will not be deleted or updated. + +@item Truncate +Truncate the feed file, rather than appending to it. By default +@command{ffserver} will append data to the file, until the maximum +file size value is reached (see @option{FileMaxSize} option). + +@item FileMaxSize @var{size} +Set maximum size of the feed file in bytes. 0 means unlimited. The +postfixes @code{K} (2^10), @code{M} (2^20), and @code{G} (2^30) are +recognized. + +Default value is 5M. + +@item Launch @var{args} +Launch an @command{ffmpeg} command when creating @command{ffserver}. + +@var{args} must be a sequence of arguments to be provided to an +@command{ffmpeg} instance. The first provided argument is ignored, and +it is replaced by a path with the same dirname of the @command{ffserver} +instance, followed by the remaining argument and terminated with a +path corresponding to the feed. + +When the launched process exits, @command{ffserver} will launch +another program instance. + +In case you need a more complex @command{ffmpeg} configuration, +e.g. if you need to generate multiple FFM feeds with a single +@command{ffmpeg} instance, you should launch @command{ffmpeg} by hand. + +This option is ignored in case the commandline option @option{-n} is +specified. + +@item ACL @var{spec} +Specify the list of IP address which are allowed or denied to write +the feed. Multiple ACL options can be specified. @end table + +@section Stream section + +A Stream section defines a stream provided by @command{ffserver}, and +identified by a single name. + +The stream is sent when answering a request containing the stream +name. + +A stream section must be introduced by the line: +@example +<Stream STREAM_NAME> +@end example + +where @var{STREAM_NAME} specifies the unique name of the stream. + +The following options are recognized within a Stream section. + +Encoding options are marked with the @emph{encoding} tag, and they are +used to set the encoding parameters, and are mapped to libavcodec +encoding options. Not all encoding options are supported, in +particular it is not possible to set encoder private options. In order +to override the encoding options specified by @command{ffserver}, you +can use the @command{ffmpeg} @option{override_ffserver} commandline +option. + +Only one of the @option{Feed} and @option{File} options should be set. + +@table @option +@item Feed @var{feed_name} +Set the input feed. @var{feed_name} must correspond to an existing +feed defined in a @code{Feed} section. + +When this option is set, encoding options are used to setup the +encoding operated by the remote @command{ffmpeg} process. + +@item File @var{filename} +Set the filename of the pre-recorded input file to stream. + +When this option is set, encoding options are ignored and the input +file content is re-streamed as is. + +@item Format @var{format_name} +Set the format of the output stream. + +Must be the name of a format recognized by FFmpeg. If set to +@samp{status}, it is treated as a status stream. + +@item InputFormat @var{format_name} +Set input format. If not specified, it is automatically guessed. + +@item Preroll @var{n} +Set this to the number of seconds backwards in time to start. Note that +most players will buffer 5-10 seconds of video, and also you need to allow +for a keyframe to appear in the data stream. + +Default value is 0. + +@item StartSendOnKey +Do not send stream until it gets the first key frame. By default +@command{ffserver} will send data immediately. + +@item MaxTime @var{n} +Set the number of seconds to run. This value set the maximum duration +of the stream a client will be able to receive. + +A value of 0 means that no limit is set on the stream duration. + +@item ACL @var{spec} +Set ACL for the stream. + +@item DynamicACL @var{spec} + +@item RTSPOption @var{option} + +@item MulticastAddress @var{address} + +@item MulticastPort @var{port} + +@item MulticastTTL @var{integer} + +@item NoLoop + +@item FaviconURL @var{url} +Set favicon (favourite icon) for the server status page. It is ignored +for regular streams. + +@item Author @var{value} +@item Comment @var{value} +@item Copyright @var{value} +@item Title @var{value} +Set metadata corresponding to the option. All these options are +deprecated in favor of @option{Metadata}. + +@item Metadata @var{key} @var{value} +Set metadata value on the output stream. + +@item NoAudio +@item NoVideo +Suppress audio/video. + +@item AudioCodec @var{codec_name} (@emph{encoding,audio}) +Set audio codec. + +@item AudioBitRate @var{rate} (@emph{encoding,audio}) +Set bitrate for the audio stream in kbits per second. + +@item AudioChannels @var{n} (@emph{encoding,audio}) +Set number of audio channels. + +@item AudioSampleRate @var{n} (@emph{encoding,audio}) +Set sampling frequency for audio. When using low bitrates, you should +lower this frequency to 22050 or 11025. The supported frequencies +depend on the selected audio codec. + +@item AVOptionAudio @var{option} @var{value} (@emph{encoding,audio}) +Set generic option for audio stream. + +@item AVPresetAudio @var{preset} (@emph{encoding,audio}) +Set preset for audio stream. + +@item VideoCodec @var{codec_name} (@emph{encoding,video}) +Set video codec. + +@item VideoBitRate @var{n} (@emph{encoding,video}) +Set bitrate for the video stream in kbits per second. + +@item VideoBitRateRange @var{range} (@emph{encoding,video}) +Set video bitrate range. + +A range must be specified in the form @var{minrate}-@var{maxrate}, and +specifies the @option{minrate} and @option{maxrate} encoding options +expressed in kbits per second. + +@item VideoBitRateRangeTolerance @var{n} (@emph{encoding,video}) +Set video bitrate tolerance in kbits per second. + +@item PixelFormat @var{pixel_format} (@emph{encoding,video}) +Set video pixel format. + +@item Debug @var{integer} (@emph{encoding,video}) +Set video @option{debug} encoding option. + +@item Strict @var{integer} (@emph{encoding,video}) +Set video @option{strict} encoding option. + +@item VideoBufferSize @var{n} (@emph{encoding,video}) +Set ratecontrol buffer size, expressed in KB. + +@item VideoFrameRate @var{n} (@emph{encoding,video}) +Set number of video frames per second. + +@item VideoSize (@emph{encoding,video}) +Set size of the video frame, must be an abbreviation or in the form +@var{W}x@var{H}. See @ref{video size syntax,,the Video size section +in the ffmpeg-utils(1) manual,ffmpeg-utils}. + +Default value is @code{160x128}. + +@item VideoIntraOnly (@emph{encoding,video}) +Transmit only intra frames (useful for low bitrates, but kills frame rate). + +@item VideoGopSize @var{n} (@emph{encoding,video}) +If non-intra only, an intra frame is transmitted every VideoGopSize +frames. Video synchronization can only begin at an intra frame. + +@item VideoTag @var{tag} (@emph{encoding,video}) +Set video tag. + +@item VideoHighQuality (@emph{encoding,video}) +@item Video4MotionVector (@emph{encoding,video}) + +@item BitExact (@emph{encoding,video}) +Set bitexact encoding flag. + +@item IdctSimple (@emph{encoding,video}) +Set simple IDCT algorithm. + +@item Qscale @var{n} (@emph{encoding,video}) +Enable constant quality encoding, and set video qscale (quantization +scale) value, expressed in @var{n} QP units. + +@item VideoQMin @var{n} (@emph{encoding,video}) +@item VideoQMax @var{n} (@emph{encoding,video}) +Set video qmin/qmax. + +@item VideoQDiff @var{integer} (@emph{encoding,video}) +Set video @option{qdiff} encoding option. + +@item LumiMask @var{float} (@emph{encoding,video}) +@item DarkMask @var{float} (@emph{encoding,video}) +Set @option{lumi_mask}/@option{dark_mask} encoding options. + +@item AVOptionVideo @var{option} @var{value} (@emph{encoding,video}) +Set generic option for video stream. + +@item AVPresetVideo @var{preset} (@emph{encoding,video}) +Set preset for video stream. + +@var{preset} must be the path of a preset file. +@end table + +@subsection Server status stream + +A server status stream is a special stream which is used to show +statistics about the @command{ffserver} operations. + +It must be specified setting the option @option{Format} to +@samp{status}. + +@section Redirect section + +A redirect section specifies where to redirect the requested URL to +another page. + +A redirect section must be introduced by the line: +@example +<Redirect NAME> +@end example + +where @var{NAME} is the name of the page which should be redirected. + +It only accepts the option @option{URL}, which specify the redirection +URL. + +@chapter Stream examples + +@itemize +@item +Multipart JPEG +@example +<Stream test.mjpg> +Feed feed1.ffm +Format mpjpeg +VideoFrameRate 2 +VideoIntraOnly +NoAudio +Strict -1 +</Stream> +@end example + +@item +Single JPEG +@example +<Stream test.jpg> +Feed feed1.ffm +Format jpeg +VideoFrameRate 2 +VideoIntraOnly +VideoSize 352x240 +NoAudio +Strict -1 +</Stream> +@end example + +@item +Flash +@example +<Stream test.swf> +Feed feed1.ffm +Format swf +VideoFrameRate 2 +VideoIntraOnly +NoAudio +</Stream> +@end example + +@item +ASF compatible +@example +<Stream test.asf> +Feed feed1.ffm +Format asf +VideoFrameRate 15 +VideoSize 352x240 +VideoBitRate 256 +VideoBufferSize 40 +VideoGopSize 30 +AudioBitRate 64 +StartSendOnKey +</Stream> +@end example + +@item +MP3 audio +@example +<Stream test.mp3> +Feed feed1.ffm +Format mp2 +AudioCodec mp3 +AudioBitRate 64 +AudioChannels 1 +AudioSampleRate 44100 +NoVideo +</Stream> +@end example + +@item +Ogg Vorbis audio +@example +<Stream test.ogg> +Feed feed1.ffm +Metadata title "Stream title" +AudioBitRate 64 +AudioChannels 2 +AudioSampleRate 44100 +NoVideo +</Stream> +@end example + +@item +Real with audio only at 32 kbits +@example +<Stream test.ra> +Feed feed1.ffm +Format rm +AudioBitRate 32 +NoVideo +</Stream> +@end example + +@item +Real with audio and video at 64 kbits +@example +<Stream test.rm> +Feed feed1.ffm +Format rm +AudioBitRate 32 +VideoBitRate 128 +VideoFrameRate 25 +VideoGopSize 25 +</Stream> +@end example + +@item +For stream coming from a file: you only need to set the input filename +and optionally a new format. + +@example +<Stream file.rm> +File "/usr/local/httpd/htdocs/tlive.rm" +NoAudio +</Stream> +@end example + +@example +<Stream file.asf> +File "/usr/local/httpd/htdocs/test.asf" +NoAudio +Metadata author "Me" +Metadata copyright "Super MegaCorp" +Metadata title "Test stream from disk" +Metadata comment "Test comment" +</Stream> +@end example +@end itemize + @c man end +@include config.texi +@ifset config-all +@ifset config-avutil +@include utils.texi +@end ifset +@ifset config-avcodec +@include codecs.texi +@include bitstream_filters.texi +@end ifset +@ifset config-avformat +@include formats.texi +@include protocols.texi +@end ifset +@ifset config-avdevice +@include devices.texi +@end ifset +@ifset config-swresample +@include resampler.texi +@end ifset +@ifset config-swscale +@include scaler.texi +@end ifset +@ifset config-avfilter +@include filters.texi +@end ifset +@end ifset + @chapter See Also @ifhtml -The @file{doc/ffserver.conf} example, +@ifset config-all +@url{ffserver.html,ffserver}, +@end ifset +@ifset config-not-all +@url{ffserver-all.html,ffserver-all}, +@end ifset +the @file{doc/ffserver.conf} example, @url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe}, @url{ffmpeg-utils.html,ffmpeg-utils}, @url{ffmpeg-scaler.html,ffmpeg-scaler}, @@ -263,7 +868,13 @@ The @file{doc/ffserver.conf} example, @end ifhtml @ifnothtml -The @file{doc/ffserver.conf} example, ffmpeg(1), ffplay(1), ffprobe(1), +@ifset config-all +ffserver(1), +@end ifset +@ifset config-not-all +ffserver-all(1), +@end ifset +the @file{doc/ffserver.conf} example, ffmpeg(1), ffplay(1), ffprobe(1), ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1), ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1), ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1) diff --git a/ffmpeg/doc/filter_design.txt b/ffmpeg/doc/filter_design.txt index 772ca9d..fca24a9 100644 --- a/ffmpeg/doc/filter_design.txt +++ b/ffmpeg/doc/filter_design.txt @@ -29,6 +29,11 @@ Format negotiation same format amongst a supported list, all it has to do is use a reference to the same list of formats. + query_formats can leave some formats unset and return AVERROR(EAGAIN) to + cause the negotiation mechanism to try again later. That can be used by + filters with complex requirements to use the format negotiated on one link + to set the formats supported on another. + Buffer references ownership and permissions =========================================== @@ -161,7 +166,7 @@ Buffer references ownership and permissions WRITE permission. * Filters that read their input to produce a new frame on output (like - scale) need the READ permission on input and and must request a buffer + scale) need the READ permission on input and must request a buffer with the WRITE permission. * Filters that intend to keep a reference after the filtering process @@ -199,7 +204,7 @@ Frame scheduling filter; these buffered frames must be flushed immediately if a new input produces new output. - (Example: framerate-doubling filter: filter_frame must (1) flush the + (Example: frame rate-doubling filter: filter_frame must (1) flush the second copy of the previous frame, if it is still there, (2) push the first copy of the incoming frame, (3) keep the second copy for later.) diff --git a/ffmpeg/doc/filters.texi b/ffmpeg/doc/filters.texi index 74a682a..a579964 100644 --- a/ffmpeg/doc/filters.texi +++ b/ffmpeg/doc/filters.texi @@ -3,37 +3,45 @@ Filtering in FFmpeg is enabled through the libavfilter library. -In libavfilter, it is possible for filters to have multiple inputs and -multiple outputs. -To illustrate the sorts of things that are possible, we can -use a complex filter graph. For example, the following one: +In libavfilter, a filter can have multiple inputs and multiple +outputs. +To illustrate the sorts of things that are possible, we consider the +following filtergraph. @example + [main] input --> split ---------------------> overlay --> output | ^ - | | + |[tmp] [flip]| +-----> crop --> vflip -------+ @end example -splits the stream in two streams, sends one stream through the crop filter -and the vflip filter before merging it back with the other stream by -overlaying it on top. You can use the following command to achieve this: +This filtergraph splits the input stream in two streams, sends one +stream through the crop filter and the vflip filter before merging it +back with the other stream by overlaying it on top. You can use the +following command to achieve this: @example -ffmpeg -i input -vf "[in] split [T1], [T2] overlay=0:H/2 [out]; [T1] crop=iw:ih/2:0:ih/2, vflip [T2]" output +ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT @end example The result will be that in output the top half of the video is mirrored onto the bottom half. -Filters are loaded using the @var{-vf} or @var{-af} option passed to -@command{ffmpeg} or to @command{ffplay}. Filters in the same linear -chain are separated by commas. In our example, @var{split, -overlay} are in one linear chain, and @var{crop, vflip} are in -another. The points where the linear chains join are labeled by names -enclosed in square brackets. In our example, that is @var{[T1]} and -@var{[T2]}. The special labels @var{[in]} and @var{[out]} are the points -where video is input and output. +Filters in the same linear chain are separated by commas, and distinct +linear chains of filters are separated by semicolons. In our example, +@var{crop,vflip} are in one linear chain, @var{split} and +@var{overlay} are separately in another. The points where the linear +chains join are labelled by names enclosed in square brackets. In the +example, the split filter generates two outputs that are associated to +the labels @var{[main]} and @var{[tmp]}. + +The stream sent to the second output of @var{split}, labelled as +@var{[tmp]}, is processed through the @var{crop} filter, which crops +away the lower half part of the video, and then vertically flipped. The +@var{overlay} filter takes in input the first unchanged output of the +split filter (which was labelled as @var{[main]}), and overlay on its +lower half the output generated by the @var{crop,vflip} filterchain. Some filters take in input a list of parameters: they are specified after the filter name and an equal sign, and are separated from each other @@ -49,7 +57,7 @@ output. @c man begin GRAPH2DOT The @file{graph2dot} program included in the FFmpeg @file{tools} -directory can be used to parse a filter graph description and issue a +directory can be used to parse a filtergraph description and issue a corresponding textual representation in the dot language. Invoke the command: @@ -61,7 +69,7 @@ to see how to use @file{graph2dot}. You can then pass the dot description to the @file{dot} program (from the graphviz suite of programs) and obtain a graphical representation -of the filter graph. +of the filtergraph. For example the sequence of commands: @example @@ -110,7 +118,7 @@ A filtergraph can be represented using a textual representation, which is recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex} options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the @code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in -@file{libavfilter/avfiltergraph.h}. +@file{libavfilter/avfilter.h}. A filterchain consists of a sequence of connected filters, each one connected to the previous one in the sequence. A filterchain is @@ -130,8 +138,31 @@ The name of the filter class is optionally followed by a string "=@var{arguments}". @var{arguments} is a string which contains the parameters used to -initialize the filter instance, and are described in the filter -descriptions below. +initialize the filter instance. It may have one of the following forms: +@itemize + +@item +A ':'-separated list of @var{key=value} pairs. + +@item +A ':'-separated list of @var{value}. In this case, the keys are assumed to be +the option names in the order they are declared. E.g. the @code{fade} filter +declares three options in this order -- @option{type}, @option{start_frame} and +@option{nb_frames}. Then the parameter list @var{in:0:30} means that the value +@var{in} is assigned to the option @option{type}, @var{0} to +@option{start_frame} and @var{30} to @option{nb_frames}. + +@item +A ':'-separated list of mixed direct @var{value} and long @var{key=value} +pairs. The direct @var{value} must precede the @var{key=value} pairs, and +follow the same constraints order of the previous point. The following +@var{key=value} pairs can be set in any preferred order. + +@end itemize + +If the option value itself is a list of items (e.g. the @code{format} filter +takes a list of pixel formats), the items in the list are usually separated by +'|'. The list of arguments can be quoted using the character "'" as initial and ending mark, and the character '\' for escaping the characters @@ -167,7 +198,7 @@ In a complete filterchain all the unlabelled filter input and output pads must be connected. A filtergraph is considered valid if all the filter input and output pads of all the filterchains are connected. -Libavfilter will automatically insert scale filters where format +Libavfilter will automatically insert @ref{scale} filters where format conversion is required. It is possible to specify swscale flags for those automatically inserted scalers by prepending @code{sws_flags=@var{flags};} @@ -237,6 +268,39 @@ See the ``Quoting and escaping'' section in the ffmpeg-utils manual for more information about the escaping and quoting rules adopted by FFmpeg. +@chapter Timeline editing + +Some filters support a generic @option{enable} option. For the filters +supporting timeline editing, this option can be set to an expression which is +evaluated before sending a frame to the filter. If the evaluation is non-zero, +the filter will be enabled, otherwise the frame will be sent unchanged to the +next filter in the filtergraph. + +The expression accepts the following values: +@table @samp +@item t +timestamp expressed in seconds, NAN if the input timestamp is unknown + +@item n +sequential number of the input frame, starting from 0 + +@item pos +the position in the file of the input frame, NAN if unknown +@end table + +Additionally, these filters support an @option{enable} command that can be used +to re-define the expression. + +Like any other filtering option, the @option{enable} option follows the same +rules. + +For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3 +minutes, and a @ref{curves} filter starting at 3 seconds: +@example +smartblur = enable='between(t,10,3*60)', +curves = enable='gte(t,3)' : preset=cross_process +@end example + @c man end FILTERGRAPH DESCRIPTION @chapter Audio Filters @@ -253,6 +317,8 @@ Below is a description of the currently available audio filters. Convert the input audio format to the specified formats. +@emph{This filter is deprecated. Use @ref{aformat} instead.} + The filter accepts a string of the form: "@var{sample_format}:@var{channel_layout}". @@ -282,313 +348,161 @@ aconvert=u8:auto @end example @end itemize -@section allpass +@section adelay -Apply a two-pole all-pass filter with central frequency (in Hz) -@var{frequency}, and filter-width @var{width}. -An all-pass filter changes the audio's frequency to phase relationship -without changing its frequency to amplitude relationship. +Delay one or more audio channels. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". +Samples in delayed channel are filled with silence. -A description of the accepted parameters follows. +The filter accepts the following option: @table @option -@item frequency, f -Set frequency in Hz. - -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope -@end table - -@item width, w -Specify the band-width of a filter in width_type units. +@item delays +Set list of delays in milliseconds for each channel separated by '|'. +At least one delay greater than 0 should be provided. +Unused delays will be silently ignored. If number of given delays is +smaller than number of channels all remaining channels will not be delayed. @end table -@section highpass - -Apply a high-pass filter with 3dB point frequency. -The filter can be either single-pole, or double-pole (the default). -The filter roll off at 6dB per pole per octave (20dB per pole per decade). - -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". - -A description of the accepted parameters follows. - -@table @option -@item frequency, f -Set frequency in Hz. Default is 3000. - -@item poles, p -Set number of poles. Default is 2. - -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope -@end table +@subsection Examples -@item width, w -Specify the band-width of a filter in width_type units. -Applies only to double-pole filter. -The default is 0.707q and gives a Butterworth response. -@end table +@itemize +@item +Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave +the second channel (and any other channels that may be present) unchanged. +@example +adelay=1500|0|500 +@end example +@end itemize -@section lowpass +@section aecho -Apply a low-pass filter with 3dB point frequency. -The filter can be either single-pole or double-pole (the default). -The filter roll off at 6dB per pole per octave (20dB per pole per decade). +Apply echoing to the input audio. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". +Echoes are reflected sound and can occur naturally amongst mountains +(and sometimes large buildings) when talking or shouting; digital echo +effects emulate this behaviour and are often used to help fill out the +sound of a single instrument or vocal. The time difference between the +original signal and the reflection is the @code{delay}, and the +loudness of the reflected signal is the @code{decay}. +Multiple echoes can have different delays and decays. A description of the accepted parameters follows. @table @option -@item frequency, f -Set frequency in Hz. Default is 500. +@item in_gain +Set input gain of reflected signal. Default is @code{0.6}. -@item poles, p -Set number of poles. Default is 2. +@item out_gain +Set output gain of reflected signal. Default is @code{0.3}. -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope -@end table +@item delays +Set list of time intervals in milliseconds between original signal and reflections +separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. +Default is @code{1000}. -@item width, w -Specify the band-width of a filter in width_type units. -Applies only to double-pole filter. -The default is 0.707q and gives a Butterworth response. +@item decays +Set list of loudnesses of reflected signals separated by '|'. +Allowed range for each @code{decay} is @code{(0 - 1.0]}. +Default is @code{0.5}. @end table -@section bass - -Boost or cut the bass (lower) frequencies of the audio using a two-pole -shelving filter with a response similar to that of a standard -hi-fi's tone-controls. This is also known as shelving equalisation (EQ). - -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". - -A description of the accepted parameters follows. - -@table @option -@item gain, g -Give the gain at 0 Hz. Its useful range is about -20 -(for a large cut) to +20 (for a large boost). -Beware of clipping when using a positive gain. - -@item frequency, f -Set the filter's central frequency and so can be used -to extend or reduce the frequency range to be boosted or cut. -The default value is @code{100} Hz. +@subsection Examples -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope -@end table +@itemize +@item +Make it sound as if there are twice as many instruments as are actually playing: +@example +aecho=0.8:0.88:60:0.4 +@end example -@item width, w -Determine how steep is the filter's shelf transition. -@end table +@item +If delay is very short, then it sound like a (metallic) robot playing music: +@example +aecho=0.8:0.88:6:0.4 +@end example -@section treble +@item +A longer delay will sound like an open air concert in the mountains: +@example +aecho=0.8:0.9:1000:0.3 +@end example -Boost or cut treble (upper) frequencies of the audio using a two-pole -shelving filter with a response similar to that of a standard -hi-fi's tone-controls. This is also known as shelving equalisation (EQ). +@item +Same as above but with one more mountain: +@example +aecho=0.8:0.9:1000|1800:0.3|0.25 +@end example +@end itemize -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". +@section aeval -A description of the accepted parameters follows. +Modify an audio signal according to the specified expressions. -@table @option -@item gain, g -Give the gain at whichever is the lower of ~22 kHz and the -Nyquist frequency. Its useful range is about -20 (for a large cut) -to +20 (for a large boost). Beware of clipping when using a positive gain. +This filter accepts one or more expressions (one for each channel), +which are evaluated and used to modify a corresponding audio signal. -@item frequency, f -Set the filter's central frequency and so can be used -to extend or reduce the frequency range to be boosted or cut. -The default value is @code{3000} Hz. +This filter accepts the following options: -@item width_type -Set method to specify band-width of filter. @table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope -@end table +@item exprs +Set the '|'-separated expressions list for each separate channel. If +the number of input channels is greater than the number of +expressions, the last specified expression is used for the remaining +output channels. -@item width, w -Determine how steep is the filter's shelf transition. +@item channel_layout, c +Set output channel layout. If not specified, the channel layout is +specified by the number of expressions. If set to @samp{same}, it will +use by default the same input channel layout. @end table -@section bandpass - -Apply a two-pole Butterworth band-pass filter with central -frequency @var{frequency}, and (3dB-point) band-width width. -The @var{csg} option selects a constant skirt gain (peak gain = Q) -instead of the default: constant 0dB peak gain. -The filter roll off at 6dB per octave (20dB per decade). - -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". - -A description of the accepted parameters follows. +Each expression in @var{exprs} can contain the following constants and functions: @table @option -@item frequency, f -Set the filter's central frequency. Default is @code{3000}. +@item ch +channel number of the current expression -@item csg -Constant skirt gain if set to 1. Defaults to 0. +@item n +number of the evaluated sample, starting from 0 -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave @item s -slope -@end table - -@item width, w -Specify the band-width of a filter in width_type units. -@end table - -@section bandreject - -Apply a two-pole Butterworth band-reject filter with central -frequency @var{frequency}, and (3dB-point) band-width @var{width}. -The filter roll off at 6dB per octave (20dB per decade). - -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". +sample rate -A description of the accepted parameters follows. +@item t +time of the evaluated sample expressed in seconds -@table @option -@item frequency, f -Set the filter's central frequency. Default is @code{3000}. +@item nb_in_channels +@item nb_out_channels +input and output number of channels -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope +@item val(CH) +the value of input channel with number @var{CH} @end table -@item width, w -Specify the band-width of a filter in width_type units. -@end table - -@section biquad - -Apply a biquad IIR filter with the given coefficients. -Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} -are the numerator and denominator coefficients respectively. - -@section equalizer - -Apply a two-pole peaking equalisation (EQ) filter. With this -filter, the signal-level at and around a selected frequency can -be increased or decreased, whilst (unlike bandpass and bandreject -filters) that at all other frequencies is unchanged. +Note: this filter is slow. For faster processing you should use a +dedicated filter. -In order to produce complex equalisation curves, this filter can -be given several times, each with a different central frequency. - -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". - -A description of the accepted parameters follows. - -@table @option -@item frequency, f -Set the filter's central frequency in Hz. - -@item width_type -Set method to specify band-width of filter. -@table @option -@item h -Hz -@item q -Q-Factor -@item o -octave -@item s -slope -@end table +@subsection Examples -@item width, w -Specify the band-width of a filter in width_type units. +@itemize +@item +Half volume: +@example +aeval=val(ch)/2:c=same +@end example -@item gain, g -Set the required gain or attenuation in dB. -Beware of clipping when using a positive gain. -@end table +@item +Invert phase of the second channel: +@example +eval=val(0)|-val(1) +@end example +@end itemize @section afade Apply fade-in/out effect to input audio. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". - A description of the accepted parameters follows. @table @option @@ -607,15 +521,26 @@ volume as the input audio, at the end of the fade-out transition the output audio will be silence. Default is 44100. @item start_time, st -Specify time in seconds for starting to apply the fade -effect. Default is 0. +Specify time for starting to apply the fade effect. Default is 0. +The accepted syntax is: +@example +[-]HH[:MM[:SS[.m...]]] +[-]S+[.m...] +@end example +See also the function @code{av_parse_time()}. If set this option is used instead of @var{start_sample} one. @item duration, d -Specify the number of seconds for which the fade effect has to last. At -the end of the fade-in effect the output audio will have the same +Specify the duration for which the fade effect has to last. Default is 0. +The accepted syntax is: +@example +[-]HH[:MM[:SS[.m...]]] +[-]S+[.m...] +@end example +See also the function @code{av_parse_time()}. +At the end of the fade-in effect the output audio will have the same volume as the input audio, at the end of the fade-out transition -the output audio will be silence. Default is 0. +the output audio will be silence. If set this option is used instead of @var{nb_samples} one. @item curve @@ -658,7 +583,7 @@ afade=t=in:ss=0:d=15 @item Fade out last 25 seconds of a 900 seconds audio: @example -afade=t=out:ss=875:d=25 +afade=t=out:st=875:d=25 @end example @end itemize @@ -672,28 +597,60 @@ The filter accepts the following named parameters: @table @option @item sample_fmts -A comma-separated list of requested sample formats. +A '|'-separated list of requested sample formats. @item sample_rates -A comma-separated list of requested sample rates. +A '|'-separated list of requested sample rates. @item channel_layouts -A comma-separated list of requested channel layouts. +A '|'-separated list of requested channel layouts. +See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} +for the required syntax. @end table If a parameter is omitted, all values are allowed. For example to force the output to either unsigned 8-bit or signed 16-bit stereo: @example -aformat='sample_fmts=u8,s16:channel_layouts=stereo' +aformat=sample_fmts=u8|s16:channel_layouts=stereo @end example +@section allpass + +Apply a two-pole all-pass filter with central frequency (in Hz) +@var{frequency}, and filter-width @var{width}. +An all-pass filter changes the audio's frequency to phase relationship +without changing its frequency to amplitude relationship. + +The filter accepts the following options: + +@table @option +@item frequency, f +Set frequency in Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +@end table + @section amerge Merge two or more audio streams into a single multi-channel stream. -The filter accepts the following named options: +The filter accepts the following options: @table @option @@ -734,16 +691,9 @@ amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge @end example @item -Multiple merges: +Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: @example -ffmpeg -f lavfi -i " -amovie=input.mkv:si=0 [a0]; -amovie=input.mkv:si=1 [a1]; -amovie=input.mkv:si=2 [a2]; -amovie=input.mkv:si=3 [a3]; -amovie=input.mkv:si=4 [a4]; -amovie=input.mkv:si=5 [a5]; -[a0][a1][a2][a3][a4][a5] amerge=inputs=6" -c:a pcm_s16le output.mkv +ffmpeg -i input.mkv -filter_complex "[0:1][0:2][0:3][0:4][0:5][0:6] amerge=inputs=6" -c:a pcm_s16le output.mkv @end example @end itemize @@ -794,6 +744,40 @@ Pass the audio source unchanged to the output. 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. +@section aphaser +Add a phasing effect to the input audio. + +A phaser filter creates series of peaks and troughs in the frequency spectrum. +The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. + +A description of the accepted parameters follows. + +@table @option +@item in_gain +Set input gain. Default is 0.4. + +@item out_gain +Set output gain. Default is 0.74 + +@item delay +Set delay in milliseconds. Default is 3.0. + +@item decay +Set decay. Default is 0.4. + +@item speed +Set modulation speed in Hz. Default is 0.5. + +@item type +Set modulation type. Default is triangular. + +It accepts the following values: +@table @samp +@item triangular, t +@item sinusoidal, s +@end table +@end table + @anchor{aresample} @section aresample @@ -836,8 +820,7 @@ The last output packet may contain a different number of samples, as the filter will flush all the remaining samples when the input audio signal its end. -The filter accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". +The filter accepts the following options: @table @option @@ -858,6 +841,18 @@ disable padding for the last frame, use: asetnsamples=n=1234:p=0 @end example +@section asetrate + +Set the sample rate without altering the PCM data. +This will result in a change of speed and pitch. + +The filter accepts the following options: + +@table @option +@item sample_rate, r +Set the output sample rate. Default is 44100 Hz. +@end table + @section ashowinfo Show a line containing various information for each input audio frame. @@ -903,37 +898,60 @@ the data is treated as if all the planes were concatenated. A list of Adler-32 checksums for each data plane. @end table -@section asplit +@section astats -Split input audio into several identical outputs. +Display time domain statistical information about the audio channels. +Statistics are calculated and displayed for each audio channel and, +where applicable, an overall figure is also given. -The filter accepts a single parameter which specifies the number of outputs. If -unspecified, it defaults to 2. +The filter accepts the following option: +@table @option +@item length +Short window length in seconds, used for peak and trough RMS measurement. +Default is @code{0.05} (50 miliseconds). Allowed range is @code{[0.1 - 10]}. +@end table -For example: -@example -[in] asplit [out0][out1] -@end example +A description of each shown parameter follows: -will create two separate outputs from the same input. +@table @option +@item DC offset +Mean amplitude displacement from zero. -To create 3 or more outputs, you need to specify the number of -outputs, like in: -@example -[in] asplit=3 [out0][out1][out2] -@end example +@item Min level +Minimal sample level. -@example -ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT -@end example -will create 5 copies of the input audio. +@item Max level +Maximal sample level. + +@item Peak level dB +@item RMS level dB +Standard peak and RMS level measured in dBFS. +@item RMS peak dB +@item RMS trough dB +Peak and trough values for RMS level measured over a short window. + +@item Crest factor +Standard ratio of peak to RMS level (note: not in dB). + +@item Flat factor +Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels +(i.e. either @var{Min level} or @var{Max level}). + +@item Peak count +Number of occasions (not the number of samples) that the signal attained either +@var{Min level} or @var{Max level}. +@end table @section astreamsync Forward two audio streams and control the order the buffers are forwarded. -The argument to the filter is an expression deciding which stream should be +The filter accepts the following options: + +@table @option +@item expr, e +Set the expression deciding which stream should be forwarded next: if the result is negative, the first stream is forwarded; if the result is positive or zero, the second stream is forwarded. It can use the following variables: @@ -949,8 +967,11 @@ current timestamp of each stream The default value is @code{t1-t2}, which means to always forward the stream that has a smaller timestamp. +@end table -Example: stress-test @code{amerge} by randomly sending buffers on the wrong +@subsection Examples + +Stress-test @code{amerge} by randomly sending buffers on the wrong input, while avoiding too much of a desynchronization: @example amovie=file.ogg [a] ; amovie=file.mp3 [b] ; @@ -958,6 +979,39 @@ amovie=file.ogg [a] ; amovie=file.mp3 [b] ; [a2] [b2] amerge @end example +@section asyncts + +Synchronize audio data with timestamps by squeezing/stretching it and/or +dropping samples/adding silence when needed. + +This filter is not built by default, please use @ref{aresample} to do squeezing/stretching. + +The filter accepts the following named parameters: +@table @option + +@item compensate +Enable stretching/squeezing the data to make it match the timestamps. Disabled +by default. When disabled, time gaps are covered with silence. + +@item min_delta +Minimum difference between timestamps and audio data (in seconds) to trigger +adding/dropping samples. Default value is 0.1. If you get non-perfect sync with +this filter, try setting this parameter to 0. + +@item max_comp +Maximum compensation in samples per second. Relevant only with compensate=1. +Default value 500. + +@item first_pts +Assume the first pts should be this value. The time base is 1 / sample rate. +This allows for padding/trimming at the start of stream. By default, no +assumption is made about the first frame's expected pts, so no padding or +trimming is done. For example, this could be set to 0 to pad the beginning with +silence if an audio stream starts after the video stream or to trim any samples +with a negative pts due to encoder delay. + +@end table + @section atempo Adjust audio tempo. @@ -982,6 +1036,317 @@ atempo=1.25 @end example @end itemize +@section atrim + +Trim the input so that the output contains one continuous subpart of the input. + +This filter accepts the following options: +@table @option +@item start +Specify time of the start of the kept section, i.e. the audio sample +with the timestamp @var{start} will be the first sample in the output. + +@item end +Specify time of the first audio sample that will be dropped, i.e. the +audio sample immediately preceding the one with the timestamp @var{end} will be +the last sample in the output. + +@item start_pts +Same as @var{start}, except this option sets the start timestamp in samples +instead of seconds. + +@item end_pts +Same as @var{end}, except this option sets the end timestamp in samples instead +of seconds. + +@item duration +Specify maximum duration of the output. + +@item start_sample +Number of the first sample that should be passed to output. + +@item end_sample +Number of the first sample that should be dropped. +@end table + +@option{start}, @option{end}, @option{duration} are expressed as time +duration specifications, check the "Time duration" section in the +ffmpeg-utils manual. + +Note that the first two sets of the start/end options and the @option{duration} +option look at the frame timestamp, while the _sample options simply count the +samples that pass through the filter. So start/end_pts and start/end_sample will +give different results when the timestamps are wrong, inexact or do not start at +zero. Also note that this filter does not modify the timestamps. If you wish +that the output timestamps start at zero, insert the asetpts filter after the +atrim filter. + +If multiple start or end options are set, this filter tries to be greedy and +keep all samples that match at least one of the specified constraints. To keep +only the part that matches all the constraints at once, chain multiple atrim +filters. + +The defaults are such that all the input is kept. So it is possible to set e.g. +just the end values to keep everything before the specified time. + +Examples: +@itemize +@item +drop everything except the second minute of input +@example +ffmpeg -i INPUT -af atrim=60:120 +@end example + +@item +keep only the first 1000 samples +@example +ffmpeg -i INPUT -af atrim=end_sample=1000 +@end example + +@end itemize + +@section bandpass + +Apply a two-pole Butterworth band-pass filter with central +frequency @var{frequency}, and (3dB-point) band-width width. +The @var{csg} option selects a constant skirt gain (peak gain = Q) +instead of the default: constant 0dB peak gain. +The filter roll off at 6dB per octave (20dB per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set the filter's central frequency. Default is @code{3000}. + +@item csg +Constant skirt gain if set to 1. Defaults to 0. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +@end table + +@section bandreject + +Apply a two-pole Butterworth band-reject filter with central +frequency @var{frequency}, and (3dB-point) band-width @var{width}. +The filter roll off at 6dB per octave (20dB per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set the filter's central frequency. Default is @code{3000}. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +@end table + +@section bass + +Boost or cut the bass (lower) frequencies of the audio using a two-pole +shelving filter with a response similar to that of a standard +hi-fi's tone-controls. This is also known as shelving equalisation (EQ). + +The filter accepts the following options: + +@table @option +@item gain, g +Give the gain at 0 Hz. Its useful range is about -20 +(for a large cut) to +20 (for a large boost). +Beware of clipping when using a positive gain. + +@item frequency, f +Set the filter's central frequency and so can be used +to extend or reduce the frequency range to be boosted or cut. +The default value is @code{100} Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Determine how steep is the filter's shelf transition. +@end table + +@section biquad + +Apply a biquad IIR filter with the given coefficients. +Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} +are the numerator and denominator coefficients respectively. + +@section channelmap + +Remap input channels to new locations. + +This filter accepts the following named parameters: +@table @option +@item channel_layout +Channel layout of the output stream. + +@item map +Map channels from input to output. The argument is a '|'-separated list of +mappings, each in the @code{@var{in_channel}-@var{out_channel}} or +@var{in_channel} form. @var{in_channel} can be either the name of the input +channel (e.g. FL for front left) or its index in the input channel layout. +@var{out_channel} is the name of the output channel or its index in the output +channel layout. If @var{out_channel} is not given then it is implicitly an +index, starting with zero and increasing by one for each mapping. +@end table + +If no mapping is present, the filter will implicitly map input channels to +output channels preserving index. + +For example, assuming a 5.1+downmix input MOV file +@example +ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav +@end example +will create an output WAV file tagged as stereo from the downmix channels of +the input. + +To fix a 5.1 WAV improperly encoded in AAC's native channel order +@example +ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav +@end example + +@section channelsplit + +Split each channel in input audio stream into a separate output stream. + +This filter accepts the following named parameters: +@table @option +@item channel_layout +Channel layout of the input stream. Default is "stereo". +@end table + +For example, assuming a stereo input MP3 file +@example +ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv +@end example +will create an output Matroska file with two audio streams, one containing only +the left channel and the other the right channel. + +To split a 5.1 WAV file into per-channel files +@example +ffmpeg -i in.wav -filter_complex +'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' +-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' +front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' +side_right.wav +@end example + +@section compand + +Compress or expand audio dynamic range. + +A description of the accepted options follows. + +@table @option +@item attacks +@item decays +Set list of times in seconds for each channel over which the instantaneous +level of the input signal is averaged to determine its volume. +@option{attacks} refers to increase of volume and @option{decays} refers +to decrease of volume. +For most situations, the attack time (response to the audio getting louder) +should be shorter than the decay time because the human ear is more sensitive +to sudden loud audio than sudden soft audio. +Typical value for attack is @code{0.3} seconds and for decay @code{0.8} +seconds. + +@item points +Set list of points for transfer function, specified in dB relative to maximum +possible signal amplitude. +Each key points list need to be defined using the following syntax: +@code{x0/y0 x1/y1 x2/y2 ...}. + +The input values must be in strictly increasing order but the transfer +function does not have to be monotonically rising. +The point @code{0/0} is assumed but may be overridden (by @code{0/out-dBn}). +Typical values for the transfer function are @code{-70/-70 -60/-20}. + +@item soft-knee +Set amount for which the points at where adjacent line segments on the +transfer function meet will be rounded. Defaults is @code{0.01}. + +@item gain +Set additional gain in dB to be applied at all points on the transfer function +and allows easy adjustment of the overall gain. +Default is @code{0}. + +@item volume +Set initial volume in dB to be assumed for each channel when filtering starts. +This permits the user to supply a nominal level initially, so that, +for example, a very large gain is not applied to initial signal levels before +the companding has begun to operate. A typical value for audio which is +initially quiet is -90 dB. Default is @code{0}. + +@item delay +Set delay in seconds. Default is @code{0}. The input audio +is analysed immediately, but audio is delayed before being fed to the +volume adjuster. Specifying a delay approximately equal to the attack/decay +times allows the filter to effectively operate in predictive rather than +reactive mode. +@end table + +@subsection Examples +@itemize +@item +Make music with both quiet and loud passages suitable for listening +in a noisy environment: +@example +compand=.3 .3:1 1:-90/-60 -60/-40 -40/-30 -20/-20:6:0:-90:0.2 +@end example + +@item +Noise-gate for when the noise is at a lower level than the signal: +@example +compand=.1 .1:.2 .2:-900/-900 -50.1/-900 -50/-50:.01:0:-90:.1 +@end example + +@item +Here is another noise-gate, this time for when the noise is at a higher level +than the signal (making it, in some ways, similar to squelch): +@example +compand=.1 .1:.1 .1:-45.1/-45.1 -45/-900 0/-900:.01:45:-90:.1 +@end example +@end itemize + @section earwax Make audio easier to listen to on headphones. @@ -993,6 +1358,260 @@ the listener (standard for speakers). Ported from SoX. +@section equalizer + +Apply a two-pole peaking equalisation (EQ) filter. With this +filter, the signal-level at and around a selected frequency can +be increased or decreased, whilst (unlike bandpass and bandreject +filters) that at all other frequencies is unchanged. + +In order to produce complex equalisation curves, this filter can +be given several times, each with a different central frequency. + +The filter accepts the following options: + +@table @option +@item frequency, f +Set the filter's central frequency in Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. + +@item gain, g +Set the required gain or attenuation in dB. +Beware of clipping when using a positive gain. +@end table + +@section highpass + +Apply a high-pass filter with 3dB point frequency. +The filter can be either single-pole, or double-pole (the default). +The filter roll off at 6dB per pole per octave (20dB per pole per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set frequency in Hz. Default is 3000. + +@item poles, p +Set number of poles. Default is 2. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +Applies only to double-pole filter. +The default is 0.707q and gives a Butterworth response. +@end table + +@section join + +Join multiple input streams into one multi-channel stream. + +The filter accepts the following named parameters: +@table @option + +@item inputs +Number of input streams. Defaults to 2. + +@item channel_layout +Desired output channel layout. Defaults to stereo. + +@item map +Map channels from inputs to output. The argument is a '|'-separated list of +mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} +form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} +can be either the name of the input channel (e.g. FL for front left) or its +index in the specified input stream. @var{out_channel} is the name of the output +channel. +@end table + +The filter will attempt to guess the mappings when those are not specified +explicitly. It does so by first trying to find an unused matching input channel +and if that fails it picks the first unused input channel. + +E.g. to join 3 inputs (with properly set channel layouts) +@example +ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT +@end example + +To build a 5.1 output from 6 single-channel streams: +@example +ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex +'join=inputs=6:channel_layout=5.1:map=0.0-FL|1.0-FR|2.0-FC|3.0-SL|4.0-SR|5.0-LFE' +out +@end example + +@section ladspa + +Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-ladspa}. + +@table @option +@item file, f +Specifies the name of LADSPA plugin library to load. If the environment +variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in +each one of the directories specified by the colon separated list in +@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in +this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, +@file{/usr/lib/ladspa/}. + +@item plugin, p +Specifies the plugin within the library. Some libraries contain only +one plugin, but others contain many of them. If this is not set filter +will list all available plugins within the specified library. + +@item controls, c +Set the '|' separated list of controls which are zero or more floating point +values that determine the behavior of the loaded plugin (for example delay, +threshold or gain). +Controls need to be defined using the following syntax: +c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where +@var{valuei} is the value set on the @var{i}-th control. +If @option{controls} is set to @code{help}, all available controls and +their valid ranges are printed. + +@item sample_rate, s +Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. + +@item nb_samples, n +Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. + +@item duration, d +Set the minimum duration of the sourced audio. See the function +@code{av_parse_time()} for the accepted format, also check the "Time duration" +section in the ffmpeg-utils manual. +Note that the resulting duration may be greater than the specified duration, +as the generated audio is always cut at the end of a complete frame. +If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. +Only used if plugin have zero inputs. + +@end table + +@subsection Examples + +@itemize +@item +List all available plugins within amp (LADSPA example plugin) library: +@example +ladspa=file=amp +@end example + +@item +List all available controls and their valid ranges for @code{vcf_notch} +plugin from @code{VCF} library: +@example +ladspa=f=vcf:p=vcf_notch:c=help +@end example + +@item +Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) +plugin library: +@example +ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 +@end example + +@item +Add reverberation to the audio using TAP-plugins +(Tom's Audio Processing plugins): +@example +ladspa=file=tap_reverb:tap_reverb +@end example + +@item +Generate white noise, with 0.2 amplitude: +@example +ladspa=file=cmt:noise_source_white:c=c0=.2 +@end example + +@item +Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the +@code{C* Audio Plugin Suite} (CAPS) library: +@example +ladspa=file=caps:Click:c=c1=20' +@end example + +@item +Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: +@example +ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 +@end example +@end itemize + +@subsection Commands + +This filter supports the following commands: +@table @option +@item cN +Modify the @var{N}-th control value. + +If the specified value is not valid, it is ignored and prior one is kept. +@end table + +@section lowpass + +Apply a low-pass filter with 3dB point frequency. +The filter can be either single-pole or double-pole (the default). +The filter roll off at 6dB per pole per octave (20dB per pole per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set frequency in Hz. Default is 500. + +@item poles, p +Set number of poles. Default is 2. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +Applies only to double-pole filter. +The default is 0.707q and gives a Butterworth response. +@end table + @section pan Mix channels with specific gain levels. The filter accepts the output @@ -1083,6 +1702,17 @@ front left and right: pan="stereo: c0=FR : c1=FR" @end example +@section replaygain + +ReplayGain scanner filter. This filter takes an audio stream as an input and +outputs it unchanged. +At end of filtering it displays @code{track_gain} and @code{track_peak}. + +@section resample + +Convert the audio sample format, sample rate and channel layout. This filter is +not meant to be used directly. + @section silencedetect Detect silence in an audio stream. @@ -1093,6 +1723,8 @@ minimum detected noise duration. The printed times and duration are expressed in seconds. +The filter accepts the following options: + @table @option @item duration, d Set silence duration until notification (default is 2 seconds). @@ -1115,156 +1747,56 @@ silencedetect=n=-50dB:d=5 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise tolerance in @file{silence.mp3}: @example -ffmpeg -f lavfi -i amovie=silence.mp3,silencedetect=noise=0.0001 -f null - +ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - @end example @end itemize -@section asyncts -Synchronize audio data with timestamps by squeezing/stretching it and/or -dropping samples/adding silence when needed. - -This filter is not built by default, please use @ref{aresample} to do squeezing/stretching. - -The filter accepts the following named parameters: -@table @option - -@item compensate -Enable stretching/squeezing the data to make it match the timestamps. Disabled -by default. When disabled, time gaps are covered with silence. - -@item min_delta -Minimum difference between timestamps and audio data (in seconds) to trigger -adding/dropping samples. Default value is 0.1. If you get non-perfect sync with -this filter, try setting this parameter to 0. - -@item max_comp -Maximum compensation in samples per second. Relevant only with compensate=1. -Default value 500. - -@item first_pts -Assume the first pts should be this value. The time base is 1 / sample rate. -This allows for padding/trimming at the start of stream. By default, no -assumption is made about the first frame's expected pts, so no padding or -trimming is done. For example, this could be set to 0 to pad the beginning with -silence if an audio stream starts after the video stream or to trim any samples -with a negative pts due to encoder delay. +@section treble -@end table +Boost or cut treble (upper) frequencies of the audio using a two-pole +shelving filter with a response similar to that of a standard +hi-fi's tone-controls. This is also known as shelving equalisation (EQ). -@section channelsplit -Split each channel in input audio stream into a separate output stream. +The filter accepts the following options: -This filter accepts the following named parameters: @table @option -@item channel_layout -Channel layout of the input stream. Default is "stereo". -@end table - -For example, assuming a stereo input MP3 file -@example -ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv -@end example -will create an output Matroska file with two audio streams, one containing only -the left channel and the other the right channel. - -To split a 5.1 WAV file into per-channel files -@example -ffmpeg -i in.wav -filter_complex -'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' --map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' -front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' -side_right.wav -@end example +@item gain, g +Give the gain at whichever is the lower of ~22 kHz and the +Nyquist frequency. Its useful range is about -20 (for a large cut) +to +20 (for a large boost). Beware of clipping when using a positive gain. -@section channelmap -Remap input channels to new locations. +@item frequency, f +Set the filter's central frequency and so can be used +to extend or reduce the frequency range to be boosted or cut. +The default value is @code{3000} Hz. -This filter accepts the following named parameters: +@item width_type +Set method to specify band-width of filter. @table @option -@item channel_layout -Channel layout of the output stream. - -@item map -Map channels from input to output. The argument is a comma-separated list of -mappings, each in the @code{@var{in_channel}-@var{out_channel}} or -@var{in_channel} form. @var{in_channel} can be either the name of the input -channel (e.g. FL for front left) or its index in the input channel layout. -@var{out_channel} is the name of the output channel or its index in the output -channel layout. If @var{out_channel} is not given then it is implicitly an -index, starting with zero and increasing by one for each mapping. +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope @end table -If no mapping is present, the filter will implicitly map input channels to -output channels preserving index. - -For example, assuming a 5.1+downmix input MOV file -@example -ffmpeg -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav -@end example -will create an output WAV file tagged as stereo from the downmix channels of -the input. - -To fix a 5.1 WAV improperly encoded in AAC's native channel order -@example -ffmpeg -i in.wav -filter 'channelmap=1\,2\,0\,5\,3\,4:channel_layout=5.1' out.wav -@end example - -@section join -Join multiple input streams into one multi-channel stream. - -The filter accepts the following named parameters: -@table @option - -@item inputs -Number of input streams. Defaults to 2. - -@item channel_layout -Desired output channel layout. Defaults to stereo. - -@item map -Map channels from inputs to output. The argument is a comma-separated list of -mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} -form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} -can be either the name of the input channel (e.g. FL for front left) or its -index in the specified input stream. @var{out_channel} is the name of the output -channel. +@item width, w +Determine how steep is the filter's shelf transition. @end table -The filter will attempt to guess the mappings when those are not specified -explicitly. It does so by first trying to find an unused matching input channel -and if that fails it picks the first unused input channel. - -E.g. to join 3 inputs (with properly set channel layouts) -@example -ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT -@end example - -To build a 5.1 output from 6 single-channel streams: -@example -ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex -'join=inputs=6:channel_layout=5.1:map=0.0-FL\,1.0-FR\,2.0-FC\,3.0-SL\,4.0-SR\,5.0-LFE' -out -@end example - -@section resample -Convert the audio sample format, sample rate and channel layout. This filter is -not meant to be used directly. - @section volume Adjust the input audio volume. -The filter accepts the following named parameters. If the key of the -first options is omitted, the arguments are interpreted according to -the following syntax: -@example -volume=@var{volume}:@var{precision} -@end example +The filter accepts the following options: @table @option @item volume -Expresses how the audio volume will be increased or decreased. +Set audio volume expression. Output values are clipped to the maximum value. @@ -1273,7 +1805,7 @@ The output audio volume is given by the relation: @var{output_volume} = @var{volume} * @var{input_volume} @end example -Default value for @var{volume} is 1.0. +Default value for @var{volume} is "1.0". @item precision Set the mathematical precision. @@ -1289,6 +1821,66 @@ precision of the volume scaling. @item double 64-bit floating-point; limits input sample format to DBL. @end table + +@item eval +Set when the volume expression is evaluated. + +It accepts the following values: +@table @samp +@item once +only evaluate expression once during the filter initialization, or +when the @samp{volume} command is sent + +@item frame +evaluate expression for each incoming frame +@end table + +Default value is @samp{once}. +@end table + +The volume expression can contain the following parameters. + +@table @option +@item n +frame number (starting at zero) +@item nb_channels +number of channels +@item nb_consumed_samples +number of samples consumed by the filter +@item nb_samples +number of samples in the current frame +@item pos +original frame position in the file +@item pts +frame PTS +@item sample_rate +sample rate +@item startpts +PTS at start of stream +@item startt +time at start of stream +@item t +frame time +@item tb +timestamp timebase +@item volume +last set volume value +@end table + +Note that when @option{eval} is set to @samp{once} only the +@var{sample_rate} and @var{tb} variables are available, all other +variables will evaluate to NAN. + +@subsection Commands + +This filter supports the following commands: +@table @option +@item volume +Modify the volume expression. +The command accepts the same syntax of the corresponding option. + +If the specified expression is not valid, it is kept at its current +value. @end table @subsection Examples @@ -1313,6 +1905,12 @@ Increase input audio power by 6 decibels using fixed-point precision: @example volume=volume=6dB:precision=fixed @end example + +@item +Fade volume after time 10 with an annihilation period of 5 seconds: +@example +volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame +@end example @end itemize @section volumedetect @@ -1323,7 +1921,7 @@ The filter has no parameters. The input is not modified. Statistics about the volume will be printed in the log when the input stream end is reached. In particular it will show the mean volume (root mean square), maximum -volume (on a per-sample basis), and the beginning of an histogram of the +volume (on a per-sample basis), and the beginning of a histogram of the registered volume values (from the maximum value to a cumulated 1/1000 of the samples). @@ -1371,11 +1969,14 @@ Buffer audio frames, and make them available to the filter chain. This source is mainly intended for a programmatic use, in particular through the interface defined in @file{libavfilter/asrc_abuffer.h}. -It accepts the following mandatory parameters: -@var{sample_rate}:@var{sample_fmt}:@var{channel_layout} +It accepts the following named parameters: @table @option +@item time_base +Timebase which will be used for timestamps of submitted frames. It must be +either a floating-point number or in @var{numerator}/@var{denominator} form. + @item sample_rate The sample rate of the incoming audio buffers. @@ -1400,7 +2001,7 @@ must be consistent. @subsection Examples @example -abuffer=44100:s16p:stereo +abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo @end example will instruct the source to accept planar 16bit signed stereo at 44100Hz. @@ -1408,7 +2009,7 @@ Since the sample format with name "s16p" corresponds to the number 6 and the "stereo" channel layout corresponds to the value 0x3, this is equivalent to: @example -abuffer=44100:6:0x3 +abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 @end example @section aevalsrc @@ -1419,18 +2020,14 @@ This source accepts in input one or more expressions (one for each channel), which are evaluated and used to generate a corresponding audio signal. -It accepts the syntax: @var{exprs}[::@var{options}]. -@var{exprs} is a list of expressions separated by ":", one for each -separate channel. In case the @var{channel_layout} is not -specified, the selected channel layout depends on the number of -provided expressions. - -@var{options} is an optional sequence of @var{key}=@var{value} pairs, -separated by ":". - -The description of the accepted options follows. +This source accepts the following options: @table @option +@item exprs +Set the '|'-separated expressions list for each separate channel. In case the +@option{channel_layout} option is not specified, the selected channel layout +depends on the number of provided expressions. Otherwise the last +specified expression is applied to the remaining output channels. @item channel_layout, c Set the channel layout. The number of channels in the specified layout @@ -1481,14 +2078,14 @@ aevalsrc=0 Generate a sin signal with frequency of 440 Hz, set sample rate to 8000 Hz: @example -aevalsrc="sin(440*2*PI*t)::s=8000" +aevalsrc="sin(440*2*PI*t):s=8000" @end example @item Generate a two channels signal, specify the channel layout (Front Center + Back Center) explicitly: @example -aevalsrc="sin(420*2*PI*t):cos(430*2*PI*t)::c=FC|BC" +aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" @end example @item @@ -1506,7 +2103,7 @@ aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" @item Generate 2.5 Hz binaural beats on a 360 Hz carrier: @example -aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) : 0.1*sin(2*PI*(360+2.5/2)*t)" +aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" @end example @end itemize @@ -1518,16 +2115,10 @@ as a template and to be employed in analysis / debugging tools, or as the source for filters which ignore the input data (for example the sox synth filter). -It accepts an optional sequence of @var{key}=@var{value} pairs, -separated by ":". - -The description of the accepted options follows. +This source accepts the following options: @table @option -@item sample_rate, s -Specify the sample rate, and defaults to 44100. - @item channel_layout, cl Specify the channel layout, and can be either an integer or a string @@ -1538,6 +2129,9 @@ Check the channel_layout_map definition in @file{libavutil/channel_layout.c} for the mapping between strings and channel layout values. +@item sample_rate, r +Specify the sample rate, and defaults to 44100. + @item nb_samples, n Set the number of samples per requested frames. @@ -1559,31 +2153,6 @@ anullsrc=r=48000:cl=mono @end example @end itemize -@section abuffer -Buffer audio frames, and make them available to the filter chain. - -This source is not intended to be part of user-supplied graph descriptions but -for insertion by calling programs through the interface defined in -@file{libavfilter/buffersrc.h}. - -It accepts the following named parameters: -@table @option - -@item time_base -Timebase which will be used for timestamps of submitted frames. It must be -either a floating-point number or in @var{numerator}/@var{denominator} form. - -@item sample_rate -Audio sample rate. - -@item sample_fmt -Name of the sample format, as returned by @code{av_get_sample_fmt_name()}. - -@item channel_layout -Channel layout of the audio data, in the form that can be accepted by -@code{av_get_channel_layout()}. -@end table - All the parameters need to be explicitly defined. @section flite @@ -1595,10 +2164,7 @@ To enable compilation of this filter you need to configure FFmpeg with Note that the flite library is not thread-safe. -The source accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". - -The description of the accepted parameters follows. +The filter accepts the following options: @table @option @@ -1659,11 +2225,7 @@ Generate an audio signal made of a sine wave with amplitude 1/8. The audio signal is bit-exact. -It accepts a list of options in the form of @var{key}=@var{value} pairs -separated by ":". If the option name is omitted, the first option is the -frequency and the second option is the beep factor. - -The supported options are: +The filter accepts the following options: @table @option @@ -1674,7 +2236,7 @@ Set the carrier frequency. Default is 440 Hz. Enable a periodic beep every second with frequency @var{beep_factor} times the carrier frequency. Default is 0, meaning the beep is disabled. -@item sample_rate, s +@item sample_rate, r Specify the sample rate, default is 44100. @item duration, d @@ -1716,9 +2278,10 @@ Below is a description of the currently available audio sinks. Buffer audio frames, and make them available to the end of filter chain. This sink is mainly intended for programmatic use, in particular -through the interface defined in @file{libavfilter/buffersink.h}. +through the interface defined in @file{libavfilter/buffersink.h} +or the options system. -It requires a pointer to an AVABufferSinkContext structure, which +It accepts a pointer to an AVABufferSinkContext structure, which defines the incoming buffers' formats, to be passed as the opaque parameter to @code{avfilter_init_filter} for initialization. @@ -1728,13 +2291,6 @@ Null audio sink, do absolutely nothing with the input audio. It is mainly useful as a template and to be employed in analysis / debugging tools. -@section abuffersink -This sink is intended for programmatic use. Frames that arrive on this sink can -be retrieved by the calling program using the interface defined in -@file{libavfilter/buffersink.h}. - -This filter accepts no parameters. - @c man end AUDIO SINKS @chapter Video Filters @@ -1788,6 +2344,13 @@ luminance value greater than the minimum allowed value. The parameters describing the bounding box are printed on the filter log. +The filter accepts the following option: + +@table @option +@item min_val +Set the minimal luminance value. Default is @code{16}. +@end table + @section blackdetect Detect video intervals that are (almost) completely black. Can be @@ -1798,9 +2361,7 @@ duration of the detected black interval expressed in seconds. In order to display the output lines, you need to set the loglevel at least to the AV_LOG_INFO value. -This filter accepts a list of options in the form of -@var{key}=@var{value} pairs separated by ":". A description of the -accepted options follows. +The filter accepts the following options: @table @option @item black_min_duration, d @@ -1852,21 +2413,18 @@ the position in the file if known or -1 and the timestamp in seconds. In order to display the output lines, you need to set the loglevel at least to the AV_LOG_INFO value. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax -blackframe[=@var{amount}[:@var{threshold}]]. - -A description of the accepted options follows. +The filter accepts the following options: @table @option + @item amount -Set the percentage of pixels that have to be below the -threshold to enable black detection. Default value is 98. +Set the percentage of the pixels that have to be below the threshold, defaults +to @code{98}. + +@item threshold, thresh +Set the threshold below which a pixel value is considered black, defaults to +@code{32}. -@item threshold -Set the threshold below which a pixel value is considered -black. Default value is 32. @end table @section blend @@ -1877,8 +2435,7 @@ It takes two input streams and outputs one stream, the first input is the "top" layer and second input is "bottom" layer. Output terminates when shortest input terminates. -This filter accepts a list of options in the form of @var{key}=@var{value} -pairs separated by ":". A description of the accepted options follows. +A description of the accepted options follows. @table @option @item c0_mode @@ -1923,7 +2480,7 @@ Available values for component modes are: @item c3_opacity @item all_opacity Set blend opacity for specific pixel component or all pixel components in case -of @var{all_expr}. Only used in combination with pixel component blend modes. +of @var{all_opacity}. Only used in combination with pixel component blend modes. @item c0_expr @item c1_expr @@ -1936,6 +2493,9 @@ of @var{all_expr}. Note that related mode options will be ignored if those are s The expressions can use the following variables: @table @option +@item N +The sequential number of the filtered frame, starting from @code{0}. + @item X @item Y the coordinates of the current sample @@ -1960,6 +2520,13 @@ Value of pixel component at current location for first video frame (top layer). @item BOTTOM, B Value of pixel component at current location for second video frame (bottom layer). @end table + +@item shortest +Force termination when the shortest input terminates. Default is @code{0}. +@item repeatlast +Continue applying the last bottom frame after the end of the stream. A value of +@code{0} disable the filter after the last frame of the bottom layer is reached. +Default is @code{1}. @end table @subsection Examples @@ -1976,16 +2543,42 @@ Apply 1x1 checkerboard effect: @example blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' @end example + +@item +Apply uncover left effect: +@example +blend=all_expr='if(gte(N*SW+X,W),A,B)' +@end example + +@item +Apply uncover down effect: +@example +blend=all_expr='if(gte(Y-N*SH,0),A,B)' +@end example + +@item +Apply uncover up-left effect: +@example +blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' +@end example @end itemize @section boxblur Apply boxblur algorithm to the input video. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax -@option{luma_radius}:@option{luma_power}:@option{chroma_radius}:@option{chroma_power}:@option{alpha_radius}:@option{alpha_power}. +The filter accepts the following options: + +@table @option + +@item luma_radius, lr +@item luma_power, lp +@item chroma_radius, cr +@item chroma_power, cp +@item alpha_radius, ar +@item alpha_power, ap + +@end table A description of the accepted options follows. @@ -2007,13 +2600,16 @@ corresponding value set for @option{luma_radius}. The expressions can contain the following constants: @table @option -@item w, h +@item w +@item h the input width and height in pixels -@item cw, ch +@item cw +@item ch the input chroma image width and height in pixels -@item hsub, vsub +@item hsub +@item vsub horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. @end table @@ -2038,6 +2634,7 @@ A value of 0 will disable the effect. Apply a boxblur filter with luma, chroma, and alpha radius set to 2: @example +boxblur=luma_radius=2:luma_power=1 boxblur=2:1 @end example @@ -2050,18 +2647,139 @@ boxblur=2:1:cr=0:ar=0 @item Set luma and chroma radius to a fraction of the video dimension: @example -boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1 +boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 +@end example +@end itemize + +@section colorbalance +Modify intensity of primary colors (red, green and blue) of input frames. + +The filter allows an input frame to be adjusted in the shadows, midtones or highlights +regions for the red-cyan, green-magenta or blue-yellow balance. + +A positive adjustment value shifts the balance towards the primary color, a negative +value towards the complementary color. + +The filter accepts the following options: + +@table @option +@item rs +@item gs +@item bs +Adjust red, green and blue shadows (darkest pixels). + +@item rm +@item gm +@item bm +Adjust red, green and blue midtones (medium pixels). + +@item rh +@item gh +@item bh +Adjust red, green and blue highlights (brightest pixels). + +Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. +@end table + +@subsection Examples + +@itemize +@item +Add red color cast to shadows: +@example +colorbalance=rs=.3 +@end example +@end itemize + +@section colorchannelmixer + +Adjust video input frames by re-mixing color channels. + +This filter modifies a color channel by adding the values associated to +the other channels of the same pixels. For example if the value to +modify is red, the output value will be: +@example +@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} +@end example + +The filter accepts the following options: + +@table @option +@item rr +@item rg +@item rb +@item ra +Adjust contribution of input red, green, blue and alpha channels for output red channel. +Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. + +@item gr +@item gg +@item gb +@item ga +Adjust contribution of input red, green, blue and alpha channels for output green channel. +Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. + +@item br +@item bg +@item bb +@item ba +Adjust contribution of input red, green, blue and alpha channels for output blue channel. +Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. + +@item ar +@item ag +@item ab +@item aa +Adjust contribution of input red, green, blue and alpha channels for output alpha channel. +Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. + +Allowed ranges for options are @code{[-2.0, 2.0]}. +@end table + +@subsection Examples + +@itemize +@item +Convert source to grayscale: +@example +colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 +@end example +@item +Simulate sepia tones: +@example +colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 @end example @end itemize @section colormatrix -The colormatrix filter allows conversion between any of the following color -space: BT.709 (@var{bt709}), BT.601 (@var{bt601}), SMPTE-240M (@var{smpte240m}) -and FCC (@var{fcc}). +Convert color matrix. -The syntax of the parameters is @var{source}:@var{destination}: +The filter accepts the following options: + +@table @option +@item src +@item dst +Specify the source and destination color matrix. Both values must be +specified. +The accepted values are: +@table @samp +@item bt709 +BT.709 + +@item bt601 +BT.601 + +@item smpte240m +SMPTE-240M + +@item fcc +FCC +@end table +@end table + +For example to convert from BT.601 to SMPTE-240M, use the command: @example colormatrix=bt601:smpte240m @end example @@ -2073,32 +2791,28 @@ testing purposes. @section crop -Crop the input video. +Crop the input video to given dimensions. -This filter accepts a list of @var{key}=@var{value} pairs as argument, -separated by ':'. If the key of the first options is omitted, the -arguments are interpreted according to the syntax -@var{out_w}:@var{out_h}:@var{x}:@var{y}:@var{keep_aspect}. +The filter accepts the following options: -A description of the accepted options follows: @table @option @item w, out_w -Set the crop area width. It defaults to @code{iw}. +Width of the output video. It defaults to @code{iw}. This expression is evaluated only once during the filter configuration. @item h, out_h -Set the crop area width. It defaults to @code{ih}. +Height of the output video. It defaults to @code{ih}. This expression is evaluated only once during the filter configuration. @item x -Set the expression for the x top-left coordinate of the cropped area. +Horizontal position, in the input video, of the left edge of the output video. It defaults to @code{(in_w-out_w)/2}. This expression is evaluated per-frame. @item y -Set the expression for the y top-left coordinate of the cropped area. +Vertical position, in the input video, of the top edge of the output video. It defaults to @code{(in_h-out_h)/2}. This expression is evaluated per-frame. @@ -2112,20 +2826,25 @@ The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are expressions containing the following constants: @table @option -@item x, y +@item x +@item y the computed values for @var{x} and @var{y}. They are evaluated for each new frame. -@item in_w, in_h +@item in_w +@item in_h the input width and height -@item iw, ih +@item iw +@item ih same as @var{in_w} and @var{in_h} -@item out_w, out_h +@item out_w +@item out_h the output (cropped) width and height -@item ow, oh +@item ow +@item oh same as @var{out_w} and @var{out_h} @item a @@ -2137,13 +2856,17 @@ input sample aspect ratio @item dar input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} -@item hsub, vsub +@item hsub +@item vsub horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. @item n the number of input frame, starting from 0 +@item pos +the position in the file of the input frame, NAN if unknown + @item t timestamp expressed in seconds, NAN if the input timestamp is unknown @@ -2191,6 +2914,7 @@ crop=2/3*in_w:2/3*in_h @item Crop the input video central square: @example +crop=out_w=in_h crop=in_h @end example @@ -2248,12 +2972,7 @@ Calculate necessary cropping parameters and prints the recommended parameters through the logging system. The detected dimensions correspond to the non-black area of the input video. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax -[@option{limit}[:@option{round}[:@option{reset}]]]. - -A description of the accepted options follows. +The filter accepts the following options: @table @option @@ -2268,7 +2987,7 @@ offset is automatically adjusted to center the video. Use 2 to get only even dimensions (needed for 4:2:2 video). 16 is best when encoding to most video codecs. Default value is 16. -@item reset +@item reset_count, reset Set the counter that determines after how many frames cropdetect will reset the previously detected largest video area and start over to detect the current optimal crop area. Default value is 0. @@ -2278,6 +2997,7 @@ indicates never reset and return the largest area encountered during playback. @end table +@anchor{curves} @section curves Apply color adjustments using curves. @@ -2303,18 +3023,46 @@ If there is no key point defined in @code{x=0}, the filter will automatically insert a @var{(0;0)} point. In the same way, if there is no key point defined in @code{x=1}, the filter will automatically insert a @var{(1;1)} point. -The filter accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". - -A description of the accepted parameters follows. +The filter accepts the following options: @table @option +@item preset +Select one of the available color presets. This option can be used in addition +to the @option{r}, @option{g}, @option{b} parameters; in this case, the later +options takes priority on the preset values. +Available presets are: +@table @samp +@item none +@item color_negative +@item cross_process +@item darker +@item increase_contrast +@item lighter +@item linear_contrast +@item medium_contrast +@item negative +@item strong_contrast +@item vintage +@end table +Default is @code{none}. +@item master, m +Set the master key points. These points will define a second pass mapping. It +is sometimes called a "luminance" or "value" mapping. It can be used with +@option{r}, @option{g}, @option{b} or @option{all} since it acts like a +post-processing LUT. @item red, r Set the key points for the red component. @item green, g Set the key points for the green component. @item blue, b Set the key points for the blue component. +@item all +Set the key points for all components (not including master). +Can be used in addition to the other key points component +options. In this case, the unset component(s) will fallback on this +@option{all} setting. +@item psfile +Specify a Photoshop curves file (@code{.asv}) to import the settings from. @end table To avoid some filtergraph syntax conflicts, each key points list need to be @@ -2343,49 +3091,117 @@ Here we obtain the following coordinates for each components: @item blue @code{(0;0.22) (0.49;0.44) (1;0.80)} @end table + +@item +The previous example can also be achieved with the associated built-in preset: +@example +curves=preset=vintage +@end example + +@item +Or simply: +@example +curves=vintage +@end example + +@item +Use a Photoshop preset and redefine the points of the green component: +@example +curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53' +@end example @end itemize -@section decimate +@section dctdnoiz -Drop frames that do not differ greatly from the previous frame in -order to reduce framerate. +Denoise frames using 2D DCT (frequency domain filtering). -The main use of this filter is for very-low-bitrate encoding -(e.g. streaming over dialup modem), but it could in theory be used for -fixing movies that were inverse-telecined incorrectly. +This filter is not designed for real time and can be extremely slow. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax: -@option{max}:@option{hi}:@option{lo}:@option{frac}. +The filter accepts the following options: -A description of the accepted options follows. +@table @option +@item sigma, s +Set the noise sigma constant. + +This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT +coefficient (absolute value) below this threshold with be dropped. + +If you need a more advanced filtering, see @option{expr}. + +Default is @code{0}. + +@item overlap +Set number overlapping pixels for each block. Each block is of size +@code{16x16}. Since the filter can be slow, you may want to reduce this value, +at the cost of a less effective filter and the risk of various artefacts. + +If the overlapping value doesn't allow to process the whole input width or +height, a warning will be displayed and according borders won't be denoised. + +Default value is @code{15}. + +@item expr, e +Set the coefficient factor expression. + +For each coefficient of a DCT block, this expression will be evaluated as a +multiplier value for the coefficient. + +If this is option is set, the @option{sigma} option will be ignored. + +The absolute value of the coefficient can be accessed through the @var{c} +variable. +@end table + +@subsection Examples + +Apply a denoise with a @option{sigma} of @code{4.5}: +@example +dctdnoiz=4.5 +@end example + +The same operation can be achieved using the expression system: +@example +dctdnoiz=e='gte(c, 4.5*3)' +@end example + +@anchor{decimate} +@section decimate + +Drop duplicated frames at regular intervals. + +The filter accepts the following options: @table @option -@item max -Set the maximum number of consecutive frames which can be dropped (if -positive), or the minimum interval between dropped frames (if -negative). If the value is 0, the frame is dropped unregarding the -number of previous sequentially dropped frames. +@item cycle +Set the number of frames from which one will be dropped. Setting this to +@var{N} means one frame in every batch of @var{N} frames will be dropped. +Default is @code{5}. -Default value is 0. +@item dupthresh +Set the threshold for duplicate detection. If the difference metric for a frame +is less than or equal to this value, then it is declared as duplicate. Default +is @code{1.1} -@item hi -@item lo -@item frac -Set the dropping threshold values. +@item scthresh +Set scene change threshold. Default is @code{15}. -Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and -represent actual pixel value differences, so a threshold of 64 -corresponds to 1 unit of difference for each pixel, or the same spread -out differently over the block. +@item blockx +@item blocky +Set the size of the x and y-axis blocks used during metric calculations. +Larger blocks give better noise suppression, but also give worse detection of +small movements. Must be a power of two. Default is @code{32}. -A frame is a candidate for dropping if no 8x8 blocks differ by more -than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 -meaning the whole image) differ by more than a threshold of @option{lo}. +@item ppsrc +Mark main input as a pre-processed input and activate clean source input +stream. This allows the input to be pre-processed with various filters to help +the metrics calculation while keeping the frame selection lossless. When set to +@code{1}, the first stream is for the pre-processed input, and the second +stream is the clean source from where the kept frames are chosen. Default is +@code{0}. -Default value for @option{hi} is 64*12, default value for @option{lo} is -64*5, and default value for @option{frac} is 0.33. +@item chroma +Set whether or not chroma is considered in the metric calculations. Default is +@code{1}. @end table @section delogo @@ -2394,19 +3210,16 @@ Suppress a TV station logo by a simple interpolation of the surrounding pixels. Just set a rectangle covering the logo and watch it disappear (and sometimes something even uglier appear - your mileage may vary). -The filter accepts parameters as a string of the form -"@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of -@var{key}=@var{value} pairs, separated by ":". - -The description of the accepted parameters follows. - +This filter accepts the following options: @table @option -@item x, y +@item x +@item y Specify the top left corner coordinates of the logo. They must be specified. -@item w, h +@item w +@item h Specify the width and height of the logo to clear. They must be specified. @@ -2416,8 +3229,13 @@ Specify the thickness of the fuzzy edge of the rectangle (added to @item show When set to 1, a green rectangle is drawn on the screen to simplify -finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and -@var{band} is set to 4. The default value is 0. +finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. +The default value is 0. + +The rectangle is drawn on the outermost pixels which will be (partly) +replaced with interpolated values. The values of the next pixels +immediately outside this rectangle in each direction will be used to +compute the interpolated pixel values inside the rectangle. @end table @@ -2428,12 +3246,6 @@ finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and Set a rectangle covering the area with top left corner coordinates 0,0 and size 100x77, setting a band of size 10: @example -delogo=0:0:100:77:10 -@end example - -@item -As the previous example, but use named options: -@example delogo=x=0:y=0:w=100:h=77:band=10 @end example @@ -2445,16 +3257,14 @@ Attempt to fix small changes in horizontal and/or vertical shift. This filter helps remove camera shake from hand-holding a camera, bumping a tripod, moving on a vehicle, etc. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax -@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}. - -A description of the accepted parameters follows. +The filter accepts the following options: @table @option -@item x, y, w, h +@item x +@item y +@item w +@item h Specify a rectangular area where to limit the search for motion vectors. If desired the search for motion vectors can be limited to a @@ -2472,7 +3282,8 @@ without specifying the bounding box for the motion vector search. Default - search the whole frame. -@item rx, ry +@item rx +@item ry Specify the maximum extent of movement in x and y directions in the range 0-64 pixels. Default 16. @@ -2514,36 +3325,73 @@ Default value is @samp{exhaustive}. If set then a detailed log of the motion search is written to the specified file. +@item opencl +If set to 1, specify using OpenCL capabilities, only available if +FFmpeg was configured with @code{--enable-opencl}. Default value is 0. + @end table @section drawbox Draw a colored box on the input image. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax -@option{x}:@option{y}:@option{width}:@option{height}:@option{color}:@option{thickness}. - -A description of the accepted options follows. +This filter accepts the following options: @table @option -@item x, y -Specify the top left corner coordinates of the box. Default to 0. +@item x +@item y +The expressions which specify the top left corner coordinates of the box. Default to 0. @item width, w @item height, h -Specify the width and height of the box, if 0 they are interpreted as +The expressions which specify the width and height of the box, if 0 they are interpreted as the input width and height. Default to 0. @item color, c -Specify the color of the box to write, it can be the name of a color -(case insensitive match) or a 0xRRGGBB[AA] sequence. If the special +Specify the color of the box to write. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. If the special value @code{invert} is used, the box edge color is the same as the video with inverted luma. @item thickness, t -Set the thickness of the box edge. Default value is @code{4}. +The expression which sets the thickness of the box edge. Default value is @code{3}. + +See below for the list of accepted constants. +@end table + +The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the +following constants: + +@table @option +@item dar +The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. + +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + +@item in_h, ih +@item in_w, iw +The input width and height. + +@item sar +The input sample aspect ratio. + +@item x +@item y +The x and y offset coordinates where the box is drawn. + +@item w +@item h +The width and height of the drawn box. + +@item t +The thickness of the drawn box. + +These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to +each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. + @end table @subsection Examples @@ -2571,6 +3419,92 @@ Fill the box with pink color: @example drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max @end example + +@item +Draw a 2-pixel red 2.40:1 mask: +@example +drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red +@end example +@end itemize + +@section drawgrid + +Draw a grid on the input image. + +This filter accepts the following options: + +@table @option +@item x +@item y +The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. + +@item width, w +@item height, h +The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the +input width and height, respectively, minus @code{thickness}, so image gets +framed. Default to 0. + +@item color, c +Specify the color of the grid. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. If the special +value @code{invert} is used, the grid color is the same as the +video with inverted luma. + +@item thickness, t +The expression which sets the thickness of the grid line. Default value is @code{1}. + +See below for the list of accepted constants. +@end table + +The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the +following constants: + +@table @option +@item dar +The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. + +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + +@item in_h, ih +@item in_w, iw +The input grid cell width and height. + +@item sar +The input sample aspect ratio. + +@item x +@item y +The x and y coordinates of some point of grid intersection (meant to configure offset). + +@item w +@item h +The width and height of the drawn cell. + +@item t +The thickness of the drawn cell. + +These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to +each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. + +@end table + +@subsection Examples + +@itemize +@item +Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: +@example +drawgrid=width=100:height=100:thickness=2:color=red@@0.5 +@end example + +@item +Draw a white 3x3 grid with an opacity of 50%: +@example +drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 +@end example @end itemize @anchor{drawtext} @@ -2584,9 +3518,6 @@ To enable compilation of this filter you need to configure FFmpeg with @subsection Syntax -The filter accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". - The description of the accepted parameters follows. @table @option @@ -2597,20 +3528,10 @@ Value should be either 1 (enable) or 0 (disable). The default value of @var{box} is 0. @item boxcolor -The color to be used for drawing box around text. -Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format -(e.g. "0xff00ff"), possibly followed by an alpha specifier. -The default value of @var{boxcolor} is "white". - -@item draw -Set an expression which specifies if the text should be drawn. If the -expression evaluates to 0, the text is not drawn. This is useful for -specifying that the text should be drawn only when specific conditions -are met. +The color to be used for drawing box around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. -Default value is "1". - -See below for the list of accepted constants and functions. +The default value of @var{boxcolor} is "white". @item expansion Select how the @var{text} is expanded. Can be either @code{none}, @@ -2622,9 +3543,9 @@ below for details. If true, check and fix text coords to avoid clipping. @item fontcolor -The color to be used for drawing fonts. -Either a string (e.g. "red") or in 0xRRGGBB[AA] format -(e.g. "0xff000033"), possibly followed by an alpha specifier. +The color to be used for drawing fonts. For the syntax of this option, check +the "Color" section in the ffmpeg-utils manual. + The default value of @var{fontcolor} is "black". @item fontfile @@ -2656,7 +3577,6 @@ a combination of the following values: @item monochrome @item linear_design @item no_autohint -@item end table @end table Default value is "render". @@ -2665,16 +3585,21 @@ For more information consult the documentation for the FT_LOAD_* libfreetype flags. @item shadowcolor -The color to be used for drawing a shadow behind the drawn text. It -can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA] -form (e.g. "0xff00ff"), possibly followed by an alpha specifier. +The color to be used for drawing a shadow behind the drawn text. For the +syntax of this option, check the "Color" section in the ffmpeg-utils manual. + The default value of @var{shadowcolor} is "black". -@item shadowx, shadowy +@item shadowx +@item shadowy The x and y offsets for the text shadow position with respect to the position of the text. They can be either positive or negative values. Default value for both is "0". +@item start_number +The starting frame number for the n/frame_num variable. The default value +is "0". + @item tabsize The size in number of spaces to use for rendering the tab. Default value is 4. @@ -2706,7 +3631,8 @@ If both @var{text} and @var{textfile} are specified, an error is thrown. If set to 1, the @var{textfile} will be reloaded before each frame. Be sure to update it atomically, or it may be read partially, or even fail. -@item x, y +@item x +@item y The expressions which specify the offsets where text will be drawn within the video frame. They are relative to the top/left border of the output image. @@ -2723,7 +3649,8 @@ following constants and functions: @item dar input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} -@item hsub, vsub +@item hsub +@item vsub horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. @@ -2776,7 +3703,8 @@ the height of the rendered text @item text_w, tw the width of the rendered text -@item x, y +@item x +@item y the x and y offset coordinates where the text is drawn. These parameters allow the @var{x} and @var{y} expressions to refer @@ -2809,7 +3737,7 @@ they should be escaped. Note that they probably must also be escaped as the value for the @option{text} option in the filter argument string and as the filter -argument in the filter graph description, and possibly also for the shell, +argument in the filtergraph description, and possibly also for the shell, that makes up to four levels of escaping; using a text file avoids these problems. @@ -2835,9 +3763,15 @@ It can accept an argument: a strftime() format string. The time at which the filter is running, expressed in the local time zone. It can accept an argument: a strftime() format string. +@item metadata +Frame metadata. It must take one argument specifying metadata key. + @item n, frame_num The frame number, starting from 0. +@item pict_type +A 1 character description of the current picture type. + @item pts The timestamp of the current frame, in seconds, with microsecond accuracy. @@ -2898,7 +3832,7 @@ drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_gly @item Show text for 1 second every 3 seconds: @example -drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:draw=lt(mod(t\,3)\,1):text='blink'" +drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" @end example @item @@ -2925,10 +3859,11 @@ For more information about fontconfig, check: Detect and draw edges. The filter uses the Canny Edge Detection algorithm. -This filter accepts the following optional named parameters: +The filter accepts the following options: @table @option -@item low, high +@item low +@item high Set low and high threshold values used by the Canny thresholding algorithm. @@ -2948,35 +3883,111 @@ Example: edgedetect=low=0.1:high=0.4 @end example +@section extractplanes + +Extract color channel components from input video stream into +separate grayscale video streams. + +The filter accepts the following option: + +@table @option +@item planes +Set plane(s) to extract. + +Available values for planes are: +@table @samp +@item y +@item u +@item v +@item a +@item r +@item g +@item b +@end table + +Choosing planes not available in the input will result in an error. +That means you cannot select @code{r}, @code{g}, @code{b} planes +with @code{y}, @code{u}, @code{v} planes at same time. +@end table + +@subsection Examples + +@itemize +@item +Extract luma, u and v color channel component from input video frame +into 3 grayscale outputs: +@example +ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi +@end example +@end itemize + +@section elbg + +Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. + +For each input image, the filter will compute the optimal mapping from +the input to the output given the codebook length, that is the number +of distinct output colors. + +This filter accepts the following options. + +@table @option +@item codebook_length, l +Set codebook length. The value must be a positive integer, and +represents the number of distinct output colors. Default value is 256. + +@item nb_steps, n +Set the maximum number of iterations to apply for computing the optimal +mapping. The higher the value the better the result and the higher the +computation time. Default value is 1. + +@item seed, s +Set a random seed, must be an integer included between 0 and +UINT32_MAX. If not specified, or if explicitly set to -1, the filter +will try to use a good random seed on a best effort basis. +@end table + @section fade Apply fade-in/out effect to input video. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the syntax -@var{type}:@var{start_frame}:@var{nb_frames}. - -A description of the accepted parameters follows. +This filter accepts the following options: @table @option @item type, t -Specify if the effect type, can be either @code{in} for fade-in, or -@code{out} for a fade-out effect. Default is @code{in}. +The effect type -- can be either "in" for fade-in, or "out" for a fade-out +effect. +Default is @code{in}. @item start_frame, s Specify the number of the start frame for starting to apply the fade effect. Default is 0. @item nb_frames, n -Specify the number of frames for which the fade effect has to last. At -the end of the fade-in effect the output video will have the same -intensity as the input video, at the end of the fade-out transition -the output video will be completely black. Default is 25. +The number of frames for which the fade effect has to last. At the end of the +fade-in effect the output video will have the same intensity as the input video, +at the end of the fade-out transition the output video will be filled with the +selected @option{color}. +Default is 25. @item alpha If set to 1, fade only alpha channel, if one exists on the input. Default value is 0. + +@item start_time, st +Specify the timestamp (in seconds) of the frame to start to apply the fade +effect. If both start_frame and start_time are specified, the fade will start at +whichever comes last. Default is 0. + +@item duration, d +The number of seconds for which the fade effect has to last. At the end of the +fade-in effect the output video will have the same intensity as the input video, +at the end of the fade-out transition the output video will be filled with the +selected @option{color}. +If both duration and nb_frames are specified, duration is used. Default is 0. + +@item color, c +Specify the color of the fade. Default is "black". @end table @subsection Examples @@ -2997,6 +4008,7 @@ fade=t=in:s=0:n=30 Fade out last 45 frames of a 200-frame video: @example fade=out:155:45 +fade=type=out:start_frame=155:nb_frames=45 @end example @item @@ -3006,9 +4018,9 @@ fade=in:0:25, fade=out:975:25 @end example @item -Make first 5 frames black, then fade in from frame 5-24: +Make first 5 frames yellow, then fade in from frame 5-24: @example -fade=in:5:20 +fade=in:5:20:color=yellow @end example @item @@ -3016,6 +4028,13 @@ Fade in alpha over first 25 frames of video: @example fade=in:0:25:alpha=1 @end example + +@item +Make first 5.5 seconds black, then fade in for 0.5 seconds: +@example +fade=t=in:st=5.5:d=0.5 +@end example + @end itemize @section field @@ -3024,7 +4043,8 @@ Extract a single field from an interlaced image using stride arithmetic to avoid wasting CPU time. The output frames are marked as non-interlaced. -This filter accepts the following named options: +The filter accepts the following options: + @table @option @item type Specify whether to extract the top (if the value is @code{0} or @@ -3032,31 +4052,339 @@ Specify whether to extract the top (if the value is @code{0} or @code{bottom}). @end table -If the option key is not specified, the first value sets the @var{type} -option. For example: +@section fieldmatch + +Field matching filter for inverse telecine. It is meant to reconstruct the +progressive frames from a telecined stream. The filter does not drop duplicated +frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be +followed by a decimation filter such as @ref{decimate} in the filtergraph. + +The separation of the field matching and the decimation is notably motivated by +the possibility of inserting a de-interlacing filter fallback between the two. +If the source has mixed telecined and real interlaced content, +@code{fieldmatch} will not be able to match fields for the interlaced parts. +But these remaining combed frames will be marked as interlaced, and thus can be +de-interlaced by a later filter such as @ref{yadif} before decimation. + +In addition to the various configuration options, @code{fieldmatch} can take an +optional second stream, activated through the @option{ppsrc} option. If +enabled, the frames reconstruction will be based on the fields and frames from +this second stream. This allows the first input to be pre-processed in order to +help the various algorithms of the filter, while keeping the output lossless +(assuming the fields are matched properly). Typically, a field-aware denoiser, +or brightness/contrast adjustments can help. + +Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) +and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from +which @code{fieldmatch} is based on. While the semantic and usage are very +close, some behaviour and options names can differ. + +The filter accepts the following options: + +@table @option +@item order +Specify the assumed field order of the input stream. Available values are: + +@table @samp +@item auto +Auto detect parity (use FFmpeg's internal parity value). +@item bff +Assume bottom field first. +@item tff +Assume top field first. +@end table + +Note that it is sometimes recommended not to trust the parity announced by the +stream. + +Default value is @var{auto}. + +@item mode +Set the matching mode or strategy to use. @option{pc} mode is the safest in the +sense that it won't risk creating jerkiness due to duplicate frames when +possible, but if there are bad edits or blended fields it will end up +outputting combed frames when a good match might actually exist. On the other +hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, +but will almost always find a good frame if there is one. The other values are +all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking +jerkiness and creating duplicate frames versus finding good matches in sections +with bad edits, orphaned fields, blended fields, etc. + +More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. + +Available values are: + +@table @samp +@item pc +2-way matching (p/c) +@item pc_n +2-way matching, and trying 3rd match if still combed (p/c + n) +@item pc_u +2-way matching, and trying 3rd match (same order) if still combed (p/c + u) +@item pc_n_ub +2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if +still combed (p/c + n + u/b) +@item pcn +3-way matching (p/c/n) +@item pcn_ub +3-way matching, and trying 4th/5th matches if all 3 of the original matches are +detected as combed (p/c/n + u/b) +@end table + +The parenthesis at the end indicate the matches that would be used for that +mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or +@var{top}). + +In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is +the slowest. + +Default value is @var{pc_n}. + +@item ppsrc +Mark the main input stream as a pre-processed input, and enable the secondary +input stream as the clean source to pick the fields from. See the filter +introduction for more details. It is similar to the @option{clip2} feature from +VFM/TFM. + +Default value is @code{0} (disabled). + +@item field +Set the field to match from. It is recommended to set this to the same value as +@option{order} unless you experience matching failures with that setting. In +certain circumstances changing the field that is used to match from can have a +large impact on matching performance. Available values are: + +@table @samp +@item auto +Automatic (same value as @option{order}). +@item bottom +Match from the bottom field. +@item top +Match from the top field. +@end table + +Default value is @var{auto}. + +@item mchroma +Set whether or not chroma is included during the match comparisons. In most +cases it is recommended to leave this enabled. You should set this to @code{0} +only if your clip has bad chroma problems such as heavy rainbowing or other +artifacts. Setting this to @code{0} could also be used to speed things up at +the cost of some accuracy. + +Default value is @code{1}. + +@item y0 +@item y1 +These define an exclusion band which excludes the lines between @option{y0} and +@option{y1} from being included in the field matching decision. An exclusion +band can be used to ignore subtitles, a logo, or other things that may +interfere with the matching. @option{y0} sets the starting scan line and +@option{y1} sets the ending line; all lines in between @option{y0} and +@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting +@option{y0} and @option{y1} to the same value will disable the feature. +@option{y0} and @option{y1} defaults to @code{0}. + +@item scthresh +Set the scene change detection threshold as a percentage of maximum change on +the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change +detection is only relevant in case @option{combmatch}=@var{sc}. The range for +@option{scthresh} is @code{[0.0, 100.0]}. + +Default value is @code{12.0}. + +@item combmatch +When @option{combatch} is not @var{none}, @code{fieldmatch} will take into +account the combed scores of matches when deciding what match to use as the +final match. Available values are: + +@table @samp +@item none +No final matching based on combed scores. +@item sc +Combed scores are only used when a scene change is detected. +@item full +Use combed scores all the time. +@end table + +Default is @var{sc}. + +@item combdbg +Force @code{fieldmatch} to calculate the combed metrics for certain matches and +print them. This setting is known as @option{micout} in TFM/VFM vocabulary. +Available values are: + +@table @samp +@item none +No forced calculation. +@item pcn +Force p/c/n calculations. +@item pcnub +Force p/c/n/u/b calculations. +@end table + +Default value is @var{none}. + +@item cthresh +This is the area combing threshold used for combed frame detection. This +essentially controls how "strong" or "visible" combing must be to be detected. +Larger values mean combing must be more visible and smaller values mean combing +can be less visible or strong and still be detected. Valid settings are from +@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will +be detected as combed). This is basically a pixel difference value. A good +range is @code{[8, 12]}. + +Default value is @code{9}. + +@item chroma +Sets whether or not chroma is considered in the combed frame decision. Only +disable this if your source has chroma problems (rainbowing, etc.) that are +causing problems for the combed frame detection with chroma enabled. Actually, +using @option{chroma}=@var{0} is usually more reliable, except for the case +where there is chroma only combing in the source. + +Default value is @code{0}. + +@item blockx +@item blocky +Respectively set the x-axis and y-axis size of the window used during combed +frame detection. This has to do with the size of the area in which +@option{combpel} pixels are required to be detected as combed for a frame to be +declared combed. See the @option{combpel} parameter description for more info. +Possible values are any number that is a power of 2 starting at 4 and going up +to 512. + +Default value is @code{16}. + +@item combpel +The number of combed pixels inside any of the @option{blocky} by +@option{blockx} size blocks on the frame for the frame to be detected as +combed. While @option{cthresh} controls how "visible" the combing must be, this +setting controls "how much" combing there must be in any localized area (a +window defined by the @option{blockx} and @option{blocky} settings) on the +frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at +which point no frames will ever be detected as combed). This setting is known +as @option{MI} in TFM/VFM vocabulary. + +Default value is @code{80}. +@end table + +@anchor{p/c/n/u/b meaning} +@subsection p/c/n/u/b meaning + +@subsubsection p/c/n + +We assume the following telecined stream: + @example -field=bottom +Top fields: 1 2 2 3 4 +Bottom fields: 1 2 3 4 4 @end example -is equivalent to: +The numbers correspond to the progressive frame the fields relate to. Here, the +first two frames are progressive, the 3rd and 4th are combed, and so on. + +When @code{fieldmatch} is configured to run a matching from bottom +(@option{field}=@var{bottom}) this is how this input stream get transformed: + +@example +Input stream: + T 1 2 2 3 4 + B 1 2 3 4 4 <-- matching reference + +Matches: c c n n c + +Output stream: + T 1 2 3 4 4 + B 1 2 3 4 4 +@end example + +As a result of the field matching, we can see that some frames get duplicated. +To perform a complete inverse telecine, you need to rely on a decimation filter +after this operation. See for instance the @ref{decimate} filter. + +The same operation now matching from top fields (@option{field}=@var{top}) +looks like this: + @example -field=type=bottom +Input stream: + T 1 2 2 3 4 <-- matching reference + B 1 2 3 4 4 + +Matches: c c p p c + +Output stream: + T 1 2 2 3 4 + B 1 2 2 3 4 +@end example + +In these examples, we can see what @var{p}, @var{c} and @var{n} mean; +basically, they refer to the frame and field of the opposite parity: + +@itemize +@item @var{p} matches the field of the opposite parity in the previous frame +@item @var{c} matches the field of the opposite parity in the current frame +@item @var{n} matches the field of the opposite parity in the next frame +@end itemize + +@subsubsection u/b + +The @var{u} and @var{b} matching are a bit special in the sense that they match +from the opposite parity flag. In the following examples, we assume that we are +currently matching the 2nd frame (Top:2, bottom:2). According to the match, a +'x' is placed above and below each matched fields. + +With bottom matching (@option{field}=@var{bottom}): +@example +Match: c p n b u + + x x x x x + Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 + Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 + x x x x x + +Output frames: + 2 1 2 2 2 + 2 2 2 1 3 +@end example + +With top matching (@option{field}=@var{top}): +@example +Match: c p n b u + + x x x x x + Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 + Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 + x x x x x + +Output frames: + 2 2 2 1 2 + 2 1 3 2 2 +@end example + +@subsection Examples + +Simple IVTC of a top field first telecined stream: +@example +fieldmatch=order=tff:combmatch=none, decimate +@end example + +Advanced IVTC, with fallback on @ref{yadif} for still combed frames: +@example +fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate @end example @section fieldorder Transform the field order of the input video. -This filter accepts the named option @option{order} which -specifies the required field order that the input interlaced video -will be transformed to. The option name can be omitted. +This filter accepts the following options: -The option @option{order} can assume one of the following values: -@table @samp -@item bff -output bottom field first -@item tff -output top field first +@table @option + +@item order +Output field order. Valid values are @var{tff} for top field first or @var{bff} +for bottom field first. @end table Default value is @samp{tff}. @@ -3093,8 +4421,14 @@ Convert the input video to one of the specified pixel formats. Libavfilter will try to pick one that is supported for the input to the next filter. -The filter accepts a list of pixel format names, separated by ":", -for example "yuv420p:monow:rgb24". +This filter accepts the following parameters: +@table @option + +@item pix_fmts +A '|'-separated list of pixel format names, for example +"pix_fmts=yuv420p|monow|rgb24". + +@end table @subsection Examples @@ -3102,25 +4436,26 @@ for example "yuv420p:monow:rgb24". @item Convert the input video to the format @var{yuv420p} @example -format=yuv420p +format=pix_fmts=yuv420p @end example Convert the input video to any of the formats in the list @example -format=yuv420p:yuv444p:yuv410p +format=pix_fmts=yuv420p|yuv444p|yuv410p @end example @end itemize +@anchor{fps} @section fps -Convert the video to specified constant framerate by duplicating or dropping +Convert the video to specified constant frame rate by duplicating or dropping frames as necessary. This filter accepts the following named parameters: @table @option @item fps -Desired output framerate. The default is @code{25}. +Desired output frame rate. The default is @code{25}. @item round Rounding method. @@ -3140,6 +4475,14 @@ round to nearest @end table The default is @code{near}. +@item start_time +Assume the first PTS should be the given value, in seconds. This allows for +padding/trimming at the start of stream. By default, no assumption is made +about the first frame's expected PTS, so no padding or trimming is done. +For example, this could be set to 0 to pad the beginning with duplicates of +the first frame if a video stream starts after the audio stream or to trim any +frames with a negative PTS. + @end table Alternatively, the options can be specified as a flat string: @@ -3147,12 +4490,32 @@ Alternatively, the options can be specified as a flat string: See also the @ref{setpts} filter. +@subsection Examples + +@itemize +@item +A typical usage in order to set the fps to 25: +@example +fps=fps=25 +@end example + +@item +Sets the fps to 24, using abbreviation and rounding method to round to nearest: +@example +fps=fps=film:round=near +@end example +@end itemize + @section framestep -Select one frame every N. +Select one frame every N-th frame. -This filter accepts in input a string representing a positive -integer. Default argument is @code{1}. +This filter accepts the following option: +@table @option +@item step +Select frame after every @code{step} frames. +Allowed values are positive integers higher than 0. Default value is @code{1}. +@end table @anchor{frei0r} @section frei0r @@ -3162,27 +4525,28 @@ Apply a frei0r effect to the input video. To enable compilation of this filter you need to install the frei0r header and configure FFmpeg with @code{--enable-frei0r}. -The filter supports the syntax: -@example -@var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}] -@end example +This filter accepts the following options: -@var{filter_name} is the name of the frei0r effect to load. If the -environment variable @env{FREI0R_PATH} is defined, the frei0r effect -is searched in each one of the directories specified by the colon (or -semicolon on Windows platforms) separated list in @env{FREIOR_PATH}, +@table @option + +@item filter_name +The name to the frei0r effect to load. If the environment variable +@env{FREI0R_PATH} is defined, the frei0r effect is searched in each one of the +directories specified by the colon separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r paths, which are in this order: @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}. -@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters -for the frei0r effect. +@item filter_params +A '|'-separated list of parameters to pass to the frei0r effect. + +@end table A frei0r effect parameter can be a boolean (whose values are specified with "y" and "n"), a double, a color (specified by the syntax -@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float -numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color -description), a position (specified by the syntax @var{X}/@var{Y}, +@var{R}/@var{G}/@var{B}, (@var{R}, @var{G}, and @var{B} being float +numbers from 0.0 to 1.0) or by a color description specified in the "Color" +section in the ffmpeg-utils manual), a position (specified by the syntax @var{X}/@var{Y}, @var{X} and @var{Y} being float numbers) and a string. The number and kind of parameters depend on the loaded effect. If an @@ -3194,7 +4558,7 @@ effect parameter is not specified the default value is set. @item Apply the distort0r effect, set the first two double parameters: @example -frei0r=distort0r:0.5:0.01 +frei0r=filter_name=distort0r:filter_params=0.5|0.01 @end example @item @@ -3209,7 +4573,7 @@ frei0r=colordistance:0x112233 Apply the perspective effect, specify the top left and top right image positions: @example -frei0r=perspective:0.2/0.2:0.8/0.2 +frei0r=perspective:0.2/0.2|0.8/0.2 @end example @end itemize @@ -3218,27 +4582,36 @@ For more information see: @section geq -The filter takes one, two, three or four equations as parameter, separated by ':'. -The first equation is mandatory and applies to the luma plane. The two -following are respectively for chroma blue and chroma red planes. - -The filter syntax allows named parameters: +The filter accepts the following options: @table @option -@item lum_expr -the luminance expression -@item cb_expr -the chrominance blue expression -@item cr_expr -the chrominance red expression -@item alpha_expr -the alpha expression +@item lum_expr, lum +Set the luminance expression. +@item cb_expr, cb +Set the chrominance blue expression. +@item cr_expr, cr +Set the chrominance red expression. +@item alpha_expr, a +Set the alpha expression. +@item red_expr, r +Set the red expression. +@item green_expr, g +Set the green expression. +@item blue_expr, b +Set the blue expression. @end table +The colorspace is selected according to the specified options. If one +of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} +options is specified, the filter will automatically select a YCbCr +colorspace. If one of the @option{red_expr}, @option{green_expr}, or +@option{blue_expr} options is specified, it will select an RGB +colorspace. + If one of the chrominance expression is not defined, it falls back on the other one. If no alpha expression is specified it will evaluate to opaque value. -If none of chrominance expressions are -specified, they will evaluate the luminance expression. +If none of chrominance expressions are specified, they will evaluate +to the luminance expression. The expressions can use the following variables and functions: @@ -3246,13 +4619,16 @@ The expressions can use the following variables and functions: @item N The sequential number of the filtered frame, starting from @code{0}. -@item X, Y +@item X +@item Y The coordinates of the current sample. -@item W, H +@item W +@item H The width and height of the image. -@item SW, SH +@item SW +@item SH Width and height scale depending on the currently filtered plane. It is the ratio between the corresponding luma plane number of pixels and the current plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and @@ -3271,15 +4647,21 @@ plane. @item cb(x, y) Return the value of the pixel at location (@var{x},@var{y}) of the -blue-difference chroma plane. Returns 0 if there is no such plane. +blue-difference chroma plane. Return 0 if there is no such plane. @item cr(x, y) Return the value of the pixel at location (@var{x},@var{y}) of the -red-difference chroma plane. Returns 0 if there is no such plane. +red-difference chroma plane. Return 0 if there is no such plane. + +@item r(x, y) +@item g(x, y) +@item b(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the +red/green/blue component. Return 0 if there is no such component. @item alpha(x, y) Return the value of the pixel at location (@var{x},@var{y}) of the alpha -plane. Returns 0 if there is no such plane. +plane. Return 0 if there is no such plane. @end table For functions, if @var{x} and @var{y} are outside the area, the value will be @@ -3306,6 +4688,18 @@ Generate a fancy enigmatic moving light: @example nullsrc=s=256x256,geq=random(1)/hypot(X-cos(N*0.07)*W/2-W/2\,Y-sin(N*0.09)*H/2-H/2)^2*1000000*sin(N*0.02):128:128 @end example + +@item +Generate a quick emboss effect: +@example +format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' +@end example + +@item +Modify RGB components depending on pixel position: +@example +geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' +@end example @end itemize @section gradfun @@ -3319,22 +4713,21 @@ This filter is designed for playback only. Do not use it prior to lossy compression, because compression tends to lose the dither and bring back the bands. -The filter accepts a list of options in the form of @var{key}=@var{value} pairs -separated by ":". A description of the accepted options follows. +This filter accepts the following options: @table @option @item strength -The maximum amount by which the filter will change -any one pixel. Also the threshold for detecting nearly flat -regions. Acceptable values range from @code{0.51} to @code{64}, default value -is @code{1.2}. +The maximum amount by which the filter will change any one pixel. Also the +threshold for detecting nearly flat regions. Acceptable values range from .51 to +64, default value is 1.2, out-of-range values will be clipped to the valid +range. @item radius -The neighborhood to fit the gradient to. A larger -radius makes for smoother gradients, but also prevents the filter from -modifying the pixels near detailed regions. Acceptable values are -@code{8-32}, default value is @code{16}. +The neighborhood to fit the gradient to. A larger radius makes for smoother +gradients, but also prevents the filter from modifying the pixels near detailed +regions. Acceptable values are 8-32, default value is 16, out-of-range values +will be clipped to the valid range. @end table @@ -3359,6 +4752,79 @@ gradfun=radius=8 @end itemize +@anchor{haldclut} +@section haldclut + +Apply a Hald CLUT to a video stream. + +First input is the video stream to process, and second one is the Hald CLUT. +The Hald CLUT input can be a simple picture or a complete video stream. + +The filter accepts the following options: + +@table @option +@item shortest +Force termination when the shortest input terminates. Default is @code{0}. +@item repeatlast +Continue applying the last CLUT after the end of the stream. A value of +@code{0} disable the filter after the last frame of the CLUT is reached. +Default is @code{1}. +@end table + +@code{haldclut} also has the same interpolation options as @ref{lut3d} (both +filters share the same internals). + +More information about the Hald CLUT can be found on Eskil Steenberg's website +(Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. + +@subsection Workflow examples + +@subsubsection Hald CLUT video stream + +Generate an identity Hald CLUT stream altered with various effects: +@example +ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut +@end example + +Note: make sure you use a lossless codec. + +Then use it with @code{haldclut} to apply it on some random stream: +@example +ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv +@end example + +The Hald CLUT will be applied to the 10 first seconds (duration of +@file{clut.nut}), then the latest picture of that CLUT stream will be applied +to the remaining frames of the @code{mandelbrot} stream. + +@subsubsection Hald CLUT with preview + +A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by +@code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the +biggest possible square starting at the top left of the picture. The remaining +padding pixels (bottom or right) will be ignored. This area can be used to add +a preview of the Hald CLUT. + +Typically, the following generated Hald CLUT will be supported by the +@code{haldclut} filter: + +@example +ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " + pad=iw+320 [padded_clut]; + smptebars=s=320x256, split [a][b]; + [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; + [main][b] overlay=W-320" -frames:v 1 clut.png +@end example + +It contains the original and a preview of the effect of the CLUT: SMPTE color +bars are displayed on the right-top, and below the same color bars processed by +the color changes. + +Then, the effect of this Hald CLUT can be visualized with: +@example +ffplay input.mkv -vf "movie=clut.png, [in] haldclut" +@end example + @section hflip Flip the input video horizontally. @@ -3379,12 +4845,7 @@ viewed as an "automatically adjusting contrast filter". This filter is useful only for correcting degraded or poorly captured source video. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to syntax -@var{strength}:@var{intensity}:@var{antibanding}. - -This filter accepts the following named options: +The filter accepts the following options: @table @option @item strength @@ -3413,7 +4874,7 @@ Compute and draw a color distribution histogram for the input video. The computed histogram is a representation of distribution of color components in an image. -The filter accepts the following named parameters: +The filter accepts the following options: @table @option @item mode @@ -3424,7 +4885,7 @@ It accepts the following values: @item levels standard histogram that display color components distribution in an image. Displays color graph for each color component. Shows distribution -of the Y, U, V, A or G, B, R components, depending on input format, +of the Y, U, V, A or R, G, B components, depending on input format, in current frame. Bellow each graph is color component scale meter. @item color @@ -3477,6 +4938,12 @@ Default value is @code{10}. Allowed range is [1, 255]. Set mode for @code{waveform}. Can be either @code{row}, or @code{column}. Default is @code{row}. +@item waveform_mirror +Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1} +means mirrored. In mirrored mode, higher values will be represented on the left +side for @code{row} mode and at the top for @code{column} mode. Default is +@code{0} (unmirrored). + @item display_mode Set display mode for @code{waveform} and @code{levels}. It accepts the following values: @@ -3507,6 +4974,10 @@ components that are supposed to be identical, such as neutral whites, grays, or blacks. @end table Default is @code{parade}. + +@item levels_mode +Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}. +Default is @code{linear}. @end table @subsection Examples @@ -3521,6 +4992,7 @@ ffplay -i input -vf histogram @end itemize +@anchor{hqdn3d} @section hqdn3d High precision/quality 3d denoise filter. This filter aims to reduce @@ -3528,7 +5000,6 @@ image noise producing smooth images and making still images really still. It should enhance compressibility. It accepts the following optional parameters: -@var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp} @table @option @item luma_spatial @@ -3552,24 +5023,31 @@ a float number which specifies chroma temporal strength, defaults to Modify the hue and/or the saturation of the input. -This filter accepts the following optional named options: +This filter accepts the following options: @table @option @item h -Specify the hue angle as a number of degrees. It accepts a float -number or an expression, and defaults to 0.0. +Specify the hue angle as a number of degrees. It accepts an expression, +and defaults to "0". + +@item s +Specify the saturation in the [-10,10] range. It accepts an expression and +defaults to "1". @item H -Specify the hue angle as a number of radians. It accepts a float -number or an expression, and defaults to 0.0. +Specify the hue angle as a number of radians. It accepts an +expression, and defaults to "0". -@item s -Specify the saturation in the [-10,10] range. It accepts a float number and -defaults to 1.0. +@item b +Specify the brightness in the [-10,10] range. It accepts an expression and +defaults to "0". @end table -The @var{h}, @var{H} and @var{s} parameters are expressions containing the -following constants: +@option{h} and @option{H} are mutually exclusive, and can't be +specified at the same time. + +The @option{b}, @option{h}, @option{H} and @option{s} option values are +expressions containing the following constants: @table @option @item n @@ -3588,10 +5066,6 @@ timestamp expressed in seconds, NAN if the input timestamp is unknown time base of the input video @end table -The options can also be set using the syntax: @var{hue}:@var{saturation} - -In this case @var{hue} is expressed in degrees. - @subsection Examples @itemize @@ -3608,19 +5082,6 @@ hue=H=PI/2:s=1 @end example @item -Same command without named options, hue must be expressed in degrees: -@example -hue=90:1 -@end example - -@item -Note that "h:s" syntax does not support expressions for the values of -h and s, so the following example will issue an error: -@example -hue=PI/2:1 -@end example - -@item Rotate hue and make the saturation swing between 0 and 2 over a period of 1 second: @example @@ -3653,14 +5114,17 @@ hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" @subsection Commands -This filter supports the following command: +This filter supports the following commands: @table @option -@item reinit -Modify the hue and/or the saturation of the input video. -The command accepts the same named options and syntax than when calling the -filter from the command-line. +@item b +@item s +@item h +@item H +Modify the hue and/or the saturation and/or brightness of the input video. +The command accepts the same syntax of the corresponding option. -If a parameter is omitted, it is kept at its current value. +If the specified expression is not valid, it is kept at its current +value. @end table @section idet @@ -3670,6 +5134,15 @@ Detect video interlacing type. This filter tries to detect if the input is interlaced or progressive, top or bottom field first. +The filter accepts the following options: + +@table @option +@item intl_thres +Set interlacing threshold. +@item prog_thres +Set progressive threshold. +@end table + @section il Deinterleave or interleave fields. @@ -3680,12 +5153,11 @@ fields (so called half pictures). Odd lines are moved to the top half of the output image, even lines to the bottom half. You can process (filter) them independently and then re-interleave them. -It accepts a list of options in the form of @var{key}=@var{value} pairs -separated by ":". A description of the accepted options follows. +The filter accepts the following options: @table @option @item luma_mode, l -@item chroma_mode, s +@item chroma_mode, c @item alpha_mode, a Available values for @var{luma_mode}, @var{chroma_mode} and @var{alpha_mode} are: @@ -3708,17 +5180,42 @@ Default value is @code{none}. Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. @end table +@section interlace + +Simple interlacing filter from progressive contents. This interleaves upper (or +lower) lines from odd frames with lower (or upper) lines from even frames, +halving the frame rate and preserving image height. + +@example + Original Original New Frame + Frame 'j' Frame 'j+1' (tff) + ========== =========== ================== + Line 0 --------------------> Frame 'j' Line 0 + Line 1 Line 1 ----> Frame 'j+1' Line 1 + Line 2 ---------------------> Frame 'j' Line 2 + Line 3 Line 3 ----> Frame 'j+1' Line 3 + ... ... ... +New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on +@end example + +It accepts the following optional parameters: + +@table @option +@item scan +determines whether the interlaced frame is taken from the even (tff - default) +or odd (bff) lines of the progressive frame. + +@item lowpass +Enable (default) or disable the vertical lowpass filter to avoid twitter +interlacing and reduce moire patterns. +@end table + @section kerndeint Deinterlace input video by applying Donald Graft's adaptive kernel deinterling. Work on interlaced parts of a video to produce progressive frames. -This filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to the following syntax: -@var{thresh}:@var{map}:@var{order}:@var{sharp}:@var{twoway}. - The description of the accepted parameters follows. @table @option @@ -3765,6 +5262,43 @@ kerndeint=map=1 @end example @end itemize +@anchor{lut3d} +@section lut3d + +Apply a 3D LUT to an input video. + +The filter accepts the following options: + +@table @option +@item file +Set the 3D LUT file name. + +Currently supported formats: +@table @samp +@item 3dl +AfterEffects +@item cube +Iridas +@item dat +DaVinci +@item m3d +Pandora +@end table +@item interp +Select interpolation mode. + +Available values are: + +@table @samp +@item nearest +Use values from the nearest defined point. +@item trilinear +Interpolate values using the 8 points defining a cube. +@item tetrahedral +Interpolate values using a tetrahedron. +@end table +@end table + @section lut, lutrgb, lutyuv Compute a look-up table for binding each pixel component input value @@ -3773,12 +5307,7 @@ to an output value, and apply it to input video. @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} to an RGB input video. -These filters accept in input a ":"-separated list of options, which -specify the expressions used for computing the lookup table for the -corresponding pixel component values. - -The @var{lut} filter requires either YUV or RGB pixel formats in -input, and accepts the options: +These filters accept the following options: @table @option @item c0 set first pixel component expression @@ -3788,14 +5317,7 @@ set second pixel component expression set third pixel component expression @item c3 set fourth pixel component expression, corresponds to the alpha component -@end table -The exact component associated to each option depends on the format in -input. - -The @var{lutrgb} filter requires RGB pixel formats in input, and -accepts the options: -@table @option @item r set red component expression @item g @@ -3804,25 +5326,29 @@ set green component expression set blue component expression @item a alpha component expression -@end table -The @var{lutyuv} filter requires YUV pixel formats in input, and -accepts the options: -@table @option @item y set Y/luminance component expression @item u set U/Cb component expression @item v set V/Cr component expression -@item a -set alpha component expression @end table +Each of them specifies the expression to use for computing the lookup table for +the corresponding pixel component values. + +The exact component associated to each of the @var{c*} options depends on the +format in input. + +The @var{lut} filter requires either YUV or RGB pixel formats in input, +@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. + The expressions can contain the following constants and functions: @table @option -@item w, h +@item w +@item h the input width and height @item val @@ -3915,11 +5441,114 @@ lutyuv=y='bitand(val, 128+64+32)' @end example @end itemize +@section mergeplanes + +Merge color channel components from several video streams. + +The filter accepts up to 4 input streams, and merge selected input +planes to the output video. + +This filter accepts the following options: +@table @option +@item mapping +Set input to output plane mapping. Default is @code{0}. + +The mappings is specified as a bitmap. It should be specified as a +hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the +mapping for the first plane of the output stream. 'A' sets the number of +the input stream to use (from 0 to 3), and 'a' the plane number of the +corresponding input to use (from 0 to 3). The rest of the mappings is +similar, 'Bb' describes the mapping for the output stream second +plane, 'Cc' describes the mapping for the output stream third plane and +'Dd' describes the mapping for the output stream fourth plane. + +@item format +Set output pixel format. Default is @code{yuva444p}. +@end table + +@subsection Examples + +@itemize +@item +Merge three gray video streams of same width and height into single video stream: +@example +[a0][a1][a2]mergeplanes=0x001020:yuv444p +@end example + +@item +Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: +@example +[a0][a1]mergeplanes=0x00010210:yuva444p +@end example + +@item +Swap Y and A plane in yuva444p stream: +@example +format=yuva444p,mergeplanes=0x03010200:yuva444p +@end example + +@item +Swap U and V plane in yuv420p stream: +@example +format=yuv420p,mergeplanes=0x000201:yuv420p +@end example + +@item +Cast a rgb24 clip to yuv444p: +@example +format=rgb24,mergeplanes=0x000102:yuv444p +@end example +@end itemize + +@section mcdeint + +Apply motion-compensation deinterlacing. + +It needs one field per frame as input and must thus be used together +with yadif=1/3 or equivalent. + +This filter accepts the following options: +@table @option +@item mode +Set the deinterlacing mode. + +It accepts one of the following values: +@table @samp +@item fast +@item medium +@item slow +use iterative motion estimation +@item extra_slow +like @samp{slow}, but use multiple reference frames. +@end table +Default value is @samp{fast}. + +@item parity +Set the picture field parity assumed for the input video. It must be +one of the following values: + +@table @samp +@item 0, tff +assume top field first +@item 1, bff +assume bottom field first +@end table + +Default value is @samp{bff}. + +@item qp +Set per-block quantization parameter (QP) used by the internal +encoder. + +Higher values should result in a smoother motion vector field but less +optimal individual vectors. Default value is 1. +@end table + @section mp Apply an MPlayer filter to the input video. -This filter provides a wrapper around most of the filters of +This filter provides a wrapper around some of the filters of MPlayer/MEncoder. This wrapper is considered experimental. Some of the wrapped filters @@ -3927,7 +5556,7 @@ may not work properly and we may drop support for them, as they will be implemented natively into FFmpeg. Thus you should avoid depending on them when writing portable scripts. -The filters accepts the parameters: +The filter accepts the parameters: @var{filter_name}[:=]@var{filter_params} @var{filter_name} is the name of a supported MPlayer filter, @@ -3936,28 +5565,12 @@ the named filter. The list of the currently supported filters follows: @table @var -@item detc -@item dint -@item divtc -@item down3dright @item eq2 @item eq -@item fil @item fspp @item ilpack -@item ivtc -@item mcdeint -@item ow -@item perspective -@item phase @item pp7 -@item pullup -@item qp -@item sab @item softpulldown -@item spp -@item telecine -@item tinterlace @item uspp @end table @@ -3977,6 +5590,45 @@ mp=eq2=1.0:2:0.5 See also mplayer(1), @url{http://www.mplayerhq.hu/}. +@section mpdecimate + +Drop frames that do not differ greatly from the previous frame in +order to reduce frame rate. + +The main use of this filter is for very-low-bitrate encoding +(e.g. streaming over dialup modem), but it could in theory be used for +fixing movies that were inverse-telecined incorrectly. + +A description of the accepted options follows. + +@table @option +@item max +Set the maximum number of consecutive frames which can be dropped (if +positive), or the minimum interval between dropped frames (if +negative). If the value is 0, the frame is dropped unregarding the +number of previous sequentially dropped frames. + +Default value is 0. + +@item hi +@item lo +@item frac +Set the dropping threshold values. + +Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and +represent actual pixel value differences, so a threshold of 64 +corresponds to 1 unit of difference for each pixel, or the same spread +out differently over the block. + +A frame is a candidate for dropping if no 8x8 blocks differ by more +than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 +meaning the whole image) differ by more than a threshold of @option{lo}. + +Default value for @option{hi} is 64*12, default value for @option{lo} is +64*5, and default value for @option{frac} is 0.33. +@end table + + @section negate Negate input video. @@ -3989,8 +5641,14 @@ alpha component (if available). The default value in input is 0. Force libavfilter not to use any of the specified pixel formats for the input to the next filter. -The filter accepts a list of pixel format names, separated by ":", -for example "yuv420p:monow:rgb24". +This filter accepts the following parameters: +@table @option + +@item pix_fmts +A '|'-separated list of pixel format names, for example +"pix_fmts=yuv420p|monow|rgb24". + +@end table @subsection Examples @@ -3999,13 +5657,13 @@ for example "yuv420p:monow:rgb24". Force libavfilter to use a format different from @var{yuv420p} for the input to the vflip filter: @example -noformat=yuv420p,vflip +noformat=pix_fmts=yuv420p,vflip @end example @item Convert the input video to any of the formats not contained in the list: @example -noformat=yuv420p:yuv444p:yuv410p +noformat=yuv420p|yuv444p|yuv410p @end example @end itemize @@ -4013,8 +5671,7 @@ noformat=yuv420p:yuv444p:yuv410p Add noise on video input frame. -This filter accepts a list of options in the form of @var{key}=@var{value} -pairs separated by ":". A description of the accepted options follows. +The filter accepts the following options: @table @option @item all_seed @@ -4045,8 +5702,6 @@ Available values for component flags are: averaged temporal noise (smoother) @item p mix random noise with a (semi)regular pattern -@item q -higher quality (slightly better looking, slightly slower) @item t temporal noise (noise pattern changes between frames) @item u @@ -4072,12 +5727,18 @@ Apply video transform using libopencv. To enable this filter install libopencv library and headers and configure FFmpeg with @code{--enable-libopencv}. -The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}. +This filter accepts the following parameters: + +@table @option + +@item filter_name +The name of the libopencv filter to apply. -@var{filter_name} is the name of the libopencv filter to apply. +@item filter_params +The parameters to pass to the libopencv filter. If not specified the default +values are assumed. -@var{filter_params} specifies the parameters to pass to the libopencv -filter. If not specified the default values are assumed. +@end table Refer to the official libopencv documentation for more precise information: @@ -4091,7 +5752,7 @@ Follows the list of supported libopencv filters. Dilate an image by using a specific structuring element. This filter corresponds to the libopencv function @code{cvDilate}. -It accepts the parameters: @var{struct_el}:@var{nb_iterations}. +It accepts the parameters: @var{struct_el}|@var{nb_iterations}. @var{struct_el} represents a structuring element, and has the syntax: @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} @@ -4119,7 +5780,7 @@ Follow some example: ocv=dilate # dilate using a structuring element with a 5x5 cross, iterate two times -ocv=dilate=5x5+2x2/cross:2 +ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 # read the shape from the file diamond.shape, iterate two times # the file diamond.shape may contain a pattern of characters like this: @@ -4129,7 +5790,7 @@ ocv=dilate=5x5+2x2/cross:2 # *** # * # the specified cols and rows are ignored (but not the anchor point coordinates) -ocv=0x0+2x2/custom=diamond.shape:2 +ocv=dilate:0x0+2x2/custom=diamond.shape|2 @end example @subsection erode @@ -4145,7 +5806,7 @@ with the same syntax and semantics as the @ref{dilate} filter. Smooth the input video. The filter takes the following parameters: -@var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}. +@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. @var{type} is the type of smooth filter to apply, and can be one of the following values: "blur", "blur_no_scale", "median", "gaussian", @@ -4170,33 +5831,37 @@ Overlay one video on top of another. It takes two inputs and one output, the first input is the "main" video on which the second input is overlayed. -This filter accepts a list of @var{key}=@var{value} pairs as argument, -separated by ":". If the key of the first options is omitted, the -arguments are interpreted according to the syntax @var{x}:@var{y}. +This filter accepts the following parameters: A description of the accepted options follows. @table @option -@item x, y +@item x +@item y Set the expression for the x and y coordinates of the overlayed video -on the main video. Default value is 0. - -The @var{x} and @var{y} expressions can contain the following -parameters: -@table @option -@item main_w, main_h -main input width and height +on the main video. Default value is "0" for both expressions. In case +the expression is invalid, it is set to a huge value (meaning that the +overlay will not be displayed within the output visible area). -@item W, H -same as @var{main_w} and @var{main_h} +@item eval +Set when the expressions for @option{x}, and @option{y} are evaluated. -@item overlay_w, overlay_h -overlay input width and height +It accepts the following values: +@table @samp +@item init +only evaluate expressions once during the filter initialization or +when a command is processed -@item w, h -same as @var{overlay_w} and @var{overlay_h} +@item frame +evaluate expressions for each incoming frame @end table +Default value is @samp{frame}. + +@item shortest +If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. + @item format Set the format for the output video. @@ -4219,13 +5884,51 @@ If set to 1, force the filter to accept inputs in the RGB color space. Default value is 0. This option is deprecated, use @option{format} instead. -@item shortest -If set to 1, force the output to terminate when the shortest input -terminates. Default value is 0. +@item repeatlast +If set to 1, force the filter to draw the last overlay frame over the +main input until the end of the stream. A value of 0 disables this +behavior. Default value is 1. +@end table + +The @option{x}, and @option{y} expressions can contain the following +parameters. + +@table @option +@item main_w, W +@item main_h, H +main input width and height + +@item overlay_w, w +@item overlay_h, h +overlay input width and height + +@item x +@item y +the computed values for @var{x} and @var{y}. They are evaluated for +each new frame. + +@item hsub +@item vsub +horizontal and vertical chroma subsample values of the output +format. For example for the pixel format "yuv422p" @var{hsub} is 2 and +@var{vsub} is 1. + +@item n +the number of input frame, starting from 0 + +@item pos +the position in the file of the input frame, NAN if unknown + +@item t +timestamp expressed in seconds, NAN if the input timestamp is unknown @end table +Note that the @var{n}, @var{pos}, @var{t} variables are available only +when evaluation is done @emph{per frame}, and will evaluate to NAN +when @option{eval} is set to @samp{init}. + Be aware that frames are taken from each input video in timestamp -order, hence, if their initial timestamps differ, it is a a good idea +order, hence, if their initial timestamps differ, it is a good idea to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to have them begin in the same zero timestamp, as it does the example for the @var{movie} filter. @@ -4233,6 +5936,19 @@ the @var{movie} filter. You can chain together more overlays but you should test the efficiency of such approach. +@subsection Commands + +This filter supports the following commands: +@table @option +@item x +@item y +Modify the x and y of the overlay input. +The command accepts the same syntax of the corresponding option. + +If the specified expression is not valid, it is kept at its current +value. +@end table + @subsection Examples @itemize @@ -4259,14 +5975,14 @@ ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output Insert 2 different transparent PNG logos (second logo on bottom right corner) using the @command{ffmpeg} tool: @example -ffmpeg -i input -i logo1 -i logo2 -filter_complex 'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output +ffmpeg -i input -i logo1 -i logo2 -filter_complex 'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output @end example @item -Add a transparent color layer on top of the main video, WxH specifies -the size of the main input to the overlay filter: +Add a transparent color layer on top of the main video, @code{WxH} +must specify the size of the main input to the overlay filter: @example -color=red@@.3:WxH [over]; [in][over] overlay [out] +color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] @end example @item @@ -4282,6 +5998,13 @@ ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' @end example @item +Make a sliding overlay appearing from the left to the right top part of the +screen starting since time 2: +@example +overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 +@end example + +@item Compose output by putting two input videos side to side: @example ffmpeg -i left.avi -i right.avi -filter_complex " @@ -4306,19 +6029,38 @@ testsrc=s=100x100, split=4 [in0][in1][in2][in3]; @end itemize +@section owdenoise + +Apply Overcomplete Wavelet denoiser. + +The filter accepts the following options: + +@table @option +@item depth +Set depth. + +Larger depth values will denoise lower frequency components more, but +slow down filtering. + +Must be an int in the range 8-16, default is @code{8}. + +@item luma_strength, ls +Set luma strength. + +Must be a double value in the range 0-1000, default is @code{1.0}. + +@item chroma_strength, cs +Set chroma strength. + +Must be a double value in the range 0-1000, default is @code{1.0}. +@end table + @section pad Add paddings to the input image, and place the original input at the given coordinates @var{x}, @var{y}. -The filter accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". - -If the key of the first options is omitted, the arguments are -interpreted according to the syntax -@var{width}:@var{height}:@var{x}:@var{y}:@var{color}. - -A description of the accepted options follows. +This filter accepts the following parameters: @table @option @item width, w @@ -4344,8 +6086,8 @@ expression, and vice versa. The default value of @var{x} and @var{y} is 0. @item color -Specify the color of the padded area, it can be the name of a color -(case insensitive match) or a 0xRRGGBB[AA] sequence. +Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils manual. The default value of @var{color} is "black". @end table @@ -4354,20 +6096,25 @@ The value for the @var{width}, @var{height}, @var{x}, and @var{y} options are expressions containing the following constants: @table @option -@item in_w, in_h +@item in_w +@item in_h the input video width and height -@item iw, ih +@item iw +@item ih same as @var{in_w} and @var{in_h} -@item out_w, out_h +@item out_w +@item out_h the output width and height, that is the size of the padded area as specified by the @var{width} and @var{height} expressions -@item ow, oh +@item ow +@item oh same as @var{out_w} and @var{out_h} -@item x, y +@item x +@item y x and y offsets as specified by the @var{x} and @var{y} expressions, or NAN if not yet specified @@ -4380,7 +6127,8 @@ input sample aspect ratio @item dar input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} -@item hsub, vsub +@item hsub +@item vsub horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. @end table @@ -4444,6 +6192,105 @@ pad="2*iw:2*ih:ow-iw:oh-ih" @end example @end itemize +@section perspective + +Correct perspective of video not recorded perpendicular to the screen. + +A description of the accepted parameters follows. + +@table @option +@item x0 +@item y0 +@item x1 +@item y1 +@item x2 +@item y2 +@item x3 +@item y3 +Set coordinates expression for top left, top right, bottom left and bottom right corners. +Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. + +The expressions can use the following variables: + +@table @option +@item W +@item H +the width and height of video frame. +@end table + +@item interpolation +Set interpolation for perspective correction. + +It accepts the following values: +@table @samp +@item linear +@item cubic +@end table + +Default value is @samp{linear}. +@end table + +@section phase + +Delay interlaced video by one field time so that the field order changes. + +The intended use is to fix PAL movies that have been captured with the +opposite field order to the film-to-video transfer. + +A description of the accepted parameters follows. + +@table @option +@item mode +Set phase mode. + +It accepts the following values: +@table @samp +@item t +Capture field order top-first, transfer bottom-first. +Filter will delay the bottom field. + +@item b +Capture field order bottom-first, transfer top-first. +Filter will delay the top field. + +@item p +Capture and transfer with the same field order. This mode only exists +for the documentation of the other options to refer to, but if you +actually select it, the filter will faithfully do nothing. + +@item a +Capture field order determined automatically by field flags, transfer +opposite. +Filter selects among @samp{t} and @samp{b} modes on a frame by frame +basis using field flags. If no field information is available, +then this works just like @samp{u}. + +@item u +Capture unknown or varying, transfer opposite. +Filter selects among @samp{t} and @samp{b} on a frame by frame basis by +analyzing the images and selecting the alternative that produces best +match between the fields. + +@item T +Capture top-first, transfer unknown or varying. +Filter selects among @samp{t} and @samp{p} using image analysis. + +@item B +Capture bottom-first, transfer unknown or varying. +Filter selects among @samp{b} and @samp{p} using image analysis. + +@item A +Capture determined by field flags, transfer unknown or varying. +Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and +image analysis. If no field information is available, then this works just +like @samp{U}. This is the default mode. + +@item U +Both capture and transfer unknown or varying. +Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. +@end table +@end table + @section pixdesctest Pixel format descriptor test filter, mainly useful for internal @@ -4464,6 +6311,13 @@ Subfilters must be separated by '/' and can be disabled by prepending a '-'. Each subfilter and some options have a short and a long name that can be used interchangeably, i.e. dr/dering are the same. +The filters accept the following options: + +@table @option +@item subfilters +Set postprocessing subfilters string. +@end table + All subfilters share common options to determine their scope: @table @option @@ -4480,12 +6334,12 @@ Do luminance filtering only (no chrominance). Do chrominance filtering only (no luminance). @end table -These options can be appended after the subfilter name, separated by a ':'. +These options can be appended after the subfilter name, separated by a '|'. Available subfilters are: @table @option -@item hb/hdeblock[:difference[:flatness]] +@item hb/hdeblock[|difference[|flatness]] Horizontal deblocking filter @table @option @item difference @@ -4494,7 +6348,7 @@ Difference factor where higher values mean more deblocking (default: @code{32}). Flatness threshold where lower values mean more deblocking (default: @code{39}). @end table -@item vb/vdeblock[:difference[:flatness]] +@item vb/vdeblock[|difference[|flatness]] Vertical deblocking filter @table @option @item difference @@ -4503,7 +6357,7 @@ Difference factor where higher values mean more deblocking (default: @code{32}). Flatness threshold where lower values mean more deblocking (default: @code{39}). @end table -@item ha/hadeblock[:difference[:flatness]] +@item ha/hadeblock[|difference[|flatness]] Accurate horizontal deblocking filter @table @option @item difference @@ -4512,7 +6366,7 @@ Difference factor where higher values mean more deblocking (default: @code{32}). Flatness threshold where lower values mean more deblocking (default: @code{39}). @end table -@item va/vadeblock[:difference[:flatness]] +@item va/vadeblock[|difference[|flatness]] Accurate vertical deblocking filter @table @option @item difference @@ -4536,7 +6390,7 @@ Experimental vertical deblocking filter @item dr/dering Deringing filter -@item tn/tmpnoise[:threshold1[:threshold2[:threshold3]]], temporal noise reducer +@item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer @table @option @item threshold1 larger -> stronger filtering @@ -4576,7 +6430,7 @@ second line with a @code{(-1 4 2 4 -1)} filter. Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. -@item fq/forceQuant[:quantizer] +@item fq/forceQuant[|quantizer] Overrides the quantizer table from the input with the constant quantizer you specify. @table @option @@ -4585,13 +6439,13 @@ Quantizer to use @end table @item de/default -Default pp filter combination (@code{hb:a,vb:a,dr:a}) +Default pp filter combination (@code{hb|a,vb|a,dr|a}) @item fa/fast -Fast pp filter combination (@code{h1:a,v1:a,dr:a}) +Fast pp filter combination (@code{h1|a,v1|a,dr|a}) @item ac -High quality pp filter combination (@code{ha:a:128:7,va:a,dr:a}) +High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) @end table @subsection Examples @@ -4613,27 +6467,163 @@ pp=de/-al @item Apply default filters and temporal denoiser: @example -pp=default/tmpnoise:1:2:3 +pp=default/tmpnoise|1|2|3 @end example @item Apply deblocking on luminance only, and switch vertical deblocking on or off automatically depending on available CPU time: @example -pp=hb:y/vb:a +pp=hb|y/vb|a @end example @end itemize +@section psnr + +Obtain the average, maximum and minimum PSNR (Peak Signal to Noise +Ratio) between two input videos. + +This filter takes in input two input videos, the first input is +considered the "main" source and is passed unchanged to the +output. The second input is used as a "reference" video for computing +the PSNR. + +Both video inputs must have the same resolution and pixel format for +this filter to work correctly. Also it assumes that both inputs +have the same number of frames, which are compared one by one. + +The obtained average PSNR is printed through the logging system. + +The filter stores the accumulated MSE (mean squared error) of each +frame, and at the end of the processing it is averaged across all frames +equally, and the following formula is applied to obtain the PSNR: + +@example +PSNR = 10*log10(MAX^2/MSE) +@end example + +Where MAX is the average of the maximum values of each component of the +image. + +The description of the accepted parameters follows. + +@table @option +@item stats_file, f +If specified the filter will use the named file to save the PSNR of +each individual frame. +@end table + +The file printed if @var{stats_file} is selected, contains a sequence of +key/value pairs of the form @var{key}:@var{value} for each compared +couple of frames. + +A description of each shown parameter follows: + +@table @option +@item n +sequential number of the input frame, starting from 1 + +@item mse_avg +Mean Square Error pixel-by-pixel average difference of the compared +frames, averaged over all the image components. + +@item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a +Mean Square Error pixel-by-pixel average difference of the compared +frames for the component specified by the suffix. + +@item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a +Peak Signal to Noise ratio of the compared frames for the component +specified by the suffix. +@end table + +For example: +@example +movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; +[main][ref] psnr="stats_file=stats.log" [out] +@end example + +On this example the input file being processed is compared with the +reference file @file{ref_movie.mpg}. The PSNR of each individual frame +is stored in @file{stats.log}. + +@section pullup + +Pulldown reversal (inverse telecine) filter, capable of handling mixed +hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive +content. + +The pullup filter is designed to take advantage of future context in making +its decisions. This filter is stateless in the sense that it does not lock +onto a pattern to follow, but it instead looks forward to the following +fields in order to identify matches and rebuild progressive frames. + +To produce content with an even framerate, insert the fps filter after +pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, +@code{fps=24} for 30fps and the (rare) telecined 25fps input. + +The filter accepts the following options: + +@table @option +@item jl +@item jr +@item jt +@item jb +These options set the amount of "junk" to ignore at the left, right, top, and +bottom of the image, respectively. Left and right are in units of 8 pixels, +while top and bottom are in units of 2 lines. +The default is 8 pixels on each side. + +@item sb +Set the strict breaks. Setting this option to 1 will reduce the chances of +filter generating an occasional mismatched frame, but it may also cause an +excessive number of frames to be dropped during high motion sequences. +Conversely, setting it to -1 will make filter match fields more easily. +This may help processing of video where there is slight blurring between +the fields, but may also cause there to be interlaced frames in the output. +Default value is @code{0}. + +@item mp +Set the metric plane to use. It accepts the following values: +@table @samp +@item l +Use luma plane. + +@item u +Use chroma blue plane. + +@item v +Use chroma red plane. +@end table + +This option may be set to use chroma plane instead of the default luma plane +for doing filter's computations. This may improve accuracy on very clean +source material, but more likely will decrease accuracy, especially if there +is chroma noise (rainbow effect) or any grayscale video. +The main purpose of setting @option{mp} to a chroma plane is to reduce CPU +load and make pullup usable in realtime on slow machines. +@end table + +For best results (without duplicated frames in the output file) it is +necessary to change the output frame rate. For example, to inverse +telecine NTSC input: +@example +ffmpeg -i input -vf pullup -r 24000/1001 ... +@end example + @section removelogo Suppress a TV station logo, using an image file to determine which pixels comprise the logo. It works by filling in the pixels that comprise the logo with neighboring pixels. -This filter requires one argument which specifies the filter bitmap -file, which can be any image format supported by libavformat. The -width and height of the image file must match those of the video -stream being processed. +The filter accepts the following options: + +@table @option +@item filename, f +Set the filter bitmap file, which can be any image format supported by +libavformat. The width and height of the image file must match those of the +video stream being processed. +@end table Pixels in the provided bitmap image with a value of zero are not considered part of the logo, non-zero pixels are considered part of @@ -4650,6 +6640,170 @@ much, but it will increase the amount of blurring needed to cover over the image and will destroy more information than necessary, and extra pixels will slow things down on a large logo. +@section rotate + +Rotate video by an arbitrary angle expressed in radians. + +The filter accepts the following options: + +A description of the optional parameters follows. +@table @option +@item angle, a +Set an expression for the angle by which to rotate the input video +clockwise, expressed as a number of radians. A negative value will +result in a counter-clockwise rotation. By default it is set to "0". + +This expression is evaluated for each frame. + +@item out_w, ow +Set the output width expression, default value is "iw". +This expression is evaluated just once during configuration. + +@item out_h, oh +Set the output height expression, default value is "ih". +This expression is evaluated just once during configuration. + +@item bilinear +Enable bilinear interpolation if set to 1, a value of 0 disables +it. Default value is 1. + +@item fillcolor, c +Set the color used to fill the output area not covered by the rotated +image. For the generalsyntax of this option, check the "Color" section in the +ffmpeg-utils manual. If the special value "none" is selected then no +background is printed (useful for example if the background is never shown). + +Default value is "black". +@end table + +The expressions for the angle and the output size can contain the +following constants and functions: + +@table @option +@item n +sequential number of the input frame, starting from 0. It is always NAN +before the first frame is filtered. + +@item t +time in seconds of the input frame, it is set to 0 when the filter is +configured. It is always NAN before the first frame is filtered. + +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + +@item in_w, iw +@item in_h, ih +the input video width and heigth + +@item out_w, ow +@item out_h, oh +the output width and heigth, that is the size of the padded area as +specified by the @var{width} and @var{height} expressions + +@item rotw(a) +@item roth(a) +the minimal width/height required for completely containing the input +video rotated by @var{a} radians. + +These are only available when computing the @option{out_w} and +@option{out_h} expressions. +@end table + +@subsection Examples + +@itemize +@item +Rotate the input by PI/6 radians clockwise: +@example +rotate=PI/6 +@end example + +@item +Rotate the input by PI/6 radians counter-clockwise: +@example +rotate=-PI/6 +@end example + +@item +Apply a constant rotation with period T, starting from an angle of PI/3: +@example +rotate=PI/3+2*PI*t/T +@end example + +@item +Make the input video rotation oscillating with a period of T +seconds and an amplitude of A radians: +@example +rotate=A*sin(2*PI/T*t) +@end example + +@item +Rotate the video, output size is choosen so that the whole rotating +input video is always completely contained in the output: +@example +rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' +@end example + +@item +Rotate the video, reduce the output size so that no background is ever +shown: +@example +rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none +@end example +@end itemize + +@subsection Commands + +The filter supports the following commands: + +@table @option +@item a, angle +Set the angle expression. +The command accepts the same syntax of the corresponding option. + +If the specified expression is not valid, it is kept at its current +value. +@end table + +@section sab + +Apply Shape Adaptive Blur. + +The filter accepts the following options: + +@table @option +@item luma_radius, lr +Set luma blur filter strength, must be a value in range 0.1-4.0, default +value is 1.0. A greater value will result in a more blurred image, and +in slower processing. + +@item luma_pre_filter_radius, lpfr +Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default +value is 1.0. + +@item luma_strength, ls +Set luma maximum difference between pixels to still be considered, must +be a value in the 0.1-100.0 range, default value is 1.0. + +@item chroma_radius, cr +Set chroma blur filter strength, must be a value in range 0.1-4.0. A +greater value will result in a more blurred image, and in slower +processing. + +@item chroma_pre_filter_radius, cpfr +Set chroma pre-filter radius, must be a value in the 0.1-2.0 range. + +@item chroma_strength, cs +Set chroma maximum difference between pixels to still be considered, +must be a value in the 0.1-100.0 range. +@end table + +Each chroma option value, if not explicitly specified, is set to the +corresponding luma option value. + +@anchor{scale} @section scale Scale (resize) the input video, using the libswscale library. @@ -4657,64 +6811,168 @@ Scale (resize) the input video, using the libswscale library. The scale filter forces the output display aspect ratio to be the same of the input, by changing the output sample aspect ratio. -This filter accepts a list of named options in the form of -@var{key}=@var{value} pairs separated by ":". If the key for the first -two options is not specified, the assumed keys for the first two -values are @code{w} and @code{h}. If the first option has no key and -can be interpreted like a video size specification, it will be used -to set the video size. +If the input image format is different from the format requested by +the next filter, the scale filter will convert the input to the +requested format. + +@subsection Options +The filter accepts the following options, or any of the options +supported by the libswscale scaler. -A description of the accepted options follows. +See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for +the complete list of scaler options. @table @option @item width, w -Set the video width expression, default value is @code{iw}. See below -for the list of accepted constants. - @item height, h -Set the video heiht expression, default value is @code{ih}. -See below for the list of accepted constants. +Set the output video dimension expression. Default value is the input +dimension. + +If the value is 0, the input width is used for the output. + +If one of the values is -1, the scale filter will use a value that +maintains the aspect ratio of the input image, calculated from the +other specified dimension. If both of them are -1, the input size is +used + +See below for the list of accepted constants for use in the dimension +expression. @item interl -Set the interlacing. It accepts the following values: +Set the interlacing mode. It accepts the following values: -@table @option +@table @samp @item 1 -force interlaced aware scaling +Force interlaced aware scaling. @item 0 -do not apply interlaced scaling +Do not apply interlaced scaling. @item -1 -select interlaced aware scaling depending on whether the source frames -are flagged as interlaced or not +Select interlaced aware scaling depending on whether the source frames +are flagged as interlaced or not. @end table -Default value is @code{0}. +Default value is @samp{0}. @item flags -Set libswscale scaling flags. If not explictly specified the filter -applies a bilinear scaling algorithm. +Set libswscale scaling flags. See +@ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the +complete list of values. If not explictly specified the filter applies +the default flags. @item size, s -Set the video size, the value must be a valid abbreviation or in the -form @var{width}x@var{height}. +Set the video size. For the syntax of this option, check the "Video size" +section in the ffmpeg-utils manual. + +@item in_color_matrix +@item out_color_matrix +Set in/output YCbCr color space type. + +This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. + +If not specified, the color space type depends on the pixel format. + +Possible values: + +@table @samp +@item auto +Choose automatically. + +@item bt709 +Format conforming to International Telecommunication Union (ITU) +Recommendation BT.709. + +@item fcc +Set color space conforming to the United States Federal Communications +Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). + +@item bt601 +Set color space conforming to: + +@itemize +@item +ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 + +@item +ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G + +@item +Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 + +@end itemize + +@item smpte240m +Set color space conforming to SMPTE ST 240:1999. +@end table + +@item in_range +@item out_range +Set in/output YCbCr sample range. + +This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. If not specified, the +range depends on the pixel format. Possible values: + +@table @samp +@item auto +Choose automatically. + +@item jpeg/full/pc +Set full range (0-255 in case of 8-bit luma). + +@item mpeg/tv +Set "MPEG" range (16-235 in case of 8-bit luma). +@end table + +@item force_original_aspect_ratio +Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: + +@table @samp +@item disable +Scale the video as specified and disable this feature. + +@item decrease +The output video dimensions will automatically be decreased if needed. + +@item increase +The output video dimensions will automatically be increased if needed. + +@end table + +One useful instance of this option is that when you know a specific device's +maximum allowed resolution, you can use this to limit the output video to +that, while retaining the aspect ratio. For example, device A allows +1280x720 playback, and your video is 1920x800. Using this option (set it to +decrease) and specifying 1280x720 to the command line makes the output +1280x533. + +Please note that this is a different thing than specifying -1 for @option{w} +or @option{h}, you still need to specify the output resolution for this option +to work. + @end table -The values of the @var{w} and @var{h} options are expressions +The values of the @option{w} and @option{h} options are expressions containing the following constants: -@table @option -@item in_w, in_h +@table @var +@item in_w +@item in_h the input width and height -@item iw, ih +@item iw +@item ih same as @var{in_w} and @var{in_h} -@item out_w, out_h -the output (cropped) width and height +@item out_w +@item out_h +the output (scaled) width and height -@item ow, oh +@item ow +@item oh same as @var{out_w} and @var{out_h} @item a @@ -4724,23 +6982,18 @@ same as @var{iw} / @var{ih} input sample aspect ratio @item dar -input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} +input display aspect ratio. Calculated from @code{(iw / ih) * sar}. -@item hsub, vsub -horizontal and vertical chroma subsample values. For example for the +@item hsub +@item vsub +horizontal and vertical input chroma subsample values. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. -@end table -If the input image format is different from the format requested by -the next filter, the scale filter will convert the input to the -requested format. - -If the value for @var{width} or @var{height} is 0, the respective input -size is used for the output. - -If the value for @var{width} or @var{height} is -1, the scale filter will -use, for the respective output size, a value that maintains the aspect -ratio of the input image. +@item ohsub +@item ovsub +horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. +@end table @subsection Examples @@ -4748,12 +7001,12 @@ ratio of the input image. @item Scale the input video to a size of 200x100: @example -scale=200:100 +scale=w=200:h=100 @end example This is equivalent to: @example -scale=w=200:h=100 +scale=200:100 @end example or: @@ -4775,7 +7028,7 @@ scale=size=qcif @item Scale the input to 2x: @example -scale=2*iw:2*ih +scale=w=2*iw:h=2*ih @end example @item @@ -4793,7 +7046,7 @@ scale=2*iw:2*ih:interl=1 @item Scale the input to half size: @example -scale=iw/2:ih/2 +scale=w=iw/2:h=ih/2 @end example @item @@ -4812,11 +7065,12 @@ scale=ih*PHI:ih @item Increase the height, and set the width to 3/2 of the height: @example -scale=3/2*oh:3/5*ih +scale=w=3/2*oh:h=3/5*ih @end example @item -Increase the size, but make the size a multiple of the chroma: +Increase the size, but make the size a multiple of the chroma +subsample values: @example scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" @end example @@ -4825,10 +7079,20 @@ scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" Increase the width to a maximum of 500 pixels, keep the same input aspect ratio: @example -scale='min(500\, iw*3/2):-1' +scale=w='min(500\, iw*3/2):h=-1' @end example @end itemize +@section separatefields + +The @code{separatefields} takes a frame-based video input and splits +each frame into its components fields, producing a new half height clip +with twice the frame rate and twice the frame count. + +This filter use field-dominance information in frame to decide which +of each pair of fields to place first in the output. +If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. + @section setdar, setsar The @code{setdar} filter sets the Display Aspect Ratio for the filter @@ -4857,52 +7121,79 @@ Keep in mind that the sample aspect ratio set by the @code{setsar} filter may be changed by later filters in the filterchain, e.g. if another "setsar" or a "setdar" filter is applied. -The @code{setdar} and @code{setsar} filters accept a string in the -form @var{num}:@var{den} expressing an aspect ratio, or the following -named options, expressed as a sequence of @var{key}=@var{value} pairs, -separated by ":". +The filters accept the following options: @table @option -@item max -Set the maximum integer value to use for expressing numerator and -denominator when reducing the expressed aspect ratio to a rational. -Default value is @code{100}. - -@item r, ratio: +@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) Set the aspect ratio used by the filter. The parameter can be a floating point number string, an expression, or a string of the form @var{num}:@var{den}, where @var{num} and @var{den} are the numerator and denominator of the aspect ratio. If the parameter is not specified, it is assumed the value "0". -In case the form "@var{num}:@var{den}" the @code{:} character should -be escaped. +In case the form "@var{num}:@var{den}" is used, the @code{:} character +should be escaped. + +@item max +Set the maximum integer value to use for expressing numerator and +denominator when reducing the expressed aspect ratio to a rational. +Default value is @code{100}. + @end table -If the keys are omitted in the named options list, the specifed values -are assumed to be @var{ratio} and @var{max} in that order. +The parameter @var{sar} is an expression containing +the following constants: -For example to change the display aspect ratio to 16:9, specify: -@example -setdar='16:9' -@end example +@table @option +@item E, PI, PHI +the corresponding mathematical approximated values for e +(euler number), pi (greek PI), phi (golden ratio) + +@item w, h +the input width and height + +@item a +same as @var{w} / @var{h} + +@item sar +input sample aspect ratio + +@item dar +input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} + +@item hsub, vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. +@end table -The example above is equivalent to: +@subsection Examples + +@itemize + +@item +To change the display aspect ratio to 16:9, specify one of the following: @example -setdar=1.77777 +setdar=dar=1.77777 +setdar=dar=16/9 +setdar=dar=1.77777 @end example +@item To change the sample aspect ratio to 10:11, specify: @example -setsar='10:11' +setsar=sar=10/11 @end example +@item To set a display aspect ratio of 16:9, and specify a maximum integer value of 1000 in the aspect ratio reduction, use the command: @example -setdar=ratio='16:9':max=1000 +setdar=ratio=16/9:max=1000 @end example +@end itemize + +@anchor{setfield} @section setfield Force field for the output video frame. @@ -4912,9 +7203,12 @@ output frames. It does not change the input frame, but only sets the corresponding property, which affects how the frame is treated by following filters (e.g. @code{fieldorder} or @code{yadif}). -This filter accepts a single option @option{mode}, which can be -specified either by setting @code{mode=VALUE} or setting the value -alone. Available values are: +The filter accepts the following options: + +@table @option + +@item mode +Available values are: @table @samp @item auto @@ -4929,6 +7223,7 @@ Mark the frame as top-field-first. @item prog Mark the frame as progressive. @end table +@end table @section showinfo @@ -4964,8 +7259,8 @@ sample aspect ratio of the input frame, expressed in the form @var{num}/@var{den} @item s -size of the input frame, expressed in the form -@var{width}x@var{height} +size of the input frame. For the syntax of this option, check the "Video size" +section in the ffmpeg-utils manual. @item i interlaced mode ("P" for "progressive", "T" for top field first, "B" @@ -4989,36 +7284,45 @@ Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]" @end table +@anchor{smartblur} @section smartblur Blur the input video without impacting the outlines. -This filter accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". - -If the key of the first options is omitted, the arguments are -interpreted according to the syntax: -@var{luma_radius}:@var{luma_strength}:@var{luma_threshold}[:@var{chroma_radius}:@var{chroma_strength}:@var{chroma_threshold}] - -A description of the accepted options follows. +The filter accepts the following options: @table @option @item luma_radius, lr -@item chroma_radius, cr -Set the luma/chroma radius. The option value must be a float number in +Set the luma radius. The option value must be a float number in the range [0.1,5.0] that specifies the variance of the gaussian filter used to blur the image (slower if larger). Default value is 1.0. @item luma_strength, ls -@item chroma_strength, cs -Set the luma/chroma strength. The option value must be a float number +Set the luma strength. The option value must be a float number in the range [-1.0,1.0] that configures the blurring. A value included in [0.0,1.0] will blur the image whereas a value included in [-1.0,0.0] will sharpen the image. Default value is 1.0. @item luma_threshold, lt +Set the luma threshold used as a coefficient to determine +whether a pixel should be blurred or not. The option value must be an +integer in the range [-30,30]. A value of 0 will filter all the image, +a value included in [0,30] will filter flat areas and a value included +in [-30,0] will filter edges. Default value is 0. + +@item chroma_radius, cr +Set the chroma radius. The option value must be a float number in +the range [0.1,5.0] that specifies the variance of the gaussian filter +used to blur the image (slower if larger). Default value is 1.0. + +@item chroma_strength, cs +Set the chroma strength. The option value must be a float number +in the range [-1.0,1.0] that configures the blurring. A value included +in [0.0,1.0] will blur the image whereas a value included in +[-1.0,0.0] will sharpen the image. Default value is 1.0. + @item chroma_threshold, ct -Set the luma/chroma threshold used as a coefficient to determine +Set the chroma threshold used as a coefficient to determine whether a pixel should be blurred or not. The option value must be an integer in the range [-30,30]. A value of 0 will filter all the image, a value included in [0,30] will filter flat areas and a value included @@ -5032,8 +7336,7 @@ is set. Convert between different stereoscopic image formats. -This filter accepts the following named options, expressed as a -sequence of @var{key}=@var{value} pairs, separated by ":". +The filters accept the following options: @table @option @item in @@ -5069,6 +7372,12 @@ above-below with half height resolution above-below with half height resolution (right eye above, left eye below) +@item al +alternating frames (left eye first, right eye second) + +@item ar +alternating frames (right eye first, left eye second) + Default value is @samp{sbsl}. @end table @@ -5149,6 +7458,58 @@ mono output (right eye only) Default value is @samp{arcd}. @end table +@subsection Examples + +@itemize +@item +Convert input video from side by side parallel to anaglyph yellow/blue dubois: +@example +stereo3d=sbsl:aybd +@end example + +@item +Convert input video from above bellow (left eye above, right eye below) to side by side crosseye. +@example +stereo3d=abl:sbsr +@end example +@end itemize + +@section spp + +Apply a simple postprocessing filter that compresses and decompresses the image +at several (or - in the case of @option{quality} level @code{6} - all) shifts +and average the results. + +The filter accepts the following options: + +@table @option +@item quality +Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-6. If set to @code{0}, the filter will have no +effect. A value of @code{6} means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +@code{3}. + +@item qp +Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). + +@item mode +Set thresholding mode. Available modes are: + +@table @samp +@item hard +Set hard thresholding (default). +@item soft +Set soft thresholding (better de-ringing effect, but likely blurrier). +@end table + +@item use_bframe_qp +Enable the use of the QP from the B-Frames if set to @code{1}. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +@code{0} (not enabled). +@end table + @anchor{subtitles} @section subtitles @@ -5159,8 +7520,7 @@ To enable compilation of this filter you need to configure FFmpeg with libavformat to convert the passed subtitles file to ASS (Advanced Substation Alpha) subtitles format. -This filter accepts the following named options, expressed as a -sequence of @var{key}=@var{value} pairs, separated by ":". +The filter accepts the following options: @table @option @item filename, f @@ -5168,8 +7528,10 @@ Set the filename of the subtitle file to read. It must be specified. @item original_size Specify the size of the original video, the video for which the ASS file -was composed. Due to a misdesign in ASS aspect ratio arithmetic, this is -necessary to correctly scale the fonts if the aspect ratio has been changed. +was composed. For the syntax of this option, check the "Video size" section in +the ffmpeg-utils manual. Due to a misdesign in ASS aspect ratio arithmetic, +this is necessary to correctly scale the fonts if the aspect ratio has been +changed. @item charenc Set subtitles input character encoding. @code{subtitles} filter only. Only @@ -5190,29 +7552,6 @@ which is equivalent to: subtitles=filename=sub.srt @end example -@section split - -Split input video into several identical outputs. - -The filter accepts a single parameter which specifies the number of outputs. If -unspecified, it defaults to 2. - -For example -@example -ffmpeg -i INPUT -filter_complex split=5 OUTPUT -@end example -will create 5 copies of the input video. - -For example: -@example -[in] split [splitout1][splitout2]; -[splitout1] crop=100:100:0:0 [cropout]; -[splitout2] pad=200:200:100:100 [padout]; -@end example - -will create two separate outputs from the same input, one cropped and -one padded. - @section super2xsai Scale the input by 2x and smooth using the Super2xSaI (Scale and @@ -5223,38 +7562,92 @@ Useful for enlarging pixel art images without reducing sharpness. @section swapuv Swap U & V plane. +@section telecine + +Apply telecine process to the video. + +This filter accepts the following options: + +@table @option +@item first_field +@table @samp +@item top, t +top field first +@item bottom, b +bottom field first +The default value is @code{top}. +@end table + +@item pattern +A string of numbers representing the pulldown pattern you wish to apply. +The default value is @code{23}. +@end table + +@example +Some typical patterns: + +NTSC output (30i): +27.5p: 32222 +24p: 23 (classic) +24p: 2332 (preferred) +20p: 33 +18p: 334 +16p: 3444 + +PAL output (25i): +27.5p: 12222 +24p: 222222222223 ("Euro pulldown") +16.67p: 33 +16p: 33333334 +@end example + @section thumbnail Select the most representative frame in a given sequence of consecutive frames. -It accepts as argument the frames batch size to analyze (default @var{N}=100); -in a set of @var{N} frames, the filter will pick one of them, and then handle -the next batch of @var{N} frames until the end. +The filter accepts the following options: -Since the filter keeps track of the whole frames sequence, a bigger @var{N} +@table @option +@item n +Set the frames batch size to analyze; in a set of @var{n} frames, the filter +will pick one of them, and then handle the next batch of @var{n} frames until +the end. Default is @code{100}. +@end table + +Since the filter keeps track of the whole frames sequence, a bigger @var{n} value will result in a higher memory usage, so a high value is not recommended. -The following example extract one picture each 50 frames: +@subsection Examples + +@itemize +@item +Extract one picture each 50 frames: @example thumbnail=50 @end example +@item Complete example of a thumbnail creation with @command{ffmpeg}: @example ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png @end example +@end itemize @section tile Tile several successive frames together. -It accepts a list of options in the form of @var{key}=@var{value} pairs -separated by ":". A description of the accepted options follows. +The filter accepts the following options: @table @option @item layout -Set the grid size (i.e. the number of lines and columns) in the form -"@var{w}x@var{h}". +Set the grid size (i.e. the number of lines and columns). For the syntax of +this option, check the "Video size" section in the ffmpeg-utils manual. + +@item nb_frames +Set the maximum number of frames to render in the given area. It must be less +than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all +the area will be used. @item margin Set the outer border margin in pixels. @@ -5264,19 +7657,17 @@ Set the inner border thickness (i.e. the number of pixels between frames). For more advanced padding options (such as having different values for the edges), refer to the pad video filter. -@item nb_frames -Set the maximum number of frames to render in the given area. It must be less -than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all -the area will be used. - +@item color +Specify the color of the unused areaFor the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. The default value of @var{color} +is "black". @end table -Alternatively, the options can be specified as a flat string: - -@var{layout}[:@var{nb_frames}[:@var{margin}[:@var{padding}]]] +@subsection Examples -For example, produce 8x8 PNG tiles of all keyframes (@option{-skip_frame -nokey}) in a movie: +@itemize +@item +Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: @example ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png @end example @@ -5284,12 +7675,14 @@ The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from duplicating each output frame to accomodate the originally detected frame rate. -Another example to display @code{5} pictures in an area of @code{3x2} frames, +@item +Display @code{5} pictures in an area of @code{3x2} frames, with @code{7} pixels between them, and @code{2} pixels of initial margin, using mixed flat and named options: @example tile=3x2:nb_frames=5:padding=7:margin=2 @end example +@end itemize @section tinterlace @@ -5298,13 +7691,7 @@ Perform various types of temporal field interlacing. Frames are counted starting from 1, so the first input frame is considered odd. -This filter accepts options in the form of @var{key}=@var{value} pairs -separated by ":". -Alternatively, the @var{mode} option can be specified as a value alone, -optionally followed by a ":" and further ":" separated @var{key}=@var{value} -pairs. - -A description of the accepted options follows. +The filter accepts the following options: @table @option @@ -5317,27 +7704,27 @@ Available values are: @table @samp @item merge, 0 Move odd frames into the upper field, even into the lower field, -generating a double height frame at half framerate. +generating a double height frame at half frame rate. @item drop_odd, 1 Only output even frames, odd frames are dropped, generating a frame with -unchanged height at half framerate. +unchanged height at half frame rate. @item drop_even, 2 Only output odd frames, even frames are dropped, generating a frame with -unchanged height at half framerate. +unchanged height at half frame rate. @item pad, 3 Expand each frame to full height, but pad alternate lines with black, -generating a frame with double height at the same input framerate. +generating a frame with double height at the same input frame rate. @item interleave_top, 4 Interleave the upper field from odd frames with the lower field from -even frames, generating a frame with unchanged height at half framerate. +even frames, generating a frame with unchanged height at half frame rate. @item interleave_bottom, 5 Interleave the lower field from odd frames with the upper field from -even frames, generating a frame with unchanged height at half framerate. +even frames, generating a frame with unchanged height at half frame rate. @item interlacex2, 6 Double frame rate with unchanged height. Frames are inserted each @@ -5375,17 +7762,16 @@ Vertical low-pass filtering can only be enabled for @option{mode} Transpose rows with columns in the input video and optionally flip it. -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ':'. If the key of the first options is omitted, -the arguments are interpreted according to the syntax -@var{dir}:@var{passthrough}. +This filter accepts the following options: @table @option + @item dir -Specify the transposition direction. Can assume the following values: +Specify the transposition direction. +Can assume the following values: @table @samp -@item 0, 4 +@item 0, 4, cclock_flip Rotate by 90 degrees counterclockwise and vertically flip (default), that is: @example L.R L.l @@ -5393,7 +7779,7 @@ L.R L.l l.r R.r @end example -@item 1, 5 +@item 1, 5, clock Rotate by 90 degrees clockwise, that is: @example L.R l.L @@ -5401,7 +7787,7 @@ L.R l.L l.r r.R @end example -@item 2, 6 +@item 2, 6, cclock Rotate by 90 degrees counterclockwise, that is: @example L.R R.r @@ -5409,7 +7795,7 @@ L.R R.r l.r L.l @end example -@item 3, 7 +@item 3, 7, clock_flip Rotate by 90 degrees clockwise and vertically flip, that is: @example L.R r.R @@ -5422,6 +7808,9 @@ For values between 4-7, the transposition is only done if the input video geometry is portrait and not landscape. These values are deprecated, the @code{passthrough} option should be used instead. +Numerical values are deprecated, and should be dropped in favor of +symbolic constants. + @item passthrough Do not apply the transposition if the input geometry matches the one specified by the specified value. It accepts the following values: @@ -5448,49 +7837,130 @@ The command above can also be specified as: transpose=1:portrait @end example -@section unsharp +@section trim +Trim the input so that the output contains one continuous subpart of the input. -Sharpen or blur the input video. +This filter accepts the following options: +@table @option +@item start +Specify time of the start of the kept section, i.e. the frame with the +timestamp @var{start} will be the first frame in the output. + +@item end +Specify time of the first frame that will be dropped, i.e. the frame +immediately preceding the one with the timestamp @var{end} will be the last +frame in the output. -This filter accepts parameters as a list of @var{key}=@var{value} pairs, -separated by ":". +@item start_pts +Same as @var{start}, except this option sets the start timestamp in timebase +units instead of seconds. -If the key of the first options is omitted, the arguments are -interpreted according to the syntax: -@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount} +@item end_pts +Same as @var{end}, except this option sets the end timestamp in timebase units +instead of seconds. -A description of the accepted options follows. +@item duration +Specify maximum duration of the output. + +@item start_frame +Number of the first frame that should be passed to output. + +@item end_frame +Number of the first frame that should be dropped. +@end table + +@option{start}, @option{end}, @option{duration} are expressed as time +duration specifications, check the "Time duration" section in the +ffmpeg-utils manual. + +Note that the first two sets of the start/end options and the @option{duration} +option look at the frame timestamp, while the _frame variants simply count the +frames that pass through the filter. Also note that this filter does not modify +the timestamps. If you wish that the output timestamps start at zero, insert a +setpts filter after the trim filter. + +If multiple start or end options are set, this filter tries to be greedy and +keep all the frames that match at least one of the specified constraints. To keep +only the part that matches all the constraints at once, chain multiple trim +filters. + +The defaults are such that all the input is kept. So it is possible to set e.g. +just the end values to keep everything before the specified time. + +Examples: +@itemize +@item +drop everything except the second minute of input +@example +ffmpeg -i INPUT -vf trim=60:120 +@end example + +@item +keep only the first second +@example +ffmpeg -i INPUT -vf trim=duration=1 +@end example + +@end itemize + + +@section unsharp + +Sharpen or blur the input video. + +It accepts the following parameters: @table @option @item luma_msize_x, lx +Set the luma matrix horizontal size. It must be an odd integer between +3 and 63, default value is 5. + +@item luma_msize_y, ly +Set the luma matrix vertical size. It must be an odd integer between 3 +and 63, default value is 5. + +@item luma_amount, la +Set the luma effect strength. It can be a float number, reasonable +values lay between -1.5 and 1.5. + +Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. + +Default value is 1.0. + @item chroma_msize_x, cx -Set the luma/chroma matrix horizontal size. It must be an odd integer +Set the chroma matrix horizontal size. It must be an odd integer between 3 and 63, default value is 5. -@item luma_msize_y, ly @item chroma_msize_y, cy -Set the luma/chroma matrix vertical size. It must be an odd integer +Set the chroma matrix vertical size. It must be an odd integer between 3 and 63, default value is 5. -@item luma_amount, la @item chroma_amount, ca -Set the luma/chroma effect strength. It can be a float number, -reasonable values lay between -1.5 and 1.5. +Set the chroma effect strength. It can be a float number, reasonable +values lay between -1.5 and 1.5. Negative values will blur the input video, while positive values will sharpen it, a value of zero will disable the effect. -Default value is 1.0 for @option{luma_amount}, 0.0 for -@option{chroma_amount}. +Default value is 0.0. + +@item opencl +If set to 1, specify using OpenCL capabilities, only available if +FFmpeg was configured with @code{--enable-opencl}. Default value is 0. + @end table +All parameters are optional and default to the equivalent of the +string '5:5:1.0:5:5:0.0'. + @subsection Examples @itemize @item Apply strong luma sharpen effect: @example -unsharp=7:7:2.5 +unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 @end example @item @@ -5500,30 +7970,400 @@ unsharp=7:7:-2:7:7:-2 @end example @end itemize +@anchor{vidstabdetect} +@section vidstabdetect + +Analyze video stabilization/deshaking. Perform pass 1 of 2, see +@ref{vidstabtransform} for pass 2. + +This filter generates a file with relative translation and rotation +transform information about subsequent frames, which is then used by +the @ref{vidstabtransform} filter. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-libvidstab}. + +This filter accepts the following options: + +@table @option +@item result +Set the path to the file used to write the transforms information. +Default value is @file{transforms.trf}. + +@item shakiness +Set how shaky the video is and how quick the camera is. It accepts an +integer in the range 1-10, a value of 1 means little shakiness, a +value of 10 means strong shakiness. Default value is 5. + +@item accuracy +Set the accuracy of the detection process. It must be a value in the +range 1-15. A value of 1 means low accuracy, a value of 15 means high +accuracy. Default value is 9. + +@item stepsize +Set stepsize of the search process. The region around minimum is +scanned with 1 pixel resolution. Default value is 6. + +@item mincontrast +Set minimum contrast. Below this value a local measurement field is +discarded. Must be a floating point value in the range 0-1. Default +value is 0.3. + +@item tripod +Set reference frame number for tripod mode. + +If enabled, the motion of the frames is compared to a reference frame +in the filtered stream, identified by the specified number. The idea +is to compensate all movements in a more-or-less static scene and keep +the camera view absolutely still. + +If set to 0, it is disabled. The frames are counted starting from 1. + +@item show +Show fields and transforms in the resulting frames. It accepts an +integer in the range 0-2. Default value is 0, which disables any +visualization. +@end table + +@subsection Examples + +@itemize +@item +Use default values: +@example +vidstabdetect +@end example + +@item +Analyze strongly shaky movie and put the results in file +@file{mytransforms.trf}: +@example +vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" +@end example + +@item +Visualize the result of internal transformations in the resulting +video: +@example +vidstabdetect=show=1 +@end example + +@item +Analyze a video with medium shakiness using @command{ffmpeg}: +@example +ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi +@end example +@end itemize + +@anchor{vidstabtransform} +@section vidstabtransform + +Video stabilization/deshaking: pass 2 of 2, +see @ref{vidstabdetect} for pass 1. + +Read a file with transform information for each frame and +apply/compensate them. Together with the @ref{vidstabdetect} +filter this can be used to deshake videos. See also +@url{http://public.hronopik.de/vid.stab}. It is important to also use +the unsharp filter, see below. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-libvidstab}. + +This filter accepts the following options: + +@table @option + +@item input +path to the file used to read the transforms (default: @file{transforms.trf}) + +@item smoothing +number of frames (value*2 + 1) used for lowpass filtering the camera movements +(default: 10). For example a number of 10 means that 21 frames are used +(10 in the past and 10 in the future) to smoothen the motion in the +video. A larger values leads to a smoother video, but limits the +acceleration of the camera (pan/tilt movements). + +@item maxshift +maximal number of pixels to translate frames (default: -1 no limit) + +@item maxangle +maximal angle in radians (degree*PI/180) to rotate frames (default: -1 +no limit) + +@item crop +How to deal with borders that may be visible due to movement +compensation. Available values are: + +@table @samp +@item keep +keep image information from previous frame (default) +@item black +fill the border black +@end table + +@item invert +@table @samp +@item 0 +keep transforms normal (default) +@item 1 +invert transforms +@end table + +@item relative +consider transforms as +@table @samp +@item 0 +absolute +@item 1 +relative to previous frame (default) +@end table + +@item zoom +percentage to zoom (default: 0) +@table @samp +@item >0 +zoom in +@item <0 +zoom out +@end table + +@item optzoom +set optimal zooming to avoid borders +@table @samp +@item 0 +disabled +@item 1 +optimal static zoom value is determined (only very strong movements will lead to visible borders) (default) +@item 2 +optimal adaptive zoom value is determined (no borders will be visible) +@end table +Note that the value given at zoom is added to the one calculated +here. + +@item interpol +type of interpolation + +Available values are: +@table @samp +@item no +no interpolation +@item linear +linear only horizontal +@item bilinear +linear in both directions (default) +@item bicubic +cubic in both directions (slow) +@end table + +@item tripod +virtual tripod mode means that the video is stabilized such that the +camera stays stationary. Use also @code{tripod} option of +@ref{vidstabdetect}. +@table @samp +@item 0 +off (default) +@item 1 +virtual tripod mode: equivalent to @code{relative=0:smoothing=0} +@end table + +@end table + +@subsection Examples + +@itemize +@item +typical call with default default values: + (note the unsharp filter which is always recommended) +@example +ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg +@end example + +@item +zoom in a bit more and load transform data from a given file +@example +vidstabtransform=zoom=5:input="mytransforms.trf" +@end example + +@item +smoothen the video even more +@example +vidstabtransform=smoothing=30 +@end example + +@end itemize + @section vflip Flip the input video vertically. +For example, to vertically flip a video with @command{ffmpeg}: @example ffmpeg -i in.avi -vf "vflip" out.avi @end example +@section vignette + +Make or reverse a natural vignetting effect. + +The filter accepts the following options: + +@table @option +@item angle, a +Set lens angle expression as a number of radians. + +The value is clipped in the @code{[0,PI/2]} range. + +Default value: @code{"PI/5"} + +@item x0 +@item y0 +Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} +by default. + +@item mode +Set forward/backward mode. + +Available modes are: +@table @samp +@item forward +The larger the distance from the central point, the darker the image becomes. + +@item backward +The larger the distance from the central point, the brighter the image becomes. +This can be used to reverse a vignette effect, though there is no automatic +detection to extract the lens @option{angle} and other settings (yet). It can +also be used to create a burning effect. +@end table + +Default value is @samp{forward}. + +@item eval +Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). + +It accepts the following values: +@table @samp +@item init +Evaluate expressions only once during the filter initialization. + +@item frame +Evaluate expressions for each incoming frame. This is way slower than the +@samp{init} mode since it requires all the scalers to be re-computed, but it +allows advanced dynamic expressions. +@end table + +Default value is @samp{init}. + +@item dither +Set dithering to reduce the circular banding effects. Default is @code{1} +(enabled). + +@item aspect +Set vignette aspect. This setting allows to adjust the shape of the vignette. +Setting this value to the SAR of the input will make a rectangular vignetting +following the dimensions of the video. + +Default is @code{1/1}. +@end table + +@subsection Expressions + +The @option{alpha}, @option{x0} and @option{y0} expressions can contain the +following parameters. + +@table @option +@item w +@item h +input width and height + +@item n +the number of input frame, starting from 0 + +@item pts +the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in +@var{TB} units, NAN if undefined + +@item r +frame rate of the input video, NAN if the input frame rate is unknown + +@item t +the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined + +@item tb +time base of the input video +@end table + + +@subsection Examples + +@itemize +@item +Apply simple strong vignetting effect: +@example +vignette=PI/4 +@end example + +@item +Make a flickering vignetting: +@example +vignette='PI/4+random(1)*PI/50':eval=frame +@end example + +@end itemize + +@section w3fdif + +Deinterlace the input video ("w3fdif" stands for "Weston 3 Field +Deinterlacing Filter"). + +Based on the process described by Martin Weston for BBC R&D, and +implemented based on the de-interlace algorithm written by Jim +Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter +uses filter coefficients calculated by BBC R&D. + +There are two sets of filter coefficients, so called "simple": +and "complex". Which set of filter coefficients is used can +be set by passing an optional parameter: + +@table @option +@item filter +Set the interlacing filter coefficients. Accepts one of the following values: + +@table @samp +@item simple +Simple filter coefficient set. +@item complex +More-complex filter coefficient set. +@end table +Default value is @samp{complex}. + +@item deint +Specify which frames to deinterlace. Accept one of the following values: + +@table @samp +@item all +Deinterlace all frames, +@item interlaced +Only deinterlace frames marked as interlaced. +@end table + +Default value is @samp{all}. +@end table + +@anchor{yadif} @section yadif Deinterlace the input video ("yadif" means "yet another deinterlacing filter"). -The filter accepts parameters as a list of @var{key}=@var{value} -pairs, separated by ":". If the key of the first options is omitted, -the arguments are interpreted according to syntax -@var{mode}:@var{parity}:@var{deint}. +This filter accepts the following options: -The description of the accepted parameters follows. @table @option + @item mode -Specify the interlacing mode to adopt. Accept one of the following -values: +The interlacing mode to adopt, accepts one of the following values: @table @option @item 0, send_frame @@ -5539,8 +8379,8 @@ like @code{send_field} but skip spatial interlacing check Default value is @code{send_frame}. @item parity -Specify the picture field parity assumed for the input interlaced -video. Accept one of the following values: +The picture field parity assumed for the input interlaced video, accepts one of +the following values: @table @option @item 0, tff @@ -5583,13 +8423,20 @@ Buffer video frames, and make them available to the filter chain. This source is mainly intended for a programmatic use, in particular through the interface defined in @file{libavfilter/vsrc_buffer.h}. -It accepts a list of options in the form of @var{key}=@var{value} pairs -separated by ":". A description of the accepted options follows. +This source accepts the following options: @table @option @item video_size -Specify the size (width and height) of the buffered video frames. +Specify the size (width and height) of the buffered video frames. For the +syntax of this option, check the "Video size" section in the ffmpeg-utils +manual. + +@item width +Input video width. + +@item height +Input video height. @item pix_fmt A string representing the pixel format of the buffered video frames. @@ -5599,10 +8446,10 @@ name. @item time_base Specify the timebase assumed by the timestamps of the buffered frames. -@item time_base +@item frame_rate Specify the frame rate expected for the video stream. -@item pixel_aspect +@item pixel_aspect, sar Specify the sample aspect ratio assumed by the video frames. @item sws_param @@ -5613,7 +8460,7 @@ input size or format. For example: @example -buffer=size=320x240:pix_fmt=yuv410p:time_base=1/24:pixel_aspect=1/1 +buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 @end example will instruct the source to accept video frames with size 320x240 and @@ -5643,9 +8490,7 @@ At each new frame a new row in the video is filled with the result of the cellular automaton next generation. The behavior when the whole frame is filled is defined by the @option{scroll} option. -This source accepts a list of options in the form of -@var{key}=@var{value} pairs separated by ":". A description of the -accepted options follows. +This source accepts the following options: @table @option @item filename, f @@ -5685,7 +8530,8 @@ Set the cellular automaton rule, it is a number ranging from 0 to 255. Default value is 110. @item size, s -Set the size of the output video. +Set the size of the output video. For the syntax of this option, check +the "Video size" section in the ffmpeg-utils manual. If @option{filename} or @option{pattern} is specified, the size is set by default to the width of the specified initial state row, and the @@ -5751,9 +8597,7 @@ cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 Generate a Mandelbrot set fractal, and progressively zoom towards the point specified with @var{start_x} and @var{start_y}. -This source accepts a list of options in the form of -@var{key}=@var{value} pairs separated by ":". A description of the -accepted options follows. +This source accepts the following options: @table @option @@ -5805,7 +8649,8 @@ Set frame rate, expressed as number of frames per second. Default value is "25". @item size, s -Set frame size. Default value is "640x480". +Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". @item start_scale Set the initial scale value. Default value is 3.0. @@ -5826,8 +8671,7 @@ Generate various test patterns, as generated by the MPlayer test filter. The size of the generated video is fixed, and is 256x256. This source is useful in particular for testing encoding features. -This source accepts an optional sequence of @var{key}=@var{value} pairs, -separated by ":". The description of the accepted options follows. +This source accepts the following options: @table @option @@ -5883,23 +8727,32 @@ Provide a frei0r source. To enable compilation of this filter you need to install the frei0r header and configure FFmpeg with @code{--enable-frei0r}. -The source supports the syntax: -@example -@var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}] -@end example +This source accepts the following options: -@var{size} is the size of the video to generate, may be a string of the -form @var{width}x@var{height} or a frame size abbreviation. -@var{rate} is the rate of the video to generate, may be a string of -the form @var{num}/@var{den} or a frame rate abbreviation. -@var{src_name} is the name to the frei0r source to load. For more -information regarding frei0r and how to set the parameters read the -section @ref{frei0r} in the description of the video filters. +@table @option + +@item size +The size of the video to generate. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. + +@item framerate +Framerate of the generated video, may be a string of the form +@var{num}/@var{den} or a frame rate abbreviation. + +@item filter_name +The name to the frei0r source to load. For more information regarding frei0r and +how to set the parameters read the section @ref{frei0r} in the description of +the video filters. + +@item filter_params +A '|'-separated list of parameters to pass to the frei0r source. + +@end table For example, to generate a frei0r partik0l source with size 200x200 and frame rate 10 which is overlayed on the overlay filter main input: @example -frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay +frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay @end example @section life @@ -5918,9 +8771,7 @@ which specifies the number of neighbor alive cells which will make a cell stay alive or born. The @option{rule} option allows to specify the rule to adopt. -This source accepts a list of options in the form of -@var{key}=@var{value} pairs separated by ":". A description of the -accepted options follows. +This source accepts the following options: @table @option @item filename, f @@ -5970,7 +8821,8 @@ cells, and will born a new cell if there are three alive cells around a dead cell. @item size, s -Set the size of the output video. +Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. If @option{filename} is specified, the size is set by default to the same size of the input file. If @option{size} is set, it must contain @@ -5998,6 +8850,9 @@ used to represent a dead cell. @item mold_color Set mold color, for definitely dead and moldy cells. + +For the syntax of these 3 color options, check the "Color" section in the +ffmpeg-utils manual. @end table @subsection Examples @@ -6029,10 +8884,20 @@ ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_c @end example @end itemize -@section color, nullsrc, rgbtestsrc, smptebars, testsrc +@anchor{color} +@anchor{haldclutsrc} +@anchor{nullsrc} +@anchor{rgbtestsrc} +@anchor{smptebars} +@anchor{smptehdbars} +@anchor{testsrc} +@section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc The @code{color} source provides an uniformly colored input. +The @code{haldclutsrc} source provides an identity Hald CLUT. See also +@ref{haldclut} filter. + The @code{nullsrc} source returns unprocessed video frames. It is mainly useful to be employed in analysis / debugging tools, or as the source for filters which ignore the input data. @@ -6044,25 +8909,34 @@ stripe from top to bottom. The @code{smptebars} source generates a color bars pattern, based on the SMPTE Engineering Guideline EG 1-1990. +The @code{smptehdbars} source generates a color bars pattern, based on +the SMPTE RP 219-2002. + The @code{testsrc} source generates a test video pattern, showing a color pattern, a scrolling gradient and a timestamp. This is mainly intended for testing purposes. -These sources accept an optional sequence of @var{key}=@var{value} pairs, -separated by ":". The description of the accepted options follows. +The sources accept the following options: @table @option @item color, c -Specify the color of the source, only used in the @code{color} -source. It can be the name of a color (case insensitive match) or a -0xRRGGBB[AA] sequence, possibly followed by an alpha specifier. The -default value is "black". +Specify the color of the source, only available in the @code{color} +source. For the syntax of this option, check the "Color" section in the +ffmpeg-utils manual. + +@item level +Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} +source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} +pixels to be used as identity matrix for 3D lookup tables. Each component is +coded on a @code{1/(N*N)} scale. @item size, s -Specify the size of the sourced video, it may be a string of the form -@var{width}x@var{height}, or the name of a size abbreviation. The -default value is "320x240". +Specify the size of the sourced video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. The default value is +"320x240". + +This option is not available with the @code{haldclutsrc} filter. @item rate, r Specify the frame rate of the sourced video, as the number of frames @@ -6086,7 +8960,7 @@ If not specified, or the expressed duration is negative, the video is supposed to be generated forever. @item decimals, n -Set the number of decimals to show in the timestamp, only used in the +Set the number of decimals to show in the timestamp, only available in the @code{testsrc} source. The displayed timestamp value will correspond to the original @@ -6116,6 +8990,16 @@ the @code{geq} filter: nullsrc=s=256x256, geq=random(1)*255:128:128 @end example +@subsection Commands + +The @code{color} source supports the following commands: + +@table @option +@item c, color +Set the color of the created image. Accepts the same syntax of the +corresponding @option{color} option. +@end table + @c man end VIDEO SOURCES @chapter Video Sinks @@ -6129,12 +9013,12 @@ Buffer video frames, and make them available to the end of the filter graph. This sink is mainly intended for a programmatic use, in particular -through the interface defined in @file{libavfilter/buffersink.h}. +through the interface defined in @file{libavfilter/buffersink.h} +or the options system. -It does not require a string parameter in input, but you need to -specify a pointer to a list of supported pixel formats terminated by --1 in the opaque parameter provided to @code{avfilter_init_filter} -when initializing this sink. +It accepts a pointer to an AVBufferSinkContext structure, which +defines the incoming buffers' formats, to be passed as the opaque +parameter to @code{avfilter_init_filter} for initialization. @section nullsink @@ -6149,18 +9033,279 @@ tools. Below is a description of the currently available multimedia filters. -@section aperms, perms +@section avectorscope + +Convert input audio to a video output, representing the audio vector +scope. + +The filter is used to measure the difference between channels of stereo +audio stream. A monoaural signal, consisting of identical left and right +signal, results in straight vertical line. Any stereo separation is visible +as a deviation from this line, creating a Lissajous figure. +If the straight (or deviation from it) but horizontal line appears this +indicates that the left and right channels are out of phase. + +The filter accepts the following options: + +@table @option +@item mode, m +Set the vectorscope mode. + +Available values are: +@table @samp +@item lissajous +Lissajous rotated by 45 degrees. + +@item lissajous_xy +Same as above but not rotated. +@end table + +Default value is @samp{lissajous}. + +@item size, s +Set the video size for the output. For the syntax of this option, check the "Video size" +section in the ffmpeg-utils manual. Default value is @code{400x400}. + +@item rate, r +Set the output frame rate. Default value is @code{25}. + +@item rc +@item gc +@item bc +Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}. +Allowed range is @code{[0, 255]}. + +@item rf +@item gf +@item bf +Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}. +Allowed range is @code{[0, 255]}. + +@item zoom +Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}. +@end table + +@subsection Examples + +@itemize +@item +Complete example using @command{ffplay}: +@example +ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; + [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' +@end example +@end itemize + +@section concat + +Concatenate audio and video streams, joining them together one after the +other. + +The filter works on segments of synchronized video and audio streams. All +segments must have the same number of streams of each type, and that will +also be the number of streams at output. + +The filter accepts the following options: + +@table @option + +@item n +Set the number of segments. Default is 2. + +@item v +Set the number of output video streams, that is also the number of video +streams in each segment. Default is 1. + +@item a +Set the number of output audio streams, that is also the number of video +streams in each segment. Default is 0. + +@item unsafe +Activate unsafe mode: do not fail if segments have a different format. + +@end table + +The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then +@var{a} audio outputs. + +There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first +segment, in the same order as the outputs, then the inputs for the second +segment, etc. + +Related streams do not always have exactly the same duration, for various +reasons including codec frame size or sloppy authoring. For that reason, +related synchronized streams (e.g. a video and its audio track) should be +concatenated at once. The concat filter will use the duration of the longest +stream in each segment (except the last one), and if necessary pad shorter +audio streams with silence. + +For this filter to work correctly, all segments must start at timestamp 0. + +All corresponding streams must have the same parameters in all segments; the +filtering system will automatically select a common pixel format for video +streams, and a common sample format, sample rate and channel layout for +audio streams, but other settings, such as resolution, must be converted +explicitly by the user. + +Different frame rates are acceptable but will result in variable frame rate +at output; be sure to configure the output file to handle it. + +@subsection Examples + +@itemize +@item +Concatenate an opening, an episode and an ending, all in bilingual version +(video in stream 0, audio in streams 1 and 2): +@example +ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ + '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] + concat=n=3:v=1:a=2 [v] [a1] [a2]' \ + -map '[v]' -map '[a1]' -map '[a2]' output.mkv +@end example + +@item +Concatenate two parts, handling audio and video separately, using the +(a)movie sources, and adjusting the resolution: +@example +movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; +movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; +[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] +@end example +Note that a desync will happen at the stitch if the audio and video streams +do not have exactly the same duration in the first file. + +@end itemize + +@section ebur128 + +EBU R128 scanner filter. This filter takes an audio stream as input and outputs +it unchanged. By default, it logs a message at a frequency of 10Hz with the +Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), +Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). + +The filter also has a video output (see the @var{video} option) with a real +time graph to observe the loudness evolution. The graphic contains the logged +message mentioned above, so it is not printed anymore when this option is set, +unless the verbose logging is set. The main graphing area contains the +short-term loudness (3 seconds of analysis), and the gauge on the right is for +the momentary loudness (400 milliseconds). + +More information about the Loudness Recommendation EBU R128 on +@url{http://tech.ebu.ch/loudness}. + +The filter accepts the following options: + +@table @option + +@item video +Activate the video output. The audio stream is passed unchanged whether this +option is set or no. The video stream will be the first output stream if +activated. Default is @code{0}. + +@item size +Set the video size. This option is for video only. For the syntax of this +option, check the "Video size" section in the ffmpeg-utils manual. Default +and minimum resolution is @code{640x480}. + +@item meter +Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and +@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any +other integer value between this range is allowed. + +@item metadata +Set metadata injection. If set to @code{1}, the audio input will be segmented +into 100ms output frames, each of them containing various loudness information +in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. + +Default is @code{0}. + +@item framelog +Force the frame logging level. + +Available values are: +@table @samp +@item info +information logging level +@item verbose +verbose logging level +@end table + +By default, the logging level is set to @var{info}. If the @option{video} or +the @option{metadata} options are set, it switches to @var{verbose}. +@end table + +@subsection Examples + +@itemize +@item +Real-time graph using @command{ffplay}, with a EBU scale meter +18: +@example +ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" +@end example + +@item +Run an analysis with @command{ffmpeg}: +@example +ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - +@end example +@end itemize + +@section interleave, ainterleave + +Temporally interleave frames from several inputs. + +@code{interleave} works with video inputs, @code{ainterleave} with audio. + +These filters read frames from several inputs and send the oldest +queued frame to the output. + +Input streams must have a well defined, monotonically increasing frame +timestamp values. + +In order to submit one frame to output, these filters need to enqueue +at least one frame for each input, so they cannot work in case one +input is not yet terminated and will not receive incoming frames. + +For example consider the case when one input is a @code{select} filter +which always drop input frames. The @code{interleave} filter will keep +reading from that input, but it will never be able to send new frames +to output until the input will send an end-of-stream signal. + +Also, depending on inputs synchronization, the filters will drop +frames in case one input receives more frames than the other ones, and +the queue is already filled. + +These filters accept the following options: + +@table @option +@item nb_inputs, n +Set the number of different inputs, it is 2 by default. +@end table + +@subsection Examples + +@itemize +@item +Interleave frames belonging to different streams using @command{ffmpeg}: +@example +ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi +@end example + +@item +Add flickering blur effect: +@example +select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave +@end example +@end itemize + +@section perms, aperms Set read/write permissions for the output frames. These filters are mainly aimed at developers to test direct path in the following filter in the filtergraph. -The filters accept parameters as a list of @var{key}=@var{value} pairs, -separated by ":". If the key of the first options is omitted, the argument is -assumed to be the @var{mode}. - -A description of the accepted parameters follows. +The filters accept the following options: @table @option @item mode @@ -6179,6 +9324,12 @@ Make the frame read-only if writable, and writable if read-only. @item random Set each output frame read-only or writable randomly. @end table + +@item seed +Set the seed for the @var{random} mode, must be an integer included between +@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to +@code{-1}, the filter will try to use a good random seed on a best effort +basis. @end table Note: in case of auto-inserted filter between the permission filter and the @@ -6186,17 +9337,30 @@ following one, the permission might not be received as expected in that following filter. Inserting a @ref{format} or @ref{aformat} filter before the perms/aperms filter can avoid this problem. -@section aselect, select +@section select, aselect + Select frames to pass in output. -These filters accept a single option @option{expr} or @option{e} -specifying the select expression, which can be specified either by -specyfing @code{expr=VALUE} or specifying the expression -alone. +This filter accepts the following options: + +@table @option + +@item expr, e +Set expression, which is evaluated for each input frame. + +If the expression is evaluated to zero, the frame is discarded. -The select expression is evaluated for each input frame. If the -evaluation result is a non-zero value, the frame is selected and -passed to the output, otherwise it is discarded. +If the evaluation result is negative or NaN, the frame is sent to the +first output; otherwise it is sent to the output with index +@code{ceil(val)-1}, assuming that the input index starts from 0. + +For example a value of @code{1.2} corresponds to the output with index +@code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. + +@item outputs, n +Set the number of outputs. The output to which to send the selected +frame is based on the result of the evaluation. Default value is 1. +@end table The expression can contain the following constants: @@ -6320,13 +9484,13 @@ select='not(mod(n\,100))' @item Select only frames contained in the 10-20 time interval: @example -select='gte(t\,10)*lte(t\,20)' +select=between(t\,10\,20) @end example @item Select only I frames contained in the 10-20 time interval: @example -select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)' +select=between(t\,10\,20)*eq(pict_type\,I) @end example @item @@ -6349,17 +9513,23 @@ ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 p Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane choice. + +@item +Send even and odd frames to separate outputs, and compose them: +@example +select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h +@end example @end itemize -@section asendcmd, sendcmd +@section sendcmd, asendcmd Send commands to filters in the filtergraph. These filters read commands to be sent to other filters in the filtergraph. -@code{asendcmd} must be inserted between two audio filters, -@code{sendcmd} must be inserted between two video filters, but apart +@code{sendcmd} must be inserted between two video filters, +@code{asendcmd} must be inserted between two audio filters, but apart from that they act the same way. The specification of commands can be provided in the filter arguments @@ -6466,13 +9636,13 @@ Specify a list of drawtext and hue commands in a file. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; # desaturate the image in the interval 15-20 -15.0-20.0 [enter] hue reinit s=0, +15.0-20.0 [enter] hue s 0, [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', - [leave] hue reinit s=1, + [leave] hue s 1, [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; # apply an exponential saturation fade-out effect, starting from time 25 -25 [enter] hue s=exp(t-25) +25 [enter] hue s exp(25-t) @end example A filtergraph allowing to read and process the above command list @@ -6483,14 +9653,23 @@ sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue @end itemize @anchor{setpts} -@section asetpts, setpts +@section setpts, asetpts Change the PTS (presentation timestamp) of the input frames. -@code{asetpts} works on audio frames, @code{setpts} on video frames. +@code{setpts} works on video frames, @code{asetpts} on audio frames. -Accept in input an expression evaluated through the eval API, which -can contain the following constants: +This filter accepts the following options: + +@table @option + +@item expr +The expression which is evaluated for each frame to construct its timestamp. + +@end table + +The expression is evaluated through the eval API and can contain the following +constants: @table @option @item FRAME_RATE @@ -6500,16 +9679,17 @@ frame rate, only defined for constant frame-rate video the presentation timestamp in input @item N -the count of the input frame, starting from 0. +the count of the input frame for video or the number of consumed samples, +not including the current frame for audio, starting from 0. @item NB_CONSUMED_SAMPLES the number of consumed samples, not including the current frame (only audio) -@item NB_SAMPLES +@item NB_SAMPLES, S the number of samples in the current frame (only audio) -@item SAMPLE_RATE +@item SAMPLE_RATE, SR audio sample rate @item STARTPTS @@ -6524,9 +9704,6 @@ tell if the current frame is interlaced @item T the time in seconds of the current frame -@item TB -the time base - @item POS original position in the file of the frame, or undefined if undefined for the current frame @@ -6549,6 +9726,10 @@ instead. @item RTCSTART wallclock (RTC) time at the start of the movie in microseconds + +@item TB +timebase of the input timestamps + @end table @subsection Examples @@ -6595,79 +9776,13 @@ Generate timestamps from a "live source" and rebase onto the current timebase: @example setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' @end example -@end itemize -@section ebur128 - -EBU R128 scanner filter. This filter takes an audio stream as input and outputs -it unchanged. By default, it logs a message at a frequency of 10Hz with the -Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), -Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). - -The filter also has a video output (see the @var{video} option) with a real -time graph to observe the loudness evolution. The graphic contains the logged -message mentioned above, so it is not printed anymore when this option is set, -unless the verbose logging is set. The main graphing area contains the -short-term loudness (3 seconds of analysis), and the gauge on the right is for -the momentary loudness (400 milliseconds). - -More information about the Loudness Recommendation EBU R128 on -@url{http://tech.ebu.ch/loudness}. - -The filter accepts the following named parameters: - -@table @option - -@item video -Activate the video output. The audio stream is passed unchanged whether this -option is set or no. The video stream will be the first output stream if -activated. Default is @code{0}. - -@item size -Set the video size. This option is for video only. Default and minimum -resolution is @code{640x480}. - -@item meter -Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and -@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any -other integer value between this range is allowed. - -@item metadata -Set metadata injection. If set to @code{1}, the audio input will be segmented -into 100ms output frames, each of them containing various loudness information -in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. - -Default is @code{0}. - -@item framelog -Force the frame logging level. - -Available values are: -@table @samp -@item info -information logging level -@item verbose -verbose logging level -@end table - -By default, the logging level is set to @var{info}. If the @option{video} or -the @option{metadata} options are set, it switches to @var{verbose}. -@end table - -@subsection Examples - -@itemize @item -Real-time graph using @command{ffplay}, with a EBU scale meter +18: +Generate timestamps by counting samples: @example -ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" +asetpts=N/SR/TB @end example -@item -Run an analysis with @command{ffmpeg}: -@example -ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - -@end example @end itemize @section settb, asettb @@ -6675,9 +9790,14 @@ ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - Set the timebase to use for the output frames timestamps. It is mainly useful for testing timebase configuration. -This filter accepts a single option @option{tb}, which can be -specified either by setting @option{tb}=@var{VALUE} or setting the -value alone. +This filter accepts the following options: + +@table @option + +@item expr, tb +The expression which is evaluated into the output timebase. + +@end table The value for @option{tb} is an arithmetic expression representing a rational. The expression can contain the constants "AVTB" (the default @@ -6690,13 +9810,13 @@ audio only). Default value is "intb". @item Set the timebase to 1/25: @example -settb=1/25 +settb=expr=1/25 @end example @item Set the timebase to 1/10: @example -settb=0.1 +settb=expr=0.1 @end example @item @@ -6718,94 +9838,18 @@ settb=AVTB @end example @end itemize -@section concat - -Concatenate audio and video streams, joining them together one after the -other. - -The filter works on segments of synchronized video and audio streams. All -segments must have the same number of streams of each type, and that will -also be the number of streams at output. - -The filter accepts the following named parameters: -@table @option - -@item n -Set the number of segments. Default is 2. - -@item v -Set the number of output video streams, that is also the number of video -streams in each segment. Default is 1. - -@item a -Set the number of output audio streams, that is also the number of video -streams in each segment. Default is 0. - -@item unsafe -Activate unsafe mode: do not fail if segments have a different format. - -@end table - -The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then -@var{a} audio outputs. - -There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first -segment, in the same order as the outputs, then the inputs for the second -segment, etc. - -Related streams do not always have exactly the same duration, for various -reasons including codec frame size or sloppy authoring. For that reason, -related synchronized streams (e.g. a video and its audio track) should be -concatenated at once. The concat filter will use the duration of the longest -stream in each segment (except the last one), and if necessary pad shorter -audio streams with silence. - -For this filter to work correctly, all segments must start at timestamp 0. - -All corresponding streams must have the same parameters in all segments; the -filtering system will automatically select a common pixel format for video -streams, and a common sample format, sample rate and channel layout for -audio streams, but other settings, such as resolution, must be converted -explicitly by the user. - -Different frame rates are acceptable but will result in variable frame rate -at output; be sure to configure the output file to handle it. - -@subsection Examples - -@itemize -@item -Concatenate an opening, an episode and an ending, all in bilingual version -(video in stream 0, audio in streams 1 and 2): -@example -ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ - '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] - concat=n=3:v=1:a=2 [v] [a1] [a2]' \ - -map '[v]' -map '[a1]' -map '[a2]' output.mkv -@end example - -@item -Concatenate two parts, handling audio and video separately, using the -(a)movie sources, and adjusting the resolution: -@example -movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; -movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; -[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] -@end example -Note that a desync will happen at the stitch if the audio and video streams -do not have exactly the same duration in the first file. - -@end itemize - @section showspectrum Convert input audio to a video output, representing the audio frequency spectrum. -The filter accepts the following named parameters: +The filter accepts the following options: + @table @option @item size, s -Specify the video size for the output. Default value is @code{640x512}. +Specify the video size for the output. For the syntax of this option, check +the "Video size" section in the ffmpeg-utils manual. Default value is +@code{640x512}. @item slide Specify if the spectrum should slide along the window. Default value is @@ -6859,6 +9903,23 @@ Set saturation modifier for displayed colors. Negative values provide alternative color scheme. @code{0} is no saturation at all. Saturation must be in [-10.0, 10.0] range. Default value is @code{1}. + +@item win_func +Set window function. + +It accepts the following values: +@table @samp +@item none +No samples pre-processing (do not expect this to be faster) +@item hann +Hann window +@item hamming +Hamming window +@item blackman +Blackman window +@end table + +Default value is @code{hann}. @end table The usage is very similar to the showwaves filter; see the examples in that @@ -6885,8 +9946,14 @@ ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; Convert input audio to a video output, representing the samples waves. -The filter accepts the following named parameters: +The filter accepts the following options: + @table @option +@item size, s +Specify the video size for the output. For the syntax of this option, check +the "Video size" section in the ffmpeg-utils manual. Default value +is "600x240". + @item mode Set display mode. @@ -6911,8 +9978,6 @@ is not explicitly specified. Set the (approximate) output frame rate. This is done by setting the option @var{n}. Default value is "25". -@item size, s -Specify the video size for the output. Default value is "600x240". @end table @subsection Examples @@ -6927,12 +9992,121 @@ amovie=a.mp3,asplit[out0],showwaves[out1] @item Create a synthetic signal and show it with showwaves, forcing a -framerate of 30 frames per second: +frame rate of 30 frames per second: @example aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] @end example @end itemize +@section split, asplit + +Split input into several identical outputs. + +@code{asplit} works with audio input, @code{split} with video. + +The filter accepts a single parameter which specifies the number of outputs. If +unspecified, it defaults to 2. + +@subsection Examples + +@itemize +@item +Create two separate outputs from the same input: +@example +[in] split [out0][out1] +@end example + +@item +To create 3 or more outputs, you need to specify the number of +outputs, like in: +@example +[in] asplit=3 [out0][out1][out2] +@end example + +@item +Create two separate outputs from the same input, one cropped and +one padded: +@example +[in] split [splitout1][splitout2]; +[splitout1] crop=100:100:0:0 [cropout]; +[splitout2] pad=200:200:100:100 [padout]; +@end example + +@item +Create 5 copies of the input audio with @command{ffmpeg}: +@example +ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT +@end example +@end itemize + +@section zmq, azmq + +Receive commands sent through a libzmq client, and forward them to +filters in the filtergraph. + +@code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} +must be inserted between two video filters, @code{azmq} between two +audio filters. + +To enable these filters you need to install the libzmq library and +headers and configure FFmpeg with @code{--enable-libzmq}. + +For more information about libzmq see: +@url{http://www.zeromq.org/} + +The @code{zmq} and @code{azmq} filters work as a libzmq server, which +receives messages sent through a network interface defined by the +@option{bind_address} option. + +The received message must be in the form: +@example +@var{TARGET} @var{COMMAND} [@var{ARG}] +@end example + +@var{TARGET} specifies the target of the command, usually the name of +the filter class or a specific filter instance name. + +@var{COMMAND} specifies the name of the command for the target filter. + +@var{ARG} is optional and specifies the optional argument list for the +given @var{COMMAND}. + +Upon reception, the message is processed and the corresponding command +is injected into the filtergraph. Depending on the result, the filter +will send a reply to the client, adopting the format: +@example +@var{ERROR_CODE} @var{ERROR_REASON} +@var{MESSAGE} +@end example + +@var{MESSAGE} is optional. + +@subsection Examples + +Look at @file{tools/zmqsend} for an example of a zmq client which can +be used to send commands processed by these filters. + +Consider the following filtergraph generated by @command{ffplay} +@example +ffplay -dumpgraph 1 -f lavfi " +color=s=100x100:c=red [l]; +color=s=100x100:c=blue [r]; +nullsrc=s=200x100, zmq [bg]; +[bg][l] overlay [bg+l]; +[bg+l][r] overlay=x=100 " +@end example + +To change the color of the left side of the video, the following +command can be used: +@example +echo Parsed_color_0 c yellow | tools/zmqsend +@end example + +To change the right side: +@example +echo Parsed_color_1 c pink | tools/zmqsend +@end example + @c man end MULTIMEDIA FILTERS @chapter Multimedia Sources @@ -6950,15 +10124,12 @@ stream by default. Read audio and/or video stream(s) from a movie container. -It accepts the syntax: @var{movie_name}[:@var{options}] where -@var{movie_name} is the name of the resource to read (not necessarily -a file but also a device or a stream accessed through some protocol), -and @var{options} is an optional sequence of @var{key}=@var{value} -pairs, separated by ":". - -The description of the accepted options follows. +This filter accepts the following options: @table @option +@item filename +The name of the resource to read (not necessarily a file but also a device or a +stream accessed through some protocol). @item format_name, f Specifies the format assumed for the movie to read, and can be either @@ -7010,16 +10181,18 @@ movie --> scale--> deltapts1 -------+ Skip 3.2 seconds from the start of the avi file in.avi, and overlay it on top of the input labelled as "in": @example -movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie]; -[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out] +movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; +[in] setpts=PTS-STARTPTS [main]; +[main][over] overlay=16:16 [out] @end example @item Read from a video4linux2 device, and overlay it on top of the input labelled as "in": @example -movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie]; -[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out] +movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; +[in] setpts=PTS-STARTPTS [main]; +[main][over] overlay=16:16 [out] @end example @item diff --git a/ffmpeg/doc/general.texi b/ffmpeg/doc/general.texi index 39b9360..0ac6455 100644 --- a/ffmpeg/doc/general.texi +++ b/ffmpeg/doc/general.texi @@ -24,7 +24,7 @@ instructions. To enable using OpenJPEG in FFmpeg, pass @code{--enable-libopenjp @file{./configure}. -@section OpenCORE and VisualOn libraries +@section OpenCORE, VisualOn, and Fraunhofer libraries Spun off Google Android sources, OpenCore, VisualOn and Fraunhofer libraries provide encoders for a number of audio codecs. @@ -32,9 +32,14 @@ libraries provide encoders for a number of audio codecs. @float NOTE OpenCORE and VisualOn libraries are under the Apache License 2.0 (see @url{http://www.apache.org/licenses/LICENSE-2.0} for details), which is -incompatible with the LGPL version 2.1 and GPL version 2. You have to +incompatible to the LGPL version 2.1 and GPL version 2. You have to upgrade FFmpeg's license to LGPL version 3 (or if you have enabled -GPL components, GPL version 3) to use it. +GPL components, GPL version 3) by passing @code{--enable-version3} to configure in +order to use it. + +The Fraunhofer AAC library is licensed under a license incompatible to the GPL +and is not known to be compatible to the LGPL. Therefore, you have to pass +@code{--enable-nonfree} to configure to use it. @end float @subsection OpenCORE AMR @@ -89,12 +94,20 @@ Then pass @code{--enable-libtwolame} to configure to enable it. @section libvpx -FFmpeg can make use of the libvpx library for VP8 encoding. +FFmpeg can make use of the libvpx library for VP8/VP9 encoding. Go to @url{http://www.webmproject.org/} and follow the instructions for installing the library. Then pass @code{--enable-libvpx} to configure to enable it. +@section libwavpack + +FFmpeg can make use of the libwavpack library for WavPack encoding. + +Go to @url{http://www.wavpack.com/} and follow the instructions for +installing the library. Then pass @code{--enable-libwavpack} to configure to +enable it. + @section x264 FFmpeg can make use of the x264 library for H.264 encoding. @@ -120,6 +133,20 @@ Go to @url{https://github.com/dekkers/libilbc} and follow the instructions for installing the library. Then pass @code{--enable-libilbc} to configure to enable it. +@section libzvbi + +libzvbi is a VBI decoding library which can be used by FFmpeg to decode DVB +teletext pages and DVB teletext subtitles. + +Go to @url{http://sourceforge.net/projects/zapping/} and follow the instructions for +installing the library. Then pass @code{--enable-libzvbi} to configure to +enable it. + +@float NOTE +libzvbi is licensed under the GNU General Public License Version 2 or later +(see @url{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html} for details), +you must upgrade FFmpeg's license to GPL in order to use it. +@end float @chapter Supported File Formats, Codecs or Features @@ -147,13 +174,15 @@ library: @tab Multimedia format used in game Heart Of Darkness. @item Apple HTTP Live Streaming @tab @tab X @item Artworx Data Format @tab @tab X +@item ADP @tab @tab X + @tab Audio format used on the Nintendo Gamecube. @item AFC @tab @tab X @tab Audio format used on the Nintendo Gamecube. @item ASF @tab X @tab X @item AST @tab X @tab X @tab Audio format used on the Nintendo Wii. @item AVI @tab X @tab X -@item AVISynth @tab @tab X +@item AviSynth @tab @tab X @item AVR @tab @tab X @tab Audio format used on Mac. @item AVS @tab @tab X @@ -220,6 +249,8 @@ library: @item GXF @tab X @tab X @tab General eXchange Format SMPTE 360M, used by Thomson Grass Valley playout servers. +@item HNM @tab @tab X + @tab Only version 4 supported, used in some games from Cryo Interactive @item iCEDraw File @tab @tab X @item ICO @tab X @tab X @tab Microsoft Windows ICO @@ -309,6 +340,7 @@ library: @item raw H.261 @tab X @tab X @item raw H.263 @tab X @tab X @item raw H.264 @tab X @tab X +@item raw HEVC @tab @tab X @item raw Ingenient MJPEG @tab @tab X @item raw MJPEG @tab X @tab X @item raw MLP @tab @tab X @@ -322,7 +354,7 @@ library: @item raw Shorten @tab @tab X @item raw TAK @tab @tab X @item raw TrueHD @tab X @tab X -@item raw VC-1 @tab @tab X +@item raw VC-1 @tab X @tab X @item raw PCM A-law @tab X @tab X @item raw PCM mu-law @tab X @tab X @item raw PCM signed 8 bit @tab X @tab X @@ -348,11 +380,13 @@ library: @tab File format used by RED Digital cameras, contains JPEG 2000 frames and PCM audio. @item RealMedia @tab X @tab X @item Redirector @tab @tab X +@item RedSpark @tab @tab X @item Renderware TeXture Dictionary @tab @tab X @item RL2 @tab @tab X @tab Audio and video format used in some games by Entertainment Software Partners. @item RPL/ARMovie @tab @tab X @item Lego Mindstorms RSO @tab X @tab X +@item RSD @tab @tab X @item RTMP @tab X @tab X @tab Output is performed by publishing stream to RTMP server @item RTP @tab X @tab X @@ -418,7 +452,6 @@ following image formats are supported: @item .Y.U.V @tab X @tab X @tab one raw file per component @item animated GIF @tab X @tab X - @tab Only uncompressed GIFs are generated. @item BMP @tab X @tab X @tab Microsoft BMP image @item PIX @tab @tab X @@ -458,6 +491,8 @@ following image formats are supported: @tab YUV, JPEG and some extension is not supported yet. @item Truevision Targa @tab X @tab X @tab Targa (.TGA) image format +@item WebP @tab E @tab X + @tab WebP image format, encoding supported through external library libwebp @item XBM @tab X @tab X @tab X BitMap image format @item XFace @tab X @tab X @@ -485,6 +520,7 @@ following image formats are supported: @item AMV Video @tab X @tab X @tab Used in Chinese MP3 players. @item ANSI/ASCII art @tab @tab X +@item Apple Intermediate Codec @tab @tab X @item Apple MJPEG-B @tab @tab X @item Apple ProRes @tab X @tab X @item Apple QuickDraw @tab @tab X @@ -567,12 +603,15 @@ following image formats are supported: @tab Sorenson H.263 used in Flash @item Forward Uncompressed @tab @tab X @item Fraps @tab @tab X +@item Go2Webinar @tab @tab X + @tab fourcc: G2M4 @item H.261 @tab X @tab X @item H.263 / H.263-1996 @tab X @tab X @item H.263+ / H.263-1998 / H.263 version 2 @tab X @tab X @item H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 @tab E @tab X @tab encoding supported through external library libx264 -@item H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (VDPAU acceleration) @tab E @tab X +@item HEVC @tab @tab X +@item HNM version 4 @tab @tab X @item HuffYUV @tab X @tab X @item HuffYUV FFmpeg variant @tab X @tab X @item IBM Ultimotion @tab @tab X @@ -624,8 +663,6 @@ following image formats are supported: @item Mobotix MxPEG video @tab @tab X @item Motion Pixels video @tab @tab X @item MPEG-1 video @tab X @tab X -@item MPEG-1/2 video XvMC (X-Video Motion Compensation) @tab @tab X -@item MPEG-1/2 video (VDPAU acceleration) @tab @tab X @item MPEG-2 video @tab X @tab X @item MPEG-4 part 2 @tab X @tab X @tab libxvidcore can be used alternatively for encoding. @@ -643,6 +680,8 @@ following image formats are supported: @tab fourcc: VP60,VP61,VP62 @item VP8 @tab E @tab X @tab fourcc: VP80, encoding supported through external library libvpx +@item VP9 @tab E @tab X + @tab encoding supported through external library libvpx @item Pinnacle TARGA CineWave YUV16 @tab @tab X @tab fourcc: Y216 @item Prores @tab @tab X @@ -769,9 +808,11 @@ following image formats are supported: @tab Used in some Sega Saturn console games. @item ADPCM IMA Duck DK4 @tab @tab X @tab Used in some Sega Saturn console games. +@item ADPCM IMA Radical @tab @tab X @item ADPCM Microsoft @tab X @tab X @item ADPCM MS IMA @tab X @tab X @item ADPCM Nintendo Gamecube AFC @tab @tab X +@item ADPCM Nintendo Gamecube DTK @tab @tab X @item ADPCM Nintendo Gamecube THP @tab @tab X @item ADPCM QT IMA @tab X @tab X @item ADPCM SEGA CRI ADX @tab X @tab X @@ -790,8 +831,8 @@ following image formats are supported: @item Amazing Studio PAF Audio @tab @tab X @item Apple lossless audio @tab X @tab X @tab QuickTime fourcc 'alac' -@item Atrac 1 @tab @tab X -@item Atrac 3 @tab @tab X +@item ATRAC1 @tab @tab X +@item ATRAC3 @tab @tab X @item Bink Audio @tab @tab X @tab Used in Bink and Smacker files in many games. @item CELT @tab @tab E @@ -831,7 +872,6 @@ following image formats are supported: @item MLP (Meridian Lossless Packing) @tab @tab X @tab Used in DVD-Audio discs. @item Monkey's Audio @tab @tab X - @tab Only versions 3.97-3.99 are supported. @item MP1 (MPEG audio layer 1) @tab @tab IX @item MP2 (MPEG audio layer 2) @tab IX @tab IX @tab libtwolame can be used alternatively for encoding. @@ -886,7 +926,7 @@ following image formats are supported: @item Sierra VMD audio @tab @tab X @tab Used in Sierra VMD files. @item Smacker audio @tab @tab X -@item SMPTE 302M AES3 audio @tab @tab X +@item SMPTE 302M AES3 audio @tab X @tab X @item Sonic @tab X @tab X @tab experimental codec @item Sonic lossless @tab X @tab X @@ -894,7 +934,7 @@ following image formats are supported: @item Speex @tab E @tab E @tab supported through external library libspeex @item TAK (Tom's lossless Audio Kompressor) @tab @tab X -@item True Audio (TTA) @tab @tab X +@item True Audio (TTA) @tab X @tab X @item TrueHD @tab @tab X @tab Used in HD-DVD and Blu-Ray discs. @item TwinVQ (VQF flavor) @tab @tab X @@ -902,7 +942,8 @@ following image formats are supported: @tab Used in LucasArts SMUSH animations. @item Vorbis @tab E @tab X @tab A native but very primitive encoder exists. -@item WavPack @tab @tab X +@item Voxware MetaSound @tab @tab X +@item WavPack @tab X @tab X @item Westwood Audio (SND1) @tab @tab X @item Windows Media Audio 1 @tab X @tab X @item Windows Media Audio 2 @tab X @tab X @@ -925,6 +966,7 @@ performance on systems without hardware floating point support). @item 3GPP Timed Text @tab @tab @tab X @tab X @item AQTitle @tab @tab X @tab @tab X @item DVB @tab X @tab X @tab X @tab X +@item DVB teletext @tab @tab X @tab @tab E @item DVD @tab X @tab X @tab X @tab X @item JACOsub @tab X @tab X @tab @tab X @item MicroDVD @tab X @tab X @tab @tab X @@ -941,12 +983,14 @@ performance on systems without hardware floating point support). @item TED Talks captions @tab @tab X @tab @tab X @item VobSub (IDX+SUB) @tab @tab X @tab @tab X @item VPlayer @tab @tab X @tab @tab X -@item WebVTT @tab @tab X @tab @tab X +@item WebVTT @tab X @tab X @tab @tab X @item XSUB @tab @tab @tab X @tab X @end multitable @code{X} means that the feature is supported. +@code{E} means that support is provided through an external library. + @section Network Protocols @multitable @columnfractions .4 .1 @@ -994,7 +1038,7 @@ performance on systems without hardware floating point support). @item OSS @tab X @tab X @item Pulseaudio @tab X @tab @item SDL @tab @tab X -@item Video4Linux2 @tab X @tab +@item Video4Linux2 @tab X @tab X @item VfW capture @tab X @tab @item X11 grabbing @tab X @tab @end multitable diff --git a/ffmpeg/doc/git-howto.txt b/ffmpeg/doc/git-howto.txt deleted file mode 100644 index 5ba72ee..0000000 --- a/ffmpeg/doc/git-howto.txt +++ /dev/null @@ -1,273 +0,0 @@ - -About Git write access: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before everything else, you should know how to use GIT properly. -Luckily Git comes with excellent documentation. - - git --help - man git - -shows you the available subcommands, - - git <command> --help - man git-<command> - -shows information about the subcommand <command>. - -The most comprehensive manual is the website Git Reference - -http://gitref.org/ - -For more information about the Git project, visit - -http://git-scm.com/ - -Consult these resources whenever you have problems, they are quite exhaustive. - -You do not need a special username or password. -All you need is to provide a ssh public key to the Git server admin. - -What follows now is a basic introduction to Git and some FFmpeg-specific -guidelines. Read it at least once, if you are granted commit privileges to the -FFmpeg project you are expected to be familiar with these rules. - - - -I. BASICS: -========== - -0. Get GIT: - - Most distributions have a git package, if not - You can get git from http://git-scm.com/ - - -1. Cloning the source tree: - - git clone git://source.ffmpeg.org/ffmpeg <target> - - This will put the FFmpeg sources into the directory <target>. - - git clone git@source.ffmpeg.org:ffmpeg <target> - - This will put the FFmpeg sources into the directory <target> and let - you push back your changes to the remote repository. - - -2. Updating the source tree to the latest revision: - - git pull (--ff-only) - - pulls in the latest changes from the tracked branch. The tracked branch - can be remote. By default the master branch tracks the branch master in - the remote origin. - Caveat: Since merge commits are forbidden at least for the initial - months of git --ff-only or --rebase (see below) are recommended. - --ff-only will fail and not create merge commits if your branch - has diverged (has a different history) from the tracked branch. - -2.a Rebasing your local branches: - - git pull --rebase - - fetches the changes from the main repository and replays your local commits - over it. This is required to keep all your local changes at the top of - FFmpeg's master tree. The master tree will reject pushes with merge commits. - - -3. Adding/removing files/directories: - - git add [-A] <filename/dirname> - git rm [-r] <filename/dirname> - - GIT needs to get notified of all changes you make to your working - directory that makes files appear or disappear. - Line moves across files are automatically tracked. - - -4. Showing modifications: - - git diff <filename(s)> - - will show all local modifications in your working directory as unified diff. - - -5. Inspecting the changelog: - - git log <filename(s)> - - You may also use the graphical tools like gitview or gitk or the web - interface available at http://source.ffmpeg.org - -6. Checking source tree status: - - git status - - detects all the changes you made and lists what actions will be taken in case - of a commit (additions, modifications, deletions, etc.). - - -7. Committing: - - git diff --check - - to double check your changes before committing them to avoid trouble later - on. All experienced developers do this on each and every commit, no matter - how small. - Every one of them has been saved from looking like a fool by this many times. - It's very easy for stray debug output or cosmetic modifications to slip in, - please avoid problems through this extra level of scrutiny. - - For cosmetics-only commits you should get (almost) empty output from - - git diff -w -b <filename(s)> - - Also check the output of - - git status - - to make sure you don't have untracked files or deletions. - - git add [-i|-p|-A] <filenames/dirnames> - - Make sure you have told git your name and email address, e.g. by running - git config --global user.name "My Name" - git config --global user.email my@email.invalid - (--global to set the global configuration for all your git checkouts). - - Git will select the changes to the files for commit. Optionally you can use - the interactive or the patch mode to select hunk by hunk what should be - added to the commit. - - git commit - - Git will commit the selected changes to your current local branch. - - You will be prompted for a log message in an editor, which is either - set in your personal configuration file through - - git config core.editor - - or set by one of the following environment variables: - GIT_EDITOR, VISUAL or EDITOR. - - Log messages should be concise but descriptive. Explain why you made a change, - what you did will be obvious from the changes themselves most of the time. - Saying just "bug fix" or "10l" is bad. Remember that people of varying skill - levels look at and educate themselves while reading through your code. Don't - include filenames in log messages, Git provides that information. - - Possibly make the commit message have a terse, descriptive first line, an - empty line and then a full description. The first line will be used to name - the patch by git format-patch. - - -8. Renaming/moving/copying files or contents of files: - - Git automatically tracks such changes, making those normal commits. - - mv/cp path/file otherpath/otherfile - - git add [-A] . - - git commit - - Do not move, rename or copy files of which you are not the maintainer without - discussing it on the mailing list first! - -9. Reverting broken commits - - git revert <commit> - - git revert will generate a revert commit. This will not make the faulty - commit disappear from the history. - - git reset <commit> - - git reset will uncommit the changes till <commit> rewriting the current - branch history. - - git commit --amend - - allows to amend the last commit details quickly. - - git rebase -i origin/master - - will replay local commits over the main repository allowing to edit, - merge or remove some of them in the process. - - Note that the reset, commit --amend and rebase rewrite history, so you - should use them ONLY on your local or topic branches. - - The main repository will reject those changes. - -10. Preparing a patchset. - - git format-patch <commit> [-o directory] - - will generate a set of patches for each commit between <commit> and - current HEAD. E.g. - - git format-patch origin/master - - will generate patches for all commits on current branch which are not - present in upstream. - A useful shortcut is also - - git format-patch -n - - which will generate patches from last n commits. - By default the patches are created in the current directory. - -11. Sending patches for review - - git send-email <commit list|directory> - - will send the patches created by git format-patch or directly generates - them. All the email fields can be configured in the global/local - configuration or overridden by command line. - Note that this tool must often be installed separately (e.g. git-email - package on Debian-based distros). - -12. Pushing changes to remote trees - - git push - - Will push the changes to the default remote (origin). - Git will prevent you from pushing changes if the local and remote trees are - out of sync. Refer to 2 and 2.a to sync the local tree. - - git remote add <name> <url> - - Will add additional remote with a name reference, it is useful if you want - to push your local branch for review on a remote host. - - git push <remote> <refspec> - - Will push the changes to the remote repository. Omitting refspec makes git - push update all the remote branches matching the local ones. - -13. Finding a specific svn revision - - Since version 1.7.1 git supports ':/foo' syntax for specifying commits - based on a regular expression. see man gitrevisions - - git show :/'as revision 23456' - - will show the svn changeset r23456. With older git versions searching in - the git log output is the easiest option (especially if a pager with - search capabilities is used). - This commit can be checked out with - - git checkout -b svn_23456 :/'as revision 23456' - - or for git < 1.7.1 with - - git checkout -b svn_23456 $SHA1 - - where $SHA1 is the commit SHA1 from the 'git log' output. - - -Contact the project admins <root at ffmpeg dot org> if you have technical -problems with the GIT server. diff --git a/ffmpeg/doc/indevs.texi b/ffmpeg/doc/indevs.texi index cc5d666..72b1493 100644 --- a/ffmpeg/doc/indevs.texi +++ b/ffmpeg/doc/indevs.texi @@ -86,7 +86,7 @@ fail to open. Set the video size in the captured video. @item framerate -Set the framerate in the captured video. +Set the frame rate in the captured video. @item sample_rate Set the sample rate (in Hz) of the captured audio. @@ -485,87 +485,52 @@ For more information about OSS see: @section pulse -pulseaudio input device. +PulseAudio input device. -To enable this input device during configuration you need libpulse-simple -installed in your system. +To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}. The filename to provide to the input device is a source device or the string "default" -To list the pulse source devices and their properties you can invoke +To list the PulseAudio source devices and their properties you can invoke the command @command{pactl list sources}. -@example -ffmpeg -f pulse -i default /tmp/pulse.wav -@end example - -@subsection @var{server} AVOption - -The syntax is: -@example --server @var{server name} -@end example - -Connects to a specific server. +More information about PulseAudio can be found on @url{http://www.pulseaudio.org}. -@subsection @var{name} AVOption - -The syntax is: -@example --name @var{application name} -@end example - -Specify the application name pulse will use when showing active clients, -by default it is the LIBAVFORMAT_IDENT string - -@subsection @var{stream_name} AVOption - -The syntax is: -@example --stream_name @var{stream name} -@end example +@subsection Options +@table @option +@item server +Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. -Specify the stream name pulse will use when showing active streams, -by default it is "record" +@item name +Specify the application name PulseAudio will use when showing active clients, +by default it is the @code{LIBAVFORMAT_IDENT} string. -@subsection @var{sample_rate} AVOption - -The syntax is: -@example --sample_rate @var{samplerate} -@end example +@item stream_name +Specify the stream name PulseAudio will use when showing active streams, +by default it is "record". +@item sample_rate Specify the samplerate in Hz, by default 48kHz is used. -@subsection @var{channels} AVOption - -The syntax is: -@example --channels @var{N} -@end example - +@item channels Specify the channels in use, by default 2 (stereo) is set. -@subsection @var{frame_size} AVOption - -The syntax is: -@example --frame_size @var{bytes} -@end example - -Specify the number of byte per frame, by default it is set to 1024. +@item frame_size +Specify the number of bytes per frame, by default it is set to 1024. -@subsection @var{fragment_size} AVOption +@item fragment_size +Specify the minimal buffering fragment in PulseAudio, it will affect the +audio latency. By default it is unset. +@end table -The syntax is: +@subsection Examples +Record a stream from default device: @example --fragment_size @var{bytes} +ffmpeg -f pulse -i default /tmp/pulse.wav @end example -Specify the minimal buffering fragment in pulseaudio, it will affect the -audio latency. By default it is unset. - @section sndio sndio input device. @@ -590,8 +555,8 @@ Video4Linux2 input video device. "v4l2" can be used as alias for "video4linux2". If FFmpeg is built with v4l-utils support (by using the -@code{--enable-libv4l2} configure option), the device will always rely -on libv4l2. +@code{--enable-libv4l2} configure option), it is possible to use it with the +@code{-use_libv4l2} input device option. The name of the device to grab is a file device node, usually Linux systems tend to automatically create such nodes when the device @@ -600,7 +565,7 @@ kind @file{/dev/video@var{N}}, where @var{N} is a number associated to the device. Video4Linux2 devices usually support a limited set of -@var{width}x@var{height} sizes and framerates. You can check which are +@var{width}x@var{height} sizes and frame rates. You can check which are supported using @command{-list_formats all} for Video4Linux2 devices. Some devices, like TV cards, support one or more standards. It is possible to list all the supported standards using @command{-list_standards all}. @@ -623,7 +588,7 @@ ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0 @item Grab and record the input of a video4linux2 device, leave the -framerate and size as previously set: +frame rate and size as previously set: @example ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg @end example @@ -640,7 +605,8 @@ list of the supported standards, use the @option{list_standards} option. @item channel -Set the input channel number. Default to 0. +Set the input channel number. Default to -1, which means using the +previously selected channel. @item video_size Set the video frame size. The argument must be a string in the form @@ -655,7 +621,7 @@ This option allows to select the input format, when several are available. @item framerate -Set the preferred video framerate. +Set the preferred video frame rate. @item list_formats List available formats (supported pixel formats, codecs, and frame @@ -735,12 +701,12 @@ properties of your X11 display (e.g. grep for "name" or "dimensions"). For example to grab from @file{:0.0} using @command{ffmpeg}: @example -ffmpeg -f x11grab -r 25 -s cif -i :0.0 out.mpg +ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg @end example Grab at position @code{10,20}: @example -ffmpeg -f x11grab -r 25 -s cif -i :0.0+10,20 out.mpg +ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg @end example @subsection Options @@ -761,17 +727,17 @@ zero) to the edge of region. For example: @example -ffmpeg -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 out.mpg +ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg @end example To follow only when the mouse pointer reaches within 100 pixels to edge: @example -ffmpeg -f x11grab -follow_mouse 100 -r 25 -s cif -i :0.0 out.mpg +ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg @end example @item framerate Set the grabbing frame rate. Default value is @code{ntsc}, -corresponding to a framerate of @code{30000/1001}. +corresponding to a frame rate of @code{30000/1001}. @item show_region Show grabbed region on screen. @@ -782,12 +748,12 @@ know what is being grabbed if only a portion of the screen is grabbed. For example: @example -ffmpeg -f x11grab -show_region 1 -r 25 -s cif -i :0.0+10,20 out.mpg +ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg @end example With @var{follow_mouse}: @example -ffmpeg -f x11grab -follow_mouse centered -show_region 1 -r 25 -s cif -i :0.0 out.mpg +ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg @end example @item video_size diff --git a/ffmpeg/doc/issue_tracker.txt b/ffmpeg/doc/issue_tracker.txt index d487f66..33b3535 100644 --- a/ffmpeg/doc/issue_tracker.txt +++ b/ffmpeg/doc/issue_tracker.txt @@ -1,4 +1,4 @@ -FFmpeg's bug/patch/feature request tracker manual +FFmpeg's bug/feature request tracker manual ================================================= NOTE: This is a draft. @@ -11,7 +11,7 @@ existing issues can be done through a web interface. Issues can be different kinds of things we want to keep track of but that do not belong into the source tree itself. This includes -bug reports, patches, feature requests and license violations. We +bug reports, feature requests and license violations. We might add more items to this list in the future, so feel free to propose a new `type of issue' on the ffmpeg-devel mailing list if you feel it is worth tracking. @@ -24,10 +24,13 @@ a mail for every change to every issue. The subscription URL for the ffmpeg-trac list is: http(s)://ffmpeg.org/mailman/listinfo/ffmpeg-trac The URL of the webinterface of the tracker is: -http(s)://ffmpeg.org/trac/ffmpeg +http(s)://trac.ffmpeg.org Type: ----- +art + Artwork such as photos, music, banners, and logos. + bug / defect An error, flaw, mistake, failure, or fault in FFmpeg or libav* that prevents it from behaving as intended. @@ -41,20 +44,18 @@ feature request / enhancement license violation ticket to keep track of (L)GPL violations of ffmpeg by others -patch - A patch as generated by diff which conforms to the patch submission and - development policy. - +sponsoring request + Developer requests for hardware, software, specifications, money, + refunds, etc. Priority: --------- critical - Bugs and patches which deal with data loss and security issues. + Bugs about data loss and security issues. No feature request can be critical. important - Bugs which make FFmpeg unusable for a significant number of users, and - patches fixing them. + Bugs which make FFmpeg unusable for a significant number of users. Examples here might be completely broken MPEG-4 decoding or a build issue on Linux. While broken 4xm decoding or a broken OS/2 build would not be important, @@ -68,7 +69,7 @@ normal minor - Bugs and patches about things like spelling errors, "mp2" instead of + Bugs about things like spelling errors, "mp2" instead of "mp3" being shown and such. Feature requests about things few people want or which do not make a big difference. @@ -103,13 +104,13 @@ This state implicates that the bug either has been reproduced or that reproduction is not needed as the bug is already understood. -Type/Status/Substatus: +Type/Status: ---------- -*/new/new - Initial state of new bugs, patches and feature requests submitted by +*/new + Initial state of new bugs and feature requests submitted by users. -*/open/open +*/open Issues which have been briefly looked at and which did not look outright invalid. This implicates that no real more detailed state applies yet. Conversely, @@ -117,9 +118,7 @@ Type/Status/Substatus: looked at. */closed/duplicate - Bugs, patches or feature requests which are duplicates. - Note that patches dealing with the same thing in a different way are not - duplicates. + Bugs or feature requests which are duplicates. Note, if you mark something as duplicate, do not forget setting the superseder so bug reports are properly linked. @@ -134,7 +133,7 @@ Type/Status/Substatus: bug/closed/fixed Bugs which have to the best of our knowledge been fixed. -bug/closed/wont_fix +bug/closed/wontfix Bugs which we will not fix. Possible reasons include legality, high complexity for the sake of supporting obscure corner cases, speed loss for similarly esoteric purposes, et cetera. @@ -148,33 +147,15 @@ bug/closed/works_for_me reproduction failed - that is the code seems to work correctly to the best of our knowledge. -patch/open/approved - Patches which have been reviewed and approved by a developer. - Such patches can be applied anytime by any other developer after some - reasonable testing (compile + regression tests + does the patch do - what the author claimed). - -patch/open/needs_changes - Patches which have been reviewed and need changes to be accepted. - -patch/closed/applied - Patches which have been applied. - -patch/closed/rejected - Patches which have been rejected. - -feature_request/closed/implemented +feature_request/closed/fixed Feature requests which have been implemented. -feature_request/closed/wont_implement +feature_request/closed/wontfix Feature requests which will not be implemented. The reasons here could be legal, philosophical or others. -Note, please do not use type-status-substatus combinations other than the -above without asking on ffmpeg-dev first! - Note2, if you provide the requested info do not forget to remove the -needs_more_info substatus. +needs_more_info resolution. Component: ---------- diff --git a/ffmpeg/doc/libavutil.texi b/ffmpeg/doc/libavutil.texi index 50b0d0e..5ec7e84 100644 --- a/ffmpeg/doc/libavutil.texi +++ b/ffmpeg/doc/libavutil.texi @@ -16,7 +16,25 @@ The libavutil library is a utility library to aid portable multimedia programming. It contains safe portable string functions, random number generators, data structures, additional mathematics functions, cryptography and multimedia related functionality (like -enumerations for pixel and sample formats). +enumerations for pixel and sample formats). It is not a library for +code needed by both libavcodec and libavformat. + +The goals for this library is to be: + +@table @strong +@item Modular +It should have few interdependencies and the possibility of disabling individual +parts during @command{./configure}. + +@item Small +Both sources and objects should be small. + +@item Efficient +It should have low CPU and memory usage. + +@item Useful +It should avoid useless features that almost no one needs. +@end table @c man end DESCRIPTION diff --git a/ffmpeg/doc/libswresample.texi b/ffmpeg/doc/libswresample.texi index 1a5b01f..383e537 100644 --- a/ffmpeg/doc/libswresample.texi +++ b/ffmpeg/doc/libswresample.texi @@ -20,7 +20,7 @@ Specifically, this library performs the following conversions: @itemize @item @emph{Resampling}: is the process of changing the audio rate, for -example from an high sample rate of 44100Hz to 8000Hz. Audio +example from a 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. diff --git a/ffmpeg/doc/metadata.texi b/ffmpeg/doc/metadata.texi index 2a28575..b7fc789 100644 --- a/ffmpeg/doc/metadata.texi +++ b/ffmpeg/doc/metadata.texi @@ -65,4 +65,20 @@ title=chapter \#1 title=multi\ line @end example + +By using the ffmetadata muxer and demuxer it is possible to extract +metadata from an input file to an ffmetadata file, and then transcode +the file into an output file with the edited ffmetadata file. + +Extracting an ffmetadata file with @file{ffmpeg} goes as follows: +@example +ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE +@end example + +Reinserting edited metadata information from the FFMETADATAFILE file can +be done as: +@example +ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT +@end example + @c man end METADATA diff --git a/ffmpeg/doc/mips.txt b/ffmpeg/doc/mips.txt index 959b32c..8c6779f 100644 --- a/ffmpeg/doc/mips.txt +++ b/ffmpeg/doc/mips.txt @@ -47,8 +47,14 @@ Files that have MIPS copyright notice in them: * libavutil/mips/ float_dsp_mips.c libm_mips.h +* libavcodec/ + fft_fixed_32.c + fft_init_table.c + fft_table.h + mdct_fixed_32.c * libavcodec/mips/ aaccoder_mips.c + aacpsy_mips.h ac3dsp_mips.c acelp_filters_mips.c acelp_vectors_mips.c diff --git a/ffmpeg/doc/muxers.texi b/ffmpeg/doc/muxers.texi index 9d119c3..776ba2b 100644 --- a/ffmpeg/doc/muxers.texi +++ b/ffmpeg/doc/muxers.texi @@ -18,6 +18,23 @@ enabled muxers. A description of some of the currently available muxers follows. +@anchor{aiff} +@section aiff + +Audio Interchange File Format muxer. + +It accepts the following options: + +@table @option +@item write_id3v2 +Enable ID3v2 tags writing when set to 1. Default is 0 (disabled). + +@item id3v2_version +Select ID3v2 version to write. Currently only version 3 and 4 (aka. +ID3v2.3 and ID3v2.4) are supported. The default is version 4. + +@end table + @anchor{crc} @section crc @@ -129,6 +146,40 @@ ffmpeg -i INPUT -f framemd5 - See also the @ref{md5} muxer. +@anchor{gif} +@section gif + +Animated GIF muxer. + +It accepts the following options: + +@table @option +@item loop +Set the number of times to loop the output. Use @code{-1} for no loop, @code{0} +for looping indefinitely (default). + +@item final_delay +Force the delay (expressed in centiseconds) after the last frame. Each frame +ends with a delay until the next frame. The default is @code{-1}, which is a +special value to tell the muxer to re-use the previous delay. In case of a +loop, you might want to customize this value to mark a pause for instance. +@end table + +For example, to encode a gif looping 10 times, with a 5 seconds delay between +the loops: +@example +ffmpeg -i INPUT -loop 10 -final_delay 500 out.gif +@end example + +Note 1: if you wish to extract the frames in separate GIF files, you need to +force the @ref{image2} muxer: +@example +ffmpeg -i INPUT -c:v gif -f image2 "out%d.gif" +@end example + +Note 2: the GIF format has a very small time base: the delay between two frames +can not be smaller than one centi second. + @anchor{hls} @section hls @@ -243,11 +294,13 @@ ffmpeg -i in.avi -f image2 -frames:v 1 img.jpeg @table @option @item start_number @var{number} Start the sequence from @var{number}. Default value is 1. Must be a -positive number. +non-negative 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. -@item updatefirst 1|0 -If set to 1, update the first written image file again and -again. Default value is 0. @end table The image muxer supports the .Y.U.V image file format. This format is @@ -256,6 +309,90 @@ each of the YUV420P components. To read or write this image file format, specify the name of the '.Y' file. The muxer will automatically open the '.U' and '.V' files as required. +@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 +ffmpeg -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 + @anchor{md5} @section md5 @@ -283,7 +420,9 @@ ffmpeg -i INPUT -f md5 - See also the @ref{framemd5} muxer. -@section MOV/MP4/ISMV +@section mov/mp4/ismv + +MOV/MP4/ISMV (Smooth Streaming) muxer. The mov/mp4/ismv muxer supports fragmentation. Normally, a MOV/MP4 file has all the metadata about all packets stored in one location @@ -348,8 +487,8 @@ 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 moov atom on top of the file. This -operation can take a while, and will not work in various situations such +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. @item -movflags rtphint Add RTP hinting tracks to the output file. @@ -361,6 +500,42 @@ point on IIS with this muxer. Example: ffmpeg -re @var{<normal input/transcoding options>} -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. The legacy ID3v1 tag is +not written by default, but may be enabled with the @code{write_id3v1} option. + +For seekable output the muxer also writes 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 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 +ffmpeg -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3 +@end example + +To attach a picture to an mp3 file select both the audio and the picture stream +with @code{map}: +@example +ffmpeg -i input.mp3 -i cover.png -c copy -map 0 -map 1 +-metadata:s:v title="Album cover" -metadata:s:v comment="Cover (Front)" out.mp3 +@end example + @section mpegts MPEG transport stream muxer. @@ -383,6 +558,40 @@ Set the service_id (default 0x0001) also known as program in DVB. Set the first PID for PMT (default 0x1000, max 0x1f00). @item -mpegts_start_pid @var{number} Set the first PID for data packets (default 0x0100, max 0x0f00). +@item -mpegts_m2ts_mode @var{number} +Enable m2ts mode if set to 1. Default value is -1 which disables m2ts mode. +@item -muxrate @var{number} +Set muxrate. +@item -pes_payload_size @var{number} +Set minimum PES packet payload in bytes. +@item -mpegts_flags @var{flags} +Set flags (see below). +@item -mpegts_copyts @var{number} +Preserve original timestamps, if value is set to 1. Default value is -1, which +results in shifting timestamps so that they start from 0. +@item -tables_version @var{number} +Set PAT, PMT and SDT version (default 0, valid values are from 0 to 31, inclusively). +This option allows updating stream structure so that standard consumer may +detect the change. To do so, reopen output AVFormatContext (in case of API +usage) or restart ffmpeg instance, cyclically changing tables_version value: +@example +ffmpeg -i source1.ts -codec copy -f mpegts -tables_version 0 udp://1.1.1.1:1111 +ffmpeg -i source2.ts -codec copy -f mpegts -tables_version 1 udp://1.1.1.1:1111 +... +ffmpeg -i source3.ts -codec copy -f mpegts -tables_version 31 udp://1.1.1.1:1111 +ffmpeg -i source1.ts -codec copy -f mpegts -tables_version 0 udp://1.1.1.1:1111 +ffmpeg -i source2.ts -codec copy -f mpegts -tables_version 1 udp://1.1.1.1:1111 +... +@end example +@end table + +Option mpegts_flags may take a set of such flags: + +@table @option +@item resend_headers +Reemit PAT/PMT before writing the next packet. +@item latm +Use LATM packetization for AAC. @end table The recognized metadata settings in mpegts muxer are @code{service_provider} @@ -424,69 +633,21 @@ Alternatively you can write the command as: ffmpeg -benchmark -i INPUT -f null - @end example -@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 +@section ogg -@table @option +Ogg container muxer. -@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 +@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 -For example a 3D WebM clip can be created using the following command line: -@example -ffmpeg -i sample_left_right_clip.mpg -an -c:v libvpx -metadata stereo_mode=left_right -y stereo_clip.webm -@end example - @section segment, stream_segment, ssegment Basic stream segmenter. @@ -513,7 +674,9 @@ The segment muxer works best with a single constant frame rate video. Optionally it can generate a list of the created segments, by setting the option @var{segment_list}. The list type is specified by the -@var{segment_list_type} option. +@var{segment_list_type} option. The entry filenames in the segment +list are set by default to the basename of the corresponding segment +files. The segment muxer supports the following options: @@ -523,7 +686,7 @@ Set the reference stream, as specified by the string @var{specifier}. If @var{specifier} is set to @code{auto}, the reference is choosen automatically. Otherwise it must be a stream specifier (see the ``Stream specifiers'' chapter in the ffmpeg manual) which specifies the -reference stream. The default value is ``auto''. +reference stream. The default value is @code{auto}. @item segment_format @var{format} Override the inner container format, by default it is guessed by the filename @@ -537,7 +700,7 @@ listfile is generated. Set flags affecting the segment list generation. It currently supports the following flags: -@table @var +@table @samp @item cache Allow caching (only affects M3U8 list files). @@ -545,18 +708,20 @@ Allow caching (only affects M3U8 list files). Allow live-friendly file generation. @end table -Default value is @code{cache}. - @item segment_list_size @var{size} Update the list file so that it contains at most the last @var{size} segments. If 0 the list file will contain all the segments. Default value is 0. -@item segment_list type @var{type} +@item segment_list_entry_prefix @var{prefix} +Set @var{prefix} to prepend to the name of each entry filename. By +default no prefix is applied. + +@item segment_list_type @var{type} Specify the format for the segment list file. The following values are recognized: -@table @option +@table @samp @item flat Generate a flat list for the created segments, one segment per line. @@ -577,7 +742,7 @@ the segment start and end time expressed in seconds. A list file with the suffix @code{".csv"} or @code{".ext"} will auto-select this format. -@code{ext} is deprecated in favor or @code{csv}. +@samp{ext} is deprecated in favor or @samp{csv}. @item ffconcat Generate an ffconcat file for the created segments. The resulting file @@ -650,6 +815,10 @@ Reset timestamps at the begin of each segment, so that each segment will start with near-zero timestamps. It is meant to ease the playback of the generated segments. May not work with some combinations of muxers/codecs. It is set to @code{0} by default. + +@item initial_offset @var{offset} +Specify timestamp offset to apply to the output packet timestamps. The +argument must be a time duration specification, and defaults to 0. @end table @subsection Examples @@ -671,9 +840,9 @@ ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_ti @end example @item -As the example above, but use the @code{ffmpeg} @var{force_key_frames} +As the example above, but use the @command{ffmpeg} @option{force_key_frames} option to force key frames in the input at the specified location, together -with the segment option @var{segment_time_delta} to account for +with the segment option @option{segment_time_delta} to account for possible roundings operated when setting key frame times. @example ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -codec:v mpeg4 -codec:a pcm_s16le -map 0 \ @@ -684,7 +853,7 @@ required. @item Segment the input file by splitting the input file according to the -frame numbers sequence specified with the @var{segment_frames} option: +frame numbers sequence specified with the @option{segment_frames} option: @example ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_frames 100,200,300,500,800 out%03d.nut @end example @@ -705,57 +874,6 @@ ffmpeg -re -i in.mkv -codec copy -map 0 -f segment -segment_list playlist.m3u8 \ @end example @end itemize -@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. The legacy ID3v1 tag is -not written by default, but may be enabled with the @code{write_id3v1} option. - -For seekable output the muxer also writes 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 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 -ffmpeg -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3 -@end example - -To attach a picture to an mp3 file select both the audio and the picture stream -with @code{map}: -@example -ffmpeg -i input.mp3 -i cover.png -c copy -map 0 -map 1 --metadata:s:v title="Album cover" -metadata:s:v comment="Cover (Front)" out.mp3 -@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 tee The tee muxer can be used to write the same data to several files or any @@ -771,22 +889,70 @@ to feed the same packets to several muxers directly. The slave outputs are specified in the file name given to the muxer, separated by '|'. If any of the slave name contains the '|' separator, leading or trailing spaces or any special character, it must be -escaped (see the ``Quoting and escaping'' section in the ffmpeg-utils -manual). +escaped (see @ref{quoting_and_escaping,,the "Quoting and escaping" +section in the ffmpeg-utils(1) manual,ffmpeg-utils}). -Options can be specified for each slave by prepending them as a list of +Muxer options can be specified for each slave by prepending them as a list of @var{key}=@var{value} pairs separated by ':', between square brackets. If the options values contain a special character or the ':' separator, they must be escaped; note that this is a second level escaping. -Example: encode something and both archive it in a WebM file and stream it -as MPEG-TS over UDP (the streams need to be explicitly mapped): +The following special options are also recognized: +@table @option +@item f +Specify the format name. Useful if it cannot be guessed from the +output name suffix. + +@item bsfs[/@var{spec}] +Specify a list of bitstream filters to apply to the specified +output. + +It is possible to specify to which streams a given bitstream filter +applies, by appending a stream specifier to the option separated by +@code{/}. @var{spec} must be a stream specifier (see @ref{Format +stream specifiers}). If the stream specifier is not specified, the +bistream filters will be applied to all streams in the output. + +Several bitstream filters can be specified, separated by ",". + +@item select +Select the streams that should be mapped to the slave output, +specified by a stream specifier. If not specified, this defaults to +all the input streams. +@end table +Some examples follow. +@itemize +@item +Encode something and both archive it in a WebM file and stream it +as MPEG-TS over UDP (the streams need to be explicitly mapped): @example ffmpeg -i ... -c:v libx264 -c:a mp2 -f tee -map 0:v -map 0:a "archive-20121107.mkv|[f=mpegts]udp://10.0.1.255:1234/" @end example +@item +Use @command{ffmpeg} to encode the input, and send the output +to three different destinations. The @code{dump_extra} bitstream +filter is used to add extradata information to all the output video +keyframes packets, as requested by the MPEG-TS format. The select +option is applied to @file{out.aac} in order to make it contain only +audio packets. +@example +ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac -strict experimental + -f tee "[bsfs/v=dump_extra]out.ts|[movflags=+faststart]out.mp4|[select=a]out.aac" +@end example + +@item +As below, but select only stream @code{a:1} for the audio output. Note +that a second level escaping must be performed, as ":" is a special +character used to separate options. +@example +ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac -strict experimental + -f tee "[bsfs/v=dump_extra]out.ts|[movflags=+faststart]out.mp4|[select=\'a:1\']out.aac" +@end example +@end itemize + Note: some codecs may need different options depending on the output format; the auto-detection of this can not work with the tee muxer. The main example is the @option{global_header} flag. diff --git a/ffmpeg/doc/outdevs.texi b/ffmpeg/doc/outdevs.texi index 371d63a..a204f32 100644 --- a/ffmpeg/doc/outdevs.texi +++ b/ffmpeg/doc/outdevs.texi @@ -1,7 +1,7 @@ @chapter Output Devices @c man begin OUTPUT DEVICES -Output devices are configured elements in FFmpeg which allow to write +Output devices are configured elements in FFmpeg that can write multimedia data to an output device attached to your system. When you configure your FFmpeg build, all the supported output devices @@ -22,11 +22,27 @@ A description of the currently available output devices follows. ALSA (Advanced Linux Sound Architecture) output device. +@subsection Examples + +@itemize +@item +Play a file on default ALSA device: +@example +ffmpeg -i INPUT -f alsa default +@end example + +@item +Play a file on soundcard 1, audio device 7: +@example +ffmpeg -i INPUT -f alsa hw:1,7 +@end example +@end itemize + @section caca CACA output device. -This output devices allows to show a video stream in CACA window. +This output device allows to show a video stream in CACA window. Only one CACA window is allowed per application, so you can have only one instance of this output device in an application. @@ -104,15 +120,92 @@ ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_dither colors - @end example @end itemize +@section fbdev + +Linux framebuffer output device. + +The Linux framebuffer is a graphic hardware-independent abstraction +layer to show graphics on a computer monitor, typically on the +console. It is accessed through a file device node, usually +@file{/dev/fb0}. + +For more detailed information read the file +@file{Documentation/fb/framebuffer.txt} included in the Linux source tree. + +@subsection Options +@table @option + +@item xoffset +@item yoffset +Set x/y coordinate of top left corner. Default is 0. +@end table + +@subsection Examples +Play a file on framebuffer device @file{/dev/fb0}. +Required pixel format depends on current framebuffer settings. +@example +ffmpeg -re -i INPUT -vcodec rawvideo -pix_fmt bgra -f fbdev /dev/fb0 +@end example + +See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1). + @section oss OSS (Open Sound System) output device. +@section pulse + +PulseAudio output device. + +To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}. + +More information about PulseAudio can be found on @url{http://www.pulseaudio.org} + +@subsection Options +@table @option + +@item server +Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. + +@item name +Specify the application name PulseAudio will use when showing active clients, +by default it is the @code{LIBAVFORMAT_IDENT} string. + +@item stream_name +Specify the stream name PulseAudio will use when showing active streams, +by default it is set to the specified output name. + +@item device +Specify the device to use. Default device is used when not provided. +List of output devices can be obtained with command @command{pactl list sinks}. + +@item buffer_size +@item buffer_duration +Control the size and duration of the PulseAudio buffer. A small buffer +gives more control, but requires more frequent updates. + +@option{buffer_size} specifies size in bytes while +@option{buffer_duration} specifies duration in milliseconds. + +When both options are provided then the highest value is used +(duration is recalculated to bytes using stream parameters). If they +are set to 0 (which is default), the device will use the default +PulseAudio duration value. By default PulseAudio set buffer duration +to around 2 seconds. +@end table + +@subsection Examples +Play a file on default device on default server: +@example +ffmpeg -i INPUT -f pulse "stream name" +@end example + @section sdl SDL (Simple DirectMedia Layer) output device. -This output devices allows to show a video stream in an SDL +This output device allows to show a video stream in an SDL window. Only one SDL window is allowed per application, so you can have only one instance of this output device in an application. @@ -139,6 +232,20 @@ Set the SDL window size, can be a string of the form @var{width}x@var{height} or a video size abbreviation. If not specified it defaults to the size of the input video, downscaled according to the aspect ratio. + +@item window_fullscreen +Set fullscreen mode when non-zero value is provided. +Default value is zero. +@end table + +@subsection Interactive commands + +The window created by the device can be controlled through the +following interactive commands. + +@table @key +@item q, ESC +Quit the device immediately. @end table @subsection Examples @@ -153,4 +260,69 @@ ffmpeg -i INPUT -vcodec rawvideo -pix_fmt yuv420p -window_size qcif -f sdl "SDL sndio audio output device. +@section xv + +XV (XVideo) output device. + +This output device allows to show a video stream in a X Window System +window. + +@subsection Options + +@table @option +@item display_name +Specify the hardware display name, which determines the display and +communications domain to be used. + +The display name or DISPLAY environment variable can be a string in +the format @var{hostname}[:@var{number}[.@var{screen_number}]]. + +@var{hostname} specifies the name of the host machine on which the +display is physically attached. @var{number} specifies the number of +the display server on that host machine. @var{screen_number} specifies +the screen to be used on that server. + +If unspecified, it defaults to the value of the DISPLAY environment +variable. + +For example, @code{dual-headed:0.1} would specify screen 1 of display +0 on the machine named ``dual-headed''. + +Check the X11 specification for more detailed information about the +display name format. + +@item window_size +Set the created window size, can be a string of the form +@var{width}x@var{height} or a video size abbreviation. If not +specified it defaults to the size of the input video. + +@item window_x +@item window_y +Set the X and Y window offsets for the created window. They are both +set to 0 by default. The values may be ignored by the window manager. + +@item window_title +Set the window title, if not specified default to the filename +specified for the output device. +@end table + +For more information about XVideo see @url{http://www.x.org/}. + +@subsection Examples + +@itemize +@item +Decode, display and encode video input with @command{ffmpeg} at the +same time: +@example +ffmpeg -i INPUT OUTPUT -f xv display +@end example + +@item +Decode and display the input video to multiple X11 windows: +@example +ffmpeg -i INPUT -f xv normal -vf negate -f xv negated +@end example +@end itemize + @c man end OUTPUT DEVICES diff --git a/ffmpeg/doc/platform.texi b/ffmpeg/doc/platform.texi index bb8e6ca..934a3ae 100644 --- a/ffmpeg/doc/platform.texi +++ b/ffmpeg/doc/platform.texi @@ -106,44 +106,53 @@ libavformat) as DLLs. @end itemize -@section Microsoft Visual C++ +@section Microsoft Visual C++ or Intel C++ Compiler for Windows -FFmpeg can be built with MSVC using a C99-to-C89 conversion utility and -wrapper. +FFmpeg can be built with MSVC 2012 or earlier using a C99-to-C89 conversion utility +and wrapper, or with MSVC 2013 and ICL natively. You will need the following prerequisites: @itemize -@item @uref{http://download.videolan.org/pub/contrib/c99-to-c89/, C99-to-C89 Converter & Wrapper} +@item @uref{https://github.com/libav/c99-to-c89/, C99-to-C89 Converter & Wrapper} +(if using MSVC 2012 or earlier) @item @uref{http://code.google.com/p/msinttypes/, msinttypes} +(if using MSVC 2012 or earlier) @item @uref{http://www.mingw.org/, MSYS} @item @uref{http://yasm.tortall.net/, YASM} @item @uref{http://gnuwin32.sourceforge.net/packages/bc.htm, bc for Windows} if you want to run @uref{fate.html, FATE}. @end itemize -To set up a proper MSVC environment in MSYS, you simply need to run -@code{msys.bat} from the Visual Studio command prompt. +To set up a proper environment in MSYS, you need to run @code{msys.bat} from +the Visual Studio or Intel Compiler command prompt. -Place @code{makedef}, @code{c99wrap.exe}, @code{c99conv.exe}, and @code{yasm.exe} -somewhere in your @code{PATH}. +Place @code{yasm.exe} somewhere in your @code{PATH}. If using MSVC 2012 or +earlier, place @code{c99wrap.exe} and @code{c99conv.exe} somewhere in your +@code{PATH} as well. -Next, make sure @code{inttypes.h} and any other headers and libs you want to use -are located in a spot that MSVC can see. Do so by modifying the @code{LIB} and -@code{INCLUDE} environment variables to include the @strong{Windows} paths to -these directories. Alternatively, you can try and use the -@code{--extra-cflags}/@code{--extra-ldflags} configure options. +Next, make sure any other headers and libs you want to use, such as zlib, are +located in a spot that the compiler can see. Do so by modifying the @code{LIB} +and @code{INCLUDE} environment variables to include the @strong{Windows-style} +paths to these directories. Alternatively, you can try and use the +@code{--extra-cflags}/@code{--extra-ldflags} configure options. If using MSVC +2012 or earlier, place @code{inttypes.h} somewhere the compiler can see too. Finally, run: @example +For MSVC: ./configure --toolchain=msvc + +For ICL: +./configure --toolchain=icl + make make install @end example If you wish to compile shared libraries, add @code{--enable-shared} to your -configure options. Note that due to the way MSVC handles DLL imports and +configure options. Note that due to the way MSVC and ICL handle DLL imports and exports, you cannot compile static and shared libraries at the same time, and enabling shared libraries will automatically disable the static ones. @@ -173,7 +182,14 @@ erroneously included when building FFmpeg. can see. @end enumerate -@item FFmpeg has been tested with Visual Studio 2010 and 2012, Pro and Express. +@item FFmpeg has been tested with the following on i686 and x86_64: +@itemize +@item Visual Studio 2010 Pro and Express +@item Visual Studio 2012 Pro and Express +@item Visual Studio 2013 Pro and Express +@item Intel Composer XE 2013 +@item Intel Composer XE 2013 SP1 +@end itemize Anything else is not officially supported. @end itemize @@ -184,16 +200,7 @@ If you plan to link with MSVC-built static libraries, you will need to make sure you have @code{Runtime Library} set to @code{Multi-threaded (/MT)} in your project's settings. -FFmpeg headers do not declare global data for Windows DLLs through the usual -dllexport/dllimport interface. Such data will be exported properly while -building, but to use them in your MSVC code you will have to edit the -appropriate headers and mark the data as dllimport. For example, in -libavutil/pixdesc.h you should have: -@example -extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[]; -@end example - -You will also need to define @code{inline} to something MSVC understands: +You will need to define @code{inline} to something MSVC understands: @example #define inline __inline @end example diff --git a/ffmpeg/doc/print_options.c b/ffmpeg/doc/print_options.c index c369cfd..ec8d839 100644 --- a/ffmpeg/doc/print_options.c +++ b/ffmpeg/doc/print_options.c @@ -1,20 +1,20 @@ /* * Copyright (c) 2012 Anton Khirnov * - * This file is part of Libav. + * This file is part of FFmpeg. * - * Libav is free software; you can redistribute it and/or + * FFmpeg is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * - * Libav is distributed in the hope that it will be useful, + * FFmpeg is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with Libav; if not, write to the Free Software + * License along with FFmpeg; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ @@ -27,7 +27,9 @@ #include <float.h> #include "libavformat/avformat.h" +#include "libavformat/options_table.h" #include "libavcodec/avcodec.h" +#include "libavcodec/options_table.h" #include "libavutil/opt.h" static void print_usage(void) @@ -96,18 +98,14 @@ static void show_opts(const AVOption *opts, int per_stream) static void show_format_opts(void) { -#include "libavformat/options_table.h" - printf("@section Format AVOptions\n"); - show_opts(options, 0); + show_opts(avformat_options, 0); } static void show_codec_opts(void) { -#include "libavcodec/options_table.h" - printf("@section Codec AVOptions\n"); - show_opts(options, 1); + show_opts(avcodec_options, 1); } int main(int argc, char **argv) diff --git a/ffmpeg/doc/protocols.texi b/ffmpeg/doc/protocols.texi index 9940b67..57f9266 100644 --- a/ffmpeg/doc/protocols.texi +++ b/ffmpeg/doc/protocols.texi @@ -1,8 +1,8 @@ @chapter Protocols @c man begin PROTOCOLS -Protocols are configured elements in FFmpeg which allow to access -resources which require the use of a particular protocol. +Protocols are configured elements in FFmpeg that enable access to +resources that require specific protocols. When you configure your FFmpeg build, all the supported protocols are enabled by default. You can list all available ones using the @@ -49,6 +49,16 @@ Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapte -playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray @end example +@section cache + +Caching wrapper for input stream. + +Cache the input stream to temporary file. It brings seeking capability to live streams. + +@example +cache:@var{URL} +@end example + @section concat Physical concatenation protocol. @@ -75,6 +85,25 @@ ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg Note that you may need to escape the character "|" which is special for many shells. +@section crypto + +AES-encrypted stream reading protocol. + +The accepted options are: +@table @option +@item key +Set the AES decryption key binary block from given hexadecimal representation. + +@item iv +Set the AES decryption initialization vector binary block from given hexadecimal representation. +@end table + +Accepted URL formats: +@example +crypto:@var{URL} +crypto+@var{URL} +@end example + @section data Data in-line in the URI. See @url{http://en.wikipedia.org/wiki/Data_URI_scheme}. @@ -100,6 +129,54 @@ The ff* tools default to the file protocol, that is a resource specified with the name "FILE.mpeg" is interpreted as the URL "file:FILE.mpeg". +This protocol accepts the following options: + +@table @option +@item truncate +Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. + +@item blocksize +Set I/O operation maximum block size, in bytes. Default value is +@code{INT_MAX}, which results in not limiting the requested block size. +Setting this value reasonably low improves user termination request reaction +time, which is valuable for files on slow medium. +@end table + +@section ftp + +FTP (File Transfer Protocol). + +Allow to read from or write to remote resources using FTP protocol. + +Following syntax is required. +@example +ftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg +@end example + +This protocol accepts the following options. + +@table @option +@item timeout +Set timeout of socket I/O operations used by the underlying low level +operation. By default it is set to -1, which means that the timeout is +not specified. + +@item ftp-anonymous-password +Password used when login as anonymous user. Typically an e-mail address +should be used. + +@item ftp-write-seekable +Control seekability of connection during encoding. If set to 1 the +resource is supposed to be seekable, if set to 0 it is assumed not +to be seekable. Default value is 0. +@end table + +NOTE: Protocol can be used as output, but it is recommended to not do +it, unless special care is taken (tests, customized server configuration +etc.). Different FTP servers behave in different way during seek +operation. ff* tools may produce incomplete content due to server limitations. + @section gopher Gopher protocol. @@ -165,6 +242,20 @@ not specified. @item mime_type Set MIME type. +@item icy +If set to 1 request ICY (SHOUTcast) metadata from the server. If the server +supports this, the metadata has to be retrieved by the application by reading +the @option{icy_metadata_headers} and @option{icy_metadata_packet} options. +The default is 0. + +@item icy_metadata_headers +If the server supports ICY metadata, this contains the ICY specific HTTP reply +headers, separated with newline characters. + +@item icy_metadata_packet +If the server supports ICY metadata, and @option{icy} was set to 1, this +contains the last non-empty metadata packet sent by the server. + @item cookies Set the cookies to be sent in future requests. The format of each cookie is the same as the value of a Set-Cookie HTTP response field. Multiple cookies can be @@ -248,6 +339,16 @@ ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi ffmpeg -i test.wav -f avi pipe: | cat > test.avi @end example +This protocol accepts the following options: + +@table @option +@item blocksize +Set I/O operation maximum block size, in bytes. Default value is +@code{INT_MAX}, which results in not limiting the requested block size. +Setting this value reasonably low improves user termination request reaction +time, which is valuable if data transmission is slow. +@end table + Note that some formats (typically MOV), require the output protocol to be seekable, so they will fail with the pipe output protocol. @@ -260,12 +361,18 @@ content across a TCP/IP network. The required syntax is: @example -rtmp://@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}] +rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}] @end example The accepted parameters are: @table @option +@item username +An optional username (mostly for publishing). + +@item password +An optional password (mostly for publishing). + @item server The address of the RTMP server. @@ -316,7 +423,8 @@ times to construct arbitrary AMF sequences. @item rtmp_flashver Version of the Flash plugin used to run the SWF player. The default -is LNX 9,0,124,2. +is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; +<libavformat version>).) @item rtmp_flush_interval Number of packets flushed in the same request (RTMPT only). The default @@ -366,6 +474,12 @@ For example to read with @command{ffplay} a multimedia resource named ffplay rtmp://myserver/vod/sample @end example +To publish to a password protected server, passing the playpath and +app names separately: +@example +ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/ +@end example + @section rtmpe Encrypted Real-Time Messaging Protocol. @@ -406,7 +520,39 @@ The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used for streaming multimedia content within HTTPS requests to traverse firewalls. -@section rtmp, rtmpe, rtmps, rtmpt, rtmpte +@section libssh + +Secure File Transfer Protocol via libssh + +Allow to read from or write to remote resources using SFTP protocol. + +Following syntax is required. + +@example +sftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg +@end example + +This protocol accepts the following options. + +@table @option +@item timeout +Set timeout of socket I/O operations used by the underlying low level +operation. By default it is set to -1, which means that the timeout +is not specified. + +@item truncate +Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. + +@end table + +Example: Play a file stored on remote server. + +@example +ffplay sftp://user:password@@server_address:22/home/user/resource.mpeg +@end example + +@section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte Real-Time Messaging Protocol and its variants supported through librtmp. @@ -448,7 +594,70 @@ ffplay "rtmp://myserver/live/mystream live=1" @section rtp -Real-Time Protocol. +Real-time Transport Protocol. + +The required syntax for an RTP URL is: +rtp://@var{hostname}[:@var{port}][?@var{option}=@var{val}...] + +@var{port} specifies the RTP port to use. + +The following URL options are supported: + +@table @option + +@item ttl=@var{n} +Set the TTL (Time-To-Live) value (for multicast only). + +@item rtcpport=@var{n} +Set the remote RTCP port to @var{n}. + +@item localrtpport=@var{n} +Set the local RTP port to @var{n}. + +@item localrtcpport=@var{n}' +Set the local RTCP port to @var{n}. + +@item pkt_size=@var{n} +Set max packet size (in bytes) to @var{n}. + +@item connect=0|1 +Do a @code{connect()} on the UDP socket (if set to 1) or not (if set +to 0). + +@item sources=@var{ip}[,@var{ip}] +List allowed source IP addresses. + +@item block=@var{ip}[,@var{ip}] +List disallowed (blocked) source IP addresses. + +@item write_to_source=0|1 +Send packets to the source address of the latest received packet (if +set to 1) or to a default remote address (if set to 0). + +@item localport=@var{n} +Set the local RTP port to @var{n}. + +This is a deprecated option. Instead, @option{localrtpport} should be +used. + +@end table + +Important notes: + +@enumerate + +@item +If @option{rtcpport} is not set the RTCP port will be set to the RTP +port value plus 1. + +@item +If @option{localrtpport} (the local RTP port) is not set any available +port will be used for the local RTP and RTCP ports. + +@item +If @option{localrtcpport} (the local RTCP port) is not set it will be +set to the the local RTP port value plus 1. +@end enumerate @section rtsp @@ -538,6 +747,11 @@ To receive a stream in realtime: ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output} @end example +@table @option +@item stimeout +Socket IO timeout in micro seconds. +@end table + @section sap Session Announcement Protocol (RFC 2974). This is not technically a @@ -630,6 +844,50 @@ To play back the first stream announced on one the default IPv6 SAP multicast ad ffplay sap://[ff0e::2:7ffe] @end example +@section sctp + +Stream Control Transmission Protocol. + +The accepted URL syntax is: +@example +sctp://@var{host}:@var{port}[?@var{options}] +@end example + +The protocol accepts the following options: +@table @option +@item listen +If set to any value, listen for an incoming connection. Outgoing connection is done by default. + +@item max_streams +Set the maximum number of streams. By default no limit is set. +@end table + +@section srtp + +Secure Real-time Transport Protocol. + +The accepted options are: +@table @option +@item srtp_in_suite +@item srtp_out_suite +Select input and output encoding suites. + +Supported values: +@table @samp +@item AES_CM_128_HMAC_SHA1_80 +@item SRTP_AES128_CM_HMAC_SHA1_80 +@item AES_CM_128_HMAC_SHA1_32 +@item SRTP_AES128_CM_HMAC_SHA1_32 +@end table + +@item srtp_in_params +@item srtp_out_params +Set input and output encoding parameters, which are expressed by a +base64-encoded representation of a binary block. The first 16 bytes of +this binary block are used as master key, the following 14 bytes are +used as master salt. +@end table + @section tcp Trasmission Control Protocol. @@ -639,48 +897,76 @@ The required syntax for a TCP url is: tcp://@var{hostname}:@var{port}[?@var{options}] @end example -@table @option +@var{options} contains a list of &-separated options of the form +@var{key}=@var{val}. -@item listen -Listen for an incoming connection +The list of supported options follows. + +@table @option +@item listen=@var{1|0} +Listen for an incoming connection. Default value is 0. @item timeout=@var{microseconds} -In read mode: if no data arrived in more than this time interval, raise error. -In write mode: if socket cannot be written in more than this time interval, raise error. -This also sets timeout on TCP connection establishing. +Set raise error timeout, expressed in microseconds. + +This option is only relevant in read mode: if no data arrived in more +than this time interval, raise error. +@item listen_timeout=@var{microseconds} +Set listen timeout, expressed in microseconds. +@end table + +The following example shows how to setup a listening TCP connection +with @command{ffmpeg}, which is then accessed with @command{ffplay}: @example ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen ffplay tcp://@var{hostname}:@var{port} @end example -@end table - @section tls -Transport Layer Security/Secure Sockets Layer +Transport Layer Security (TLS) / Secure Sockets Layer (SSL) The required syntax for a TLS/SSL url is: @example tls://@var{hostname}:@var{port}[?@var{options}] @end example -@table @option - -@item listen -Act as a server, listening for an incoming connection. - -@item cafile=@var{filename} -Certificate authority file. The file must be in OpenSSL PEM format. - -@item cert=@var{filename} -Certificate file. The file must be in OpenSSL PEM format. +The following parameters can be set via command line options +(or in code via @code{AVOption}s): -@item key=@var{filename} -Private key file. +@table @option -@item verify=@var{0|1} -Verify the peer's certificate. +@item ca_file, cafile=@var{filename} +A file containing certificate authority (CA) root certificates to treat +as trusted. If the linked TLS library contains a default this might not +need to be specified for verification to work, but not all libraries and +setups have defaults built in. +The file must be in OpenSSL PEM format. + +@item tls_verify=@var{1|0} +If enabled, try to verify the peer that we are communicating with. +Note, if using OpenSSL, this currently only makes sure that the +peer certificate is signed by one of the root certificates in the CA +database, but it does not validate that the certificate actually +matches the host name we are trying to connect to. (With GnuTLS, +the host name is validated as well.) + +This is disabled by default since it requires a CA database to be +provided by the caller in many cases. + +@item cert_file, cert=@var{filename} +A file containing a certificate to use in the handshake with the peer. +(When operating as server, in listen mode, this is more often required +by the peer, while client certificates only are mandated in certain +setups.) + +@item key_file, key=@var{filename} +A file containing the private key for the certificate. + +@item listen=@var{1|0} +If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. @end table @@ -702,7 +988,7 @@ ffplay tls://@var{hostname}:@var{port} User Datagram Protocol. -The required syntax for a UDP url is: +The required syntax for an UDP URL is: @example udp://@var{hostname}:@var{port}[?@var{options}] @end example @@ -717,7 +1003,6 @@ UDP socket buffer overruns. The @var{fifo_size} and The list of supported options follows. @table @option - @item buffer_size=@var{size} Set the UDP socket buffer size in bytes. This is used both for the receiving and the sending buffer size. @@ -767,24 +1052,53 @@ Survive in case of UDP receiving circular buffer overrun. Default value is 0. @item timeout=@var{microseconds} -In read mode: if no data arrived in more than this time interval, raise error. +Set raise error timeout, expressed in microseconds. + +This option is only relevant in read mode: if no data arrived in more +than this time interval, raise error. @end table -Some usage examples of the UDP protocol with @command{ffmpeg} follow. +@subsection Examples -To stream over UDP to a remote endpoint: +@itemize +@item +Use @command{ffmpeg} to stream over UDP to a remote endpoint: @example ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port} @end example -To stream in mpegts format over UDP using 188 sized UDP packets, using a large input buffer: +@item +Use @command{ffmpeg} to stream in mpegts format over UDP using 188 +sized UDP packets, using a large input buffer: @example ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535 @end example -To receive over UDP from a remote endpoint: +@item +Use @command{ffmpeg} to receive over UDP from a remote endpoint: +@example +ffmpeg -i udp://[@var{multicast-address}]:@var{port} ... +@end example +@end itemize + +@section unix + +Unix local socket + +The required syntax for a Unix socket URL is: + @example -ffmpeg -i udp://[@var{multicast-address}]:@var{port} +unix://@var{filepath} @end example +The following parameters can be set via command line options +(or in code via @code{AVOption}s): + +@table @option +@item timeout +Timeout in ms. +@item listen +Create the Unix socket in listening mode. +@end table + @c man end PROTOCOLS diff --git a/ffmpeg/doc/snow.txt b/ffmpeg/doc/snow.txt index f991339..080a33b 100644 --- a/ffmpeg/doc/snow.txt +++ b/ffmpeg/doc/snow.txt @@ -50,8 +50,10 @@ header: temporal_decomposition_count u header_state spatial_decomposition_count u header_state colorspace_type u header_state - chroma_h_shift u header_state - chroma_v_shift u header_state + if (nb_planes > 2) { + chroma_h_shift u header_state + chroma_v_shift u header_state + } spatial_scalability b header_state max_ref_frames-1 u header_state qlogs @@ -59,7 +61,7 @@ header: if(!keyframe){ update_mc b header_state if(update_mc){ - for(plane=0; plane<2; plane++){ + for(plane=0; plane<nb_plane_types; plane++){ diag_mc b header_state htaps/2-1 u header_state for(i= p->htaps/2; i; i--) @@ -80,7 +82,7 @@ header: block_max_depth s header_state qlogs: - for(plane=0; plane<2; plane++){ + for(plane=0; plane<nb_plane_types; plane++){ quant_table[plane][0][0] s header_state for(level=0; level < spatial_decomposition_count; level++){ quant_table[plane][level][1]s header_state @@ -131,8 +133,10 @@ block(level): residual: residual2(luma) - residual2(chroma_cr) - residual2(chroma_cb) + if (nb_planes > 2) { + residual2(chroma_cr) + residual2(chroma_cb) + } residual2: for(level=0; level<spatial_decomposition_count; level++){ @@ -146,7 +150,7 @@ residual2: subband: FIXME - +nb_plane_types = gray ? 1 : 2; Tag description: ---------------- @@ -168,7 +172,11 @@ spatial_decomposition_count FIXME colorspace_type - 0 + 0 unspecified YcbCr + 1 Gray + 2 Gray + Alpha + 3 GBR + 4 GBRA this MUST NOT change within a bitstream chroma_h_shift diff --git a/ffmpeg/doc/soc.txt b/ffmpeg/doc/soc.txt deleted file mode 100644 index 2504dba..0000000 --- a/ffmpeg/doc/soc.txt +++ /dev/null @@ -1,24 +0,0 @@ -Google Summer of Code and similar project guidelines - -Summer of Code is a project by Google in which students are paid to implement -some nice new features for various participating open source projects ... - -This text is a collection of things to take care of for the next soc as -it's a little late for this year's soc (2006). - -The Goal: -Our goal in respect to soc is and must be of course exactly one thing and -that is to improve FFmpeg, to reach this goal, code must -* conform to the development policy and patch submission guidelines -* must improve FFmpeg somehow (faster, smaller, "better", - more codecs supported, fewer bugs, cleaner, ...) - -for mentors and other developers to help students to reach that goal it is -essential that changes to their codebase are publicly visible, clean and -easy reviewable that again leads us to: -* use of a revision control system like git -* separation of cosmetic from non-cosmetic changes (this is almost entirely - ignored by mentors and students in soc 2006 which might lead to a surprise - when the code will be reviewed at the end before a possible inclusion in - FFmpeg, individual changes were generally not reviewable due to cosmetics). -* frequent commits, so that comments can be provided early diff --git a/ffmpeg/doc/syntax.texi b/ffmpeg/doc/syntax.texi deleted file mode 100644 index af22d6c..0000000 --- a/ffmpeg/doc/syntax.texi +++ /dev/null @@ -1,258 +0,0 @@ -@chapter Syntax -@c man begin SYNTAX - -This section documents the syntax and formats employed by the FFmpeg -libraries and tools. - -@anchor{quoting_and_escaping} -@section Quoting and escaping - -FFmpeg adopts the following quoting and escaping mechanism, unless -explicitly specified. The following rules are applied: - -@itemize -@item -@code{'} and @code{\} are special characters (respectively used for -quoting and escaping). In addition to them, there might be other -special characters depending on the specific syntax where the escaping -and quoting are employed. - -@item -A special character is escaped by prefixing it with a '\'. - -@item -All characters enclosed between '' are included literally in the -parsed string. The quote character @code{'} itself cannot be quoted, -so you may need to close the quote and escape it. - -@item -Leading and trailing whitespaces, unless escaped or quoted, are -removed from the parsed string. -@end itemize - -Note that you may need to add a second level of escaping when using -the command line or a script, which depends on the syntax of the -adopted shell language. - -The function @code{av_get_token} defined in -@file{libavutil/avstring.h} can be used to parse a token quoted or -escaped according to the rules defined above. - -The tool @file{tools/ffescape} in the FFmpeg source tree can be used -to automatically quote or escape a string in a script. - -@subsection Examples - -@itemize -@item -Escape the string @code{Crime d'Amour} containing the @code{'} special -character: -@example -Crime d\'Amour -@end example - -@item -The string above contains a quote, so the @code{'} needs to be escaped -when quoting it: -@example -'Crime d'\''Amour' -@end example - -@item -Include leading or trailing whitespaces using quoting: -@example -' this string starts and ends with whitespaces ' -@end example - -@item -Escaping and quoting can be mixed together: -@example -' The string '\'string\'' is a string ' -@end example - -@item -To include a literal @code{\} you can use either escaping or quoting: -@example -'c:\foo' can be written as c:\\foo -@end example -@end itemize - -@anchor{date syntax} -@section Date - -The accepted syntax is: -@example -[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z] -now -@end example - -If the value is "now" it takes the current time. - -Time is local time unless Z is appended, in which case it is -interpreted as UTC. -If the year-month-day part is not specified it takes the current -year-month-day. - -@anchor{time duration syntax} -@section Time duration - -The accepted syntax is: -@example -[-][HH:]MM:SS[.m...] -[-]S+[.m...] -@end example - -@var{HH} expresses the number of hours, @var{MM} the number a of minutes -and @var{SS} the number of seconds. - -@anchor{video size syntax} -@section Video size -Specify the size of the sourced video, it may be a string of the form -@var{width}x@var{height}, or the name of a size abbreviation. - -The following abbreviations are recognized: -@table @samp -@item ntsc -720x480 -@item pal -720x576 -@item qntsc -352x240 -@item qpal -352x288 -@item sntsc -640x480 -@item spal -768x576 -@item film -352x240 -@item ntsc-film -352x240 -@item sqcif -128x96 -@item qcif -176x144 -@item cif -352x288 -@item 4cif -704x576 -@item 16cif -1408x1152 -@item qqvga -160x120 -@item qvga -320x240 -@item vga -640x480 -@item svga -800x600 -@item xga -1024x768 -@item uxga -1600x1200 -@item qxga -2048x1536 -@item sxga -1280x1024 -@item qsxga -2560x2048 -@item hsxga -5120x4096 -@item wvga -852x480 -@item wxga -1366x768 -@item wsxga -1600x1024 -@item wuxga -1920x1200 -@item woxga -2560x1600 -@item wqsxga -3200x2048 -@item wquxga -3840x2400 -@item whsxga -6400x4096 -@item whuxga -7680x4800 -@item cga -320x200 -@item ega -640x350 -@item hd480 -852x480 -@item hd720 -1280x720 -@item hd1080 -1920x1080 -@item 2k -2048x1080 -@item 2kflat -1998x1080 -@item 2kscope -2048x858 -@item 4k -4096x2160 -@item 4kflat -3996x2160 -@item 4kscope -4096x1716 -@end table - -@anchor{video rate syntax} -@section Video rate - -Specify the frame rate of a video, expressed as the number of frames -generated per second. It has to be a string in the format -@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float -number or a valid video frame rate abbreviation. - -The following abbreviations are recognized: -@table @samp -@item ntsc -30000/1001 -@item pal -25/1 -@item qntsc -30000/1001 -@item qpal -25/1 -@item sntsc -30000/1001 -@item spal -25/1 -@item film -24/1 -@item ntsc-film -24000/1001 -@end table - -@anchor{ratio syntax} -@section Ratio - -A ratio can be expressed as an expression, or in the form -@var{numerator}:@var{denominator}. - -Note that a ratio with infinite (1/0) or negative value is -considered valid, so you should check on the returned value if you -want to exclude those values. - -The undefined value can be expressed using the "0:0" string. - -@anchor{color syntax} -@section Color - -It can be the name of a color (case insensitive match) or a -[0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string -representing the alpha component. - -The alpha component may be a string composed by "0x" followed by an -hexadecimal number or a decimal number between 0.0 and 1.0, which -represents the opacity value (0x00/0.0 means completely transparent, -0xff/1.0 completely opaque). -If the alpha component is not specified then 0xff is assumed. - -The string "random" will result in a random color. - -@c man end SYNTAX diff --git a/ffmpeg/doc/t2h.init b/ffmpeg/doc/t2h.init index 2aab488..e7760f4 100644 --- a/ffmpeg/doc/t2h.init +++ b/ffmpeg/doc/t2h.init @@ -17,6 +17,7 @@ my $TEMPLATE_HEADER = $ENV{"FFMPEG_HEADER"} || <<EOT; </head> <body> <div id="container"> +<div id="body"> EOT $PRE_BODY_CLOSE = '</div></div>'; @@ -32,7 +33,7 @@ sub FFmpeg_print_page_foot($$) T2H_DEFAULT_program_string() : program_string(); print $fh '<footer class="footer pagination-right">' . "\n"; print $fh '<span class="label label-info">' . $program_string; - print $fh "</span></footer></div>\n"; + print $fh "</span></footer></div></div></body>\n"; } $float = \&FFmpeg_float; @@ -92,8 +93,6 @@ $Texi2HTML::THISDOC{program_authors} $description <meta name="keywords" content="$longtitle"> -<meta name="resource-type" content="document"> -<meta name="distribution" content="global"> <meta name="Generator" content="$Texi2HTML::THISDOC{program}"> $encoding $CSS_LINES diff --git a/ffmpeg/doc/texi2pod.pl b/ffmpeg/doc/texi2pod.pl index 697576c..6cf78d8 100755 --- a/ffmpeg/doc/texi2pod.pl +++ b/ffmpeg/doc/texi2pod.pl @@ -1,4 +1,4 @@ -#! /usr/bin/perl +#!/usr/bin/env perl # Copyright (C) 1999, 2000, 2001 Free Software Foundation, Inc. @@ -121,7 +121,7 @@ INF: while(<$inf>) { $chapters{$chapter_name} .= postprocess($chapter) if ($chapter_name); # start new chapter - $chapter_name = $1, push (@chapters_sequence, $chapter_name); + $chapter_name = $1, push (@chapters_sequence, $chapter_name) unless $skipping; $chapters{$chapter_name} = "" unless exists $chapters{$chapter_name}; $chapter = ""; $output = 1; diff --git a/ffmpeg/doc/viterbi.txt b/ffmpeg/doc/viterbi.txt deleted file mode 100644 index 9782546..0000000 --- a/ffmpeg/doc/viterbi.txt +++ /dev/null @@ -1,109 +0,0 @@ -This is a quick description of the viterbi aka dynamic programing -algorthm. - -Its reason for existence is that wikipedia has become very poor on -describing algorithms in a way that makes it useable for understanding -them or anything else actually. It tends now to describe the very same -algorithm under 50 different names and pages with few understandable -by even people who fully understand the algorithm and the theory behind. - -Problem description: (that is what it can solve) -assume we have a 2d table, or you could call it a graph or matrix if you -prefer - - O O O O O O O - - O O O O O O O - - O O O O O O O - - O O O O O O O - - -That table has edges connecting points from each column to the next column -and each edge has a score like: (only some edge and scores shown to keep it -readable) - - - O--5--O-----O-----O-----O-----O - 2 / 7 / \ / \ / \ / - \ / \ / \ / \ / \ / - O7-/--O--/--O--/--O--/--O--/--O - \/ \/ 1/ \/ \/ \/ \/ \/ \/ \/ - /\ /\ 2\ /\ /\ /\ /\ /\ /\ /\ - O3-/--O--/--O--/--O--/--O--/--O - / \ / \ / \ / \ / \ - 1 \ 9 \ / \ / \ / \ - O--2--O--1--O--5--O--3--O--8--O - - - -Our goal is to find a path from left to right through it which -minimizes the sum of the score of all edges. -(and of course left/right is just a convention here it could be top down too) -Similarly the minimum could be the maximum by just fliping the sign, -Example of a path with scores: - - O O O O O O O - ->---O. O O .O-2-O O O - 5. .7 . - O O-1-O O O 8 O O - . - O O O O O O-1-O---> (sum here is 24) - - -The viterbi algorthm now solves this simply column by column -For the previous column each point has a best path and a associated -score: - - O-----5 O - \ - \ - O \ 1 O - \/ - /\ - O / 2 O - / - / - O-----2 O - - -To move one column forward we just need to find the best path and associated -scores for the next column -here are some edges we could choose from: - - - O-----5--3--O - \ \8 - \ \ - O \ 1--9--O - \/ \3 - /\ \ - O / 2--1--O - / \2 - / \ - O-----2--4--O - -Finding the new best paths and scores for each point of our new column is -trivial given we know the previous column best paths and scores: - - O-----0-----8 - \ - \ - O \ 0----10 - \/ - /\ - O / 0-----3 - / \ - / \ - O 0 4 - - -the viterbi algorthm continues exactly like this column for column until the -end and then just picks the path with the best score (above that would be the -one with score 3) - - -Author: Michael niedermayer -Copyright LGPL |