diff --git a/DebugView/Dbgview.exe b/DebugView/Dbgview.exe new file mode 100644 index 00000000..b91df079 Binary files /dev/null and b/DebugView/Dbgview.exe differ diff --git a/DebugView/Dbgview64a.exe b/DebugView/Dbgview64a.exe new file mode 100644 index 00000000..8949c2f8 Binary files /dev/null and b/DebugView/Dbgview64a.exe differ diff --git a/DebugView/Eula.txt b/DebugView/Eula.txt new file mode 100644 index 00000000..8efa7116 --- /dev/null +++ b/DebugView/Eula.txt @@ -0,0 +1,75 @@ +Sysinternals Software License Terms +These license terms are an agreement between Sysinternals (a wholly owned subsidiary of Microsoft Corporation) and you. Please read them. They apply to the software you are downloading from technet.microsoft.com/sysinternals, which includes the media on which you received it, if any. The terms also apply to any Sysinternals +* updates, +* supplements, +* Internet-based services, +* and support services +for this software, unless other terms accompany those items. If so, those terms apply. +BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. IF YOU DO NOT ACCEPT THEM, DO NOT USE THE SOFTWARE. +If you comply with these license terms, you have the rights below. + +Installation and User Rights + +You may install and use any number of copies of the software on your devices. + +Scope of License + +The software is licensed, not sold. This agreement only gives you some rights to use the software. Sysinternals reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways. You may not +* work around any technical limitations in the software; +* reverse engineer, decompile or disassemble the software, except and only to the extent that applicable law expressly permits, despite this limitation; +* make more copies of the software than specified in this agreement or allowed by applicable law, despite this limitation; +* publish the software for others to copy; +* rent, lease or lend the software; +* transfer the software or this agreement to any third party; or +* use the software for commercial software hosting services. + +Sensitive Information + +Please be aware that, similar to other debug tools that capture “process state” information, files saved by Sysinternals tools may include personally identifiable or other sensitive information (such as usernames, passwords, paths to files accessed, and paths to registry accessed). By using this software, you acknowledge that you are aware of this and take sole responsibility for any personally identifiable or other sensitive information provided to Microsoft or any other party through your use of the software. + +Documentation + +Any person that has valid access to your computer or internal network may copy and use the documentation for your internal, reference purposes. + +Export Restrictions + +The software is subject to United States export laws and regulations. You must comply with all domestic and international export laws and regulations that apply to the software. These laws include restrictions on destinations, end users and end use. For additional information, see www.microsoft.com/exporting . + +Support Services + +Because this software is "as is," we may not provide support services for it. + +Entire Agreement + +This agreement, and the terms for supplements, updates, Internet-based services and support services that you use, are the entire agreement for the software and support services. + +Applicable Law + +United States . If you acquired the software in the United States , Washington state law governs the interpretation of this agreement and applies to claims for breach of it, regardless of conflict of laws principles. The laws of the state where you live govern all other claims, including claims under state consumer protection laws, unfair competition laws, and in tort. +Outside the United States . If you acquired the software in any other country, the laws of that country apply. + +Legal Effect + +This agreement describes certain legal rights. You may have other rights under the laws of your country. You may also have rights with respect to the party from whom you acquired the software. This agreement does not change your rights under the laws of your country if the laws of your country do not permit it to do so. + +Disclaimer of Warranty + +The software is licensed "as-is." You bear the risk of using it. Sysinternals gives no express warranties, guarantees or conditions. You may have additional consumer rights under your local laws which this agreement cannot change. To the extent permitted under your local laws, sysinternals excludes the implied warranties of merchantability, fitness for a particular purpose and non-infringement. + +Limitation on and Exclusion of Remedies and Damages + +You can recover from sysinternals and its suppliers only direct damages up to U.S. $5.00. You cannot recover any other damages, including consequential, lost profits, special, indirect or incidental damages. +This limitation applies to +* anything related to the software, services, content (including code) on third party Internet sites, or third party programs; and +* claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law. + +It also applies even if Sysinternals knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages. +Please note: As this software is distributed in Quebec , Canada , some of the clauses in this agreement are provided below in French. +Remarque : Ce logiciel étant distribué au Québec, Canada, certaines des clauses dans ce contrat sont fournies ci-dessous en français. +EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « tel quel ». Toute utilisation de ce logiciel est à votre seule risque et péril. Sysinternals n'accorde aucune autre garantie expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection dues consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties implicites de qualité marchande, d'adéquation à un usage particulier et d'absence de contrefaçon sont exclues. +LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de Sysinternals et de ses fournisseurs une indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices. +Cette limitation concerne : +tout ce qui est relié au logiciel, aux services ou au contenu (y compris le code) figurant sur des sites Internet tiers ou dans des programmes tiers ; et +les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité stricte, de négligence ou d'une autre faute dans la limite autorisée par la loi en vigueur. +Elle s'applique également, même si Sysinternals connaissait ou devrait connaître l'éventualité d'un tel dommage. Si votre pays n'autorise pas l'exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires ou de quelque nature que ce soit, il se peut que la limitation ou l'exclusion ci-dessus ne s'appliquera pas à votre égard. +EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d'autres droits prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre pays si celles-ci ne le permettent pas. diff --git a/DebugView/dbgview64.exe b/DebugView/dbgview64.exe new file mode 100644 index 00000000..095a7d2d Binary files /dev/null and b/DebugView/dbgview64.exe differ diff --git a/ODHUBYOLODarknet/lib/ansdn.exe b/ODHUBYOLODarknet/lib/ansdn.exe index 44c6b072..c48572e6 100644 Binary files a/ODHUBYOLODarknet/lib/ansdn.exe and b/ODHUBYOLODarknet/lib/ansdn.exe differ diff --git a/ODHUBYOLODarknet/lib/odhublib.dll b/ODHUBYOLODarknet/lib/odhublib.dll index 04641469..2cf7e0c1 100644 Binary files a/ODHUBYOLODarknet/lib/odhublib.dll and b/ODHUBYOLODarknet/lib/odhublib.dll differ diff --git a/ODHUBYOLODarknet/lib/odhublib.lib b/ODHUBYOLODarknet/lib/odhublib.lib index 06ceee56..f583a8bd 100644 Binary files a/ODHUBYOLODarknet/lib/odhublib.lib and b/ODHUBYOLODarknet/lib/odhublib.lib differ diff --git a/ODHUBYOLODarknet/lib/odhublib_cpu.dll b/ODHUBYOLODarknet/lib/odhublib_cpu.dll index 1c57f7dd..49498c8c 100644 Binary files a/ODHUBYOLODarknet/lib/odhublib_cpu.dll and b/ODHUBYOLODarknet/lib/odhublib_cpu.dll differ diff --git a/ODHUBYOLODarknet/lib/odhublib_cpu.lib b/ODHUBYOLODarknet/lib/odhublib_cpu.lib index c1f20d72..b4c9eaeb 100644 Binary files a/ODHUBYOLODarknet/lib/odhublib_cpu.lib and b/ODHUBYOLODarknet/lib/odhublib_cpu.lib differ diff --git a/ODHUBYOLODarknet/CUDA11.8/include/darknet.h b/ODHUBYOLODarknet_old/CUDA11.8/include/darknet.h similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/include/darknet.h rename to ODHUBYOLODarknet_old/CUDA11.8/include/darknet.h diff --git a/ODHUBYOLODarknet/CUDA11.8/include/yolo_v2_class.hpp b/ODHUBYOLODarknet_old/CUDA11.8/include/yolo_v2_class.hpp similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/include/yolo_v2_class.hpp rename to ODHUBYOLODarknet_old/CUDA11.8/include/yolo_v2_class.hpp diff --git a/ODHUBYOLODarknet/CUDA11.8/include/yolo_v2cpu_class.hpp b/ODHUBYOLODarknet_old/CUDA11.8/include/yolo_v2cpu_class.hpp similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/include/yolo_v2cpu_class.hpp rename to ODHUBYOLODarknet_old/CUDA11.8/include/yolo_v2cpu_class.hpp diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib.dll b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.dll similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib.dll rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.dll diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib.exp b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.exp similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib.exp rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.exp diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib.lib b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.lib similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib.lib rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.lib diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib.pdb b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.pdb similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib.pdb rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib.pdb diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.dll b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.dll similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.dll rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.dll diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.exp b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.exp similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.exp rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.exp diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.lib b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.lib similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.lib rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.lib diff --git a/ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.pdb b/ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.pdb similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/lib/odhublib_cpu.pdb rename to ODHUBYOLODarknet_old/CUDA11.8/lib/odhublib_cpu.pdb diff --git a/ODHUBYOLODarknet/CUDA11.8/src/yolo_v2_class.cpp b/ODHUBYOLODarknet_old/CUDA11.8/src/yolo_v2_class.cpp similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/src/yolo_v2_class.cpp rename to ODHUBYOLODarknet_old/CUDA11.8/src/yolo_v2_class.cpp diff --git a/ODHUBYOLODarknet/CUDA11.8/src/yolo_v2cpuclass.cpp b/ODHUBYOLODarknet_old/CUDA11.8/src/yolo_v2cpuclass.cpp similarity index 100% rename from ODHUBYOLODarknet/CUDA11.8/src/yolo_v2cpuclass.cpp rename to ODHUBYOLODarknet_old/CUDA11.8/src/yolo_v2cpuclass.cpp diff --git a/ODHUBYOLODarknet_old/include/darknet.h b/ODHUBYOLODarknet_old/include/darknet.h new file mode 100644 index 00000000..55ab50d5 --- /dev/null +++ b/ODHUBYOLODarknet_old/include/darknet.h @@ -0,0 +1,1125 @@ +#ifndef DARKNET_API +#define DARKNET_API + +#if defined(_MSC_VER) && _MSC_VER < 1900 +#define inline __inline +#endif + +#if defined(DEBUG) && !defined(_CRTDBG_MAP_ALLOC) +#define _CRTDBG_MAP_ALLOC +#endif + +#include +#include +#include +#include +#include +#include + +#ifndef LIB_API +#ifdef LIB_EXPORTS +#if defined(_MSC_VER) +#define LIB_API __declspec(dllexport) +#else +#define LIB_API __attribute__((visibility("default"))) +#endif +#else +#if defined(_MSC_VER) +#define LIB_API +#else +#define LIB_API +#endif +#endif +#endif + +#define SECRET_NUM -1234 + +typedef enum { UNUSED_DEF_VAL } UNUSED_ENUM_TYPE; + +#ifdef GPU + +#include +#include +#include + +#ifdef CUDNN +#include +#endif // CUDNN +#endif // GPU + +#ifdef __cplusplus +extern "C" { +#endif + +struct network; +typedef struct network network; + +struct network_state; +typedef struct network_state network_state; + +struct layer; +typedef struct layer layer; + +struct image; +typedef struct image image; + +struct detection; +typedef struct detection detection; + +struct load_args; +typedef struct load_args load_args; + +struct data; +typedef struct data data; + +struct metadata; +typedef struct metadata metadata; + +struct tree; +typedef struct tree tree; + +extern int gpu_index; + +// option_list.h +typedef struct metadata { + int classes; + char **names; +} metadata; + + +// tree.h +typedef struct tree { + int *leaf; + int n; + int *parent; + int *child; + int *group; + char **name; + + int groups; + int *group_size; + int *group_offset; +} tree; + + +// activations.h +typedef enum { + LOGISTIC, RELU, RELU6, RELIE, LINEAR, RAMP, TANH, PLSE, REVLEAKY, LEAKY, ELU, LOGGY, STAIR, HARDTAN, LHTAN, SELU, GELU, SWISH, MISH, HARD_MISH, NORM_CHAN, NORM_CHAN_SOFTMAX, NORM_CHAN_SOFTMAX_MAXVAL +}ACTIVATION; + +// parser.h +typedef enum { + IOU, GIOU, MSE, DIOU, CIOU +} IOU_LOSS; + +// parser.h +typedef enum { + DEFAULT_NMS, GREEDY_NMS, DIOU_NMS, CORNERS_NMS +} NMS_KIND; + +// parser.h +typedef enum { + YOLO_CENTER = 1 << 0, YOLO_LEFT_TOP = 1 << 1, YOLO_RIGHT_BOTTOM = 1 << 2 +} YOLO_POINT; + +// parser.h +typedef enum { + NO_WEIGHTS, PER_FEATURE, PER_CHANNEL +} WEIGHTS_TYPE_T; + +// parser.h +typedef enum { + NO_NORMALIZATION, RELU_NORMALIZATION, SOFTMAX_NORMALIZATION +} WEIGHTS_NORMALIZATION_T; + +// image.h +typedef enum{ + PNG, BMP, TGA, JPG +} IMTYPE; + +// activations.h +typedef enum{ + MULT, ADD, SUB, DIV +} BINARY_ACTIVATION; + +// blas.h +typedef struct contrastive_params { + float sim; + float exp_sim; + float P; + int i, j; + int time_step_i, time_step_j; +} contrastive_params; + + +// layer.h +typedef enum { + CONVOLUTIONAL, + DECONVOLUTIONAL, + CONNECTED, + MAXPOOL, + LOCAL_AVGPOOL, + SOFTMAX, + DETECTION, + DROPOUT, + CROP, + ROUTE, + COST, + NORMALIZATION, + AVGPOOL, + LOCAL, + SHORTCUT, + SCALE_CHANNELS, + SAM, + ACTIVE, + RNN, + GRU, + LSTM, + CONV_LSTM, + HISTORY, + CRNN, + BATCHNORM, + NETWORK, + XNOR, + REGION, + YOLO, + GAUSSIAN_YOLO, + ISEG, + REORG, + REORG_OLD, + UPSAMPLE, + LOGXENT, + L2NORM, + EMPTY, + BLANK, + CONTRASTIVE, + IMPLICIT +} LAYER_TYPE; + +// layer.h +typedef enum{ + SSE, MASKED, L1, SEG, SMOOTH,WGAN +} COST_TYPE; + +// layer.h +typedef struct update_args { + int batch; + float learning_rate; + float momentum; + float decay; + int adam; + float B1; + float B2; + float eps; + int t; +} update_args; + +// layer.h +struct layer { + LAYER_TYPE type; + ACTIVATION activation; + ACTIVATION lstm_activation; + COST_TYPE cost_type; + void(*forward) (struct layer, struct network_state); + void(*backward) (struct layer, struct network_state); + void(*update) (struct layer, int, float, float, float); + void(*forward_gpu) (struct layer, struct network_state); + void(*backward_gpu) (struct layer, struct network_state); + void(*update_gpu) (struct layer, int, float, float, float, float); + layer *share_layer; + int train; + int avgpool; + int batch_normalize; + int shortcut; + int batch; + int dynamic_minibatch; + int forced; + int flipped; + int inputs; + int outputs; + float mean_alpha; + int nweights; + int nbiases; + int extra; + int truths; + int h, w, c; + int out_h, out_w, out_c; + int n; + int max_boxes; + int truth_size; + int groups; + int group_id; + int size; + int side; + int stride; + int stride_x; + int stride_y; + int dilation; + int antialiasing; + int maxpool_depth; + int maxpool_zero_nonmax; + int out_channels; + float reverse; + int coordconv; + int flatten; + int spatial; + int pad; + int sqrt; + int flip; + int index; + int scale_wh; + int binary; + int xnor; + int peephole; + int use_bin_output; + int keep_delta_gpu; + int optimized_memory; + int steps; + int history_size; + int bottleneck; + float time_normalizer; + int state_constrain; + int hidden; + int truth; + float smooth; + float dot; + int deform; + int grad_centr; + int sway; + int rotate; + int stretch; + int stretch_sway; + float angle; + float jitter; + float resize; + float saturation; + float exposure; + float shift; + float ratio; + float learning_rate_scale; + float clip; + int focal_loss; + float *classes_multipliers; + float label_smooth_eps; + int noloss; + int softmax; + int classes; + int detection; + int embedding_layer_id; + float *embedding_output; + int embedding_size; + float sim_thresh; + int track_history_size; + int dets_for_track; + int dets_for_show; + float track_ciou_norm; + int coords; + int background; + int rescore; + int objectness; + int does_cost; + int joint; + int noadjust; + int reorg; + int log; + int tanh; + int *mask; + int total; + float bflops; + + int adam; + float B1; + float B2; + float eps; + + int t; + + float alpha; + float beta; + float kappa; + + float coord_scale; + float object_scale; + float noobject_scale; + float mask_scale; + float class_scale; + int bias_match; + float random; + float ignore_thresh; + float truth_thresh; + float iou_thresh; + float thresh; + float focus; + int classfix; + int absolute; + int assisted_excitation; + + int onlyforward; + int stopbackward; + int train_only_bn; + int dont_update; + int burnin_update; + int dontload; + int dontsave; + int dontloadscales; + int numload; + + float temperature; + float probability; + float dropblock_size_rel; + int dropblock_size_abs; + int dropblock; + float scale; + + int receptive_w; + int receptive_h; + int receptive_w_scale; + int receptive_h_scale; + + char * cweights; + int * indexes; + int * input_layers; + int * input_sizes; + float **layers_output; + float **layers_delta; + WEIGHTS_TYPE_T weights_type; + WEIGHTS_NORMALIZATION_T weights_normalization; + int * map; + int * counts; + float ** sums; + float * rand; + float * cost; + int *labels; + int *class_ids; + int contrastive_neg_max; + float *cos_sim; + float *exp_cos_sim; + float *p_constrastive; + contrastive_params *contrast_p_gpu; + float * state; + float * prev_state; + float * forgot_state; + float * forgot_delta; + float * state_delta; + float * combine_cpu; + float * combine_delta_cpu; + + float *concat; + float *concat_delta; + + float *binary_weights; + + float *biases; + float *bias_updates; + + float *scales; + float *scale_updates; + + float *weights_ema; + float *biases_ema; + float *scales_ema; + + float *weights; + float *weight_updates; + + float scale_x_y; + int objectness_smooth; + int new_coords; + int show_details; + float max_delta; + float uc_normalizer; + float iou_normalizer; + float obj_normalizer; + float cls_normalizer; + float delta_normalizer; + IOU_LOSS iou_loss; + IOU_LOSS iou_thresh_kind; + NMS_KIND nms_kind; + float beta_nms; + YOLO_POINT yolo_point; + + char *align_bit_weights_gpu; + float *mean_arr_gpu; + float *align_workspace_gpu; + float *transposed_align_workspace_gpu; + int align_workspace_size; + + char *align_bit_weights; + float *mean_arr; + int align_bit_weights_size; + int lda_align; + int new_lda; + int bit_align; + + float *col_image; + float * delta; + float * output; + float * activation_input; + int delta_pinned; + int output_pinned; + float * loss; + float * squared; + float * norms; + + float * spatial_mean; + float * mean; + float * variance; + + float * mean_delta; + float * variance_delta; + + float * rolling_mean; + float * rolling_variance; + + float * x; + float * x_norm; + + float * m; + float * v; + + float * bias_m; + float * bias_v; + float * scale_m; + float * scale_v; + + + float *z_cpu; + float *r_cpu; + float *h_cpu; + float *stored_h_cpu; + float * prev_state_cpu; + + float *temp_cpu; + float *temp2_cpu; + float *temp3_cpu; + + float *dh_cpu; + float *hh_cpu; + float *prev_cell_cpu; + float *cell_cpu; + float *f_cpu; + float *i_cpu; + float *g_cpu; + float *o_cpu; + float *c_cpu; + float *stored_c_cpu; + float *dc_cpu; + + float *binary_input; + uint32_t *bin_re_packed_input; + char *t_bit_input; + + struct layer *input_layer; + struct layer *self_layer; + struct layer *output_layer; + + struct layer *reset_layer; + struct layer *update_layer; + struct layer *state_layer; + + struct layer *input_gate_layer; + struct layer *state_gate_layer; + struct layer *input_save_layer; + struct layer *state_save_layer; + struct layer *input_state_layer; + struct layer *state_state_layer; + + struct layer *input_z_layer; + struct layer *state_z_layer; + + struct layer *input_r_layer; + struct layer *state_r_layer; + + struct layer *input_h_layer; + struct layer *state_h_layer; + + struct layer *wz; + struct layer *uz; + struct layer *wr; + struct layer *ur; + struct layer *wh; + struct layer *uh; + struct layer *uo; + struct layer *wo; + struct layer *vo; + struct layer *uf; + struct layer *wf; + struct layer *vf; + struct layer *ui; + struct layer *wi; + struct layer *vi; + struct layer *ug; + struct layer *wg; + + tree *softmax_tree; + + size_t workspace_size; + +//#ifdef GPU + int *indexes_gpu; + + int stream; + int wait_stream_id; + + float *z_gpu; + float *r_gpu; + float *h_gpu; + float *stored_h_gpu; + float *bottelneck_hi_gpu; + float *bottelneck_delta_gpu; + + float *temp_gpu; + float *temp2_gpu; + float *temp3_gpu; + + float *dh_gpu; + float *hh_gpu; + float *prev_cell_gpu; + float *prev_state_gpu; + float *last_prev_state_gpu; + float *last_prev_cell_gpu; + float *cell_gpu; + float *f_gpu; + float *i_gpu; + float *g_gpu; + float *o_gpu; + float *c_gpu; + float *stored_c_gpu; + float *dc_gpu; + + // adam + float *m_gpu; + float *v_gpu; + float *bias_m_gpu; + float *scale_m_gpu; + float *bias_v_gpu; + float *scale_v_gpu; + + float * combine_gpu; + float * combine_delta_gpu; + + float * forgot_state_gpu; + float * forgot_delta_gpu; + float * state_gpu; + float * state_delta_gpu; + float * gate_gpu; + float * gate_delta_gpu; + float * save_gpu; + float * save_delta_gpu; + float * concat_gpu; + float * concat_delta_gpu; + + float *binary_input_gpu; + float *binary_weights_gpu; + float *bin_conv_shortcut_in_gpu; + float *bin_conv_shortcut_out_gpu; + + float * mean_gpu; + float * variance_gpu; + float * m_cbn_avg_gpu; + float * v_cbn_avg_gpu; + + float * rolling_mean_gpu; + float * rolling_variance_gpu; + + float * variance_delta_gpu; + float * mean_delta_gpu; + + float * col_image_gpu; + + float * x_gpu; + float * x_norm_gpu; + float * weights_gpu; + float * weight_updates_gpu; + float * weight_deform_gpu; + float * weight_change_gpu; + + float * weights_gpu16; + float * weight_updates_gpu16; + + float * biases_gpu; + float * bias_updates_gpu; + float * bias_change_gpu; + + float * scales_gpu; + float * scale_updates_gpu; + float * scale_change_gpu; + + float * input_antialiasing_gpu; + float * output_gpu; + float * output_avg_gpu; + float * activation_input_gpu; + float * loss_gpu; + float * delta_gpu; + float * cos_sim_gpu; + float * rand_gpu; + float * drop_blocks_scale; + float * drop_blocks_scale_gpu; + float * squared_gpu; + float * norms_gpu; + + float *gt_gpu; + float *a_avg_gpu; + + int *input_sizes_gpu; + float **layers_output_gpu; + float **layers_delta_gpu; +#ifdef CUDNN + cudnnTensorDescriptor_t srcTensorDesc, dstTensorDesc; + cudnnTensorDescriptor_t srcTensorDesc16, dstTensorDesc16; + cudnnTensorDescriptor_t dsrcTensorDesc, ddstTensorDesc; + cudnnTensorDescriptor_t dsrcTensorDesc16, ddstTensorDesc16; + cudnnTensorDescriptor_t normTensorDesc, normDstTensorDesc, normDstTensorDescF16; + cudnnFilterDescriptor_t weightDesc, weightDesc16; + cudnnFilterDescriptor_t dweightDesc, dweightDesc16; + cudnnConvolutionDescriptor_t convDesc; + cudnnConvolutionFwdAlgo_t fw_algo, fw_algo16; + cudnnConvolutionBwdDataAlgo_t bd_algo, bd_algo16; + cudnnConvolutionBwdFilterAlgo_t bf_algo, bf_algo16; + cudnnPoolingDescriptor_t poolingDesc; +#else // CUDNN + void* srcTensorDesc, *dstTensorDesc; + void* srcTensorDesc16, *dstTensorDesc16; + void* dsrcTensorDesc, *ddstTensorDesc; + void* dsrcTensorDesc16, *ddstTensorDesc16; + void* normTensorDesc, *normDstTensorDesc, *normDstTensorDescF16; + void* weightDesc, *weightDesc16; + void* dweightDesc, *dweightDesc16; + void* convDesc; + UNUSED_ENUM_TYPE fw_algo, fw_algo16; + UNUSED_ENUM_TYPE bd_algo, bd_algo16; + UNUSED_ENUM_TYPE bf_algo, bf_algo16; + void* poolingDesc; +#endif // CUDNN +//#endif // GPU +}; + + +// network.h +typedef enum { + CONSTANT, STEP, EXP, POLY, STEPS, SIG, RANDOM, SGDR +} learning_rate_policy; + +// network.h +typedef struct network { + int n; + int batch; + uint64_t *seen; + float *badlabels_reject_threshold; + float *delta_rolling_max; + float *delta_rolling_avg; + float *delta_rolling_std; + int weights_reject_freq; + int equidistant_point; + float badlabels_rejection_percentage; + float num_sigmas_reject_badlabels; + float ema_alpha; + int *cur_iteration; + float loss_scale; + int *t; + float epoch; + int subdivisions; + layer *layers; + float *output; + learning_rate_policy policy; + int benchmark_layers; + int *total_bbox; + int *rewritten_bbox; + + float learning_rate; + float learning_rate_min; + float learning_rate_max; + int batches_per_cycle; + int batches_cycle_mult; + float momentum; + float decay; + float gamma; + float scale; + float power; + int time_steps; + int step; + int max_batches; + int num_boxes; + int train_images_num; + float *seq_scales; + float *scales; + int *steps; + int num_steps; + int burn_in; + int cudnn_half; + + int adam; + float B1; + float B2; + float eps; + + int inputs; + int outputs; + int truths; + int notruth; + int h, w, c; + int max_crop; + int min_crop; + float max_ratio; + float min_ratio; + int center; + int flip; // horizontal flip 50% probability augmentaiont for classifier training (default = 1) + int gaussian_noise; + int blur; + int mixup; + float label_smooth_eps; + int resize_step; + int attention; + int adversarial; + float adversarial_lr; + float max_chart_loss; + int letter_box; + int mosaic_bound; + int contrastive; + int contrastive_jit_flip; + int contrastive_color; + int unsupervised; + float angle; + float aspect; + float exposure; + float saturation; + float hue; + int random; + int track; + int augment_speed; + int sequential_subdivisions; + int init_sequential_subdivisions; + int current_subdivision; + int try_fix_nan; + + int gpu_index; + tree *hierarchy; + + float *input; + float *truth; + float *delta; + float *workspace; + int train; + int index; + float *cost; + float clip; + +//#ifdef GPU + //float *input_gpu; + //float *truth_gpu; + float *delta_gpu; + float *output_gpu; + + float *input_state_gpu; + float *input_pinned_cpu; + int input_pinned_cpu_flag; + + float **input_gpu; + float **truth_gpu; + float **input16_gpu; + float **output16_gpu; + size_t *max_input16_size; + size_t *max_output16_size; + int wait_stream; + + void *cuda_graph; + void *cuda_graph_exec; + int use_cuda_graph; + int *cuda_graph_ready; + + float *global_delta_gpu; + float *state_delta_gpu; + size_t max_delta_gpu_size; +//#endif // GPU + int optimized_memory; + int dynamic_minibatch; + size_t workspace_size_limit; +} network; + +// network.h +typedef struct network_state { + float *truth; + float *input; + float *delta; + float *workspace; + int train; + int index; + network net; +} network_state; + +//typedef struct { +// int w; +// int h; +// float scale; +// float rad; +// float dx; +// float dy; +// float aspect; +//} augment_args; + +// image.h +typedef struct image { + int w; + int h; + int c; + float *data; +} image; + +//typedef struct { +// int w; +// int h; +// int c; +// float *data; +//} image; + +// box.h +typedef struct box { + float x, y, w, h; +} box; + +// box.h +typedef struct boxabs { + float left, right, top, bot; +} boxabs; + +// box.h +typedef struct dxrep { + float dt, db, dl, dr; +} dxrep; + +// box.h +typedef struct ious { + float iou, giou, diou, ciou; + dxrep dx_iou; + dxrep dx_giou; +} ious; + + +// box.h +typedef struct detection{ + box bbox; + int classes; + int best_class_idx; + float *prob; + float *mask; + float objectness; + int sort_class; + float *uc; // Gaussian_YOLOv3 - tx,ty,tw,th uncertainty + int points; // bit-0 - center, bit-1 - top-left-corner, bit-2 - bottom-right-corner + float *embeddings; // embeddings for tracking + int embedding_size; + float sim; + int track_id; +} detection; + +// network.c -batch inference +typedef struct det_num_pair { + int num; + detection *dets; +} det_num_pair, *pdet_num_pair; + +// matrix.h +typedef struct matrix { + int rows, cols; + float **vals; +} matrix; + +// data.h +typedef struct data { + int w, h; + matrix X; + matrix y; + int shallow; + int *num_boxes; + box **boxes; +} data; + +// data.h +typedef enum { + CLASSIFICATION_DATA, DETECTION_DATA, CAPTCHA_DATA, REGION_DATA, IMAGE_DATA, COMPARE_DATA, WRITING_DATA, SWAG_DATA, TAG_DATA, OLD_CLASSIFICATION_DATA, STUDY_DATA, DET_DATA, SUPER_DATA, LETTERBOX_DATA, REGRESSION_DATA, SEGMENTATION_DATA, INSTANCE_DATA, ISEG_DATA +} data_type; + +// data.h +typedef struct load_args { + int threads; + char **paths; + char *path; + int n; + int m; + char **labels; + int h; + int w; + int c; // color depth + int out_w; + int out_h; + int nh; + int nw; + int num_boxes; + int truth_size; + int min, max, size; + int classes; + int background; + int scale; + int center; + int coords; + int mini_batch; + int track; + int augment_speed; + int letter_box; + int mosaic_bound; + int show_imgs; + int dontuse_opencv; + int contrastive; + int contrastive_jit_flip; + int contrastive_color; + float jitter; + float resize; + int flip; + int gaussian_noise; + int blur; + int mixup; + float label_smooth_eps; + float angle; + float aspect; + float saturation; + float exposure; + float hue; + data *d; + image *im; + image *resized; + data_type type; + tree *hierarchy; +} load_args; + +// data.h +typedef struct box_label { + int id; + int track_id; + float x, y, w, h; + float left, right, top, bottom; +} box_label; + +// list.h +//typedef struct node { +// void *val; +// struct node *next; +// struct node *prev; +//} node; + +// list.h +//typedef struct list { +// int size; +// node *front; +// node *back; +//} list; +// ----------------------------------------------------- + + +// parser.c +LIB_API network *load_network(char *cfg, char *weights, int clear); +LIB_API network *load_network_custom(char *cfg, char *weights, int clear, int batch); +LIB_API void free_network(network net); +LIB_API void free_network_ptr(network* net); + +// network.c +LIB_API load_args get_base_args(network *net); + +// box.h +LIB_API void do_nms_sort(detection *dets, int total, int classes, float thresh); +LIB_API void do_nms_obj(detection *dets, int total, int classes, float thresh); +LIB_API void diounms_sort(detection *dets, int total, int classes, float thresh, NMS_KIND nms_kind, float beta1); + +// network.h +LIB_API float *network_predict(network net, float *input); +LIB_API float *network_predict_ptr(network *net, float *input); +#ifdef CUDA_OPENGL_INTEGRATION +LIB_API float *network_predict_gl_texture(network *net, uint32_t texture_id); +#endif // CUDA_OPENGL_INTEGRATION + +LIB_API void set_batch_network(network *net, int b); +LIB_API detection *get_network_boxes(network *net, int w, int h, float thresh, float hier, int *map, int relative, int *num, int letter); +LIB_API det_num_pair* network_predict_batch(network *net, image im, int batch_size, int w, int h, float thresh, float hier, int *map, int relative, int letter); +LIB_API void free_detections(detection *dets, int n); +LIB_API void free_batch_detections(det_num_pair *det_num_pairs, int n); +LIB_API void fuse_conv_batchnorm(network net); +LIB_API void calculate_binary_weights(network net); +LIB_API char *detection_to_json(detection *dets, int nboxes, int classes, char **names, long long int frame_id, char *filename); + +LIB_API layer* get_network_layer(network* net, int i); +//LIB_API detection *get_network_boxes(network *net, int w, int h, float thresh, float hier, int *map, int relative, int *num, int letter); +LIB_API detection *make_network_boxes(network *net, float thresh, int *num); +LIB_API void reset_rnn(network *net); +LIB_API float *network_predict_image(network *net, image im); +LIB_API float *network_predict_image_letterbox(network *net, image im); +LIB_API float validate_detector_map(char *datacfg, char *cfgfile, char *weightfile, float thresh_calc_avg_iou, const float iou_thresh, const int map_points, int letter_box, network *existing_net); +LIB_API void train_detector(char *datacfg, char *cfgfile, char *weightfile, int *gpus, int ngpus, int clear, int dont_show, int calc_map, float thresh, float iou_thresh, int mjpeg_port, int show_imgs, int benchmark_layers, char* chart_path, int mAP_epochs); +LIB_API void test_detector(char *datacfg, char *cfgfile, char *weightfile, char *filename, float thresh, + float hier_thresh, int dont_show, int ext_output, int save_labels, char *outfile, int letter_box, int benchmark_layers); +LIB_API int network_width(network *net); +LIB_API int network_height(network *net); +LIB_API void optimize_picture(network *net, image orig, int max_layer, float scale, float rate, float thresh, int norm); + +// image.h +LIB_API void make_image_red(image im); +LIB_API image make_attention_image(int img_size, float *original_delta_cpu, float *original_input_cpu, int w, int h, int c, float alpha); +LIB_API image resize_image(image im, int w, int h); +LIB_API void quantize_image(image im); +LIB_API void copy_image_from_bytes(image im, char *pdata); +LIB_API image letterbox_image(image im, int w, int h); +LIB_API void rgbgr_image(image im); +LIB_API image make_image(int w, int h, int c); +LIB_API image load_image_color(char *filename, int w, int h); +LIB_API void free_image(image m); +LIB_API image crop_image(image im, int dx, int dy, int w, int h); +LIB_API image resize_min(image im, int min); + +// layer.h +LIB_API void free_layer_custom(layer l, int keep_cudnn_desc); +LIB_API void free_layer(layer l); + +// data.c +LIB_API void free_data(data d); +LIB_API pthread_t load_data(load_args args); +LIB_API void free_load_threads(void *ptr); +LIB_API pthread_t load_data_in_thread(load_args args); +LIB_API void *load_thread(void *ptr); + +// dark_cuda.h +LIB_API void cuda_pull_array(float *x_gpu, float *x, size_t n); +LIB_API void cuda_pull_array_async(float *x_gpu, float *x, size_t n); +LIB_API void cuda_set_device(int n); +LIB_API void *cuda_get_context(); + +// utils.h +LIB_API void free_ptrs(void **ptrs, int n); +LIB_API void top_k(float *a, int n, int k, int *index); + +// tree.h +LIB_API tree *read_tree(char *filename); + +// option_list.h +LIB_API metadata get_metadata(char *file); + + +// http_stream.h +LIB_API void delete_json_sender(); +LIB_API void send_json_custom(char const* send_buf, int port, int timeout); +LIB_API double get_time_point(); +void start_timer(); +void stop_timer(); +double get_time(); +void stop_timer_and_show(); +void stop_timer_and_show_name(char *name); +void show_total_time(); + +LIB_API void set_track_id(detection *new_dets, int new_dets_num, float thresh, float sim_thresh, float track_ciou_norm, int deque_size, int dets_for_track, int dets_for_show); +LIB_API int fill_remaining_id(detection *new_dets, int new_dets_num, int new_track_id, float thresh); + + +// gemm.h +LIB_API void init_cpu(); + +#ifdef __cplusplus +} +#endif // __cplusplus +#endif // DARKNET_API diff --git a/ODHUBYOLODarknet_old/include/yolo_v2_class.hpp b/ODHUBYOLODarknet_old/include/yolo_v2_class.hpp new file mode 100644 index 00000000..34662b02 --- /dev/null +++ b/ODHUBYOLODarknet_old/include/yolo_v2_class.hpp @@ -0,0 +1,1044 @@ +#ifndef YOLO_V2_CLASS_HPP +#define YOLO_V2_CLASS_HPP + +#ifndef LIB_API +#ifdef LIB_EXPORTS +#if defined(_MSC_VER) +#define LIB_API __declspec(dllexport) +#else +#define LIB_API __attribute__((visibility("default"))) +#endif +#else +#if defined(_MSC_VER) +#define LIB_API +#else +#define LIB_API +#endif +#endif +#endif + +#define C_SHARP_MAX_OBJECTS 1000 + +struct bbox_t { + unsigned int x, y, w, h; // (x,y) - top-left corner, (w, h) - width & height of bounded box + float prob; // confidence - probability that the object was found correctly + unsigned int obj_id; // class of object - from range [0, classes-1] + unsigned int track_id; // tracking id for video (0 - untracked, 1 - inf - tracked object) + unsigned int frames_counter; // counter of frames on which the object was detected + float x_3d, y_3d, z_3d; // center of object (in Meters) if ZED 3D Camera is used +}; + +struct image_t { + int h; // height + int w; // width + int c; // number of chanels (3 - for RGB) + float *data; // pointer to the image data +}; + +struct bbox_t_container { + bbox_t candidates[C_SHARP_MAX_OBJECTS]; +}; + +#ifdef __cplusplus +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include // C++ +#include // C +#include // C + +extern "C" LIB_API int init(const char *configurationFilename, const char *weightsFilename, int gpu, int batch_size); +extern "C" LIB_API int detect_image(const char *filename, bbox_t_container &container); +extern "C" LIB_API int detect_mat(const uint8_t* data, const size_t data_length, bbox_t_container &container); +extern "C" LIB_API int dispose(); +extern "C" LIB_API int get_device_count(bool useGPU); +extern "C" LIB_API int get_device_name(int gpu, char* deviceName); +extern "C" LIB_API bool built_with_cuda(bool useGPU); +extern "C" LIB_API bool built_with_cudnn(bool useGPU); +extern "C" LIB_API bool built_with_opencv(); +extern "C" LIB_API void send_json_custom(char const* send_buf, int port, int timeout); + +class Detector { + std::shared_ptr detector_gpu_ptr; + std::deque> prev_bbox_vec_deque; + std::string _cfg_filename, _weight_filename; +private: + bool _useGPU; +public: + int cur_gpu_id; + float nms = .4; + bool wait_stream; + LIB_API Detector(); + LIB_API Detector(std::string cfg_filename, std::string weight_filename, int gpu_id = 0, int batch_size = 1); + LIB_API ~Detector(); + + LIB_API void Init(std::string cfg_filename, std::string weight_filename, int gpu_id = 0, int batch_size = 1); + LIB_API std::vector detect(std::string image_filename, float thresh = 0.2, bool use_mean = false); + LIB_API std::vector detect(image_t img, float thresh = 0.2, bool use_mean = false); + LIB_API std::vector> detectBatch(image_t img, int batch_size, int width, int height, float thresh, bool make_nms = true); + static LIB_API image_t load_image(std::string image_filename); + static LIB_API void free_image(image_t m); + LIB_API int get_net_width() const; + LIB_API int get_net_height() const; + LIB_API int get_net_color_depth() const; + + LIB_API std::vector tracking_id(std::vector cur_bbox_vec, bool const change_history = true, + int const frames_story = 5, int const max_dist = 40); + + LIB_API void *get_cuda_context(); + + //LIB_API bool send_json_http(std::vector cur_bbox_vec, std::vector obj_names, int frame_id, + // std::string filename = std::string(), int timeout = 400000, int port = 8070); + + std::vector detect_resized(image_t img, int init_w, int init_h, float thresh = 0.2, bool use_mean = false) + { + if (img.data == NULL) + throw std::runtime_error("Image is empty"); + auto detection_boxes = detect(img, thresh, use_mean); + float wk = (float)init_w / img.w, hk = (float)init_h / img.h; + for (auto &i : detection_boxes) i.x *= wk, i.w *= wk, i.y *= hk, i.h *= hk; + return detection_boxes; + } + std::vector detect(cv::Mat mat, float thresh = 0.2, bool use_mean = false) + { + if(mat.data == NULL) + throw std::runtime_error("Image is empty"); + auto image_ptr = mat_to_image_resize(mat); + return detect_resized(*image_ptr, mat.cols, mat.rows, thresh, use_mean); + } + std::shared_ptr mat_to_image_resize(cv::Mat mat) const + { + if (mat.data == NULL) return std::shared_ptr(NULL); + + cv::Size network_size = cv::Size(get_net_width(), get_net_height()); + cv::Mat det_mat; + if (mat.size() != network_size) + cv::resize(mat, det_mat, network_size); + else + det_mat = mat; // only reference is copied + + return mat_to_image(det_mat); + } + static std::shared_ptr mat_to_image(cv::Mat img_src) + { + cv::Mat img; + if (img_src.channels() == 4) cv::cvtColor(img_src, img, cv::COLOR_RGBA2BGR); + else if (img_src.channels() == 3) cv::cvtColor(img_src, img, cv::COLOR_RGB2BGR); + else if (img_src.channels() == 1) cv::cvtColor(img_src, img, cv::COLOR_GRAY2BGR); + else std::cerr << " Warning: img_src.channels() is not 1, 3 or 4. It is = " << img_src.channels() << std::endl; + std::shared_ptr image_ptr(new image_t, [](image_t *img) { free_image(*img); delete img; }); + *image_ptr = mat_to_image_custom(img); + return image_ptr; + } + +private: + + static image_t mat_to_image_custom(cv::Mat mat) + { + int w = mat.cols; + int h = mat.rows; + int c = mat.channels(); + image_t im = make_image_custom(w, h, c); + unsigned char *data = (unsigned char *)mat.data; + int step = mat.step; + for (int y = 0; y < h; ++y) { + for (int k = 0; k < c; ++k) { + for (int x = 0; x < w; ++x) { + im.data[k*w*h + y*w + x] = data[y*step + x*c + k] / 255.0f; + } + } + } + return im; + } + static image_t make_empty_image(int w, int h, int c) + { + image_t out; + out.data = 0; + out.h = h; + out.w = w; + out.c = c; + return out; + } + static image_t make_image_custom(int w, int h, int c) + { + image_t out = make_empty_image(w, h, c); + out.data = (float *)calloc(h*w*c, sizeof(float)); + return out; + } + + +public: + + bool send_json_http(std::vector cur_bbox_vec, std::vector obj_names, int frame_id, + std::string filename = std::string(), int timeout = 400000, int port = 8070) + { + std::string send_str; + + char *tmp_buf = (char *)calloc(1024, sizeof(char)); + if (!filename.empty()) { + sprintf(tmp_buf, "{\n \"frame_id\":%d, \n \"filename\":\"%s\", \n \"objects\": [ \n", frame_id, filename.c_str()); + } + else { + sprintf(tmp_buf, "{\n \"frame_id\":%d, \n \"objects\": [ \n", frame_id); + } + send_str = tmp_buf; + free(tmp_buf); + + for (auto & i : cur_bbox_vec) { + char *buf = (char *)calloc(2048, sizeof(char)); + + sprintf(buf, " {\"class_id\":%d, \"name\":\"%s\", \"absolute_coordinates\":{\"center_x\":%d, \"center_y\":%d, \"width\":%d, \"height\":%d}, \"confidence\":%f", + i.obj_id, obj_names[i.obj_id].c_str(), i.x, i.y, i.w, i.h, i.prob); + + //sprintf(buf, " {\"class_id\":%d, \"name\":\"%s\", \"relative_coordinates\":{\"center_x\":%f, \"center_y\":%f, \"width\":%f, \"height\":%f}, \"confidence\":%f", + // i.obj_id, obj_names[i.obj_id], i.x, i.y, i.w, i.h, i.prob); + + send_str += buf; + + if (!std::isnan(i.z_3d)) { + sprintf(buf, "\n , \"coordinates_in_meters\":{\"x_3d\":%.2f, \"y_3d\":%.2f, \"z_3d\":%.2f}", + i.x_3d, i.y_3d, i.z_3d); + send_str += buf; + } + + send_str += "}\n"; + + free(buf); + } + + //send_str += "\n ] \n}, \n"; + send_str += "\n ] \n}"; + + send_json_custom(send_str.c_str(), port, timeout); + return true; + } +}; +// -------------------------------------------------------------------------------- + + +#if defined(TRACK_OPTFLOW) && defined(OPENCV) && defined(GPU) + +#include +#include +#include +#include + +class Tracker_optflow { +public: + const int gpu_count; + const int gpu_id; + const int flow_error; + + + Tracker_optflow(int _gpu_id = 0, int win_size = 15, int max_level = 3, int iterations = 8000, int _flow_error = -1) : + gpu_count(cv::cuda::getCudaEnabledDeviceCount()), gpu_id(std::min(_gpu_id, gpu_count-1)), + flow_error((_flow_error > 0)? _flow_error:(win_size*4)) + { + int const old_gpu_id = cv::cuda::getDevice(); + cv::cuda::setDevice(gpu_id); + + stream = cv::cuda::Stream(); + + sync_PyrLKOpticalFlow_gpu = cv::cuda::SparsePyrLKOpticalFlow::create(); + sync_PyrLKOpticalFlow_gpu->setWinSize(cv::Size(win_size, win_size)); // 9, 15, 21, 31 + sync_PyrLKOpticalFlow_gpu->setMaxLevel(max_level); // +- 3 pt + sync_PyrLKOpticalFlow_gpu->setNumIters(iterations); // 2000, def: 30 + + cv::cuda::setDevice(old_gpu_id); + } + + // just to avoid extra allocations + cv::cuda::GpuMat src_mat_gpu; + cv::cuda::GpuMat dst_mat_gpu, dst_grey_gpu; + cv::cuda::GpuMat prev_pts_flow_gpu, cur_pts_flow_gpu; + cv::cuda::GpuMat status_gpu, err_gpu; + + cv::cuda::GpuMat src_grey_gpu; // used in both functions + cv::Ptr sync_PyrLKOpticalFlow_gpu; + cv::cuda::Stream stream; + + std::vector cur_bbox_vec; + std::vector good_bbox_vec_flags; + cv::Mat prev_pts_flow_cpu; + + void update_cur_bbox_vec(std::vector _cur_bbox_vec) + { + cur_bbox_vec = _cur_bbox_vec; + good_bbox_vec_flags = std::vector(cur_bbox_vec.size(), true); + cv::Mat prev_pts, cur_pts_flow_cpu; + + for (auto &i : cur_bbox_vec) { + float x_center = (i.x + i.w / 2.0F); + float y_center = (i.y + i.h / 2.0F); + prev_pts.push_back(cv::Point2f(x_center, y_center)); + } + + if (prev_pts.rows == 0) + prev_pts_flow_cpu = cv::Mat(); + else + cv::transpose(prev_pts, prev_pts_flow_cpu); + + if (prev_pts_flow_gpu.cols < prev_pts_flow_cpu.cols) { + prev_pts_flow_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), prev_pts_flow_cpu.type()); + cur_pts_flow_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), prev_pts_flow_cpu.type()); + + status_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), CV_8UC1); + err_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), CV_32FC1); + } + + prev_pts_flow_gpu.upload(cv::Mat(prev_pts_flow_cpu), stream); + } + + + void update_tracking_flow(cv::Mat src_mat, std::vector _cur_bbox_vec) + { + int const old_gpu_id = cv::cuda::getDevice(); + if (old_gpu_id != gpu_id) + cv::cuda::setDevice(gpu_id); + + if (src_mat.channels() == 1 || src_mat.channels() == 3 || src_mat.channels() == 4) { + if (src_mat_gpu.cols == 0) { + src_mat_gpu = cv::cuda::GpuMat(src_mat.size(), src_mat.type()); + src_grey_gpu = cv::cuda::GpuMat(src_mat.size(), CV_8UC1); + } + + if (src_mat.channels() == 1) { + src_mat_gpu.upload(src_mat, stream); + src_mat_gpu.copyTo(src_grey_gpu); + } + else if (src_mat.channels() == 3) { + src_mat_gpu.upload(src_mat, stream); + cv::cuda::cvtColor(src_mat_gpu, src_grey_gpu, CV_BGR2GRAY, 1, stream); + } + else if (src_mat.channels() == 4) { + src_mat_gpu.upload(src_mat, stream); + cv::cuda::cvtColor(src_mat_gpu, src_grey_gpu, CV_BGRA2GRAY, 1, stream); + } + else { + std::cerr << " Warning: src_mat.channels() is not: 1, 3 or 4. It is = " << src_mat.channels() << " \n"; + return; + } + + } + update_cur_bbox_vec(_cur_bbox_vec); + + if (old_gpu_id != gpu_id) + cv::cuda::setDevice(old_gpu_id); + } + + + std::vector tracking_flow(cv::Mat dst_mat, bool check_error = true) + { + if (sync_PyrLKOpticalFlow_gpu.empty()) { + std::cout << "sync_PyrLKOpticalFlow_gpu isn't initialized \n"; + return cur_bbox_vec; + } + + int const old_gpu_id = cv::cuda::getDevice(); + if(old_gpu_id != gpu_id) + cv::cuda::setDevice(gpu_id); + + if (dst_mat_gpu.cols == 0) { + dst_mat_gpu = cv::cuda::GpuMat(dst_mat.size(), dst_mat.type()); + dst_grey_gpu = cv::cuda::GpuMat(dst_mat.size(), CV_8UC1); + } + + //dst_grey_gpu.upload(dst_mat, stream); // use BGR + dst_mat_gpu.upload(dst_mat, stream); + cv::cuda::cvtColor(dst_mat_gpu, dst_grey_gpu, CV_BGR2GRAY, 1, stream); + + if (src_grey_gpu.rows != dst_grey_gpu.rows || src_grey_gpu.cols != dst_grey_gpu.cols) { + stream.waitForCompletion(); + src_grey_gpu = dst_grey_gpu.clone(); + cv::cuda::setDevice(old_gpu_id); + return cur_bbox_vec; + } + + ////sync_PyrLKOpticalFlow_gpu.sparse(src_grey_gpu, dst_grey_gpu, prev_pts_flow_gpu, cur_pts_flow_gpu, status_gpu, &err_gpu); // OpenCV 2.4.x + sync_PyrLKOpticalFlow_gpu->calc(src_grey_gpu, dst_grey_gpu, prev_pts_flow_gpu, cur_pts_flow_gpu, status_gpu, err_gpu, stream); // OpenCV 3.x + + cv::Mat cur_pts_flow_cpu; + cur_pts_flow_gpu.download(cur_pts_flow_cpu, stream); + + dst_grey_gpu.copyTo(src_grey_gpu, stream); + + cv::Mat err_cpu, status_cpu; + err_gpu.download(err_cpu, stream); + status_gpu.download(status_cpu, stream); + + stream.waitForCompletion(); + + std::vector result_bbox_vec; + + if (err_cpu.cols == cur_bbox_vec.size() && status_cpu.cols == cur_bbox_vec.size()) + { + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + { + cv::Point2f cur_key_pt = cur_pts_flow_cpu.at(0, i); + cv::Point2f prev_key_pt = prev_pts_flow_cpu.at(0, i); + + float moved_x = cur_key_pt.x - prev_key_pt.x; + float moved_y = cur_key_pt.y - prev_key_pt.y; + + if (abs(moved_x) < 100 && abs(moved_y) < 100 && good_bbox_vec_flags[i]) + if (err_cpu.at(0, i) < flow_error && status_cpu.at(0, i) != 0 && + ((float)cur_bbox_vec[i].x + moved_x) > 0 && ((float)cur_bbox_vec[i].y + moved_y) > 0) + { + cur_bbox_vec[i].x += moved_x + 0.5; + cur_bbox_vec[i].y += moved_y + 0.5; + result_bbox_vec.push_back(cur_bbox_vec[i]); + } + else good_bbox_vec_flags[i] = false; + else good_bbox_vec_flags[i] = false; + + //if(!check_error && !good_bbox_vec_flags[i]) result_bbox_vec.push_back(cur_bbox_vec[i]); + } + } + + cur_pts_flow_gpu.swap(prev_pts_flow_gpu); + cur_pts_flow_cpu.copyTo(prev_pts_flow_cpu); + + if (old_gpu_id != gpu_id) + cv::cuda::setDevice(old_gpu_id); + + return result_bbox_vec; + } + +}; + +#elif defined(TRACK_OPTFLOW) && defined(OPENCV) + +//#include +#include + +class Tracker_optflow { +public: + const int flow_error; + + + Tracker_optflow(int win_size = 15, int max_level = 3, int iterations = 8000, int _flow_error = -1) : + flow_error((_flow_error > 0)? _flow_error:(win_size*4)) + { + sync_PyrLKOpticalFlow = cv::SparsePyrLKOpticalFlow::create(); + sync_PyrLKOpticalFlow->setWinSize(cv::Size(win_size, win_size)); // 9, 15, 21, 31 + sync_PyrLKOpticalFlow->setMaxLevel(max_level); // +- 3 pt + + } + + // just to avoid extra allocations + cv::Mat dst_grey; + cv::Mat prev_pts_flow, cur_pts_flow; + cv::Mat status, err; + + cv::Mat src_grey; // used in both functions + cv::Ptr sync_PyrLKOpticalFlow; + + std::vector cur_bbox_vec; + std::vector good_bbox_vec_flags; + + void update_cur_bbox_vec(std::vector _cur_bbox_vec) + { + cur_bbox_vec = _cur_bbox_vec; + good_bbox_vec_flags = std::vector(cur_bbox_vec.size(), true); + cv::Mat prev_pts, cur_pts_flow; + + for (auto &i : cur_bbox_vec) { + float x_center = (i.x + i.w / 2.0F); + float y_center = (i.y + i.h / 2.0F); + prev_pts.push_back(cv::Point2f(x_center, y_center)); + } + + if (prev_pts.rows == 0) + prev_pts_flow = cv::Mat(); + else + cv::transpose(prev_pts, prev_pts_flow); + } + + + void update_tracking_flow(cv::Mat new_src_mat, std::vector _cur_bbox_vec) + { + if (new_src_mat.channels() == 1) { + src_grey = new_src_mat.clone(); + } + else if (new_src_mat.channels() == 3) { + cv::cvtColor(new_src_mat, src_grey, CV_BGR2GRAY, 1); + } + else if (new_src_mat.channels() == 4) { + cv::cvtColor(new_src_mat, src_grey, CV_BGRA2GRAY, 1); + } + else { + std::cerr << " Warning: new_src_mat.channels() is not: 1, 3 or 4. It is = " << new_src_mat.channels() << " \n"; + return; + } + update_cur_bbox_vec(_cur_bbox_vec); + } + + + std::vector tracking_flow(cv::Mat new_dst_mat, bool check_error = true) + { + if (sync_PyrLKOpticalFlow.empty()) { + std::cout << "sync_PyrLKOpticalFlow isn't initialized \n"; + return cur_bbox_vec; + } + + cv::cvtColor(new_dst_mat, dst_grey, CV_BGR2GRAY, 1); + + if (src_grey.rows != dst_grey.rows || src_grey.cols != dst_grey.cols) { + src_grey = dst_grey.clone(); + //std::cerr << " Warning: src_grey.rows != dst_grey.rows || src_grey.cols != dst_grey.cols \n"; + return cur_bbox_vec; + } + + if (prev_pts_flow.cols < 1) { + return cur_bbox_vec; + } + + ////sync_PyrLKOpticalFlow_gpu.sparse(src_grey_gpu, dst_grey_gpu, prev_pts_flow_gpu, cur_pts_flow_gpu, status_gpu, &err_gpu); // OpenCV 2.4.x + sync_PyrLKOpticalFlow->calc(src_grey, dst_grey, prev_pts_flow, cur_pts_flow, status, err); // OpenCV 3.x + + dst_grey.copyTo(src_grey); + + std::vector result_bbox_vec; + + if (err.rows == cur_bbox_vec.size() && status.rows == cur_bbox_vec.size()) + { + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + { + cv::Point2f cur_key_pt = cur_pts_flow.at(0, i); + cv::Point2f prev_key_pt = prev_pts_flow.at(0, i); + + float moved_x = cur_key_pt.x - prev_key_pt.x; + float moved_y = cur_key_pt.y - prev_key_pt.y; + + if (abs(moved_x) < 100 && abs(moved_y) < 100 && good_bbox_vec_flags[i]) + if (err.at(0, i) < flow_error && status.at(0, i) != 0 && + ((float)cur_bbox_vec[i].x + moved_x) > 0 && ((float)cur_bbox_vec[i].y + moved_y) > 0) + { + cur_bbox_vec[i].x += moved_x + 0.5; + cur_bbox_vec[i].y += moved_y + 0.5; + result_bbox_vec.push_back(cur_bbox_vec[i]); + } + else good_bbox_vec_flags[i] = false; + else good_bbox_vec_flags[i] = false; + + //if(!check_error && !good_bbox_vec_flags[i]) result_bbox_vec.push_back(cur_bbox_vec[i]); + } + } + + prev_pts_flow = cur_pts_flow.clone(); + + return result_bbox_vec; + } + +}; +#else + +class Tracker_optflow {}; + +#endif // defined(TRACK_OPTFLOW) && defined(OPENCV) + + + + +static cv::Scalar obj_id_to_color(int obj_id) { + int const colors[6][3] = { { 1,0,1 },{ 0,0,1 },{ 0,1,1 },{ 0,1,0 },{ 1,1,0 },{ 1,0,0 } }; + int const offset = obj_id * 123457 % 6; + int const color_scale = 150 + (obj_id * 123457) % 100; + cv::Scalar color(colors[offset][0], colors[offset][1], colors[offset][2]); + color *= color_scale; + return color; +} + +class preview_boxes_t { + enum { frames_history = 30 }; // how long to keep the history saved + + struct preview_box_track_t { + unsigned int track_id, obj_id, last_showed_frames_ago; + bool current_detection; + bbox_t bbox; + cv::Mat mat_obj, mat_resized_obj; + preview_box_track_t() : track_id(0), obj_id(0), last_showed_frames_ago(frames_history), current_detection(false) {} + }; + std::vector preview_box_track_id; + size_t const preview_box_size, bottom_offset; + bool const one_off_detections; +public: + preview_boxes_t(size_t _preview_box_size = 100, size_t _bottom_offset = 100, bool _one_off_detections = false) : + preview_box_size(_preview_box_size), bottom_offset(_bottom_offset), one_off_detections(_one_off_detections) + {} + + void set(cv::Mat src_mat, std::vector result_vec) + { + size_t const count_preview_boxes = src_mat.cols / preview_box_size; + if (preview_box_track_id.size() != count_preview_boxes) preview_box_track_id.resize(count_preview_boxes); + + // increment frames history + for (auto &i : preview_box_track_id) + i.last_showed_frames_ago = std::min((unsigned)frames_history, i.last_showed_frames_ago + 1); + + // occupy empty boxes + for (auto &k : result_vec) { + bool found = false; + // find the same (track_id) + for (auto &i : preview_box_track_id) { + if (i.track_id == k.track_id) { + if (!one_off_detections) i.last_showed_frames_ago = 0; // for tracked objects + found = true; + break; + } + } + if (!found) { + // find empty box + for (auto &i : preview_box_track_id) { + if (i.last_showed_frames_ago == frames_history) { + if (!one_off_detections && k.frames_counter == 0) break; // don't show if obj isn't tracked yet + i.track_id = k.track_id; + i.obj_id = k.obj_id; + i.bbox = k; + i.last_showed_frames_ago = 0; + break; + } + } + } + } + + // draw preview box (from old or current frame) + for (size_t i = 0; i < preview_box_track_id.size(); ++i) + { + // get object image + cv::Mat dst = preview_box_track_id[i].mat_resized_obj; + preview_box_track_id[i].current_detection = false; + + for (auto &k : result_vec) { + if (preview_box_track_id[i].track_id == k.track_id) { + if (one_off_detections && preview_box_track_id[i].last_showed_frames_ago > 0) { + preview_box_track_id[i].last_showed_frames_ago = frames_history; break; + } + bbox_t b = k; + cv::Rect r(b.x, b.y, b.w, b.h); + cv::Rect img_rect(cv::Point2i(0, 0), src_mat.size()); + cv::Rect rect_roi = r & img_rect; + if (rect_roi.width > 1 || rect_roi.height > 1) { + cv::Mat roi = src_mat(rect_roi); + cv::resize(roi, dst, cv::Size(preview_box_size, preview_box_size), cv::INTER_NEAREST); + preview_box_track_id[i].mat_obj = roi.clone(); + preview_box_track_id[i].mat_resized_obj = dst.clone(); + preview_box_track_id[i].current_detection = true; + preview_box_track_id[i].bbox = k; + } + break; + } + } + } + } + + + void draw(cv::Mat draw_mat, bool show_small_boxes = false) + { + // draw preview box (from old or current frame) + for (size_t i = 0; i < preview_box_track_id.size(); ++i) + { + auto &prev_box = preview_box_track_id[i]; + + // draw object image + cv::Mat dst = prev_box.mat_resized_obj; + if (prev_box.last_showed_frames_ago < frames_history && + dst.size() == cv::Size(preview_box_size, preview_box_size)) + { + cv::Rect dst_rect_roi(cv::Point2i(i * preview_box_size, draw_mat.rows - bottom_offset), dst.size()); + cv::Mat dst_roi = draw_mat(dst_rect_roi); + dst.copyTo(dst_roi); + + cv::Scalar color = obj_id_to_color(prev_box.obj_id); + int thickness = (prev_box.current_detection) ? 5 : 1; + cv::rectangle(draw_mat, dst_rect_roi, color, thickness); + + unsigned int const track_id = prev_box.track_id; + std::string track_id_str = (track_id > 0) ? std::to_string(track_id) : ""; + putText(draw_mat, track_id_str, dst_rect_roi.tl() - cv::Point2i(-4, 5), cv::FONT_HERSHEY_COMPLEX_SMALL, 0.9, cv::Scalar(0, 0, 0), 2); + + std::string size_str = std::to_string(prev_box.bbox.w) + "x" + std::to_string(prev_box.bbox.h); + putText(draw_mat, size_str, dst_rect_roi.tl() + cv::Point2i(0, 12), cv::FONT_HERSHEY_COMPLEX_SMALL, 0.8, cv::Scalar(0, 0, 0), 1); + + if (!one_off_detections && prev_box.current_detection) { + cv::line(draw_mat, dst_rect_roi.tl() + cv::Point2i(preview_box_size, 0), + cv::Point2i(prev_box.bbox.x, prev_box.bbox.y + prev_box.bbox.h), + color); + } + + if (one_off_detections && show_small_boxes) { + cv::Rect src_rect_roi(cv::Point2i(prev_box.bbox.x, prev_box.bbox.y), + cv::Size(prev_box.bbox.w, prev_box.bbox.h)); + unsigned int const color_history = (255 * prev_box.last_showed_frames_ago) / frames_history; + color = cv::Scalar(255 - 3 * color_history, 255 - 2 * color_history, 255 - 1 * color_history); + if (prev_box.mat_obj.size() == src_rect_roi.size()) { + prev_box.mat_obj.copyTo(draw_mat(src_rect_roi)); + } + cv::rectangle(draw_mat, src_rect_roi, color, thickness); + putText(draw_mat, track_id_str, src_rect_roi.tl() - cv::Point2i(0, 10), cv::FONT_HERSHEY_COMPLEX_SMALL, 0.8, cv::Scalar(0, 0, 0), 1); + } + } + } + } +}; + + +class track_kalman_t +{ + int track_id_counter; + std::chrono::steady_clock::time_point global_last_time; + float dT; + +public: + int max_objects; // max objects for tracking + int min_frames; // min frames to consider an object as detected + const float max_dist; // max distance (in px) to track with the same ID + cv::Size img_size; // max value of x,y,w,h + + struct tst_t { + int track_id; + int state_id; + std::chrono::steady_clock::time_point last_time; + int detection_count; + tst_t() : track_id(-1), state_id(-1) {} + }; + std::vector track_id_state_id_time; + std::vector result_vec_pred; + + struct one_kalman_t; + std::vector kalman_vec; + + struct one_kalman_t + { + cv::KalmanFilter kf; + cv::Mat state; + cv::Mat meas; + int measSize, stateSize, contrSize; + + void set_delta_time(float dT) { + kf.transitionMatrix.at(2) = dT; + kf.transitionMatrix.at(9) = dT; + } + + void set(bbox_t box) + { + initialize_kalman(); + + kf.errorCovPre.at(0) = 1; // px + kf.errorCovPre.at(7) = 1; // px + kf.errorCovPre.at(14) = 1; + kf.errorCovPre.at(21) = 1; + kf.errorCovPre.at(28) = 1; // px + kf.errorCovPre.at(35) = 1; // px + + state.at(0) = box.x; + state.at(1) = box.y; + state.at(2) = 0; + state.at(3) = 0; + state.at(4) = box.w; + state.at(5) = box.h; + // <<<< Initialization + + kf.statePost = state; + } + + // Kalman.correct() calculates: statePost = statePre + gain * (z(k)-measurementMatrix*statePre); + // corrected state (x(k)): x(k)=x'(k)+K(k)*(z(k)-H*x'(k)) + void correct(bbox_t box) { + meas.at(0) = box.x; + meas.at(1) = box.y; + meas.at(2) = box.w; + meas.at(3) = box.h; + + kf.correct(meas); + + bbox_t new_box = predict(); + if (new_box.w == 0 || new_box.h == 0) { + set(box); + //std::cerr << " force set(): track_id = " << box.track_id << + // ", x = " << box.x << ", y = " << box.y << ", w = " << box.w << ", h = " << box.h << std::endl; + } + } + + // Kalman.predict() calculates: statePre = TransitionMatrix * statePost; + // predicted state (x'(k)): x(k)=A*x(k-1)+B*u(k) + bbox_t predict() { + bbox_t box; + state = kf.predict(); + + box.x = state.at(0); + box.y = state.at(1); + box.w = state.at(4); + box.h = state.at(5); + return box; + } + + void initialize_kalman() + { + kf = cv::KalmanFilter(stateSize, measSize, contrSize, CV_32F); + + // Transition State Matrix A + // Note: set dT at each processing step! + // [ 1 0 dT 0 0 0 ] + // [ 0 1 0 dT 0 0 ] + // [ 0 0 1 0 0 0 ] + // [ 0 0 0 1 0 0 ] + // [ 0 0 0 0 1 0 ] + // [ 0 0 0 0 0 1 ] + cv::setIdentity(kf.transitionMatrix); + + // Measure Matrix H + // [ 1 0 0 0 0 0 ] + // [ 0 1 0 0 0 0 ] + // [ 0 0 0 0 1 0 ] + // [ 0 0 0 0 0 1 ] + kf.measurementMatrix = cv::Mat::zeros(measSize, stateSize, CV_32F); + kf.measurementMatrix.at(0) = 1.0f; + kf.measurementMatrix.at(7) = 1.0f; + kf.measurementMatrix.at(16) = 1.0f; + kf.measurementMatrix.at(23) = 1.0f; + + // Process Noise Covariance Matrix Q - result smoother with lower values (1e-2) + // [ Ex 0 0 0 0 0 ] + // [ 0 Ey 0 0 0 0 ] + // [ 0 0 Ev_x 0 0 0 ] + // [ 0 0 0 Ev_y 0 0 ] + // [ 0 0 0 0 Ew 0 ] + // [ 0 0 0 0 0 Eh ] + //cv::setIdentity(kf.processNoiseCov, cv::Scalar(1e-3)); + kf.processNoiseCov.at(0) = 1e-2; + kf.processNoiseCov.at(7) = 1e-2; + kf.processNoiseCov.at(14) = 1e-2;// 5.0f; + kf.processNoiseCov.at(21) = 1e-2;// 5.0f; + kf.processNoiseCov.at(28) = 5e-3; + kf.processNoiseCov.at(35) = 5e-3; + + // Measures Noise Covariance Matrix R - result smoother with higher values (1e-1) + cv::setIdentity(kf.measurementNoiseCov, cv::Scalar(1e-1)); + + //cv::setIdentity(kf.errorCovPost, cv::Scalar::all(1e-2)); + // <<<< Kalman Filter + + set_delta_time(0); + } + + + one_kalman_t(int _stateSize = 6, int _measSize = 4, int _contrSize = 0) : + kf(_stateSize, _measSize, _contrSize, CV_32F), measSize(_measSize), stateSize(_stateSize), contrSize(_contrSize) + { + state = cv::Mat(stateSize, 1, CV_32F); // [x,y,v_x,v_y,w,h] + meas = cv::Mat(measSize, 1, CV_32F); // [z_x,z_y,z_w,z_h] + //cv::Mat procNoise(stateSize, 1, type) + // [E_x,E_y,E_v_x,E_v_y,E_w,E_h] + + initialize_kalman(); + } + }; + // ------------------------------------------ + + + + track_kalman_t(int _max_objects = 1000, int _min_frames = 3, float _max_dist = 40, cv::Size _img_size = cv::Size(10000, 10000)) : + track_id_counter(0), max_objects(_max_objects), min_frames(_min_frames), max_dist(_max_dist), img_size(_img_size) + { + kalman_vec.resize(max_objects); + track_id_state_id_time.resize(max_objects); + result_vec_pred.resize(max_objects); + } + + float calc_dt() { + dT = std::chrono::duration(std::chrono::steady_clock::now() - global_last_time).count(); + return dT; + } + + static float get_distance(float src_x, float src_y, float dst_x, float dst_y) { + return sqrtf((src_x - dst_x)*(src_x - dst_x) + (src_y - dst_y)*(src_y - dst_y)); + } + + void clear_old_states() { + // clear old bboxes + for (size_t state_id = 0; state_id < track_id_state_id_time.size(); ++state_id) + { + float time_sec = std::chrono::duration(std::chrono::steady_clock::now() - track_id_state_id_time[state_id].last_time).count(); + float time_wait = 0.5; // 0.5 second + if (track_id_state_id_time[state_id].track_id > -1) + { + if ((result_vec_pred[state_id].x > img_size.width) || + (result_vec_pred[state_id].y > img_size.height)) + { + track_id_state_id_time[state_id].track_id = -1; + } + + if (time_sec >= time_wait || track_id_state_id_time[state_id].detection_count < 0) { + //std::cerr << " remove track_id = " << track_id_state_id_time[state_id].track_id << ", state_id = " << state_id << std::endl; + track_id_state_id_time[state_id].track_id = -1; // remove bbox + } + } + } + } + + tst_t get_state_id(bbox_t find_box, std::vector &busy_vec) + { + tst_t tst; + tst.state_id = -1; + + float min_dist = std::numeric_limits::max(); + + for (size_t i = 0; i < max_objects; ++i) + { + if (track_id_state_id_time[i].track_id > -1 && result_vec_pred[i].obj_id == find_box.obj_id && busy_vec[i] == false) + { + bbox_t pred_box = result_vec_pred[i]; + + float dist = get_distance(pred_box.x, pred_box.y, find_box.x, find_box.y); + + float movement_dist = std::max(max_dist, static_cast(std::max(pred_box.w, pred_box.h)) ); + + if ((dist < movement_dist) && (dist < min_dist)) { + min_dist = dist; + tst.state_id = i; + } + } + } + + if (tst.state_id > -1) { + track_id_state_id_time[tst.state_id].last_time = std::chrono::steady_clock::now(); + track_id_state_id_time[tst.state_id].detection_count = std::max(track_id_state_id_time[tst.state_id].detection_count + 2, 10); + tst = track_id_state_id_time[tst.state_id]; + busy_vec[tst.state_id] = true; + } + else { + //std::cerr << " Didn't find: obj_id = " << find_box.obj_id << ", x = " << find_box.x << ", y = " << find_box.y << + // ", track_id_counter = " << track_id_counter << std::endl; + } + + return tst; + } + + tst_t new_state_id(std::vector &busy_vec) + { + tst_t tst; + // find empty cell to add new track_id + auto it = std::find_if(track_id_state_id_time.begin(), track_id_state_id_time.end(), [&](tst_t &v) { return v.track_id == -1; }); + if (it != track_id_state_id_time.end()) { + it->state_id = it - track_id_state_id_time.begin(); + //it->track_id = track_id_counter++; + it->track_id = 0; + it->last_time = std::chrono::steady_clock::now(); + it->detection_count = 1; + tst = *it; + busy_vec[it->state_id] = true; + } + + return tst; + } + + std::vector find_state_ids(std::vector result_vec) + { + std::vector tst_vec(result_vec.size()); + + std::vector busy_vec(max_objects, false); + + for (size_t i = 0; i < result_vec.size(); ++i) + { + tst_t tst = get_state_id(result_vec[i], busy_vec); + int state_id = tst.state_id; + int track_id = tst.track_id; + + // if new state_id + if (state_id < 0) { + tst = new_state_id(busy_vec); + state_id = tst.state_id; + track_id = tst.track_id; + if (state_id > -1) { + kalman_vec[state_id].set(result_vec[i]); + //std::cerr << " post: "; + } + } + + //std::cerr << " track_id = " << track_id << ", state_id = " << state_id << + // ", x = " << result_vec[i].x << ", det_count = " << tst.detection_count << std::endl; + + if (state_id > -1) { + tst_vec[i] = tst; + result_vec_pred[state_id] = result_vec[i]; + result_vec_pred[state_id].track_id = track_id; + } + } + + return tst_vec; + } + + std::vector predict() + { + clear_old_states(); + std::vector result_vec; + + for (size_t i = 0; i < max_objects; ++i) + { + tst_t tst = track_id_state_id_time[i]; + if (tst.track_id > -1) { + bbox_t box = kalman_vec[i].predict(); + + result_vec_pred[i].x = box.x; + result_vec_pred[i].y = box.y; + result_vec_pred[i].w = box.w; + result_vec_pred[i].h = box.h; + + if (tst.detection_count >= min_frames) + { + if (track_id_state_id_time[i].track_id == 0) { + track_id_state_id_time[i].track_id = ++track_id_counter; + result_vec_pred[i].track_id = track_id_counter; + } + + result_vec.push_back(result_vec_pred[i]); + } + } + } + //std::cerr << " result_vec.size() = " << result_vec.size() << std::endl; + + //global_last_time = std::chrono::steady_clock::now(); + + return result_vec; + } + + + std::vector correct(std::vector result_vec) + { + calc_dt(); + clear_old_states(); + + for (size_t i = 0; i < max_objects; ++i) + track_id_state_id_time[i].detection_count--; + + std::vector tst_vec = find_state_ids(result_vec); + + for (size_t i = 0; i < tst_vec.size(); ++i) { + tst_t tst = tst_vec[i]; + int state_id = tst.state_id; + if (state_id > -1) + { + kalman_vec[state_id].set_delta_time(dT); + kalman_vec[state_id].correct(result_vec_pred[state_id]); + } + } + + result_vec = predict(); + + global_last_time = std::chrono::steady_clock::now(); + + return result_vec; + } + +}; +// ---------------------------------------------- +#endif // __cplusplus + +#endif // YOLO_V2_CLASS_HPP diff --git a/ODHUBYOLODarknet_old/include/yolo_v2cpu_class.hpp b/ODHUBYOLODarknet_old/include/yolo_v2cpu_class.hpp new file mode 100644 index 00000000..e092eded --- /dev/null +++ b/ODHUBYOLODarknet_old/include/yolo_v2cpu_class.hpp @@ -0,0 +1,1041 @@ +#ifndef YOLO_V2CPU_CLASS_HPP +#define YOLO_V2CPU_CLASS_HPP + +#ifndef LIB_API +#ifdef LIB_EXPORTS +#if defined(_MSC_VER) +#define LIB_API __declspec(dllexport) +#else +#define LIB_API __attribute__((visibility("default"))) +#endif +#else +#if defined(_MSC_VER) +#define LIB_API +#else +#define LIB_API +#endif +#endif +#endif + +//#define C_SHARP_MAX_OBJECTS 1000 +// +//struct bbox_t { +// unsigned int x, y, w, h; // (x,y) - top-left corner, (w, h) - width & height of bounded box +// float prob; // confidence - probability that the object was found correctly +// unsigned int obj_id; // class of object - from range [0, classes-1] +// unsigned int track_id; // tracking id for video (0 - untracked, 1 - inf - tracked object) +// unsigned int frames_counter; // counter of frames on which the object was detected +// float x_3d, y_3d, z_3d; // center of object (in Meters) if ZED 3D Camera is used +//}; +// +//struct image_t { +// int h; // height +// int w; // width +// int c; // number of chanels (3 - for RGB) +// float *data; // pointer to the image data +//}; +// +//struct bbox_t_container { +// bbox_t candidates[C_SHARP_MAX_OBJECTS]; +//}; + +#ifdef __cplusplus +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include // C++ +#include // C +#include // C + +//extern "C" LIB_API int init(const char *configurationFilename, const char *weightsFilename, int gpu, int batch_size); +//extern "C" LIB_API int detect_image(const char *filename, bbox_t_container &container); +//extern "C" LIB_API int detect_mat(const uint8_t* data, const size_t data_length, bbox_t_container &container); +//extern "C" LIB_API int dispose(); +//extern "C" LIB_API int get_device_count(bool useGPU); +//extern "C" LIB_API int get_device_name(int gpu, char* deviceName); +//extern "C" LIB_API bool built_with_cuda(bool useGPU); +//extern "C" LIB_API bool built_with_cudnn(bool useGPU); +//extern "C" LIB_API bool built_with_opencv(); +//extern "C" LIB_API void send_json_custom(char const* send_buf, int port, int timeout); + +class CPUDetector { + std::shared_ptr detector_gpu_ptr; + std::deque> prev_bbox_vec_deque; + std::string _cfg_filename, _weight_filename; +private: + bool _useGPU; +public: + int cur_gpu_id; + float nms = .4; + bool wait_stream; + LIB_API CPUDetector(); + LIB_API CPUDetector(std::string cfg_filename, std::string weight_filename, int gpu_id = 0, int batch_size = 1); + LIB_API ~CPUDetector(); + + LIB_API void Init(std::string cfg_filename, std::string weight_filename, int gpu_id = 0, int batch_size = 1); + LIB_API std::vector detect(std::string image_filename, float thresh = 0.2, bool use_mean = false); + LIB_API std::vector detect(image_t img, float thresh = 0.2, bool use_mean = false); + LIB_API std::vector> detectBatch(image_t img, int batch_size, int width, int height, float thresh, bool make_nms = true); + static LIB_API image_t load_image(std::string image_filename); + static LIB_API void free_image(image_t m); + LIB_API int get_net_width() const; + LIB_API int get_net_height() const; + LIB_API int get_net_color_depth() const; + + LIB_API std::vector tracking_id(std::vector cur_bbox_vec, bool const change_history = true, + int const frames_story = 5, int const max_dist = 40); + + LIB_API void *get_cuda_context(); + + //LIB_API bool send_json_http(std::vector cur_bbox_vec, std::vector obj_names, int frame_id, + // std::string filename = std::string(), int timeout = 400000, int port = 8070); + + std::vector detect_resized(image_t img, int init_w, int init_h, float thresh = 0.2, bool use_mean = false) + { + if (img.data == NULL) + throw std::runtime_error("Image is empty"); + auto detection_boxes = detect(img, thresh, use_mean); + float wk = (float)init_w / img.w, hk = (float)init_h / img.h; + for (auto &i : detection_boxes) i.x *= wk, i.w *= wk, i.y *= hk, i.h *= hk; + return detection_boxes; + } + std::vector detect(cv::Mat mat, float thresh = 0.2, bool use_mean = false) + { + if(mat.data == NULL) + throw std::runtime_error("Image is empty"); + auto image_ptr = mat_to_image_resize(mat); + return detect_resized(*image_ptr, mat.cols, mat.rows, thresh, use_mean); + } + std::shared_ptr mat_to_image_resize(cv::Mat mat) const + { + if (mat.data == NULL) return std::shared_ptr(NULL); + + cv::Size network_size = cv::Size(get_net_width(), get_net_height()); + cv::Mat det_mat; + if (mat.size() != network_size) + cv::resize(mat, det_mat, network_size); + else + det_mat = mat; // only reference is copied + + return mat_to_image(det_mat); + } + static std::shared_ptr mat_to_image(cv::Mat img_src) + { + cv::Mat img; + if (img_src.channels() == 4) cv::cvtColor(img_src, img, cv::COLOR_RGBA2BGR); + else if (img_src.channels() == 3) cv::cvtColor(img_src, img, cv::COLOR_RGB2BGR); + else if (img_src.channels() == 1) cv::cvtColor(img_src, img, cv::COLOR_GRAY2BGR); + else std::cerr << " Warning: img_src.channels() is not 1, 3 or 4. It is = " << img_src.channels() << std::endl; + std::shared_ptr image_ptr(new image_t, [](image_t *img) { free_image(*img); delete img; }); + *image_ptr = mat_to_image_custom(img); + return image_ptr; + } + +private: + + static image_t mat_to_image_custom(cv::Mat mat) + { + int w = mat.cols; + int h = mat.rows; + int c = mat.channels(); + image_t im = make_image_custom(w, h, c); + unsigned char *data = (unsigned char *)mat.data; + int step = mat.step; + for (int y = 0; y < h; ++y) { + for (int k = 0; k < c; ++k) { + for (int x = 0; x < w; ++x) { + im.data[k*w*h + y*w + x] = data[y*step + x*c + k] / 255.0f; + } + } + } + return im; + } + static image_t make_empty_image(int w, int h, int c) + { + image_t out; + out.data = 0; + out.h = h; + out.w = w; + out.c = c; + return out; + } + static image_t make_image_custom(int w, int h, int c) + { + image_t out = make_empty_image(w, h, c); + out.data = (float *)calloc(h*w*c, sizeof(float)); + return out; + } + + +public: + + bool send_json_http(std::vector cur_bbox_vec, std::vector obj_names, int frame_id, + std::string filename = std::string(), int timeout = 400000, int port = 8070) + { + std::string send_str; + + char *tmp_buf = (char *)calloc(1024, sizeof(char)); + if (!filename.empty()) { + sprintf(tmp_buf, "{\n \"frame_id\":%d, \n \"filename\":\"%s\", \n \"objects\": [ \n", frame_id, filename.c_str()); + } + else { + sprintf(tmp_buf, "{\n \"frame_id\":%d, \n \"objects\": [ \n", frame_id); + } + send_str = tmp_buf; + free(tmp_buf); + + for (auto & i : cur_bbox_vec) { + char *buf = (char *)calloc(2048, sizeof(char)); + + sprintf(buf, " {\"class_id\":%d, \"name\":\"%s\", \"absolute_coordinates\":{\"center_x\":%d, \"center_y\":%d, \"width\":%d, \"height\":%d}, \"confidence\":%f", + i.obj_id, obj_names[i.obj_id].c_str(), i.x, i.y, i.w, i.h, i.prob); + + //sprintf(buf, " {\"class_id\":%d, \"name\":\"%s\", \"relative_coordinates\":{\"center_x\":%f, \"center_y\":%f, \"width\":%f, \"height\":%f}, \"confidence\":%f", + // i.obj_id, obj_names[i.obj_id], i.x, i.y, i.w, i.h, i.prob); + + send_str += buf; + + if (!std::isnan(i.z_3d)) { + sprintf(buf, "\n , \"coordinates_in_meters\":{\"x_3d\":%.2f, \"y_3d\":%.2f, \"z_3d\":%.2f}", + i.x_3d, i.y_3d, i.z_3d); + send_str += buf; + } + + send_str += "}\n"; + + free(buf); + } + + //send_str += "\n ] \n}, \n"; + send_str += "\n ] \n}"; + + send_json_custom(send_str.c_str(), port, timeout); + return true; + } +}; +// -------------------------------------------------------------------------------- + + +#if defined(TRACK_OPTFLOW) && defined(OPENCV) && defined(GPU) + +#include +#include +#include +#include + +class Tracker_optflow { +public: + const int gpu_count; + const int gpu_id; + const int flow_error; + + + Tracker_optflow(int _gpu_id = 0, int win_size = 15, int max_level = 3, int iterations = 8000, int _flow_error = -1) : + gpu_count(cv::cuda::getCudaEnabledDeviceCount()), gpu_id(std::min(_gpu_id, gpu_count-1)), + flow_error((_flow_error > 0)? _flow_error:(win_size*4)) + { + int const old_gpu_id = cv::cuda::getDevice(); + cv::cuda::setDevice(gpu_id); + + stream = cv::cuda::Stream(); + + sync_PyrLKOpticalFlow_gpu = cv::cuda::SparsePyrLKOpticalFlow::create(); + sync_PyrLKOpticalFlow_gpu->setWinSize(cv::Size(win_size, win_size)); // 9, 15, 21, 31 + sync_PyrLKOpticalFlow_gpu->setMaxLevel(max_level); // +- 3 pt + sync_PyrLKOpticalFlow_gpu->setNumIters(iterations); // 2000, def: 30 + + cv::cuda::setDevice(old_gpu_id); + } + + // just to avoid extra allocations + cv::cuda::GpuMat src_mat_gpu; + cv::cuda::GpuMat dst_mat_gpu, dst_grey_gpu; + cv::cuda::GpuMat prev_pts_flow_gpu, cur_pts_flow_gpu; + cv::cuda::GpuMat status_gpu, err_gpu; + + cv::cuda::GpuMat src_grey_gpu; // used in both functions + cv::Ptr sync_PyrLKOpticalFlow_gpu; + cv::cuda::Stream stream; + + std::vector cur_bbox_vec; + std::vector good_bbox_vec_flags; + cv::Mat prev_pts_flow_cpu; + + void update_cur_bbox_vec(std::vector _cur_bbox_vec) + { + cur_bbox_vec = _cur_bbox_vec; + good_bbox_vec_flags = std::vector(cur_bbox_vec.size(), true); + cv::Mat prev_pts, cur_pts_flow_cpu; + + for (auto &i : cur_bbox_vec) { + float x_center = (i.x + i.w / 2.0F); + float y_center = (i.y + i.h / 2.0F); + prev_pts.push_back(cv::Point2f(x_center, y_center)); + } + + if (prev_pts.rows == 0) + prev_pts_flow_cpu = cv::Mat(); + else + cv::transpose(prev_pts, prev_pts_flow_cpu); + + if (prev_pts_flow_gpu.cols < prev_pts_flow_cpu.cols) { + prev_pts_flow_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), prev_pts_flow_cpu.type()); + cur_pts_flow_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), prev_pts_flow_cpu.type()); + + status_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), CV_8UC1); + err_gpu = cv::cuda::GpuMat(prev_pts_flow_cpu.size(), CV_32FC1); + } + + prev_pts_flow_gpu.upload(cv::Mat(prev_pts_flow_cpu), stream); + } + + + void update_tracking_flow(cv::Mat src_mat, std::vector _cur_bbox_vec) + { + int const old_gpu_id = cv::cuda::getDevice(); + if (old_gpu_id != gpu_id) + cv::cuda::setDevice(gpu_id); + + if (src_mat.channels() == 1 || src_mat.channels() == 3 || src_mat.channels() == 4) { + if (src_mat_gpu.cols == 0) { + src_mat_gpu = cv::cuda::GpuMat(src_mat.size(), src_mat.type()); + src_grey_gpu = cv::cuda::GpuMat(src_mat.size(), CV_8UC1); + } + + if (src_mat.channels() == 1) { + src_mat_gpu.upload(src_mat, stream); + src_mat_gpu.copyTo(src_grey_gpu); + } + else if (src_mat.channels() == 3) { + src_mat_gpu.upload(src_mat, stream); + cv::cuda::cvtColor(src_mat_gpu, src_grey_gpu, CV_BGR2GRAY, 1, stream); + } + else if (src_mat.channels() == 4) { + src_mat_gpu.upload(src_mat, stream); + cv::cuda::cvtColor(src_mat_gpu, src_grey_gpu, CV_BGRA2GRAY, 1, stream); + } + else { + std::cerr << " Warning: src_mat.channels() is not: 1, 3 or 4. It is = " << src_mat.channels() << " \n"; + return; + } + + } + update_cur_bbox_vec(_cur_bbox_vec); + + if (old_gpu_id != gpu_id) + cv::cuda::setDevice(old_gpu_id); + } + + + std::vector tracking_flow(cv::Mat dst_mat, bool check_error = true) + { + if (sync_PyrLKOpticalFlow_gpu.empty()) { + std::cout << "sync_PyrLKOpticalFlow_gpu isn't initialized \n"; + return cur_bbox_vec; + } + + int const old_gpu_id = cv::cuda::getDevice(); + if(old_gpu_id != gpu_id) + cv::cuda::setDevice(gpu_id); + + if (dst_mat_gpu.cols == 0) { + dst_mat_gpu = cv::cuda::GpuMat(dst_mat.size(), dst_mat.type()); + dst_grey_gpu = cv::cuda::GpuMat(dst_mat.size(), CV_8UC1); + } + + //dst_grey_gpu.upload(dst_mat, stream); // use BGR + dst_mat_gpu.upload(dst_mat, stream); + cv::cuda::cvtColor(dst_mat_gpu, dst_grey_gpu, CV_BGR2GRAY, 1, stream); + + if (src_grey_gpu.rows != dst_grey_gpu.rows || src_grey_gpu.cols != dst_grey_gpu.cols) { + stream.waitForCompletion(); + src_grey_gpu = dst_grey_gpu.clone(); + cv::cuda::setDevice(old_gpu_id); + return cur_bbox_vec; + } + + ////sync_PyrLKOpticalFlow_gpu.sparse(src_grey_gpu, dst_grey_gpu, prev_pts_flow_gpu, cur_pts_flow_gpu, status_gpu, &err_gpu); // OpenCV 2.4.x + sync_PyrLKOpticalFlow_gpu->calc(src_grey_gpu, dst_grey_gpu, prev_pts_flow_gpu, cur_pts_flow_gpu, status_gpu, err_gpu, stream); // OpenCV 3.x + + cv::Mat cur_pts_flow_cpu; + cur_pts_flow_gpu.download(cur_pts_flow_cpu, stream); + + dst_grey_gpu.copyTo(src_grey_gpu, stream); + + cv::Mat err_cpu, status_cpu; + err_gpu.download(err_cpu, stream); + status_gpu.download(status_cpu, stream); + + stream.waitForCompletion(); + + std::vector result_bbox_vec; + + if (err_cpu.cols == cur_bbox_vec.size() && status_cpu.cols == cur_bbox_vec.size()) + { + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + { + cv::Point2f cur_key_pt = cur_pts_flow_cpu.at(0, i); + cv::Point2f prev_key_pt = prev_pts_flow_cpu.at(0, i); + + float moved_x = cur_key_pt.x - prev_key_pt.x; + float moved_y = cur_key_pt.y - prev_key_pt.y; + + if (abs(moved_x) < 100 && abs(moved_y) < 100 && good_bbox_vec_flags[i]) + if (err_cpu.at(0, i) < flow_error && status_cpu.at(0, i) != 0 && + ((float)cur_bbox_vec[i].x + moved_x) > 0 && ((float)cur_bbox_vec[i].y + moved_y) > 0) + { + cur_bbox_vec[i].x += moved_x + 0.5; + cur_bbox_vec[i].y += moved_y + 0.5; + result_bbox_vec.push_back(cur_bbox_vec[i]); + } + else good_bbox_vec_flags[i] = false; + else good_bbox_vec_flags[i] = false; + + //if(!check_error && !good_bbox_vec_flags[i]) result_bbox_vec.push_back(cur_bbox_vec[i]); + } + } + + cur_pts_flow_gpu.swap(prev_pts_flow_gpu); + cur_pts_flow_cpu.copyTo(prev_pts_flow_cpu); + + if (old_gpu_id != gpu_id) + cv::cuda::setDevice(old_gpu_id); + + return result_bbox_vec; + } + +}; + +#elif defined(TRACK_OPTFLOW) && defined(OPENCV) + +//#include +#include + +class Tracker_optflow { +public: + const int flow_error; + + + Tracker_optflow(int win_size = 15, int max_level = 3, int iterations = 8000, int _flow_error = -1) : + flow_error((_flow_error > 0)? _flow_error:(win_size*4)) + { + sync_PyrLKOpticalFlow = cv::SparsePyrLKOpticalFlow::create(); + sync_PyrLKOpticalFlow->setWinSize(cv::Size(win_size, win_size)); // 9, 15, 21, 31 + sync_PyrLKOpticalFlow->setMaxLevel(max_level); // +- 3 pt + + } + + // just to avoid extra allocations + cv::Mat dst_grey; + cv::Mat prev_pts_flow, cur_pts_flow; + cv::Mat status, err; + + cv::Mat src_grey; // used in both functions + cv::Ptr sync_PyrLKOpticalFlow; + + std::vector cur_bbox_vec; + std::vector good_bbox_vec_flags; + + void update_cur_bbox_vec(std::vector _cur_bbox_vec) + { + cur_bbox_vec = _cur_bbox_vec; + good_bbox_vec_flags = std::vector(cur_bbox_vec.size(), true); + cv::Mat prev_pts, cur_pts_flow; + + for (auto &i : cur_bbox_vec) { + float x_center = (i.x + i.w / 2.0F); + float y_center = (i.y + i.h / 2.0F); + prev_pts.push_back(cv::Point2f(x_center, y_center)); + } + + if (prev_pts.rows == 0) + prev_pts_flow = cv::Mat(); + else + cv::transpose(prev_pts, prev_pts_flow); + } + + + void update_tracking_flow(cv::Mat new_src_mat, std::vector _cur_bbox_vec) + { + if (new_src_mat.channels() == 1) { + src_grey = new_src_mat.clone(); + } + else if (new_src_mat.channels() == 3) { + cv::cvtColor(new_src_mat, src_grey, CV_BGR2GRAY, 1); + } + else if (new_src_mat.channels() == 4) { + cv::cvtColor(new_src_mat, src_grey, CV_BGRA2GRAY, 1); + } + else { + std::cerr << " Warning: new_src_mat.channels() is not: 1, 3 or 4. It is = " << new_src_mat.channels() << " \n"; + return; + } + update_cur_bbox_vec(_cur_bbox_vec); + } + + + std::vector tracking_flow(cv::Mat new_dst_mat, bool check_error = true) + { + if (sync_PyrLKOpticalFlow.empty()) { + std::cout << "sync_PyrLKOpticalFlow isn't initialized \n"; + return cur_bbox_vec; + } + + cv::cvtColor(new_dst_mat, dst_grey, CV_BGR2GRAY, 1); + + if (src_grey.rows != dst_grey.rows || src_grey.cols != dst_grey.cols) { + src_grey = dst_grey.clone(); + //std::cerr << " Warning: src_grey.rows != dst_grey.rows || src_grey.cols != dst_grey.cols \n"; + return cur_bbox_vec; + } + + if (prev_pts_flow.cols < 1) { + return cur_bbox_vec; + } + + ////sync_PyrLKOpticalFlow_gpu.sparse(src_grey_gpu, dst_grey_gpu, prev_pts_flow_gpu, cur_pts_flow_gpu, status_gpu, &err_gpu); // OpenCV 2.4.x + sync_PyrLKOpticalFlow->calc(src_grey, dst_grey, prev_pts_flow, cur_pts_flow, status, err); // OpenCV 3.x + + dst_grey.copyTo(src_grey); + + std::vector result_bbox_vec; + + if (err.rows == cur_bbox_vec.size() && status.rows == cur_bbox_vec.size()) + { + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + { + cv::Point2f cur_key_pt = cur_pts_flow.at(0, i); + cv::Point2f prev_key_pt = prev_pts_flow.at(0, i); + + float moved_x = cur_key_pt.x - prev_key_pt.x; + float moved_y = cur_key_pt.y - prev_key_pt.y; + + if (abs(moved_x) < 100 && abs(moved_y) < 100 && good_bbox_vec_flags[i]) + if (err.at(0, i) < flow_error && status.at(0, i) != 0 && + ((float)cur_bbox_vec[i].x + moved_x) > 0 && ((float)cur_bbox_vec[i].y + moved_y) > 0) + { + cur_bbox_vec[i].x += moved_x + 0.5; + cur_bbox_vec[i].y += moved_y + 0.5; + result_bbox_vec.push_back(cur_bbox_vec[i]); + } + else good_bbox_vec_flags[i] = false; + else good_bbox_vec_flags[i] = false; + + //if(!check_error && !good_bbox_vec_flags[i]) result_bbox_vec.push_back(cur_bbox_vec[i]); + } + } + + prev_pts_flow = cur_pts_flow.clone(); + + return result_bbox_vec; + } + +}; +#else + +//class Tracker_optflow {}; + +#endif // defined(TRACK_OPTFLOW) && defined(OPENCV) + +//static cv::Scalar obj_id_to_color(int obj_id) { +// int const colors[6][3] = { { 1,0,1 },{ 0,0,1 },{ 0,1,1 },{ 0,1,0 },{ 1,1,0 },{ 1,0,0 } }; +// int const offset = obj_id * 123457 % 6; +// int const color_scale = 150 + (obj_id * 123457) % 100; +// cv::Scalar color(colors[offset][0], colors[offset][1], colors[offset][2]); +// color *= color_scale; +// return color; +//} + +//class preview_boxes_t { +// enum { frames_history = 30 }; // how long to keep the history saved +// +// struct preview_box_track_t { +// unsigned int track_id, obj_id, last_showed_frames_ago; +// bool current_detection; +// bbox_t bbox; +// cv::Mat mat_obj, mat_resized_obj; +// preview_box_track_t() : track_id(0), obj_id(0), last_showed_frames_ago(frames_history), current_detection(false) {} +// }; +// std::vector preview_box_track_id; +// size_t const preview_box_size, bottom_offset; +// bool const one_off_detections; +//public: +// preview_boxes_t(size_t _preview_box_size = 100, size_t _bottom_offset = 100, bool _one_off_detections = false) : +// preview_box_size(_preview_box_size), bottom_offset(_bottom_offset), one_off_detections(_one_off_detections) +// {} +// +// void set(cv::Mat src_mat, std::vector result_vec) +// { +// size_t const count_preview_boxes = src_mat.cols / preview_box_size; +// if (preview_box_track_id.size() != count_preview_boxes) preview_box_track_id.resize(count_preview_boxes); +// +// // increment frames history +// for (auto &i : preview_box_track_id) +// i.last_showed_frames_ago = std::min((unsigned)frames_history, i.last_showed_frames_ago + 1); +// +// // occupy empty boxes +// for (auto &k : result_vec) { +// bool found = false; +// // find the same (track_id) +// for (auto &i : preview_box_track_id) { +// if (i.track_id == k.track_id) { +// if (!one_off_detections) i.last_showed_frames_ago = 0; // for tracked objects +// found = true; +// break; +// } +// } +// if (!found) { +// // find empty box +// for (auto &i : preview_box_track_id) { +// if (i.last_showed_frames_ago == frames_history) { +// if (!one_off_detections && k.frames_counter == 0) break; // don't show if obj isn't tracked yet +// i.track_id = k.track_id; +// i.obj_id = k.obj_id; +// i.bbox = k; +// i.last_showed_frames_ago = 0; +// break; +// } +// } +// } +// } +// +// // draw preview box (from old or current frame) +// for (size_t i = 0; i < preview_box_track_id.size(); ++i) +// { +// // get object image +// cv::Mat dst = preview_box_track_id[i].mat_resized_obj; +// preview_box_track_id[i].current_detection = false; +// +// for (auto &k : result_vec) { +// if (preview_box_track_id[i].track_id == k.track_id) { +// if (one_off_detections && preview_box_track_id[i].last_showed_frames_ago > 0) { +// preview_box_track_id[i].last_showed_frames_ago = frames_history; break; +// } +// bbox_t b = k; +// cv::Rect r(b.x, b.y, b.w, b.h); +// cv::Rect img_rect(cv::Point2i(0, 0), src_mat.size()); +// cv::Rect rect_roi = r & img_rect; +// if (rect_roi.width > 1 || rect_roi.height > 1) { +// cv::Mat roi = src_mat(rect_roi); +// cv::resize(roi, dst, cv::Size(preview_box_size, preview_box_size), cv::INTER_NEAREST); +// preview_box_track_id[i].mat_obj = roi.clone(); +// preview_box_track_id[i].mat_resized_obj = dst.clone(); +// preview_box_track_id[i].current_detection = true; +// preview_box_track_id[i].bbox = k; +// } +// break; +// } +// } +// } +// } +// +// +// void draw(cv::Mat draw_mat, bool show_small_boxes = false) +// { +// // draw preview box (from old or current frame) +// for (size_t i = 0; i < preview_box_track_id.size(); ++i) +// { +// auto &prev_box = preview_box_track_id[i]; +// +// // draw object image +// cv::Mat dst = prev_box.mat_resized_obj; +// if (prev_box.last_showed_frames_ago < frames_history && +// dst.size() == cv::Size(preview_box_size, preview_box_size)) +// { +// cv::Rect dst_rect_roi(cv::Point2i(i * preview_box_size, draw_mat.rows - bottom_offset), dst.size()); +// cv::Mat dst_roi = draw_mat(dst_rect_roi); +// dst.copyTo(dst_roi); +// +// cv::Scalar color = obj_id_to_color(prev_box.obj_id); +// int thickness = (prev_box.current_detection) ? 5 : 1; +// cv::rectangle(draw_mat, dst_rect_roi, color, thickness); +// +// unsigned int const track_id = prev_box.track_id; +// std::string track_id_str = (track_id > 0) ? std::to_string(track_id) : ""; +// putText(draw_mat, track_id_str, dst_rect_roi.tl() - cv::Point2i(-4, 5), cv::FONT_HERSHEY_COMPLEX_SMALL, 0.9, cv::Scalar(0, 0, 0), 2); +// +// std::string size_str = std::to_string(prev_box.bbox.w) + "x" + std::to_string(prev_box.bbox.h); +// putText(draw_mat, size_str, dst_rect_roi.tl() + cv::Point2i(0, 12), cv::FONT_HERSHEY_COMPLEX_SMALL, 0.8, cv::Scalar(0, 0, 0), 1); +// +// if (!one_off_detections && prev_box.current_detection) { +// cv::line(draw_mat, dst_rect_roi.tl() + cv::Point2i(preview_box_size, 0), +// cv::Point2i(prev_box.bbox.x, prev_box.bbox.y + prev_box.bbox.h), +// color); +// } +// +// if (one_off_detections && show_small_boxes) { +// cv::Rect src_rect_roi(cv::Point2i(prev_box.bbox.x, prev_box.bbox.y), +// cv::Size(prev_box.bbox.w, prev_box.bbox.h)); +// unsigned int const color_history = (255 * prev_box.last_showed_frames_ago) / frames_history; +// color = cv::Scalar(255 - 3 * color_history, 255 - 2 * color_history, 255 - 1 * color_history); +// if (prev_box.mat_obj.size() == src_rect_roi.size()) { +// prev_box.mat_obj.copyTo(draw_mat(src_rect_roi)); +// } +// cv::rectangle(draw_mat, src_rect_roi, color, thickness); +// putText(draw_mat, track_id_str, src_rect_roi.tl() - cv::Point2i(0, 10), cv::FONT_HERSHEY_COMPLEX_SMALL, 0.8, cv::Scalar(0, 0, 0), 1); +// } +// } +// } +// } +//}; + + +//class track_kalman_t +//{ +// int track_id_counter; +// std::chrono::steady_clock::time_point global_last_time; +// float dT; +// +//public: +// int max_objects; // max objects for tracking +// int min_frames; // min frames to consider an object as detected +// const float max_dist; // max distance (in px) to track with the same ID +// cv::Size img_size; // max value of x,y,w,h +// +// struct tst_t { +// int track_id; +// int state_id; +// std::chrono::steady_clock::time_point last_time; +// int detection_count; +// tst_t() : track_id(-1), state_id(-1) {} +// }; +// std::vector track_id_state_id_time; +// std::vector result_vec_pred; +// +// struct one_kalman_t; +// std::vector kalman_vec; +// +// struct one_kalman_t +// { +// cv::KalmanFilter kf; +// cv::Mat state; +// cv::Mat meas; +// int measSize, stateSize, contrSize; +// +// void set_delta_time(float dT) { +// kf.transitionMatrix.at(2) = dT; +// kf.transitionMatrix.at(9) = dT; +// } +// +// void set(bbox_t box) +// { +// initialize_kalman(); +// +// kf.errorCovPre.at(0) = 1; // px +// kf.errorCovPre.at(7) = 1; // px +// kf.errorCovPre.at(14) = 1; +// kf.errorCovPre.at(21) = 1; +// kf.errorCovPre.at(28) = 1; // px +// kf.errorCovPre.at(35) = 1; // px +// +// state.at(0) = box.x; +// state.at(1) = box.y; +// state.at(2) = 0; +// state.at(3) = 0; +// state.at(4) = box.w; +// state.at(5) = box.h; +// // <<<< Initialization +// +// kf.statePost = state; +// } +// +// // Kalman.correct() calculates: statePost = statePre + gain * (z(k)-measurementMatrix*statePre); +// // corrected state (x(k)): x(k)=x'(k)+K(k)*(z(k)-H*x'(k)) +// void correct(bbox_t box) { +// meas.at(0) = box.x; +// meas.at(1) = box.y; +// meas.at(2) = box.w; +// meas.at(3) = box.h; +// +// kf.correct(meas); +// +// bbox_t new_box = predict(); +// if (new_box.w == 0 || new_box.h == 0) { +// set(box); +// //std::cerr << " force set(): track_id = " << box.track_id << +// // ", x = " << box.x << ", y = " << box.y << ", w = " << box.w << ", h = " << box.h << std::endl; +// } +// } +// +// // Kalman.predict() calculates: statePre = TransitionMatrix * statePost; +// // predicted state (x'(k)): x(k)=A*x(k-1)+B*u(k) +// bbox_t predict() { +// bbox_t box; +// state = kf.predict(); +// +// box.x = state.at(0); +// box.y = state.at(1); +// box.w = state.at(4); +// box.h = state.at(5); +// return box; +// } +// +// void initialize_kalman() +// { +// kf = cv::KalmanFilter(stateSize, measSize, contrSize, CV_32F); +// +// // Transition State Matrix A +// // Note: set dT at each processing step! +// // [ 1 0 dT 0 0 0 ] +// // [ 0 1 0 dT 0 0 ] +// // [ 0 0 1 0 0 0 ] +// // [ 0 0 0 1 0 0 ] +// // [ 0 0 0 0 1 0 ] +// // [ 0 0 0 0 0 1 ] +// cv::setIdentity(kf.transitionMatrix); +// +// // Measure Matrix H +// // [ 1 0 0 0 0 0 ] +// // [ 0 1 0 0 0 0 ] +// // [ 0 0 0 0 1 0 ] +// // [ 0 0 0 0 0 1 ] +// kf.measurementMatrix = cv::Mat::zeros(measSize, stateSize, CV_32F); +// kf.measurementMatrix.at(0) = 1.0f; +// kf.measurementMatrix.at(7) = 1.0f; +// kf.measurementMatrix.at(16) = 1.0f; +// kf.measurementMatrix.at(23) = 1.0f; +// +// // Process Noise Covariance Matrix Q - result smoother with lower values (1e-2) +// // [ Ex 0 0 0 0 0 ] +// // [ 0 Ey 0 0 0 0 ] +// // [ 0 0 Ev_x 0 0 0 ] +// // [ 0 0 0 Ev_y 0 0 ] +// // [ 0 0 0 0 Ew 0 ] +// // [ 0 0 0 0 0 Eh ] +// //cv::setIdentity(kf.processNoiseCov, cv::Scalar(1e-3)); +// kf.processNoiseCov.at(0) = 1e-2; +// kf.processNoiseCov.at(7) = 1e-2; +// kf.processNoiseCov.at(14) = 1e-2;// 5.0f; +// kf.processNoiseCov.at(21) = 1e-2;// 5.0f; +// kf.processNoiseCov.at(28) = 5e-3; +// kf.processNoiseCov.at(35) = 5e-3; +// +// // Measures Noise Covariance Matrix R - result smoother with higher values (1e-1) +// cv::setIdentity(kf.measurementNoiseCov, cv::Scalar(1e-1)); +// +// //cv::setIdentity(kf.errorCovPost, cv::Scalar::all(1e-2)); +// // <<<< Kalman Filter +// +// set_delta_time(0); +// } +// +// +// one_kalman_t(int _stateSize = 6, int _measSize = 4, int _contrSize = 0) : +// kf(_stateSize, _measSize, _contrSize, CV_32F), measSize(_measSize), stateSize(_stateSize), contrSize(_contrSize) +// { +// state = cv::Mat(stateSize, 1, CV_32F); // [x,y,v_x,v_y,w,h] +// meas = cv::Mat(measSize, 1, CV_32F); // [z_x,z_y,z_w,z_h] +// //cv::Mat procNoise(stateSize, 1, type) +// // [E_x,E_y,E_v_x,E_v_y,E_w,E_h] +// +// initialize_kalman(); +// } +// }; +// // ------------------------------------------ +// +// +// +// track_kalman_t(int _max_objects = 1000, int _min_frames = 3, float _max_dist = 40, cv::Size _img_size = cv::Size(10000, 10000)) : +// track_id_counter(0), max_objects(_max_objects), min_frames(_min_frames), max_dist(_max_dist), img_size(_img_size) +// { +// kalman_vec.resize(max_objects); +// track_id_state_id_time.resize(max_objects); +// result_vec_pred.resize(max_objects); +// } +// +// float calc_dt() { +// dT = std::chrono::duration(std::chrono::steady_clock::now() - global_last_time).count(); +// return dT; +// } +// +// static float get_distance(float src_x, float src_y, float dst_x, float dst_y) { +// return sqrtf((src_x - dst_x)*(src_x - dst_x) + (src_y - dst_y)*(src_y - dst_y)); +// } +// +// void clear_old_states() { +// // clear old bboxes +// for (size_t state_id = 0; state_id < track_id_state_id_time.size(); ++state_id) +// { +// float time_sec = std::chrono::duration(std::chrono::steady_clock::now() - track_id_state_id_time[state_id].last_time).count(); +// float time_wait = 0.5; // 0.5 second +// if (track_id_state_id_time[state_id].track_id > -1) +// { +// if ((result_vec_pred[state_id].x > img_size.width) || +// (result_vec_pred[state_id].y > img_size.height)) +// { +// track_id_state_id_time[state_id].track_id = -1; +// } +// +// if (time_sec >= time_wait || track_id_state_id_time[state_id].detection_count < 0) { +// //std::cerr << " remove track_id = " << track_id_state_id_time[state_id].track_id << ", state_id = " << state_id << std::endl; +// track_id_state_id_time[state_id].track_id = -1; // remove bbox +// } +// } +// } +// } +// +// tst_t get_state_id(bbox_t find_box, std::vector &busy_vec) +// { +// tst_t tst; +// tst.state_id = -1; +// +// float min_dist = std::numeric_limits::max(); +// +// for (size_t i = 0; i < max_objects; ++i) +// { +// if (track_id_state_id_time[i].track_id > -1 && result_vec_pred[i].obj_id == find_box.obj_id && busy_vec[i] == false) +// { +// bbox_t pred_box = result_vec_pred[i]; +// +// float dist = get_distance(pred_box.x, pred_box.y, find_box.x, find_box.y); +// +// float movement_dist = std::max(max_dist, static_cast(std::max(pred_box.w, pred_box.h)) ); +// +// if ((dist < movement_dist) && (dist < min_dist)) { +// min_dist = dist; +// tst.state_id = i; +// } +// } +// } +// +// if (tst.state_id > -1) { +// track_id_state_id_time[tst.state_id].last_time = std::chrono::steady_clock::now(); +// track_id_state_id_time[tst.state_id].detection_count = std::max(track_id_state_id_time[tst.state_id].detection_count + 2, 10); +// tst = track_id_state_id_time[tst.state_id]; +// busy_vec[tst.state_id] = true; +// } +// else { +// //std::cerr << " Didn't find: obj_id = " << find_box.obj_id << ", x = " << find_box.x << ", y = " << find_box.y << +// // ", track_id_counter = " << track_id_counter << std::endl; +// } +// +// return tst; +// } +// +// tst_t new_state_id(std::vector &busy_vec) +// { +// tst_t tst; +// // find empty cell to add new track_id +// auto it = std::find_if(track_id_state_id_time.begin(), track_id_state_id_time.end(), [&](tst_t &v) { return v.track_id == -1; }); +// if (it != track_id_state_id_time.end()) { +// it->state_id = it - track_id_state_id_time.begin(); +// //it->track_id = track_id_counter++; +// it->track_id = 0; +// it->last_time = std::chrono::steady_clock::now(); +// it->detection_count = 1; +// tst = *it; +// busy_vec[it->state_id] = true; +// } +// +// return tst; +// } +// +// std::vector find_state_ids(std::vector result_vec) +// { +// std::vector tst_vec(result_vec.size()); +// +// std::vector busy_vec(max_objects, false); +// +// for (size_t i = 0; i < result_vec.size(); ++i) +// { +// tst_t tst = get_state_id(result_vec[i], busy_vec); +// int state_id = tst.state_id; +// int track_id = tst.track_id; +// +// // if new state_id +// if (state_id < 0) { +// tst = new_state_id(busy_vec); +// state_id = tst.state_id; +// track_id = tst.track_id; +// if (state_id > -1) { +// kalman_vec[state_id].set(result_vec[i]); +// //std::cerr << " post: "; +// } +// } +// +// //std::cerr << " track_id = " << track_id << ", state_id = " << state_id << +// // ", x = " << result_vec[i].x << ", det_count = " << tst.detection_count << std::endl; +// +// if (state_id > -1) { +// tst_vec[i] = tst; +// result_vec_pred[state_id] = result_vec[i]; +// result_vec_pred[state_id].track_id = track_id; +// } +// } +// +// return tst_vec; +// } +// +// std::vector predict() +// { +// clear_old_states(); +// std::vector result_vec; +// +// for (size_t i = 0; i < max_objects; ++i) +// { +// tst_t tst = track_id_state_id_time[i]; +// if (tst.track_id > -1) { +// bbox_t box = kalman_vec[i].predict(); +// +// result_vec_pred[i].x = box.x; +// result_vec_pred[i].y = box.y; +// result_vec_pred[i].w = box.w; +// result_vec_pred[i].h = box.h; +// +// if (tst.detection_count >= min_frames) +// { +// if (track_id_state_id_time[i].track_id == 0) { +// track_id_state_id_time[i].track_id = ++track_id_counter; +// result_vec_pred[i].track_id = track_id_counter; +// } +// +// result_vec.push_back(result_vec_pred[i]); +// } +// } +// } +// //std::cerr << " result_vec.size() = " << result_vec.size() << std::endl; +// +// //global_last_time = std::chrono::steady_clock::now(); +// +// return result_vec; +// } +// +// +// std::vector correct(std::vector result_vec) +// { +// calc_dt(); +// clear_old_states(); +// +// for (size_t i = 0; i < max_objects; ++i) +// track_id_state_id_time[i].detection_count--; +// +// std::vector tst_vec = find_state_ids(result_vec); +// +// for (size_t i = 0; i < tst_vec.size(); ++i) { +// tst_t tst = tst_vec[i]; +// int state_id = tst.state_id; +// if (state_id > -1) +// { +// kalman_vec[state_id].set_delta_time(dT); +// kalman_vec[state_id].correct(result_vec_pred[state_id]); +// } +// } +// +// result_vec = predict(); +// +// global_last_time = std::chrono::steady_clock::now(); +// +// return result_vec; +// } +// +//}; +// ---------------------------------------------- +#endif // __cplusplus + +#endif // YOLO_V2_CLASS_HPP diff --git a/ODHUBYOLODarknet_old/lib/ansdn.exe b/ODHUBYOLODarknet_old/lib/ansdn.exe new file mode 100644 index 00000000..44c6b072 Binary files /dev/null and b/ODHUBYOLODarknet_old/lib/ansdn.exe differ diff --git a/ODHUBYOLODarknet_old/lib/odhublib.dll b/ODHUBYOLODarknet_old/lib/odhublib.dll new file mode 100644 index 00000000..04641469 Binary files /dev/null and b/ODHUBYOLODarknet_old/lib/odhublib.dll differ diff --git a/ODHUBYOLODarknet_old/lib/odhublib.lib b/ODHUBYOLODarknet_old/lib/odhublib.lib new file mode 100644 index 00000000..06ceee56 Binary files /dev/null and b/ODHUBYOLODarknet_old/lib/odhublib.lib differ diff --git a/ODHUBYOLODarknet_old/lib/odhublib_cpu.dll b/ODHUBYOLODarknet_old/lib/odhublib_cpu.dll new file mode 100644 index 00000000..1c57f7dd Binary files /dev/null and b/ODHUBYOLODarknet_old/lib/odhublib_cpu.dll differ diff --git a/ODHUBYOLODarknet_old/lib/odhublib_cpu.lib b/ODHUBYOLODarknet_old/lib/odhublib_cpu.lib new file mode 100644 index 00000000..c1f20d72 Binary files /dev/null and b/ODHUBYOLODarknet_old/lib/odhublib_cpu.lib differ diff --git a/ODHUBYOLODarknet_old/src/yolo_v2_class.cpp b/ODHUBYOLODarknet_old/src/yolo_v2_class.cpp new file mode 100644 index 00000000..c2ee9404 --- /dev/null +++ b/ODHUBYOLODarknet_old/src/yolo_v2_class.cpp @@ -0,0 +1,519 @@ +#include "darknet.h" +#include "yolo_v2_class.hpp" +#include "network.h" +extern "C" { +#include "detection_layer.h" +#include "region_layer.h" +#include "cost_layer.h" +#include "utils.h" +#include "parser.h" +#include "box.h" +#include "image.h" +#include "demo.h" +#include "option_list.h" +#include +} +//#include + +#include +#include +#include +#include + +#define NFRAMES 3 + +//static Detector* detector = NULL; +static std::unique_ptr detector; + +int init(const char *configurationFilename, const char *weightsFilename, int gpu, int batch_size) +{ + detector.reset(new Detector(configurationFilename, weightsFilename, gpu, batch_size)); + return 1; +} +int detect_image(const char *filename, bbox_t_container &container) +{ + std::vector detection = detector->detect(filename); + for (size_t i = 0; i < detection.size() && i < C_SHARP_MAX_OBJECTS; ++i) + container.candidates[i] = detection[i]; + return detection.size(); +} +int detect_mat(const uint8_t* data, const size_t data_length, bbox_t_container &container) { + std::vector vdata(data, data + data_length); + cv::Mat image = imdecode(cv::Mat(vdata), 1); + std::vector detection = detector->detect(image); + for (size_t i = 0; i < detection.size() && i < C_SHARP_MAX_OBJECTS; ++i) + container.candidates[i] = detection[i]; + return detection.size(); +} + +int dispose() { + detector.reset(); + return 1; +} + +int get_device_count(bool useGPU) { + if (useGPU) { + int count = 0; + cudaGetDeviceCount(&count); + return count; + + } + else return -1; +} + +bool built_with_cuda(bool useGPU){ + return useGPU; +} + +bool built_with_cudnn(bool useGPU){ + return useGPU; +} + +bool built_with_opencv(){ + return true; +} + + +int get_device_name(int gpu, char* deviceName) { + if (gpu >= 0) { + cudaDeviceProp prop; + cudaGetDeviceProperties(&prop, gpu); + std::string result = prop.name; + std::copy(result.begin(), result.end(), deviceName); + return 1; + } + else return -1; +} + +void check_cuda(cudaError_t status) { + if (status != cudaSuccess) { + const char *s = cudaGetErrorString(status); + printf("CUDA Error Prev: %s\n", s); + } +} + +struct detector_gpu_t { + network net; + image images[NFRAMES]; + float *avg; + float* predictions[NFRAMES]; + int demo_index; + unsigned int *track_id; +}; +LIB_API Detector::Detector() { + wait_stream = 0; + cur_gpu_id = 0; + _useGPU = false; +} +LIB_API Detector::Detector(std::string cfg_filename, std::string weight_filename, int gpu_id, int batch_size) + : cur_gpu_id(gpu_id) +{ + wait_stream = 0; + if (gpu_id < 0) _useGPU = false; + else _useGPU = true; + int old_gpu_index; + if (_useGPU) { + check_cuda(cudaGetDevice(&old_gpu_index)); + } + detector_gpu_ptr = std::make_shared(); + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + + if (_useGPU) { + cuda_set_device(cur_gpu_id); + printf(" Used GPU %d \n", cur_gpu_id); + } + network &net = detector_gpu.net; + net.gpu_index = cur_gpu_id; + + _cfg_filename = cfg_filename; + _weight_filename = weight_filename; + + char *cfgfile = const_cast(_cfg_filename.c_str()); + char *weightfile = const_cast(_weight_filename.c_str()); + + net = parse_network_cfg_custom(cfgfile, batch_size, batch_size); + if (weightfile) { + load_weights(&net, weightfile); + } + set_batch_network(&net, batch_size); + net.gpu_index = cur_gpu_id; + fuse_conv_batchnorm(net); + + layer l = net.layers[net.n - 1]; + int j; + + detector_gpu.avg = (float *)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.predictions[j] = (float*)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.images[j] = make_image(1, 1, 3); + + detector_gpu.track_id = (unsigned int *)calloc(l.classes, sizeof(unsigned int)); + for (j = 0; j < l.classes; ++j) detector_gpu.track_id[j] = 1; + + if (_useGPU) { + check_cuda(cudaSetDevice(old_gpu_index)); + } +} + +LIB_API void Detector::Init(std::string cfg_filename, std::string weight_filename, int gpu_id, int batch_size) { + wait_stream = 0; + if (gpu_id < 0) _useGPU = false; + else { + cur_gpu_id = gpu_id; + _useGPU = true; + } + int old_gpu_index; + if (_useGPU) { + check_cuda(cudaGetDevice(&old_gpu_index)); + } + detector_gpu_ptr = std::make_shared(); + detector_gpu_t& detector_gpu = *static_cast(detector_gpu_ptr.get()); + + if (_useGPU) { + cuda_set_device(cur_gpu_id); + printf(" Used GPU %d \n", cur_gpu_id); + } + network& net = detector_gpu.net; + net.gpu_index = cur_gpu_id; + + _cfg_filename = cfg_filename; + _weight_filename = weight_filename; + + char* cfgfile = const_cast(_cfg_filename.c_str()); + char* weightfile = const_cast(_weight_filename.c_str()); + + net = parse_network_cfg_custom(cfgfile, batch_size, batch_size); + if (weightfile) { + load_weights(&net, weightfile); + } + set_batch_network(&net, batch_size); + net.gpu_index = cur_gpu_id; + fuse_conv_batchnorm(net); + + layer l = net.layers[net.n - 1]; + int j; + + detector_gpu.avg = (float*)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.predictions[j] = (float*)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.images[j] = make_image(1, 1, 3); + + detector_gpu.track_id = (unsigned int*)calloc(l.classes, sizeof(unsigned int)); + for (j = 0; j < l.classes; ++j) detector_gpu.track_id[j] = 1; + + if (_useGPU) { + check_cuda(cudaSetDevice(old_gpu_index)); + } +} + +LIB_API Detector::~Detector() +{ + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + //layer l = detector_gpu.net.layers[detector_gpu.net.n - 1]; + + free(detector_gpu.track_id); + + free(detector_gpu.avg); + for (int j = 0; j < NFRAMES; ++j) free(detector_gpu.predictions[j]); + for (int j = 0; j < NFRAMES; ++j) if (detector_gpu.images[j].data) free(detector_gpu.images[j].data); + int old_gpu_index; + if (_useGPU) { + cudaGetDevice(&old_gpu_index); + cuda_set_device(detector_gpu.net.gpu_index); + } + free_network(detector_gpu.net); + if (_useGPU) { + cudaSetDevice(old_gpu_index); + } +} + +LIB_API int Detector::get_net_width() const { + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + return detector_gpu.net.w; +} +LIB_API int Detector::get_net_height() const { + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + return detector_gpu.net.h; +} +LIB_API int Detector::get_net_color_depth() const { + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + return detector_gpu.net.c; +} + + +LIB_API std::vector Detector::detect(std::string image_filename, float thresh, bool use_mean) +{ + std::shared_ptr image_ptr(new image_t, [](image_t *img) { if (img->data) free(img->data); delete img; }); + *image_ptr = load_image(image_filename); + return detect(*image_ptr, thresh, use_mean); +} + +static image load_image_stb(char *filename, int channels) +{ + int w, h, c; + unsigned char *data = stbi_load(filename, &w, &h, &c, channels); + if (!data) + throw std::runtime_error("file not found"); + if (channels) c = channels; + int i, j, k; + image im = make_image(w, h, c); + for (k = 0; k < c; ++k) { + for (j = 0; j < h; ++j) { + for (i = 0; i < w; ++i) { + int dst_index = i + w*j + w*h*k; + int src_index = k + c*i + c*w*j; + im.data[dst_index] = (float)data[src_index] / 255.; + } + } + } + free(data); + return im; +} + +LIB_API image_t Detector::load_image(std::string image_filename) +{ + char *input = const_cast(image_filename.c_str()); + image im = load_image_stb(input, 3); + + image_t img; + img.c = im.c; + img.data = im.data; + img.h = im.h; + img.w = im.w; + + return img; +} + + +LIB_API void Detector::free_image(image_t m) +{ + if (m.data) { + free(m.data); + } +} + +LIB_API std::vector Detector::detect(image_t img, float thresh, bool use_mean) +{ + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + network &net = detector_gpu.net; + int old_gpu_index; + if (_useGPU) { + cudaGetDevice(&old_gpu_index); + if (cur_gpu_id != old_gpu_index) + cudaSetDevice(net.gpu_index); + + net.wait_stream = wait_stream; // 1 - wait CUDA-stream, 0 - not to wait + } + image im; + im.c = img.c; + im.data = img.data; + im.h = img.h; + im.w = img.w; + + image sized; + + if (net.w == im.w && net.h == im.h) { + sized = make_image(im.w, im.h, im.c); + memcpy(sized.data, im.data, im.w*im.h*im.c * sizeof(float)); + } + else + sized = resize_image(im, net.w, net.h); + + layer l = net.layers[net.n - 1]; + + float *X = sized.data; + + float *prediction = network_predict(net, X); + + if (use_mean) { + memcpy(detector_gpu.predictions[detector_gpu.demo_index], prediction, l.outputs * sizeof(float)); + mean_arrays(detector_gpu.predictions, NFRAMES, l.outputs, detector_gpu.avg); + l.output = detector_gpu.avg; + detector_gpu.demo_index = (detector_gpu.demo_index + 1) % NFRAMES; + } + //get_region_boxes(l, 1, 1, thresh, detector_gpu.probs, detector_gpu.boxes, 0, 0); + //if (nms) do_nms_sort(detector_gpu.boxes, detector_gpu.probs, l.w*l.h*l.n, l.classes, nms); + + int nboxes = 0; + int letterbox = 0; + float hier_thresh = 0.5; + detection *dets = get_network_boxes(&net, im.w, im.h, thresh, hier_thresh, 0, 1, &nboxes, letterbox); + if (nms) do_nms_sort(dets, nboxes, l.classes, nms); + + std::vector bbox_vec; + + for (int i = 0; i < nboxes; ++i) { + box b = dets[i].bbox; + int const obj_id = max_index(dets[i].prob, l.classes); + float const prob = dets[i].prob[obj_id]; + + if (prob > thresh) + { + bbox_t bbox; + bbox.x = std::max((double)0, (b.x - b.w / 2.)*im.w); + bbox.y = std::max((double)0, (b.y - b.h / 2.)*im.h); + bbox.w = b.w*im.w; + bbox.h = b.h*im.h; + bbox.obj_id = obj_id; + bbox.prob = prob; + bbox.track_id = 0; + bbox.frames_counter = 0; + bbox.x_3d = NAN; + bbox.y_3d = NAN; + bbox.z_3d = NAN; + + bbox_vec.push_back(bbox); + } + } + + free_detections(dets, nboxes); + if(sized.data) + free(sized.data); + if (_useGPU) { + if (cur_gpu_id != old_gpu_index) + cudaSetDevice(old_gpu_index); + } + return bbox_vec; +} + +LIB_API std::vector> Detector::detectBatch(image_t img, int batch_size, int width, int height, float thresh, bool make_nms) +{ + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + network &net = detector_gpu.net; + int old_gpu_index=0; + if (_useGPU) { + int old_gpu_index; + cudaGetDevice(&old_gpu_index); + if (cur_gpu_id != old_gpu_index) + cudaSetDevice(net.gpu_index); + + net.wait_stream = wait_stream; // 1 - wait CUDA-stream, 0 - not to wait + } + //std::cout << "net.gpu_index = " << net.gpu_index << std::endl; + layer l = net.layers[net.n - 1]; + float hier_thresh = 0.5; + image in_img; + in_img.c = img.c; + in_img.w = img.w; + in_img.h = img.h; + in_img.data = img.data; + det_num_pair* prediction = network_predict_batch(&net, in_img, batch_size, width, height, thresh, hier_thresh, 0, 0, 0); + + std::vector> bbox_vec(batch_size); + + for (int bi = 0; bi < batch_size; ++bi) + { + auto dets = prediction[bi].dets; + + if (make_nms && nms) + do_nms_sort(dets, prediction[bi].num, l.classes, nms); + + for (int i = 0; i < prediction[bi].num; ++i) + { + box b = dets[i].bbox; + int const obj_id = max_index(dets[i].prob, l.classes); + float const prob = dets[i].prob[obj_id]; + + if (prob > thresh) + { + bbox_t bbox; + bbox.x = std::max((double)0, (b.x - b.w / 2.)); + bbox.y = std::max((double)0, (b.y - b.h / 2.)); + bbox.w = b.w; + bbox.h = b.h; + bbox.obj_id = obj_id; + bbox.prob = prob; + bbox.track_id = 0; + bbox.frames_counter = 0; + bbox.x_3d = NAN; + bbox.y_3d = NAN; + bbox.z_3d = NAN; + + bbox_vec[bi].push_back(bbox); + } + } + } + free_batch_detections(prediction, batch_size); + + if (_useGPU) { + if (cur_gpu_id != old_gpu_index) + cudaSetDevice(old_gpu_index); + } + + return bbox_vec; +} + +LIB_API std::vector Detector::tracking_id(std::vector cur_bbox_vec, bool const change_history, + int const frames_story, int const max_dist) +{ + detector_gpu_t &det_gpu = *static_cast(detector_gpu_ptr.get()); + + bool prev_track_id_present = false; + for (auto &i : prev_bbox_vec_deque) + if (i.size() > 0) prev_track_id_present = true; + + if (!prev_track_id_present) { + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + cur_bbox_vec[i].track_id = det_gpu.track_id[cur_bbox_vec[i].obj_id]++; + prev_bbox_vec_deque.push_front(cur_bbox_vec); + if (prev_bbox_vec_deque.size() > frames_story) prev_bbox_vec_deque.pop_back(); + return cur_bbox_vec; + } + + std::vector dist_vec(cur_bbox_vec.size(), std::numeric_limits::max()); + + for (auto &prev_bbox_vec : prev_bbox_vec_deque) { + for (auto &i : prev_bbox_vec) { + int cur_index = -1; + for (size_t m = 0; m < cur_bbox_vec.size(); ++m) { + bbox_t const& k = cur_bbox_vec[m]; + if (i.obj_id == k.obj_id) { + float center_x_diff = (float)(i.x + i.w/2) - (float)(k.x + k.w/2); + float center_y_diff = (float)(i.y + i.h/2) - (float)(k.y + k.h/2); + unsigned int cur_dist = sqrt(center_x_diff*center_x_diff + center_y_diff*center_y_diff); + if (cur_dist < max_dist && (k.track_id == 0 || dist_vec[m] > cur_dist)) { + dist_vec[m] = cur_dist; + cur_index = m; + } + } + } + + bool track_id_absent = !std::any_of(cur_bbox_vec.begin(), cur_bbox_vec.end(), + [&i](bbox_t const& b) { return b.track_id == i.track_id && b.obj_id == i.obj_id; }); + + if (cur_index >= 0 && track_id_absent){ + cur_bbox_vec[cur_index].track_id = i.track_id; + cur_bbox_vec[cur_index].w = (cur_bbox_vec[cur_index].w + i.w) / 2; + cur_bbox_vec[cur_index].h = (cur_bbox_vec[cur_index].h + i.h) / 2; + } + } + } + + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + if (cur_bbox_vec[i].track_id == 0) + cur_bbox_vec[i].track_id = det_gpu.track_id[cur_bbox_vec[i].obj_id]++; + + if (change_history) { + prev_bbox_vec_deque.push_front(cur_bbox_vec); + if (prev_bbox_vec_deque.size() > frames_story) prev_bbox_vec_deque.pop_back(); + } + + return cur_bbox_vec; +} + + +void *Detector::get_cuda_context() +{ + int old_gpu_index; + if (_useGPU) { + cudaGetDevice(&old_gpu_index); + if (cur_gpu_id != old_gpu_index) + cudaSetDevice(cur_gpu_id); + + void* cuda_context = cuda_get_context(); + + if (cur_gpu_id != old_gpu_index) + cudaSetDevice(old_gpu_index); + + return cuda_context; + } + else return NULL; +} diff --git a/ODHUBYOLODarknet_old/src/yolo_v2cpuclass.cpp b/ODHUBYOLODarknet_old/src/yolo_v2cpuclass.cpp new file mode 100644 index 00000000..e66d2e2e --- /dev/null +++ b/ODHUBYOLODarknet_old/src/yolo_v2cpuclass.cpp @@ -0,0 +1,456 @@ +#include "darknet.h" +#include "yolo_v2cpu_class.hpp" +#include "network.h" +extern "C" { +#include "detection_layer.h" +#include "region_layer.h" +#include "cost_layer.h" +#include "utils.h" +#include "parser.h" +#include "box.h" +#include "image.h" +#include "demo.h" +#include "option_list.h" +#include +} +//#include + +#include +#include +#include +#include + +#define NFRAMES 3 + +//static Detector* detector = NULL; +static std::unique_ptr detector; + +int init(const char *configurationFilename, const char *weightsFilename, int gpu, int batch_size) +{ + detector.reset(new CPUDetector(configurationFilename, weightsFilename, gpu, batch_size)); + return 1; +} +int detect_image(const char *filename, bbox_t_container &container) +{ + std::vector detection = detector->detect(filename); + for (size_t i = 0; i < detection.size() && i < C_SHARP_MAX_OBJECTS; ++i) + container.candidates[i] = detection[i]; + return detection.size(); +} +int detect_mat(const uint8_t* data, const size_t data_length, bbox_t_container &container) { + std::vector vdata(data, data + data_length); + cv::Mat image = imdecode(cv::Mat(vdata), 1); + std::vector detection = detector->detect(image); + for (size_t i = 0; i < detection.size() && i < C_SHARP_MAX_OBJECTS; ++i) + container.candidates[i] = detection[i]; + return detection.size(); +} + +int dispose() { + detector.reset(); + return 1; +} + +int get_device_count(bool useGPU) { + + return -1; +} + +bool built_with_cuda(bool useGPU){ + return useGPU; +} + +bool built_with_cudnn(bool useGPU){ + return useGPU; +} + +bool built_with_opencv(){ + return true; +} + + +int get_device_name(int gpu, char* deviceName) { + + return -1; +} + + + +struct detector_gpu_t { + network net; + image images[NFRAMES]; + float *avg; + float* predictions[NFRAMES]; + int demo_index; + unsigned int *track_id; +}; +LIB_API CPUDetector::CPUDetector() { + wait_stream = 0; + cur_gpu_id = 0; + _useGPU = false; +} +LIB_API CPUDetector::CPUDetector(std::string cfg_filename, std::string weight_filename, int gpu_id, int batch_size) + : cur_gpu_id(gpu_id) +{ + wait_stream = 0; + if (gpu_id < 0) _useGPU = false; + else _useGPU = true; + int old_gpu_index; + + detector_gpu_ptr = std::make_shared(); + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + + if (_useGPU) { + cuda_set_device(cur_gpu_id); + printf(" Used GPU %d \n", cur_gpu_id); + } + network &net = detector_gpu.net; + net.gpu_index = cur_gpu_id; + + _cfg_filename = cfg_filename; + _weight_filename = weight_filename; + + char *cfgfile = const_cast(_cfg_filename.c_str()); + char *weightfile = const_cast(_weight_filename.c_str()); + + net = parse_network_cfg_custom(cfgfile, batch_size, batch_size); + if (weightfile) { + load_weights(&net, weightfile); + } + set_batch_network(&net, batch_size); + net.gpu_index = cur_gpu_id; + fuse_conv_batchnorm(net); + + layer l = net.layers[net.n - 1]; + int j; + + detector_gpu.avg = (float *)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.predictions[j] = (float*)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.images[j] = make_image(1, 1, 3); + + detector_gpu.track_id = (unsigned int *)calloc(l.classes, sizeof(unsigned int)); + for (j = 0; j < l.classes; ++j) detector_gpu.track_id[j] = 1; + + +} + +LIB_API void CPUDetector::Init(std::string cfg_filename, std::string weight_filename, int gpu_id, int batch_size) { + wait_stream = 0; + if (gpu_id < 0) _useGPU = false; + else { + cur_gpu_id = gpu_id; + _useGPU = true; + } + int old_gpu_index; + + detector_gpu_ptr = std::make_shared(); + detector_gpu_t& detector_gpu = *static_cast(detector_gpu_ptr.get()); + + if (_useGPU) { + cuda_set_device(cur_gpu_id); + printf(" Used GPU %d \n", cur_gpu_id); + } + network& net = detector_gpu.net; + net.gpu_index = cur_gpu_id; + + _cfg_filename = cfg_filename; + _weight_filename = weight_filename; + + char* cfgfile = const_cast(_cfg_filename.c_str()); + char* weightfile = const_cast(_weight_filename.c_str()); + + net = parse_network_cfg_custom(cfgfile, batch_size, batch_size); + if (weightfile) { + load_weights(&net, weightfile); + } + set_batch_network(&net, batch_size); + net.gpu_index = cur_gpu_id; + fuse_conv_batchnorm(net); + + layer l = net.layers[net.n - 1]; + int j; + + detector_gpu.avg = (float*)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.predictions[j] = (float*)calloc(l.outputs, sizeof(float)); + for (j = 0; j < NFRAMES; ++j) detector_gpu.images[j] = make_image(1, 1, 3); + + detector_gpu.track_id = (unsigned int*)calloc(l.classes, sizeof(unsigned int)); + for (j = 0; j < l.classes; ++j) detector_gpu.track_id[j] = 1; + + +} + +LIB_API CPUDetector::~CPUDetector() +{ + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + //layer l = detector_gpu.net.layers[detector_gpu.net.n - 1]; + + free(detector_gpu.track_id); + + free(detector_gpu.avg); + for (int j = 0; j < NFRAMES; ++j) free(detector_gpu.predictions[j]); + for (int j = 0; j < NFRAMES; ++j) if (detector_gpu.images[j].data) free(detector_gpu.images[j].data); + + free_network(detector_gpu.net); + +} + +LIB_API int CPUDetector::get_net_width() const { + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + return detector_gpu.net.w; +} +LIB_API int CPUDetector::get_net_height() const { + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + return detector_gpu.net.h; +} +LIB_API int CPUDetector::get_net_color_depth() const { + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + return detector_gpu.net.c; +} + + +LIB_API std::vector CPUDetector::detect(std::string image_filename, float thresh, bool use_mean) +{ + std::shared_ptr image_ptr(new image_t, [](image_t *img) { if (img->data) free(img->data); delete img; }); + *image_ptr = load_image(image_filename); + return detect(*image_ptr, thresh, use_mean); +} + +static image load_image_stb(char *filename, int channels) +{ + int w, h, c; + unsigned char *data = stbi_load(filename, &w, &h, &c, channels); + if (!data) + throw std::runtime_error("file not found"); + if (channels) c = channels; + int i, j, k; + image im = make_image(w, h, c); + for (k = 0; k < c; ++k) { + for (j = 0; j < h; ++j) { + for (i = 0; i < w; ++i) { + int dst_index = i + w*j + w*h*k; + int src_index = k + c*i + c*w*j; + im.data[dst_index] = (float)data[src_index] / 255.; + } + } + } + free(data); + return im; +} + +LIB_API image_t CPUDetector::load_image(std::string image_filename) +{ + char *input = const_cast(image_filename.c_str()); + image im = load_image_stb(input, 3); + + image_t img; + img.c = im.c; + img.data = im.data; + img.h = im.h; + img.w = im.w; + + return img; +} + + +LIB_API void CPUDetector::free_image(image_t m) +{ + if (m.data) { + free(m.data); + } +} + +LIB_API std::vector CPUDetector::detect(image_t img, float thresh, bool use_mean) +{ + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + network &net = detector_gpu.net; + int old_gpu_index; + image im; + im.c = img.c; + im.data = img.data; + im.h = img.h; + im.w = img.w; + + image sized; + + if (net.w == im.w && net.h == im.h) { + sized = make_image(im.w, im.h, im.c); + memcpy(sized.data, im.data, im.w*im.h*im.c * sizeof(float)); + } + else + sized = resize_image(im, net.w, net.h); + + layer l = net.layers[net.n - 1]; + + float *X = sized.data; + + float *prediction = network_predict(net, X); + + if (use_mean) { + memcpy(detector_gpu.predictions[detector_gpu.demo_index], prediction, l.outputs * sizeof(float)); + mean_arrays(detector_gpu.predictions, NFRAMES, l.outputs, detector_gpu.avg); + l.output = detector_gpu.avg; + detector_gpu.demo_index = (detector_gpu.demo_index + 1) % NFRAMES; + } + //get_region_boxes(l, 1, 1, thresh, detector_gpu.probs, detector_gpu.boxes, 0, 0); + //if (nms) do_nms_sort(detector_gpu.boxes, detector_gpu.probs, l.w*l.h*l.n, l.classes, nms); + + int nboxes = 0; + int letterbox = 0; + float hier_thresh = 0.5; + detection *dets = get_network_boxes(&net, im.w, im.h, thresh, hier_thresh, 0, 1, &nboxes, letterbox); + if (nms) do_nms_sort(dets, nboxes, l.classes, nms); + + std::vector bbox_vec; + + for (int i = 0; i < nboxes; ++i) { + box b = dets[i].bbox; + int const obj_id = max_index(dets[i].prob, l.classes); + float const prob = dets[i].prob[obj_id]; + + if (prob > thresh) + { + bbox_t bbox; + bbox.x = std::max((double)0, (b.x - b.w / 2.)*im.w); + bbox.y = std::max((double)0, (b.y - b.h / 2.)*im.h); + bbox.w = b.w*im.w; + bbox.h = b.h*im.h; + bbox.obj_id = obj_id; + bbox.prob = prob; + bbox.track_id = 0; + bbox.frames_counter = 0; + bbox.x_3d = NAN; + bbox.y_3d = NAN; + bbox.z_3d = NAN; + + bbox_vec.push_back(bbox); + } + } + + free_detections(dets, nboxes); + if(sized.data) + free(sized.data); + + return bbox_vec; +} + +LIB_API std::vector> CPUDetector::detectBatch(image_t img, int batch_size, int width, int height, float thresh, bool make_nms) +{ + detector_gpu_t &detector_gpu = *static_cast(detector_gpu_ptr.get()); + network &net = detector_gpu.net; + int old_gpu_index=0; + + //std::cout << "net.gpu_index = " << net.gpu_index << std::endl; + layer l = net.layers[net.n - 1]; + float hier_thresh = 0.5; + image in_img; + in_img.c = img.c; + in_img.w = img.w; + in_img.h = img.h; + in_img.data = img.data; + det_num_pair* prediction = network_predict_batch(&net, in_img, batch_size, width, height, thresh, hier_thresh, 0, 0, 0); + + std::vector> bbox_vec(batch_size); + + for (int bi = 0; bi < batch_size; ++bi) + { + auto dets = prediction[bi].dets; + + if (make_nms && nms) + do_nms_sort(dets, prediction[bi].num, l.classes, nms); + + for (int i = 0; i < prediction[bi].num; ++i) + { + box b = dets[i].bbox; + int const obj_id = max_index(dets[i].prob, l.classes); + float const prob = dets[i].prob[obj_id]; + + if (prob > thresh) + { + bbox_t bbox; + bbox.x = std::max((double)0, (b.x - b.w / 2.)); + bbox.y = std::max((double)0, (b.y - b.h / 2.)); + bbox.w = b.w; + bbox.h = b.h; + bbox.obj_id = obj_id; + bbox.prob = prob; + bbox.track_id = 0; + bbox.frames_counter = 0; + bbox.x_3d = NAN; + bbox.y_3d = NAN; + bbox.z_3d = NAN; + + bbox_vec[bi].push_back(bbox); + } + } + } + free_batch_detections(prediction, batch_size); + + + + return bbox_vec; +} + +LIB_API std::vector CPUDetector::tracking_id(std::vector cur_bbox_vec, bool const change_history, + int const frames_story, int const max_dist) +{ + detector_gpu_t &det_gpu = *static_cast(detector_gpu_ptr.get()); + + bool prev_track_id_present = false; + for (auto &i : prev_bbox_vec_deque) + if (i.size() > 0) prev_track_id_present = true; + + if (!prev_track_id_present) { + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + cur_bbox_vec[i].track_id = det_gpu.track_id[cur_bbox_vec[i].obj_id]++; + prev_bbox_vec_deque.push_front(cur_bbox_vec); + if (prev_bbox_vec_deque.size() > frames_story) prev_bbox_vec_deque.pop_back(); + return cur_bbox_vec; + } + + std::vector dist_vec(cur_bbox_vec.size(), std::numeric_limits::max()); + + for (auto &prev_bbox_vec : prev_bbox_vec_deque) { + for (auto &i : prev_bbox_vec) { + int cur_index = -1; + for (size_t m = 0; m < cur_bbox_vec.size(); ++m) { + bbox_t const& k = cur_bbox_vec[m]; + if (i.obj_id == k.obj_id) { + float center_x_diff = (float)(i.x + i.w/2) - (float)(k.x + k.w/2); + float center_y_diff = (float)(i.y + i.h/2) - (float)(k.y + k.h/2); + unsigned int cur_dist = sqrt(center_x_diff*center_x_diff + center_y_diff*center_y_diff); + if (cur_dist < max_dist && (k.track_id == 0 || dist_vec[m] > cur_dist)) { + dist_vec[m] = cur_dist; + cur_index = m; + } + } + } + + bool track_id_absent = !std::any_of(cur_bbox_vec.begin(), cur_bbox_vec.end(), + [&i](bbox_t const& b) { return b.track_id == i.track_id && b.obj_id == i.obj_id; }); + + if (cur_index >= 0 && track_id_absent){ + cur_bbox_vec[cur_index].track_id = i.track_id; + cur_bbox_vec[cur_index].w = (cur_bbox_vec[cur_index].w + i.w) / 2; + cur_bbox_vec[cur_index].h = (cur_bbox_vec[cur_index].h + i.h) / 2; + } + } + } + + for (size_t i = 0; i < cur_bbox_vec.size(); ++i) + if (cur_bbox_vec[i].track_id == 0) + cur_bbox_vec[i].track_id = det_gpu.track_id[cur_bbox_vec[i].obj_id]++; + + if (change_history) { + prev_bbox_vec_deque.push_front(cur_bbox_vec); + if (prev_bbox_vec_deque.size() > frames_story) prev_bbox_vec_deque.pop_back(); + } + + return cur_bbox_vec; +} + + +void * CPUDetector::get_cuda_context() +{ + return NULL; +} diff --git a/OpenVINO/runtime/cmake/OpenVINOTargets-debug.cmake b/OpenVINO/runtime/cmake/OpenVINOTargets-debug.cmake.disabled similarity index 100% rename from OpenVINO/runtime/cmake/OpenVINOTargets-debug.cmake rename to OpenVINO/runtime/cmake/OpenVINOTargets-debug.cmake.disabled diff --git a/depends22_x64/depends.chm b/depends22_x64/depends.chm new file mode 100644 index 00000000..23c18408 Binary files /dev/null and b/depends22_x64/depends.chm differ diff --git a/depends22_x64/depends.dll b/depends22_x64/depends.dll new file mode 100644 index 00000000..8a91f593 Binary files /dev/null and b/depends22_x64/depends.dll differ diff --git a/depends22_x64/depends.exe b/depends22_x64/depends.exe new file mode 100644 index 00000000..acda2643 Binary files /dev/null and b/depends22_x64/depends.exe differ diff --git a/ffmpeg-n8.1/LICENSE.txt b/ffmpeg-n8.1/LICENSE.txt new file mode 100644 index 00000000..65c5ca88 --- /dev/null +++ b/ffmpeg-n8.1/LICENSE.txt @@ -0,0 +1,165 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + + This version of the GNU Lesser General Public License incorporates +the terms and conditions of version 3 of the GNU General Public +License, supplemented by the additional permissions listed below. + + 0. Additional Definitions. + + As used herein, "this License" refers to version 3 of the GNU Lesser +General Public License, and the "GNU GPL" refers to version 3 of the GNU +General Public License. + + "The Library" refers to a covered work governed by this License, +other than an Application or a Combined Work as defined below. + + An "Application" is any work that makes use of an interface provided +by the Library, but which is not otherwise based on the Library. +Defining a subclass of a class defined by the Library is deemed a mode +of using an interface provided by the Library. + + A "Combined Work" is a work produced by combining or linking an +Application with the Library. The particular version of the Library +with which the Combined Work was made is also called the "Linked +Version". + + The "Minimal Corresponding Source" for a Combined Work means the +Corresponding Source for the Combined Work, excluding any source code +for portions of the Combined Work that, considered in isolation, are +based on the Application, and not on the Linked Version. + + The "Corresponding Application Code" for a Combined Work means the +object code and/or source code for the Application, including any data +and utility programs needed for reproducing the Combined Work from the +Application, but excluding the System Libraries of the Combined Work. + + 1. Exception to Section 3 of the GNU GPL. + + You may convey a covered work under sections 3 and 4 of this License +without being bound by section 3 of the GNU GPL. + + 2. Conveying Modified Versions. + + If you modify a copy of the Library, and, in your modifications, a +facility refers to a function or data to be supplied by an Application +that uses the facility (other than as an argument passed when the +facility is invoked), then you may convey a copy of the modified +version: + + a) under this License, provided that you make a good faith effort to + ensure that, in the event an Application does not supply the + function or data, the facility still operates, and performs + whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of + this License applicable to that copy. + + 3. Object Code Incorporating Material from Library Header Files. + + The object code form of an Application may incorporate material from +a header file that is part of the Library. You may convey such object +code under terms of your choice, provided that, if the incorporated +material is not limited to numerical parameters, data structure +layouts and accessors, or small macros, inline functions and templates +(ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the + Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license + document. + + 4. Combined Works. + + You may convey a Combined Work under terms of your choice that, +taken together, effectively do not restrict modification of the +portions of the Library contained in the Combined Work and reverse +engineering for debugging such modifications, if you also do each of +the following: + + a) Give prominent notice with each copy of the Combined Work that + the Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license + document. + + c) For a Combined Work that displays copyright notices during + execution, include the copyright notice for the Library among + these notices, as well as a reference directing the user to the + copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this + License, and the Corresponding Application Code in a form + suitable for, and under terms that permit, the user to + recombine or relink the Application with a modified version of + the Linked Version to produce a modified Combined Work, in the + manner specified by section 6 of the GNU GPL for conveying + Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (a) uses at run time + a copy of the Library already present on the user's computer + system, and (b) will operate properly with a modified version + of the Library that is interface-compatible with the Linked + Version. + + e) Provide Installation Information, but only if you would otherwise + be required to provide such information under section 6 of the + GNU GPL, and only to the extent that such information is + necessary to install and execute a modified version of the + Combined Work produced by recombining or relinking the + Application with a modified version of the Linked Version. (If + you use option 4d0, the Installation Information must accompany + the Minimal Corresponding Source and Corresponding Application + Code. If you use option 4d1, you must provide the Installation + Information in the manner specified by section 6 of the GNU GPL + for conveying Corresponding Source.) + + 5. Combined Libraries. + + You may place library facilities that are a work based on the +Library side by side in a single library together with other library +facilities that are not Applications and are not covered by this +License, and convey such a combined library under terms of your +choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities, + conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it + is a work based on the Library, and explaining where to find the + accompanying uncombined form of the same work. + + 6. Revised Versions of the GNU Lesser General Public License. + + The Free Software Foundation may publish revised and/or new versions +of the GNU Lesser General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the +Library as you received it specifies that a certain numbered version +of the GNU Lesser General Public License "or any later version" +applies to it, you have the option of following the terms and +conditions either of that published version or of any later version +published by the Free Software Foundation. If the Library as you +received it does not specify a version number of the GNU Lesser +General Public License, you may choose any version of the GNU Lesser +General Public License ever published by the Free Software Foundation. + + If the Library as you received it specifies that a proxy can decide +whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is +permanent authorization for you to choose that version for the +Library. diff --git a/ffmpeg-n8.1/bin/avcodec-62.dll b/ffmpeg-n8.1/bin/avcodec-62.dll new file mode 100644 index 00000000..90182368 Binary files /dev/null and b/ffmpeg-n8.1/bin/avcodec-62.dll differ diff --git a/ffmpeg-n8.1/bin/avdevice-62.dll b/ffmpeg-n8.1/bin/avdevice-62.dll new file mode 100644 index 00000000..282aaccc Binary files /dev/null and b/ffmpeg-n8.1/bin/avdevice-62.dll differ diff --git a/ffmpeg-n8.1/bin/avfilter-11.dll b/ffmpeg-n8.1/bin/avfilter-11.dll new file mode 100644 index 00000000..df19ddc8 Binary files /dev/null and b/ffmpeg-n8.1/bin/avfilter-11.dll differ diff --git a/ffmpeg-n8.1/bin/avformat-62.dll b/ffmpeg-n8.1/bin/avformat-62.dll new file mode 100644 index 00000000..1a0d61cd Binary files /dev/null and b/ffmpeg-n8.1/bin/avformat-62.dll differ diff --git a/ffmpeg-n8.1/bin/avutil-60.dll b/ffmpeg-n8.1/bin/avutil-60.dll new file mode 100644 index 00000000..82d827ea Binary files /dev/null and b/ffmpeg-n8.1/bin/avutil-60.dll differ diff --git a/ffmpeg-n8.1/bin/ffmpeg.exe b/ffmpeg-n8.1/bin/ffmpeg.exe new file mode 100644 index 00000000..7b476e6e Binary files /dev/null and b/ffmpeg-n8.1/bin/ffmpeg.exe differ diff --git a/ffmpeg-n8.1/bin/ffplay.exe b/ffmpeg-n8.1/bin/ffplay.exe new file mode 100644 index 00000000..7c5089d7 Binary files /dev/null and b/ffmpeg-n8.1/bin/ffplay.exe differ diff --git a/ffmpeg-n8.1/bin/ffprobe.exe b/ffmpeg-n8.1/bin/ffprobe.exe new file mode 100644 index 00000000..f693b3ff Binary files /dev/null and b/ffmpeg-n8.1/bin/ffprobe.exe differ diff --git a/ffmpeg-n8.1/bin/swresample-6.dll b/ffmpeg-n8.1/bin/swresample-6.dll new file mode 100644 index 00000000..08a5ded9 Binary files /dev/null and b/ffmpeg-n8.1/bin/swresample-6.dll differ diff --git a/ffmpeg-n8.1/bin/swscale-9.dll b/ffmpeg-n8.1/bin/swscale-9.dll new file mode 100644 index 00000000..090336e6 Binary files /dev/null and b/ffmpeg-n8.1/bin/swscale-9.dll differ diff --git a/ffmpeg-n8.1/doc/bootstrap.min.css b/ffmpeg-n8.1/doc/bootstrap.min.css new file mode 100644 index 00000000..45bf263d --- /dev/null +++ b/ffmpeg-n8.1/doc/bootstrap.min.css @@ -0,0 +1,5 @@ +/*! + * Bootstrap v3.2.0 (http://getbootstrap.com) + * Copyright 2011-2014 Twitter, Inc. + * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE) + *//*! normalize.css v3.0.1 | MIT License | git.io/normalize */html{font-family:sans-serif;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}audio,canvas,progress,video{display:inline-block;vertical-align:baseline}audio:not([controls]){display:none;height:0}[hidden],template{display:none}a{background:0 0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}dfn{font-style:italic}h1{margin:.67em 0;font-size:2em}mark{color:#000;background:#ff0}small{font-size:80%}sub,sup{position:relative;font-size:75%;line-height:0;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}img{border:0}svg:not(:root){overflow:hidden}figure{margin:1em 40px}hr{height:0;-webkit-box-sizing:content-box;-moz-box-sizing:content-box;box-sizing:content-box}pre{overflow:auto}code,kbd,pre,samp{font-family:monospace,monospace;font-size:1em}button,input,optgroup,select,textarea{margin:0;font:inherit;color:inherit}button{overflow:visible}button,select{text-transform:none}button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}button[disabled],html input[disabled]{cursor:default}button::-moz-focus-inner,input::-moz-focus-inner{padding:0;border:0}input{line-height:normal}input[type=checkbox],input[type=radio]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box;padding:0}input[type=number]::-webkit-inner-spin-button,input[type=number]::-webkit-outer-spin-button{height:auto}input[type=search]{-webkit-box-sizing:content-box;-moz-box-sizing:content-box;box-sizing:content-box;-webkit-appearance:textfield}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}fieldset{padding:.35em .625em .75em;margin:0 2px;border:1px solid silver}legend{padding:0;border:0}textarea{overflow:auto}optgroup{font-weight:700}table{border-spacing:0;border-collapse:collapse}td,th{padding:0}@media print{*{color:#000!important;text-shadow:none!important;background:transparent!important;-webkit-box-shadow:none!important;box-shadow:none!important}a,a:visited{text-decoration:underline}a[href]:after{content:" (" attr(href) ")"}abbr[title]:after{content:" (" attr(title) ")"}a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100%!important}p,h2,h3{orphans:3;widows:3}h2,h3{page-break-after:avoid}select{background:#fff!important}.navbar{display:none}.table td,.table th{background-color:#fff!important}.btn>.caret,.dropup>.btn>.caret{border-top-color:#000!important}.label{border:1px solid #000}.table{border-collapse:collapse!important}.table-bordered th,.table-bordered td{border:1px solid #ddd!important}}@font-face{font-family:'Glyphicons Halflings';src:url(../fonts/glyphicons-halflings-regular.eot);src:url(../fonts/glyphicons-halflings-regular.eot?#iefix) format('embedded-opentype'),url(../fonts/glyphicons-halflings-regular.woff) format('woff'),url(../fonts/glyphicons-halflings-regular.ttf) format('truetype'),url(../fonts/glyphicons-halflings-regular.svg#glyphicons_halflingsregular) format('svg')}.glyphicon{position:relative;top:1px;display:inline-block;font-family:'Glyphicons Halflings';font-style:normal;font-weight:400;line-height:1;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.glyphicon-asterisk:before{content:"\2a"}.glyphicon-plus:before{content:"\2b"}.glyphicon-euro:before{content:"\20ac"}.glyphicon-minus:before{content:"\2212"}.glyphicon-cloud:before{content:"\2601"}.glyphicon-envelope:before{content:"\2709"}.glyphicon-pencil:before{content:"\270f"}.glyphicon-glass:before{content:"\e001"}.glyphicon-music:before{content:"\e002"}.glyphicon-search:before{content:"\e003"}.glyphicon-heart:before{content:"\e005"}.glyphicon-star:before{content:"\e006"}.glyphicon-star-empty:before{content:"\e007"}.glyphicon-user:before{content:"\e008"}.glyphicon-film:before{content:"\e009"}.glyphicon-th-large:before{content:"\e010"}.glyphicon-th:before{content:"\e011"}.glyphicon-th-list:before{content:"\e012"}.glyphicon-ok:before{content:"\e013"}.glyphicon-remove:before{content:"\e014"}.glyphicon-zoom-in:before{content:"\e015"}.glyphicon-zoom-out:before{content:"\e016"}.glyphicon-off:before{content:"\e017"}.glyphicon-signal:before{content:"\e018"}.glyphicon-cog:before{content:"\e019"}.glyphicon-trash:before{content:"\e020"}.glyphicon-home:before{content:"\e021"}.glyphicon-file:before{content:"\e022"}.glyphicon-time:before{content:"\e023"}.glyphicon-road:before{content:"\e024"}.glyphicon-download-alt:before{content:"\e025"}.glyphicon-download:before{content:"\e026"}.glyphicon-upload:before{content:"\e027"}.glyphicon-inbox:before{content:"\e028"}.glyphicon-play-circle:before{content:"\e029"}.glyphicon-repeat:before{content:"\e030"}.glyphicon-refresh:before{content:"\e031"}.glyphicon-list-alt:before{content:"\e032"}.glyphicon-lock:before{content:"\e033"}.glyphicon-flag:before{content:"\e034"}.glyphicon-headphones:before{content:"\e035"}.glyphicon-volume-off:before{content:"\e036"}.glyphicon-volume-down:before{content:"\e037"}.glyphicon-volume-up:before{content:"\e038"}.glyphicon-qrcode:before{content:"\e039"}.glyphicon-barcode:before{content:"\e040"}.glyphicon-tag:before{content:"\e041"}.glyphicon-tags:before{content:"\e042"}.glyphicon-book:before{content:"\e043"}.glyphicon-bookmark:before{content:"\e044"}.glyphicon-print:before{content:"\e045"}.glyphicon-camera:before{content:"\e046"}.glyphicon-font:before{content:"\e047"}.glyphicon-bold:before{content:"\e048"}.glyphicon-italic:before{content:"\e049"}.glyphicon-text-height:before{content:"\e050"}.glyphicon-text-width:before{content:"\e051"}.glyphicon-align-left:before{content:"\e052"}.glyphicon-align-center:before{content:"\e053"}.glyphicon-align-right:before{content:"\e054"}.glyphicon-align-justify:before{content:"\e055"}.glyphicon-list:before{content:"\e056"}.glyphicon-indent-left:before{content:"\e057"}.glyphicon-indent-right:before{content:"\e058"}.glyphicon-facetime-video:before{content:"\e059"}.glyphicon-picture:before{content:"\e060"}.glyphicon-map-marker:before{content:"\e062"}.glyphicon-adjust:before{content:"\e063"}.glyphicon-tint:before{content:"\e064"}.glyphicon-edit:before{content:"\e065"}.glyphicon-share:before{content:"\e066"}.glyphicon-check:before{content:"\e067"}.glyphicon-move:before{content:"\e068"}.glyphicon-step-backward:before{content:"\e069"}.glyphicon-fast-backward:before{content:"\e070"}.glyphicon-backward:before{content:"\e071"}.glyphicon-play:before{content:"\e072"}.glyphicon-pause:before{content:"\e073"}.glyphicon-stop:before{content:"\e074"}.glyphicon-forward:before{content:"\e075"}.glyphicon-fast-forward:before{content:"\e076"}.glyphicon-step-forward:before{content:"\e077"}.glyphicon-eject:before{content:"\e078"}.glyphicon-chevron-left:before{content:"\e079"}.glyphicon-chevron-right:before{content:"\e080"}.glyphicon-plus-sign:before{content:"\e081"}.glyphicon-minus-sign:before{content:"\e082"}.glyphicon-remove-sign:before{content:"\e083"}.glyphicon-ok-sign:before{content:"\e084"}.glyphicon-question-sign:before{content:"\e085"}.glyphicon-info-sign:before{content:"\e086"}.glyphicon-screenshot:before{content:"\e087"}.glyphicon-remove-circle:before{content:"\e088"}.glyphicon-ok-circle:before{content:"\e089"}.glyphicon-ban-circle:before{content:"\e090"}.glyphicon-arrow-left:before{content:"\e091"}.glyphicon-arrow-right:before{content:"\e092"}.glyphicon-arrow-up:before{content:"\e093"}.glyphicon-arrow-down:before{content:"\e094"}.glyphicon-share-alt:before{content:"\e095"}.glyphicon-resize-full:before{content:"\e096"}.glyphicon-resize-small:before{content:"\e097"}.glyphicon-exclamation-sign:before{content:"\e101"}.glyphicon-gift:before{content:"\e102"}.glyphicon-leaf:before{content:"\e103"}.glyphicon-fire:before{content:"\e104"}.glyphicon-eye-open:before{content:"\e105"}.glyphicon-eye-close:before{content:"\e106"}.glyphicon-warning-sign:before{content:"\e107"}.glyphicon-plane:before{content:"\e108"}.glyphicon-calendar:before{content:"\e109"}.glyphicon-random:before{content:"\e110"}.glyphicon-comment:before{content:"\e111"}.glyphicon-magnet:before{content:"\e112"}.glyphicon-chevron-up:before{content:"\e113"}.glyphicon-chevron-down:before{content:"\e114"}.glyphicon-retweet:before{content:"\e115"}.glyphicon-shopping-cart:before{content:"\e116"}.glyphicon-folder-close:before{content:"\e117"}.glyphicon-folder-open:before{content:"\e118"}.glyphicon-resize-vertical:before{content:"\e119"}.glyphicon-resize-horizontal:before{content:"\e120"}.glyphicon-hdd:before{content:"\e121"}.glyphicon-bullhorn:before{content:"\e122"}.glyphicon-bell:before{content:"\e123"}.glyphicon-certificate:before{content:"\e124"}.glyphicon-thumbs-up:before{content:"\e125"}.glyphicon-thumbs-down:before{content:"\e126"}.glyphicon-hand-right:before{content:"\e127"}.glyphicon-hand-left:before{content:"\e128"}.glyphicon-hand-up:before{content:"\e129"}.glyphicon-hand-down:before{content:"\e130"}.glyphicon-circle-arrow-right:before{content:"\e131"}.glyphicon-circle-arrow-left:before{content:"\e132"}.glyphicon-circle-arrow-up:before{content:"\e133"}.glyphicon-circle-arrow-down:before{content:"\e134"}.glyphicon-globe:before{content:"\e135"}.glyphicon-wrench:before{content:"\e136"}.glyphicon-tasks:before{content:"\e137"}.glyphicon-filter:before{content:"\e138"}.glyphicon-briefcase:before{content:"\e139"}.glyphicon-fullscreen:before{content:"\e140"}.glyphicon-dashboard:before{content:"\e141"}.glyphicon-paperclip:before{content:"\e142"}.glyphicon-heart-empty:before{content:"\e143"}.glyphicon-link:before{content:"\e144"}.glyphicon-phone:before{content:"\e145"}.glyphicon-pushpin:before{content:"\e146"}.glyphicon-usd:before{content:"\e148"}.glyphicon-gbp:before{content:"\e149"}.glyphicon-sort:before{content:"\e150"}.glyphicon-sort-by-alphabet:before{content:"\e151"}.glyphicon-sort-by-alphabet-alt:before{content:"\e152"}.glyphicon-sort-by-order:before{content:"\e153"}.glyphicon-sort-by-order-alt:before{content:"\e154"}.glyphicon-sort-by-attributes:before{content:"\e155"}.glyphicon-sort-by-attributes-alt:before{content:"\e156"}.glyphicon-unchecked:before{content:"\e157"}.glyphicon-expand:before{content:"\e158"}.glyphicon-collapse-down:before{content:"\e159"}.glyphicon-collapse-up:before{content:"\e160"}.glyphicon-log-in:before{content:"\e161"}.glyphicon-flash:before{content:"\e162"}.glyphicon-log-out:before{content:"\e163"}.glyphicon-new-window:before{content:"\e164"}.glyphicon-record:before{content:"\e165"}.glyphicon-save:before{content:"\e166"}.glyphicon-open:before{content:"\e167"}.glyphicon-saved:before{content:"\e168"}.glyphicon-import:before{content:"\e169"}.glyphicon-export:before{content:"\e170"}.glyphicon-send:before{content:"\e171"}.glyphicon-floppy-disk:before{content:"\e172"}.glyphicon-floppy-saved:before{content:"\e173"}.glyphicon-floppy-remove:before{content:"\e174"}.glyphicon-floppy-save:before{content:"\e175"}.glyphicon-floppy-open:before{content:"\e176"}.glyphicon-credit-card:before{content:"\e177"}.glyphicon-transfer:before{content:"\e178"}.glyphicon-cutlery:before{content:"\e179"}.glyphicon-header:before{content:"\e180"}.glyphicon-compressed:before{content:"\e181"}.glyphicon-earphone:before{content:"\e182"}.glyphicon-phone-alt:before{content:"\e183"}.glyphicon-tower:before{content:"\e184"}.glyphicon-stats:before{content:"\e185"}.glyphicon-sd-video:before{content:"\e186"}.glyphicon-hd-video:before{content:"\e187"}.glyphicon-subtitles:before{content:"\e188"}.glyphicon-sound-stereo:before{content:"\e189"}.glyphicon-sound-dolby:before{content:"\e190"}.glyphicon-sound-5-1:before{content:"\e191"}.glyphicon-sound-6-1:before{content:"\e192"}.glyphicon-sound-7-1:before{content:"\e193"}.glyphicon-copyright-mark:before{content:"\e194"}.glyphicon-registration-mark:before{content:"\e195"}.glyphicon-cloud-download:before{content:"\e197"}.glyphicon-cloud-upload:before{content:"\e198"}.glyphicon-tree-conifer:before{content:"\e199"}.glyphicon-tree-deciduous:before{content:"\e200"}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}:before,:after{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:10px;-webkit-tap-highlight-color:rgba(0,0,0,0)}body{font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:14px;line-height:1.42857143;color:#333;background-color:#fff}input,button,select,textarea{font-family:inherit;font-size:inherit;line-height:inherit}a{color:#428bca;text-decoration:none}a:hover,a:focus{color:#2a6496;text-decoration:underline}a:focus{outline:thin dotted;outline:5px auto -webkit-focus-ring-color;outline-offset:-2px}figure{margin:0}img{vertical-align:middle}.img-responsive,.thumbnail>img,.thumbnail a>img,.carousel-inner>.item>img,.carousel-inner>.item>a>img{display:block;width:100% \9;max-width:100%;height:auto}.img-rounded{border-radius:6px}.img-thumbnail{display:inline-block;width:100% \9;max-width:100%;height:auto;padding:4px;line-height:1.42857143;background-color:#fff;border:1px solid #ddd;border-radius:4px;-webkit-transition:all .2s ease-in-out;-o-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.img-circle{border-radius:50%}hr{margin-top:20px;margin-bottom:20px;border:0;border-top:1px solid #eee}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}h1,h2,h3,h4,h5,h6,.h1,.h2,.h3,.h4,.h5,.h6{font-family:inherit;font-weight:500;line-height:1.1;color:inherit}h1 small,h2 small,h3 small,h4 small,h5 small,h6 small,.h1 small,.h2 small,.h3 small,.h4 small,.h5 small,.h6 small,h1 .small,h2 .small,h3 .small,h4 .small,h5 .small,h6 .small,.h1 .small,.h2 .small,.h3 .small,.h4 .small,.h5 .small,.h6 .small{font-weight:400;line-height:1;color:#777}h1,.h1,h2,.h2,h3,.h3{margin-top:20px;margin-bottom:10px}h1 small,.h1 small,h2 small,.h2 small,h3 small,.h3 small,h1 .small,.h1 .small,h2 .small,.h2 .small,h3 .small,.h3 .small{font-size:65%}h4,.h4,h5,.h5,h6,.h6{margin-top:10px;margin-bottom:10px}h4 small,.h4 small,h5 small,.h5 small,h6 small,.h6 small,h4 .small,.h4 .small,h5 .small,.h5 .small,h6 .small,.h6 .small{font-size:75%}h1,.h1{font-size:36px}h2,.h2{font-size:30px}h3,.h3{font-size:24px}h4,.h4{font-size:18px}h5,.h5{font-size:14px}h6,.h6{font-size:12px}p{margin:0 0 10px}.lead{margin-bottom:20px;font-size:16px;font-weight:300;line-height:1.4}@media (min-width:768px){.lead{font-size:21px}}small,.small{font-size:85%}cite{font-style:normal}mark,.mark{padding:.2em;background-color:#fcf8e3}.text-left{text-align:left}.text-right{text-align:right}.text-center{text-align:center}.text-justify{text-align:justify}.text-nowrap{white-space:nowrap}.text-lowercase{text-transform:lowercase}.text-uppercase{text-transform:uppercase}.text-capitalize{text-transform:capitalize}.text-muted{color:#777}.text-primary{color:#428bca}a.text-primary:hover{color:#3071a9}.text-success{color:#3c763d}a.text-success:hover{color:#2b542c}.text-info{color:#31708f}a.text-info:hover{color:#245269}.text-warning{color:#8a6d3b}a.text-warning:hover{color:#66512c}.text-danger{color:#a94442}a.text-danger:hover{color:#843534}.bg-primary{color:#fff;background-color:#428bca}a.bg-primary:hover{background-color:#3071a9}.bg-success{background-color:#dff0d8}a.bg-success:hover{background-color:#c1e2b3}.bg-info{background-color:#d9edf7}a.bg-info:hover{background-color:#afd9ee}.bg-warning{background-color:#fcf8e3}a.bg-warning:hover{background-color:#f7ecb5}.bg-danger{background-color:#f2dede}a.bg-danger:hover{background-color:#e4b9b9}.page-header{padding-bottom:9px;margin:40px 0 20px;border-bottom:1px solid #eee}ul,ol{margin-top:0;margin-bottom:10px}ul ul,ol ul,ul ol,ol ol{margin-bottom:0}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;margin-left:-5px;list-style:none}.list-inline>li{display:inline-block;padding-right:5px;padding-left:5px}dl{margin-top:0;margin-bottom:20px}dt,dd{line-height:1.42857143}dt{font-weight:700}dd{margin-left:0}@media (min-width:768px){.dl-horizontal dt{float:left;width:160px;overflow:hidden;clear:left;text-align:right;text-overflow:ellipsis;white-space:nowrap}.dl-horizontal dd{margin-left:180px}}abbr[title],abbr[data-original-title]{cursor:help;border-bottom:1px dotted #777}.initialism{font-size:90%;text-transform:uppercase}blockquote{padding:10px 20px;margin:0 0 20px;font-size:17.5px;border-left:5px solid #eee}blockquote p:last-child,blockquote ul:last-child,blockquote ol:last-child{margin-bottom:0}blockquote footer,blockquote small,blockquote .small{display:block;font-size:80%;line-height:1.42857143;color:#777}blockquote footer:before,blockquote small:before,blockquote .small:before{content:'\2014 \00A0'}.blockquote-reverse,blockquote.pull-right{padding-right:15px;padding-left:0;text-align:right;border-right:5px solid #eee;border-left:0}.blockquote-reverse footer:before,blockquote.pull-right footer:before,.blockquote-reverse small:before,blockquote.pull-right small:before,.blockquote-reverse .small:before,blockquote.pull-right .small:before{content:''}.blockquote-reverse footer:after,blockquote.pull-right footer:after,.blockquote-reverse small:after,blockquote.pull-right small:after,.blockquote-reverse .small:after,blockquote.pull-right .small:after{content:'\00A0 \2014'}blockquote:before,blockquote:after{content:""}address{margin-bottom:20px;font-style:normal;line-height:1.42857143}code,kbd,pre,samp{font-family:Menlo,Monaco,Consolas,"Courier New",monospace}code{padding:2px 4px;font-size:90%;color:#c7254e;background-color:#f9f2f4;border-radius:4px}kbd{padding:2px 4px;font-size:90%;color:#fff;background-color:#333;border-radius:3px;-webkit-box-shadow:inset 0 -1px 0 rgba(0,0,0,.25);box-shadow:inset 0 -1px 0 rgba(0,0,0,.25)}kbd kbd{padding:0;font-size:100%;-webkit-box-shadow:none;box-shadow:none}pre{display:block;padding:9.5px;margin:0 0 10px;font-size:13px;line-height:1.42857143;color:#333;word-break:break-all;word-wrap:break-word;background-color:#f5f5f5;border:1px solid #ccc;border-radius:4px}pre code{padding:0;font-size:inherit;color:inherit;white-space:pre-wrap;background-color:transparent;border-radius:0}.pre-scrollable{max-height:340px;overflow-y:scroll}.container{padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}@media (min-width:768px){.container{width:750px}}@media (min-width:992px){.container{width:970px}}@media (min-width:1200px){.container{width:1170px}}.container-fluid{padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}.row{margin-right:-15px;margin-left:-15px}.col-xs-1,.col-sm-1,.col-md-1,.col-lg-1,.col-xs-2,.col-sm-2,.col-md-2,.col-lg-2,.col-xs-3,.col-sm-3,.col-md-3,.col-lg-3,.col-xs-4,.col-sm-4,.col-md-4,.col-lg-4,.col-xs-5,.col-sm-5,.col-md-5,.col-lg-5,.col-xs-6,.col-sm-6,.col-md-6,.col-lg-6,.col-xs-7,.col-sm-7,.col-md-7,.col-lg-7,.col-xs-8,.col-sm-8,.col-md-8,.col-lg-8,.col-xs-9,.col-sm-9,.col-md-9,.col-lg-9,.col-xs-10,.col-sm-10,.col-md-10,.col-lg-10,.col-xs-11,.col-sm-11,.col-md-11,.col-lg-11,.col-xs-12,.col-sm-12,.col-md-12,.col-lg-12{position:relative;min-height:1px;padding-right:15px;padding-left:15px}.col-xs-1,.col-xs-2,.col-xs-3,.col-xs-4,.col-xs-5,.col-xs-6,.col-xs-7,.col-xs-8,.col-xs-9,.col-xs-10,.col-xs-11,.col-xs-12{float:left}.col-xs-12{width:100%}.col-xs-11{width:91.66666667%}.col-xs-10{width:83.33333333%}.col-xs-9{width:75%}.col-xs-8{width:66.66666667%}.col-xs-7{width:58.33333333%}.col-xs-6{width:50%}.col-xs-5{width:41.66666667%}.col-xs-4{width:33.33333333%}.col-xs-3{width:25%}.col-xs-2{width:16.66666667%}.col-xs-1{width:8.33333333%}.col-xs-pull-12{right:100%}.col-xs-pull-11{right:91.66666667%}.col-xs-pull-10{right:83.33333333%}.col-xs-pull-9{right:75%}.col-xs-pull-8{right:66.66666667%}.col-xs-pull-7{right:58.33333333%}.col-xs-pull-6{right:50%}.col-xs-pull-5{right:41.66666667%}.col-xs-pull-4{right:33.33333333%}.col-xs-pull-3{right:25%}.col-xs-pull-2{right:16.66666667%}.col-xs-pull-1{right:8.33333333%}.col-xs-pull-0{right:auto}.col-xs-push-12{left:100%}.col-xs-push-11{left:91.66666667%}.col-xs-push-10{left:83.33333333%}.col-xs-push-9{left:75%}.col-xs-push-8{left:66.66666667%}.col-xs-push-7{left:58.33333333%}.col-xs-push-6{left:50%}.col-xs-push-5{left:41.66666667%}.col-xs-push-4{left:33.33333333%}.col-xs-push-3{left:25%}.col-xs-push-2{left:16.66666667%}.col-xs-push-1{left:8.33333333%}.col-xs-push-0{left:auto}.col-xs-offset-12{margin-left:100%}.col-xs-offset-11{margin-left:91.66666667%}.col-xs-offset-10{margin-left:83.33333333%}.col-xs-offset-9{margin-left:75%}.col-xs-offset-8{margin-left:66.66666667%}.col-xs-offset-7{margin-left:58.33333333%}.col-xs-offset-6{margin-left:50%}.col-xs-offset-5{margin-left:41.66666667%}.col-xs-offset-4{margin-left:33.33333333%}.col-xs-offset-3{margin-left:25%}.col-xs-offset-2{margin-left:16.66666667%}.col-xs-offset-1{margin-left:8.33333333%}.col-xs-offset-0{margin-left:0}@media (min-width:768px){.col-sm-1,.col-sm-2,.col-sm-3,.col-sm-4,.col-sm-5,.col-sm-6,.col-sm-7,.col-sm-8,.col-sm-9,.col-sm-10,.col-sm-11,.col-sm-12{float:left}.col-sm-12{width:100%}.col-sm-11{width:91.66666667%}.col-sm-10{width:83.33333333%}.col-sm-9{width:75%}.col-sm-8{width:66.66666667%}.col-sm-7{width:58.33333333%}.col-sm-6{width:50%}.col-sm-5{width:41.66666667%}.col-sm-4{width:33.33333333%}.col-sm-3{width:25%}.col-sm-2{width:16.66666667%}.col-sm-1{width:8.33333333%}.col-sm-pull-12{right:100%}.col-sm-pull-11{right:91.66666667%}.col-sm-pull-10{right:83.33333333%}.col-sm-pull-9{right:75%}.col-sm-pull-8{right:66.66666667%}.col-sm-pull-7{right:58.33333333%}.col-sm-pull-6{right:50%}.col-sm-pull-5{right:41.66666667%}.col-sm-pull-4{right:33.33333333%}.col-sm-pull-3{right:25%}.col-sm-pull-2{right:16.66666667%}.col-sm-pull-1{right:8.33333333%}.col-sm-pull-0{right:auto}.col-sm-push-12{left:100%}.col-sm-push-11{left:91.66666667%}.col-sm-push-10{left:83.33333333%}.col-sm-push-9{left:75%}.col-sm-push-8{left:66.66666667%}.col-sm-push-7{left:58.33333333%}.col-sm-push-6{left:50%}.col-sm-push-5{left:41.66666667%}.col-sm-push-4{left:33.33333333%}.col-sm-push-3{left:25%}.col-sm-push-2{left:16.66666667%}.col-sm-push-1{left:8.33333333%}.col-sm-push-0{left:auto}.col-sm-offset-12{margin-left:100%}.col-sm-offset-11{margin-left:91.66666667%}.col-sm-offset-10{margin-left:83.33333333%}.col-sm-offset-9{margin-left:75%}.col-sm-offset-8{margin-left:66.66666667%}.col-sm-offset-7{margin-left:58.33333333%}.col-sm-offset-6{margin-left:50%}.col-sm-offset-5{margin-left:41.66666667%}.col-sm-offset-4{margin-left:33.33333333%}.col-sm-offset-3{margin-left:25%}.col-sm-offset-2{margin-left:16.66666667%}.col-sm-offset-1{margin-left:8.33333333%}.col-sm-offset-0{margin-left:0}}@media (min-width:992px){.col-md-1,.col-md-2,.col-md-3,.col-md-4,.col-md-5,.col-md-6,.col-md-7,.col-md-8,.col-md-9,.col-md-10,.col-md-11,.col-md-12{float:left}.col-md-12{width:100%}.col-md-11{width:91.66666667%}.col-md-10{width:83.33333333%}.col-md-9{width:75%}.col-md-8{width:66.66666667%}.col-md-7{width:58.33333333%}.col-md-6{width:50%}.col-md-5{width:41.66666667%}.col-md-4{width:33.33333333%}.col-md-3{width:25%}.col-md-2{width:16.66666667%}.col-md-1{width:8.33333333%}.col-md-pull-12{right:100%}.col-md-pull-11{right:91.66666667%}.col-md-pull-10{right:83.33333333%}.col-md-pull-9{right:75%}.col-md-pull-8{right:66.66666667%}.col-md-pull-7{right:58.33333333%}.col-md-pull-6{right:50%}.col-md-pull-5{right:41.66666667%}.col-md-pull-4{right:33.33333333%}.col-md-pull-3{right:25%}.col-md-pull-2{right:16.66666667%}.col-md-pull-1{right:8.33333333%}.col-md-pull-0{right:auto}.col-md-push-12{left:100%}.col-md-push-11{left:91.66666667%}.col-md-push-10{left:83.33333333%}.col-md-push-9{left:75%}.col-md-push-8{left:66.66666667%}.col-md-push-7{left:58.33333333%}.col-md-push-6{left:50%}.col-md-push-5{left:41.66666667%}.col-md-push-4{left:33.33333333%}.col-md-push-3{left:25%}.col-md-push-2{left:16.66666667%}.col-md-push-1{left:8.33333333%}.col-md-push-0{left:auto}.col-md-offset-12{margin-left:100%}.col-md-offset-11{margin-left:91.66666667%}.col-md-offset-10{margin-left:83.33333333%}.col-md-offset-9{margin-left:75%}.col-md-offset-8{margin-left:66.66666667%}.col-md-offset-7{margin-left:58.33333333%}.col-md-offset-6{margin-left:50%}.col-md-offset-5{margin-left:41.66666667%}.col-md-offset-4{margin-left:33.33333333%}.col-md-offset-3{margin-left:25%}.col-md-offset-2{margin-left:16.66666667%}.col-md-offset-1{margin-left:8.33333333%}.col-md-offset-0{margin-left:0}}@media (min-width:1200px){.col-lg-1,.col-lg-2,.col-lg-3,.col-lg-4,.col-lg-5,.col-lg-6,.col-lg-7,.col-lg-8,.col-lg-9,.col-lg-10,.col-lg-11,.col-lg-12{float:left}.col-lg-12{width:100%}.col-lg-11{width:91.66666667%}.col-lg-10{width:83.33333333%}.col-lg-9{width:75%}.col-lg-8{width:66.66666667%}.col-lg-7{width:58.33333333%}.col-lg-6{width:50%}.col-lg-5{width:41.66666667%}.col-lg-4{width:33.33333333%}.col-lg-3{width:25%}.col-lg-2{width:16.66666667%}.col-lg-1{width:8.33333333%}.col-lg-pull-12{right:100%}.col-lg-pull-11{right:91.66666667%}.col-lg-pull-10{right:83.33333333%}.col-lg-pull-9{right:75%}.col-lg-pull-8{right:66.66666667%}.col-lg-pull-7{right:58.33333333%}.col-lg-pull-6{right:50%}.col-lg-pull-5{right:41.66666667%}.col-lg-pull-4{right:33.33333333%}.col-lg-pull-3{right:25%}.col-lg-pull-2{right:16.66666667%}.col-lg-pull-1{right:8.33333333%}.col-lg-pull-0{right:auto}.col-lg-push-12{left:100%}.col-lg-push-11{left:91.66666667%}.col-lg-push-10{left:83.33333333%}.col-lg-push-9{left:75%}.col-lg-push-8{left:66.66666667%}.col-lg-push-7{left:58.33333333%}.col-lg-push-6{left:50%}.col-lg-push-5{left:41.66666667%}.col-lg-push-4{left:33.33333333%}.col-lg-push-3{left:25%}.col-lg-push-2{left:16.66666667%}.col-lg-push-1{left:8.33333333%}.col-lg-push-0{left:auto}.col-lg-offset-12{margin-left:100%}.col-lg-offset-11{margin-left:91.66666667%}.col-lg-offset-10{margin-left:83.33333333%}.col-lg-offset-9{margin-left:75%}.col-lg-offset-8{margin-left:66.66666667%}.col-lg-offset-7{margin-left:58.33333333%}.col-lg-offset-6{margin-left:50%}.col-lg-offset-5{margin-left:41.66666667%}.col-lg-offset-4{margin-left:33.33333333%}.col-lg-offset-3{margin-left:25%}.col-lg-offset-2{margin-left:16.66666667%}.col-lg-offset-1{margin-left:8.33333333%}.col-lg-offset-0{margin-left:0}}table{background-color:transparent}th{text-align:left}.table{width:100%;max-width:100%;margin-bottom:20px}.table>thead>tr>th,.table>tbody>tr>th,.table>tfoot>tr>th,.table>thead>tr>td,.table>tbody>tr>td,.table>tfoot>tr>td{padding:8px;line-height:1.42857143;vertical-align:top;border-top:1px solid #ddd}.table>thead>tr>th{vertical-align:bottom;border-bottom:2px solid #ddd}.table>caption+thead>tr:first-child>th,.table>colgroup+thead>tr:first-child>th,.table>thead:first-child>tr:first-child>th,.table>caption+thead>tr:first-child>td,.table>colgroup+thead>tr:first-child>td,.table>thead:first-child>tr:first-child>td{border-top:0}.table>tbody+tbody{border-top:2px solid #ddd}.table-condensed>thead>tr>th,.table-condensed>tbody>tr>th,.table-condensed>tfoot>tr>th,.table-condensed>thead>tr>td,.table-condensed>tbody>tr>td,.table-condensed>tfoot>tr>td{padding:5px}.table-bordered{border:1px solid #ddd}.table-bordered>thead>tr>th,.table-bordered>tbody>tr>th,.table-bordered>tfoot>tr>th,.table-bordered>thead>tr>td,.table-bordered>tbody>tr>td,.table-bordered>tfoot>tr>td{border:1px solid #ddd}.table-bordered>thead>tr>th,.table-bordered>thead>tr>td{border-bottom-width:2px}.table-striped>tbody>tr:nth-child(odd)>td,.table-striped>tbody>tr:nth-child(odd)>th{background-color:#f9f9f9}.table-hover>tbody>tr:hover>td,.table-hover>tbody>tr:hover>th{background-color:#f5f5f5}table col[class*=col-]{position:static;display:table-column;float:none}table td[class*=col-],table th[class*=col-]{position:static;display:table-cell;float:none}.table>thead>tr>td.active,.table>tbody>tr>td.active,.table>tfoot>tr>td.active,.table>thead>tr>th.active,.table>tbody>tr>th.active,.table>tfoot>tr>th.active,.table>thead>tr.active>td,.table>tbody>tr.active>td,.table>tfoot>tr.active>td,.table>thead>tr.active>th,.table>tbody>tr.active>th,.table>tfoot>tr.active>th{background-color:#f5f5f5}.table-hover>tbody>tr>td.active:hover,.table-hover>tbody>tr>th.active:hover,.table-hover>tbody>tr.active:hover>td,.table-hover>tbody>tr:hover>.active,.table-hover>tbody>tr.active:hover>th{background-color:#e8e8e8}.table>thead>tr>td.success,.table>tbody>tr>td.success,.table>tfoot>tr>td.success,.table>thead>tr>th.success,.table>tbody>tr>th.success,.table>tfoot>tr>th.success,.table>thead>tr.success>td,.table>tbody>tr.success>td,.table>tfoot>tr.success>td,.table>thead>tr.success>th,.table>tbody>tr.success>th,.table>tfoot>tr.success>th{background-color:#dff0d8}.table-hover>tbody>tr>td.success:hover,.table-hover>tbody>tr>th.success:hover,.table-hover>tbody>tr.success:hover>td,.table-hover>tbody>tr:hover>.success,.table-hover>tbody>tr.success:hover>th{background-color:#d0e9c6}.table>thead>tr>td.info,.table>tbody>tr>td.info,.table>tfoot>tr>td.info,.table>thead>tr>th.info,.table>tbody>tr>th.info,.table>tfoot>tr>th.info,.table>thead>tr.info>td,.table>tbody>tr.info>td,.table>tfoot>tr.info>td,.table>thead>tr.info>th,.table>tbody>tr.info>th,.table>tfoot>tr.info>th{background-color:#d9edf7}.table-hover>tbody>tr>td.info:hover,.table-hover>tbody>tr>th.info:hover,.table-hover>tbody>tr.info:hover>td,.table-hover>tbody>tr:hover>.info,.table-hover>tbody>tr.info:hover>th{background-color:#c4e3f3}.table>thead>tr>td.warning,.table>tbody>tr>td.warning,.table>tfoot>tr>td.warning,.table>thead>tr>th.warning,.table>tbody>tr>th.warning,.table>tfoot>tr>th.warning,.table>thead>tr.warning>td,.table>tbody>tr.warning>td,.table>tfoot>tr.warning>td,.table>thead>tr.warning>th,.table>tbody>tr.warning>th,.table>tfoot>tr.warning>th{background-color:#fcf8e3}.table-hover>tbody>tr>td.warning:hover,.table-hover>tbody>tr>th.warning:hover,.table-hover>tbody>tr.warning:hover>td,.table-hover>tbody>tr:hover>.warning,.table-hover>tbody>tr.warning:hover>th{background-color:#faf2cc}.table>thead>tr>td.danger,.table>tbody>tr>td.danger,.table>tfoot>tr>td.danger,.table>thead>tr>th.danger,.table>tbody>tr>th.danger,.table>tfoot>tr>th.danger,.table>thead>tr.danger>td,.table>tbody>tr.danger>td,.table>tfoot>tr.danger>td,.table>thead>tr.danger>th,.table>tbody>tr.danger>th,.table>tfoot>tr.danger>th{background-color:#f2dede}.table-hover>tbody>tr>td.danger:hover,.table-hover>tbody>tr>th.danger:hover,.table-hover>tbody>tr.danger:hover>td,.table-hover>tbody>tr:hover>.danger,.table-hover>tbody>tr.danger:hover>th{background-color:#ebcccc}@media screen and (max-width:767px){.table-responsive{width:100%;margin-bottom:15px;overflow-x:auto;overflow-y:hidden;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar;border:1px solid #ddd}.table-responsive>.table{margin-bottom:0}.table-responsive>.table>thead>tr>th,.table-responsive>.table>tbody>tr>th,.table-responsive>.table>tfoot>tr>th,.table-responsive>.table>thead>tr>td,.table-responsive>.table>tbody>tr>td,.table-responsive>.table>tfoot>tr>td{white-space:nowrap}.table-responsive>.table-bordered{border:0}.table-responsive>.table-bordered>thead>tr>th:first-child,.table-responsive>.table-bordered>tbody>tr>th:first-child,.table-responsive>.table-bordered>tfoot>tr>th:first-child,.table-responsive>.table-bordered>thead>tr>td:first-child,.table-responsive>.table-bordered>tbody>tr>td:first-child,.table-responsive>.table-bordered>tfoot>tr>td:first-child{border-left:0}.table-responsive>.table-bordered>thead>tr>th:last-child,.table-responsive>.table-bordered>tbody>tr>th:last-child,.table-responsive>.table-bordered>tfoot>tr>th:last-child,.table-responsive>.table-bordered>thead>tr>td:last-child,.table-responsive>.table-bordered>tbody>tr>td:last-child,.table-responsive>.table-bordered>tfoot>tr>td:last-child{border-right:0}.table-responsive>.table-bordered>tbody>tr:last-child>th,.table-responsive>.table-bordered>tfoot>tr:last-child>th,.table-responsive>.table-bordered>tbody>tr:last-child>td,.table-responsive>.table-bordered>tfoot>tr:last-child>td{border-bottom:0}}fieldset{min-width:0;padding:0;margin:0;border:0}legend{display:block;width:100%;padding:0;margin-bottom:20px;font-size:21px;line-height:inherit;color:#333;border:0;border-bottom:1px solid #e5e5e5}label{display:inline-block;max-width:100%;margin-bottom:5px;font-weight:700}input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=radio],input[type=checkbox]{margin:4px 0 0;margin-top:1px \9;line-height:normal}input[type=file]{display:block}input[type=range]{display:block;width:100%}select[multiple],select[size]{height:auto}input[type=file]:focus,input[type=radio]:focus,input[type=checkbox]:focus{outline:thin dotted;outline:5px auto -webkit-focus-ring-color;outline-offset:-2px}output{display:block;padding-top:7px;font-size:14px;line-height:1.42857143;color:#555}.form-control{display:block;width:100%;height:34px;padding:6px 12px;font-size:14px;line-height:1.42857143;color:#555;background-color:#fff;background-image:none;border:1px solid #ccc;border-radius:4px;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075);box-shadow:inset 0 1px 1px rgba(0,0,0,.075);-webkit-transition:border-color ease-in-out .15s,-webkit-box-shadow ease-in-out .15s;-o-transition:border-color ease-in-out .15s,box-shadow ease-in-out .15s;transition:border-color ease-in-out .15s,box-shadow ease-in-out .15s}.form-control:focus{border-color:#66afe9;outline:0;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 8px rgba(102,175,233,.6);box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 8px rgba(102,175,233,.6)}.form-control::-moz-placeholder{color:#777;opacity:1}.form-control:-ms-input-placeholder{color:#777}.form-control::-webkit-input-placeholder{color:#777}.form-control[disabled],.form-control[readonly],fieldset[disabled] .form-control{cursor:not-allowed;background-color:#eee;opacity:1}textarea.form-control{height:auto}input[type=search]{-webkit-appearance:none}input[type=date],input[type=time],input[type=datetime-local],input[type=month]{line-height:34px;line-height:1.42857143 \0}input[type=date].input-sm,input[type=time].input-sm,input[type=datetime-local].input-sm,input[type=month].input-sm{line-height:30px}input[type=date].input-lg,input[type=time].input-lg,input[type=datetime-local].input-lg,input[type=month].input-lg{line-height:46px}.form-group{margin-bottom:15px}.radio,.checkbox{position:relative;display:block;min-height:20px;margin-top:10px;margin-bottom:10px}.radio label,.checkbox label{padding-left:20px;margin-bottom:0;font-weight:400;cursor:pointer}.radio input[type=radio],.radio-inline input[type=radio],.checkbox input[type=checkbox],.checkbox-inline input[type=checkbox]{position:absolute;margin-top:4px \9;margin-left:-20px}.radio+.radio,.checkbox+.checkbox{margin-top:-5px}.radio-inline,.checkbox-inline{display:inline-block;padding-left:20px;margin-bottom:0;font-weight:400;vertical-align:middle;cursor:pointer}.radio-inline+.radio-inline,.checkbox-inline+.checkbox-inline{margin-top:0;margin-left:10px}input[type=radio][disabled],input[type=checkbox][disabled],input[type=radio].disabled,input[type=checkbox].disabled,fieldset[disabled] input[type=radio],fieldset[disabled] input[type=checkbox]{cursor:not-allowed}.radio-inline.disabled,.checkbox-inline.disabled,fieldset[disabled] .radio-inline,fieldset[disabled] .checkbox-inline{cursor:not-allowed}.radio.disabled label,.checkbox.disabled label,fieldset[disabled] .radio label,fieldset[disabled] .checkbox label{cursor:not-allowed}.form-control-static{padding-top:7px;padding-bottom:7px;margin-bottom:0}.form-control-static.input-lg,.form-control-static.input-sm{padding-right:0;padding-left:0}.input-sm,.form-horizontal .form-group-sm .form-control{height:30px;padding:5px 10px;font-size:12px;line-height:1.5;border-radius:3px}select.input-sm{height:30px;line-height:30px}textarea.input-sm,select[multiple].input-sm{height:auto}.input-lg,.form-horizontal .form-group-lg .form-control{height:46px;padding:10px 16px;font-size:18px;line-height:1.33;border-radius:6px}select.input-lg{height:46px;line-height:46px}textarea.input-lg,select[multiple].input-lg{height:auto}.has-feedback{position:relative}.has-feedback .form-control{padding-right:42.5px}.form-control-feedback{position:absolute;top:25px;right:0;z-index:2;display:block;width:34px;height:34px;line-height:34px;text-align:center}.input-lg+.form-control-feedback{width:46px;height:46px;line-height:46px}.input-sm+.form-control-feedback{width:30px;height:30px;line-height:30px}.has-success .help-block,.has-success .control-label,.has-success .radio,.has-success .checkbox,.has-success .radio-inline,.has-success .checkbox-inline{color:#3c763d}.has-success .form-control{border-color:#3c763d;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075);box-shadow:inset 0 1px 1px rgba(0,0,0,.075)}.has-success .form-control:focus{border-color:#2b542c;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 6px #67b168;box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 6px #67b168}.has-success .input-group-addon{color:#3c763d;background-color:#dff0d8;border-color:#3c763d}.has-success .form-control-feedback{color:#3c763d}.has-warning .help-block,.has-warning .control-label,.has-warning .radio,.has-warning .checkbox,.has-warning .radio-inline,.has-warning .checkbox-inline{color:#8a6d3b}.has-warning .form-control{border-color:#8a6d3b;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075);box-shadow:inset 0 1px 1px rgba(0,0,0,.075)}.has-warning .form-control:focus{border-color:#66512c;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 6px #c0a16b;box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 6px #c0a16b}.has-warning .input-group-addon{color:#8a6d3b;background-color:#fcf8e3;border-color:#8a6d3b}.has-warning .form-control-feedback{color:#8a6d3b}.has-error .help-block,.has-error .control-label,.has-error .radio,.has-error .checkbox,.has-error .radio-inline,.has-error .checkbox-inline{color:#a94442}.has-error .form-control{border-color:#a94442;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075);box-shadow:inset 0 1px 1px rgba(0,0,0,.075)}.has-error .form-control:focus{border-color:#843534;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 6px #ce8483;box-shadow:inset 0 1px 1px rgba(0,0,0,.075),0 0 6px #ce8483}.has-error .input-group-addon{color:#a94442;background-color:#f2dede;border-color:#a94442}.has-error .form-control-feedback{color:#a94442}.has-feedback label.sr-only~.form-control-feedback{top:0}.help-block{display:block;margin-top:5px;margin-bottom:10px;color:#737373}@media (min-width:768px){.form-inline .form-group{display:inline-block;margin-bottom:0;vertical-align:middle}.form-inline .form-control{display:inline-block;width:auto;vertical-align:middle}.form-inline .input-group{display:inline-table;vertical-align:middle}.form-inline .input-group .input-group-addon,.form-inline .input-group .input-group-btn,.form-inline .input-group .form-control{width:auto}.form-inline .input-group>.form-control{width:100%}.form-inline .control-label{margin-bottom:0;vertical-align:middle}.form-inline .radio,.form-inline .checkbox{display:inline-block;margin-top:0;margin-bottom:0;vertical-align:middle}.form-inline .radio label,.form-inline .checkbox label{padding-left:0}.form-inline .radio input[type=radio],.form-inline .checkbox input[type=checkbox]{position:relative;margin-left:0}.form-inline .has-feedback .form-control-feedback{top:0}}.form-horizontal .radio,.form-horizontal .checkbox,.form-horizontal .radio-inline,.form-horizontal .checkbox-inline{padding-top:7px;margin-top:0;margin-bottom:0}.form-horizontal .radio,.form-horizontal .checkbox{min-height:27px}.form-horizontal .form-group{margin-right:-15px;margin-left:-15px}@media (min-width:768px){.form-horizontal .control-label{padding-top:7px;margin-bottom:0;text-align:right}}.form-horizontal .has-feedback .form-control-feedback{top:0;right:15px}@media (min-width:768px){.form-horizontal .form-group-lg .control-label{padding-top:14.3px}}@media (min-width:768px){.form-horizontal .form-group-sm .control-label{padding-top:6px}}.btn{display:inline-block;padding:6px 12px;margin-bottom:0;font-size:14px;font-weight:400;line-height:1.42857143;text-align:center;white-space:nowrap;vertical-align:middle;cursor:pointer;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;background-image:none;border:1px solid transparent;border-radius:4px}.btn:focus,.btn:active:focus,.btn.active:focus{outline:thin dotted;outline:5px auto -webkit-focus-ring-color;outline-offset:-2px}.btn:hover,.btn:focus{color:#333;text-decoration:none}.btn:active,.btn.active{background-image:none;outline:0;-webkit-box-shadow:inset 0 3px 5px rgba(0,0,0,.125);box-shadow:inset 0 3px 5px rgba(0,0,0,.125)}.btn.disabled,.btn[disabled],fieldset[disabled] .btn{pointer-events:none;cursor:not-allowed;filter:alpha(opacity=65);-webkit-box-shadow:none;box-shadow:none;opacity:.65}.btn-default{color:#333;background-color:#fff;border-color:#ccc}.btn-default:hover,.btn-default:focus,.btn-default:active,.btn-default.active,.open>.dropdown-toggle.btn-default{color:#333;background-color:#e6e6e6;border-color:#adadad}.btn-default:active,.btn-default.active,.open>.dropdown-toggle.btn-default{background-image:none}.btn-default.disabled,.btn-default[disabled],fieldset[disabled] .btn-default,.btn-default.disabled:hover,.btn-default[disabled]:hover,fieldset[disabled] .btn-default:hover,.btn-default.disabled:focus,.btn-default[disabled]:focus,fieldset[disabled] .btn-default:focus,.btn-default.disabled:active,.btn-default[disabled]:active,fieldset[disabled] .btn-default:active,.btn-default.disabled.active,.btn-default[disabled].active,fieldset[disabled] .btn-default.active{background-color:#fff;border-color:#ccc}.btn-default .badge{color:#fff;background-color:#333}.btn-primary{color:#fff;background-color:#428bca;border-color:#357ebd}.btn-primary:hover,.btn-primary:focus,.btn-primary:active,.btn-primary.active,.open>.dropdown-toggle.btn-primary{color:#fff;background-color:#3071a9;border-color:#285e8e}.btn-primary:active,.btn-primary.active,.open>.dropdown-toggle.btn-primary{background-image:none}.btn-primary.disabled,.btn-primary[disabled],fieldset[disabled] .btn-primary,.btn-primary.disabled:hover,.btn-primary[disabled]:hover,fieldset[disabled] .btn-primary:hover,.btn-primary.disabled:focus,.btn-primary[disabled]:focus,fieldset[disabled] .btn-primary:focus,.btn-primary.disabled:active,.btn-primary[disabled]:active,fieldset[disabled] .btn-primary:active,.btn-primary.disabled.active,.btn-primary[disabled].active,fieldset[disabled] .btn-primary.active{background-color:#428bca;border-color:#357ebd}.btn-primary .badge{color:#428bca;background-color:#fff}.btn-success{color:#fff;background-color:#5cb85c;border-color:#4cae4c}.btn-success:hover,.btn-success:focus,.btn-success:active,.btn-success.active,.open>.dropdown-toggle.btn-success{color:#fff;background-color:#449d44;border-color:#398439}.btn-success:active,.btn-success.active,.open>.dropdown-toggle.btn-success{background-image:none}.btn-success.disabled,.btn-success[disabled],fieldset[disabled] .btn-success,.btn-success.disabled:hover,.btn-success[disabled]:hover,fieldset[disabled] .btn-success:hover,.btn-success.disabled:focus,.btn-success[disabled]:focus,fieldset[disabled] .btn-success:focus,.btn-success.disabled:active,.btn-success[disabled]:active,fieldset[disabled] .btn-success:active,.btn-success.disabled.active,.btn-success[disabled].active,fieldset[disabled] .btn-success.active{background-color:#5cb85c;border-color:#4cae4c}.btn-success .badge{color:#5cb85c;background-color:#fff}.btn-info{color:#fff;background-color:#5bc0de;border-color:#46b8da}.btn-info:hover,.btn-info:focus,.btn-info:active,.btn-info.active,.open>.dropdown-toggle.btn-info{color:#fff;background-color:#31b0d5;border-color:#269abc}.btn-info:active,.btn-info.active,.open>.dropdown-toggle.btn-info{background-image:none}.btn-info.disabled,.btn-info[disabled],fieldset[disabled] .btn-info,.btn-info.disabled:hover,.btn-info[disabled]:hover,fieldset[disabled] .btn-info:hover,.btn-info.disabled:focus,.btn-info[disabled]:focus,fieldset[disabled] .btn-info:focus,.btn-info.disabled:active,.btn-info[disabled]:active,fieldset[disabled] .btn-info:active,.btn-info.disabled.active,.btn-info[disabled].active,fieldset[disabled] .btn-info.active{background-color:#5bc0de;border-color:#46b8da}.btn-info .badge{color:#5bc0de;background-color:#fff}.btn-warning{color:#fff;background-color:#f0ad4e;border-color:#eea236}.btn-warning:hover,.btn-warning:focus,.btn-warning:active,.btn-warning.active,.open>.dropdown-toggle.btn-warning{color:#fff;background-color:#ec971f;border-color:#d58512}.btn-warning:active,.btn-warning.active,.open>.dropdown-toggle.btn-warning{background-image:none}.btn-warning.disabled,.btn-warning[disabled],fieldset[disabled] .btn-warning,.btn-warning.disabled:hover,.btn-warning[disabled]:hover,fieldset[disabled] .btn-warning:hover,.btn-warning.disabled:focus,.btn-warning[disabled]:focus,fieldset[disabled] .btn-warning:focus,.btn-warning.disabled:active,.btn-warning[disabled]:active,fieldset[disabled] .btn-warning:active,.btn-warning.disabled.active,.btn-warning[disabled].active,fieldset[disabled] .btn-warning.active{background-color:#f0ad4e;border-color:#eea236}.btn-warning .badge{color:#f0ad4e;background-color:#fff}.btn-danger{color:#fff;background-color:#d9534f;border-color:#d43f3a}.btn-danger:hover,.btn-danger:focus,.btn-danger:active,.btn-danger.active,.open>.dropdown-toggle.btn-danger{color:#fff;background-color:#c9302c;border-color:#ac2925}.btn-danger:active,.btn-danger.active,.open>.dropdown-toggle.btn-danger{background-image:none}.btn-danger.disabled,.btn-danger[disabled],fieldset[disabled] .btn-danger,.btn-danger.disabled:hover,.btn-danger[disabled]:hover,fieldset[disabled] .btn-danger:hover,.btn-danger.disabled:focus,.btn-danger[disabled]:focus,fieldset[disabled] .btn-danger:focus,.btn-danger.disabled:active,.btn-danger[disabled]:active,fieldset[disabled] .btn-danger:active,.btn-danger.disabled.active,.btn-danger[disabled].active,fieldset[disabled] .btn-danger.active{background-color:#d9534f;border-color:#d43f3a}.btn-danger .badge{color:#d9534f;background-color:#fff}.btn-link{font-weight:400;color:#428bca;cursor:pointer;border-radius:0}.btn-link,.btn-link:active,.btn-link[disabled],fieldset[disabled] .btn-link{background-color:transparent;-webkit-box-shadow:none;box-shadow:none}.btn-link,.btn-link:hover,.btn-link:focus,.btn-link:active{border-color:transparent}.btn-link:hover,.btn-link:focus{color:#2a6496;text-decoration:underline;background-color:transparent}.btn-link[disabled]:hover,fieldset[disabled] .btn-link:hover,.btn-link[disabled]:focus,fieldset[disabled] .btn-link:focus{color:#777;text-decoration:none}.btn-lg,.btn-group-lg>.btn{padding:10px 16px;font-size:18px;line-height:1.33;border-radius:6px}.btn-sm,.btn-group-sm>.btn{padding:5px 10px;font-size:12px;line-height:1.5;border-radius:3px}.btn-xs,.btn-group-xs>.btn{padding:1px 5px;font-size:12px;line-height:1.5;border-radius:3px}.btn-block{display:block;width:100%}.btn-block+.btn-block{margin-top:5px}input[type=submit].btn-block,input[type=reset].btn-block,input[type=button].btn-block{width:100%}.fade{opacity:0;-webkit-transition:opacity .15s linear;-o-transition:opacity .15s linear;transition:opacity .15s linear}.fade.in{opacity:1}.collapse{display:none}.collapse.in{display:block}tr.collapse.in{display:table-row}tbody.collapse.in{display:table-row-group}.collapsing{position:relative;height:0;overflow:hidden;-webkit-transition:height .35s ease;-o-transition:height .35s ease;transition:height .35s ease}.caret{display:inline-block;width:0;height:0;margin-left:2px;vertical-align:middle;border-top:4px solid;border-right:4px solid transparent;border-left:4px solid transparent}.dropdown{position:relative}.dropdown-toggle:focus{outline:0}.dropdown-menu{position:absolute;top:100%;left:0;z-index:1000;display:none;float:left;min-width:160px;padding:5px 0;margin:2px 0 0;font-size:14px;text-align:left;list-style:none;background-color:#fff;-webkit-background-clip:padding-box;background-clip:padding-box;border:1px solid #ccc;border:1px solid rgba(0,0,0,.15);border-radius:4px;-webkit-box-shadow:0 6px 12px rgba(0,0,0,.175);box-shadow:0 6px 12px rgba(0,0,0,.175)}.dropdown-menu.pull-right{right:0;left:auto}.dropdown-menu .divider{height:1px;margin:9px 0;overflow:hidden;background-color:#e5e5e5}.dropdown-menu>li>a{display:block;padding:3px 20px;clear:both;font-weight:400;line-height:1.42857143;color:#333;white-space:nowrap}.dropdown-menu>li>a:hover,.dropdown-menu>li>a:focus{color:#262626;text-decoration:none;background-color:#f5f5f5}.dropdown-menu>.active>a,.dropdown-menu>.active>a:hover,.dropdown-menu>.active>a:focus{color:#fff;text-decoration:none;background-color:#428bca;outline:0}.dropdown-menu>.disabled>a,.dropdown-menu>.disabled>a:hover,.dropdown-menu>.disabled>a:focus{color:#777}.dropdown-menu>.disabled>a:hover,.dropdown-menu>.disabled>a:focus{text-decoration:none;cursor:not-allowed;background-color:transparent;background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled=false)}.open>.dropdown-menu{display:block}.open>a{outline:0}.dropdown-menu-right{right:0;left:auto}.dropdown-menu-left{right:auto;left:0}.dropdown-header{display:block;padding:3px 20px;font-size:12px;line-height:1.42857143;color:#777;white-space:nowrap}.dropdown-backdrop{position:fixed;top:0;right:0;bottom:0;left:0;z-index:990}.pull-right>.dropdown-menu{right:0;left:auto}.dropup .caret,.navbar-fixed-bottom .dropdown .caret{content:"";border-top:0;border-bottom:4px solid}.dropup .dropdown-menu,.navbar-fixed-bottom .dropdown .dropdown-menu{top:auto;bottom:100%;margin-bottom:1px}@media (min-width:768px){.navbar-right .dropdown-menu{right:0;left:auto}.navbar-right .dropdown-menu-left{right:auto;left:0}}.btn-group,.btn-group-vertical{position:relative;display:inline-block;vertical-align:middle}.btn-group>.btn,.btn-group-vertical>.btn{position:relative;float:left}.btn-group>.btn:hover,.btn-group-vertical>.btn:hover,.btn-group>.btn:focus,.btn-group-vertical>.btn:focus,.btn-group>.btn:active,.btn-group-vertical>.btn:active,.btn-group>.btn.active,.btn-group-vertical>.btn.active{z-index:2}.btn-group>.btn:focus,.btn-group-vertical>.btn:focus{outline:0}.btn-group .btn+.btn,.btn-group .btn+.btn-group,.btn-group .btn-group+.btn,.btn-group .btn-group+.btn-group{margin-left:-1px}.btn-toolbar{margin-left:-5px}.btn-toolbar .btn-group,.btn-toolbar .input-group{float:left}.btn-toolbar>.btn,.btn-toolbar>.btn-group,.btn-toolbar>.input-group{margin-left:5px}.btn-group>.btn:not(:first-child):not(:last-child):not(.dropdown-toggle){border-radius:0}.btn-group>.btn:first-child{margin-left:0}.btn-group>.btn:first-child:not(:last-child):not(.dropdown-toggle){border-top-right-radius:0;border-bottom-right-radius:0}.btn-group>.btn:last-child:not(:first-child),.btn-group>.dropdown-toggle:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.btn-group>.btn-group{float:left}.btn-group>.btn-group:not(:first-child):not(:last-child)>.btn{border-radius:0}.btn-group>.btn-group:first-child>.btn:last-child,.btn-group>.btn-group:first-child>.dropdown-toggle{border-top-right-radius:0;border-bottom-right-radius:0}.btn-group>.btn-group:last-child>.btn:first-child{border-top-left-radius:0;border-bottom-left-radius:0}.btn-group .dropdown-toggle:active,.btn-group.open .dropdown-toggle{outline:0}.btn-group>.btn+.dropdown-toggle{padding-right:8px;padding-left:8px}.btn-group>.btn-lg+.dropdown-toggle{padding-right:12px;padding-left:12px}.btn-group.open .dropdown-toggle{-webkit-box-shadow:inset 0 3px 5px rgba(0,0,0,.125);box-shadow:inset 0 3px 5px rgba(0,0,0,.125)}.btn-group.open .dropdown-toggle.btn-link{-webkit-box-shadow:none;box-shadow:none}.btn .caret{margin-left:0}.btn-lg .caret{border-width:5px 5px 0;border-bottom-width:0}.dropup .btn-lg .caret{border-width:0 5px 5px}.btn-group-vertical>.btn,.btn-group-vertical>.btn-group,.btn-group-vertical>.btn-group>.btn{display:block;float:none;width:100%;max-width:100%}.btn-group-vertical>.btn-group>.btn{float:none}.btn-group-vertical>.btn+.btn,.btn-group-vertical>.btn+.btn-group,.btn-group-vertical>.btn-group+.btn,.btn-group-vertical>.btn-group+.btn-group{margin-top:-1px;margin-left:0}.btn-group-vertical>.btn:not(:first-child):not(:last-child){border-radius:0}.btn-group-vertical>.btn:first-child:not(:last-child){border-top-right-radius:4px;border-bottom-right-radius:0;border-bottom-left-radius:0}.btn-group-vertical>.btn:last-child:not(:first-child){border-top-left-radius:0;border-top-right-radius:0;border-bottom-left-radius:4px}.btn-group-vertical>.btn-group:not(:first-child):not(:last-child)>.btn{border-radius:0}.btn-group-vertical>.btn-group:first-child:not(:last-child)>.btn:last-child,.btn-group-vertical>.btn-group:first-child:not(:last-child)>.dropdown-toggle{border-bottom-right-radius:0;border-bottom-left-radius:0}.btn-group-vertical>.btn-group:last-child:not(:first-child)>.btn:first-child{border-top-left-radius:0;border-top-right-radius:0}.btn-group-justified{display:table;width:100%;table-layout:fixed;border-collapse:separate}.btn-group-justified>.btn,.btn-group-justified>.btn-group{display:table-cell;float:none;width:1%}.btn-group-justified>.btn-group .btn{width:100%}.btn-group-justified>.btn-group .dropdown-menu{left:auto}[data-toggle=buttons]>.btn>input[type=radio],[data-toggle=buttons]>.btn>input[type=checkbox]{position:absolute;z-index:-1;filter:alpha(opacity=0);opacity:0}.input-group{position:relative;display:table;border-collapse:separate}.input-group[class*=col-]{float:none;padding-right:0;padding-left:0}.input-group .form-control{position:relative;z-index:2;float:left;width:100%;margin-bottom:0}.input-group-lg>.form-control,.input-group-lg>.input-group-addon,.input-group-lg>.input-group-btn>.btn{height:46px;padding:10px 16px;font-size:18px;line-height:1.33;border-radius:6px}select.input-group-lg>.form-control,select.input-group-lg>.input-group-addon,select.input-group-lg>.input-group-btn>.btn{height:46px;line-height:46px}textarea.input-group-lg>.form-control,textarea.input-group-lg>.input-group-addon,textarea.input-group-lg>.input-group-btn>.btn,select[multiple].input-group-lg>.form-control,select[multiple].input-group-lg>.input-group-addon,select[multiple].input-group-lg>.input-group-btn>.btn{height:auto}.input-group-sm>.form-control,.input-group-sm>.input-group-addon,.input-group-sm>.input-group-btn>.btn{height:30px;padding:5px 10px;font-size:12px;line-height:1.5;border-radius:3px}select.input-group-sm>.form-control,select.input-group-sm>.input-group-addon,select.input-group-sm>.input-group-btn>.btn{height:30px;line-height:30px}textarea.input-group-sm>.form-control,textarea.input-group-sm>.input-group-addon,textarea.input-group-sm>.input-group-btn>.btn,select[multiple].input-group-sm>.form-control,select[multiple].input-group-sm>.input-group-addon,select[multiple].input-group-sm>.input-group-btn>.btn{height:auto}.input-group-addon,.input-group-btn,.input-group .form-control{display:table-cell}.input-group-addon:not(:first-child):not(:last-child),.input-group-btn:not(:first-child):not(:last-child),.input-group .form-control:not(:first-child):not(:last-child){border-radius:0}.input-group-addon,.input-group-btn{width:1%;white-space:nowrap;vertical-align:middle}.input-group-addon{padding:6px 12px;font-size:14px;font-weight:400;line-height:1;color:#555;text-align:center;background-color:#eee;border:1px solid #ccc;border-radius:4px}.input-group-addon.input-sm{padding:5px 10px;font-size:12px;border-radius:3px}.input-group-addon.input-lg{padding:10px 16px;font-size:18px;border-radius:6px}.input-group-addon input[type=radio],.input-group-addon input[type=checkbox]{margin-top:0}.input-group .form-control:first-child,.input-group-addon:first-child,.input-group-btn:first-child>.btn,.input-group-btn:first-child>.btn-group>.btn,.input-group-btn:first-child>.dropdown-toggle,.input-group-btn:last-child>.btn:not(:last-child):not(.dropdown-toggle),.input-group-btn:last-child>.btn-group:not(:last-child)>.btn{border-top-right-radius:0;border-bottom-right-radius:0}.input-group-addon:first-child{border-right:0}.input-group .form-control:last-child,.input-group-addon:last-child,.input-group-btn:last-child>.btn,.input-group-btn:last-child>.btn-group>.btn,.input-group-btn:last-child>.dropdown-toggle,.input-group-btn:first-child>.btn:not(:first-child),.input-group-btn:first-child>.btn-group:not(:first-child)>.btn{border-top-left-radius:0;border-bottom-left-radius:0}.input-group-addon:last-child{border-left:0}.input-group-btn{position:relative;font-size:0;white-space:nowrap}.input-group-btn>.btn{position:relative}.input-group-btn>.btn+.btn{margin-left:-1px}.input-group-btn>.btn:hover,.input-group-btn>.btn:focus,.input-group-btn>.btn:active{z-index:2}.input-group-btn:first-child>.btn,.input-group-btn:first-child>.btn-group{margin-right:-1px}.input-group-btn:last-child>.btn,.input-group-btn:last-child>.btn-group{margin-left:-1px}.nav{padding-left:0;margin-bottom:0;list-style:none}.nav>li{position:relative;display:block}.nav>li>a{position:relative;display:block;padding:10px 15px}.nav>li>a:hover,.nav>li>a:focus{text-decoration:none;background-color:#eee}.nav>li.disabled>a{color:#777}.nav>li.disabled>a:hover,.nav>li.disabled>a:focus{color:#777;text-decoration:none;cursor:not-allowed;background-color:transparent}.nav .open>a,.nav .open>a:hover,.nav .open>a:focus{background-color:#eee;border-color:#428bca}.nav .nav-divider{height:1px;margin:9px 0;overflow:hidden;background-color:#e5e5e5}.nav>li>a>img{max-width:none}.nav-tabs{border-bottom:1px solid #ddd}.nav-tabs>li{float:left;margin-bottom:-1px}.nav-tabs>li>a{margin-right:2px;line-height:1.42857143;border:1px solid transparent;border-radius:4px 4px 0 0}.nav-tabs>li>a:hover{border-color:#eee #eee #ddd}.nav-tabs>li.active>a,.nav-tabs>li.active>a:hover,.nav-tabs>li.active>a:focus{color:#555;cursor:default;background-color:#fff;border:1px solid #ddd;border-bottom-color:transparent}.nav-tabs.nav-justified{width:100%;border-bottom:0}.nav-tabs.nav-justified>li{float:none}.nav-tabs.nav-justified>li>a{margin-bottom:5px;text-align:center}.nav-tabs.nav-justified>.dropdown .dropdown-menu{top:auto;left:auto}@media (min-width:768px){.nav-tabs.nav-justified>li{display:table-cell;width:1%}.nav-tabs.nav-justified>li>a{margin-bottom:0}}.nav-tabs.nav-justified>li>a{margin-right:0;border-radius:4px}.nav-tabs.nav-justified>.active>a,.nav-tabs.nav-justified>.active>a:hover,.nav-tabs.nav-justified>.active>a:focus{border:1px solid #ddd}@media (min-width:768px){.nav-tabs.nav-justified>li>a{border-bottom:1px solid #ddd;border-radius:4px 4px 0 0}.nav-tabs.nav-justified>.active>a,.nav-tabs.nav-justified>.active>a:hover,.nav-tabs.nav-justified>.active>a:focus{border-bottom-color:#fff}}.nav-pills>li{float:left}.nav-pills>li>a{border-radius:4px}.nav-pills>li+li{margin-left:2px}.nav-pills>li.active>a,.nav-pills>li.active>a:hover,.nav-pills>li.active>a:focus{color:#fff;background-color:#428bca}.nav-stacked>li{float:none}.nav-stacked>li+li{margin-top:2px;margin-left:0}.nav-justified{width:100%}.nav-justified>li{float:none}.nav-justified>li>a{margin-bottom:5px;text-align:center}.nav-justified>.dropdown .dropdown-menu{top:auto;left:auto}@media (min-width:768px){.nav-justified>li{display:table-cell;width:1%}.nav-justified>li>a{margin-bottom:0}}.nav-tabs-justified{border-bottom:0}.nav-tabs-justified>li>a{margin-right:0;border-radius:4px}.nav-tabs-justified>.active>a,.nav-tabs-justified>.active>a:hover,.nav-tabs-justified>.active>a:focus{border:1px solid #ddd}@media (min-width:768px){.nav-tabs-justified>li>a{border-bottom:1px solid #ddd;border-radius:4px 4px 0 0}.nav-tabs-justified>.active>a,.nav-tabs-justified>.active>a:hover,.nav-tabs-justified>.active>a:focus{border-bottom-color:#fff}}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.nav-tabs .dropdown-menu{margin-top:-1px;border-top-left-radius:0;border-top-right-radius:0}.navbar{position:relative;min-height:50px;margin-bottom:20px;border:1px solid transparent}@media (min-width:768px){.navbar{border-radius:4px}}@media (min-width:768px){.navbar-header{float:left}}.navbar-collapse{padding-right:15px;padding-left:15px;overflow-x:visible;-webkit-overflow-scrolling:touch;border-top:1px solid transparent;-webkit-box-shadow:inset 0 1px 0 rgba(255,255,255,.1);box-shadow:inset 0 1px 0 rgba(255,255,255,.1)}.navbar-collapse.in{overflow-y:auto}@media (min-width:768px){.navbar-collapse{width:auto;border-top:0;-webkit-box-shadow:none;box-shadow:none}.navbar-collapse.collapse{display:block!important;height:auto!important;padding-bottom:0;overflow:visible!important}.navbar-collapse.in{overflow-y:visible}.navbar-fixed-top .navbar-collapse,.navbar-static-top .navbar-collapse,.navbar-fixed-bottom .navbar-collapse{padding-right:0;padding-left:0}}.navbar-fixed-top .navbar-collapse,.navbar-fixed-bottom .navbar-collapse{max-height:340px}@media (max-width:480px) and (orientation:landscape){.navbar-fixed-top .navbar-collapse,.navbar-fixed-bottom .navbar-collapse{max-height:200px}}.container>.navbar-header,.container-fluid>.navbar-header,.container>.navbar-collapse,.container-fluid>.navbar-collapse{margin-right:-15px;margin-left:-15px}@media (min-width:768px){.container>.navbar-header,.container-fluid>.navbar-header,.container>.navbar-collapse,.container-fluid>.navbar-collapse{margin-right:0;margin-left:0}}.navbar-static-top{z-index:1000;border-width:0 0 1px}@media (min-width:768px){.navbar-static-top{border-radius:0}}.navbar-fixed-top,.navbar-fixed-bottom{position:fixed;right:0;left:0;z-index:1030;-webkit-transform:translate3d(0,0,0);-o-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}@media (min-width:768px){.navbar-fixed-top,.navbar-fixed-bottom{border-radius:0}}.navbar-fixed-top{top:0;border-width:0 0 1px}.navbar-fixed-bottom{bottom:0;margin-bottom:0;border-width:1px 0 0}.navbar-brand{float:left;height:50px;padding:15px 15px;font-size:18px;line-height:20px}.navbar-brand:hover,.navbar-brand:focus{text-decoration:none}@media (min-width:768px){.navbar>.container .navbar-brand,.navbar>.container-fluid .navbar-brand{margin-left:-15px}}.navbar-toggle{position:relative;float:right;padding:9px 10px;margin-top:8px;margin-right:15px;margin-bottom:8px;background-color:transparent;background-image:none;border:1px solid transparent;border-radius:4px}.navbar-toggle:focus{outline:0}.navbar-toggle .icon-bar{display:block;width:22px;height:2px;border-radius:1px}.navbar-toggle .icon-bar+.icon-bar{margin-top:4px}@media (min-width:768px){.navbar-toggle{display:none}}.navbar-nav{margin:7.5px -15px}.navbar-nav>li>a{padding-top:10px;padding-bottom:10px;line-height:20px}@media (max-width:767px){.navbar-nav .open .dropdown-menu{position:static;float:none;width:auto;margin-top:0;background-color:transparent;border:0;-webkit-box-shadow:none;box-shadow:none}.navbar-nav .open .dropdown-menu>li>a,.navbar-nav .open .dropdown-menu .dropdown-header{padding:5px 15px 5px 25px}.navbar-nav .open .dropdown-menu>li>a{line-height:20px}.navbar-nav .open .dropdown-menu>li>a:hover,.navbar-nav .open .dropdown-menu>li>a:focus{background-image:none}}@media (min-width:768px){.navbar-nav{float:left;margin:0}.navbar-nav>li{float:left}.navbar-nav>li>a{padding-top:15px;padding-bottom:15px}.navbar-nav.navbar-right:last-child{margin-right:-15px}}@media (min-width:768px){.navbar-left{float:left!important}.navbar-right{float:right!important}}.navbar-form{padding:10px 15px;margin-top:8px;margin-right:-15px;margin-bottom:8px;margin-left:-15px;border-top:1px solid transparent;border-bottom:1px solid transparent;-webkit-box-shadow:inset 0 1px 0 rgba(255,255,255,.1),0 1px 0 rgba(255,255,255,.1);box-shadow:inset 0 1px 0 rgba(255,255,255,.1),0 1px 0 rgba(255,255,255,.1)}@media (min-width:768px){.navbar-form .form-group{display:inline-block;margin-bottom:0;vertical-align:middle}.navbar-form .form-control{display:inline-block;width:auto;vertical-align:middle}.navbar-form .input-group{display:inline-table;vertical-align:middle}.navbar-form .input-group .input-group-addon,.navbar-form .input-group .input-group-btn,.navbar-form .input-group .form-control{width:auto}.navbar-form .input-group>.form-control{width:100%}.navbar-form .control-label{margin-bottom:0;vertical-align:middle}.navbar-form .radio,.navbar-form .checkbox{display:inline-block;margin-top:0;margin-bottom:0;vertical-align:middle}.navbar-form .radio label,.navbar-form .checkbox label{padding-left:0}.navbar-form .radio input[type=radio],.navbar-form .checkbox input[type=checkbox]{position:relative;margin-left:0}.navbar-form .has-feedback .form-control-feedback{top:0}}@media (max-width:767px){.navbar-form .form-group{margin-bottom:5px}}@media (min-width:768px){.navbar-form{width:auto;padding-top:0;padding-bottom:0;margin-right:0;margin-left:0;border:0;-webkit-box-shadow:none;box-shadow:none}.navbar-form.navbar-right:last-child{margin-right:-15px}}.navbar-nav>li>.dropdown-menu{margin-top:0;border-top-left-radius:0;border-top-right-radius:0}.navbar-fixed-bottom .navbar-nav>li>.dropdown-menu{border-bottom-right-radius:0;border-bottom-left-radius:0}.navbar-btn{margin-top:8px;margin-bottom:8px}.navbar-btn.btn-sm{margin-top:10px;margin-bottom:10px}.navbar-btn.btn-xs{margin-top:14px;margin-bottom:14px}.navbar-text{margin-top:15px;margin-bottom:15px}@media (min-width:768px){.navbar-text{float:left;margin-right:15px;margin-left:15px}.navbar-text.navbar-right:last-child{margin-right:0}}.navbar-default{background-color:#f8f8f8;border-color:#e7e7e7}.navbar-default .navbar-brand{color:#777}.navbar-default .navbar-brand:hover,.navbar-default .navbar-brand:focus{color:#5e5e5e;background-color:transparent}.navbar-default .navbar-text{color:#777}.navbar-default .navbar-nav>li>a{color:#777}.navbar-default .navbar-nav>li>a:hover,.navbar-default .navbar-nav>li>a:focus{color:#333;background-color:transparent}.navbar-default .navbar-nav>.active>a,.navbar-default .navbar-nav>.active>a:hover,.navbar-default .navbar-nav>.active>a:focus{color:#555;background-color:#e7e7e7}.navbar-default .navbar-nav>.disabled>a,.navbar-default .navbar-nav>.disabled>a:hover,.navbar-default .navbar-nav>.disabled>a:focus{color:#ccc;background-color:transparent}.navbar-default .navbar-toggle{border-color:#ddd}.navbar-default .navbar-toggle:hover,.navbar-default .navbar-toggle:focus{background-color:#ddd}.navbar-default .navbar-toggle .icon-bar{background-color:#888}.navbar-default .navbar-collapse,.navbar-default .navbar-form{border-color:#e7e7e7}.navbar-default .navbar-nav>.open>a,.navbar-default .navbar-nav>.open>a:hover,.navbar-default .navbar-nav>.open>a:focus{color:#555;background-color:#e7e7e7}@media (max-width:767px){.navbar-default .navbar-nav .open .dropdown-menu>li>a{color:#777}.navbar-default .navbar-nav .open .dropdown-menu>li>a:hover,.navbar-default .navbar-nav .open .dropdown-menu>li>a:focus{color:#333;background-color:transparent}.navbar-default .navbar-nav .open .dropdown-menu>.active>a,.navbar-default .navbar-nav .open .dropdown-menu>.active>a:hover,.navbar-default .navbar-nav .open .dropdown-menu>.active>a:focus{color:#555;background-color:#e7e7e7}.navbar-default .navbar-nav .open .dropdown-menu>.disabled>a,.navbar-default .navbar-nav .open .dropdown-menu>.disabled>a:hover,.navbar-default .navbar-nav .open .dropdown-menu>.disabled>a:focus{color:#ccc;background-color:transparent}}.navbar-default .navbar-link{color:#777}.navbar-default .navbar-link:hover{color:#333}.navbar-default .btn-link{color:#777}.navbar-default .btn-link:hover,.navbar-default .btn-link:focus{color:#333}.navbar-default .btn-link[disabled]:hover,fieldset[disabled] .navbar-default .btn-link:hover,.navbar-default .btn-link[disabled]:focus,fieldset[disabled] .navbar-default .btn-link:focus{color:#ccc}.navbar-inverse{background-color:#222;border-color:#080808}.navbar-inverse .navbar-brand{color:#777}.navbar-inverse .navbar-brand:hover,.navbar-inverse .navbar-brand:focus{color:#fff;background-color:transparent}.navbar-inverse .navbar-text{color:#777}.navbar-inverse .navbar-nav>li>a{color:#777}.navbar-inverse .navbar-nav>li>a:hover,.navbar-inverse .navbar-nav>li>a:focus{color:#fff;background-color:transparent}.navbar-inverse .navbar-nav>.active>a,.navbar-inverse .navbar-nav>.active>a:hover,.navbar-inverse .navbar-nav>.active>a:focus{color:#fff;background-color:#080808}.navbar-inverse .navbar-nav>.disabled>a,.navbar-inverse .navbar-nav>.disabled>a:hover,.navbar-inverse .navbar-nav>.disabled>a:focus{color:#444;background-color:transparent}.navbar-inverse .navbar-toggle{border-color:#333}.navbar-inverse .navbar-toggle:hover,.navbar-inverse .navbar-toggle:focus{background-color:#333}.navbar-inverse .navbar-toggle .icon-bar{background-color:#fff}.navbar-inverse .navbar-collapse,.navbar-inverse .navbar-form{border-color:#101010}.navbar-inverse .navbar-nav>.open>a,.navbar-inverse .navbar-nav>.open>a:hover,.navbar-inverse .navbar-nav>.open>a:focus{color:#fff;background-color:#080808}@media (max-width:767px){.navbar-inverse .navbar-nav .open .dropdown-menu>.dropdown-header{border-color:#080808}.navbar-inverse .navbar-nav .open .dropdown-menu .divider{background-color:#080808}.navbar-inverse .navbar-nav .open .dropdown-menu>li>a{color:#777}.navbar-inverse .navbar-nav .open .dropdown-menu>li>a:hover,.navbar-inverse .navbar-nav .open .dropdown-menu>li>a:focus{color:#fff;background-color:transparent}.navbar-inverse .navbar-nav .open .dropdown-menu>.active>a,.navbar-inverse .navbar-nav .open .dropdown-menu>.active>a:hover,.navbar-inverse .navbar-nav .open .dropdown-menu>.active>a:focus{color:#fff;background-color:#080808}.navbar-inverse .navbar-nav .open .dropdown-menu>.disabled>a,.navbar-inverse .navbar-nav .open .dropdown-menu>.disabled>a:hover,.navbar-inverse .navbar-nav .open .dropdown-menu>.disabled>a:focus{color:#444;background-color:transparent}}.navbar-inverse .navbar-link{color:#777}.navbar-inverse .navbar-link:hover{color:#fff}.navbar-inverse .btn-link{color:#777}.navbar-inverse .btn-link:hover,.navbar-inverse .btn-link:focus{color:#fff}.navbar-inverse .btn-link[disabled]:hover,fieldset[disabled] .navbar-inverse .btn-link:hover,.navbar-inverse .btn-link[disabled]:focus,fieldset[disabled] .navbar-inverse .btn-link:focus{color:#444}.breadcrumb{padding:8px 15px;margin-bottom:20px;list-style:none;background-color:#f5f5f5;border-radius:4px}.breadcrumb>li{display:inline-block}.breadcrumb>li+li:before{padding:0 5px;color:#ccc;content:"/\00a0"}.breadcrumb>.active{color:#777}.pagination{display:inline-block;padding-left:0;margin:20px 0;border-radius:4px}.pagination>li{display:inline}.pagination>li>a,.pagination>li>span{position:relative;float:left;padding:6px 12px;margin-left:-1px;line-height:1.42857143;color:#428bca;text-decoration:none;background-color:#fff;border:1px solid #ddd}.pagination>li:first-child>a,.pagination>li:first-child>span{margin-left:0;border-top-left-radius:4px;border-bottom-left-radius:4px}.pagination>li:last-child>a,.pagination>li:last-child>span{border-top-right-radius:4px;border-bottom-right-radius:4px}.pagination>li>a:hover,.pagination>li>span:hover,.pagination>li>a:focus,.pagination>li>span:focus{color:#2a6496;background-color:#eee;border-color:#ddd}.pagination>.active>a,.pagination>.active>span,.pagination>.active>a:hover,.pagination>.active>span:hover,.pagination>.active>a:focus,.pagination>.active>span:focus{z-index:2;color:#fff;cursor:default;background-color:#428bca;border-color:#428bca}.pagination>.disabled>span,.pagination>.disabled>span:hover,.pagination>.disabled>span:focus,.pagination>.disabled>a,.pagination>.disabled>a:hover,.pagination>.disabled>a:focus{color:#777;cursor:not-allowed;background-color:#fff;border-color:#ddd}.pagination-lg>li>a,.pagination-lg>li>span{padding:10px 16px;font-size:18px}.pagination-lg>li:first-child>a,.pagination-lg>li:first-child>span{border-top-left-radius:6px;border-bottom-left-radius:6px}.pagination-lg>li:last-child>a,.pagination-lg>li:last-child>span{border-top-right-radius:6px;border-bottom-right-radius:6px}.pagination-sm>li>a,.pagination-sm>li>span{padding:5px 10px;font-size:12px}.pagination-sm>li:first-child>a,.pagination-sm>li:first-child>span{border-top-left-radius:3px;border-bottom-left-radius:3px}.pagination-sm>li:last-child>a,.pagination-sm>li:last-child>span{border-top-right-radius:3px;border-bottom-right-radius:3px}.pager{padding-left:0;margin:20px 0;text-align:center;list-style:none}.pager li{display:inline}.pager li>a,.pager li>span{display:inline-block;padding:5px 14px;background-color:#fff;border:1px solid #ddd;border-radius:15px}.pager li>a:hover,.pager li>a:focus{text-decoration:none;background-color:#eee}.pager .next>a,.pager .next>span{float:right}.pager .previous>a,.pager .previous>span{float:left}.pager .disabled>a,.pager .disabled>a:hover,.pager .disabled>a:focus,.pager .disabled>span{color:#777;cursor:not-allowed;background-color:#fff}.label{display:inline;padding:.2em .6em .3em;font-size:75%;font-weight:700;line-height:1;color:#fff;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25em}a.label:hover,a.label:focus{color:#fff;text-decoration:none;cursor:pointer}.label:empty{display:none}.btn .label{position:relative;top:-1px}.label-default{background-color:#777}.label-default[href]:hover,.label-default[href]:focus{background-color:#5e5e5e}.label-primary{background-color:#428bca}.label-primary[href]:hover,.label-primary[href]:focus{background-color:#3071a9}.label-success{background-color:#5cb85c}.label-success[href]:hover,.label-success[href]:focus{background-color:#449d44}.label-info{background-color:#5bc0de}.label-info[href]:hover,.label-info[href]:focus{background-color:#31b0d5}.label-warning{background-color:#f0ad4e}.label-warning[href]:hover,.label-warning[href]:focus{background-color:#ec971f}.label-danger{background-color:#d9534f}.label-danger[href]:hover,.label-danger[href]:focus{background-color:#c9302c}.badge{display:inline-block;min-width:10px;padding:3px 7px;font-size:12px;font-weight:700;line-height:1;color:#fff;text-align:center;white-space:nowrap;vertical-align:baseline;background-color:#777;border-radius:10px}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.btn-xs .badge{top:0;padding:1px 5px}a.badge:hover,a.badge:focus{color:#fff;text-decoration:none;cursor:pointer}a.list-group-item.active>.badge,.nav-pills>.active>a>.badge{color:#428bca;background-color:#fff}.nav-pills>li>a>.badge{margin-left:3px}.jumbotron{padding:30px;margin-bottom:30px;color:inherit;background-color:#eee}.jumbotron h1,.jumbotron .h1{color:inherit}.jumbotron p{margin-bottom:15px;font-size:21px;font-weight:200}.jumbotron>hr{border-top-color:#d5d5d5}.container .jumbotron{border-radius:6px}.jumbotron .container{max-width:100%}@media screen and (min-width:768px){.jumbotron{padding-top:48px;padding-bottom:48px}.container .jumbotron{padding-right:60px;padding-left:60px}.jumbotron h1,.jumbotron .h1{font-size:63px}}.thumbnail{display:block;padding:4px;margin-bottom:20px;line-height:1.42857143;background-color:#fff;border:1px solid #ddd;border-radius:4px;-webkit-transition:all .2s ease-in-out;-o-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.thumbnail>img,.thumbnail a>img{margin-right:auto;margin-left:auto}a.thumbnail:hover,a.thumbnail:focus,a.thumbnail.active{border-color:#428bca}.thumbnail .caption{padding:9px;color:#333}.alert{padding:15px;margin-bottom:20px;border:1px solid transparent;border-radius:4px}.alert h4{margin-top:0;color:inherit}.alert .alert-link{font-weight:700}.alert>p,.alert>ul{margin-bottom:0}.alert>p+p{margin-top:5px}.alert-dismissable,.alert-dismissible{padding-right:35px}.alert-dismissable .close,.alert-dismissible .close{position:relative;top:-2px;right:-21px;color:inherit}.alert-success{color:#3c763d;background-color:#dff0d8;border-color:#d6e9c6}.alert-success hr{border-top-color:#c9e2b3}.alert-success .alert-link{color:#2b542c}.alert-info{color:#31708f;background-color:#d9edf7;border-color:#bce8f1}.alert-info hr{border-top-color:#a6e1ec}.alert-info .alert-link{color:#245269}.alert-warning{color:#8a6d3b;background-color:#fcf8e3;border-color:#faebcc}.alert-warning hr{border-top-color:#f7e1b5}.alert-warning .alert-link{color:#66512c}.alert-danger{color:#a94442;background-color:#f2dede;border-color:#ebccd1}.alert-danger hr{border-top-color:#e4b9c0}.alert-danger .alert-link{color:#843534}@-webkit-keyframes progress-bar-stripes{from{background-position:40px 0}to{background-position:0 0}}@-o-keyframes progress-bar-stripes{from{background-position:40px 0}to{background-position:0 0}}@keyframes progress-bar-stripes{from{background-position:40px 0}to{background-position:0 0}}.progress{height:20px;margin-bottom:20px;overflow:hidden;background-color:#f5f5f5;border-radius:4px;-webkit-box-shadow:inset 0 1px 2px rgba(0,0,0,.1);box-shadow:inset 0 1px 2px rgba(0,0,0,.1)}.progress-bar{float:left;width:0;height:100%;font-size:12px;line-height:20px;color:#fff;text-align:center;background-color:#428bca;-webkit-box-shadow:inset 0 -1px 0 rgba(0,0,0,.15);box-shadow:inset 0 -1px 0 rgba(0,0,0,.15);-webkit-transition:width .6s ease;-o-transition:width .6s ease;transition:width .6s ease}.progress-striped .progress-bar,.progress-bar-striped{background-image:-webkit-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:-o-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);-webkit-background-size:40px 40px;background-size:40px 40px}.progress.active .progress-bar,.progress-bar.active{-webkit-animation:progress-bar-stripes 2s linear infinite;-o-animation:progress-bar-stripes 2s linear infinite;animation:progress-bar-stripes 2s linear infinite}.progress-bar[aria-valuenow="1"],.progress-bar[aria-valuenow="2"]{min-width:30px}.progress-bar[aria-valuenow="0"]{min-width:30px;color:#777;background-color:transparent;background-image:none;-webkit-box-shadow:none;box-shadow:none}.progress-bar-success{background-color:#5cb85c}.progress-striped .progress-bar-success{background-image:-webkit-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:-o-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent)}.progress-bar-info{background-color:#5bc0de}.progress-striped .progress-bar-info{background-image:-webkit-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:-o-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent)}.progress-bar-warning{background-color:#f0ad4e}.progress-striped .progress-bar-warning{background-image:-webkit-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:-o-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent)}.progress-bar-danger{background-color:#d9534f}.progress-striped .progress-bar-danger{background-image:-webkit-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:-o-linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent)}.media,.media-body{overflow:hidden;zoom:1}.media,.media .media{margin-top:15px}.media:first-child{margin-top:0}.media-object{display:block}.media-heading{margin:0 0 5px}.media>.pull-left{margin-right:10px}.media>.pull-right{margin-left:10px}.media-list{padding-left:0;list-style:none}.list-group{padding-left:0;margin-bottom:20px}.list-group-item{position:relative;display:block;padding:10px 15px;margin-bottom:-1px;background-color:#fff;border:1px solid #ddd}.list-group-item:first-child{border-top-left-radius:4px;border-top-right-radius:4px}.list-group-item:last-child{margin-bottom:0;border-bottom-right-radius:4px;border-bottom-left-radius:4px}.list-group-item>.badge{float:right}.list-group-item>.badge+.badge{margin-right:5px}a.list-group-item{color:#555}a.list-group-item .list-group-item-heading{color:#333}a.list-group-item:hover,a.list-group-item:focus{color:#555;text-decoration:none;background-color:#f5f5f5}.list-group-item.disabled,.list-group-item.disabled:hover,.list-group-item.disabled:focus{color:#777;background-color:#eee}.list-group-item.disabled .list-group-item-heading,.list-group-item.disabled:hover .list-group-item-heading,.list-group-item.disabled:focus .list-group-item-heading{color:inherit}.list-group-item.disabled .list-group-item-text,.list-group-item.disabled:hover .list-group-item-text,.list-group-item.disabled:focus .list-group-item-text{color:#777}.list-group-item.active,.list-group-item.active:hover,.list-group-item.active:focus{z-index:2;color:#fff;background-color:#428bca;border-color:#428bca}.list-group-item.active .list-group-item-heading,.list-group-item.active:hover .list-group-item-heading,.list-group-item.active:focus .list-group-item-heading,.list-group-item.active .list-group-item-heading>small,.list-group-item.active:hover .list-group-item-heading>small,.list-group-item.active:focus .list-group-item-heading>small,.list-group-item.active .list-group-item-heading>.small,.list-group-item.active:hover .list-group-item-heading>.small,.list-group-item.active:focus .list-group-item-heading>.small{color:inherit}.list-group-item.active .list-group-item-text,.list-group-item.active:hover .list-group-item-text,.list-group-item.active:focus .list-group-item-text{color:#e1edf7}.list-group-item-success{color:#3c763d;background-color:#dff0d8}a.list-group-item-success{color:#3c763d}a.list-group-item-success .list-group-item-heading{color:inherit}a.list-group-item-success:hover,a.list-group-item-success:focus{color:#3c763d;background-color:#d0e9c6}a.list-group-item-success.active,a.list-group-item-success.active:hover,a.list-group-item-success.active:focus{color:#fff;background-color:#3c763d;border-color:#3c763d}.list-group-item-info{color:#31708f;background-color:#d9edf7}a.list-group-item-info{color:#31708f}a.list-group-item-info .list-group-item-heading{color:inherit}a.list-group-item-info:hover,a.list-group-item-info:focus{color:#31708f;background-color:#c4e3f3}a.list-group-item-info.active,a.list-group-item-info.active:hover,a.list-group-item-info.active:focus{color:#fff;background-color:#31708f;border-color:#31708f}.list-group-item-warning{color:#8a6d3b;background-color:#fcf8e3}a.list-group-item-warning{color:#8a6d3b}a.list-group-item-warning .list-group-item-heading{color:inherit}a.list-group-item-warning:hover,a.list-group-item-warning:focus{color:#8a6d3b;background-color:#faf2cc}a.list-group-item-warning.active,a.list-group-item-warning.active:hover,a.list-group-item-warning.active:focus{color:#fff;background-color:#8a6d3b;border-color:#8a6d3b}.list-group-item-danger{color:#a94442;background-color:#f2dede}a.list-group-item-danger{color:#a94442}a.list-group-item-danger .list-group-item-heading{color:inherit}a.list-group-item-danger:hover,a.list-group-item-danger:focus{color:#a94442;background-color:#ebcccc}a.list-group-item-danger.active,a.list-group-item-danger.active:hover,a.list-group-item-danger.active:focus{color:#fff;background-color:#a94442;border-color:#a94442}.list-group-item-heading{margin-top:0;margin-bottom:5px}.list-group-item-text{margin-bottom:0;line-height:1.3}.panel{margin-bottom:20px;background-color:#fff;border:1px solid transparent;border-radius:4px;-webkit-box-shadow:0 1px 1px rgba(0,0,0,.05);box-shadow:0 1px 1px rgba(0,0,0,.05)}.panel-body{padding:15px}.panel-heading{padding:10px 15px;border-bottom:1px solid transparent;border-top-left-radius:3px;border-top-right-radius:3px}.panel-heading>.dropdown .dropdown-toggle{color:inherit}.panel-title{margin-top:0;margin-bottom:0;font-size:16px;color:inherit}.panel-title>a{color:inherit}.panel-footer{padding:10px 15px;background-color:#f5f5f5;border-top:1px solid #ddd;border-bottom-right-radius:3px;border-bottom-left-radius:3px}.panel>.list-group{margin-bottom:0}.panel>.list-group .list-group-item{border-width:1px 0;border-radius:0}.panel>.list-group:first-child .list-group-item:first-child{border-top:0;border-top-left-radius:3px;border-top-right-radius:3px}.panel>.list-group:last-child .list-group-item:last-child{border-bottom:0;border-bottom-right-radius:3px;border-bottom-left-radius:3px}.panel-heading+.list-group .list-group-item:first-child{border-top-width:0}.list-group+.panel-footer{border-top-width:0}.panel>.table,.panel>.table-responsive>.table,.panel>.panel-collapse>.table{margin-bottom:0}.panel>.table:first-child,.panel>.table-responsive:first-child>.table:first-child{border-top-left-radius:3px;border-top-right-radius:3px}.panel>.table:first-child>thead:first-child>tr:first-child td:first-child,.panel>.table-responsive:first-child>.table:first-child>thead:first-child>tr:first-child td:first-child,.panel>.table:first-child>tbody:first-child>tr:first-child td:first-child,.panel>.table-responsive:first-child>.table:first-child>tbody:first-child>tr:first-child td:first-child,.panel>.table:first-child>thead:first-child>tr:first-child th:first-child,.panel>.table-responsive:first-child>.table:first-child>thead:first-child>tr:first-child th:first-child,.panel>.table:first-child>tbody:first-child>tr:first-child th:first-child,.panel>.table-responsive:first-child>.table:first-child>tbody:first-child>tr:first-child th:first-child{border-top-left-radius:3px}.panel>.table:first-child>thead:first-child>tr:first-child td:last-child,.panel>.table-responsive:first-child>.table:first-child>thead:first-child>tr:first-child td:last-child,.panel>.table:first-child>tbody:first-child>tr:first-child td:last-child,.panel>.table-responsive:first-child>.table:first-child>tbody:first-child>tr:first-child td:last-child,.panel>.table:first-child>thead:first-child>tr:first-child th:last-child,.panel>.table-responsive:first-child>.table:first-child>thead:first-child>tr:first-child th:last-child,.panel>.table:first-child>tbody:first-child>tr:first-child th:last-child,.panel>.table-responsive:first-child>.table:first-child>tbody:first-child>tr:first-child th:last-child{border-top-right-radius:3px}.panel>.table:last-child,.panel>.table-responsive:last-child>.table:last-child{border-bottom-right-radius:3px;border-bottom-left-radius:3px}.panel>.table:last-child>tbody:last-child>tr:last-child td:first-child,.panel>.table-responsive:last-child>.table:last-child>tbody:last-child>tr:last-child td:first-child,.panel>.table:last-child>tfoot:last-child>tr:last-child td:first-child,.panel>.table-responsive:last-child>.table:last-child>tfoot:last-child>tr:last-child td:first-child,.panel>.table:last-child>tbody:last-child>tr:last-child th:first-child,.panel>.table-responsive:last-child>.table:last-child>tbody:last-child>tr:last-child th:first-child,.panel>.table:last-child>tfoot:last-child>tr:last-child th:first-child,.panel>.table-responsive:last-child>.table:last-child>tfoot:last-child>tr:last-child th:first-child{border-bottom-left-radius:3px}.panel>.table:last-child>tbody:last-child>tr:last-child td:last-child,.panel>.table-responsive:last-child>.table:last-child>tbody:last-child>tr:last-child td:last-child,.panel>.table:last-child>tfoot:last-child>tr:last-child td:last-child,.panel>.table-responsive:last-child>.table:last-child>tfoot:last-child>tr:last-child td:last-child,.panel>.table:last-child>tbody:last-child>tr:last-child th:last-child,.panel>.table-responsive:last-child>.table:last-child>tbody:last-child>tr:last-child th:last-child,.panel>.table:last-child>tfoot:last-child>tr:last-child th:last-child,.panel>.table-responsive:last-child>.table:last-child>tfoot:last-child>tr:last-child th:last-child{border-bottom-right-radius:3px}.panel>.panel-body+.table,.panel>.panel-body+.table-responsive{border-top:1px solid #ddd}.panel>.table>tbody:first-child>tr:first-child th,.panel>.table>tbody:first-child>tr:first-child td{border-top:0}.panel>.table-bordered,.panel>.table-responsive>.table-bordered{border:0}.panel>.table-bordered>thead>tr>th:first-child,.panel>.table-responsive>.table-bordered>thead>tr>th:first-child,.panel>.table-bordered>tbody>tr>th:first-child,.panel>.table-responsive>.table-bordered>tbody>tr>th:first-child,.panel>.table-bordered>tfoot>tr>th:first-child,.panel>.table-responsive>.table-bordered>tfoot>tr>th:first-child,.panel>.table-bordered>thead>tr>td:first-child,.panel>.table-responsive>.table-bordered>thead>tr>td:first-child,.panel>.table-bordered>tbody>tr>td:first-child,.panel>.table-responsive>.table-bordered>tbody>tr>td:first-child,.panel>.table-bordered>tfoot>tr>td:first-child,.panel>.table-responsive>.table-bordered>tfoot>tr>td:first-child{border-left:0}.panel>.table-bordered>thead>tr>th:last-child,.panel>.table-responsive>.table-bordered>thead>tr>th:last-child,.panel>.table-bordered>tbody>tr>th:last-child,.panel>.table-responsive>.table-bordered>tbody>tr>th:last-child,.panel>.table-bordered>tfoot>tr>th:last-child,.panel>.table-responsive>.table-bordered>tfoot>tr>th:last-child,.panel>.table-bordered>thead>tr>td:last-child,.panel>.table-responsive>.table-bordered>thead>tr>td:last-child,.panel>.table-bordered>tbody>tr>td:last-child,.panel>.table-responsive>.table-bordered>tbody>tr>td:last-child,.panel>.table-bordered>tfoot>tr>td:last-child,.panel>.table-responsive>.table-bordered>tfoot>tr>td:last-child{border-right:0}.panel>.table-bordered>thead>tr:first-child>td,.panel>.table-responsive>.table-bordered>thead>tr:first-child>td,.panel>.table-bordered>tbody>tr:first-child>td,.panel>.table-responsive>.table-bordered>tbody>tr:first-child>td,.panel>.table-bordered>thead>tr:first-child>th,.panel>.table-responsive>.table-bordered>thead>tr:first-child>th,.panel>.table-bordered>tbody>tr:first-child>th,.panel>.table-responsive>.table-bordered>tbody>tr:first-child>th{border-bottom:0}.panel>.table-bordered>tbody>tr:last-child>td,.panel>.table-responsive>.table-bordered>tbody>tr:last-child>td,.panel>.table-bordered>tfoot>tr:last-child>td,.panel>.table-responsive>.table-bordered>tfoot>tr:last-child>td,.panel>.table-bordered>tbody>tr:last-child>th,.panel>.table-responsive>.table-bordered>tbody>tr:last-child>th,.panel>.table-bordered>tfoot>tr:last-child>th,.panel>.table-responsive>.table-bordered>tfoot>tr:last-child>th{border-bottom:0}.panel>.table-responsive{margin-bottom:0;border:0}.panel-group{margin-bottom:20px}.panel-group .panel{margin-bottom:0;border-radius:4px}.panel-group .panel+.panel{margin-top:5px}.panel-group .panel-heading{border-bottom:0}.panel-group .panel-heading+.panel-collapse>.panel-body{border-top:1px solid #ddd}.panel-group .panel-footer{border-top:0}.panel-group .panel-footer+.panel-collapse .panel-body{border-bottom:1px solid #ddd}.panel-default{border-color:#ddd}.panel-default>.panel-heading{color:#333;background-color:#f5f5f5;border-color:#ddd}.panel-default>.panel-heading+.panel-collapse>.panel-body{border-top-color:#ddd}.panel-default>.panel-heading .badge{color:#f5f5f5;background-color:#333}.panel-default>.panel-footer+.panel-collapse>.panel-body{border-bottom-color:#ddd}.panel-primary{border-color:#428bca}.panel-primary>.panel-heading{color:#fff;background-color:#428bca;border-color:#428bca}.panel-primary>.panel-heading+.panel-collapse>.panel-body{border-top-color:#428bca}.panel-primary>.panel-heading .badge{color:#428bca;background-color:#fff}.panel-primary>.panel-footer+.panel-collapse>.panel-body{border-bottom-color:#428bca}.panel-success{border-color:#d6e9c6}.panel-success>.panel-heading{color:#3c763d;background-color:#dff0d8;border-color:#d6e9c6}.panel-success>.panel-heading+.panel-collapse>.panel-body{border-top-color:#d6e9c6}.panel-success>.panel-heading .badge{color:#dff0d8;background-color:#3c763d}.panel-success>.panel-footer+.panel-collapse>.panel-body{border-bottom-color:#d6e9c6}.panel-info{border-color:#bce8f1}.panel-info>.panel-heading{color:#31708f;background-color:#d9edf7;border-color:#bce8f1}.panel-info>.panel-heading+.panel-collapse>.panel-body{border-top-color:#bce8f1}.panel-info>.panel-heading .badge{color:#d9edf7;background-color:#31708f}.panel-info>.panel-footer+.panel-collapse>.panel-body{border-bottom-color:#bce8f1}.panel-warning{border-color:#faebcc}.panel-warning>.panel-heading{color:#8a6d3b;background-color:#fcf8e3;border-color:#faebcc}.panel-warning>.panel-heading+.panel-collapse>.panel-body{border-top-color:#faebcc}.panel-warning>.panel-heading .badge{color:#fcf8e3;background-color:#8a6d3b}.panel-warning>.panel-footer+.panel-collapse>.panel-body{border-bottom-color:#faebcc}.panel-danger{border-color:#ebccd1}.panel-danger>.panel-heading{color:#a94442;background-color:#f2dede;border-color:#ebccd1}.panel-danger>.panel-heading+.panel-collapse>.panel-body{border-top-color:#ebccd1}.panel-danger>.panel-heading .badge{color:#f2dede;background-color:#a94442}.panel-danger>.panel-footer+.panel-collapse>.panel-body{border-bottom-color:#ebccd1}.embed-responsive{position:relative;display:block;height:0;padding:0;overflow:hidden}.embed-responsive .embed-responsive-item,.embed-responsive iframe,.embed-responsive embed,.embed-responsive object{position:absolute;top:0;bottom:0;left:0;width:100%;height:100%;border:0}.embed-responsive.embed-responsive-16by9{padding-bottom:56.25%}.embed-responsive.embed-responsive-4by3{padding-bottom:75%}.well{min-height:20px;padding:19px;margin-bottom:20px;background-color:#f5f5f5;border:1px solid #e3e3e3;border-radius:4px;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.05);box-shadow:inset 0 1px 1px rgba(0,0,0,.05)}.well blockquote{border-color:#ddd;border-color:rgba(0,0,0,.15)}.well-lg{padding:24px;border-radius:6px}.well-sm{padding:9px;border-radius:3px}.close{float:right;font-size:21px;font-weight:700;line-height:1;color:#000;text-shadow:0 1px 0 #fff;filter:alpha(opacity=20);opacity:.2}.close:hover,.close:focus{color:#000;text-decoration:none;cursor:pointer;filter:alpha(opacity=50);opacity:.5}button.close{-webkit-appearance:none;padding:0;cursor:pointer;background:0 0;border:0}.modal-open{overflow:hidden}.modal{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1050;display:none;overflow:hidden;-webkit-overflow-scrolling:touch;outline:0}.modal.fade .modal-dialog{-webkit-transition:-webkit-transform .3s ease-out;-o-transition:-o-transform .3s ease-out;transition:transform .3s ease-out;-webkit-transform:translate3d(0,-25%,0);-o-transform:translate3d(0,-25%,0);transform:translate3d(0,-25%,0)}.modal.in .modal-dialog{-webkit-transform:translate3d(0,0,0);-o-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}.modal-open .modal{overflow-x:hidden;overflow-y:auto}.modal-dialog{position:relative;width:auto;margin:10px}.modal-content{position:relative;background-color:#fff;-webkit-background-clip:padding-box;background-clip:padding-box;border:1px solid #999;border:1px solid rgba(0,0,0,.2);border-radius:6px;outline:0;-webkit-box-shadow:0 3px 9px rgba(0,0,0,.5);box-shadow:0 3px 9px rgba(0,0,0,.5)}.modal-backdrop{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1040;background-color:#000}.modal-backdrop.fade{filter:alpha(opacity=0);opacity:0}.modal-backdrop.in{filter:alpha(opacity=50);opacity:.5}.modal-header{min-height:16.43px;padding:15px;border-bottom:1px solid #e5e5e5}.modal-header .close{margin-top:-2px}.modal-title{margin:0;line-height:1.42857143}.modal-body{position:relative;padding:15px}.modal-footer{padding:15px;text-align:right;border-top:1px solid #e5e5e5}.modal-footer .btn+.btn{margin-bottom:0;margin-left:5px}.modal-footer .btn-group .btn+.btn{margin-left:-1px}.modal-footer .btn-block+.btn-block{margin-left:0}.modal-scrollbar-measure{position:absolute;top:-9999px;width:50px;height:50px;overflow:scroll}@media (min-width:768px){.modal-dialog{width:600px;margin:30px auto}.modal-content{-webkit-box-shadow:0 5px 15px rgba(0,0,0,.5);box-shadow:0 5px 15px rgba(0,0,0,.5)}.modal-sm{width:300px}}@media (min-width:992px){.modal-lg{width:900px}}.tooltip{position:absolute;z-index:1070;display:block;font-size:12px;line-height:1.4;visibility:visible;filter:alpha(opacity=0);opacity:0}.tooltip.in{filter:alpha(opacity=90);opacity:.9}.tooltip.top{padding:5px 0;margin-top:-3px}.tooltip.right{padding:0 5px;margin-left:3px}.tooltip.bottom{padding:5px 0;margin-top:3px}.tooltip.left{padding:0 5px;margin-left:-3px}.tooltip-inner{max-width:200px;padding:3px 8px;color:#fff;text-align:center;text-decoration:none;background-color:#000;border-radius:4px}.tooltip-arrow{position:absolute;width:0;height:0;border-color:transparent;border-style:solid}.tooltip.top .tooltip-arrow{bottom:0;left:50%;margin-left:-5px;border-width:5px 5px 0;border-top-color:#000}.tooltip.top-left .tooltip-arrow{bottom:0;left:5px;border-width:5px 5px 0;border-top-color:#000}.tooltip.top-right .tooltip-arrow{right:5px;bottom:0;border-width:5px 5px 0;border-top-color:#000}.tooltip.right .tooltip-arrow{top:50%;left:0;margin-top:-5px;border-width:5px 5px 5px 0;border-right-color:#000}.tooltip.left .tooltip-arrow{top:50%;right:0;margin-top:-5px;border-width:5px 0 5px 5px;border-left-color:#000}.tooltip.bottom .tooltip-arrow{top:0;left:50%;margin-left:-5px;border-width:0 5px 5px;border-bottom-color:#000}.tooltip.bottom-left .tooltip-arrow{top:0;left:5px;border-width:0 5px 5px;border-bottom-color:#000}.tooltip.bottom-right .tooltip-arrow{top:0;right:5px;border-width:0 5px 5px;border-bottom-color:#000}.popover{position:absolute;top:0;left:0;z-index:1060;display:none;max-width:276px;padding:1px;text-align:left;white-space:normal;background-color:#fff;-webkit-background-clip:padding-box;background-clip:padding-box;border:1px solid #ccc;border:1px solid rgba(0,0,0,.2);border-radius:6px;-webkit-box-shadow:0 5px 10px rgba(0,0,0,.2);box-shadow:0 5px 10px rgba(0,0,0,.2)}.popover.top{margin-top:-10px}.popover.right{margin-left:10px}.popover.bottom{margin-top:10px}.popover.left{margin-left:-10px}.popover-title{padding:8px 14px;margin:0;font-size:14px;font-weight:400;line-height:18px;background-color:#f7f7f7;border-bottom:1px solid #ebebeb;border-radius:5px 5px 0 0}.popover-content{padding:9px 14px}.popover>.arrow,.popover>.arrow:after{position:absolute;display:block;width:0;height:0;border-color:transparent;border-style:solid}.popover>.arrow{border-width:11px}.popover>.arrow:after{content:"";border-width:10px}.popover.top>.arrow{bottom:-11px;left:50%;margin-left:-11px;border-top-color:#999;border-top-color:rgba(0,0,0,.25);border-bottom-width:0}.popover.top>.arrow:after{bottom:1px;margin-left:-10px;content:" ";border-top-color:#fff;border-bottom-width:0}.popover.right>.arrow{top:50%;left:-11px;margin-top:-11px;border-right-color:#999;border-right-color:rgba(0,0,0,.25);border-left-width:0}.popover.right>.arrow:after{bottom:-10px;left:1px;content:" ";border-right-color:#fff;border-left-width:0}.popover.bottom>.arrow{top:-11px;left:50%;margin-left:-11px;border-top-width:0;border-bottom-color:#999;border-bottom-color:rgba(0,0,0,.25)}.popover.bottom>.arrow:after{top:1px;margin-left:-10px;content:" ";border-top-width:0;border-bottom-color:#fff}.popover.left>.arrow{top:50%;right:-11px;margin-top:-11px;border-right-width:0;border-left-color:#999;border-left-color:rgba(0,0,0,.25)}.popover.left>.arrow:after{right:1px;bottom:-10px;content:" ";border-right-width:0;border-left-color:#fff}.carousel{position:relative}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-inner>.item{position:relative;display:none;-webkit-transition:.6s ease-in-out left;-o-transition:.6s ease-in-out left;transition:.6s ease-in-out left}.carousel-inner>.item>img,.carousel-inner>.item>a>img{line-height:1}.carousel-inner>.active,.carousel-inner>.next,.carousel-inner>.prev{display:block}.carousel-inner>.active{left:0}.carousel-inner>.next,.carousel-inner>.prev{position:absolute;top:0;width:100%}.carousel-inner>.next{left:100%}.carousel-inner>.prev{left:-100%}.carousel-inner>.next.left,.carousel-inner>.prev.right{left:0}.carousel-inner>.active.left{left:-100%}.carousel-inner>.active.right{left:100%}.carousel-control{position:absolute;top:0;bottom:0;left:0;width:15%;font-size:20px;color:#fff;text-align:center;text-shadow:0 1px 2px rgba(0,0,0,.6);filter:alpha(opacity=50);opacity:.5}.carousel-control.left{background-image:-webkit-linear-gradient(left,rgba(0,0,0,.5) 0,rgba(0,0,0,.0001) 100%);background-image:-o-linear-gradient(left,rgba(0,0,0,.5) 0,rgba(0,0,0,.0001) 100%);background-image:-webkit-gradient(linear,left top,right top,from(rgba(0,0,0,.5)),to(rgba(0,0,0,.0001)));background-image:linear-gradient(to right,rgba(0,0,0,.5) 0,rgba(0,0,0,.0001) 100%);filter:progid:DXImageTransform.Microsoft.gradient(startColorstr='#80000000', endColorstr='#00000000', GradientType=1);background-repeat:repeat-x}.carousel-control.right{right:0;left:auto;background-image:-webkit-linear-gradient(left,rgba(0,0,0,.0001) 0,rgba(0,0,0,.5) 100%);background-image:-o-linear-gradient(left,rgba(0,0,0,.0001) 0,rgba(0,0,0,.5) 100%);background-image:-webkit-gradient(linear,left top,right top,from(rgba(0,0,0,.0001)),to(rgba(0,0,0,.5)));background-image:linear-gradient(to right,rgba(0,0,0,.0001) 0,rgba(0,0,0,.5) 100%);filter:progid:DXImageTransform.Microsoft.gradient(startColorstr='#00000000', endColorstr='#80000000', GradientType=1);background-repeat:repeat-x}.carousel-control:hover,.carousel-control:focus{color:#fff;text-decoration:none;filter:alpha(opacity=90);outline:0;opacity:.9}.carousel-control .icon-prev,.carousel-control .icon-next,.carousel-control .glyphicon-chevron-left,.carousel-control .glyphicon-chevron-right{position:absolute;top:50%;z-index:5;display:inline-block}.carousel-control .icon-prev,.carousel-control .glyphicon-chevron-left{left:50%;margin-left:-10px}.carousel-control .icon-next,.carousel-control .glyphicon-chevron-right{right:50%;margin-right:-10px}.carousel-control .icon-prev,.carousel-control .icon-next{width:20px;height:20px;margin-top:-10px;font-family:serif}.carousel-control .icon-prev:before{content:'\2039'}.carousel-control .icon-next:before{content:'\203a'}.carousel-indicators{position:absolute;bottom:10px;left:50%;z-index:15;width:60%;padding-left:0;margin-left:-30%;text-align:center;list-style:none}.carousel-indicators li{display:inline-block;width:10px;height:10px;margin:1px;text-indent:-999px;cursor:pointer;background-color:#000 \9;background-color:rgba(0,0,0,0);border:1px solid #fff;border-radius:10px}.carousel-indicators .active{width:12px;height:12px;margin:0;background-color:#fff}.carousel-caption{position:absolute;right:15%;bottom:20px;left:15%;z-index:10;padding-top:20px;padding-bottom:20px;color:#fff;text-align:center;text-shadow:0 1px 2px rgba(0,0,0,.6)}.carousel-caption .btn{text-shadow:none}@media screen and (min-width:768px){.carousel-control .glyphicon-chevron-left,.carousel-control .glyphicon-chevron-right,.carousel-control .icon-prev,.carousel-control .icon-next{width:30px;height:30px;margin-top:-15px;font-size:30px}.carousel-control .glyphicon-chevron-left,.carousel-control .icon-prev{margin-left:-15px}.carousel-control .glyphicon-chevron-right,.carousel-control .icon-next{margin-right:-15px}.carousel-caption{right:20%;left:20%;padding-bottom:30px}.carousel-indicators{bottom:20px}}.clearfix:before,.clearfix:after,.dl-horizontal dd:before,.dl-horizontal dd:after,.container:before,.container:after,.container-fluid:before,.container-fluid:after,.row:before,.row:after,.form-horizontal .form-group:before,.form-horizontal .form-group:after,.btn-toolbar:before,.btn-toolbar:after,.btn-group-vertical>.btn-group:before,.btn-group-vertical>.btn-group:after,.nav:before,.nav:after,.navbar:before,.navbar:after,.navbar-header:before,.navbar-header:after,.navbar-collapse:before,.navbar-collapse:after,.pager:before,.pager:after,.panel-body:before,.panel-body:after,.modal-footer:before,.modal-footer:after{display:table;content:" "}.clearfix:after,.dl-horizontal dd:after,.container:after,.container-fluid:after,.row:after,.form-horizontal .form-group:after,.btn-toolbar:after,.btn-group-vertical>.btn-group:after,.nav:after,.navbar:after,.navbar-header:after,.navbar-collapse:after,.pager:after,.panel-body:after,.modal-footer:after{clear:both}.center-block{display:block;margin-right:auto;margin-left:auto}.pull-right{float:right!important}.pull-left{float:left!important}.hide{display:none!important}.show{display:block!important}.invisible{visibility:hidden}.text-hide{font:0/0 a;color:transparent;text-shadow:none;background-color:transparent;border:0}.hidden{display:none!important;visibility:hidden!important}.affix{position:fixed;-webkit-transform:translate3d(0,0,0);-o-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}@-ms-viewport{width:device-width}.visible-xs,.visible-sm,.visible-md,.visible-lg{display:none!important}.visible-xs-block,.visible-xs-inline,.visible-xs-inline-block,.visible-sm-block,.visible-sm-inline,.visible-sm-inline-block,.visible-md-block,.visible-md-inline,.visible-md-inline-block,.visible-lg-block,.visible-lg-inline,.visible-lg-inline-block{display:none!important}@media (max-width:767px){.visible-xs{display:block!important}table.visible-xs{display:table}tr.visible-xs{display:table-row!important}th.visible-xs,td.visible-xs{display:table-cell!important}}@media (max-width:767px){.visible-xs-block{display:block!important}}@media (max-width:767px){.visible-xs-inline{display:inline!important}}@media (max-width:767px){.visible-xs-inline-block{display:inline-block!important}}@media (min-width:768px) and (max-width:991px){.visible-sm{display:block!important}table.visible-sm{display:table}tr.visible-sm{display:table-row!important}th.visible-sm,td.visible-sm{display:table-cell!important}}@media (min-width:768px) and (max-width:991px){.visible-sm-block{display:block!important}}@media (min-width:768px) and (max-width:991px){.visible-sm-inline{display:inline!important}}@media (min-width:768px) and (max-width:991px){.visible-sm-inline-block{display:inline-block!important}}@media (min-width:992px) and (max-width:1199px){.visible-md{display:block!important}table.visible-md{display:table}tr.visible-md{display:table-row!important}th.visible-md,td.visible-md{display:table-cell!important}}@media (min-width:992px) and (max-width:1199px){.visible-md-block{display:block!important}}@media (min-width:992px) and (max-width:1199px){.visible-md-inline{display:inline!important}}@media (min-width:992px) and (max-width:1199px){.visible-md-inline-block{display:inline-block!important}}@media (min-width:1200px){.visible-lg{display:block!important}table.visible-lg{display:table}tr.visible-lg{display:table-row!important}th.visible-lg,td.visible-lg{display:table-cell!important}}@media (min-width:1200px){.visible-lg-block{display:block!important}}@media (min-width:1200px){.visible-lg-inline{display:inline!important}}@media (min-width:1200px){.visible-lg-inline-block{display:inline-block!important}}@media (max-width:767px){.hidden-xs{display:none!important}}@media (min-width:768px) and (max-width:991px){.hidden-sm{display:none!important}}@media (min-width:992px) and (max-width:1199px){.hidden-md{display:none!important}}@media (min-width:1200px){.hidden-lg{display:none!important}}.visible-print{display:none!important}@media print{.visible-print{display:block!important}table.visible-print{display:table}tr.visible-print{display:table-row!important}th.visible-print,td.visible-print{display:table-cell!important}}.visible-print-block{display:none!important}@media print{.visible-print-block{display:block!important}}.visible-print-inline{display:none!important}@media print{.visible-print-inline{display:inline!important}}.visible-print-inline-block{display:none!important}@media print{.visible-print-inline-block{display:inline-block!important}}@media print{.hidden-print{display:none!important}} diff --git a/ffmpeg-n8.1/doc/community.html b/ffmpeg-n8.1/doc/community.html new file mode 100644 index 00000000..7e7089b3 --- /dev/null +++ b/ffmpeg-n8.1/doc/community.html @@ -0,0 +1,227 @@ + + + + + + + Community + + + + + + +
+

+ Community +

+ + + + + + + +

1 Organisation

+ +

The FFmpeg project is organized through a community working on global consensus. +

+

Decisions are taken by the ensemble of active members, through voting and are aided by two committees. +

+ +

2 General Assembly

+ +

The ensemble of active members is called the General Assembly (GA). +

+

The General Assembly is sovereign and legitimate for all its decisions regarding the FFmpeg project. +

+

The General Assembly is made up of active contributors. +

+

Contributors are considered "active contributors" if they have authored more than 20 patches in the last 36 months in the main FFmpeg repository, or if they have been voted in by the GA. +

+

The list of active contributors is updated twice each year, on 1st January and 1st July, 0:00 UTC. +

+

Additional members are added to the General Assembly through a vote after proposal by a member of the General Assembly. They are part of the GA for two years, after which they need a confirmation by the GA. +

+

A script to generate the current members of the general assembly (minus members voted in) can be found in ‘tools/general_assembly.pl‘. +

+ +

3 Voting

+ +

Voting is done using a ranked voting system, currently running on https://vote.ffmpeg.org/ . +

+

Majority vote means more than 50% of the expressed ballots. +

+ +

4 Technical Committee

+ +

The Technical Committee (TC) is here to arbitrate and make decisions when technical conflicts occur in the project. They will consider the merits of all the positions, judge them and make a decision. +

+

The TC resolves technical conflicts but is not a technical steering committee. +

+

Decisions by the TC are binding for all the contributors. +

+

Decisions made by the TC can be re-opened after 1 year or by a majority vote of the General Assembly, requested by one of the member of the GA. +

+

The TC is elected by the General Assembly for a duration of 1 year, and is composed of 5 members. Members can be re-elected if they wish. A majority vote in the General Assembly can trigger a new election of the TC. +

+

The members of the TC can be elected from outside of the GA. Candidates for election can either be suggested or self-nominated. +

+

The conflict resolution process is detailed in the resolution process document. +

+

The TC can be contacted at <tc@ffmpeg>. +

+ +

4.1 Resolution Process

+ +

The Technical Committee (TC) is here to arbitrate and make decisions when technical conflicts occur in the project. +

+

The TC main role is to resolve technical conflicts. It is therefore not a technical steering committee, but it is understood that some decisions might impact the future of the project. +

+ +

4.1.1 Seizing

+ +

The TC can take possession of any technical matter that it sees fit. +

+

To involve the TC in a matter, email tc or CC them on an ongoing discussion. +

+

As members of TC are developers, they also can email tc to raise an issue. +

+

4.1.2 Announcement

+ +

The TC, once seized, must announce itself on the main mailing list, with a [TC] tag. +

+

The TC has 2 modes of operation: a RFC one and an internal one. +

+

If the TC thinks it needs the input from the larger community, the TC can call for a RFC. Else, it can decide by itself. +

+

The decision to use a RFC process or an internal discussion is a discretionary decision of the TC. +

+

The TC can also reject a seizure for a few reasons such as: the matter was not discussed enough previously; it lacks expertise to reach a beneficial decision on the matter; or the matter is too trivial. +

+

4.1.3 RFC call

+ +

In the RFC mode, one person from the TC posts on the mailing list the technical question and will request input from the community. +

+

The mail will have the following specification: +

+

a precise title + a specific tag [TC RFC] + a top-level email + contain a precise question that does not exceed 100 words and that is answerable by developers + may have an extra description, or a link to a previous discussion, if deemed necessary, + contain a precise end date for the answers. +

+

The answers from the community must be on the main mailing list and must have the following specification: +

+

keep the tag and the title unchanged + limited to 400 words + a first-level, answering directly to the main email + answering to the question. +

+

Further replies to answers are permitted, as long as they conform to the community standards of politeness, they are limited to 100 words, and are not nested more than once. (max-depth=2) +

+

After the end-date, mails on the thread will be ignored. +

+

Violations of those rules will be escalated through the Community Committee. +

+

After all the emails are in, the TC has 96 hours to give its final decision. Exceptionally, the TC can request an extra delay, that will be notified on the mailing list. +

+

4.1.4 Within TC

+ +

In the internal case, the TC has 96 hours to give its final decision. Exceptionally, the TC can request an extra delay. +

+

4.1.5 Decisions

+ +

The decisions from the TC will be sent on the mailing list, with the [TC] tag. +

+

Internally, the TC should take decisions with a majority, or using ranked-choice voting. +

+

Each TC member must vote on such decision according to what is, in their view, best for the project. +

+

If a TC member feels they are affected by a conflict of interest with regards to the case, they should announce it and recuse themselves from the TC +discussion and vote. +

+

A conflict of interest is presumed to occur when a TC member has a personal interest (e.g. financial) in a specific outcome of the case. +

+

The decision from the TC should be published with a summary of the reasons that lead to this decision. +

+

The decisions from the TC are final, until the matters are reopened after no less than one year. +

+ +

5 Community Committee

+ +

The Community Committee (CC) is here to arbitrage and make decisions when inter-personal conflicts occur in the project. It will decide quickly and take actions, for the sake of the project. +

+

The CC can remove privileges of offending members, including removal of commit access and temporary ban from the community. +

+

Decisions made by the CC can be re-opened after 1 year or by a majority vote of the General Assembly. Indefinite bans from the community must be confirmed by the General Assembly, in a majority vote. +

+

The CC is elected by the General Assembly for a duration of 1 year, and is composed of 5 members. Members can be re-elected if they wish. A majority vote in the General Assembly can trigger a new election of the CC. +

+

The members of the CC can be elected from outside of the GA. Candidates for election can either be suggested or self-nominated. +

+

The CC is governed by and responsible for enforcing the Code of Conduct. +

+

The CC can be contacted at <cc@ffmpeg>. +

+ +

6 Code of Conduct

+ +

Be friendly and respectful towards others and third parties. +Treat others the way you yourself want to be treated. +

+

Be considerate. Not everyone shares the same viewpoint and priorities as you do. +Different opinions and interpretations help the project. +Looking at issues from a different perspective assists development. +

+

Do not assume malice for things that can be attributed to incompetence. Even if +it is malice, it’s rarely good to start with that as initial assumption. +

+

Stay friendly even if someone acts contrarily. Everyone has a bad day +once in a while. +If you yourself have a bad day or are angry then try to take a break and reply +once you are calm and without anger if you have to. +

+

Try to help other team members and cooperate if you can. +

+

The goal of software development is to create technical excellence, not for any +individual to be better and "win" against the others. Large software projects +are only possible and successful through teamwork. +

+

If someone struggles do not put them down. Give them a helping hand +instead and point them in the right direction. +

+

Finally, keep in mind the immortal words of Bill and Ted, +"Be excellent to each other." +

+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/default.css b/ffmpeg-n8.1/doc/default.css new file mode 100644 index 00000000..bf50200c --- /dev/null +++ b/ffmpeg-n8.1/doc/default.css @@ -0,0 +1,165 @@ +a.summary-letter { + text-decoration: none; +} + +a { + color: #2D6198; +} + +a:visited { + color: #884488; +} + +#banner { + background-color: white; + position: relative; + text-align: center; +} + +#banner img { + margin-bottom: 1px; + margin-top: 5px; +} + +#body { + margin-left: 1em; + margin-right: 1em; +} + +body { + background-color: #313131; + margin: 0; + text-align: justify; +} + +.center { + margin-left: auto; + margin-right: auto; + text-align: center; +} + +#container { + background-color: white; + color: #202020; + margin-left: 1em; + margin-right: 1em; +} + +#footer { + text-align: center; +} + +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.25em; + padding-top: 0.25em; + border: 1px solid #6A996A; +} + +h1 { + background-color: #7BB37B; + color: #151515; + font-size: 1.2em; + padding-bottom: 0.3em; + padding-top: 0.3em; +} + +h2 { + color: #313131; + 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: #D1FDD1; +} + +img { + border: 0; +} + +#navbar { + background-color: #738073; + border-bottom: 1px solid #5C665C; + border-top: 1px solid #5C665C; + margin-top: 12px; + padding: 0.3em; + position: relative; + text-align: center; +} + +#navbar a, #navbar_secondary a { + color: white; + padding: 0.3em; + text-decoration: none; +} + +#navbar a:hover, #navbar_secondary a:hover { + background-color: #313131; + color: white; + text-decoration: none; +} + +#navbar_secondary { + background-color: #738073; + border-bottom: 1px solid #5C665C; + border-left: 1px solid #5C665C; + border-right: 1px solid #5C665C; + padding: 0.3em; + position: relative; + text-align: center; +} + +p { + margin-left: 1em; + margin-right: 1em; +} + +pre { + margin-left: 3em; + margin-right: 3em; + padding: 0.3em; + border: 1px solid #bbb; + background-color: #f7f7f7; +} + +dl dt { + font-weight: bold; +} + +#proj_desc { + font-size: 1.2em; +} + +#repos { + margin-left: 1em; + margin-right: 1em; + border-collapse: collapse; + border: solid 1px #6A996A; +} + +#repos th { + background-color: #7BB37B; + border: solid 1px #6A996A; +} + +#repos td { + padding: 0.2em; + border: solid 1px #6A996A; +} diff --git a/ffmpeg-n8.1/doc/developer.html b/ffmpeg-n8.1/doc/developer.html new file mode 100644 index 00000000..8af73dbc --- /dev/null +++ b/ffmpeg-n8.1/doc/developer.html @@ -0,0 +1,1153 @@ + + + + + + + Developer Documentation + + + + + + +
+

+ Developer Documentation +

+ + + + + + + +

1 Introduction

+ +

This text is concerned with the development of FFmpeg itself. Information +on using the FFmpeg libraries in other programs can be found elsewhere, e.g. in: +

+ +

For more detailed legal information about the use of FFmpeg in +external programs read the LICENSE file in the source tree and +consult https://ffmpeg.org/legal.html. +

+

If you modify FFmpeg code for your own use case, you are highly encouraged to +submit your changes back to us, using this document as a guide. There are +both pragmatic and ideological reasons to do so: +

    +
  • Maintaining external changes to keep up with upstream development is +time-consuming and error-prone. With your code in the main tree, it will be +maintained by FFmpeg developers. +
  • FFmpeg developers include leading experts in the field who can find bugs or +design flaws in your code. +
  • By supporting the project you find useful you ensure it continues to be +maintained and developed. +
+ +

All proposed code changes should be submitted for review to +Forgejo or +the development mailing list, as +described in more detail in the Submitting patches chapter. The code +should comply with the Development Policy and follow the Coding Rules. +The developer making the commit and the author are responsible for their changes +and should try to fix issues their commit causes. +

+ +

2 Coding Rules

+ + +

2.1 Language

+ +

FFmpeg is mainly programmed in the ISO C11 language, except for the public +headers which must stay C99 compatible. +

+

Compiler-specific extensions may be used with good reason, but must not be +depended on, i.e. the code must still compile and work with compilers lacking +the extension. +

+

The following C99 features must not be used anywhere in the codebase: +

    +
  • variable-length arrays; + +
  • complex numbers; +
+ + +

2.1.1 SIMD/DSP

+ +

As modern compilers are unable to generate efficient SIMD or other +performance-critical DSP code from plain C, handwritten assembly is used. +Usually such code is isolated in a separate function. Then the standard approach +is writing multiple versions of this function – a plain C one that works +everywhere and may also be useful for debugging, and potentially multiple +architecture-specific optimized implementations. Initialization code then +chooses the best available version at runtime and loads it into a function +pointer; the function in question is then always called through this pointer. +

+

The specific syntax used for writing assembly is: +

    +
  • NASM on x86; + +
  • GAS on ARM and RISC-V. +
+ +

A unit testing framework for assembly called checkasm lives under +tests/checkasm. All new assembly should come with checkasm tests; +adding tests for existing assembly that lacks them is also strongly encouraged. +

+ +

2.1.2 Other languages

+ +

Other languages than C may be used in special cases: +

    +
  • Compiler intrinsics or inline assembly when the code in question cannot be +written in the standard way described in the SIMD/DSP section. This +typically applies to code that needs to be inlined. + +
  • Objective-C where required for interacting with macOS-specific interfaces. +
+ + +

2.2 Code formatting conventions

+ +

There are the following guidelines regarding the code style in files: +

+
    +
  • Indent size is 4. + +
  • 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. + +
  • You should try to limit your code lines to 80 characters; however, do so if +and only if this improves readability. + +
  • K&R coding style is used. +
+

The presentation is one inspired by ’indent -i4 -kr -nut’. +

+ +

2.2.1 Examples

+

Some notable examples to illustrate common code style in FFmpeg: +

+
    +
  • Space around assignments and after +if/do/while/for keywords: + +
    +
    // Good
    +if (condition)
    +    av_foo();
    +
    + +
    +
    // Good
    +for (size_t i = 0; i < len; i++)
    +    av_bar(i);
    +
    + +
    +
    // Good
    +size_t size = 0;
    +
    + +

    However no spaces between the parentheses and condition, unless it helps +readability of complex conditions, so the following should not be done: +

    +
    +
    // Bad style
    +if ( condition )
    +    av_foo();
    +
    + +
  • No unnecessary parentheses, unless it helps readability: + +
    +
    // Good
    +int fields = ilace ? 2 : 1;
    +
    + +
  • Don’t wrap single-line blocks in braces. Use braces only if there is an accompanying else statement. This keeps future code changes easier to keep track of. + +
    +
    // Good
    +if (bits_pixel == 24) {
    +    avctx->pix_fmt = AV_PIX_FMT_BGR24;
    +} else if (bits_pixel == 8) {
    +    avctx->pix_fmt = AV_PIX_FMT_GRAY8;
    +} else
    +    return AVERROR_INVALIDDATA;
    +
    +
    + +
  • Avoid assignments in conditions where it makes sense: + +
    +
    // Good
    +video_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64)
    +if (!video_enc->chroma_intra_matrix)
    +    return AVERROR(ENOMEM);
    +
    + +
    +
    // Bad style
    +if (!(video_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64)))
    +    return AVERROR(ENOMEM);
    +
    + +
    +
    // Ok
    +while ((entry = av_dict_iterate(options, entry)))
    +    av_log(ctx, AV_LOG_INFO, "Item '%s': '%s'\n", entry->key, entry->value);
    +
    + +
  • When declaring a pointer variable, the * goes with the variable not the type: + +
    +
    // Good
    +AVStream *stream;
    +
    + +
    +
    // Bad style
    +AVStream* stream;
    +
    + +
+ +

If you work on a file that does not follow these guidelines consistently, +change the parts that you are editing to follow these guidelines but do +not make unrelated changes in the file to make it conform to these. +

+ +

2.2.2 Vim configuration

+

In order to configure Vim to follow FFmpeg formatting conventions, paste +the following snippet into your .vimrc: +

+
" indentation rules for FFmpeg: 4 spaces, no tabs
+set expandtab
+set shiftwidth=4
+set softtabstop=4
+set cindent
+set cinoptions=(0
+" Allow tabs in Makefiles.
+autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8
+" Trailing whitespace and tabs are forbidden, so highlight them.
+highlight ForbiddenWhitespace ctermbg=red guibg=red
+match ForbiddenWhitespace /\s\+$\|\t/
+" Do not highlight spaces at the end of line while typing on that line.
+autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@<!$/
+
+ + +

2.2.3 Emacs configuration

+

For Emacs, add these roughly equivalent lines to your .emacs.d/init.el: +

+
(c-add-style "ffmpeg"
+             '("k&r"
+               (c-basic-offset . 4)
+               (indent-tabs-mode . nil)
+               (show-trailing-whitespace . t)
+               (c-offsets-alist
+                (statement-cont . (c-lineup-assignments +)))
+               )
+             )
+(setq c-default-style "ffmpeg")
+
+ + +

2.3 Comments

+

Use the JavaDoc/Doxygen format (see examples below) so that code documentation +can be generated automatically. All nontrivial functions should have a comment +above them explaining what the function does, even if it is just one sentence. +All structures and their member variables should be documented, too. +

+

Avoid Qt-style and similar Doxygen syntax with ! in it, i.e. replace +//! with /// and similar. Also @ syntax should be employed +for markup commands, i.e. use @param and not \param. +

+
+
/**
+ * @file
+ * MPEG codec.
+ * @author ...
+ */
+
+/**
+ * Summary sentence.
+ * more text ...
+ * ...
+ */
+typedef struct Foobar {
+    int var1; /**< var1 description */
+    int var2; ///< var2 description
+    /** var3 description */
+    int var3;
+} Foobar;
+
+/**
+ * Summary sentence.
+ * more text ...
+ * ...
+ * @param my_parameter description of my_parameter
+ * @return return value description
+ */
+int myfunc(int my_parameter)
+...
+
+ + +

2.4 Naming conventions

+ +

Names of functions, variables, and struct members must be lowercase, using +underscores (_) to separate words. For example, ‘avfilter_get_video_buffer’ +is an acceptable function name and ‘AVFilterGetVideo’ is not. +

+

Struct, union, enum, and typedeffed type names must use CamelCase. All structs +and unions should be typedeffed to the same name as the struct/union tag, e.g. +typedef struct AVFoo { ... } AVFoo;. Enums are typically not +typedeffed. +

+

Enumeration constants and macros must be UPPERCASE, except for macros +masquerading as functions, which should use the function naming convention. +

+

All identifiers in the libraries should be namespaced as follows: +

    +
  • No namespacing for identifiers with file and lower scope (e.g. local variables, +static functions), and struct and union members, + +
  • The ff_ prefix must be used for variables and functions visible outside +of file scope, but only used internally within a single library, e.g. +‘ff_w64_demuxer’. This prevents name collisions when FFmpeg is statically +linked. + +
  • For variables and functions visible outside of file scope, used internally +across multiple libraries, use avpriv_ as prefix, for example, +‘avpriv_report_missing_feature’. + +
  • All other internal identifiers, like private type or macro names, should be +namespaced only to avoid possible internal conflicts. E.g. H264_NAL_SPS +vs. HEVC_NAL_SPS. + +
  • Each library has its own prefix for public symbols, in addition to the +commonly used av_ (avformat_ for libavformat, +avcodec_ for libavcodec, swr_ for libswresample, etc). +Check the existing code and choose names accordingly. + +
  • Other public identifiers (struct, union, enum, macro, type names) must use their +library’s public prefix (AV, Sws, or Swr). +
+ +

Furthermore, name space reserved for the system should not be invaded. +Identifiers ending in _t are reserved by +POSIX. +Also avoid names starting with __ or _ followed by an uppercase +letter as they are reserved by the C standard. Names starting with _ +are reserved at the file level and may not be used for externally visible +symbols. If in doubt, just avoid names starting with _ altogether. +

+ +

2.5 Miscellaneous conventions

+ +
    +
  • Casts should be used only when necessary. Unneeded parentheses +should also be avoided if they don’t make the code easier to understand. +
  • Where applicable, SI units shall be used. For example timeouts should use seconds as the fundamental unit not micro seconds. +That means a bare value like ‘1.0’ must mean 1 second, ‘50m’ means 50 milliseconds. For weight, gram shall be used. +
+ + +

3 Development Policy

+ + +

3.1 Code behaviour

+ + +

The code must be valid. It must not crash, abort, access invalid pointers, leak +memory, cause data races or signed integer overflow, or otherwise cause +undefined behaviour. Error codes should be checked and, when applicable, +forwarded to the caller. +

+ +

Our libraries may be called by multiple independent callers in the same process. +These calls may happen from any number of threads and the different call sites +may not be aware of each other - e.g. a user program may be calling our +libraries directly, and use one or more libraries that also call our libraries. +The code must behave correctly under such conditions. +

+ +

The code must treat as untrusted any bytestream received from a caller or read +from a file, network, etc. It must not misbehave when arbitrary data is sent to +it - typically it should print an error message and return +AVERROR_INVALIDDATA on encountering invalid input data. +

+ +

The code must use the av_malloc() family of functions from +libavutil/mem.h to perform all memory allocation, except in special cases +(e.g. when interacting with an external library that requires a specific +allocator to be used). +

+

All allocations should be checked and AVERROR(ENOMEM) returned on +failure. A common mistake is that error paths leak memory - make sure that does +not happen. +

+ +

Our libraries must not access the stdio streams stdin/stdout/stderr directly +(e.g. via printf() family of functions), as that is not library-safe. For +logging, use av_log(). +

+ +

3.2 Patches/Committing

+ +

Contributions should be licensed under the +LGPL 2.1, +including an "or any later version" clause, or, if you prefer +a gift-style license, the +ISC or +MIT license. +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. +

+ +

This means unfinished code which is enabled and breaks compilation, +or compiles but does not work/breaks the regression tests. Code which +is unfinished but disabled may be permitted under-circumstances, like +missing samples or an implementation with a small subset of features. +Always check the mailing list for any reviewers with issues and test +FATE before you push. +

+ +

Commit messages are highly important tools for informing other developers on +what a given change does and why. Every commit must always have a properly +filled out commit message with the following format: +

+
area changed: short 1 line description
+
+details describing what and why and giving references.
+
+ +

If the commit addresses a known bug on our bug tracker or other external issue +(e.g. CVE), the commit message should include the relevant bug ID(s) or other +external identifiers. Note that this should be done in addition to a proper +explanation and not instead of it. Comments such as "fixed!" or "Changed it." +are not acceptable. +

+

When applying patches that have been discussed at length on the mailing list, +reference the thread in the commit message. +

+ +

If it works for you, others, and passes FATE then it should be OK to commit +it, provided it fits the other committing criteria. You should not worry about +over-testing things. If your code has problems (portability, triggers +compiler bugs, unusual environment etc) they will be reported and eventually +fixed. +

+ +

They should be 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. +

+ +

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 +

+ +

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. +

+ +

If a commit/patch fixes an issues found by some researcher, always credit the +researcher in the commit message for finding/reporting the issue. +

+ +

Do NOT commit to code actively maintained by others without permission. +Send a patch to ffmpeg-devel. If no one answers within a reasonable +time-frame (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! +

+ +

3.3 Code

+ +

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. +

+ +

3.4 Library public interfaces

+

Every library in FFmpeg provides a set of public APIs in its installed headers, +which are those listed in the variable HEADERS in that library’s +Makefile. All identifiers defined in those headers (except for those +explicitly documented otherwise), and corresponding symbols exported from +compiled shared or static libraries are considered public interfaces and must +comply with the API and ABI compatibility rules described in this section. +

+

Public APIs must be backward compatible within a given major version. I.e. any +valid user code that compiles and works with a given library version must still +compile and work with any later version, as long as the major version number is +unchanged. "Valid user code" here means code that is calling our APIs in a +documented and/or intended manner and is not relying on any undefined behavior. +Incrementing the major version may break backward compatibility, but only to the +extent described in Major version bumps. +

+

We also guarantee backward ABI compatibility for shared and static libraries. +I.e. it should be possible to replace a shared or static build of our library +with a build of any later version (re-linking the user binary in the static +case) without breaking any valid user binaries, as long as the major version +number remains unchanged. +

+ +

3.4.1 Adding new interfaces

+

Any new public identifiers in installed headers are considered new API - this +includes new functions, structs, macros, enum values, typedefs, new fields in +existing structs, new installed headers, etc. Consider the following +guidelines when adding new APIs. +

+ +

While new APIs can be added relatively easily, changing or removing them is much +harder due to abovementioned compatibility requirements. You should then +consider carefully whether the functionality you are adding really needs to be +exposed to our callers as new public API. +

+

Your new API should have at least one well-established use case outside of the +library that cannot be easily achieved with existing APIs. Every library in +FFmpeg also has a defined scope - your new API must fit within it. +

+ +

If your new API is replacing an existing one, it should be strictly superior to +it, so that the advantages of using the new API outweigh the cost to the +callers of changing their code. After adding the new API you should then +deprecate the old one and schedule it for removal, as described in +Removing interfaces. +

+

If you deem an existing API deficient and want to fix it, the preferred approach +in most cases is to add a differently-named replacement and deprecate the +existing API rather than modify it. It is important to make the changes visible +to our callers (e.g. through compile- or run-time deprecation warnings) and make +it clear how to transition to the new API (e.g. in the Doxygen documentation or +on the wiki). +

+ +

The FFmpeg libraries are used by a variety of callers to perform a wide range of +multimedia-related processing tasks. You should therefore - within reason - try +to design your new API for the broadest feasible set of use cases and avoid +unnecessarily limiting it to a specific type of callers (e.g. just media +playback or just transcoding). +

+ +

Check whether similar APIs already exist in FFmpeg. If they do, try to model +your new addition on them to achieve better overall consistency. +

+

The naming of your new identifiers should follow the Naming conventions +and be aligned with other similar APIs, if applicable. +

+ +

You should also consider how your API might be extended in the future in a +backward-compatible way. If you are adding a new struct AVFoo, the +standard approach is requiring the caller to always allocate it through a +constructor function, typically named av_foo_alloc(). This way new fields +may be added to the end of the struct without breaking ABI compatibility. +Typically you will also want a destructor - av_foo_free(AVFoo**) that +frees the indirectly supplied object (and its contents, if applicable) and +writes NULL to the supplied pointer, thus eliminating the potential +dangling pointer in the caller’s memory. +

+

If you are adding new functions, consider whether it might be desirable to tweak +their behavior in the future - you may want to add a flags argument, even though +it would be unused initially. +

+ +

All new APIs must be documented as Doxygen-formatted comments above the +identifiers you add to the public headers. You should also briefly mention the +change in doc/APIchanges. +

+ +

Backward-incompatible API or ABI changes require incrementing (bumping) the +major version number, as described in Major version bumps. Major +bumps are significant events that happen on a schedule - so if your change +strictly requires one you should add it under #if preprocessor guards that +disable it until the next major bump happens. +

+

New APIs that can be added without breaking API or ABI compatibility require +bumping the minor version number. +

+

Incrementing the third (micro) version 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. +

+ +

3.4.2 Removing interfaces

+

Due to abovementioned compatibility guarantees, removing APIs is an involved +process that should only be undertaken with good reason. Typically a deficient, +restrictive, or otherwise inadequate API is replaced by a superior one, though +it does at times happen that we remove an API without any replacement (e.g. when +the feature it provides is deemed not worth the maintenance effort, out of scope +of the project, fundamentally flawed, etc.). +

+

The removal has two steps - first the API is deprecated and scheduled for +removal, but remains present and functional. The second step is actually +removing the API - this is described in Major version bumps. +

+

To deprecate an API you should signal to our users that they should stop using +it. E.g. if you intend to remove struct members or functions, you should mark +them with attribute_deprecated. When this cannot be done, it may be +possible to detect the use of the deprecated API at runtime and print a warning +(though take care not to print it too often). You should also document the +deprecation (and the replacement, if applicable) in the relevant Doxygen +documentation block. +

+

Finally, you should define a deprecation guard along the lines of +#define FF_API_<FOO> (LIBAVBAR_VERSION_MAJOR < XX) (where XX is the major +version in which the API will be removed) in libavbar/version_major.h +(version.h in case of libavutil). Then wrap all uses of the +deprecated API in #if FF_API_<FOO> .... #endif, so that the code will +automatically get disabled once the major version reaches XX. You can also use +FF_DISABLE_DEPRECATION_WARNINGS and FF_ENABLE_DEPRECATION_WARNINGS +to suppress compiler deprecation warnings inside these guards. You should test +that the code compiles and works with the guard macro evaluating to both true +and false. +

+ +

3.4.3 Major version bumps

+

A major version bump signifies an API and/or ABI compatibility break. To reduce +the negative effects on our callers, who are required to adapt their code, +backward-incompatible changes during a major bump should be limited to: +

    +
  • Removing previously deprecated APIs. + +
  • Performing ABI- but not API-breaking changes, like reordering struct contents. +
+ + +

3.5 Documentation/Other

+ +

It is important to be subscribed to the +ffmpeg-devel +mailing list. Almost any non-trivial patch is to be sent there for review. +Other developers may have comments about your contribution. We expect you see +those comments, and to improve it if requested. (N.B. Experienced committers +have other channels, and may sometimes skip review for trivial fixes.) Also, +discussion here about bug fixes and FFmpeg improvements by other developers may +be helpful information for you. Finally, by being a list subscriber, your +contribution will be posted immediately to the list, without the moderation +hold which messages from non-subscribers experience. +

+

However, it is more important to the project that we receive your patch than +that you be subscribed to the ffmpeg-devel list. If you have a patch, and don’t +want to subscribe and discuss the patch, then please do send it to the list +anyway. +

+ +

Diffs of all commits are sent to the +ffmpeg-cvslog +mailing list. Some developers read this list to review all code base changes +from all sources. Subscribing to this list is not mandatory. +

+ +

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. +

+ +

Try to keep important discussions and requests (also) on the public +developer mailing list, so that all developers can benefit from them. +

+ +

Make sure that no parts of the codebase that you maintain are missing from the +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 in +finding a new maintainer and also don’t forget to update the MAINTAINERS file. +

+

We think our rules are not too hard. If you have comments, contact us. +

+ +

4 Submitting patches

+ +

First, read the Coding Rules above if you did not yet, in particular +the rules regarding patch submission. +

+

When you submit your patch, please use git format-patch or +git send-email. We cannot read other diffs :-). +

+

Also please do not submit a patch which contains several unrelated changes. +Split it into separate, self-contained pieces. This does not mean splitting +file by file. Instead, make the patch as small as possible while still +keeping it as a logical unit that contains an individual change, even +if it spans multiple files. This makes reviewing your patches much easier +for us and greatly increases your chances of getting your patch applied. +

+

Use the patcheck tool of FFmpeg to check your patch. +The tool is located in the tools directory. +

+

Run the Regression tests before submitting a patch in order to verify +it does not cause unexpected problems. +

+

It also helps quite a bit if you tell us what the patch does (for example +’replaces lrint by lrintf’), and why (for example ’*BSD isn’t C99 compliant +and has no lrint()’) +

+

Also please if you send several patches, send each patch as a separate mail, +do not attach several unrelated patches to the same mail. +

+

Patches should be posted to +Forgejo or the +ffmpeg-devel +mailing list. Use git send-email when possible since it will properly +send patches without requiring extra care. If you cannot, then send patches +as base64-encoded attachments, so your patch is not trashed during +transmission. Also ensure the correct mime type is used +(text/x-diff or text/x-patch or at least text/plain) and that only one +patch is inline or attached per mail. +You can check https://patchwork.ffmpeg.org, if your patch does not show up, its mime type +likely was wrong. +

+ + +

Please see https://git-send-email.io/. +For gmail additionally see https://shallowsky.com/blog/tech/email/gmail-app-passwds.html. +

+ +

Using git send-email might not be desirable for everyone. The +following trick allows to send patches via email clients in a safe +way. It has been tested with Outlook and Thunderbird (with X-Unsent +extension) and might work with other applications. +

+

Create your patch like this: +

+
git format-patch -s -o "outputfolder" --add-header "X-Unsent: 1" --suffix .eml --to ffmpeg-devel@ffmpeg.org -1 1a2b3c4d
+
+

Now you’ll just need to open the eml file with the email application +and execute ’Send’. +

+ +

Your patch will be reviewed on the mailing list. You will likely be asked +to make some changes and are expected to send in an improved version that +incorporates the requests from the review. This process may go through +several iterations. Once your patch is deemed good enough, some developer +will pick it up and commit it to the official FFmpeg tree. +

+

Give us a few days to react. But if some time passes without reaction, +send a reminder by email. Your patch should eventually be dealt with. +

+ + +

5 New codecs or formats checklist

+ +
    +
  1. Did you use av_cold for codec initialization and close functions? + +
  2. Did you add a long_name under NULL_IF_CONFIG_SMALL to the AVCodec or +AVInputFormat/AVOutputFormat struct? + +
  3. Did you bump the minor version number (and reset the micro version +number) in libavcodec/version.h or libavformat/version.h? + +
  4. Did you register it in allcodecs.c or allformats.c? + +
  5. Did you add the AVCodecID to codec_id.h? +When adding new codec IDs, also add an entry to the codec descriptor +list in libavcodec/codec_desc.c. + +
  6. If it has a FourCC, did you add it to libavformat/riff.c, +even if it is only a decoder? + +
  7. 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. + +
  8. Did you add an entry to the table of supported formats or codecs in +doc/general_contents.texi? + +
  9. Did you add an entry in the Changelog? + +
  10. If it depends on a parser or a library, did you add that dependency in +configure? + +
  11. Did you git add the appropriate files before committing? + +
  12. Did you make sure it compiles standalone, i.e. with +configure --disable-everything --enable-decoder=foo +(or --enable-demuxer or whatever your component is)? +
+ + + +

6 Patch submission checklist

+ +
    +
  1. Does make fate pass with the patch applied? + +
  2. Was the patch generated with git format-patch or send-email? + +
  3. Did you sign-off your patch? (git commit -s) +See Sign your work for the meaning +of sign-off. + +
  4. Did you provide a clear git commit log message? + +
  5. Is the patch against latest FFmpeg git master branch? + +
  6. Are you subscribed to ffmpeg-devel? +(the list is subscribers only due to spam) + +
  7. Have you checked that the changes are minimal, so that the same cannot be +achieved with a smaller patch and/or simpler final code? + +
  8. If the change is to speed critical code, did you benchmark it? + +
  9. If you did any benchmarks, did you provide them in the mail? + +
  10. Have you checked that the patch does not introduce buffer overflows or +other security issues? + +
  11. Did you test your decoder or demuxer against damaged data? If no, see +tools/trasher, the noise bitstream filter, and +zzuf. Your decoder or demuxer +should not crash, end in a (near) infinite loop, or allocate ridiculous +amounts of memory when fed damaged data. + +
  12. Did you test your decoder or demuxer against sample files? +Samples may be obtained at https://samples.ffmpeg.org. + +
  13. Does the patch not mix functional and cosmetic changes? + +
  14. Did you add tabs or trailing whitespace to the code? Both are forbidden. + +
  15. Is the patch attached to the email you send? + +
  16. 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. + +
  17. If the patch fixes a bug, did you provide a verbose analysis of the bug? + +
  18. 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 https://streams.videolan.org/upload/. + +
  19. Did you provide a verbose summary about what the patch does change? + +
  20. Did you provide a verbose explanation why it changes things like it does? + +
  21. Did you provide a verbose summary of the user visible advantages and +disadvantages if the patch is applied? + +
  22. Did you provide an example so we can verify the new feature added by the +patch easily? + +
  23. 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. + +
  24. You should maintain alphabetical order in alphabetically ordered lists as +long as doing so does not break API/ABI compatibility. + +
  25. Lines with similar content should be aligned vertically when doing so +improves readability. + +
  26. Consider adding a regression test for your code. All new modules +should be covered by tests. That includes demuxers, muxers, decoders, encoders +filters, bitstream filters, parsers. If its not possible to do that, add +an explanation why to your patchset, its ok to not test if there’s a reason. + +
  27. If you added NASM code please check that things still work with –disable-x86asm. + +
  28. Test your code with valgrind and or Address Sanitizer to ensure it’s free +of leaks, out of array accesses, etc. +
+ + +

7 Patch review process

+ +

All patches posted to ffmpeg-devel will be reviewed, unless they contain a +clear note that the patch is not for the git master branch. +Reviews and comments will be posted as replies to the patch on the +mailing list. The patch submitter then has to take care of every comment, +that can be by resubmitting a changed patch or by discussion. Resubmitted +patches will themselves be reviewed like any other patch. If at some point +a patch passes review with no comments then it is approved, that can for +simple and small patches happen immediately while large patches will generally +have to be changed and reviewed many times before they are approved. +After a patch is approved it will be committed to the repository. +

+

We will review all submitted patches, but sometimes we are quite busy so +especially for large patches this can take several weeks. +

+

If you feel that the review process is too slow and you are willing to try to +take over maintainership of the area of code you change then just clone +git master and maintain the area of code there. We will merge each area from +where its best maintained. +

+

When resubmitting patches, please do not make any significant changes +not related to the comments received during review. Such patches will +be rejected. Instead, submit significant changes or new features as +separate patches. +

+

Everyone is welcome to review patches. Also if you are waiting for your patch +to be reviewed, please consider helping to review other patches, that is a great +way to get everyone’s patches reviewed sooner. +

+ +

8 Regression tests

+ +

Before submitting a patch (or committing to the repository), you should at least +test that you did not break anything. +

+

Running ’make fate’ accomplishes this, please see fate.html for details. +

+

[Of course, some patches may change the results of the regression tests. In +this case, the reference results of the regression tests shall be modified +accordingly]. +

+ +

8.1 Adding files to the fate-suite dataset

+ +

If you need a sample uploaded send a mail to samples-request. +

+

When there is no muxer or encoder available to generate test media for a +specific test then the media has to be included in the fate-suite. +First please make sure that the sample file is as small as possible to test the +respective decoder or demuxer sufficiently. Large files increase network +bandwidth and disk space requirements. +Once you have a working fate test and fate sample, provide in the commit +message or introductory message for the patch series that you post to +the ffmpeg-devel mailing list, a direct link to download the sample media. +

+ +

8.2 Visualizing Test Coverage

+ +

The FFmpeg build system allows visualizing the test coverage in an easy +manner with the coverage tools gcov/lcov. This involves +the following steps: +

+
    +
  1. Configure to compile with instrumentation enabled: + configure --toolchain=gcov. + +
  2. 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. + +
  3. Run make lcov to generate coverage data in HTML format. + +
  4. View lcov/index.html in your preferred HTML viewer. +
+ +

You can use the command make lcov-reset to reset the coverage +measurements. You will need to rerun make lcov after running a +new test. +

+ +

8.3 Using Valgrind

+ +

The configure script provides a shortcut for using valgrind to spot bugs +related to memory handling. Just add the option +--toolchain=valgrind-memcheck or --toolchain=valgrind-massif +to your configure line, and reasonable defaults will be set for running +FATE under the supervision of either the memcheck or the +massif tool of the valgrind suite. +

+

In case you need finer control over how valgrind is invoked, use the +--target-exec='valgrind <your_custom_valgrind_options> option in +your configure line instead. +

+ +

9 Maintenance process

+ + +

9.1 MAINTAINERS

+ +

The developers maintaining each part of the codebase are listed in MAINTAINERS. +Being listed in MAINTAINERS, gives one the right to have git write access to +the specific repository. +

+ +

9.2 Becoming a maintainer

+ +

People add themselves to MAINTAINERS by sending a patch like any other code +change. These get reviewed by the community like any other patch. It is expected +that, if someone has an objection to a new maintainer, she is willing to object +in public with her full name and is willing to take over maintainership for the area. +

+ + +

10 Release process

+ +

FFmpeg maintains a set of release branches, which are the +recommended deliverable for system integrators and distributors (such as +Linux distributions, etc.). At regular times, a release +manager prepares, tests and publishes tarballs on the +https://ffmpeg.org website. +

+

There are two kinds of releases: +

+
    +
  1. Major releases always include the latest and greatest +features and functionality. + +
  2. Point releases are cut from release branches, +which are named release/X, with X being the release +version number. +
+ +

Note that we promise to our users that shared libraries from any FFmpeg +release never break programs that have been compiled against +previous versions of the same release series in any case! +

+

However, from time to time, we do make API changes that require adaptations +in applications. Such changes are only allowed in (new) major releases and +require further steps such as bumping library version numbers and/or +adjustments to the symbol versioning file. Please discuss such changes +on the ffmpeg-devel mailing list in time to allow forward planning. +

+ +

10.1 Criteria for Point Releases

+ +

Changes that match the following criteria are valid candidates for +inclusion into a point release: +

+
    +
  1. Fixes a security issue, preferably identified by a CVE +number issued by http://cve.mitre.org/. + +
  2. Fixes a documented bug in https://trac.ffmpeg.org. + +
  3. Improves the included documentation. + +
  4. Retains both source code and binary compatibility with previous +point releases of the same release branch. +
+ +

The order for checking the rules is (1 OR 2 OR 3) AND 4. +

+ + +

10.2 Release Checklist

+ +

The release process involves the following steps: +

+
    +
  1. Ensure that the RELEASE file contains the version number for +the upcoming release. + +
  2. Add the release at https://trac.ffmpeg.org/admin/ticket/versions. + +
  3. Announce the intent to do a release to the mailing list. + +
  4. Make sure all relevant security fixes have been backported. See +https://ffmpeg.org/security.html. + +
  5. Ensure that the FATE regression suite still passes in the release +branch on at least i386 and amd64 +(cf. Regression tests). + +
  6. Prepare the release tarballs in bz2 and gz formats, and +supplementing files that contain gpg signatures + +
  7. Publish the tarballs at https://ffmpeg.org/releases. Create and +push an annotated tag in the form nX, with X +containing the version number. + +
  8. Propose and send a patch to the ffmpeg-devel mailing list +with a news entry for the website. + +
  9. Publish the news entry. + +
  10. Send an announcement to the mailing list. +
+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/drawvg-reference.html b/ffmpeg-n8.1/doc/drawvg-reference.html new file mode 100644 index 00000000..e742f21e --- /dev/null +++ b/ffmpeg-n8.1/doc/drawvg-reference.html @@ -0,0 +1,2967 @@ + + + + + + + drawvg - Language Reference + + + + + + +
+

+ drawvg - Language Reference +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + + + +

1 Introduction

+ +

drawvg (draw vector graphics) is a language to draw +two-dimensional graphics on top of video frames. It is not intended to +be used as a general-purpose language. Since its scope is limited, it +prioritizes being concise and easy to use. +

+

For example, using the +Canvas +API we can render a triangle running this code in a Web browser: +

+
+
const canvas = document.getElementById("canvas");
+const ctx = canvas.getContext("2d");
+
+ctx.beginPath();
+ctx.moveTo(125, 50);
+ctx.lineTo(100, 100);
+ctx.lineTo(150, 100);
+ctx.closePath();
+ctx.stroke();
+
+ +

The same triangle can be written with this drawvg script: +

+
+
moveto 125 50
+lineto 100 100 150 100
+closepath
+stroke
+
+ +

It can be shortened using the aliases for moveto, lineto, +and closepath: +

+
+
M 125 50
+L 100 100 150 100
+Z
+stroke
+
+ +

Both newlines (U+000A) and spaces (U+0020) can be used +interchangeably as delimiters, so multiple commands can appear on the +same line: +

+
+
M 125 50 L 100 100 150 100 Z
+stroke
+
+ + +

Finally, drawvg can use FFmpeg expressions and frame metadata in command arguments. In +this example, we are using the variables w (frame width) and h +(frame height) to create a circle in the middle of the frame. +

+
+
circle (w / 2) (h / 2) (w / 3)
+stroke
+
+ +

Many commands are a direct equivalent to a function in the +Cairo graphics library. For such +commands, the reference below provides a link to the related Cairo +documentation. +

+ +

2 Syntax

+ + +

The syntax is heavily inspired by languages like +Magick +Vector Graphics, or SVG’s <path>. Many command names are taken from +PostScript. +

+ +

2.1 Structure

+ +

A drawvg script consists of a series of commands to describe 2D +graphics. +

+

A command is an identifier (like setcolor or lineto) +followed by its arguments. Each item in the code (command name, +arguments, etc.) is separated by any of the following characters: +

+
    +
  • Space (' ') +
  • Comma (',') +
  • Newline ('\n') +
  • Tabs ('\t') +
  • Return ('\r') +
+ +

The beginning of the item indicates how it will be interpreted: +

+
+
//
+

Comment +

+
0, …, 9, +, -
+

Number literal +

+
(
+

Expression +

+
{, }
+

Block delimiters +

+
Anything else
+

Name of a command, a color, etc. +

+
+ + +

2.2 Comments

+ +

Comments start with two slashes (//), and stop at the end of the +line (either a \n, or the end of the script). +

+
+
circle 100 100 50 // this is ignored
+fill
+
+// this is also ignored
+
+ +

// must appear after a space, or at the beginning of the line. If +// is preceded by any non-blank character, the parser will +consider // as part of the previous item. +

+

For example, in this script: +

+
+
circle 10 10 50// something
+
+ +

The parser throws an error because it tries to parse 50// as a +number literal. +

+ +

2.3 Commands

+ +

The way commands are parsed is inspired by SVG’s <path>: +

+
    +
  • Every command in the script starts with its name, and it is followed by +zero or more arguments. + +
  • There are no explicit delimiters between commands or arguments. + +

    Most programming languages expect characters like parenthesis, commas, +or semicolons, to separate items. For example: +

    +
    +
    moveto(10, 10); lineto(20, 30);
    +
    + +

    The equivalent in drawvg is: +

    +
    +
    moveto 10 10 lineto 20 30
    +
    + +
  • If the command has no arguments (like closepath or +stroke), the next command starts at the next item. + +
+ +
+Example
+

In the next script there are 4 different commands: +

+
+
newpath rect 10 20 30 40 setcolor teal fill
+
+ +
    +
  1. newpath requires no arguments. + +
  2. rect requires 4 arguments, so it takes the next 4 numbers. + +
  3. setcolor requires 1 argument, so it takes the word teal. + +
  4. fill requires no arguments. +
+ +
+ + +

2.3.1 Single-Letter Aliases

+ +

Most commands in SVG’s <path> are also present in drawvg. For some of them, +there is an alias to a longer name: +

+ + +

Other commands only exist in a single-letter form: +

+ + +

This makes it possible to use a path in SVG to create the same shape in +a drawvg script. +

+ +

2.3.2 Implicit Commands

+ +

For many commands, the name can be omitted when it is used multiple +times in successive calls. +

+

In the reference below, these commands has a Can be Implicit note +in their signature. +

+
+Example
+

For example, in this script: +

+
+
M 50 50
+l 10 10
+l 10 -10
+l 10 10
+l 10 -10
+l 10 10
+stroke
+
+ +

After the first call to l (alias to rlineto), the command +can be executed without the name, so it can be written as: +

+
+
M 50 50
+l 10 10 10 -10 10 10 10 -10 10 10
+stroke
+
+ +
+ +

To reuse the same command (l, in the previous example), the +parser checks if the item after the last argument is a numeric value, +like a number literal or a FFmpeg expression. +

+
+Example
+

In this example: +

+
+
l 10 20 30 40 stroke
+
+ +

l requires 2 arguments, and can be implicit, so the parser +performs this operation: +

+
    +
  1. Takes the two next items (10 and 20) and emits the first +instruction. + +
  2. Checks if the item after 20 is a numeric value. Since it is +30, it takes 30 and 40 and emits the second +instruction (l 30 40). + +
  3. Checks if the next item after 40 is a numeric value, but it is a +command (stroke), so it stops reusing l. + +
+ +
+ +

This is another feature taken from SVG’s <path>. An important difference with +SVG is that the separator between items is always required. In SVG, it can be +omitted in some cases. For example, the expression m1-2 is equivalent to +m 1 -2 in SVG, but a syntax error in drawvg. +

+ +

2.4 Arguments

+ +

Most commands expect numeric arguments, like number literals, variable +names, or expressions. +

+

setcolor and colorstop expect a color. +

+

setlinecap and setlinejoin expect a constant value. +

+ +

2.4.1 Number Literals

+ +

A number literal is an item in the script that represents a constant +value. Any item that starts with a decimal digit (between 0 and +9), a - or a +, is interpreted as a number literal. +

+

The value is parsed with +av_strtod. +It supports the prefix 0x to write a value with hexadecimal +digits, and +many +units (like K or GiB). +

+

In the next example, all literals represent the same value: +

+
+
10000
+1e4
+10K
+0x2710
+
+ + +

2.4.2 Expressions

+ +

FFmpeg expressions can be used as arguments for any command that expects a numeric +argument. The expression must be enclosed in parenthesis. +

+
+Example
+

The variables w and h represent the width and height of the +frame. We can compute the center of the frame by dividing them by 2: +

+
+
M (w / 2) (h / 2)
+
+ +

They can also contain parenthesis (to group operations, to call functions, +etc): +

+
+
moveto
+    ((w + 10) / 2)      // x
+    (h / (2 * cos(t)))  // y
+
+ +
+ +

The variables n and t can be used to compute a value that changes +over time. +

+
+Example
+

To draw a circle oscillating from left to right, we can use an +expression based on sin(t) for the x coordinate: +

+
+
circle
+    (w / 2 + sin(2 * t) * w / 4)  // x
+    (h / 2)                       // y
+    (w / 5)                       // radius
+
+stroke
+
+ +
+ +

Expressions can be split in multiple lines, but they can’t contain +comments within them. +

+
+
moveto   // This is a comment.
+    (w   // This is part of the expression, not a comment.
+     + h)
+
+ + +

2.4.3 Variable Names

+ +

When an expression is only a reference to a variable, the parenthesis +can be omitted, and the item is just the variable name. +

+
+Example
+

The next 3 expressions are equivalent: in all cases, they create a +rectangle covering the whole frame. +

+
+
rect (0) (0) (w) (h)
+
+rect 0 0 w h
+
+rect (0) 0 (w) h
+
+ +
+ +

It is possible to create a variable with the same name of a command, and +then use it as an argument. In the previous example, the item h is a +reference to a variable (frame height), but in other contexts it may be +a command (h). +

+

For implicit commands, the parser prioritizes +commands over variable names when it has to determine if the command is +reused. +

+
+Example
+

In this example, the variable c is used as the first argument in two +calls to l. However, only the first one is valid, because in the +second call the parser recognizes c as a command. +

+
+
setvar c 5
+l c 10 c 15
+
+ +

This issue can be fixed by surrounding the start of the second call with +parenthesis: +

+
+
setvar c 5
+l c 10 (c) 15
+
+ +
+ + +

2.4.4 Colors

+ +

The color to stroke and to fill paths can be set with setcolor. +Its argument has the same syntax for colors in FFmpeg: +

+
    +
  • A predefined color name. + +
  • In #RRGGBB format. + +
  • Optionally, an @a suffix can be added to set the alpha value, +where a is a number between 0 and 1. +
+ +
+
circle 70 70 60
+setcolor #FF0000
+fill
+
+circle 170 170 60
+setcolor blue@0.5
+fill
+
+ +

The color can be a variable name. In that case, it must be assigned with +defrgba, defhsla, or setvar and a color. +

+
+
circle 70 70 60
+setvar CustomGreen #22FF44
+setcolor CustomGreen
+fill
+
+circle 170 170 60
+defhsla CustomBlue 200 0.7 0.5 1
+setcolor CustomBlue
+fill
+
+ +

The commands setrgba and sethsla allow setting colors using +expressions. Similar to defrgba and defhsla, but with no +intermediate variable. +

+ +

2.4.5 Constants

+ +

The argument for setlinecap and setlinejoin is an +identifier referring to a constant value. +

+
+
setlinecap round
+
+ + +

3 Guide

+ + +

3.1 Paths

+ +

A path is a complex shape, composed by lines and curves, that can be +used to fill a region, to stroke an outline, or to establish a clip +region. +

+

In order to draw anything on top of a video frame, first we have to +define a path, and then use stroke or fill. +

+

The +tutorial +on paths in MDN is a good introduction to the topic. It is focused on +SVG’s <path>, but the same concepts can be applied in drawvg. +

+ +

3.1.1 Current Point

+ +

Some commands require a current point. Initially, the +current point is set to +NaN. It is initialized +with M or moveto. Other commands, like lineto or +curveto, updates the current point to the new end of the +shape. +

+

The current point can be cleared with newpath. Commands +that clear the path, like stroke or fill, also clear the +current point. +

+
+Example
+

rlineto uses coordinates relative to the current point. +

+

Given this script: +

+
+
moveto 20 100
+rlineto 150 -90
+rlineto -50 200
+closepath
+stroke
+
+ +

These are the coordinates of the current point after executing +each command: +

+ + + + + + + +
CommandCurrent Point
moveto 20 10020, 100
rlineto 150 -90170, 10
rlineto -10 50140, 210
closepath20, 100
+ +

The same script can be written with single-letter aliases: +

+
+
M 20 100 l 150 -90 -50 200 z stroke
+
+ +
+ + +

3.1.2 Defining a Shape

+ +

A path is defined by adding lines, curves, or basic shapes. +

+ + +

Single-letter commands are taken from SVG’s <path>. +

+ +

3.1.3 Fill

+ +

The region within the shape defined by a path can be filled with +fill or eofill. Each command uses a different +fill +rule: +

+ + +
+Example
+

This script shows the difference between the +winding +and +even–odd +rules: +

+
+
rect 50 10 100 60
+circle 150 70 40
+setcolor seagreen
+fill
+
+rect 50 130 100 60
+circle 150 190 40
+setcolor skyblue
+eofill
+
+ +
+ + +

3.1.4 Stroke

+ +

stroke draws a line around the shape defined by the path. The +stroke can be configured with different commands: +

+ + +
+Example
+

This example use setdashoffset to animate the stroke: +

+
+
moveto 0 0
+lineto w h
+
+setlinecap round
+setdash 50 50
+setlinewidth 20
+setdashoffset (hypot(w, h) * t / -3)
+setcolor seagreen
+
+stroke
+
+ +
+ + +

3.1.5 Clip

+ +

A clip +region can be established with clip and eoclip. +

+

If there is an active clip region, the new clip region will be the +intersection between the existing one and the path. resetclip +reset the clip region to the whole frame. +

+

eoclip uses the +even–odd +rule to compute the clip region. +

+
+Example
+
+
rect 50 50 100 200
+clip
+
+circle 30 30 150
+setcolor seagreen
+fill
+
+// Draw outside the clip region.
+resetclip
+circle 30 30 150
+setlinewidth 3
+setcolor skyblue
+stroke
+
+ +
+ + +

3.1.6 Preserving Paths

+ +

The path is cleared after any operation on it, like fill or +stroke. To reuse the same path in multiple operations, +preserve must be called before them. +

+
+Example
+

In this example, each path is used twice. +

+
+
circle 120 120 50
+setcolor seagreen
+preserve stroke
+clip
+
+circle 100 100 50
+setcolor skyblue
+preserve fill
+setcolor tomato
+stroke
+
+ +
+ + +

3.2 Variables

+ +

A drawvg can use some variables, provided by the interpreter, to compute +values in FFmpeg expressions: +

+
+
cx
+

X coordinate of the current point. +

+
+
cy
+

Y coordinate of the current point. +

+
+
w
+

Width, in pixels, of the frame. +

+
+
h
+

Height, in pixels, of the frame. +

+
+
i
+

The loop counter in repeat blocks. +

+
+
n
+

Frame number. +

+
+
t
+

Timestamp, in seconds. +

+
+
ts
+

Timestamp, in seconds, of the first frame. +

+
+
duration
+

Duration, in seconds, of the frame. +

+
+ + +

3.2.1 User Variables

+ +

New variables can be created with the setvar command. It +associates a name with a numeric value. +

+

The name must follow these rules: +

+
    +
  • It must start with an ASCII letter or an underscore (_). + +
  • It can contain only ASCII letters, underscores, and digits. + +
  • It must not match the name of a variable provided by the interpreter +(like w or t). +
+ +

The same variable can be assigned multiple times. +

+
+Example
+

In this example, the result of an expression is stored in a variable +with the name progress. Then, it is used for the x and +width arguments of rect. +

+
+
setvar progress (w * (pow(mod(t / 2 + 0.5, 1), 2.5)))
+
+rect ((w - progress) / 2) 0 progress h
+
+setcolor darkblue
+fill
+
+ +
+ +

Currently, a script can contain only 20 different variable names, but +this limit can be modified in the future. +

+ +

3.3 Patterns

+ +

The pattern for fill and stroke operations can be either a solid color, +or a gradient. +

+ + +

The pattern is not cleared after being used in a fill or stroke +operation, but it is replaced by any command that sets a new pattern. +

+ +

3.3.1 Gradients

+ +

To configure a gradient, first call to lineargrad or +radialgrad, and then add color stops by calling colorstop +for each stop. +

+
+Example
+

In this example, the whole frame is filled with a linear gradient: +

+
+
lineargrad 0 0 w h
+colorstop 0 skyblue
+colorstop 1 darkblue
+
+rect 0 0 w h
+fill
+
+ +

In this example, a radial gradient is used to simulate a sphere: +

+
+
radialgrad 90 90 5 120 120 100
+colorstop 0.0 #90DDFF
+colorstop 0.9 #000030
+colorstop 1.0 #000000
+
+rect 0 0 w h
+fill
+
+ +
+ + +

3.3.2 Variables

+ +

setcolor and colorstop accept a variable name as the +argument. The variable must be assigned with defrgba, +defhsla, or setvar and a color. +

+
+Example
+
+
// Use color #1020FF, alpha = 50%
+setvar someblue #1020FF@0.5
+
+setcolor someblue
+
+rect 30 30 120 120
+fill
+
+rect 90 90 120 120
+fill
+
+ +
+ +

If a variable has the same name of a known color, the +variable has preference, and will be used instead of the predefined color. +

+
+Example
+
+
setcolor teal
+rect 30 30 120 120
+fill
+
+setvar teal #70AAAA
+setcolor teal         // Use the new color for `teal`.
+rect 90 90 120 120
+fill
+
+ +
+ +

defrgba and defhsla assign a color to a variable, by providing +an expression for each color component: +

+
    +
  • For defrgba: red, green, blue, and +alpha. + +
  • For defhsla: hue, saturation, lightness, and +alpha. +
+ +

Each color component must be in range 0 to 1, except +hue, which is 0 to 360. +

+
+Example
+
+
defrgba colorA 1 0.5 0.25 1     // colorA = RGB(255, 127, 63)
+defhsla colorB 200 0.75 0.25 1  // colorB = HSL(200, 75%, 25%)
+
+rect 0 0 (w / 2) h
+setcolor colorA
+fill
+
+rect (w / 2) 0 (w / 2) h
+setcolor colorB
+fill
+
+ +
+ + +

3.4 Transformations

+ +

The coordinates for each command can be scaled, rotated, and translated, +by using the following commands: +

+ + +

The transformations are applied when the command is executed. They have +no effect on the existing path, only on the new segments added to it. +

+

They are done by updating the +current +transformation matrix in the Cairo context. To reset the matrix to its +original state, before any transformation, use resetmatrix. +

+

The transform origin for scale and rotation is initially at 0, 0, +but it can be adjusted with translate. +

+
+Example
+
+
// Map (0, 0) as the center of the frame.
+translate (w / 2) (h / 2)
+
+// Scale the space as if the frame is 1x1 pixel.
+scalexy w h
+
+// Draw multiple lines with the same arguments,
+// but each one on a different rotation.
+repeat 10 {
+    rotate (PI / 10)
+    M -0.25 0
+    H 0.25
+}
+
+// Reset transformations, so the scale does not
+// affect stroke.
+resetmatrix
+
+stroke
+
+ +
+ + +

3.5 State Stack

+ +

The state of a drawvg script contains all parameters used for drawing +operations, like the current color, the transformation matrix, the +stroke configuration, etc. +

+

The save command pushes a snapshot of the state to an internal +stack. Later, restore pops the latest snapshot from the stack, +and uses it as the new state. +

+

The parameters that can be saved and restored are: +

+ + + +

3.6 Frame Metadata

+ +

Some FFmpeg filters add metadata to frames. The command +getmetadata can read metadata items containing a numeric value, +and store it in a variable that can be used for command arguments. +

+
+Example
+

The cropdetect filter computes the parameters to remove empty +regions around the video. These parameters are accessible in the +lavfi.cropdetect keys of the frame metadata. +

+
+
// Get metadata from cropdetect filter and store it
+// in `cd*` variables.
+getmetadata cdx lavfi.cropdetect.x
+getmetadata cdy lavfi.cropdetect.y
+getmetadata cdw lavfi.cropdetect.w
+getmetadata cdh lavfi.cropdetect.h
+
+rect cdx cdy cdw cdh
+setcolor yellow@0.5
+setlinewidth 10
+stroke
+
+ +

To test the script, copy it to a drawcropdetect.vgs file, and +then execute a command like this: +

+
+
ffplay -i example-video.webm -vf 'cropdetect, drawvg=file=drawcropdetect.vgs'
+
+ +
+ + +

3.7 if / repeat Statements

+ +

There is limited support for control flow statements: only if and +repeat. +

+

Both commands receive two arguments: an expression and a block. +

+
+
if (condition) {
+    // commands
+}
+
+repeat (count) {
+    // commands
+}
+
+ +

if executes its block if the result of (condition) is not +zero. +

+

repeat executes its block the number of times specified by +(count). In each iteration, the variable i is used as a +loop +counter. +

+

If the result of the expression is not a finite number (like +NaN) the block is not +executed. +

+ +

3.7.1 Comparison and Logical Operators

+ +

FFmpeg expressions only supports arithmetic operators (like + for addition). +Comparison operators (like !=) are supported via functions, while +logical operators (like && for AND) can be emulated with +arithmetic operations. +

+ + + + + + + + + +
ExpressionFFmpeg Equivalent
x = yeq(x, y)
x < ylt(x, y)
x > ygt(x, y)
x ≤ ylte(x, y)
x ≥ ygte(x, y)
a ≤ x ≤ bbetween(x, a, b)
+ +

Logical operators can be emulated with multiplication (for AND), +or addition (for OR): +

+ + + + + +
ExpressionFFmpeg Equivalent
x OR yx + y
x AND yx * y
+ +
+Example
+

In other programming languages, a code like this: +

+
+
if (x > y && z != 1) {
+    // …
+}
+
+ +

Can be written for drawvg like this: +

+
+
if (gt(x, y) * not(eq(z, 1))) {
+    // …
+}
+
+ +
+ + +

3.7.2 Early Exit

+

break causes a repeat loop to be terminated immediately. +

+

If it is executed outside a repeat block, it terminates the whole +script, or the current procedure. +

+
+Example
+

In this example, we are using the randomg function +to draw a line with random segments. +

+

The loop can be executed 500 times, but it is interrupted if the X +coordinate of the current point (cx) exceeds the frame width +(w). The current point is updated after each call to +rlineto. +

+
+
moveto 0 0
+
+repeat 500 {
+    rlineto
+        (randomg(0) * 15)
+        (randomg(0) * 20)
+
+    if (gt(cx, w)) {
+        break
+    }
+}
+
+stroke
+
+ +
+ + +

3.8 Procedures

+ +

A procedure is a name associated with a block that can be executed +multiple times. It can take between 0 and 6 parameters. +

+

proc is used to set the parameter names and the block for a +procedure: +

+
+
proc p0 {
+    // …
+}
+
+proc p1 param1 param2 {
+    // …
+}
+
+ +

Inside the block, the arguments can be accessed as regular variables: +

+
+
proc square center_x center_y side {
+    rect
+        (center_x - side / 2) (center_y - side / 2)
+        side side
+}
+
+ +

call executes the block assigned to the procedure name. It +requires the name of the procedure, and the value for each parameter +defined in the call to proc. +

+
+
call p0
+
+call p1 1 2
+
+call square (w / 2) (h / 2) (w / t)
+
+ +
+Example
+

In this example, the procedure zigzag draws multiple lines from +the current point. +

+
+
setvar len (w / 10)
+setlinewidth 5
+
+proc zigzag {
+    repeat 10 {
+        l len len len (-len)
+    }
+
+    stroke
+}
+
+setcolor #40C0FF
+M 0 60
+call zigzag
+
+setcolor #00AABB
+M 0 120
+call zigzag
+
+setcolor #20F0B7
+M 0 180
+call zigzag
+
+ +

The color and the Y coordinate of the starting point can be sent as +procedure arguments: +

+
+
setvar len (w / 10)
+setlinewidth 5
+
+proc zigzag color y {
+    setcolor color
+
+    M 0 y
+    repeat 10 {
+        l len len len (-len)
+    }
+
+    stroke
+}
+
+call zigzag #40C0FF 60
+call zigzag #00AABB 120
+call zigzag #20F0B7 180
+
+ +
+ +

When the procedure returns, the value of the variable for each argument +is restored to the value it had before calling the procedure. Changes in +other variables (with setvar, getmetadata, defhsla, +and defrgba) are preserved. +

+
+Example
+

In the next example, the variable A has the value 0 before +calling the procedure P. During the execution of P, +A is 1, but after it, A is 0 again. +

+
+
setvar A 0
+
+proc P A {
+    print A
+}
+
+print A
+call P 1
+print A
+
+ +

It writes the following messages: +

+
[7:7] A = 0.000
+[4:8] A = 1.000
+[9:7] A = 0.000
+
+
+ +

break causes the script to leave the current procedure, similar +to the +return +statement in other programming languages, unless it is called within a +repeat loop. +

+

The body of the procedure must be defined with proc before +using call. +

+
+Example
+

In this example, when the procedure notyet is called, its body +has not yet defined, so the execution fails with the error +Missing body for procedure 'notyet'. +

+
+
call notyet
+
+proc notyet {
+    // ...
+}
+
+ +
+ +

A procedure can be redefined by other calls to proc with the same +name. In such case, call invokes the last assigned block. +

+
+Example
+

In this example, the procedure example has two different blocks. +

+
+
proc example {
+    // block1
+}
+
+call example    // executes block1
+
+proc example {
+    // block2
+}
+
+call example    // executes block2
+
+ +
+ + +

3.9 Functions in Expressions

+ +

There are some functions specific to drawvg available in FFmpeg expressions. +

+ +

3.9.1 Function p

+ +

p(x, y) returns the color of the pixel at coordinates x, y, as a +0xRRGGBBAA value. It can be assigned to a variable, so the color can be +available for setcolor and colorstop commands. +

+

If a single expression contains multiple calls to the function, it must return +the value of the last call in order to use it as a color. +

+
+Example
+

In this example, the first call to p(0, 0) is stored in the variable +0 of the expression. Then, the same expression makes a second call to +p(1, 1), and finally it returns the value in the variable 0. +

+
+
setvar pixel (st(0, p(0, 0)); p(1, 1); ld(0))
+
+ +

Since the result of the expression is not the last call to p, the +variable pixel can not be used as a color, but it still can be used as +a numeric 0xRRGGBBAA value. +

+
+ +

If the coordinates are outside the frame, or any of the arguments is not +a finite number (like +NaN), the function +returns NaN. +

+

The transformation matrix is applied to the +arguments. To use the original frame coordinates, call +resetmatrix between save and restore: +

+
+
save
+resetmatrix
+setvar pixel (p(0, 0))    // top-left pixel of the frame.
+restore
+
+setcolor pixel
+
+ +

Bitwise operations can be used to extract individual color components: +

+
+
setvar pixel (p(x, y))
+
+if (not(isnan(pixel))) {
+    setvar px_red   (pixel / 0x1000000)
+    setvar px_green (bitand(pixel / 0x10000, 0xFF))
+    setvar px_blue  (bitand(pixel / 0x100, 0xFF))
+    setvar px_alpha (bitand(pixel, 0xFF))
+}
+
+ + +

3.9.2 Function pathlen

+ +

pathlen(n) computes the length of the current path, by adding the +length of each line segment returned by +cairo_copy_path_flat. +

+

The function expects an argument n, as the maximum number of line +segments to add to the length, or 0 to add all segments. +

+
+Example
+

In this example, pathlen is used to animate the stroke of a +spiral, in a 5 seconds loop. +

+
+
M (w / 2) (h / 2)
+
+setvar a -1
+repeat 16 {
+    rcurveto
+        (a * 2 / 3) 0
+        (a * 2 / 3) (a)
+        0 (a)
+
+    setvar a (-sgn(a) * (abs(a) + 10))
+}
+
+setlinewidth 3
+setdash
+    (pathlen(0) * (1 - mod(t / 5, 1)))
+    1e6
+
+setcolor teal
+stroke
+
+ +
+ + +

3.9.3 Function randomg

+ +

randomg(idx) is similar to the random(idx) function, +available in FFmpeg expressions, but its state is global to the frame, instead +of specific to each expression. +

+

To understand the difference, we need to dive into how +random(idx) works inside a drawvg script. +

+

First, each expression in FFmpeg has a set of 10 internal variables, +which can be written with st(idx, value), and can be read with +ld(idx). idx is a value between 0 and 9. +These variables are initialized to 0. +

+

When a drawvg script is parsed, each expression is compiled with +av_expr_parse, +from libavutil, and these +compiled expressions are reused for every frame. The changes in the +internal variables (with st(idx, value)) are visible between +frames, but they are not shared between expressions. +

+
+Example
+

In this example, the expression for the X coordinate updates its +internal variable 0 in every frame: +

+
+
circle
+    (st(0, mod(ld(0) + 15, w))) // X
+    120                         // Y
+    (ld(0) + 20)                // radius
+
+fill
+
+ +

st(idx, value) returns the updated value, so it can be used as +the result of the expression. +

+

The radius is not affected because its internal variable (from +ld(0)) is not updated by the other expression. +

+

Also, note that this example is just to show how internal variables are +kept between frames. A better approach to create this animation is to +use the variables n or t: +

+
+
circle (mod(n * 15, w)) 120 20
+fill
+
+ +
+ +

The function random(idx) returns a +pseudorandom +value between 0 and 1. idx is the internal variable +that is used both as the seed and to keep the state of the number +generator. +

+
+Example
+

The next example uses random(0) to generate a random value for +the center of a circle: +

+
+
circle
+    (random(0) * w)
+    (random(0) * h)
+    10
+
+fill
+
+ +

The circle in every frame is at a different position, but always on the +diagonal line of the frame. This happens because the values for the +coordinates X and Y are identical, since both number generators use the +same seed. +

+

To distribute the circles over the whole frame we need different seeds +for each expression. This can be achieved by writing a non-zero value +(like 0xF0F0) to the internal variable of one of expressions, but +only when its value is 0: +

+
+
circle
+    (random(0) * w)
+    (st(0, if(ld(0), ld(0), 0xF0F0)); random(0) * h)
+    10
+
+fill
+
+ +

This approach is only useful if we need completely different positions +in each frame. In the next example, random values are used to distribute +many circles over the frame, but the position is fixed. The only change +over time is the fill color: +

+
+
repeat 20 {
+    circle
+        (st(0, i + 1e5); random(0) * w)
+        (st(0, i + 1e10); random(0) * h)
+        10
+}
+
+sethsla (t * 60) 0.5 0.5 1
+preserve fill
+
+setcolor black@0.5
+setlinewidth 1
+stroke
+
+ +

This is achieved by using a precomputed state before calling random(0). +The variable i, updated by repeat, is needed to compute +different states in each iteration. +

+
+ +

The randomg(idx) function, which is specific to drawvg scripts, +is similar to random(idx), but intended to solve the previous +problems: +

+
    +
  • All frames have the same seed. +
  • The state is shared between expressions. +
+ +

The parameter idx has two uses: +

+
    +
  • The last two bits are the index of an internal state, so it is possible +to have 4 different number generators. + +
  • The first call to randomg with a specific index will use the +argument as the seed for the number generator in that index. +
+ +

In a script like this: +

+
+
M (randomg(0xFF1)) (randomg(0xFF0))
+l (randomg(0xAA1)) (randomg(0xFF0))
+
+ +

There are 4 calls to randomg: +

+
    +
  1. The first call, with the argument 0xFF1, uses the internal state +at index 1 (because 0xFF1 modulo 4 is 1). + +

    Since this is the first use of that index, the number generator is +initialized with the seed 0xFF1. +

    +
  2. The second call has the same behaviour: it initializes the state at +index 0 with the value 0xFF0. + +
  3. The third call has the argument 0xAA1, and it uses index +1. Since that state is already initialized (with the seed +0xFF1), the value 0xAA1 is ignored, and it returns the +next number. + +
+ +
+Example
+

This example renders a simple rain animation, moving lines from top to +bottom. +

+

randomg is used to distribute the lines over the frame, and to +apply different speeds to each one. +

+
+
rect 0 0 w h
+setcolor midnightblue
+fill
+
+setcolor white
+
+repeat 50 {
+    setvar offset (t * (randomg(0) + 1))
+
+    moveto
+        (mod(randomg(0) + offset / 6, 1) * w)
+        (mod(randomg(0) + offset, 1) * h)
+
+    rlineto 6 36
+
+    setlinewidth (randomg(1) / 2 + 0.2)
+    stroke
+}
+
+ +
+ + +

3.10 Tracing with print

+ +

It is possible to trace the execution of a drawvg script by printing the +value of an expression, either with the print command, or with +the print function. +

+

In both cases, the values are written to the FFmpeg log. +

+

Printing expressions may have a noticeable impact on the performance, so +it is preferable to use it only when necessary. +

+ +

3.10.1 Function print

+ +

The function print(t) writes the value of t, and returns its +argument. +

+
+Example
+

Given a line line this: +

+
+
M (sin(2 * PI * t) * w) 0
+
+ +

We can see the values of sin(2 * PI * t) by surrounding it with a +call to print(): +

+
+
M (print(sin(2 * PI * t)) * w) 0
+
+ +

Executing this script with a 1 second / 8 FPS video shows the expected +values for the sine function. +

+
$ ffmpeg \
+    -f lavfi \
+    -i 'color=r=8:d=1, drawvg=M (print(sin(2 * PI * t)) * w) 0' \
+    -f null /dev/null \
+  |& grep 'Eval @'
+
+[Eval @ 0x7f500f502d20] 0.000000
+[Eval @ 0x7f4ff784b420] 0.707107
+[Eval @ 0x7f4ff784ba20] 1.000000
+[Eval @ 0x7f4ff784c020] 0.707107
+[Eval @ 0x7f4ff784c620] 0.000000
+[Eval @ 0x7f4ff784cc20] -0.707107
+[Eval @ 0x7f4ff784d220] -1.000000
+[Eval @ 0x7f4ff784d820] -0.707107
+
+
+ + +

3.10.2 Command print

+ +

The command print accepts an arbitrary number of arguments, and +for each one it writes: +

+
    +
  • The source location (line and column). +
  • The source code of the expression. +
  • The result of evaluating the expression. +
+ +

When there are multiple expressions, they are separated by the | +character. +

+
+Example
+

The next script prints the position of the current point after the +l command: +

+
+
M 10 20
+l 100 100
+print cx cy
+stroke
+
+ +

For each frame, it produces this output: +

+
[3:7] cx = 110.000000 | [3:10] cy = 120.000000
+
+

The next example prints the values of random(0): +

+
$ ffmpeg \
+    -f lavfi \
+    -i 'color=r=8:d=1, drawvg=print (random(0))' \
+    -f null /dev/null \
+  |& grep 'drawvg @'
+
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.229731
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.959813
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.071676
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.044600
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.134127
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.320513
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.857675
+[drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.562456
+
+
+ + +

4 Commands

+ + + + +

4.1 arc

+ +

arc xc yc radius angle1 angle2    — Can be implicit +

+

Adds a circular arc of the given radius to the current path. The +arc is centered at xc, yc, begins at angle1 and proceeds +in the direction of increasing angles to end at angle2. +

+

If there is a current point, a line is added from it to the beginning of +the arc. If this is not desired, use newpath before arc to clear +the current point. +

+

See the documentation of the +cairo_arc +function for more details. +

+
+Example
+
+
arc 120 120 60 0 (3 * PI / 2)
+stroke
+
+ +
+ + +

4.2 arcn

+ +

arcn xc yc radius angle1 angle2    — Can be implicit +

+

Similar to arc, but it differs in the direction of the arc +between the two angles. +

+

See the documentation of the +cairo_arc_negative +function for more details. +

+
+Example
+

In this example, both arc and arcn have the same angles, +but they render different arcs: +

+
+
arc  120  90 60 (PI / 2) 0
+
+newpath
+arcn 120 150 60 (PI / 2) 0
+
+stroke
+
+ +
+ +

newpath is needed to prevent a line between the two arcs. +

+ +

4.3 break

+ +

break +

+

break terminates the execution of the innermost block, either a +repeat loop or a procedure. +

+

If it is used outside of a repeat / proc block, it +terminates the script for the current frame. +

+ +

4.4 call

+ +

call name args* +

+

Invokes a procedure defined by proc. +

+

See the Procedures section above for more details. +

+ +

4.5 circle

+ +

circle xc yc radius    — Can be implicit +

+

Adds a circle of the given radius to the current path. The circle +is centered at xc, yc. The current point is cleared before and +after adding the circle. +

+

This is a convenience wrapper for arc. A call to circle is +equivalent to: +

+
+
newpath
+arc xc yc radius (0) (2 * PI)
+newpath
+
+ + +

4.6 clip, eoclip

+ +

clip, eoclip +

+

Establishes a new clip region by intersecting the current clip region +with the current path as it would be filled by fill or +eofill. +

+

eoclip uses the +even–odd +rule. See fill rules for more details. +

+

The path is cleared after updating the clip region, unless the +preserve command is used before clip or eoclip. +

+

See the documentation of the +cairo_clip +function for more details. +

+ +

4.7 Z, z, closepath

+ +

Z, z, closepath +

+

Adds a line segment to the path from the current point to the beginning +of the current sub-path, and closes this sub-path. The beginning is set by any +of the move commands (M, m, moveto, +rmoveto). +

+

See the documentation of the +cairo_close_path +function for more details. +

+ +

4.8 colorstop

+ +

colorstop offset color    — Can be implicit +

+

Adds a color stop to a gradient pattern. +

+

offset is a value between 0 and 1, and it specifies +the location along the gradient’s control vector. +

+

This command must be executed after lineargrad or +radialgrad. +

+

Color stops can be added in any number of calls to colorstop. In +the next example, the 3 blocks define the same gradient: +

+
+
// 1
+colorstop 0.0 red
+colorstop 0.5 green
+colorstop 1.0 blue
+
+// 2
+colorstop 0 red 0.5 green
+colorstop 1 blue
+
+// 3
+colorstop 0 red 0.5 green 1 blue
+
+ +

See the documentation of the +cairo_pattern_add_color_stop_rgba +function for more details. +

+
+Example
+

In this example, color stops are added in a repeat loop. +

+
+
lineargrad 0 0 w h
+
+repeat 6 {
+    defhsla s (i * 60) 0.8 0.5 1
+    colorstop (i / 5) s
+}
+
+rect 0 0 w h
+fill
+
+ +

It is possible to avoid transitions between color stops by repeating the +same color in two stops: +

+
+
lineargrad 0 0 w h
+
+repeat 6 {
+    defhsla s (i * 60) 0.8 0.5 1
+    colorstop (i / 5) s
+    colorstop ((i + 1) / 5) s
+}
+
+rect 0 0 w h
+fill
+
+ +
+ + +

4.9 C, curveto

+ +

C, curveto x1 y1 x2 y2 x y    — Can be implicit +

+

Draw a cubic Bézier curve from the current point to the end point +specified by x, y. The start control point is specified by +x1, y1 and the end control point is specified by x2, y2. +

+ + +

The behaviour is identical to the C command in SVG’s <path>. For more +details, see Cubic Bézier Curve on MDN, and the Curve Commands section of the Paths tutorial on MDN. +

+
+Example
+
+
moveto 20 20
+
+curveto
+    0 (h / 2)           // start control point
+    w (h / 2)           // end control point
+    (w - 20) (h - 20)   // end point
+
+stroke
+
+ +
+ + +

4.10 c, rcurveto

+ +

c, rcurveto dx1 dy1 dx2 dy2 dx dy    — Can be implicit +

+

Like curveto, but the coordinates are relative to the current point. +

+ +

4.11 defhsla

+ +

defhsla varname h s l a +

+

Similar to sethsla, but instead of establishing the color for +stroke and fill operations, the computed color is assigned to the +variable varname. +

+

varname can then be used as a color for setcolor and +colorstop. +

+

See sethsla for more details on how the color is computed. +

+ +

4.12 defrgba

+ +

defrgba varname r g b a +

+

Computes a color from the red, green, blue, and +alpha components, and assigns it to the variable varname. +

+

All components are values between 0 and 1. Values outside +that range are clamped to it. +

+ +

4.13 ellipse

+ +

ellipse cx cy rx ry    — Can be implicit +

+

Adds an ellipse to the current path. Similar to circle, but it is +possible to use different radius for both axes. +

+
+Example
+
ellipse 120 120 75 50
+stroke
+
+
+ + +

4.14 fill, eofill

+ +

fill, eofill +

+

Fill the current path, using the current pattern (either +a solid color or a gradient). +

+

eofill uses the +even–odd +rule. See fill rules for more details. +

+

The path is cleared after the operation, unless the preserve +command is used before fill or eofill. +

+

See the documentation of the +cairo_fill +function for more details. +

+ +

4.15 getmetadata

+ +

getmetadata varname key +

+

Get the value of a metadata entry created by another filter, and assign +it to the variable varname. +

+

If there is no metadata entry for key, or its value is not a +number, varname is set to +NaN. +

+

See the Frame Metadata section above for an +example. +

+ +

4.16 H, h

+ +

H, h x    — Can be implicit +

+

Draw a horizontal line from the current point to x. +

+

The coordinate for H is absolute, and for h it is relative +to the current point. +

+ +

4.17 if

+ +

if condition { block } +

+

Executes a block if the value of condition is not zero, and a +finite number (unlike +NaN). +

+

See the Comparison and Logical Operators section +above for more details on how to write conditional expressions. +

+ +

4.18 lineargrad

+ +

lineargrad x0 y0 x1 y1 +

+

Set the current pattern to a new linear gradient, along +the line from the coordinates x0, y0 to x1, y1. +

+

This gradient can be used for stroke and fill operations. +

+

Use colorstop to set the color for each position in the gradient. +

+ +

4.19 L, lineto

+ +

L, lineto x y    — Can be implicit +

+

Draw a line from the current point to the coordinates at x, y. +

+

See the documentation of the +cairo_line_to +function for more details. +

+ +

4.20 l, rlineto

+ +

l, rlineto dx dy    — Can be implicit +

+

Like lineto, but the coordinates are relative to the current point. +

+ +

4.21 M, moveto

+ +

M, moveto x y    — Can be implicit +

+

Begin a new sub-path, and set the current point to x, y. +

+ +

4.22 m, rmoveto

+ +

m, rmoveto dx dy    — Can be implicit +

+

Like moveto, but the coordinates are relative to the current point. +

+ +

4.23 newpath

+ +

newpath +

+

Begin a new sub-path. Like moveto, but there is no +current point after it. +

+
+Example
+

In the next example, newpath is used in the path on the right to +prevent the line connecting both arcs. +

+
setlinewidth 3
+
+setcolor skyblue
+arcn 70 90 20 0 (PI)
+arc 70 150 20 0 (PI)
+stroke
+
+setcolor seagreen
+arcn 170 90 20 0 (PI)
+newpath
+arc 170 150 20 0 (PI)
+stroke
+
+
+ + +

4.24 preserve

+ +

preserve +

+

Indicates that the next operation to fill, stroke, or clip, must +preserve the path, so the same path can be used in multiple operations. +

+

It has effect on these commands: +

+ + +

The script can contain any command between preserve and the +associated operation. This allows modifying other properties, like the +current color. +

+
+Example
+

In this example, the same path is used for both fill and +stroke, but with different colors. +

+
circle (w / 2) (h / 2) (w / 3)
+
+setcolor skyblue
+preserve fill
+
+setlinewidth 10
+setcolor seagreen
+stroke
+
+
+ +

preserve can be called multiple times, if the same path has to be +used in 3 or more operations. +

+
+Example
+

In this example, the path created by circle is used by +fill, stroke, and clip. After clip, the +path is cleared. +

+
circle 100 100 50
+
+preserve fill
+preserve stroke
+clip
+
+
+ + +

4.25 print

+ +

print expr    — Can be implicit +

+

Print its arguments to the FFmpeg log. +

+

See the Command print section above for more details. +

+ +

4.26 proc

+ +

proc name params* { block } +

+

Assign the block and the parameters for the procedure name. The +procedure can be called multiple times with the call command. +

+

See the Procedures section above for more details. +

+ +

4.27 Q

+ +

Q x1 y1 x y +

+

Draw a quadratic Bézier curve from the current point to the end +point specified by x, y. The control point is specified by +x1, y1. +

+ +

The behaviour is identical to the Q command in SVG’s <path>. For more +details, see Quadratic Bézier curve on MDN, and the Curve Commands section of the Paths tutorial on MDN. +

+
+Example
+
moveto 20 20
+
+Q
+    0 h                 // control point
+    (w - 20) (h - 20)   // end point
+
+stroke
+
+
+ + +

4.28 q

+ +

q dx1 dy1 dx dy +

+

Like Q, but the coordinates are relative to the current point. +

+ +

4.29 radialgrad

+ +

radialgrad cx0 cy0 radius0 cx1 cy1 radius1 +

+

Creates a new radial gradient between the two circles defined by +cx0 cy0 radius0 and cx1 cy1 radius1. Each set of arguments +is the coordinates of the center and the radius. +

+

This gradient can be used for stroke and fill operations. +

+

Use colorstop to set the color for each position in the gradient. +

+
+Example
+

The animation in the next example shows how the two circles defined in +the radialgrad arguments interact with each other. +

+

The red circle represent the circle for the cx0 cy0 radius0 +arguments, and the yellow circle is the one for the +cx1 cy1 radius1 arguments. +

+
setvar cx0 (mod(t * 30, w))
+setvar cy0 120
+setvar radius0 20
+
+setvar cx1 120
+setvar cy1 120
+setvar radius1 70
+
+radialgrad
+    cx0 cy0 radius0
+    cx1 cy1 radius1
+
+colorstop
+    0 lightblue
+    1 darkblue
+
+// Fill the frame with the gradient.
+rect 0 0 w h
+fill
+
+// Draw inner circle.
+circle cx0 cy0 radius0
+setcolor red
+stroke
+
+// Draw outer circle.
+circle cx1 cy1 radius1
+setcolor yellow
+stroke
+
+
+ + +

4.30 rect

+ +

rect x y width height +

+

Adds a rectangle of the given size (width × height), at +position x, y, to the current path. The current point is cleared +before and after adding the rectangle. +

+

See the documentation of the +cairo_rectangle +function for more details. +

+ +

4.31 repeat

+ +

repeat count { block } +

+

Executes a block the number of times indicated by count. +

+

In each iteration, the variable i is used as a +loop +counter. It takes the values from 0 to count - 1. When +the loop is terminated, the variable is restored to the value before +starting the loop. +

+

If count is less than 1, or it is not a finite number +(like NaN), the block is +not executed. +

+ +

4.32 resetclip

+ +

resetclip +

+

Reset the current clip region to its original state, covering the whole +frame. +

+

See the documentation of the +cairo_reset_clip +function for more details. +

+ +

4.33 resetdash

+ +

resetdash +

+

Disable the dash pattern to be used by stroke. This reverts any +change made by setdash and setdashoffset. +

+

It calls +cairo_set_dash +with num_dashes set to 0. +

+ +

4.34 resetmatrix

+ +

resetmatrix +

+

Resets the current transformation matrix. +

+ +

4.35 restore

+ +

restore +

+

Restores the state saved by a preceding call to save. +

+

For more details, see the State Stack section above, and the +cairo_restore +function. +

+ +

4.36 rotate

+ +

rotate angle +

+

Modifies the current transformation matrix by rotating the user-space +axes by angle radians. +

+

See the documentation of the +cairo_rotate +function for more details. +

+
+Example
+

In this example: +

+
    +
  • scalexy maps the coordinates to a 1x1 frame. +
  • translate put 0, 0 at the center of the frame. +
  • rotate rotates 45°. +
  • resetmatrix reverts the transformations before stroke, so the +line width is not affected by the scale. +
+ +
scalexy w h
+translate 0.5 0.5
+rotate (PI / 4)
+rect -0.25 -0.25 0.5 0.5
+resetmatrix
+stroke
+
+
+ + +

4.37 roundedrect

+ +

roundedrect x y width height radius    — Can be implicit +

+

Like rect, but a circular arc is used for the corners. +

+
+Example
+

The next example shows the same rectangle, with different values for the +corner radius. +

+

The radius is computed by multiplying i (the +loop counter) by +4.5. This number is chosen to make the last shape a perfect circle. +

+
+
repeat 9 {
+    roundedrect
+        (mod(i, 3) * 80 + 5)     // x
+        (floor(i / 3) * 80 + 5)  // y
+        70 70                    // size
+        (i * 4.5)                // radius
+}
+
+stroke
+
+ +
+ + +

4.38 save

+ +

save +

+

Saves a copy of the current state on an internal stack. This copy can be +restored later with restore. +

+

For more details, see the State Stack section above, and the +cairo_save +function. +

+ +

4.39 scale

+ +

scale sxy +

+

Similar to scalexy, but the same value is used for both axes. It +is equivalent to: +

+

scalexy sxy sxy +

+ +

4.40 scalexy

+ +

scalexy sx sy +

+

Modifies the current transformation matrix by scaling the X and Y +user-space axes by sx and sy respectively. +

+

See the documentation of the +cairo_scale +function for more details. +

+

See rotate for an example on combining multiple transformations. +

+ +

4.41 setcolor

+ +

setcolor color +

+

Set a solid color as the current pattern for stroke and fill operations +

+

See the Colors section above for more details. +

+ +

4.42 setdash

+ +

setdash length    — Can be implicit +

+

Sets the dash pattern to be used by stroke. +

+

Each call to setdash adds a length to the pattern, alternating +between on and off portions of the stroke. +

+

After a call to setdash, resetdash is needed either to +create a new pattern, or to discard the current one. +

+

See the documentation of the +cairo_set_dash +function for more details. +

+ +

4.43 setdashoffset

+ +

setdashoffset offset +

+

Set the offset into the dash pattern at which the stroke should start. +

+

setdash must be called before setdashoffset. +

+

See the documentation of the +cairo_set_dash +function for more details. +

+
+Example
+

The next animation shows the effect of setdashoffset when its +argument changes over time. +

+
scalexy w h
+M 0.5 1
+curveto 0 0.5, 1 0.5, 0.5 0
+resetmatrix
+
+setdash 20 5 // 20 on, 5 off
+setdashoffset (t * 100)
+
+setlinewidth 20
+stroke
+
+
+ + +

4.44 sethsla

+ +

sethsla h s l a +

+

Set the current pattern to a solid color, given the hue, +saturation, and lightness, and alpha components. +

+

h is the hue, a value between 0 and 359. Negative +values are clamped to 0, and values greater than 359 are +interpreted as modulo 360. +

+

s (saturation), l (lightness), and a (alpha), are +values between 0 and 1. +

+

The conversion to RGB is implemented according to the +formulae from +Wikipedia. +

+ +

4.45 setlinecap

+ +

setlinecap cap +

+

Set the current line cap style, which determines the shape used to draw +the end points of lines. +

+

cap must be one of the following names: +

+
    +
  • butt +
  • round +
  • square +
+ +

It calls to +cairo_set_line_cap +to set the line cap style. +

+
+Example
+

This example draws 3 lines with the same length, each one with a +different line cap style: +

+
setlinewidth 40
+
+setlinecap butt
+setcolor tomato
+M 60 40 v 100 stroke
+
+setlinecap round
+setcolor seagreen
+M 120 40 v 100 stroke
+
+setlinecap square
+setcolor skyblue
+M 180 40 v 100 stroke
+
+M 20 40 H 220 m 0 100 H 20
+setcolor black@0.5
+setlinewidth 2
+stroke
+
+
+ + +

4.46 setlinejoin

+ +

setlinejoin join +

+

Sets the current line join style, which determines the shape used to +join two line segments. +

+

join must be one of the following names: +

+
    +
  • bevel +
  • miter +
  • round +
+ +

It calls to +cairo_set_line_join +to set the line join style. +

+
+Example
+

This example draws 3 lines with the same length, each one with a +different line join style: +

+
setlinewidth 30
+
+setlinejoin bevel
+setcolor tomato
+M 70 20 l 50 50 50 -50 stroke
+
+setlinejoin miter
+setcolor seagreen
+M 70 90 l 50 50 50 -50 stroke
+
+setlinejoin round
+setcolor skyblue
+M 70 160 l 50 50 50 -50 stroke
+
+
+ + +

4.47 setlinewidth

+ +

setlinewidth width +

+

Set the line width for stroke. +

+

width is affected by the transformation matrix. +

+

To specify a width that is not affected by other transformations, +resetmatrix can be used between save / restore: +

+
save
+
+resetmatrix
+setlinewidth 1
+stroke
+
+// Restore matrix after stroke.
+restore
+
+

See the documentation of the +cairo_set_line_width +function for more details. +

+ +

4.48 setrgba

+ +

setrgba r g b a +

+

Set the current pattern to a solid color, given the +red, green, blue, and alpha components. +

+

All components are values between 0 and 1. Values outside +that range are clamped to it. +

+ +

4.49 setvar

+ +

setvar varname value +

+

Set the variable varname to value. +

+

See the User Variables section above for more details. +

+ +

4.50 stroke

+ +

stroke +

+

Strokes the current path according to the current line width, line join, +line cap, and dash settings. +

+

The path is cleared after the operation, unless the preserve +command is used before stroke. +

+

See the documentation of the +cairo_stroke +function for more details. +

+ +

4.51 S, s

+ +

S, s x2 y2 x y    — Can be implicit +

+

Draw a smooth cubic Bézier curve from the current point to the end +point specified by x, y. The end control point is specified by +x2, y2. +

+

The start control point is the reflection of the end +control point of the previous curve command about the current +point. +

+

The behaviour is identical to the S command in SVG’s <path>. For more +details, see Cubic Bézier Curve on MDN, and the Curve Commands section of the Paths tutorial on MDN. +

+

s is like S, but the coordinates are relative to the current point. +

+
+Example
+
+
M 20 120
+
+c 25 -50, 25 50, 50 0
+
+repeat 3 {
+    s 20 50, 50 0
+}
+
+stroke
+
+ +
+ + +

4.52 translate

+ +

translate tx ty +

+

Modifies the current transformation matrix by +translating the user-space origin by tx, ty. +

+

See the documentation of the +cairo_translate +function for more details. +

+ +

4.53 T, t

+ +

T, t x y    — Can be implicit +

+

Draw a smooth quadratic Bézier curve from the current point to the +end point specified by x, y. +

+

The control point is the reflection of the control point +of the previous curve command about the current point. +

+

The behaviour is identical to the T command in SVG’s <path>. For more +details, see Quadratic Bézier curve on MDN, and the Curve Commands section of the Paths tutorial on MDN. +

+

t is like T, but the coordinates are relative to the +current point. +

+
+Example
+
+
M 20 120
+
+q 10 -20, 20 0
+
+repeat 9 {
+    t 20 0
+}
+
+stroke
+
+ +
+ + +

4.54 V, v

+ +

V, v y    — Can be implicit +

+

Draw a vertical line from the current point to y. +

+

The coordinate for V is absolute, and for v it is relative +to the current point. +

+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/faq.html b/ffmpeg-n8.1/doc/faq.html new file mode 100644 index 00000000..85df0306 --- /dev/null +++ b/ffmpeg-n8.1/doc/faq.html @@ -0,0 +1,821 @@ + + + + + + + FFmpeg FAQ + + + + + + +
+

+ FFmpeg FAQ +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 General Questions

+ + +

1.1 Why doesn’t FFmpeg support feature [xyz]?

+ +

Because no one has taken on that task yet. FFmpeg development is +driven by the tasks that are important to the individual developers. +If there is a feature that is important to you, the best way to get +it implemented is to undertake the task yourself or sponsor a developer. +

+ +

1.2 FFmpeg does not support codec XXX. Can you include a Windows DLL loader to support it?

+ +

No. Windows DLLs are not portable, bloated and often slow. +Moreover FFmpeg strives to support all codecs natively. +A DLL loader is not conducive to that goal. +

+ +

1.3 I cannot read this file although this format seems to be supported by ffmpeg.

+ +

Even if ffmpeg can read the container format, it may not support all its +codecs. Please consult the supported codec list in the ffmpeg +documentation. +

+ +

1.4 Which codecs are supported by Windows?

+ +

Windows does not support standard formats like MPEG very well, unless you +install some additional codecs. +

+

The following list of video codecs should work on most Windows systems: +

+
msmpeg4v2
+

.avi/.asf +

+
msmpeg4
+

.asf only +

+
wmv1
+

.asf only +

+
wmv2
+

.asf only +

+
mpeg4
+

Only if you have some MPEG-4 codec like ffdshow or Xvid installed. +

+
mpeg1video
+

.mpg only +

+
+

Note, ASF files often have .wmv or .wma extensions in Windows. It should also +be mentioned that Microsoft claims a patent on the ASF format, and may sue +or threaten users who create ASF files with non-Microsoft software. It is +strongly advised to avoid ASF where possible. +

+

The following list of audio codecs should work on most Windows systems: +

+
adpcm_ima_wav
+
adpcm_ms
+
pcm_s16le
+

always +

+
libmp3lame
+

If some MP3 codec like LAME is installed. +

+
+ + + +

2 Compilation

+ + +

2.1 error: can't find a register in class 'GENERAL_REGS' while reloading 'asm'

+ +

This is a bug in gcc. Do not report it to us. Instead, please report it to +the gcc developers. Note that we will not add workarounds for gcc bugs. +

+

Also note that (some of) the gcc developers believe this is not a bug or +not a bug they should fix: +https://gcc.gnu.org/bugzilla/show_bug.cgi?id=11203. +Then again, some of them do not know the difference between an undecidable +problem and an NP-hard problem... +

+ +

2.2 I have installed this library with my distro’s package manager. Why does configure not see it?

+ +

Distributions usually split libraries in several packages. The main package +contains the files necessary to run programs using the library. The +development package contains the files necessary to build programs using the +library. Sometimes, docs and/or data are in a separate package too. +

+

To build FFmpeg, you need to install the development package. It is usually +called libfoo-dev or libfoo-devel. You can remove it after the +build is finished, but be sure to keep the main package. +

+ +

2.3 How do I make pkg-config find my libraries?

+ +

Somewhere along with your libraries, there is a .pc file (or several) +in a pkgconfig directory. You need to set environment variables to +point pkg-config to these files. +

+

If you need to add directories to pkg-config’s search list +(typical use case: library installed separately), add it to +$PKG_CONFIG_PATH: +

+
+
export PKG_CONFIG_PATH=/opt/x264/lib/pkgconfig:/opt/opus/lib/pkgconfig
+
+ +

If you need to replace pkg-config’s search list +(typical use case: cross-compiling), set it in +$PKG_CONFIG_LIBDIR: +

+
+
export PKG_CONFIG_LIBDIR=/home/me/cross/usr/lib/pkgconfig:/home/me/cross/usr/local/lib/pkgconfig
+
+ +

If you need to know the library’s internal dependencies (typical use: static +linking), add the --static option to pkg-config: +

+
+
./configure --pkg-config-flags=--static
+
+ + +

2.4 How do I use pkg-config when cross-compiling?

+ +

The best way is to install pkg-config in your cross-compilation +environment. It will automatically use the cross-compilation libraries. +

+

You can also use pkg-config from the host environment by +specifying explicitly --pkg-config=pkg-config to configure. +In that case, you must point pkg-config to the correct directories +using the PKG_CONFIG_LIBDIR, as explained in the previous entry. +

+

As an intermediate solution, you can place in your cross-compilation +environment a script that calls the host pkg-config with +PKG_CONFIG_LIBDIR set. That script can look like that: +

+
+
#!/bin/sh
+PKG_CONFIG_LIBDIR=/path/to/cross/lib/pkgconfig
+export PKG_CONFIG_LIBDIR
+exec /usr/bin/pkg-config "$@"
+
+ + +

3 Usage

+ + +

3.1 ffmpeg does not work; what is wrong?

+ +

Try a make distclean in the ffmpeg source directory before the build. +If this does not help see +(https://ffmpeg.org/bugreports.html). +

+ +

3.2 How do I encode single pictures into movies?

+ +

First, rename your pictures to follow a numerical sequence. +For example, img1.jpg, img2.jpg, img3.jpg,... +Then you may run: +

+
+
ffmpeg -f image2 -i img%d.jpg /tmp/a.mpg
+
+ +

Notice that ‘%d’ is replaced by the image number. +

+

img%03d.jpg means the sequence img001.jpg, img002.jpg, etc. +

+

Use the -start_number option to declare a starting number for +the sequence. This is useful if your sequence does not start with +img001.jpg but is still in a numerical order. The following +example will start with img100.jpg: +

+
+
ffmpeg -f image2 -start_number 100 -i img%d.jpg /tmp/a.mpg
+
+ +

If you have large number of pictures to rename, you can use the +following command to ease the burden. The command, using the bourne +shell syntax, symbolically links all files in the current directory +that match *jpg to the /tmp directory in the sequence of +img001.jpg, img002.jpg and so on. +

+
+
x=1; for i in *jpg; do counter=$(printf %03d $x); ln -s "$i" /tmp/img"$counter".jpg; x=$(($x+1)); done
+
+ +

If you want to sequence them by oldest modified first, substitute +$(ls -r -t *jpg) in place of *jpg. +

+

Then run: +

+
+
ffmpeg -f image2 -i /tmp/img%03d.jpg /tmp/a.mpg
+
+ +

The same logic is used for any image format that ffmpeg reads. +

+

You can also use cat to pipe images to ffmpeg: +

+
+
cat *.jpg | ffmpeg -f image2pipe -c:v mjpeg -i - output.mpg
+
+ + +

3.3 How do I encode movie to single pictures?

+ +

Use: +

+
+
ffmpeg -i movie.mpg movie%d.jpg
+
+ +

The movie.mpg used as input will be converted to +movie1.jpg, movie2.jpg, etc... +

+

Instead of relying on file format self-recognition, you may also use +

+
-c:v ppm
+
-c:v png
+
-c:v mjpeg
+
+

to force the encoding. +

+

Applying that to the previous example: +

+
ffmpeg -i movie.mpg -f image2 -c:v mjpeg menu%d.jpg
+
+ +

Beware that there is no "jpeg" codec. Use "mjpeg" instead. +

+ +

3.4 Why do I see a slight quality degradation with multithreaded MPEG* encoding?

+ +

For multithreaded MPEG* encoding, the encoded slices must be independent, +otherwise thread n would practically have to wait for n-1 to finish, so it’s +quite logical that there is a small reduction of quality. This is not a bug. +

+ +

3.5 How can I read from the standard input or write to the standard output?

+ +

Use - as file name. +

+ +

3.6 -f jpeg doesn’t work.

+ +

Try ’-f image2 test%d.jpg’. +

+ +

3.7 Why can I not change the frame rate?

+ +

Some codecs, like MPEG-1/2, only allow a small number of fixed frame rates. +Choose a different codec with the -c:v command line option. +

+ +

3.8 How do I encode Xvid or DivX video with ffmpeg?

+ +

Both Xvid and DivX (version 4+) are implementations of the ISO MPEG-4 +standard (note that there are many other coding formats that use this +same standard). Thus, use ’-c:v mpeg4’ to encode in these formats. The +default fourcc stored in an MPEG-4-coded file will be ’FMP4’. If you want +a different fourcc, use the ’-vtag’ option. E.g., ’-vtag xvid’ will +force the fourcc ’xvid’ to be stored as the video fourcc rather than the +default. +

+ +

3.9 Which are good parameters for encoding high quality MPEG-4?

+ +

’-mbd rd -flags +mv4+aic -trellis 2 -cmp 2 -subcmp 2 -g 300 -pass 1/2’, +things to try: ’-bf 2’, ’-mpv_flags qp_rd’, ’-mpv_flags mv0’, ’-mpv_flags skip_rd’. +

+ +

3.10 Which are good parameters for encoding high quality MPEG-1/MPEG-2?

+ +

’-mbd rd -trellis 2 -cmp 2 -subcmp 2 -g 100 -pass 1/2’ +but beware the ’-g 100’ might cause problems with some decoders. +Things to try: ’-bf 2’, ’-mpv_flags qp_rd’, ’-mpv_flags mv0’, ’-mpv_flags skip_rd’. +

+ +

3.11 Interlaced video looks very bad when encoded with ffmpeg, what is wrong?

+ +

You should use ’-flags +ilme+ildct’ and maybe ’-flags +alt’ for interlaced +material, and try ’-top 0/1’ if the result looks really messed-up. +

+ +

3.12 How can I read DirectShow files?

+ +

If you have built FFmpeg with ./configure --enable-avisynth +(only possible on MinGW/Cygwin platforms), +then you may use any file that DirectShow can read as input. +

+

Just create an "input.avs" text file with this single line ... +

+
DirectShowSource("C:\path to your file\yourfile.asf")
+
+

... and then feed that text file to ffmpeg: +

+
ffmpeg -i input.avs
+
+ +

For ANY other help on AviSynth, please visit the +AviSynth homepage. +

+ +

3.13 How can I join video files?

+ +

To "join" video files is quite ambiguous. The following list explains the +different kinds of "joining" and points out how those are addressed in +FFmpeg. To join video files may mean: +

+
    +
  • To put them one after the other: this is called to concatenate them +(in short: concat) and is addressed +in this very faq. + +
  • To put them together in the same file, to let the user choose between the +different versions (example: different audio languages): this is called to +multiplex them together (in short: mux), and is done by simply +invoking ffmpeg with several -i options. + +
  • For audio, to put all channels together in a single stream (example: two +mono streams into one stereo stream): this is sometimes called to +merge them, and can be done using the +amerge filter. + +
  • For audio, to play one on top of the other: this is called to mix +them, and can be done by first merging them into a single stream and then +using the pan filter to mix +the channels at will. + +
  • For video, to display both together, side by side or one on top of a part of +the other; it can be done using the +overlay video filter. + +
+ + +

3.14 How can I concatenate video files?

+ +

There are several solutions, depending on the exact circumstances. +

+ +

3.14.1 Concatenating using the concat filter

+ +

FFmpeg has a concat filter designed specifically for that, with examples in the +documentation. This operation is recommended if you need to re-encode. +

+ +

3.14.2 Concatenating using the concat demuxer

+ +

FFmpeg has a concat demuxer which you can use when you want to avoid a re-encode and +your format doesn’t support file level concatenation. +

+ +

3.14.3 Concatenating using the concat protocol (file level)

+ +

FFmpeg has a concat protocol designed specifically for that, with examples in the +documentation. +

+

A few multimedia containers (MPEG-1, MPEG-2 PS, DV) allow one to concatenate +video by merely concatenating the files containing them. +

+

Hence you may concatenate your multimedia files by first transcoding them to +these privileged formats, then using the humble cat command (or the +equally humble copy under Windows), and finally transcoding back to your +format of choice. +

+
+
ffmpeg -i input1.avi -qscale:v 1 intermediate1.mpg
+ffmpeg -i input2.avi -qscale:v 1 intermediate2.mpg
+cat intermediate1.mpg intermediate2.mpg > intermediate_all.mpg
+ffmpeg -i intermediate_all.mpg -qscale:v 2 output.avi
+
+ +

Additionally, you can use the concat protocol instead of cat or +copy which will avoid creation of a potentially huge intermediate file. +

+
+
ffmpeg -i input1.avi -qscale:v 1 intermediate1.mpg
+ffmpeg -i input2.avi -qscale:v 1 intermediate2.mpg
+ffmpeg -i concat:"intermediate1.mpg|intermediate2.mpg" -c copy intermediate_all.mpg
+ffmpeg -i intermediate_all.mpg -qscale:v 2 output.avi
+
+ +

Note that you may need to escape the character "|" which is special for many +shells. +

+

Another option is usage of named pipes, should your platform support it: +

+
+
mkfifo intermediate1.mpg
+mkfifo intermediate2.mpg
+ffmpeg -i input1.avi -qscale:v 1 -y intermediate1.mpg < /dev/null &
+ffmpeg -i input2.avi -qscale:v 1 -y intermediate2.mpg < /dev/null &
+cat intermediate1.mpg intermediate2.mpg |\
+ffmpeg -f mpeg -i - -c:v mpeg4 -c:a libmp3lame output.avi
+
+ + +

3.14.4 Concatenating using raw audio and video

+ +

Similarly, the yuv4mpegpipe format, and the raw video, raw audio codecs also +allow concatenation, and the transcoding step is almost lossless. +When using multiple yuv4mpegpipe(s), the first line needs to be discarded +from all but the first stream. This can be accomplished by piping through +tail as seen below. Note that when piping through tail you +must use command grouping, { ;}, to background properly. +

+

For example, let’s say we want to concatenate two FLV files into an +output.flv file: +

+
+
mkfifo temp1.a
+mkfifo temp1.v
+mkfifo temp2.a
+mkfifo temp2.v
+mkfifo all.a
+mkfifo all.v
+ffmpeg -i input1.flv -vn -f u16le -c:a pcm_s16le -ac 2 -ar 44100 - > temp1.a < /dev/null &
+ffmpeg -i input2.flv -vn -f u16le -c:a pcm_s16le -ac 2 -ar 44100 - > temp2.a < /dev/null &
+ffmpeg -i input1.flv -an -f yuv4mpegpipe - > temp1.v < /dev/null &
+{ ffmpeg -i input2.flv -an -f yuv4mpegpipe - < /dev/null | tail -n +2 > temp2.v ; } &
+cat temp1.a temp2.a > all.a &
+cat temp1.v temp2.v > all.v &
+ffmpeg -f u16le -c:a pcm_s16le -ac 2 -ar 44100 -i all.a \
+       -f yuv4mpegpipe -i all.v \
+       -y output.flv
+rm temp[12].[av] all.[av]
+
+ + +

3.15 Using -f lavfi, audio becomes mono for no apparent reason.

+ +

Use -dumpgraph - to find out exactly where the channel layout is +lost. +

+

Most likely, it is through auto-inserted aresample. Try to understand +why the converting filter was needed at that place. +

+

Just before the output is a likely place, as -f lavfi currently +only support packed S16. +

+

Then insert the correct aformat explicitly in the filtergraph, +specifying the exact format. +

+
+
aformat=sample_fmts=s16:channel_layouts=stereo
+
+ + +

3.16 Why does FFmpeg not see the subtitles in my VOB file?

+ +

VOB and a few other formats do not have a global header that describes +everything present in the file. Instead, applications are supposed to scan +the file to see what it contains. Since VOB files are frequently large, only +the beginning is scanned. If the subtitles happen only later in the file, +they will not be initially detected. +

+

Some applications, including the ffmpeg command-line tool, can only +work with streams that were detected during the initial scan; streams that +are detected later are ignored. +

+

The size of the initial scan is controlled by two options: probesize +(default ~5 Mo) and analyzeduration (default 5,000,000 µs = 5 s). For +the subtitle stream to be detected, both values must be large enough. +

+ +

3.17 Why was the ffmpeg -sameq option removed? What to use instead?

+ +

The -sameq option meant "same quantizer", and made sense only in a +very limited set of cases. Unfortunately, a lot of people mistook it for +"same quality" and used it in places where it did not make sense: it had +roughly the expected visible effect, but achieved it in a very inefficient +way. +

+

Each encoder has its own set of options to set the quality-vs-size balance, +use the options for the encoder you are using to set the quality level to a +point acceptable for your tastes. The most common options to do that are +-qscale and -qmax, but you should peruse the documentation +of the encoder you chose. +

+ +

3.18 I have a stretched video, why does scaling not fix it?

+ +

A lot of video codecs and formats can store the aspect ratio of the +video: this is the ratio between the width and the height of either the full +image (DAR, display aspect ratio) or individual pixels (SAR, sample aspect +ratio). For example, EGA screens at resolution 640×350 had 4:3 DAR and 35:48 +SAR. +

+

Most still image processing work with square pixels, i.e. 1:1 SAR, but a lot +of video standards, especially from the analogic-numeric transition era, use +non-square pixels. +

+

Most processing filters in FFmpeg handle the aspect ratio to avoid +stretching the image: cropping adjusts the DAR to keep the SAR constant, +scaling adjusts the SAR to keep the DAR constant. +

+

If you want to stretch, or “unstretch”, the image, you need to override the +information with the +setdar or setsar filters. +

+

Do not forget to examine carefully the original video to check whether the +stretching comes from the image or from the aspect ratio information. +

+

For example, to fix a badly encoded EGA capture, use the following commands, +either the first one to upscale to square pixels or the second one to set +the correct aspect ratio or the third one to avoid transcoding (may not work +depending on the format / codec / player / phase of the moon): +

+
+
ffmpeg -i ega_screen.nut -vf scale=640:480,setsar=1 ega_screen_scaled.nut
+ffmpeg -i ega_screen.nut -vf setdar=4/3 ega_screen_anamorphic.nut
+ffmpeg -i ega_screen.nut -aspect 4/3 -c copy ega_screen_overridden.nut
+
+ + +

3.19 How do I run ffmpeg as a background task?

+ +

ffmpeg normally checks the console input, for entries like "q" to stop +and "?" to give help, while performing operations. ffmpeg does not have a way of +detecting when it is running as a background task. +When it checks the console input, that can cause the process running ffmpeg +in the background to suspend. +

+

To prevent those input checks, allowing ffmpeg to run as a background task, +use the -nostdin option +in the ffmpeg invocation. This is effective whether you run ffmpeg in a shell +or invoke ffmpeg in its own process via an operating system API. +

+

As an alternative, when you are running ffmpeg in a shell, you can redirect +standard input to /dev/null (on Linux and macOS) +or NUL (on Windows). You can do this redirect either +on the ffmpeg invocation, or from a shell script which calls ffmpeg. +

+

For example: +

+
+
ffmpeg -nostdin -i INPUT OUTPUT
+
+ +

or (on Linux, macOS, and other UNIX-like shells): +

+
+
ffmpeg -i INPUT OUTPUT </dev/null
+
+ +

or (on Windows): +

+
+
ffmpeg -i INPUT OUTPUT <NUL
+
+ + +

3.20 How do I prevent ffmpeg from suspending with a message like suspended (tty output)?

+ +

If you run ffmpeg in the background, you may find that its process suspends. +There may be a message like suspended (tty output). The question is how +to prevent the process from being suspended. +

+

For example: +

+
+
% ffmpeg -i INPUT OUTPUT &> ~/tmp/log.txt &
+[1] 93352
+%
+[1]  + suspended (tty output)  ffmpeg -i INPUT OUTPUT &>
+
+ +

The message "tty output" notwithstanding, the problem here is that +ffmpeg normally checks the console input when it runs. The operating system +detects this, and suspends the process until you can bring it to the +foreground and attend to it. +

+

The solution is to use the right techniques to tell ffmpeg not to consult +console input. You can use the +-nostdin option, +or redirect standard input with < /dev/null. +See FAQ +How do I run ffmpeg as a background task? +for details. +

+ +

4 Development

+ + +

4.1 Are there examples illustrating how to use the FFmpeg libraries, particularly libavcodec and libavformat?

+ +

Yes. Check the doc/examples directory in the source +repository, also available online at: +https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples. +

+

Examples are also installed by default, usually in +$PREFIX/share/ffmpeg/examples. +

+

Also you may read the Developers Guide of the FFmpeg documentation. Alternatively, +examine the source code for one of the many open source projects that +already incorporate FFmpeg at (projects.html). +

+ +

4.2 Can you support my C compiler XXX?

+ +

It depends. If your compiler is C99-compliant, then patches to support +it are likely to be welcome if they do not pollute the source code +with #ifdefs related to the compiler. +

+ +

4.3 Is Microsoft Visual C++ supported?

+ +

Yes. Please see the Microsoft Visual C++ +section in the FFmpeg documentation. +

+ +

4.4 Can you add automake, libtool or autoconf support?

+ +

No. These tools are too bloated and they complicate the build. +

+ +

4.5 Why not rewrite FFmpeg in object-oriented C++?

+ +

FFmpeg is already organized in a highly modular manner and does not need to +be rewritten in a formal object language. Further, many of the developers +favor straight C; it works for them. For more arguments on this matter, +read "Programming Religion". +

+ +

4.6 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. +

+ +

4.7 I do not like the LGPL, can I contribute code under the GPL instead?

+ +

Yes, as long as the code is optional and can easily and cleanly be placed +under #if CONFIG_GPL without breaking anything. So, for example, a new codec +or filter would be OK under GPL while a bug fix to LGPL code would not. +

+ +

4.8 I’m using FFmpeg from within my C application but the linker complains about missing symbols from the libraries themselves.

+ +

FFmpeg builds static libraries by default. In static libraries, dependencies +are not handled. That has two consequences. First, you must specify the +libraries in dependency order: -lavdevice must come before +-lavformat, -lavutil must come after everything else, etc. +Second, external libraries that are used in FFmpeg have to be specified too. +

+

An easy way to get the full list of required libraries in dependency order +is to use pkg-config. +

+
+
c99 -o program program.c $(pkg-config --cflags --libs libavformat libavcodec)
+
+ +

See doc/example/Makefile and doc/example/pc-uninstalled for +more details. +

+ +

4.9 I’m using FFmpeg from within my C++ application but the linker complains about missing symbols which seem to be available.

+ +

FFmpeg is a pure C project, so to use the libraries within your C++ application +you need to explicitly state that you are using a C library. You can do this by +encompassing your FFmpeg includes using extern "C". +

+

See http://www.parashift.com/c++-faq-lite/mixing-c-and-cpp.html#faq-32.3 +

+ +

4.10 I’m using libavutil from within my C++ application but the compiler complains about ’UINT64_C’ was not declared in this scope

+ +

FFmpeg is a pure C project using C99 math features, in order to enable C++ +to use them you have to append -D__STDC_CONSTANT_MACROS to your CXXFLAGS +

+ +

4.11 I have a file in memory / a API different from *open/*read/ libc how do I use it with libavformat?

+ +

You have to create a custom AVIOContext using avio_alloc_context, +see libavformat/aviobuf.c in FFmpeg and libmpdemux/demux_lavf.c in MPlayer or MPlayer2 sources. +

+ +

4.12 Where is the documentation about ffv1, msmpeg4, asv1, 4xm?

+ +

see https://www.ffmpeg.org/~michael/ +

+ +

4.13 How do I feed H.263-RTP (and other codecs in RTP) to libavcodec?

+ +

Even if peculiar since it is network oriented, RTP is a container like any +other. You have to demux RTP before feeding the payload to libavcodec. +In this specific case please look at RFC 4629 to see how it should be done. +

+ +

4.14 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 +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 (it is the least common multiple). +If you are looking for the average frame rate, see AVStream.avg_frame_rate. +

+ +

4.15 Why is make fate not running all tests?

+ +

Make sure you have the fate-suite samples and the SAMPLES Make variable +or FATE_SAMPLES environment variable or the --samples +configure option is set to the right path. +

+ +

4.16 Why is make fate not finding the samples?

+ +

Do you happen to have a ~ character in the samples path to indicate a +home directory? The value is used in ways where the shell cannot expand it, +causing FATE to not find files. Just replace ~ by the full path. +

+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/fate.html b/ffmpeg-n8.1/doc/fate.html new file mode 100644 index 00000000..0dfd6321 --- /dev/null +++ b/ffmpeg-n8.1/doc/fate.html @@ -0,0 +1,416 @@ + + + + + + + FFmpeg Automated Testing Environment + + + + + + +
+

+ FFmpeg Automated Testing Environment +

+ + + + + + + + +

1 Introduction

+ +

FATE is an extended regression suite on the client-side and a means +for results aggregation and presentation on the server-side. +

+

The first part of this document explains how you can use FATE from +your FFmpeg source directory to test your ffmpeg binary. The second +part describes how you can run FATE to submit the results to FFmpeg’s +FATE server. +

+

In any way you can have a look at the publicly viewable FATE results +by visiting this website: +

+

http://fate.ffmpeg.org/ +

+

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 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 +submit your results to FFmpeg’s FATE server. If you want to submit your +results be sure to check that your combination of CPU, OS and compiler +is not already listed on the above mentioned website. +

+

In the third part you can find a comprehensive listing of FATE makefile +targets and variables. +

+ + +

2 Using FATE from your FFmpeg source directory

+ +

If you want to run FATE on your machine, FFmpeg needs to be configured first. +You may specify the location of samples during configuration by adding the +argument --samples=/path/to/fate-suite. +

+
+
./configure --enable-somelib --samples=/path/to/fate-suite
+
+ +

After successful configuration, you need to add and/or update the samples in place: +

+
+
make fate-rsync
+
+ +

Now you are ready to run FATE: +

+
+
make fate
+
+ +

See makefile variables for a list of arguments that can be added. +

+

If you did not set the samples path during configuration, or if you wish to +override it just before starting FATE, you can do so in one of three ways. +

+

Either by setting a make variable: +

+
+
make fate-rsync SAMPLES=/path/to/fate-suite
+make fate       SAMPLES=/path/to/fate-suite
+
+ +

or by setting an environment variable for the current session: +

+
+
export FATE_SAMPLES=/path/to/fate-suite
+make fate-rsync
+make fate
+
+ +

or in isolation for a single command by prepending it: +

+
+
FATE_SAMPLES=/path/to/fate-suite make fate-rsync
+FATE_SAMPLES=/path/to/fate-suite make fate
+
+ +

This variable can also be set in your shell profile to make it permanent. +

+
+

Do not put a ’~’ character in the samples path to indicate a home +directory. Because of shell nuances, this will cause FATE to fail. +Also, on Windows the path has to be relative to the build path +which in this case is the FFmpeg source directory. +

+

Beware that some assertions are disabled by default, so mind setting +--assert-level=<level> at configuration time, e.g. when seeking +the highest possible test coverage: +

+
./configure --assert-level=2
+
+

Note that raising the assert level could have a performance impact. +

+

To get the complete list of tests, run the command: +

+
make fate-list
+
+ +

You can specify a subset of tests to run by specifying the +corresponding elements from the list with the fate- prefix, +e.g. as in: +

+
make fate-ffprobe_compact fate-ffprobe_xml
+
+ +

This makes it easier to run a few tests in case of failure without +running the complete test suite. +

+

To use a custom wrapper to run the test, pass --target-exec to +configure or set the TARGET_EXEC Make variable. +

+ + +

3 Submitting the results to the FFmpeg result aggregation server

+ +

To submit your results to the server you should run fate through the +shell script tests/fate.sh from the FFmpeg sources. This script needs +to be invoked with a configuration file as its first argument. +

+
+
tests/fate.sh /path/to/fate_config
+
+ +

A configuration file template with comments describing the individual +configuration variables can be found at doc/fate_config.sh.template. +

+

The mentioned configuration template is also available here: +

slot=                                    # some unique identifier
+repo=https://git.ffmpeg.org/ffmpeg.git   # the source repository
+#branch=release/2.6                       # the branch to test
+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
+skip_clean=     # set to "yes" to preserve build/install directories
+ignore_tests=
+
+# the following are optional and map to configure options
+arch=
+cpu=
+toolchain=
+cross_prefix=
+ar=
+as=
+cc=
+cxx=
+ld=
+nm=
+target_os=
+sysroot=
+target_exec=
+target_path=
+target_samples=
+extra_cflags=
+extra_cxxflags=
+extra_objcflags=
+extra_ldflags=
+extra_libs=
+extra_conf=     # extra configure options not covered above
+
+#make=          # name of GNU make if not 'make'
+makeopts=       # extra options passed to 'make'
+#makeopts_fate= # extra options passed to 'make' when running tests,
+                # defaulting to makeopts above if this is not set
+#tar=           # command to create a tar archive from its arguments on stdout,
+                # defaults to 'tar c'
+#fate_targets=  # targets to make when running fate; defaults to "fate",
+                # can be set to run a subset of tests, e.g. "fate-checkasm".
+
+#fate_environments=  # a list of names of configurations to run tests for;
+                     # each round is run with variables from ${${name}_env} set.
+
+# One example of using fate_environments:
+
+# target_exec="qemu-aarch64-static"
+# fate_targets="fate-checkasm fate-cpu"
+# fate_environments="sve128 sve256"
+# sve128_env="QEMU_CPU=max,sve128=on"
+# sve256_env="QEMU_CPU=max,sve256=on"
+
+# The variables set by fate_environments can also be used explicitly
+# by target_exec, e.g. like this:
+
+# target_exec="qemu-aarch64-static -cpu \$(MY_CPU)"
+# fate_targets="fate-checkasm fate-cpu"
+# fate_environments="sve128 sve256"
+# sve128_env="MY_CPU=max,sve128=on"
+# sve256_env="MY_CPU=max,sve256=on"
+
+

Create a configuration that suits your needs, based on the configuration +template. The slot configuration variable can be any string that is not +yet used, but it is suggested that you name it adhering to the following +pattern ‘arch-os-compiler-compiler version’. The +configuration file itself will be sourced in a shell script, therefore all +shell features may be used. This enables you to setup the environment as you +need it for your build. +

+

For your first test runs the fate_recv variable should be empty or +commented out. This will run everything as normal except that it will omit +the submission of the results to the server. The following files should be +present in $workdir as specified in the configuration file: +

+
    +
  • configure.log +
  • compile.log +
  • test.log +
  • report +
  • version +
+ +

When you have everything working properly you can create an SSH key pair +and send the public key to the FATE server administrator who can be contacted +at the email address . +

+

Configure your SSH client to use public key authentication with that key +when connecting to the FATE server. Also do not forget to check the identity +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: +

+
+
‘RSA’
+

d3:f1:83:97:a4:75:2b:a6:fb:d6:e8:aa:81:93:97:51 +

+
‘ECDSA’
+

76:9f:68:32:04:1e:d5:d4:ec:47:3f:dc:fc:18:17:86 +

+
+ +

If you have problems connecting to the FATE server, it may help to try out +the ssh command with one or more -v options. You should +get detailed output concerning your SSH configuration and the authentication +process. +

+

The only thing left is to automate the execution of the fate.sh script and +the synchronisation of the samples directory. +

+ +

4 Uploading new samples to the fate suite

+ +

If you need a sample uploaded send a mail to samples-request. +

+

This is for developers who have an account on the fate suite server. +If you upload new samples, please make sure they are as small as possible, +space on each client, network bandwidth and so on benefit from smaller test cases. +Also keep in mind older checkouts use existing sample files, that means in +practice generally do not replace, remove or overwrite files as it likely would +break older checkouts or releases. +Also all needed samples for a commit should be uploaded, ideally 24 +hours, before the push. +If you need an account for frequently uploading samples or you wish to help +others by doing that send a mail to ffmpeg-devel. +

+
+
#First update your local samples copy:
+rsync -vauL --chmod=Dg+s,Duo+x,ug+rw,o+r,o-w,+X fate-suite.ffmpeg.org:/home/samples/fate-suite/ ~/fate-suite
+
+#Then do a dry run checking what would be uploaded:
+rsync -vanL --no-g --chmod=Dg+s,Duo+x,ug+rw,o+r,o-w,+X ~/fate-suite/ fate-suite.ffmpeg.org:/home/samples/fate-suite
+
+#Upload the files:
+rsync -vaL  --no-g --chmod=Dg+s,Duo+x,ug+rw,o+r,o-w,+X ~/fate-suite/ fate-suite.ffmpeg.org:/home/samples/fate-suite
+
+ + + +

5 FATE makefile targets and variables

+ + +

5.1 Makefile targets

+ +
+
fate-rsync
+

Download/synchronize sample files to the configured samples directory. +

+
+
fate-list
+

Will list all fate/regression test targets. +

+
+
fate-list-failing
+

List the fate tests that failed the last time they were executed. +

+
+
fate-clear-reports
+

Remove the test reports from previous test executions (getting rid of +potentially stale results from fate-list-failing). +

+
+
fate
+

Run the FATE test suite (requires the fate-suite dataset). +

+
+ + +

5.2 Makefile variables

+ +
+
V
+

Verbosity level, can be set to 0, 1 or 2. +

    +
  • 0: show just the test arguments +
  • 1: show just the command used in the test +
  • 2: show everything +
+ +
+
SAMPLES
+

Specify or override the path to the FATE samples at make time, it has a +meaning only while running the regression tests. +

+
+
THREADS
+

Specify how many threads to use while running regression tests, it is +quite useful to detect thread-related regressions. +

+

This variable may be set to the string "random", optionally followed by a +number, like "random99", This will cause each test to use a random number of +threads. If a number is specified, it is used as a maximum number of threads, +otherwise 16 is the maximum. +

+

In case a test fails, the thread count used for it will be written into the +errfile. +

+
+
THREAD_TYPE
+

Specify which threading strategy test, either ‘slice’ or ‘frame’, +by default ‘slice+frame’ +

+
+
CPUFLAGS
+

Specify CPU flags. +

+
+
TARGET_EXEC
+

Specify or override the wrapper used to run the tests. +The TARGET_EXEC option provides a way to run FATE wrapped in +valgrind, qemu-user or wine or on remote targets +through ssh. +

+
+
GEN
+

Set to ‘1’ to generate the missing or mismatched references. +

+
+
HWACCEL
+

Specify which hardware acceleration to use while running regression tests, +by default ‘none’ is used. +

+
+
KEEP
+

Set to ‘1’ to keep temp files generated by fate test(s) when test is successful. +Default is ‘0’, which removes these files. Files are always kept when a test +fails. +

+
+
+ + +

5.3 Examples

+ +
+
make V=1 SAMPLES=/var/fate/samples THREADS=2 CPUFLAGS=mmx fate
+
+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-all.html b/ffmpeg-n8.1/doc/ffmpeg-all.html new file mode 100644 index 00000000..dd428a37 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-all.html @@ -0,0 +1,69054 @@ + + + + + + + ffmpeg Documentation + + + + + + +
+

+ ffmpeg Documentation +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 Synopsis

+ +

ffmpeg [global_options] {[input_file_options] -i input_url} ... {[output_file_options] output_url} ... +

+ +

2 Description

+ +

ffmpeg is a universal media converter. It can read a wide variety of +inputs - including live grabbing/recording devices - filter, and transcode them +into a plethora of output formats. +

+

ffmpeg reads from an arbitrary number of inputs (which can be regular +files, pipes, network streams, grabbing devices, etc.), specified by the +-i option, and writes to an arbitrary number of outputs, which are +specified by a plain output url. Anything found on the command line which cannot +be interpreted as an option is considered to be an output url. +

+

Each input or output can, in principle, contain any number of elementary streams +of different types (video/audio/subtitle/attachment/data), though the allowed +stream counts and/or types 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 -map option (see the Stream selection +chapter). +

+

To refer to inputs/outputs in options, you must use their indices (0-based). +E.g. the first input is 0, the second is 1, etc. Similarly, +streams within an input/output are referred to by their indices. E.g. 2:3 +refers to the fourth stream in the third input or output. 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 +option on the command line multiple times. Each occurrence is +then applied to the next input or output file. +Exceptions from this rule are the global options (e.g. verbosity level), +which should be specified first. +

+

Do not mix input and output files – first specify all input files, then all +output files. Also do not mix options which belong to different files. All +options apply ONLY to the next input or output file and are reset between files. +

+

Some simple examples follow. +

+
    +
  • Convert an input media file to a different format, by re-encoding media streams: +
    +
    ffmpeg -i input.avi output.mp4
    +
    + +
  • Set the video bitrate of the output file to 64 kbit/s: +
    +
    ffmpeg -i input.avi -b:v 64k -bufsize 64k output.mp4
    +
    + +
  • Force the frame rate of the output file to 24 fps: +
    +
    ffmpeg -i input.avi -r 24 output.mp4
    +
    + +
  • Force the frame rate of the input file (valid for raw formats only) to 1 fps and +the frame rate of the output file to 24 fps: +
    +
    ffmpeg -r 1 -i input.m2v -r 24 output.mp4
    +
    +
+ +

The format option may be needed for raw input files. +

+ + +

3 Detailed description

+ +

ffmpeg builds a transcoding pipeline out of the components listed +below. The program’s operation then consists of input data chunks flowing from +the sources down the pipes towards the sinks, while being transformed by the +components they encounter along the way. +

+

The following kinds of components are available: +

    +
  • Demuxers (short for "demultiplexers") read an input source in order to +extract + +
      +
    • global properties such as metadata or chapters; +
    • list of input elementary streams and their properties +
    + +

    One demuxer instance is created for each -i option, and sends encoded +packets to decoders or muxers. +

    +

    In other literature, demuxers are sometimes called splitters, because +their main function is splitting a file into elementary streams (though some +files only contain one elementary stream). +

    +

    A schematic representation of a demuxer looks like this: +

    ┌──────────┬───────────────────────┐
    +│ demuxer  │                       │ packets for stream 0
    +╞══════════╡ elementary stream 0   ├──────────────────────►
    +│          │                       │
    +│  global  ├───────────────────────┤
    +│properties│                       │ packets for stream 1
    +│   and    │ elementary stream 1   ├──────────────────────►
    +│ metadata │                       │
    +│          ├───────────────────────┤
    +│          │                       │
    +│          │     ...........       │
    +│          │                       │
    +│          ├───────────────────────┤
    +│          │                       │ packets for stream N
    +│          │ elementary stream N   ├──────────────────────►
    +│          │                       │
    +└──────────┴───────────────────────┘
    +     ▲
    +     │
    +     │ read from file, network stream,
    +     │     grabbing device, etc.
    +     │
    +
    +
  • Decoders receive encoded (compressed) packets for an audio, video, +or subtitle elementary stream, and decode them into raw frames (arrays of +pixels for video, PCM for audio). A decoder is typically associated with (and +receives its input from) an elementary stream in a demuxer, but sometimes +may also exist on its own (see Loopback decoders). + +

    A schematic representation of a decoder looks like this: +

              ┌─────────┐
    + packets  │         │ raw frames
    +─────────►│ decoder ├────────────►
    +          │         │
    +          └─────────┘
    +
    +
  • Filtergraphs process and transform raw audio or video frames. A +filtergraph consists of one or more individual filters linked into a +graph. Filtergraphs come in two flavors - simple and complex, +configured with the -filter and -filter_complex options, +respectively. + +

    A simple filtergraph is associated with an output elementary stream; it +receives the input to be filtered from a decoder and sends filtered +output to that output stream’s encoder. +

    +

    A simple video filtergraph that performs deinterlacing (using the yadif +deinterlacer) followed by resizing (using the scale filter) can look like +this: +

    +             ┌────────────────────────┐
    +             │  simple filtergraph    │
    + frames from ╞════════════════════════╡ frames for
    + a decoder   │  ┌───────┐  ┌───────┐  │ an encoder
    +────────────►├─►│ yadif ├─►│ scale ├─►│────────────►
    +             │  └───────┘  └───────┘  │
    +             └────────────────────────┘
    +
    +

    A complex filtergraph is standalone and not associated with any specific stream. +It may have multiple (or zero) inputs, potentially of different types (audio or +video), each of which receiving data either from a decoder or another complex +filtergraph’s output. It also has one or more outputs that feed either an +encoder or another complex filtergraph’s input. +

    +

    The following example diagram represents a complex filtergraph with 3 inputs and +2 outputs (all video): +

              ┌─────────────────────────────────────────────────┐
    +          │               complex filtergraph               │
    +          ╞═════════════════════════════════════════════════╡
    + frames   ├───────┐  ┌─────────┐      ┌─────────┐  ┌────────┤ frames
    +─────────►│input 0├─►│ overlay ├─────►│ overlay ├─►│output 0├────────►
    +          ├───────┘  │         │      │         │  └────────┤
    + frames   ├───────┐╭►│         │    ╭►│         │           │
    +─────────►│input 1├╯ └─────────┘    │ └─────────┘           │
    +          ├───────┘                 │                       │
    + frames   ├───────┐ ┌─────┐ ┌─────┬─╯              ┌────────┤ frames
    +─────────►│input 2├►│scale├►│split├───────────────►│output 1├────────►
    +          ├───────┘ └─────┘ └─────┘                └────────┤
    +          └─────────────────────────────────────────────────┘
    +

    Frames from second input are overlaid over those from the first. Frames from the +third input are rescaled, then the duplicated into two identical streams. One of +them is overlaid over the combined first two inputs, with the result exposed as +the filtergraph’s first output. The other duplicate ends up being the +filtergraph’s second output. +

    +
  • Encoders receive raw audio, video, or subtitle frames and encode +them into encoded packets. The encoding (compression) process is +typically lossy - it degrades stream quality to make the output smaller; +some encoders are lossless, but at the cost of much higher output size. A +video or audio encoder receives its input from some filtergraph’s output, +subtitle encoders receive input from a decoder (since subtitle filtering is not +supported yet). Every encoder is associated with some muxer’s output +elementary stream and sends its output to that muxer. + +

    A schematic representation of an encoder looks like this: +

                 ┌─────────┐
    + raw frames  │         │ packets
    +────────────►│ encoder ├─────────►
    +             │         │
    +             └─────────┘
    +
    +
  • Muxers (short for "multiplexers") receive encoded packets for +their elementary streams from encoders (the transcoding path) or directly +from demuxers (the streamcopy path), interleave them (when there is more +than one elementary stream), and write the resulting bytes into the output file +(or pipe, network stream, etc.). + +

    A schematic representation of a muxer looks like this: +

                           ┌──────────────────────┬───────────┐
    + packets for stream 0  │                      │   muxer   │
    +──────────────────────►│  elementary stream 0 ╞═══════════╡
    +                       │                      │           │
    +                       ├──────────────────────┤  global   │
    + packets for stream 1  │                      │properties │
    +──────────────────────►│  elementary stream 1 │   and     │
    +                       │                      │ metadata  │
    +                       ├──────────────────────┤           │
    +                       │                      │           │
    +                       │     ...........      │           │
    +                       │                      │           │
    +                       ├──────────────────────┤           │
    + packets for stream N  │                      │           │
    +──────────────────────►│  elementary stream N │           │
    +                       │                      │           │
    +                       └──────────────────────┴─────┬─────┘
    +                                                    │
    +                     write to file, network stream, │
    +                         grabbing device, etc.      │
    +                                                    │
    +                                                    ▼
    +
    +
+ + +

3.1 Streamcopy

+

The simplest pipeline in ffmpeg is single-stream +streamcopy, that is copying one input elementary stream’s packets +without decoding, filtering, or encoding them. As an example, consider an input +file called INPUT.mkv with 3 elementary streams, from which we take the +second and write it to file OUTPUT.mp4. A schematic representation of +such a pipeline looks like this: +

┌──────────┬─────────────────────┐
+│ demuxer  │                     │ unused
+╞══════════╡ elementary stream 0 ├────────╳
+│          │                     │
+│INPUT.mkv ├─────────────────────┤          ┌──────────────────────┬───────────┐
+│          │                     │ packets  │                      │   muxer   │
+│          │ elementary stream 1 ├─────────►│  elementary stream 0 ╞═══════════╡
+│          │                     │          │                      │OUTPUT.mp4 │
+│          ├─────────────────────┤          └──────────────────────┴───────────┘
+│          │                     │ unused
+│          │ elementary stream 2 ├────────╳
+│          │                     │
+└──────────┴─────────────────────┘
+
+

The above pipeline can be constructed with the following commandline: +

+
ffmpeg -i INPUT.mkv -map 0:1 -c copy OUTPUT.mp4
+
+ +

In this commandline +

    +
  • there is a single input INPUT.mkv; + +
  • there are no input options for this input; + +
  • there is a single output OUTPUT.mp4; + +
  • there are two output options for this output: + +
      +
    • -map 0:1 selects the input stream to be used - from input with index 0 +(i.e. the first one) the stream with index 1 (i.e. the second one); + +
    • -c copy selects the copy encoder, i.e. streamcopy with no decoding +or encoding. +
    + +
+ +

Streamcopy is useful for changing the elementary stream count, container format, +or modifying container-level metadata. 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 a variety of factors (e.g. certain information required by the +target container is not available in the source). Applying filters is obviously +also impossible, since filters work on decoded frames. +

+

More complex streamcopy scenarios can be constructed - e.g. combining streams +from two input files into a single output: +

┌──────────┬────────────────────┐         ┌────────────────────┬───────────┐
+│ demuxer 0│                    │ packets │                    │   muxer   │
+╞══════════╡elementary stream 0 ├────────►│elementary stream 0 ╞═══════════╡
+│INPUT0.mkv│                    │         │                    │OUTPUT.mp4 │
+└──────────┴────────────────────┘         ├────────────────────┤           │
+┌──────────┬────────────────────┐         │                    │           │
+│ demuxer 1│                    │ packets │elementary stream 1 │           │
+╞══════════╡elementary stream 0 ├────────►│                    │           │
+│INPUT1.aac│                    │         └────────────────────┴───────────┘
+└──────────┴────────────────────┘
+

that can be built by the commandline +

+
ffmpeg -i INPUT0.mkv -i INPUT1.aac -map 0:0 -map 1:0 -c copy OUTPUT.mp4
+
+ +

The output -map option is used twice here, creating two streams in the +output file - one fed by the first input and one by the second. The single +instance of the -c option selects streamcopy for both of those streams. +You could also use multiple instances of this option together with +Stream specifiers to apply different values to each stream, as will be +demonstrated in following sections. +

+

A converse scenario is splitting multiple streams from a single input into +multiple outputs: +

┌──────────┬─────────────────────┐          ┌───────────────────┬───────────┐
+│ demuxer  │                     │ packets  │                   │ muxer 0   │
+╞══════════╡ elementary stream 0 ├─────────►│elementary stream 0╞═══════════╡
+│          │                     │          │                   │OUTPUT0.mp4│
+│INPUT.mkv ├─────────────────────┤          └───────────────────┴───────────┘
+│          │                     │ packets  ┌───────────────────┬───────────┐
+│          │ elementary stream 1 ├─────────►│                   │ muxer 1   │
+│          │                     │          │elementary stream 0╞═══════════╡
+└──────────┴─────────────────────┘          │                   │OUTPUT1.mp4│
+                                            └───────────────────┴───────────┘
+

built with +

+
ffmpeg -i INPUT.mkv -map 0:0 -c copy OUTPUT0.mp4 -map 0:1 -c copy OUTPUT1.mp4
+
+

Note how a separate instance of the -c option is needed for every +output file even though their values are the same. This is because non-global +options (which is most of them) only apply in the context of the file before +which they are placed. +

+

These examples can of course be further generalized into arbitrary remappings +of any number of inputs into any number of outputs. +

+ +

3.2 Transcoding

+

Transcoding is the process of decoding a stream and then encoding it +again. Since encoding tends to be computationally expensive and in most cases +degrades the stream quality (i.e. it is lossy), you should only transcode +when you need to and perform streamcopy otherwise. Typical reasons to transcode +are: +

+
    +
  • applying filters - e.g. resizing, deinterlacing, or overlaying video; resampling +or mixing audio; + +
  • you want to feed the stream to something that cannot decode the original codec. +
+

Note that ffmpeg will transcode all audio, video, and subtitle streams +unless you specify -c copy for them. +

+

Consider an example pipeline that reads an input file with one audio and one +video stream, transcodes the video and copies the audio into a single output +file. This can be schematically represented as follows +

┌──────────┬─────────────────────┐
+│ demuxer  │                     │       audio packets
+╞══════════╡ stream 0 (audio)    ├─────────────────────────────────────╮
+│          │                     │                                     │
+│INPUT.mkv ├─────────────────────┤ video    ┌─────────┐     raw        │
+│          │                     │ packets  │  video  │ video frames   │
+│          │ stream 1 (video)    ├─────────►│ decoder ├──────────────╮ │
+│          │                     │          │         │              │ │
+└──────────┴─────────────────────┘          └─────────┘              │ │
+                                                                     ▼ ▼
+                                                                     │ │
+┌──────────┬─────────────────────┐ video    ┌─────────┐              │ │
+│ muxer    │                     │ packets  │  video  │              │ │
+╞══════════╡ stream 0 (video)    │◄─────────┤ encoder ├──────────────╯ │
+│          │                     │          │(libx264)│                │
+│OUTPUT.mp4├─────────────────────┤          └─────────┘                │
+│          │                     │                                     │
+│          │ stream 1 (audio)    │◄────────────────────────────────────╯
+│          │                     │
+└──────────┴─────────────────────┘
+

and implemented with the following commandline: +

+
ffmpeg -i INPUT.mkv -map 0:v -map 0:a -c:v libx264 -c:a copy OUTPUT.mp4
+
+

Note how it uses stream specifiers :v and :a to select input +streams and apply different values of the -c option to them; see the +Stream specifiers section for more details. +

+ + +

3.3 Filtering

+ +

When transcoding, audio and video streams can be filtered before encoding, with +either a simple or complex filtergraph. +

+ +

3.3.1 Simple filtergraphs

+ +

Simple filtergraphs are those that have exactly one input and output, both of +the same type (audio or video). They are configured with the per-stream +-filter option (with -vf and -af aliases for +-filter:v (video) and -filter:a (audio) respectively). Note +that simple filtergraphs are tied to their output stream, so e.g. if you have +multiple audio streams, -af will create a separate filtergraph for each +one. +

+

Taking the transcoding example from above, adding filtering (and omitting audio, +for clarity) makes it look like this: +

┌──────────┬───────────────┐
+│ demuxer  │               │          ┌─────────┐
+╞══════════╡ video stream  │ packets  │  video  │ frames
+│INPUT.mkv │               ├─────────►│ decoder ├─────►───╮
+│          │               │          └─────────┘         │
+└──────────┴───────────────┘                              │
+                                  ╭───────────◄───────────╯
+                                  │   ┌────────────────────────┐
+                                  │   │  simple filtergraph    │
+                                  │   ╞════════════════════════╡
+                                  │   │  ┌───────┐  ┌───────┐  │
+                                  ╰──►├─►│ yadif ├─►│ scale ├─►├╮
+                                      │  └───────┘  └───────┘  ││
+                                      └────────────────────────┘│
+                                                                │
+                                                                │
+┌──────────┬───────────────┐ video    ┌─────────┐               │
+│ muxer    │               │ packets  │  video  │               │
+╞══════════╡ video stream  │◄─────────┤ encoder ├───────◄───────╯
+│OUTPUT.mp4│               │          │         │
+│          │               │          └─────────┘
+└──────────┴───────────────┘
+
+ +

3.3.2 Complex filtergraphs

+ +

Complex filtergraphs are those which cannot be described as simply a linear +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. Complex filtergraphs are configured with the +-filter_complex option. Note that this option is global, since a +complex filtergraph, by its nature, cannot be unambiguously associated with a +single stream or file. Each instance of -filter_complex creates a new +complex filtergraph, and there can be any number of them. +

+

A trivial example of a complex filtergraph is the overlay filter, which +has two video inputs and one video output, containing one video overlaid on top +of the other. Its audio counterpart is the amix filter. +

+ +

3.4 Loopback decoders

+

While decoders are normally associated with demuxer streams, it is also possible +to create "loopback" decoders that decode the output from some encoder and allow +it to be fed back to complex filtergraphs. This is done with the -dec +directive, which takes as a parameter the index of the output stream that should +be decoded. Every such directive creates a new loopback decoder, indexed with +successive integers starting at zero. These indices should then be used to refer +to loopback decoders in complex filtergraph link labels, as described in the +documentation for -filter_complex. +

+

Decoding AVOptions can be passed to loopback decoders by placing them before +-dec, analogously to input/output options. +

+

E.g. the following example: +

+
+
ffmpeg -i INPUT                                        \
+  -map 0:v:0 -c:v libx264 -crf 45 -f null -            \
+  -threads 3 -dec 0:0                                  \
+  -filter_complex '[0:v][dec:0]hstack[stack]'          \
+  -map '[stack]' -c:v ffv1 OUTPUT
+
+ +

reads an input video and +

    +
  • (line 2) encodes it with libx264 at low quality; + +
  • (line 3) decodes this encoded stream using 3 threads; + +
  • (line 4) places decoded video side by side with the original input video; + +
  • (line 5) combined video is then losslessly encoded and written into +OUTPUT. + +
+ +

Such a transcoding pipeline can be represented with the following diagram: +

┌──────────┬───────────────┐
+│ demuxer  │               │   ┌─────────┐            ┌─────────┐    ┌────────────────────┐
+╞══════════╡ video stream  │   │  video  │            │  video  │    │ null muxer         │
+│   INPUT  │               ├──►│ decoder ├──┬────────►│ encoder ├─┬─►│(discards its input)│
+│          │               │   └─────────┘  │         │(libx264)│ │  └────────────────────┘
+└──────────┴───────────────┘                │         └─────────┘ │
+                                 ╭───────◄──╯   ┌─────────┐       │
+                                 │              │loopback │       │
+                                 │ ╭─────◄──────┤ decoder ├────◄──╯
+                                 │ │            └─────────┘
+                                 │ │
+                                 │ │
+                                 │ │  ┌───────────────────┐
+                                 │ │  │complex filtergraph│
+                                 │ │  ╞═══════════════════╡
+                                 │ │  │  ┌─────────────┐  │
+                                 ╰─╫─►├─►│   hstack    ├─►├╮
+                                   ╰─►├─►│             │  ││
+                                      │  └─────────────┘  ││
+                                      └───────────────────┘│
+                                                           │
+┌──────────┬───────────────┐  ┌─────────┐                  │
+│ muxer    │               │  │  video  │                  │
+╞══════════╡ video stream  │◄─┤ encoder ├───────◄──────────╯
+│  OUTPUT  │               │  │ (ffv1)  │
+│          │               │  └─────────┘
+└──────────┴───────────────┘
+
+ + + +

4 Stream selection

+ +

ffmpeg provides the -map option for manual control of stream selection in each +output file. Users can skip -map and let ffmpeg perform automatic stream selection as +described below. The -vn / -an / -sn / -dn options can be used to skip inclusion of +video, audio, subtitle and data streams respectively, whether manually mapped or automatically +selected, except for those streams which are outputs of complex filtergraphs. +

+ +

4.1 Description

+

The sub-sections that follow describe the various rules that are involved in stream selection. +The examples that follow next show how these rules are applied in practice. +

+

While every effort is made to accurately reflect the behavior of the program, FFmpeg is under +continuous development and the code may have changed since the time of this writing. +

+ +

4.1.1 Automatic stream selection

+ +

In the absence of any map options for a particular output file, ffmpeg inspects the output +format to check which type of streams can be included in it, viz. video, audio and/or +subtitles. For each acceptable stream type, ffmpeg will pick one stream, when available, +from among all the inputs. +

+

It will select that stream 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 found but there’s a caveat. +The output format’s default subtitle encoder can be either text-based or image-based, +and only a subtitle stream of the same type will be chosen. +
+ +

In the case where several streams of the same type rate equally, the stream with the lowest +index is chosen. +

+

Data or attachment streams are not automatically selected and can only be included +using -map. +

+

4.1.2 Manual stream selection

+ +

When -map is used, only user-mapped streams are included in that output file, +with one possible exception for filtergraph outputs described below. +

+ +

4.1.3 Complex filtergraphs

+ +

If there are any complex filtergraph output streams with unlabeled pads, they will be added +to the first output file. This will lead to a fatal error if the stream type is not supported +by the output format. In the absence of the map option, the inclusion of these streams leads +to the automatic stream selection of their types being skipped. If map options are present, +these filtergraph streams are included in addition to the mapped streams. +

+

Complex filtergraph output streams with labeled pads must be mapped once and exactly once. +

+ +

4.1.4 Stream handling

+ +

Stream handling is independent of stream selection, with an exception for subtitles described +below. Stream handling is set via the -codec option addressed to streams within a +specific output file. In particular, codec options are applied by ffmpeg after the +stream selection process and thus do not influence the latter. If no -codec option is +specified for a stream type, ffmpeg will select the default encoder registered by the output +file muxer. +

+

An exception exists for subtitles. If a subtitle encoder is specified for an output file, the +first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate +if the specified encoder can convert the selected stream or if the converted stream is acceptable +within the output format. This applies generally as well: when the user sets an encoder manually, +the stream selection process cannot check if the encoded stream can be muxed into the output file. +If it cannot, ffmpeg will abort and all output files will fail to be processed. +

+ +

4.2 Examples

+ +

The following examples illustrate the behavior, quirks and limitations of ffmpeg’s stream +selection methods. +

+

They assume the following three input files. +

+
+input file 'A.avi'
+      stream 0: video 640x360
+      stream 1: audio 2 channels
+
+input file 'B.mp4'
+      stream 0: video 1920x1080
+      stream 1: audio 2 channels
+      stream 2: subtitles (text)
+      stream 3: audio 5.1 channels
+      stream 4: subtitles (text)
+
+input file 'C.mkv'
+      stream 0: video 1280x720
+      stream 1: audio 2 channels
+      stream 2: subtitles (image)
+
+ +
+
ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
+
+

There are three output files specified, and for the first two, no -map options +are set, so ffmpeg will select streams for these two files automatically. +

+

out1.mkv is a Matroska container file and accepts video, audio and subtitle streams, +so ffmpeg will try to select one of each type.
+For video, it will select stream 0 from B.mp4, which has the highest +resolution among all the input video streams.
+For audio, it will select stream 3 from B.mp4, since it has the greatest +number of channels.
+For subtitles, it will select stream 2 from B.mp4, which is the first subtitle +stream from among A.avi and B.mp4. +

+

out2.wav accepts only audio streams, so only stream 3 from B.mp4 is +selected. +

+

For out3.mov, since a -map option is set, no automatic stream selection will +occur. The -map 1:a option will select all audio streams from the second input +B.mp4. No other streams will be included in this output file. +

+

For the first two outputs, all included streams will be transcoded. The encoders chosen will +be the default ones registered by each output format, which may not match the codec of the +selected input streams. +

+

For the third output, codec option for audio streams has been set +to copy, so no decoding-filtering-encoding operations will occur, or can occur. +Packets of selected streams shall be conveyed from the input file and muxed within the output +file. +

+ +
+
ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
+
+

Although out1.mkv is a Matroska container file which accepts subtitle streams, only a +video and audio stream shall be selected. The subtitle stream of C.mkv is image-based +and the default subtitle encoder of the Matroska muxer is text-based, so a transcode operation +for the subtitles is expected to fail and hence the stream isn’t selected. However, in +out2.mkv, a subtitle encoder is specified in the command and so, the subtitle stream is +selected, in addition to the video stream. The presence of -an disables audio stream +selection for out2.mkv. +

+ +
+
ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
+
+

A filtergraph is setup here using the -filter_complex option and consists of a single +video filter. The overlay filter requires exactly two video inputs, but none are +specified, so the first two available video streams are used, those of A.avi and +C.mkv. The output pad of the filter has no label and so is sent to the first output file +out1.mp4. Due to this, automatic selection of the video stream is skipped, which would +have selected the stream in B.mp4. The audio stream with most channels viz. stream 3 +in B.mp4, is chosen automatically. No subtitle stream is chosen however, since the MP4 +format has no default subtitle encoder registered, and the user hasn’t specified a subtitle encoder. +

+

The 2nd output file, out2.srt, only accepts text-based subtitle streams. So, even though +the first subtitle stream available belongs to C.mkv, it is image-based and hence skipped. +The selected stream, stream 2 in B.mp4, is the first text-based subtitle stream. +

+ +
+
ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+       -map '[outv]' -an        out1.mp4 \
+                                out2.mkv \
+       -map '[outv]' -map 1:a:0 out3.mkv
+
+ +

The above command will fail, as the output pad labelled [outv] has been mapped twice. +None of the output files shall be processed. +

+
+
ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+       -an        out1.mp4 \
+                  out2.mkv \
+       -map 1:a:0 out3.mkv
+
+ +

This command above will also fail as the hue filter output has a label, [outv], +and hasn’t been mapped anywhere. +

+

The command should be modified as follows, +

+
ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
+        -map '[outv1]' -an        out1.mp4 \
+                                  out2.mkv \
+        -map '[outv2]' -map 1:a:0 out3.mkv
+
+

The video stream from B.mp4 is sent to the hue filter, whose output is cloned once using +the split filter, and both outputs labelled. Then a copy each is mapped to the first and third +output files. +

+

The overlay filter, requiring two video inputs, uses the first two unused video streams. Those +are the streams from A.avi and C.mkv. The overlay output isn’t labelled, so it is +sent to the first output file out1.mp4, regardless of the presence of the -map option. +

+

The aresample filter is sent the first unused audio stream, that of A.avi. Since this filter +output is also unlabelled, it too is mapped to the first output file. The presence of -an +only suppresses automatic or manual stream selection of audio streams, not outputs sent from +filtergraphs. Both these mapped streams shall be ordered before the mapped stream in out1.mp4. +

+

The video, audio and subtitle streams mapped to out2.mkv are entirely determined by +automatic stream selection. +

+

out3.mkv consists of the cloned video output from the hue filter and the first audio +stream from B.mp4. +
+

+ + +

5 Options

+ +

All the numerical options, if not specified otherwise, accept a string +representing a number as input, which may be followed by one of the SI +unit prefixes, for example: ’K’, ’M’, or ’G’. +

+

If ’i’ is appended to the SI unit prefix, the complete prefix will be +interpreted as a unit prefix for binary multiples, which are based on +powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit +prefix multiplies the value by 8. This allows using, for example: +’KB’, ’MiB’, ’G’ and ’B’ as number suffixes. +

+

Options which do not take arguments are boolean options, and set the +corresponding value to true. They can be set to false by prefixing +the option name with "no". For example using "-nofoo" +will set the boolean option with name "foo" to false. +

+

Options that take arguments support a special syntax where the argument given on +the command line is interpreted as a path to the file from which the actual +argument value is loaded. To use this feature, add a forward slash ’/’ +immediately before the option name (after the leading dash). E.g. +

+
ffmpeg -i INPUT -/filter:v filter.script OUTPUT
+
+

will load a filtergraph description from the file named filter.script. +

+ +

5.1 Stream specifiers

+

Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers +are used to precisely specify which stream(s) a given option belongs to. +

+

A stream specifier is a string generally appended to the option name and +separated from it by a colon. E.g. -codec:a:1 ac3 contains the +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, so that the option is applied to all +of them. E.g. the stream specifier in -b:a 128k matches all audio +streams. +

+

An empty stream specifier matches all streams. For example, -codec copy +or -codec: copy would copy all the streams without reencoding. +

+

Possible forms of stream specifiers are: +

+
stream_index
+

Matches the stream with this index. E.g. -threads:1 4 would set the +thread count for the second stream to 4. If stream_index is used as an +additional stream specifier (see below), then it selects stream number +stream_index from the matching streams. Stream numbering is based on the +order of the streams as detected by libavformat except when a stream group +specifier or program ID is also specified. In this case it is based on the +ordering of the streams in the group or program. +

+
stream_type[:additional_stream_specifier]
+

stream_type is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’ +for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video +streams, ’V’ only matches video streams which are not attached pictures, video +thumbnails or cover arts. If additional_stream_specifier is used, then +it matches streams which both have this type and match the +additional_stream_specifier. Otherwise, it matches all streams of the +specified type. +

+
g:group_specifier[:additional_stream_specifier]
+

Matches streams which are in the group with the specifier group_specifier. +if additional_stream_specifier is used, then it matches streams which both +are part of the group and match the additional_stream_specifier. +group_specifier may be one of the following: +

+
group_index
+

Match the stream with this group index. +

+
#group_id or i:group_id
+

Match the stream with this group id. +

+
+
+
p:program_id[:additional_stream_specifier]
+

Matches streams which are in the program with the id program_id. If +additional_stream_specifier is used, then it matches streams which both +are part of the program and match the additional_stream_specifier. +

+
+
#stream_id or i:stream_id
+

Match the stream by stream id (e.g. PID in MPEG-TS container). +

+
m:key[:value]
+

Matches streams with the metadata tag key having the specified value. If +value is not given, matches streams that contain the given tag with any +value. The colon character ’:’ in key or value needs to be +backslash-escaped. +

+
disp:dispositions[:additional_stream_specifier]
+

Matches streams with the given disposition(s). dispositions is a list of +one or more dispositions (as printed by the -dispositions option) +joined with ’+’. +

+
u
+

Matches streams with usable configuration, the codec must be defined and the +essential information such as video dimension or audio sample rate must be present. +

+

Note that in ffmpeg, matching by metadata will only work properly for +input files. +

+
+ + +

5.2 Generic options

+ +

These options are shared amongst the ff* tools. +

+
+
-L, -license
+

Show license. +

+
+
-h, -?, -help, --help [arg]
+

Show help. An optional parameter may be specified to print help about a specific +item. If no argument is specified, only basic (non advanced) tool +options are shown. +

+

Possible values of arg are: +

+
long
+

Print advanced tool options in addition to the basic tool options. +

+
+
full
+

Print complete list of options, including shared and private options +for encoders, decoders, demuxers, muxers, filters, etc. +

+
+
decoder=decoder_name
+

Print detailed information about the decoder named decoder_name. Use the +-decoders option to get a list of all decoders. +

+
+
encoder=encoder_name
+

Print detailed information about the encoder named encoder_name. Use the +-encoders option to get a list of all encoders. +

+
+
demuxer=demuxer_name
+

Print detailed information about the demuxer named demuxer_name. Use the +-formats option to get a list of all demuxers and muxers. +

+
+
muxer=muxer_name
+

Print detailed information about the muxer named muxer_name. Use the +-formats option to get a list of all muxers and demuxers. +

+
+
filter=filter_name
+

Print detailed information about the filter named filter_name. Use the +-filters option to get a list of all filters. +

+
+
bsf=bitstream_filter_name
+

Print detailed information about the bitstream filter named bitstream_filter_name. +Use the -bsfs option to get a list of all bitstream filters. +

+
+
protocol=protocol_name
+

Print detailed information about the protocol named protocol_name. +Use the -protocols option to get a list of all protocols. +

+
+ +
+
-version
+

Show version. +

+
+
-buildconf
+

Show the build configuration, one option per line. +

+
+
-formats
+

Show available formats (including devices). +

+
+
-demuxers
+

Show available demuxers. +

+
+
-muxers
+

Show available muxers. +

+
+
-devices
+

Show available devices. +

+
+
-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. +

+
+
-decoders
+

Show available decoders. +

+
+
-encoders
+

Show all available encoders. +

+
+
-bsfs
+

Show available bitstream filters. +

+
+
-protocols
+

Show available protocols. +

+
+
-filters
+

Show available libavfilter filters. +

+
+
-pix_fmts
+

Show available pixel formats. +

+
+
-sample_fmts
+

Show available sample formats. +

+
+
-layouts
+

Show channel names and standard channel layouts. +

+
+
-dispositions
+

Show stream dispositions. +

+
+
-colors
+

Show recognized color names. +

+
+
-sources device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sources of the input device. +Some devices may provide system-dependent source names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sources pulse,server=192.168.0.4
+
+ +
+
-sinks device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sinks of the output device. +Some devices may provide system-dependent sink names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sinks pulse,server=192.168.0.4
+
+ +
+
-loglevel [flags+]loglevel | -v [flags+]loglevel
+

Set logging level and flags used by the library. +

+

The optional flags prefix can consist of the following values: +

+
‘repeat’
+

Indicates that repeated log output should not be compressed to the first line +and the "Last message repeated n times" line will be omitted. +

+
‘level’
+

Indicates that log output should add a [level] prefix to each message +line. This can be used as an alternative to log coloring, e.g. when dumping the +log to file. +

+
‘time’
+

Indicates that log lines should be prefixed with time information. +

+
‘datetime’
+

Indicates that log lines should be prefixed with date and time information. +

+
+

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single +flag without affecting other flags or changing loglevel. When +setting both flags and loglevel, a ’+’ separator is expected +between the last flags value and before loglevel. +

+

loglevel is a string or a number containing one of the following values: +

+
‘quiet, -8’
+

Show nothing at all; be silent. +

+
‘panic, 0’
+

Only show fatal errors which could lead the process to crash, such as +an assertion failure. This is not currently used for anything. +

+
‘fatal, 8’
+

Only show fatal errors. These are errors after which the process absolutely +cannot continue. +

+
‘error, 16’
+

Show all errors, including ones which can be recovered from. +

+
‘warning, 24’
+

Show all warnings and errors. Any message related to possibly +incorrect or unexpected events will be shown. +

+
‘info, 32’
+

Show informative messages during processing. This is in addition to +warnings and errors. This is the default value. +

+
‘verbose, 40’
+

Same as info, except more verbose. +

+
‘debug, 48’
+

Show everything, including debugging information. +

+
‘trace, 56’
+
+ +

For example to enable repeated log output, add the level prefix, and set +loglevel to verbose: +

+
ffmpeg -loglevel repeat+level+verbose -i input output
+
+

Another example that enables repeated log output without affecting current +state of level prefix flag or loglevel: +

+
ffmpeg [...] -loglevel +repeat
+
+ +

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 +AV_LOG_FORCE_NOCOLOR, or can be forced setting +the environment variable AV_LOG_FORCE_COLOR. +

+
+
-report
+

Dump full command line and log output to a file named +program-YYYYMMDD-HHMMSS.log in the current +directory. +This file can be useful for bug reports. +It also implies -loglevel debug. +

+

Setting the environment variable FFREPORT to any value has the +same effect. If the value is a ’:’-separated key=value sequence, these +options will affect the report; option 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 options are recognized: +

+
file
+

set the file name to use for the report; %p is expanded to the name +of the program, %t is expanded to a timestamp, %% is expanded +to a plain % +

+
level
+

set the log verbosity level using a numerical value (see -loglevel). +

+
+ +

For example, to output a report to a file named ffreport.log +using a log level of 32 (alias for log level info): +

+
+
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+ +

Errors in parsing the environment variable are not fatal, and will not +appear in the report. +

+
+
-hide_banner
+

Suppress printing banner. +

+

All FFmpeg tools will normally show a copyright notice, build options +and library versions. This option can be used to suppress printing +this information. +

+
+
-cpuflags flags (global)
+

Allows setting and clearing cpu flags. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpuflags -sse+mmx ...
+ffmpeg -cpuflags mmx ...
+ffmpeg -cpuflags 0 ...
+
+

Possible flags for this option are: +

+
‘x86’
+
+
‘mmx’
+
‘mmxext’
+
‘sse’
+
‘sse2’
+
‘sse2slow’
+
‘sse3’
+
‘sse3slow’
+
‘ssse3’
+
‘atom’
+
‘sse4.1’
+
‘sse4.2’
+
‘avx’
+
‘avx2’
+
‘xop’
+
‘fma3’
+
‘fma4’
+
‘3dnow’
+
‘3dnowext’
+
‘bmi1’
+
‘bmi2’
+
‘cmov’
+
+
+
‘ARM’
+
+
‘armv5te’
+
‘armv6’
+
‘armv6t2’
+
‘vfp’
+
‘vfpv3’
+
‘neon’
+
‘setend’
+
+
+
‘AArch64’
+
+
‘armv8’
+
‘vfp’
+
‘neon’
+
+
+
‘PowerPC’
+
+
‘altivec’
+
+
+
‘Specific Processors’
+
+
‘pentium2’
+
‘pentium3’
+
‘pentium4’
+
‘k6’
+
‘k62’
+
‘athlon’
+
‘athlonxp’
+
‘k8’
+
+
+
+ +
+
-cpucount count (global)
+

Override detection of CPU count. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpucount 2
+
+ +
+
-max_alloc bytes
+

Set the maximum size limit for allocating a block on the heap by ffmpeg’s +family of malloc functions. Exercise extreme caution when using +this option. Don’t use if you do not understand the full consequence of doing so. +Default is INT_MAX. +

+
+ + +

5.3 AVOptions

+ +

These options are provided directly by the libavformat, libavdevice and +libavcodec libraries. To see the list of available AVOptions, use the +-help option. They are separated into two categories: +

+
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. +

+
private
+

These options are specific to the given container, device or codec. Private +options are listed under their corresponding containers/devices/codecs. +

+
+ +

For example to write an ID3v2.3 header instead of a default ID3v2.4 to +an MP3 file, use the id3v2_version private option of the MP3 +muxer: +

+
ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+ +

All codec AVOptions are per-stream, and thus a stream specifier +should be attached to them: +

+
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+ +

In the above example, a multichannel audio stream is mapped twice for output. +The first instance is encoded with codec ac3 and bitrate 640k. +The second instance is downmixed to 2 channels and encoded with codec aac. A bitrate of 128k is specified for it using +absolute index of the output stream. +

+

Note: the -nooption syntax cannot be used for boolean +AVOptions, use -option 0/-option 1. +

+

Note: the 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. +

+ +

5.4 Main options

+ +
+
-f fmt (input/output)
+

Force input or output file format. The format is normally auto detected for input +files and guessed from the file extension for output files, so this option is not +needed in most cases. +

+
+
-i url (input)
+

input file url +

+
+
-y (global)
+

Overwrite output files without asking. +

+
+
-n (global)
+

Do not overwrite output files, and exit immediately if a specified +output file already exists. +

+
+
-stream_loop number (input)
+

Set number of times input stream shall be looped. Loop 0 means no loop, +loop -1 means infinite loop. +

+
+
-recast_media (global)
+

Allow forcing a decoder of a different media type than the one +detected or designated by the demuxer. Useful for decoding media +data muxed as data streams. +

+
+
-c[:stream_specifier] codec (input/output,per-stream)
+
-codec[:stream_specifier] codec (input/output,per-stream)
+

Select an encoder (when used before an output file) or a decoder (when used +before an input file) for one or more streams. codec is the name of a +decoder/encoder or a special value copy (output only) to indicate that +the stream is not to be re-encoded. +

+

For example +

+
ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+
+

encodes all video streams with libx264 and copies all audio streams. +

+

For each stream, the last matching c option is applied, so +

+
ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+
+

will copy all the streams except the second video, which will be encoded with +libx264, and the 138th audio, which will be encoded with libvorbis. +

+
+
-t duration (input/output)
+

When used as an input option (before -i), limit the duration of +data read from the input file. +

+

When used as an output option (before an output url), stop writing the +output after its duration reaches duration. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

-to and -t are mutually exclusive and -t has priority. +

+
+
-to position (input/output)
+

Stop writing the output or reading the input at position. +position must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

-to and -t are mutually exclusive and -t has priority. +

+
+
-fs limit_size (output)
+

Set the file size limit, expressed in bytes. No further chunk of bytes is written +after the limit is exceeded. The size of the output file is slightly more than the +requested file size. +

+
+
-ss position (input/output)
+

When used as an input option (before -i), seeks in this input file to +position. Note that in most formats it is not possible to seek exactly, +so ffmpeg will seek to the closest seek point before position. +When transcoding and -accurate_seek is enabled (the default), this +extra segment between the seek point and position will be decoded and +discarded. When doing stream copy or when -noaccurate_seek is used, it +will be preserved. +

+

When used as an output option (before an output url), decodes but discards +input until the timestamps reach position. +

+

position must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+
+
-sseof position (input)
+
+

Like the -ss option but relative to the "end of file". That is negative +values are earlier in the file, 0 is at EOF. +

+
+
-isync input_index (input)
+

Assign an input as a sync source. +

+

This will take the difference between the start times of the target and reference inputs and +offset the timestamps of the target file by that difference. The source timestamps of the two +inputs should derive from the same clock source for expected results. If copyts is set +then start_at_zero must also be set. If either of the inputs has no starting timestamp +then no sync adjustment is made. +

+

Acceptable values are those that refer to a valid ffmpeg input index. If the sync reference is +the target index itself or -1, then no adjustment is made to target timestamps. A sync +reference may not itself be synced to any other input. +

+

Default value is -1. +

+
+
-itsoffset offset (input)
+

Set the input time offset. +

+

offset must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

The offset is added to the timestamps of the input files. Specifying +a positive offset means that the corresponding streams are delayed by +the time duration specified in offset. +

+
+
-itsscale scale (input,per-stream)
+

Rescale input timestamps. scale should be a floating point number. +

+
+
-timestamp date (output)
+

Set the recording timestamp in the container. +

+

date must be a date specification, +see the Date section in the ffmpeg-utils(1) manual. +

+
+
-metadata[:metadata_specifier] key=value (output,per-metadata)
+

Set a metadata key/value pair. +

+

An optional metadata_specifier may be given to set metadata +on streams, chapters or programs. See -map_metadata +documentation for details. +

+

This option overrides metadata set with -map_metadata. It is +also possible to delete metadata by using an empty value. +

+

For example, for setting the title in the output file: +

+
ffmpeg -i in.avi -metadata title="my title" out.flv
+
+ +

To set the language of the first audio stream: +

+
ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
+
+ +
+
-disposition[:stream_specifier] value (output,per-stream)
+

Sets the disposition flags for a stream. +

+

Default value: by default, all disposition flags are copied from the input stream, +unless the output stream this option applies to is fed by a complex filtergraph +- in that case no disposition flags are set by default. +

+

value is a sequence of disposition flags separated by ’+’ or ’-’. A ’+’ +prefix adds the given disposition, ’-’ removes it. If the first flag is also +prefixed with ’+’ or ’-’, the resulting disposition is the default value +updated by value. If the first flag is not prefixed, the resulting +disposition is value. It is also possible to clear the disposition by +setting it to 0. +

+

If no -disposition options were specified for an output file, ffmpeg will +automatically set the ’default’ disposition flag on the first stream of each type, +when there are multiple streams of this type in the output file and no stream of +that type is already marked as default. +

+

The -dispositions option lists the known disposition flags. +

+

For example, to make the second audio stream the default stream: +

+
ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
+
+ +

To make the second subtitle stream the default stream and remove the default +disposition from the first subtitle stream: +

+
ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
+
+ +

To add an embedded cover/thumbnail: +

+
ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
+
+ +

To add the ’original’ and remove the ’comment’ disposition flag from the first +audio stream without removing its other disposition flags: +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 +original-comment out.mkv
+
+ +

To remove the ’original’ and add the ’comment’ disposition flag to the first +audio stream without removing its other disposition flags: +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 -original+comment out.mkv
+
+ +

To set only the ’original’ and ’comment’ disposition flags on the first audio +stream (and remove its other disposition flags): +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 original+comment out.mkv
+
+ +

To remove all disposition flags from the first audio stream: +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 0 out.mkv
+
+ +

Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG. +

+
+
-program [title=title:][program_num=program_num:]st=stream[:st=stream...] (output)
+
+

Creates a program with the specified title, program_num and adds the specified +stream(s) to it. +

+
+
-stream_group [map=input_file_id=stream_group][type=type:]st=stream[:st=stream][:stg=stream_group][:id=stream_group_id...] (output)
+
+

Creates a stream group of the specified type and stream_group_id, or by +mapping an input group, adding the specified stream(s) and/or previously +defined stream_group(s) to it. +

+

type can be one of the following: +

+
iamf_audio_element
+

Groups streams that belong to the same IAMF Audio Element +

+

For this group type, the following options are available +

+
audio_element_type
+

The Audio Element type. The following values are supported: +

+
+
channel
+

Scalable channel audio representation +

+
scene
+

Ambisonics representation +

+
+ +
+
demixing
+

Demixing information used to reconstruct a scalable channel audio representation. +This option must be separated from the rest with a ’,’, and takes the following +key=value options +

+
+
parameter_id
+

An identifier parameters blocks in frames may refer to +

+
dmixp_mode
+

A pre-defined combination of demixing parameters +

+
+ +
+
recon_gain
+

Recon gain information used to reconstruct a scalable channel audio representation. +This option must be separated from the rest with a ’,’, and takes the following +key=value options +

+
+
parameter_id
+

An identifier parameters blocks in frames may refer to +

+
+ +
+
layer
+

A layer defining a Channel Layout in the Audio Element. +This option must be separated from the rest with a ’,’. Several ’,’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options +

+
+
ch_layout
+

The layer’s channel layout +

+
flags
+

The following flags are available: +

+
+
recon_gain
+

Whether to signal if recon_gain is present as metadata in parameter blocks within frames +

+
+ +
+
output_gain
+
output_gain_flags
+

Which channels output_gain applies to. The following flags are available: +

+
+
FL
+
FR
+
BL
+
BR
+
TFL
+
TFR
+
+ +
+
ambisonics_mode
+

The ambisonics mode. This has no effect if audio_element_type is set to channel. +

+

The following values are supported: +

+
+
mono
+

Each ambisonics channel is coded as an individual mono stream in the group +

+
+ +
+
+ +
+
default_w
+

Default weight value +

+
+
+ +
+
iamf_mix_presentation
+

Groups streams that belong to all IAMF Audio Element the same +IAMF Mix Presentation references +

+

For this group type, the following options are available +

+
+
submix
+

A sub-mix within the Mix Presentation. +This option must be separated from the rest with a ’,’. Several ’,’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options +

+
+
parameter_id
+

An identifier parameters blocks in frames may refer to, for post-processing the mixed +audio signal to generate the audio signal for playback +

+
parameter_rate
+

The sample rate duration fields in parameters blocks in frames that refer to this +parameter_id are expressed as +

+
default_mix_gain
+

Default mix gain value to apply when there are no parameter blocks sharing the same +parameter_id for a given frame +

+
+
element
+

References an Audio Element used in this Mix Presentation to generate the final output +audio signal for playback. +This option must be separated from the rest with a ’|’. Several ’|’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options: +

+
+
stg
+

The stream_group_id for an Audio Element which this sub-mix refers to +

+
parameter_id
+

An identifier parameters blocks in frames may refer to, for applying any processing to +the referenced and rendered Audio Element before being summed with other processed Audio +Elements +

+
parameter_rate
+

The sample rate duration fields in parameters blocks in frames that refer to this +parameter_id are expressed as +

+
default_mix_gain
+

Default mix gain value to apply when there are no parameter blocks sharing the same +parameter_id for a given frame +

+
annotations
+

A key=value string describing the sub-mix element where "key" is a string conforming to +BCP-47 that specifies the language for the "value" string. "key" must be the same as the +one in the mix’s annotations +

+
headphones_rendering_mode
+

Indicates whether the input channel-based Audio Element is rendered to stereo loudspeakers +or spatialized with a binaural renderer when played back on headphones. +This has no effect if the referenced Audio Element’s audio_element_type is set to +channel. +

+

The following values are supported: +

+
+
stereo
+
binaural
+
+ +
+
+ +
+
layout
+

Specifies the layouts for this sub-mix on which the loudness information was measured. +This option must be separated from the rest with a ’|’. Several ’|’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options: +

+
+
layout_type
+
+
+
loudspeakers
+

The layout follows the loudspeaker sound system convention of ITU-2051-3. +

+
binaural
+

The layout is binaural. +

+
+ +
+
sound_system
+

Channel layout matching one of Sound Systems A to J of ITU-2051-3, plus 7.1.2 and 3.1.2 +This has no effect if layout_type is set to binaural. +

+
integrated_loudness
+

The program integrated loudness information, as defined in ITU-1770-4. +

+
digital_peak
+

The digital (sampled) peak value of the audio signal, as defined in ITU-1770-4. +

+
true_peak
+

The true peak of the audio signal, as defined in ITU-1770-4. +

+
dialog_anchored_loudness
+

The Dialogue loudness information, as defined in ITU-1770-4. +

+
album_anchored_loudness
+

The Album loudness information, as defined in ITU-1770-4. +

+
+ +
+
+ +
+
annotations
+

A key=value string string describing the mix where "key" is a string conforming to BCP-47 +that specifies the language for the "value" string. "key" must be the same as the ones in +all sub-mix element’s annotationss +

+
+ +
+
+ +

E.g. to create an scalable 5.1 IAMF file from several WAV input files +

+
ffmpeg -i front.wav -i back.wav -i center.wav -i lfe.wav
+-map 0:0 -map 1:0 -map 2:0 -map 3:0 -c:a opus
+-stream_group type=iamf_audio_element:id=1:st=0:st=1:st=2:st=3,
+demixing=parameter_id=998,
+recon_gain=parameter_id=101,
+layer=ch_layout=stereo,
+layer=ch_layout=5.1(side),
+-stream_group type=iamf_mix_presentation:id=2:stg=0:annotations=en-us=Mix_Presentation,
+submix=parameter_id=100:parameter_rate=48000|element=stg=0:parameter_id=100:annotations=en-us=Scalable_Submix|layout=sound_system=stereo|layout=sound_system=5.1(side)
+-streamid 0:0 -streamid 1:1 -streamid 2:2 -streamid 3:3 output.iamf
+
+ +

To copy the two stream groups (Audio Element and Mix Presentation) from an input IAMF file with four +streams into an mp4 output +

+
ffmpeg -i input.iamf -c:a copy -stream_group map=0=0:st=0:st=1:st=2:st=3 -stream_group map=0=1:stg=0
+-streamid 0:0 -streamid 1:1 -streamid 2:2 -streamid 3:3 output.mp4
+
+ +
+
-target type (output)
+

Specify target file type (vcd, svcd, dvd, dv, +dv50). type may be prefixed with pal-, ntsc- or +film- to use the corresponding standard. All the format options +(bitrate, codecs, buffer sizes) are then set automatically. You can just type: +

+
+
ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
+
+ +

Nevertheless you can specify additional options as long as you know +they do not conflict with the standard, as in: +

+
+
ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+
+ +

The parameters set for each target are as follows. +

+

VCD +

+
pal:
+-f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
+-s 352x288 -r 25
+-codec:v mpeg1video -g 15 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
+-ar 44100 -ac 2
+-codec:a mp2 -b:a 224k
+
+ntsc:
+-f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
+-s 352x240 -r 30000/1001
+-codec:v mpeg1video -g 18 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
+-ar 44100 -ac 2
+-codec:a mp2 -b:a 224k
+
+film:
+-f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
+-s 352x240 -r 24000/1001
+-codec:v mpeg1video -g 18 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
+-ar 44100 -ac 2
+-codec:a mp2 -b:a 224k
+
+ +

SVCD +

+
pal:
+-f svcd -packetsize 2324
+-s 480x576 -pix_fmt yuv420p -r 25
+-codec:v mpeg2video -g 15 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
+-ar 44100
+-codec:a mp2 -b:a 224k
+
+ntsc:
+-f svcd -packetsize 2324
+-s 480x480 -pix_fmt yuv420p -r 30000/1001
+-codec:v mpeg2video -g 18 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
+-ar 44100
+-codec:a mp2 -b:a 224k
+
+film:
+-f svcd -packetsize 2324
+-s 480x480 -pix_fmt yuv420p -r 24000/1001
+-codec:v mpeg2video -g 18 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
+-ar 44100
+-codec:a mp2 -b:a 224k
+
+ +

DVD +

+
pal:
+-f dvd -muxrate 10080k -packetsize 2048
+-s 720x576 -pix_fmt yuv420p -r 25
+-codec:v mpeg2video -g 15 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
+-ar 48000
+-codec:a ac3 -b:a 448k
+
+ntsc:
+-f dvd -muxrate 10080k -packetsize 2048
+-s 720x480 -pix_fmt yuv420p -r 30000/1001
+-codec:v mpeg2video -g 18 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
+-ar 48000
+-codec:a ac3 -b:a 448k
+
+film:
+-f dvd -muxrate 10080k -packetsize 2048
+-s 720x480 -pix_fmt yuv420p -r 24000/1001
+-codec:v mpeg2video -g 18 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
+-ar 48000
+-codec:a ac3 -b:a 448k
+
+ +

DV +

+
pal:
+-f dv
+-s 720x576 -pix_fmt yuv420p -r 25
+-ar 48000 -ac 2
+
+ntsc:
+-f dv
+-s 720x480 -pix_fmt yuv411p -r 30000/1001
+-ar 48000 -ac 2
+
+film:
+-f dv
+-s 720x480 -pix_fmt yuv411p -r 24000/1001
+-ar 48000 -ac 2
+
+

The dv50 target is identical to the dv target except that the pixel format set is yuv422p for all three standards. +

+

Any user-set value for a parameter above will override the target preset value. In that case, the output may +not comply with the target standard. +

+
+
-dn (input/output)
+

As an input option, blocks all data streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables data recording i.e. automatic selection or +mapping of any data stream. For full manual control see the -map +option. +

+
+
-dframes number (output)
+

Set the number of data frames to output. This is an obsolete alias for +-frames:d, which you should use instead. +

+
+
-frames[:stream_specifier] framecount (output,per-stream)
+

Stop writing to the stream after framecount frames. +

+
+
-q[:stream_specifier] q (output,per-stream)
+
-qscale[:stream_specifier] q (output,per-stream)
+

Use fixed quality scale (VBR). The meaning of q/qscale is +codec-dependent. +If qscale is used without a 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. +

+
+
-filter[:stream_specifier] filtergraph (output,per-stream)
+

Create the filtergraph specified by filtergraph and use it to +filter the stream. +

+

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 filtergraph, the input is associated +to the label in, and the output to the label out. See +the ffmpeg-filters manual for more information about the filtergraph +syntax. +

+

See the -filter_complex option if you +want to create filtergraphs with multiple inputs and/or outputs. +

+
+
-reinit_filter[:stream_specifier] integer (input,per-stream)
+

This boolean option determines if the filtergraph(s) to which this stream is fed gets +reinitialized when input frame parameters change mid-stream. This option is enabled by +default as most video and all audio filters cannot handle deviation in input frame properties. +Upon reinitialization, existing filter state is lost, like e.g. the frame count n +reference available in some filters. Any frames buffered at time of reinitialization are lost. +The properties where a change triggers reinitialization are, +for video, frame resolution or pixel format; +for audio, sample format, sample rate, channel count or channel layout. +

+
+
-drop_changed[:stream_specifier] integer (input,per-stream)
+

This boolean option determines whether a frame with differing frame parameters mid-stream +gets dropped instead of leading to filtergraph reinitialization, as that would lead to loss +of filter state. Generally useful to avoid corrupted yet decodable packets in live streaming +inputs. Default is false. +

+
+
-filter_threads nb_threads (global)
+

Defines how many threads are used to process a filter pipeline. Each pipeline +will produce a thread pool with this many threads available for parallel processing. +The default is the number of available CPUs. +

+
+
-filter_buffered_frames nb_frames (global)
+

Defines the maximum number of buffered frames allowed in a filtergraph. Under +normal circumstances, a filtergraph should not buffer more than a few frames, +especially if frames are being fed to it and read from it in a balanced way +(which is the intended behavior in ffmpeg). That said, this option allows you +to limit the total number of frames buffered across all links in a filtergraph. +If more frames are generated, filtering is aborted and an error is returned. +The default value is 0, which means no limit. +

+
+
-pre[:stream_specifier] preset_name (output,per-stream)
+

Specify the preset for matching stream(s). +

+
+
-stats (global)
+

Log encoding progress/statistics as "info"-level log (see -loglevel). +It is on by default, to explicitly disable it you need to specify -nostats. +

+
+
-stats_period time (global)
+

Set period at which encoding progress/statistics are updated. Default is 0.5 seconds. +

+
+
-print_graphs (global)
+

Prints execution graph details to stderr in the format set via -print_graphs_format. +

+
+
-print_graphs_file filename (global)
+

Writes execution graph details to the specified file in the format set via -print_graphs_format. +

+
+
-print_graphs_format format (global)
+

Sets the output format (available formats are: default, compact, csv, flat, ini, json, xml, mermaid, mermaidhtml) +The default format is json. +

+
+
-progress url (global)
+

Send program-friendly progress information to url. +

+

Progress information is written periodically and at the end of +the encoding process. It is made of "key=value" lines. key +consists of only alphanumeric characters. The last key of a sequence of +progress information is always "progress" with the value "continue" or "end". +

+

The update period is set using -stats_period. +

+

For example, log progress information to stdout: +

+
+
ffmpeg -progress pipe:1 -i in.mkv out.mkv
+
+ +
+
-stdin
+

Enable interaction on standard input. On by default unless standard input is +used as an input. To explicitly disable interaction you need to specify +-nostdin. +

+

Disabling interaction on standard input is useful, for example, if +ffmpeg is in the background process group. Roughly the same result can +be achieved with ffmpeg ... < /dev/null but it requires a +shell. +

+
+
-debug_ts (global)
+

Print timestamp/latency information. It is off by default. This option is +mostly useful for testing and debugging purposes, and the output +format may change from one version to another, so it should not be +employed by portable scripts. +

+

See also the option -fdebug ts. +

+
+
-attach filename (output)
+

Add an attachment to the output file. This is supported by a few formats +like Matroska for e.g. fonts used in rendering subtitles. Attachments +are implemented as a specific type of stream, so this option will add +a new stream to the file. It is then possible to use per-stream options +on this stream in the usual way. Attachment streams created with this +option will be created after all the other streams (i.e. those created +with -map or automatic mappings). +

+

Note that for Matroska you also have to set the mimetype metadata tag: +

+
ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
+
+

(assuming that the attachment stream will be third in the output file). +

+
+
-dump_attachment[:stream_specifier] filename (input,per-stream)
+

Extract the matching attachment stream into a file named filename. If +filename is empty, then the value of the filename metadata tag +will be used. +

+

E.g. to extract the first attachment to a file named ’out.ttf’: +

+
ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
+
+

To extract all attachments to files determined by the filename tag: +

+
ffmpeg -dump_attachment:t "" -i INPUT
+
+ +

Technical note – attachments are implemented as codec extradata, so this +option can actually be used to extract extradata from any stream, not just +attachments. +

+
+ + +

5.5 Video Options

+ +
+
-vframes number (output)
+

Set the number of video frames to output. This is an obsolete alias for +-frames:v, which you should use instead. +

+
-r[:stream_specifier] fps (input/output,per-stream)
+

Set frame rate (Hz value, fraction or abbreviation). +

+

As an input option, ignore any timestamps stored in the file and instead +generate timestamps assuming constant frame rate fps. +This is not the same as the -framerate option used for some input formats +like image2 or v4l2 (it used to be the same in older versions of FFmpeg). +If in doubt use -framerate instead of the input option -r. +

+

As an output option: +

+
video encoding
+

Duplicate or drop frames right before encoding them to achieve constant output +frame rate fps. +

+
+
video streamcopy
+

Indicate to the muxer that fps is the stream frame rate. No data is +dropped or duplicated in this case. This may produce invalid files if fps +does not match the actual stream frame rate as determined by packet timestamps. +See also the setts bitstream filter. +

+
+
+ +
+
-fpsmax[:stream_specifier] fps (output,per-stream)
+

Set maximum frame rate (Hz value, fraction or abbreviation). +

+

Clamps output frame rate when output framerate is auto-set and is higher than this value. +Useful in batch processing or when input framerate is wrongly detected as very high. +It cannot be set together with -r. It is ignored during streamcopy. +

+
+
-s[:stream_specifier] size (input/output,per-stream)
+

Set frame size. +

+

As an input option, this is a shortcut for the video_size private +option, recognized by some demuxers for which the frame size is either not +stored in the file or is configurable – e.g. raw video or video grabbers. +

+

As an output option, this inserts the scale video filter to the +end of the corresponding filtergraph. Please use the scale filter +directly to insert it at the beginning or some other place. +

+

The format is ‘wxh’ (default - same as source). +

+
+
-aspect[:stream_specifier] aspect (output,per-stream)
+

Set the video display aspect ratio specified by aspect. +

+

aspect can be a floating point number string, or a string of the +form num:den, where num and 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 -vcodec copy, it will affect the aspect ratio +stored at container level, but not the aspect ratio stored in encoded +frames, if it exists. +

+
+
-display_rotation[:stream_specifier] rotation (input,per-stream)
+

Set video rotation metadata. +

+

rotation is a decimal number specifying the amount in degree by +which the video should be rotated counter-clockwise before being +displayed. +

+

This option overrides the rotation/display transform metadata stored in +the file, if any. When the video is being transcoded (rather than +copied) and -autorotate is enabled, the video will be rotated at +the filtering stage. Otherwise, the metadata will be written into the +output file if the muxer supports it. +

+

If the -display_hflip and/or -display_vflip options are +given, they are applied after the rotation specified by this option. +

+
+
-display_hflip[:stream_specifier] (input,per-stream)
+

Set whether on display the image should be horizontally flipped. +

+

See the -display_rotation option for more details. +

+
+
-display_vflip[:stream_specifier] (input,per-stream)
+

Set whether on display the image should be vertically flipped. +

+

See the -display_rotation option for more details. +

+
+
-vn (input/output)
+

As an input option, blocks all video streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables video recording i.e. automatic selection or +mapping of any video stream. For full manual control see the -map +option. +

+
+
-vcodec codec (output)
+

Set the video codec. This is an alias for -codec:v. +

+
+
-pass[:stream_specifier] n (output,per-stream)
+

Select the pass number (1 or 2). It is used to do two-pass +video encoding. The statistics of the video are recorded in the first +pass into a log file (see also the option -passlogfile), +and in the second pass that log file is used to generate the video +at the exact requested bitrate. +On pass 1, you may just deactivate audio and set output to null, +examples for Windows and Unix: +

+
ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
+ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
+
+ +
+
-passlogfile[:stream_specifier] prefix (output,per-stream)
+

Set two-pass log file name prefix to prefix, the default file name +prefix is “ffmpeg2pass”. The complete file name will be +PREFIX-N.log, where N is a number specific to the output +stream +

+
+
-vf filtergraph (output)
+

Create the filtergraph specified by filtergraph and use it to +filter the stream. +

+

This is an alias for -filter:v, see the -filter option. +

+
+
-autorotate
+

Automatically rotate the video according to file metadata. Enabled by +default, use -noautorotate to disable it. +

+
+
-autoscale
+

Automatically scale the video according to the resolution of first frame. +Enabled by default, use -noautoscale to disable it. When autoscale is +disabled, all output frames of filter graph might not be in the same resolution +and may be inadequate for some encoder/muxer. Therefore, it is not recommended +to disable it unless you really know what you are doing. +Disable autoscale at your own risk. +

+
+ + +

5.6 Advanced Video options

+ +
+
-pix_fmt[:stream_specifier] format (input/output,per-stream)
+

Set pixel format. Use -pix_fmts to show all the supported +pixel formats. +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 pix_fmt is prefixed by a +, ffmpeg will exit with an error +if the requested pixel format can not be selected, and automatic conversions +inside filtergraphs are disabled. +If pix_fmt is a single +, ffmpeg selects the same pixel format +as the input (or graph output) and automatic conversions are disabled. +

+
+
-sws_flags flags (input/output)
+

Set default flags for the libswscale library. These flags are used by +automatically inserted scale filters and those within simple +filtergraphs, if not overridden within the filtergraph definition. +

+

See the ffmpeg-scaler manual for a list +of scaler options. +

+
+
-rc_override[:stream_specifier] override (output,per-stream)
+

Rate control override for specific intervals, formatted as "int,int,int" +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. +

+
+
-vstats
+

Dump video coding statistics to vstats_HHMMSS.log. See the +vstats file format section for the format description. +

+
+
-vstats_file file
+

Dump video coding statistics to file. See the +vstats file format section for the format description. +

+
+
-vstats_version file
+

Specify which version of the vstats format to use. Default is 2. See the +vstats file format section for the format description. +

+
+
-vtag fourcc/tag (output)
+

Force video tag/fourcc. This is an alias for -tag:v. +

+
+
-force_key_frames[:stream_specifier] time[,time...] (output,per-stream)
+
-force_key_frames[:stream_specifier] expr:expr (output,per-stream)
+
-force_key_frames[:stream_specifier] source (output,per-stream)
+
-force_key_frames[:stream_specifier] scd_metadata (output,per-stream)
+
+

force_key_frames can take arguments of the following form: +

+
+
time[,time...]
+

If the argument consists of timestamps, ffmpeg will round the specified times to the nearest +output timestamp as per the encoder time base and force a keyframe at the first frame having +timestamp equal or greater than the computed timestamp. Note that if the encoder time base is too +coarse, then the keyframes may be forced on frames with timestamps lower than the specified time. +The default encoder time base is the inverse of the output framerate but may be set otherwise +via -enc_time_base. +

+

If one of the times is "chapters[delta]", it is expanded into +the time of the beginning of all chapters in the file, shifted by +delta, expressed as a time in seconds. +This option can be useful to ensure that a seek point is present at a +chapter mark or any other designated place in the output file. +

+

For example, to insert a key frame at 5 minutes, plus key frames 0.1 second +before the beginning of every chapter: +

+
-force_key_frames 0:05:00,chapters-0.1
+
+ +
+
expr:expr
+

If the argument is prefixed with expr:, the string expr +is interpreted like an expression and is evaluated for each frame. A +key frame is forced in case the evaluation is non-zero. +

+

The expression in expr can contain the following constants: +

+
n
+

the number of current processed frame, starting from 0 +

+
n_forced
+

the number of forced frames +

+
prev_forced_n
+

the number of the previous forced frame, it is NAN when no +keyframe was forced yet +

+
prev_forced_t
+

the time of the previous forced frame, it is NAN when no +keyframe was forced yet +

+
t
+

the time of the current processed frame +

+
+ +

For example to force a key frame every 5 seconds, you can specify: +

+
-force_key_frames expr:gte(t,n_forced*5)
+
+ +

To force a key frame 5 seconds after the time of the last forced one, +starting from second 13: +

+
-force_key_frames expr:if(isnan(prev_forced_t),gte(t,13),gte(t,prev_forced_t+5))
+
+ +
+
source
+

If the argument is source, ffmpeg will force a key frame if +the current frame being encoded is marked as a key frame in its source. +In cases where this particular source frame has to be dropped, +enforce the next available frame to become a key frame instead. +

+
+
scd_metadata
+

If the argument is scd_metadata, ffmpeg will force a key frame if +the current frame contains a metadata entry with the key lavfi.scd.time. +The metadata can be added by filters like scdet and scdet_vulkan. +Avoid inserting filters that duplicate frames after scdet, as this can +cause duplicate metadata for multiple frames and repeated insertion of key +frames. +

+
+
+ +

Note that forcing too many keyframes is very harmful for the lookahead +algorithms of certain encoders: using fixed-GOP options or similar +would be more efficient. +

+
+
-apply_cropping[:stream_specifier] source (input,per-stream)
+

Automatically crop the video after decoding according to file metadata. +Default is all. +

+
+
none (0)
+

Don’t apply any cropping metadata. +

+
all (1)
+

Apply both codec and container level croppping. This is the default mode. +

+
codec (2)
+

Apply codec level croppping. +

+
container (3)
+

Apply container level croppping. +

+
+ +
+
-copyinkf[:stream_specifier] (output,per-stream)
+

When doing stream copy, copy also non-key frames found at the +beginning. +

+
+
-init_hw_device type[=name][:device[,key=value...]]
+

Initialise a new hardware device of type type called name, using the +given device parameters. +If no name is specified it will receive a default name of the form "type%d". +

+

The meaning of device and the following arguments depends on the +device type: +

+
cuda
+

device is the number of the CUDA device. +

+

The following options are recognized: +

+
primary_ctx
+

If set to 1, uses the primary device context instead of creating a new one. +

+
+ +

Examples: +

+
-init_hw_device cuda:1
+

Choose the second device on the system. +

+
+
-init_hw_device cuda:0,primary_ctx=1
+

Choose the first device and use the primary device context. +

+
+ +
+
dxva2
+

device is the number of the Direct3D 9 display adapter. +

+
+
d3d11va
+

device is the number of the Direct3D 11 display adapter. +If not specified, it will attempt to use the default Direct3D 11 display adapter +or the first Direct3D 11 display adapter whose hardware VendorId is specified +by ‘vendor_id’. +

+

Examples: +

+
-init_hw_device d3d11va
+

Create a d3d11va device on the default Direct3D 11 display adapter. +

+
+
-init_hw_device d3d11va:1
+

Create a d3d11va device on the Direct3D 11 display adapter specified by index 1. +

+
+
-init_hw_device d3d11va:,vendor_id=0x8086
+

Create a d3d11va device on the first Direct3D 11 display adapter whose hardware VendorId is 0x8086. +

+
+ +
+
vaapi
+

device is either an X11 display name, a DRM render node or a DirectX adapter index. +If not specified, it will attempt to open the default X11 display ($DISPLAY) +and then the first DRM render node (/dev/dri/renderD128), or the default +DirectX adapter on Windows. +

+

The following options are recognized: +

+
kernel_driver
+

When device is not specified, use this option to specify the name of the kernel +driver associated with the desired device. This option is available only when +the hardware acceleration method drm and vaapi are enabled. +

+
vendor_id
+

When device and kernel_driver are not specified, use this option to specify +the vendor id associated with the desired device. This option is available only when the +hardware acceleration method drm and vaapi are enabled and kernel_driver +is not specified. +

+
+ +

Examples: +

+
-init_hw_device vaapi
+

Create a vaapi device on the default device. +

+
+
-init_hw_device vaapi:/dev/dri/renderD129
+

Create a vaapi device on DRM render node /dev/dri/renderD129. +

+
+
-init_hw_device vaapi:1
+

Create a vaapi device on DirectX adapter 1. +

+
+
-init_hw_device vaapi:,kernel_driver=i915
+

Create a vaapi device on a device associated with kernel driver ‘i915’. +

+
+
-init_hw_device vaapi:,vendor_id=0x8086
+

Create a vaapi device on a device associated with vendor id ‘0x8086’. +

+
+ +
+
vdpau
+

device is an X11 display name. +If not specified, it will attempt to open the default X11 display ($DISPLAY). +

+
+
qsv
+

device selects a value in ‘MFX_IMPL_*’. Allowed values are: +

+
auto
+
sw
+
hw
+
auto_any
+
hw_any
+
hw2
+
hw3
+
hw4
+
+

If not specified, ‘auto_any’ is used. +(Note that it may be easier to achieve the desired result for QSV by creating the +platform-appropriate subdevice (‘dxva2’ or ‘d3d11va’ or ‘vaapi’) and then deriving a +QSV device from that.) +

+

The following options are recognized: +

+
child_device
+

Specify a DRM render node on Linux or DirectX adapter on Windows. +

+
child_device_type
+

Choose platform-appropriate subdevice type. On Windows ‘d3d11va’ is used +as default subdevice type when --enable-libvpl is specified at configuration time, +‘dxva2’ is used as default subdevice type when --enable-libmfx is specified at +configuration time. On Linux user can use ‘vaapi’ only as subdevice type. +

+
+ +

Examples: +

+
-init_hw_device qsv:hw,child_device=/dev/dri/renderD129
+

Create a QSV device with ‘MFX_IMPL_HARDWARE’ on DRM render node /dev/dri/renderD129. +

+
+
-init_hw_device qsv:hw,child_device=1
+

Create a QSV device with ‘MFX_IMPL_HARDWARE’ on DirectX adapter 1. +

+
+
-init_hw_device qsv:hw,child_device_type=d3d11va
+

Choose the GPU subdevice with type ‘d3d11va’ and create QSV device with ‘MFX_IMPL_HARDWARE’. +

+
+
-init_hw_device qsv:hw,child_device_type=dxva2
+

Choose the GPU subdevice with type ‘dxva2’ and create QSV device with ‘MFX_IMPL_HARDWARE’. +

+
+
-init_hw_device qsv:hw,child_device=1,child_device_type=d3d11va
+

Create a QSV device with ‘MFX_IMPL_HARDWARE’ on DirectX adapter 1 with subdevice type ‘d3d11va’. +

+
+
-init_hw_device vaapi=va:/dev/dri/renderD129 -init_hw_device qsv=hw1@va
+

Create a VAAPI device called ‘va’ on /dev/dri/renderD129, then derive a QSV device called ‘hw1’ +from device ‘va’. +

+
+
+ +
+
opencl
+

device selects the platform and device as platform_index.device_index. +

+

The set of devices can also be filtered using the key-value pairs to find only +devices matching particular platform or device strings. +

+

The strings usable as filters are: +

+
platform_profile
+
platform_version
+
platform_name
+
platform_vendor
+
platform_extensions
+
device_name
+
device_vendor
+
driver_version
+
device_version
+
device_profile
+
device_extensions
+
device_type
+
+ +

The indices and filters must together uniquely select a device. +

+

Examples: +

+
-init_hw_device opencl:0.1
+

Choose the second device on the first platform. +

+
+
-init_hw_device opencl:,device_name=Foo9000
+

Choose the device with a name containing the string Foo9000. +

+
+
-init_hw_device opencl:1,device_type=gpu,device_extensions=cl_khr_fp16
+

Choose the GPU device on the second platform supporting the cl_khr_fp16 +extension. +

+
+ +
+
vulkan
+

If device is an integer, it selects the device by its index in a +system-dependent list of devices. If device is any other string, it +selects the first device with a name containing that string as a substring. +

+

The following options are recognized: +

+
debug
+

If set to 1, enables the validation layer, if installed. +

+
linear_images
+

If set to 1, images allocated by the hwcontext will be linear and locally mappable. +

+
instance_extensions
+

A plus separated list of additional instance extensions to enable. +

+
device_extensions
+

A plus separated list of additional device extensions to enable. +

+
+ +

Examples: +

+
-init_hw_device vulkan:1
+

Choose the second device on the system. +

+
+
-init_hw_device vulkan:RADV
+

Choose the first device with a name containing the string RADV. +

+
+
-init_hw_device vulkan:0,instance_extensions=VK_KHR_wayland_surface+VK_KHR_xcb_surface
+

Choose the first device and enable the Wayland and XCB instance extensions. +

+
+ +
+
+ +
+
-init_hw_device type[=name]@source
+

Initialise a new hardware device of type type called name, +deriving it from the existing device with the name source. +

+
+
-init_hw_device list
+

List all hardware device types supported in this build of ffmpeg. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +This can be used to set the device to upload to with the hwupload filter, +or the device to map to with the hwmap filter. Other filters may also +make use of this parameter when they require a hardware device. Note that this +is typically only required when the input is not already in hardware frames - +when it is, filters will derive the device they require from the context of the +frames they receive as input. +

+

This is a global setting, so all filters will receive the same device. +

+
+
-hwaccel[:stream_specifier] hwaccel (input,per-stream)
+

Use hardware acceleration to decode the matching stream(s). The allowed values +of hwaccel are: +

+
none
+

Do not use any hardware acceleration (the default). +

+
+
auto
+

Automatically select the hardware acceleration method. +

+
+
vdpau
+

Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration. +

+
+
dxva2
+

Use DXVA2 (DirectX Video Acceleration) hardware acceleration. +

+
+
d3d11va
+

Use D3D11VA (DirectX Video Acceleration) hardware acceleration. +

+
+
vaapi
+

Use VAAPI (Video Acceleration API) hardware acceleration. +

+
+
qsv
+

Use the Intel QuickSync Video acceleration for video transcoding. +

+

Unlike most other values, this option does not enable accelerated decoding (that +is used automatically whenever a qsv decoder is selected), but accelerated +transcoding, without copying the frames into the system memory. +

+

For it to work, both the decoder and the encoder must support QSV acceleration +and no filters must be used. +

+
+
videotoolbox
+

Use Video Toolbox hardware acceleration. +

+
+ +

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, 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. +

+
+
-hwaccel_device[:stream_specifier] hwaccel_device (input,per-stream)
+

Select a device to use for hardware acceleration. +

+

This option only makes sense when the -hwaccel option is also specified. +It can either refer to an existing device created with -init_hw_device +by name, or it can create a new device as if +‘-init_hw_device’ type:hwaccel_device +were called immediately before. +

+
+
-hwaccels
+

List all hardware acceleration components enabled in this build of ffmpeg. +Actual runtime availability depends on the hardware and its suitable driver +being installed. +

+
+
-fix_sub_duration_heartbeat[:stream_specifier]
+

Set a specific output video stream as the heartbeat stream according to which +to split and push through currently in-progress subtitle upon receipt of a +random access packet. +

+

This lowers the latency of subtitles for which the end packet or the following +subtitle has not yet been received. As a drawback, this will most likely lead +to duplication of subtitle events in order to cover the full duration, so +when dealing with use cases where latency of when the subtitle event is passed +on to output is not relevant this option should not be utilized. +

+

Requires -fix_sub_duration to be set for the relevant input subtitle +stream for this to have any effect, as well as for the input subtitle stream +having to be directly mapped to the same output in which the heartbeat stream +resides. +

+
+
+ + +

5.7 Audio Options

+ +
+
-aframes number (output)
+

Set the number of audio frames to output. This is an obsolete alias for +-frames:a, which you should use instead. +

+
-ar[:stream_specifier] freq (input/output,per-stream)
+

Set the audio sampling frequency. For output streams it is set by +default to the frequency of the corresponding input stream. For input +streams this option only makes sense for audio grabbing devices and raw +demuxers and is mapped to the corresponding demuxer options. +

+
-aq q (output)
+

Set the audio quality (codec-specific, VBR). This is an alias for -q:a. +

+
-ac[:stream_specifier] channels (input/output,per-stream)
+

Set the number of audio channels. For output streams it is set by +default to the number of input audio channels. For input streams +this option only makes sense for audio grabbing devices and raw demuxers +and is mapped to the corresponding demuxer options. +

+
-an (input/output)
+

As an input option, blocks all audio streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables audio recording i.e. automatic selection or +mapping of any audio stream. For full manual control see the -map +option. +

+
-acodec codec (input/output)
+

Set the audio codec. This is an alias for -codec:a. +

+
-sample_fmt[:stream_specifier] sample_fmt (output,per-stream)
+

Set the audio sample format. Use -sample_fmts to get a list +of supported sample formats. +

+
+
-af filtergraph (output)
+

Create the filtergraph specified by filtergraph and use it to +filter the stream. +

+

This is an alias for -filter:a, see the -filter option. +

+
+ + +

5.8 Advanced Audio options

+ +
+
-atag fourcc/tag (output)
+

Force audio tag/fourcc. This is an alias for -tag:a. +

+
-ch_layout[:stream_specifier] layout (input/output,per-stream)
+

Alias for -channel_layout. +

+
-channel_layout[:stream_specifier] layout (input/output,per-stream)
+

Set the audio channel layout. For output streams it is set by default to the +input channel layout. For input streams it overrides the channel layout of the +input. Not all decoders respect the overridden channel layout. This option +also sets the channel layout for audio grabbing devices and raw demuxers +and is mapped to the corresponding demuxer option. +

+
-guess_layout_max channels (input,per-stream)
+

If some input channel layout is not known, try to guess only if it +corresponds to at most the specified number of channels. For example, 2 +tells to ffmpeg to recognize 1 channel as mono and 2 channels as +stereo but not 6 channels as 5.1. The default is to always try to guess. Use +0 to disable all guessing. Using the -channel_layout option to +explicitly specify an input layout also disables guessing. +

+
+ + +

5.9 Subtitle options

+ +
+
-scodec codec (input/output)
+

Set the subtitle codec. This is an alias for -codec:s. +

+
-sn (input/output)
+

As an input option, blocks all subtitle streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables subtitle recording i.e. automatic selection or +mapping of any subtitle stream. For full manual control see the -map +option. +

+
+ + +

5.10 Advanced Subtitle options

+ +
+
-fix_sub_duration
+

Fix subtitles durations. For each subtitle, wait for the next packet in the +same stream and adjust the duration of the first to avoid overlap. This is +necessary with some subtitles codecs, especially DVB subtitles, because the +duration in the original packet is only a rough estimate and the end is +actually marked by an empty subtitle frame. Failing to use this option when +necessary can result in exaggerated durations or muxing failures due to +non-monotonic timestamps. +

+

Note that this option will delay the output of all data until the next +subtitle packet is decoded: it may increase memory consumption and latency a +lot. +

+
+
-canvas_size size
+

Set the size of the canvas used to render subtitles. +

+
+
+ + +

5.11 Advanced options

+ +
+
-map [-]input_file_id[:stream_specifier][:view_specifier][:?] | [linklabel] (output)
+
+

Create one or more streams in the output file. This option has two forms for +specifying the data source(s): the first selects one or more streams from some +input file (specified with -i), the second takes an output from some +complex filtergraph (specified with -filter_complex). +

+

In the first form, an output stream is created for every stream from the input +file with the index input_file_id. If stream_specifier is given, +only those streams that match the specifier are used (see the +Stream specifiers section for the stream_specifier syntax). +

+

A - character before the stream identifier creates a "negative" mapping. +It disables matching streams from already created mappings. +

+

An optional view_specifier may be given after the stream specifier, which +for multiview video specifies the view to be used. The view specifier may have +one of the following formats: +

+
view:view_id
+

select a view by its ID; view_id may be set to ’all’ to use all the views +interleaved into one stream; +

+
+
vidx:view_idx
+

select a view by its index; i.e. 0 is the base view, 1 is the first non-base +view, etc. +

+
+
vpos:position
+

select a view by its display position; position may be left or +right +

+
+

The default for transcoding is to only use the base view, i.e. the equivalent of +vidx:0. For streamcopy, view specifiers are not supported and all views +are always copied. +

+

A trailing ? after the stream index will allow the map to be +optional: if the map matches no streams the map will be ignored instead +of failing. Note the map will still fail if an invalid input file index +is used; such as if the map refers to a non-existent input. +

+

An alternative [linklabel] form will map outputs from complex filter +graphs (see the -filter_complex option) to the output file. +linklabel must correspond to a defined output link label in the graph. +

+

This option may be specified multiple times, each adding more streams to the +output file. Any given input stream may also be mapped any number of times as a +source for different output streams, e.g. in order to use different encoding +options and/or filters. The streams are created in the output in the same order +in which the -map options are given on the commandline. +

+

Using this option disables the default mappings for this output file. +

+

Examples: +

+
+
map everything
+

To map ALL streams from the first input file to output +

+
ffmpeg -i INPUT -map 0 output
+
+ +
+
select specific stream
+

If you have two audio streams in the first input file, these streams are +identified by 0:0 and 0:1. You can use -map to select which +streams to place in an output file. For example: +

+
ffmpeg -i INPUT -map 0:1 out.wav
+
+

will map the second input stream in INPUT to the (single) output stream +in out.wav. +

+
+
create multiple streams
+

To select the stream with index 2 from input file a.mov (specified by the +identifier 0:2), and stream with index 6 from input b.mov +(specified by the identifier 1:6), and copy them to the output file +out.mov: +

+
ffmpeg -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
+
+ +
+
create multiple streams 2
+

To select all video and the third audio stream from an input file: +

+
ffmpeg -i INPUT -map 0:v -map 0:a:2 OUTPUT
+
+ +
+
negative map
+

To map all the streams except the second audio, use negative mappings +

+
ffmpeg -i INPUT -map 0 -map -0:a:1 OUTPUT
+
+ +
+
optional map
+

To map the video and audio streams from the first input, and using the +trailing ?, ignore the audio mapping if no audio streams exist in +the first input: +

+
ffmpeg -i INPUT -map 0:v -map 0:a? OUTPUT
+
+ +
+
map by language
+

To pick the English audio stream: +

+
ffmpeg -i INPUT -map 0:m:language:eng OUTPUT
+
+ +
+
+ +
+
-ignore_unknown
+

Ignore input streams with unknown type instead of failing if copying +such streams is attempted. +

+
+
-copy_unknown
+

Allow input streams with unknown type to be copied instead of failing if copying +such streams is attempted. +

+
+
-map_metadata[:metadata_spec_out] infile[:metadata_spec_in] (output,per-metadata)
+

Set metadata information of the next output file from infile. Note that +those are file indices (zero-based), not filenames. +Optional metadata_spec_in/out parameters specify, which metadata to copy. +A metadata specifier can have the following forms: +

+
g
+

global metadata, i.e. metadata that applies to the whole file +

+
+
s[:stream_spec]
+

per-stream metadata. stream_spec is a stream specifier as described +in the Stream specifiers chapter. In an input metadata specifier, the first +matching stream is copied from. In an output metadata specifier, all matching +streams are copied to. +

+
+
c:chapter_index
+

per-chapter metadata. chapter_index is the zero-based chapter index. +

+
+
p:program_index
+

per-program metadata. program_index is the zero-based program index. +

+
+

If metadata specifier is omitted, it defaults to global. +

+

By default, global metadata is copied from the first input file, +per-stream and per-chapter metadata is copied along with streams/chapters. These +default mappings are disabled by creating any mapping of the relevant type. A negative +file index can be used to create a dummy mapping that just disables automatic copying. +

+

For example to copy metadata from the first stream of the input file to global metadata +of the output file: +

+
ffmpeg -i in.ogg -map_metadata 0:s:0 out.mp3
+
+ +

To do the reverse, i.e. copy global metadata to all audio streams: +

+
ffmpeg -i in.mkv -map_metadata:s:a 0:g out.mkv
+
+

Note that simple 0 would work as well in this example, since global +metadata is assumed by default. +

+
+
-map_chapters input_file_index (output)
+

Copy chapters from input file with index input_file_index to the next +output file. If no chapter mapping is specified, then chapters are copied from +the first input file with at least one chapter. Use a negative file index to +disable any chapter copying. +

+
+
-benchmark (global)
+

Show benchmarking information at the end of an encode. +Shows real, system and user time used and maximum memory consumption. +Maximum memory consumption is not supported on all systems, +it will usually display as 0 if not supported. +

+
-benchmark_all (global)
+

Show benchmarking information during the encode. +Shows real, system and user time used in various steps (audio/video encode/decode). +

+
-timelimit duration (global)
+

Exit after ffmpeg has been running for duration seconds in CPU user time. +

+
-dump (global)
+

Dump each input packet to stderr. +

+
-hex (global)
+

When dumping packets, also dump the payload. +

+
-readrate speed (input)
+

Limit input read speed. +

+

Its value is a floating-point positive number which represents the maximum duration of +media, in seconds, that should be ingested in one second of wallclock time. +Default value is zero and represents no imposed limitation on speed of ingestion. +Value 1 represents real-time speed and is equivalent to -re. +

+

Mainly used to simulate a capture device or live input stream (e.g. when reading from a file). +Should not be used with a low value when input is an actual capture device or live stream as +it may cause packet loss. +

+

It is useful for when flow speed of output packets is important, such as live streaming. +

+
-re (input)
+

Read input at native frame rate. This is equivalent to setting -readrate 1. +

+
-readrate_initial_burst seconds
+

Set an initial read burst time, in seconds, after which -re/-readrate +will be enforced. +

+
-readrate_catchup speed (input)
+

If either the input or output is blocked leading to actual read speed falling behind the +specified readrate, then this rate takes effect till the input catches up with the +specified readrate. Must not be lower than the primary readrate. +

+
+
-vsync parameter (global)
+
-fps_mode[:stream_specifier] parameter (output,per-stream)
+

Set video sync method / framerate mode. vsync is applied to all output video streams +but can be overridden for a stream by setting fps_mode. vsync is deprecated and will be +removed in the future. +

+

For compatibility reasons some of the values for vsync can be specified as numbers (shown +in parentheses in the following table). +

+
+
passthrough (0)
+

Each frame is passed with its timestamp from the demuxer to the muxer. +

+
cfr (1)
+

Frames will be duplicated and dropped to achieve exactly the requested +constant frame rate. +

+
vfr (2)
+

Frames are passed through with their timestamp or dropped so as to +prevent 2 frames from having the same timestamp. +

+
auto (-1)
+

Chooses between cfr and vfr depending on muxer capabilities. This is the +default method. +

+
+ +

Note that the timestamps may be further modified by the muxer, after this. +For example, in the case that the format option avoid_negative_ts +is enabled. +

+

With -map you can select from which stream the timestamps should be +taken. You can leave either video or audio unchanged and sync the +remaining stream(s) to the unchanged one. +

+
+
-frame_drop_threshold parameter
+

Frame drop threshold, which specifies how much behind video frames can +be before they are dropped. In frame rate units, so 1.0 is one frame. +The default is -1.1. One possible usecase is to avoid framedrops in case +of noisy timestamps or to increase frame drop precision in case of exact +timestamps. +

+
+
-apad parameters (output,per-stream)
+

Pad the output audio stream(s). This is the same as applying -af apad. +Argument is a string of filter parameters composed the same as with the apad filter. +-shortest must be set for this output for the option to take effect. +

+
+
-copyts
+

Do not process input timestamps, but keep their values without trying +to sanitize them. In particular, do not remove the initial start time +offset value. +

+

Note that, depending on the vsync option or on specific muxer +processing (e.g. in case the format option avoid_negative_ts +is enabled) the output timestamps may mismatch with the input +timestamps even when this option is selected. +

+
+
-start_at_zero
+

When used with copyts, shift input timestamps so they start at zero. +

+

This means that using e.g. -ss 50 will make output timestamps start at +50 seconds, regardless of what timestamp the input file started at. +

+
+
-copytb mode
+

Specify how to set the encoder timebase when stream copying. mode is an +integer numeric value, and can assume one of the following values: +

+
+
1
+

Use the demuxer timebase. +

+

The time base is copied to the output encoder from the corresponding input +demuxer. This is sometimes required to avoid non monotonically increasing +timestamps when copying video streams with variable frame rate. +

+
+
0
+

Use the decoder timebase. +

+

The time base is copied to the output encoder from the corresponding input +decoder. +

+
+
-1
+

Try to make the choice automatically, in order to generate a sane output. +

+
+ +

Default value is -1. +

+
+
-enc_time_base[:stream_specifier] timebase (output,per-stream)
+

Set the encoder timebase. timebase can assume one of the following values: +

+
+
0
+

Assign a default value according to the media type. +

+

For video - use 1/framerate, for audio - use 1/samplerate. +

+
+
demux
+

Use the timebase from the demuxer. +

+
+
filter
+

Use the timebase from the filtergraph. +

+
+
a positive number
+

Use the provided number as the timebase. +

+

This field can be provided as a ratio of two integers (e.g. 1:24, 1:48000) +or as a decimal number (e.g. 0.04166, 2.0833e-5) +

+
+ +

Default value is 0. +

+
+
-bitexact (input/output)
+

Enable bitexact mode for (de)muxer and (de/en)coder +

+
-shortest (output)
+

Finish encoding when the shortest output stream ends. +

+

Note that this option may require buffering frames, which introduces extra +latency. The maximum amount of this latency may be controlled with the +-shortest_buf_duration option. +

+
+
-shortest_buf_duration duration (output)
+

The -shortest option may require buffering potentially large amounts +of data when at least one of the streams is "sparse" (i.e. has large gaps +between frames – this is typically the case for subtitles). +

+

This option controls the maximum duration of buffered frames in seconds. +Larger values may allow the -shortest option to produce more accurate +results, but increase memory use and latency. +

+

The default value is 10 seconds. +

+
+
-dts_delta_threshold threshold
+

Timestamp discontinuity delta threshold, expressed as a decimal number +of seconds. +

+

The timestamp discontinuity correction enabled by this option is only +applied to input formats accepting timestamp discontinuity (for which +the AVFMT_TS_DISCONT flag is enabled), e.g. MPEG-TS and HLS, and +is automatically disabled when employing the -copyts option +(unless wrapping is detected). +

+

If a timestamp discontinuity is detected whose absolute value is +greater than threshold, ffmpeg will remove the discontinuity by +decreasing/increasing the current DTS and PTS by the corresponding +delta value. +

+

The default value is 10. +

+
+
-dts_error_threshold threshold
+

Timestamp error delta threshold, expressed as a decimal number of +seconds. +

+

The timestamp correction enabled by this option is only applied to +input formats not accepting timestamp discontinuity (for which the +AVFMT_TS_DISCONT flag is not enabled). +

+

If a timestamp discontinuity is detected whose absolute value is +greater than threshold, ffmpeg will drop the PTS/DTS timestamp +value. +

+

The default value is 3600*30 (30 hours), which is arbitrarily +picked and quite conservative. +

+
+
-muxdelay seconds (output)
+

Set the maximum demux-decode delay. +

+
-muxpreload seconds (output)
+

Set the initial demux-decode delay. +

+
-streamid output-stream-index:new-value (output)
+

Assign a new stream-id value to an output stream. This option should be +specified prior to the output filename to which it applies. +For the situation where multiple output files exist, a streamid +may be reassigned to a different value. +

+

For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for +an output mpegts file: +

+
ffmpeg -i inurl -streamid 0:33 -streamid 1:36 out.ts
+
+ +
+
-bsf[:stream_specifier] bitstream_filters (input/output,per-stream)
+

Apply bitstream filters to matching streams. The filters are applied to each +packet as it is received from the demuxer (when used as an input option) or +before it is sent to the muxer (when used as an output option). +

+

bitstream_filters is a comma-separated list of bitstream filter +specifications, each of the form +

+
filter[=optname0=optval0:optname1=optval1:...]
+
+

Any of the ’,=:’ characters that are to be a part of an option value need to be +escaped with a backslash. +

+

Use the -bsfs option to get the list of bitstream filters. +

+

E.g. +

+
ffmpeg -bsf:v h264_mp4toannexb -i h264.mp4 -c:v copy -an out.h264
+
+

applies the h264_mp4toannexb bitstream filter (which converts +MP4-encapsulated H.264 stream to Annex B) to the input video stream. +

+

On the other hand, +

+
ffmpeg -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
+
+

applies the mov2textsub bitstream filter (which extracts text from MOV +subtitles) to the output subtitle stream. Note, however, that since both +examples use -c copy, it matters little whether the filters are applied +on input or output - that would change if transcoding was happening. +

+
+
-tag[:stream_specifier] codec_tag (input/output,per-stream)
+

Force a tag/fourcc for matching streams. +

+
+
-timecode hh:mm:ssSEPff
+

Specify Timecode for writing. SEP is ’:’ for non drop timecode and ’;’ +(or ’.’) for drop. +

+
ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
+
+ +
+
-filter_complex filtergraph (global)
+

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 -filter options. filtergraph is a description of +the filtergraph, as described in the “Filtergraph syntax” section of the +ffmpeg-filters manual. This option may be specified multiple times - each use +creates a new complex filtergraph. +

+

Inputs to a complex filtergraph may come from different source types, +distinguished by the format of the corresponding link label: +

    +
  • To connect an input stream, use [file_index:stream_specifier] (i.e. the +same syntax as -map). If stream_specifier matches multiple +streams, the first one will be used. For multiview video, the stream specifier +may be followed by the view specifier, see documentation for the -map +option for its syntax. + +
  • To connect a loopback decoder use [dec:dec_idx], where dec_idx is +the index of the loopback decoder to be connected to given input. For multiview +video, the decoder index may be followed by the view specifier, see +documentation for the -map option for its syntax. + +
  • To connect an output from another complex filtergraph, use its link label. E.g +the following example: + +
    +
    ffmpeg -i input.mkv \
    +  -filter_complex '[0:v]scale=size=hd1080,split=outputs=2[for_enc][orig_scaled]' \
    +  -c:v libx264 -map '[for_enc]' output.mkv \
    +  -dec 0:0 \
    +  -filter_complex '[dec:0][orig_scaled]hstack[stacked]' \
    +  -map '[stacked]' -c:v ffv1 comparison.mkv
    +
    + +

    reads an input video and +

      +
    • (line 2) uses a complex filtergraph with one input and two outputs +to scale the video to 1920x1080 and duplicate the result to both +outputs; + +
    • (line 3) encodes one scaled output with libx264 and writes the result to +output.mkv; + +
    • (line 4) decodes this encoded stream with a loopback decoder; + +
    • (line 5) places the output of the loopback decoder (i.e. the +libx264-encoded video) side by side with the scaled original input; + +
    • (line 6) combined video is then losslessly encoded and written into +comparison.mkv. + +
    + +

    Note that the two filtergraphs cannot be combined into one, because then there +would be a cycle in the transcoding pipeline (filtergraph output goes to +encoding, from there to decoding, then back to the same graph), and such cycles +are not allowed. +

    +
+ +

An unlabeled input will be connected to the first unused input stream of the +matching type. +

+

Output link labels are referred to with -map. Unlabeled outputs are +added to the first output file. +

+

Note that with this option it is possible to use only lavfi sources without +normal input files. +

+

For example, to overlay an image over video +

+
ffmpeg -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
+'[out]' out.mkv
+
+

Here [0:v] refers to the first video stream in the first input file, +which is linked to the first (main) input of the overlay filter. Similarly the +first video stream in the second input is linked to the second (overlay) input +of overlay. +

+

Assuming there is only one video stream in each input file, we can omit input +labels, so the above is equivalent to +

+
ffmpeg -i video.mkv -i image.png -filter_complex 'overlay[out]' -map
+'[out]' out.mkv
+
+ +

Furthermore we can omit the output label and the single output from the filter +graph will be added to the output file automatically, so we can simply write +

+
ffmpeg -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
+
+ +

As a special exception, you can use a bitmap subtitle stream as input: it +will be converted into a video with the same size as the largest video in +the file, or 720x576 if no video is present. Note that this is an +experimental and temporary solution. It will be removed once libavfilter has +proper support for subtitles. +

+

For example, to hardcode subtitles on top of a DVB-T recording stored in +MPEG-TS format, delaying the subtitles by 1 second: +

+
ffmpeg -i input.ts -filter_complex \
+  '[#0x2ef] setpts=PTS+1/TB [sub] ; [#0x2d0] [sub] overlay' \
+  -sn -map '#0x2dc' output.mkv
+
+

(0x2d0, 0x2dc and 0x2ef are the MPEG-TS PIDs of respectively the video, +audio and subtitles streams; 0:0, 0:3 and 0:7 would have worked too) +

+

To generate 5 seconds of pure red video using lavfi color source: +

+
ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv
+
+ +
+
-filter_complex_threads nb_threads (global)
+

Defines how many threads are used to process a filter_complex graph. +Similar to filter_threads but used for -filter_complex graphs only. +The default is the number of available CPUs. +

+
+
-lavfi filtergraph (global)
+

Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or +outputs. Equivalent to -filter_complex. +

+
+
-accurate_seek (input)
+

This option enables or disables accurate seeking in input files with the +-ss option. It is enabled by default, so seeking is accurate when +transcoding. Use -noaccurate_seek to disable it, which may be useful +e.g. when copying some streams and transcoding the others. +

+
+
-seek_timestamp (input)
+

This option enables or disables seeking by timestamp in input files with the +-ss option. It is disabled by default. If enabled, the argument +to the -ss option is considered an actual timestamp, and is not +offset by the start time of the file. This matters only for files which do +not start from timestamp 0, such as transport streams. +

+
+
-thread_queue_size size (input/output)
+

For input, this option sets the maximum number of queued packets when reading +from the file or device. With low latency / high rate live streams, packets may +be discarded if they are not read in a timely manner; setting this value can +force ffmpeg to use a separate input thread and read packets as soon as they +arrive. By default ffmpeg only does this if multiple inputs are specified. +

+

For output, this option specified the maximum number of packets that may be +queued to each muxing thread. +

+
+
-sdp_file file (global)
+

Print sdp information for an output stream to file. +This allows dumping sdp information when at least one output isn’t an +rtp stream. (Requires at least one of the output formats to be rtp). +

+
+
-discard (input)
+

Allows discarding specific streams or frames from streams. +Any input stream can be fully discarded, using value all whereas +selective discarding of frames from a stream occurs at the demuxer +and is not supported by all demuxers. +

+
+
none
+

Discard no frame. +

+
+
default
+

Default, which discards no frames. +

+
+
noref
+

Discard all non-reference frames. +

+
+
bidir
+

Discard all bidirectional frames. +

+
+
nokey
+

Discard all frames excepts keyframes. +

+
+
all
+

Discard all frames. +

+
+ +
+
-abort_on flags (global)
+

Stop and abort on various conditions. The following flags are available: +

+
+
empty_output
+

No packets were passed to the muxer, the output is empty. +

+
empty_output_stream
+

No packets were passed to the muxer in some of the output streams. +

+
+ +
+
-max_error_rate (global)
+

Set fraction of decoding frame failures across all inputs which when crossed +ffmpeg will return exit code 69. Crossing this threshold does not terminate +processing. Range is a floating-point number between 0 to 1. Default is 2/3. +

+
+
-xerror (global)
+

Stop and exit on error +

+
+
-max_muxing_queue_size packets (output,per-stream)
+

When transcoding audio and/or video streams, ffmpeg will not begin writing into +the output until it has one packet for each such stream. While waiting for that +to happen, packets for other streams are buffered. This option sets the size of +this buffer, in packets, for the matching output stream. +

+

The default value of this option should be high enough for most uses, so only +touch this option if you are sure that you need it. +

+
+
-muxing_queue_data_threshold bytes (output,per-stream)
+

This is a minimum threshold until which the muxing queue size is not taken into +account. Defaults to 50 megabytes per stream, and is based on the overall size +of packets passed to the muxer. +

+
+
-auto_conversion_filters (global)
+

Enable automatically inserting format conversion filters in all filter +graphs, including those defined by -vf, -af, +-filter_complex and -lavfi. If filter format negotiation +requires a conversion, the initialization of the filters will fail. +Conversions can still be performed by inserting the relevant conversion +filter (scale, aresample) in the graph. +On by default, to explicitly disable it you need to specify +-noauto_conversion_filters. +

+
+
-bits_per_raw_sample[:stream_specifier] value (output,per-stream)
+

Declare the number of bits per raw sample in the given output stream to be +value. Note that this option sets the information provided to the +encoder/muxer, it does not change the stream to conform to this value. Setting +values that do not match the stream properties may result in encoding failures +or invalid output files. +

+
+
-stats_enc_pre[:stream_specifier] path (output,per-stream)
+
-stats_enc_post[:stream_specifier] path (output,per-stream)
+
-stats_mux_pre[:stream_specifier] path (output,per-stream)
+

Write per-frame encoding information about the matching streams into the file +given by path. +

+

-stats_enc_pre writes information about raw video or audio frames right +before they are sent for encoding, while -stats_enc_post writes +information about encoded packets as they are received from the encoder. +-stats_mux_pre writes information about packets just as they are about to +be sent to the muxer. Every frame or packet produces one line in the specified +file. The format of this line is controlled by -stats_enc_pre_fmt / +-stats_enc_post_fmt / -stats_mux_pre_fmt. +

+

When stats for multiple streams are written into a single file, the lines +corresponding to different streams will be interleaved. The precise order of +this interleaving is not specified and not guaranteed to remain stable between +different invocations of the program, even with the same options. +

+
+
-stats_enc_pre_fmt[:stream_specifier] format_spec (output,per-stream)
+
-stats_enc_post_fmt[:stream_specifier] format_spec (output,per-stream)
+
-stats_mux_pre_fmt[:stream_specifier] format_spec (output,per-stream)
+

Specify the format for the lines written with -stats_enc_pre / +-stats_enc_post / -stats_mux_pre. +

+

format_spec is a string that may contain directives of the form +{fmt}. format_spec is backslash-escaped — use \{, \}, and \\ +to write a literal {, }, or \, respectively, into the output. +

+

The directives given with fmt may be one of the following: +

+
fidx
+

Index of the output file. +

+
+
sidx
+

Index of the output stream in the file. +

+
+
n
+

Frame number. Pre-encoding: number of frames sent to the encoder so far. +Post-encoding: number of packets received from the encoder so far. +Muxing: number of packets submitted to the muxer for this stream so far. +

+
+
ni
+

Input frame number. Index of the input frame (i.e. output by a decoder) that +corresponds to this output frame or packet. -1 if unavailable. +

+
+
tb
+

Timebase in which this frame/packet’s timestamps are expressed, as a rational +number num/den. Note that encoder and muxer may use different timebases. +

+
+
tbi
+

Timebase for ptsi, as a rational number num/den. Available when +ptsi is available, 0/1 otherwise. +

+
+
pts
+

Presentation timestamp of the frame or packet, as an integer. Should be +multiplied by the timebase to compute presentation time. +

+
+
ptsi
+

Presentation timestamp of the input frame (see ni), as an integer. Should +be multiplied by tbi to compute presentation time. Printed as +(2^63 - 1 = 9223372036854775807) when not available. +

+
+
t
+

Presentation time of the frame or packet, as a decimal number. Equal to +pts multiplied by tb. +

+
+
ti
+

Presentation time of the input frame (see ni), as a decimal number. Equal +to ptsi multiplied by tbi. Printed as inf when not available. +

+
+
dts (packet)
+

Decoding timestamp of the packet, as an integer. Should be multiplied by the +timebase to compute presentation time. +

+
+
dt (packet)
+

Decoding time of the frame or packet, as a decimal number. Equal to +dts multiplied by tb. +

+
+
sn (frame,audio)
+

Number of audio samples sent to the encoder so far. +

+
+
samp (frame,audio)
+

Number of audio samples in the frame. +

+
+
size (packet)
+

Size of the encoded packet in bytes. +

+
+
br (packet)
+

Current bitrate in bits per second. +

+
+
abr (packet)
+

Average bitrate for the whole stream so far, in bits per second, -1 if it cannot +be determined at this point. +

+
+
key (packet)
+

Character ’K’ if the packet contains a keyframe, character ’N’ otherwise. +

+
+ +

Directives tagged with packet may only be used with +-stats_enc_post_fmt and -stats_mux_pre_fmt. +

+

Directives tagged with frame may only be used with +-stats_enc_pre_fmt. +

+

Directives tagged with audio may only be used with audio streams. +

+

The default format strings are: +

+
pre-encoding
+

{fidx} {sidx} {n} {t} +

+
post-encoding
+

{fidx} {sidx} {n} {t} +

+
+

In the future, new items may be added to the end of the default formatting +strings. Users who depend on the format staying exactly the same, should +prescribe it manually. +

+

Note that stats for different streams written into the same file may have +different formats. +

+
+
+ + +

5.12 Preset files

+

A preset file contains a sequence of option=value pairs, +one for each line, specifying a sequence of options which would be +awkward to specify on the command line. Lines starting with the hash +(’#’) character are ignored and are used to provide comments. Check +the presets directory in the FFmpeg source tree for examples. +

+

There are two types of preset files: ffpreset and avpreset files. +

+ +

5.12.1 ffpreset files

+

ffpreset files are specified with the vpre, apre, +spre, and fpre options. The fpre option takes the +filename of the preset instead of a preset name as input and can be +used for any kind of codec. For the vpre, apre, and +spre options, the options specified in a preset file are +applied to the currently selected codec of the same type as the preset +option. +

+

The argument passed to the vpre, apre, and spre +preset options identifies the preset file to use according to the +following rules: +

+

First ffmpeg searches for a file named arg.ffpreset in the +directories $FFMPEG_DATADIR (if set), and $HOME/.ffmpeg, and in +the datadir defined at configuration time (usually PREFIX/share/ffmpeg) +or in a ffpresets folder along the executable on win32, +in that order. For example, if the argument is libvpx-1080p, it will +search for the file libvpx-1080p.ffpreset. +

+

If no such file is found, then ffmpeg will search for a file named +codec_name-arg.ffpreset in the above-mentioned +directories, where codec_name is the name of the codec to which +the preset file options will be applied. For example, if you select +the video codec with -vcodec libvpx and use -vpre 1080p, +then it will search for the file libvpx-1080p.ffpreset. +

+ +

5.12.2 avpreset files

+

avpreset files are specified with the pre option. They work similar to +ffpreset files, but they only allow encoder- specific options. Therefore, an +option=value pair specifying an encoder cannot be used. +

+

When the pre option is specified, ffmpeg will look for files with the +suffix .avpreset in the directories $AVCONV_DATADIR (if set), and +$HOME/.avconv, and in the datadir defined at configuration time (usually +PREFIX/share/ffmpeg), in that order. +

+

First ffmpeg searches for a file named codec_name-arg.avpreset in +the above-mentioned directories, where codec_name is the name of the codec +to which the preset file options will be applied. For example, if you select the +video codec with -vcodec libvpx and use -pre 1080p, then it will +search for the file libvpx-1080p.avpreset. +

+

If no such file is found, then ffmpeg will search for a file named +arg.avpreset in the same directories. +

+ +

5.13 vstats file format

+

The -vstats and -vstats_file options enable generation of a file +containing statistics about the generated video outputs. +

+

The -vstats_version option controls the format version of the generated +file. +

+

With version 1 the format is: +

+
frame= FRAME q= FRAME_QUALITY PSNR= PSNR f_size= FRAME_SIZE s_size= STREAM_SIZEkB time= TIMESTAMP br= BITRATEkbits/s avg_br= AVERAGE_BITRATEkbits/s
+
+ +

With version 2 the format is: +

+
out= OUT_FILE_INDEX st= OUT_FILE_STREAM_INDEX frame= FRAME_NUMBER q= FRAME_QUALITYf PSNR= PSNR f_size= FRAME_SIZE s_size= STREAM_SIZEkB time= TIMESTAMP br= BITRATEkbits/s avg_br= AVERAGE_BITRATEkbits/s
+
+ +

The value corresponding to each key is described below: +

+
avg_br
+

average bitrate expressed in Kbits/s +

+
+
br
+

bitrate expressed in Kbits/s +

+
+
frame
+

number of encoded frame +

+
+
out
+

out file index +

+
+
PSNR
+

Peak Signal to Noise Ratio +

+
+
q
+

quality of the frame +

+
+
f_size
+

encoded packet size expressed as number of bytes +

+
+
s_size
+

stream size expressed in KiB +

+
+
st
+

out file stream index +

+
+
time
+

time of the packet +

+
+
type
+

picture type +

+
+ +

See also the -stats_enc options for an alternative way +to show encoding statistics. +

+ + +

6 Examples

+ + +

6.1 Video and Audio grabbing

+ +

If you specify the input format and device then ffmpeg can grab video +and audio directly. +

+
+
ffmpeg -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
+
+ +

Or with an ALSA audio source (mono input, card id 1) instead of OSS: +

+
ffmpeg -f alsa -ac 1 -i hw:1 -f video4linux2 -i /dev/video0 /tmp/out.mpg
+
+ +

Note that you must activate the right video source and channel before +launching ffmpeg with any TV viewer such as +xawtv by Gerd Knorr. You also +have to set the audio recording levels correctly with a +standard mixer. +

+ +

6.2 X11 grabbing

+ +

Grab the X11 display with ffmpeg via +

+
+
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0 /tmp/out.mpg
+
+ +

0.0 is display.screen number of your X11 server, same as +the DISPLAY environment variable. +

+
+
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0+10,20 /tmp/out.mpg
+
+ +

0.0 is display.screen number of your X11 server, same as the DISPLAY environment +variable. 10 is the x-offset and 20 the y-offset for the grabbing. +

+ +

6.3 Video and Audio file format conversion

+ +

Any supported file format and protocol can serve as input to ffmpeg: +

+

Examples: +

    +
  • You can use YUV files as input: + +
    +
    ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
    +
    + +

    It will use the files: +

    +
    /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
    +/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
    +
    + +

    The Y files use twice the resolution of the U and V files. They are +raw files, without header. They can be generated by all decent video +decoders. You must specify the size of the image with the -s option +if ffmpeg cannot guess it. +

    +
  • You can input from a raw YUV420P file: + +
    +
    ffmpeg -i /tmp/test.yuv /tmp/out.avi
    +
    + +

    test.yuv is a file containing raw YUV planar data. Each frame is composed +of the Y plane followed by the U and V planes at half vertical and +horizontal resolution. +

    +
  • You can output to a raw YUV420P file: + +
    +
    ffmpeg -i mydivx.avi hugefile.yuv
    +
    + +
  • You can set several input files and output files: + +
    +
    ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
    +
    + +

    Converts the audio file a.wav and the raw YUV video file a.yuv +to MPEG file a.mpg. +

    +
  • You can also do audio and video conversions at the same time: + +
    +
    ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
    +
    + +

    Converts a.wav to MPEG audio at 22050 Hz sample rate. +

    +
  • You can encode to several formats at the same time and define a +mapping from input stream to output streams: + +
    +
    ffmpeg -i /tmp/a.wav -map 0:a -b:a 64k /tmp/a.mp2 -map 0:a -b:a 128k /tmp/b.mp2
    +
    + +

    Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. ’-map +file:index’ specifies which input stream is used for each output +stream, in the order of the definition of output streams. +

    +
  • You can transcode decrypted VOBs: + +
    +
    ffmpeg -i snatch_1.vob -f avi -c:v mpeg4 -b:v 800k -g 300 -bf 2 -c:a libmp3lame -b:a 128k snatch.avi
    +
    + +

    This is a typical DVD ripping example; the input is a VOB file, the +output an AVI file with MPEG-4 video and MP3 audio. Note that in this +command we use B-frames so the MPEG-4 stream is DivX5 compatible, and +GOP size is 300 which means one intra frame every 10 seconds for 29.97fps +input video. Furthermore, the audio stream is MP3-encoded so you need +to enable LAME support by passing --enable-libmp3lame to configure. +The mapping is particularly useful for DVD transcoding +to get the desired audio language. +

    +

    NOTE: To see the supported input formats, use ffmpeg -demuxers. +

    +
  • You can extract images from a video, or create a video from many images: + +

    For extracting images from a video: +

    +
    ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
    +
    + +

    This will extract one video frame per second from the video and will +output them in files named foo-001.jpeg, foo-002.jpeg, +etc. Images will be rescaled to fit the new WxH values. +

    +

    If you want to extract just a limited number of frames, you can use the +above command in combination with the -frames:v or -t option, +or in combination with -ss to start extracting from a certain point in time. +

    +

    For creating a video from many images: +

    +
    ffmpeg -f image2 -framerate 12 -i foo-%03d.jpeg -s WxH foo.avi
    +
    + +

    The syntax foo-%03d.jpeg specifies to use a decimal number +composed of three digits padded with zeroes to express the sequence +number. It is the same syntax supported by the C printf function, but +only formats accepting a normal integer are suitable. +

    +

    When importing an image sequence, -i also supports expanding +shell-like wildcard patterns (globbing) internally, by selecting the +image2-specific -pattern_type glob option. +

    +

    For example, for creating a video from filenames matching the glob pattern +foo-*.jpeg: +

    +
    ffmpeg -f image2 -pattern_type glob -framerate 12 -i 'foo-*.jpeg' -s WxH foo.avi
    +
    + +
  • You can put many streams of the same type in the output: + +
    +
    ffmpeg -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut
    +
    + +

    The resulting output file test12.nut will contain the first four streams +from the input files in reverse order. +

    +
  • To force CBR video output: +
    +
    ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
    +
    + +
  • The four options lmin, lmax, mblmin and mblmax use ’lambda’ units, +but you may use the QP2LAMBDA constant to easily convert from ’q’ units: +
    +
    ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
    +
    + +
+ + +

7 Syntax

+ +

This section documents the syntax and formats employed by the FFmpeg +libraries and tools. +

+ +

7.1 Quoting and escaping

+ +

FFmpeg adopts the following quoting and escaping mechanism, unless +explicitly specified. The following rules are applied: +

+
    +
  • ‘'’ and ‘\’ 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. + +
  • A special character is escaped by prefixing it with a ‘\’. + +
  • All characters enclosed between ‘''’ are included literally in the +parsed string. The quote character ‘'’ itself cannot be quoted, +so you may need to close the quote and escape it. + +
  • Leading and trailing whitespaces, unless escaped or quoted, are +removed from the parsed string. +
+ +

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 av_get_token defined in +libavutil/avstring.h can be used to parse a token quoted or +escaped according to the rules defined above. +

+

The tool tools/ffescape in the FFmpeg source tree can be used +to automatically quote or escape a string in a script. +

+ +

7.1.1 Examples

+ +
    +
  • Escape the string Crime d'Amour containing the ' special +character: +
    +
    Crime d\'Amour
    +
    + +
  • The string above contains a quote, so the ' needs to be escaped +when quoting it: +
    +
    'Crime d'\''Amour'
    +
    + +
  • Include leading or trailing whitespaces using quoting: +
    +
    '  this string starts and ends with whitespaces  '
    +
    + +
  • Escaping and quoting can be mixed together: +
    +
    ' The string '\'string\'' is a string '
    +
    + +
  • To include a literal ‘\’ you can use either escaping or quoting: +
    +
    'c:\foo' can be written as c:\\foo
    +
    +
+ + +

7.2 Date

+ +

The accepted syntax is: +

+
[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
+now
+
+ +

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. +

+ +

7.3 Time duration

+ +

There are two accepted syntaxes for expressing time duration. +

+
+
[-][HH:]MM:SS[.m...]
+
+ +

HH expresses the number of hours, MM the number of minutes +for a maximum of 2 digits, and SS the number of seconds for a +maximum of 2 digits. The m at the end expresses decimal value for +SS. +

+

or +

+
+
[-]S+[.m...][s|ms|us]
+
+ +

S expresses the number of seconds, with the optional decimal part +m. The optional literal suffixes ‘s’, ‘ms’ or ‘us’ +indicate to interpret the value as seconds, milliseconds or microseconds, +respectively. +

+

In both expressions, the optional ‘-’ indicates negative duration. +

+ +

7.3.1 Examples

+ +

The following examples are all valid time duration: +

+
+
‘55’
+

55 seconds +

+
+
‘0.2’
+

0.2 seconds +

+
+
‘200ms’
+

200 milliseconds, that’s 0.2s +

+
+
‘200000us’
+

200000 microseconds, that’s 0.2s +

+
+
‘12:03:45’
+

12 hours, 03 minutes and 45 seconds +

+
+
‘23.189’
+

23.189 seconds +

+
+ + +

7.4 Video size

+

Specify the size of the sourced video, it may be a string of the form +widthxheight, or the name of a size abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

720x480 +

+
‘pal’
+

720x576 +

+
‘qntsc’
+

352x240 +

+
‘qpal’
+

352x288 +

+
‘sntsc’
+

640x480 +

+
‘spal’
+

768x576 +

+
‘film’
+

352x240 +

+
‘ntsc-film’
+

352x240 +

+
‘sqcif’
+

128x96 +

+
‘qcif’
+

176x144 +

+
‘cif’
+

352x288 +

+
‘4cif’
+

704x576 +

+
‘16cif’
+

1408x1152 +

+
‘qqvga’
+

160x120 +

+
‘qvga’
+

320x240 +

+
‘vga’
+

640x480 +

+
‘svga’
+

800x600 +

+
‘xga’
+

1024x768 +

+
‘uxga’
+

1600x1200 +

+
‘qxga’
+

2048x1536 +

+
‘sxga’
+

1280x1024 +

+
‘qsxga’
+

2560x2048 +

+
‘hsxga’
+

5120x4096 +

+
‘wvga’
+

852x480 +

+
‘wxga’
+

1366x768 +

+
‘wsxga’
+

1600x1024 +

+
‘wuxga’
+

1920x1200 +

+
‘woxga’
+

2560x1600 +

+
‘wqsxga’
+

3200x2048 +

+
‘wquxga’
+

3840x2400 +

+
‘whsxga’
+

6400x4096 +

+
‘whuxga’
+

7680x4800 +

+
‘cga’
+

320x200 +

+
‘ega’
+

640x350 +

+
‘hd480’
+

852x480 +

+
‘hd720’
+

1280x720 +

+
‘hd1080’
+

1920x1080 +

+
‘2k’
+

2048x1080 +

+
‘2kflat’
+

1998x1080 +

+
‘2kscope’
+

2048x858 +

+
‘4k’
+

4096x2160 +

+
‘4kflat’
+

3996x2160 +

+
‘4kscope’
+

4096x1716 +

+
‘nhd’
+

640x360 +

+
‘hqvga’
+

240x160 +

+
‘wqvga’
+

400x240 +

+
‘fwqvga’
+

432x240 +

+
‘hvga’
+

480x320 +

+
‘qhd’
+

960x540 +

+
‘2kdci’
+

2048x1080 +

+
‘4kdci’
+

4096x2160 +

+
‘uhd2160’
+

3840x2160 +

+
‘uhd4320’
+

7680x4320 +

+
+ + +

7.5 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 +frame_rate_num/frame_rate_den, an integer number, a float +number or a valid video frame rate abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

30000/1001 +

+
‘pal’
+

25/1 +

+
‘qntsc’
+

30000/1001 +

+
‘qpal’
+

25/1 +

+
‘sntsc’
+

30000/1001 +

+
‘spal’
+

25/1 +

+
‘film’
+

24/1 +

+
‘ntsc-film’
+

24000/1001 +

+
+ + +

7.6 Ratio

+ +

A ratio can be expressed as an expression, or in the form +numerator: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. +

+ +

7.7 Color

+ +

It can be the name of a color as defined below (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’ or ‘0.0’ means completely +transparent, ‘0xff’ or ‘1.0’ completely opaque). If the alpha +component is not specified then ‘0xff’ is assumed. +

+

The string ‘random’ will result in a random color. +

+

The following names of colors are recognized: +

+
‘AliceBlue’
+

0xF0F8FF +

+
‘AntiqueWhite’
+

0xFAEBD7 +

+
‘Aqua’
+

0x00FFFF +

+
‘Aquamarine’
+

0x7FFFD4 +

+
‘Azure’
+

0xF0FFFF +

+
‘Beige’
+

0xF5F5DC +

+
‘Bisque’
+

0xFFE4C4 +

+
‘Black’
+

0x000000 +

+
‘BlanchedAlmond’
+

0xFFEBCD +

+
‘Blue’
+

0x0000FF +

+
‘BlueViolet’
+

0x8A2BE2 +

+
‘Brown’
+

0xA52A2A +

+
‘BurlyWood’
+

0xDEB887 +

+
‘CadetBlue’
+

0x5F9EA0 +

+
‘Chartreuse’
+

0x7FFF00 +

+
‘Chocolate’
+

0xD2691E +

+
‘Coral’
+

0xFF7F50 +

+
‘CornflowerBlue’
+

0x6495ED +

+
‘Cornsilk’
+

0xFFF8DC +

+
‘Crimson’
+

0xDC143C +

+
‘Cyan’
+

0x00FFFF +

+
‘DarkBlue’
+

0x00008B +

+
‘DarkCyan’
+

0x008B8B +

+
‘DarkGoldenRod’
+

0xB8860B +

+
‘DarkGray’
+

0xA9A9A9 +

+
‘DarkGreen’
+

0x006400 +

+
‘DarkKhaki’
+

0xBDB76B +

+
‘DarkMagenta’
+

0x8B008B +

+
‘DarkOliveGreen’
+

0x556B2F +

+
‘Darkorange’
+

0xFF8C00 +

+
‘DarkOrchid’
+

0x9932CC +

+
‘DarkRed’
+

0x8B0000 +

+
‘DarkSalmon’
+

0xE9967A +

+
‘DarkSeaGreen’
+

0x8FBC8F +

+
‘DarkSlateBlue’
+

0x483D8B +

+
‘DarkSlateGray’
+

0x2F4F4F +

+
‘DarkTurquoise’
+

0x00CED1 +

+
‘DarkViolet’
+

0x9400D3 +

+
‘DeepPink’
+

0xFF1493 +

+
‘DeepSkyBlue’
+

0x00BFFF +

+
‘DimGray’
+

0x696969 +

+
‘DodgerBlue’
+

0x1E90FF +

+
‘FireBrick’
+

0xB22222 +

+
‘FloralWhite’
+

0xFFFAF0 +

+
‘ForestGreen’
+

0x228B22 +

+
‘Fuchsia’
+

0xFF00FF +

+
‘Gainsboro’
+

0xDCDCDC +

+
‘GhostWhite’
+

0xF8F8FF +

+
‘Gold’
+

0xFFD700 +

+
‘GoldenRod’
+

0xDAA520 +

+
‘Gray’
+

0x808080 +

+
‘Green’
+

0x008000 +

+
‘GreenYellow’
+

0xADFF2F +

+
‘HoneyDew’
+

0xF0FFF0 +

+
‘HotPink’
+

0xFF69B4 +

+
‘IndianRed’
+

0xCD5C5C +

+
‘Indigo’
+

0x4B0082 +

+
‘Ivory’
+

0xFFFFF0 +

+
‘Khaki’
+

0xF0E68C +

+
‘Lavender’
+

0xE6E6FA +

+
‘LavenderBlush’
+

0xFFF0F5 +

+
‘LawnGreen’
+

0x7CFC00 +

+
‘LemonChiffon’
+

0xFFFACD +

+
‘LightBlue’
+

0xADD8E6 +

+
‘LightCoral’
+

0xF08080 +

+
‘LightCyan’
+

0xE0FFFF +

+
‘LightGoldenRodYellow’
+

0xFAFAD2 +

+
‘LightGreen’
+

0x90EE90 +

+
‘LightGrey’
+

0xD3D3D3 +

+
‘LightPink’
+

0xFFB6C1 +

+
‘LightSalmon’
+

0xFFA07A +

+
‘LightSeaGreen’
+

0x20B2AA +

+
‘LightSkyBlue’
+

0x87CEFA +

+
‘LightSlateGray’
+

0x778899 +

+
‘LightSteelBlue’
+

0xB0C4DE +

+
‘LightYellow’
+

0xFFFFE0 +

+
‘Lime’
+

0x00FF00 +

+
‘LimeGreen’
+

0x32CD32 +

+
‘Linen’
+

0xFAF0E6 +

+
‘Magenta’
+

0xFF00FF +

+
‘Maroon’
+

0x800000 +

+
‘MediumAquaMarine’
+

0x66CDAA +

+
‘MediumBlue’
+

0x0000CD +

+
‘MediumOrchid’
+

0xBA55D3 +

+
‘MediumPurple’
+

0x9370D8 +

+
‘MediumSeaGreen’
+

0x3CB371 +

+
‘MediumSlateBlue’
+

0x7B68EE +

+
‘MediumSpringGreen’
+

0x00FA9A +

+
‘MediumTurquoise’
+

0x48D1CC +

+
‘MediumVioletRed’
+

0xC71585 +

+
‘MidnightBlue’
+

0x191970 +

+
‘MintCream’
+

0xF5FFFA +

+
‘MistyRose’
+

0xFFE4E1 +

+
‘Moccasin’
+

0xFFE4B5 +

+
‘NavajoWhite’
+

0xFFDEAD +

+
‘Navy’
+

0x000080 +

+
‘OldLace’
+

0xFDF5E6 +

+
‘Olive’
+

0x808000 +

+
‘OliveDrab’
+

0x6B8E23 +

+
‘Orange’
+

0xFFA500 +

+
‘OrangeRed’
+

0xFF4500 +

+
‘Orchid’
+

0xDA70D6 +

+
‘PaleGoldenRod’
+

0xEEE8AA +

+
‘PaleGreen’
+

0x98FB98 +

+
‘PaleTurquoise’
+

0xAFEEEE +

+
‘PaleVioletRed’
+

0xD87093 +

+
‘PapayaWhip’
+

0xFFEFD5 +

+
‘PeachPuff’
+

0xFFDAB9 +

+
‘Peru’
+

0xCD853F +

+
‘Pink’
+

0xFFC0CB +

+
‘Plum’
+

0xDDA0DD +

+
‘PowderBlue’
+

0xB0E0E6 +

+
‘Purple’
+

0x800080 +

+
‘Red’
+

0xFF0000 +

+
‘RosyBrown’
+

0xBC8F8F +

+
‘RoyalBlue’
+

0x4169E1 +

+
‘SaddleBrown’
+

0x8B4513 +

+
‘Salmon’
+

0xFA8072 +

+
‘SandyBrown’
+

0xF4A460 +

+
‘SeaGreen’
+

0x2E8B57 +

+
‘SeaShell’
+

0xFFF5EE +

+
‘Sienna’
+

0xA0522D +

+
‘Silver’
+

0xC0C0C0 +

+
‘SkyBlue’
+

0x87CEEB +

+
‘SlateBlue’
+

0x6A5ACD +

+
‘SlateGray’
+

0x708090 +

+
‘Snow’
+

0xFFFAFA +

+
‘SpringGreen’
+

0x00FF7F +

+
‘SteelBlue’
+

0x4682B4 +

+
‘Tan’
+

0xD2B48C +

+
‘Teal’
+

0x008080 +

+
‘Thistle’
+

0xD8BFD8 +

+
‘Tomato’
+

0xFF6347 +

+
‘Turquoise’
+

0x40E0D0 +

+
‘Violet’
+

0xEE82EE +

+
‘Wheat’
+

0xF5DEB3 +

+
‘White’
+

0xFFFFFF +

+
‘WhiteSmoke’
+

0xF5F5F5 +

+
‘Yellow’
+

0xFFFF00 +

+
‘YellowGreen’
+

0x9ACD32 +

+
+ + +

7.8 Channel Layout

+ +

A channel layout specifies the spatial disposition of the channels in +a multi-channel audio stream. To specify a channel layout, FFmpeg +makes use of a special syntax. +

+

Individual channels are identified by an id, as given by the table +below: +

+
‘FL’
+

front left +

+
‘FR’
+

front right +

+
‘FC’
+

front center +

+
‘LFE’
+

low frequency +

+
‘BL’
+

back left +

+
‘BR’
+

back right +

+
‘FLC’
+

front left-of-center +

+
‘FRC’
+

front right-of-center +

+
‘BC’
+

back center +

+
‘SL’
+

side left +

+
‘SR’
+

side right +

+
‘TC’
+

top center +

+
‘TFL’
+

top front left +

+
‘TFC’
+

top front center +

+
‘TFR’
+

top front right +

+
‘TBL’
+

top back left +

+
‘TBC’
+

top back center +

+
‘TBR’
+

top back right +

+
‘DL’
+

downmix left +

+
‘DR’
+

downmix right +

+
‘WL’
+

wide left +

+
‘WR’
+

wide right +

+
‘SDL’
+

surround direct left +

+
‘SDR’
+

surround direct right +

+
‘LFE2’
+

low frequency 2 +

+
+ +

Standard channel layout compositions can be specified by using the +following identifiers: +

+
‘mono’
+

FC +

+
‘stereo’
+

FL+FR +

+
‘2.1’
+

FL+FR+LFE +

+
‘3.0’
+

FL+FR+FC +

+
‘3.0(back)’
+

FL+FR+BC +

+
‘4.0’
+

FL+FR+FC+BC +

+
‘quad’
+

FL+FR+BL+BR +

+
‘quad(side)’
+

FL+FR+SL+SR +

+
‘3.1’
+

FL+FR+FC+LFE +

+
‘5.0’
+

FL+FR+FC+BL+BR +

+
‘5.0(side)’
+

FL+FR+FC+SL+SR +

+
‘4.1’
+

FL+FR+FC+LFE+BC +

+
‘5.1’
+

FL+FR+FC+LFE+BL+BR +

+
‘5.1(side)’
+

FL+FR+FC+LFE+SL+SR +

+
‘6.0’
+

FL+FR+FC+BC+SL+SR +

+
‘6.0(front)’
+

FL+FR+FLC+FRC+SL+SR +

+
‘3.1.2’
+

FL+FR+FC+LFE+TFL+TFR +

+
‘hexagonal’
+

FL+FR+FC+BL+BR+BC +

+
‘6.1’
+

FL+FR+FC+LFE+BC+SL+SR +

+
‘6.1’
+

FL+FR+FC+LFE+BL+BR+BC +

+
‘6.1(front)’
+

FL+FR+LFE+FLC+FRC+SL+SR +

+
‘7.0’
+

FL+FR+FC+BL+BR+SL+SR +

+
‘7.0(front)’
+

FL+FR+FC+FLC+FRC+SL+SR +

+
‘7.1’
+

FL+FR+FC+LFE+BL+BR+SL+SR +

+
‘7.1(wide)’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC +

+
‘7.1(wide-side)’
+

FL+FR+FC+LFE+FLC+FRC+SL+SR +

+
‘5.1.2’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR +

+
‘octagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR +

+
‘cube’
+

FL+FR+BL+BR+TFL+TFR+TBL+TBR +

+
‘5.1.4’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR+TBL+TBR +

+
‘7.1.2’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR +

+
‘7.1.4’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBL+TBR +

+
‘7.2.3’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBC+LFE2 +

+
‘9.1.4’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR +

+
‘9.1.6’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR+TSL+TSR +

+
‘hexadecagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR +

+
‘binaural’
+

BIL+BIR +

+
‘downmix’
+

DL+DR +

+
‘22.2’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+BC+SL+SR+TC+TFL+TFC+TFR+TBL+TBC+TBR+LFE2+TSL+TSR+BFC+BFL+BFR +

+
+ +

A custom channel layout can be specified as a sequence of terms, separated by ’+’. +Each term can be: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.), +each optionally containing a custom name after a ’@’, (e.g. ‘FL@Left’, +‘FR@Right’, ‘FC@Center’, ‘LFE@Low_Frequency’, etc.) +
+ +

A standard channel layout can be specified by the following: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.) + +
  • the name of a standard channel layout (e.g. ‘mono’, +‘stereo’, ‘4.0’, ‘quad’, ‘5.0’, etc.) + +
  • a number of channels, in decimal, followed by ’c’, yielding the default channel +layout for that number of channels (see the function +av_channel_layout_default). Note that not all channel counts have a +default layout. + +
  • a number of channels, in decimal, followed by ’C’, yielding an unknown channel +layout with the specified number of channels. Note that not all channel layout +specification strings support unknown channel layouts. + +
  • a channel layout mask, in hexadecimal starting with "0x" (see the +AV_CH_* macros in libavutil/channel_layout.h. +
+ +

Before libavutil version 53 the trailing character "c" to specify a number of +channels was optional, but now it is required, while a channel layout mask can +also be specified as a decimal number (if and only if not followed by "c" or "C"). +

+

See also the function av_channel_layout_from_string defined in +libavutil/channel_layout.h. +

+ +

8 Expression Evaluation

+ +

When evaluating an arithmetic expression, FFmpeg uses an internal +formula evaluator, implemented through the libavutil/eval.h +interface. +

+

An expression may contain unary, binary operators, constants, and +functions. +

+

Two expressions expr1 and expr2 can be combined to form +another expression "expr1;expr2". +expr1 and expr2 are evaluated in turn, and the new +expression evaluates to the value of expr2. +

+

The following binary operators are available: +, -, +*, /, ^. +

+

The following unary operators are available: +, -. +

+

Some internal variables can be used to store and load intermediary +results. They can be accessed using the ld and st +functions with an index argument varying from 0 to 9 to specify which +internal variable to access. +

+

The following functions are available: +

+
abs(x)
+

Compute absolute value of x. +

+
+
acos(x)
+

Compute arccosine of x. +

+
+
asin(x)
+

Compute arcsine of x. +

+
+
atan(x)
+

Compute arctangent of x. +

+
+
atan2(y, x)
+

Compute principal value of the arc tangent of y/x. +

+
+
between(x, min, max)
+

Return 1 if x is greater than or equal to min and lesser than or +equal to max, 0 otherwise. +

+
+
bitand(x, y)
+
bitor(x, y)
+

Compute bitwise and/or operation on x and y. +

+

The results of the evaluation of x and 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). +

+
+
ceil(expr)
+

Round the value of expression expr upwards to the nearest +integer. For example, "ceil(1.5)" is "2.0". +

+
+
clip(x, min, max)
+

Return the value of x clipped between min and max. +

+
+
cos(x)
+

Compute cosine of x. +

+
+
cosh(x)
+

Compute hyperbolic cosine of x. +

+
+
eq(x, y)
+

Return 1 if x and y are equivalent, 0 otherwise. +

+
+
exp(x)
+

Compute exponential of x (with base e, the Euler’s number). +

+
+
floor(expr)
+

Round the value of expression expr downwards to the nearest +integer. For example, "floor(-1.5)" is "-2.0". +

+
+
gauss(x)
+

Compute Gauss function of x, corresponding to +exp(-x*x/2) / sqrt(2*PI). +

+
+
gcd(x, y)
+

Return the greatest common divisor of x and y. If both x and +y are 0 or either or both are less than zero then behavior is undefined. +

+
+
gt(x, y)
+

Return 1 if x is greater than y, 0 otherwise. +

+
+
gte(x, y)
+

Return 1 if x is greater than or equal to y, 0 otherwise. +

+
+
hypot(x, y)
+

This function is similar to the C function with the same name; it returns +"sqrt(x*x + y*y)", the length of the hypotenuse of a +right triangle with sides of length x and y, or the distance of the +point (x, y) from the origin. +

+
+
if(x, y)
+

Evaluate x, and if the result is non-zero return the result of +the evaluation of y, return 0 otherwise. +

+
+
if(x, y, z)
+

Evaluate x, and if the result is non-zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
ifnot(x, y)
+

Evaluate x, and if the result is zero return the result of the +evaluation of y, return 0 otherwise. +

+
+
ifnot(x, y, z)
+

Evaluate x, and if the result is zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
isinf(x)
+

Return 1.0 if x is +/-INFINITY, 0.0 otherwise. +

+
+
isnan(x)
+

Return 1.0 if x is NAN, 0.0 otherwise. +

+
+
ld(idx)
+

Load the value of the internal variable with index idx, which was +previously stored with st(idx, expr). +The function returns the loaded value. +

+
+
lerp(x, y, z)
+

Return linear interpolation between x and y by amount of z. +

+
+
log(x)
+

Compute natural logarithm of x. +

+
+
lt(x, y)
+

Return 1 if x is lesser than y, 0 otherwise. +

+
+
lte(x, y)
+

Return 1 if x is lesser than or equal to y, 0 otherwise. +

+
+
max(x, y)
+

Return the maximum between x and y. +

+
+
min(x, y)
+

Return the minimum between x and y. +

+
+
mod(x, y)
+

Compute the remainder of division of x by y. +

+
+
not(expr)
+

Return 1.0 if expr is zero, 0.0 otherwise. +

+
+
pow(x, y)
+

Compute the power of x elevated y, it is equivalent to +"(x)^(y)". +

+
+
print(t)
+
print(t, l)
+

Print the value of expression t with loglevel l. If l is not +specified then a default log level is used. +Return the value of the expression printed. +

+
+
random(idx)
+

Return a pseudo random value between 0.0 and 1.0. idx is the +index of the internal variable used to save the seed/state, which can be +previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+

For example, to store the seed with value 42 in the internal +variable with index 0 and print a few random values: +

+
st(0,42); print(random(0)); print(random(0)); print(random(0))
+
+ +
+
randomi(idx, min, max)
+

Return a pseudo random value in the interval between min and +max. idx is the index of the internal variable which will be used to +save the seed/state, which can be previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+
+
root(expr, max)
+

Find an input value for which the function represented by expr +with argument ld(0) is 0 in the interval 0..max. +

+

The expression in expr must denote a continuous function or the +result is undefined. +

+

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 ld(0). When the expression evaluates to +0 then the corresponding input value will be returned. +

+
+
round(expr)
+

Round the value of expression expr to the nearest integer. For example, +"round(1.5)" is "2.0". +

+
+
sgn(x)
+

Compute sign of x. +

+
+
sin(x)
+

Compute sine of x. +

+
+
sinh(x)
+

Compute hyperbolic sine of x. +

+
+
sqrt(expr)
+

Compute the square root of expr. This is equivalent to +"(expr)^.5". +

+
+
squish(x)
+

Compute expression 1/(1 + exp(4*x)). +

+
+
st(idx, expr)
+

Store the value of the expression expr in an internal +variable. idx specifies the index 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. +

+

The stored value can be retrieved with ld(var). +

+

Note: variables are currently not shared between expressions. +

+
+
tan(x)
+

Compute tangent of x. +

+
+
tanh(x)
+

Compute hyperbolic tangent of x. +

+
+
taylor(expr, x)
+
taylor(expr, x, idx)
+

Evaluate a Taylor series at x, given an expression representing +the ld(idx)-th derivative of a function at 0. +

+

When the series does not converge the result is undefined. +

+

ld(idx) is used to represent the derivative order in expr, +which means that the given expression will be evaluated multiple times +with various input values that the expression can access through +ld(idx). If idx is not specified then 0 is assumed. +

+

Note, when you have the derivatives at y instead of 0, +taylor(expr, x-y) can be used. +

+
+
time(0)
+

Return the current (wallclock) time in seconds. +

+
+
trunc(expr)
+

Round the value of expression expr towards zero to the nearest +integer. For example, "trunc(-1.5)" is "-1.0". +

+
+
while(cond, expr)
+

Evaluate expression expr while the expression cond is +non-zero, and returns the value of the last expr evaluation, or +NAN if cond was always false. +

+
+ +

The following constants are available: +

+
PI
+

area of the unit disc, approximately 3.14 +

+
E
+

exp(1) (Euler’s number), approximately 2.718 +

+
PHI
+

golden ratio (1+sqrt(5))/2, approximately 1.618 +

+
+ +

Assuming that an expression is considered "true" if it has a non-zero +value, note that: +

+

* works like AND +

+

+ works like OR +

+

For example the construct: +

+
if (A AND B) then C
+
+

is equivalent to: +

+
if(A*B, C)
+
+ +

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. +

+
y
+

10^-24 / 2^-80 +

+
z
+

10^-21 / 2^-70 +

+
a
+

10^-18 / 2^-60 +

+
f
+

10^-15 / 2^-50 +

+
p
+

10^-12 / 2^-40 +

+
n
+

10^-9 / 2^-30 +

+
u
+

10^-6 / 2^-20 +

+
m
+

10^-3 / 2^-10 +

+
c
+

10^-2 +

+
d
+

10^-1 +

+
h
+

10^2 +

+
k
+

10^3 / 2^10 +

+
K
+

10^3 / 2^10 +

+
M
+

10^6 / 2^20 +

+
G
+

10^9 / 2^30 +

+
T
+

10^12 / 2^40 +

+
P
+

10^15 / 2^50 +

+
E
+

10^18 / 2^60 +

+
Z
+

10^21 / 2^70 +

+
Y
+

10^24 / 2^80 +

+
+ + +

9 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 nonsensical 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVCodecContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follow: +

+
+
b integer (encoding,audio,video)
+

Set bitrate in bits/s. Default value is 200K. +

+
+
ab integer (encoding,audio)
+

Set audio bitrate (in bits/s). Default value is 128K. +

+
+
bt integer (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. +

+
+
flags flags (decoding/encoding,audio,video,subtitles)
+

Set generic flags. +

+

Possible values: +

+
‘mv4’
+

Use four motion vector by macroblock (mpeg4). +

+
‘qpel’
+

Use 1/4 pel motion compensation. +

+
‘loop’
+

Use loop filter. +

+
‘qscale’
+

Use fixed qscale. +

+
‘pass1’
+

Use internal 2pass ratecontrol in first pass mode. +

+
‘pass2’
+

Use internal 2pass ratecontrol in second pass mode. +

+
‘gray’
+

Only decode/encode grayscale. +

+
‘psnr’
+

Set error[?] variables during encoding. +

+
‘truncated’
+

Input bitstream might be randomly truncated. +

+
‘drop_changed’
+

Don’t output frames whose parameters differ from first decoded frame in stream. +Error AVERROR_INPUT_CHANGED is returned when a frame is dropped. +

+
+
‘ildct’
+

Use interlaced DCT. +

+
‘low_delay’
+

Force low delay. +

+
‘global_header’
+

Place global headers in extradata instead of every keyframe. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. (except (I)DCT). +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘aic’
+

Apply H263 advanced intra coding / mpeg4 ac prediction. +

+
‘ilme’
+

Apply interlaced motion estimation. +

+
‘cgop’
+

Use closed gop. +

+
‘output_corrupt’
+

Output even potentially corrupted frames. +

+
+ +
+
time_base 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 / frame_rate and timestamp increments should be +identically 1. +

+
+
g integer (encoding,video)
+

Set the group of picture (GOP) size. Default value is 12. +

+
+
ar integer (decoding/encoding,audio)
+

Set audio sampling rate (in Hz). +

+
+
ac integer (decoding/encoding,audio)
+

Set number of audio channels. +

+
+
cutoff integer (encoding,audio)
+

Set cutoff bandwidth. (Supported only by selected encoders, see +their respective documentation sections.) +

+
+
frame_size integer (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. +

+
+
frame_number integer
+

Set the frame number. +

+
+
delay integer
+
qcomp float (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. +

+
+
qblur float (encoding,video)
+

Set video quantizer scale blur (VBR). +

+
+
qmin integer (encoding,video)
+

Set min video quantizer scale (VBR). Must be included between -1 and +69, default value is 2. +

+
+
qmax integer (encoding,video)
+

Set max video quantizer scale (VBR). Must be included between -1 and +1024, default value is 31. +

+
+
qdiff integer (encoding,video)
+

Set max difference between the quantizer scale (VBR). +

+
+
bf integer (encoding,video)
+

Set max number of B frames between non-B-frames. +

+

Must be an integer between -1 and 16. 0 means that B-frames are +disabled. If a value of -1 is used, it will choose an automatic value +depending on the encoder. +

+

Default value is 0. +

+
+
b_qfactor float (encoding,video)
+

Set qp factor between P and B frames. +

+
+
codec_tag integer
+
bug flags (decoding,video)
+

Workaround not auto detected encoder bugs. +

+

Possible values: +

+
‘autodetect’
+
‘xvid_ilace’
+

Xvid interlacing bug (autodetected if fourcc==XVIX) +

+
‘ump4’
+

(autodetected if fourcc==UMP4) +

+
‘no_padding’
+

padding bug (autodetected) +

+
‘amv’
+
‘qpel_chroma’
+
‘std_qpel’
+

old standard qpel (autodetected per fourcc/version) +

+
‘qpel_chroma2’
+
‘direct_blocksize’
+

direct-qpel-blocksize bug (autodetected per fourcc/version) +

+
‘edge’
+

edge padding bug (autodetected per fourcc/version) +

+
‘hpel_chroma’
+
‘dc_clip’
+
‘ms’
+

Workaround various bugs in microsoft broken decoders. +

+
‘trunc’
+

trancated frames +

+
+ +
+
strict integer (decoding/encoding,audio,video)
+

Specify how strictly to follow the standards. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
b_qoffset float (encoding,video)
+

Set QP offset between P and B frames. +

+
+
err_detect flags (decoding,audio,video)
+

Set error detection flags. +

+

Possible values: +

+
‘crccheck’
+

verify embedded CRCs +

+
‘bitstream’
+

detect bitstream specification deviations +

+
‘buffer’
+

detect improper bitstream length +

+
‘explode’
+

abort decoding on minor error detection +

+
‘ignore_err’
+

ignore decoding errors, and continue decoding. +This is useful if you want to analyze the content of a video and thus want +everything to be decoded no matter what. This option will not result in a video +that is pleasing to watch in case of errors. +

+
‘careful’
+

consider things that violate the spec and have not been seen in the wild as errors +

+
‘compliant’
+

consider all spec non compliancies as errors +

+
‘aggressive’
+

consider things that a sane encoder should not do as an error +

+
+ +
+
has_b_frames integer
+
block_align integer
+
rc_override_count integer
+
maxrate integer (encoding,audio,video)
+

Set max bitrate tolerance (in bits/s). Requires bufsize to be set. +

+
+
minrate integer (encoding,audio,video)
+

Set min bitrate tolerance (in bits/s). Most useful in setting up a CBR +encode. It is of little use elsewise. +

+
+
bufsize integer (encoding,audio,video)
+

Set ratecontrol buffer size (in bits). +

+
+
i_qfactor float (encoding,video)
+

Set QP factor between P and I frames. +

+
+
i_qoffset float (encoding,video)
+

Set QP offset between P and I frames. +

+
+
dct integer (encoding,video)
+

Set DCT algorithm. +

+

Possible values: +

+
‘auto’
+

autoselect a good one (default) +

+
‘fastint’
+

fast integer +

+
‘int’
+

accurate integer +

+
‘mmx’
+
‘altivec’
+
‘faan’
+

floating point AAN DCT +

+
+ +
+
lumi_mask float (encoding,video)
+

Compress bright areas stronger than medium ones. +

+
+
tcplx_mask float (encoding,video)
+

Set temporal complexity masking. +

+
+
scplx_mask float (encoding,video)
+

Set spatial complexity masking. +

+
+
p_mask float (encoding,video)
+

Set inter masking. +

+
+
dark_mask float (encoding,video)
+

Compress dark areas stronger than medium ones. +

+
+
idct integer (decoding/encoding,video)
+

Select IDCT implementation. +

+

Possible values: +

+
‘auto’
+
‘int’
+
‘simple’
+
‘simplemmx’
+
‘simpleauto’
+

Automatically pick a IDCT compatible with the simple one +

+
+
‘arm’
+
‘altivec’
+
‘sh4’
+
‘simplearm’
+
‘simplearmv5te’
+
‘simplearmv6’
+
‘simpleneon’
+
‘xvid’
+
‘faani’
+

floating point AAN IDCT +

+
+ +
+
slice_count integer
+
ec flags (decoding,video)
+

Set error concealment strategy. +

+

Possible values: +

+
‘guess_mvs’
+

iterative motion vector (MV) search (slow) +

+
‘deblock’
+

use strong deblock filter for damaged MBs +

+
‘favor_inter’
+

favor predicting from the previous frame instead of the current +

+
+ +
+
bits_per_coded_sample integer
+
aspect rational number (encoding,video)
+

Set sample aspect ratio. +

+
+
sar rational number (encoding,video)
+

Set sample aspect ratio. Alias to aspect. +

+
+
debug flags (decoding/encoding,audio,video,subtitles)
+

Print specific debug info. +

+

Possible values: +

+
‘pict’
+

picture info +

+
‘rc’
+

rate control +

+
‘bitstream’
+
‘mb_type’
+

macroblock (MB) type +

+
‘qp’
+

per-block quantization parameter (QP) +

+
‘dct_coeff’
+
‘green_metadata’
+

display complexity metadata for the upcoming frame, GoP or for a given duration. +

+
+
‘skip’
+
‘startcode’
+
‘er’
+

error recognition +

+
‘mmco’
+

memory management control operations (H.264) +

+
‘bugs’
+
‘buffers’
+

picture buffer allocations +

+
‘thread_ops’
+

threading operations +

+
‘nomc’
+

skip motion compensation +

+
+ +
+
cmp integer (encoding,video)
+

Set full pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
subcmp integer (encoding,video)
+

Set sub pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
mbcmp integer (encoding,video)
+

Set macroblock compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
ildctcmp integer (encoding,video)
+

Set interlaced dct compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation. +

+
‘(1024, INT_MAX)’
+

full motion estimation(slowest) +

+
‘(768, 1024]’
+

umh motion estimation +

+
‘(512, 768]’
+

hex motion estimation +

+
‘(256, 512]’
+

l2s diamond motion estimation +

+
‘[2,256]’
+

var diamond motion estimation +

+
‘(-1, 2)’
+

small diamond motion estimation +

+
‘-1’
+

funny diamond motion estimation +

+
‘(INT_MIN, -1)’
+

sab diamond motion estimation +

+
+ +
+
last_pred integer (encoding,video)
+

Set amount of motion predictors from the previous frame. +

+
+
precmp integer (encoding,video)
+

Set pre motion estimation compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
pre_dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation pre-pass. +

+
+
subq integer (encoding,video)
+

Set sub pel motion estimation quality. +

+
+
me_range integer (encoding,video)
+

Set limit motion vectors range (1023 for DivX player). +

+
+
global_quality integer (encoding,audio,video)
+
slice_flags integer
+
mbd integer (encoding,video)
+

Set macroblock decision algorithm (high quality mode). +

+

Possible values: +

+
‘simple’
+

use mbcmp (default) +

+
‘bits’
+

use fewest bits +

+
‘rd’
+

use best rate distortion +

+
+ +
+
rc_init_occupancy integer (encoding,video)
+

Set number of bits which should be loaded into the rc buffer before +decoding starts. +

+
+
flags2 flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘fast’
+

Allow non spec compliant speedup tricks. +

+
‘noout’
+

Skip bitstream encoding. +

+
‘ignorecrop’
+

Ignore cropping information from sps. +

+
‘local_header’
+

Place global headers at every keyframe instead of in extradata. +

+
‘chunks’
+

Frame data might be split into multiple chunks. +

+
‘showall’
+

Show all frames before the first keyframe. +

+
‘export_mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘skip_manual’
+

Do not skip samples and export skip information as frame side data. +

+
‘ass_ro_flush_noop’
+

Do not reset ASS ReadOrder field on flush. +

+
‘icc_profiles’
+

Generate/parse embedded ICC profiles from/to colorimetry tags. +

+
+ +
+
export_side_data flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘prft’
+

Export encoder Producer Reference Time into packet side-data (see AV_PKT_DATA_PRFT) +for codecs that support it. +

+
‘venc_params’
+

Export video encoding parameters through frame side data (see AV_FRAME_DATA_VIDEO_ENC_PARAMS) +for codecs that support it. At present, those are H.264 and VP9. +

+
‘film_grain’
+

Export film grain parameters through frame side data (see AV_FRAME_DATA_FILM_GRAIN_PARAMS). +Supported at present by AV1 decoders. +

+
‘enhancements’
+

Export picture enhancement metadata through frame side data, e.g. LCEVC (see AV_FRAME_DATA_LCEVC). +

+
+ +
+
threads integer (decoding/encoding,video)
+

Set the number of threads to be used, in case the selected codec +implementation supports multi-threading. +

+

Possible values: +

+
‘auto, 0’
+

automatically select the number of threads to set +

+
+ +

Default value is ‘auto’. +

+
+
dc integer (encoding,video)
+

Set intra_dc_precision. +

+
+
nssew integer (encoding,video)
+

Set nsse weight. +

+
+
skip_top integer (decoding,video)
+

Set number of macroblock rows at the top which are skipped. +

+
+
skip_bottom integer (decoding,video)
+

Set number of macroblock rows at the bottom which are skipped. +

+
+
profile integer (encoding,audio,video)
+
+

Set encoder codec profile. Default value is ‘unknown’. Encoder specific +profiles are documented in the relevant encoder documentation. +

+
+
level integer (encoding,audio,video)
+
+

Set the encoder level. This level depends on the specific codec, and +might correspond to the profile level. It is set by default to +‘unknown’. +

+

Possible values: +

+
‘unknown’
+
+ +
+
lowres integer (decoding,audio,video)
+

Decode at 1= 1/2, 2=1/4, 3=1/8 resolutions. +

+
+
mblmin integer (encoding,video)
+

Set min macroblock lagrange factor (VBR). +

+
+
mblmax integer (encoding,video)
+

Set max macroblock lagrange factor (VBR). +

+
+
skip_loop_filter integer (decoding,video)
+
skip_idct integer (decoding,video)
+
skip_frame integer (decoding,video)
+
+

Make decoder discard processing depending on the frame type selected +by the option value. +

+

skip_loop_filter skips frame loop filtering, skip_idct +skips frame IDCT/dequantization, skip_frame skips decoding. +

+

Possible values: +

+
‘none’
+

Discard no frame. +

+
+
‘default’
+

Discard useless frames like 0-sized frames. +

+
+
‘noref’
+

Discard all non-reference frames. +

+
+
‘bidir’
+

Discard all bidirectional frames. +

+
+
‘nokey’
+

Discard all frames excepts keyframes. +

+
+
‘nointra’
+

Discard all frames except I frames. +

+
+
‘all’
+

Discard all frames. +

+
+ +

Default value is ‘default’. +

+
+
bidir_refine integer (encoding,video)
+

Refine the two motion vectors used in bidirectional macroblocks. +

+
+
keyint_min integer (encoding,video)
+

Set minimum interval between IDR-frames. +

+
+
refs integer (encoding,video)
+

Set reference frames to consider for motion compensation. +

+
+
trellis integer (encoding,audio,video)
+

Set rate-distortion optimal quantization. +

+
+
mv0_threshold integer (encoding,video)
+
compression_level integer (encoding,audio,video)
+
bits_per_raw_sample integer
+
channel_layout integer (decoding/encoding,audio)
+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
rc_max_vbv_use float (encoding,video)
+
rc_min_vbv_use float (encoding,video)
+
color_primaries integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘bt470m’
+

BT.470 M +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘film’
+

Film +

+
‘bt2020’
+

BT.2020 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘smpte431’
+

SMPTE 431-2 +

+
‘smpte432’
+

SMPTE 432-1 +

+
‘jedec-p22’
+

JEDEC P22 +

+
+ +
+
color_trc integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘gamma22’
+

BT.470 M +

+
‘gamma28’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘linear’
+

Linear +

+
‘log’
+
‘log100’
+

Log +

+
‘log_sqrt’
+
‘log316’
+

Log square root +

+
‘iec61966_2_4’
+
‘iec61966-2-4’
+

IEC 61966-2-4 +

+
‘bt1361’
+
‘bt1361e’
+

BT.1361 +

+
‘iec61966_2_1’
+
‘iec61966-2-1’
+

IEC 61966-2-1 +

+
‘bt2020_10’
+
‘bt2020_10bit’
+

BT.2020 - 10 bit +

+
‘bt2020_12’
+
‘bt2020_12bit’
+

BT.2020 - 12 bit +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ +
+
colorspace integer (decoding/encoding,video)
+

Possible values: +

+
‘rgb’
+

RGB +

+
‘bt709’
+

BT.709 +

+
‘fcc’
+

FCC +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘ycocg’
+

YCOCG +

+
‘bt2020nc’
+
‘bt2020_ncl’
+

BT.2020 NCL +

+
‘bt2020c’
+
‘bt2020_cl’
+

BT.2020 CL +

+
‘smpte2085’
+

SMPTE 2085 +

+
‘chroma-derived-nc’
+

Chroma-derived NCL +

+
‘chroma-derived-c’
+

Chroma-derived CL +

+
‘ictcp’
+

ICtCp +

+
+ +
+
color_range integer (decoding/encoding,video)
+

If used as input parameter, it serves as a hint to the decoder, which +color_range the input has. +Possible values: +

+
‘tv’
+
‘mpeg’
+
‘limited’
+

MPEG (219*2^(n-8)) +

+
‘pc’
+
‘jpeg’
+
‘full’
+

JPEG (2^n-1) +

+
+ +
+
chroma_sample_location integer (decoding/encoding,video)
+

Possible values: +

+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode integer (decoding/encoding,video)
+

Possible values: +

+
‘premultiplied’
+
‘straight’
+
+ + +
+
log_level_offset integer
+

Set the log level offset. +

+
+
slices integer (encoding,video)
+

Number of slices, used in parallelized encoding. +

+
+
thread_type flags (decoding/encoding,video)
+

Select which multithreading methods to use. +

+

Use of ‘frame’ will increase decoding delay by one frame per +thread, so clients which cannot provide future frames should not use +it. +

+

Possible values: +

+
‘slice’
+

Decode more than one part of a single frame at once. +

+

Multithreading using slices works only when the video was encoded with +slices. +

+
+
‘frame’
+

Decode more than one frame at once. +

+
+ +

Default value is ‘slice+frame’. +

+
+
audio_service_type integer (encoding,audio)
+

Set audio service type. +

+

Possible values: +

+
‘ma’
+

Main Audio Service +

+
‘ef’
+

Effects +

+
‘vi’
+

Visually Impaired +

+
‘hi’
+

Hearing Impaired +

+
‘di’
+

Dialogue +

+
‘co’
+

Commentary +

+
‘em’
+

Emergency +

+
‘vo’
+

Voice Over +

+
‘ka’
+

Karaoke +

+
+ +
+
request_sample_fmt sample_fmt (decoding,audio)
+

Set sample format audio decoders should prefer. Default value is +none. +

+
+
pkt_timebase rational number
+
sub_charenc encoding (decoding,subtitles)
+

Set the input subtitles character encoding. +

+
+
field_order field_order (video)
+

Set/override the field order of the video. +Possible values: +

+
‘progressive’
+

Progressive video +

+
‘tt’
+

Interlaced video, top field coded and displayed first +

+
‘bb’
+

Interlaced video, bottom field coded and displayed first +

+
‘tb’
+

Interlaced video, top coded first, bottom displayed first +

+
‘bt’
+

Interlaced video, bottom coded first, top displayed first +

+
+ +
+
skip_alpha bool (decoding,video)
+

Set to 1 to disable processing alpha (transparency). This works like the +‘gray’ flag in the flags option which skips chroma information +instead of alpha. Default is 0. +

+
+
codec_whitelist list (input)
+

"," separated list of allowed decoders. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_pixels integer (decoding/encoding,video)
+

Maximum number of pixels per image. This value can be used to avoid out of +memory failures due to large images. +

+
+
apply_cropping bool (decoding,video)
+

Enable cropping if cropping parameters are multiples of the required +alignment for the left and top parameters. If the alignment is not met the +cropping will be partially applied to maintain alignment. +Default is 1 (enabled). +Note: The required alignment depends on if AV_CODEC_FLAG_UNALIGNED is set and the +CPU. AV_CODEC_FLAG_UNALIGNED cannot be changed from the command line. Also hardware +decoders will not apply left/top Cropping. +

+ +
+
+ + + +

10 Decoders

+ +

Decoders are configured elements in FFmpeg which allow the decoding of +multimedia streams. +

+

When you configure your FFmpeg build, all the supported native decoders +are enabled by default. Decoders requiring an external library must be enabled +manually via the corresponding --enable-lib option. You can list all +available decoders using the configure option --list-decoders. +

+

You can disable all the decoders with the configure option +--disable-decoders and selectively enable / disable single decoders +with the options --enable-decoder=DECODER / +--disable-decoder=DECODER. +

+

The option -decoders of the ff* tools will display the list of +enabled decoders. +

+ + +

11 Video Decoders

+ +

A description of some of the currently available video decoders +follows. +

+ +

11.1 av1

+ +

AOMedia Video 1 (AV1) decoder. +

+ +

11.1.1 Options

+ +
+
operating_point
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Default is 0. +

+
+
+ + +

11.2 hevc

+

HEVC (AKA ITU-T H.265 or ISO/IEC 23008-2) decoder. +

+

The decoder supports MV-HEVC multiview streams with at most two views. Views to +be output are selected by supplying a list of view IDs to the decoder (the +view_ids option). This option may be set either statically before +decoder init, or from the get_format() callback - useful for the case +when the view count or IDs change dynamically during decoding. +

+

Only the base layer is decoded by default. +

+

Note that if you are using the ffmpeg CLI tool, you should be using view +specifiers as documented in its manual, rather than the options documented here. +

+ +

11.2.1 Options

+ +
+
view_ids (MV-HEVC)
+

Specify a list of view IDs that should be output. This option can also be set to +a single ’-1’, which will cause all views defined in the VPS to be decoded and +output. +

+
+
view_ids_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view IDs available +in the active VPS. The array is empty for single-layer video. +

+

The value of this option is guaranteed to be accurate when read from the +get_format() callback. It may also be set at other times (e.g. after +opening the decoder), but the value is informational only and may be incorrect +(e.g. when the stream contains multiple distinct VPS NALUs). +

+
+
view_pos_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view positions +(left, right, or unspecified) available in the active VPS, as +AVStereo3DView values. When the array is available, its elements apply to +the corresponding elements of view_ids_available, i.e. +view_pos_available[i] contains the position of view with ID +view_ids_available[i]. +

+

Same validity restrictions as for view_ids_available apply to +this option. +

+
+
+ + +

11.3 rawvideo

+ +

Raw video decoder. +

+

This decoder decodes rawvideo streams. +

+ +

11.3.1 Options

+ +
+
top top_field_first
+

Specify the assumed field type of the input video. +

+
-1
+

the video is assumed to be progressive (default) +

+
0
+

bottom-field-first is assumed +

+
1
+

top-field-first is assumed +

+
+ +
+
+ + +

11.4 libdav1d

+ +

dav1d AV1 decoder. +

+

libdav1d allows libavcodec to decode the AOMedia Video 1 (AV1) codec. +Requires the presence of the libdav1d headers and library during configuration. +You need to explicitly configure the build with --enable-libdav1d. +

+ +

11.4.1 Options

+ +

The following options are supported by the libdav1d wrapper. +

+
+
max_frame_delay
+

Set max amount of frames the decoder may buffer internally. The default value is 0 +(autodetect). +

+
+
filmgrain
+

Apply film grain to the decoded video if present in the bitstream. Defaults to the +internal default of the library. +This option is deprecated and will be removed in the future. See the global option +export_side_data to export Film Grain parameters instead of applying it. +

+
+
oppoint
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Defaults to the +internal default of the library. +

+
+
alllayers
+

Output all spatial layers of a scalable AV1 bitstream. The default value is false. +

+
+
+ + +

11.5 libdavs2

+ +

AVS2-P2/IEEE1857.4 video decoder wrapper. +

+

This decoder allows libavcodec to decode AVS2 streams with davs2 library. +

+ + +

11.6 libuavs3d

+ +

AVS3-P2/IEEE1857.10 video decoder. +

+

libuavs3d allows libavcodec to decode AVS3 streams. +Requires the presence of the libuavs3d headers and library during configuration. +You need to explicitly configure the build with --enable-libuavs3d. +

+ +

11.6.1 Options

+ +

The following option is supported by the libuavs3d wrapper. +

+
+
frame_threads
+

Set amount of frame threads to use during decoding. The default value is 0 (autodetect). +

+
+
+ + +

11.7 libxevd

+ +

eXtra-fast Essential Video Decoder (XEVD) MPEG-5 EVC decoder wrapper. +

+

This decoder requires the presence of the libxevd headers and library +during configuration. You need to explicitly configure the build with +--enable-libxevd. +

+

The xevd project website is at https://github.com/mpeg5/xevd. +

+ +

11.7.1 Options

+ +

The following options are supported by the libxevd wrapper. +The xevd-equivalent options or values are listed in parentheses for easy migration. +

+

To get a more accurate and extensive documentation of the libxevd options, +invoke the command xevd_app --help or consult the libxevd documentation. +

+
+
threads (threads)
+

Force to use a specific number of threads +

+
+
+ + +

11.8 QSV Decoders

+ +

The family of Intel QuickSync Video decoders (VC1, MPEG-2, H.264, HEVC, +JPEG/MJPEG, VP8, VP9, AV1, VVC). +

+ +

11.8.1 Common Options

+ +

The following options are supported by all qsv decoders. +

+
+
async_depth
+

Internal parallelization depth, the higher the value the higher the latency. +

+
+
gpu_copy
+

A GPU-accelerated copy between video and system memory +

+
‘default’
+
‘on’
+
‘off’
+
+ +
+
+ + +

11.8.2 HEVC Options

+

Extra options for hevc_qsv. +

+
+
load_plugin
+

A user plugin to load in an internal session +

+
‘none’
+
‘hevc_sw’
+
‘hevc_hw’
+
+ +
+
load_plugins
+

A :-separate list of hexadecimal plugin UIDs to load in an internal session +

+
+
+ + +

11.9 v210

+ +

Uncompressed 4:2:2 10-bit decoder. +

+ +

11.9.1 Options

+ +
+
custom_stride
+

Set the line size of the v210 data in bytes. The default value is 0 +(autodetect). You can use the special -1 value for a strideless v210 as seen in +BOXX files. +

+
+
+ + + +

12 Audio Decoders

+ +

A description of some of the currently available audio decoders +follows. +

+ +

12.1 ac3

+ +

AC-3 audio decoder. +

+

This decoder implements part of ATSC A/52:2010 and ETSI TS 102 366, as well as +the undocumented RealAudio 3 (a.k.a. dnet). +

+ +

12.1.1 AC-3 Decoder Options

+ +
+
-drc_scale value
+

Dynamic Range Scale Factor. The factor to apply to dynamic range values +from the AC-3 stream. This factor is applied exponentially. The default value is 1. +There are 3 notable scale factor ranges: +

+
drc_scale == 0
+

DRC disabled. Produces full range audio. +

+
0 < drc_scale <= 1
+

DRC enabled. Applies a fraction of the stream DRC value. +Audio reproduction is between full range and full compression. +

+
drc_scale > 1
+

DRC enabled. Applies drc_scale asymmetrically. +Loud sounds are fully compressed. Soft sounds are enhanced. +

+
+ +
+
+ + +

12.2 flac

+ +

FLAC audio decoder. +

+

This decoder aims to implement the complete FLAC specification from Xiph. +

+ +

12.2.1 FLAC Decoder options

+ +
+
-use_buggy_lpc
+

The lavc FLAC encoder used to produce buggy streams with high lpc values +(like the default value). This option makes it possible to decode such streams +correctly by using lavc’s old buggy lpc logic for decoding. +

+
+
+ + +

12.3 ffwavesynth

+ +

Internal wave synthesizer. +

+

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. +

+ +

12.4 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 --enable-libcelt. +

+ +

12.5 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 --enable-libgsm. +

+

This decoder supports both the ordinary GSM and the Microsoft variant. +

+ +

12.6 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 +--enable-libilbc. +

+ +

12.6.1 Options

+ +

The following option is supported by the libilbc wrapper. +

+
+
enhance
+
+

Enable the enhancement of the decoded audio when set to 1. The default +value is 0 (disabled). +

+
+
+ + +

12.7 libmpeghdec

+ +

libmpeghdec decoder wrapper. +

+

libmpeghdec allows libmpeghdec to decode the MPEG-H 3D audio codec. +Requires the presence of the libmpeghdec headers and library during +configuration. You need to explicitly configure the build with +--enable-libmpeghdec --enable-nonfree. +

+ +

12.8 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 --enable-libopencore-amrnb. +

+

An FFmpeg native decoder for AMR-NB exists, so users can decode AMR-NB +without this library. +

+ +

12.9 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 --enable-libopencore-amrwb. +

+

An FFmpeg native decoder for AMR-WB exists, so users can decode AMR-WB +without this library. +

+ +

12.10 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 +--enable-libopus. +

+

An FFmpeg native decoder for Opus exists, so users can decode Opus +without this library. +

+ + +

13 Subtitles Decoders

+ + +

13.1 libaribb24

+ +

ARIB STD-B24 caption decoder. +

+

Implements profiles A and C of the ARIB STD-B24 standard. +

+ +

13.1.1 libaribb24 Decoder Options

+ +
+
-aribb24-base-path path
+

Sets the base path for the libaribb24 library. This is utilized for reading of +configuration files (for custom unicode conversions), and for dumping of +non-text symbols as images under that location. +

+

Unset by default. +

+
+
-aribb24-skip-ruby-text boolean
+

Tells the decoder wrapper to skip text blocks that contain half-height ruby +text. +

+

Enabled by default. +

+
+
+ + +

13.2 libaribcaption

+ +

Yet another ARIB STD-B24 caption decoder using external libaribcaption +library. +

+

Implements profiles A and C of the Japanese ARIB STD-B24 standard, +Brazilian ABNT NBR 15606-1, and Philippines version of ISDB-T. +

+

Requires the presence of the libaribcaption headers and library +(https://github.com/xqq/libaribcaption) during configuration. +You need to explicitly configure the build with --enable-libaribcaption. +If both libaribb24 and libaribcaption are enabled, libaribcaption +decoder precedes. +

+ +

13.2.1 libaribcaption Decoder Options

+ +
+
-sub_type subtitle_type
+

Specifies the format of the decoded subtitles. +

+
+
‘bitmap’
+

Graphical image. +

+
‘ass’
+

ASS formatted text. +

+
‘text’
+

Simple text based output without formatting. +

+
+ +

The default is ass as same as libaribb24 decoder. +Some present players (e.g., mpv) expect ASS format for ARIB caption. +

+
+
-caption_encoding encoding_scheme
+

Specifies the encoding scheme of input subtitle text. +

+
+
‘auto’
+

Automatically detect text encoding (default). +

+
‘jis’
+

8bit-char JIS encoding defined in ARIB STD B24. +This encoding used in Japan for ISDB captions. +

+
‘utf8’
+

UTF-8 encoding defined in ARIB STD B24. +This encoding is used in Philippines for ISDB-T captions. +

+
‘latin’
+

Latin character encoding defined in ABNT NBR 15606-1. +This encoding is used in South America for SBTVD / ISDB-Tb captions. +

+
+ +
+
-font font_name[,font_name2,...]
+

Specify comma-separated list of font family names to be used for bitmap +or ass type subtitle rendering. +Only first font name is used for ass type subtitle. +

+

If not specified, use internally defined default font family. +

+
+
-ass_single_rect boolean
+

ARIB STD-B24 specifies that some captions may be displayed at different +positions at a time (multi-rectangle subtitle). +Since some players (e.g., old mpv) can’t handle multiple ASS rectangles +in a single AVSubtitle, or multiple ASS rectangles of indeterminate duration +with the same start timestamp, this option can change the behavior so that +all the texts are displayed in a single ASS rectangle. +

+

The default is false. +

+

If your player cannot handle AVSubtitles with multiple ASS rectangles properly, +set this option to true or define ASS_SINGLE_RECT=1 to change +default behavior at compilation. +

+
+
-force_outline_text boolean
+

Specify whether always render outline text for all characters regardless of +the indication by character style. +

+

The default is false. +

+
+
-outline_width number (0.0 - 3.0)
+

Specify width for outline text, in dots (relative). +

+

The default is 1.5. +

+
+
-ignore_background boolean
+

Specify whether to ignore background color rendering. +

+

The default is false. +

+
+
-ignore_ruby boolean
+

Specify whether to ignore rendering for ruby-like (furigana) characters. +

+

The default is false. +

+
+
-replace_drcs boolean
+

Specify whether to render replaced DRCS characters as Unicode characters. +

+

The default is true. +

+
+
-replace_msz_ascii boolean
+

Specify whether to replace MSZ (Middle Size; half width) fullwidth +alphanumerics with halfwidth alphanumerics. +

+

The default is true. +

+
+
-replace_msz_japanese boolean
+

Specify whether to replace some MSZ (Middle Size; half width) fullwidth +japanese special characters with halfwidth ones. +

+

The default is true. +

+
+
-replace_msz_glyph boolean
+

Specify whether to replace MSZ (Middle Size; half width) characters +with halfwidth glyphs if the fonts supports it. +This option works under FreeType or DirectWrite renderer +with Adobe-Japan1 compliant fonts. +e.g., IBM Plex Sans JP, Morisawa BIZ UDGothic, Morisawa BIZ UDMincho, +Yu Gothic, Yu Mincho, and Meiryo. +

+

The default is true. +

+
+
-canvas_size image_size
+

Specify the resolution of the canvas to render subtitles to; usually, this +should be frame size of input video. +This only applies when -subtitle_type is set to bitmap. +

+

The libaribcaption decoder assumes input frame size for bitmap rendering as below: +

    +
  1. PROFILE_A : 1440 x 1080 with SAR (PAR) 4:3 +
  2. PROFILE_C : 320 x 180 with SAR (PAR) 1:1 +
+ +

If actual frame size of input video does not match above assumption, +the rendered captions may be distorted. +To make the captions undistorted, add -canvas_size option to specify +actual input video size. +

+

Note that the -canvas_size option is not required for video with +different size but same aspect ratio. +In such cases, the caption will be stretched or shrunk to actual video size +if -canvas_size option is not specified. +If -canvas_size option is specified with different size, +the caption will be stretched or shrunk as specified size with calculated SAR. +

+
+
+ + +

13.2.2 libaribcaption decoder usage examples

+ +

Display MPEG-TS file with ARIB subtitle by ffplay tool: +

+
ffplay -sub_type bitmap MPEG.TS
+
+ +

Display MPEG-TS file with input frame size 1920x1080 by ffplay tool: +

+
ffplay -sub_type bitmap -canvas_size 1920x1080 MPEG.TS
+
+ +

Embed ARIB subtitle in transcoded video: +

+
ffmpeg -sub_type bitmap -i src.m2t -filter_complex "[0:v][0:s]overlay" -vcodec h264 dest.mp4
+
+ + +

13.3 dvbsub

+ + +

13.3.1 Options

+ +
+
compute_clut
+
+
-2
+

Compute clut once if no matching CLUT is in the stream. +

+
-1
+

Compute clut if no matching CLUT is in the stream. +

+
0
+

Never compute CLUT +

+
1
+

Always compute CLUT and override the one provided in the stream. +

+
+
+
dvb_substream
+

Selects the dvb substream, or all substreams if -1 which is default. +

+
+
+ + +

13.4 dvdsub

+ +

This codec decodes the bitmap subtitles used in DVDs; the same subtitles can +also be found in VobSub file pairs and in some Matroska files. +

+ +

13.4.1 Options

+ +
+
palette
+

Specify the global palette used by the bitmaps. When stored in VobSub, the +palette is normally specified in the index file; in Matroska, the palette is +stored in the codec extra-data in the same format as in VobSub. In DVDs, the +palette is stored in the IFO file, and therefore not available when reading +from dumped VOB files. +

+

The format for this option is a string containing 16 24-bits hexadecimal +numbers (without 0x prefix) separated by commas, for example 0d00ee, +ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, +7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b. +

+
+
ifo_palette
+

Specify the IFO file from which the global palette is obtained. +(experimental) +

+
+
forced_subs_only
+

Only decode subtitle entries marked as forced. Some titles have forced +and non-forced subtitles in the same track. Setting this flag to 1 +will only keep the forced subtitles. Default value is 0. +

+
+ + +

13.5 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 +--enable-libzvbi. +

+ +

13.5.1 Options

+ +
+
txt_page
+

List of teletext page numbers to decode. Pages that do not match the specified +list are dropped. You may use the special * string to match all pages, +or subtitle to match all subtitle pages. +Default value is *. +

+
txt_default_region
+

Set default character set used for decoding, a value between 0 and 87 (see +ETS 300 706, Section 15, Table 32). Default value is -1, which does not +override the libzvbi default. This option is needed for some legacy level 1.0 +transmissions which cannot signal the proper charset. +

+
txt_chop_top
+

Discards the top teletext line. Default value is 1. +

+
txt_format
+

Specifies the format of the decoded subtitles. +

+
bitmap
+

The default format, you should use this for teletext pages, because certain +graphics and colors cannot be expressed in simple text or even ASS. +

+
text
+

Simple text based output without formatting. +

+
ass
+

Formatted ASS output, subtitle pages and teletext pages are returned in +different styles, subtitle pages are stripped down to text, but an effort is +made to keep the text alignment and the formatting. +

+
+
+
txt_left
+

X offset of generated bitmaps, default is 0. +

+
txt_top
+

Y offset of generated bitmaps, default is 0. +

+
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 characters. +Default value is 1. +

+
txt_duration
+

Sets the display duration of the decoded teletext pages or subtitles in +milliseconds. Default value is -1 which means infinity or until the next +subtitle event comes. +

+
txt_transparent
+

Force transparent background of the generated teletext bitmaps. Default value +is 0 which means an opaque background. +

+
txt_opacity
+

Sets the opacity (0-255) of the teletext background. If +txt_transparent is not set, it only affects characters between a start +box and an end box, typically subtitles. Default value is 0 if +txt_transparent is set, 255 otherwise. +

+
+
+ + +

14 Encoders

+ +

Encoders are configured elements in FFmpeg which allow the encoding of +multimedia streams. +

+

When you configure your FFmpeg build, all the supported native encoders +are enabled by default. Encoders requiring an external library must be enabled +manually via the corresponding --enable-lib option. You can list all +available encoders using the configure option --list-encoders. +

+

You can disable all the encoders with the configure option +--disable-encoders and selectively enable / disable single encoders +with the options --enable-encoder=ENCODER / +--disable-encoder=ENCODER. +

+

The option -encoders of the ff* tools will display the list of +enabled encoders. +

+ + +

15 Audio Encoders

+ +

A description of some of the currently available audio encoders +follows. +

+ +

15.1 aac

+ +

Advanced Audio Coding (AAC) encoder. +

+

This encoder is the default AAC encoder, natively implemented into FFmpeg. +

+ +

15.1.1 Options

+ +
+
b
+

Set bit rate in bits/s. Setting this automatically activates constant bit rate +(CBR) mode. If this option is unspecified it is set to 128kbps. +

+
+
q
+

Set quality for variable bit rate (VBR) mode. This option is valid only using +the ffmpeg command-line tool. For library interface users, use +global_quality. +

+
+
cutoff
+

Set cutoff frequency. If unspecified will allow the encoder to dynamically +adjust the cutoff to improve clarity on low bitrates. +

+
+
aac_coder
+

Set AAC encoder coding method. Possible values: +

+
+
‘twoloop’
+

Two loop searching (TLS) method. This is the default 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. Will tune +itself based on whether aac_is, aac_ms and aac_pns +are enabled. +

+
+
‘anmr’
+

Average noise to mask ratio (ANMR) trellis-based solution. +

+

This is an experimental coder which currently produces a lower quality, is more +unstable and is slower than the default twoloop coder but has potential. +Currently has no support for the aac_is or aac_pns options. +Not currently recommended. +

+
+
‘fast’
+

Constant quantizer method. +

+

Uses a cheaper version of twoloop algorithm that doesn’t try to do as many +clever adjustments. Worse with low bitrates (less than 64kbps), but is better +and much faster at higher bitrates. +

+
+
+ +
+
aac_ms
+

Sets mid/side coding mode. The default value of "auto" will automatically use +M/S with bands which will benefit from such coding. Can be forced for all bands +using the value "enable", which is mainly useful for debugging or disabled using +"disable". +

+
+
aac_is
+

Sets intensity stereo coding tool usage. By default, it’s enabled and will +automatically toggle IS for similar pairs of stereo bands if it’s beneficial. +Can be disabled for debugging by setting the value to "disable". +

+
+
aac_pns
+

Uses perceptual noise substitution to replace low entropy high frequency bands +with imperceptible white noise during the decoding process. By default, it’s +enabled, but can be disabled for debugging purposes by using "disable". +

+
+
aac_tns
+

Enables the use of a multitap FIR filter which spans through the high frequency +bands to hide quantization noise during the encoding process and is reverted +by the decoder. As well as decreasing unpleasant artifacts in the high range +this also reduces the entropy in the high bands and allows for more bits to +be used by the mid-low bands. By default it’s enabled but can be disabled for +debugging by setting the option to "disable". +

+
+
aac_ltp
+

Enables the use of the long term prediction extension which increases coding +efficiency in very low bandwidth situations such as encoding of voice or +solo piano music by extending constant harmonic peaks in bands throughout +frames. This option is implied by profile:a aac_low. +Use in conjunction with -ar to decrease the samplerate. +

+
+
profile
+

Sets the encoding profile, possible values: +

+
+
‘aac_low’
+

The default, AAC "Low-complexity" profile. Is the most compatible and produces +decent quality. +

+
+
‘mpeg2_aac_low’
+

Equivalent to -profile:a aac_low -aac_pns 0. PNS was introduced with the +MPEG4 specifications. +

+
+
‘aac_ltp’
+

Long term prediction profile, is enabled by and will enable the aac_ltp +option. Introduced in MPEG4. +

+
+
+

If this option is unspecified it is set to ‘aac_low’. +

+
+ + +

15.2 ac3 and ac3_fixed

+ +

AC-3 audio encoders. +

+

These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366. +

+

The ac3 encoder uses floating-point math, while the ac3_fixed +encoder only uses fixed-point integer math. This does not mean that one is +always faster, just that one or the other may be better suited to a +particular system. The ac3_fixed encoder is not the default codec for +any of the output formats, so it must be specified explicitly using the option +-acodec ac3_fixed in order to use it. +

+ +

15.2.1 AC-3 Metadata

+ +

The AC-3 metadata options are used to set parameters that describe the audio, +but in most cases do not affect the audio encoding itself. Some of the options +do directly affect or influence the decoding and playback of the resulting +bitstream, while others are just for informational purposes. A few of the +options will add bits to the output stream that could otherwise be used for +audio data, and will thus affect the quality of the output. Those will be +indicated accordingly with a note in the option list below. +

+

These parameters are described in detail in several publicly-available +documents. +

+ + +

15.2.1.1 Metadata Control Options

+ +
+
-per_frame_metadata boolean
+

Allow Per-Frame Metadata. Specifies if the encoder should check for changing +metadata for each frame. +

+
0
+

The metadata values set at initialization will be used for every frame in the +stream. (default) +

+
1
+

Metadata values can be changed before encoding each frame. +

+
+ +
+
+ + +

15.2.1.2 Downmix Levels

+ +
+
-center_mixlev level
+

Center Mix Level. The amount of gain the decoder should apply to the center +channel when downmixing to stereo. This field will only be written to the +bitstream if a center channel is present. The value is specified as a scale +factor. There are 3 valid values: +

+
0.707
+

Apply -3dB gain +

+
0.595
+

Apply -4.5dB gain (default) +

+
0.500
+

Apply -6dB gain +

+
+ +
+
-surround_mixlev level
+

Surround Mix Level. The amount of gain the decoder should apply to the surround +channel(s) when downmixing to stereo. This field will only be written to the +bitstream if one or more surround channels are present. The value is specified +as a scale factor. There are 3 valid values: +

+
0.707
+

Apply -3dB gain +

+
0.500
+

Apply -6dB gain (default) +

+
0.000
+

Silence Surround Channel(s) +

+
+ +
+
+ + +

15.2.1.3 Audio Production Information

+

Audio Production Information is optional information describing the mixing +environment. Either none or both of the fields are written to the bitstream. +

+
+
-mixing_level number
+

Mixing Level. Specifies peak sound pressure level (SPL) in the production +environment when the mix was mastered. Valid values are 80 to 111, or -1 for +unknown or not indicated. The default value is -1, but that value cannot be +used if the Audio Production Information is written to the bitstream. Therefore, +if the room_type option is not the default value, the mixing_level +option must not be -1. +

+
+
-room_type type
+

Room Type. Describes the equalization used during the final mixing session at +the studio or on the dubbing stage. A large room is a dubbing stage with the +industry standard X-curve equalization; a small room has flat equalization. +This field will not be written to the bitstream if both the mixing_level +option and the room_type option have the default values. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
large
+

Large Room +

+
2
+
small
+

Small Room +

+
+ +
+
+ + +

15.2.1.4 Other Metadata Options

+ +
+
-copyright boolean
+

Copyright Indicator. Specifies whether a copyright exists for this audio. +

+
0
+
off
+

No Copyright Exists (default) +

+
1
+
on
+

Copyright Exists +

+
+ +
+
-dialnorm value
+

Dialogue Normalization. Indicates how far the average dialogue level of the +program is below digital 100% full scale (0 dBFS). This parameter determines a +level shift during audio reproduction that sets the average volume of the +dialogue to a preset level. The goal is to match volume level between program +sources. A value of -31dB will result in no volume level change, relative to +the source volume, during audio reproduction. Valid values are whole numbers in +the range -31 to -1, with -31 being the default. +

+
+
-dsur_mode mode
+

Dolby Surround Mode. Specifies whether the stereo signal uses Dolby Surround +(Pro Logic). This field will only be written to the bitstream if the audio +stream is stereo. Using this option does NOT mean the encoder will actually +apply Dolby Surround processing. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
off
+

Not Dolby Surround Encoded +

+
2
+
on
+

Dolby Surround Encoded +

+
+ +
+
-original boolean
+

Original Bit Stream Indicator. Specifies whether this audio is from the +original source and not a copy. +

+
0
+
off
+

Not Original Source +

+
1
+
on
+

Original Source (default) +

+
+ +
+
+ + +

15.2.2 Extended Bitstream Information

+

The extended bitstream options are part of the Alternate Bit Stream Syntax as +specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts. +If any one parameter in a group is specified, all values in that group will be +written to the bitstream. Default values are used for those that are written +but have not been specified. If the mixing levels are written, the decoder +will use these values instead of the ones specified in the center_mixlev +and surround_mixlev options if it supports the Alternate Bit Stream +Syntax. +

+ +

15.2.2.1 Extended Bitstream Information - Part 1

+ +
+
-dmix_mode mode
+

Preferred Stereo Downmix Mode. Allows the user to select either Lt/Rt +(Dolby Surround) or Lo/Ro (normal stereo) as the preferred stereo downmix mode. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
ltrt
+

Lt/Rt Downmix Preferred +

+
2
+
loro
+

Lo/Ro Downmix Preferred +

+
+ +
+
-ltrt_cmixlev level
+

Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the +center channel when downmixing to stereo in Lt/Rt mode. +

+
1.414
+

Apply +3dB gain +

+
1.189
+

Apply +1.5dB gain +

+
1.000
+

Apply 0dB gain +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain (default) +

+
0.500
+

Apply -6.0dB gain +

+
0.000
+

Silence Center Channel +

+
+ +
+
-ltrt_surmixlev level
+

Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the +surround channel(s) when downmixing to stereo in Lt/Rt mode. +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain +

+
0.500
+

Apply -6.0dB gain (default) +

+
0.000
+

Silence Surround Channel(s) +

+
+ +
+
-loro_cmixlev level
+

Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the +center channel when downmixing to stereo in Lo/Ro mode. +

+
1.414
+

Apply +3dB gain +

+
1.189
+

Apply +1.5dB gain +

+
1.000
+

Apply 0dB gain +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain (default) +

+
0.500
+

Apply -6.0dB gain +

+
0.000
+

Silence Center Channel +

+
+ +
+
-loro_surmixlev level
+

Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the +surround channel(s) when downmixing to stereo in Lo/Ro mode. +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain +

+
0.500
+

Apply -6.0dB gain (default) +

+
0.000
+

Silence Surround Channel(s) +

+
+ +
+
+ + +

15.2.2.2 Extended Bitstream Information - Part 2

+ +
+
-dsurex_mode mode
+

Dolby Surround EX Mode. Indicates whether the stream uses Dolby Surround EX +(7.1 matrixed to 5.1). Using this option does NOT mean the encoder will actually +apply Dolby Surround EX processing. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
on
+

Dolby Surround EX Off +

+
2
+
off
+

Dolby Surround EX On +

+
+ +
+
-dheadphone_mode mode
+

Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone +encoding (multi-channel matrixed to 2.0 for use with headphones). Using this +option does NOT mean the encoder will actually apply Dolby Headphone +processing. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
on
+

Dolby Headphone Off +

+
2
+
off
+

Dolby Headphone On +

+
+ +
+
-ad_conv_type type
+

A/D Converter Type. Indicates whether the audio has passed through HDCD A/D +conversion. +

+
0
+
standard
+

Standard A/D Converter (default) +

+
1
+
hdcd
+

HDCD A/D Converter +

+
+ +
+
+ + +

15.2.3 Other AC-3 Encoding Options

+ +
+
-stereo_rematrixing boolean
+

Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This +is an optional AC-3 feature that increases quality by selectively encoding +the left/right channels as mid/side. This option is enabled by default, and it +is highly recommended that it be left as enabled except for testing purposes. +

+
+
cutoff frequency
+

Set lowpass cutoff frequency. If unspecified, the encoder selects a default +determined by various other encoding parameters. +

+
+
+ + +

15.2.4 Floating-Point-Only AC-3 Encoding Options

+ +

These options are only valid for the floating-point encoder and do not exist +for the fixed-point encoder due to the corresponding features not being +implemented in fixed-point. +

+
+
-channel_coupling boolean
+

Enables/Disables use of channel coupling, which is an optional AC-3 feature +that increases quality by combining high frequency information from multiple +channels into a single channel. The per-channel high frequency information is +sent with less accuracy in both the frequency and time domains. This allows +more bits to be used for lower frequencies while preserving enough information +to reconstruct the high frequencies. This option is enabled by default for the +floating-point encoder and should generally be left as enabled except for +testing purposes or to increase encoding speed. +

+
-1
+
auto
+

Selected by Encoder (default) +

+
0
+
off
+

Disable Channel Coupling +

+
1
+
on
+

Enable Channel Coupling +

+
+ +
+
-cpl_start_band number
+

Coupling Start Band. Sets the channel coupling start band, from 1 to 15. If a +value higher than the bandwidth is used, it will be reduced to 1 less than the +coupling end band. If auto is used, the start band will be determined by +the encoder based on the bit rate, sample rate, and channel layout. This option +has no effect if channel coupling is disabled. +

+
-1
+
auto
+

Selected by Encoder (default) +

+
+ +
+
+ + +

15.3 flac

+ +

FLAC (Free Lossless Audio Codec) Encoder +

+ +

15.3.1 Options

+ +

The following options are supported by FFmpeg’s flac encoder. +

+
+
compression_level
+

Sets the compression level, which chooses defaults for many other options +if they are not set explicitly. Valid values are from 0 to 12, 5 is the +default. +

+
+
frame_size
+

Sets the size of the frames in samples per channel. +

+
+
lpc_coeff_precision
+

Sets the LPC coefficient precision, valid values are from 1 to 15, 15 is the +default. +

+
+
lpc_type
+

Sets the first stage LPC algorithm +

+
‘none’
+

LPC is not used +

+
+
‘fixed’
+

fixed LPC coefficients +

+
+
‘levinson’
+
‘cholesky’
+
+ +
+
lpc_passes
+

Number of passes to use for Cholesky factorization during LPC analysis +

+
+
min_partition_order
+

The minimum partition order +

+
+
max_partition_order
+

The maximum partition order +

+
+
prediction_order_method
+
+
‘estimation’
+
‘2level’
+
‘4level’
+
‘8level’
+
‘search’
+

Bruteforce search +

+
‘log’
+
+ +
+
ch_mode
+

Channel mode +

+
‘auto’
+

The mode is chosen automatically for each frame +

+
‘indep’
+

Channels are independently coded +

+
‘left_side’
+
‘right_side’
+
‘mid_side’
+
+ +
+
exact_rice_parameters
+

Chooses if rice parameters are calculated exactly or approximately. +if set to 1 then they are chosen exactly, which slows the code down slightly and +improves compression slightly. +

+
+
multi_dim_quant
+

Multi Dimensional Quantization. If set to 1 then a 2nd stage LPC algorithm is +applied after the first stage to finetune the coefficients. This is quite slow +and slightly improves compression. +

+
+
+ + +

15.4 opus

+ +

Opus encoder. +

+

This is a native FFmpeg encoder for the Opus format. Currently, it’s in development and +only implements the CELT part of the codec. Its quality is usually worse and at best +is equal to the libopus encoder. +

+ +

15.4.1 Options

+ +
+
b
+

Set bit rate in bits/s. If unspecified it uses the number of channels and the layout +to make a good guess. +

+
+
opus_delay
+

Sets the maximum delay in milliseconds. Lower delays than 20ms will very quickly +decrease quality. +

+
+ + +

15.5 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 +--enable-libfdk-aac. The library is also incompatible with GPL, +so if you allow the use of GPL, you should configure with +--enable-gpl --enable-nonfree --enable-libfdk-aac. +

+

This encoder has support for the AAC-HE profiles. +

+

VBR encoding, enabled through the vbr or flags ++qscale options, is experimental and only works with some +combinations of parameters. +

+

Support for encoding 7.1 audio is only available with libfdk-aac 0.1.3 or +higher. +

+

For more information see the fdk-aac project at +http://sourceforge.net/p/opencore-amr/fdk-aac/. +

+ +

15.5.1 Options

+ +

The following options are mapped on the shared FFmpeg codec options. +

+
+
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. +

+
+
ar
+

Set audio sampling rate (in Hz). +

+
+
channels
+

Set the number of audio channels. +

+
+
flags +qscale
+

Enable fixed quality, VBR (Variable Bit Rate) mode. +Note that VBR is implicitly enabled when the vbr value is +positive. +

+
+
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. +

+
+
profile
+

Set audio profile. +

+

The following profiles are recognized: +

+
‘aac_low’
+

Low Complexity AAC (LC) +

+
+
‘aac_he’
+

High Efficiency AAC (HE-AAC) +

+
+
‘aac_he_v2’
+

High Efficiency AAC version 2 (HE-AACv2) +

+
+
‘aac_ld’
+

Low Delay AAC (LD) +

+
+
‘aac_eld’
+

Enhanced Low Delay AAC (ELD) +

+
+ +

If not specified it is set to ‘aac_low’. +

+
+ +

The following are private options of the libfdk_aac encoder. +

+
+
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. +

+
+
eld_sbr
+

Enable SBR (Spectral Band Replication) for ELD if set to 1, disabled +if set to 0. +

+

Default value is 0. +

+
+
eld_v2
+

Enable ELDv2 (LD-MPS extension for ELD stereo signals) for ELDv2 if set to 1, +disabled if set to 0. +

+

Note that option is available when fdk-aac version (AACENCODER_LIB_VL0.AACENCODER_LIB_VL1.AACENCODER_LIB_VL2) > (4.0.0). +

+

Default value is 0. +

+
+
signaling
+

Set SBR/PS signaling style. +

+

It can assume one of the following values: +

+
‘default’
+

choose signaling implicitly (explicit hierarchical by default, +implicit if global header is disabled) +

+
+
‘implicit’
+

implicit backwards compatible signaling +

+
+
‘explicit_sbr’
+

explicit SBR, implicit PS signaling +

+
+
‘explicit_hierarchical’
+

explicit hierarchical signaling +

+
+ +

Default value is ‘default’. +

+
+
latm
+

Output LATM/LOAS encapsulated data if set to 1, disabled if set to 0. +

+

Default value is 0. +

+
+
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. +

+
+
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 ‘aac_low’ profile supports VBR encoding. +

+

VBR modes 1-5 correspond to roughly the following average bit rates: +

+
+
‘1’
+

32 kbps/channel +

+
‘2’
+

40 kbps/channel +

+
‘3’
+

48-56 kbps/channel +

+
‘4’
+

64 kbps/channel +

+
‘5’
+

about 80-96 kbps/channel +

+
+ +

Default value is 0. +

+
+
frame_length
+

Set the audio frame length in samples. Default value is the internal +default of the library. Refer to the library’s documentation for information +about supported values. +

+
+ + +

15.5.2 Examples

+ +
    +
  • Use ffmpeg to convert an audio file to VBR AAC in an M4A (MP4) +container: +
    +
    ffmpeg -i input.wav -codec:a libfdk_aac -vbr 3 output.m4a
    +
    + +
  • Use ffmpeg to convert an audio file to CBR 64k kbps AAC, using the +High-Efficiency AAC profile: +
    +
    ffmpeg -i input.wav -c:a libfdk_aac -profile:a aac_he -b:a 64k output.m4a
    +
    +
+ + +

15.6 liblc3

+ +

liblc3 LC3 (Low Complexity Communication Codec) encoder wrapper. +

+

Requires the presence of the liblc3 headers and library during configuration. +You need to explicitly configure the build with --enable-liblc3. +

+

This encoder has support for the Bluetooth SIG LC3 codec for the LE Audio +protocol, and the following features of LC3plus: +

    +
  • Frame duration of 2.5 and 5ms. +
  • High-Resolution mode, 48 KHz, and 96 kHz sampling rates. +
+ +

For more information see the liblc3 project at +https://github.com/google/liblc3. +

+ +

15.6.1 Options

+ +

The following options are mapped on the shared FFmpeg codec options. +

+
+
b bitrate
+

Set the bit rate in bits/s. This will determine the fixed size of the encoded +frames, for a selected frame duration. +

+
+
ar frequency
+

Set the audio sampling rate (in Hz). +

+
+
channels
+

Set the number of audio channels. +

+
+
frame_duration
+

Set the audio frame duration in milliseconds. Default value is 10ms. +Allowed frame durations are 2.5ms, 5ms, 7.5ms and 10ms. +LC3 (Bluetooth LE Audio), allows 7.5ms and 10ms; and LC3plus 2.5ms, 5ms +and 10ms. +

+

The 10ms frame duration is available in LC3 and LC3 plus standard. +In this mode, the produced bitstream can be referenced either as LC3 or LC3plus. +

+
+
high_resolution boolean
+

Enable the high-resolution mode if set to 1. The high-resolution mode is +available with all LC3plus frame durations and for a sampling rate of 48 KHz, +and 96 KHz. +

+

The encoder automatically turns off this mode at lower sampling rates and +activates it at 96 KHz. +

+

This mode should be preferred at high bitrates. In this mode, the audio +bandwidth is always up to the Nyquist frequency, compared to LC3 at 48 KHz, +which limits the bandwidth to 20 KHz. +

+
+ + +

15.7 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 +--enable-libmp3lame. +

+

See libshine for a fixed-point MP3 encoder, although with a +lower quality. +

+ +

15.7.1 Options

+ +

The following options are supported by the libmp3lame wrapper. The +lame-equivalent of the options are listed in parentheses. +

+
+
b (-b)
+

Set bitrate expressed in bits/s for CBR or ABR. LAME bitrate is +expressed in kilobits/s. +

+
+
q (-V)
+

Set constant quality setting for VBR. This option is valid only +using the ffmpeg command-line tool. For library interface +users, use global_quality. +

+
+
compression_level (-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. +

+
+
cutoff (--lowpass)
+

Set lowpass cutoff frequency. If unspecified, the encoder dynamically +adjusts the cutoff. +

+
+
reservoir
+

Enable use of bit reservoir when set to 1. Default value is 1. LAME +has this enabled by default, but can be overridden by use +--nores option. +

+
+
joint_stereo (-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. +

+
+
abr (--abr)
+

Enable the encoder to use ABR when set to 1. The lame +--abr sets the target bitrate, while this options only +tells FFmpeg to use ABR still relies on b to set bitrate. +

+
+
copyright (-c)
+

Set MPEG audio copyright flag when set to 1. The default value is 0 +(disabled). +

+
+
original (-o)
+

Set MPEG audio original flag when set to 1. The default value is 1 +(enabled). +

+
+ + +

15.8 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 +--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 strict to ‘unofficial’ or +lower. +

+ +

15.8.1 Options

+ +
+
b
+

Set bitrate in bits per second. Only the following bitrates are supported, +otherwise libavcodec will round to the nearest valid bitrate. +

+
+
4750
+
5150
+
5900
+
6700
+
7400
+
7950
+
10200
+
12200
+
+ +
+
dtx
+

Allow discontinuous transmission (generate comfort noise) when set to 1. The +default value is 0 (disabled). +

+
+
+ + +

15.9 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 +--enable-libopus. +

+ +

15.9.1 Option Mapping

+ +

Most libopus options are modelled after the opusenc utility from +opus-tools. The following is an option mapping chart describing options +supported by the libopus wrapper, and their opusenc-equivalent +in parentheses. +

+
+
b (bitrate)
+

Set the bit rate in bits/s. FFmpeg’s b option is +expressed in bits/s, while opusenc’s bitrate in +kilobits/s. +

+
+
vbr (vbr, hard-cbr, and cvbr)
+

Set VBR mode. The FFmpeg vbr option has the following +valid arguments, with the opusenc equivalent options +in parentheses: +

+
+
‘off (hard-cbr)’
+

Use constant bit rate encoding. +

+
+
‘on (vbr)’
+

Use variable bit rate encoding (the default). +

+
+
‘constrained (cvbr)’
+

Use constrained variable bit rate encoding. +

+
+ +
+
compression_level (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. +

+
+
frame_duration (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. +

+
+
packet_loss (expect-loss)
+

Set expected packet loss percentage. The default is 0. +

+
+
fec (n/a)
+

Enable inband forward error correction. packet_loss must be non-zero +to take advantage - frequency of FEC ’side-data’ is proportional to expected packet loss. +Default is disabled. +

+
+
application (N.A.)
+

Set intended application type. Valid options are listed below: +

+
+
‘voip’
+

Favor improved speech intelligibility. +

+
‘audio’
+

Favor faithfulness to the input (the default). +

+
‘lowdelay’
+

Restrict to only the lowest delay modes by disabling voice-optimized +modes. +

+
+ +
+
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). Note that libopus +forces a wideband cutoff for bitrates < 15 kbps, unless CELT-only +(application set to ‘lowdelay’) mode is used. +

+
+
mapping_family (mapping_family)
+

Set channel mapping family to be used by the encoder. The default value of -1 +uses mapping family 0 for mono and stereo inputs, and mapping family 1 +otherwise. The default also disables the surround masking and LFE bandwidth +optimizations in libopus, and requires that the input contains 8 channels or +fewer. +

+

Other values include 0 for mono and stereo, 1 for surround sound with masking +and LFE bandwidth optimizations, and 255 for independent streams with an +unspecified channel layout. +

+
+
apply_phase_inv (N.A.) (requires libopus >= 1.2)
+

If set to 0, disables the use of phase inversion for intensity stereo, +improving the quality of mono downmixes, but slightly reducing normal stereo +quality. The default is 1 (phase inversion enabled). +

+
+
+ + +

15.10 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 +http://sourceforge.net/projects/libshine-fxp/. We only support the +updated fork by the Savonet/Liquidsoap project at https://github.com/savonet/shine. +

+

Requires the presence of the libshine headers and library during +configuration. You need to explicitly configure the build with +--enable-libshine. +

+

See also libmp3lame. +

+ +

15.10.1 Options

+ +

The following options are supported by the libshine wrapper. The +shineenc-equivalent of the options are listed in parentheses. +

+
+
b (-b)
+

Set bitrate expressed in bits/s for CBR. shineenc -b option +is expressed in kilobits/s. +

+
+
+ + +

15.11 libtwolame

+ +

TwoLAME MP2 encoder wrapper. +

+

Requires the presence of the libtwolame headers and library during +configuration. You need to explicitly configure the build with +--enable-libtwolame. +

+ +

15.11.1 Options

+ +

The following options are supported by the libtwolame wrapper. The +twolame-equivalent options follow the FFmpeg ones and are in +parentheses. +

+
+
b (-b)
+

Set bitrate expressed in bits/s for CBR. twolame b +option is expressed in kilobits/s. Default value is 128k. +

+
+
q (-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 +ffmpeg command-line tool. For library interface users, +use global_quality. +

+
+
mode (--mode)
+

Set the mode of the resulting audio. Possible values: +

+
+
‘auto’
+

Choose mode automatically based on the input. This is the default. +

+
‘stereo’
+

Stereo +

+
‘joint_stereo’
+

Joint stereo +

+
‘dual_channel’
+

Dual channel +

+
‘mono’
+

Mono +

+
+ +
+
psymodel (--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. +

+
+
energy_levels (--energy)
+

Enable energy levels extensions when set to 1. The default value is +0 (disabled). +

+
+
error_protection (--protect)
+

Enable CRC error protection when set to 1. The default value is 0 +(disabled). +

+
+
copyright (--copyright)
+

Set MPEG audio copyright flag when set to 1. The default value is 0 +(disabled). +

+
+
original (--original)
+

Set MPEG audio original flag when set to 1. The default value is 0 +(disabled). +

+
+
+ + +

15.12 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 +--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 strict to +‘unofficial’ or lower. +

+ +

15.12.1 Options

+ +
+
b
+

Set bitrate in bits/s. Only the following bitrates are supported, otherwise +libavcodec will round to the nearest valid bitrate. +

+
+
‘6600’
+
‘8850’
+
‘12650’
+
‘14250’
+
‘15850’
+
‘18250’
+
‘19850’
+
‘23050’
+
‘23850’
+
+ +
+
dtx
+

Allow discontinuous transmission (generate comfort noise) when set to 1. The +default value is 0 (disabled). +

+
+
+ + +

15.13 libvorbis

+ +

libvorbis encoder wrapper. +

+

Requires the presence of the libvorbisenc headers and library during +configuration. You need to explicitly configure the build with +--enable-libvorbis. +

+ +

15.13.1 Options

+ +

The following options are supported by the libvorbis wrapper. The +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 oggenc’s documentations. +See http://xiph.org/vorbis/, +http://wiki.xiph.org/Vorbis-tools, and oggenc(1). +

+
+
b (-b)
+

Set bitrate expressed in bits/s for ABR. oggenc -b is +expressed in kilobits/s. +

+
+
q (-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 ‘3.0’. +

+

This option is valid only using the ffmpeg command-line tool. +For library interface users, use global_quality. +

+
+
cutoff (--advanced-encode-option lowpass_frequency=N)
+

Set cutoff bandwidth in Hz, a value of 0 disables cutoff. oggenc’s +related option is expressed in kHz. The default value is ‘0’ (cutoff +disabled). +

+
+
minrate (-m)
+

Set minimum bitrate expressed in bits/s. oggenc -m is +expressed in kilobits/s. +

+
+
maxrate (-M)
+

Set maximum bitrate expressed in bits/s. oggenc -M is +expressed in kilobits/s. This only has effect on ABR mode. +

+
+
iblock (--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. +

+
+
+ + +

15.14 mjpeg

+ +

Motion JPEG encoder. +

+ +

15.14.1 Options

+ +
+
huffman
+

Set the huffman encoding strategy. Possible values: +

+
+
‘default’
+

Use the default huffman tables. This is the default strategy. +

+
+
‘optimal’
+

Compute and use optimal huffman tables. +

+
+
+
+
+ + +

15.15 wavpack

+ +

WavPack lossless audio encoder. +

+ +

15.15.1 Options

+ +

The equivalent options for wavpack command line utility are listed in +parentheses. +

+ +

15.15.1.1 Shared options

+ +

The following shared options are effective for this encoder. Only special notes +about this particular encoder will be documented here. For the general meaning +of the options, see the Codec Options chapter. +

+
+
frame_size (--blocksize)
+

For this encoder, the range for this option is between 128 and 131072. Default +is automatically decided based on sample rate and number of channel. +

+

For the complete formula of calculating default, see +libavcodec/wavpackenc.c. +

+
+
compression_level (-f, -h, -hh, and -x)
+
+ + +

15.15.1.2 Private options

+ +
+
joint_stereo (-j)
+

Set whether to enable joint stereo. Valid values are: +

+
+
‘on (1)’
+

Force mid/side audio encoding. +

+
‘off (0)’
+

Force left/right audio encoding. +

+
‘auto’
+

Let the encoder decide automatically. +

+
+ +
+
optimize_mono
+

Set whether to enable optimization for mono. This option is only effective for +non-mono streams. Available values: +

+
+
‘on’
+

enabled +

+
‘off’
+

disabled +

+
+ +
+
+ + + +

16 Video Encoders

+ +

A description of some of the currently available video encoders +follows. +

+ +

16.1 a64_multi, a64_multi5

+ +

A64 / Commodore 64 multicolor charset encoder. a64_multi5 is extended with 5th color (colram). +

+ +

16.2 Cinepak

+ +

Cinepak aka CVID encoder. +Compatible with Windows 3.1 and vintage MacOS. +

+ +

16.2.1 Options

+ +
+
g integer
+

Keyframe interval. +A keyframe is inserted at least every -g frames, sometimes sooner. +

+
+
q:v integer
+

Quality factor. Lower is better. Higher gives lower bitrate. +The following table lists bitrates when encoding akiyo_cif.y4m for various values of -q:v with -g 100: +

+
+
-q:v 1 1918 kb/s
+
-q:v 2 1735 kb/s
+
-q:v 4 1500 kb/s
+
-q:v 10 1041 kb/s
+
-q:v 20 826 kb/s
+
-q:v 40 553 kb/s
+
-q:v 100 394 kb/s
+
-q:v 200 312 kb/s
+
-q:v 400 266 kb/s
+
-q:v 1000 237 kb/s
+
+ +
+
max_extra_cb_iterations integer
+

Max extra codebook recalculation passes, more is better and slower. +

+
+
skip_empty_cb boolean
+

Avoid wasting bytes, ignore vintage MacOS decoder. +

+
+
max_strips integer
+
min_strips integer
+

The minimum and maximum number of strips to use. +Wider range sometimes improves quality. +More strips is generally better quality but costs more bits. +Fewer strips tend to yield more keyframes. +Vintage compatible is 1..3. +

+
+
strip_number_adaptivity integer
+

How much number of strips is allowed to change between frames. +Higher is better but slower. +

+
+
+ + +

16.3 ffv1

+ +

FFv1 Encoder +

+ +

16.3.1 Options

+ +

The following options are supported by FFmpeg’s FFv1 encoder. +

+
+
context
+

Sets the context size, 0 (default) is small, 1 is big. +

+
+
coder
+

Set the coder, +

+
‘rice’
+

Golomb rice coder +

+
‘range_def’
+

Range coder with default table +

+
‘range_tab’
+

Range coder with custom table +

+
+ +
+
slicecrc
+

-1 (default, automatic), 1 use crc with zero initial and final state, 2 use crc with non zero initial and final state +

+
+
qtable
+
+
‘default’
+

default, automatic +

+
‘8bit’
+

use 8bit default +

+
‘greater8bit’
+

use >8bit default +

+
+ +
+
remap_optimizer
+

0 - 5, default 3, how much effort the encoder puts into optimizing the remap table. +

+
+
+ + +

16.4 GIF

+ +

GIF image/animation encoder. +

+ +

16.4.1 Options

+ +
+
gifflags integer
+

Sets the flags used for GIF encoding. +

+
+
offsetting
+

Enables picture offsetting. +

+

Default is enabled. +

+
+
transdiff
+

Enables transparency detection between frames. +

+

Default is enabled. +

+
+
+ +
+
gifimage integer
+

Enables encoding one full GIF image per frame, rather than an animated GIF. +

+

Default value is 0. +

+
+
global_palette integer
+

Writes a palette to the global GIF header where feasible. +

+

If disabled, every frame will always have a palette written, even if there +is a global palette supplied. +

+

Default value is 1. +

+
+
+ + +

16.5 Hap

+ +

Vidvox Hap video encoder. +

+ +

16.5.1 Options

+ +
+
format integer
+

Specifies the Hap format to encode. +

+
+
hap
+
hap_alpha
+
hap_q
+
+ +

Default value is hap. +

+
+
chunks integer
+

Specifies the number of chunks to split frames into, between 1 and 64. This +permits multithreaded decoding of large frames, potentially at the cost of +data-rate. The encoder may modify this value to divide frames evenly. +

+

Default value is 1. +

+
+
compressor integer
+

Specifies the second-stage compressor to use. If set to none, +chunks will be limited to 1, as chunked uncompressed frames offer no +benefit. +

+
+
none
+
snappy
+
+ +

Default value is snappy. +

+
+
+ + +

16.6 jpeg2000

+ +

The native jpeg 2000 encoder is lossy by default, the -q:v +option can be used to set the encoding quality. Lossless encoding +can be selected with -pred 1. +

+ +

16.6.1 Options

+ +
+
format integer
+

Can be set to either j2k or jp2 (the default) that +makes it possible to store non-rgb pix_fmts. +

+
+
tile_width integer
+

Sets tile width. Range is 1 to 1073741824. Default is 256. +

+
+
tile_height integer
+

Sets tile height. Range is 1 to 1073741824. Default is 256. +

+
+
pred integer
+

Allows setting the discrete wavelet transform (DWT) type +

+
dwt97int (Lossy)
+
dwt53 (Lossless)
+
+

Default is dwt97int +

+
+
sop boolean
+

Enable this to add SOP marker at the start of each packet. Disabled by default. +

+
+
eph boolean
+

Enable this to add EPH marker at the end of each packet header. Disabled by default. +

+
+
prog integer
+

Sets the progression order to be used by the encoder. +Possible values are: +

+
lrcp
+
rlcp
+
rpcl
+
pcrl
+
cprl
+
+

Set to lrcp by default. +

+
+
layer_rates string
+

By default, when this option is not used, compression is done using the quality metric. +This option allows for compression using compression ratio. The compression ratio for each +level could be specified. The compression ratio of a layer l species the what ratio of +total file size is contained in the first l layers. +

+

Example usage: +

+
+
ffmpeg -i input.bmp -c:v jpeg2000 -layer_rates "100,10,1" output.j2k
+
+ +

This would compress the image to contain 3 layers, where the data contained in the +first layer would be compressed by 1000 times, compressed by 100 in the first two layers, +and shall contain all data while using all 3 layers. +

+
+
+ + +

16.7 librav1e

+ +

rav1e AV1 encoder wrapper. +

+

Requires the presence of the rav1e headers and library during configuration. +You need to explicitly configure the build with --enable-librav1e. +

+ +

16.7.1 Options

+ +
+
qmax
+

Sets the maximum quantizer to use when using bitrate mode. +

+
+
qmin
+

Sets the minimum quantizer to use when using bitrate mode. +

+
+
qp
+

Uses quantizer mode to encode at the given quantizer (0-255). +

+
+
speed
+

Selects the speed preset (0-10) to encode with. +

+
+
tiles
+

Selects how many tiles to encode with. +

+
+
tile-rows
+

Selects how many rows of tiles to encode with. +

+
+
tile-columns
+

Selects how many columns of tiles to encode with. +

+
+
rav1e-params
+

Set rav1e options using a list of key=value pairs separated +by ":". See rav1e --help for a list of options. +

+

For example to specify librav1e encoding options with -rav1e-params: +

+
+
ffmpeg -i input -c:v librav1e -b:v 500K -rav1e-params speed=5:low_latency=true output.mp4
+
+ +
+
+ + +

16.8 libaom-av1

+ +

libaom AV1 encoder wrapper. +

+

Requires the presence of the libaom headers and library during +configuration. You need to explicitly configure the build with +--enable-libaom. +

+ +

16.8.1 Options

+ +

The wrapper supports the following standard libavcodec options: +

+
+
b
+

Set bitrate target in bits/second. By default this will use +variable-bitrate mode. If maxrate and minrate are +also set to the same value then it will use constant-bitrate mode, +otherwise if crf is set as well then it will use +constrained-quality mode. +

+
+
g keyint_min
+

Set key frame placement. The GOP size sets the maximum distance between +key frames; if zero the output stream will be intra-only. The minimum +distance is ignored unless it is the same as the GOP size, in which case +key frames will always appear at a fixed interval. Not set by default, +so without this option the library has completely free choice about +where to place key frames. +

+
+
qmin qmax
+

Set minimum/maximum quantisation values. Valid range is from 0 to 63 +(warning: this does not match the quantiser values actually used by AV1 +- divide by four to map real quantiser values to this range). Defaults +to min/max (no constraint). +

+
+
minrate maxrate bufsize rc_init_occupancy
+

Set rate control buffering parameters. Not used if not set - defaults +to unconstrained variable bitrate. +

+
+
threads
+

Set the number of threads to use while encoding. This may require the +tiles or row-mt options to also be set to actually +use the specified number of threads fully. Defaults to the number of +hardware threads supported by the host machine. +

+
+
profile
+

Set the encoding profile. Defaults to using the profile which matches +the bit depth and chroma subsampling of the input. +

+
+
+ +

The wrapper also has some specific options: +

+
+
cpu-used
+

Set the quality/encoding speed tradeoff. Valid range is from 0 to 8, +higher numbers indicating greater speed and lower quality. The default +value is 1, which will be slow and high quality. +

+
+
auto-alt-ref
+

Enable use of alternate reference frames. Defaults to the internal +default of the library. +

+
+
arnr-max-frames (frames)
+

Set altref noise reduction max frame count. Default is -1. +

+
+
arnr-strength (strength)
+

Set altref noise reduction filter strength. Range is -1 to 6. Default is -1. +

+
+
aq-mode (aq-mode)
+

Set adaptive quantization mode. Possible values: +

+
+
‘none (0)’
+

Disabled. +

+
+
‘variance (1)’
+

Variance-based. +

+
+
‘complexity (2)’
+

Complexity-based. +

+
+
‘cyclic (3)’
+

Cyclic refresh. +

+
+ +
+
tune (tune)
+

Set the distortion metric the encoder is tuned with. Default is psnr. +

+
+
‘psnr (0)’
+
‘ssim (1)’
+
+ +
+
lag-in-frames
+

Set the maximum number of frames which the encoder may keep in flight +at any one time for lookahead purposes. Defaults to the internal +default of the library. +

+
+
error-resilience
+

Enable error resilience features: +

+
default
+

Improve resilience against losses of whole frames. +

+
+

Not enabled by default. +

+
+
crf
+

Set the quality/size tradeoff for constant-quality (no bitrate target) +and constrained-quality (with maximum bitrate target) modes. Valid +range is 0 to 63, higher numbers indicating lower quality and smaller +output size. Only used if set; by default only the bitrate target is +used. +

+
+
static-thresh
+

Set a change threshold on blocks below which they will be skipped by +the encoder. Defined in arbitrary units as a nonnegative integer, +defaulting to zero (no blocks are skipped). +

+
+
drop-threshold
+

Set a threshold for dropping frames when close to rate control bounds. +Defined as a percentage of the target buffer - when the rate control +buffer falls below this percentage, frames will be dropped until it +has refilled above the threshold. Defaults to zero (no frames are +dropped). +

+
+
denoise-noise-level (level)
+

Amount of noise to be removed for grain synthesis. Grain synthesis is disabled if +this option is not set or set to 0. +

+
+
denoise-block-size (pixels)
+

Block size used for denoising for grain synthesis. If not set, AV1 codec +uses the default value of 32. +

+
+
undershoot-pct (pct)
+

Set datarate undershoot (min) percentage of the target bitrate. Range is -1 to 100. +Default is -1. +

+
+
overshoot-pct (pct)
+

Set datarate overshoot (max) percentage of the target bitrate. Range is -1 to 1000. +Default is -1. +

+
+
minsection-pct (pct)
+

Minimum percentage variation of the GOP bitrate from the target bitrate. If minsection-pct +is not set, the libaomenc wrapper computes it as follows: (minrate * 100 / bitrate). +Range is -1 to 100. Default is -1 (unset). +

+
+
maxsection-pct (pct)
+

Maximum percentage variation of the GOP bitrate from the target bitrate. If maxsection-pct +is not set, the libaomenc wrapper computes it as follows: (maxrate * 100 / bitrate). +Range is -1 to 5000. Default is -1 (unset). +

+
+
frame-parallel (boolean)
+

Enable frame parallel decodability features. Default is true. +

+
+
tiles
+

Set the number of tiles to encode the input video with, as columns x +rows. Larger numbers allow greater parallelism in both encoding and +decoding, but may decrease coding efficiency. Defaults to the minimum +number of tiles required by the size of the input video (this is 1x1 +(that is, a single tile) for sizes up to and including 4K). +

+
+
tile-columns tile-rows
+

Set the number of tiles as log2 of the number of tile rows and columns. +Provided for compatibility with libvpx/VP9. +

+
+
row-mt (Requires libaom >= 1.0.0-759-g90a15f4f2)
+

Enable row based multi-threading. Disabled by default. +

+
+
enable-cdef (boolean)
+

Enable Constrained Directional Enhancement Filter. The libaom-av1 +encoder enables CDEF by default. +

+
+
enable-restoration (boolean)
+

Enable Loop Restoration Filter. Default is true for libaom-av1. +

+
+
enable-global-motion (boolean)
+

Enable the use of global motion for block prediction. Default is true. +

+
+
enable-intrabc (boolean)
+

Enable block copy mode for intra block prediction. This mode is +useful for screen content. Default is true. +

+
+
enable-rect-partitions (boolean) (Requires libaom >= v2.0.0)
+

Enable rectangular partitions. Default is true. +

+
+
enable-1to4-partitions (boolean) (Requires libaom >= v2.0.0)
+

Enable 1:4/4:1 partitions. Default is true. +

+
+
enable-ab-partitions (boolean) (Requires libaom >= v2.0.0)
+

Enable AB shape partitions. Default is true. +

+
+
enable-angle-delta (boolean) (Requires libaom >= v2.0.0)
+

Enable angle delta intra prediction. Default is true. +

+
+
enable-cfl-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable chroma predicted from luma intra prediction. Default is true. +

+
+
enable-filter-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable filter intra predictor. Default is true. +

+
+
enable-intra-edge-filter (boolean) (Requires libaom >= v2.0.0)
+

Enable intra edge filter. Default is true. +

+
+
enable-smooth-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable smooth intra prediction mode. Default is true. +

+
+
enable-paeth-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable paeth predictor in intra prediction. Default is true. +

+
+
enable-palette (boolean) (Requires libaom >= v2.0.0)
+

Enable palette prediction mode. Default is true. +

+
+
enable-flip-idtx (boolean) (Requires libaom >= v2.0.0)
+

Enable extended transform type, including FLIPADST_DCT, DCT_FLIPADST, +FLIPADST_FLIPADST, ADST_FLIPADST, FLIPADST_ADST, IDTX, V_DCT, H_DCT, +V_ADST, H_ADST, V_FLIPADST, H_FLIPADST. Default is true. +

+
+
enable-tx64 (boolean) (Requires libaom >= v2.0.0)
+

Enable 64-pt transform. Default is true. +

+
+
reduced-tx-type-set (boolean) (Requires libaom >= v2.0.0)
+

Use reduced set of transform types. Default is false. +

+
+
use-intra-dct-only (boolean) (Requires libaom >= v2.0.0)
+

Use DCT only for INTRA modes. Default is false. +

+
+
use-inter-dct-only (boolean) (Requires libaom >= v2.0.0)
+

Use DCT only for INTER modes. Default is false. +

+
+
use-intra-default-tx-only (boolean) (Requires libaom >= v2.0.0)
+

Use Default-transform only for INTRA modes. Default is false. +

+
+
enable-ref-frame-mvs (boolean) (Requires libaom >= v2.0.0)
+

Enable temporal mv prediction. Default is true. +

+
+
enable-reduced-reference-set (boolean) (Requires libaom >= v2.0.0)
+

Use reduced set of single and compound references. Default is false. +

+
+
enable-obmc (boolean) (Requires libaom >= v2.0.0)
+

Enable obmc. Default is true. +

+
+
enable-dual-filter (boolean) (Requires libaom >= v2.0.0)
+

Enable dual filter. Default is true. +

+
+
enable-diff-wtd-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable difference-weighted compound. Default is true. +

+
+
enable-dist-wtd-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable distance-weighted compound. Default is true. +

+
+
enable-onesided-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable one sided compound. Default is true. +

+
+
enable-interinter-wedge (boolean) (Requires libaom >= v2.0.0)
+

Enable interinter wedge compound. Default is true. +

+
+
enable-interintra-wedge (boolean) (Requires libaom >= v2.0.0)
+

Enable interintra wedge compound. Default is true. +

+
+
enable-masked-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable masked compound. Default is true. +

+
+
enable-interintra-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable interintra compound. Default is true. +

+
+
enable-smooth-interintra (boolean) (Requires libaom >= v2.0.0)
+

Enable smooth interintra mode. Default is true. +

+
+
aom-params
+

Set libaom options using a list of key=value pairs separated +by ":". For a list of supported options, see aomenc --help under the +section "AV1 Specific Options". +

+

For example to specify libaom encoding options with -aom-params: +

+
+
ffmpeg -i input -c:v libaom-av1 -b:v 500K -aom-params tune=psnr:enable-tpl-model=1 output.mp4
+
+ +
+
+ + +

16.9 liboapv

+ +

Advanced Professional Video codec encoder wrapper. +

+

This encoder requires the presence of the liboapv headers and library +during configuration. You need to explicitly configure the build with +--enable-liboapv. +

+
+

Many liboapv encoder options are mapped to FFmpeg global codec options, +while unique encoder options are provided through private options. +

+

The apv project website is at https://github.com/AcademySoftwareFoundation/openapv. +

+ +

16.9.1 Options

+ +

The following options are supported by the liboapv wrapper. +

+
+

To get a more extensive documentation of the liboapv options, consult the +liboapv documentation. +

+
+
preset
+

Set the quality-speed tradeoff [fastest, fast, medium, slow, placebo, default] +

+
+
qp
+

Set the quantization parameter value for CQP rate control mode. +

+
+
oapv-params (parse_apv_params)
+

Set liboapvenc options using a list of key=value pairs separated +by ":". See the liboapv encoder user guide for a list of accepted parameters. +

+
+ + +

16.10 libsvtav1

+ +

SVT-AV1 encoder wrapper. +

+

Requires the presence of the SVT-AV1 headers and library during configuration. +You need to explicitly configure the build with --enable-libsvtav1. +

+ +

16.10.1 Options

+ +
+
profile
+

Set the encoding profile. +

+
‘main’
+
‘high’
+
‘professional’
+
+ +
+
level
+

Set the operating point level. For example: ’4.0’ +

+
+
hielevel
+

Set the Hierarchical prediction levels. +

+
‘3level’
+
‘4level’
+

This is the default. +

+
+ +
+
tier
+

Set the operating point tier. +

+
‘main’
+

This is the default. +

+
‘high’
+
+ +
+
qmax
+

Set the maximum quantizer to use when using a bitrate mode. +

+
+
qmin
+

Set the minimum quantizer to use when using a bitrate mode. +

+
+
crf
+

Constant rate factor value used in crf rate control mode (0-63). +

+
+
qp
+

Set the quantizer used in cqp rate control mode (0-63). +

+
+
sc_detection
+

Enable scene change detection. +

+
+
la_depth
+

Set number of frames to look ahead (0-120). +

+
+
preset
+

Set the quality-speed tradeoff, in the range 0 to 13. Higher values are +faster but lower quality. +

+
+
tile_rows
+

Set log2 of the number of rows of tiles to use (0-6). +

+
+
tile_columns
+

Set log2 of the number of columns of tiles to use (0-4). +

+
+
svtav1-params
+

Set SVT-AV1 options using a list of key=value pairs separated +by ":". See the SVT-AV1 encoder user guide for a list of accepted parameters. +

+
+
+ + +

16.11 libsvtjpegxs

+ +

SVT-JPEG-XS encoder wrapper. +

+

Requires the presence of the SVT-JPEG-XS headers and library during configuration. +You need to explicitly configure the build with --enable-libsvtjpegxs. +

+ +

16.11.1 Options

+ +
+
decomp_v
+

Set vertical decomposition level +

+
decomp_h
+

Set horizontal decomposition level +

+
+
quantization
+

Set the quantization algorithm. +

+
‘deadzone’
+
‘uniform’
+
+ +
+
coding-signs
+

Enable Signs handling strategy +

+
‘disable’
+
‘fast’
+
‘full’
+
+ +
+
coding-sigf
+

Enable Significance coding +

+
+
coding-vpred
+

Enable Vertical Prediction coding +

+
‘disable’
+
‘no_residuals’
+
‘no_coeffs’
+
+ +
+
+ + +

16.12 libjxl

+ +

libjxl JPEG XL encoder wrapper. +

+

Requires the presence of the libjxl headers and library during +configuration. You need to explicitly configure the build with +--enable-libjxl. +

+ +

16.12.1 Options

+ +

The libjxl wrapper supports the following options: +

+
+
distance
+

Set the target Butteraugli distance. This is a quality setting: lower +distance yields higher quality, with distance=1.0 roughly comparable to +libjpeg Quality 90 for photographic content. Setting distance=0.0 yields +true lossless encoding. Valid values range between 0.0 and 15.0, and sane +values rarely exceed 5.0. Setting distance=0.1 usually attains +transparency for most input. The default is 1.0. +

+
+
effort
+

Set the encoding effort used. Higher effort values produce more consistent +quality and usually produces a better quality/bpp curve, at the cost of +more CPU time required. Valid values range from 1 to 9, and the default is 7. +

+
+
modular
+

Force the encoder to use Modular mode instead of choosing automatically. The +default is to use VarDCT for lossy encoding and Modular for lossless. VarDCT +is generally superior to Modular for lossy encoding but does not support +lossless encoding. +

+
+
+ + +

16.13 libkvazaar

+ +

Kvazaar H.265/HEVC encoder. +

+

Requires the presence of the libkvazaar headers and library during +configuration. You need to explicitly configure the build with +--enable-libkvazaar. +

+ +

16.13.1 Options

+ +
+
b
+

Set target video bitrate in bit/s and enable rate control. +

+
+
kvazaar-params
+

Set kvazaar parameters as a list of name=value pairs separated +by commas (,). See kvazaar documentation for a list of options. +

+
+
+ + +

16.14 libopenh264

+ +

Cisco libopenh264 H.264/MPEG-4 AVC encoder wrapper. +

+

This encoder requires the presence of the libopenh264 headers and +library during configuration. You need to explicitly configure the +build with --enable-libopenh264. The library is detected using +pkg-config. +

+

For more information about the library see +http://www.openh264.org. +

+ +

16.14.1 Options

+ +

The following FFmpeg global options affect the configurations of the +libopenh264 encoder. +

+
+
b
+

Set the bitrate (as a number of bits per second). +

+
+
g
+

Set the GOP size. +

+
+
maxrate
+

Set the max bitrate (as a number of bits per second). +

+
+
flags +global_header
+

Set global header in the bitstream. +

+
+
slices
+

Set the number of slices, used in parallelized encoding. Default value +is 0. This is only used when slice_mode is set to +‘fixed’. +

+
+
loopfilter
+

Enable loop filter, if set to 1 (automatically enabled). To disable +set a value of 0. +

+
+
profile
+

Set profile restrictions. If set to the value of ‘main’ enable +CABAC (set the SEncParamExt.iEntropyCodingModeFlag flag to 1). +

+
+
max_nal_size
+

Set maximum NAL size in bytes. +

+
+
allow_skip_frames
+

Allow skipping frames to hit the target bitrate if set to 1. +

+
+ + +

16.15 libtheora

+ +

libtheora Theora encoder wrapper. +

+

Requires the presence of the libtheora headers and library during +configuration. You need to explicitly configure the build with +--enable-libtheora. +

+

For more information about the libtheora project see +http://www.theora.org/. +

+ +

16.15.1 Options

+ +

The following global options are mapped to internal libtheora options +which affect the quality and the bitrate of the encoded stream. +

+
+
b
+

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. +

+
+
flags
+

Used to enable constant quality mode (VBR) encoding through the +qscale flag, and to enable the pass1 and pass2 +modes. +

+
+
g
+

Set the GOP size. +

+
+
global_quality
+

Set the global quality as an integer in lambda units. +

+

Only relevant when VBR mode is enabled with flags +qscale. The +value is converted to QP units by dividing it by 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. +

+
+
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 ffmpeg command-line +tool. For library interface users, use global_quality. +

+
+ + +

16.15.2 Examples

+ +
    +
  • Set maximum constant quality (VBR) encoding with ffmpeg: +
    +
    ffmpeg -i INPUT -codec:v libtheora -q:v 10 OUTPUT.ogg
    +
    + +
  • Use ffmpeg to convert a CBR 1000 kbps Theora video stream: +
    +
    ffmpeg -i INPUT -codec:v libtheora -b:v 1000k OUTPUT.ogg
    +
    +
+ + +

16.16 libvpx

+ +

VP8/VP9 format supported through libvpx. +

+

Requires the presence of the libvpx headers and library during configuration. +You need to explicitly configure the build with --enable-libvpx. +

+ +

16.16.1 Options

+ +

The following options are supported by the libvpx wrapper. The +vpxenc-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 +the Codec Options chapter. +

+

To get more documentation of the libvpx options, invoke the command +ffmpeg -h encoder=libvpx, ffmpeg -h encoder=libvpx-vp9 or +vpxenc --help. Further information is available in the libvpx API +documentation. +

+
+
b (target-bitrate)
+

Set bitrate in bits/s. Note that FFmpeg’s b option is +expressed in bits/s, while vpxenc’s target-bitrate is in +kilobits/s. +

+
+
g (kf-max-dist)
+
keyint_min (kf-min-dist)
+
qmin (min-q)
+

Minimum (Best Quality) Quantizer. +

+
+
qmax (max-q)
+

Maximum (Worst Quality) Quantizer. +Can be changed per-frame. +

+
+
bufsize (buf-sz, buf-optimal-sz)
+

Set ratecontrol buffer size (in bits). Note vpxenc’s options are +specified in milliseconds, the libvpx wrapper converts this value as follows: +buf-sz = bufsize * 1000 / bitrate, +buf-optimal-sz = bufsize * 1000 / bitrate * 5 / 6. +

+
+
rc_init_occupancy (buf-initial-sz)
+

Set number of bits which should be loaded into the rc buffer before decoding +starts. Note vpxenc’s option is specified in milliseconds, the libvpx +wrapper converts this value as follows: +rc_init_occupancy * 1000 / bitrate. +

+
+
undershoot-pct
+

Set datarate undershoot (min) percentage of the target bitrate. +

+
+
overshoot-pct
+

Set datarate overshoot (max) percentage of the target bitrate. +

+
+
skip_threshold (drop-frame)
+
qcomp (bias-pct)
+
maxrate (maxsection-pct)
+

Set GOP max bitrate in bits/s. Note vpxenc’s option is specified as a +percentage of the target bitrate, the libvpx wrapper converts this value as +follows: (maxrate * 100 / bitrate). +

+
+
minrate (minsection-pct)
+

Set GOP min bitrate in bits/s. Note vpxenc’s option is specified as a +percentage of the target bitrate, the libvpx wrapper converts this value as +follows: (minrate * 100 / bitrate). +

+
+
minrate, maxrate, b end-usage=cbr
+

(minrate == maxrate == bitrate). +

+
+
crf (end-usage=cq, cq-level)
+
tune (tune)
+
+
‘psnr (psnr)’
+
‘ssim (ssim)’
+
+ +
+
quality, deadline (deadline)
+
+
‘best’
+

Use best quality deadline. Poorly named and quite slow, this option should be +avoided as it may give worse quality output than good. +

+
‘good’
+

Use good quality deadline. This is a good trade-off between speed and quality +when used with the cpu-used option. +

+
‘realtime’
+

Use realtime quality deadline. +

+
+ +
+
speed, cpu-used (cpu-used)
+

Set quality/speed ratio modifier. Higher values speed up the encode at the cost +of quality. +

+
+
nr (noise-sensitivity)
+
static-thresh
+

Set a change threshold on blocks below which they will be skipped by the +encoder. +

+
+
slices (token-parts)
+

Note that FFmpeg’s slices option gives the total number of partitions, +while vpxenc’s token-parts is given as +log2(partitions). +

+
+
max-intra-rate
+

Set maximum I-frame bitrate as a percentage of the target bitrate. A value of 0 +means unlimited. +

+
+
force_key_frames
+

VPX_EFLAG_FORCE_KF +

+
+
Alternate reference frame related
+
+
auto-alt-ref
+

Enable use of alternate reference frames (2-pass only). +Values greater than 1 enable multi-layer alternate reference frames (VP9 only). +

+
arnr-maxframes
+

Set altref noise reduction max frame count. +

+
arnr-type
+

Set altref noise reduction filter type: backward, forward, centered. +

+
arnr-strength
+

Set altref noise reduction filter strength. +

+
rc-lookahead, lag-in-frames (lag-in-frames)
+

Set number of frames to look ahead for frametype and ratecontrol. +

+
min-gf-interval
+

Set minimum golden/alternate reference frame interval (VP9 only). +

+
+ +
+
error-resilient
+

Enable error resiliency features. +

+
+
sharpness integer
+

Increase sharpness at the expense of lower PSNR. +The valid range is [0, 7]. +

+
+
ts-parameters
+

Sets the temporal scalability configuration using a :-separated list of +key=value pairs. For example, to specify temporal scalability parameters +with ffmpeg: +

+
ffmpeg -i INPUT -c:v libvpx -ts-parameters ts_number_layers=3:\
+ts_target_bitrate=250,500,1000:ts_rate_decimator=4,2,1:\
+ts_periodicity=4:ts_layer_id=0,2,1,2:ts_layering_mode=3 OUTPUT
+
+

Below is a brief explanation of each of the parameters, please +refer to struct vpx_codec_enc_cfg in vpx/vpx_encoder.h for more +details. +

+
ts_number_layers
+

Number of temporal coding layers. +

+
ts_target_bitrate
+

Target bitrate for each temporal layer (in kbps). +(bitrate should be inclusive of the lower temporal layer). +

+
ts_rate_decimator
+

Frame rate decimation factor for each temporal layer. +

+
ts_periodicity
+

Length of the sequence defining frame temporal layer membership. +

+
ts_layer_id
+

Template defining the membership of frames to temporal layers. +

+
ts_layering_mode
+

(optional) Selecting the temporal structure from a set of pre-defined temporal layering modes. +Currently supports the following options. +

+
0
+

No temporal layering flags are provided internally, +relies on flags being passed in using metadata field in AVFrame +with following keys. +

+
vp8-flags
+

Sets the flags passed into the encoder to indicate the referencing scheme for +the current frame. +Refer to function vpx_codec_encode in vpx/vpx_encoder.h for more +details. +

+
temporal_id
+

Explicitly sets the temporal id of the current frame to encode. +

+
+
+
2
+

Two temporal layers. 0-1... +

+
3
+

Three temporal layers. 0-2-1-2...; with single reference frame. +

+
4
+

Same as option "3", except there is a dependency between +the two temporal layer 2 frames within the temporal period. +

+
+
+
+ +
+
VP8-specific options
+
+
screen-content-mode
+

Screen content mode, one of: 0 (off), 1 (screen), 2 (screen with more aggressive rate control). +

+
+ +
+
VP9-specific options
+
+
lossless
+

Enable lossless mode. +

+
tile-columns
+

Set number of tile columns to use. Note this is given as +log2(tile_columns). For example, 8 tile columns would be requested by +setting the tile-columns option to 3. +

+
tile-rows
+

Set number of tile rows to use. Note this is given as log2(tile_rows). +For example, 4 tile rows would be requested by setting the tile-rows +option to 2. +

+
frame-parallel
+

Enable frame parallel decodability features. +

+
aq-mode
+

Set adaptive quantization mode (0: off (default), 1: variance 2: complexity, 3: +cyclic refresh, 4: equator360). +

+
colorspace color-space
+

Set input color space. The VP9 bitstream supports signaling the following +colorspaces: +

+
‘rgb’ sRGB
+
‘bt709’ bt709
+
‘unspecified’ unknown
+
‘bt470bg’ bt601
+
‘smpte170m’ smpte170
+
‘smpte240m’ smpte240
+
‘bt2020_ncl’ bt2020
+
+
+
row-mt boolean
+

Enable row based multi-threading. +

+
tune-content
+

Set content type: default (0), screen (1), film (2). +

+
corpus-complexity
+

Corpus VBR mode is a variant of standard VBR where the complexity distribution +midpoint is passed in rather than calculated for a specific clip or chunk. +

+

The valid range is [0, 10000]. 0 (default) uses standard VBR. +

+
enable-tpl boolean
+

Enable temporal dependency model. +

+
ref-frame-config
+

Using per-frame metadata, set members of the structure vpx_svc_ref_frame_config_t in vpx/vp8cx.h to fine-control referencing schemes and frame buffer management. +
Use a :-separated list of key=value pairs. +For example, +

+
av_dict_set(&av_frame->metadata, "ref-frame-config", \
+"rfc_update_buffer_slot=7:rfc_lst_fb_idx=0:rfc_gld_fb_idx=1:rfc_alt_fb_idx=2:rfc_reference_last=0:rfc_reference_golden=0:rfc_reference_alt_ref=0");
+
+
+
rfc_update_buffer_slot
+

Indicates the buffer slot number to update +

+
rfc_update_last
+

Indicates whether to update the LAST frame +

+
rfc_update_golden
+

Indicates whether to update GOLDEN frame +

+
rfc_update_alt_ref
+

Indicates whether to update ALT_REF frame +

+
rfc_lst_fb_idx
+

LAST frame buffer index +

+
rfc_gld_fb_idx
+

GOLDEN frame buffer index +

+
rfc_alt_fb_idx
+

ALT_REF frame buffer index +

+
rfc_reference_last
+

Indicates whether to reference LAST frame +

+
rfc_reference_golden
+

Indicates whether to reference GOLDEN frame +

+
rfc_reference_alt_ref
+

Indicates whether to reference ALT_REF frame +

+
rfc_reference_duration
+

Indicates frame duration +

+
+
+
+ +
+
+ +

For more information about libvpx see: +http://www.webmproject.org/ +

+ +

16.17 libvvenc

+ +

VVenC H.266/VVC encoder wrapper. +

+

This encoder requires the presence of the libvvenc headers and library +during configuration. You need to explicitly configure the build with +--enable-libvvenc. +

+

The VVenC project website is at +https://github.com/fraunhoferhhi/vvenc. +

+ +

16.17.1 Supported Pixel Formats

+ +

VVenC supports only 10-bit color spaces as input. But the internal (encoded) +bit depth can be set to 8-bit or 10-bit at runtime. +

+ +

16.17.2 Options

+ +
+
b
+

Sets target video bitrate. +

+
+
g
+

Set the GOP size. Currently support for g=1 (Intra only) or default. +

+
+
preset
+

Set the VVenC preset. +

+
+
levelidc
+

Set level idc. +

+
+
tier
+

Set vvc tier. +

+
+
qp
+

Set constant quantization parameter. +

+
+
subopt boolean
+

Set subjective (perceptually motivated) optimization. Default is 1 (on). +

+
+
bitdepth8 boolean
+

Set 8bit coding mode instead of using 10bit. Default is 0 (off). +

+
+
period
+

set (intra) refresh period in seconds. +

+
+
vvenc-params
+

Set vvenc options using a list of key=value couples separated +by ":". See vvencapp --fullhelp or vvencFFapp --fullhelp for a list of options. +

+

For example, the options might be provided as: +

+
+
intraperiod=64:decodingrefreshtype=idr:poc0idr=1:internalbitdepth=8
+
+ +

For example the encoding options might be provided with -vvenc-params: +

+
+
ffmpeg -i input -c:v libvvenc -b 1M -vvenc-params intraperiod=64:decodingrefreshtype=idr:poc0idr=1:internalbitdepth=8 output.mp4
+
+ +
+
+ + +

16.18 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. +

+ +

16.18.1 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. +

+ +

16.18.2 Options

+ +
+
-lossless boolean
+

Enables/Disables use of lossless mode. Default is 0. +

+
+
-compression_level 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 method option in libwebp. The valid range is 0 to 6. +Default is 4. +

+
+
-quality float
+

For lossy encoding, this controls image quality. For lossless encoding, this +controls the effort and time spent in compression. +Range is 0 to 100. Default is 75. +

+
+
-preset type
+

Configuration preset. This does some automatic settings based on the general +type of the image. +

+
none
+

Do not use a preset. +

+
default
+

Use the encoder default. +

+
picture
+

Digital picture, like portrait, inner shot +

+
photo
+

Outdoor photograph, with natural lighting +

+
drawing
+

Hand or line drawing, with high-contrast details +

+
icon
+

Small-sized colorful images +

+
text
+

Text-like +

+
+ +
+
+ + +

16.19 libx264, libx264rgb

+ +

x264 H.264/MPEG-4 AVC encoder wrapper. +

+

This encoder requires the presence of the libx264 headers and library +during configuration. You need to explicitly configure the build with +--enable-libx264. +

+

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). +

+

Many libx264 encoder options are mapped to FFmpeg global codec +options, while unique encoder options are provided through private +options. Additionally the x264opts and x264-params +private options allows one to pass a list of key=value tuples as accepted +by the libx264 x264_param_parse function. +

+

The x264 project website is at +http://www.videolan.org/developers/x264.html. +

+

The libx264rgb encoder is the same as libx264, except it accepts packed RGB +pixel formats as input instead of YUV. +

+ +

16.19.1 Supported Pixel Formats

+ +

x264 supports 8- to 10-bit color spaces. The exact bit depth is controlled at +x264’s configure time. +

+ +

16.19.2 Options

+ +

The following options are supported by the libx264 wrapper. The +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 +the Codec Options chapter. +

+

To get a more accurate and extensive documentation of the libx264 +options, invoke the command x264 --fullhelp or consult +the libx264 documentation. +

+

In the list below, note that the x264 option name is shown +in parentheses after the libavcodec corresponding name, in case there +is a direct mapping. +

+
+
b (bitrate)
+

Set bitrate in bits/s. Note that FFmpeg’s b option is +expressed in bits/s, while x264’s bitrate is in +kilobits/s. +

+
+
bf (bframes)
+

Number of B-frames between I and P-frames +

+
+
g (keyint)
+

Maximum GOP size +

+
+
qmin (qpmin)
+

Minimum quantizer scale +

+
+
qmax (qpmax)
+

Maximum quantizer scale +

+
+
qdiff (qpstep)
+

Maximum difference between quantizer scales +

+
+
qblur (qblur)
+

Quantizer curve blur +

+
+
qcomp (qcomp)
+

Quantizer curve compression factor +

+
+
refs (ref)
+

Number of reference frames each P-frame can use. The range is 0-16. +

+
+
level (level)
+

Set the x264_param_t.i_level_idc value in case the value is +positive, it is ignored otherwise. +

+

This value can be set using the AVCodecContext API (e.g. by +setting the AVCodecContext value directly), and is specified as +an integer mapped on a corresponding level (e.g. the value 31 maps +to H.264 level IDC "3.1", as defined in the x264_levels +table). It is ignored when set to a non positive value. +

+

Alternatively it can be set as a private option, overriding the value +set in AVCodecContext, and in this case must be specified as +the level IDC identifier (e.g. "3.1"), as defined by H.264 Annex A. +

+
+
sc_threshold (scenecut)
+

Sets the threshold for the scene change detection. +

+
+
trellis (trellis)
+

Performs Trellis quantization to increase efficiency. Enabled by default. +

+
+
nr (nr)
+

Noise reduction +

+
+
me_range (merange)
+

Maximum range of the motion search in pixels. +

+
+
me_method (me)
+

Set motion estimation method. Possible values in the decreasing order +of speed: +

+
+
‘dia (dia)’
+
‘epzs (dia)’
+

Diamond search with radius 1 (fastest). ‘epzs’ is an alias for +‘dia’. +

+
‘hex (hex)’
+

Hexagonal search with radius 2. +

+
‘umh (umh)’
+

Uneven multi-hexagon search. +

+
‘esa (esa)’
+

Exhaustive search. +

+
‘tesa (tesa)’
+

Hadamard exhaustive search (slowest). +

+
+ +
+
forced-idr
+

Normally, when forcing a I-frame type, the encoder can select any type +of I-frame. This option forces it to choose an IDR-frame. +

+
+
subq (subme)
+

Sub-pixel motion estimation method. +

+
+
b_strategy (b-adapt)
+

Adaptive B-frame placement decision algorithm. Use only on first-pass. +

+
+
keyint_min (min-keyint)
+

Minimum GOP size. +

+
+
coder
+

Set entropy encoder. Possible values: +

+
+
‘ac’
+

Enable CABAC. +

+
+
‘vlc’
+

Enable CAVLC and disable CABAC. It generates the same effect as +x264’s --no-cabac option. +

+
+ +
+
cmp
+

Set full pixel motion estimation comparison algorithm. Possible values: +

+
+
‘chroma’
+

Enable chroma in motion estimation. +

+
+
‘sad’
+

Ignore chroma in motion estimation. It generates the same effect as +x264’s --no-chroma-me option. +

+
+ +
+
threads (threads)
+

Number of encoding threads. +

+
+
thread_type
+

Set multithreading technique. Possible values: +

+
+
‘slice’
+

Slice-based multithreading. It generates the same effect as +x264’s --sliced-threads option. +

+
‘frame’
+

Frame-based multithreading. +

+
+ +
+
flags
+

Set encoding flags. It can be used to disable closed GOP and enable +open GOP by setting it to -cgop. The result is similar to +the behavior of x264’s --open-gop option. +

+
+
rc_init_occupancy (vbv-init)
+

Initial VBV buffer occupancy +

+
+
preset (preset)
+

Set the encoding preset. +

+
+
tune (tune)
+

Set tuning of the encoding params. +

+
+
profile (profile)
+

Set profile restrictions. +

+
+
fastfirstpass
+

Enable fast settings when encoding first pass, when set to 1. When set +to 0, it has the same effect of x264’s +--slow-firstpass option. +

+
+
crf (crf)
+

Set the quality for constant quality mode. +

+
+
crf_max (crf-max)
+

In CRF mode, prevents VBV from lowering quality beyond this point. +

+
+
qp (qp)
+

Set constant quantization rate control method parameter. +

+
+
aq-mode (aq-mode)
+

Set AQ method. Possible values: +

+
+
‘none (0)’
+

Disabled. +

+
+
‘variance (1)’
+

Variance AQ (complexity mask). +

+
+
‘autovariance (2)’
+

Auto-variance AQ (experimental). +

+
+ +
+
aq-strength (aq-strength)
+

Set AQ strength, reduce blocking and blurring in flat and textured areas. +

+
+
psy
+

Use psychovisual optimizations when set to 1. When set to 0, it has the +same effect as x264’s --no-psy option. +

+
+
psy-rd (psy-rd)
+

Set strength of psychovisual optimization, in +psy-rd:psy-trellis format. +

+
+
rc-lookahead (rc-lookahead)
+

Set number of frames to look ahead for frametype and ratecontrol. +

+
+
weightb
+

Enable weighted prediction for B-frames when set to 1. When set to 0, +it has the same effect as x264’s --no-weightb option. +

+
+
weightp (weightp)
+

Set weighted prediction method for P-frames. Possible values: +

+
+
‘none (0)’
+

Disabled +

+
‘simple (1)’
+

Enable only weighted refs +

+
‘smart (2)’
+

Enable both weighted refs and duplicates +

+
+ +
+
ssim (ssim)
+

Enable calculation and printing SSIM stats after the encoding. +

+
+
intra-refresh (intra-refresh)
+

Enable the use of Periodic Intra Refresh instead of IDR frames when set +to 1. +

+
+
avcintra-class (class)
+

Configure the encoder to generate AVC-Intra. +Valid values are 50, 100 and 200 +

+
+
bluray-compat (bluray-compat)
+

Configure the encoder to be compatible with the bluray standard. +It is a shorthand for setting "bluray-compat=1 force-cfr=1". +

+
+
b-bias (b-bias)
+

Set the influence on how often B-frames are used. +

+
+
b-pyramid (b-pyramid)
+

Set method for keeping of some B-frames as references. Possible values: +

+
+
‘none (none)’
+

Disabled. +

+
‘strict (strict)’
+

Strictly hierarchical pyramid. +

+
‘normal (normal)’
+

Non-strict (not Blu-ray compatible). +

+
+ +
+
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 x264’s --no-mixed-refs option. +

+
+
8x8dct
+

Enable adaptive spatial transform (high profile 8x8 transform) +when set to 1. When set to 0, it has the same effect as +x264’s --no-8x8dct option. +

+
+
fast-pskip
+

Enable early SKIP detection on P-frames when set to 1. When set +to 0, it has the same effect as x264’s +--no-fast-pskip option. +

+
+
aud (aud)
+

Enable use of access unit delimiters when set to 1. +

+
+
mbtree
+

Enable use macroblock tree ratecontrol when set to 1. When set +to 0, it has the same effect as x264’s +--no-mbtree option. +

+
+
deblock (deblock)
+

Set loop filter parameters, in alpha:beta form. +

+
+
cplxblur (cplxblur)
+

Set fluctuations reduction in QP (before curve compression). +

+
+
partitions (partitions)
+

Set partitions to consider as a comma-separated list of values. +Possible values in the list: +

+
+
‘p8x8’
+

8x8 P-frame partition. +

+
‘p4x4’
+

4x4 P-frame partition. +

+
‘b8x8’
+

4x4 B-frame partition. +

+
‘i8x8’
+

8x8 I-frame partition. +

+
‘i4x4’
+

4x4 I-frame partition. +(Enabling ‘p4x4’ requires ‘p8x8’ to be enabled. Enabling +‘i8x8’ requires adaptive spatial transform (8x8dct +option) to be enabled.) +

+
‘none (none)’
+

Do not consider any partitions. +

+
‘all (all)’
+

Consider every partition. +

+
+ +
+
direct-pred (direct)
+

Set direct MV prediction mode. Possible values: +

+
+
‘none (none)’
+

Disable MV prediction. +

+
‘spatial (spatial)’
+

Enable spatial predicting. +

+
‘temporal (temporal)’
+

Enable temporal predicting. +

+
‘auto (auto)’
+

Automatically decided. +

+
+ +
+
slice-max-size (slice-max-size)
+

Set the limit of the size of each slice in bytes. If not specified +but RTP payload size (ps) is specified, that is used. +

+
+
stats (stats)
+

Set the file name for multi-pass stats. +

+
+
nal-hrd (nal-hrd)
+

Set signal HRD information (requires vbv-bufsize to be set). +Possible values: +

+
+
‘none (none)’
+

Disable HRD information signaling. +

+
‘vbr (vbr)’
+

Variable bit rate. +

+
‘cbr (cbr)’
+

Constant bit rate (not allowed in MP4 container). +

+
+ +
+
x264opts opts
+
x264-params opts
+

Override the x264 configuration using a :-separated list of key=value +options. +

+

The argument for both options is a list of key=value +couples separated by ":". With x264opts the value can be +omitted, and the value 1 is assumed in that case. +

+

For filter and psy-rd options values that use ":" as a +separator themselves, use "," instead. They accept it as well since +long ago but this is kept undocumented for some reason. +

+

For example, the options might be provided as: +

+
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
+
+ +

For example to specify libx264 encoding options with ffmpeg: +

+
ffmpeg -i foo.mpg -c:v libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
+
+ +

To get the complete list of the libx264 options, invoke the command +x264 --fullhelp or consult the libx264 documentation. +

+
+
a53cc boolean
+

Import closed captions (which must be ATSC compatible format) into output. +Only the mpeg2 and h264 decoders provide these. Default is 1 (on). +

+
+
udu_sei boolean
+

Import user data unregistered SEI if available into output. Default is 0 (off). +

+
+
mb_info boolean
+

Set mb_info data through AVFrameSideData, only useful when used from the +API. Default is 0 (off). +

+
+ +

Encoding ffpresets for common usages are provided so they can be used with the +general presets system (e.g. passing the pre option). +

+ +

16.20 libx265

+ +

x265 H.265/HEVC encoder wrapper. +

+

This encoder requires the presence of the libx265 headers and library +during configuration. You need to explicitly configure the build with +--enable-libx265. +

+ +

16.20.1 Options

+ +
+
b
+

Sets target video bitrate. +

+
+
bf
+
g
+

Set the GOP size. +

+
+
keyint_min
+

Minimum GOP size. +

+
+
refs
+

Number of reference frames each P-frame can use. The range is from 1-16. +

+
+
preset
+

Set the x265 preset. +

+
+
tune
+

Set the x265 tune parameter. +

+
+
profile
+

Set profile restrictions. +

+
+
crf
+

Set the quality for constant quality mode. +

+
+
qp
+

Set constant quantization rate control method parameter. +

+
+
qmin
+

Minimum quantizer scale. +

+
+
qmax
+

Maximum quantizer scale. +

+
+
qdiff
+

Maximum difference between quantizer scales. +

+
+
qblur
+

Quantizer curve blur +

+
+
qcomp
+

Quantizer curve compression factor +

+
+
i_qfactor
+
b_qfactor
+
forced-idr
+

Normally, when forcing a I-frame type, the encoder can select any type +of I-frame. This option forces it to choose an IDR-frame. +

+
+
x265-stats
+

Specify the file name for 2-pass stats. This is set automatically when using +the -passlogfile option. +

+
+
udu_sei boolean
+

Import user data unregistered SEI if available into output. Default is 0 (off). +

+
+
x265-params
+

Set x265 options using a list of key=value couples separated +by ":". See x265 --help for a list of options. +

+

For example to specify libx265 encoding options with -x265-params: +

+
+
ffmpeg -i input -c:v libx265 -x265-params crf=26:psy-rd=1 output.mp4
+
+
+
+ + +

16.21 libxavs2

+ +

xavs2 AVS2-P2/IEEE1857.4 encoder wrapper. +

+

This encoder requires the presence of the libxavs2 headers and library +during configuration. You need to explicitly configure the build with +--enable-libxavs2. +

+

The following standard libavcodec options are used: +

    +
  • b / bit_rate +
  • g / gop_size +
  • bf / max_b_frames +
+ +

The encoder also has its own specific options: +

+

16.21.1 Options

+ +
+
lcu_row_threads
+

Set the number of parallel threads for rows from 1 to 8 (default 5). +

+
+
initial_qp
+

Set the xavs2 quantization parameter from 1 to 63 (default 34). This is +used to set the initial qp for the first frame. +

+
+
qp
+

Set the xavs2 quantization parameter from 1 to 63 (default 34). This is +used to set the qp value under constant-QP mode. +

+
+
max_qp
+

Set the max qp for rate control from 1 to 63 (default 55). +

+
+
min_qp
+

Set the min qp for rate control from 1 to 63 (default 20). +

+
+
speed_level
+

Set the Speed level from 0 to 9 (default 0). Higher is better but slower. +

+
+
log_level
+

Set the log level from -1 to 3 (default 0). -1: none, 0: error, +1: warning, 2: info, 3: debug. +

+
+
xavs2-params
+

Set xavs2 options using a list of key=value couples separated +by ":". +

+

For example to specify libxavs2 encoding options with -xavs2-params: +

+
+
ffmpeg -i input -c:v libxavs2 -xavs2-params RdoqLevel=0 output.avs2
+
+
+
+ + +

16.22 libxeve

+ +

eXtra-fast Essential Video Encoder (XEVE) MPEG-5 EVC encoder wrapper. +The xeve-equivalent options or values are listed in parentheses for easy migration. +

+

This encoder requires the presence of the libxeve headers and library +during configuration. You need to explicitly configure the build with +--enable-libxeve. +

+
+

Many libxeve encoder options are mapped to FFmpeg global codec options, +while unique encoder options are provided through private options. +Additionally the xeve-params private options allows one to pass a list +of key=value tuples as accepted by the libxeve parse_xeve_params function. +

+

The xeve project website is at https://github.com/mpeg5/xeve. +

+ +

16.22.1 Options

+ +

The following options are supported by the libxeve wrapper. +The xeve-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 +the Codec Options chapter. +

+
+

To get a more accurate and extensive documentation of the libxeve options, +invoke the command xeve_app --help or consult the libxeve documentation. +

+
+
b (bitrate)
+

Set target video bitrate in bits/s. +Note that FFmpeg’s b option is expressed in bits/s, while xeve’s bitrate is in kilobits/s. +

+
+
bf (bframes)
+

Set the maximum number of B frames (1,3,7,15). +

+
+
g (keyint)
+

Set the GOP size (I-picture period). +

+
+
preset (preset)
+

Set the xeve preset. +Set the encoder preset value to determine encoding speed [fast, medium, slow, placebo] +

+
+
tune (tune)
+

Set the encoder tune parameter [psnr, zerolatency] +

+
+
profile (profile)
+

Set the encoder profile [0: baseline; 1: main] +

+
+
crf (crf)
+

Set the quality for constant quality mode. +Constant rate factor <10..49> [default: 32] +

+
+
qp (qp)
+

Set constant quantization rate control method parameter. +Quantization parameter qp <0..51> [default: 32] +

+
+
threads (threads)
+

Force to use a specific number of threads +

+
+
+ + +

16.23 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 +--enable-libxvid --enable-gpl. +

+

The native mpeg4 encoder supports the MPEG-4 Part 2 format, so +users can encode to this format without this library. +

+ +

16.23.1 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 the Codec +Options chapter for their documentation. The other shared options +which are not listed have no effect for the libxvid encoder. +

+
+
b
+
g
+
qmin
+
qmax
+
mpeg_quant
+
threads
+
bf
+
b_qfactor
+
b_qoffset
+
flags
+

Set specific encoding flags. Possible values: +

+
+
‘mv4’
+

Use four motion vector by macroblock. +

+
+
‘aic’
+

Enable high quality AC prediction. +

+
+
‘gray’
+

Only encode grayscale. +

+
+
‘qpel’
+

Enable quarter-pixel motion compensation. +

+
+
‘cgop’
+

Enable closed GOP. +

+
+
‘global_header’
+

Place global headers in extradata instead of every keyframe. +

+
+
+ +
+
gmc
+

Enable the use of global motion compensation (GMC). Default is 0 +(disabled). +

+
+
me_quality
+

Set motion estimation quality level. Possible values in decreasing order of +speed and increasing order of quality: +

+
+
‘0’
+

Use no motion estimation (default). +

+
+
‘1, 2’
+

Enable advanced diamond zonal search for 16x16 blocks and half-pixel +refinement for 16x16 blocks. +

+
+
‘3, 4’
+

Enable all of the things described above, plus advanced diamond zonal +search for 8x8 blocks and half-pixel refinement for 8x8 blocks, also +enable motion estimation on chroma planes for P and B-frames. +

+
+
‘5, 6’
+

Enable all of the things described above, plus extended 16x16 and 8x8 +blocks search. +

+
+ +
+
mbd
+

Set macroblock decision algorithm. Possible values in the increasing +order of quality: +

+
+
‘simple’
+

Use macroblock comparing function algorithm (default). +

+
+
‘bits’
+

Enable rate distortion-based half pixel and quarter pixel refinement for +16x16 blocks. +

+
+
‘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. +

+
+ +
+
lumi_aq
+

Enable lumi masking adaptive quantization when set to 1. Default is 0 +(disabled). +

+
+
variance_aq
+

Enable variance adaptive quantization when set to 1. Default is 0 +(disabled). +

+

When combined with 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. +

+
+
trellis
+

Set rate-distortion optimal quantization. +

+
+
ssim
+

Set structural similarity (SSIM) displaying method. Possible values: +

+
+
‘off’
+

Disable displaying of SSIM information. +

+
+
‘avg’
+

Output average SSIM at the end of encoding to stdout. The format of +showing the average SSIM is: +

+
+
Average SSIM: %f
+
+ +

For users who are not familiar with C, %f means a float number, or +a decimal (e.g. 0.939232). +

+
+
‘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: +

+
+
       SSIM: avg: %1.3f min: %1.3f max: %1.3f
+
+ +

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). +

+
+
+ +
+
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. +

+
+
+ + +

16.24 MediaCodec

+ +

MediaCodec encoder wrapper enables hardware-accelerated video encoding on +Android device. It supports H.264, H.265 (HEVC), VP8, VP9, MPEG-4, and AV1 +encoding (whether works or not is device dependent). +

+

Android provides two sets of APIs: Java MediaCodec and NDK MediaCodec. The +MediaCodec encoder wrapper supports both. Note that the NDK MediaCodec API +operates without requiring JVM, but may fail to function outside the JVM +environment due to dependencies on system framework services, particularly +after Android 15. +

+
+
ndk_codec boolean
+

Use the NDK-based MediaCodec API instead of the Java API. Enabled by default +if av_jni_get_java_vm() return NULL. +

+
+
ndk_async boolean
+

Use NDK MediaCodec in async mode. Async mode has less overhead than poll in a +loop in sync mode. The drawback of async mode is AV_CODEC_FLAG_GLOBAL_HEADER +doesn’t work (use extract_extradata bsf when necessary). It doesn’t work and +will be disabled automatically on devices below Android 8.0. +

+
+
codec_name string
+

A codec type can have multiple implementations on a single device, this option +specify which backend to use (via MediaCodec createCodecByName API). It’s NULL +by default, and encoder is created by createEncoderByType. +

+
+
bitrate_mode integer
+
+

Possible values: +

+
‘cq’
+

Constant quality mode +

+
‘vbr’
+

Variable bitrate mode +

+
‘cbr’
+

Constant bitrate mode +

+
‘cbr_fd’
+

Constant bitrate mode with frame drops +

+
+ +
+
pts_as_dts boolean
+

Use PTS as DTS. This is a workaround since MediaCodec API doesn’t provide +decoding timestamp. It is enabled automatically if B frame is 0. +

+
+
operating_rate integer
+

The desired operating rate that the codec will need to operate at, zero for +unspecified. This is used for cases like high-speed/slow-motion video capture, +where the video encoder format contains the target playback rate (e.g. 30fps), +but the component must be able to handle the high operating capture rate (e.g. +240fps). This rate will be used by codec for resource planning and setting the +operating points. +

+
+
qp_i_min integer
+

Minimum quantization parameter for I frame. +

+
qp_p_min integer
+

Minimum quantization parameter for P frame. +

+
qp_b_min integer
+

Minimum quantization parameter for B frame. +

+
qp_i_max integer
+

Maximum quantization parameter for I frame. +

+
qp_p_max integer
+

Maximum quantization parameter for P frame. +

+
qp_b_max integer
+

Maximum quantization parameter for B frame. +

+
+
+ + +

16.25 MediaFoundation

+ +

The following wrappers for encoders in the MediaFoundation framework are +available: +

+
    +
  • h264_mf +
  • hevc_mf +
  • av1_mf +
+ +

These support both software and hardware encoding. +

+

Video encoders can take input in either of nv12 or yuv420p form +(some encoders support both, some support only either - in practice, +nv12 is the safer choice, especially among HW encoders). +

+

Hardware-accelerated encoding requires D3D11, including hardware +scaling capabilities through the scale_d3d11 filter. +

+

To list all available options for the MediaFoundation encoders, use: +ffmpeg -h encoder=<encoder> e.g. ffmpeg -h encoder=h264_mf +

+ +

16.25.1 Options

+ +
+
rate_control
+

Select rate control mode. Available modes: +

+
+
‘default’
+

Default mode +

+
‘cbr’
+

CBR mode +

+
‘pc_vbr’
+

Peak constrained VBR mode +

+
‘u_vbr’
+

Unconstrained VBR mode +

+
‘quality’
+

Quality mode +

+
‘ld_vbr’
+

Low delay VBR mode (requires Windows 8+) +

+
‘g_vbr’
+

Global VBR mode (requires Windows 8+) +

+
‘gld_vbr’
+

Global low delay VBR mode (requires Windows 8+) +

+
+ +
+
scenario
+

Select usage scenario. Available scenarios: +

+
+
‘default’
+

Default scenario +

+
‘display_remoting’
+

Display remoting scenario +

+
‘video_conference’
+

Video conference scenario +

+
‘archive’
+

Archive scenario +

+
‘live_streaming’
+

Live streaming scenario +

+
‘camera_record’
+

Camera record scenario +

+
‘display_remoting_with_feature_map’
+

Display remoting with feature map scenario +

+
+ +
+
quality
+

Set encoding quality (0-100). -1 means default quality. +

+
+
hw_encoding
+

Force hardware encoding (0-1). Default is 0 (disabled). +

+
+
+ + +

16.25.2 Examples

+ +

Hardware encoding: +

+
ffmpeg -i input.mp4 -c:v h264_mf -hw_encoding 1 output.mp4
+
+ +

Hardware-accelerated decoding with hardware encoding: +

+
ffmpeg -hwaccel d3d11va -i input.mp4 -c:v h264_mf -hw_encoding 1 output.mp4
+
+ +

Hardware-accelerated decoding, HW scaling and encoding with quality setting: +

+
ffmpeg -hwaccel d3d11va -hwaccel_output_format d3d11 -i input.mp4 -vf scale_d3d11=1920:1080 -c:v hevc_mf -hw_encoding 1 -quality 80 output.mp4
+
+ + +

16.26 Microsoft RLE

+ +

Microsoft RLE aka MSRLE encoder. +Only 8-bit palette mode supported. +Compatible with Windows 3.1 and Windows 95. +

+ +

16.26.1 Options

+ +
+
g integer
+

Keyframe interval. +A keyframe is inserted at least every -g frames, sometimes sooner. +

+
+ + +

16.27 mpeg2

+ +

MPEG-2 video encoder. +

+ +

16.27.1 Options

+ +
+
profile
+

Select the mpeg2 profile to encode: +

+
+
‘422’
+
‘high’
+
‘ss’
+

Spatially Scalable +

+
‘snr’
+

SNR Scalable +

+
‘main’
+
‘simple’
+
+ +
+
level
+

Select the mpeg2 level to encode: +

+
+
‘high’
+
‘high1440’
+
‘main’
+
‘low’
+
+ +
+
seq_disp_ext integer
+

Specifies if the encoder should write a sequence_display_extension to the +output. +

+
-1
+
auto
+

Decide automatically to write it or not (this is the default) by checking if +the data to be written is different from the default or unspecified values. +

+
0
+
never
+

Never write it. +

+
1
+
always
+

Always write it. +

+
+
+
video_format integer
+

Specifies the video_format written into the sequence display extension +indicating the source of the video pictures. The default is ‘unspecified’, +can be ‘component’, ‘pal’, ‘ntsc’, ‘secam’ or ‘mac’. +For maximum compatibility, use ‘component’. +

+
a53cc boolean
+

Import closed captions (which must be ATSC compatible format) into output. +Default is 1 (on). +

+
+ + +

16.28 png

+ +

PNG image encoder. +

+ +

16.28.1 Options

+ +
+
compression_level
+

Sets the compression level, from 0 to 9(default) +

+
+ + +

16.28.2 Private options

+ +
+
dpi integer
+

Set physical density of pixels, in dots per inch, unset by default +

+
dpm integer
+

Set physical density of pixels, in dots per meter, unset by default +

+
pred method
+

Set prediction method (none, sub, up, avg, paeth, mixed), default is paeth +

+
+ + +

16.29 ProRes

+ +

Apple ProRes encoder. +

+

FFmpeg contains 2 ProRes encoders, the prores-aw and prores-ks encoder. +The used encoder can be chosen with the -vcodec option. +

+ +

16.29.1 Private Options for prores-ks

+ +
+
profile integer
+

Select the ProRes profile to encode +

+
‘proxy’
+
‘lt’
+
‘standard’
+
‘hq’
+
‘4444’
+
‘4444xq’
+
+ +
+
quant_mat integer
+

Select quantization matrix. +

+
‘auto’
+
‘default’
+
‘proxy’
+
‘lt’
+
‘standard’
+
‘hq’
+
+

If set to auto, the matrix matching the profile will be picked. +If not set, the matrix providing the highest quality, default, will be +picked. +

+
+
bits_per_mb integer
+

How many bits to allot for coding one macroblock. Different profiles use +between 200 and 2400 bits per macroblock, the maximum is 8000. +

+
+
mbs_per_slice integer
+

Number of macroblocks in each slice (1-8); the default value (8) +should be good in almost all situations. +

+
+
vendor string
+

Override the 4-byte vendor ID. +A custom vendor ID like apl0 would claim the stream was produced by +the Apple encoder. +

+
+
alpha_bits integer
+

Specify number of bits for alpha component. +Possible values are 0, 8 and 16. +Use 0 to disable alpha plane coding. +

+
+
+ + +

16.29.2 Speed considerations

+ +

In the default mode of operation the encoder has to honor frame constraints +(i.e. not produce 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 bits_per_mb limit will improve the speed. +

+

For the fastest encoding speed set the qscale parameter (4 is the +recommended value) and do not set a size constraint. +

+ +

16.30 QSV Encoders

+ +

The family of Intel QuickSync Video encoders (MPEG-2, H.264, HEVC, JPEG/MJPEG, +VP9, AV1) +

+ +

16.30.1 Ratecontrol Method

+

The ratecontrol method is selected as follows: +

    +
  • When global_quality is specified, a quality-based mode is used. +Specifically this means either +
      +
    • CQP - constant quantizer scale, when the qscale codec flag is +also set (the -qscale ffmpeg option). + +
    • LA_ICQ - intelligent constant quality with lookahead, when the +look_ahead option is also set. + +
    • ICQ – intelligent constant quality otherwise. For the ICQ modes, global +quality range is 1 to 51, with 1 being the best quality. +
    + +
  • Otherwise when the desired average bitrate is specified with the b +option, a bitrate-based mode is used. +
      +
    • LA - VBR with lookahead, when the look_ahead option is specified. + +
    • VCM - video conferencing mode, when the vcm option is set. + +
    • CBR - constant bitrate, when maxrate is specified and equal to +the average bitrate. + +
    • VBR - variable bitrate, when maxrate is specified, but is higher +than the average bitrate. + +
    • AVBR - average VBR mode, when maxrate is not specified, both +avbr_accuracy and avbr_convergence are set to non-zero. This +mode is available for H264 and HEVC on Windows. +
    + +
  • Otherwise the default ratecontrol method CQP is used. +
+ +

Note that depending on your system, a different mode than the one you specified +may be selected by the encoder. Set the verbosity level to verbose or +higher to see the actual settings used by the QSV runtime. +

+ +

16.30.2 Global Options -> MSDK Options

+

Additional libavcodec global options are mapped to MSDK options as follows: +

+
    +
  • g/gop_size -> GopPicSize + +
  • bf/max_b_frames+1 -> GopRefDist + +
  • rc_init_occupancy/rc_initial_buffer_occupancy -> +InitialDelayInKB + +
  • slices -> NumSlice + +
  • refs -> NumRefFrame + +
  • b_strategy/b_frame_strategy -> BRefType + +
  • cgop/CLOSED_GOP codec flag -> GopOptFlag + +
  • For the CQP mode, the i_qfactor/i_qoffset and +b_qfactor/b_qoffset set the difference between QPP and QPI, +and QPP and QPB respectively. + +
  • Setting the coder option to the value vlc will make the H.264 +encoder use CAVLC instead of CABAC. + +
+ + +

16.30.3 Common Options

+

Following options are used by all qsv encoders. +

+
+
async_depth
+

Specifies how many asynchronous operations an application performs +before the application explicitly synchronizes the result. If zero, +the value is not specified. +

+
+
preset
+

This option itemizes a range of choices from veryfast (best speed) to veryslow +(best quality). +

+
‘veryfast’
+
‘faster’
+
‘fast’
+
‘medium’
+
‘slow’
+
‘slower’
+
‘veryslow’
+
+ +
+
forced_idr
+

Forcing I frames as IDR frames. +

+
+
low_power
+

For encoders set this flag to ON to reduce power consumption and GPU usage. +

+
+ + +

16.30.4 Runtime Options

+

Following options can be used during qsv encoding. +

+
+
global_quality
+
i_quant_factor
+
i_quant_offset
+
b_quant_factor
+
b_quant_offset
+

Supported in h264_qsv and hevc_qsv. +Change these value to reset qsv codec’s qp configuration. +

+
+
max_frame_size
+

Supported in h264_qsv and hevc_qsv. +Change this value to reset qsv codec’s MaxFrameSize configuration. +

+
+
gop_size
+

Change this value to reset qsv codec’s gop configuration. +

+
+
int_ref_type
+
int_ref_cycle_size
+
int_ref_qp_delta
+
int_ref_cycle_dist
+

Supported in h264_qsv and hevc_qsv. +Change these value to reset qsv codec’s Intra Refresh configuration. +

+
+
qmax
+
qmin
+
max_qp_i
+
min_qp_i
+
max_qp_p
+
min_qp_p
+
max_qp_b
+
min_qp_b
+

Supported in h264_qsv. +Change these value to reset qsv codec’s max/min qp configuration. +

+
+
low_delay_brc
+

Supported in h264_qsv, hevc_qsv and av1_qsv. +Change this value to reset qsv codec’s low_delay_brc configuration. +

+
+
framerate
+

Change this value to reset qsv codec’s framerate configuration. +

+
+
bit_rate
+
rc_buffer_size
+
rc_initial_buffer_occupancy
+
rc_max_rate
+

Change these value to reset qsv codec’s bitrate control configuration. +

+
+
pic_timing_sei
+

Supported in h264_qsv and hevc_qsv. +Change this value to reset qsv codec’s pic_timing_sei configuration. +

+
+
qsv_params
+

Set QSV encoder parameters as a colon-separated list of key-value pairs. +

+

The qsv_params should be formatted as key1=value1:key2=value2:.... +

+

These parameters are passed directly to the underlying Intel Quick Sync Video (QSV) encoder using the MFXSetParameter function. +

+

Example: +

+
ffmpeg -i input.mp4 -c:v h264_qsv -qsv_params "CodingOption1=1:CodingOption2=2" output.mp4
+
+ +

This option allows fine-grained control over various encoder-specific settings provided by the QSV encoder. +

+
+ + +

16.30.5 H264 options

+

These options are used by h264_qsv +

+
+
extbrc
+

Extended bitrate control. +

+
+
recovery_point_sei
+

Set this flag to insert the recovery point SEI message at the beginning of every +intra refresh cycle. +

+
+
rdo
+

Enable rate distortion optimization. +

+
+
max_frame_size
+

Maximum encoded frame size in bytes. +

+
+
max_frame_size_i
+

Maximum encoded frame size for I frames in bytes. If this value is set as larger +than zero, then for I frames the value set by max_frame_size is ignored. +

+
+
max_frame_size_p
+

Maximum encoded frame size for P frames in bytes. If this value is set as larger +than zero, then for P frames the value set by max_frame_size is ignored. +

+
+
max_slice_size
+

Maximum encoded slice size in bytes. +

+
+
bitrate_limit
+

Toggle bitrate limitations. +Modifies bitrate to be in the range imposed by the QSV encoder. Setting this +flag off may lead to violation of HRD conformance. Mind that specifying bitrate +below the QSV encoder range might significantly affect quality. If on this +option takes effect in non CQP modes: if bitrate is not in the range imposed +by the QSV encoder, it will be changed to be in the range. +

+
+
mbbrc
+

Setting this flag enables macroblock level bitrate control that generally +improves subjective visual quality. Enabling this flag may have negative impact +on performance and objective visual quality metric. +

+
+
low_delay_brc
+

Setting this flag turns on or off LowDelayBRC feature in qsv plugin, which provides +more accurate bitrate control to minimize the variance of bitstream size frame +by frame. Value: -1-default 0-off 1-on +

+
+
adaptive_i
+

This flag controls insertion of I frames by the QSV encoder. Turn ON this flag +to allow changing of frame type from P and B to I. +

+
+
adaptive_b
+

This flag controls changing of frame type from B to P. +

+
+
p_strategy
+

Enable P-pyramid: 0-default 1-simple 2-pyramid(bf need to be set to 0). +

+
+
b_strategy
+

This option controls usage of B frames as reference. +

+
+
dblk_idc
+

This option disable deblocking. It has value in range 0~2. +

+
+
cavlc
+

If set, CAVLC is used; if unset, CABAC is used for encoding. +

+
+
vcm
+

Video conferencing mode, please see ratecontrol method. +

+
+
idr_interval
+

Distance (in I-frames) between IDR frames. +

+
+
pic_timing_sei
+

Insert picture timing SEI with pic_struct_syntax element. +

+
+
single_sei_nal_unit
+

Put all the SEI messages into one NALU. +

+
+
max_dec_frame_buffering
+

Maximum number of frames buffered in the DPB. +

+
+
look_ahead
+

Use VBR algorithm with look ahead. +

+
+
look_ahead_depth
+

Depth of look ahead in number frames. +

+
+
look_ahead_downsampling
+

Downscaling factor for the frames saved for the lookahead analysis. +

+
‘unknown’
+
‘auto’
+
‘off’
+
‘2x’
+
‘4x’
+
+ +
+
int_ref_type
+

Specifies intra refresh type. The major goal of intra refresh is improvement of +error resilience without significant impact on encoded bitstream size caused by +I frames. The SDK encoder achieves this by encoding part of each frame in +refresh cycle using intra MBs. none means no refresh. vertical means +vertical refresh, by column of MBs. horizontal means horizontal refresh, +by rows of MBs. slice means horizontal refresh by slices without +overlapping. In case of slice, in_ref_cycle_size is ignored. To enable +intra refresh, B frame should be set to 0. +

+
+
int_ref_cycle_size
+

Specifies number of pictures within refresh cycle starting from 2. 0 and 1 are +invalid values. +

+
+
int_ref_qp_delta
+

Specifies QP difference for inserted intra MBs. This is signed value in +[-51, 51] range if target encoding bit-depth for luma samples is 8 and this +range is [-63, 63] for 10 bit-depth or [-75, 75] for 12 bit-depth respectively. +

+
+
int_ref_cycle_dist
+

Distance between the beginnings of the intra-refresh cycles in frames. +

+
+
profile
+
+
‘unknown’
+
‘baseline’
+
‘main’
+
‘high’
+
+ +
+
a53cc
+

Use A53 Closed Captions (if available). +

+
+
aud
+

Insert the Access Unit Delimiter NAL. +

+
+
mfmode
+

Multi-Frame Mode. +

+
‘off’
+
‘auto’
+
+ +
+
repeat_pps
+

Repeat pps for every frame. +

+
+
max_qp_i
+

Maximum video quantizer scale for I frame. +

+
+
min_qp_i
+

Minimum video quantizer scale for I frame. +

+
+
max_qp_p
+

Maximum video quantizer scale for P frame. +

+
+
min_qp_p
+

Minimum video quantizer scale for P frame. +

+
+
max_qp_b
+

Maximum video quantizer scale for B frame. +

+
+
min_qp_b
+

Minimum video quantizer scale for B frame. +

+
+
scenario
+

Provides a hint to encoder about the scenario for the encoding session. +

+
‘unknown’
+
‘displayremoting’
+
‘videoconference’
+
‘archive’
+
‘livestreaming’
+
‘cameracapture’
+
‘videosurveillance’
+
‘gamestreaming’
+
‘remotegaming’
+
+ +
+
avbr_accuracy
+

Accuracy of the AVBR ratecontrol (unit of tenth of percent). +

+
+
avbr_convergence
+

Convergence of the AVBR ratecontrol (unit of 100 frames) +

+

The parameters avbr_accuracy and avbr_convergence are for the +average variable bitrate control (AVBR) algorithm. +The algorithm focuses on overall encoding quality while meeting the specified +bitrate, target_bitrate, within the accuracy range avbr_accuracy, +after a avbr_Convergence period. This method does not follow HRD and the +instant bitrate is not capped or padded. +

+
+
skip_frame
+

Use per-frame metadata "qsv_skip_frame" to skip frame when encoding. This option +defines the usage of this metadata. +

+
‘no_skip’
+

Frame skipping is disabled. +

+
‘insert_dummy’
+

Encoder inserts into bitstream frame where all macroblocks are encoded as +skipped. +

+
‘insert_nothing’
+

Similar to insert_dummy, but encoder inserts nothing into bitstream. The skipped +frames are still used in brc. For example, gop still include skipped frames, and +the frames after skipped frames will be larger in size. +

+
‘brc_only’
+

skip_frame metadata indicates the number of missed frames before the current +frame. +

+
+ +
+
+ + +

16.30.6 HEVC Options

+

These options are used by hevc_qsv +

+
+
extbrc
+

Extended bitrate control. +

+
+
recovery_point_sei
+

Set this flag to insert the recovery point SEI message at the beginning of every +intra refresh cycle. +

+
+
rdo
+

Enable rate distortion optimization. +

+
+
max_frame_size
+

Maximum encoded frame size in bytes. +

+
+
max_frame_size_i
+

Maximum encoded frame size for I frames in bytes. If this value is set as larger +than zero, then for I frames the value set by max_frame_size is ignored. +

+
+
max_frame_size_p
+

Maximum encoded frame size for P frames in bytes. If this value is set as larger +than zero, then for P frames the value set by max_frame_size is ignored. +

+
+
max_slice_size
+

Maximum encoded slice size in bytes. +

+
+
mbbrc
+

Setting this flag enables macroblock level bitrate control that generally +improves subjective visual quality. Enabling this flag may have negative impact +on performance and objective visual quality metric. +

+
+
low_delay_brc
+

Setting this flag turns on or off LowDelayBRC feature in qsv plugin, which provides +more accurate bitrate control to minimize the variance of bitstream size frame +by frame. Value: -1-default 0-off 1-on +

+
+
adaptive_i
+

This flag controls insertion of I frames by the QSV encoder. Turn ON this flag +to allow changing of frame type from P and B to I. +

+
+
adaptive_b
+

This flag controls changing of frame type from B to P. +

+
+
p_strategy
+

Enable P-pyramid: 0-default 1-simple 2-pyramid(bf need to be set to 0). +

+
+
b_strategy
+

This option controls usage of B frames as reference. +

+
+
dblk_idc
+

This option disable deblocking. It has value in range 0~2. +

+
+
idr_interval
+

Distance (in I-frames) between IDR frames. +

+
‘begin_only’
+

Output an IDR-frame only at the beginning of the stream. +

+
+ +
+
load_plugin
+

A user plugin to load in an internal session. +

+
‘none’
+
‘hevc_sw’
+
‘hevc_hw’
+
+ +
+
load_plugins
+

A :-separate list of hexadecimal plugin UIDs to load in +an internal session. +

+
+
look_ahead_depth
+

Depth of look ahead in number frames, available when extbrc option is enabled. +

+
+
profile
+

Set the encoding profile (scc requires libmfx >= 1.32). +

+
+
‘unknown’
+
‘main’
+
‘main10’
+
‘mainsp’
+
‘rext’
+
‘scc’
+
+ +
+
tier
+

Set the encoding tier (only level >= 4 can support high tier). +This option only takes effect when the level option is specified. +

+
+
‘main’
+
‘high’
+
+ +
+
gpb
+

1: GPB (generalized P/B frame) +

+

0: regular P frame. +

+
+
tile_cols
+

Number of columns for tiled encoding. +

+
+
tile_rows
+

Number of rows for tiled encoding. +

+
+
aud
+

Insert the Access Unit Delimiter NAL. +

+
+
pic_timing_sei
+

Insert picture timing SEI with pic_struct_syntax element. +

+
+
transform_skip
+

Turn this option ON to enable transformskip. It is supported on platform equal +or newer than ICL. +

+
+
int_ref_type
+

Specifies intra refresh type. The major goal of intra refresh is improvement of +error resilience without significant impact on encoded bitstream size caused by +I frames. The SDK encoder achieves this by encoding part of each frame in +refresh cycle using intra MBs. none means no refresh. vertical means +vertical refresh, by column of MBs. horizontal means horizontal refresh, +by rows of MBs. slice means horizontal refresh by slices without +overlapping. In case of slice, in_ref_cycle_size is ignored. To enable +intra refresh, B frame should be set to 0. +

+
+
int_ref_cycle_size
+

Specifies number of pictures within refresh cycle starting from 2. 0 and 1 are +invalid values. +

+
+
int_ref_qp_delta
+

Specifies QP difference for inserted intra MBs. This is signed value in +[-51, 51] range if target encoding bit-depth for luma samples is 8 and this +range is [-63, 63] for 10 bit-depth or [-75, 75] for 12 bit-depth respectively. +

+
+
int_ref_cycle_dist
+

Distance between the beginnings of the intra-refresh cycles in frames. +

+
+
max_qp_i
+

Maximum video quantizer scale for I frame. +

+
+
min_qp_i
+

Minimum video quantizer scale for I frame. +

+
+
max_qp_p
+

Maximum video quantizer scale for P frame. +

+
+
min_qp_p
+

Minimum video quantizer scale for P frame. +

+
+
max_qp_b
+

Maximum video quantizer scale for B frame. +

+
+
min_qp_b
+

Minimum video quantizer scale for B frame. +

+
+
scenario
+

Provides a hint to encoder about the scenario for the encoding session. +

+
‘unknown’
+
‘displayremoting’
+
‘videoconference’
+
‘archive’
+
‘livestreaming’
+
‘cameracapture’
+
‘videosurveillance’
+
‘gamestreaming’
+
‘remotegaming’
+
+ +
+
avbr_accuracy
+

Accuracy of the AVBR ratecontrol (unit of tenth of percent). +

+
+
avbr_convergence
+

Convergence of the AVBR ratecontrol (unit of 100 frames) +

+

The parameters avbr_accuracy and avbr_convergence are for the +average variable bitrate control (AVBR) algorithm. +The algorithm focuses on overall encoding quality while meeting the specified +bitrate, target_bitrate, within the accuracy range avbr_accuracy, +after a avbr_Convergence period. This method does not follow HRD and the +instant bitrate is not capped or padded. +

+
+
skip_frame
+

Use per-frame metadata "qsv_skip_frame" to skip frame when encoding. This option +defines the usage of this metadata. +

+
‘no_skip’
+

Frame skipping is disabled. +

+
‘insert_dummy’
+

Encoder inserts into bitstream frame where all macroblocks are encoded as +skipped. +

+
‘insert_nothing’
+

Similar to insert_dummy, but encoder inserts nothing into bitstream. The skipped +frames are still used in brc. For example, gop still include skipped frames, and +the frames after skipped frames will be larger in size. +

+
‘brc_only’
+

skip_frame metadata indicates the number of missed frames before the current +frame. +

+
+ +
+
+ + +

16.30.7 MPEG2 Options

+

These options are used by mpeg2_qsv +

+
profile
+
+
‘unknown’
+
‘simple’
+
‘main’
+
‘high’
+
+
+
+ + +

16.30.8 VP9 Options

+

These options are used by vp9_qsv +

+
profile
+
+
‘unknown’
+
‘profile0’
+
‘profile1’
+
‘profile2’
+
‘profile3’
+
+ +
+
tile_cols
+

Number of columns for tiled encoding (requires libmfx >= 1.29). +

+
+
tile_rows
+

Number of rows for tiled encoding (requires libmfx >= 1.29). +

+
+ + +

16.30.9 AV1 Options

+

These options are used by av1_qsv (requires libvpl). +

+
profile
+
+
‘unknown’
+
‘main’
+
+ +
+
tile_cols
+

Number of columns for tiled encoding. +

+
+
tile_rows
+

Number of rows for tiled encoding. +

+
+
adaptive_i
+

This flag controls insertion of I frames by the QSV encoder. Turn ON this flag +to allow changing of frame type from P and B to I. +

+
+
adaptive_b
+

This flag controls changing of frame type from B to P. +

+
+
b_strategy
+

This option controls usage of B frames as reference. +

+
+
extbrc
+

Extended bitrate control. +

+
+
look_ahead_depth
+

Depth of look ahead in number frames, available when extbrc option is enabled. +

+
+
low_delay_brc
+

Setting this flag turns on or off LowDelayBRC feature in qsv plugin, which provides +more accurate bitrate control to minimize the variance of bitstream size frame +by frame. Value: -1-default 0-off 1-on +

+
+
max_frame_size
+

Set the allowed max size in bytes for each frame. If the frame size exceeds +the limitation, encoder will adjust the QP value to control the frame size. +Invalid in CQP rate control mode. +

+
+
max_frame_size_i
+

Maximum encoded frame size for I frames in bytes. If this value is set as larger +than zero, then for I frames the value set by max_frame_size is ignored. +

+
+
max_frame_size_p
+

Maximum encoded frame size for P frames in bytes. If this value is set as larger +than zero, then for P frames the value set by max_frame_size is ignored. +

+
+ + +

16.31 snow

+ + +

16.31.1 Options

+ +
+
iterative_dia_size
+

dia size for the iterative motion estimation +

+
+ + +

16.32 VAAPI encoders

+ +

Wrappers for hardware encoders accessible via VAAPI. +

+

These encoders only accept input in VAAPI hardware surfaces. If you have input +in software frames, use the hwupload filter to upload them to the GPU. +

+

The following standard libavcodec options are used: +

    +
  • g / gop_size +
  • bf / max_b_frames +
  • profile + +

    If not set, this will be determined automatically from the format of the input +frames and the profiles supported by the driver. +

  • level +
  • b / bit_rate +
  • maxrate / rc_max_rate +
  • bufsize / rc_buffer_size +
  • rc_init_occupancy / rc_initial_buffer_occupancy +
  • compression_level + +

    Speed / quality tradeoff: higher values are faster / worse quality. +

  • q / global_quality + +

    Size / quality tradeoff: higher values are smaller / worse quality. +

  • qmin +
  • qmax +
  • i_qfactor / i_quant_factor +
  • i_qoffset / i_quant_offset +
  • b_qfactor / b_quant_factor +
  • b_qoffset / b_quant_offset +
  • slices +
+ +

All encoders support the following options: +

+
low_power
+

Some drivers/platforms offer a second encoder for some codecs intended to use +less power than the default encoder; setting this option will attempt to use +that encoder. Note that it may support a reduced feature set, so some other +options may not be available in this mode. +

+
+
idr_interval
+

Set the number of normal intra frames between full-refresh (IDR) frames in +open-GOP mode. The intra frames are still IRAPs, but will not include global +headers and may have non-decodable leading pictures. +

+
+
b_depth
+

Set the B-frame reference depth. When set to one (the default), all B-frames +will refer only to P- or I-frames. When set to greater values multiple layers +of B-frames will be present, frames in each layer only referring to frames in +higher layers. +

+
+
async_depth
+

Maximum processing parallelism. Increase this to improve single channel +performance. This option doesn’t work if driver doesn’t implement vaSyncBuffer +function. Please make sure there are enough hw_frames allocated if a large +number of async_depth is used. +

+
+
max_frame_size
+

Set the allowed max size in bytes for each frame. If the frame size exceeds +the limitation, encoder will adjust the QP value to control the frame size. +Invalid in CQP rate control mode. +

+
+
rc_mode
+

Set the rate control mode to use. A given driver may only support a subset of +modes. +

+

Possible modes: +

+
auto
+

Choose the mode automatically based on driver support and the other options. +This is the default. +

+
CQP
+

Constant-quality. +

+
CBR
+

Constant-bitrate. +

+
VBR
+

Variable-bitrate. +

+
ICQ
+

Intelligent constant-quality. +

+
QVBR
+

Quality-defined variable-bitrate. +

+
AVBR
+

Average variable bitrate. +

+
+ +
+
blbrc
+

Enable block level rate control, which assigns different bitrate block by block. +Invalid for CQP mode. +

+
+
+ +

Each encoder also has its own specific options: +

+
av1_vaapi
+

profile sets the value of seq_profile. +tier sets the value of seq_tier. +level sets the value of seq_level_idx. +

+
+
tiles
+

Set the number of tiles to encode the input video with, as columns x rows. +(default is auto, which means use minimal tile column/row number). +

+
tile_groups
+

Set tile groups number. All the tiles will be distributed as evenly as possible to +each tile group. (default is 1). +

+
+ +
+
h264_vaapi
+

profile sets the value of profile_idc and the constraint_set*_flags. +level sets the value of level_idc. +

+
+
coder
+

Set entropy encoder (default is cabac). Possible values: +

+
+
‘ac’
+
‘cabac’
+

Use CABAC. +

+
+
‘vlc’
+
‘cavlc’
+

Use CAVLC. +

+
+ +
+
aud
+

Include access unit delimiters in the stream (not included by default). +

+
+
sei
+

Set SEI message types to include. +Some combination of the following values: +

+
‘identifier’
+

Include a user_data_unregistered message containing information about +the encoder. +

+
‘timing’
+

Include picture timing parameters (buffering_period and +pic_timing messages). +

+
‘recovery_point’
+

Include recovery points where appropriate (recovery_point messages). +

+
+ +
+
+ +
+
hevc_vaapi
+

profile and level set the values of +general_profile_idc and general_level_idc respectively. +

+
+
aud
+

Include access unit delimiters in the stream (not included by default). +

+
+
tier
+

Set general_tier_flag. This may affect the level chosen for the stream +if it is not explicitly specified. +

+
+
sei
+

Set SEI message types to include. +Some combination of the following values: +

+
‘hdr’
+

Include HDR metadata if the input frames have it +(mastering_display_colour_volume and content_light_level +messages). +

+
+ +
+
tiles
+

Set the number of tiles to encode the input video with, as columns x rows. +Larger numbers allow greater parallelism in both encoding and decoding, but +may decrease coding efficiency. +

+
+
+ +
+
mjpeg_vaapi
+

Only baseline DCT encoding is supported. The encoder always uses the standard +quantisation and huffman tables - global_quality scales the standard +quantisation table (range 1-100). +

+

For YUV, 4:2:0, 4:2:2 and 4:4:4 subsampling modes are supported. RGB is also +supported, and will create an RGB JPEG. +

+
+
jfif
+

Include JFIF header in each frame (not included by default). +

+
huffman
+

Include standard huffman tables (on by default). Turning this off will save +a few hundred bytes in each output frame, but may lose compatibility with some +JPEG decoders which don’t fully handle MJPEG. +

+
+ +
+
mpeg2_vaapi
+

profile and level set the value of profile_and_level_indication. +

+
+
vp8_vaapi
+

B-frames are not supported. +

+

global_quality sets the q_idx used for non-key frames (range 0-127). +

+
+
loop_filter_level
+
loop_filter_sharpness
+

Manually set the loop filter parameters. +

+
+ +
+
vp9_vaapi
+

global_quality sets the q_idx used for P-frames (range 0-255). +

+
+
loop_filter_level
+
loop_filter_sharpness
+

Manually set the loop filter parameters. +

+
+ +

B-frames are supported, but the output stream is always in encode order rather than display +order. If B-frames are enabled, it may be necessary to use the vp9_raw_reorder +bitstream filter to modify the output stream to display frames in the correct order. +

+

Only normal frames are produced - the vp9_superframe bitstream filter may be +required to produce a stream usable with all decoders. +

+
+
+ + +

16.33 vbn

+ +

Vizrt Binary Image encoder. +

+

This format is used by the broadcast vendor Vizrt for quick texture streaming. +Advanced features of the format such as LZW compression of texture data or +generation of mipmaps are not supported. +

+ +

16.33.1 Options

+ +
+
format string
+

Sets the texture compression used by the VBN file. Can be dxt1, +dxt5 or raw. Default is dxt5. +

+
+ + +

16.34 vc2

+ +

SMPTE VC-2 (previously BBC Dirac Pro). This codec was primarily aimed at +professional broadcasting but since it supports yuv420, yuv422 and yuv444 at +8 (limited range or full range), 10 or 12 bits, this makes it suitable for +other tasks which require low overhead and low compression (like screen +recording). +

+ +

16.34.1 Options

+ +
+
b
+

Sets target video bitrate. Usually that’s around 1:6 of the uncompressed +video bitrate (e.g. for 1920x1080 50fps yuv422p10 that’s around 400Mbps). Higher +values (close to the uncompressed bitrate) turn on lossless compression mode. +

+
+
field_order
+

Enables field coding when set (e.g. to tt - top field first) for interlaced +inputs. Should increase compression with interlaced content as it splits the +fields and encodes each separately. +

+
+
wavelet_depth
+

Sets the total amount of wavelet transforms to apply, between 1 and 5 (default). +Lower values reduce compression and quality. Less capable decoders may not be +able to handle values of wavelet_depth over 3. +

+
+
wavelet_type
+

Sets the transform type. Currently only 5_3 (LeGall) and 9_7 +(Deslauriers-Dubuc) +are implemented, with 9_7 being the one with better compression and thus +is the default. +

+
+
slice_width
+
slice_height
+

Sets the slice size for each slice. Larger values result in better compression. +For compatibility with other more limited decoders use slice_width of +32 and slice_height of 8. +

+
+
tolerance
+

Sets the undershoot tolerance of the rate control system in percent. This is +to prevent an expensive search from being run. +

+
+
qm
+

Sets the quantization matrix preset to use by default or when wavelet_depth +is set to 5 +

    +
  • default +Uses the default quantization matrix from the specifications, extended with +values for the fifth level. This provides a good balance between keeping detail +and omitting artifacts. + +
  • flat +Use a completely zeroed out quantization matrix. This increases PSNR but might +reduce perception. Use in bogus benchmarks. + +
  • color +Reduces detail but attempts to preserve color at extremely low bitrates. +
+ +
+
+ + + +

17 Subtitles Encoders

+ + +

17.1 dvbsub

+ +

This codec encodes the bitmap subtitle format that is used in DVB +broadcasts and recordings. The bitmaps are typically embedded in a +container such as MPEG-TS as a separate stream. +

+ +

17.1.1 Options

+ +
+
min_bpp integer (2, 4, or 8)
+

Set a minimum bits-per-pixel value for the subtitle color lookup tables. +

+

DVB supports 2, 4, and 8 bits-per-pixel color lookup tables. This +option enables forcing a particular bits-per-pixel value regardless of +the number of colors. Since not all players support or properly +support 2 bits-per-pixel, this value defaults to 4. +

+
+
+ + +

17.2 dvdsub

+ +

This codec encodes the bitmap subtitle format that is used in DVDs. +Typically they are stored in VOBSUB file pairs (*.idx + *.sub), +and they can also be used in Matroska files. +

+ +

17.2.1 Options

+ +
+
palette
+

Specify the global palette used by the bitmaps. +

+

The format for this option is a string containing 16 24-bits hexadecimal +numbers (without 0x prefix) separated by commas, for example 0d00ee, +ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, +7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b. +

+
+
even_rows_fix
+

When set to 1, enable a work-around that makes the number of pixel rows +even in all subtitles. This fixes a problem with some players that +cut off the bottom row if the number is odd. The work-around just adds +a fully transparent row if needed. The overhead is low, typically +one byte per subtitle on average. +

+

By default, this work-around is disabled. +

+
+ + +

17.3 lrc

+ +

This codec encodes the LRC lyrics format. +

+ +

17.3.1 Options

+ +
+
precision
+

Specify the precision of the fractional part of the timestamp. Time base is +determined based on this value. +

+

Defaults to 2 for centiseconds. +

+
+ + +

18 Bitstream Filters

+ +

When you configure your FFmpeg build, all the supported bitstream +filters are enabled by default. You can list all available ones using +the configure option --list-bsfs. +

+

You can disable all the bitstream filters using the configure option +--disable-bsfs, and selectively enable any bitstream filter using +the option --enable-bsf=BSF, or you can disable a particular +bitstream filter using the option --disable-bsf=BSF. +

+

The option -bsfs of the ff* tools will display the list of +all the supported bitstream filters included in your build. +

+

The ff* tools have a -bsf option applied per stream, taking a +comma-separated list of filters, whose parameters follow the filter +name after a ’=’. +

+
+
ffmpeg -i INPUT -c:v copy -bsf:v filter1[=opt1=str1:opt2=str2][,filter2] OUTPUT
+
+ +

Below is a description of the currently available bitstream filters, +with their parameters, if any. +

+ +

18.1 aac_adtstoasc

+ +

Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration +bitstream. +

+

This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4 +ADTS header and removes the ADTS header. +

+

This filter is required for example when copying an AAC stream from a +raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or +to MOV/MP4 files and related formats such as 3GP or M4A. Please note +that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats. +

+ +

18.2 av1_metadata

+ +

Modify metadata embedded in an AV1 stream. +

+
+
td
+

Insert or remove temporal delimiter OBUs in all temporal units of the +stream. +

+
+
‘insert’
+

Insert a TD at the beginning of every TU which does not already have one. +

+
‘remove’
+

Remove the TD from the beginning of every TU which has one. +

+
+ +
+
color_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the color description fields in the stream (see AV1 section 6.4.2). +

+
+
color_range
+

Set the color range in the stream (see AV1 section 6.4.2; note that +this cannot be set for streams using BT.709 primaries, sRGB transfer +characteristic and identity (RGB) matrix coefficients). +

+
‘tv’
+

Limited range. +

+
‘pc’
+

Full range. +

+
+ +
+
chroma_sample_position
+

Set the chroma sample location in the stream (see AV1 section 6.4.2). +This can only be set for 4:2:0 streams. +

+
+
‘vertical’
+

Left position (matching the default in MPEG-2 and H.264). +

+
‘colocated’
+

Top-left position. +

+
+ +
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_display_tick) in +the timing info in the sequence header. +

+
num_ticks_per_picture
+

Set the number of ticks in each picture, to indicate that the stream +has a fixed framerate. Ignored if tick_rate is not also set. +

+
+
delete_padding
+

Deletes Padding OBUs. +

+
+
+ + +

18.3 chomp

+ +

Remove zero padding at the end of a packet. +

+ +

18.4 dca_core

+ +

Extract the core from a DCA/DTS stream, dropping extensions such as +DTS-HD. +

+ +

18.5 dovi_rpu

+ +

Manipulate Dolby Vision metadata in a HEVC/AV1 bitstream, optionally enabling +metadata compression. +

+
+
strip
+

If enabled, strip all Dolby Vision metadata (configuration record + RPU data +blocks) from the stream. +

+
compression
+

Which compression level to enable. +

+
‘none’
+

No metadata compression. +

+
‘limited’
+

Limited metadata compression scheme. Should be compatible with most devices. +This is the default. +

+
‘extended’
+

Extended metadata compression. Devices are not required to support this. Note +that this level currently behaves the same as ‘limited’ in libavcodec. +

+
+
+
+ + +

18.6 dump_extra

+ +

Add extradata to the beginning of the filtered packets except when +said packets already exactly begin with the extradata that is intended +to be added. +

+
+
freq
+

The additional argument specifies which packets should be filtered. +It accepts the values: +

+
‘k’
+
‘keyframe’
+

add extradata to all key packets +

+
+
‘e’
+
‘all’
+

add extradata to all packets +

+
+
+
+ +

If not specified it is assumed ‘k’. +

+

For example the following ffmpeg command forces a global +header (thus disabling individual packet headers) in the H.264 packets +generated by the libx264 encoder, but corrects them by adding +the header stored in extradata to the key packets: +

+
ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts
+
+ + +

18.7 dv_error_marker

+ +

Blocks in DV which are marked as damaged are replaced by blocks of the specified color. +

+
+
color
+

The color to replace damaged blocks by +

+
sta
+

A 16 bit mask which specifies which of the 16 possible error status values are +to be replaced by colored blocks. 0xFFFE is the default which replaces all non 0 +error status values. +

+
‘ok’
+

No error, no concealment +

+
‘err’
+

Error, No concealment +

+
‘res’
+

Reserved +

+
‘notok’
+

Error or concealment +

+
‘notres’
+

Not reserved +

+
‘Aa, Ba, Ca, Ab, Bb, Cb, A, B, C, a, b, erri, erru’
+

The specific error status code +

+
+

see page 44-46 or section 5.5 of +http://web.archive.org/web/20060927044735/http://www.smpte.org/smpte_store/standards/pdf/s314m.pdf +

+
+
+ + +

18.8 eac3_core

+ +

Extract the core from a E-AC-3 stream, dropping extra channels. +

+ +

18.9 eia608_to_smpte436m

+ +

Convert from a EIA_608 stream to a SMPTE_436M_ANC data stream, wrapping the closed captions in CTA-708 CDP VANC packets. +

+
+
line_number
+

Choose which line number the generated VANC packets should go on. You generally want either line 9 (the default) or 11. +

+
wrapping_type
+

Choose the SMPTE 436M wrapping type, defaults to ‘vanc_frame’. +It accepts the values: +

+
‘vanc_frame’
+

VANC frame (interlaced or segmented progressive frame) +

+
‘vanc_field_1’
+
‘vanc_field_2’
+
‘vanc_progressive_frame’
+
+
+
sample_coding
+

Choose the SMPTE 436M sample coding, defaults to ‘8bit_luma’. +It accepts the values: +

+
‘8bit_luma’
+

8-bit component luma samples +

+
‘8bit_color_diff’
+

8-bit component color difference samples +

+
‘8bit_luma_and_color_diff’
+

8-bit component luma and color difference samples +

+
‘10bit_luma’
+

10-bit component luma samples +

+
‘10bit_color_diff’
+

10-bit component color difference samples +

+
‘10bit_luma_and_color_diff’
+

10-bit component luma and color difference samples +

+
‘8bit_luma_parity_error’
+

8-bit component luma samples with parity error +

+
‘8bit_color_diff_parity_error’
+

8-bit component color difference samples with parity error +

+
‘8bit_luma_and_color_diff_parity_error’
+

8-bit component luma and color difference samples with parity error +

+
+
+
initial_cdp_sequence_cntr
+

The initial value of the CDP’s 16-bit unsigned integer cdp_hdr_sequence_cntr and cdp_ftr_sequence_cntr fields. Defaults to 0. +

+
cdp_frame_rate
+

Set the CDP’s cdp_frame_rate field. This doesn’t actually change the timing of the data stream, it just changes the values inserted in that field in the generated CDP packets. Defaults to ‘30000/1001’. +

+
+ + +

18.10 extract_extradata

+ +

Extract the in-band extradata. +

+

Certain codecs allow the long-term headers (e.g. MPEG-2 sequence headers, +or H.264/HEVC (VPS/)SPS/PPS) to be transmitted either "in-band" (i.e. as a part +of the bitstream containing the coded frames) or "out of band" (e.g. on the +container level). This latter form is called "extradata" in FFmpeg terminology. +

+

This bitstream filter detects the in-band headers and makes them available as +extradata. +

+
+
remove
+

When this option is enabled, the long-term headers are removed from the +bitstream after extraction. +

+
+ + +

18.11 filter_units

+ +

Remove units with types in or not in a given set from the stream. +

+
+
pass_types
+

List of unit types or ranges of unit types to pass through while removing +all others. This is specified as a ’|’-separated list of unit type values +or ranges of values with ’-’. +

+
+
remove_types
+

Identical to pass_types, except the units in the given set +removed and all others passed through. +

+
+ +

The types used by pass_types and remove_types correspond to NAL unit types +(nal_unit_type) in H.264, HEVC and H.266 (see Table 7-1 in the H.264 +and HEVC specifications or Table 5 in the H.266 specification), to +marker values for JPEG (without 0xFF prefix) and to start codes without +start code prefix (i.e. the byte following the 0x000001) for MPEG-2. +For VP8 and VP9, every unit has type zero. +

+

Extradata is unchanged by this transformation, but note that if the stream +contains inline parameter sets then the output may be unusable if they are +removed. +

+

For example, to remove all non-VCL NAL units from an H.264 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=pass_types=1-5' OUTPUT
+
+ +

To remove all AUDs, SEI and filler from an H.265 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=35|38-40' OUTPUT
+
+ +

To remove all user data from a MPEG-2 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=178' OUTPUT
+
+ +

To remove all SEI from a H264 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=6' OUTPUT
+
+ +

To remove all prefix and suffix SEI from a HEVC stream, including Closed Captions and dynamic HDR: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=39|40' OUTPUT
+
+ + +

18.12 hapqa_extract

+ +

Extract Rgb or Alpha part of an HAPQA file, without recompression, in order to create an HAPQ or an HAPAlphaOnly file. +

+
+
texture
+

Specifies the texture to keep. +

+
+
color
+
alpha
+
+ +
+
+ +

Convert HAPQA to HAPQ +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=color -tag:v HapY -metadata:s:v:0 encoder="HAPQ" hapq_file.mov
+
+ +

Convert HAPQA to HAPAlphaOnly +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=alpha -tag:v HapA -metadata:s:v:0 encoder="HAPAlpha Only" hapalphaonly_file.mov
+
+ + +

18.13 h264_metadata

+ +

Modify metadata embedded in an H.264 stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
+ +

Default is pass. +

+
+
sample_aspect_ratio
+

Set the sample aspect ratio of the stream in the VUI parameters. +See H.264 table E-1. +

+
+
overscan_appropriate_flag
+

Set whether the stream is suitable for display using overscan +or not (see H.264 section E.2.1). +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.264 section E.2.1 and +table E-2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.264 section E.2.1 +and tables E-3, E-4 and E-5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.264 section +E.2.1 and figure E-1). +

+
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_tick) in the VUI +parameters. This is the smallest time unit representable in the +stream, and in many cases represents the field rate of the stream +(double the frame rate). +

+
fixed_frame_rate_flag
+

Set whether the stream has fixed framerate - typically this indicates +that the framerate is exactly half the tick rate, but the exact +meaning is dependent on interlacing and the picture structure (see +H.264 section E.2.1 and table E-6). +

+
zero_new_constraint_set_flags
+

Zero constraint_set4_flag and constraint_set5_flag in the SPS. These +bits were reserved in a previous version of the H.264 spec, and thus +some hardware decoders require these to be zero. The result of zeroing +this is still a valid bitstream. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the frame cropping offsets in the SPS. These values will replace +the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled or the stream is interlaced +(see H.264 section 7.4.2.1.1). +

+
+
sei_user_data
+

Insert a string as SEI unregistered user data. The argument must +be of the form UUID+string, where the UUID is as hex digits +possibly separated by hyphens, and the string can be anything. +

+

For example, ‘086f3693-b7b3-4f2c-9653-21492feee5b8+hello’ will +insert the string “hello” associated with the given UUID. +

+
+
delete_filler
+

Deletes both filler NAL units and filler SEI messages. +

+
+
display_orientation
+

Insert, extract or remove Display orientation SEI messages. +See H.264 section D.1.27 and D.2.27 for syntax and semantics. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
‘extract’
+
+ +

Default is pass. +

+

Insert mode works in conjunction with rotate and flip options. +Any pre-existing Display orientation messages will be removed in insert or remove mode. +Extract mode attaches the display matrix to the packet as side data. +

+
+
rotate
+

Set rotation in display orientation SEI (anticlockwise angle in degrees). +Range is -360 to +360. Default is NaN. +

+
+
flip
+

Set flip in display orientation SEI. +

+
+
‘horizontal’
+
‘vertical’
+
+ +

Default is unset. +

+
+
level
+

Set the level in the SPS. Refer to H.264 section A.3 and tables A-1 +to A-5. +

+

The argument must be the name of a level (for example, ‘4.2’), a +level_idc value (for example, ‘42’), or the special name ‘auto’ +indicating that the filter should attempt to guess the level from the +input stream properties. +

+
+
+ + +

18.14 h264_mp4toannexb

+ +

Convert an H.264 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.264 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an H.264 stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw H.264 (muxer h264) output formats. +

+ +

18.15 h264_redundant_pps

+ +

This applies a specific fixup to some Blu-ray BDMV H264 streams +which contain redundant PPSs. The PPSs modify irrelevant parameters +of the stream, confusing other transformations which require +the correct extradata. +

+

The encoder used on these impacted streams adds extra PPSs throughout +the stream, varying the initial QP and whether weighted prediction +was enabled. This causes issues after copying the stream into +a global header container, as the starting PPS is not suitable +for the rest of the stream. One side effect, for example, +is seeking will return garbled output until a new PPS appears. +

+

This BSF removes the extra PPSs and rewrites the slice headers +such that the stream uses a single leading PPS in the global header, +which resolves the issue. +

+ +

18.16 hevc_metadata

+ +

Modify metadata embedded in an HEVC stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘insert’
+
‘remove’
+
+ +
+
sample_aspect_ratio
+

Set the sample aspect ratio in the stream in the VUI parameters. +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.265 section E.3.1 and +table E.2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.265 section E.3.1 +and tables E.3, E.4 and E.5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.265 section +E.3.1 and figure E.1). +

+
+
tick_rate
+

Set the tick rate in the VPS and VUI parameters (time_scale / +num_units_in_tick). Combined with num_ticks_poc_diff_one, this can +set a constant framerate in the stream. Note that it is likely to be +overridden by container parameters when the stream is in a container. +

+
+
num_ticks_poc_diff_one
+

Set poc_proportional_to_timing_flag in VPS and VUI and use this value +to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and +E.3.1). Ignored if tick_rate is not also set. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the conformance window cropping offsets in the SPS. These values +will replace the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled (H.265 section 7.4.3.2.1). +

+
+
width
+
height
+

Set width and height after crop. +

+
+
level
+

Set the level in the VPS and SPS. See H.265 section A.4 and tables +A.6 and A.7. +

+

The argument must be the name of a level (for example, ‘5.1’), a +general_level_idc value (for example, ‘153’ for level 5.1), +or the special name ‘auto’ indicating that the filter should +attempt to guess the level from the input stream properties. +

+
+
+ + +

18.17 hevc_mp4toannexb

+ +

Convert an HEVC/H.265 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.265 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an HEVC stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw HEVC/H.265 (muxer h265 or +hevc) output formats. +

+ +

18.18 imxdump

+ +

Modifies the bitstream to fit in MOV and to be usable by the Final Cut +Pro decoder. This filter only applies to the mpeg2video codec, and is +likely not needed for Final Cut Pro 7 and newer with the appropriate +-tag:v. +

+

For example, to remux 30 MB/sec NTSC IMX to MOV: +

+
+
ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov
+
+ + +

18.19 mjpeg2jpeg

+ +

Convert MJPEG/AVI1 packets to full JPEG/JFIF packets. +

+

MJPEG is a video codec wherein each video frame is essentially a +JPEG image. The individual frames can be extracted without loss, +e.g. by +

+
+
ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg
+
+ +

Unfortunately, these chunks are incomplete JPEG images, because +they lack the DHT segment required for decoding. Quoting from +http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml: +

+

Avery Lee, writing in the rec.video.desktop newsgroup in 2001, +commented that "MJPEG, or at least the MJPEG in AVIs having the +MJPG fourcc, is restricted JPEG with a fixed – and *omitted* – +Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2, +and it must use basic Huffman encoding, not arithmetic or +progressive. . . . You can indeed extract the MJPEG frames and +decode them with a regular JPEG decoder, but you have to prepend +the DHT segment to them, or else the decoder won’t have any idea +how to decompress the data. The exact table necessary is given in +the OpenDML spec." +

+

This bitstream filter patches the header of frames extracted from an MJPEG +stream (carrying the AVI1 header ID and lacking a DHT segment) to +produce fully qualified JPEG images. +

+
+
ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg
+exiftran -i -9 frame*.jpg
+ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
+
+ + +

18.20 mjpegadump

+ +

Add an MJPEG A header to the bitstream, to enable decoding by +Quicktime. +

+ +

18.21 mov2textsub

+ +

Extract a representable text file from MOV subtitles, stripping the +metadata header from each subtitle packet. +

+

See also the text2movsub filter. +

+ +

18.22 mpeg2_metadata

+ +

Modify metadata embedded in an MPEG-2 stream. +

+
+
display_aspect_ratio
+

Set the display aspect ratio in the stream. +

+

The following fixed values are supported: +

+
4/3
+
16/9
+
221/100
+
+

Any other value will result in square pixels being signalled instead +(see H.262 section 6.3.3 and table 6-3). +

+
+
frame_rate
+

Set the frame rate in the stream. This is constructed from a table +of known values combined with a small multiplier and divisor - if +the supplied value is not exactly representable, the nearest +representable value will be used instead (see H.262 section 6.3.3 +and table 6-4). +

+
+
video_format
+

Set the video format in the stream (see H.262 section 6.3.6 and +table 6-6). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.262 section 6.3.6 +and tables 6-7, 6-8 and 6-9). +

+
+
+ + +

18.23 mpeg4_unpack_bframes

+ +

Unpack DivX-style packed B-frames. +

+

DivX-style packed B-frames are not valid MPEG-4 and were only a +workaround for the broken Video for Windows subsystem. +They use more space, can cause minor AV sync issues, require more +CPU power to decode (unless the player has some decoded picture queue +to compensate the 2,0,2,0 frame per packet style) and cause +trouble if copied into a standard container like mp4 or mpeg-ps/ts, +because MPEG-4 decoders may not be able to decode them, since they are +not valid MPEG-4. +

+

For example to fix an AVI file containing an MPEG-4 stream with +DivX-style packed B-frames using ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi
+
+ + +

18.24 noise

+ +

Damages the contents of packets or simply drops them without damaging the +container. Can be used for fuzzing or testing error resilience/concealment. +

+

Parameters: +

+
amount
+

Accepts an expression whose evaluation per-packet determines how often bytes in that +packet will be modified. A value below 0 will result in a variable frequency. +Default is 0 which results in no modification. However, if neither amount nor drop is specified, +amount will be set to -1. See below for accepted variables. +

+
drop
+

Accepts an expression evaluated per-packet whose value determines whether that packet is dropped. +Evaluation to a positive value results in the packet being dropped. Evaluation to a negative +value results in a variable chance of it being dropped, roughly inverse in proportion to the magnitude +of the value. Default is 0 which results in no drops. See below for accepted variables. +

+
dropamount
+

Accepts a non-negative integer, which assigns a variable chance of it being dropped, roughly inverse +in proportion to the value. Default is 0 which results in no drops. This option is kept for backwards +compatibility and is equivalent to setting drop to a negative value with the same magnitude +i.e. dropamount=4 is the same as drop=-4. Ignored if drop is also specified. +

+
+ +

Both amount and drop accept expressions containing the following variables: +

+
+
‘n’
+

The index of the packet, starting from zero. +

+
‘tb’
+

The timebase for packet timestamps. +

+
‘pts’
+

Packet presentation timestamp. +

+
‘dts’
+

Packet decoding timestamp. +

+
‘nopts’
+

Constant representing AV_NOPTS_VALUE. +

+
‘startpts’
+

First non-AV_NOPTS_VALUE PTS seen in the stream. +

+
‘startdts’
+

First non-AV_NOPTS_VALUE DTS seen in the stream. +

+
‘duration’
+
‘d’
+

Packet duration, in timebase units. +

+
‘pos’
+

Packet position in input; may be -1 when unknown or not set. +

+
‘size’
+

Packet size, in bytes. +

+
‘key’
+

Whether packet is marked as a keyframe. +

+
‘state’
+

A pseudo random integer, primarily derived from the content of packet payload. +

+
+ + +

18.24.1 Examples

+

Apply modification to every byte but don’t drop any packets. +

+
ffmpeg -i INPUT -c copy -bsf noise=1 output.mkv
+
+ +

Drop every video packet not marked as a keyframe after timestamp 30s but do not +modify any of the remaining packets. +

+
ffmpeg -i INPUT -c copy -bsf:v noise=drop='gt(pts*tb\,30)*not(key)' output.mkv
+
+ +

Drop one second of audio every 10 seconds and add some random noise to the rest. +

+
ffmpeg -i INPUT -c copy -bsf:a noise=amount=-1:drop='between(mod(pts*tb\,10)\,9\,10)' output.mkv
+
+ + +

18.25 null

+

This bitstream filter passes the packets through unchanged. +

+ +

18.26 pcm_rechunk

+ +

Repacketize PCM audio to a fixed number of samples per packet or a fixed packet +rate per second. This is similar to the asetnsamples audio +filter but works on audio packets instead of audio frames. +

+
+
nb_out_samples, n
+

Set the number of samples per each output audio packet. The number is intended +as the number of samples per each channel. Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio packet with silence, so that it +will contain the same number of samples (or roughly the same number of samples, +see frame_rate) as the previous ones. Default value is 1. +

+
+
frame_rate, r
+

This option makes the filter output a fixed number of packets per second instead +of a fixed number of samples per packet. If the audio sample rate is not +divisible by the frame rate then the number of samples will not be constant but +will vary slightly so that each packet will start as close to the frame +boundary as possible. Using this option has precedence over nb_out_samples. +

+
+ +

You can generate the well known 1602-1601-1602-1601-1602 pattern of 48kHz audio +for NTSC frame rate using the frame_rate option. +

+
ffmpeg -f lavfi -i sine=r=48000:d=1 -c pcm_s16le -bsf pcm_rechunk=r=30000/1001 -f framecrc -
+
+ + +

18.27 pgs_frame_merge

+ +

Merge a sequence of PGS Subtitle segments ending with an "end of display set" +segment into a single packet. +

+

This is required by some containers that support PGS subtitles +(muxer matroska). +

+ +

18.28 prores_metadata

+ +

Modify color property metadata embedded in prores stream. +

+
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘bt470bg’
+

BT601 625 +

+
+
‘smpte170m’
+

BT601 525 +

+
+
‘bt2020’
+
‘smpte431’
+

DCI P3 +

+
+
‘smpte432’
+

P3 D65 +

+
+
+ +
+
transfer_characteristics
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same transfer characteristics property (default). +

+
+
‘unknown’
+
‘bt709’
+

BT 601, BT 709, BT 2020 +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ + +
+
matrix_coefficients
+

Set the matrix coefficient. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘smpte170m’
+

BT 601 +

+
+
‘bt2020nc’
+
+
+
+ +

Set Rec709 colorspace for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt709:color_trc=bt709:colorspace=bt709 output.mov
+
+ +

Set Hybrid Log-Gamma parameters for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt2020:color_trc=arib-std-b67:colorspace=bt2020nc output.mov
+
+ + +

18.29 remove_extra

+ +

Remove extradata from packets. +

+

It accepts the following parameter: +

+
freq
+

Set which frame types to remove extradata from. +

+
+
‘k’
+

Remove extradata from non-keyframes only. +

+
+
‘keyframe’
+

Remove extradata from keyframes only. +

+
+
‘e, all’
+

Remove extradata from all frames. +

+
+
+
+
+ + +

18.30 setts

+

Set PTS and DTS in packets. +

+

It accepts the following parameters: +

+
ts
+
pts
+
dts
+

Set expressions for PTS, DTS or both. +

+
duration
+

Set expression for duration. +

+
time_base
+

Set output time base. +

+
prescale
+

Set whether to convert time fields to user-set output time base before evaluation of expressions. Defaults to 0. +

+
+ +

The expressions are evaluated through the eval API and can contain the following +constants: +

+
+
N
+

The count of the input packet. Starting from 0. +

+
+
TS
+

The demux timestamp in input in case of ts or dts option or presentation +timestamp in case of pts option. +

+
+
POS
+

The original position in the file of the packet, or undefined if undefined +for the current packet +

+
+
DTS
+

The demux timestamp in input. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
DURATION
+

The duration in input. +

+
+
STARTDTS
+

The DTS of the first packet. +

+
+
STARTPTS
+

The PTS of the first packet. +

+
+
PREV_INDTS
+

The previous input DTS. +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INDURATION
+

The previous input duration. +

+
+
PREV_OUTDTS
+

The previous output DTS. +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTDURATION
+

The previous output duration. +

+
+
NEXT_DTS
+

The next input DTS. +

+
+
NEXT_PTS
+

The next input PTS. +

+
+
NEXT_DURATION
+

The next input duration. +

+
+
TB
+

The timebase in which time fields are denominated. The user-set output timebase if prescale is enabled, else the input timebase. +

+
+
TB_OUT
+

The output timebase. +

+
+
SR
+

The sample rate of stream packet belongs. +

+
+
NOPTS
+

The AV_NOPTS_VALUE constant. +

+
+ +

For example, to set PTS equal to DTS (not recommended if B-frames are involved): +

+
ffmpeg -i INPUT -c:a copy -bsf:a setts=pts=DTS out.mkv
+
+ + +

18.31 showinfo

+

Log basic packet information. Mainly useful for testing, debugging, +and development. +

+ +

18.32 smpte436m_to_eia608

+ +

Convert from a SMPTE_436M_ANC data stream to a EIA_608 stream, +extracting the closed captions from CTA-708 CDP VANC packets, and ignoring all other data. +

+ +

18.33 text2movsub

+ +

Convert text subtitles to MOV subtitles (as used by the mov_text +codec) with metadata headers. +

+

See also the mov2textsub filter. +

+ +

18.34 trace_headers

+ +

Log trace output containing all syntax elements in the coded stream +headers (everything above the level of individual coded blocks). +This can be useful for debugging low-level stream issues. +

+

Supports AV1, H.264, H.265, (M)JPEG, MPEG-2 and VP9, but depending +on the build only a subset of these may be available. +

+ +

18.35 truehd_core

+ +

Extract the core from a TrueHD stream, dropping ATMOS data. +

+ +

18.36 vp9_metadata

+ +

Modify metadata embedded in a VP9 stream. +

+
+
color_space
+

Set the color space value in the frame header. Note that any frame +set to RGB will be implicitly set to PC range and that RGB is +incompatible with profiles 0 and 2. +

+
‘unknown’
+
‘bt601’
+
‘bt709’
+
‘smpte170’
+
‘smpte240’
+
‘bt2020’
+
‘rgb’
+
+ +
+
color_range
+

Set the color range value in the frame header. Note that any value +imposed by the color space will take precedence over this value. +

+
‘tv’
+
‘pc’
+
+
+
+ + +

18.37 vp9_superframe

+ +

Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This +fixes merging of split/segmented VP9 streams where the alt-ref frame +was split from its visible counterpart. +

+ +

18.38 vp9_superframe_split

+ +

Split VP9 superframes into single frames. +

+ +

18.39 vp9_raw_reorder

+ +

Given a VP9 stream with correct timestamps but possibly out of order, +insert additional show-existing-frame packets to correct the ordering. +

+ +

19 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
avioflags flags (input/output)
+

Possible values: +

+
‘direct’
+

Reduce buffering. +

+
+ +
+
probesize integer (input)
+

Set probing size in bytes, i.e. the size of the data to analyze to get +stream information. A higher value will enable detecting 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. +

+
+
max_probe_packets integer (input)
+

Set the maximum number of buffered packets when probing a codec. +Default is 2500 packets. +

+
+
packetsize integer (output)
+

Set packet size. +

+
+
fflags flags
+

Set format flags. Some are implemented for a limited number of formats. +

+

Possible values for input files: +

+
‘discardcorrupt’
+

Discard corrupted packets. +

+
‘fastseek’
+

Enable fast, but inaccurate seeks for some formats. +

+
‘genpts’
+

Generate missing PTS if DTS is present. +

+
‘igndts’
+

Ignore DTS if PTS is also set. In case the PTS is set, the DTS value +is set to NOPTS. This is ignored when the nofillin flag is set. +

+
‘ignidx’
+

Ignore index. +

+
‘nobuffer’
+

Reduce the latency introduced by buffering during initial input streams analysis. +

+
‘nofillin’
+

Do not fill in missing values in packet fields that can be exactly calculated. +

+
‘noparse’
+

Disable AVParsers, this needs +nofillin too. +

+
‘sortdts’
+

Try to interleave output packets by DTS. At present, available only for AVIs with an index. +

+
+ +

Possible values for output files: +

+
‘autobsf’
+

Automatically apply bitstream filters as required by the output format. Enabled by default. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘flush_packets’
+

Write out packets immediately. +

+
‘shortest’
+

Stop muxing at the end of the shortest stream. +It may be needed to increase max_interleave_delta to avoid flushing the longer +streams before EOF. +

+
+ +
+
seek2any integer (input)
+

Allow seeking to non-keyframes on demuxer level when supported if set to 1. +Default is 0. +

+
+
analyzeduration integer (input)
+

Specify how many microseconds are analyzed to probe the input. A +higher value will enable detecting more accurate information, but will +increase latency. It defaults to 5,000,000 microseconds = 5 seconds. +

+
+
cryptokey hexadecimal string (input)
+

Set decryption key. +

+
+
indexmem integer (input)
+

Set max memory used for timestamp index (per stream). +

+
+
rtbufsize integer (input)
+

Set max memory used for buffering real-time frames. +

+
+
fdebug flags (input/output)
+

Print specific debug info. +

+

Possible values: +

+
‘ts’
+
+ +
+
max_delay integer (input/output)
+

Set maximum muxing or demuxing delay in microseconds. +

+
+
fpsprobesize integer (input)
+

Set number of frames used to probe fps. +

+
+
audio_preload integer (output)
+

Set microseconds by which audio packets should be interleaved earlier. +

+
+
chunk_duration integer (output)
+

Set microseconds for each chunk. +

+
+
chunk_size integer (output)
+

Set size in bytes for each chunk. +

+
+
err_detect, f_err_detect flags (input)
+

Set error detection flags. f_err_detect is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘crccheck’
+

Verify embedded CRCs. +

+
‘bitstream’
+

Detect bitstream specification deviations. +

+
‘buffer’
+

Detect improper bitstream length. +

+
‘explode’
+

Abort decoding on minor error detection. +

+
‘careful’
+

Consider things that violate the spec and have not been seen in the +wild as errors. +

+
‘compliant’
+

Consider all spec non compliancies as errors. +

+
‘aggressive’
+

Consider things that a sane encoder should not do as an error. +

+
+ +
+
max_interleave_delta integer (output)
+

Set maximum buffering duration for interleaving. The duration is +expressed in microseconds, and defaults to 10000000 (10 seconds). +

+

To ensure all the streams are interleaved correctly, libavformat will +wait until it has at least one packet for each stream before actually +writing any packets to the output file. When some streams are +"sparse" (i.e. there are large gaps between successive packets), this +can result in excessive buffering. +

+

This field specifies the maximum difference between the timestamps of the +first and the last packet in the muxing queue, above which libavformat +will output a packet regardless of whether it has queued a packet for all +the streams. +

+

If set to 0, libavformat will continue buffering packets until it has +a packet for each stream, regardless of the maximum timestamp +difference between the buffered packets. +

+
+
use_wallclock_as_timestamps integer (input)
+

Use wallclock as timestamps if set to 1. Default is 0. +

+
+
avoid_negative_ts integer (output)
+
+

Possible values: +

+
‘make_non_negative’
+

Shift timestamps to make them non-negative. +Also note that this affects only leading negative timestamps, and not +non-monotonic negative timestamps. +

+
‘make_zero’
+

Shift timestamps so that the first timestamp is 0. +

+
‘auto (default)’
+

Enables shifting when required by the target format. +

+
‘disabled’
+

Disables shifting of timestamp. +

+
+ +

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. +

+
+
skip_initial_bytes integer (input)
+

Set number of bytes to skip before reading header and frames if set to 1. +Default is 0. +

+
+
correct_ts_overflow integer (input)
+

Correct single timestamp overflows if set to 1. Default is 1. +

+
+
flush_packets integer (output)
+

Flush the underlying I/O stream after each packet. Default is -1 (auto), which +means that the underlying protocol will decide, 1 enables it, and has the +effect of reducing the latency, 0 disables it and may increase IO throughput in +some cases. +

+
+
output_ts_offset offset (output)
+

Set the output time offset. +

+

offset must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

The offset is added by the muxer to the output timestamps. +

+

Specifying a positive offset means that the corresponding streams are +delayed bt the time duration specified in offset. Default value +is 0 (meaning that no offset is applied). +

+
+
format_whitelist list (input)
+

"," separated list of allowed demuxers. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_streams integer (input)
+

Specifies the maximum number of streams. This can be used to reject files that +would require too many resources due to a large number of streams. +

+
+
skip_estimate_duration_from_pts bool (input)
+

Skip estimation of input duration if it requires an additional probing for PTS at end of file. +At present, applicable for MPEG-PS and MPEG-TS. +

+
+
duration_probesize integer (input)
+

Set probing size, in bytes, for input duration estimation when it actually requires +an additional probing for PTS at end of file (at present: MPEG-PS and MPEG-TS). +It is aimed at users interested in better durations probing for itself, or indirectly +because using the concat demuxer, for example. +The typical use case is an MPEG-TS CBR with a high bitrate, high video buffering and +ending cleaning with similar PTS for video and audio: in such a scenario, the large +physical gap between the last video packet and the last audio packet makes it necessary +to read many bytes in order to get the video stream duration. +Another use case is where the default probing behaviour only reaches a single video frame which is +not the last one of the stream due to frame reordering, so the duration is not accurate. +Setting this option has a performance impact even for small files because the probing +size is fixed. +Default behaviour is a general purpose trade-off, largely adaptive, but the probing size +will not be extended to get streams durations at all costs. +Must be an integer not lesser than 1, or 0 for default behaviour. +

+
+
strict, f_strict integer (input/output)
+

Specify how strictly to follow the standards. f_strict is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
+ + + +

19.1 Format stream specifiers

+ +

Format stream specifiers allow selection of one or more streams that +match specific properties. +

+

The exact semantics of stream specifiers is defined by the +avformat_match_stream_specifier() function declared in the +libavformat/avformat.h header and documented in the +Stream specifiers section in the ffmpeg(1) manual. +

+ +

20 Demuxers

+ +

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 +are enabled by default. You can list all available ones using the +configure option --list-demuxers. +

+

You can disable all the demuxers using the configure option +--disable-demuxers, and selectively enable a single demuxer with +the option --enable-demuxer=DEMUXER, or disable it +with the option --disable-demuxer=DEMUXER. +

+

The option -demuxers of the ff* tools will display the list of +enabled demuxers. Use -formats to view a combined list of +enabled demuxers and muxers. +

+

The description of some of the currently available demuxers follows. +

+ +

20.1 aa

+ +

Audible Format 2, 3, and 4 demuxer. +

+

This demuxer is used to demux Audible Format 2, 3, and 4 (.aa) files. +

+ +

20.2 aac

+ +

Raw Audio Data Transport Stream AAC demuxer. +

+

This demuxer is used to demux an ADTS input containing a single AAC stream +alongwith any ID3v1/2 or APE tags in it. +

+ +

20.3 apng

+ +

Animated Portable Network Graphics demuxer. +

+

This demuxer is used to demux APNG files. +All headers, but the PNG signature, up to (but not including) the first +fcTL chunk are transmitted as extradata. +Frames are then split as being all the chunks between two fcTL ones, or +between the last fcTL and IEND chunks. +

+
+
-ignore_loop bool
+

Ignore the loop variable in the file if set. Default is enabled. +

+
+
-max_fps int
+

Maximum framerate in frames per second. Default of 0 imposes no limit. +

+
+
-default_fps int
+

Default framerate in frames per second when none is specified in the file +(0 meaning as fast as possible). Default is 15. +

+
+
+ + +

20.4 asf

+ +

Advanced Systems Format demuxer. +

+

This demuxer is used to demux ASF files and MMS network streams. +

+
+
-no_resync_search bool
+

Do not try to resynchronize by looking for a certain optional start code. +

+
+ + +

20.5 concat

+ +

Virtual concatenation script demuxer. +

+

This demuxer reads a list of files and other directives from a text file and +demuxes them one after the other, as if all their packets had been muxed +together. +

+

The timestamps in the files are adjusted so that the first file starts at 0 +and each next file starts where the previous one finishes. Note that it is +done globally and may cause gaps if all streams do not have exactly the same +length. +

+

All files must have the same streams (same codecs, same time base, etc.). +

+

The duration of each file is used to adjust the timestamps of the next file: +if the duration is incorrect (because it was computed using the bit-rate or +because the file is truncated, for example), it can cause artifacts. The +duration directive can be used to override the duration stored in +each file. +

+ +

20.5.1 Syntax

+ +

The script is a text file in extended-ASCII, with one directive per line. +Empty lines, leading spaces and lines starting with ’#’ are ignored. The +following directive is recognized: +

+
+
file path
+

Path to a file to read; special characters and spaces must be escaped with +backslash or single quotes. +

+

All subsequent file-related directives apply to that file. +

+
+
ffconcat version 1.0
+

Identify the script type and version. +

+

To make FFmpeg recognize the format automatically, this directive must +appear exactly as is (no extra space or byte-order-mark) on the very first +line of the script. +

+
+
duration dur
+

Duration of the file. This information can be specified from the file; +specifying it here may be more efficient or help if the information from the +file is not available or accurate. +

+

If the duration is set for all files, then it is possible to seek in the +whole concatenated video. +

+
+
inpoint timestamp
+

In point of the file. When the demuxer opens the file it instantly seeks to the +specified timestamp. Seeking is done so that all streams can be presented +successfully at In point. +

+

This directive works best with intra frame codecs, because for non-intra frame +ones you will usually get extra packets before the actual In point and the +decoded content will most likely contain frames before In point too. +

+

For each file, packets before the file In point will have timestamps less than +the calculated start timestamp of the file (negative in case of the first +file), and the duration of the files (if not specified by the duration +directive) will be reduced based on their specified In point. +

+

Because of potential packets before the specified In point, packet timestamps +may overlap between two concatenated files. +

+
+
outpoint timestamp
+

Out point of the file. When the demuxer reaches the specified decoding +timestamp in any of the streams, it handles it as an end of file condition and +skips the current and all the remaining packets from all streams. +

+

Out point is exclusive, which means that the demuxer will not output packets +with a decoding timestamp greater or equal to Out point. +

+

This directive works best with intra frame codecs and formats where all streams +are tightly interleaved. For non-intra frame codecs you will usually get +additional packets with presentation timestamp after Out point therefore the +decoded content will most likely contain frames after Out point too. If your +streams are not tightly interleaved you may not get all the packets from all +streams before Out point and you may only will be able to decode the earliest +stream until Out point. +

+

The duration of the files (if not specified by the duration +directive) will be reduced based on their specified Out point. +

+
+
file_packet_metadata key=value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +This directive is deprecated, use file_packet_meta instead. +

+
+
file_packet_meta key value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +

+
+
option key value
+

Option to access, open and probe the file. +Can be present multiple times. +

+
+
stream
+

Introduce a stream in the virtual file. +All subsequent stream-related directives apply to the last introduced +stream. +Some streams properties must be set in order to allow identifying the +matching streams in the subfiles. +If no streams are defined in the script, the streams from the first file are +copied. +

+
+
exact_stream_id id
+

Set the id of the stream. +If this directive is given, the string with the corresponding id in the +subfiles will be used. +This is especially useful for MPEG-PS (VOB) files, where the order of the +streams is not reliable. +

+
+
stream_meta key value
+

Metadata for the stream. +Can be present multiple times. +

+
+
stream_codec value
+

Codec for the stream. +

+
+
stream_extradata hex_string
+

Extradata for the string, encoded in hexadecimal. +

+
+
chapter id start end
+

Add a chapter. id is an unique identifier, possibly small and +consecutive. +

+
+
+ + +

20.5.2 Options

+ +

This demuxer accepts the following option: +

+
+
safe
+

If set to 1, reject unsafe file paths and directives. +A file path is considered safe if it +does not contain a protocol specification and is relative and all components +only contain characters from the portable character set (letters, digits, +period, underscore and hyphen) and have no period at the beginning of a +component. +

+

If set to 0, any file name is accepted. +

+

The default is 1. +

+
+
auto_convert
+

If set to 1, try to perform automatic conversions on packet data to make the +streams concatenable. +The default is 1. +

+

Currently, the only conversion is adding the h264_mp4toannexb bitstream +filter to H.264 streams in MP4 format. This is necessary in particular if +there are resolution changes. +

+
+
segment_time_metadata
+

If set to 1, every packet will contain the lavf.concat.start_time and the +lavf.concat.duration packet metadata values which are the start_time and +the duration of the respective file segments in the concatenated output +expressed in microseconds. The duration metadata is only set if it is known +based on the concat file. +The default is 0. +

+
+
+ + +

20.5.3 Examples

+ +
    +
  • Use absolute filenames and include some comments: +
    +
    # my first filename
    +file /mnt/share/file-1.wav
    +# my second filename including whitespace
    +file '/mnt/share/file 2.wav'
    +# my third filename including whitespace plus single quote
    +file '/mnt/share/file 3'\''.wav'
    +
    + +
  • Allow for input format auto-probing, use safe filenames and set the duration of +the first file: +
    +
    ffconcat version 1.0
    +
    +file file-1.wav
    +duration 20.0
    +
    +file subdir/file-2.wav
    +
    +
+ + +

20.6 dash

+ +

Dynamic Adaptive Streaming over HTTP demuxer. +

+

This demuxer presents all AVStreams found in the manifest. +By setting the discard flags on AVStreams the caller can decide +which streams to actually receive. +Each stream mirrors the id and bandwidth properties from the +<Representation> as metadata keys named "id" and "variant_bitrate" respectively. +

+ +

20.6.1 Options

+ +

This demuxer accepts the following option: +

+
+
cenc_decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
cenc_decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
+ + +

20.7 dvdvideo

+ +

DVD-Video demuxer, powered by libdvdnav and libdvdread. +

+

Can directly ingest DVD titles, specifically sequential PGCs, into +a conversion pipeline. Menu assets, such as background video or audio, +can also be demuxed given the menu’s coordinates (at best effort). +

+

Block devices (DVD drives), ISO files, and directory structures are accepted. +Activate with -f dvdvideo in front of one of these inputs. +

+

This demuxer does NOT have decryption code of any kind. You are on your own +working with encrypted DVDs, and should not expect support on the matter. +

+

Underlying playback is handled by libdvdnav, and structure parsing by libdvdread. +FFmpeg must be built with GPL library support available as well as the +configure switches --enable-libdvdnav and --enable-libdvdread. +

+

You will need to provide either the desired "title number" or exact PGC/PG coordinates. +Many open-source DVD players and tools can aid in providing this information. +If not specified, the demuxer will default to title 1 which works for many discs. +However, due to the flexibility of the format, it is recommended to check manually. +There are many discs that are authored strangely or with invalid headers. +

+

If the input is a real DVD drive, please note that there are some drives which may +silently fail on reading bad sectors from the disc, returning random bits instead +which is effectively corrupt data. This is especially prominent on aging or rotting discs. +A second pass and integrity checks would be needed to detect the corruption. +This is not an FFmpeg issue. +

+ +

20.7.1 Background

+ +

DVD-Video is not a directly accessible, linear container format in the +traditional sense. Instead, it allows for complex and programmatic playback of +carefully muxed MPEG-PS streams that are stored in headerless VOB files. +To the end-user, these streams are known simply as "titles", but the actual +logical playback sequence is defined by one or more "PGCs", or Program Group Chains, +within the title. The PGC is in turn comprised of multiple "PGs", or Programs", +which are the actual video segments (and for a typical video feature, sequentially +ordered). The PGC structure, along with stream layout and metadata, are stored in +IFO files that need to be parsed. PGCs can be thought of as playlists in easier terms. +

+

An actual DVD player relies on user GUI interaction via menus and an internal VM +to drive the direction of demuxing. Generally, the user would either navigate (via menus) +or automatically be redirected to the PGC of their choice. During this process and +the subsequent playback, the DVD player’s internal VM also maintains a state and +executes instructions that can create jumps to different sectors during playback. +This is why libdvdnav is involved, as a linear read of the MPEG-PS blobs on the +disc (VOBs) is not enough to produce the right sequence in many cases. +

+

There are many other DVD structures (a long subject) that will not be discussed here. +NAV packets, in particular, are handled by this demuxer to build accurate timing +but not emitted as a stream. For a good high-level understanding, refer to: +https://code.videolan.org/videolan/libdvdnav/-/blob/master/doc/dvd_structures +

+ +

20.7.2 Options

+ +

This demuxer accepts the following options: +

+
+
title int
+

The title number to play. Must be set if pgc and pg are not set. +Not applicable to menus. +Default is 0 (auto), which currently only selects the first available title (title 1) +and notifies the user about the implications. +

+
+
chapter_start int
+

The chapter, or PTT (part-of-title), number to start at. Not applicable to menus. +Default is 1. +

+
+
chapter_end int
+

The chapter, or PTT (part-of-title), number to end at. Not applicable to menus. +Default is 0, which is a special value to signal end at the last possible chapter. +

+
+
angle int
+

The video angle number, referring to what is essentially an additional +video stream that is composed from alternate frames interleaved in the VOBs. +Not applicable to menus. +Default is 1. +

+
+
region int
+

The region code to use for playback. Some discs may use this to default playback +at a particular angle in different regions. This option will not affect the region code +of a real DVD drive, if used as an input. Not applicable to menus. +Default is 0, "world". +

+
+
menu bool
+

Demux menu assets instead of navigating a title. Requires exact coordinates +of the menu (menu_lu, menu_vts, pgc, pg). +Default is false. +

+
+
menu_lu int
+

The menu language to demux. In DVD, menus are grouped by language. +Default is 1, the first language unit. +

+
+
menu_vts int
+

The VTS where the menu lives, or 0 if it is a VMG menu (root-level). +Default is 1, menu of the first VTS. +

+
+
pgc int
+

The entry PGC to start playback, in conjunction with pg. +Alternative to setting title. +Chapter markers are not supported at this time. +Must be explicitly set for menus. +Default is 0, automatically resolve from value of title. +

+
+
pg int
+

The entry PG to start playback, in conjunction with pgc. +Alternative to setting title. +Chapter markers are not supported at this time. +Default is 1, the first PG of the PGC. +

+
+
preindex bool
+

Enable this to have accurate chapter (PTT) markers and duration measurement, +which requires a slow second pass read in order to index the chapter marker +timestamps from NAV packets. This is non-ideal extra work for real optical drives. +It is recommended and faster to use this option with a backup of the DVD structure +stored on a hard drive. Not compatible with pgc and pg. +Default is 0, false. +

+
+
trim bool
+

Skip padding cells (i.e. cells shorter than 1 second) from the beginning. +There exist many discs with filler segments at the beginning of the PGC, +often with junk data intended for controlling a real DVD player’s +buffering speed and with no other material data value. +Not applicable to menus. +Default is 1, true. +

+
+
+ + +

20.7.3 Examples

+ +
    +
  • Open title 3 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -title 3 -i <path to DVD> ...
    +
    + +
  • Open chapters 3-6 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 3 -chapter_end 6 -title 1 -i <path to DVD> ...
    +
    + +
  • Open only chapter 5 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 5 -chapter_end 5 -title 1 -i <path to DVD> ...
    +
    + +
  • Demux menu with language 1 from VTS 1, PGC 1, starting at PG 1: +
    +
    ffmpeg -f dvdvideo -menu 1 -menu_lu 1 -menu_vts 1 -pgc 1 -pg 1 -i <path to DVD> ...
    +
    +
+ + +

20.8 ea

+ +

Electronic Arts Multimedia format demuxer. +

+

This format is used by various Electronic Arts games. +

+ +

20.8.1 Options

+ +
+
merge_alpha bool
+
+

Normally the VP6 alpha channel (if exists) is returned as a secondary video +stream, by setting this option you can make the demuxer return a single video +stream which contains the alpha channel in addition to the ordinary video. +

+
+
+ + +

20.9 imf

+ +

Interoperable Master Format demuxer. +

+

This demuxer presents audio and video streams found in an IMF Composition, as +specified in SMPTE ST 2067-2. +

+
+
ffmpeg [-assetmaps <path of ASSETMAP1>,<path of ASSETMAP2>,...] -i <path of CPL> ...
+
+ +

If -assetmaps is not specified, the demuxer looks for a file called +ASSETMAP.xml in the same directory as the CPL. +

+ +

20.10 flv, live_flv, kux

+ +

Adobe Flash Video Format demuxer. +

+

This demuxer is used to demux FLV files and RTMP network streams. In case of live network streams, if you force format, you may use live_flv option instead of flv to survive timestamp discontinuities. +KUX is a flv variant used on the Youku platform. +

+
+
ffmpeg -f flv -i myfile.flv ...
+ffmpeg -f live_flv -i rtmp://<any.server>/anything/key ....
+
+ + +
+
-flv_metadata bool
+

Allocate the streams according to the onMetaData array content. +

+
+
-flv_ignore_prevtag bool
+

Ignore the size of previous tag value. +

+
+
-flv_full_metadata bool
+

Output all context of the onMetadata. +

+
+ + +

20.11 gif

+ +

Animated GIF demuxer. +

+

It accepts the following options: +

+
+
min_delay
+

Set the minimum valid delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 2. +

+
+
max_gif_delay
+

Set the maximum valid delay between frames in hundredth of seconds. +Range is 0 to 65535. Default value is 65535 (nearly eleven minutes), +the maximum value allowed by the specification. +

+
+
default_delay
+

Set the default delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 10. +

+
+
ignore_loop
+

GIF files can contain information to loop a certain number of times (or +infinitely). If ignore_loop is set to 1, then the loop setting +from the input will be ignored and looping will not occur. If set to 0, +then looping will occur and will cycle the number of times according to +the GIF. Default value is 1. +

+
+ +

For example, with the overlay filter, place an infinitely looping GIF +over another video: +

+
ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv
+
+ +

Note that in the above example the shortest option for overlay filter is +used to end the output video at the length of the shortest input file, +which in this case is input.mp4 as the GIF in this example loops +infinitely. +

+ +

20.12 hls

+ +

HLS demuxer +

+

Apple HTTP Live Streaming demuxer. +

+

This demuxer presents all AVStreams from all variant streams. +The id field is set to the bitrate variant index number. By setting +the discard flags on AVStreams (by pressing ’a’ or ’v’ in ffplay), +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". +

+

It accepts the following options: +

+
+
live_start_index
+

segment index to start live streams at (negative values are from the end). +

+
+
prefer_x_start
+

prefer to use #EXT-X-START if it’s in playlist instead of live_start_index. +

+
+
allowed_extensions
+

’,’ separated list of file extensions that hls is allowed to access. +

+
+
extension_picky
+

This blocks disallowed extensions from probing +It also requires all available segments to have matching extensions to the format +except mpegts, which is always allowed. +It is recommended to set the whitelists correctly instead of depending on extensions +Enabled by default. +

+
+
max_reload
+

Maximum number of times a insufficient list is attempted to be reloaded. +Default value is 1000. +

+
+
m3u8_hold_counters
+

The maximum number of times to load m3u8 when it refreshes without new segments. +Default value is 1000. +

+
+
http_persistent
+

Use persistent HTTP connections. Applicable only for HTTP streams. +Enabled by default. +

+
+
http_multiple
+

Use multiple HTTP connections for downloading HTTP segments. +Enabled by default for HTTP/1.1 servers. +

+
+
http_seekable
+

Use HTTP partial requests for downloading HTTP segments. +0 = disable, 1 = enable, -1 = auto, Default is auto. +

+
+
seg_format_options
+

Set options for the demuxer of media segments using a list of key=value pairs separated by :. +

+
+
seg_max_retry
+

Maximum number of times to reload a segment on error, useful when segment skip on network error is not desired. +Default value is 0. +

+
+ + +

20.13 image2

+ +

Image file demuxer. +

+

This demuxer reads from a list of image files specified by a pattern. +The syntax and meaning of the pattern is specified by the +option pattern_type. +

+

The pattern may contain a suffix which is used to automatically +determine the format of the images contained in the files. +

+

The size, the pixel format, and the format of each image must be the +same for all the files in the sequence. +

+

This demuxer accepts the following options: +

+
framerate
+

Set the frame rate for the video stream. It defaults to 25. +

+
loop
+

If set to 1, loop over the input. Default value is 0. +

+
pattern_type
+

Select the pattern type used to interpret the provided filename. +

+

pattern_type accepts one of the following values. +

+
none
+

Disable pattern matching, therefore the video will only contain the specified +image. You should use this option if you do not want to create sequences from +multiple images and your filenames may contain special pattern characters. +

+
sequence
+

Select a sequence pattern type, used to specify a sequence of files +indexed by sequential numbers. +

+

A sequence pattern may contain the string "%d" or "%0Nd", which +specifies the position of the characters representing a sequential +number in each filename matched by the pattern. If the form +"%d0Nd" is used, the string representing the number in each +filename is 0-padded and N is the total number of 0-padded +digits representing the number. The literal character ’%’ can be +specified in the pattern with the string "%%". +

+

If the sequence pattern contains "%d" or "%0Nd", the first filename of +the file list specified by the pattern must contain a number +inclusively contained between start_number and +start_number+start_number_range-1, and all the following +numbers must be sequential. +

+

For example the pattern "img-%03d.bmp" will match a sequence of +filenames of the form img-001.bmp, img-002.bmp, ..., +img-010.bmp, etc.; the pattern "i%%m%%g-%d.jpg" will match a +sequence of filenames of the form i%m%g-1.jpg, +i%m%g-2.jpg, ..., i%m%g-10.jpg, etc. +

+

Note that the pattern must not necessarily contain "%d" or +"%0Nd", for example to convert a single image file +img.jpeg you can employ the command: +

+
ffmpeg -i img.jpeg img.png
+
+ +
+
glob
+

Select a glob wildcard pattern type. +

+

The pattern is interpreted like a glob() pattern. This is only +selectable if libavformat was compiled with globbing support. +

+
+ +

Default value is sequence. +

+
pixel_format
+

Set the pixel format of the images to read. If not specified the pixel +format is guessed from the first image file in the sequence. +

+
start_number
+

Set the index of the file matched by the image file pattern to start +to read from. Default value is 0. +

+
start_number_range
+

Set the index interval range to check when looking for the first image +file in the sequence, starting from start_number. Default value +is 5. +

+
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. +If set to 2, will set frame timestamp to the modification time of the image file in +nanosecond precision. +

+
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. +

+
export_path_metadata
+

If set to 1, will add two extra fields to the metadata found in input, making them +also available for other filters (see drawtext filter for examples). Default +value is 0. The extra fields are described below: +

+
lavf.image2dec.source_path
+

Corresponds to the full path to the input file being read. +

+
lavf.image2dec.source_basename
+

Corresponds to the name of the file being read. +

+
+ +
+
+ + +

20.13.1 Examples

+ +
    +
  • Use ffmpeg for creating a video from the images in the file +sequence img-001.jpeg, img-002.jpeg, ..., assuming an +input frame rate of 10 frames per second: +
    +
    ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • As above, but start by reading from a file with index 100 in the sequence: +
    +
    ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • Read images matching the "*.png" glob pattern , that is all the files +terminating with the ".png" suffix: +
    +
    ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv
    +
    +
+ + +

20.14 libgme

+ +

The Game Music Emu library is a collection of video game music file emulators. +

+

See https://bitbucket.org/mpyne/game-music-emu/overview for more information. +

+

It accepts the following options: +

+
+
track_index
+

Set the index of which track to demux. The demuxer can only export one track. +Track indexes start at 0. Default is to pick the first track. Number of tracks +is exported as tracks metadata entry. +

+
+
sample_rate
+

Set the sampling rate of the exported track. Range is 1000 to 999999. Default is 44100. +

+
+
max_size (bytes)
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. +Default is 50 MiB. +

+
+
+ + +

20.15 libmodplug

+ +

ModPlug based module demuxer +

+

See https://github.com/Konstanty/libmodplug +

+

It will export one 2-channel 16-bit 44.1 kHz audio stream. +Optionally, a pal8 16-color video stream can be exported with or without printed metadata. +

+

It accepts the following options: +

+
+
noise_reduction
+

Apply a simple low-pass filter. Can be 1 (on) or 0 (off). Default is 0. +

+
+
reverb_depth
+

Set amount of reverb. Range 0-100. Default is 0. +

+
+
reverb_delay
+

Set delay in ms, clamped to 40-250 ms. Default is 0. +

+
+
bass_amount
+

Apply bass expansion a.k.a. XBass or megabass. Range is 0 (quiet) to 100 (loud). Default is 0. +

+
+
bass_range
+

Set cutoff i.e. upper-bound for bass frequencies. Range is 10-100 Hz. Default is 0. +

+
+
surround_depth
+

Apply a Dolby Pro-Logic surround effect. Range is 0 (quiet) to 100 (heavy). Default is 0. +

+
+
surround_delay
+

Set surround delay in ms, clamped to 5-40 ms. Default is 0. +

+
+
max_size
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. Range is 0 to 100 MiB. +0 removes buffer size limit (not recommended). Default is 5 MiB. +

+
+
video_stream_expr
+

String which is evaluated using the eval API to assign colors to the generated video stream. +Variables which can be used are x, y, w, h, t, speed, +tempo, order, pattern and row. +

+
+
video_stream
+

Generate video stream. Can be 1 (on) or 0 (off). Default is 0. +

+
+
video_stream_w
+

Set video frame width in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_h
+

Set video frame height in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_ptxt
+

Print metadata on video stream. Includes speed, tempo, order, pattern, +row and ts (time in ms). Can be 1 (on) or 0 (off). Default is 1. +

+
+
+ + +

20.16 libopenmpt

+ +

libopenmpt based module demuxer +

+

See https://lib.openmpt.org/libopenmpt/ for more information. +

+

Some files have multiple subsongs (tracks) this can be set with the subsong +option. +

+

It accepts the following options: +

+
+
subsong
+

Set the subsong index. This can be either ’all’, ’auto’, or the index of the +subsong. Subsong indexes start at 0. The default is ’auto’. +

+

The default value is to let libopenmpt choose. +

+
+
layout
+

Set the channel layout. Valid values are 1, 2, and 4 channel layouts. +The default value is STEREO. +

+
+
sample_rate
+

Set the sample rate for libopenmpt to output. +Range is from 1000 to INT_MAX. The value default is 48000. +

+
+ + +

20.17 mcc

+ +

Demuxer for MacCaption MCC files, it supports MCC versions 1.0 and 2.0. +MCC files store VANC data, which can include closed captions (EIA-608 and CEA-708), ancillary time code, pan-scan data, etc. +By default, for backward compatibility, the MCC demuxer extracts just the EIA-608 and CEA-708 closed captions and returns a EIA_608 stream, ignoring all other VANC data. +You can change it to return all VANC data in a SMPTE_436M_ANC data stream by setting -eia608_extract 0 +

+ +

20.17.1 Examples

+ +
    +
  • Convert a MCC file to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.mcc -c:s copy CC.scc
    +
    +

    Note that the SCC format only supports EIA-608, so this will discard all other data such as CEA-708 extensions. +

    +
  • Merge a MCC file into a MXF file: +
    +
    ffmpeg -i video_and_audio.mxf -eia608_extract 0 -i CC.mcc -c copy -map 0 -map 1 out.mxf
    +
    +

    This retains all VANC data and inserts it into the output MXF file as a SMPTE_436M_ANC data stream. +

+ + +

20.18 mov/mp4/3gp

+ +

Demuxer for Quicktime File Format & ISO/IEC Base Media File Format (ISO/IEC 14496-12 or MPEG-4 Part 12, ISO/IEC 15444-12 or JPEG 2000 Part 12). +

+

Registered extensions: mov, mp4, m4a, 3gp, 3g2, mj2, psp, m4b, ism, ismv, isma, f4v +

+ +

20.18.1 Options

+ +

This demuxer accepts the following options: +

+
enable_drefs
+

Enable loading of external tracks, disabled by default. +Enabling this can theoretically leak information in some use cases. +

+
+
use_absolute_path
+

Allows loading of external tracks via absolute paths, disabled by default. +Enabling this poses a security risk. It should only be enabled if the source +is known to be non-malicious. +

+
+
seek_streams_individually
+

When seeking, identify the closest point in each stream individually and demux packets in +that stream from identified point. This can lead to a different sequence of packets compared +to demuxing linearly from the beginning. Default is true. +

+
+
ignore_editlist
+

Ignore any edit list atoms. The demuxer, by default, modifies the stream index to reflect the +timeline described by the edit list. Default is false. +

+
+
advanced_editlist
+

Modify the stream index to reflect the timeline described by the edit list. ignore_editlist +must be set to false for this option to be effective. +If both ignore_editlist and this option are set to false, then only the +start of the stream index is modified to reflect initial dwell time or starting timestamp +described by the edit list. Default is true. +

+
+
ignore_chapters
+

Don’t parse chapters. This includes GoPro ’HiLight’ tags/moments. Note that chapters are +only parsed when input is seekable. Default is false. +

+
+
use_mfra_for
+

For seekable fragmented input, set fragment’s starting timestamp from media fragment random access box, if present. +

+

Following options are available: +

+
‘auto’
+

Auto-detect whether to set mfra timestamps as PTS or DTS (default) +

+
+
‘dts’
+

Set mfra timestamps as DTS +

+
+
‘pts’
+

Set mfra timestamps as PTS +

+
+
‘0’
+

Don’t use mfra box to set timestamps +

+
+ +
+
use_tfdt
+

For fragmented input, set fragment’s starting timestamp to baseMediaDecodeTime from the tfdt box. +Default is enabled, which will prefer to use the tfdt box to set DTS. Disable to use the earliest_presentation_time from the sidx box. +In either case, the timestamp from the mfra box will be used if it’s available and use_mfra_for is +set to pts or dts. +

+
+
export_all
+

Export unrecognized boxes within the udta box as metadata entries. The first four +characters of the box type are set as the key. Default is false. +

+
+
export_xmp
+

Export entire contents of XMP_ box and uuid box as a string with key xmp. Note that +if export_all is set and this option isn’t, the contents of XMP_ box are still exported +but with key XMP_. Default is false. +

+
+
activation_bytes
+

4-byte key required to decrypt Audible AAX and AAX+ files. See Audible AAX subsection below. +

+
+
audible_fixed_key
+

Fixed key used for handling Audible AAX/AAX+ files. It has been pre-set so should not be necessary to +specify. +

+
+
decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
max_stts_delta
+

Very high sample deltas written in a trak’s stts box may occasionally be intended but usually they are written in +error or used to store a negative value for dts correction when treated as signed 32-bit integers. This option lets +the user set an upper limit, beyond which the delta is clamped to 1. Values greater than the limit if negative when +cast to int32 are used to adjust onward dts. +

+

Unit is the track time scale. Range is 0 to UINT_MAX. Default is UINT_MAX - 48000*10 which allows up to +a 10 second dts correction for 48 kHz audio streams while accommodating 99.9% of uint32 range. +

+
+
interleaved_read
+

Interleave packets from multiple tracks at demuxer level. For badly interleaved files, this prevents playback issues +caused by large gaps between packets in different tracks, as MOV/MP4 do not have packet placement requirements. +However, this can cause excessive seeking on very badly interleaved files, due to seeking between tracks, so disabling +it may prevent I/O issues, at the expense of playback. +

+
+
+ + +

20.18.2 Audible AAX

+ +

Audible AAX files are encrypted M4B files, and they can be decrypted by specifying a 4 byte activation secret. +

+
ffmpeg -activation_bytes 1CEB00DA -i test.aax -vn -c:a copy output.mp4
+
+ + +

20.19 mpegts

+ +

MPEG-2 transport stream demuxer. +

+

This demuxer accepts the following options: +

+
resync_size
+

Set size limit for looking up a new synchronization. Default value is +65536. +

+
+
skip_unknown_pmt
+

Skip PMTs for programs not defined in the PAT. Default value is 0. +

+
+
fix_teletext_pts
+

Override 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. +

+
+
ts_packetsize
+

Output option carrying the raw packet size in bytes. +Show the detected raw packet size, cannot be set by the user. +

+
+
scan_all_pmts
+

Scan and combine all PMTs. The value is an integer with value from -1 +to 1 (-1 means automatic setting, 1 means enabled, 0 means +disabled). Default value is -1. +

+
+
merge_pmt_versions
+

Reuse existing streams when a PMT’s version is updated and elementary +streams move to different PIDs. Default value is 0. +

+
+
max_packet_size
+

Set maximum size, in bytes, of packet emitted by the demuxer. Payloads above this size +are split across multiple packets. Range is 1 to INT_MAX/2. Default is 204800 bytes. +

+
+ + +

20.20 mpjpeg

+ +

MJPEG encapsulated in multi-part MIME demuxer. +

+

This demuxer allows reading of MJPEG, where each frame is represented as a part of +multipart/x-mixed-replace stream. +

+
strict_mime_boundary
+

Default implementation applies a relaxed standard to multi-part MIME boundary detection, +to prevent regression with numerous existing endpoints not generating a proper MIME +MJPEG stream. Turning this option on by setting it to 1 will result in a stricter check +of the boundary value. +

+
+ + +

20.21 rawvideo

+ +

Raw video demuxer. +

+

This demuxer allows one to read raw video data. Since there is no header +specifying the assumed video parameters, the user must specify them +in order to be able to decode the data correctly. +

+

This demuxer accepts the following options: +

+
framerate
+

Set input video frame rate. Default value is 25. +

+
+
pixel_format
+

Set the input video pixel format. Default value is yuv420p. +

+
+
stride
+

Set frame line size in bytes, only required if there are extra padding. +For multiplane formats, stride is a list of line size for each +plane. +

+
+
video_size
+

Set the input video size. This value must be specified explicitly. +

+
+ +

For example to read a rawvideo file input.raw with +ffplay, assuming a pixel format of rgb24, a video +size of 320x240, and a frame rate of 10 images per second, use +the command: +

+
ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw
+
+ +

Read a rawvideo with ffplay, assuming a pixel format of yuv420p, +a video size of 1080x1920, has 8 bytes of padding in each line of Y plane, +and 4 bytes of padding with UV plane, +

+
ffplay -f rawvideo -pixel_format yuv420p -video_size 1080x1920 -stride 1088,544,544 input.raw
+
+ + +

20.22 rcwt

+ +

RCWT (Raw Captions With Time) is a format native to ccextractor, a commonly +used open source tool for processing 608/708 Closed Captions (CC) sources. +For more information on the format, see (ffmpeg-formats)rcwtenc. +

+

This demuxer implements the specification as of March 2024, which has +been stable and unchanged since April 2014. +

+ +

20.22.1 Examples

+ +
    +
  • Render CC to ASS using the built-in decoder: +
    +
    ffmpeg -i CC.rcwt.bin CC.ass
    +
    +

    Note that if your output appears to be empty, you may have to manually +set the decoder’s data_field option to pick the desired CC substream. +

    +
  • Convert an RCWT backup to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.rcwt.bin -c:s copy CC.scc
    +
    +

    Note that the SCC format does not support all of the possible CC extensions +that can be stored in RCWT (such as EIA-708). +

+ + +

20.23 sbg

+ +

SBaGen script demuxer. +

+

This demuxer reads the script language used by SBaGen +http://uazu.net/sbagen/ to generate binaural beats sessions. A SBG +script looks like that: +

+
-SE
+a: 300-2.5/3 440+4.5/0
+b: 300-2.5/0 440+4.5/3
+off: -
+NOW      == a
++0:07:00 == b
++0:14:00 == a
++0:21:00 == b
++0:30:00    off
+
+ +

A SBG script can mix absolute and relative timestamps. If the script uses +either only absolute timestamps (including the script start time) or only +relative ones, then its layout is fixed, and the conversion is +straightforward. On the other hand, if the script mixes both kind of +timestamps, then the NOW reference for relative timestamps will be +taken from the current time of day at the time the script is read, and the +script layout will be frozen according to that reference. That means that if +the script is directly played, the actual times will match the absolute +timestamps up to the sound controller’s clock accuracy, but if the user +somehow pauses the playback or seeks, all times will be shifted accordingly. +

+ +

20.24 tedcaptions

+ +

JSON captions used for TED Talks. +

+

TED does not provide links to the captions, but they can be guessed from the +page. The file tools/bookmarklets.html from the FFmpeg source tree +contains a bookmarklet to expose them. +

+

This demuxer accepts the following option: +

+
start_time
+

Set the start time of the TED talk, in milliseconds. The default is 15000 +(15s). It is used to sync the captions with the downloadable videos, because +they include a 15s intro. +

+
+ +

Example: convert the captions to a format most players understand: +

+
ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt
+
+ + +

20.25 vapoursynth

+ +

Vapoursynth wrapper. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+

This demuxer accepts the following option: +

+
max_script_size
+

The demuxer buffers the entire script into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of scripts that can be read. +Default is 1 MiB. +

+
+ + +

20.26 w64

+ +

Sony Wave64 Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

See the same option for the wav demuxer. +

+
+ + +

20.27 wav

+ +

RIFF Wave Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

Specify the maximum packet size in bytes for the demuxed packets. By default +this is set to 0, which means that a sensible value is chosen based on the +input format. +

+
+ + +

21 Muxers

+ +

Muxers are configured elements in FFmpeg which allow writing +multimedia streams to a particular type of file. +

+

When you configure your FFmpeg build, all the supported muxers +are enabled by default. You can list all available muxers using the +configure option --list-muxers. +

+

You can disable all the muxers with the configure option +--disable-muxers and selectively enable / disable single muxers +with the options --enable-muxer=MUXER / +--disable-muxer=MUXER. +

+

The option -muxers of the ff* tools will display the list of +enabled muxers. Use -formats to view a combined list of +enabled demuxers and muxers. +

+

A description of some of the currently available muxers follows. +

+ +

21.1 Raw muxers

+ +

This section covers raw muxers. They accept a single stream matching +the designated codec. They do not store timestamps or metadata. The +recognized extension is the same as the muxer name unless indicated +otherwise. +

+

It comprises the following muxers. The media type and the eventual +extensions used to automatically selects the muxer from the output +extensions are also shown. +

+
+
‘ac3 audio’
+

Dolby Digital, also known as AC-3. +

+
+
‘adx audio’
+

CRI Middleware ADX audio. +

+

This muxer will write out the total sample count near the start of the +first packet when the output is seekable and the count can be stored +in 32 bits. +

+
+
‘aptx audio’
+

aptX (Audio Processing Technology for Bluetooth) +

+
+
‘aptx_hd audio (aptxdh)’
+

aptX HD (Audio Processing Technology for Bluetooth) audio +

+
+
‘avs2 video (avs, avs2)’
+

AVS2-P2 (Audio Video Standard - Second generation - Part 2) / +IEEE 1857.4 video +

+
+
‘avs3 video (avs3)’
+

AVS3-P2 (Audio Video Standard - Third generation - Part 2) / +IEEE 1857.10 video +

+
+
‘cavsvideo video (cavs)’
+

Chinese AVS (Audio Video Standard - First generation) +

+
+
‘codec2raw audio’
+

Codec 2 audio. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f codec2raw. +

+
+
‘data any’
+

Generic data muxer. +

+

This muxer accepts a single stream with any codec of any type. The +input stream has to be selected using the -map option with the +ffmpeg CLI tool. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f data. +

+
+
‘dfpwm audio (dfpwm)’
+

Raw DFPWM1a (Dynamic Filter Pulse With Modulation) audio muxer. +

+
+
‘dirac video (drc, vc2)’
+

BBC Dirac video. +

+

The Dirac Pro codec is a subset and is standardized as SMPTE VC-2. +

+
+
‘dnxhd video (dnxhd, dnxhr)’
+

Avid DNxHD video. +

+

It is standardized as SMPTE VC-3. Accepts DNxHR streams. +

+
+
‘dts audio’
+

DTS Coherent Acoustics (DCA) audio +

+
+
‘eac3 audio’
+

Dolby Digital Plus, also known as Enhanced AC-3 +

+
+
‘evc video (evc)’
+

MPEG-5 Essential Video Coding (EVC) / EVC / MPEG-5 Part 1 EVC video +

+
+
‘g722 audio’
+

ITU-T G.722 audio +

+
+
‘g723_1 audio (tco, rco)’
+

ITU-T G.723.1 audio +

+
+
‘g726 audio’
+

ITU-T G.726 big-endian ("left-justified") audio. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f g726. +

+
+
‘g726le audio’
+

ITU-T G.726 little-endian ("right-justified") audio. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f g726le. +

+
+
‘gsm audio’
+

Global System for Mobile Communications audio +

+
+
‘h261 video’
+

ITU-T H.261 video +

+
+
‘h263 video’
+

ITU-T H.263 / H.263-1996, H.263+ / H.263-1998 / H.263 version 2 video +

+
+
‘h264 video (h264, 264)’
+

ITU-T H.264 / MPEG-4 Part 10 AVC video. Bitstream shall be converted +to Annex B syntax if it’s in length-prefixed mode. +

+
+
‘hevc video (hevc, h265, 265)’
+

ITU-T H.265 / MPEG-H Part 2 HEVC video. Bitstream shall be converted +to Annex B syntax if it’s in length-prefixed mode. +

+
+
‘m4v video’
+

MPEG-4 Part 2 video +

+
+
‘mjpeg video (mjpg, mjpeg)’
+

Motion JPEG video +

+
+
‘mlp audio’
+

Meridian Lossless Packing, also known as Packed PCM +

+
+
‘mp2 audio (mp2, m2a, mpa)’
+

MPEG-1 Audio Layer II audio +

+
+
‘mpeg1video video (mpg, mpeg, m1v)’
+

MPEG-1 Part 2 video. +

+
+
‘mpeg2video video (m2v)’
+

ITU-T H.262 / MPEG-2 Part 2 video +

+
+
‘obu video’
+

AV1 low overhead Open Bitstream Units muxer. +

+

Temporal delimiter OBUs will be inserted in all temporal units of the +stream. +

+
+
‘rawvideo video (yuv, rgb)’
+

Raw uncompressed video. +

+
+
‘sbc audio (sbc, msbc)’
+

Bluetooth SIG low-complexity subband codec audio +

+
+
‘truehd audio (thd)’
+

Dolby TrueHD audio +

+
+
‘vc1 video’
+

SMPTE 421M / VC-1 video +

+
+ + +

21.1.1 Examples

+ +
    +
  • Store raw video frames with the ‘rawvideo’ muxer using ffmpeg: +
    +
    ffmpeg -f lavfi -i testsrc -t 10 -s hd1080p testsrc.yuv
    +
    + +

    Since the rawvideo muxer do not store the information related to size +and format, this information must be provided when demuxing the file: +

    +
    ffplay -video_size 1920x1080 -pixel_format rgb24 -f rawvideo testsrc.rgb
    +
    +
+ + +

21.2 Raw PCM muxers

+

This section covers raw PCM (Pulse-Code Modulation) audio muxers. +

+

They accept a single stream matching the designated codec. They do not +store timestamps or metadata. The recognized extension is the same as +the muxer name. +

+

It comprises the following muxers. The optional additional extension +used to automatically select the muxer from the output extension is +also shown in parentheses. +

+
+
‘alaw (al)’
+

PCM A-law +

+
+
‘f32be’
+

PCM 32-bit floating-point big-endian +

+
+
‘f32le’
+

PCM 32-bit floating-point little-endian +

+
+
‘f64be’
+

PCM 64-bit floating-point big-endian +

+
+
‘f64le’
+

PCM 64-bit floating-point little-endian +

+
+
‘mulaw (ul)’
+

PCM mu-law +

+
+
‘s16be’
+

PCM signed 16-bit big-endian +

+
+
‘s16le’
+

PCM signed 16-bit little-endian +

+
+
‘s24be’
+

PCM signed 24-bit big-endian +

+
+
‘s24le’
+

PCM signed 24-bit little-endian +

+
+
‘s32be’
+

PCM signed 32-bit big-endian +

+
+
‘s32le’
+

PCM signed 32-bit little-endian +

+
+
‘s8 (sb)’
+

PCM signed 8-bit +

+
+
‘u16be’
+

PCM unsigned 16-bit big-endian +

+
+
‘u16le’
+

PCM unsigned 16-bit little-endian +

+
+
‘u24be’
+

PCM unsigned 24-bit big-endian +

+
+
‘u24le’
+

PCM unsigned 24-bit little-endian +

+
+
‘u32be’
+

PCM unsigned 32-bit big-endian +

+
+
‘u32le’
+

PCM unsigned 32-bit little-endian +

+
+
‘u8 (ub)’
+

PCM unsigned 8-bit +

+
+
‘vidc’
+

PCM Archimedes VIDC +

+
+ + +

21.3 MPEG-1/MPEG-2 program stream muxers

+ +

This section covers formats belonging to the MPEG-1 and MPEG-2 Systems +family. +

+

The MPEG-1 Systems format (also known as ISO/IEEC 11172-1 or MPEG-1 +program stream) has been adopted for the format of media track stored +in VCD (Video Compact Disc). +

+

The MPEG-2 Systems standard (also known as ISO/IEEC 13818-1) covers +two containers formats, one known as transport stream and one known as +program stream; only the latter is covered here. +

+

The MPEG-2 program stream format (also known as VOB due to the +corresponding file extension) is an extension of MPEG-1 program +stream: in addition to support different codecs for the audio and +video streams, it also stores subtitles and navigation metadata. +MPEG-2 program stream has been adopted for storing media streams in +SVCD and DVD storage devices. +

+

This section comprises the following muxers. +

+
+
‘mpeg (mpg,mpeg)’
+

MPEG-1 Systems / MPEG-1 program stream muxer. +

+
+
‘vcd’
+

MPEG-1 Systems / MPEG-1 program stream (VCD) muxer. +

+

This muxer can be used to generate tracks in the format accepted by +the VCD (Video Compact Disc) storage devices. +

+

It is the same as the ‘mpeg’ muxer with a few differences. +

+
+
‘vob’
+

MPEG-2 program stream (VOB) muxer. +

+
+
‘dvd’
+

MPEG-2 program stream (DVD VOB) muxer. +

+

This muxer can be used to generate tracks in the format accepted by +the DVD (Digital Versatile Disc) storage devices. +

+

This is the same as the ‘vob’ muxer with a few differences. +

+
+
‘svcd (vob)’
+

MPEG-2 program stream (SVCD VOB) muxer. +

+

This muxer can be used to generate tracks in the format accepted by +the SVCD (Super Video Compact Disc) storage devices. +

+

This is the same as the ‘vob’ muxer with a few differences. +

+
+ + +

21.3.1 Options

+
+
muxrate rate
+

Set user-defined mux rate expressed as a number of bits/s. If not +specified the automatically computed mux rate is employed. Default value +is 0. +

+
+
preload delay
+

Set initial demux-decode delay in microseconds. Default value is +500000. +

+
+ + +

21.4 MOV/MPEG-4/ISOMBFF muxers

+ +

This section covers formats belonging to the QuickTime / MOV family, +including the MPEG-4 Part 14 format and ISO base media file format +(ISOBMFF). These formats share a common structure based on the ISO +base media file format (ISOBMFF). +

+

The MOV format was originally developed for use with Apple QuickTime. +It was later used as the basis for the MPEG-4 Part 1 (later Part 14) +format, also known as ISO/IEC 14496-1. That format was then +generalized into ISOBMFF, also named MPEG-4 Part 12 format, ISO/IEC +14496-12, or ISO/IEC 15444-12. +

+

It comprises the following muxers. +

+
+
‘3gp’
+

Third Generation Partnership Project (3GPP) format for 3G UMTS +multimedia services +

+
+
‘3g2’
+

Third Generation Partnership Project 2 (3GP2 or 3GPP2) format for 3G +CDMA2000 multimedia services, similar to ‘3gp’ with extensions +and limitations +

+
+
‘f4v’
+

Adobe Flash Video format +

+
+
‘ipod’
+

MPEG-4 audio file format, as MOV/MP4 but limited to contain only audio +streams, typically played with the Apple ipod device +

+
+
‘ismv’
+

Microsoft IIS (Internet Information Services) Smooth Streaming +Audio/Video (ISMV or ISMA) format. This is based on MPEG-4 Part 14 +format with a few incompatible variants, used to stream media files +for the Microsoft IIS server. +

+
+
‘mov’
+

QuickTime player format identified by the .mov extension +

+
+
‘mp4’
+

MP4 or MPEG-4 Part 14 format +

+
+
‘psp’
+

PlayStation Portable MP4/MPEG-4 Part 14 format variant. This is based +on MPEG-4 Part 14 format with a few incompatible variants, used to +play files on PlayStation devices. +

+
+ + +

21.4.1 Fragmentation

+ +

The ‘mov’, ‘mp4’, and ‘ismv’ muxers support +fragmentation. Normally, a MOV/MP4 file has all the metadata about all +packets stored in one location. +

+

This data is usually written at the end of the file, but it can be +moved to the start for better playback by adding +faststart to +the -movflags, or using the qt-faststart tool). +

+

A fragmented file consists of a number of fragments, where packets and +metadata about these packets are stored together. Writing a fragmented +file has the advantage that the file is decodable even if the writing +is interrupted (while a normal MOV/MP4 is undecodable if it is not +properly finished), and it requires less memory when writing very long +files (since writing normal MOV/MP4 files stores info about every +single packet in memory until the file is closed). The downside is +that it is less compatible with other applications. +

+

Fragmentation is enabled by setting one of the options that define +how to cut the file into fragments: +

+
frag_duration
+
frag_size
+
min_frag_duration
+
movflags +frag_keyframe
+
movflags +frag_custom
+
+ +

If more than one condition is specified, fragments are cut when one of +the specified conditions is fulfilled. The exception to this is the +option min_frag_duration, which has to be fulfilled for any +of the other conditions to apply. +

+ +

21.4.2 Options

+ +
+
brand brand_string
+

Override major brand. +

+
+
empty_hdlr_name bool
+

Enable to skip writing the name inside a hdlr box. +Default is false. +

+
+
encryption_key key
+

set the media encryption key in hexadecimal format +

+
+
encryption_kid kid
+

set the media encryption key identifier in hexadecimal format +

+
+
encryption_scheme scheme
+

configure the encryption scheme, allowed values are ‘none’, and +‘cenc-aes-ctr’ +

+
+
frag_duration duration
+

Create fragments that are duration microseconds long. +

+
+
frag_interleave number
+

Interleave samples within fragments (max number of consecutive +samples, lower is tighter interleaving, but with more overhead. It is +set to 0 by default. +

+
+
frag_size size
+

create fragments that contain up to size bytes of payload data +

+
+
iods_audio_profile profile
+

specify iods number for the audio profile atom (from -1 to 255), +default is -1 +

+
+
iods_video_profile profile
+

specify iods number for the video profile atom (from -1 to 255), +default is -1 +

+
+
ism_lookahead num_entries
+

specify number of lookahead entries for ISM files (from 0 to 255), +default is 0 +

+
+
min_frag_duration duration
+

do not create fragments that are shorter than duration microseconds long +

+
+
moov_size bytes
+

Reserves space for the moov atom at the beginning of the file instead of placing the +moov atom at the end. If the space reserved is insufficient, muxing will fail. +

+
+
mov_gamma gamma
+

specify gamma value for gama atom (as a decimal number from 0 to 10), +default is 0.0, must be set together with + movflags +

+
+
movflags flags
+

Set various muxing switches. The following flags can be used: +

+
‘cmaf’
+

write CMAF (Common Media Application Format) compatible fragmented +MP4 output +

+
+
‘dash’
+

write DASH (Dynamic Adaptive Streaming over HTTP) compatible fragmented +MP4 output +

+
+
‘default_base_moof’
+

Similarly to the ‘omit_tfhd_offset’ flag, this flag avoids +writing the absolute base_data_offset field in tfhd atoms, but does so +by using the new default-base-is-moof flag instead. This flag is new +from 14496-12:2012. This may make the fragments easier to parse in +certain circumstances (avoiding basing track fragment location +calculations on the implicit end of the previous track fragment). +

+
+
‘delay_moov’
+

delay writing the initial moov until the first fragment is cut, or +until the first fragment flush +

+
+
‘disable_chpl’
+

Disable Nero chapter markers (chpl atom). Normally, both Nero chapters +and a QuickTime chapter track are written to the file. With this +option set, only the QuickTime chapter track will be written. Nero +chapters can cause failures when the file is reprocessed with certain +tagging programs, like mp3Tag 2.61a and iTunes 11.3, most likely other +versions are affected as well. +

+
+
‘faststart’
+

Run a second pass moving the index (moov atom) to the beginning of the +file. This operation can take a while, and will not work in various +situations such as fragmented output, thus it is not enabled by +default. +

+
+
‘frag_custom’
+

Allow the caller to manually choose when to cut fragments, by calling +av_write_frame(ctx, NULL) to write a fragment with the packets +written so far. (This is only useful with other applications +integrating libavformat, not from ffmpeg.) +

+
+
‘frag_discont’
+

signal that the next fragment is discontinuous from earlier ones +

+
+
‘frag_every_frame’
+

fragment at every frame +

+
+
‘frag_keyframe’
+

start a new fragment at each video keyframe +

+
+
‘global_sidx’
+

write a global sidx index at the start of the file +

+
+
‘isml’
+

create a live smooth streaming feed (for pushing to a publishing point) +

+
+
‘negative_cts_offsets’
+

Enables utilization of version 1 of the CTTS box, in which the CTS offsets can +be negative. This enables the initial sample to have DTS/CTS of zero, and +reduces the need for edit lists for some cases such as video tracks with +B-frames. Additionally, eases conformance with the DASH-IF interoperability +guidelines. +

+

This option is implicitly set when writing ‘ismv’ (Smooth +Streaming) files. +

+
+
‘omit_tfhd_offset’
+

Do not write any absolute base_data_offset in tfhd atoms. This avoids +tying fragments to absolute byte positions in the file/streams. +

+
+
‘prefer_icc’
+

If writing colr atom prioritise usage of ICC profile if it exists in +stream packet side data. +

+
+
‘rtphint’
+

add RTP hinting tracks to the output file +

+
+
‘separate_moof’
+

Write a separate moof (movie fragment) atom for each track. Normally, +packets for all tracks are written in a moof atom (which is slightly +more efficient), but with this option set, the muxer writes one +moof/mdat pair for each track, making it easier to separate tracks. +

+
+
‘skip_sidx’
+

Skip writing of sidx atom. When bitrate overhead due to sidx atom is +high, this option could be used for cases where sidx atom is not +mandatory. When the ‘global_sidx’ flag is enabled, this option +is ignored. +

+
+
‘skip_trailer’
+

skip writing the mfra/tfra/mfro trailer for fragmented files +

+
+
‘use_metadata_tags’
+

use mdta atom for metadata +

+
+
‘write_colr’
+

write colr atom even if the color info is unspecified. This flag is +experimental, may be renamed or changed, do not use from scripts. +

+
+
‘write_gama’
+

write deprecated gama atom +

+
+
‘hybrid_fragmented’
+

For recoverability - write the output file as a fragmented file. +This allows the intermediate file to be read while being written +(in particular, if the writing process is aborted uncleanly). When +writing is finished, the file is converted to a regular, non-fragmented +file, which is more compatible and allows easier and quicker seeking. +

+

If writing is aborted, the intermediate file can manually be +remuxed to get a regular, non-fragmented file of what had been +written into the unfinished file. +

+
+ +
+
movie_timescale scale
+

Set the timescale written in the movie header box (mvhd). +Range is 1 to INT_MAX. Default is 1000. +

+
+
rtpflags flags
+

Add RTP hinting tracks to the output file. +

+

The following flags can be used: +

+
‘h264_mode0’
+

use mode 0 for H.264 in RTP +

+
+
‘latm’
+

use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC +

+
+
‘rfc2190’
+

use RFC 2190 packetization instead of RFC 4629 for H.263 +

+
+
‘send_bye’
+

send RTCP BYE packets when finishing +

+
+
‘skip_rtcp’
+

do not send RTCP sender reports +

+
+ +
+
skip_iods bool
+

skip writing iods atom (default value is true) +

+
+
use_editlist bool
+

use edit list (default value is auto) +

+
+
use_stream_ids_as_track_ids bool
+

use stream ids as track ids (default value is false) +

+
+
video_track_timescale scale
+

Set the timescale used for video tracks. Range is 0 to INT_MAX. If +set to 0, the timescale is automatically set based on the +native stream time base. Default is 0. +

+
+
write_btrt bool
+

Force or disable writing bitrate box inside stsd box of a track. The +box contains decoding buffer size (in bytes), maximum bitrate and +average bitrate for the track. The box will be skipped if none of +these values can be computed. Default is -1 or auto, +which will write the box only in MP4 mode. +

+
+
write_prft option
+

Write producer time reference box (PRFT) with a specified time source for the +NTP field in the PRFT box. Set value as ‘wallclock’ to specify timesource +as wallclock time and ‘pts’ to specify timesource as input packets’ PTS +values. +

+
+
write_tmcd bool
+

Specify on to force writing a timecode track, off to disable it +and auto to write a timecode track only for mov and mp4 output (default). +

+

Setting value to ‘pts’ is applicable only for a live encoding use case, +where PTS values are set as as wallclock time at the source. For example, an +encoding use case with decklink capture source where video_pts and +audio_pts are set to ‘abs_wallclock’. +

+
+ + +

21.4.3 Examples

+ +
    +
  • Push Smooth Streaming content in real time to a publishing point on +IIS with the ‘ismv’ muxer using ffmpeg: +
    +
    ffmpeg -re <normal input/transcoding options> -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
    +
    +
+ + +

21.5 a64

+

A64 Commodore 64 video muxer. +

+

This muxer accepts a single a64_multi or a64_multi5 +codec video stream. +

+ +

21.6 ac4

+

Raw AC-4 audio muxer. +

+

This muxer accepts a single ac4 audio stream. +

+ +

21.6.1 Options

+
+
write_crc bool
+

when enabled, write a CRC checksum for each packet to the output, +default is false +

+
+ + +

21.7 adts

+

Audio Data Transport Stream muxer. +

+

It accepts a single AAC stream. +

+ +

21.7.1 Options

+
+
write_id3v2 bool
+

Enable to write ID3v2.4 tags at the start of the stream. Default is +disabled. +

+
+
write_apetag bool
+

Enable to write APE tags at the end of the stream. Default is +disabled. +

+
+
write_mpeg2 bool
+

Enable to set MPEG version bit in the ADTS frame header to 1 which +indicates MPEG-2. Default is 0, which indicates MPEG-4. +

+
+ + +

21.8 aea

+

MD STUDIO audio muxer. +

+

This muxer accepts a single ATRAC1 audio stream with either one or two channels +and a sample rate of 44100Hz. +

+

As AEA supports storing the track title, this muxer will also write +the title from stream’s metadata to the container. +

+ +

21.9 aiff

+

Audio Interchange File Format muxer. +

+ +

21.9.1 Options

+
+
write_id3v2 bool
+

Enable ID3v2 tags writing when set to 1. Default is 0 (disabled). +

+
+
id3v2_version bool
+

Select ID3v2 version to write. Currently only version 3 and 4 (aka. +ID3v2.3 and ID3v2.4) are supported. The default is version 4. +

+
+ + +

21.10 alp

+

High Voltage Software’s Lego Racers game audio muxer. +

+

It accepts a single ADPCM_IMA_ALP stream with no more than 2 channels +and a sample rate not greater than 44100 Hz. +

+

Extensions: tun, pcm +

+ +

21.10.1 Options

+
+
type type
+

Set file type. +

+

type accepts the following values: +

+
‘tun’
+

Set file type as music. Must have a sample rate of 22050 Hz. +

+
+
‘pcm’
+

Set file type as sfx. +

+
+
‘auto’
+

Set file type as per output file extension. .pcm results in +type pcm else type tun is set. (default) +

+
+
+
+ + +

21.11 amr

+

3GPP AMR (Adaptive Multi-Rate) audio muxer. +

+

It accepts a single audio stream containing an AMR NB stream. +

+ +

21.12 amv

+

AMV (Actions Media Video) format muxer. +

+ +

21.13 apm

+

Ubisoft Rayman 2 APM audio muxer. +

+

It accepts a single ADPCM IMA APM audio stream. +

+ +

21.14 apng

+

Animated Portable Network Graphics muxer. +

+

It accepts a single APNG video stream. +

+ +

21.14.1 Options

+
+
final_delay delay
+

Force a delay expressed in seconds after the last frame of each +repetition. Default value is 0.0. +

+
+
plays repetitions
+

specify how many times to play the content, 0 causes an infinite +loop, with 1 there is no loop +

+
+ + +

21.14.2 Examples

+
    +
  • Use ffmpeg to generate an APNG output with 2 repetitions, +and with a delay of half a second after the first repetition: +
    +
    ffmpeg -i INPUT -final_delay 0.5 -plays 2 out.apng
    +
    +
+ + +

21.15 argo_asf

+

Argonaut Games ASF audio muxer. +

+

It accepts a single ADPCM audio stream. +

+ +

21.15.1 Options

+
+
version_major version
+

override file major version, specified as an integer, default value is +2 +

+
+
version_minor version
+

override file minor version, specified as an integer, default value is +1 +

+
+
name name
+

Embed file name into file, if not specified use the output file +name. The name is truncated to 8 characters. +

+
+ + +

21.16 argo_cvg

+

Argonaut Games CVG audio muxer. +

+

It accepts a single one-channel ADPCM 22050Hz audio stream. +

+

The loop and reverb options set the corresponding +flags in the header which can be later retrieved to process the audio +stream accordingly. +

+ +

21.16.1 Options

+
+
skip_rate_check bool
+

skip sample rate check (default is false) +

+
+
loop bool
+

set loop flag (default is false) +

+
+
reverb boolean
+

set reverb flag (default is true) +

+
+ + +

21.17 asf, asf_stream

+

Advanced / Active Systems (or Streaming) Format audio muxer. +

+

The ‘asf_stream’ variant should be selected for streaming. +

+

Note that Windows Media Audio (wma) and Windows Media Video (wmv) use this +muxer too. +

+ +

21.17.1 Options

+
+
packet_size size
+

Set the muxer packet size as a number of bytes. By tuning this setting +you may reduce data fragmentation or muxer overhead depending on your +source. Default value is 3200, minimum is 100, maximum +is 64Ki. +

+
+ + +

21.18 ass

+

ASS/SSA (SubStation Alpha) subtitles muxer. +

+

It accepts a single ASS subtitles stream. +

+ +

21.18.1 Options

+
+
ignore_readorder bool
+

Write dialogue events immediately, even if they are out-of-order, +default is false, otherwise they are cached until the expected +time event is found. +

+
+ + +

21.19 ast

+

AST (Audio Stream) muxer. +

+

This format is used to play audio on some Nintendo Wii games. +

+

It accepts a single audio stream. +

+

The loopstart and loopend options can be used to +define a section of the file to loop for players honoring such +options. +

+ +

21.19.1 Options

+
+
loopstart start
+

Specify loop start position expressesd in milliseconds, from -1 +to INT_MAX, in case -1 is set then no loop is specified +(default -1) and the loopend value is ignored. +

+
+
loopend end
+

Specify loop end position expressed in milliseconds, from 0 to +INT_MAX, default is 0, in case 0 is set it +assumes the total stream duration. +

+
+ + +

21.20 au

+

SUN AU audio muxer. +

+

It accepts a single audio stream. +

+ +

21.21 avi

+

Audio Video Interleaved muxer. +

+

AVI is a proprietary format developed by Microsoft, and later formally specified +through the Open DML specification. +

+

Because of differences in players implementations, it might be required to set +some options to make sure that the generated output can be correctly played by +the target player. +

+ +

21.21.1 Options

+
+
flipped_raw_rgb bool
+

If set to true, store positive height for raw RGB bitmaps, which +indicates bitmap is stored bottom-up. Note that this option does not flip the +bitmap which has to be done manually beforehand, e.g. by using the ‘vflip’ +filter. Default is false and indicates bitmap is stored top down. +

+
+
reserve_index_space size
+

Reserve the specified amount of bytes for the OpenDML master index of each +stream within the file header. By default additional master indexes are +embedded within the data packets if there is no space left in the first master +index and are linked together as a chain of indexes. This index structure can +cause problems for some use cases, e.g. third-party software strictly relying +on the OpenDML index specification or when file seeking is slow. Reserving +enough index space in the file header avoids these problems. +

+

The required index space depends on the output file size and should be about 16 +bytes per gigabyte. When this option is omitted or set to zero the necessary +index space is guessed. +

+

Default value is 0. +

+
+
write_channel_mask bool
+

Write the channel layout mask into the audio stream header. +

+

This option is enabled by default. Disabling the channel mask can be useful in +specific scenarios, e.g. when merging multiple audio streams into one for +compatibility with software that only supports a single audio stream in AVI +(see the "amerge" section in the ffmpeg-filters manual). +

+
+ + +

21.22 avif

+

AV1 (Alliance for Open Media Video codec 1) image format muxer. +

+

This muxers stores images encoded using the AV1 codec. +

+

It accepts one or two video streams. In case two video streams are +provided, the second one shall contain a single plane storing the +alpha mask. +

+

In case more than one image is provided, the generated output is +considered an animated AVIF and the number of loops can be specified +with the loop option. +

+

This is based on the specification by Alliance for Open Media at url +https://aomediacodec.github.io/av1-avif. +

+ +

21.22.1 Options

+
+
loop count
+

number of times to loop an animated AVIF, 0 specify an infinite +loop, default is 0 +

+
+
movie_timescale timescale
+

Set the timescale written in the movie header box (mvhd). +Range is 1 to INT_MAX. Default is 1000. +

+
+ + +

21.23 avm2

+

ShockWave Flash (SWF) / ActionScript Virtual Machine 2 (AVM2) format muxer. +

+

It accepts one audio stream, one video stream, or both. +

+ +

21.24 bit

+

G.729 (.bit) file format muxer. +

+

It accepts a single G.729 audio stream. +

+ +

21.25 caf

+

Apple CAF (Core Audio Format) muxer. +

+

It accepts a single audio stream. +

+ +

21.26 codec2

+

Codec2 audio audio muxer. +

+

It accepts a single codec2 audio stream. +

+ +

21.27 chromaprint

+

Chromaprint fingerprinter muxers. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-chromaprint. +

+

This muxer feeds audio data to the Chromaprint library, which +generates a fingerprint for the provided audio data. See: +https://acoustid.org/chromaprint +

+

It takes a single signed native-endian 16-bit raw audio stream of at +most 2 channels. +

+ +

21.27.1 Options

+
+
algorithm version
+

Select version of algorithm to fingerprint with. Range is 0 to +4. Version 3 enables silence detection. Default is 1. +

+
+
fp_format format
+

Format to output the fingerprint as. Accepts the following options: +

+
‘base64’
+

Base64 compressed fingerprint (default) +

+
+
‘compressed’
+

Binary compressed fingerprint +

+
+
‘raw’
+

Binary raw fingerprint +

+
+ +
+
silence_threshold threshold
+

Threshold for detecting silence. Range is from -1 to +32767, where -1 disables silence detection. Silence +detection can only be used with version 3 of the algorithm. +

+

Silence detection must be disabled for use with the AcoustID +service. Default is -1. +

+
+ + +

21.28 crc

+

CRC (Cyclic Redundancy Check) muxer. +

+

This muxer computes and prints the Adler-32 CRC of all the input audio +and video frames. By default audio frames are converted to signed +16-bit raw audio and video frames to raw video before computing the +CRC. +

+

The output of the muxer consists of a single line of the form: +CRC=0xCRC, where CRC is a hexadecimal number 0-padded to +8 digits containing the CRC for all the decoded input frames. +

+

See also the framecrc muxer. +

+ +

21.28.1 Examples

+
    +
  • Use ffmpeg to compute the CRC of the input, and store it in +the file out.crc: +
    +
    ffmpeg -i INPUT -f crc out.crc
    +
    + +
  • Use ffmpeg to print the CRC to stdout with the command: +
    +
    ffmpeg -i INPUT -f crc -
    +
    + +
  • You can select the output format of each frame with ffmpeg by +specifying the audio and video codec and format. For example, to +compute the CRC of the input audio converted to PCM unsigned 8-bit +and the input video converted to MPEG-2 video, use the command: +
    +
    ffmpeg -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
    +
    +
+ + +

21.29 dash

+

Dynamic Adaptive Streaming over HTTP (DASH) muxer. +

+

This muxer creates segments and manifest files according to the +MPEG-DASH standard ISO/IEC 23009-1:2014 and following standard +updates. +

+

For more information see: +

+ +

This muxer creates an MPD (Media Presentation Description) manifest +file and segment files for each stream. Segment files are placed in +the same directory of the MPD manifest file. +

+

The segment filename might contain pre-defined identifiers used in the +manifest SegmentTemplate section as defined in section +5.3.9.4.4 of the standard. +

+

Available identifiers are $RepresentationID$, $Number$, +$Bandwidth$, and $Time$. In addition to the standard +identifiers, an ffmpeg-specific $ext$ identifier is also +supported. When specified, ffmpeg will replace $ext$ +in the file name with muxing format’s extensions such as mp4, +webm etc. +

+ +

21.29.1 Options

+
+
adaptation_sets adaptation_sets
+

Assign streams to adaptation sets, specified in the MPD manifest +AdaptationSets section. +

+

An adaptation set contains a set of one or more streams accessed as a +single subset, e.g. corresponding streams encoded at different size +selectable by the user depending on the available bandwidth, or to +different audio streams with a different language. +

+

Each adaptation set is specified with the syntax: +

+
id=index,streams=streams
+
+ +

where index must be a numerical index, and streams is a +sequence of ,-separated stream indices. Multiple adaptation +sets can be specified, separated by spaces. +

+

To map all video (or audio) streams to an adaptation set, v (or +a) can be used as stream identifier instead of IDs. +

+

When no assignment is defined, this defaults to an adaptation set for +each stream. +

+

The following optional fields can also be specified: +

+
+
descriptor
+

Define the descriptor as defined by ISO/IEC 23009-1:2014/Amd.2:2015. +

+

For example: +

+
<SupplementalProperty schemeIdUri=\"urn:mpeg:dash:srd:2014\" value=\"0,0,0,1,1,2,2\"/>
+
+ +

The descriptor string should be a self-closing XML tag. +

+
+
frag_duration
+

Override the global fragment duration specified with the +frag_duration option. +

+
+
frag_type
+

Override the global fragment type specified with the +frag_type option. +

+
+
seg_duration
+

Override the global segment duration specified with the +seg_duration option. +

+
+
trick_id
+

Mark an adaptation set as containing streams meant to be used for +Trick Mode for the referenced adaptation set. +

+
+ +

A few examples of possible values for the adaptation_sets +option follow: +

+
id=0,seg_duration=2,frag_duration=1,frag_type=duration,streams=v id=1,seg_duration=2,frag_type=none,streams=a
+
+ +
+
id=0,seg_duration=2,frag_type=none,streams=0 id=1,seg_duration=10,frag_type=none,trick_id=0,streams=1
+
+ +
+
dash_segment_type type
+

Set DASH segment files type. +

+

Possible values: +

+
‘auto’
+

The dash segment files format will be selected based on the stream +codec. This is the default mode. +

+
‘mp4’
+

the dash segment files will be in ISOBMFF/MP4 format +

+
‘webm’
+

the dash segment files will be in WebM format +

+
+ +
+
extra_window_size size
+

Set the maximum number of segments kept outside of the manifest before +removing from disk. +

+
+
format_options options_list
+

Set container format (mp4/webm) options using a :-separated list of +key=value parameters. Values containing : special characters must be +escaped. +

+
+
frag_duration duration
+

Set the length in seconds of fragments within segments, fractional +value can also be set. +

+
+
frag_type type
+

Set the type of interval for fragmentation. +

+

Possible values: +

+
‘auto’
+

set one fragment per segment +

+
+
‘every_frame’
+

fragment at every frame +

+
+
‘duration’
+

fragment at specific time intervals +

+
+
‘pframes’
+

fragment at keyframes and following P-Frame reordering (Video only, +experimental) +

+
+ +
+
global_sidx bool
+

Write global SIDX atom. Applicable only for single file, mp4 +output, non-streaming mode. +

+
+
hls_master_name file_name
+

HLS master playlist name. Default is master.m3u8. +

+
+
hls_playlist bool
+

Generate HLS playlist files. The master playlist is generated with +filename specified by the hls_master_name option. One media +playlist file is generated for each stream with filenames +media_0.m3u8, media_1.m3u8, etc. +

+
+
http_opts http_opts
+

Specify a list of :-separated key=value options to pass to the +underlying HTTP protocol. Applicable only for HTTP output. +

+
+
http_persistent bool
+

Use persistent HTTP connections. Applicable only for HTTP output. +

+
+
http_user_agent user_agent
+

Override User-Agent field in HTTP header. Applicable only for HTTP +output. +

+
+
ignore_io_errors bool
+

Ignore IO errors during open and write. Useful for long-duration runs +with network output. This is disabled by default. +

+
+
index_correction bool
+

Enable or disable segment index correction logic. Applicable only when +use_template is enabled and use_timeline is +disabled. This is disabled by default. +

+

When enabled, the logic monitors the flow of segment indexes. If a +streams’s segment index value is not at the expected real time +position, then the logic corrects that index value. +

+

Typically this logic is needed in live streaming use cases. The +network bandwidth fluctuations are common during long run +streaming. Each fluctuation can cause the segment indexes fall behind +the expected real time position. +

+
+
init_seg_name init_name
+

DASH-templated name to use for the initialization segment. Default is +init-stream$RepresentationID$.$ext$. $ext$ is replaced +with the file name extension specific for the segment format. +

+
+
ldash bool
+

Enable Low-latency Dash by constraining the presence and values of +some elements. This is disabled by default. +

+
+
lhls bool
+

Enable Low-latency HLS (LHLS). Add #EXT-X-PREFETCH tag with +current segment’s URI. hls.js player folks are trying to standardize +an open LHLS spec. The draft spec is available at +https://github.com/video-dev/hlsjs-rfcs/blob/lhls-spec/proposals/0001-lhls.md. +

+

This option tries to comply with the above open spec. It enables +streaming and hls_playlist options automatically. +This is an experimental feature. +

+

Note: This is not Apple’s version LHLS. See +https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis +

+
+
master_m3u8_publish_rate segment_intervals_count
+

Publish master playlist repeatedly every after specified number of +segment intervals. +

+
+
max_playback_rate rate
+

Set the maximum playback rate indicated as appropriate for the +purposes of automatically adjusting playback latency and buffer +occupancy during normal playback by clients. +

+
+
media_seg_name segment_name
+

DASH-templated name to use for the media segments. Default is +chunk-stream$RepresentationID$-$Number%05d$.$ext$. $ext$ +is replaced with the file name extension specific for the segment +format. +

+
+
method method
+

Use the given HTTP method to create output files. Generally set to PUT +or POST. +

+
+
min_playback_rate rate
+

Set the minimum playback rate indicated as appropriate for the +purposes of automatically adjusting playback latency and buffer +occupancy during normal playback by clients. +

+
+
mpd_profile flags
+

Set one or more MPD manifest profiles. +

+

Possible values: +

+
‘dash’
+

MPEG-DASH ISO Base media file format live profile +

+
‘dvb_dash’
+

DVB-DASH profile +

+
+ +

Default value is dash. +

+
+
remove_at_exit bool
+

Enable or disable removal of all segments when finished. This is +disabled by default. +

+
+
seg_duration duration
+

Set the segment length in seconds (fractional value can be set). The +value is treated as average segment duration when the +use_template option is enabled and the use_timeline +option is disabled and as minimum segment duration for all the other +use cases. +

+

Default value is 5. +

+
+
single_file bool
+

Enable or disable storing all segments in one file, accessed using +byte ranges. This is disabled by default. +

+

The name of the single file can be specified with the +single_file_name option, if not specified assume the basename +of the manifest file with the output format extension. +

+
+
single_file_name file_name
+

DASH-templated name to use for the manifest baseURL +element. Imply that the single_file option is set to +true. In the template, $ext$ is replaced with the file +name extension specific for the segment format. +

+
+
streaming bool
+

Enable or disable chunk streaming mode of output. In chunk streaming +mode, each frame will be a moof fragment which forms a +chunk. This is disabled by default. +

+
+
target_latency target_latency
+

Set an intended target latency in seconds for serving (fractional +value can be set). Applicable only when the streaming and +write_prft options are enabled. This is an informative fields +clients can use to measure the latency of the service. +

+
+
timeout timeout
+

Set timeout for socket I/O operations expressed in seconds (fractional +value can be set). Applicable only for HTTP output. +

+
+
update_period period
+

Set the MPD update period, for dynamic content. The unit is +second. If set to 0, the period is automatically computed. +

+

Default value is 0. +

+
+
use_template bool
+

Enable or disable use of SegmentTemplate instead of +SegmentList in the manifest. This is enabled by default. +

+
+
use_timeline bool
+

Enable or disable use of SegmentTimeline within the +SegmentTemplate manifest section. This is enabled by default. +

+
+
utc_timing_url url
+

URL of the page that will return the UTC timestamp in ISO +format, for example https://time.akamai.com/?iso +

+
+
window_size size
+

Set the maximum number of segments kept in the manifest, discard the +oldest one. This is useful for live streaming. +

+

If the value is 0, all segments are kept in the +manifest. Default value is 0. +

+
+
write_prft write_prft
+

Write Producer Reference Time elements on supported streams. This also +enables writing prft boxes in the underlying muxer. Applicable only +when the utc_url option is enabled. It is set to auto by +default, in which case the muxer will attempt to enable it only in +modes that require it. +

+
+ + +

21.29.2 Example

+

Generate a DASH output reading from an input source in realtime using +ffmpeg. +

+

Two multimedia streams are generated from the input file, both +containing a video stream encoded through ‘libx264’, and an audio +stream encoded with ‘libfdk_aac’. The first multimedia stream +contains video with a bitrate of 800k and audio at the default rate, +the second with video scaled to 320x170 pixels at 300k and audio +resampled at 22005 Hz. +

+

The window_size option keeps only the latest 5 segments with +the default duration of 5 seconds. +

+
+
ffmpeg -re -i <input> -map 0 -map 0 -c:a libfdk_aac -c:v libx264 \
+-b:v:0 800k -profile:v:0 main \
+-b:v:1 300k -s:v:1 320x170 -profile:v:1 baseline -ar:a:1 22050 \
+-bf 1 -keyint_min 120 -g 120 -sc_threshold 0 -b_strategy 0 \
+-use_timeline 1 -use_template 1 -window_size 5 \
+-adaptation_sets "id=0,streams=v id=1,streams=a" \
+-f dash /path/to/out.mpd
+
+ + +

21.30 daud

+

D-Cinema audio muxer. +

+

It accepts a single 6-channels audio stream resampled at 96000 Hz +encoded with the ‘pcm_24daud’ codec. +

+ +

21.30.1 Example

+

Use ffmpeg to mux input audio to a ‘5.1’ channel layout +resampled at 96000Hz: +

+
ffmpeg -i INPUT -af aresample=96000,pan=5.1 slow.302
+
+ +

For ffmpeg versions before 7.0 you might have to use the ‘asetnsamples’ +filter to limit the muxed packet size, because this format does not support +muxing packets larger than 65535 bytes (3640 samples). For newer ffmpeg +versions audio is automatically packetized to 36000 byte (2000 sample) packets. +

+ +

21.31 dv

+

DV (Digital Video) muxer. +

+

It accepts exactly one ‘dvvideo’ video stream and at most two +‘pcm_s16’ audio streams. More constraints are defined by the +property of the video, which must correspond to a DV video supported +profile, and on the framerate. +

+ +

21.31.1 Example

+

Use ffmpeg to convert the input: +

+
ffmpeg -i INPUT -s:v 720x480 -pix_fmt yuv411p -r 29.97 -ac 2 -ar 48000 -y out.dv
+
+ + +

21.32 ffmetadata

+

FFmpeg metadata muxer. +

+

This muxer writes the streams metadata in the ‘ffmetadata’ +format. +

+

See the Metadata chapter for +information about the format. +

+ +

21.32.1 Example

+ +

Use ffmpeg to extract metadata from an input file to a metadata.ffmeta +file in ‘ffmetadata’ format: +

+
ffmpeg -i INPUT -f ffmetadata metadata.ffmeta
+
+ + +

21.33 fifo

+

FIFO (First-In First-Out) muxer. +

+

The ‘fifo’ pseudo-muxer allows the separation of encoding and +muxing by using a first-in-first-out queue and running the actual muxer +in a separate thread. +

+

This is especially useful in combination with +the tee muxer and can be used to send data to several +destinations with different reliability/writing speed/latency. +

+

The target muxer is either selected from the output name or specified +through the fifo_format option. +

+

The behavior of the ‘fifo’ muxer if the queue fills up or if the +output fails (e.g. if a packet cannot be written to the output) is +selectable: +

    +
  • Output can be transparently restarted with configurable delay between +retries based on real time or time of the processed stream. + +
  • Encoding can be blocked during temporary failure, or continue transparently +dropping packets in case the FIFO queue fills up. +
+ +

API users should be aware that callback functions +(interrupt_callback, io_open and io_close) used +within its AVFormatContext must be thread-safe. +

+ +

21.33.1 Options

+
+
attempt_recovery bool
+

If failure occurs, attempt to recover the output. This is especially +useful when used with network output, since it makes it possible to +restart streaming transparently. By default this option is set to +false. +

+
+
drop_pkts_on_overflow bool
+

If set to true, in case the fifo queue fills up, packets will +be dropped rather than blocking the encoder. This makes it possible to +continue streaming without delaying the input, at the cost of omitting +part of the stream. By default this option is set to false, so in +such cases the encoder will be blocked until the muxer processes some +of the packets and none of them is lost. +

+
+
fifo_format format_name
+

Specify the format name. Useful if it cannot be guessed from the +output name suffix. +

+
+
format_opts options
+

Specify format options for the underlying muxer. Muxer options can be +specified as a list of key=value pairs separated by ’:’. +

+
+
max_recovery_attempts count
+

Set maximum number of successive unsuccessful recovery attempts after +which the output fails permanently. By default this option is set to +0 (unlimited). +

+
+
queue_size size
+

Specify size of the queue as a number of packets. Default value is +60. +

+
+
recover_any_error bool
+

If set to true, recovery will be attempted regardless of type +of the error causing the failure. By default this option is set to +false and in case of certain (usually permanent) errors the +recovery is not attempted even when the attempt_recovery +option is set to true. +

+
+
recovery_wait_streamtime bool
+

If set to false, the real time is used when waiting for the +recovery attempt (i.e. the recovery will be attempted after the time +specified by the recovery_wait_time option). +

+

If set to true, the time of the processed stream is taken into +account instead (i.e. the recovery will be attempted after discarding +the packets corresponding to the recovery_wait_time option). +

+

By default this option is set to false. +

+
+
recovery_wait_time duration
+

Specify waiting time in seconds before the next recovery attempt after +previous unsuccessful recovery attempt. Default value is 5. +

+
+
restart_with_keyframe bool
+

Specify whether to wait for the keyframe after recovering from +queue overflow or failure. This option is set to false by default. +

+
+
timeshift duration
+

Buffer the specified amount of packets and delay writing the +output. Note that the value of the queue_size option must be +big enough to store the packets for timeshift. At the end of the input +the fifo buffer is flushed at realtime speed. +

+
+ + +

21.33.2 Example

+ +

Use ffmpeg to stream to an RTMP server, continue processing +the stream at real-time rate even in case of temporary failure +(network outage) and attempt to recover streaming every second +indefinitely: +

+
ffmpeg -re -i ... -c:v libx264 -c:a aac -f fifo -fifo_format flv \
+  -drop_pkts_on_overflow 1 -attempt_recovery 1 -recovery_wait_time 1 \
+  -map 0:v -map 0:a rtmp://example.com/live/stream_name
+
+ + +

21.34 film_cpk

+

Sega film (.cpk) muxer. +

+

This format was used as internal format for several Sega games. +

+

For more information regarding the Sega film file format, visit +http://wiki.multimedia.cx/index.php?title=Sega_FILM. +

+

It accepts at maximum one ‘cinepak’ or raw video stream, and at +maximum one audio stream. +

+ +

21.35 filmstrip

+

Adobe Filmstrip muxer. +

+

This format is used by several Adobe tools to store a generated filmstrip export. It +accepts a single raw video stream. +

+ +

21.36 fits

+

Flexible Image Transport System (FITS) muxer. +

+

This image format is used to store astronomical data. +

+

For more information regarding the format, visit +https://fits.gsfc.nasa.gov. +

+ +

21.37 flac

+

Raw FLAC audio muxer. +

+

This muxer accepts exactly one FLAC audio stream. Additionally, it is possible to add +images with disposition ‘attached_pic’. +

+ +

21.37.1 Options

+
+
write_header bool
+

write the file header if set to true, default is true +

+
+ + +

21.37.2 Example

+

Use ffmpeg to store the audio stream from an input file, +together with several pictures used with ‘attached_pic’ +disposition: +

+
ffmpeg -i INPUT -i pic1.png -i pic2.jpg -map 0:a -map 1 -map 2 -disposition:v attached_pic OUTPUT
+
+ + +

21.38 flv

+

Adobe Flash Video Format muxer. +

+ +

21.38.1 Options

+
+
flvflags flags
+

Possible values: +

+
+
‘aac_seq_header_detect’
+

Place AAC sequence header based on audio stream data. +

+
+
‘no_sequence_end’
+

Disable sequence end tag. +

+
+
‘no_metadata’
+

Disable metadata tag. +

+
+
‘no_duration_filesize’
+

Disable duration and filesize in metadata when they are equal to zero +at the end of stream. (Be used to non-seekable living stream). +

+
+
‘add_keyframe_index’
+

Used to facilitate seeking; particularly for HTTP pseudo streaming. +

+
+
+
+ + +

21.39 framecrc

+ +

Per-packet CRC (Cyclic Redundancy Check) testing format. +

+

This muxer computes and prints the Adler-32 CRC for each audio +and video packet. By default audio frames are converted to signed +16-bit raw audio and video frames to raw video before computing the +CRC. +

+

The output of the muxer consists of a line for each audio and video +packet of the form: +

+
stream_index, packet_dts, packet_pts, packet_duration, packet_size, 0xCRC
+
+ +

CRC is a hexadecimal number 0-padded to 8 digits containing the +CRC of the packet. +

+ +

21.39.1 Examples

+ +

For example to compute the CRC of the audio and video frames in +INPUT, converted to raw audio and video packets, and store it +in the file out.crc: +

+
ffmpeg -i INPUT -f framecrc out.crc
+
+ +

To print the information to stdout, use the command: +

+
ffmpeg -i INPUT -f framecrc -
+
+ +

With ffmpeg, you can select the output format to which the +audio and video frames are encoded before computing the CRC for each +packet by specifying the audio and video codec. For example, to +compute the CRC of each decoded input audio frame converted to PCM +unsigned 8-bit and of each decoded input video frame converted to +MPEG-2 video, use the command: +

+
ffmpeg -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc -
+
+ +

See also the crc muxer. +

+ +

21.40 framehash

+ +

Per-packet hash testing format. +

+

This muxer computes and prints a cryptographic hash for each audio +and video packet. This can be used for packet-by-packet equality +checks without having to individually do a binary comparison on each. +

+

By default audio frames are converted to signed 16-bit raw audio and +video frames to raw video before computing the hash, but the output +of explicit conversions to other codecs can also be used. It uses the +SHA-256 cryptographic hash function by default, but supports several +other algorithms. +

+

The output of the muxer consists of a line for each audio and video +packet of the form: +

+
stream_index, packet_dts, packet_pts, packet_duration, packet_size, hash
+
+ +

hash is a hexadecimal number representing the computed hash +for the packet. +

+
+
hash algorithm
+

Use the cryptographic hash function specified by the string algorithm. +Supported values include MD5, murmur3, RIPEMD128, +RIPEMD160, RIPEMD256, RIPEMD320, SHA160, +SHA224, SHA256 (default), SHA512/224, SHA512/256, +SHA384, SHA512, CRC32 and adler32. +

+
+
+ + +

21.40.1 Examples

+ +

To compute the SHA-256 hash of the audio and video frames in INPUT, +converted to raw audio and video packets, and store it in the file +out.sha256: +

+
ffmpeg -i INPUT -f framehash out.sha256
+
+ +

To print the information to stdout, using the MD5 hash function, use +the command: +

+
ffmpeg -i INPUT -f framehash -hash md5 -
+
+ +

See also the hash muxer. +

+ +

21.41 framemd5

+ +

Per-packet MD5 testing format. +

+

This is a variant of the framehash muxer. Unlike that muxer, +it defaults to using the MD5 hash function. +

+ +

21.41.1 Examples

+ +

To compute the MD5 hash of the audio and video frames in INPUT, +converted to raw audio and video packets, and store it in the file +out.md5: +

+
ffmpeg -i INPUT -f framemd5 out.md5
+
+ +

To print the information to stdout, use the command: +

+
ffmpeg -i INPUT -f framemd5 -
+
+ +

See also the framehash and md5 muxers. +

+ +

21.42 gif

+

Animated GIF muxer. +

+

Note that the GIF format has a very large time base: the delay between two frames can +therefore not be smaller than one centi second. +

+ +

21.42.1 Options

+
+
loop bool
+

Set the number of times to loop the output. Use -1 for no loop, 0 +for looping indefinitely (default). +

+
+
final_delay delay
+

Force the delay (expressed in centiseconds) after the last frame. Each frame +ends with a delay until the next frame. The default is -1, which is a +special value to tell the muxer to reuse the previous delay. In case of a +loop, you might want to customize this value to mark a pause for instance. +

+
+ + +

21.42.2 Example

+

Encode a gif looping 10 times, with a 5 seconds delay between +the loops: +

+
ffmpeg -i INPUT -loop 10 -final_delay 500 out.gif
+
+ +

Note 1: if you wish to extract the frames into separate GIF files, you need to +force the image2 muxer: +

+
ffmpeg -i INPUT -c:v gif -f image2 "out%d.gif"
+
+ + +

21.43 gxf

+

General eXchange Format (GXF) muxer. +

+

GXF was developed by Grass Valley Group, then standardized by SMPTE as SMPTE +360M and was extended in SMPTE RDD 14-2007 to include high-definition video +resolutions. +

+

It accepts at most one video stream with codec ‘mjpeg’, or +‘mpeg1video’, or ‘mpeg2video’, or ‘dvvideo’ with resolution +‘512x480’ or ‘608x576’, and several audio streams with rate 48000Hz +and codec ‘pcm16_le’. +

+ +

21.44 hash

+ +

Hash testing format. +

+

This muxer computes and prints a cryptographic hash of all the input +audio and video frames. This can be used for equality checks without +having to do a complete binary comparison. +

+

By default audio frames are converted to signed 16-bit raw audio and +video frames to raw video before computing the hash, but the output +of explicit conversions to other codecs can also be used. Timestamps +are ignored. It uses the SHA-256 cryptographic hash function by default, +but supports several other algorithms. +

+

The output of the muxer consists of a single line of the form: +algo=hash, where algo is a short string representing +the hash function used, and hash is a hexadecimal number +representing the computed hash. +

+
+
hash algorithm
+

Use the cryptographic hash function specified by the string algorithm. +Supported values include MD5, murmur3, RIPEMD128, +RIPEMD160, RIPEMD256, RIPEMD320, SHA160, +SHA224, SHA256 (default), SHA512/224, SHA512/256, +SHA384, SHA512, CRC32 and adler32. +

+
+
+ + +

21.44.1 Examples

+ +

To compute the SHA-256 hash of the input converted to raw audio and +video, and store it in the file out.sha256: +

+
ffmpeg -i INPUT -f hash out.sha256
+
+ +

To print an MD5 hash to stdout use the command: +

+
ffmpeg -i INPUT -f hash -hash md5 -
+
+ +

See also the framehash muxer. +

+ +

21.45 hds

+

HTTP Dynamic Streaming (HDS) muxer. +

+

HTTP dynamic streaming, or HDS, is an adaptive bitrate streaming method +developed by Adobe. HDS delivers MP4 video content over HTTP connections. HDS +can be used for on-demand streaming or live streaming. +

+

This muxer creates an .f4m (Adobe Flash Media Manifest File) manifest, an .abst +(Adobe Bootstrap File) for each stream, and segment files in a directory +specified as the output. +

+

These needs to be accessed by an HDS player through HTTPS for it to be able to +perform playback on the generated stream. +

+ +

21.45.1 Options

+
+
extra_window_size int
+

number of fragments kept outside of the manifest before removing from disk +

+
+
min_frag_duration microseconds
+

minimum fragment duration (in microseconds), default value is 1 second +(10000000) +

+
+
remove_at_exit bool
+

remove all fragments when finished when set to true +

+
+
window_size int
+

number of fragments kept in the manifest, if set to a value different from +0. By default all segments are kept in the output directory. +

+
+ + +

21.45.2 Example

+

Use ffmpeg to generate HDS files to the output.hds directory in +real-time rate: +

+
ffmpeg -re -i INPUT -f hds -b:v 200k output.hds
+
+ + +

21.46 hls

+ +

Apple HTTP Live Streaming muxer that segments MPEG-TS according to +the HTTP Live Streaming (HLS) specification. +

+

It creates a playlist file, and one or more segment files. The output filename +specifies the playlist filename. +

+

By default, the muxer creates a file for each segment produced. These files +have the same name as the playlist, followed by a sequential number and a +.ts extension. +

+

Make sure to require a closed GOP when encoding and to set the GOP +size to fit your segment time constraint. +

+

For example, to convert an input file with ffmpeg: +

+
ffmpeg -i in.mkv -c:v h264 -flags +cgop -g 30 -hls_time 1 out.m3u8
+
+

This example will produce the playlist, out.m3u8, and segment files: +out0.ts, out1.ts, out2.ts, etc. +

+

See also the segment muxer, which provides a more generic and +flexible implementation of a segmenter, and can be used to perform HLS +segmentation. +

+ +

21.46.1 Options

+
+
hls_init_time duration
+

Set the initial target segment length. Default value is 0. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

Segment will be cut on the next key frame after this time has passed on the +first m3u8 list. After the initial playlist is filled, ffmpeg will cut +segments at duration equal to hls_time. +

+
+
hls_time duration
+

Set the target segment length. Default value is 2. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +Segment will be cut on the next key frame after this time has passed. +

+
+
hls_list_size size
+

Set the maximum number of playlist entries. If set to 0 the list file +will contain all the segments. Default value is 5. +

+
+
hls_delete_threshold size
+

Set the number of unreferenced segments to keep on disk before hls_flags delete_segments +deletes them. Increase this to allow continue clients to download segments which +were recently referenced in the playlist. Default value is 1, meaning segments older than +hls_list_size+1 will be deleted. +

+
+
hls_start_number_source source
+

Start the playlist sequence number (#EXT-X-MEDIA-SEQUENCE) according to the specified source. +Unless hls_flags single_file is set, it also specifies source of starting sequence numbers of +segment and subtitle filenames. In any case, if hls_flags append_list +is set and read playlist sequence number is greater than the specified start sequence number, +then that value will be used as start value. +

+

It accepts the following values: +

+
+
generic (default)
+

Set the start numbers according to the start_number option value. +

+
+
epoch
+

Set the start number as the seconds since epoch (1970-01-01 00:00:00). +

+
+
epoch_us
+

Set the start number as the microseconds since epoch (1970-01-01 00:00:00). +

+
+
datetime
+

Set the start number based on the current date/time as YYYYmmddHHMMSS. e.g. 20161231235759. +

+
+ +
+
start_number number
+

Start the playlist sequence number (#EXT-X-MEDIA-SEQUENCE) from the specified number +when hls_start_number_source value is generic. (This is the default case.) +Unless hls_flags single_file is set, it also specifies starting sequence numbers of segment and subtitle filenames. +Default value is 0. +

+
+
hls_allow_cache bool
+

Explicitly set whether the client MAY (1) or MUST NOT (0) cache media segments. +

+
+
hls_base_url baseurl
+

Append baseurl to every entry in the playlist. +Useful to generate playlists with absolute paths. +

+

Note that the playlist sequence number must be unique for each segment +and it is not to be confused with the segment filename sequence number +which can be cyclic, for example if the wrap option is +specified. +

+
+
hls_segment_filename filename
+

Set the segment filename. Unless the hls_flags option is set with +‘single_file’, filename is used as a string format with the +segment number appended. +

+

For example: +

+
ffmpeg -i in.nut -hls_segment_filename 'file%03d.ts' out.m3u8
+
+ +

will produce the playlist, out.m3u8, and segment files: +file000.ts, file001.ts, file002.ts, etc. +

+

filename may contain a full path or relative path specification, +but only the file name part without any path will be contained in the m3u8 segment list. +Should a relative path be specified, the path of the created segment +files will be relative to the current working directory. +When strftime_mkdir is set, the whole expanded value of filename will be written into the m3u8 segment list. +

+

When var_stream_map is set with two or more variant streams, the +filename pattern must contain the string "%v", and this string will be +expanded to the position of variant stream index in the generated segment file +names. +

+

For example: +

+
ffmpeg -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
+  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
+  -hls_segment_filename 'file_%v_%03d.ts' out_%v.m3u8
+
+ +

will produce the playlists segment file sets: +file_0_000.ts, file_0_001.ts, file_0_002.ts, etc. and +file_1_000.ts, file_1_001.ts, file_1_002.ts, etc. +

+

The string "%v" may be present in the filename or in the last directory name +containing the file, but only in one of them. (Additionally, %v may appear multiple times in the last +sub-directory or filename.) If the string %v is present in the directory name, then +sub-directories are created after expanding the directory name pattern. This +enables creation of segments corresponding to different variant streams in +subdirectories. +

+

For example: +

+
ffmpeg -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
+  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
+  -hls_segment_filename 'vs%v/file_%03d.ts' vs%v/out.m3u8
+
+

will produce the playlists segment file sets: +vs0/file_000.ts, vs0/file_001.ts, vs0/file_002.ts, etc. and +vs1/file_000.ts, vs1/file_001.ts, vs1/file_002.ts, etc. +

+
+
strftime bool
+

Use strftime() on filename to expand the segment filename with +localtime. The segment number is also available in this mode, but to use it, +you need to set ‘second_level_segment_index’ in the hls_flag and +%%d will be the specifier. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -hls_segment_filename 'file-%Y%m%d-%s.ts' out.m3u8
+
+

will produce the playlist, out.m3u8, and segment files: +file-20160215-1455569023.ts, file-20160215-1455569024.ts, etc. +Note: On some systems/environments, the %s specifier is not +available. See strftime() documentation. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -hls_flags second_level_segment_index -hls_segment_filename 'file-%Y%m%d-%%04d.ts' out.m3u8
+
+

will produce the playlist, out.m3u8, and segment files: +file-20160215-0001.ts, file-20160215-0002.ts, etc. +

+
+
strftime_mkdir bool
+

Used together with strftime, it will create all subdirectories which +are present in the expanded values of option hls_segment_filename. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -strftime_mkdir 1 -hls_segment_filename '%Y%m%d/file-%Y%m%d-%s.ts' out.m3u8
+
+

will create a directory 201560215 (if it does not exist), and then +produce the playlist, out.m3u8, and segment files: +20160215/file-20160215-1455569023.ts, +20160215/file-20160215-1455569024.ts, etc. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -strftime_mkdir 1 -hls_segment_filename '%Y/%m/%d/file-%Y%m%d-%s.ts' out.m3u8
+
+

will create a directory hierarchy 2016/02/15 (if any of them do not +exist), and then produce the playlist, out.m3u8, and segment files: +2016/02/15/file-20160215-1455569023.ts, +2016/02/15/file-20160215-1455569024.ts, etc. +

+
+
hls_segment_options options_list
+

Set output format options using a :-separated list of key=value +parameters. Values containing : special characters must be +escaped. +

+
+
hls_key_info_file key_info_file
+

Use the information in key_info_file for segment encryption. The first +line of key_info_file specifies the key URI written to the playlist. The +key URL is used to access the encryption key during playback. The second line +specifies the path to the key file used to obtain the key during the encryption +process. The key file is read as a single packed array of 16 octets in binary +format. The optional third line specifies the initialization vector (IV) as a +hexadecimal string to be used instead of the segment sequence number (default) +for encryption. Changes to key_info_file will result in segment +encryption with the new key/IV and an entry in the playlist for the new key +URI/IV if hls_flags periodic_rekey is enabled. +

+

Key info file format: +

+
key URI
+key file path
+IV (optional)
+
+ +

Example key URIs: +

+
http://server/file.key
+/path/to/file.key
+file.key
+
+ +

Example key file paths: +

+
file.key
+/path/to/file.key
+
+ +

Example IV: +

+
0123456789ABCDEF0123456789ABCDEF
+
+ +

Key info file example: +

+
http://server/file.key
+/path/to/file.key
+0123456789ABCDEF0123456789ABCDEF
+
+ +

Example shell script: +

+
#!/bin/sh
+BASE_URL=${1:-'.'}
+openssl rand 16 > file.key
+echo $BASE_URL/file.key > file.keyinfo
+echo file.key >> file.keyinfo
+echo $(openssl rand -hex 16) >> file.keyinfo
+ffmpeg -f lavfi -re -i testsrc -c:v h264 -hls_flags delete_segments \
+  -hls_key_info_file file.keyinfo out.m3u8
+
+ +
+
hls_enc bool
+

Enable (1) or disable (0) the AES128 encryption. +When enabled every segment generated is encrypted and the encryption key +is saved as playlist name.key. +

+
+
hls_enc_key key
+

Specify a 16-octet key to encrypt the segments, by default it is randomly +generated. +

+
+
hls_enc_key_url keyurl
+

If set, keyurl is prepended instead of baseurl to the key filename +in the playlist. +

+
+
hls_enc_iv iv
+

Specify the 16-octet initialization vector for every segment instead of the +autogenerated ones. +

+
+
hls_segment_type flags
+

Possible values: +

+
+
‘mpegts’
+

Output segment files in MPEG-2 Transport Stream format. This is +compatible with all HLS versions. +

+
+
‘fmp4’
+

Output segment files in fragmented MP4 format, similar to MPEG-DASH. +fmp4 files may be used in HLS version 7 and above. +

+
+ +
+
hls_fmp4_init_filename filename
+

Set filename for the fragment files header file, default filename is init.mp4. +

+

When strftime is enabled, filename is expanded to the segment filename with localtime. +

+

For example: +

+
ffmpeg -i in.nut -hls_segment_type fmp4 -strftime 1 -hls_fmp4_init_filename "%s_init.mp4" out.m3u8
+
+

will produce init like this 1602678741_init.mp4. +

+
+
hls_fmp4_init_resend bool
+

Resend init file after m3u8 file refresh every time, default is 0. +

+

When var_stream_map is set with two or more variant streams, the +filename pattern must contain the string "%v", this string specifies +the position of variant stream index in the generated init file names. +The string "%v" may be present in the filename or in the last directory name +containing the file. If the string is present in the directory name, then +sub-directories are created after expanding the directory name pattern. This +enables creation of init files corresponding to different variant streams in +subdirectories. +

+
+
hls_flags flags
+

Possible values: +

+
+
‘single_file’
+

If this flag is set, the muxer will store all segments in a single MPEG-TS +file, and will use byte ranges in the playlist. HLS playlists generated with +this way will have the version number 4. +

+

For example: +

+
ffmpeg -i in.nut -hls_flags single_file out.m3u8
+
+

will produce the playlist, out.m3u8, and a single segment file, +out.ts. +

+
+
‘delete_segments’
+

Segment files removed from the playlist are deleted after a period of time +equal to the duration of the segment plus the duration of the playlist. +

+
+
‘append_list’
+

Append new segments into the end of old segment list, +and remove the #EXT-X-ENDLIST from the old segment list. +

+
+
‘round_durations’
+

Round the duration info in the playlist file segment info to integer +values, instead of using floating point. +If there are no other features requiring higher HLS versions be used, +then this will allow ffmpeg to output a HLS version 2 m3u8. +

+
+
‘discont_start’
+

Add the #EXT-X-DISCONTINUITY tag to the playlist, before the +first segment’s information. +

+
+
‘omit_endlist’
+

Do not append the EXT-X-ENDLIST tag at the end of the playlist. +

+
+
‘periodic_rekey’
+

The file specified by hls_key_info_file will be checked periodically and +detect updates to the encryption info. Be sure to replace this file atomically, +including the file containing the AES encryption key. +

+
+
‘independent_segments’
+

Add the #EXT-X-INDEPENDENT-SEGMENTS tag to playlists that has video segments +and when all the segments of that playlist are guaranteed to start with a key frame. +

+
+
‘iframes_only’
+

Add the #EXT-X-I-FRAMES-ONLY tag to playlists that has video segments +and can play only I-frames in the #EXT-X-BYTERANGE mode. +

+
+
‘split_by_time’
+

Allow segments to start on frames other than key frames. This improves +behavior on some players when the time between key frames is inconsistent, +but may make things worse on others, and can cause some oddities during +seeking. This flag should be used with the hls_time option. +

+
+
‘program_date_time’
+

Generate EXT-X-PROGRAM-DATE-TIME tags. +

+
+
‘second_level_segment_index’
+

Make it possible to use segment indexes as %%d in the +hls_segment_filename option expression besides date/time values when +strftime option is on. To get fixed width numbers with trailing zeroes, %%0xd format +is available where x is the required width. +

+
+
‘second_level_segment_size’
+

Make it possible to use segment sizes (counted in bytes) as %%s in +hls_segment_filename option expression besides date/time values when +strftime is on. To get fixed width numbers with trailing zeroes, %%0xs format +is available where x is the required width. +

+
+
‘second_level_segment_duration’
+

Make it possible to use segment duration (calculated in microseconds) as %%t in +hls_segment_filename option expression besides date/time values when +strftime is on. To get fixed width numbers with trailing zeroes, %%0xt format +is available where x is the required width. +

+

For example: +

+
ffmpeg -i sample.mpeg \
+   -f hls -hls_time 3 -hls_list_size 5 \
+   -hls_flags second_level_segment_index+second_level_segment_size+second_level_segment_duration \
+   -strftime 1 -strftime_mkdir 1 -hls_segment_filename "segment_%Y%m%d%H%M%S_%%04d_%%08s_%%013t.ts" stream.m3u8
+
+

will produce segments like this: +segment_20170102194334_0003_00122200_0000003000000.ts, segment_20170102194334_0004_00120072_0000003000000.ts etc. +

+
+
‘temp_file’
+

Write segment data to filename.tmp and rename to filename only once the +segment is complete. +

+

A webserver serving up segments can be configured to reject requests to *.tmp to +prevent access to in-progress segments before they have been added to the m3u8 +playlist. +

+

This flag also affects how m3u8 playlist files are created. If this flag is set, +all playlist files will be written into a temporary file and renamed after they +are complete, similarly as segments are handled. But playlists with file +protocol and with hls_playlist_type type other than ‘vod’ are +always written into a temporary file regardless of this flag. +

+

Master playlist files specified with master_pl_name, if any, with +file protocol, are always written into temporary file regardless of this +flag if master_pl_publish_rate value is other than zero. +

+
+ +
+
hls_playlist_type type
+

If type is ‘event’, emit #EXT-X-PLAYLIST-TYPE:EVENT in the m3u8 +header. This forces hls_list_size to 0; the playlist can only be +appended to. +

+

If type is ‘vod’, emit #EXT-X-PLAYLIST-TYPE:VOD in the m3u8 +header. This forces hls_list_size to 0; the playlist must not change. +

+
+
method method
+

Use the given HTTP method to create the hls files. +

+

For example: +

+
ffmpeg -re -i in.ts -f hls -method PUT http://example.com/live/out.m3u8
+
+

will upload all the mpegts segment files to the HTTP server using the HTTP PUT +method, and update the m3u8 files every refresh times using the same +method. Note that the HTTP server must support the given method for uploading +files. +

+
+
http_user_agent agent
+

Override User-Agent field in HTTP header. Applicable only for HTTP output. +

+
+
var_stream_map stream_map
+

Specify a map string defining how to group the audio, video and subtitle streams +into different variant streams. The variant stream groups are separated by +space. +

+

Expected string format is like this "a:0,v:0 a:1,v:1 ....". Here a:, v:, s: are +the keys to specify audio, video and subtitle streams respectively. +Allowed values are 0 to 9 (limited just based on practical usage). +

+

When there are two or more variant streams, the output filename pattern must +contain the string "%v": this string specifies the position of variant stream +index in the output media playlist filenames. The string "%v" may be present in +the filename or in the last directory name containing the file. If the string is +present in the directory name, then sub-directories are created after expanding +the directory name pattern. This enables creation of variant streams in +subdirectories. +

+

A few examples follow. +

+
    +
  • Create two hls variant streams. The first variant stream will contain video +stream of bitrate 1000k and audio stream of bitrate 64k and the second variant +stream will contain video stream of bitrate 256k and audio stream of bitrate +32k. Here, two media playlist with file names out_0.m3u8 and +out_1.m3u8 will be created. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
    +  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • If you want something meaningful text instead of indexes in result names, you +may specify names for each or some of the variants. The following example will +create two hls variant streams as in the previous one. But here, the two media +playlist with file names out_my_hd.m3u8 and out_my_sd.m3u8 will be +created. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
    +  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0,name:my_hd v:1,a:1,name:my_sd" \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create three hls variant streams. The first variant stream will be a video only +stream with video bitrate 1000k, the second variant stream will be an audio only +stream with bitrate 64k and the third variant stream will be a video only stream +with bitrate 256k. Here, three media playlist with file names out_0.m3u8, +out_1.m3u8 and out_2.m3u8 will be created. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k \
    +  -map 0:v -map 0:a -map 0:v -f hls -var_stream_map "v:0 a:0 v:1" \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create the variant streams in subdirectories. Here, the first media playlist is +created at http://example.com/live/vs_0/out.m3u8 and the second one at +http://example.com/live/vs_1/out.m3u8. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
    +  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
    +  http://example.com/live/vs_%v/out.m3u8
    +
    + +
  • Create two audio only and two video only variant streams. In addition to the +#EXT-X-STREAM-INF tag for each variant stream in the master playlist, the +#EXT-X-MEDIA tag is also added for the two audio only variant streams and +they are mapped to the two video only variant streams with audio group names +’aud_low’ and ’aud_high’. +By default, a single hls variant containing all the encoded streams is created. +
    +
    ffmpeg -re -i in.ts -b:a:0 32k -b:a:1 64k -b:v:0 1000k -b:v:1 3000k  \
    +  -map 0:a -map 0:a -map 0:v -map 0:v -f hls \
    +  -var_stream_map "a:0,agroup:aud_low a:1,agroup:aud_high v:0,agroup:aud_low v:1,agroup:aud_high" \
    +  -master_pl_name master.m3u8 \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • +Create two audio only and one video only variant streams. In addition to the +#EXT-X-STREAM-INF tag for each variant stream in the master playlist, the +#EXT-X-MEDIA tag is also added for the two audio only variant streams and +they are mapped to the one video only variant streams with audio group name +’aud_low’, and the audio group have default stat is NO or YES. +By default, a single hls variant containing all the encoded streams is created. +
    +
    ffmpeg -re -i in.ts -b:a:0 32k -b:a:1 64k -b:v:0 1000k \
    +  -map 0:a -map 0:a -map 0:v -f hls \
    +  -var_stream_map "a:0,agroup:aud_low,default:yes a:1,agroup:aud_low v:0,agroup:aud_low" \
    +  -master_pl_name master.m3u8 \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create two audio only and one video only variant streams. In addition to the +#EXT-X-STREAM-INF tag for each variant stream in the master playlist, the +#EXT-X-MEDIA tag is also added for the two audio only variant streams and +they are mapped to the one video only variant streams with audio group name +’aud_low’, and the audio group have default stat is NO or YES, and one audio +have and language is named ENG, the other audio language is named CHN. By +default, a single hls variant containing all the encoded streams is created. +
    +
    ffmpeg -re -i in.ts -b:a:0 32k -b:a:1 64k -b:v:0 1000k \
    +  -map 0:a -map 0:a -map 0:v -f hls \
    +  -var_stream_map "a:0,agroup:aud_low,default:yes,language:ENG a:1,agroup:aud_low,language:CHN v:0,agroup:aud_low" \
    +  -master_pl_name master.m3u8 \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create a single variant stream. Add the #EXT-X-MEDIA tag with +TYPE=SUBTITLES in the master playlist with webvtt subtitle group name +’subtitle’ and optional subtitle name, e.g. ’English’. Make sure the input +file has one text subtitle stream at least. +
    +
    ffmpeg -y -i input_with_subtitle.mkv \
    + -b:v:0 5250k -c:v h264 -pix_fmt yuv420p -profile:v main -level 4.1 \
    + -b:a:0 256k \
    + -c:s webvtt -c:a mp2 -ar 48000 -ac 2 -map 0:v -map 0:a:0 -map 0:s:0 \
    + -f hls -var_stream_map "v:0,a:0,s:0,sgroup:subtitle,sname:English" \
    + -master_pl_name master.m3u8 -t 300 -hls_time 10 -hls_init_time 4 -hls_list_size \
    + 10 -master_pl_publish_rate 10 -hls_flags \
    + delete_segments+discont_start+split_by_time ./tmp/video.m3u8
    +
    +
+ +
+
cc_stream_map cc_stream_map
+

Map string which specifies different closed captions groups and their +attributes. The closed captions stream groups are separated by space. +

+

Expected string format is like this +"ccgroup:<group name>,instreamid:<INSTREAM-ID>,language:<language code> ....". +’ccgroup’ and ’instreamid’ are mandatory attributes. ’language’ is an optional +attribute. +

+

The closed captions groups configured using this option are mapped to different +variant streams by providing the same ’ccgroup’ name in the +var_stream_map string. +

+

For example: +

+
ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
+  -a53cc:0 1 -a53cc:1 1 \
+  -map 0:v -map 0:a -map 0:v -map 0:a -f hls \
+  -cc_stream_map "ccgroup:cc,instreamid:CC1,language:en ccgroup:cc,instreamid:CC2,language:sp" \
+  -var_stream_map "v:0,a:0,ccgroup:cc v:1,a:1,ccgroup:cc" \
+  -master_pl_name master.m3u8 \
+  http://example.com/live/out_%v.m3u8
+
+

will add two #EXT-X-MEDIA tags with TYPE=CLOSED-CAPTIONS in the +master playlist for the INSTREAM-IDs ’CC1’ and ’CC2’. Also, it will add +CLOSED-CAPTIONS attribute with group name ’cc’ for the two output variant +streams. +

+

If var_stream_map is not set, then the first available ccgroup in +cc_stream_map is mapped to the output variant stream. +

+

For example: +

+
ffmpeg -re -i in.ts -b:v 1000k -b:a 64k -a53cc 1 -f hls \
+  -cc_stream_map "ccgroup:cc,instreamid:CC1,language:en" \
+  -master_pl_name master.m3u8 \
+  http://example.com/live/out.m3u8
+
+

this will add #EXT-X-MEDIA tag with TYPE=CLOSED-CAPTIONS in the +master playlist with group name ’cc’, language ’en’ (english) and INSTREAM-ID +’CC1’. Also, it will add CLOSED-CAPTIONS attribute with group name ’cc’ +for the output variant stream. +

+
+
master_pl_name name
+

Create HLS master playlist with the given name. +

+

For example: +

+
ffmpeg -re -i in.ts -f hls -master_pl_name master.m3u8 http://example.com/live/out.m3u8
+
+

creates an HLS master playlist with name master.m3u8 which is published +at http://example.com/live/. +

+
+
master_pl_publish_rate count
+

Publish master play list repeatedly every after specified number of segment intervals. +

+

For example: +

+
ffmpeg -re -i in.ts -f hls -master_pl_name master.m3u8 \
+-hls_time 2 -master_pl_publish_rate 30 http://example.com/live/out.m3u8
+
+

creates an HLS master playlist with name master.m3u8 and keeps +publishing it repeatedly every after 30 segments i.e. every after 60s. +

+
+
http_persistent bool
+

Use persistent HTTP connections. Applicable only for HTTP output. +

+
+
timeout timeout
+

Set timeout for socket I/O operations. Applicable only for HTTP output. +

+
+
ignore_io_errors bool
+

Ignore IO errors during open, write and delete. Useful for long-duration runs with network output. +

+
+
headers headers
+

Set custom HTTP headers, can override built in default headers. Applicable only for HTTP output. +

+
+ + +

21.47 iamf

+

Immersive Audio Model and Formats (IAMF) muxer. +

+

IAMF is used to provide immersive audio content for presentation on a wide range +of devices in both streaming and offline applications. These applications +include internet audio streaming, multicasting/broadcasting services, file +download, gaming, communication, virtual and augmented reality, and others. In +these applications, audio may be played back on a wide range of devices, e.g., +headphones, mobile phones, tablets, TVs, sound bars, home theater systems, and +big screens. +

+

This format was promoted and designed by Alliance for Open Media. +

+

For more information about this format, see https://aomedia.org/iamf/. +

+ +

21.48 ico

+ +

ICO file muxer. +

+

Microsoft’s icon file format (ICO) has some strict limitations that should be noted: +

+
    +
  • Size cannot exceed 256 pixels in any dimension + +
  • Only BMP and PNG images can be stored + +
  • If a BMP image is used, it must be one of the following pixel formats: +
    +
    BMP Bit Depth      FFmpeg Pixel Format
    +1bit               pal8
    +4bit               pal8
    +8bit               pal8
    +16bit              rgb555le
    +24bit              bgr24
    +32bit              bgra
    +
    + +
  • If a BMP image is used, it must use the BITMAPINFOHEADER DIB header + +
  • If a PNG image is used, it must use the rgba pixel format +
+ + +

21.49 ilbc

+

Internet Low Bitrate Codec (iLBC) raw muxer. +

+

It accepts a single ‘ilbc’ audio stream. +

+ +

21.50 image2, image2pipe

+

Image file muxer. +

+

The ‘image2’ muxer writes video frames to image files. +

+

The output filenames are specified by a pattern, which can be used to +produce sequentially numbered series of files. +The pattern may contain the string "%d" or "%0Nd", this string +specifies the position of the characters representing a numbering in +the filenames. If the form "%0Nd" is used, the string +representing the number in each filename is 0-padded to N +digits. The literal character ’%’ can be specified in the pattern with +the string "%%". +

+

If the pattern contains "%d" or "%0Nd", the first filename of +the file list specified will contain the number 1, all the following +numbers will be sequential. +

+

The pattern may contain a suffix which is used to automatically +determine the format of the image files to write. +

+

For example the pattern "img-%03d.bmp" will specify a sequence of +filenames of the form img-001.bmp, img-002.bmp, ..., +img-010.bmp, etc. +The pattern "img%%-%d.jpg" will specify a sequence of filenames of the +form img%-1.jpg, img%-2.jpg, ..., img%-10.jpg, +etc. +

+

The image muxer supports the .Y.U.V image file format. This format is +special in that each image frame consists of three files, for +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. +

+

The ‘image2pipe’ muxer accepts the same options as the ‘image2’ muxer, +but ignores the pattern verification and expansion, as it is supposed to write +to the command output rather than to an actual stored file. +

+ +

21.50.1 Options

+
+
frame_pts bool
+

If set to 1, expand the filename with the packet PTS (presentation time stamp). +Default value is 0. +

+
+
start_number count
+

Start the sequence from the specified number. Default value is 1. +

+
+
update bool
+

If set to 1, the filename will always be interpreted as just a +filename, not a pattern, and the corresponding file will be continuously +overwritten with new images. Default value is 0. +

+
+
strftime bool
+

If set to 1, expand the filename with date and time information from +strftime(). Default value is 0. +

+
+
atomic_writing bool
+

Write output to a temporary file, which is renamed to target filename once +writing is completed. Default is disabled. +

+
+
protocol_opts options_list
+

Set protocol options as a :-separated list of key=value parameters. Values +containing the : special character must be escaped. +

+
+ + +

21.50.2 Examples

+
    +
  • Use ffmpeg for creating a sequence of files img-001.jpeg, +img-002.jpeg, ..., taking one image every second from the input video: +
    +
    ffmpeg -i in.avi -vsync cfr -r 1 -f image2 'img-%03d.jpeg'
    +
    + +

    Note that with ffmpeg, if the format is not specified with the +-f option and the output filename specifies an image file +format, the image2 muxer is automatically selected, so the previous +command can be written as: +

    +
    ffmpeg -i in.avi -vsync cfr -r 1 'img-%03d.jpeg'
    +
    + +

    Note also that the pattern must not necessarily contain "%d" or +"%0Nd", for example to create a single image file +img.jpeg from the start of the input video you can employ the command: +

    +
    ffmpeg -i in.avi -f image2 -frames:v 1 img.jpeg
    +
    + +
  • The strftime option allows you to expand the filename with +date and time information. Check the documentation of +the strftime() function for the syntax. + +

    To generate image files from the strftime() "%Y-%m-%d_%H-%M-%S" pattern, +the following ffmpeg command can be used: +

    +
    ffmpeg -f v4l2 -r 1 -i /dev/video0 -f image2 -strftime 1 "%Y-%m-%d_%H-%M-%S.jpg"
    +
    + +
  • Set the file name with current frame’s PTS: +
    +
    ffmpeg -f v4l2 -r 1 -i /dev/video0 -copyts -f image2 -frame_pts true %d.jpg
    +
    + +
  • Publish contents of your desktop directly to a WebDAV server every second: +
    +
    ffmpeg -f x11grab -framerate 1 -i :0.0 -q:v 6 -update 1 -protocol_opts method=PUT http://example.com/desktop.jpg
    +
    +
+ + +

21.51 ircam

+

Berkeley / IRCAM / CARL Sound Filesystem (BICSF) format muxer. +

+

The Berkeley/IRCAM/CARL Sound Format, developed in the 1980s, is a result of the +merging of several different earlier sound file formats and systems including +the csound system developed by Dr Gareth Loy at the Computer Audio Research Lab +(CARL) at UC San Diego, the IRCAM sound file system developed by Rob Gross and +Dan Timis at the Institut de Recherche et Coordination Acoustique / Musique in +Paris and the Berkeley Fast Filesystem. +

+

It was developed initially as part of the Berkeley/IRCAM/CARL Sound Filesystem, +a suite of programs designed to implement a filesystem for audio applications +running under Berkeley UNIX. It was particularly popular in academic music +research centres, and was used a number of times in the creation of early +computer-generated compositions. +

+

This muxer accepts a single audio stream containing PCM data. +

+ +

21.52 ivf

+

On2 IVF muxer. +

+

IVF was developed by On2 Technologies (formerly known as Duck +Corporation), to store internally developed codecs. +

+

This muxer accepts a single ‘vp8’, ‘vp9’, or ‘av1’ +video stream. +

+ +

21.53 jacosub

+

JACOsub subtitle format muxer. +

+

This muxer accepts a single ‘jacosub’ subtitles stream. +

+

For more information about the format, see +http://unicorn.us.com/jacosub/jscripts.html. +

+ +

21.54 kvag

+

Simon & Schuster Interactive VAG muxer. +

+

This custom VAG container is used by some Simon & Schuster Interactive +games such as "Real War", and "Real War: Rogue States". +

+

This muxer accepts a single ‘adpcm_ima_ssi’ audio stream. +

+ +

21.55 lc3

+

Bluetooth SIG Low Complexity Communication Codec audio (LC3), or +ETSI TS 103 634 Low Complexity Communication Codec plus (LC3plus). +

+

This muxer accepts a single ‘lc3’ audio stream. +

+ +

21.56 lrc

+

LRC lyrics file format muxer. +

+

LRC (short for LyRiCs) is a computer file format that synchronizes +song lyrics with an audio file, such as MP3, Vorbis, or MIDI. +

+

This muxer accepts a single ‘subrip’ or ‘text’ subtitles stream. +

+ +

21.56.1 Metadata

+

The following metadata tags are converted to the format corresponding +metadata: +

+
+
title
+
album
+
artist
+
author
+
creator
+
encoder
+
encoder_version
+
+ +

If ‘encoder_version’ is not explicitly set, it is automatically +set to the libavformat version. +

+ +

21.57 matroska

+

Matroska container muxer. +

+

This muxer implements the matroska and webm container specs. +

+ +

21.57.1 Metadata

+

The recognized metadata settings in this muxer are: +

+
+
title
+

Set title name provided to a single track. This gets mapped to +the FileDescription element for a stream written as attachment. +

+
+
language
+

Specify the language of the track in the Matroska languages form. +

+

The language can be either the 3 letters bibliographic ISO-639-2 (ISO +639-2/B) form (like "fre" for French), or a language code mixed with a +country code for specialities in languages (like "fre-ca" for Canadian +French). +

+
+
stereo_mode
+

Set stereo 3D video layout of two views in a single video track. +

+

The following values are recognized: +

+
‘mono’
+

video is not stereo +

+
‘left_right’
+

Both views are arranged side by side, Left-eye view is on the left +

+
‘bottom_top’
+

Both views are arranged in top-bottom orientation, Left-eye view is at bottom +

+
‘top_bottom’
+

Both views are arranged in top-bottom orientation, Left-eye view is on top +

+
‘checkerboard_rl’
+

Each view is arranged in a checkerboard interleaved pattern, Left-eye view being first +

+
‘checkerboard_lr’
+

Each view is arranged in a checkerboard interleaved pattern, Right-eye view being first +

+
‘row_interleaved_rl’
+

Each view is constituted by a row based interleaving, Right-eye view is first row +

+
‘row_interleaved_lr’
+

Each view is constituted by a row based interleaving, Left-eye view is first row +

+
‘col_interleaved_rl’
+

Both views are arranged in a column based interleaving manner, Right-eye view is first column +

+
‘col_interleaved_lr’
+

Both views are arranged in a column based interleaving manner, Left-eye view is first column +

+
‘anaglyph_cyan_red’
+

All frames are in anaglyph format viewable through red-cyan filters +

+
‘right_left’
+

Both views are arranged side by side, Right-eye view is on the left +

+
‘anaglyph_green_magenta’
+

All frames are in anaglyph format viewable through green-magenta filters +

+
‘block_lr’
+

Both eyes laced in one Block, Left-eye view is first +

+
‘block_rl’
+

Both eyes laced in one Block, Right-eye view is first +

+
+
+
+ +

For example a 3D WebM clip can be created using the following command line: +

+
ffmpeg -i sample_left_right_clip.mpg -an -c:v libvpx -metadata stereo_mode=left_right -y stereo_clip.webm
+
+ + +

21.57.2 Options

+
+
reserve_index_space size
+

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 size bytes +of space in the file header and then try to write the cues there when the muxing +finishes. If the reserved space does not suffice, no Cues will be written, the +file will be finalized and writing the trailer will return an error. +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. +

+
+
cues_to_front bool
+

If set, the muxer will write the index at the beginning of the file +by shifting the main data if necessary. This can be combined with +reserve_index_space in which case the data is only shifted if +the initially reserved space turns out to be insufficient. +

+

This option is ignored if the output is unseekable. +

+
+
cluster_size_limit size
+

Store at most the provided amount of bytes in a cluster. +

+

If not specified, the limit is set automatically to a sensible +hardcoded fixed value. +

+
+
cluster_time_limit duration
+

Store at most the provided number of milliseconds in a cluster. +

+

If not specified, the limit is set automatically to a sensible +hardcoded fixed value. +

+
+
dash bool
+

Create a WebM file conforming to WebM DASH specification. By default +it is set to false. +

+
+
dash_track_number index
+

Track number for the DASH stream. By default it is set to 1. +

+
+
live bool
+

Write files assuming it is a live stream. By default it is set to +false. +

+
+
allow_raw_vfw bool
+

Allow raw VFW mode. By default it is set to false. +

+
+
flipped_raw_rgb bool
+

If set to true, store positive height for raw RGB bitmaps, which indicates +bitmap is stored bottom-up. Note that this option does not flip the bitmap +which has to be done manually beforehand, e.g. by using the ‘vflip’ filter. +Default is false and indicates bitmap is stored top down. +

+
+
write_crc32 bool
+

Write a CRC32 element inside every Level 1 element. By default it is +set to true. This option is ignored for WebM. +

+
+
default_mode mode
+

Control how the FlagDefault of the output tracks will be set. +It influences which tracks players should play by default. The default mode +is ‘passthrough’. +

+
‘infer’
+

Every track with disposition default will have the FlagDefault set. +Additionally, for each type of track (audio, video or subtitle), if no track +with disposition default of this type exists, then the first track of this type +will be marked as default (if existing). This ensures that the default flag +is set in a sensible way even if the input originated from containers that +lack the concept of default tracks. +

+
‘infer_no_subs’
+

This mode is the same as infer except that if no subtitle track with +disposition default exists, no subtitle track will be marked as default. +

+
‘passthrough’
+

In this mode the FlagDefault is set if and only if the AV_DISPOSITION_DEFAULT +flag is set in the disposition of the corresponding stream. +

+
+
+
+ + +

21.58 md5

+

MD5 testing format. +

+

This is a variant of the hash muxer. Unlike that muxer, it +defaults to using the MD5 hash function. +

+

See also the hash and framemd5 muxers. +

+ +

21.58.1 Examples

+
    +
  • To compute the MD5 hash of the input converted to raw +audio and video, and store it in the file out.md5: +
    +
    ffmpeg -i INPUT -f md5 out.md5
    +
    + +
  • To print the MD5 hash to stdout: +
    +
    ffmpeg -i INPUT -f md5 -
    +
    +
+ + +

21.59 mcc

+

Muxer for MacCaption MCC files, it supports MCC versions 1.0 and 2.0. +MCC files store VANC data, which can include closed captions (EIA-608 and CEA-708), ancillary time code, pan-scan data, etc. +

+ +

21.59.1 Options

+ +

The muxer options are: +

+
+
override_time_code_rate
+

Override the Time Code Rate value in the output. Defaults to trying to deduce from the stream’s time_base, which often doesn’t work. +

+
use_u_alias
+

Use the U alias for the byte sequence E1h 00h 00h 00h. +Disabled by default because some .mcc files disagree on whether it has 2 or 3 zero bytes. +

+
mcc_version
+

The MCC file format version. Must be either 1 or 2, defaults to 2. +

+
creation_program
+

The creation program. Defaults to this version of FFmpeg. +

+
creation_time
+

The creation time. Defaults to the current time. +

+
+ + +

21.59.2 Examples

+
    +
  • Extract a MXF SMPTE_436M_ANC stream from a MXF file and write it to a MCC file at 30 fps. +
    +
    ffmpeg -i input.mxf -c copy -map 0:d -override_time_code_rate 30 out.mcc
    +
    + +
  • Extract EIA-608/CTA-708 closed captions from a .mp4 file and write them to a MCC file at 29.97 fps. +
    +
    ffmpeg -f lavfi -i "movie=input.mp4[out+subcc]" -c:s copy -map 0:s -override_time_code_rate 30000/1001 out.mcc
    +
    +
+ + +

21.60 microdvd

+

MicroDVD subtitle format muxer. +

+

This muxer accepts a single ‘microdvd’ subtitles stream. +

+ +

21.61 mmf

+

Synthetic music Mobile Application Format (SMAF) format muxer. +

+

SMAF is a music data format specified by Yamaha for portable +electronic devices, such as mobile phones and personal digital +assistants. +

+

This muxer accepts a single ‘adpcm_yamaha’ audio stream. +

+ +

21.62 mp3

+ +

The MP3 muxer writes a raw MP3 stream with the following optional features: +

    +
  • An ID3v2 metadata header at the beginning (enabled by default). Versions 2.3 and +2.4 are supported, the id3v2_version private option controls which one is +used (3 or 4). Setting id3v2_version to 0 disables the ID3v2 header +completely. + +

    The muxer supports writing attached pictures (APIC frames) to the ID3v2 header. +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 title and comment map +to APIC description and picture type respectively. See +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. +

    +
  • A Xing/LAME frame right after the ID3v2 header (if present). It is enabled by +default, but will be written only if the output is seekable. The +write_xing private option can be used to disable it. The frame contains +various information that may be useful to the decoder, like the audio duration +or encoder delay. + +
  • A legacy ID3v1 tag at the end of the file (disabled by default). It may be +enabled with the write_id3v1 private option, but as its capabilities are +very limited, its usage is not recommended. +
+ +

Examples: +

+

Write an mp3 with an ID3v2.3 header and an ID3v1 footer: +

+
ffmpeg -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3
+
+ +

To attach a picture to an mp3 file select both the audio and the picture stream +with map: +

+
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
+
+ +

Write a "clean" MP3 without any extra features: +

+
ffmpeg -i input.wav -write_xing 0 -id3v2_version 0 out.mp3
+
+ + +

21.63 mpegts

+ +

MPEG transport stream muxer. +

+

This muxer implements ISO 13818-1 and part of ETSI EN 300 468. +

+

The recognized metadata settings in mpegts muxer are service_provider +and service_name. If they are not set the default for +service_provider is ‘FFmpeg’ and the default for +service_name is ‘Service01’. +

+ +

21.63.1 Options

+ +

The muxer options are: +

+
+
mpegts_transport_stream_id integer
+

Set the ‘transport_stream_id’. This identifies a transponder in DVB. +Default is 0x0001. +

+
+
mpegts_original_network_id integer
+

Set the ‘original_network_id’. This is unique identifier of a +network in DVB. Its main use is in the unique identification of a service +through the path ‘Original_Network_ID, Transport_Stream_ID’. Default +is 0x0001. +

+
+
mpegts_service_id integer
+

Set the ‘service_id’, also known as program in DVB. Default is +0x0001. +

+
+
mpegts_service_type integer
+

Set the program ‘service_type’. Default is digital_tv. +Accepts the following options: +

+
‘hex_value’
+

Any hexadecimal value between 0x01 and 0xff as defined in +ETSI 300 468. +

+
‘digital_tv’
+

Digital TV service. +

+
‘digital_radio’
+

Digital Radio service. +

+
‘teletext’
+

Teletext service. +

+
‘advanced_codec_digital_radio’
+

Advanced Codec Digital Radio service. +

+
‘mpeg2_digital_hdtv’
+

MPEG2 Digital HDTV service. +

+
‘advanced_codec_digital_sdtv’
+

Advanced Codec Digital SDTV service. +

+
‘advanced_codec_digital_hdtv’
+

Advanced Codec Digital HDTV service. +

+
+ +
+
mpegts_pmt_start_pid integer
+

Set the first PID for PMTs. Default is 0x1000, minimum is 0x0020, +maximum is 0x1ffa. This option has no effect in m2ts mode where the PMT +PID is fixed 0x0100. +

+
+
mpegts_start_pid integer
+

Set the first PID for elementary streams. Default is 0x0100, minimum is +0x0020, maximum is 0x1ffa. This option has no effect in m2ts mode +where the elementary stream PIDs are fixed. +

+
+
mpegts_m2ts_mode boolean
+

Enable m2ts mode if set to 1. Default value is -1 which +disables m2ts mode. +

+
+
muxrate integer
+

Set a constant muxrate. Default is VBR. +

+
+
pes_payload_size integer
+

Set minimum PES packet payload in bytes. Default is 2930. +

+
+
mpegts_flags flags
+

Set mpegts flags. Accepts the following options: +

+
‘resend_headers’
+

Reemit PAT/PMT before writing the next packet. +

+
‘latm’
+

Use LATM packetization for AAC. +

+
‘pat_pmt_at_frames’
+

Reemit PAT and PMT at each video frame. +

+
‘system_b’
+

Conform to System B (DVB) instead of System A (ATSC). +

+
‘initial_discontinuity’
+

Mark the initial packet of each stream as discontinuity. +

+
‘nit’
+

Emit NIT table. +

+
‘omit_rai’
+

Disable writing of random access indicator. +

+
+ +
+
mpegts_copyts boolean
+

Preserve original timestamps, if value is set to 1. Default value +is -1, which results in shifting timestamps so that they start from 0. +

+
+
omit_video_pes_length boolean
+

Omit the PES packet length for video packets. Default is 1 (true). +

+
+
pcr_period integer
+

Override the default PCR retransmission time in milliseconds. Default is +-1 which means that the PCR interval will be determined automatically: +20 ms is used for CBR streams, the highest multiple of the frame duration which +is less than 100 ms is used for VBR streams. +

+
+
pat_period duration
+

Maximum time in seconds between PAT/PMT tables. Default is 0.1. +

+
+
sdt_period duration
+

Maximum time in seconds between SDT tables. Default is 0.5. +

+
+
nit_period duration
+

Maximum time in seconds between NIT tables. Default is 0.5. +

+
+
tables_version integer
+

Set PAT, PMT, SDT and NIT 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: +

+
+
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
+...
+
+
+
+ + +

21.63.2 Example

+ +
+
ffmpeg -i file.mpg -c copy \
+     -mpegts_original_network_id 0x1122 \
+     -mpegts_transport_stream_id 0x3344 \
+     -mpegts_service_id 0x5566 \
+     -mpegts_pmt_start_pid 0x1500 \
+     -mpegts_start_pid 0x150 \
+     -metadata service_provider="Some provider" \
+     -metadata service_name="Some Channel" \
+     out.ts
+
+ + +

21.64 mxf, mxf_d10, mxf_opatom

+ +

MXF muxer. +

+ +

21.64.1 Options

+ +

The muxer options are: +

+
+
store_user_comments bool
+

Set if user comments should be stored if available or never. +IRT D-10 does not allow user comments. The default is thus to write them for +mxf and mxf_opatom but not for mxf_d10 +

+
+ + +

21.65 null

+ +

Null muxer. +

+

This muxer does not generate any output file, it is mainly useful for +testing or benchmarking purposes. +

+

For example to benchmark decoding with ffmpeg you can use the +command: +

+
ffmpeg -benchmark -i INPUT -f null out.null
+
+ +

Note that the above command does not read or write the out.null +file, but specifying the output file is required by the ffmpeg +syntax. +

+

Alternatively you can write the command as: +

+
ffmpeg -benchmark -i INPUT -f null -
+
+ + +

21.66 nut

+ +
+
-syncpoints flags
+

Change the syncpoint usage in nut: +

+
default use the normal low-overhead seeking aids.
+
none do not use the syncpoints at all, reducing the overhead but making the stream non-seekable;
+

Use of this option is not recommended, as the resulting files are very damage + sensitive and seeking is not possible. Also in general the overhead from + syncpoints is negligible. Note, -write_index 0 can be used to disable + all growing data tables, allowing to mux endless streams with limited memory + and without these disadvantages. +

+
timestamped extend the syncpoint with a wallclock field.
+
+

The none and timestamped flags are experimental. +

+
-write_index bool
+

Write index at the end, the default is to write an index. +

+
+ +
+
ffmpeg -i INPUT -f_strict experimental -syncpoints none - | processor
+
+ + +

21.67 ogg

+ +

Ogg container muxer. +

+
+
-page_duration duration
+

Preferred page duration, in microseconds. The muxer will attempt to create +pages that are approximately 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. +

+
-serial_offset value
+

Serial value from which to set the streams serial number. +Setting it to different and sufficiently large values ensures that the produced +ogg files can be safely chained. +

+
+
+ + +

21.68 rcwt

+ +

RCWT (Raw Captions With Time) is a format native to ccextractor, a commonly +used open source tool for processing 608/708 Closed Captions (CC) sources. +It can be used to archive the original extracted CC bitstream and to produce +a source file for later processing or conversion. The format allows +for interoperability between ccextractor and FFmpeg, is simple to parse, +and can be used to create a backup of the CC presentation. +

+

This muxer implements the specification as of March 2024, which has +been stable and unchanged since April 2014. +

+

This muxer will have some nuances from the way that ccextractor muxes RCWT. +No compatibility issues when processing the output with ccextractor +have been observed as a result of this so far, but mileage may vary +and outputs will not be a bit-exact match. +

+

A free specification of RCWT can be found here: +https://github.com/CCExtractor/ccextractor/blob/master/docs/BINARY_FILE_FORMAT.TXT +

+ +

21.68.1 Examples

+ +
    +
  • Extract Closed Captions to RCWT using lavfi: +
    +
    ffmpeg -f lavfi -i "movie=INPUT.mkv[out+subcc]" -map 0:s:0 -c:s copy -f rcwt CC.rcwt.bin
    +
    +
+ + +

21.69 segment, stream_segment, ssegment

+ +

Basic stream segmenter. +

+

This muxer outputs streams to a number of separate files of nearly +fixed duration. Output filename pattern can be set in a fashion +similar to image2, or by using a strftime template if +the strftime option is enabled. +

+

stream_segment is a variant of the muxer used to write to +streaming output formats, i.e. which do not require global headers, +and is recommended for outputting e.g. to MPEG transport stream segments. +ssegment is a shorter alias for stream_segment. +

+

Every segment starts with a keyframe of the selected reference stream, +which is set through the reference_stream option. +

+

Note that if you want accurate splitting for a video file, you need to +make the input key frames correspond to the exact splitting times +expected by the segmenter, or the segment muxer will start the new +segment with the key frame found next after the specified start +time. +

+

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 segment_list. The list type is specified by the +segment_list_type option. The entry filenames in the segment +list are set by default to the basename of the corresponding segment +files. +

+

See also the hls muxer, which provides a more specific +implementation for HLS segmentation. +

+ +

21.69.1 Options

+ +

The segment muxer supports the following options: +

+
+
increment_tc 1|0
+

if set to 1, increment timecode between each segment +If this is selected, the input need to have +a timecode in the first video stream. Default value is +0. +

+
+
reference_stream specifier
+

Set the reference stream, as specified by the string specifier. +If specifier is set to auto, the reference is chosen +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. +

+
+
segment_format format
+

Override the inner container format, by default it is guessed by the filename +extension. +

+
+
segment_format_options options_list
+

Set output format options using a :-separated list of key=value +parameters. Values containing the : special character must be +escaped. +

+
+
segment_list name
+

Generate also a listfile named name. If not specified no +listfile is generated. +

+
+
segment_list_flags flags
+

Set flags affecting the segment list generation. +

+

It currently supports the following flags: +

+
‘cache’
+

Allow caching (only affects M3U8 list files). +

+
+
‘live’
+

Allow live-friendly file generation. +

+
+ +
+
segment_list_size size
+

Update the list file so that it contains at most size +segments. If 0 the list file will contain all the segments. Default +value is 0. +

+
+
segment_list_entry_prefix prefix
+

Prepend prefix to each entry. Useful to generate absolute paths. +By default no prefix is applied. +

+
+
segment_list_type type
+

Select the listing format. +

+

The following values are recognized: +

+
‘flat’
+

Generate a flat list for the created segments, one segment per line. +

+
+
‘csv, ext’
+

Generate a list for the created segments, one segment per line, +each line matching the format (comma-separated values): +

+
segment_filename,segment_start_time,segment_end_time
+
+ +

segment_filename is the name of the output file generated by the +muxer according to the provided pattern. CSV escaping (according to +RFC4180) is applied if required. +

+

segment_start_time and segment_end_time specify +the segment start and end time expressed in seconds. +

+

A list file with the suffix ".csv" or ".ext" will +auto-select this format. +

+

‘ext’ is deprecated in favor or ‘csv’. +

+
+
‘ffconcat’
+

Generate an ffconcat file for the created segments. The resulting file +can be read using the FFmpeg concat demuxer. +

+

A list file with the suffix ".ffcat" or ".ffconcat" will +auto-select this format. +

+
+
‘m3u8’
+

Generate an extended M3U8 file, version 3, compliant with +http://tools.ietf.org/id/draft-pantos-http-live-streaming. +

+

A list file with the suffix ".m3u8" will auto-select this format. +

+
+ +

If not specified the type is guessed from the list file name suffix. +

+
+
segment_time time
+

Set segment duration to time, the value must be a duration +specification. Default value is "2". See also the +segment_times option. +

+

Note that splitting may not be accurate, unless you force the +reference stream key-frames at the given time. See the introductory +notice and the examples below. +

+
+
min_seg_duration time
+

Set minimum segment duration to time, the value must be a duration +specification. This prevents the muxer ending segments at a duration below +this value. Only effective with segment_time. Default value is "0". +

+
+
segment_atclocktime 1|0
+

If set to "1" split at regular clock time intervals starting from 00:00 +o’clock. The time value specified in segment_time is +used for setting the length of the splitting interval. +

+

For example with segment_time set to "900" this makes it possible +to create files at 12:00 o’clock, 12:15, 12:30, etc. +

+

Default value is "0". +

+
+
segment_clocktime_offset duration
+

Delay the segment splitting times with the specified duration when using +segment_atclocktime. +

+

For example with segment_time set to "900" and +segment_clocktime_offset set to "300" this makes it possible to +create files at 12:05, 12:20, 12:35, etc. +

+

Default value is "0". +

+
+
segment_clocktime_wrap_duration duration
+

Force the segmenter to only start a new segment if a packet reaches the muxer +within the specified duration after the segmenting clock time. This way you +can make the segmenter more resilient to backward local time jumps, such as +leap seconds or transition to standard time from daylight savings time. +

+

Default is the maximum possible duration which means starting a new segment +regardless of the elapsed time since the last clock time. +

+
+
segment_time_delta delta
+

Specify the accuracy time when selecting the start time for a +segment, expressed as a duration specification. Default value is "0". +

+

When delta is specified a key-frame will start a new segment if its +PTS satisfies the relation: +

+
PTS >= start_time - time_delta
+
+ +

This option is useful when splitting video content, which is always +split at GOP boundaries, in case a key frame is found just before the +specified split time. +

+

In particular may be used in combination with the ffmpeg option +force_key_frames. The key frame times specified by +force_key_frames may not be set accurately because of rounding +issues, with the consequence that a key frame time may result set just +before the specified time. For constant frame rate videos a value of +1/(2*frame_rate) should address the worst case mismatch between +the specified time and the time set by force_key_frames. +

+
+
segment_times times
+

Specify a list of split points. times contains a list of comma +separated duration specifications, in increasing order. See also +the segment_time option. +

+
+
segment_frames frames
+

Specify a list of split video frame numbers. frames contains a +list of comma separated integer numbers, in increasing order. +

+

This option specifies to start a new segment whenever a reference +stream key frame is found and the sequential number (starting from 0) +of the frame is greater or equal to the next value in the list. +

+
+
segment_wrap limit
+

Wrap around segment index once it reaches limit. +

+
+
segment_start_number number
+

Set the sequence number of the first segment. Defaults to 0. +

+
+
strftime 1|0
+

Use the strftime function to define the name of the new +segments to write. If this is selected, the output segment name must +contain a strftime function template. Default value is +0. +

+
+
break_non_keyframes 1|0
+

If enabled, allow segments to start on frames other than keyframes. This +improves behavior on some players when the time between keyframes is +inconsistent, but may make things worse on others, and can cause some oddities +during seeking. Defaults to 0. +

+
+
reset_timestamps 1|0
+

Reset timestamps at the beginning 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 0 by default. +

+
+
initial_offset offset
+

Specify timestamp offset to apply to the output packet timestamps. The +argument must be a time duration specification, and defaults to 0. +

+
+
write_empty_segments 1|0
+

If enabled, write an empty segment if there are no packets during the period a +segment would usually span. Otherwise, the segment will be filled with the next +packet written. Defaults to 0. +

+
+ +

Make sure to require a closed GOP when encoding and to set the GOP +size to fit your segment time constraint. +

+ +

21.69.2 Examples

+ +
    +
  • Remux the content of file in.mkv to a list of segments +out-000.nut, out-001.nut, etc., and write the list of +generated segments to out.list: +
    +
    ffmpeg -i in.mkv -codec hevc -flags +cgop -g 60 -map 0 -f segment -segment_list out.list out%03d.nut
    +
    + +
  • Segment input and set output format options for the output segments: +
    +
    ffmpeg -i in.mkv -f segment -segment_time 10 -segment_format_options movflags=+faststart out%03d.mp4
    +
    + +
  • Segment the input file according to the split points specified by the +segment_times option: +
    +
    ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 out%03d.nut
    +
    + +
  • Use the ffmpeg force_key_frames +option to force key frames in the input at the specified location, together +with the segment option segment_time_delta to account for +possible roundings operated when setting key frame times. +
    +
    ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -codec:v mpeg4 -codec:a pcm_s16le -map 0 \
    +-f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 -segment_time_delta 0.05 out%03d.nut
    +
    +

    In order to force key frames on the input file, transcoding is +required. +

    +
  • Segment the input file by splitting the input file according to the +frame numbers sequence specified with the segment_frames option: +
    +
    ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_frames 100,200,300,500,800 out%03d.nut
    +
    + +
  • Convert the in.mkv to TS segments using the libx264 +and aac encoders: +
    +
    ffmpeg -i in.mkv -map 0 -codec:v libx264 -codec:a aac -f ssegment -segment_list out.list out%03d.ts
    +
    + +
  • Segment the input file, and create an M3U8 live playlist (can be used +as live HLS source): +
    +
    ffmpeg -re -i in.mkv -codec copy -map 0 -f segment -segment_list playlist.m3u8 \
    +-segment_list_flags +live -segment_time 10 out%03d.mkv
    +
    +
+ + +

21.70 smoothstreaming

+ +

Smooth Streaming muxer generates a set of files (Manifest, chunks) suitable for serving with conventional web server. +

+
+
window_size
+

Specify the number of fragments kept in the manifest. Default 0 (keep all). +

+
+
extra_window_size
+

Specify the number of fragments kept outside of the manifest before removing from disk. Default 5. +

+
+
lookahead_count
+

Specify the number of lookahead fragments. Default 2. +

+
+
min_frag_duration
+

Specify the minimum fragment duration (in microseconds). Default 5000000. +

+
+
remove_at_exit
+

Specify whether to remove all fragments when finished. Default 0 (do not remove). +

+
+
+ + +

21.71 streamhash

+ +

Per stream hash testing format. +

+

This muxer computes and prints a cryptographic hash of all the input frames, +on a per-stream basis. This can be used for equality checks without having +to do a complete binary comparison. +

+

By default audio frames are converted to signed 16-bit raw audio and +video frames to raw video before computing the hash, but the output +of explicit conversions to other codecs can also be used. Timestamps +are ignored. It uses the SHA-256 cryptographic hash function by default, +but supports several other algorithms. +

+

The output of the muxer consists of one line per stream of the form: +streamindex,streamtype,algo=hash, where +streamindex is the index of the mapped stream, streamtype is a +single character indicating the type of stream, algo is a short string +representing the hash function used, and hash is a hexadecimal number +representing the computed hash. +

+
+
hash algorithm
+

Use the cryptographic hash function specified by the string algorithm. +Supported values include MD5, murmur3, RIPEMD128, +RIPEMD160, RIPEMD256, RIPEMD320, SHA160, +SHA224, SHA256 (default), SHA512/224, SHA512/256, +SHA384, SHA512, CRC32 and adler32. +

+
+
+ + +

21.71.1 Examples

+ +

To compute the SHA-256 hash of the input converted to raw audio and +video, and store it in the file out.sha256: +

+
ffmpeg -i INPUT -f streamhash out.sha256
+
+ +

To print an MD5 hash to stdout use the command: +

+
ffmpeg -i INPUT -f streamhash -hash md5 -
+
+ +

See also the hash and framehash muxers. +

+ +

21.72 tee

+ +

The tee muxer can be used to write the same data to several outputs, such as files or streams. +It can be used, for example, to stream a video over a network and save it to disk at the same time. +

+

It is different from specifying several outputs to the ffmpeg +command-line tool. With the tee muxer, the audio and video data will be encoded only once. +With conventional multiple outputs, multiple encoding operations in parallel are initiated, +which can be a very expensive process. The tee muxer is not useful when using the libavformat API +directly because it is then possible to feed the same packets to several muxers directly. +

+

Since the tee muxer does not represent any particular output format, ffmpeg cannot auto-select +output streams. So all streams intended for output must be specified using -map. See +the examples below. +

+

Some encoders may need different options depending on the output format; +the auto-detection of this can not work with the tee muxer, so they need to be explicitly specified. +The main example is the global_header flag. +

+

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, those must be +escaped (see the "Quoting and escaping" +section in the ffmpeg-utils(1) manual). +

+ +

21.72.1 Options

+ +
+
use_fifo bool
+

If set to 1, slave outputs will be processed in separate threads using the fifo +muxer. This allows to compensate for different speed/latency/reliability of +outputs and setup transparent recovery. By default this feature is turned off. +

+
+
fifo_options
+

Options to pass to fifo pseudo-muxer instances. See fifo. +

+
+
+ +

Muxer options can be specified for each slave by prepending them as a list of +key=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. +

+

The following special options are also recognized: +

+
f
+

Specify the format name. Required if it cannot be guessed from the +output URL. +

+
+
bsfs[/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 +/. spec must be a stream specifier (see Format stream specifiers). +

+

If the stream specifier is not specified, the bitstream filters will be +applied to all streams in the output. This will cause that output operation +to fail if the output contains streams to which the bitstream filter cannot +be applied e.g. h264_mp4toannexb being applied to an output containing an audio stream. +

+

Options for a bitstream filter must be specified in the form of opt=value. +

+

Several bitstream filters can be specified, separated by ",". +

+
+
use_fifo bool
+

This allows to override tee muxer use_fifo option for individual slave muxer. +

+
+
fifo_options
+

This allows to override tee muxer fifo_options for individual slave muxer. +See fifo. +

+
+
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 mapped streams. This will cause that output operation to fail +if the output format does not accept all mapped streams. +

+

You may use multiple stream specifiers separated by commas (,) e.g.: a:0,v +

+
+
onfail
+

Specify behaviour on output failure. This can be set to either abort (which is +default) or ignore. abort will cause whole process to fail in case of failure +on this slave output. ignore will ignore failure on this output, so other outputs +will continue without being affected. +

+
+ + +

21.72.2 Examples

+ +
    +
  • Encode something and both archive it in a WebM file and stream it +as MPEG-TS over UDP: +
    +
    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/"
    +
    + +
  • As above, but continue streaming even if output to local file fails +(for example local drive fills up): +
    +
    ffmpeg -i ... -c:v libx264 -c:a mp2 -f tee -map 0:v -map 0:a
    +  "[onfail=ignore]archive-20121107.mkv|[f=mpegts]udp://10.0.1.255:1234/"
    +
    + +
  • Use ffmpeg to encode the input, and send the output +to three different destinations. The 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 out.aac in order to make it contain only +audio packets. +
    +
    ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac
    +       -f tee "[bsfs/v=dump_extra=freq=keyframe]out.ts|[movflags=+faststart]out.mp4|[select=a]out.aac"
    +
    + +
  • As above, but select only stream a:1 for the audio output. Note +that a second level escaping must be performed, as ":" is a special +character used to separate options. +
    +
    ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac
    +       -f tee "[bsfs/v=dump_extra=freq=keyframe]out.ts|[movflags=+faststart]out.mp4|[select=\'a:1\']out.aac"
    +
    +
+ + +

21.73 webm_chunk

+ +

WebM Live Chunk Muxer. +

+

This muxer writes out WebM headers and chunks as separate files which can be +consumed by clients that support WebM Live streams via DASH. +

+ +

21.73.1 Options

+ +

This muxer supports the following options: +

+
+
chunk_start_index
+

Index of the first chunk (defaults to 0). +

+
+
header
+

Filename of the header where the initialization data will be written. +

+
+
audio_chunk_duration
+

Duration of each audio chunk in milliseconds (defaults to 5000). +

+
+ + +

21.73.2 Example

+
+
ffmpeg -f v4l2 -i /dev/video0 \
+       -f alsa -i hw:0 \
+       -map 0:0 \
+       -c:v libvpx-vp9 \
+       -s 640x360 -keyint_min 30 -g 30 \
+       -f webm_chunk \
+       -header webm_live_video_360.hdr \
+       -chunk_start_index 1 \
+       webm_live_video_360_%d.chk \
+       -map 1:0 \
+       -c:a libvorbis \
+       -b:a 128k \
+       -f webm_chunk \
+       -header webm_live_audio_128.hdr \
+       -chunk_start_index 1 \
+       -audio_chunk_duration 1000 \
+       webm_live_audio_128_%d.chk
+
+ + +

21.74 webm_dash_manifest

+ +

WebM DASH Manifest muxer. +

+

This muxer implements the WebM DASH Manifest specification to generate the DASH +manifest XML. It also supports manifest generation for DASH live streams. +

+

For more information see: +

+ + + +

21.74.1 Options

+ +

This muxer supports the following options: +

+
+
adaptation_sets
+

This option has the following syntax: "id=x,streams=a,b,c id=y,streams=d,e" where x and y are the +unique identifiers of the adaptation sets and a,b,c,d and e are the indices of the corresponding +audio and video streams. Any number of adaptation sets can be added using this option. +

+
+
live
+

Set this to 1 to create a live stream DASH Manifest. Default: 0. +

+
+
chunk_start_index
+

Start index of the first chunk. This will go in the ‘startNumber’ attribute +of the ‘SegmentTemplate’ element in the manifest. Default: 0. +

+
+
chunk_duration_ms
+

Duration of each chunk in milliseconds. This will go in the ‘duration’ +attribute of the ‘SegmentTemplate’ element in the manifest. Default: 1000. +

+
+
utc_timing_url
+

URL of the page that will return the UTC timestamp in ISO format. This will go +in the ‘value’ attribute of the ‘UTCTiming’ element in the manifest. +Default: None. +

+
+
time_shift_buffer_depth
+

Smallest time (in seconds) shifting buffer for which any Representation is +guaranteed to be available. This will go in the ‘timeShiftBufferDepth’ +attribute of the ‘MPD’ element. Default: 60. +

+
+
minimum_update_period
+

Minimum update period (in seconds) of the manifest. This will go in the +‘minimumUpdatePeriod’ attribute of the ‘MPD’ element. Default: 0. +

+
+
+ + +

21.74.2 Example

+
+
ffmpeg -f webm_dash_manifest -i video1.webm \
+       -f webm_dash_manifest -i video2.webm \
+       -f webm_dash_manifest -i audio1.webm \
+       -f webm_dash_manifest -i audio2.webm \
+       -map 0 -map 1 -map 2 -map 3 \
+       -c copy \
+       -f webm_dash_manifest \
+       -adaptation_sets "id=0,streams=0,1 id=1,streams=2,3" \
+       manifest.xml
+
+ + +

21.75 whip

+ +

WebRTC (Real-Time Communication) muxer that supports sub-second latency streaming according to +the WHIP (WebRTC-HTTP ingestion protocol) specification. +

+

This is an experimental feature. +

+

It uses HTTP as a signaling protocol to exchange SDP capabilities and ICE lite candidates. Then, +it uses STUN binding requests and responses to establish a session over UDP. Subsequently, it +initiates a DTLS handshake to exchange the SRTP encryption keys. Lastly, it splits video and +audio frames into RTP packets and encrypts them using SRTP. +

+

Ensure that you use H.264 without B frames and Opus for the audio codec. For example, to convert +an input file with ffmpeg to WebRTC: +

+
ffmpeg -re -i input.mp4 -acodec libopus -ar 48000 -ac 2 \
+  -vcodec libx264 -profile:v baseline -tune zerolatency -threads 1 -bf 0 \
+  -f whip "http://localhost:1985/rtc/v1/whip/?app=live&stream=livestream"
+
+ +

For this example, we have employed low latency options, resulting in an end-to-end latency of +approximately 150ms. +

+ +

21.75.1 Options

+ +

This muxer supports the following options: +

+
+
handshake_timeout integer
+

Set the timeout in milliseconds for ICE and DTLS handshake. +Default value is 5000. +

+
+
pkt_size integer
+

Set the maximum size, in bytes, of RTP packets that send out. +Default value is 1200. +

+
+
ts_buffer_size integer
+

Set the buffer size, in bytes, of underlying protocol. +Default value is -1(auto). The UDP auto selects a reasonable value. +

+
+
whip_flags flags
+

Possible values: +

+
+
‘dtls_active’
+

The muxer will try to set dtls active role and send the first client hello. +

+
+ +
+
rtp_history integer
+

Set the number of RTP history items to store. +Default value is 512. +

+
+
authorization string
+

The optional Bearer token for WHIP Authorization. +

+
+
cert_file string
+

The optional certificate file path for DTLS. +

+
+
key_file string
+

The optional private key file path for DTLS. +

+
+
+ + +

22 Metadata

+ +

FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded +INI-like text file and then load it back using the metadata muxer/demuxer. +

+

The file format is as follows: +

    +
  1. A file consists of a header and a number of metadata tags divided into sections, +each on its own line. + +
  2. The header is a ‘;FFMETADATA’ string, followed by a version number (now 1). + +
  3. Metadata tags are of the form ‘key=value’ + +
  4. Immediately after header follows global metadata + +
  5. After global metadata there may be sections with per-stream/per-chapter +metadata. + +
  6. A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in +brackets (‘[’, ‘]’) and ends with next section or end of file. + +
  7. At the beginning of a chapter section there may be an optional timebase to be +used for start/end values. It must be in form +‘TIMEBASE=num/den’, where num and den are +integers. If the timebase is missing then start/end times are assumed to +be in nanoseconds. + +

    Next a chapter section must contain chapter start and end times in form +‘START=num’, ‘END=num’, where num is a positive +integer. +

    +
  8. Empty lines and lines starting with ‘;’ or ‘#’ are ignored. + +
  9. Metadata keys or values containing special characters (‘=’, ‘;’, +‘#’, ‘\’ and a newline) must be escaped with a backslash ‘\’. + +
  10. Note that whitespace in metadata (e.g. ‘foo = bar’) is considered to be +a part of the tag (in the example above key is ‘foo ’, value is +‘ bar’). +
+ +

A ffmetadata file might look like this: +

+
;FFMETADATA1
+title=bike\\shed
+;this is a comment
+artist=FFmpeg troll team
+
+[CHAPTER]
+TIMEBASE=1/1000
+START=0
+#chapter ends at 0:01:00
+END=60000
+title=chapter \#1
+[STREAM]
+title=multi\
+line
+
+ +

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 ffmpeg goes as follows: +

+
ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
+
+ +

Reinserting edited metadata information from the FFMETADATAFILE file can +be done as: +

+
ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
+
+ + +

23 Protocol Options

+ +

The libavformat library provides some generic global options, which +can be set on all the protocols. In addition each protocol may support +so-called private options, which are specific for that component. +

+

Options may be set by specifying -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
protocol_whitelist list (input)
+

Set a ","-separated list of allowed protocols. "ALL" matches all protocols. Protocols +prefixed by "-" are disabled. +All protocols are allowed by default but protocols used by an another +protocol (nested protocols) are restricted to a per protocol subset. +

+
+ + + +

24 Protocols

+ +

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 +configure option "–list-protocols". +

+

You can disable all the protocols using the configure option +"–disable-protocols", and selectively enable a protocol using the +option "–enable-protocol=PROTOCOL", or you can disable a +particular protocol using the option +"–disable-protocol=PROTOCOL". +

+

The option "-protocols" of the ff* tools will display the list of +supported protocols. +

+

All protocols accept the following options: +

+
+
rw_timeout
+

Maximum time to wait for (network) read/write operations to complete, +in microseconds. +

+
+ +

A description of the currently available protocols follows. +

+ +

24.1 amqp

+ +

Advanced Message Queueing Protocol (AMQP) version 0-9-1 is a broker based +publish-subscribe communication protocol. +

+

FFmpeg must be compiled with –enable-librabbitmq to support AMQP. A separate +AMQP broker must also be run. An example open-source AMQP broker is RabbitMQ. +

+

After starting the broker, an FFmpeg client may stream data to the broker using +the command: +

+
+
ffmpeg -re -i input -f mpegts amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

Where hostname and port (default is 5672) is the address of the broker. The +client may also set a user/password for authentication. The default for both +fields is "guest". Name of virtual host on broker can be set with vhost. The +default value is "/". +

+

Multiple subscribers may stream from the broker using the command: +

+
ffplay amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

In RabbitMQ all data published to the broker flows through a specific exchange, +and each subscribing client has an assigned queue/buffer. When a packet arrives +at an exchange, it may be copied to a client’s queue depending on the exchange +and routing_key fields. +

+

The following options are supported: +

+
+
exchange
+

Sets the exchange to use on the broker. RabbitMQ has several predefined +exchanges: "amq.direct" is the default exchange, where the publisher and +subscriber must have a matching routing_key; "amq.fanout" is the same as a +broadcast operation (i.e. the data is forwarded to all queues on the fanout +exchange independent of the routing_key); and "amq.topic" is similar to +"amq.direct", but allows for more complex pattern matching (refer to the RabbitMQ +documentation). +

+
+
routing_key
+

Sets the routing key. The default value is "amqp". The routing key is used on +the "amq.direct" and "amq.topic" exchanges to decide whether packets are written +to the queue of a subscriber. +

+
+
pkt_size
+

Maximum size of each packet sent/received to the broker. Default is 131072. +Minimum is 4096 and max is any large value (representable by an int). When +receiving packets, this sets an internal buffer size in FFmpeg. It should be +equal to or greater than the size of the published packets to the broker. Otherwise +the received message may be truncated causing decoding errors. +

+
+
connection_timeout
+

The timeout in seconds during the initial connection to the broker. The +default value is rw_timeout, or 5 seconds if rw_timeout is not set. +

+
+
delivery_mode mode
+

Sets the delivery mode of each message sent to broker. +The following values are accepted: +

+
‘persistent’
+

Delivery mode set to "persistent" (2). This is the default value. +Messages may be written to the broker’s disk depending on its setup. +

+
+
‘non-persistent’
+

Delivery mode set to "non-persistent" (1). +Messages will stay in broker’s memory unless the broker is under memory +pressure. +

+
+
+ +
+
+ + +

24.2 async

+ +

Asynchronous data filling wrapper for input stream. +

+

Fill data in a background thread, to decouple I/O operation from demux thread. +

+
+
async:URL
+async:http://host/resource
+async:cache:http://host/resource
+
+ + +

24.3 bluray

+ +

Read BluRay playlist. +

+

The accepted options are: +

+
angle
+

BluRay angle +

+
+
chapter
+

Start chapter (1...N) +

+
+
playlist
+

Playlist to read (BDMV/PLAYLIST/?????.mpls) +

+
+
+ +

Examples: +

+

Read longest playlist from BluRay mounted to /mnt/bluray: +

+
bluray:/mnt/bluray
+
+ +

Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: +

+
-playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
+
+ + +

24.4 cache

+ +

Caching wrapper for input stream. +

+

Cache the input stream to temporary file. It brings seeking capability to live streams. +

+

The accepted options are: +

+
read_ahead_limit
+

Amount in bytes that may be read ahead when seeking isn’t supported. Range is -1 to INT_MAX. +-1 for unlimited. Default is 65536. +

+
+
+ +

URL Syntax is +

+
cache:URL
+
+ + +

24.5 concat

+ +

Physical concatenation protocol. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concat:URL1|URL2|...|URLN
+
+ +

where URL1, URL2, ..., URLN are the urls of the +resource to be concatenated, each one possibly specifying a distinct +protocol. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg with ffplay use the +command: +

+
ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+
+ +

Note that you may need to escape the character "|" which is special for +many shells. +

+ +

24.6 concatf

+ +

Physical concatenation protocol using a line break delimited list of +resources. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concatf:URL
+
+ +

where URL is the url containing a line break delimited list of +resources to be concatenated, each one possibly specifying a distinct +protocol. Special characters must be escaped with backslash or single +quotes. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg listed in separate lines within +a file split.txt with ffplay use the command: +

+
ffplay concatf:split.txt
+
+

Where split.txt contains the lines: +

+
split1.mpeg
+split2.mpeg
+split3.mpeg
+
+ + +

24.7 crypto

+ +

AES-encrypted stream reading protocol. +

+

The accepted options are: +

+
key
+

Set the AES decryption key binary block from given hexadecimal representation. +

+
+
iv
+

Set the AES decryption initialization vector binary block from given hexadecimal representation. +

+
+ +

Accepted URL formats: +

+
crypto:URL
+crypto+URL
+
+ + +

24.8 data

+ +

Data in-line in the URI. See http://en.wikipedia.org/wiki/Data_URI_scheme. +

+

For example, to convert a GIF file given inline with ffmpeg: +

+
ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
+
+ + +

24.9 fd

+ +

File descriptor access protocol. +

+

The accepted syntax is: +

+
fd: -fd file_descriptor
+
+ +

If fd is not specified, by default the stdout file descriptor will be +used for writing, stdin for reading. Unlike the pipe protocol, fd protocol has +seek support if it corresponding to a regular file. fd protocol doesn’t support +pass file descriptor via URL for security. +

+

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
fd
+

Set file descriptor. +

+
+ + +

24.10 file

+ +

File access protocol. +

+

Read from or write to a file. +

+

A file URL can have the form: +

+
file:filename
+
+ +

where filename is the path of the file to read. +

+

An URL that does not have a protocol prefix will be assumed to be a +file URL. Depending on the build, an URL that looks like a Windows +path with the drive letter at the beginning will also be assumed to be +a file URL (usually not the case in builds for unix-like systems). +

+

For example to read from a file input.mpeg with ffmpeg +use the command: +

+
ffmpeg -i file:input.mpeg output.mpeg
+
+ +

This protocol accepts the following options: +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
follow
+

If set to 1, the protocol will retry reading at the end of the file, allowing +reading files that still are being written. In order for this to terminate, +you either need to use the rw_timeout option, or use the interrupt callback +(for API users). +

+
+
seekable
+

Controls if seekability is advertised on the file. 0 means non-seekable, -1 +means auto (seekable for normal files, non-seekable for named pipes). +

+

Many demuxers handle seekable and non-seekable resources differently, +overriding this might speed up opening certain files at the cost of losing some +features (e.g. accurate seeking). +

+
+
pkt_size
+

Set the maximum packet size used for file I/O. A smaller value may reduce +memory usage. A higher value may increase throughput especially with networked +filesystems. +

+

For reading, if explicitly set, it overrides the default internal buffer size +(32 KB) and limits the maximum amount of data read per operation. +

+

For writing, this sets the size of each write operation. The default is 256 KB +for regular files, 32 KB otherwise. +

+
+ + +

24.11 ftp

+ +

FTP (File Transfer Protocol). +

+

Read from or write to remote resources using FTP protocol. +

+

Following syntax is required. +

+
ftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in microseconds 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. +

+
+
ftp-user
+

Set a user to be used for authenticating to the FTP server. This is overridden by the +user in the FTP URL. +

+
+
ftp-password
+

Set a password to be used for authenticating to the FTP server. This is overridden by +the password in the FTP URL, or by ftp-anonymous-password if no user is set. +

+
+
ftp-anonymous-password
+

Password used when login as anonymous user. Typically an e-mail address +should be used. +

+
+
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. +

+
+ +

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. +

+ +

24.12 gopher

+ +

Gopher protocol. +

+ +

24.13 gophers

+ +

Gophers protocol. +

+

The Gopher protocol with TLS encapsulation. +

+ +

24.14 http

+ +

HTTP (Hyper Text Transfer Protocol). +

+

This protocol accepts the following options: +

+
+
seekable
+

Control seekability of connection. If set to 1 the resource is +supposed to be seekable, if set to 0 it is assumed not to be seekable, +if set to -1 it will try to autodetect if it is seekable. Default +value is -1. +

+
+
chunked_post
+

If set to 1 use chunked Transfer-Encoding for posts, default is 1. +

+
+
http_proxy
+

set HTTP proxy to tunnel through e.g. http://example.com:1234 +

+
+
headers
+

Set custom HTTP headers, can override built in default headers. The +value must be a string encoding the headers. +

+
+
content_type
+

Set a specific content type for the POST messages or for listen mode. +

+
+
user_agent
+

Override the User-Agent header. If not specified the protocol will use a +string describing the libavformat build. ("Lavf/<version>") +

+
+
referer
+

Set the Referer header. Include ’Referer: URL’ header in HTTP request. +

+
+
multiple_requests
+

Use persistent connections if set to 1, default is 0. +

+
+
request_size
+

Limit the size of requests made. This is useful for some pathological servers +that throttle unbounded range requests, as well as when expecting to seek +frequently. Disabled (set to 0) by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. Doing so allows FFmpeg +to reuse a single HTTP connection wherever possible. +

+
+
initial_request_size
+

Limit the size of initial requests. Similar to request_size, but only +used during initial format parsing. Useful for formats like MXF or MOV that +require frequent seeks during header parsing. Lasts until the demuxer makes a +read request larger than this size (without a seek in between), after which +the implementation will continue using requests as usual. Disabled (set to 0) +by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. +

+
+
post_data
+

Set custom HTTP post data. +

+
+
mime_type
+

Export the MIME type. +

+
+
http_version
+

Exports the HTTP response version number. Usually "1.0" or "1.1". +

+
+
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 +delimited by a newline character. +

+
+
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 icy_metadata_headers and icy_metadata_packet options. +The default is 1. +

+
+
icy_metadata_headers
+

If the server supports ICY metadata, this contains the ICY-specific HTTP reply +headers, separated by newline characters. +

+
+
icy_metadata_packet
+

If the server supports ICY metadata, and icy was set to 1, this +contains the last non-empty metadata packet sent by the server. It should be +polled in regular intervals by applications interested in mid-stream metadata +updates. +

+
+
metadata
+

Set an exported dictionary containing Icecast metadata from the bitstream, if present. +Only useful with the C API. +

+
+
auth_type
+
+

Set HTTP authentication type. No option for Digest, since this method requires +getting nonce parameters from the server first and can’t be used straight away like +Basic. +

+
+
none
+

Choose the HTTP authentication type automatically. This is the default. +

+
basic
+
+

Choose the HTTP basic authentication. +

+

Basic authentication sends a Base64-encoded string that contains a user name and password +for the client. Base64 is not a form of encryption and should be considered the same as +sending the user name and password in clear text (Base64 is a reversible encoding). +If a resource needs to be protected, strongly consider using an authentication scheme +other than basic authentication. HTTPS/TLS should be used with basic authentication. +Without these additional security enhancements, basic authentication should not be used +to protect sensitive or valuable information. +

+
+ +
+
send_expect_100
+

Send an Expect: 100-continue header for POST. If set to 1 it will send, if set +to 0 it won’t, if set to -1 it will try to send if it is applicable. Default +value is -1. +

+
+
location
+

An exported dictionary containing the content location. Only useful with the C +API. +

+
+
offset
+

Set initial byte offset. +

+
+
end_offset
+

Try to limit the request to bytes preceding this offset. +

+
+
method
+

When used as a client option it sets the HTTP method for the request. +

+

When used as a server option it sets the HTTP method that is going to be +expected from the client(s). +If the expected and the received HTTP method do not match the client will +be given a Bad Request response. +When unset the HTTP method is not checked for now. This will be replaced by +autodetection in the future. +

+
+
reconnect
+

Reconnect automatically when disconnected before EOF is hit. +

+
+
reconnect_at_eof
+

If set then eof is treated like an error and causes reconnection, this is useful +for live / endless streams. +

+
+
reconnect_on_network_error
+

Reconnect automatically in case of TCP/TLS errors during connect. +

+
+
reconnect_on_http_error
+

A comma separated list of HTTP status codes to reconnect on. The list can +include specific status codes (e.g. ’503’) or the strings ’4xx’ / ’5xx’. +

+
+
reconnect_streamed
+

If set then even streamed/non seekable streams will be reconnected on errors. +

+
+
reconnect_delay_max
+

Set the maximum delay in seconds after which to give up reconnecting. +

+
+
reconnect_max_retries
+

Set the maximum number of times to retry a connection. Default unset. +

+
+
reconnect_delay_total_max
+

Set the maximum total delay in seconds after which to give up reconnecting. +

+
+
respect_retry_after
+

If enabled, and a Retry-After header is encountered, its requested reconnection +delay will be honored, rather than using exponential backoff. Useful for 429 and +503 errors. Default enabled. +

+
+
listen
+

If set to 1 enables experimental HTTP server. This can be used to send data when +used as an output option, or read data from a client with HTTP POST when used as +an input option. +If set to 2 enables experimental multi-client HTTP server. This is not yet implemented +in ffmpeg.c and thus must not be used as a command line option. +

+
# Server side (sending):
+ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://server:port
+
+# Client side (receiving):
+ffmpeg -i http://server:port -c copy somefile.ogg
+
+# Client can also be done with wget:
+wget http://server:port -O somefile.ogg
+
+# Server side (receiving):
+ffmpeg -listen 1 -i http://server:port -c copy somefile.ogg
+
+# Client side (sending):
+ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://server:port
+
+# Client can also be done with wget:
+wget --post-file=somefile.ogg http://server:port
+
+ +
+
resource
+

The resource requested by a client, when the experimental HTTP server is in use. +

+
+
reply_code
+

The HTTP code returned to the client, when the experimental HTTP server is in use. +

+
+
short_seek_size
+

Set the threshold, in bytes, for when a readahead should be preferred over a seek and +new HTTP request. This is useful, for example, to make sure the same connection +is used for reading large video packets with small audio packets in between. +

+
+
+ + +

24.14.1 HTTP Cookies

+ +

Some HTTP requests will be denied unless cookie values are passed in with the +request. The cookies option allows these cookies to be specified. At +the very least, each cookie must specify a value along with a path and domain. +HTTP requests that match both the domain and path will automatically include the +cookie value in the HTTP Cookie header field. Multiple cookies can be delimited +by a newline. +

+

The required syntax to play a stream specifying a cookie is: +

+
ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
+
+ + +

24.15 Icecast

+ +

Icecast protocol (stream to Icecast servers) +

+

This protocol accepts the following options: +

+
+
ice_genre
+

Set the stream genre. +

+
+
ice_name
+

Set the stream name. +

+
+
ice_description
+

Set the stream description. +

+
+
ice_url
+

Set the stream website URL. +

+
+
ice_public
+

Set if the stream should be public. +The default is 0 (not public). +

+
+
user_agent
+

Override the User-Agent header. If not specified a string of the form +"Lavf/<version>" will be used. +

+
+
password
+

Set the Icecast mountpoint password. +

+
+
content_type
+

Set the stream content type. This must be set if it is different from +audio/mpeg. +

+
+
legacy_icecast
+

This enables support for Icecast versions < 2.4.0, that do not support the +HTTP PUT method but the SOURCE method. +

+
+
tls
+

Establish a TLS (HTTPS) connection to Icecast. +

+
+
+ +
+
icecast://[username[:password]@]server:port/mountpoint
+
+ + +

24.16 ipfs

+ +

InterPlanetary File System (IPFS) protocol support. One can access files stored +on the IPFS network through so-called gateways. These are http(s) endpoints. +This protocol wraps the IPFS native protocols (ipfs:// and ipns://) to be sent +to such a gateway. Users can (and should) host their own node which means this +protocol will use one’s local gateway to access files on the IPFS network. +

+

This protocol accepts the following options: +

+
+
gateway
+

Defines the gateway to use. When not set, the protocol will first try +locating the local gateway by looking at $IPFS_GATEWAY, $IPFS_PATH +and $HOME/.ipfs/, in that order. +

+
+
+ +

One can use this protocol in 2 ways. Using IPFS: +

+
ffplay ipfs://<hash>
+
+ +

Or the IPNS protocol (IPNS is mutable IPFS): +

+
ffplay ipns://<hash>
+
+ + +

24.17 mmst

+ +

MMS (Microsoft Media Server) protocol over TCP. +

+ +

24.18 mmsh

+ +

MMS (Microsoft Media Server) protocol over HTTP. +

+

The required syntax is: +

+
mmsh://server[:port][/app][/playpath]
+
+ + +

24.19 md5

+ +

MD5 output protocol. +

+

Computes the MD5 hash of the data to be written, and on close writes +this to the designated output or stdout if none is specified. It can +be used to test muxers without writing an actual file. +

+

Some examples follow. +

+
# Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
+ffmpeg -i input.flv -f avi -y md5:output.avi.md5
+
+# Write the MD5 hash of the encoded AVI file to stdout.
+ffmpeg -i input.flv -f avi -y md5:
+
+ +

Note that some formats (typically MOV) require the output protocol to +be seekable, so they will fail with the MD5 output protocol. +

+ +

24.20 pipe

+ +

UNIX pipe access protocol. +

+

Read and write from UNIX pipes. +

+

The accepted syntax is: +

+
pipe:[number]
+
+ +

If fd isn’t specified, number is the number corresponding to the file descriptor of the +pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If number +is not specified, by default the stdout file descriptor will be used +for writing, stdin for reading. +

+

For example to read from stdin with ffmpeg: +

+
cat test.wav | ffmpeg -i pipe:0
+# ...this is the same as...
+cat test.wav | ffmpeg -i pipe:
+
+ +

For writing to stdout with ffmpeg: +

+
ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
+# ...this is the same as...
+ffmpeg -i test.wav -f avi pipe: | cat > test.avi
+
+ +

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
fd
+

Set file descriptor. +

+
+ +

Note that some formats (typically MOV), require the output protocol to +be seekable, so they will fail with the pipe output protocol. +

+ +

24.21 prompeg

+ +

Pro-MPEG Code of Practice #3 Release 2 FEC protocol. +

+

The Pro-MPEG CoP#3 FEC is a 2D parity-check forward error correction mechanism +for MPEG-2 Transport Streams sent over RTP. +

+

This protocol must be used in conjunction with the rtp_mpegts muxer and +the rtp protocol. +

+

The required syntax is: +

+
-f rtp_mpegts -fec prompeg=option=val... rtp://hostname:port
+
+ +

The destination UDP ports are port + 2 for the column FEC stream +and port + 4 for the row FEC stream. +

+

This protocol accepts the following options: +

+
l=n
+

The number of columns (4-20, LxD <= 100) +

+
+
d=n
+

The number of rows (4-20, LxD <= 100) +

+
+
+ +

Example usage: +

+
+
-f rtp_mpegts -fec prompeg=l=8:d=4 rtp://hostname:port
+
+ + +

24.22 rist

+ +

Reliable Internet Streaming Transport protocol +

+

The accepted options are: +

+
rist_profile
+

Supported values: +

+
‘simple’
+
‘main’
+

This one is default. +

+
‘advanced’
+
+ +
+
buffer_size
+

Set internal RIST buffer size in milliseconds for retransmission of data. +Default value is 0 which means the librist default (1 sec). Maximum value is 30 +seconds. +

+
+
fifo_size
+

Size of the librist receiver output fifo in number of packets. This must be a +power of 2. +Defaults to 8192 (vs the librist default of 1024). +

+
+
overrun_nonfatal=1|0
+

Survive in case of librist fifo buffer overrun. Default value is 0. +

+
+
pkt_size
+

Set maximum packet size for sending data. 1316 by default. +

+
+
log_level
+

Set loglevel for RIST logging messages. You only need to set this if you +explicitly want to enable debug level messages or packet loss simulation, +otherwise the regular loglevel is respected. +

+
+
secret
+

Set override of encryption secret, by default is unset. +

+
+
encryption
+

Set encryption type, by default is disabled. +Acceptable values are 128 and 256. +

+
+ + +

24.23 rtmp

+ +

Real-Time Messaging Protocol. +

+

The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia +content across a TCP/IP network. +

+

The required syntax is: +

+
rtmp://[username:password@]server[:port][/app][/instance][/playpath]
+
+ +

The accepted parameters are: +

+
username
+

An optional username (mostly for publishing). +

+
+
password
+

An optional password (mostly for publishing). +

+
+
server
+

The address of the RTMP server. +

+
+
port
+

The number of the TCP port to use (by default is 1935). +

+
+
app
+

It is the name of the application to access. It usually corresponds to +the path where the application is installed on the RTMP server +(e.g. /ondemand/, /flash/live/, etc.). You can override +the value parsed from the URI through the rtmp_app option, too. +

+
+
playpath
+

It is the path or name of the resource to play with reference to the +application specified in app, may be prefixed by "mp4:". You +can override the value parsed from the URI through the rtmp_playpath +option, too. +

+
+
listen
+

Act as a server, listening for an incoming connection. +

+
+
timeout
+

Maximum time to wait for the incoming connection. Implies listen. +

+
+ +

Additionally, the following parameters can be set via command line options +(or in code via AVOptions): +

+
rtmp_app
+

Name of application to connect on the RTMP server. This option +overrides the parameter specified in the URI. +

+
+
rtmp_buffer
+

Set the client buffer time in milliseconds. The default is 3000. +

+
+
rtmp_conn
+

Extra arbitrary AMF connection parameters, parsed from a string, +e.g. like B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0. +Each value is prefixed by a single character denoting the type, +B for Boolean, N for number, S for string, O for object, or Z for null, +followed by a colon. For Booleans the data must be either 0 or 1 for +FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or +1 to end or begin an object, respectively. Data items in subobjects may +be named, by prefixing the type with ’N’ and specifying the name before +the value (i.e. NB:myFlag:1). This option may be used multiple +times to construct arbitrary AMF sequences. +

+
+
rtmp_enhanced_codecs
+

Specify the list of codecs the client advertises to support in an +enhanced RTMP stream. This option should be set to a comma separated +list of fourcc values, like hvc1,av01,vp09 for multiple codecs +or hvc1 for only one codec. The specified list will be presented +in the "fourCcLive" property of the Connect Command Message. +

+
+
rtmp_flashver
+

Version of the Flash plugin used to run the SWF player. The default +is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; +<libavformat version>).) +

+
+
rtmp_flush_interval
+

Number of packets flushed in the same request (RTMPT only). The default +is 10. +

+
+
rtmp_live
+

Specify that the media is a live stream. No resuming or seeking in +live streams is possible. The default value is any, which means the +subscriber first tries to play the live stream specified in the +playpath. If a live stream of that name is not found, it plays the +recorded stream. The other possible values are live and +recorded. +

+
+
rtmp_pageurl
+

URL of the web page in which the media was embedded. By default no +value will be sent. +

+
+
rtmp_playpath
+

Stream identifier to play or to publish. This option overrides the +parameter specified in the URI. +

+
+
rtmp_subscribe
+

Name of live stream to subscribe to. By default no value will be sent. +It is only sent if the option is specified or if rtmp_live +is set to live. +

+
+
rtmp_swfhash
+

SHA256 hash of the decompressed SWF file (32 bytes). +

+
+
rtmp_swfsize
+

Size of the decompressed SWF file, required for SWFVerification. +

+
+
rtmp_swfurl
+

URL of the SWF player for the media. By default no value will be sent. +

+
+
rtmp_swfverify
+

URL to player swf file, compute hash/size automatically. +

+
+
rtmp_tcurl
+

URL of the target stream. Defaults to proto://host[:port]/app. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_keepalive=1|0
+

Enable the TCP keepalive mechanism to detect dead peers and help maintain long-lived idle connections. Default value is 0. +

+

Only the basic keepalive option (SO_KEEPALIVE) can be enabled or disabled. Platform-specific tuning parameters such as TCP_KEEPIDLE, TCP_KEEPINTVL, or TCP_KEEPCNT are not configurable and will use the operating system’s default values. +

+
+
+ +

For example to read with ffplay a multimedia resource named +"sample" from the application "vod" from an RTMP server "myserver": +

+
ffplay rtmp://myserver/vod/sample
+
+ +

To publish to a password protected server, passing the playpath and +app names separately: +

+
ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@myserver/
+
+ + +

24.24 rtmpe

+ +

Encrypted Real-Time Messaging Protocol. +

+

The Encrypted Real-Time Messaging Protocol (RTMPE) is used for +streaming multimedia content within standard cryptographic primitives, +consisting of Diffie-Hellman key exchange and HMACSHA256, generating +a pair of RC4 keys. +

+ +

24.25 rtmps

+ +

Real-Time Messaging Protocol over a secure SSL connection. +

+

The Real-Time Messaging Protocol (RTMPS) is used for streaming +multimedia content across an encrypted connection. +

+ +

24.26 rtmpt

+ +

Real-Time Messaging Protocol tunneled through HTTP. +

+

The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used +for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

24.27 rtmpte

+ +

Encrypted Real-Time Messaging Protocol tunneled through HTTP. +

+

The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) +is used for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

24.28 rtmpts

+ +

Real-Time Messaging Protocol tunneled through HTTPS. +

+

The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used +for streaming multimedia content within HTTPS requests to traverse +firewalls. +

+ +

24.29 libsmbclient

+ +

libsmbclient permits one to manipulate CIFS/SMB network resources. +

+

Following syntax is required. +

+
+
smb://[[domain:]user[:password@]]server[/share[/path[/file]]]
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in milliseconds 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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
workgroup
+

Set the workgroup used for making connections. By default workgroup is not specified. +

+
+
+ +

For more information see: http://www.samba.org/. +

+ +

24.30 libssh

+ +

Secure File Transfer Protocol via libssh +

+

Read from or write to remote resources using SFTP protocol. +

+

Following syntax is required. +

+
+
sftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
private_key
+

Specify the path of the file containing private key to use during authorization. +By default libssh searches for keys in the ~/.ssh/ directory. +

+
+
+ +

Example: Play a file stored on remote server. +

+
+
ffplay sftp://user:password@server_address:22/home/user/resource.mpeg
+
+ + +

24.31 librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte

+ +

Real-Time Messaging Protocol and its variants supported through +librtmp. +

+

Requires the presence of the librtmp headers and library during +configuration. You need to explicitly configure the build with +"–enable-librtmp". If enabled this will replace the native RTMP +protocol. +

+

This protocol provides most client functions and a few server +functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), +encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled +variants of these encrypted types (RTMPTE, RTMPTS). +

+

The required syntax is: +

+
rtmp_proto://server[:port][/app][/playpath] options
+
+ +

where rtmp_proto is one of the strings "rtmp", "rtmpt", "rtmpe", +"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and +server, port, app and playpath have the same +meaning as specified for the RTMP native protocol. +options contains a list of space-separated options of the form +key=val. +

+

See the librtmp manual page (man 3 librtmp) for more information. +

+

For example, to stream a file in real-time to an RTMP server using +ffmpeg: +

+
ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
+
+ +

To play the same stream using ffplay: +

+
ffplay "rtmp://myserver/live/mystream live=1"
+
+ + +

24.32 rtp

+ +

Real-time Transport Protocol. +

+

The required syntax for an RTP URL is: +

+
rtp://hostname[:port][?options]
+
+ +

port specifies the RTP port to use. +

+

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ttl=n
+

Set the TTL (Time-To-Live) value (for multicast only). +

+
+
rtcpport=n
+

Set the remote RTCP port to n. +

+
+
localport, local_rtpport, localrtpport=n
+

Set the local RTP port to n. +

+

Using the localport option name is deprecated and should not be used. +

+
+
local_rtcpport, localrtcpport=n'
+

Set the local RTCP port to n. +

+
+
pkt_size=n
+

Set max packet size (in bytes) to n. +

+
+
buffer_size=size
+

Set the maximum UDP socket buffer size in bytes. +

+
+
connect=0|1
+

Do a connect() on the UDP socket (if set to 1) or not (if set +to 0). +

+
+
sources=ip[,ip]
+

List allowed source IP addresses. +

+
+
block=ip[,ip]
+

List disallowed (blocked) source IP addresses. +

+
+
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). +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
timeout=n
+

Set timeout (in microseconds) of socket I/O operations to n. +

+
+ +

Important notes: +

+
    +
  1. If rtcpport is not set the RTCP port will be set to the RTP +port value plus 1. + +
  2. If localrtpport (the local RTP port) is not set any available +port will be used for the local RTP and RTCP ports. + +
  3. If localrtcpport (the local RTCP port) is not set it will be +set to the local RTP port value plus 1. +
+ + +

24.33 rtsp

+ +

Real-Time Streaming Protocol. +

+

RTSP is not technically a protocol handler in libavformat, it is a demuxer +and muxer. The demuxer supports both normal RTSP (with data transferred +over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with +data transferred over RDT). +

+

The muxer can be used to send a stream using RTSP ANNOUNCE to a server +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock’s +RTSP server). +

+

The required syntax for a RTSP url is: +

+
rtsp://hostname[:port]/path
+
+ +

Options can be set on the ffmpeg/ffplay command +line, or set in code via AVOptions or in +avformat_open_input. +

+ +

24.33.1 Muxer

+

The following options are supported. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+ +

Default value is ‘0’. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘latm’
+

Use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC. +

+
‘rfc2190’
+

Use RFC 2190 packetization instead of RFC 4629 for H.263. +

+
‘skip_rtcp’
+

Don’t send RTCP sender reports. +

+
‘h264_mode0’
+

Use mode 0 for H.264 in RTP. +

+
‘send_bye’
+

Send RTCP BYE packets when finishing. +

+
+ +

Default value is ‘0’. +

+ +
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+
pkt_size
+

Set max send packet size (in bytes). Default value is 1472. +

+
+ + +

24.33.2 Demuxer

+

The following options are supported. +

+
+
initial_pause
+

Do not start playing the stream immediately if set to 1. Default value +is 0. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+
‘udp_multicast’
+

Use UDP multicast as lower transport protocol. +

+
+
‘http’
+

Use HTTP tunneling as lower transport protocol, which is useful for +passing proxies. +

+
+
‘https’
+

Use HTTPs tunneling as lower transport protocol, which is useful for +passing proxies and widely used for security consideration. +

+
+ +

Multiple lower transport protocols may be specified, in that case they are +tried one at a time (if the setup of one fails, the next one is tried). +For the muxer, only the ‘tcp’ and ‘udp’ options are supported. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘filter_src’
+

Accept packets only from negotiated peer address and port. +

+
‘listen’
+

Act as a server, listening for an incoming connection. +

+
‘prefer_tcp’
+

Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. +

+
‘satip_raw’
+

Export raw MPEG-TS stream instead of demuxing. The flag will simply write out +the raw stream, with the original PAT/PMT/PIDs intact. +

+
+ +

Default value is ‘none’. +

+
+
allowed_media_types
+

Set media types to accept from the server. +

+

The following flags are accepted: +

+
‘video’
+
‘audio’
+
‘data’
+
‘subtitle’
+
+ +

By default it accepts all media types. +

+
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
listen_timeout
+

Set maximum timeout (in seconds) to establish an initial connection. Setting +listen_timeout > 0 sets rtsp_flags to ‘listen’. Default is -1 +which means an infinite timeout when ‘listen’ mode is set. +

+
+
reorder_queue_size
+

Set number of packets to buffer for handling of reordered packets. +

+
+
timeout
+

Set socket TCP I/O timeout in microseconds. +

+
+
user_agent
+

Override User-Agent header. If not specified, it defaults to the +libavformat identifier string. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+ +

When receiving data over UDP, the demuxer tries to reorder received packets +(since they may arrive out of order, or packets may get lost totally). This +can be disabled by setting the maximum demuxing delay to zero (via +the max_delay field of AVFormatContext). +

+

When watching multi-bitrate Real-RTSP streams with ffplay, the +streams to display can be chosen with -vst n and +-ast n for video and audio respectively, and can be switched +on the fly by pressing v and a. +

+ +

24.33.3 Examples

+ +

The following examples all make use of the ffplay and +ffmpeg tools. +

+
    +
  • Watch a stream over UDP, with a max reordering delay of 0.5 seconds: +
    +
    ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
    +
    + +
  • Watch a stream tunneled over HTTP: +
    +
    ffplay -rtsp_transport http rtsp://server/video.mp4
    +
    + +
  • Send a stream in realtime to a RTSP server, for others to watch: +
    +
    ffmpeg -re -i input -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
    +
    + +
  • Receive a stream in realtime: +
    +
    ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp output
    +
    +
+ + +

24.34 sap

+ +

Session Announcement Protocol (RFC 2974). This is not technically a +protocol handler in libavformat, it is a muxer and demuxer. +It is used for signalling of RTP streams, by announcing the SDP for the +streams regularly on a separate port. +

+ +

24.34.1 Muxer

+ +

The syntax for a SAP url given to the muxer is: +

+
sap://destination[:port][?options]
+
+ +

The RTP packets are sent to destination on port port, +or to port 5004 if no port is specified. +options is a &-separated list. The following options +are supported: +

+
+
announce_addr=address
+

Specify the destination IP address for sending the announcements to. +If omitted, the announcements are sent to the commonly used SAP +announcement multicast address 224.2.127.254 (sap.mcast.net), or +ff0e::2:7ffe if destination is an IPv6 address. +

+
+
announce_port=port
+

Specify the port to send the announcements on, defaults to +9875 if not specified. +

+
+
ttl=ttl
+

Specify the time to live value for the announcements and RTP packets, +defaults to 255. +

+
+
same_port=0|1
+

If set to 1, send all RTP streams on the same port pair. If zero (the +default), all streams are sent on unique ports, with each stream on a +port 2 numbers higher than the previous. +VLC/Live555 requires this to be set to 1, to be able to receive the stream. +The RTP stack in libavformat for receiving requires all streams to be sent +on unique ports. +

+
+ +

Example command lines follow. +

+

To broadcast a stream on the local subnet, for watching in VLC: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255?same_port=1
+
+ +

Similarly, for watching in ffplay: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255
+
+ +

And for watching in ffplay, over IPv6: +

+
+
ffmpeg -re -i input -f sap sap://[ff0e::1:2:3:4]
+
+ + +

24.34.2 Demuxer

+ +

The syntax for a SAP url given to the demuxer is: +

+
sap://[address][:port]
+
+ +

address is the multicast address to listen for announcements on, +if omitted, the default 224.2.127.254 (sap.mcast.net) is used. port +is the port that is listened on, 9875 if omitted. +

+

The demuxers listens for announcements on the given address and port. +Once an announcement is received, it tries to receive that particular stream. +

+

Example command lines follow. +

+

To play back the first stream announced on the normal SAP multicast address: +

+
+
ffplay sap://
+
+ +

To play back the first stream announced on one the default IPv6 SAP multicast address: +

+
+
ffplay sap://[ff0e::2:7ffe]
+
+ + +

24.35 sctp

+ +

Stream Control Transmission Protocol. +

+

The accepted URL syntax is: +

+
sctp://host:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen
+

If set to any value, listen for an incoming connection. Outgoing connection is done by default. +

+
+
max_streams
+

Set the maximum number of streams. By default no limit is set. +

+
+ + +

24.36 srt

+ +

Haivision Secure Reliable Transport Protocol via libsrt. +

+

The supported syntax for a SRT URL is: +

+
srt://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
connect_timeout=milliseconds
+

Connection timeout; SRT cannot connect for RTT > 1500 msec +(2 handshake exchanges) with the default connect timeout of +3 seconds. This option applies to the caller and rendezvous +connection modes. The connect timeout is 10 times the value +set for the rendezvous mode (which can be used as a +workaround for this connection problem with earlier versions). +

+
+
ffs=bytes
+

Flight Flag Size (Window Size), in bytes. FFS is actually an +internal parameter and you should set it to not less than +recv_buffer_size and mss. The default value +is relatively large, therefore unless you set a very large receiver buffer, +you do not need to change this option. Default value is 25600. +

+
+
inputbw=bytes/seconds
+

Sender nominal input rate, in bytes per seconds. Used along with +oheadbw, when maxbw is set to relative (0), to +calculate maximum sending rate when recovery packets are sent +along with the main media stream: +inputbw * (100 + oheadbw) / 100 +if inputbw is not set while maxbw is set to +relative (0), the actual input rate is evaluated inside +the library. Default value is 0. +

+
+
iptos=tos
+

IP Type of Service. Applies to sender only. Default value is 0xB8. +

+
+
ipttl=ttl
+

IP Time To Live. Applies to sender only. Default value is 64. +

+
+
latency=microseconds
+

Timestamp-based Packet Delivery Delay. +Used to absorb bursts of missed packet retransmissions. +This flag sets both rcvlatency and peerlatency +to the same value. Note that prior to version 1.3.0 +this is the only flag to set the latency, however +this is effectively equivalent to setting peerlatency, +when side is sender and rcvlatency +when side is receiver, and the bidirectional stream +sending is not supported. +

+
+
listen_timeout=microseconds
+

Set socket listen timeout. +

+
+
maxbw=bytes/seconds
+

Maximum sending bandwidth, in bytes per seconds. +-1 infinite (CSRTCC limit is 30mbps) +0 relative to input rate (see inputbw) +>0 absolute limit value +Default value is 0 (relative) +

+
+
mode=caller|listener|rendezvous
+

Connection mode. +caller opens client connection. +listener starts server to listen for incoming connections. +rendezvous use Rendez-Vous connection mode. +Default value is caller. +

+
+
mss=bytes
+

Maximum Segment Size, in bytes. Used for buffer allocation +and rate calculation using a packet counter assuming fully +filled packets. The smallest MSS between the peers is +used. This is 1500 by default in the overall internet. +This is the maximum size of the UDP packet and can be +only decreased, unless you have some unusual dedicated +network settings. Default value is 1500. +

+
+
nakreport=1|0
+

If set to 1, Receiver will send ‘UMSG_LOSSREPORT‘ messages +periodically until a lost packet is retransmitted or +intentionally dropped. Default value is 1. +

+
+
oheadbw=percents
+

Recovery bandwidth overhead above input rate, in percents. +See inputbw. Default value is 25%. +

+
+
passphrase=string
+

HaiCrypt Encryption/Decryption Passphrase string, length +from 10 to 79 characters. The passphrase is the shared +secret between the sender and the receiver. It is used +to generate the Key Encrypting Key using PBKDF2 +(Password-Based Key Derivation Function). It is used +only if pbkeylen is non-zero. It is used on +the receiver only if the received data is encrypted. +The configured passphrase cannot be recovered (write-only). +

+
+
enforced_encryption=1|0
+

If true, both connection parties must have the same password +set (including empty, that is, with no encryption). If the +password doesn’t match or only one side is unencrypted, +the connection is rejected. Default is true. +

+
+
kmrefreshrate=packets
+

The number of packets to be transmitted after which the +encryption key is switched to a new key. Default is -1. +-1 means auto (0x1000000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
kmpreannounce=packets
+

The interval between when a new encryption key is sent and +when switchover occurs. This value also applies to the +subsequent interval between when switchover occurs and +when the old encryption key is decommissioned. Default is -1. +-1 means auto (0x1000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
snddropdelay=microseconds
+

The sender’s extra delay before dropping packets. This delay is +added to the default drop delay time interval value. +

+

Special value -1: Do not drop packets on the sender at all. +

+
+
payload_size=bytes
+

Sets the maximum declared size of a packet transferred +during the single call to the sending function in Live +mode. Use 0 if this value isn’t used (which is default in +file mode). +Default is -1 (automatic), which typically means MPEG-TS; +if you are going to use SRT +to send any different kind of payload, such as, for example, +wrapping a live stream in very small frames, then you can +use a bigger maximum frame size, though not greater than +1456 bytes. +

+
+
pkt_size=bytes
+

Alias for ‘payload_size’. +

+
+
peerlatency=microseconds
+

The latency value (as described in rcvlatency) that is +set by the sender side as a minimum value for the receiver. +

+
+
pbkeylen=bytes
+

Sender encryption key length, in bytes. +Only can be set to 0, 16, 24 and 32. +Enable sender encryption if not 0. +Not required on receiver (set to 0), +key size obtained from sender in HaiCrypt handshake. +Default value is 0. +

+
+
rcvlatency=microseconds
+

The time that should elapse since the moment when the +packet was sent and the moment when it’s delivered to +the receiver application in the receiving function. +This time should be a buffer time large enough to cover +the time spent for sending, unexpectedly extended RTT +time, and the time needed to retransmit the lost UDP +packet. The effective latency value will be the maximum +of this options’ value and the value of peerlatency +set by the peer side. Before version 1.3.0 this option +is only available as latency. +

+
+
recv_buffer_size=bytes
+

Set UDP receive buffer size, expressed in bytes. +

+
+
send_buffer_size=bytes
+

Set UDP send buffer size, expressed in bytes. +

+
+
timeout=microseconds
+

Set raise error timeouts for read, write and connect operations. Note that the +SRT library has internal timeouts which can be controlled separately, the +value set here is only a cap on those. +

+
+
tlpktdrop=1|0
+

Too-late Packet Drop. When enabled on receiver, it skips +missing packets that have not been delivered in time and +delivers the following packets to the application when +their time-to-play has come. It also sends a fake ACK to +the sender. When enabled on sender and enabled on the +receiving peer, the sender drops the older packets that +have no chance of being delivered in time. It was +automatically enabled in the sender if the receiver +supports it. +

+
+
sndbuf=bytes
+

Set send buffer size, expressed in bytes. +

+
+
rcvbuf=bytes
+

Set receive buffer size, expressed in bytes. +

+

Receive buffer must not be greater than ffs. +

+
+
lossmaxttl=packets
+

The value up to which the Reorder Tolerance may grow. When +Reorder Tolerance is > 0, then packet loss report is delayed +until that number of packets come in. Reorder Tolerance +increases every time a "belated" packet has come, but it +wasn’t due to retransmission (that is, when UDP packets tend +to come out of order), with the difference between the latest +sequence and this packet’s sequence, and not more than the +value of this option. By default it’s 0, which means that this +mechanism is turned off, and the loss report is always sent +immediately upon experiencing a "gap" in sequences. +

+
+
minversion
+

The minimum SRT version that is required from the peer. A connection +to a peer that does not satisfy the minimum version requirement +will be rejected. +

+

The version format in hex is 0xXXYYZZ for x.y.z in human readable +form. +

+
+
streamid=string
+

A string limited to 512 characters that can be set on the socket prior +to connecting. This stream ID will be able to be retrieved by the +listener side from the socket that is returned from srt_accept and +was connected by a socket with that set stream ID. SRT does not enforce +any special interpretation of the contents of this string. +This option doesn’t make sense in Rendezvous connection; the result +might be that simply one side will override the value from the other +side and it’s the matter of luck which one would win +

+
+
srt_streamid=string
+

Alias for ‘streamid’ to avoid conflict with ffmpeg command line option. +

+
+
smoother=live|file
+

The type of Smoother used for the transmission for that socket, which +is responsible for the transmission and congestion control. The Smoother +type must be exactly the same on both connecting parties, otherwise +the connection is rejected. +

+
+
messageapi=1|0
+

When set, this socket uses the Message API, otherwise it uses Buffer +API. Note that in live mode (see transtype) there’s only +message API available. In File mode you can chose to use one of two modes: +

+

Stream API (default, when this option is false). In this mode you may +send as many data as you wish with one sending instruction, or even use +dedicated functions that read directly from a file. The internal facility +will take care of any speed and congestion control. When receiving, you +can also receive as many data as desired, the data not extracted will be +waiting for the next call. There is no boundary between data portions in +the Stream mode. +

+

Message API. In this mode your single sending instruction passes exactly +one piece of data that has boundaries (a message). Contrary to Live mode, +this message may span across multiple UDP packets and the only size +limitation is that it shall fit as a whole in the sending buffer. The +receiver shall use as large buffer as necessary to receive the message, +otherwise the message will not be given up. When the message is not +complete (not all packets received or there was a packet loss) it will +not be given up. +

+
+
transtype=live|file
+

Sets the transmission type for the socket, in particular, setting this +option sets multiple other parameters to their default values as required +for a particular transmission type. +

+

live: Set options as for live transmission. In this mode, you should +send by one sending instruction only so many data that fit in one UDP packet, +and limited to the value defined first in payload_size (1316 is +default in this mode). There is no speed control in this mode, only the +bandwidth control, if configured, in order to not exceed the bandwidth with +the overhead transmission (retransmitted and control packets). +

+

file: Set options as for non-live transmission. See messageapi +for further explanations +

+
+
linger=seconds
+

The number of seconds that the socket waits for unsent data when closing. +Default is -1. -1 means auto (off with 0 seconds in live mode, on with 180 +seconds in file mode). The range for this option is integers in the +0 - INT_MAX. +

+
+
tsbpd=1|0
+

When true, use Timestamp-based Packet Delivery mode. The default behavior +depends on the transmission type: enabled in live mode, disabled in file +mode. +

+
+
+ +

For more information see: https://github.com/Haivision/srt. +

+ +

24.37 srtp

+ +

Secure Real-time Transport Protocol. +

+

The accepted options are: +

+
srtp_in_suite
+
srtp_out_suite
+

Select input and output encoding suites. +

+

Supported values: +

+
‘AES_CM_128_HMAC_SHA1_80’
+
‘SRTP_AES128_CM_HMAC_SHA1_80’
+
‘AES_CM_128_HMAC_SHA1_32’
+
‘SRTP_AES128_CM_HMAC_SHA1_32’
+
+ +
+
srtp_in_params
+
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. +

+
+ + +

24.38 subfile

+ +

Virtually extract a segment of a file or another stream. +The underlying stream must be seekable. +

+

Accepted options: +

+
start
+

Start offset of the extracted segment, in bytes. +

+
end
+

End offset of the extracted segment, in bytes. +If set to 0, extract till end of file. +

+
+ +

Examples: +

+

Extract a chapter from a DVD VOB file (start and end sectors obtained +externally and multiplied by 2048): +

+
subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
+
+ +

Play an AVI file directly from a TAR archive: +

+
subfile,,start,183241728,end,366490624,,:archive.tar
+
+ +

Play a MPEG-TS file from start offset till end: +

+
subfile,,start,32815239,end,0,,:video.ts
+
+ + +

24.39 tee

+ +

Writes the output to multiple protocols. The individual outputs are separated +by | +

+
+
tee:file://path/to/local/this.avi|file://path/to/local/that.avi
+
+ + +

24.40 tcp

+ +

Transmission Control Protocol. +

+

The required syntax for a TCP url is: +

+
tcp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen=2|1|0
+

Listen for an incoming connection. 0 disables listen, 1 enables listen in +single client mode, 2 enables listen in multi-client mode. Default value is 0. +

+
+
local_addr=addr
+

Local IP address of a network interface used for tcp socket connect. +

+
+
local_port=port
+

Local port used for tcp socket connect. +

+
+
timeout=microseconds
+

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. +

+
+
listen_timeout=milliseconds
+

Set listen timeout, expressed in milliseconds. +

+
+
recv_buffer_size=bytes
+

Set receive buffer size, expressed bytes. +

+
+
send_buffer_size=bytes
+

Set send buffer size, expressed bytes. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_mss=bytes
+

Set maximum segment size for outgoing TCP packets, expressed in bytes. +

+
+ +

The following example shows how to setup a listening TCP connection +with ffmpeg, which is then accessed with ffplay: +

+
ffmpeg -i input -f format tcp://hostname:port?listen
+ffplay tcp://hostname:port
+
+ + +

24.41 tls

+ +

Transport Layer Security (TLS) / Secure Sockets Layer (SSL) +

+

The required syntax for a TLS/SSL url is: +

+
tls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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 other backends, +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. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
http_proxy
+

The HTTP proxy to tunnel through, e.g. http://example.com:1234. +The proxy must support the CONNECT method. +

+
+
+ +

Example command lines: +

+

To create a TLS/SSL server that serves an input stream. +

+
+
ffmpeg -i input -f format tls://hostname:port?listen&cert=server.crt&key=server.key
+
+ +

To play back a stream from the TLS/SSL server using ffplay: +

+
+
ffplay tls://hostname:port
+
+ + +

24.42 dtls

+ +

Datagram Transport Layer Security (DTLS) +

+

The required syntax for a DTLS URL is: +

+
dtls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

DTLS shares most options with TLS, but operates over UDP instead of TCP. +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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. +

+

This is disabled by default since it requires a CA database to be +provided by the caller in many cases. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
cert_pem=string
+

Certificate PEM string +

+
+
key_pem=string
+

Private key PEM string +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
mtu=size
+

Set the Maximum Transmission Unit (MTU) for DTLS packets. +

+
+
use_srtp=1|0
+

Enable the use_srtp DTLS extension. +This is used in WebRTC applications to establish SRTP encryption keys +through the DTLS handshake. Default is disabled. +

+
+
external_sock=1|0
+

Use an external socket instead of creating a new one. +This option only makes sense to pass when interacting with the code via +API, enabling this from CLI will cause immediate failure. +Default is disabled. +

+
+
+ +

Example command lines: +

+

To create a DTLS server: +

+
+
ffmpeg -listen 1 -i dtls://hostname:port output
+
+ +

To create a DTLS client and send data to server: +

+
+
ffmpeg -i input -f format dtls://hostname:port
+
+ + +

24.43 udp

+ +

User Datagram Protocol. +

+

The required syntax for an UDP URL is: +

+
udp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

In case threading is enabled on the system, a circular buffer is used +to store the incoming data, which allows one to reduce loss of data due to +UDP socket buffer overruns. The fifo_size and +overrun_nonfatal options are related to this buffer. +

+

The list of supported options follows. +

+
+
buffer_size=size
+

Set the UDP maximum socket buffer size in bytes. This is used to set either +the receive or send buffer size, depending on what the socket is used for. +Default is 32 KB for output, 384 KB for input. See also fifo_size. +

+
+
bitrate=bitrate
+

If set to nonzero, the output will have the specified constant bitrate if the +input has enough packets to sustain it. +

+
+
burst_bits=bits
+

When using bitrate this specifies the maximum number of bits in +packet bursts. +

+
+
localport=port
+

Override the local UDP port to bind with. +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
pkt_size=size
+

Set the size in bytes of UDP packets. +

+
+
reuse=1|0
+

Explicitly allow or disallow reusing UDP sockets. +

+
+
ttl=ttl
+

Set the time to live value (for multicast only). +

+
+
dscp=dscp
+

Set the 6-bit DSCP field for outgoing packets. +

+
+
connect=1|0
+

Initialize the UDP socket with connect(). In this case, the +destination address can’t be changed with ff_udp_set_remote_url later. +If the destination address isn’t known at the start, this option can +be specified in ff_udp_set_remote_url, too. +This allows finding out the source address for the packets with getsockname, +and makes writes return with AVERROR(ECONNREFUSED) if "destination +unreachable" is received. +For receiving, this gives the benefit of only receiving packets from +the specified peer address/port. +

+
+
sources=address[,address]
+

Only receive packets sent from the specified addresses. In case of multicast, +also subscribe to multicast traffic coming from these addresses only. +

+
+
block=address[,address]
+

Ignore packets sent from the specified addresses. In case of multicast, also +exclude the source addresses in the multicast subscription. +

+
+
fifo_size=units
+

Set the UDP receiving circular buffer size, expressed as a number of +packets with size of 188 bytes. If not specified defaults to 7*4096. +

+
+
overrun_nonfatal=1|0
+

Survive in case of UDP receiving circular buffer overrun. Default +value is 0. +

+
+
timeout=microseconds
+

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. +

+
+
broadcast=1|0
+

Explicitly allow or disallow UDP broadcasting. +

+

Note that broadcasting may not work properly on networks having +a broadcast storm protection. +

+
+ + +

24.43.1 Examples

+ +
    +
  • Use ffmpeg to stream over UDP to a remote endpoint: +
    +
    ffmpeg -i input -f format udp://hostname:port
    +
    + +
  • Use ffmpeg to stream in mpegts format over UDP using 188 +sized UDP packets, using a large input buffer: +
    +
    ffmpeg -i input -f mpegts udp://hostname:port?pkt_size=188&buffer_size=65535
    +
    + +
  • Use ffmpeg to receive over UDP from a remote endpoint: +
    +
    ffmpeg -i udp://[multicast-address]:port ...
    +
    +
+ + +

24.44 unix

+ +

Unix local socket +

+

The required syntax for a Unix socket URL is: +

+
+
unix://filepath
+
+ +

The following parameters can be set via command line options +(or in code via AVOptions): +

+
+
timeout
+

Timeout in ms. +

+
listen
+

Create the Unix socket in listening mode. +

+
type
+

Select socket type. +

+
‘stream Corresponds to SOCK_STREAM (reliable stream-oriented)’
+
‘datagram Corresponds to SOCK_DGRAM (unreliable packet-oriented)’
+
‘seqpacket Corresponds to SOCK_SEQPACKET (reliable packet-oriented)’
+
+
+
pkt_size
+

Maximum packet size for packet-oriented sockets (SOCK_DGRAM and +SOCK_SEQPACKET). If greater than zero, this value is used as +max_packet_size. Ignored for SOCK_STREAM. Default is 0. +

+
+ + +

24.45 zmq

+ +

ZeroMQ asynchronous messaging using the libzmq library. +

+

This library supports unicast streaming to multiple clients without relying on +an external server. +

+

The required syntax for streaming or connecting to a stream is: +

+
zmq:tcp://ip-address:port
+
+ +

Example: +Create a localhost stream on port 5555: +

+
ffmpeg -re -i input -f mpegts zmq:tcp://127.0.0.1:5555
+
+ +

Multiple clients may connect to the stream using: +

+
ffplay zmq:tcp://127.0.0.1:5555
+
+ +

Streaming to multiple clients is implemented using a ZeroMQ Pub-Sub pattern. +The server side binds to a port and publishes data. Clients connect to the +server (via IP address/port) and subscribe to the stream. The order in which +the server and client start generally does not matter. +

+

ffmpeg must be compiled with the –enable-libzmq option to support +this protocol. +

+

Options can be set on the ffmpeg/ffplay command +line. The following options are supported: +

+
+
pkt_size
+

Forces the maximum packet size for sending/receiving data. The default value is +131,072 bytes. On the server side, this sets the maximum size of sent packets +via ZeroMQ. On the clients, it sets an internal buffer size for receiving +packets. Note that pkt_size on the clients should be equal to or greater than +pkt_size on the server. Otherwise the received message may be truncated causing +decoding errors. +

+
+
+ + +

25 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the device +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+ + +

26 Input Devices

+ +

Input devices are configured elements in FFmpeg which enable accessing +the data coming from a multimedia device attached to your system. +

+

When you configure your FFmpeg build, all the supported input devices +are enabled by default. You can list all available ones using the +configure option "–list-indevs". +

+

You can disable all the input devices using the configure option +"–disable-indevs", and selectively enable an input device using the +option "–enable-indev=INDEV", or you can disable a particular +input device using the option "–disable-indev=INDEV". +

+

The option "-devices" of the ff* tools will display the list of +supported input devices. +

+

A description of the currently available input devices follows. +

+ +

26.1 alsa

+ +

ALSA (Advanced Linux Sound Architecture) input device. +

+

To enable this input device during configuration you need libasound +installed on your system. +

+

This device allows capturing from an ALSA device. The name of the +device to capture has to be an ALSA card identifier. +

+

An ALSA identifier has the syntax: +

+
hw:CARD[,DEV[,SUBDEV]]
+
+ +

where the DEV and SUBDEV components are optional. +

+

The three arguments (in order: CARD,DEV,SUBDEV) +specify card number or identifier, device number and subdevice number +(-1 means any). +

+

To see the list of cards currently recognized by your system check the +files /proc/asound/cards and /proc/asound/devices. +

+

For example to capture with ffmpeg from an ALSA device with +card id 0, you may run the command: +

+
ffmpeg -f alsa -i hw:0 alsaout.wav
+
+ +

For more information see: +http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html +

+ +

26.1.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

26.2 android_camera

+ +

Android camera input device. +

+

This input devices uses the Android Camera2 NDK API which is +available on devices with API level 24+. The availability of +android_camera is autodetected during configuration. +

+

This device allows capturing from all cameras on an Android device, +which are integrated into the Camera2 NDK API. +

+

The available cameras are enumerated internally and can be selected +with the camera_index parameter. The input file string is +discarded. +

+

Generally the back facing camera has index 0 while the front facing +camera has index 1. +

+ +

26.2.1 Options

+ +
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Falls back to the first available configuration reported by +Android if requested video size is not available or by default. +

+
+
framerate
+

Set the video framerate. +Falls back to the first available configuration reported by +Android if requested framerate is not available or by default (-1). +

+
+
camera_index
+

Set the index of the camera to use. Default is 0. +

+
+
input_queue_size
+

Set the maximum number of frames to buffer. Default is 5. +

+
+
+ + +

26.3 avfoundation

+ +

AVFoundation input device. +

+

AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS. +

+

The input filename has to be given in the following syntax: +

+
-i "[[VIDEO]:[AUDIO]]"
+
+

The first entry selects the video input while the latter selects the audio input. +The stream has to be specified by the device name or the device index as shown by the device list. +Alternatively, the video and/or audio input device can be chosen by index using the + + -video_device_index <INDEX> + +and/or + + -audio_device_index <INDEX> + +, overriding any +device name or index given in the input filename. +

+

All available devices can be enumerated by using -list_devices true, listing +all device names and corresponding indices. +

+

There are two device name aliases: +

+
default
+

Select the AVFoundation default device of the corresponding type. +

+
+
none
+

Do not record the corresponding media type. +This is equivalent to specifying an empty device name or index. +

+
+
+ + +

26.3.1 Options

+ +

AVFoundation supports the following options: +

+
+
-list_devices <TRUE|FALSE>
+

If set to true, a list of all available input devices is given showing all +device names and indices. +

+
+
-video_device_index <INDEX>
+

Specify the video device by its index. Overrides anything given in the input filename. +

+
+
-audio_device_index <INDEX>
+

Specify the audio device by its index. Overrides anything given in the input filename. +

+
+
-pixel_format <FORMAT>
+

Request the video device to use a specific pixel format. +If the specified format is not supported, a list of available formats is given +and the first one in this list is used instead. Available pixel formats are: +monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0, + bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10, + yuv420p, nv12, yuyv422, gray +

+
+
-framerate
+

Set the grabbing frame rate. Default is ntsc, corresponding to a +frame rate of 30000/1001. +

+
+
-video_size
+

Set the video frame size. +

+
+
-capture_cursor
+

Capture the mouse pointer. Default is 0. +

+
+
-capture_mouse_clicks
+

Capture the screen mouse clicks. Default is 0. +

+
+
-capture_raw_data
+

Capture the raw device data. Default is 0. +Using this option may result in receiving the underlying data delivered to the AVFoundation framework. E.g. for muxed devices that sends raw DV data to the framework (like tape-based camcorders), setting this option to false results in extracted video frames captured in the designated pixel format only. Setting this option to true results in receiving the raw DV stream untouched. +

+
+ + +

26.3.2 Examples

+ +
    +
  • Print the list of AVFoundation supported devices and exit: +
    +
    $ ffmpeg -f avfoundation -list_devices true -i ""
    +
    + +
  • Record video from video device 0 and audio from audio device 0 into out.avi: +
    +
    $ ffmpeg -f avfoundation -i "0:0" out.avi
    +
    + +
  • Record video from video device 2 and audio from audio device 1 into out.avi: +
    +
    $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi
    +
    + +
  • Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi: +
    +
    $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi
    +
    + +
  • Record raw DV data from a suitable input device and write the output into out.dv: +
    +
    $ ffmpeg -f avfoundation -capture_raw_data true -i "zr100:none" out.dv
    +
    + + +
+ + +

26.4 decklink

+ +

The decklink input device provides capture capabilities for Blackmagic +DeckLink devices. +

+

To enable this input device, you need the Blackmagic DeckLink SDK and you +need to configure with the appropriate --extra-cflags +and --extra-ldflags. +On Windows, you need to run the IDL files through widl. +

+

DeckLink is very picky about the formats it supports. Pixel format of the +input can be set with raw_format. +Framerate and video size must be determined for your device with +-list_formats 1. Audio sample rate is always 48 kHz and the number +of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single +audio track. +

+ +

26.4.1 Options

+ +
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. This option is deprecated, please use the +-sources option of ffmpeg to list the available input devices. +

+
+
list_formats
+

If set to true, print a list of supported formats and exit. +Defaults to false. +

+
+
format_code <FourCC>
+

This sets the input video format to the format given by the FourCC. To see +the supported values of your device(s) use list_formats. +Note that there is a FourCC 'pal ' that can also be used +as pal (3 letters). +Default behavior is autodetection of the input video format, if the hardware +supports it. +

+
+
raw_format
+

Set the pixel format of the captured video. +Available values are: +

+
‘auto’
+
+

This is the default which means 8-bit YUV 422 or 8-bit ARGB if format +autodetection is used, 8-bit YUV 422 otherwise. +

+
+
‘uyvy422’
+
+

8-bit YUV 422. +

+
+
‘yuv422p10’
+
+

10-bit YUV 422. +

+
+
‘argb’
+
+

8-bit RGB. +

+
+
‘bgra’
+
+

8-bit RGB. +

+
+
‘rgb10’
+
+

10-bit RGB. +

+
+
+ +
+
teletext_lines
+

If set to nonzero, an additional teletext stream will be captured from the +vertical ancillary data. Both SD PAL (576i) and HD (1080i or 1080p) +sources are supported. In case of HD sources, OP47 packets are decoded. +

+

This option is a bitmask of the SD PAL VBI lines captured, specifically lines 6 +to 22, and lines 318 to 335. Line 6 is the LSB in the mask. Selected lines +which do not contain teletext information will be ignored. You can use the +special all constant to select all possible lines, or +standard to skip lines 6, 318 and 319, which are not compatible with +all receivers. +

+

For SD sources, ffmpeg needs to be compiled with --enable-libzvbi. For +HD sources, on older (pre-4K) DeckLink card models you have to capture in 10 +bit mode. +

+
+
channels
+

Defines number of audio channels to capture. Must be ‘2’, ‘8’ or ‘16’. +Defaults to ‘2’. +

+
+
duplex_mode
+

Sets the decklink device duplex/profile mode. Must be ‘unset’, ‘half’, ‘full’, +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +Defaults to ‘unset’. +

+

Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property. +For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 +sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile +is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles. +

+

Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0): +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +

+

Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2: +‘half’, ‘full’ +

+
+
timecode_format
+

Timecode type to include in the frame and video stream metadata. Must be +‘none’, ‘rp188vitc’, ‘rp188vitc2’, ‘rp188ltc’, +‘rp188hfr’, ‘rp188any’, ‘vitc’, ‘vitc2’, or ‘serial’. +Defaults to ‘none’ (not included). +

+

In order to properly support 50/60 fps timecodes, the ordering of the queried +timecode types for ‘rp188any’ is HFR, VITC1, VITC2 and LTC for >30 fps +content. Note that this is slightly different to the ordering used by the +DeckLink API, which is HFR, VITC1, LTC, VITC2. +

+
+
video_input
+

Sets the video input source. Must be ‘unset’, ‘sdi’, ‘hdmi’, +‘optical_sdi’, ‘component’, ‘composite’ or ‘s_video’. +Defaults to ‘unset’. +

+
+
audio_input
+

Sets the audio input source. Must be ‘unset’, ‘embedded’, +‘aes_ebu’, ‘analog’, ‘analog_xlr’, ‘analog_rca’ or +‘microphone’. Defaults to ‘unset’. +

+
+
video_pts
+

Sets the video packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘video’. +

+
+
audio_pts
+

Sets the audio packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘audio’. +

+
+
draw_bars
+

If set to ‘true’, color bars are drawn in the event of a signal loss. +Defaults to ‘true’. +This option is deprecated, please use the signal_loss_action option. +

+
+
signal_loss_action
+

Sets the action to take in the event of a signal loss. Accepts one of the +following values: +

+
+
1, none
+

Do nothing on signal loss. This usually results in black frames. +

+
2, bars
+

Draw color bars on signal loss. Only supported for 8-bit input signals. +

+
3, repeat
+

Repeat the last video frame on signal loss. +

+
+ +

Defaults to ‘bars’. +

+
+
queue_size
+

Sets maximum input buffer size in bytes. If the buffering reaches this value, +incoming frames will be dropped. +Defaults to ‘1073741824’. +

+
+
audio_depth
+

Sets the audio sample bit depth. Must be ‘16’ or ‘32’. +Defaults to ‘16’. +

+
+
decklink_copyts
+

If set to true, timestamps are forwarded as they are without removing +the initial offset. +Defaults to false. +

+
+
timestamp_align
+

Capture start time alignment in seconds. If set to nonzero, input frames are +dropped till the system timestamp aligns with configured value. +Alignment difference of up to one frame duration is tolerated. +This is useful for maintaining input synchronization across N different +hardware devices deployed for ’N-way’ redundancy. The system time of different +hardware devices should be synchronized with protocols such as NTP or PTP, +before using this option. +Note that this method is not foolproof. In some border cases input +synchronization may not happen due to thread scheduling jitters in the OS. +Either sync could go wrong by 1 frame or in a rarer case +timestamp_align seconds. +Defaults to ‘0’. +

+
+
wait_for_tc (bool)
+

Drop frames till a frame with timecode is received. Sometimes serial timecode +isn’t received with the first input frame. If that happens, the stored stream +timecode will be inaccurate. If this option is set to true, input frames +are dropped till a frame with timecode is received. +Option timecode_format must be specified. +Defaults to false. +

+
+
enable_klv(bool)
+

If set to true, extracts KLV data from VANC and outputs KLV packets. +KLV VANC packets are joined based on MID and PSC fields and aggregated into +one KLV packet. +Defaults to false. +

+
+
+ + +

26.4.2 Examples

+ +
    +
  • List input devices: +
    +
    ffmpeg -sources decklink
    +
    + +
  • List supported formats: +
    +
    ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'
    +
    + +
  • Capture video clip at 1080i50: +
    +
    ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 10 bit: +
    +
    ffmpeg -raw_format yuv422p10 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 with 16 audio channels: +
    +
    ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
+ + +

26.5 dshow

+ +

Windows DirectShow input device. +

+

DirectShow support is enabled when FFmpeg is built with the mingw-w64 project. +Currently only audio and video devices are supported. +

+

Multiple devices may be opened as separate inputs, but they may also be +opened on the same input, which should improve synchronism between them. +

+

The input name should be in the format: +

+
+
TYPE=NAME[:TYPE=NAME]
+
+ +

where TYPE can be either audio or video, +and NAME is the device’s name or alternative name.. +

+ +

26.5.1 Options

+ +

If no options are specified, the device’s defaults are used. +If the device does not support the requested options, it will +fail to open. +

+
+
video_size
+

Set the video size in the captured video. +

+
+
framerate
+

Set the frame rate in the captured video. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. +

+
+
channels
+

Set the number of channels in the captured audio. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +

+
+
list_options
+

If set to true, print a list of selected device’s options +and exit. +

+
+
video_device_number
+

Set video device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
audio_device_number
+

Set audio device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
pixel_format
+

Select pixel format to be used by DirectShow. This may only be set when +the video codec is not set or set to rawvideo. +

+
+
audio_buffer_size
+

Set audio device buffer size in milliseconds (which can directly +impact latency, depending on the device). +Defaults to using the audio device’s +default buffer size (typically some multiple of 500ms). +Setting this value too low can degrade performance. +See also +http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx +

+
+
video_pin_name
+

Select video capture pin to use by name or alternative name. +

+
+
audio_pin_name
+

Select audio capture pin to use by name or alternative name. +

+
+
crossbar_video_input_pin_number
+

Select video input pin number for crossbar device. This will be +routed to the crossbar device’s Video Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
crossbar_audio_input_pin_number
+

Select audio input pin number for crossbar device. This will be +routed to the crossbar device’s Audio Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
show_video_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change video filter properties +and configurations manually. +Note that for crossbar devices, adjusting values in this dialog +may be needed at times to toggle between PAL (25 fps) and NTSC (29.97) +input frame rates, sizes, interlacing, etc. Changing these values can +enable different scan rates/frame rates and avoiding green bars at +the bottom, flickering scan lines, etc. +Note that with some devices, changing these properties can also affect future +invocations (sets new defaults) until system reboot occurs. +

+
+
show_audio_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change audio filter properties +and configurations manually. +

+
+
show_video_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens a video device. +

+
+
show_audio_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens an audio device. +

+
+
show_analog_tv_tuner_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV channels and frequencies. +

+
+
show_analog_tv_tuner_audio_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV audio (like mono vs. stereo, Language A,B or C). +

+
+
audio_device_load
+

Load an audio capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this an audio capture source has to be specified, but it can +be anything even fake one. +

+
+
audio_device_save
+

Save the currently used audio capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
video_device_load
+

Load a video capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this a video capture source has to be specified, but it can +be anything even fake one. +

+
+
video_device_save
+

Save the currently used video capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
use_video_device_timestamps
+

If set to false, the timestamp for video frames will be +derived from the wallclock instead of the timestamp provided by +the capture device. This allows working around devices that +provide unreliable timestamps. +

+
+
+ + +

26.5.2 Examples

+ +
    +
  • Print the list of DirectShow supported devices and exit: +
    +
    $ ffmpeg -list_devices true -f dshow -i dummy
    +
    + +
  • Open video device Camera: +
    +
    $ ffmpeg -f dshow -i video="Camera"
    +
    + +
  • Open second video device with name Camera: +
    +
    $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"
    +
    + +
  • Open video device Camera and audio device Microphone: +
    +
    $ ffmpeg -f dshow -i video="Camera":audio="Microphone"
    +
    + +
  • Print the list of supported options in selected device and exit: +
    +
    $ ffmpeg -list_options true -f dshow -i video="Camera"
    +
    + +
  • Specify pin names to capture by name or alternative name, specify alternative device name: +
    +
    $ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\{ca465100-deb0-4d59-818f-8c477184adf6}":audio="Microphone"
    +
    + +
  • Configure a crossbar device, specifying crossbar pins, allow user to adjust video capture properties at startup: +
    +
    $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0
    +     -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"
    +
    + +
+ + +

26.6 fbdev

+ +

Linux framebuffer input 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 +/dev/fb0. +

+

For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. +

+

See also http://linux-fbdev.sourceforge.net/, and fbset(1). +

+

To record from the framebuffer device /dev/fb0 with +ffmpeg: +

+
ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi
+
+ +

You can take a single screenshot image with the command: +

+
ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg
+
+ + +

26.6.1 Options

+ +
+
framerate
+

Set the frame rate. Default is 25. +

+
+
+ + +

26.7 gdigrab

+ +

Win32 GDI-based screen capture device. +

+

This device allows you to capture a region of the display on Windows. +

+

Amongst options for the input filenames are such elements as: +

+
desktop
+
+

or +

+
title=window_title
+
+

or +

+
hwnd=window_hwnd
+
+ +

The first option will capture the entire desktop, or a fixed region of the +desktop. The second and third options will instead capture the contents of a single +window, regardless of its position on the screen. +

+

For example, to grab the entire desktop using ffmpeg: +

+
ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg
+
+ +

Grab a 640x480 region at position 10,20: +

+
ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg
+
+ +

Grab the contents of the window named "Calculator" +

+
ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg
+
+ + +

26.7.1 Options

+ +
+
draw_mouse
+

Specify whether to draw the mouse pointer. Use the value 0 to +not draw the pointer. Default value is 1. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+

Note that show_region is incompatible with grabbing the contents +of a single window. +

+

For example: +

+
ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg
+
+ +
+
video_size
+

Set the video frame size. The default is to capture the full screen if desktop is selected, or the full window size if title=window_title is selected. +

+
+
offset_x
+

When capturing a region with video_size, set the distance from the left edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned to the left of your primary monitor, you will need to use a negative offset_x value to move the region to that monitor. +

+
+
offset_y
+

When capturing a region with video_size, set the distance from the top edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned above your primary monitor, you will need to use a negative offset_y value to move the region to that monitor. +

+
+
+ + +

26.8 iec61883

+ +

FireWire DV/HDV input device using libiec61883. +

+

To enable this input device, you need libiec61883, libraw1394 and +libavc1394 installed on your system. Use the configure option +--enable-libiec61883 to compile with the device enabled. +

+

The iec61883 capture device supports capturing from a video device +connected via IEEE1394 (FireWire), using libiec61883 and the new Linux +FireWire stack (juju). This is the default DV/HDV input method in Linux +Kernel 2.6.37 and later, since the old FireWire stack was removed. +

+

Specify the FireWire port to be used as input file, or "auto" +to choose the first port connected. +

+ +

26.8.1 Options

+ +
+
dvtype
+

Override autodetection of DV/HDV. This should only be used if auto +detection does not work, or if usage of a different device type +should be prohibited. Treating a DV device as HDV (or vice versa) will +not work and result in undefined behavior. +The values auto, dv and hdv are supported. +

+
+
dvbuffer
+

Set maximum size of buffer for incoming data, in frames. For DV, this +is an exact value. For HDV, it is not frame exact, since HDV does +not have a fixed frame size. +

+
+
dvguid
+

Select the capture device by specifying its GUID. Capturing will only +be performed from the specified device and fails if no device with the +given GUID is found. This is useful to select the input if multiple +devices are connected at the same time. +Look at /sys/bus/firewire/devices to find out the GUIDs. +

+
+
+ + +

26.8.2 Examples

+ +
    +
  • Grab and show the input of a FireWire DV/HDV device. +
    +
    ffplay -f iec61883 -i auto
    +
    + +
  • Grab and record the input of a FireWire DV/HDV device, +using a packet buffer of 100000 packets if the source is HDV. +
    +
    ffmpeg -f iec61883 -i auto -dvbuffer 100000 out.mpg
    +
    + +
+ + +

26.9 jack

+ +

JACK input device. +

+

To enable this input device during configuration you need libjack +installed on your system. +

+

A JACK input device creates one or more JACK writable clients, one for +each audio channel, with name client_name:input_N, where +client_name is the name provided by the application, and N +is a number which identifies the channel. +Each writable client will send the acquired data to the FFmpeg input +device. +

+

Once you have created one or more JACK readable clients, you need to +connect them to one or more JACK writable clients. +

+

To connect or disconnect JACK clients you can use the jack_connect +and jack_disconnect programs, or do it through a graphical interface, +for example with qjackctl. +

+

To list the JACK clients and their properties you can invoke the command +jack_lsp. +

+

Follows an example which shows how to capture a JACK readable client +with ffmpeg. +

+
# Create a JACK writable client with name "ffmpeg".
+$ ffmpeg -f jack -i ffmpeg -y out.wav
+
+# Start the sample jack_metro readable client.
+$ jack_metro -b 120 -d 0.2 -f 4000
+
+# List the current JACK clients.
+$ jack_lsp -c
+system:capture_1
+system:capture_2
+system:playback_1
+system:playback_2
+ffmpeg:input_1
+metro:120_bpm
+
+# Connect metro to the ffmpeg writable client.
+$ jack_connect metro:120_bpm ffmpeg:input_1
+
+ +

For more information read: +http://jackaudio.org/ +

+ +

26.9.1 Options

+ +
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

26.10 kmsgrab

+ +

KMS video input device. +

+

Captures the KMS scanout framebuffer associated with a specified CRTC or plane as a +DRM object that can be passed to other hardware functions. +

+

Requires either DRM master or CAP_SYS_ADMIN to run. +

+

If you don’t understand what all of that means, you probably don’t want this. Look at +x11grab instead. +

+ +

26.10.1 Options

+ +
+
device
+

DRM device to capture on. Defaults to /dev/dri/card0. +

+
+
format
+

Pixel format of the framebuffer. This can be autodetected if you are running Linux 5.7 +or later, but needs to be provided for earlier versions. Defaults to bgr0, +which is the most common format used by the Linux console and Xorg X server. +

+
+
format_modifier
+

Format modifier to signal on output frames. This is necessary to import correctly into +some APIs. It can be autodetected if you are running Linux 5.7 or later, but will need +to be provided explicitly when needed in earlier versions. See the libdrm documentation +for possible values. +

+
+
crtc_id
+

KMS CRTC ID to define the capture source. The first active plane on the given CRTC +will be used. +

+
+
plane_id
+

KMS plane ID to define the capture source. Defaults to the first active plane found if +neither crtc_id nor plane_id are specified. +

+
+
framerate
+

Framerate to capture at. This is not synchronised to any page flipping or framebuffer +changes - it just defines the interval at which the framebuffer is sampled. Sampling +faster than the framebuffer update rate will generate independent frames with the same +content. Defaults to 30. +

+
+
+ + +

26.10.2 Examples

+ +
    +
  • Capture from the first active plane, download the result to normal frames and encode. +This will only work if the framebuffer is both linear and mappable - if not, the result +may be scrambled or fail to download. +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwdownload,format=bgr0' output.mp4
    +
    + +
  • Capture from CRTC ID 42 at 60fps, map the result to VAAPI, convert to NV12 and encode as H.264. +
    +
    ffmpeg -crtc_id 42 -framerate 60 -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,scale_vaapi=w=1920:h=1080:format=nv12' -c:v h264_vaapi output.mp4
    +
    + +
  • To capture only part of a plane the output can be cropped - this can be used to capture +a single window, as long as it has a known absolute position and size. For example, to +capture and encode the middle quarter of a 1920x1080 plane: +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,crop=960:540:480:270,scale_vaapi=960:540:nv12' -c:v h264_vaapi output.mp4
    +
    + +
+ + +

26.11 lavfi

+ +

Libavfilter input virtual device. +

+

This input device reads data from the open output pads of a libavfilter +filtergraph. +

+

For each filtergraph open output, the input device will create a +corresponding stream which is mapped to the generated output. +The filtergraph is specified through the option graph. +

+ +

26.11.1 Options

+ +
+
graph
+

Specify the filtergraph to use as input. Each video open output must be +labelled by a unique string of the form "outN", where N is a +number starting from 0 corresponding to the mapped input stream +generated by the device. +The first unlabelled output is automatically assigned to the "out0" +label, but all the others need to be specified explicitly. +

+

The suffix "+subcc" can be appended to the output label to create an extra +stream with the closed captions packets attached to that output +(experimental; only for EIA-608 / CEA-708 for now). +The subcc streams are created after all the normal streams, in the order of +the corresponding stream. +For example, if there is "out19+subcc", "out7+subcc" and up to "out42", the +stream #43 is subcc for stream #7 and stream #44 is subcc for stream #19. +

+

If not specified defaults to the filename specified for the input +device. +

+
+
graph_file
+

Set the filename of the filtergraph to be read and sent to the other +filters. Syntax of the filtergraph is the same as the one specified by +the option graph. +

+
+
dumpgraph
+

Dump graph to stderr. +

+
+
+ + +

26.11.2 Examples

+ +
    +
  • Create a color video stream and play it back with ffplay: +
    +
    ffplay -f lavfi -graph "color=c=pink [out0]" dummy
    +
    + +
  • As the previous example, but use filename for specifying the graph +description, and omit the "out0" label: +
    +
    ffplay -f lavfi color=c=pink
    +
    + +
  • Create three different video test filtered sources and play them: +
    +
    ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3
    +
    + +
  • Read an audio stream from a file using the amovie source and play it +back with ffplay: +
    +
    ffplay -f lavfi "amovie=test.wav"
    +
    + +
  • Read an audio stream and a video stream and play it back with +ffplay: +
    +
    ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"
    +
    + +
  • Dump decoded frames to images and Closed Captions to an RCWT backup: +
    +
    ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rcwt subcc.bin
    +
    + +
+ + +

26.12 libcdio

+ +

Audio-CD input device based on libcdio. +

+

To enable this input device during configuration you need libcdio +installed on your system. It requires the configure option +--enable-libcdio. +

+

This device allows playing and grabbing from an Audio-CD. +

+

For example to copy with ffmpeg the entire Audio-CD in /dev/sr0, +you may run the command: +

+
ffmpeg -f libcdio -i /dev/sr0 cd.wav
+
+ + +

26.12.1 Options

+
+
speed
+

Set drive reading speed. Default value is 0. +

+

The speed is specified CD-ROM speed units. The speed is set through +the libcdio cdio_cddap_speed_set function. On many CD-ROM +drives, specifying a value too large will result in using the fastest +speed. +

+
+
paranoia_mode
+

Set paranoia recovery mode flags. It accepts one of the following values: +

+
+
‘disable’
+
‘verify’
+
‘overlap’
+
‘neverskip’
+
‘full’
+
+ +

Default value is ‘disable’. +

+

For more information about the available recovery modes, consult the +paranoia project documentation. +

+
+ + +

26.13 libdc1394

+ +

IIDC1394 input device, based on libdc1394 and libraw1394. +

+

Requires the configure option --enable-libdc1394. +

+ +

26.13.1 Options

+
+
framerate
+

Set the frame rate. Default is ntsc, corresponding to a frame +rate of 30000/1001. +

+
+
pixel_format
+

Select the pixel format. Default is uyvy422. +

+
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Default is qvga. +

+
+ + +

26.14 openal

+ +

The OpenAL input device provides audio capture on all systems with a +working OpenAL 1.1 implementation. +

+

To enable this input device during configuration, you need OpenAL +headers and libraries installed on your system, and need to configure +FFmpeg with --enable-openal. +

+

OpenAL headers and libraries should be provided as part of your OpenAL +implementation, or as an additional download (an SDK). Depending on your +installation you may need to specify additional flags via the +--extra-cflags and --extra-ldflags for allowing the build +system to locate the OpenAL headers and libraries. +

+

An incomplete list of OpenAL implementations follows: +

+
+
Creative
+

The official Windows implementation, providing hardware acceleration +with supported devices and software fallback. +See http://openal.org/. +

+
OpenAL Soft
+

Portable, open source (LGPL) software implementation. Includes +backends for the most common sound APIs on the Windows, Linux, +Solaris, and BSD operating systems. +See http://kcat.strangesoft.net/openal.html. +

+
Apple
+

OpenAL is part of Core Audio, the official Mac OS X Audio interface. +See http://developer.apple.com/technologies/mac/audio-and-video.html +

+
+ +

This device allows one to capture from an audio input device handled +through OpenAL. +

+

You need to specify the name of the device to capture in the provided +filename. If the empty string is provided, the device will +automatically select the default device. You can get the list of the +supported devices by using the option list_devices. +

+ +

26.14.1 Options

+ +
+
channels
+

Set the number of channels in the captured audio. Only the values +1 (monaural) and 2 (stereo) are currently supported. +Defaults to 2. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. Only the values +8 and 16 are currently supported. Defaults to +16. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +Defaults to 44.1k. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. +

+
+
+ + +

26.14.2 Examples

+ +

Print the list of OpenAL supported devices and exit: +

+
$ ffmpeg -list_devices true -f openal -i dummy out.ogg
+
+ +

Capture from the OpenAL device DR-BT101 via PulseAudio: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg
+
+ +

Capture from the default device (note the empty string ” as filename): +

+
$ ffmpeg -f openal -i '' out.ogg
+
+ +

Capture from two devices simultaneously, writing to two different files, +within the same ffmpeg command: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg
+
+

Note: not all OpenAL implementations support multiple simultaneous capture - +try the latest OpenAL Soft if the above does not work. +

+ +

26.15 oss

+ +

Open Sound System input device. +

+

The filename to provide to the input device is the device node +representing the OSS input device, and is usually set to +/dev/dsp. +

+

For example to grab from /dev/dsp using ffmpeg use the +command: +

+
ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
+
+ +

For more information about OSS see: +http://manuals.opensound.com/usersguide/dsp.html +

+ +

26.15.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

26.16 pulse

+ +

PulseAudio input device. +

+

To enable this output device you need to configure FFmpeg with --enable-libpulse. +

+

The filename to provide to the input device is a source device or the +string "default" +

+

To list the PulseAudio source devices and their properties you can invoke +the command pactl list sources. +

+

More information about PulseAudio can be found on http://www.pulseaudio.org. +

+ +

26.16.1 Options

+
+
server
+

Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. +

+
+
name
+

Specify the application name PulseAudio will use when showing active clients, +by default it is the LIBAVFORMAT_IDENT string. +

+
+
stream_name
+

Specify the stream name PulseAudio will use when showing active streams, +by default it is "record". +

+
+
sample_rate
+

Specify the samplerate in Hz, by default 48kHz is used. +

+
+
channels
+

Specify the channels in use, by default 2 (stereo) is set. +

+
+
frame_size
+

This option does nothing and is deprecated. +

+
+
fragment_size
+

Specify the size in bytes of the minimal buffering fragment in PulseAudio, it +will affect the audio latency. By default it is set to 50 ms amount of data. +

+
+
wallclock
+

Set the initial PTS using the current time. Default is 1. +

+
+
+ + +

26.16.2 Examples

+

Record a stream from default device: +

+
ffmpeg -f pulse -i default /tmp/pulse.wav
+
+ + +

26.17 sndio

+ +

sndio input device. +

+

To enable this input device during configuration you need libsndio +installed on your system. +

+

The filename to provide to the input device is the device node +representing the sndio input device, and is usually set to +/dev/audio0. +

+

For example to grab from /dev/audio0 using ffmpeg use the +command: +

+
ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
+
+ + +

26.17.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

26.18 video4linux2, v4l2

+ +

Video4Linux2 input video device. +

+

"v4l2" can be used as alias for "video4linux2". +

+

If FFmpeg is built with v4l-utils support (by using the +--enable-libv4l2 configure option), it is possible to use it with the +-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 +(e.g. an USB webcam) is plugged into the system, and has a name of the +kind /dev/videoN, where N is a number associated to +the device. +

+

Video4Linux2 devices usually support a limited set of +widthxheight sizes and frame rates. You can check which are +supported using -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 -list_standards all. +

+

The time base for the timestamps is 1 microsecond. Depending on the kernel +version and configuration, the timestamps may be derived from the real time +clock (origin at the Unix Epoch) or the monotonic clock (origin usually at +boot time, unaffected by NTP or manual changes to the clock). The +-timestamps abs or -ts abs option can be used to force +conversion into the real time clock. +

+

Some usage examples of the video4linux2 device with ffmpeg +and ffplay: +

    +
  • List supported formats for a video4linux2 device: +
    +
    ffplay -f video4linux2 -list_formats all /dev/video0
    +
    + +
  • Grab and show the input of a video4linux2 device: +
    +
    ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
    +
    + +
  • Grab and record the input of a video4linux2 device, leave the +frame rate and size as previously set: +
    +
    ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
    +
    +
+ +

For more information about Video4Linux, check http://linuxtv.org/. +

+ +

26.18.1 Options

+ +
+
standard
+

Set the standard. Must be the name of a supported standard. To get a +list of the supported standards, use the list_standards +option. +

+
+
channel
+

Set the input channel number. Default to -1, which means using the +previously selected channel. +

+
+
video_size
+

Set the video frame size. The argument must be a string in the form +WIDTHxHEIGHT or a valid size abbreviation. +

+
+
pixel_format
+

Select the pixel format (only valid for raw video input). +

+
+
input_format
+

Set the preferred pixel format (for raw video) or a codec name. +This option allows one to select the input format, when several are +available. +

+
+
framerate
+

Set the preferred video frame rate. +

+
+
list_formats
+

List available formats (supported pixel formats, codecs, and frame +sizes) and exit. +

+

Available values are: +

+
‘all’
+

Show all available (compressed and non-compressed) formats. +

+
+
‘raw’
+

Show only raw video (non-compressed) formats. +

+
+
‘compressed’
+

Show only compressed formats. +

+
+ +
+
list_standards
+

List supported standards and exit. +

+

Available values are: +

+
‘all’
+

Show all supported standards. +

+
+ +
+
timestamps, ts
+

Set type of timestamps for grabbed frames. +

+

Available values are: +

+
‘default’
+

Use timestamps from the kernel. +

+
+
‘abs’
+

Use absolute timestamps (wall clock). +

+
+
‘mono2abs’
+

Force conversion from monotonic to absolute timestamps. +

+
+ +

Default value is default. +

+
+
use_libv4l2
+

Use libv4l2 (v4l-utils) conversion functions. Default is 0. +

+
+
+ + +

26.19 vfwcap

+ +

VfW (Video for Windows) capture input device. +

+

The filename passed as input is the capture driver number, ranging from +0 to 9. You may use "list" as filename to print a list of drivers. Any +other filename will be interpreted as device number 0. +

+ +

26.19.1 Options

+ +
+
video_size
+

Set the video frame size. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
+ + +

26.20 x11grab

+ +

X11 video input device. +

+

To enable this input device during configuration you need libxcb +installed on your system. It will be automatically detected during +configuration. +

+

This device allows one to capture a region of an X11 display. +

+

The filename passed as input has the syntax: +

+
[hostname]:display_number.screen_number[+x_offset,y_offset]
+
+ +

hostname:display_number.screen_number specifies the +X11 display name of the screen to grab from. hostname can be +omitted, and defaults to "localhost". The environment variable +DISPLAY contains the default display name. +

+

x_offset and y_offset specify the offsets of the grabbed +area with respect to the top-left border of the X11 screen. They +default to 0. +

+

Check the X11 documentation (e.g. man X) for more detailed +information. +

+

Use the xdpyinfo program for getting basic information about +the properties of your X11 display (e.g. grep for "name" or +"dimensions"). +

+

For example to grab from :0.0 using ffmpeg: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

Grab at position 10,20: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ + +

26.20.1 Options

+ +
+
select_region
+

Specify whether to select the grabbing area graphically using the pointer. +A value of 1 prompts the user to select the grabbing area graphically +by clicking and dragging. A single click with no dragging will select the +whole screen. A region with zero width or height will also select the whole +screen. This option overwrites the video_size, grab_x, and +grab_y options. Default value is 0. +

+
+
draw_mouse
+

Specify whether to draw the mouse pointer. A value of 0 specifies +not to draw the pointer. Default value is 1. +

+
+
follow_mouse
+

Make the grabbed area follow the mouse. The argument can be +centered or a number of pixels PIXELS. +

+

When it is specified with "centered", the grabbing region follows the mouse +pointer and keeps the pointer at the center of region; otherwise, the region +follows only when the mouse pointer reaches within PIXELS (greater than +zero) to the edge of region. +

+

For example: +

+
ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

To follow only when the mouse pointer reaches within 100 pixels to edge: +

+
ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+
+
region_border
+

Set the region border thickness if -show_region 1 is used. +Range is 1 to 128 and default is 3 (XCB-based x11grab only). +

+

For example: +

+
ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ +

With follow_mouse: +

+
ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
window_id
+

Grab this window, instead of the whole screen. Default value is 0, which maps to +the whole screen (root window). +

+

The id of a window can be found using the xwininfo program, possibly with options -tree and +-root. +

+

If the window is later enlarged, the new area is not recorded. Video ends when +the window is closed, unmapped (i.e., iconified) or shrunk beyond the video +size (which defaults to the initial window size). +

+

This option disables options follow_mouse and select_region. +

+
+
video_size
+

Set the video frame size. Default is the full desktop or window. +

+
+
grab_x
+
grab_y
+

Set the grabbing region coordinates. They are expressed as offset from +the top left corner of the X11 window and correspond to the +x_offset and y_offset parameters in the device name. The +default value for both options is 0. +

+
+ + +

27 Output Devices

+ +

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 +are enabled by default. You can list all available ones using the +configure option "–list-outdevs". +

+

You can disable all the output devices using the configure option +"–disable-outdevs", and selectively enable an output device using the +option "–enable-outdev=OUTDEV", or you can disable a particular +input device using the option "–disable-outdev=OUTDEV". +

+

The option "-devices" of the ff* tools will display the list of +enabled output devices. +

+

A description of the currently available output devices follows. +

+ +

27.1 alsa

+ +

ALSA (Advanced Linux Sound Architecture) output device. +

+ +

27.1.1 Examples

+ +
    +
  • Play a file on default ALSA device: +
    +
    ffmpeg -i INPUT -f alsa default
    +
    + +
  • Play a file on soundcard 1, audio device 7: +
    +
    ffmpeg -i INPUT -f alsa hw:1,7
    +
    +
+ + +

27.2 AudioToolbox

+ +

AudioToolbox output device. +

+

Allows native output to CoreAudio devices on OSX. +

+

The output filename can be empty (or -) to refer to the default system output device or a number that refers to the device index as shown using: -list_devices true. +

+

Alternatively, the audio input device can be chosen by index using the + + -audio_device_index <INDEX> + +, overriding any device name or index given in the input filename. +

+

All available devices can be enumerated by using -list_devices true, listing +all device names, UIDs and corresponding indices. +

+ +

27.2.1 Options

+ +

AudioToolbox supports the following options: +

+
+
-audio_device_index <INDEX>
+

Specify the audio device by its index. Overrides anything given in the output filename. +

+
+
+ + +

27.2.2 Examples

+ +
    +
  • Print the list of supported devices and output a sine wave to the default device: +
    +
    $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -list_devices true -
    +
    + +
  • Output a sine wave to the device with the index 2, overriding any output filename: +
    +
    $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -audio_device_index 2 -
    +
    + +
+ + +

27.3 caca

+ +

CACA output device. +

+

This output device allows one 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. +

+

To enable this output device you need to configure FFmpeg with +--enable-libcaca. +libcaca is a graphics library that outputs text instead of pixels. +

+

For more information about libcaca, check: +http://caca.zoy.org/wiki/libcaca +

+ +

27.3.1 Options

+ +
+
window_title
+

Set the CACA window title, if not specified default to the filename +specified for the output device. +

+
+
window_size
+

Set the CACA window size, can be a string of the form +widthxheight or a video size abbreviation. +If not specified it defaults to the size of the input video. +

+
+
driver
+

Set display driver. +

+
+
algorithm
+

Set dithering algorithm. Dithering is necessary +because the picture being rendered has usually far more colours than +the available palette. +The accepted values are listed with -list_dither algorithms. +

+
+
antialias
+

Set antialias method. Antialiasing smoothens the rendered +image and avoids the commonly seen staircase effect. +The accepted values are listed with -list_dither antialiases. +

+
+
charset
+

Set which characters are going to be used when rendering text. +The accepted values are listed with -list_dither charsets. +

+
+
color
+

Set color to be used when rendering text. +The accepted values are listed with -list_dither colors. +

+
+
list_drivers
+

If set to true, print a list of available drivers and exit. +

+
+
list_dither
+

List available dither options related to the argument. +The argument must be one of algorithms, antialiases, +charsets, colors. +

+
+ + +

27.3.2 Examples

+ +
    +
  • The following command shows the ffmpeg output is an +CACA window, forcing its size to 80x25: +
    +
    ffmpeg -i INPUT -c:v rawvideo -pix_fmt rgb24 -window_size 80x25 -f caca -
    +
    + +
  • Show the list of available drivers and exit: +
    +
    ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_drivers true -
    +
    + +
  • Show the list of available dither colors and exit: +
    +
    ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_dither colors -
    +
    +
+ + +

27.4 decklink

+ +

The decklink output device provides playback capabilities for Blackmagic +DeckLink devices. +

+

To enable this output device, you need the Blackmagic DeckLink SDK and you +need to configure with the appropriate --extra-cflags +and --extra-ldflags. +On Windows, you need to run the IDL files through widl. +

+

DeckLink is very picky about the formats it supports. Pixel format is always +uyvy422, framerate, field order and video size must be determined for your +device with -list_formats 1. Audio sample rate is always 48 kHz. +

+ +

27.4.1 Options

+ +
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. This option is deprecated, please use the +-sinks option of ffmpeg to list the available output devices. +

+
+
list_formats
+

If set to true, print a list of supported formats and exit. +Defaults to false. +

+
+
preroll
+

Amount of time to preroll video in seconds. +Defaults to 0.5. +

+
+
duplex_mode
+

Sets the decklink device duplex/profile mode. Must be ‘unset’, ‘half’, ‘full’, +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +Defaults to ‘unset’. +

+

Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property. +For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 +sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile +is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles. +

+

Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0): +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +

+

Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2: +‘half’, ‘full’ +

+
+
timing_offset
+

Sets the genlock timing pixel offset on the used output. +Defaults to ‘unset’. +

+
+
link
+

Sets the SDI video link configuration on the used output. Must be +‘unset’, ‘single’ link SDI, ‘dual’ link SDI or ‘quad’ link +SDI. +Defaults to ‘unset’. +

+
+
sqd
+

Enable Square Division Quad Split mode for Quad-link SDI output. +Must be ‘unset’, ‘true’ or ‘false’. +Defaults to unset. +

+
+
level_a
+

Enable SMPTE Level A mode on the used output. +Must be ‘unset’, ‘true’ or ‘false’. +Defaults to unset. +

+
+
vanc_queue_size
+

Sets maximum output buffer size in bytes for VANC data. If the buffering reaches this value, +outgoing VANC data will be dropped. +Defaults to ‘1048576’. +

+
+
+ + +

27.4.2 Examples

+ +
    +
  • List output devices: +
    +
    ffmpeg -sinks decklink
    +
    + +
  • List supported formats: +
    +
    ffmpeg -i test.avi -f decklink -list_formats 1 'DeckLink Mini Monitor'
    +
    + +
  • Play video clip: +
    +
    ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 'DeckLink Mini Monitor'
    +
    + +
  • Play video clip with non-standard framerate or video size: +
    +
    ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 -s 720x486 -r 24000/1001 'DeckLink Mini Monitor'
    +
    + +
+ + +

27.5 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 +/dev/fb0. +

+

For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. +

+ +

27.5.1 Options

+
+
xoffset
+
yoffset
+

Set x/y coordinate of top left corner. Default is 0. +

+
+ + +

27.5.2 Examples

+

Play a file on framebuffer device /dev/fb0. +Required pixel format depends on current framebuffer settings. +

+
ffmpeg -re -i INPUT -c:v rawvideo -pix_fmt bgra -f fbdev /dev/fb0
+
+ +

See also http://linux-fbdev.sourceforge.net/, and fbset(1). +

+ +

27.6 oss

+ +

OSS (Open Sound System) output device. +

+ +

27.7 pulse

+ +

PulseAudio output device. +

+

To enable this output device you need to configure FFmpeg with --enable-libpulse. +

+

More information about PulseAudio can be found on http://www.pulseaudio.org +

+ +

27.7.1 Options

+
+
server
+

Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. +

+
+
name
+

Specify the application name PulseAudio will use when showing active clients, +by default it is the LIBAVFORMAT_IDENT string. +

+
+
stream_name
+

Specify the stream name PulseAudio will use when showing active streams, +by default it is set to the specified output name. +

+
+
device
+

Specify the device to use. Default device is used when not provided. +List of output devices can be obtained with command pactl list sinks. +

+
+
buffer_size
+
buffer_duration
+

Control the size and duration of the PulseAudio buffer. A small buffer +gives more control, but requires more frequent updates. +

+

buffer_size specifies size in bytes while +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. +

+
+
prebuf
+

Specify pre-buffering size in bytes. The server does not start with +playback before at least prebuf bytes are available in the +buffer. By default this option is initialized to the same value as +buffer_size or buffer_duration (whichever is bigger). +

+
+
minreq
+

Specify minimum request size in bytes. The server does not request less +than minreq bytes from the client, instead waits until the buffer +is free enough to request more bytes at once. It is recommended to not set +this option, which will initialize this to a value that is deemed sensible +by the server. +

+
+
+ + +

27.7.2 Examples

+

Play a file on default device on default server: +

+
ffmpeg  -i INPUT -f pulse "stream name"
+
+ + +

27.8 sndio

+ +

sndio audio output device. +

+ +

27.9 v4l2

+ +

Video4Linux2 output device. +

+ +

27.10 xv

+ +

XV (XVideo) output device. +

+

This output device allows one to show a video stream in a X Window System +window. +

+ +

27.10.1 Options

+ +
+
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 hostname[:number[.screen_number]]. +

+

hostname specifies the name of the host machine on which the +display is physically attached. number specifies the number of +the display server on that host machine. 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, 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. +

+
+
window_id
+

When set to non-zero value then device doesn’t create new window, +but uses existing one with provided window_id. By default +this options is set to zero and device creates its own window. +

+
+
window_size
+

Set the created window size, can be a string of the form +widthxheight or a video size abbreviation. If not +specified it defaults to the size of the input video. +Ignored when window_id is set. +

+
+
window_x
+
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. +Ignored when window_id is set. +

+
+
window_title
+

Set the window title, if not specified default to the filename +specified for the output device. Ignored when window_id is set. +

+
+ +

For more information about XVideo see http://www.x.org/. +

+ +

27.10.2 Examples

+ +
    +
  • Decode, display and encode video input with ffmpeg at the +same time: +
    +
    ffmpeg -i INPUT OUTPUT -f xv display
    +
    + +
  • Decode and display the input video to multiple X11 windows: +
    +
    ffmpeg -i INPUT -f xv normal -vf negate -f xv negated
    +
    +
+ + +

28 Resampler Options

+ +

The audio resampler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, option=value for the aresample filter, +by setting the value explicitly in the +SwrContext options or using the libavutil/opt.h API for +programmatic use. +

+
+
uchl, used_chlayout
+

Set used input channel layout. Default is unset. This option is +only used for special remapping. +

+
+
isr, in_sample_rate
+

Set the input sample rate. Default value is 0. +

+
+
osr, out_sample_rate
+

Set the output sample rate. Default value is 0. +

+
+
isf, in_sample_fmt
+

Specify the input sample format. It is set by default to none. +

+
+
osf, out_sample_fmt
+

Specify the output sample format. It is set by default to none. +

+
+
tsf, internal_sample_fmt
+

Set the internal sample format. Default value is none. +This will automatically be chosen when it is not explicitly set. +

+
+
ichl, in_chlayout
+
ochl, out_chlayout
+

Set the input/output channel layout. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
clev, center_mix_level
+

Set the center mix level. It is a value expressed in deciBel, and must be +in the interval [-32,32]. +

+
+
slev, surround_mix_level
+

Set the surround mix level. It is a value expressed in deciBel, and must +be in the interval [-32,32]. +

+
+
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]. +

+
+
rmvol, rematrix_volume
+

Set rematrix volume. Default value is 1.0. +

+
+
rematrix_maxval
+

Set maximum output value for rematrixing. +This can be used to prevent clipping vs. preventing volume reduction. +A value of 1.0 prevents clipping. +

+
+
flags, swr_flags
+

Set flags used by the converter. Default value is 0. +

+

It supports the following individual flags: +

+
res
+

force resampling, this flag forces resampling to be used even when the +input and output sample rates match. +

+
+ +
+
dither_scale
+

Set the dither scale. Default value is 1. +

+
+
dither_method
+

Set dither method. Default value is 0. +

+

Supported values: +

+
‘rectangular’
+

select rectangular dither +

+
‘triangular’
+

select triangular dither +

+
‘triangular_hp’
+

select triangular dither with high pass +

+
‘lipshitz’
+

select Lipshitz noise shaping dither. +

+
‘shibata’
+

select Shibata noise shaping dither. +

+
‘low_shibata’
+

select low Shibata noise shaping dither. +

+
‘high_shibata’
+

select high Shibata noise shaping dither. +

+
‘f_weighted’
+

select f-weighted noise shaping dither +

+
‘modified_e_weighted’
+

select modified-e-weighted noise shaping dither +

+
‘improved_e_weighted’
+

select improved-e-weighted noise shaping dither +

+
+
+ +
+
resampler
+

Set resampling engine. Default value is swr. +

+

Supported values: +

+
‘swr’
+

select the native SW Resampler; filter options precision and cheby are not +applicable in this case. +

+
‘soxr’
+

select the SoX Resampler (where available); compensation, and filter options +filter_size, phase_shift, exact_rational, filter_type & kaiser_beta, are not +applicable in this case. +

+
+ +
+
filter_size
+

For swr only, set resampling filter size, default value is 32. +

+
+
phase_shift
+

For swr only, set resampling phase shift, default value is 10, and must be in +the interval [0,30]. +

+
+
linear_interp
+

Use linear interpolation when enabled (the default). Disable it if you want +to preserve speed instead of quality when exact_rational fails. +

+
+
exact_rational
+

For swr only, when enabled, try to use exact phase_count based on input and +output sample rate. However, if it is larger than 1 << phase_shift, +the phase_count will be 1 << phase_shift as fallback. Default is enabled. +

+
+
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). +

+
+
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’. +

+
+
cheby
+

For soxr only, selects passband rolloff none (Chebyshev) & higher-precision +approximation for ’irrational’ ratios. Default value is 0. +

+
+
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. +

+
+
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. +

+
+
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 +(min_comp = FLT_MAX). +

+
+
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 min_comp. +The default is 0.1. +

+
+
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. +

+
+
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. +

+
+
matrix_encoding
+

Select matrixed stereo encoding. +

+

It accepts the following values: +

+
‘none’
+

select none +

+
‘dolby’
+

select Dolby +

+
‘dplii’
+

select Dolby Pro Logic II +

+
+ +

Default value is none. +

+
+
filter_type
+

For swr only, select resampling filter type. This only affects resampling +operations. +

+

It accepts the following values: +

+
‘cubic’
+

select cubic +

+
‘blackman_nuttall’
+

select Blackman Nuttall windowed sinc +

+
‘kaiser’
+

select Kaiser windowed sinc +

+
+ +
+
kaiser_beta
+

For swr only, set Kaiser window beta value. Must be a double float value in the +interval [2,16], default value is 9. +

+
+
output_sample_bits
+

For swr only, set number of used output sample bits for dithering. Must be an integer in the +interval [0,64], default value is 0, which means it’s not used. +

+
+
+ + +

29 Scaler Options

+ +

The video scaler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, with a few API-only exceptions noted below. +For programmatic use, they can be set explicitly in the +SwsContext options or through the libavutil/opt.h API. +

+
+
+
+
sws_flags
+

Set the scaler flags. This is also used to set the scaling +algorithm. Only a single algorithm should be selected. Default +value is ‘bicubic’. +

+

It accepts the following values: +

+
‘fast_bilinear’
+

Select fast bilinear scaling algorithm. +

+
+
‘bilinear’
+

Select bilinear scaling algorithm. +

+
+
‘bicubic’
+

Select bicubic scaling algorithm. +

+
+
‘experimental’
+

Select experimental scaling algorithm. +

+
+
‘neighbor’
+

Select nearest neighbor rescaling algorithm. +

+
+
‘area’
+

Select averaging area rescaling algorithm. +

+
+
‘bicublin’
+

Select bicubic scaling algorithm for the luma component, bilinear for +chroma components. +

+
+
‘gauss’
+

Select Gaussian rescaling algorithm. +

+
+
‘sinc’
+

Select sinc rescaling algorithm. +

+
+
‘lanczos’
+

Select Lanczos rescaling algorithm. The default width (alpha) is 3 and can be +changed by setting param0. +

+
+
‘spline’
+

Select natural bicubic spline rescaling algorithm. +

+
+
‘print_info’
+

Enable printing/debug logging. +

+
+
‘accurate_rnd’
+

Enable accurate rounding. +

+
+
‘full_chroma_int’
+

Enable full chroma interpolation. +

+
+
‘full_chroma_inp’
+

Select full chroma input. +

+
+
‘bitexact’
+

Enable bitexact output. +

+
+
‘unstable’
+

Allow the use of experimental new code. May subtly affect the output or even +produce wrong results. For testing only. +

+
+ +
+
srcw (API only)
+

Set source width. +

+
+
srch (API only)
+

Set source height. +

+
+
dstw (API only)
+

Set destination width. +

+
+
dsth (API only)
+

Set destination height. +

+
+
src_format (API only)
+

Set source pixel format (must be expressed as an integer). +

+
+
dst_format (API only)
+

Set destination pixel format (must be expressed as an integer). +

+
+
src_range (boolean)
+

If value is set to 1, indicates source is full range. Default value is +0, which indicates source is limited range. +

+
+
dst_range (boolean)
+

If value is set to 1, enable full range for destination. Default value +is 0, which enables limited range. +

+
+
gamma (boolean)
+

If value is set to 1, enable gamma correct scaling. Default value is 0. +

+
+
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. +

+
+
sws_dither
+

Set the dithering algorithm. Accepts one of the following +values. Default value is ‘auto’. +

+
+
‘auto’
+

automatic choice +

+
+
‘none’
+

no dithering +

+
+
‘bayer’
+

bayer dither +

+
+
‘ed’
+

error diffusion dither +

+
+
‘a_dither’
+

arithmetic dither, based using addition +

+
+
‘x_dither’
+

arithmetic dither, based using xor (more random/less apparent patterning that +a_dither). +

+
+
+ +
+
alphablend
+

Set the alpha blending to use when the input has alpha but the output does not. +Default value is ‘none’. +

+
+
‘uniform_color’
+

Blend onto a uniform background color +

+
+
‘checkerboard’
+

Blend onto a checkerboard +

+
+
‘none’
+

No blending +

+
+
+ +
+
+ + +

30 Filtering Introduction

+ +

Filtering in FFmpeg is enabled through the libavfilter library. +

+

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. +

+
                [main]
+input --> split ---------------------> overlay --> output
+            |                             ^
+            |[tmp]                  [flip]|
+            +-----> crop --> vflip -------+
+
+

This filtergraph splits the input stream in two streams, then 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: +

+
+
ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
+
+ +

The result will be that the top half of the video is mirrored +onto the bottom half of the output video. +

+

Filters in the same linear chain are separated by commas, and distinct +linear chains of filters are separated by semicolons. In our example, +crop,vflip are in one linear chain, split and +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 [main] and [tmp]. +

+

The stream sent to the second output of split, labelled as +[tmp], is processed through the crop filter, which crops +away the lower half part of the video, and then vertically flipped. The +overlay filter takes in input the first unchanged output of the +split filter (which was labelled as [main]), and overlay on its +lower half the output generated by the 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 +by a colon. +

+

There exist so-called source filters that do not have an +audio/video input, and sink filters that will not have audio/video +output. +

+ + +

31 graph2dot

+ +

The graph2dot program included in the FFmpeg tools +directory can be used to parse a filtergraph description and issue a +corresponding textual representation in the dot language. +

+

Invoke the command: +

+
graph2dot -h
+
+ +

to see how to use graph2dot. +

+

You can then pass the dot description to the dot program (from +the graphviz suite of programs) and obtain a graphical representation +of the filtergraph. +

+

For example the sequence of commands: +

+
echo GRAPH_DESCRIPTION | \
+tools/graph2dot -o graph.tmp && \
+dot -Tpng graph.tmp -o graph.png && \
+display graph.png
+
+ +

can be used to create and display an image representing the graph +described by the GRAPH_DESCRIPTION string. Note that this string must be +a complete self-contained graph, with its inputs and outputs explicitly defined. +For example if your command line is of the form: +

+
ffmpeg -i infile -vf scale=640:360 outfile
+
+

your GRAPH_DESCRIPTION string will need to be of the form: +

+
nullsrc,scale=640:360,nullsink
+
+

you may also need to set the nullsrc parameters and add a format +filter in order to simulate a specific input file. +

+ + +

32 Filtergraph description

+ +

A filtergraph is a directed graph of connected filters. It can contain +cycles, and there can be multiple links between a pair of +filters. Each link has one input pad on one side connecting it to one +filter from which it takes its input, and one output pad on the other +side connecting it to one filter accepting its output. +

+

Each filter in a filtergraph is an instance of a filter class +registered in the application, which defines the features and the +number of input and output pads of the filter. +

+

A filter with no input pads is called a "source", and a filter with no +output pads is called a "sink". +

+ +

32.1 Filtergraph syntax

+ +

A filtergraph has a textual representation, which is recognized by the +-filter/-vf/-af and +-filter_complex options in ffmpeg and +-vf/-af in ffplay, and by the +avfilter_graph_parse_ptr() function defined in +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 +represented by a list of ","-separated filter descriptions. +

+

A filtergraph consists of a sequence of filterchains. A sequence of +filterchains is represented by a list of ";"-separated filterchain +descriptions. +

+

A filter is represented by a string of the form: +[in_link_1]...[in_link_N]filter_name@id=arguments[out_link_1]...[out_link_M] +

+

filter_name is the name of the filter class of which the +described filter is an instance of, and has to be the name of one of +the filter classes registered in the program optionally followed by "@id". +The name of the filter class is optionally followed by a string +"=arguments". +

+

arguments is a string which contains the parameters used to +initialize the filter instance. It may have one of two forms: +

    +
  • A ’:’-separated list of key=value pairs. + +
  • A ’:’-separated list of value. In this case, the keys are assumed to be +the option names in the order they are declared. E.g. the fade filter +declares three options in this order – type, start_frame and +nb_frames. Then the parameter list in:0:30 means that the value +in is assigned to the option type, 0 to +start_frame and 30 to nb_frames. + +
  • A ’:’-separated list of mixed direct value and long key=value +pairs. The direct value must precede the key=value pairs, and +follow the same constraints order of the previous point. The following +key=value pairs can be set in any preferred order. + +
+ +

If the option value itself is a list of items (e.g. the 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 +within the quoted text; otherwise the argument string is considered +terminated when the next special character (belonging to the set +‘[]=;,’) is encountered. +

+

A special syntax implemented in the ffmpeg CLI tool allows loading +option values from files. This is done be prepending a slash ’/’ to the option +name, then the supplied value is interpreted as a path from which the actual +value is loaded. E.g. +

+
ffmpeg -i <INPUT> -vf drawtext=/text=/tmp/some_text <OUTPUT>
+
+

will load the text to be drawn from /tmp/some_text. API users wishing to +implement a similar feature should use the avfilter_graph_segment_*() +functions together with custom IO code. +

+

The name and arguments of the filter are optionally preceded and +followed by a list of link labels. +A link label allows one to name a link and associate it to a filter output +or input pad. The preceding labels in_link_1 +... in_link_N, are associated to the filter input pads, +the following labels out_link_1 ... out_link_M, are +associated to the output pads. +

+

When two link labels with the same name are found in the +filtergraph, a link between the corresponding input and output pad is +created. +

+

If an output pad is not labelled, it is linked by default to the first +unlabelled input pad of the next filter in the filterchain. +For example in the filterchain +

+
nullsrc, split[L1], [L2]overlay, nullsink
+
+

the split filter instance has two output pads, and the overlay filter +instance two input pads. The first output pad of split is labelled +"L1", the first input pad of overlay is labelled "L2", and the second +output pad of split is linked to the second input pad of overlay, +which are both unlabelled. +

+

In a filter description, if the input label of the first filter is not +specified, "in" is assumed; if the output label of the last filter is not +specified, "out" is assumed. +

+

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. +

+

Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens +in the filtergraph specification are ignored. This means that the filtergraph +can be expressed using empty lines and spaces to improve readability. +

+

For example, the filtergraph: +

+
testsrc,split[L1],hflip[L2];[L1][L2] hstack
+
+ +

can be represented as: +

+
testsrc,
+split [L1], hflip [L2];
+
+[L1][L2] hstack
+
+ +

Libavfilter will automatically insert scale filters where format +conversion is required. It is possible to specify swscale flags +for those automatically inserted scalers by prepending +sws_flags=flags; +to the filtergraph description. +

+

Here is a BNF description of the filtergraph syntax: +

+
NAME             ::= sequence of alphanumeric characters and '_'
+FILTER_NAME      ::= NAME["@"NAME]
+LINKLABEL        ::= "[" NAME "]"
+LINKLABELS       ::= LINKLABEL [LINKLABELS]
+FILTER_ARGUMENTS ::= sequence of chars (possibly quoted)
+FILTER           ::= [LINKLABELS] FILTER_NAME ["=" FILTER_ARGUMENTS] [LINKLABELS]
+FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
+FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]
+
+ + +

32.2 Notes on filtergraph escaping

+ +

Filtergraph description composition entails several levels of +escaping. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual for more +information about the employed escaping procedure. +

+

A first level escaping affects the content of each filter option +value, which may contain the special character : used to +separate values, or one of the escaping characters \'. +

+

A second level escaping affects the whole filter description, which +may contain the escaping characters \' or the special +characters [],; used by the filtergraph description. +

+

Finally, when you specify a filtergraph on a shell commandline, you +need to perform a third level escaping for the shell special +characters contained within it. +

+

For example, consider the following string to be embedded in +the drawtext filter description text value: +

+
this is a 'string': may contain one, or more, special characters
+
+ +

This string contains the ' special escaping character, and the +: special character, so it needs to be escaped in this way: +

+
text=this is a \'string\'\: may contain one, or more, special characters
+
+ +

A second level of escaping is required when embedding the filter +description in a filtergraph description, in order to escape all the +filtergraph special characters. Thus the example above becomes: +

+
drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
+
+

(note that in addition to the \' escaping special characters, +also , needs to be escaped). +

+

Finally an additional level of escaping is needed when writing the +filtergraph description in a shell command, which depends on the +escaping rules of the adopted shell. For example, assuming that +\ is special and needs to be escaped with another \, the +previous string will finally result in: +

+
-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
+
+ +

In order to avoid cumbersome escaping when using a commandline tool accepting a +filter specification as input, it is advisable to avoid direct inclusion of the +filter or options specification in the shell. +

+

For example, in case of the drawtext filter, you might prefer to +use the textfile option in place of text to specify the text +to render. +

+ +

33 Timeline editing

+ +

Some filters support a generic 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: +

+
‘t’
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
‘n’
+

sequential number of the input frame, starting from 0 +

+
+
‘pos’
+

the position in the file of the input frame, NAN if unknown; deprecated, do +not use +

+
+
‘w’
+
‘h’
+

width and height of the input frame if video +

+
+ +

Additionally, these filters support an enable command that can be used +to re-define the expression. +

+

Like any other filtering option, the enable option follows the same +rules. +

+

For example, to enable a blur filter (smartblur) from 10 seconds to 3 +minutes, and a curves filter starting at 3 seconds: +

+
smartblur = enable='between(t,10,3*60)',
+curves    = enable='gte(t,3)' : preset=cross_process
+
+ +

See ffmpeg -filters to view which filters have timeline support. +

+ + +

34 Changing options at runtime with a command

+ +

Some options can be changed during the operation of the filter using +a command. These options are marked ’T’ on the output of +ffmpeg -h filter=<name of filter>. +The name of the command is the name of the option and the argument is +the new value. +

+ +

35 Options for filters with several inputs (framesync)

+ +

Some filters with several inputs support a common set of options. +These options can only be set by name, not with the short notation. +

+
+
eof_action
+

The action to take when EOF is encountered on the secondary input; it accepts +one of the following values: +

+
+
repeat
+

Repeat the last frame (the default). +

+
endall
+

End both streams. +

+
pass
+

Pass the main input through. +

+
+ +
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
repeatlast
+

If set to 1, force the filter to extend the last frame of secondary streams +until the end of the primary stream. A value of 0 disables this behavior. +Default value is 1. +

+
+
ts_sync_mode
+

How strictly to sync streams based on secondary input timestamps; it accepts +one of the following values: +

+
+
default
+

Frame from secondary input with the nearest lower or equal timestamp to the +primary input frame. +

+
nearest
+

Frame from secondary input with the absolute nearest timestamp to the primary +input frame. +

+
+
+
+ + + +

36 Audio Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the audio filters included in your +build. +

+

Below is a description of the currently available audio filters. +

+ +

36.1 aap

+

Apply Affine Projection algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to estimate unknown audio based on multiple input audio samples. +Affine projection algorithm can make trade-offs between computation complexity with convergence speed. +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
projection
+

Set the projection order. +

+
+
mu
+

Set the filter mu. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

36.2 acompressor

+ +

A compressor is mainly used to reduce the dynamic range of a signal. +Especially modern music is mostly compressed at a high ratio to +improve the overall loudness. It’s done to get the highest attention +of a listener, "fatten" the sound and bring more "power" to the track. +If a signal is compressed too much it may sound dull or "dead" +afterwards or it may start to "pump" (which could be a powerful effect +but can also destroy a track completely). +The right compression is the key to reach a professional sound and is +the high art of mixing and mastering. Because of its complex settings +it may take a long time to get the right feeling for this kind of effect. +

+

Compression is done by detecting the volume above a chosen level +threshold and dividing it by the factor set with ratio. +So if you set the threshold to -12dB and your signal reaches -6dB a ratio +of 2:1 will result in a signal at -9dB. Because an exact manipulation of +the signal would cause distortion of the waveform the reduction can be +levelled over the time. This is done by setting "Attack" and "Release". +attack determines how long the signal has to rise above the threshold +before any reduction will occur and release sets the time the signal +has to fall below the threshold to reduce the reduction again. Shorter signals +than the chosen attack time will be left untouched. +The overall reduction of the signal can be made up afterwards with the +makeup setting. So compressing the peaks of a signal about 6dB and +raising the makeup to this level results in a signal twice as loud than the +source. To gain a softer entry in the compression the knee flattens the +hard edge at the threshold in the range of the chosen decibels. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of stream rises above this level it will affect the gain +reduction. +By default it is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. 1:2 means that if the level +rose 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of input stream +or the louder(maximum) channel of input stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mostly smoother. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

36.2.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.3 acontrast

+

Simple audio dynamic range compression/expansion filter. +

+

The filter accepts the following options: +

+
+
contrast
+

Set contrast. Default is 33. Allowed range is between 0 and 100. +

+
+ + +

36.4 acopy

+ +

Copy the input audio source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

36.5 acrossfade

+ +

Apply cross fade from one input audio stream to another input audio stream. +The cross fade is applied for specified duration near the end of first stream. +

+

The filter accepts the following options: +

+
+
inputs, n
+

Specify the number of inputs to crossfade. When crossfading multiple inputs, +each input will be concatenated and crossfaded in sequence, similar to the +concat filter. Default is 2. +

+
+
nb_samples, ns
+

Specify the number of samples for which the cross fade effect has to last. +At the end of the cross fade effect the first input audio will be completely +silent. Default is 44100. +

+
+
duration, d
+

Specify the duration of the cross fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
overlap, o
+

Should first stream end overlap with second stream start. Default is enabled. +

+
+
curve1
+

Set curve for cross fade transition for first stream. +

+
+
curve2
+

Set curve for cross fade transition for second stream. +

+

For description of available curve types see afade filter description. +

+
+ + +

36.5.1 Examples

+ +
    +
  • Cross fade from one input to another: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
    +
    + +
  • Cross fade from one input to another but without overlapping: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
    +
    + +

    Concatenate multiple inputs with cross fade between each: +

    +
    ffmpeg -i first.flac -i second.flac -i third.flac -filter_complex acrossfade=n=3 output.flac
    +
    +
+ + +

36.6 acrossover

+

Split audio stream into several bands. +

+

This filter splits audio stream into two or more frequency ranges. +Summing all streams back will give flat output. +

+

The filter accepts the following options: +

+
+
split
+

Set split frequencies. Those must be positive and increasing. +

+
+
order
+

Set filter order for each band split. This controls filter roll-off or steepness +of filter transfer function. +Available values are: +

+
+
‘2nd’
+

12 dB per octave. +

+
‘4th’
+

24 dB per octave. +

+
‘6th’
+

36 dB per octave. +

+
‘8th’
+

48 dB per octave. +

+
‘10th’
+

60 dB per octave. +

+
‘12th’
+

72 dB per octave. +

+
‘14th’
+

84 dB per octave. +

+
‘16th’
+

96 dB per octave. +

+
‘18th’
+

108 dB per octave. +

+
‘20th’
+

120 dB per octave. +

+
+ +

Default is 4th. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+
gains
+

Set output gain for each band. Default value is 1 for all bands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+ + +

36.6.1 Examples

+ +
    +
  • Split input audio stream into two bands (low and high) with split frequency of 1500 Hz, +each band will be in separate stream: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but with higher filter order: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but also with additional middle band (frequencies between 1500 and 8000): +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav
    +
    +
+ + +

36.7 acrusher

+ +

Reduce audio bit resolution. +

+

This filter is bit crusher with enhanced functionality. A bit crusher +is used to audibly reduce number of bits an audio signal is sampled +with. This doesn’t change the bit depth at all, it just produces the +effect. Material reduced in bit depth sounds more harsh and "digital". +This filter is able to even round to continuous values instead of discrete +bit depths. +Additionally it has a D/C offset which results in different crushing of +the lower and the upper half of the signal. +An Anti-Aliasing setting is able to produce "softer" crushing sounds. +

+

Another feature of this filter is the logarithmic mode. +This setting switches from linear distances between bits to logarithmic ones. +The result is a much more "natural" sounding crusher which doesn’t gate low +signals for example. The human ear has a logarithmic perception, +so this kind of crushing is much more pleasant. +Logarithmic crushing is also able to get anti-aliased. +

+

The filter accepts the following options: +

+
+
level_in
+

Set level in. +

+
+
level_out
+

Set level out. +

+
+
bits
+

Set bit reduction. +

+
+
mix
+

Set mixing amount. +

+
+
mode
+

Can be linear: lin or logarithmic: log. +

+
+
dc
+

Set DC. +

+
+
aa
+

Set anti-aliasing. +

+
+
samples
+

Set sample reduction. +

+
+
lfo
+

Enable LFO. By default disabled. +

+
+
lforange
+

Set LFO range. +

+
+
lforate
+

Set LFO rate. +

+
+ + +

36.7.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.8 acue

+ +

Delay audio filtering until a given wallclock timestamp. See the cue +filter. +

+ +

36.9 adeclick

+

Remove impulsive noise from input audio. +

+

Samples detected as impulsive noise are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to +100. Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from +50 to 95. Default value is 75 percent. +Setting this to a very high value increases impulsive noise removal but makes +whole process much slower. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 2 percent. This option also +controls quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 2. +This controls the strength of impulsive noise which is going to be removed. +The lower value, the more samples will be detected as impulsive noise. +

+
+
burst, b
+

Set burst fusion, in percentage of window size. Allowed range is 0 to +10. Default value is 2. +If any two samples detected as noise are spaced less than this value then any +sample between those two samples will be also detected as noise. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly +changed with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

36.10 adeclip

+

Remove clipped samples from input audio. +

+

Samples detected as clipped are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to 100. +Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from 50 +to 95. Default value is 75 percent. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 8 percent. This option also controls +quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 10. Higher values make clip detection less aggressive. +

+
+
hsize, n
+

Set size of histogram used to detect clips. Allowed range is from 100 to 9999. +Default value is 1000. Higher values make clip detection less aggressive. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly changed +with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

36.11 adecorrelate

+

Apply decorrelation to input audio stream. +

+

The filter accepts the following options: +

+
+
stages
+

Set decorrelation stages of filtering. Allowed +range is from 1 to 16. Default value is 6. +

+
+
seed
+

Set random seed used for setting delay in samples across channels. +

+
+ + +

36.12 adelay

+ +

Delay one or more audio channels. +

+

Samples in delayed channel are filled with silence. +

+

The filter accepts the following option: +

+
+
delays
+

Set list of delays in milliseconds for each channel separated by ’|’. +Unused delays will be silently ignored. If number of given delays is +smaller than number of channels all remaining channels will not be delayed. +If you want to delay exact number of samples, append ’S’ to number. +If you want instead to delay in seconds, append ’s’ to number. +

+
+
all
+

Use last set delay for all remaining channels. By default is disabled. +This option if enabled changes how option delays is interpreted. +

+
+ + +

36.12.1 Examples

+ +
    +
  • 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. +
    +
    adelay=1500|0|500
    +
    + +
  • Delay second channel by 500 samples, the third channel by 700 samples and leave +the first channel (and any other channels that may be present) unchanged. +
    +
    adelay=0|500S|700S
    +
    + +
  • Delay all channels by same number of samples: +
    +
    adelay=delays=64S:all=1
    +
    +
+ + +

36.13 adenorm

+

Remedy denormals in audio by adding extremely low-level noise. +

+

This filter shall be placed before any filter that can produce denormals. +

+

A description of the accepted parameters follows. +

+
+
level
+

Set level of added noise in dB. Default is -351. +Allowed range is from -451 to -90. +

+
+
type
+

Set type of added noise. +

+
+
dc
+

Add DC signal. +

+
ac
+

Add AC signal. +

+
square
+

Add square signal. +

+
pulse
+

Add pulse signal. +

+
+ +

Default is dc. +

+
+ + +

36.13.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.14 aderivative, aintegral

+ +

Compute derivative/integral of audio stream. +

+

Applying both filters one after another produces original audio. +

+ +

36.15 adrc

+ +

Apply spectral dynamic range controller filter to input audio stream. +

+

A description of the accepted options follows. +

+
+
transfer
+

Set the transfer expression. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frequency power value, in dB +

+
+
f
+

current frequency in Hz +

+
+ +

Default value is p. +

+
+
attack
+

Set the attack in milliseconds. Default is 50 milliseconds. +Allowed range is from 1 to 1000 milliseconds. +

+
release
+

Set the release in milliseconds. Default is 100 milliseconds. +Allowed range is from 5 to 2000 milliseconds. +

+
channels
+

Set which channels to filter, by default all channels in audio stream are filtered. +

+
+ + +

36.15.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.15.2 Examples

+ +
    +
  • Apply spectral compression to all frequencies with threshold of -50 dB and 1:6 ratio: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/6,p)':attack=50:release=100
    +
    + +
  • Similar to above but with 1:2 ratio and filtering only front center channel: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/2,p)':attack=50:release=100:channels=FC
    +
    + +
  • Apply spectral noise gate to all frequencies with threshold of -85 dB and with short attack time and short release time: +
    +
    adrc=transfer='if(lte(p,-85),p-800,p)':attack=1:release=5
    +
    + +
  • Apply spectral expansion to all frequencies with threshold of -10 dB and 1:2 ratio: +
    +
    adrc=transfer='if(lt(p,-10),-10+(p-(-10))*2,p)':attack=50:release=100
    +
    + +
  • Apply limiter to max -60 dB to all frequencies, with attack of 2 ms and release of 10 ms: +
    +
    adrc=transfer='min(p,-60)':attack=2:release=10
    +
    +
+ + +

36.16 adynamicequalizer

+ +

Apply dynamic equalization to input audio stream. +

+

A description of the accepted options follows. +

+
+
threshold
+

Set the detection threshold used to trigger equalization. +Threshold detection is using detection filter. +Default value is 0. Allowed range is from 0 to 100. +

+
+
dfrequency
+

Set the detection frequency in Hz used for detection filter used to trigger equalization. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
dqfactor
+

Set the detection resonance factor for detection filter used to trigger equalization. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
tfrequency
+

Set the target frequency of equalization filter. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
tqfactor
+

Set the target resonance factor for target equalization filter. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
attack
+

Set the amount of milliseconds the signal from detection has to rise above +the detection threshold before equalization starts. +Default is 20. Allowed range is between 1 and 2000. +

+
+
release
+

Set the amount of milliseconds the signal from detection has to fall below the +detection threshold before equalization ends. +Default is 200. Allowed range is between 1 and 2000. +

+
+
ratio
+

Set the ratio by which the equalization gain is raised. +Default is 1. Allowed range is between 0 and 30. +

+
+
makeup
+

Set the makeup offset by which the equalization gain is raised. +Default is 0. Allowed range is between 0 and 100. +

+
+
range
+

Set the max allowed cut/boost amount. Default is 50. +Allowed range is from 1 to 200. +

+
+
mode
+

Set the mode of filter operation, can be one of the following: +

+
+
‘listen’
+

Output only isolated detection signal. +

+
‘cutbelow’
+

Cut frequencies below detection threshold. +

+
‘cutabove’
+

Cut frequencies above detection threshold. +

+
‘boostbelow’
+

Boost frequencies below detection threshold. +

+
‘boostabove’
+

Boost frequencies above detection threshold. +

+
+

Default mode is ‘cutbelow’. +

+
+
dftype
+

Set the type of detection filter, can be one of the following: +

+
+
‘bandpass’
+
‘lowpass’
+
‘highpass’
+
‘peak’
+
+

Default type is ‘bandpass’. +

+
+
tftype
+

Set the type of target filter, can be one of the following: +

+
+
‘bell’
+
‘lowshelf’
+
‘highshelf’
+
+

Default type is ‘bell’. +

+
+
auto
+

Automatically gather threshold from detection filter. By default +is ‘disabled’. +This option is useful to detect threshold in certain time frame of +input audio stream, in such case option value is changed at runtime. +

+

Available values are: +

+
‘disabled’
+

Disable using automatically gathered threshold value. +

+
‘off’
+

Stop picking threshold value. +

+
‘on’
+

Start picking threshold value. +

+
‘adaptive’
+

Adaptively pick threshold value, by calculating sliding window entropy. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

36.16.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.17 adynamicsmooth

+ +

Apply dynamic smoothing to input audio stream. +

+

A description of the accepted options follows. +

+
+
sensitivity
+

Set an amount of sensitivity to frequency fluctations. Default is 2. +Allowed range is from 0 to 1e+06. +

+
+
basefreq
+

Set a base frequency for smoothing. Default value is 22050. +Allowed range is from 2 to 1e+06. +

+
+ + +

36.17.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.18 aecho

+ +

Apply echoing to the input audio. +

+

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 delay, and the +loudness of the reflected signal is the decay. +Multiple echoes can have different delays and decays. +

+

A description of the accepted parameters follows. +

+
+
in_gain
+

Set input gain of reflected signal. Default is 0.6. +

+
+
out_gain
+

Set output gain of reflected signal. Default is 0.3. +

+
+
delays
+

Set list of time intervals in milliseconds between original signal and reflections +separated by ’|’. Allowed range for each delay is (0 - 90000.0]. +Default is 1000. +

+
+
decays
+

Set list of loudness of reflected signals separated by ’|’. +Allowed range for each decay is (0 - 1.0]. +Default is 0.5. +

+
+ + +

36.18.1 Examples

+ +
    +
  • Make it sound as if there are twice as many instruments as are actually playing: +
    +
    aecho=0.8:0.88:60:0.4
    +
    + +
  • If delay is very short, then it sounds like a (metallic) robot playing music: +
    +
    aecho=0.8:0.88:6:0.4
    +
    + +
  • A longer delay will sound like an open air concert in the mountains: +
    +
    aecho=0.8:0.9:1000:0.3
    +
    + +
  • Same as above but with one more mountain: +
    +
    aecho=0.8:0.9:1000|1800:0.3|0.25
    +
    +
+ + +

36.19 aemphasis

+

Audio emphasis filter creates or restores material directly taken from LPs or +emphased CDs with different filter curves. E.g. to store music on vinyl the +signal has to be altered by a filter first to even out the disadvantages of +this recording medium. +Once the material is played back the inverse filter has to be applied to +restore the distortion of the frequency response. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. +

+
+
level_out
+

Set output gain. +

+
+
mode
+

Set filter mode. For restoring material use reproduction mode, otherwise +use production mode. Default is reproduction mode. +

+
+
type
+

Set filter type. Selects medium. Can be one of the following: +

+
+
col
+

select Columbia. +

+
emi
+

select EMI. +

+
bsi
+

select BSI (78RPM). +

+
riaa
+

select RIAA. +

+
cd
+

select Compact Disc (CD). +

+
50fm
+

select 50µs (FM). +

+
75fm
+

select 75µs (FM). +

+
50kf
+

select 50µs (FM-KF). +

+
75kf
+

select 75µs (FM-KF). +

+
+
+
+ + +

36.19.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.20 aeval

+ +

Modify an audio signal according to the specified expressions. +

+

This filter accepts one or more expressions (one for each channel), +which are evaluated and used to modify a corresponding audio signal. +

+

It accepts the following parameters: +

+
+
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. +

+
+
channel_layout, c
+

Set output channel layout. If not specified, the channel layout is +specified by the number of expressions. If set to ‘same’, it will +use by default the same input channel layout. +

+
+ +

Each expression in exprs can contain the following constants and functions: +

+
+
ch
+

channel number of the current expression +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
s
+

sample rate +

+
+
t
+

time of the evaluated sample expressed in seconds +

+
+
nb_in_channels
+
nb_out_channels
+

input and output number of channels +

+
+
val(CH)
+

the value of input channel with number CH +

+
+ +

Note: this filter is slow. For faster processing you should use a +dedicated filter. +

+ +

36.20.1 Examples

+ +
    +
  • Half volume: +
    +
    aeval=val(ch)/2:c=same
    +
    + +
  • Invert phase of the second channel: +
    +
    aeval=val(0)|-val(1)
    +
    +
+ + +

36.21 aexciter

+ +

An exciter is used to produce high sound that is not present in the +original signal. This is done by creating harmonic distortions of the +signal which are restricted in range and added to the original signal. +An Exciter raises the upper end of an audio signal without simply raising +the higher frequencies like an equalizer would do to create a more +"crisp" or "brilliant" sound. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level prior processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
level_out
+

Set output level after processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
amount
+

Set the amount of harmonics added to original signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
drive
+

Set the amount of newly created harmonics. +Allowed range is from 0.1 to 10. +Default value is 8.5. +

+
+
blend
+

Set the octave of newly created harmonics. +Allowed range is from -10 to 10. +Default value is 0. +

+
+
freq
+

Set the lower frequency limit of producing harmonics in Hz. +Allowed range is from 2000 to 12000 Hz. +Default is 7500 Hz. +

+
+
ceil
+

Set the upper frequency limit of producing harmonics. +Allowed range is from 9999 to 20000 Hz. +If value is lower than 10000 Hz no limit is applied. +

+
+
listen
+

Mute the original signal and output only added harmonics. +By default is disabled. +

+
+ + +

36.21.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.22 afade

+ +

Apply fade-in/out effect to input audio. +

+

A description of the accepted parameters follows. +

+
+
type, t
+

Specify the effect type, can be either in for fade-in, or +out for a fade-out effect. Default is in. +

+
+
start_sample, ss
+

Specify the number of the start sample for starting to apply the fade +effect. Default is 0. +

+
+
nb_samples, ns
+

Specify the number of samples for which the fade effect has to last. 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 44100. +

+
+
start_time, st
+

Specify the start time of the fade effect. Default is 0. +The value must be specified as a time duration; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +If set this option is used instead of start_sample. +

+
+
duration, d
+

Specify the duration of the fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
curve
+

Set curve for fade transition. +

+

It accepts the following values: +

+
tri
+

select triangular, linear slope (default) +

+
qsin
+

select quarter of sine wave +

+
hsin
+

select half of sine wave +

+
esin
+

select exponential sine wave +

+
log
+

select logarithmic +

+
ipar
+

select inverted parabola +

+
qua
+

select quadratic +

+
cub
+

select cubic +

+
squ
+

select square root +

+
cbr
+

select cubic root +

+
par
+

select parabola +

+
exp
+

select exponential +

+
iqsin
+

select inverted quarter of sine wave +

+
ihsin
+

select inverted half of sine wave +

+
dese
+

select double-exponential seat +

+
desi
+

select double-exponential sigmoid +

+
losi
+

select logistic sigmoid +

+
sinc
+

select sine cardinal function +

+
isinc
+

select inverted sine cardinal function +

+
quat
+

select quartic +

+
quatr
+

select quartic root +

+
qsin2
+

select squared quarter of sine wave +

+
hsin2
+

select squared half of sine wave +

+
nofade
+

no fade applied +

+
+ +
+
silence
+

Set the initial gain for fade-in or final gain for fade-out. +Default value is 0.0. +

+
+
unity
+

Set the initial gain for fade-out or final gain for fade-in. +Default value is 1.0. +

+
+ + +

36.22.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.22.2 Examples

+ +
    +
  • Fade in first 15 seconds of audio: +
    +
    afade=t=in:ss=0:d=15
    +
    + +
  • Fade out last 25 seconds of a 900 seconds audio: +
    +
    afade=t=out:st=875:d=25
    +
    +
+ + +

36.23 afftdn

+

Denoise audio samples with FFT. +

+

A description of the accepted parameters follows. +

+
+
noise_reduction, nr
+

Set the noise reduction in dB, allowed range is 0.01 to 97. +Default value is 12 dB. +

+
+
noise_floor, nf
+

Set the noise floor in dB, allowed range is -80 to -20. +Default value is -50 dB. +

+
+
noise_type, nt
+

Set the noise type. +

+

It accepts the following values: +

+
white, w
+

Select white noise. +

+
+
vinyl, v
+

Select vinyl noise. +

+
+
shellac, s
+

Select shellac noise. +

+
+
custom, c
+

Select custom noise, defined in bn option. +

+

Default value is white noise. +

+
+ +
+
band_noise, bn
+

Set custom band noise profile for every one of 15 bands. +Bands are separated by ’ ’ or ’|’. +

+
+
residual_floor, rf
+

Set the residual floor in dB, allowed range is -80 to -20. +Default value is -38 dB. +

+
+
track_noise, tn
+

Enable noise floor tracking. By default is disabled. +With this enabled, noise floor is automatically adjusted. +

+
+
track_residual, tr
+

Enable residual tracking. By default is disabled. +

+
+
output_mode, om
+

Set the output mode. +

+

It accepts the following values: +

+
input, i
+

Pass input unchanged. +

+
+
output, o
+

Pass noise filtered out. +

+
+
noise, n
+

Pass only noise. +

+

Default value is output. +

+
+ +
+
adaptivity, ad
+

Set the adaptivity factor, used how fast to adapt gains adjustments per +each frequency bin. Value 0 enables instant adaptation, while higher values +react much slower. +Allowed range is from 0 to 1. Default value is 0.5. +

+
+
floor_offset, fo
+

Set the noise floor offset factor. This option is used to adjust offset applied to measured +noise floor. It is only effective when noise floor tracking is enabled. +Allowed range is from -2.0 to 2.0. Default value is 1.0. +

+
+
noise_link, nl
+

Set the noise link used for multichannel audio. +

+

It accepts the following values: +

+
none
+

Use unchanged channel’s noise floor. +

+
+
min
+

Use measured min noise floor of all channels. +

+
+
max
+

Use measured max noise floor of all channels. +

+
+
average
+

Use measured average noise floor of all channels. +

+

Default value is min. +

+
+ +
+
band_multiplier, bm
+

Set the band multiplier factor, used how much to spread bands across frequency bins. +Allowed range is from 0.2 to 5. Default value is 1.25. +

+
+
sample_noise, sn
+

Toggle capturing and measurement of noise profile from input audio. +

+

It accepts the following values: +

+
start, begin
+

Start sample noise capture. +

+
+
stop, end
+

Stop sample noise capture and measure new noise band profile. +

+

Default value is none. +

+
+ +
+
gain_smooth, gs
+

Set gain smooth spatial radius, used to smooth gains applied to each frequency bin. +Useful to reduce random music noise artefacts. +Higher values increases smoothing of gains. +Allowed range is from 0 to 50. +Default value is 0. +

+
+ + +

36.23.1 Commands

+ +

This filter supports the some above mentioned options as commands. +

+ +

36.23.2 Examples

+ +
    +
  • Reduce white noise by 10dB, and use previously measured noise floor of -40dB: +
    +
    afftdn=nr=10:nf=-40
    +
    + +
  • Reduce white noise by 10dB, also set initial noise floor to -80dB and enable automatic +tracking of noise floor so noise floor will gradually change during processing: +
    +
    afftdn=nr=10:nf=-80:tn=1
    +
    + +
  • Reduce noise by 20dB, using noise floor of -40dB and using commands to take noise profile +of first 0.4 seconds of input audio: +
    +
    asendcmd=0.0 afftdn sn start,asendcmd=0.4 afftdn sn stop,afftdn=nr=20:nf=-40
    +
    +
+ + +

36.24 afftfilt

+

Apply arbitrary expressions to samples in frequency domain. +

+
+
real
+

Set frequency domain real expression for each separate channel separated +by ’|’. Default is "re". +If the number of input channels is greater than the number of +expressions, the last specified expression is used for the remaining +output channels. +

+
+
imag
+

Set frequency domain imaginary expression for each separate channel +separated by ’|’. Default is "im". +

+

Each expression in real and imag can contain the following +constants and functions: +

+
+
sr
+

sample rate +

+
+
b
+

current frequency bin number +

+
+
nb
+

number of available bins +

+
+
ch
+

channel number of the current expression +

+
+
chs
+

number of channels +

+
+
pts
+

current frame pts +

+
+
re
+

current real part of frequency bin of current channel +

+
+
im
+

current imaginary part of frequency bin of current channel +

+
+
real(b, ch)
+

Return the value of real part of frequency bin at location (bin,channel) +

+
+
imag(b, ch)
+

Return the value of imaginary part of frequency bin at location (bin,channel) +

+
+ +
+
win_size
+

Set window size. Allowed range is from 16 to 131072. +Default is 4096 +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.75. +

+
+ + +

36.24.1 Examples

+ +
    +
  • Leave almost only low frequencies in audio: +
    +
    afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
    +
    + +
  • Apply robotize effect: +
    +
    afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
    +
    + +
  • Apply whisper effect: +
    +
    afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8"
    +
    + +
  • Apply phase shift: +
    +
    afftfilt="real=re*cos(1)-im*sin(1):imag=re*sin(1)+im*cos(1)"
    +
    +
+ + +

36.25 afir

+ +

Apply an arbitrary Finite Impulse Response filter. +

+

This filter is designed for applying long FIR filters, +up to 60 seconds long. +

+

It can be used as component for digital crossover filters, +room equalization, cross talk cancellation, wavefield synthesis, +auralization, ambiophonics, ambisonics and spatialization. +

+

This filter uses the streams higher than first one as FIR coefficients. +If the non-first stream holds a single channel, it will be used +for all input channels in the first stream, otherwise +the number of channels in the non-first stream must be same as +the number of channels in the first stream. +

+

It accepts the following parameters: +

+
+
dry
+

Set dry gain. This sets input gain. +

+
+
wet
+

Set wet gain. This sets final output gain. +

+
+
length
+

Set Impulse Response filter length. Default is 1, which means whole IR is processed. +

+
+
gtype
+

This option is deprecated, and does nothing. +

+
+
irnorm
+

Set norm to be applied to IR coefficients before filtering. +Allowed range is from -1 to 2. +IR coefficients are normalized with calculated vector norm set by this option. +For negative values, no norm is calculated, and IR coefficients are not modified at all. +Default is 1. +

+
+
irlink
+

For multichannel IR if this option is set to true, all IR channels will be +normalized with maximal measured gain of all IR channels coefficients as set by irnorm option. +When disabled, all IR coefficients in each IR channel will be normalized independently. +Default is true. +

+
+
irgain
+

Set gain to be applied to IR coefficients before filtering. +Allowed range is 0 to 1. This gain is applied after any gain applied with irnorm option. +

+
+
irfmt
+

Set format of IR stream. Can be mono or input. +Default is input. +

+
+
maxir
+

Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. +Allowed range is 0.1 to 60 seconds. +

+
+
response
+

This option is deprecated, and does nothing. +

+
+
channel
+

This option is deprecated, and does nothing. +

+
+
size
+

This option is deprecated, and does nothing. +

+
+
rate
+

This option is deprecated, and does nothing. +

+
+
minp
+

Set minimal partition size used for convolution. Default is 8192. +Allowed range is from 1 to 65536. +Lower values decreases latency at cost of higher CPU usage. +

+
+
maxp
+

Set maximal partition size used for convolution. Default is 8192. +Allowed range is from 8 to 65536. +Lower values may increase CPU usage. +

+
+
nbirs
+

Set number of input impulse responses streams which will be switchable at runtime. +Allowed range is from 1 to 32. Default is 1. +

+
+
ir
+

Set IR stream which will be used for convolution, starting from 0, should always be +lower than supplied value by nbirs option. Default is 0. +This option can be changed at runtime via commands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+
irload
+

Set when to load IR stream. Can be init or access. +First one load and prepares all IRs on initialization, second one +once on first access of specific IR. +Default is init. +

+
+ + +

36.25.1 Examples

+ +
    +
  • Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: +
    +
    ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
    +
    + +
  • Apply true stereo processing given input stereo stream, and two stereo impulse responses for left and right channel, +the impulse response files are files with names l_ir.wav and r_ir.wav, and setting irnorm option value: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irnorm=1.2,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    + +
  • Similar to above example, but with irgain explicitly set to estimated value and with irnorm disabled: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irgain=-5dB:irnom=-1,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    +
+ + +

36.26 aformat

+ +

Set output format constraints for the input audio. The framework will +negotiate the most appropriate format to minimize conversions. +

+

It accepts the following parameters: +

+
sample_fmts, f
+

A ’|’-separated list of requested sample formats. +

+
+
sample_rates, r
+

A ’|’-separated list of requested sample rates. +

+
+
channel_layouts, cl
+

A ’|’-separated list of requested channel layouts. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+ +

If a parameter is omitted, all values are allowed. +

+

Force the output to either unsigned 8-bit or signed 16-bit stereo +

+
aformat=sample_fmts=u8|s16:channel_layouts=stereo
+
+ + +

36.27 afreqshift

+

Apply frequency shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify frequency shift. Allowed range is -INT_MAX to INT_MAX. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

36.27.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.28 afwtdn

+

Reduce broadband noise from input samples using Wavelets. +

+

A description of the accepted options follows. +

+
+
sigma
+

Set the noise sigma, allowed range is from 0 to 1. +Default value is 0. +This option controls strength of denoising applied to input samples. +Most useful way to set this option is via decibels, eg. -45dB. +

+
+
levels
+

Set the number of wavelet levels of decomposition. +Allowed range is from 1 to 12. +Default value is 10. +Setting this too low make denoising performance very poor. +

+
+
wavet
+

Set wavelet type for decomposition of input frame. +They are sorted by number of coefficients, from lowest to highest. +More coefficients means worse filtering speed, but overall better quality. +Available wavelets are: +

+
+
‘sym2’
+
‘sym4’
+
‘rbior68’
+
‘deb10’
+
‘sym10’
+
‘coif5’
+
‘bl3’
+
+ +
+
percent
+

Set percent of full denoising. Allowed range is from 0 to 100 percent. +Default value is 85 percent or partial denoising. +

+
+
profile
+

If enabled, first input frame will be used as noise profile. +If first frame samples contain non-noise performance will be very poor. +

+
+
adaptive
+

If enabled, input frames are analyzed for presence of noise. +If noise is detected with high possibility then input frame profile will be +used for processing following frames, until new noise frame is detected. +

+
+
samples
+

Set size of single frame in number of samples. Allowed range is from 512 to +65536. Default frame size is 8192 samples. +

+
+
softness
+

Set softness applied inside thresholding function. Allowed range is from 0 to +10. Default softness is 1. +

+
+ + +

36.28.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.29 agate

+ +

A gate is mainly used to reduce lower parts of a signal. This kind of signal +processing reduces disturbing noise between useful signals. +

+

Gating is done by detecting the volume below a chosen level threshold +and dividing it by the factor set with ratio. The bottom of the noise +floor is set via range. Because an exact manipulation of the signal +would cause distortion of the waveform the reduction can be levelled over +time. This is done by setting attack and release. +

+

attack determines how long the signal has to fall below the threshold +before any reduction will occur and release sets the time the signal +has to rise above the threshold to reduce the reduction again. +Shorter signals than the chosen attack time will be left untouched. +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+ + +

36.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.30 aiir

+ +

Apply an arbitrary Infinite Impulse Response filter. +

+

It accepts the following parameters: +

+
+
zeros, z
+

Set B/numerator/zeros/reflection coefficients. +

+
+
poles, p
+

Set A/denominator/poles/ladder coefficients. +

+
+
gains, k
+

Set channels gains. +

+
+
dry_gain
+

Set input gain. +

+
+
wet_gain
+

Set output gain. +

+
+
format, f
+

Set coefficients format. +

+
+
‘ll’
+

lattice-ladder function +

+
‘sf’
+

analog transfer function +

+
‘tf’
+

digital transfer function +

+
‘zp’
+

Z-plane zeros/poles, cartesian (default) +

+
‘pr’
+

Z-plane zeros/poles, polar radians +

+
‘pd’
+

Z-plane zeros/poles, polar degrees +

+
‘sp’
+

S-plane zeros/poles +

+
+ +
+
process, r
+

Set type of processing. +

+
+
‘d’
+

direct processing +

+
‘s’
+

serial processing +

+
‘p’
+

parallel processing +

+
+ +
+
precision, e
+

Set filtering precision. +

+
+
‘dbl’
+

double-precision floating-point (default) +

+
‘flt’
+

single-precision floating-point +

+
‘i32’
+

32-bit integers +

+
‘i16’
+

16-bit integers +

+
+ +
+
normalize, n
+

Normalize filter coefficients, by default is enabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
mix
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
response
+

Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. +By default it is disabled. +

+
+
channel
+

Set for which IR channel to display frequency response. By default is first channel +displayed. This option is used only when response is enabled. +

+
+
size
+

Set video stream size. This option is used only when response is enabled. +

+
+ +

Coefficients in tf and sf format are separated by spaces and are in ascending +order. +

+

Coefficients in zp format are separated by spaces and order of coefficients +doesn’t matter. Coefficients in zp format are complex numbers with i +imaginary unit. +

+

Different coefficients and gains can be provided for every channel, in such case +use ’|’ to separate coefficients or gains. Last provided coefficients will be +used for all remaining channels. +

+ +

36.30.1 Examples

+ +
    +
  • Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate: +
    +
    aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
    +
    + +
  • Same as above but in zp format: +
    +
    aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
    +
    + +
  • Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format: +
    +
    aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
    +
    +
+ + +

36.31 alimiter

+ +

The limiter prevents an input signal from rising over a desired threshold. +This limiter uses lookahead technology to prevent your signal from distorting. +It means that there is a small delay after the signal is processed. Keep in mind +that the delay it produces is the attack time you set. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
limit
+

Don’t let signals above this level pass the limiter. Default is 1. +

+
+
attack
+

The limiter will reach its attenuation level in this amount of time in +milliseconds. Default is 5 milliseconds. +

+
+
release
+

Come back from limiting to attenuation 1.0 in this amount of milliseconds. +Default is 50 milliseconds. +

+
+
asc
+

When gain reduction is always needed ASC takes care of releasing to an +average reduction level rather than reaching a reduction of 0 in the release +time. +

+
+
asc_level
+

Select how much the release time is affected by ASC, 0 means nearly no changes +in release time while 1 produces higher release times. +

+
+
level
+

Auto level output signal. Default is enabled. +This normalizes audio back to 0dB if enabled. +

+
+
latency
+

Compensate the delay introduced by using the lookahead buffer set with attack +parameter. Also flush the valid audio data in the lookahead buffer when the +stream hits EOF. +

+
+ +

Depending on picked setting it is recommended to upsample input 2x or 4x times +with aresample before applying this filter. +

+ +

36.32 allpass

+ +

Apply a two-pole all-pass filter with central frequency (in Hz) +frequency, and filter-width 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: +

+
+
frequency, f
+

Set frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
order, o
+

Set the filter order, can be 1 or 2. Default is 2. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+
+
+ + +

36.32.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change allpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change allpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change allpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change allpass mix. +Syntax for the command is : "mix" +

+
+ + +

36.33 aloop

+ +

Loop audio samples. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal number of samples. Default is 0. +

+
+
start
+

Set first sample of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

36.34 amerge

+ +

Merge two or more audio streams into a single multi-channel stream. +

+

All inputs must have the same sample rate, and format. +

+

If inputs do not have the same duration, the output will stop with the +shortest. +

+

The filter accepts the following options: +

+
+
inputs
+

Set the number of inputs. Default is 2. +

+
+
layout_mode
+
+

This option controls how the output channel layout is determined and if the +audio channels are reordered during merge. +

+
+
legacy
+
+

This is the mode how the filter behaved historically so it is the default. +

+

If the channel layouts of the inputs are known and disjoint, and therefore +compatible, the channel layout of the output will be set accordingly and the +channels will be reordered as necessary. If the channel layouts of the inputs +are not disjoint, some of them are unknown, or they are using special channel +layouts, such as ambisonics, the output will have all the channels of the first +input then all the channels of the second input, in that order, and the channel +layout of the output will be the default value corresponding to the total +number of channels. +

+

For example, if the first input is in 2.1 (FL+FR+LF) and the second input +is FC+BL+BR, then the output will be in 5.1, with the channels in the +following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the +first input, b1 is the first channel of the second input). +

+

On the other hand, if both input are in stereo, the output channels will be +in the default order: a1, a2, b1, b2, and the channel layout will be +arbitrarily set to 4.0, which may or may not be the expected value. +

+
+
reset
+

This mode ignores the input channel layouts and does no channel reordering. +The output will have all the channels of the first input, then all the channels +of the second input, in that order, and so on. +

+

The output channel layout will only specify the total channel count. +

+
+
normal
+

This mode keeps channel name and designation information from the input +channels and does no channel reordering. The output will have all the channels +of the first input, then all the channels of the second input, in that order, +and so on. +

+
+
+ +
+
+ + +

36.34.1 Examples

+ +
    +
  • Merge two mono files into a stereo stream: +
    +
    amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
    +
    + +
  • Multiple merges assuming 1 video stream and 6 audio streams in input.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
    +
    +
+ + +

36.35 amix

+ +

Mixes multiple audio inputs into a single output. +

+

Note that this filter only supports float samples (the amerge +and pan audio filters support many formats). If the amix +input has integer samples then aresample will be automatically +inserted to perform the conversion to float samples. +

+

It accepts the following parameters: +

+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
duration
+

How to determine the end-of-stream. +

+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+
+ +
+
dropout_transition
+

The transition time, in seconds, for volume renormalization when an input +stream ends. The default value is 2 seconds. +

+
+
weights
+

Specify weight of each input audio stream as a sequence of numbers separated +by a space. If fewer weights are specified compared to number of inputs, the +last weight is assigned to the remaining inputs. +Default weight for each input is 1. +

+
+
normalize
+

Always scale inputs instead of only doing summation of samples. +Beware of heavy clipping if inputs are not normalized prior or after filtering +by this filter if this option is disabled. By default is enabled. +

+
+ + +

36.35.1 Examples

+ +
    +
  • This will mix 3 input audio streams to a single output with the same duration as the +first input and a dropout transition time of 3 seconds: +
    +
    ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
    +
    + +
  • This will mix one vocal and one music input audio stream to a single output with the same duration as the +longest input. The music will have quarter the weight as the vocals, and the inputs are not normalized: +
    +
    ffmpeg -i VOCALS -i MUSIC -filter_complex amix=inputs=2:duration=longest:dropout_transition=0:weights="1 0.25":normalize=0 OUTPUT
    +
    + +
+ + +

36.35.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
normalize
+

Syntax is same as option with same name. +

+
+ + +

36.36 amultiply

+ +

Multiply first audio stream with second audio stream and store result +in output audio stream. Multiplication is done by multiplying each +sample from first stream with sample at same position from second stream. +

+

With this element-wise multiplication one can create amplitude fades and +amplitude modulations. +

+ +

36.37 anequalizer

+ +

High-order parametric multiband equalizer for each channel. +

+

It accepts the following parameters: +

+
params
+
+

This option string is in format: +"cchn f=cf w=w g=g t=f | ..." +Each equalizer band is separated by ’|’. +

+
+
chn
+

Set channel number to which equalization will be applied. +If input doesn’t have that channel the entry is ignored. +

+
+
f
+

Set central frequency for band. +If input doesn’t have that frequency the entry is ignored. +

+
+
w
+

Set band width in Hertz. +

+
+
g
+

Set band gain in dB. +

+
+
t
+

Set filter type for band, optional, can be: +

+
+
‘0’
+

Butterworth, this is default. +

+
+
‘1’
+

Chebyshev type 1. +

+
+
‘2’
+

Chebyshev type 2. +

+
+
+
+ +
+
curves
+

With this option activated frequency response of anequalizer is displayed +in video stream. +

+
+
size
+

Set video stream size. Only useful if curves option is activated. +

+
+
mgain
+

Set max gain that will be displayed. Only useful if curves option is activated. +Setting this to a reasonable value makes it possible to display gain which is derived from +neighbour bands which are too close to each other and thus produce higher gain +when both are activated. +

+
+
fscale
+

Set frequency scale used to draw frequency response in video output. +Can be linear or logarithmic. Default is logarithmic. +

+
+
colors
+

Set color for each channel curve which is going to be displayed in video stream. +This is list of color names separated by space or by ’|’. +Unrecognised or missing colors will be replaced by white color. +

+
+ + +

36.37.1 Examples

+ +
    +
  • Lower gain by 10 of central frequency 200Hz and width 100 Hz +for first 2 channels using Chebyshev type 1 filter: +
    +
    anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
    +
    +
+ + +

36.37.2 Commands

+ +

This filter supports the following commands: +

+
change
+

Alter existing filter parameters. +Syntax for the commands is : "fN|f=freq|w=width|g=gain" +

+

fN is existing filter number, starting from 0, if no such filter is available +error is returned. +freq set new frequency parameter. +width set new width parameter in Hertz. +gain set new gain parameter in dB. +

+

Full filter invocation with asendcmd may look like this: +asendcmd=c=’4.0 anequalizer change 0|f=200|w=50|g=1’,anequalizer=... +

+
+ + +

36.38 anlmdn

+ +

Reduce broadband noise in audio samples using Non-Local Means algorithm. +

+

Each sample is adjusted by looking for other samples with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +p. Patches are searched in an area of r around the sample. +

+

The filter accepts the following options: +

+
+
strength, s
+

Set denoising strength. Allowed range is from 0.00001 to 10000. Default value is 0.00001. +

+
+
patch, p
+

Set patch radius duration. Allowed range is from 1 to 100 milliseconds. +Default value is 2 milliseconds. +

+
+
research, r
+

Set research radius duration. Allowed range is from 2 to 300 milliseconds. +Default value is 6 milliseconds. +

+
+
output, o
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass noise filtered out. +

+
+
n
+

Pass only noise. +

+

Default value is o. +

+
+ +
+
smooth, m
+

Set smooth factor. Default value is 11. Allowed range is from 1 to 1000. +

+
+ + +

36.38.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.39 anlmf, anlms

+

Apply Normalized Least-Mean-(Squares|Fourth) algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by finding the filter coefficients that +relate to producing the least mean square of the error signal (difference between the desired, +2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set filter order. +

+
+
mu
+

Set filter mu. +

+
+
eps
+

Set the filter eps. +

+
+
leakage
+

Set the filter leakage. +

+
+
out_mode
+

It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

36.39.1 Examples

+ +
    +
  • One of many usages of this filter is noise reduction, input audio is filtered +with same samples that are delayed by fixed amount, one such example for stereo audio is: +
    +
    asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
    +
    +
+ + +

36.39.2 Commands

+ +

This filter supports the same commands as options, excluding option order. +

+ +

36.40 anull

+ +

Pass the audio source unchanged to the output. +

+ +

36.41 apad

+ +

Pad the end of an audio stream with silence. +

+

This can be used together with ffmpeg -shortest to +extend audio streams to the same length as the video stream. +

+

A description of the accepted options follows. +

+
+
packet_size
+

Set silence packet size. Default value is 4096. +

+
+
pad_len
+

Set the number of samples of silence to add to the end. After the +value is reached, the stream is terminated. This option is mutually +exclusive with whole_len. +

+
+
whole_len
+

Set the minimum total number of samples in the output audio stream. If +the value is longer than the input audio length, silence is added to +the end, until the value is reached. This option is mutually exclusive +with pad_len. +

+
+
pad_dur
+

Specify the duration of samples of silence to add. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. +

+
+
whole_dur
+

Specify the minimum total duration in the output audio stream. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. If the value is longer than +the input audio length, silence is added to the end, until the value is reached. +This option is mutually exclusive with pad_dur +

+
+ +

If neither the pad_len nor the whole_len nor pad_dur +nor whole_dur option is set, the filter will add silence to the end of +the input stream indefinitely. +

+

Note that for ffmpeg 4.4 and earlier a zero pad_dur or +whole_dur also caused the filter to add silence indefinitely. +

+ +

36.41.1 Examples

+ +
    +
  • Add 1024 samples of silence to the end of the input: +
    +
    apad=pad_len=1024
    +
    + +
  • Make sure the audio output will contain at least 10000 samples, pad +the input with silence if required: +
    +
    apad=whole_len=10000
    +
    + +
  • Use ffmpeg to pad the audio input with silence, so that the +video stream will always result the shortest and will be converted +until the end in the output file when using the shortest +option: +
    +
    ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
    +
    +
+ + +

36.42 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. +

+
+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.74 +

+
+
delay
+

Set delay in milliseconds. Default is 3.0. +

+
+
decay
+

Set decay. Default is 0.4. +

+
+
speed
+

Set modulation speed in Hz. Default is 0.5. +

+
+
type
+

Set modulation type. Default is triangular. +

+

It accepts the following values: +

+
‘triangular, t’
+
‘sinusoidal, s’
+
+
+
+ + +

36.43 aphaseshift

+

Apply phase shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify phase shift. Allowed range is from -1.0 to 1.0. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

36.43.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.44 apsnr

+

Measure Audio Peak Signal-to-Noise Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

36.45 apsyclip

+

Apply Psychoacoustic clipper to input audio stream. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
clip
+

Set the clipping start value. Default value is 0dBFS or 1. +

+
+
diff
+

Output only difference samples, useful to hear introduced distortions. +By default is disabled. +

+
+
adaptive
+

Set strength of adaptive distortion applied. Default value is 0.5. +Allowed range is from 0 to 1. +

+
+
iterations
+

Set number of iterations of psychoacoustic clipper. +Allowed range is from 1 to 20. Default value is 10. +

+
+
level
+

Auto level output signal. Default is disabled. +This normalizes audio back to 0dBFS if enabled. +

+
+ + +

36.45.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.46 apulsator

+ +

Audio pulsator is something between an autopanner and a tremolo. +But it can produce funny stereo effects as well. Pulsator changes the volume +of the left and right channel based on a LFO (low frequency oscillator) with +different waveforms and shifted phases. +This filter have the ability to define an offset between left and right +channel. An offset of 0 means that both LFO shapes match each other. +The left and right channel are altered equally - a conventional tremolo. +An offset of 50% means that the shape of the right channel is exactly shifted +in phase (or moved backwards about half of the frequency) - pulsator acts as +an autopanner. At 1 both curves match again. Every setting in between moves the +phase shift gapless between all stages and produces some "bypassing" sounds with +sine and triangle waveforms. The more you set the offset near 1 (starting from +the 0.5) the faster the signal passes from the left to the right speaker. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
mode
+

Set waveform shape the LFO will use. Can be one of: sine, triangle, square, +sawup or sawdown. Default is sine. +

+
+
amount
+

Set modulation. Define how much of original signal is affected by the LFO. +

+
+
offset_l
+

Set left channel offset. Default is 0. Allowed range is [0 - 1]. +

+
+
offset_r
+

Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. +

+
+
width
+

Set pulse width. Default is 1. Allowed range is [0 - 2]. +

+
+
timing
+

Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. +

+
+
bpm
+

Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing +is set to bpm. +

+
+
ms
+

Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing +is set to ms. +

+
+
hz
+

Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used +if timing is set to hz. +

+
+ + +

36.47 aresample

+ +

Resample the input audio to the specified parameters, using the +libswresample library. If none are specified then the filter will +automatically convert between its input and output. +

+

This filter is also able to stretch/squeeze the audio data to make it match +the timestamps or to inject silence / cut out audio to make it match the +timestamps, do a combination of both or do neither. +

+

The filter accepts the syntax +[sample_rate:]resampler_options, where sample_rate +expresses a sample rate and resampler_options is a list of +key=value pairs, separated by ":". See the +"Resampler Options" section in the +ffmpeg-resampler(1) manual +for the complete list of supported options. +

+ +

36.47.1 Examples

+ +
    +
  • Resample the input audio to 44100Hz: +
    +
    aresample=44100
    +
    + +
  • Stretch/squeeze samples to the given timestamps, with a maximum of 1000 +samples per second compensation: +
    +
    aresample=async=1000
    +
    +
+ + +

36.48 areverse

+ +

Reverse an audio clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

36.48.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    atrim=end=5,areverse
    +
    +
+ + +

36.49 arls

+

Apply Recursive Least Squares algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by recursively finding the filter coefficients that +relate to producing the minimal weighted linear least squares cost function of the error signal (difference +between the desired, 2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
lambda
+

Set the forgetting factor. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

36.50 arnndn

+ +

Reduce noise from speech using Recurrent Neural Networks. +

+

This filter accepts the following options: +

+
+
model, m
+

Set train model file to load. This option is always required. +

+
+
mix
+

Set how much to mix filtered samples into final output. +Allowed range is from -1 to 1. Default value is 1. +Negative values are special, they set how much to keep filtered noise +in the final filter output. Set this option to -1 to hear actual +noise removed from input signal. +

+
+ + +

36.50.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.51 asdr

+

Measure Audio Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

36.52 asetnsamples

+ +

Set the number of samples per each output audio frame. +

+

The last output packet may contain a different number of samples, as +the filter will flush all the remaining samples when the input audio +signals its end. +

+

The filter accepts the following options: +

+
+
nb_out_samples, n
+

Set the number of frames per each output audio frame. The number is +intended as the number of samples per each channel. +Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio frame with zeroes, so +that the last frame will contain the same number of samples as the +previous ones. Default value is 1. +

+
+ +

For example, to set the number of per-frame samples to 1234 and +disable padding for the last frame, use: +

+
asetnsamples=n=1234:p=0
+
+ + +

36.53 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: +

+
+
sample_rate, r
+

Set the output sample rate. Default is 44100 Hz. +

+
+ + +

36.54 ashowinfo

+ +

Show a line containing various information for each input audio frame. +The input audio is not modified. +

+

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The presentation timestamp of the input frame, in time base units; the time base +depends on the filter input pad, and is usually 1/sample_rate. +

+
+
pts_time
+

The presentation timestamp of the input frame in seconds. +

+
+
fmt
+

The sample format. +

+
+
chlayout
+

The channel layout. +

+
+
rate
+

The sample rate for the audio frame. +

+
+
nb_samples
+

The number of samples (per channel) in the frame. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar +audio, the data is treated as if all the planes were concatenated. +

+
+
plane_checksums
+

A list of Adler-32 checksums for each data plane. +

+
+ + +

36.55 asisdr

+

Measure Audio Scaled-Invariant Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

36.56 asoftclip

+

Apply audio soft clipping. +

+

Soft clipping is a type of distortion effect where the amplitude of a signal is saturated +along a smooth curve, rather than the abrupt shape of hard-clipping. +

+

This filter accepts the following options: +

+
+
type
+

Set type of soft-clipping. +

+

It accepts the following values: +

+
hard
+
tanh
+
atan
+
cubic
+
exp
+
alg
+
quintic
+
sin
+
erf
+
+ +
+
threshold
+

Set threshold from where to start clipping. Default value is 0dB or 1. +

+
+
output
+

Set gain applied to output. Default value is 0dB or 1. +

+
+
param
+

Set additional parameter which controls sigmoid function. +

+
+
oversample
+

Set oversampling factor. +

+
+ + +

36.56.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.57 aspectralstats

+ +

Display frequency domain statistical information about the audio channels. +Statistics are calculated and stored as metadata for each audio channel and for each audio frame. +

+

It accepts the following option: +

+
win_size
+

Set the window length in samples. Default value is 2048. +Allowed range is from 32 to 65536. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. Allowed range is from 0 +to 1. Default value is 0.5. +

+
+
measure
+

Select the parameters which are measured. The metadata keys can +be used as flags, default is all which measures everything. +none disables all measurement. +

+
+ +

A list of each metadata key follows: +

+
+
mean
+
variance
+
centroid
+
spread
+
skewness
+
kurtosis
+
entropy
+
flatness
+
crest
+
flux
+
slope
+
decrease
+
rolloff
+
+ + +

36.58 asr

+

Automatic Speech Recognition +

+

This filter uses PocketSphinx for speech recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-pocketsphinx. +

+

It accepts the following options: +

+
+
rate
+

Set sampling rate of input audio. Defaults is 16000. +This need to match speech models, otherwise one will get poor results. +

+
+
hmm
+

Set dictionary containing acoustic model files. +

+
+
dict
+

Set pronunciation dictionary. +

+
+
lm
+

Set language model file. +

+
+
lmctl
+

Set language model set. +

+
+
lmname
+

Set which language model to use. +

+
+
logfn
+

Set output for log messages. +

+
+ +

The filter exports recognized speech as the frame metadata lavfi.asr.text. +

+ +

36.59 astats

+ +

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. +

+

It accepts the following option: +

+
length
+

Short window length in seconds, used for peak and through RMS measurement. +Default is 0.05 (50 milliseconds). Allowed range is [0 - 10]. +

+
+
metadata
+
+

Set metadata injection. All the metadata keys are prefixed with lavfi.astats.X, +where X is channel number starting from 1 or string Overall. Default is +disabled. +

+

Available keys for each channel are: +Bit_depth +Crest_factor +DC_offset +Dynamic_range +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_peak +RMS_trough +Zero_crossings +Zero_crossings_rate +

+

and for Overall: +Bit_depth +DC_offset +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Number_of_samples +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_level +RMS_peak +RMS_trough +

+

For example, a full key looks like lavfi.astats.1.DC_offset or +lavfi.astats.Overall.Peak_count. +

+

Read below for the description of the keys. +

+
+
reset
+

Set the number of frames over which cumulative stats are calculated before +being reset. Default is disabled. +

+
+
measure_perchannel
+

Select the parameters which are measured per channel. The metadata keys can +be used as flags, default is all which measures everything. +none disables all per channel measurement. +

+
+
measure_overall
+

Select the parameters which are measured overall. The metadata keys can +be used as flags, default is all which measures everything. +none disables all overall measurement. +

+
+
+ +

A description of the measure keys follow: +

+
+
none
+

no measures +

+
+
all
+

all measures +

+
+
Bit_depth
+

overall bit depth of audio, i.e. number of bits used for each sample +

+
+
Crest_factor
+

standard ratio of peak to RMS level (note: not in dB) +

+
+
DC_offset
+

mean amplitude displacement from zero +

+
+
Dynamic_range
+

measured dynamic range of audio in dB +

+
+
Entropy
+

entropy measured across whole audio, entropy of value near 1.0 is typically measured for white noise +

+
+
Flat_factor
+

flatness (i.e. consecutive samples with the same value) of the signal at its peak levels +(i.e. either Min_level or Max_level) +

+
+
Max_difference
+

maximal difference between two consecutive samples +

+
+
Max_level
+

maximal sample level +

+
+
Mean_difference
+

mean difference between two consecutive samples, i.e. the average of each difference between two consecutive samples +

+
+
Min_difference
+

minimal difference between two consecutive samples +

+
+
Min_level
+

minimal sample level +

+
+
Noise_floor
+

minimum local peak measured in dBFS over a short window +

+
+
Noise_floor_count
+

number of occasions (not the number of samples) that the signal attained +Noise floor +

+
+
Number_of_Infs
+

number of samples with an infinite value +

+
+
Number_of_NaNs
+

number of samples with a NaN (not a number) value +

+
+
Number_of_denormals
+

number of samples with a subnormal value +

+
+
Number_of_samples
+

number of samples +

+
+
Peak_count
+

number of occasions (not the number of samples) that the signal attained either +Min_level or Max_level +

+
+
Abs_Peak_count
+

number of occasions that the absolute samples taken from the signal attained +max absolute value of Min_level and Max_level +

+
+
Peak_level
+

standard peak level measured in dBFS +

+
+
RMS_difference
+

Root Mean Square difference between two consecutive samples +

+
+
RMS_level
+

standard RMS level measured in dBFS +

+
+
RMS_peak
+
RMS_trough
+

peak and through values for RMS level measured over a short window, +measured in dBFS. +

+
+
Zero crossings
+

number of points where the waveform crosses the zero level axis +

+
+
Zero crossings rate
+

rate of Zero crossings and number of audio samples +

+
+ + +

36.60 asubboost

+

Boost subwoofer frequencies. +

+

The filter accepts the following options: +

+
+
dry
+

Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
wet
+

Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
boost
+

Set max boost factor. Allowed range is from 1 to 12. Default value is 2. +

+
+
decay
+

Set delay line decay gain value. Allowed range is from 0 to 1. +Default value is 0.0. +

+
+
feedback
+

Set delay line feedback gain value. Allowed range is from 0 to 1. +Default value is 0.9. +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 50 to 900. +Default value is 100. +

+
+
slope
+

Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1. +Default value is 0.5. +

+
+
delay
+

Set delay. Allowed range is from 1 to 100. +Default value is 20. +

+
+
channels
+

Set the channels to process. Default value is all available. +

+
+ + +

36.60.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.61 asubcut

+

Cut subwoofer frequencies. +

+

This filter allows to set custom, steeper +roll off than highpass filter, and thus is able to more attenuate +frequency content in stop-band. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 2 to 200. +Default value is 20. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

36.61.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.62 asupercut

+

Cut super frequencies. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 20000 to 192000. +Default value is 20000. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

36.62.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.63 asuperpass

+

Apply high order Butterworth band-pass filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

36.63.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.64 asuperstop

+

Apply high order Butterworth band-stop filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

36.64.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.65 atempo

+ +

Adjust audio tempo. +

+

The filter accepts exactly one parameter, the audio tempo. If not +specified then the filter will assume nominal 1.0 tempo. Tempo must +be in the [0.5, 100.0] range. +

+

Note that tempo greater than 2 will skip some samples rather than +blend them in. If for any reason this is a concern it is always +possible to daisy-chain several instances of atempo to achieve the +desired product tempo. +

+ +

36.65.1 Examples

+ +
    +
  • Slow down audio to 80% tempo: +
    +
    atempo=0.8
    +
    + +
  • To speed up audio to 300% tempo: +
    +
    atempo=3
    +
    + +
  • To speed up audio to 300% tempo by daisy-chaining two atempo instances: +
    +
    atempo=sqrt(3),atempo=sqrt(3)
    +
    +
+ + +

36.65.2 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+ + +

36.66 atilt

+

Apply spectral tilt filter to audio stream. +

+

This filter apply any spectral roll-off slope over any specified frequency band. +

+

The filter accepts the following options: +

+
+
freq
+

Set central frequency of tilt in Hz. Default is 10000 Hz. +

+
+
slope
+

Set slope direction of tilt. Default is 0. Allowed range is from -1 to 1. +

+
+
width
+

Set width of tilt. Default is 1000. Allowed range is from 100 to 10000. +

+
+
order
+

Set order of tilt filter. +

+
+
level
+

Set input volume level. Allowed range is from 0 to 4. +Default is 1. +

+
+ + +

36.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.67 atrim

+ +

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Timestamp (in seconds) of the start of the section to keep. I.e. the audio +sample with the timestamp start will be the first sample in the output. +

+
+
end
+

Specify time of the first audio sample that will be dropped, i.e. the +audio sample immediately preceding the one with the timestamp end will be +the last sample in the output. +

+
+
start_pts
+

Same as start, except this option sets the start timestamp in samples +instead of seconds. +

+
+
end_pts
+

Same as end, except this option sets the end timestamp in samples instead +of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_sample
+

The number of the first sample that should be output. +

+
+
end_sample
+

The number of the first sample that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual. +

+

Note that the first two sets of the start/end options and the 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 +to have 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -af atrim=60:120
    +
    + +
  • Keep only the first 1000 samples: +
    +
    ffmpeg -i INPUT -af atrim=end_sample=1000
    +
    + +
+ + +

36.68 axcorrelate

+

Calculate normalized windowed cross-correlation between two input audio streams. +

+

Resulted samples are always between -1 and 1 inclusive. +If result is 1 it means two input samples are highly correlated in that selected segment. +Result 0 means they are not correlated at all. +If result is -1 it means two input samples are out of phase, which means they cancel each +other. +

+

The filter accepts the following options: +

+
+
size
+

Set size of segment over which cross-correlation is calculated. +Default is 256. Allowed range is from 2 to 131072. +

+
+
algo
+

Set algorithm for cross-correlation. Can be slow or fast or best. +Default is best. Fast algorithm assumes mean values over any given segment +are always zero and thus need much less calculations to make. +This is generally not true, but is valid for typical audio streams. +

+
+ + +

36.68.1 Examples

+ +
    +
  • Calculate correlation between channels in stereo audio stream: +
    +
    ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
    +
    +
+ + +

36.69 bandpass

+ +

Apply a two-pole Butterworth band-pass filter with central +frequency frequency, and (3dB-point) band-width width. +The 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: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
csg
+

Constant skirt gain if set to 1. Defaults to 0. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.69.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandpass mix. +Syntax for the command is : "mix" +

+
+ + +

36.70 bandreject

+ +

Apply a two-pole Butterworth band-reject filter with central +frequency frequency, and (3dB-point) band-width width. +The filter roll off at 6dB per octave (20dB per decade). +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.70.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandreject frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandreject width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandreject width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandreject mix. +Syntax for the command is : "mix" +

+
+ + +

36.71 bass, lowshelf

+ +

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: +

+
+
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. +

+
+
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 100 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.71.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bass width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change bass gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change bass mix. +Syntax for the command is : "mix" +

+
+ + +

36.72 biquad

+ +

Apply a biquad IIR filter with the given coefficients. +Where b0, b1, b2 and a0, a1, a2 +are the numerator and denominator coefficients respectively. +and channels, c specify which channels to filter, by default all +available are filtered. +

+ +

36.72.1 Commands

+ +

This filter supports the following commands: +

+
a0
+
a1
+
a2
+
b0
+
b1
+
b2
+

Change biquad parameter. +Syntax for the command is : "value" +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.73 bs2b

+

Bauer stereo to binaural transformation, which improves headphone listening of +stereo audio records. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libbs2b. +

+

It accepts the following parameters: +

+
profile
+

Pre-defined crossfeed level. +

+
default
+

Default level (fcut=700, feed=50). +

+
+
cmoy
+

Chu Moy circuit (fcut=700, feed=60). +

+
+
jmeier
+

Jan Meier circuit (fcut=650, feed=95). +

+
+
+ +
+
fcut
+

Cut frequency (in Hz). +

+
+
feed
+

Feed level (in Hz). +

+
+
+ + +

36.74 channelmap

+ +

Remap input channels to new locations. +

+

It accepts the following parameters: +

+
map
+

Map channels from input to output. The argument is a ’|’-separated list of +mappings, each in the in_channel-out_channel or +in_channel form. 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. out_channel is the name of the output channel or its index in the +output channel layout. If out_channel is not given then it is implicitly +an index, starting with zero and increasing by one for each mapping. Mixing +different types of mappings is not allowed and will result in a parse error. +

+
+
channel_layout
+

The channel layout of the output stream. If not specified, then filter will +guess it based on the out_channel names or the number of mappings. +Guessed layouts will not necessarily contain channels in the order of the +mappings. +

+
+ +

If no mapping is present, the filter will implicitly map input channels to +output channels, preserving indices. +

+ +

36.74.1 Examples

+ +
    +
  • For example, assuming a 5.1+downmix input MOV file, +
    +
    ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
    +
    +

    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 +
    +
    ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
    +
    +
+ + +

36.75 channelsplit

+ +

Split each channel from an input audio stream into a separate output stream. +

+

It accepts the following parameters: +

+
channel_layout
+

The channel layout of the input stream. The default is "stereo". +

+
channels
+

A channel layout describing the channels to be extracted as separate output streams +or "all" to extract each input channel as a separate stream. The default is "all". +

+

Choosing channels not present in channel layout in the input will result in an error. +

+
+ + +

36.75.1 Examples

+ +
    +
  • For example, assuming a stereo input MP3 file, +
    +
    ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
    +
    +

    will create an output Matroska file with two audio streams, one containing only +the left channel and the other the right channel. +

    +
  • Split a 5.1 WAV file into per-channel files: +
    +
    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
    +
    + +
  • Extract only LFE from a 5.1 WAV file: +
    +
    ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
    +-map '[LFE]' lfe.wav
    +
    +
+ + +

36.76 chorus

+

Add a chorus effect to the audio. +

+

Can make a single vocal sound like a chorus, but can also be applied to instrumentation. +

+

Chorus resembles an echo effect with a short delay, but whereas with echo the delay is +constant, with chorus, it is varied using sinusoidal or triangular modulation. +The modulation depth defines the range the modulated delay is played before or after +the delay. Hence the delayed sound will sound slower or faster, that is the delayed +sound tuned around the original one, like in a chorus where some vocals are slightly +off key. +

+

It accepts the following parameters: +

+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.4. +

+
+
delays
+

Set delays. A typical delay is around 40ms to 60ms. +

+
+
decays
+

Set decays. +

+
+
speeds
+

Set speeds. +

+
+
depths
+

Set depths. +

+
+ + +

36.76.1 Examples

+ +
    +
  • A single delay: +
    +
    chorus=0.7:0.9:55:0.4:0.25:2
    +
    + +
  • Two delays: +
    +
    chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
    +
    + +
  • Fuller sounding chorus with three delays: +
    +
    chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3
    +
    +
+ + +

36.77 compand

+

Compress or expand the audio’s dynamic range. +

+

It accepts the following parameters: +

+
+
attacks
+
decays
+

A list of times in seconds for each channel over which the instantaneous level +of the input signal is averaged to determine its volume. attacks refers to +increase of volume and 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. A typical value for attack is 0.3 seconds and +a typical value for decay is 0.8 seconds. +If specified number of attacks & decays is lower than number of channels, the last +set attack/decay will be used for all remaining channels. +

+
+
points
+

A list of points for the transfer function, specified in dB relative to the +maximum possible signal amplitude. Each key points list must be defined using +the following syntax: x0/y0|x1/y1|x2/y2|.... or +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 0/0 is assumed but +may be overridden (by 0/out-dBn). Typical values for the transfer +function are -70/-70|-60/-20|1/0. +

+
+
soft-knee
+

Set the curve radius in dB for all joints. It defaults to 0.01. +

+
+
gain
+

Set the additional gain in dB to be applied at all points on the transfer +function. This allows for easy adjustment of the overall gain. +It defaults to 0. +

+
+
volume
+

Set an 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. It defaults to 0. +

+
+
delay
+

Set a delay, in seconds. The input audio is analyzed 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. It defaults to 0. +

+
+
+ + +

36.77.1 Examples

+ +
    +
  • Make music with both quiet and loud passages suitable for listening to in a +noisy environment: +
    +
    compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
    +
    + +

    Another example for audio with whisper and explosion parts: +

    +
    compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
    +
    + +
  • A noise gate for when the noise is at a lower level than the signal: +
    +
    compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
    +
    + +
  • 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): +
    +
    compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
    +
    + +
  • 2:1 compression starting at -6dB: +
    +
    compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
    +
    + +
  • 2:1 compression starting at -9dB: +
    +
    compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
    +
    + +
  • 2:1 compression starting at -12dB: +
    +
    compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
    +
    + +
  • 2:1 compression starting at -18dB: +
    +
    compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
    +
    + +
  • 3:1 compression starting at -15dB: +
    +
    compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
    +
    + +
  • Compressor/Gate: +
    +
    compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
    +
    + +
  • Expander: +
    +
    compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
    +
    + +
  • Hard limiter at -6dB: +
    +
    compand=attacks=0:points=-80/-80|-6/-6|20/-6
    +
    + +
  • Hard limiter at -12dB: +
    +
    compand=attacks=0:points=-80/-80|-12/-12|20/-12
    +
    + +
  • Hard noise gate at -35 dB: +
    +
    compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
    +
    + +
  • Soft limiter: +
    +
    compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
    +
    +
+ + +

36.78 compensationdelay

+ +

Compensation Delay Line is a metric based delay to compensate differing +positions of microphones or speakers. +

+

For example, you have recorded guitar with two microphones placed in +different locations. Because the front of sound wave has fixed speed in +normal conditions, the phasing of microphones can vary and depends on +their location and interposition. The best sound mix can be achieved when +these microphones are in phase (synchronized). Note that a distance of +~30 cm between microphones makes one microphone capture the signal in +antiphase to the other microphone. That makes the final mix sound moody. +This filter helps to solve phasing problems by adding different delays +to each microphone track and make them synchronized. +

+

The best result can be reached when you take one track as base and +synchronize other tracks one by one with it. +Remember that synchronization/delay tolerance depends on sample rate, too. +Higher sample rates will give more tolerance. +

+

The filter accepts the following parameters: +

+
+
mm
+

Set millimeters distance. This is compensation distance for fine tuning. +Default is 0. +

+
+
cm
+

Set cm distance. This is compensation distance for tightening distance setup. +Default is 0. +

+
+
m
+

Set meters distance. This is compensation distance for hard distance setup. +Default is 0. +

+
+
dry
+

Set dry amount. Amount of unprocessed (dry) signal. +Default is 0. +

+
+
wet
+

Set wet amount. Amount of processed (wet) signal. +Default is 1. +

+
+
temp
+

Set temperature in degrees Celsius. This is the temperature of the environment. +Default is 20. +

+
+ + +

36.78.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.79 crossfeed

+

Apply headphone crossfeed filter. +

+

Crossfeed is the process of blending the left and right channels of stereo +audio recording. +It is mainly used to reduce extreme stereo separation of low frequencies. +

+

The intent is to produce more speaker like sound to the listener. +

+

The filter accepts the following options: +

+
+
strength
+

Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. +This sets gain of low shelf filter for side part of stereo image. +Default is -6dB. Max allowed is -30db when strength is set to 1. +

+
+
range
+

Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. +This sets cut off frequency of low shelf filter. Default is cut off near +1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. +

+
+
slope
+

Set curve slope of low shelf filter. Default is 0.5. +Allowed range is from 0.01 to 1. +

+
+
level_in
+

Set input gain. Default is 0.9. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
block_size
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.79.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.80 crystalizer

+

Simple algorithm for audio noise sharpening. +

+

This filter linearly increases differences between each audio sample. +

+

The filter accepts the following options: +

+
+
i
+

Sets the intensity of effect (default: 2.0). Must be in range between -10.0 to 0 +(unchanged sound) to 10.0 (maximum effect). +To inverse filtering use negative value. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

36.80.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.81 dcshift

+

Apply a DC shift to the audio. +

+

This can be useful to remove a DC offset (caused perhaps by a hardware problem +in the recording chain) from the audio. The effect of a DC offset is reduced +headroom and hence volume. The astats filter can be used to determine if +a signal has a DC offset. +

+
+
shift
+

Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift +the audio. +

+
+
limitergain
+

Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is +used to prevent clipping. +

+
+ + +

36.82 deesser

+ +

Apply de-essing to the audio samples. +

+
+
i
+

Set intensity for triggering de-essing. Allowed range is from 0 to 1. +Default is 0. +

+
+
m
+

Set amount of ducking on treble part of sound. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
f
+

How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
s
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass ess filtered out. +

+
+
e
+

Pass only ess. +

+

Default value is o. +

+
+ +
+
+ + +

36.83 dialoguenhance

+

Enhance dialogue in stereo audio. +

+

This filter accepts stereo input and produce surround (3.0) channels output. +The newly produced front center channel have enhanced speech dialogue originally +available in both stereo channels. +This filter outputs front left and front right channels same as available in stereo input. +

+

The filter accepts the following options: +

+
+
original
+

Set the original center factor to keep in front center channel output. +Allowed range is from 0 to 1. Default value is 1. +

+
+
enhance
+

Set the dialogue enhance factor to put in front center channel output. +Allowed range is from 0 to 3. Default value is 1. +

+
+
voice
+

Set the voice detection factor. +Allowed range is from 2 to 32. Default value is 2. +

+
+ + +

36.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.84 drmeter

+

Measure audio dynamic range. +

+

DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 +is found in transition material. And anything less that 8 have very poor dynamics +and is very compressed. +

+

The filter accepts the following options: +

+
+
length
+

Set window length in seconds used to split audio into segments of equal length. +Default is 3 seconds. +

+
+ + +

36.85 dynaudnorm

+

Dynamic Audio Normalizer. +

+

This filter applies a certain amount of gain to the input audio in order +to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in +contrast to more "simple" normalization algorithms, the Dynamic Audio +Normalizer *dynamically* re-adjusts the gain factor to the input audio. +This allows for applying extra gain to the "quiet" sections of the audio +while avoiding distortions or clipping the "loud" sections. In other words: +The Dynamic Audio Normalizer will "even out" the volume of quiet and loud +sections, in the sense that the volume of each section is brought to the +same target level. Note, however, that the Dynamic Audio Normalizer achieves +this goal *without* applying "dynamic range compressing". It will retain 100% +of the dynamic range *within* each section of the audio file. +

+
+
framelen, f
+

Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. +Default is 500 milliseconds. +The Dynamic Audio Normalizer processes the input audio in small chunks, +referred to as frames. This is required, because a peak magnitude has no +meaning for just a single sample value. Instead, we need to determine the +peak magnitude for a contiguous sequence of sample values. While a "standard" +normalizer would simply use the peak magnitude of the complete file, the +Dynamic Audio Normalizer determines the peak magnitude individually for each +frame. The length of a frame is specified in milliseconds. By default, the +Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has +been found to give good results with most files. +Note that the exact frame length, in number of samples, will be determined +automatically, based on the sampling rate of the individual input audio file. +

+
+
gausssize, g
+

Set the Gaussian filter window size. In range from 3 to 301, must be odd +number. Default is 31. +Probably the most important parameter of the Dynamic Audio Normalizer is the +window size of the Gaussian smoothing filter. The filter’s window size +is specified in frames, centered around the current frame. For the sake of +simplicity, this must be an odd number. Consequently, the default value of 31 +takes into account the current frame, as well as the 15 preceding frames and +the 15 subsequent frames. Using a larger window results in a stronger +smoothing effect and thus in less gain variation, i.e. slower gain +adaptation. Conversely, using a smaller window results in a weaker smoothing +effect and thus in more gain variation, i.e. faster gain adaptation. +In other words, the more you increase this value, the more the Dynamic Audio +Normalizer will behave like a "traditional" normalization filter. On the +contrary, the more you decrease this value, the more the Dynamic Audio +Normalizer will behave like a dynamic range compressor. +

+
+
peak, p
+

Set the target peak value. This specifies the highest permissible magnitude +level for the normalized audio input. This filter will try to approach the +target peak magnitude as closely as possible, but at the same time it also +makes sure that the normalized signal will never exceed the peak magnitude. +A frame’s maximum local gain factor is imposed directly by the target peak +magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. +It is not recommended to go above this value. +

+
+
maxgain, m
+

Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. +The Dynamic Audio Normalizer determines the maximum possible (local) gain +factor for each input frame, i.e. the maximum gain factor that does not +result in clipping or distortion. The maximum gain factor is determined by +the frame’s highest magnitude sample. However, the Dynamic Audio Normalizer +additionally bounds the frame’s maximum gain factor by a predetermined +(global) maximum gain factor. This is done in order to avoid excessive gain +factors in "silent" or almost silent frames. By default, the maximum gain +factor is 10.0, For most inputs the default value should be sufficient and +it usually is not recommended to increase this value. Though, for input +with an extremely low overall volume level, it may be necessary to allow even +higher gain factors. Note, however, that the Dynamic Audio Normalizer does +not simply apply a "hard" threshold (i.e. cut off values above the threshold). +Instead, a "sigmoid" threshold function will be applied. This way, the +gain factors will smoothly approach the threshold value, but never exceed that +value. +

+
+
targetrms, r
+

Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. +By default, the Dynamic Audio Normalizer performs "peak" normalization. +This means that the maximum local gain factor for each frame is defined +(only) by the frame’s highest magnitude sample. This way, the samples can +be amplified as much as possible without exceeding the maximum signal +level, i.e. without clipping. Optionally, however, the Dynamic Audio +Normalizer can also take into account the frame’s root mean square, +abbreviated RMS. In electrical engineering, the RMS is commonly used to +determine the power of a time-varying signal. It is therefore considered +that the RMS is a better approximation of the "perceived loudness" than +just looking at the signal’s peak magnitude. Consequently, by adjusting all +frames to a constant RMS value, a uniform "perceived loudness" can be +established. If a target RMS value has been specified, a frame’s local gain +factor is defined as the factor that would result in exactly that RMS value. +Note, however, that the maximum local gain factor is still restricted by the +frame’s highest magnitude sample, in order to prevent clipping. +

+
+
coupling, n
+

Enable channels coupling. By default is enabled. +By default, the Dynamic Audio Normalizer will amplify all channels by the same +amount. This means the same gain factor will be applied to all channels, i.e. +the maximum possible gain factor is determined by the "loudest" channel. +However, in some recordings, it may happen that the volume of the different +channels is uneven, e.g. one channel may be "quieter" than the other one(s). +In this case, this option can be used to disable the channel coupling. This way, +the gain factor will be determined independently for each channel, depending +only on the individual channel’s highest magnitude sample. This allows for +harmonizing the volume of the different channels. +

+
+
correctdc, c
+

Enable DC bias correction. By default is disabled. +An audio signal (in the time domain) is a sequence of sample values. +In the Dynamic Audio Normalizer these sample values are represented in the +-1.0 to 1.0 range, regardless of the original input format. Normally, the +audio signal, or "waveform", should be centered around the zero point. +That means if we calculate the mean value of all samples in a file, or in a +single frame, then the result should be 0.0 or at least very close to that +value. If, however, there is a significant deviation of the mean value from +0.0, in either positive or negative direction, this is referred to as a +DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic +Audio Normalizer provides optional DC bias correction. +With DC bias correction enabled, the Dynamic Audio Normalizer will determine +the mean value, or "DC correction" offset, of each input frame and subtract +that value from all of the frame’s sample values which ensures those samples +are centered around 0.0 again. Also, in order to avoid "gaps" at the frame +boundaries, the DC correction offset values will be interpolated smoothly +between neighbouring frames. +

+
+
altboundary, b
+

Enable alternative boundary mode. By default is disabled. +The Dynamic Audio Normalizer takes into account a certain neighbourhood +around each frame. This includes the preceding frames as well as the +subsequent frames. However, for the "boundary" frames, located at the very +beginning and at the very end of the audio file, not all neighbouring +frames are available. In particular, for the first few frames in the audio +file, the preceding frames are not known. And, similarly, for the last few +frames in the audio file, the subsequent frames are not known. Thus, the +question arises which gain factors should be assumed for the missing frames +in the "boundary" region. The Dynamic Audio Normalizer implements two modes +to deal with this situation. The default boundary mode assumes a gain factor +of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and +"fade out" at the beginning and at the end of the input, respectively. +

+
+
compress, s
+

Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. +By default, the Dynamic Audio Normalizer does not apply "traditional" +compression. This means that signal peaks will not be pruned and thus the +full dynamic range will be retained within each local neighbourhood. However, +in some cases it may be desirable to combine the Dynamic Audio Normalizer’s +normalization algorithm with a more "traditional" compression. +For this purpose, the Dynamic Audio Normalizer provides an optional compression +(thresholding) function. If (and only if) the compression feature is enabled, +all input frames will be processed by a soft knee thresholding function prior +to the actual normalization process. Put simply, the thresholding function is +going to prune all samples whose magnitude exceeds a certain threshold value. +However, the Dynamic Audio Normalizer does not simply apply a fixed threshold +value. Instead, the threshold value will be adjusted for each individual +frame. +In general, smaller parameters result in stronger compression, and vice versa. +Values below 3.0 are not recommended, because audible distortion may appear. +

+
+
threshold, t
+

Set the target threshold value. This specifies the lowest permissible +magnitude level for the audio input which will be normalized. +If input frame volume is above this value frame will be normalized. +Otherwise frame may not be normalized at all. The default value is set +to 0, which means all input frames will be normalized. +This option is mostly useful if digital noise is not wanted to be amplified. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
overlap, o
+

Specify overlap for frames. If set to 0 (default) no frame overlapping is done. +Using >0 and <1 values will make less conservative gain adjustments, like +when framelen option is set to smaller value, if framelen option value is +compensated for non-zero overlap then gain adjustments will be smoother across time +compared to zero overlap case. +

+
+
curve, v
+

Specify the peak mapping curve expression which is going to be used when calculating +gain applied to frames. The max output frame gain will still be limited by other +options mentioned previously for this filter. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frame peak value +

+
+
+
+ + +

36.85.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.86 earwax

+ +

Make audio easier to listen to on headphones. +

+

This filter adds ‘cues’ to 44.1kHz stereo (i.e. audio CD format) audio +so that when listened to on headphones the stereo image is moved from +inside your head (standard for headphones) to outside and in front of +the listener (standard for speakers). +

+

Ported from SoX. +

+ +

36.87 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: +

+
+
frequency, f
+

Set the filter’s central frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
gain, g
+

Set the required gain or attenuation in dB. +Beware of clipping when using a positive gain. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.87.1 Examples

+
    +
  • Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: +
    +
    equalizer=f=1000:t=h:width=200:g=-10
    +
    + +
  • Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: +
    +
    equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
    +
    +
+ + +

36.87.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change equalizer frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change equalizer width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change equalizer width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change equalizer gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change equalizer mix. +Syntax for the command is : "mix" +

+
+ + +

36.88 extrastereo

+ +

Linearly increases the difference between left and right channels which +adds some sort of "live" effect to playback. +

+

The filter accepts the following options: +

+
+
m
+

Sets the difference coefficient (default: 2.5). 0.0 means mono sound +(average of both channels), with 1.0 sound will be unchanged, with +-1.0 left and right channels will be swapped. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

36.88.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.89 firequalizer

+

Apply FIR Equalization using arbitrary frequency response. +

+

The filter accepts the following option: +

+
+
gain
+

Set gain curve equation (in dB). The expression can contain variables: +

+
f
+

the evaluated frequency +

+
sr
+

sample rate +

+
ch
+

channel number, set to 0 when multichannels evaluation is disabled +

+
chid
+

channel id, see libavutil/channel_layout.h, set to the first channel id when +multichannels evaluation is disabled +

+
chs
+

number of channels +

+
chlayout
+

channel_layout, see libavutil/channel_layout.h +

+
+
+

and functions: +

+
gain_interpolate(f)
+

interpolate gain on frequency f based on gain_entry +

+
cubic_interpolate(f)
+

same as gain_interpolate, but smoother +

+
+

This option is also available as command. Default is gain_interpolate(f). +

+
+
gain_entry
+

Set gain entry for gain_interpolate function. The expression can +contain functions: +

+
entry(f, g)
+

store gain entry at frequency f with value g +

+
+

This option is also available as command. +

+
+
delay
+

Set filter delay in seconds. Higher value means more accurate. +Default is 0.01. +

+
+
accuracy
+

Set filter accuracy in Hz. Lower value means more accurate. +Default is 5. +

+
+
wfunc
+

Set window function. Acceptable values are: +

+
rectangular
+

rectangular window, useful when gain curve is already smooth +

+
hann
+

hann window (default) +

+
hamming
+

hamming window +

+
blackman
+

blackman window +

+
nuttall3
+

3-terms continuous 1st derivative nuttall window +

+
mnuttall3
+

minimum 3-terms discontinuous nuttall window +

+
nuttall
+

4-terms continuous 1st derivative nuttall window +

+
bnuttall
+

minimum 4-terms discontinuous nuttall (blackman-nuttall) window +

+
bharris
+

blackman-harris window +

+
tukey
+

tukey window +

+
+ +
+
fixed
+

If enabled, use fixed number of audio samples. This improves speed when +filtering with large delay. Default is disabled. +

+
+
multi
+

Enable multichannels evaluation on gain. Default is disabled. +

+
+
zero_phase
+

Enable zero phase mode by subtracting timestamp to compensate delay. +Default is disabled. +

+
+
scale
+

Set scale used by gain. Acceptable values are: +

+
linlin
+

linear frequency, linear gain +

+
linlog
+

linear frequency, logarithmic (in dB) gain (default) +

+
loglin
+

logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain +

+
loglog
+

logarithmic frequency, logarithmic gain +

+
+ +
+
dumpfile
+

Set file for dumping, suitable for gnuplot. +

+
+
dumpscale
+

Set scale for dumpfile. Acceptable values are same with scale option. +Default is linlog. +

+
+
fft2
+

Enable 2-channel convolution using complex FFT. This improves speed significantly. +Default is disabled. +

+
+
min_phase
+

Enable minimum phase impulse response. Default is disabled. +

+
+ + +

36.89.1 Examples

+
    +
  • lowpass at 1000 Hz: +
    +
    firequalizer=gain='if(lt(f,1000), 0, -INF)'
    +
    +
  • lowpass at 1000 Hz with gain_entry: +
    +
    firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
    +
    +
  • custom equalization: +
    +
    firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
    +
    +
  • higher delay with zero phase to compensate delay: +
    +
    firequalizer=delay=0.1:fixed=on:zero_phase=on
    +
    +
  • lowpass on left channel, highpass on right channel: +
    +
    firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
    +:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
    +
    +
+ + +

36.90 flanger

+

Apply a flanging effect to the audio. +

+

The filter accepts the following options: +

+
+
delay
+

Set base delay in milliseconds. Range from 0 to 30. Default value is 0. +

+
+
depth
+

Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. +

+
+
regen
+

Set percentage regeneration (delayed signal feedback). Range from -95 to 95. +Default value is 0. +

+
+
width
+

Set percentage of delayed signal mixed with original. Range from 0 to 100. +Default value is 71. +

+
+
speed
+

Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. +

+
+
shape
+

Set swept wave shape, can be triangular or sinusoidal. +Default value is sinusoidal. +

+
+
phase
+

Set swept wave percentage-shift for multi channel. Range from 0 to 100. +Default value is 25. +

+
+
interp
+

Set delay-line interpolation, linear or quadratic. +Default is linear. +

+
+ + +

36.91 haas

+

Apply Haas effect to audio. +

+

Note that this makes most sense to apply on mono signals. +With this filter applied to mono signals it give some directionality and +stretches its stereo image. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level. By default is 1, or 0dB +

+
+
level_out
+

Set output level. By default is 1, or 0dB. +

+
+
side_gain
+

Set gain applied to side part of signal. By default is 1. +

+
+
middle_source
+

Set kind of middle source. Can be one of the following: +

+
+
‘left’
+

Pick left channel. +

+
+
‘right’
+

Pick right channel. +

+
+
‘mid’
+

Pick middle part signal of stereo image. +

+
+
‘side’
+

Pick side part signal of stereo image. +

+
+ +
+
middle_phase
+

Change middle phase. By default is disabled. +

+
+
left_delay
+

Set left channel delay. By default is 2.05 milliseconds. +

+
+
left_balance
+

Set left channel balance. By default is -1. +

+
+
left_gain
+

Set left channel gain. By default is 1. +

+
+
left_phase
+

Change left phase. By default is disabled. +

+
+
right_delay
+

Set right channel delay. By defaults is 2.12 milliseconds. +

+
+
right_balance
+

Set right channel balance. By default is 1. +

+
+
right_gain
+

Set right channel gain. By default is 1. +

+
+
right_phase
+

Change right phase. By default is enabled. +

+
+ + +

36.92 hdcd

+ +

Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with +embedded HDCD codes is expanded into a 20-bit PCM stream. +

+

The filter supports the Peak Extend and Low-level Gain Adjustment features +of HDCD, and detects the Transient Filter flag. +

+
+
ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
+
+ +

When using the filter with wav, note the default encoding for wav is 16-bit, +so the resulting 20-bit stream will be truncated back to 16-bit. Use something +like -acodec pcm_s24le after the filter to get 24-bit PCM output. +

+
ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
+ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
+
+ +

The filter accepts the following options: +

+
+
disable_autoconvert
+

Disable any automatic format conversion or resampling in the filter graph. +

+
+
process_stereo
+

Process the stereo channels together. If target_gain does not match between +channels, consider it invalid and use the last valid target_gain. +

+
+
cdt_ms
+

Set the code detect timer period in ms. +

+
+
force_pe
+

Always extend peaks above -3dBFS even if PE isn’t signaled. +

+
+
analyze_mode
+

Replace audio with a solid tone and adjust the amplitude to signal some +specific aspect of the decoding process. The output file can be loaded in +an audio editor alongside the original to aid analysis. +

+

analyze_mode=pe:force_pe=true can be used to see all samples above the PE level. +

+

Modes are: +

+
‘0, off’
+

Disabled +

+
‘1, lle’
+

Gain adjustment level at each sample +

+
‘2, pe’
+

Samples where peak extend occurs +

+
‘3, cdt’
+

Samples where the code detect timer is active +

+
‘4, tgm’
+

Samples where the target gain does not match between channels +

+
+
+
+ + +

36.93 headphone

+ +

Apply head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones. +The HRIRs are provided via additional streams, for each channel +one stereo input stream is needed. +

+

The filter accepts the following options: +

+
+
map
+

Set mapping of input streams for convolution. +The argument is a ’|’-separated list of channel names in order as they +are given as additional stream inputs for filter. +This also specify number of input streams. Number of input streams +must be not less than number of channels in first stream plus one. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
lfe
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
size
+

Set size of frame in number of samples which will be processed at once. +Default value is 1024. Allowed range is from 1024 to 96000. +

+
+
hrir
+

Set format of hrir stream. +Default value is stereo. Alternative value is multich. +If value is set to stereo, number of additional streams should +be greater or equal to number of input channels in first input stream. +Also each additional stream should have stereo number of channels. +If value is set to multich, number of additional streams should +be exactly one. Also number of input channels of additional stream +should be equal or greater than twice number of channels of first input +stream. +

+
+ + +

36.93.1 Examples

+ +
    +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +each amovie filter use stereo file with IR coefficients as input. +The files give coefficients for each position of virtual loudspeaker: +
    +
    ffmpeg -i input.wav
    +-filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
    +output.wav
    +
    + +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +but now in multich hrir format. +
    +
    ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
    +output.wav
    +
    +
+ + +

36.94 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 3000. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.94.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change highpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change highpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change highpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change highpass mix. +Syntax for the command is : "mix" +

+
+ + +

36.95 join

+ +

Join multiple input streams into one multi-channel stream. +

+

It accepts the following parameters: +

+
inputs
+

The number of input streams. It defaults to 2. +

+
+
channel_layout
+

The desired output channel layout. It defaults to stereo. +

+
+
map
+

Map channels from inputs to output. The argument is a ’|’-separated list of +mappings, each in the input_idx.in_channel-out_channel +form. input_idx is the 0-based index of the input stream. 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. out_channel is the name of the output +channel. +

+
+ +

The filter will attempt to guess the mappings when they 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. +

+

Join 3 inputs (with properly set channel layouts): +

+
ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
+
+ +

Build a 5.1 output from 6 single-channel streams: +

+
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
+
+ + +

36.96 ladspa

+ +

Load a LADSPA (Linux Audio Developer’s Simple Plugin API) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-ladspa. +

+
+
file, f
+

Specifies the name of LADSPA plugin library to load. If the environment +variable LADSPA_PATH is defined, the LADSPA plugin is searched in +each one of the directories specified by the colon separated list in +LADSPA_PATH, otherwise in the standard LADSPA paths, which are in +this order: HOME/.ladspa/lib/, /usr/local/lib/ladspa/, +/usr/lib/ladspa/. +

+
+
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. +

+
+
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=value0|c1=value1|c2=value2|..., where +valuei is the value set on the i-th control. +Alternatively they can be also defined using the following syntax: +value0|value1|value2|..., where +valuei is the value set on the i-th control. +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
latency, l
+

Enable latency compensation, by default is disabled. +Only used if plugin have inputs. +

+
+ + +

36.96.1 Examples

+ +
    +
  • List all available plugins within amp (LADSPA example plugin) library: +
    +
    ladspa=file=amp
    +
    + +
  • List all available controls and their valid ranges for vcf_notch +plugin from VCF library: +
    +
    ladspa=f=vcf:p=vcf_notch:c=help
    +
    + +
  • Simulate low quality audio equipment using Computer Music Toolkit (CMT) +plugin library: +
    +
    ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
    +
    + +
  • Add reverberation to the audio using TAP-plugins +(Tom’s Audio Processing plugins): +
    +
    ladspa=file=tap_reverb:tap_reverb
    +
    + +
  • Generate white noise, with 0.2 amplitude: +
    +
    ladspa=file=cmt:noise_source_white:c=c0=.2
    +
    + +
  • Generate 20 bpm clicks using plugin C* Click - Metronome from the +C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=file=caps:Click:c=c1=20'
    +
    + +
  • Apply C* Eq10X2 - Stereo 10-band equaliser effect: +
    +
    ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
    +
    + +
  • Increase volume by 20dB using fast lookahead limiter from Steve Harris +SWH Plugins collection: +
    +
    ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
    +
    + +
  • Attenuate low frequencies using Multiband EQ from Steve Harris +SWH Plugins collection: +
    +
    ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
    +
    + +
  • Reduce stereo image using Narrower from the C* Audio Plugin Suite +(CAPS) library: +
    +
    ladspa=caps:Narrower
    +
    + +
  • Another white noise, now using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:White:.2
    +
    + +
  • Some fractal noise, using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:Fractal:c=c1=1
    +
    + +
  • Dynamic volume normalization using VLevel plugin: +
    +
    ladspa=vlevel-ladspa:vlevel_mono
    +
    +
+ + +

36.96.2 Commands

+ +

This filter supports the following commands: +

+
cN
+

Modify the N-th control value. +

+

If the specified value is not valid, it is ignored and prior one is kept. +

+
+ + +

36.97 loudnorm

+ +

EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. +Support for both single pass (livestreams, files) and double pass (files) modes. +This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately +detect true peaks, the audio stream will be upsampled to 192 kHz. +Use the -ar option or aresample filter to explicitly set an output sample rate. +

+

The filter accepts the following options: +

+
+
I, i
+

Set integrated loudness target. +Range is -70.0 - -5.0. Default value is -24.0. +

+
+
LRA, lra
+

Set loudness range target. +Range is 1.0 - 50.0. Default value is 7.0. +

+
+
TP, tp
+

Set maximum true peak. +Range is -9.0 - +0.0. Default value is -2.0. +

+
+
measured_I, measured_i
+

Measured IL of input file. +Range is -99.0 - +0.0. +

+
+
measured_LRA, measured_lra
+

Measured LRA of input file. +Range is 0.0 - 99.0. +

+
+
measured_TP, measured_tp
+

Measured true peak of input file. +Range is -99.0 - +99.0. +

+
+
measured_thresh
+

Measured threshold of input file. +Range is -99.0 - +0.0. +

+
+
offset
+

Set offset gain. Gain is applied before the true-peak limiter. +Range is -99.0 - +99.0. Default is +0.0. +

+
+
linear
+

Normalize by linearly scaling the source audio. +measured_I, measured_LRA, measured_TP, +and measured_thresh must all be specified. Target LRA shouldn’t +be lower than source LRA and the change in integrated loudness shouldn’t +result in a true peak which exceeds the target TP. If any of these +conditions aren’t met, normalization mode will revert to dynamic. +Options are true or false. Default is true. +

+
+
dual_mono
+

Treat mono input files as "dual-mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +Options are true or false. Default is false. +

+
+
print_format
+

Set print format for stats. Options are summary, json, or none. +Default value is none. +

+
+
stats_file
+

Write stats to specified file. Format is controlled by print_format, +which must be set. Specify - to write to standard output. +Default is unset. +

+
+ + +

36.98 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 500. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.98.1 Examples

+
    +
  • Lowpass only LFE channel, it LFE is not present it does nothing: +
    +
    lowpass=c=LFE
    +
    +
+ + +

36.98.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change lowpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change lowpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change lowpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change lowpass mix. +Syntax for the command is : "mix" +

+
+ + +

36.99 lv2

+ +

Load a LV2 (LADSPA Version 2) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-lv2. +

+
+
plugin, p
+

Specifies the plugin URI. You may need to escape ’:’. +

+
+
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). +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+ + +

36.99.1 Examples

+ +
    +
  • Apply bass enhancer plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
    +
    + +
  • Apply vinyl plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
    +
    + +
  • Apply bit crusher plugin from ArtyFX: +
    +
    lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
    +
    +
+ + +

36.99.2 Commands

+ +

This filter supports all options that are exported by plugin as commands. +

+ +

36.100 mcompand

+

Multiband Compress or expand the audio’s dynamic range. +

+

The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. +This is akin to the crossover of a loudspeaker, and results in flat frequency +response when absent compander action. +

+

It accepts the following parameters: +

+
+
args
+

This option syntax is: +attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... +For explanation of each item refer to compand filter documentation. +

+
+ + +

36.101 pan

+ +

Mix channels with specific gain levels. The filter accepts the output +channel layout followed by a set of channels definitions. +

+

This filter is also designed to efficiently remap the channels of an audio +stream. +

+

The filter accepts parameters of the form: +"l|outdef|outdef|..." +

+
+
l
+

output channel layout or number of channels +

+
+
outdef
+

output channel specification, of the form: +"out_name=[gain*]in_name[(+-)[gain*]in_name...]" +

+
+
out_name
+

output channel to define, either a channel name (FL, FR, etc.) or a channel +number (c0, c1, etc.) +

+
+
gain
+

multiplicative coefficient for the channel, 1 leaving the volume unchanged +

+
+
in_name
+

input channel to use, see out_name for details; it is not possible to mix +named and numbered input channels +

+
+ +

If the ‘=’ in a channel specification is replaced by ‘<’, then the gains for +that specification will be renormalized so that the total is 1, thus +avoiding clipping noise. +

+ +

36.101.1 Mixing examples

+ +

For example, if you want to down-mix from stereo to mono, but with a bigger +factor for the left channel: +

+
pan=1c|c0=0.9*c0+0.1*c1
+
+ +

A customized down-mix to stereo that works automatically for 3-, 4-, 5- and +7-channels surround: +

+
pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
+
+ +

Note that ffmpeg integrates a default down-mix (and up-mix) system +that should be preferred (see "-ac" option) unless you have very specific +needs. +

+ +

36.101.2 Remapping examples

+ +

The channel remapping will be effective if, and only if: +

+
    +
  • gain coefficients are zeroes or ones, +
  • only one input per channel output, +
+ +

If all these conditions are satisfied, the filter will notify the user ("Pure +channel mapping detected"), and use an optimized and lossless method to do the +remapping. +

+

For example, if you have a 5.1 source and want a stereo audio stream by +dropping the extra channels: +

+
pan="stereo| c0=FL | c1=FR"
+
+ +

Given the same source, you can also switch front left and front right channels +and keep the input channel layout: +

+
pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
+
+ +

If the input is a stereo audio stream, you can mute the front left channel (and +still keep the stereo channel layout) with: +

+
pan="stereo|c1=c1"
+
+ +

Still with a stereo audio stream input, you can copy the right channel in both +front left and right: +

+
pan="stereo| c0=FR | c1=FR"
+
+ + +

36.102 replaygain

+ +

ReplayGain scanner filter. This filter takes an audio stream as an input and +outputs it unchanged. +At end of filtering it displays track_gain and track_peak. +

+

The filter accepts the following exported read-only options: +

+
+
track_gain
+

Exported track gain in dB at end of stream. +

+
+
track_peak
+

Exported track peak at end of stream. +

+
+ + +

36.103 resample

+ +

Convert the audio sample format, sample rate and channel layout. It is +not meant to be used directly. +

+ +

36.104 rubberband

+

Apply time-stretching and pitch-shifting with librubberband. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-librubberband. +

+

The filter accepts the following options: +

+
+
tempo
+

Set tempo scale factor. +

+
+
pitch
+

Set pitch scale factor. +

+
+
transients
+

Set transients detector. +Possible values are: +

+
crisp
+
mixed
+
smooth
+
+ +
+
detector
+

Set detector. +Possible values are: +

+
compound
+
percussive
+
soft
+
+ +
+
phase
+

Set phase. +Possible values are: +

+
laminar
+
independent
+
+ +
+
window
+

Set processing window size. +Possible values are: +

+
standard
+
short
+
long
+
+ +
+
smoothing
+

Set smoothing. +Possible values are: +

+
off
+
on
+
+ +
+
formant
+

Enable formant preservation when shift pitching. +Possible values are: +

+
shifted
+
preserved
+
+ +
+
pitchq
+

Set pitch quality. +Possible values are: +

+
quality
+
speed
+
consistency
+
+ +
+
channels
+

Set channels. +Possible values are: +

+
apart
+
together
+
+
+
+ + +

36.104.1 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+
pitch
+

Change filter pitch scale factor. +Syntax for the command is : "pitch" +

+
+ + +

36.105 sidechaincompress

+ +

This filter acts like normal compressor but has the ability to compress +detected signal using second input signal. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +The filtered signal then can be filtered with other filters in later stages of +processing. See pan and amerge filter. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of second stream raises above this level it will affect the gain +reduction of first stream. +By default is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. 1:2 means that if the level +raised 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of side-chain stream +or the louder(maximum) channel of side-chain stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mainly smoother. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

36.105.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.105.2 Examples

+ +
    +
  • Full ffmpeg example taking 2 audio inputs, 1st input to be compressed +depending on the signal of 2nd input and later compressed signal to be +merged with 2nd input: +
    +
    ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
    +
    +
+ + +

36.106 sidechaingate

+ +

A sidechain gate acts like a normal (wideband) gate but has the ability to +filter the detected signal before sending it to the gain reduction stage. +Normally a gate uses the full range signal to detect a level above the +threshold. +For example: If you cut all lower frequencies from your sidechain signal +the gate will decrease the volume of your track only if not enough highs +appear. With this technique you are able to reduce the resonation of a +natural drum or remove "rumbling" of muted strokes from a heavily distorted +guitar. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is from 0.015625 to 64. +

+
+ + +

36.106.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.107 silencedetect

+ +

Detect silence in an audio stream. +

+

This filter logs a message when it detects that the input audio volume is less +or equal to a noise tolerance value for a duration greater or equal to the +minimum detected noise duration. +

+

The printed times and duration are expressed in seconds. The +lavfi.silence_start or lavfi.silence_start.X metadata key +is set on the first frame whose timestamp equals or exceeds the detection +duration and it contains the timestamp of the first frame of the silence. +

+

The lavfi.silence_duration or lavfi.silence_duration.X +and lavfi.silence_end or lavfi.silence_end.X metadata +keys are set on the first frame after the silence. If mono is +enabled, and each channel is evaluated separately, the .X +suffixed keys are used, and X corresponds to the channel number. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or amplitude ratio. Default is -60dB, or 0.001. +

+
+
duration, d
+

Set silence duration until notification (default is 2 seconds). See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+
+
mono, m
+

Process each channel separately, instead of combined. By default is disabled. +

+
+ + +

36.107.1 Examples

+ +
    +
  • Detect 5 seconds of silence with -50dB noise tolerance: +
    +
    silencedetect=n=-50dB:d=5
    +
    + +
  • Complete example with ffmpeg to detect silence with 0.0001 noise +tolerance in silence.mp3: +
    +
    ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
    +
    +
+ + +

36.108 silenceremove

+ +

Remove silence from the beginning, middle or end of the audio. +

+

The filter accepts the following options: +

+
+
start_periods
+

This value is used to indicate if audio should be trimmed at beginning of +the audio. A value of zero indicates no silence should be trimmed from the +beginning. When specifying a non-zero value, it trims audio up until it +finds non-silence. Normally, when trimming silence from beginning of audio +the start_periods will be 1 but it can be increased to higher +values to trim all audio up to specific count of non-silence periods. +Default value is 0. +

+
+
start_duration
+

Specify the amount of time that non-silence must be detected before it stops +trimming audio. By increasing the duration, bursts of noises can be treated +as silence and trimmed off. Default value is 0. +

+
+
start_threshold
+

This indicates what sample value should be treated as silence. For digital +audio, a value of 0 may be fine but for audio recorded from analog, +you may wish to increase the value to account for background noise. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
start_silence
+

Specify max duration of silence at beginning that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
start_mode
+

Specify mode of detection of silence end at start of multi-channel audio. +Can be any or all. Default is any. +With any, any sample from any channel that is detected as non-silence +will trigger end of silence trimming at start of audio stream. +With all, only if every sample from every channel is detected as non-silence +will trigger end of silence trimming at start of audio stream, limited usage. +

+
+
stop_periods
+

Set the count for trimming silence from the end of audio. When specifying a +positive value, it trims audio after it finds specified silence period. +To remove silence from the middle of a file, specify a stop_periods +that is negative. This value is then treated as a positive value and is +used to indicate the effect should restart processing as specified by +stop_periods, making it suitable for removing periods of silence +in the middle of the audio. +Default value is 0. +

+
+
stop_duration
+

Specify a duration of silence that must exist before audio is not copied any +more. By specifying a higher duration, silence that is wanted can be left in +the audio. +Default value is 0. +

+
+
stop_threshold
+

This is the same as start_threshold but for trimming silence from +the end of audio. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
stop_silence
+

Specify max duration of silence at end that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
stop_mode
+

Specify mode of detection of silence start after start of multi-channel audio. +Can be any or all. Default is all. +With any, any sample from any channel that is detected as silence +will trigger start of silence trimming after start of audio stream, limited usage. +With all, only if every sample from every channel is detected as silence +will trigger start of silence trimming after start of audio stream. +

+
+
detection
+

Set how is silence detected. +

+
avg
+

Mean of absolute values of samples in moving window. +

+
rms
+

Root squared mean of absolute values of samples in moving window. +

+
peak
+

Maximum of absolute values of samples in moving window. +

+
median
+

Median of absolute values of samples in moving window. +

+
ptp
+

Absolute of max peak to min peak difference of samples in moving window. +

+
dev
+

Standard deviation of values of samples in moving window. +

+
+

Default value is rms. +

+
+
window
+

Set duration in number of seconds used to calculate size of window in number +of samples for detecting silence. Using 0 will effectively disable +any windowing and use only single sample per channel for silence detection. +In that case it may be needed to also set start_silence and/or +stop_silence to nonzero values with also start_duration and/or +stop_duration to nonzero values. +Default value is 0.02. Allowed range is from 0 to 10. +

+
+
timestamp
+

Set processing mode of every audio frame output timestamp. +

+
write
+

Full timestamps rewrite, keep only the start time for the first output frame. +

+
copy
+

Non-dropped frames are left with same timestamp as input audio frame. +

+
+

Defaults value is write. +

+
+ + +

36.108.1 Examples

+ +
    +
  • The following example shows how this filter can be used to start a recording +that does not contain the delay at the start which usually occurs between +pressing the record button and the start of the performance: +
    +
    silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
    +
    + +
  • Trim all silence encountered from beginning to end where there is more than 1 +second of silence in audio: +
    +
    silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Trim all digital silence samples, using peak detection, from beginning to end +where there is more than 0 samples of digital silence in audio and digital +silence is detected in all channels at same positions in stream: +
    +
    silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
    +
    + +
  • Trim every 2nd encountered silence period from beginning to end where there is +more than 1 second of silence per silence period in audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Similar as above, but keep maximum of 0.5 seconds of silence from each trimmed period: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5
    +
    + +
  • Similar as above, but keep maximum of 1.5 seconds of silence from start of audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5:start_periods=1:start_duration=1:start_silence=1.5:stop_threshold=-90dB
    +
    +
+ + +

36.108.2 Commands

+ +

This filter supports some above options as commands. +

+ +

36.109 sofalizer

+ +

SOFAlizer uses head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones (audio +formats up to 9 channels supported). +The HRTFs are stored in SOFA files (see http://www.sofacoustics.org/ for a database). +SOFAlizer is developed at the Acoustics Research Institute (ARI) of the +Austrian Academy of Sciences. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libmysofa. +

+

The filter accepts the following options: +

+
+
sofa
+

Set the SOFA file used for rendering. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
rotation
+

Set rotation of virtual loudspeakers in deg. Default is 0. +

+
+
elevation
+

Set elevation of virtual speakers in deg. Default is 0. +

+
+
radius
+

Set distance in meters between loudspeakers and the listener with near-field +HRTFs. Default is 1. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
speakers
+

Set custom positions of virtual loudspeakers. Syntax for this option is: +<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. +Each virtual loudspeaker is described with short channel name following with +azimuth and elevation in degrees. +Each virtual loudspeaker description is separated by ’|’. +For example to override front left and front right channel positions use: +’speakers=FL 45 15|FR 345 15’. +Descriptions with unrecognised channel names are ignored. +

+
+
lfegain
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
framesize
+

Set custom frame size in number of samples. Default is 1024. +Allowed range is from 1024 to 96000. Only used if option ‘type’ +is set to freq. +

+
+
normalize
+

Should all IRs be normalized upon importing SOFA file. +By default is enabled. +

+
+
interpolate
+

Should nearest IRs be interpolated with neighbor IRs if exact position +does not match. By default is disabled. +

+
+
minphase
+

Minphase all IRs upon loading of SOFA file. By default is disabled. +

+
+
anglestep
+

Set neighbor search angle step. Only used if option interpolate is enabled. +

+
+
radstep
+

Set neighbor search radius step. Only used if option interpolate is enabled. +

+
+ + +

36.109.1 Examples

+ +
    +
  • Using ClubFritz6 sofa file: +
    +
    sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
    +
    + +
  • Using ClubFritz12 sofa file and bigger radius with small rotation: +
    +
    sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
    +
    + +
  • Similar as above but with custom speaker positions for front left, front right, back left and back right +and also with custom gain: +
    +
    "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
    +
    +
+ + +

36.110 speechnorm

+

Speech Normalizer. +

+

This filter expands or compresses each half-cycle of audio samples +(local set of samples all above or all below zero and between two nearest zero crossings) depending +on threshold value, so audio reaches target peak value under conditions controlled by below options. +

+

The filter accepts the following options: +

+
+
peak, p
+

Set the expansion target peak value. This specifies the highest allowed absolute amplitude +level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0. +

+
+
expansion, e
+

Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples expansion. The maximum expansion +would be such that local peak value reaches target peak value but never to surpass it and that +ratio between new and previous peak value does not surpass this option value. +

+
+
compression, c
+

Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples compression. This option is used +only if threshold option is set to value greater than 0.0, then in such cases +when local peak is lower or same as value set by threshold all samples belonging to +that peak’s half-cycle will be compressed by current compression factor. +

+
+
threshold, t
+

Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0. +This option specifies which half-cycles of samples will be compressed and which will be expanded. +Any half-cycle samples with their local peak value below or same as this option value will be +compressed by current compression factor, otherwise, if greater than threshold value they will be +expanded with expansion factor so that it could reach peak target value but never surpass it. +

+
+
raise, r
+

Set the expansion raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per +each new half-cycle until it reaches expansion value. +Setting this options too high may lead to distortions. +

+
+
fall, f
+

Set the compression raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per +each new half-cycle until it reaches compression value. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
invert, i
+

Enable inverted filtering, by default is disabled. This inverts interpretation of threshold +option. When enabled any half-cycle of samples with their local peak value below or same as +threshold option will be expanded otherwise it will be compressed. +

+
+
link, l
+

Link channels when calculating gain applied to each filtered channel sample, by default is disabled. +When disabled each filtered channel gain calculation is independent, otherwise when this option +is enabled the minimum of all possible gains for each filtered channel is used. +

+
+
rms, m
+

Set the expansion target RMS value. This specifies the highest allowed RMS level for the normalized +audio input. Default value is 0.0, thus disabled. Allowed range is from 0.0 to 1.0. +

+
+ + +

36.110.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.110.2 Examples

+ +
    +
  • Weak and slow amplification: +
    +
    speechnorm=e=3:r=0.00001:l=1
    +
    + +
  • Moderate and slow amplification: +
    +
    speechnorm=e=6.25:r=0.00001:l=1
    +
    + +
  • Strong and fast amplification: +
    +
    speechnorm=e=12.5:r=0.0001:l=1
    +
    + +
  • Very strong and fast amplification: +
    +
    speechnorm=e=25:r=0.0001:l=1
    +
    + +
  • Extreme and fast amplification: +
    +
    speechnorm=e=50:r=0.0001:l=1
    +
    +
+ + +

36.111 stereotools

+ +

This filter has some handy utilities to manage stereo signals, for converting +M/S stereo recordings to L/R signal while having control over the parameters +or spreading the stereo image of master track. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
level_out
+

Set output level after filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
balance_in
+

Set input balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
balance_out
+

Set output balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
softclip
+

Enable softclipping. Results in analog distortion instead of harsh digital 0dB +clipping. Disabled by default. +

+
+
mutel
+

Mute the left channel. Disabled by default. +

+
+
muter
+

Mute the right channel. Disabled by default. +

+
+
phasel
+

Change the phase of the left channel. Disabled by default. +

+
+
phaser
+

Change the phase of the right channel. Disabled by default. +

+
+
mode
+

Set stereo mode. Available values are: +

+
+
‘lr>lr’
+

Left/Right to Left/Right, this is default. +

+
+
‘lr>ms’
+

Left/Right to Mid/Side. +

+
+
‘ms>lr’
+

Mid/Side to Left/Right. +

+
+
‘lr>ll’
+

Left/Right to Left/Left. +

+
+
‘lr>rr’
+

Left/Right to Right/Right. +

+
+
‘lr>l+r’
+

Left/Right to Left + Right. +

+
+
‘lr>rl’
+

Left/Right to Right/Left. +

+
+
‘ms>ll’
+

Mid/Side to Left/Left. +

+
+
‘ms>rr’
+

Mid/Side to Right/Right. +

+
+
‘ms>rl’
+

Mid/Side to Right/Left. +

+
+
‘lr>l-r’
+

Left/Right to Left - Right. +

+
+ +
+
slev
+

Set level of side signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
sbal
+

Set balance of side signal. Default is 0. +Allowed range is from -1 to 1. +

+
+
mlev
+

Set level of the middle signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
mpan
+

Set middle signal pan. Default is 0. Allowed range is from -1 to 1. +

+
+
base
+

Set stereo base between mono and inversed channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
delay
+

Set delay in milliseconds how much to delay left from right channel and +vice versa. Default is 0. Allowed range is from -20 to 20. +

+
+
sclevel
+

Set S/C level. Default is 1. Allowed range is from 1 to 100. +

+
+
phase
+

Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. +

+
+
bmode_in, bmode_out
+

Set balance mode for balance_in/balance_out option. +

+

Can be one of the following: +

+
+
‘balance’
+

Classic balance mode. Attenuate one channel at time. +Gain is raised up to 1. +

+
+
‘amplitude’
+

Similar as classic mode above but gain is raised up to 2. +

+
+
‘power’
+

Equal power distribution, from -6dB to +6dB range. +

+
+
+
+ + +

36.111.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

36.111.2 Examples

+ +
    +
  • Apply karaoke like effect: +
    +
    stereotools=mlev=0.015625
    +
    + +
  • Convert M/S signal to L/R: +
    +
    "stereotools=mode=ms>lr"
    +
    +
+ + +

36.112 stereowiden

+ +

This filter enhance the stereo effect by suppressing signal common to both +channels and by delaying the signal of left into right and vice versa, +thereby widening the stereo effect. +

+

The filter accepts the following options: +

+
+
delay
+

Time in milliseconds of the delay of left signal into right and vice versa. +Default is 20 milliseconds. +

+
+
feedback
+

Amount of gain in delayed signal into right and vice versa. Gives a delay +effect of left signal in right output and vice versa which gives widening +effect. Default is 0.3. +

+
+
crossfeed
+

Cross feed of left into right with inverted phase. This helps in suppressing +the mono. If the value is 1 it will cancel all the signal common to both +channels. Default is 0.3. +

+
+
drymix
+

Set level of input signal of original channel. Default is 0.8. +

+
+ + +

36.112.1 Commands

+ +

This filter supports the all above options except delay as commands. +

+ +

36.113 superequalizer

+

Apply 18 band equalizer. +

+

The filter accepts the following options: +

+
1b
+

Set 65Hz band gain. +

+
2b
+

Set 92Hz band gain. +

+
3b
+

Set 131Hz band gain. +

+
4b
+

Set 185Hz band gain. +

+
5b
+

Set 262Hz band gain. +

+
6b
+

Set 370Hz band gain. +

+
7b
+

Set 523Hz band gain. +

+
8b
+

Set 740Hz band gain. +

+
9b
+

Set 1047Hz band gain. +

+
10b
+

Set 1480Hz band gain. +

+
11b
+

Set 2093Hz band gain. +

+
12b
+

Set 2960Hz band gain. +

+
13b
+

Set 4186Hz band gain. +

+
14b
+

Set 5920Hz band gain. +

+
15b
+

Set 8372Hz band gain. +

+
16b
+

Set 11840Hz band gain. +

+
17b
+

Set 16744Hz band gain. +

+
18b
+

Set 20000Hz band gain. +

+
+ + +

36.114 surround

+

Apply audio surround upmix filter. +

+

This filter allows to produce multichannel output from audio stream. +

+

The filter accepts the following options: +

+
+
chl_out
+

Set output channel layout. By default, this is 5.1. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
chl_in
+

Set input channel layout. By default, this is stereo. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
level_in
+

Set input volume level. By default, this is 1. +

+
+
level_out
+

Set output volume level. By default, this is 1. +

+
+
lfe
+

Enable LFE channel output if output channel layout has it. By default, this is enabled. +

+
+
lfe_low
+

Set LFE low cut off frequency. By default, this is 128 Hz. +

+
+
lfe_high
+

Set LFE high cut off frequency. By default, this is 256 Hz. +

+
+
lfe_mode
+

Set LFE mode, can be add or sub. Default is add. +In add mode, LFE channel is created from input audio and added to output. +In sub mode, LFE channel is created from input audio and added to output but +also all non-LFE output channels are subtracted with output LFE channel. +

+
+
smooth
+

Set temporal smoothness strength, used to gradually change factors when transforming +stereo sound in time. Allowed range is from 0.0 to 1.0. +Useful to improve output quality with focus option values greater than 0.0. +Default is 0.0. Only values inside this range and without edges are effective. +

+
+
angle
+

Set angle of stereo surround transform, Allowed range is from 0 to 360. +Default is 90. +

+
+
focus
+

Set focus of stereo surround transform, Allowed range is from -1 to 1. +Default is 0. +

+
+
fc_in
+

Set front center input volume. By default, this is 1. +

+
+
fc_out
+

Set front center output volume. By default, this is 1. +

+
+
fl_in
+

Set front left input volume. By default, this is 1. +

+
+
fl_out
+

Set front left output volume. By default, this is 1. +

+
+
fr_in
+

Set front right input volume. By default, this is 1. +

+
+
fr_out
+

Set front right output volume. By default, this is 1. +

+
+
sl_in
+

Set side left input volume. By default, this is 1. +

+
+
sl_out
+

Set side left output volume. By default, this is 1. +

+
+
sr_in
+

Set side right input volume. By default, this is 1. +

+
+
sr_out
+

Set side right output volume. By default, this is 1. +

+
+
bl_in
+

Set back left input volume. By default, this is 1. +

+
+
bl_out
+

Set back left output volume. By default, this is 1. +

+
+
br_in
+

Set back right input volume. By default, this is 1. +

+
+
br_out
+

Set back right output volume. By default, this is 1. +

+
+
bc_in
+

Set back center input volume. By default, this is 1. +

+
+
bc_out
+

Set back center output volume. By default, this is 1. +

+
+
lfe_in
+

Set LFE input volume. By default, this is 1. +

+
+
lfe_out
+

Set LFE output volume. By default, this is 1. +

+
+
allx
+

Set spread usage of stereo image across X axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
ally
+

Set spread usage of stereo image across Y axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
fcx, flx, frx, blx, brx, slx, srx, bcx
+

Set spread usage of stereo image across X axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
fcy, fly, fry, bly, bry, sly, sry, bcy
+

Set spread usage of stereo image across Y axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.5. +

+
+ + +

36.115 tiltshelf

+ +

Boost or cut the lower frequencies and cut or boost higher 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: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.115.1 Commands

+ +

This filter supports some options as commands. +

+ +

36.116 treble, highshelf

+ +

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). +

+

The filter accepts the following options: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

36.116.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change treble frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change treble width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change treble width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change treble gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change treble mix. +Syntax for the command is : "mix" +

+
+ + +

36.117 tremolo

+ +

Sinusoidal amplitude modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. Modulation frequencies in the subharmonic range +(20 Hz or lower) will result in a tremolo effect. +This filter may also be used as a ring modulator by specifying +a modulation frequency higher than 20 Hz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

36.118 vibrato

+ +

Sinusoidal phase modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

36.119 virtualbass

+ +

Apply audio Virtual Bass filter. +

+

This filter accepts stereo input and produce stereo with LFE (2.1) channels output. +The newly produced LFE channel have enhanced virtual bass originally obtained from both stereo channels. +This filter outputs front left and front right channels unchanged as available in stereo input. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set the virtual bass cutoff frequency. Default value is 250 Hz. +Allowed range is from 100 to 500 Hz. +

+
+
strength
+

Set the virtual bass strength. Allowed range is from 0.5 to 3. +Default value is 3. +

+
+ + +

36.120 volume

+ +

Adjust the input audio volume. +

+

It accepts the following parameters: +

+
volume
+

Set audio volume expression. +

+

Output values are clipped to the maximum value. +

+

The output audio volume is given by the relation: +

+
output_volume = volume * input_volume
+
+ +

The default value for volume is "1.0". +

+
+
precision
+

This parameter represents the mathematical precision. +

+

It determines which input sample formats will be allowed, which affects the +precision of the volume scaling. +

+
+
fixed
+

8-bit fixed-point; this limits input sample format to U8, S16, and S32. +

+
float
+

32-bit floating-point; this limits input sample format to FLT. (default) +

+
double
+

64-bit floating-point; this limits input sample format to DBL. +

+
+ +
+
replaygain
+

Choose the behaviour on encountering ReplayGain side data in input frames. +

+
+
drop
+

Remove ReplayGain side data, ignoring its contents (the default). +

+
+
ignore
+

Ignore ReplayGain side data, but leave it in the frame. +

+
+
track
+

Prefer the track gain, if present. +

+
+
album
+

Prefer the album gain, if present. +

+
+ +
+
replaygain_preamp
+

Pre-amplification gain in dB to apply to the selected replaygain gain. +

+

Default value for replaygain_preamp is 0.0. +

+
+
replaygain_noclip
+

Prevent clipping by limiting the gain applied. +

+

Default value for replaygain_noclip is 1. +

+
+
eval
+

Set when the volume expression is evaluated. +

+

It accepts the following values: +

+
‘once’
+

only evaluate expression once during the filter initialization, or +when the ‘volume’ command is sent +

+
+
‘frame’
+

evaluate expression for each incoming frame +

+
+ +

Default value is ‘once’. +

+
+ +

The volume expression can contain the following parameters. +

+
+
n
+

frame number (starting at zero) +

+
nb_channels
+

number of channels +

+
nb_consumed_samples
+

number of samples consumed by the filter +

+
nb_samples
+

number of samples in the current frame +

+
pos
+

original frame position in the file; deprecated, do not use +

+
pts
+

frame PTS +

+
sample_rate
+

sample rate +

+
startpts
+

PTS at start of stream +

+
startt
+

time at start of stream +

+
t
+

frame time +

+
tb
+

timestamp timebase +

+
volume
+

last set volume value +

+
+ +

Note that when eval is set to ‘once’ only the +sample_rate and tb variables are available, all other +variables will evaluate to NAN. +

+ +

36.120.1 Commands

+ +

This filter supports the following commands: +

+
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. +

+
+ + +

36.120.2 Examples

+ +
    +
  • Halve the input audio volume: +
    +
    volume=volume=0.5
    +volume=volume=1/2
    +volume=volume=-6.0206dB
    +
    + +

    In all the above example the named key for volume can be +omitted, for example like in: +

    +
    volume=0.5
    +
    + +
  • Increase input audio power by 6 decibels using fixed-point precision: +
    +
    volume=volume=6dB:precision=fixed
    +
    + +
  • Fade volume after time 10 with an annihilation period of 5 seconds: +
    +
    volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
    +
    +
+ + +

36.121 volumedetect

+ +

Detect the volume of the input video. +

+

The filter has no parameters. It supports only 16-bit signed integer samples, +so the input will be converted when needed. 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 a histogram of the +registered volume values (from the maximum value to a cumulated 1/1000 of +the samples). +

+

All volumes are in decibels relative to the maximum PCM value. +

+ +

36.121.1 Examples

+ +

Here is an excerpt of the output: +

+
[Parsed_volumedetect_0  0xa23120] mean_volume: -27 dB
+[Parsed_volumedetect_0  0xa23120] max_volume: -4 dB
+[Parsed_volumedetect_0  0xa23120] histogram_4db: 6
+[Parsed_volumedetect_0  0xa23120] histogram_5db: 62
+[Parsed_volumedetect_0  0xa23120] histogram_6db: 286
+[Parsed_volumedetect_0  0xa23120] histogram_7db: 1042
+[Parsed_volumedetect_0  0xa23120] histogram_8db: 2551
+[Parsed_volumedetect_0  0xa23120] histogram_9db: 4609
+[Parsed_volumedetect_0  0xa23120] histogram_10db: 8409
+
+ +

It means that: +

    +
  • The mean square energy is approximately -27 dB, or 10^-2.7. +
  • The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. +
  • There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. +
+ +

In other words, raising the volume by +4 dB does not cause any clipping, +raising it by +5 dB causes clipping for 6 samples, etc. +

+ +

36.122 whisper

+ +

It runs automatic speech recognition using the OpenAI’s Whisper model. +

+

It requires the whisper.cpp library (https://github.com/ggml-org/whisper.cpp) +as a prerequisite. After installing the library it can be enabled using: +./configure --enable-whisper. +

+

The filter has following options: +

+
+
model
+

The file path of the downloaded whisper.cpp model (mandatory). +

+
+
language
+

The language to use for transcription (’auto’ for auto-detect). +Default value: "auto" +

+
+
queue
+

The maximum size that will be queued into the filter before processing the audio +with whisper. Using a small value the audio stream will be processed more often, +but the transcription quality will be lower and the required processing power +will be higher. Using a large value (e.g. 10-20s) will produce more accurate +results using less CPU (as using the whisper-cli tool), but the transcription +latency will be higher, thus not useful to process real-time streams. +Consider using the vad_model option associated with a large queue value. +Default value: "3" +

+
+
use_gpu
+

If the GPU support should be enabled. +Default value: "true" +

+
+
gpu_device
+

The GPU device index to use. +Default value: "0" +

+
+
destination
+

If set, the transcription output will be sent to the specified file or URL +(use one of the FFmpeg AVIO protocols); otherwise, the output will be logged as +info messages. +The output will also be set in the "lavfi.whisper.text" frame metadata. +If the destination is a file and it already exists, it will be overwritten. +

+
+
format
+

The destination format string; it could be "text" (only the transcribed text +will be sent to the destination), "srt" (subtitle format) or "json". +Default value: "text" +

+
+
max_len
+

Maximum segment length in characters. When set to a value greater than 0, +transcription segments will be split to not exceed this length. This is useful +for generating subtitles with shorter lines. +Default value: "0" +

+
+
vad_model
+

Path to the VAD model file. If set, the filter will load an additional voice +activity detection module (https://github.com/snakers4/silero-vad) that will be +used to fragment the audio queue; use this option setting a valid path obtained +from the whisper.cpp repository (e.g. "../whisper.cpp/models/ggml-silero-v5.1.2.bin") +and increase the queue parameter to a higher value (e.g. 20). +

+
+
vad_threshold
+

The VAD threshold to use. +Default value: "0.5" +

+
+
vad_min_speech_duration
+

The minimum VAD speaking duration. +Default value: "0.1" +

+
+
vad_min_silence_duration
+

The minimum VAD silence duration. +Default value: "0.5" +

+
+
+ + +

36.122.1 Examples

+
    +
  • Run a transcription with srt file generation: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=output.srt\
    +:format=srt" -f null -
    +
    + +
  • Run a transcription and send the output in JSON format to an HTTP service: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=http\\://localhost\\:3000\
    +:format=json' -f null -
    +
    + +
  • Transcribe the microphone input using the VAD option: +
    +
    ffmpeg -loglevel warning -f pulse -i default \
    +-af 'highpass=f=200,lowpass=f=3000,whisper=model=../whisper.cpp/models/ggml-medium.bin\
    +:language=en\
    +:queue=10\
    +:destination=-\
    +:format=json\
    +:vad_model=../whisper.cpp/models/ggml-silero-v5.1.2.bin' -f null -
    +
    + +
+ + + +

37 Audio Sources

+ +

Below is a description of the currently available audio sources. +

+ +

37.1 abuffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
time_base
+

The timebase which will be used for timestamps of submitted frames. It must be +either a floating-point number or in numerator/denominator form. +

+
+
sample_rate
+

The sample rate of the incoming audio buffers. +

+
+
sample_fmt
+

The sample format of the incoming audio buffers. +Either a sample format name or its corresponding integer representation from +the enum AVSampleFormat in libavutil/samplefmt.h +

+
+
channel_layout
+

The channel layout of the incoming audio buffers. +Either a channel layout name from channel_layout_map in +libavutil/channel_layout.c or its corresponding integer representation +from the AV_CH_LAYOUT_* macros in libavutil/channel_layout.h +

+
+
channels
+

The number of channels of the incoming audio buffers. +If both channels and channel_layout are specified, then they +must be consistent. +

+
+
+ + +

37.1.1 Examples

+ +
+
abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
+
+ +

will instruct the source to accept planar 16bit signed stereo at 44100Hz. +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: +

+
abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
+
+ + +

37.2 aevalsrc

+ +

Generate an audio signal specified by an expression. +

+

This source accepts in input one or more expressions (one for each +channel), which are evaluated and used to generate a corresponding +audio signal. +

+

This source accepts the following options: +

+
+
exprs
+

Set the ’|’-separated expressions list for each separate channel. In case the +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. +

+
+
channel_layout, c
+

Set the channel layout. The number of channels in the specified layout +must be equal to the number of specified expressions. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, +default to 1024. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. +

+
+ +

Each expression in exprs can contain the following constants: +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
t
+

time of the evaluated sample expressed in seconds, starting from 0 +

+
+
s
+

sample rate +

+
+
+ + +

37.2.1 Examples

+ +
    +
  • Generate silence: +
    +
    aevalsrc=0
    +
    + +
  • Generate a sin signal with frequency of 440 Hz, set sample rate to +8000 Hz: +
    +
    aevalsrc="sin(440*2*PI*t):s=8000"
    +
    + +
  • Generate a two channels signal, specify the channel layout (Front +Center + Back Center) explicitly: +
    +
    aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
    +
    + +
  • Generate white noise: +
    +
    aevalsrc="-2+random(0)"
    +
    + +
  • Generate an amplitude modulated signal: +
    +
    aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
    +
    + +
  • Generate 2.5 Hz binaural beats on a 360 Hz carrier: +
    +
    aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
    +
    + +
+ + +

37.3 afdelaysrc

+ +

Generate a fractional delay FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
delay, d
+

Set the fractional delay. Default is 0. +

+
+
sample_rate, r
+

Set the sample rate, default is 44100. +

+
+
nb_samples, n
+

Set the number of samples per each frame. Default is 1024. +

+
+
taps, t
+

Set the number of filter coefficients in output audio stream. +Default value is 0. +

+
+
channel_layout, c
+

Specifies the channel layout, and can be a string representing a channel layout. +The default value of channel_layout is "stereo". +

+
+ + +

37.4 afireqsrc

+ +

Generate a FIR equalizer coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
preset, p
+

Set equalizer preset. +Default preset is flat. +

+

Available presets are: +

+
‘custom’
+
‘flat’
+
‘acoustic’
+
‘bass’
+
‘beats’
+
‘classic’
+
‘clear’
+
‘deep bass’
+
‘dubstep’
+
‘electronic’
+
‘hard-style’
+
‘hip-hop’
+
‘jazz’
+
‘metal’
+
‘movie’
+
‘pop’
+
‘r&b’
+
‘rock’
+
‘vocal booster’
+
+ +
+
gains, g
+

Set custom gains for each band. Only used if the preset option is set to custom. +Gains are separated by white spaces and each gain is set in dBFS. +Default is 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0. +

+
+
bands, b
+

Set the custom bands from where custom equalizer gains are set. +This must be in strictly increasing order. Only used if the preset option is set to custom. +Bands are separated by white spaces and each band represent frequency in Hz. +Default is 25 40 63 100 160 250 400 630 1000 1600 2500 4000 6300 10000 16000 24000. +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 4096. +

+
+
sample_rate, r
+

Set sample rate of output audio stream, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame in output audio stream. Default is 1024. +

+
+
interp, i
+

Set interpolation method for FIR equalizer coefficients. Can be linear or cubic. +

+
+
phase, h
+

Set phase type of FIR filter. Can be linear or min: minimum-phase. +Default is minimum-phase filter. +

+
+ + +

37.5 afirsrc

+ +

Generate a FIR coefficients using frequency sampling method. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 1025. +

+
+
frequency, f
+

Set frequency points from where magnitude and phase are set. +This must be in non decreasing order, and first element must be 0, while last element +must be 1. Elements are separated by white spaces. +

+
+
magnitude, m
+

Set magnitude value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
phase, p
+

Set phase value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
win_func, w
+

Set window function. Default is blackman. +

+
+ + +

37.6 anullsrc

+ +

The null audio source, return unprocessed audio frames. It is mainly useful +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). +

+

This source accepts the following options: +

+
+
channel_layout, cl
+
+

Specifies the channel layout, and can be either an integer or a string +representing a channel layout. The default value of channel_layout +is "stereo". +

+

Check the channel_layout_map definition in +libavutil/channel_layout.c for the mapping between strings and +channel layout values. +

+
+
sample_rate, r
+

Specifies the sample rate, and defaults to 44100. +

+
+
nb_samples, n
+

Set the number of samples per requested frames. +

+
+
duration, d
+

Set the duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. +

+
+ + +

37.6.1 Examples

+ +
    +
  • Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. +
    +
    anullsrc=r=48000:cl=4
    +
    + +
  • Do the same operation with a more obvious syntax: +
    +
    anullsrc=r=48000:cl=mono
    +
    +
+ +

All the parameters need to be explicitly defined. +

+ +

37.7 flite

+ +

Synthesize a voice utterance using the libflite library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libflite. +

+

Note that versions of the flite library prior to 2.0 are not thread-safe. +

+

The filter accepts the following options: +

+
+
list_voices
+

If set to 1, list the names of the available voices and exit +immediately. Default value is 0. +

+
+
nb_samples, n
+

Set the maximum number of samples per frame. Default value is 512. +

+
+
textfile
+

Set the filename containing the text to speak. +

+
+
text
+

Set the text to speak. +

+
+
voice, v
+

Set the voice to use for the speech synthesis. Default value is +kal. See also the list_voices option. +

+
+ + +

37.7.1 Examples

+ +
    +
  • Read from file speech.txt, and synthesize the text using the +standard flite voice: +
    +
    flite=textfile=speech.txt
    +
    + +
  • Read the specified text selecting the slt voice: +
    +
    flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Input text to ffmpeg: +
    +
    ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Make ffplay speak the specified text, using flite and +the lavfi device: +
    +
    ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
    +
    +
+ +

For more information about libflite, check: +http://www.festvox.org/flite/ +

+ +

37.8 anoisesrc

+ +

Generate a noise audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Specify the sample rate. Default value is 48000 Hz. +

+
+
amplitude, a
+

Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value +is 1.0. +

+
+
duration, d
+

Specify the duration of the generated audio stream. Not specifying this option +results in noise with an infinite length. +

+
+
color, colour, c
+

Specify the color of noise. Available noise colors are white, pink, brown, +blue, violet and velvet. Default color is white. +

+
+
seed, s
+

Specify a value used to seed the PRNG. +

+
+
nb_samples, n
+

Set the number of samples per each output frame, default is 1024. +

+
+
density
+

Set the density (0.0 - 1.0) for the velvet noise generator, default is 0.05. +

+
+ + +

37.8.1 Examples

+ +
    +
  • Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: +
    +
    anoisesrc=d=60:c=pink:r=44100:a=0.5
    +
    +
+ + +

37.9 hilbert

+ +

Generate odd-tap Hilbert transform FIR coefficients. +

+

The resulting stream can be used with afir filter for phase-shifting +the signal by 90 degrees. +

+

This is used in many matrix coding schemes and for analytic signal generation. +The process is often written as a multiplication by i (or j), the imaginary unit. +

+

The filter accepts the following options: +

+
+
sample_rate, s
+

Set sample rate, default is 44100. +

+
+
taps, t
+

Set length of FIR filter, default is 22051. +

+
+
nb_samples, n
+

Set number of samples per each frame. +

+
+
win_func, w
+

Set window function to be used when generating FIR coefficients. +

+
+ + +

37.10 sinc

+ +

Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
hp
+

Set high-pass frequency. Default is 0. +

+
+
lp
+

Set low-pass frequency. Default is 0. +If high-pass frequency is lower than low-pass frequency and low-pass frequency +is higher than 0 then filter will create band-pass filter coefficients, +otherwise band-reject filter coefficients. +

+
+
phase
+

Set filter phase response. Default is 50. Allowed range is from 0 to 100. +

+
+
beta
+

Set Kaiser window beta. +

+
+
att
+

Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. +

+
+
round
+

Enable rounding, by default is disabled. +

+
+
hptaps
+

Set number of taps for high-pass filter. +

+
+
lptaps
+

Set number of taps for low-pass filter. +

+
+ + +

37.11 sine

+ +

Generate an audio signal made of a sine wave with amplitude 1/8. +

+

The audio signal is bit-exact. +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the carrier frequency. Default is 440 Hz. +

+
+
beep_factor, b
+

Enable a periodic beep every second with frequency beep_factor times +the carrier frequency. Default is 0, meaning the beep is disabled. +

+
+
sample_rate, r
+

Specify the sample rate, default is 44100. +

+
+
duration, d
+

Specify the duration of the generated audio stream. +

+
+
samples_per_frame
+

Set the number of samples per output frame. +

+

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the output audio frame, starting from 0. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the output audio frame, +expressed in TB units. +

+
+
t
+

The PTS of the output audio frame, expressed in seconds. +

+
+
TB
+

The timebase of the output audio frames. +

+
+ +

Default is 1024. +

+
+ + +

37.11.1 Examples

+ +
    +
  • Generate a simple 440 Hz sine wave: +
    +
    sine
    +
    + +
  • Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: +
    +
    sine=220:4:d=5
    +sine=f=220:b=4:d=5
    +sine=frequency=220:beep_factor=4:duration=5
    +
    + +
  • Generate a 1 kHz sine wave following 1602,1601,1602,1601,1602 NTSC +pattern: +
    +
    sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
    +
    +
+ + + +

38 Audio Sinks

+ +

Below is a description of the currently available audio sinks. +

+ +

38.1 abuffersink

+ +

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 libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVABufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+

38.2 anullsink

+ +

Null audio sink; do absolutely nothing with the input audio. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

39 Video Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the video filters included in your +build. +

+

Below is a description of the currently available video filters. +

+ +

39.1 addroi

+ +

Mark a region of interest in a video frame. +

+

The frame data is passed through unchanged, but metadata is attached +to the frame indicating regions of interest which can affect the +behaviour of later encoding. Multiple regions can be marked by +applying the filter multiple times. +

+
+
x
+

Region distance in pixels from the left edge of the frame. +

+
y
+

Region distance in pixels from the top edge of the frame. +

+
w
+

Region width in pixels. +

+
h
+

Region height in pixels. +

+

The parameters x, y, w and h are expressions, +and may contain the following variables: +

+
iw
+

Width of the input frame. +

+
ih
+

Height of the input frame. +

+
+ +
+
qoffset
+

Quantisation offset to apply within the region. +

+

This must be a real value in the range -1 to +1. A value of zero +indicates no quality change. A negative value asks for better quality +(less quantisation), while a positive value asks for worse quality +(greater quantisation). +

+

The range is calibrated so that the extreme values indicate the +largest possible offset - if the rest of the frame is encoded with the +worst possible quality, an offset of -1 indicates that this region +should be encoded with the best possible quality anyway. Intermediate +values are then interpolated in some codec-dependent way. +

+

For example, in 10-bit H.264 the quantisation parameter varies between +-12 and 51. A typical qoffset value of -1/10 therefore indicates that +this region should be encoded with a QP around one-tenth of the full +range better than the rest of the frame. So, if most of the frame +were to be encoded with a QP of around 30, this region would get a QP +of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). +An extreme value of -1 would indicate that this region should be +encoded with the best possible quality regardless of the treatment of +the rest of the frame - that is, should be encoded at a QP of -12. +

+
clear
+

If set to true, remove any existing regions of interest marked on the +frame before adding the new one. +

+
+ + +

39.1.1 Examples

+ +
    +
  • Mark the centre quarter of the frame as interesting. +
    +
    addroi=iw/4:ih/4:iw/2:ih/2:-1/10
    +
    +
  • Mark the 100-pixel-wide region on the left edge of the frame as very +uninteresting (to be encoded at much lower quality than the rest of +the frame). +
    +
    addroi=0:0:100:ih:+1/5
    +
    +
+ + +

39.2 alphaextract

+ +

Extract the alpha component from the input as a grayscale video. This +is especially useful with the alphamerge filter. +

+ +

39.3 alphamerge

+ +

Add or replace the alpha component of the primary input with the +grayscale value of a second input. This is intended for use with +alphaextract to allow the transmission or storage of frame +sequences that have alpha in a format that doesn’t support an alpha +channel. +

+

For example, to reconstruct full frames from a normal YUV-encoded video +and a separate video created with alphaextract, you might use: +

+
movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
+
+ + +

39.4 amplify

+ +

Amplify differences between current pixel and pixels of adjacent frames in +same pixel location. +

+

This filter accepts the following options: +

+
+
radius
+

Set frame radius. Default is 2. Allowed range is from 1 to 63. +For example radius of 3 will instruct filter to calculate average of 7 frames. +

+
+
factor
+

Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. +

+
+
threshold
+

Set threshold for difference amplification. Any difference greater or equal to +this value will not alter source pixel. Default is 10. +Allowed range is from 0 to 65535. +

+
+
tolerance
+

Set tolerance for difference amplification. Any difference lower to +this value will not alter source pixel. Default is 0. +Allowed range is from 0 to 65535. +

+
+
low
+

Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will decrease source pixel value. +

+
+
high
+

Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will increase source pixel value. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

39.4.1 Commands

+ +

This filter supports the following commands that corresponds to option of same name: +

+
factor
+
threshold
+
tolerance
+
low
+
high
+
planes
+
+ + +

39.5 ass

+ +

Same as the subtitles filter, except that it doesn’t require libavcodec +and libavformat to work. On the other hand, it is limited to ASS (Advanced +Substation Alpha) subtitles files. +

+

This filter accepts the following option in addition to the common options from +the subtitles filter: +

+
+
shaping
+

Set the shaping engine +

+

Available values are: +

+
‘auto’
+

The default libass shaping engine, which is the best available. +

+
‘simple’
+

Fast, font-agnostic shaper that can do only substitutions +

+
‘complex’
+

Slower shaper using OpenType for substitutions and positioning +

+
+ +

The default is auto. +

+
+ + +

39.6 atadenoise

+

Apply an Adaptive Temporal Averaging Denoiser to the video input. +

+

The filter accepts the following options: +

+
+
0a
+

Set threshold A for 1st plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
0b
+

Set threshold B for 1st plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
1a
+

Set threshold A for 2nd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
1b
+

Set threshold B for 2nd plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
2a
+

Set threshold A for 3rd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
2b
+

Set threshold B for 3rd plane. Default is 0.04. +Valid range is 0 to 5. +

+

Threshold A is designed to react on abrupt changes in the input signal and +threshold B is designed to react on continuous changes in the input signal. +

+
+
s
+

Set number of frames filter will use for averaging. Default is 9. Must be odd +number in range [5, 129]. +

+
+
p
+

Set what planes of frame filter will use for averaging. Default is all. +

+
+
a
+

Set what variant of algorithm filter will use for averaging. Default is p parallel. +Alternatively can be set to s serial. +

+

Parallel can be faster then serial, while other way around is never true. +Parallel will abort early on first change being greater then thresholds, while serial +will continue processing other side of frames if they are equal or below thresholds. +

+
+
0s
+
1s
+
2s
+

Set sigma for 1st plane, 2nd plane or 3rd plane. Default is 32767. +Valid range is from 0 to 32767. +This options controls weight for each pixel in radius defined by size. +Default value means every pixel have same weight. +Setting this option to 0 effectively disables filtering. +

+
+ + +

39.6.1 Commands

+

This filter supports same commands as options except option s. +The command accepts the same syntax of the corresponding option. +

+ +

39.7 avgblur

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sizeY
+

Set vertical radius size, if zero it will be same as sizeX. +Default is 0. +

+
+ + +

39.7.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.8 backgroundkey

+ +

Turns a static background into transparency. +

+

The filter accepts the following option: +

+
+
threshold
+

Threshold for scene change detection. +

+
similarity
+

Similarity percentage with the background. +

+
blend
+

Set the blend amount for pixels that are not similar. +

+
+ + +

39.8.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.9 bbox

+ +

Compute the bounding box for the non-black pixels in the input frame +luma plane. +

+

This filter computes the bounding box containing all the pixels with a +luma 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: +

+
+
min_val
+

Set the minimal luma value. Default is 16. +

+
+ + +

39.9.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.10 bilateral

+

Apply bilateral filter, spatial smoothing while preserving edges. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight. +Allowed range is 0 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate range weight. +Allowed range is 0 to 1. Default is 0.1. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

39.10.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.11 bitplanenoise

+ +

Show and measure bit plane noise. +

+

The filter accepts the following options: +

+
+
bitplane
+

Set which plane to analyze. Default is 1. +

+
+
filter
+

Filter out noisy pixels from bitplane set above. +Default is disabled. +

+
+ + +

39.12 blackdetect, blackdetect_vulkan

+ +

Detect video intervals that are (almost) completely black. Can be +useful to detect chapter transitions, commercials, or invalid +recordings. +

+

The filter outputs its detection analysis to both the log as well as +frame metadata. If a black segment of at least the specified minimum +duration is found, a line with the start and end timestamps as well +as duration is printed to the log with level info. In addition, +a log line with level debug is printed per frame showing the +black amount detected for that frame. +

+

The filter also attaches metadata to the first frame of a black +segment with key lavfi.black_start and to the first frame +after the black segment ends with key lavfi.black_end. The +value is the frame’s timestamp. This metadata is added regardless +of the minimum duration specified. +

+

The filter accepts the following options: +

+
+
black_min_duration, d
+

Set the minimum detected black duration expressed in seconds. It must +be a non-negative floating point number. +

+

Default value is 2.0. +

+
+
picture_black_ratio_th, pic_th
+

Set the threshold for considering a picture "black". +Express the minimum value for the ratio: +

+
nb_black_pixels / nb_pixels
+
+ +

for which a picture is considered black. +Default value is 0.98. +

+
+
pixel_black_th, pix_th
+

Set the threshold for considering a pixel "black". +

+

The threshold expresses the maximum pixel luma value for which a +pixel is considered "black". The provided value is scaled according to +the following equation: +

+
absolute_threshold = luma_minimum_value + pixel_black_th * luma_range_size
+
+ +

luma_range_size and luma_minimum_value depend on +the input video format, the range is [0-255] for YUV full-range +formats and [16-235] for YUV non full-range formats. +

+

Default value is 0.10. +

+
+
alpha
+

If true, check the alpha channel instead of the luma channel. Detects frames +which are (almost) transparent, instead of frames which are almost black. +

+

Default value is disabled. +

+
+ +

The following example sets the maximum pixel threshold to the minimum +value, and detects only black intervals of 2 or more seconds: +

+
blackdetect=d=2:pix_th=0.00
+
+ + +

39.13 blackframe

+ +

Detect frames that are (almost) completely black. Can be useful to +detect chapter transitions or commercials. Output lines consist of +the frame number of the detected frame, the percentage of blackness, +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. +

+

This filter exports frame metadata lavfi.blackframe.pblack. +The value represents the percentage of pixels in the picture that +are below the threshold value. +

+

It accepts the following parameters: +

+
+
amount
+

The percentage of the pixels that have to be below the threshold; it defaults to +98. +

+
+
threshold, thresh
+

The threshold below which a pixel value is considered black; it defaults to +32. +

+
+
+ + +

39.14 blend

+ +

Blend two video frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

The tblend (time blend) filter takes two consecutive frames +from one single stream, and outputs the result obtained by blending +the new frame on top of the old frame. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘addition’
+
‘and’
+
‘average’
+
‘bleach’
+
‘burn’
+
‘darken’
+
‘difference’
+
‘divide’
+
‘dodge’
+
‘exclusion’
+
‘extremity’
+
‘freeze’
+
‘geometric’
+
‘glow’
+
‘grainextract’
+
‘grainmerge’
+
‘hardlight’
+
‘hardmix’
+
‘hardoverlay’
+
‘harmonic’
+
‘heat’
+
‘interpolate’
+
‘lighten’
+
‘linearlight’
+
‘multiply’
+
‘multiply128’
+
‘negation’
+
‘normal’
+
‘or’
+
‘overlay’
+
‘phoenix’
+
‘pinlight’
+
‘reflect’
+
‘screen’
+
‘softdifference’
+
‘softlight’
+
‘stain’
+
‘subtract’
+
‘vividlight’
+
‘xor’
+
+ +
+
c0_opacity
+
c1_opacity
+
c2_opacity
+
c3_opacity
+
all_opacity
+

Set blend opacity for specific pixel component or all pixel components in case +of all_opacity. Only used in combination with pixel component blend modes. +

+
+
c0_expr
+
c1_expr
+
c2_expr
+
c3_expr
+
all_expr
+

Set blend expression for specific pixel component or all pixel components in case +of all_expr. Note that related mode options will be ignored if those are set. +

+

The expressions can use the following variables: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

the coordinates of the current sample +

+
+
W
+
H
+

the width and height of currently filtered plane +

+
+
SW
+
SH
+

Width and height scale for the plane being filtered. It is the +ratio between the dimensions of the current plane to the luma plane, +e.g. for a yuv420p frame, the values are 1,1 for +the luma plane and 0.5,0.5 for the chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
TOP, A
+

Value of pixel component at current location for first video frame (top layer). +

+
+
BOTTOM, B
+

Value of pixel component at current location for second video frame (bottom layer). +

+
+
+
+ +

The blend filter also supports the framesync options. +

+ +

39.14.1 Examples

+ +
    +
  • Apply transition from bottom layer to top layer in first 10 seconds: +
    +
    blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
    +
    + +
  • Apply linear horizontal transition from top layer to bottom layer: +
    +
    blend=all_expr='A*(X/W)+B*(1-X/W)'
    +
    + +
  • Apply 1x1 checkerboard effect: +
    +
    blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
    +
    + +
  • Apply uncover left effect: +
    +
    blend=all_expr='if(gte(N*SW+X,W),A,B)'
    +
    + +
  • Apply uncover down effect: +
    +
    blend=all_expr='if(gte(Y-N*SH,0),A,B)'
    +
    + +
  • Apply uncover up-left effect: +
    +
    blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
    +
    + +
  • Split diagonally video and shows top and bottom layer on each side: +
    +
    blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
    +
    + +
  • Display differences between the current and the previous frame: +
    +
    tblend=all_mode=grainextract
    +
    +
+ + +

39.14.2 Commands

+

This filter supports same commands as options. +

+ +

39.15 blockdetect

+ +

Determines blockiness of frames without altering the input frames. +

+

Based on Remco Muijs and Ihor Kirenko: "A no-reference blocking artifact measure for adaptive video processing." 2005 13th European signal processing conference. +

+

The filter accepts the following options: +

+
+
period_min
+
period_max
+

Set minimum and maximum values for determining pixel grids (periods). +Default values are [3,24]. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

39.15.1 Examples

+ +
    +
  • Determine blockiness for the first plane and search for periods within [8,32]: +
    +
    blockdetect=period_min=8:period_max=32:planes=1
    +
    +
+ + +

39.16 blurdetect

+ +

Determines blurriness of frames without altering the input frames. +

+

Based on Marziliano, Pina, et al. "A no-reference perceptual blur metric." +Allows for a block-based abbreviation. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
radius
+

Define the radius to search around an edge pixel for local maxima. +

+
+
block_pct
+

Determine blurriness only for the most significant blocks, given in percentage. +

+
+
block_width
+

Determine blurriness for blocks of width block_width. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_height. +

+
+
block_height
+

Determine blurriness for blocks of height block_height. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_width. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

39.16.1 Examples

+ +
    +
  • Determine blur for 80% of most significant 32x32 blocks: +
    +
    blurdetect=block_width=32:block_height=32:block_pct=80
    +
    +
+ + +

39.17 bm3d

+ +

Denoise frames using Block-Matching 3D algorithm. +

+

The filter accepts the following options. +

+
+
sigma
+

Set denoising strength. Default value is 1. +Allowed range is from 0 to 999.9. +The denoising algorithm is very sensitive to sigma, so adjust it +according to the source. +

+
+
block
+

Set local patch size. This sets dimensions in 2D. +

+
+
bstep
+

Set sliding step for processing blocks. Default value is 4. +Allowed range is from 1 to 64. +Smaller values allows processing more reference blocks and is slower. +

+
+
group
+

Set maximal number of similar blocks for 3rd dimension. Default value is 1. +When set to 1, no block matching is done. Larger values allows more blocks +in single group. +Allowed range is from 1 to 256. +

+
+
range
+

Set radius for search block matching. Default is 9. +Allowed range is from 1 to INT32_MAX. +

+
+
mstep
+

Set step between two search locations for block matching. Default is 1. +Allowed range is from 1 to 64. Smaller is slower. +

+
+
thmse
+

Set threshold of mean square error for block matching. Valid range is 0 to +INT32_MAX. +

+
+
hdthr
+

Set thresholding parameter for hard thresholding in 3D transformed domain. +Larger values results in stronger hard-thresholding filtering in frequency +domain. +

+
+
estim
+

Set filtering estimation mode. Can be basic or final. +Default is basic. +

+
+
ref
+

If enabled, filter will use 2nd stream for block matching. +Default is disabled for basic value of estim option, +and always enabled if value of estim is final. +

+
+
planes
+

Set planes to filter. Default is all available except alpha. +

+
+ + +

39.17.1 Examples

+ +
    +
  • Basic filtering with bm3d: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
    +
    + +
  • Same as above, but filtering only luma: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
    +
    + +
  • Same as above, but with both estimation modes: +
    +
    split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    + +
  • Same as above, but prefilter with nlmeans filter instead: +
    +
    split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    +
+ + +

39.18 boxblur

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

39.18.1 Examples

+ +
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radii +set to 2: +
    +
    boxblur=luma_radius=2:luma_power=1
    +boxblur=2:1
    +
    + +
  • Set the luma radius to 2, and alpha and chroma radius to 0: +
    +
    boxblur=2:1:cr=0:ar=0
    +
    + +
  • Set the luma and chroma radii to a fraction of the video dimension: +
    +
    boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
    +
    +
+ + +

39.19 bwdif

+ +

Deinterlace the input video ("bwdif" stands for "Bob Weaver +Deinterlacing Filter"). +

+

Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic +interpolation algorithms. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

39.20 ccrepack

+ +

Repack CEA-708 closed captioning side data +

+

This filter fixes various issues seen with commercial encoders +related to upstream malformed CEA-708 payloads, specifically +incorrect number of tuples (wrong cc_count for the target FPS), +and incorrect ordering of tuples (i.e. the CEA-608 tuples are not at +the first entries in the payload). +

+ +

39.21 cas

+ +

Apply Contrast Adaptive Sharpen filter to video stream. +

+

The filter accepts the following options: +

+
+
strength
+

Set the sharpening strength. Default value is 0. +

+
+
planes
+

Set planes to filter. Default value is to filter all +planes except alpha plane. +

+
+ + +

39.21.1 Commands

+

This filter supports same commands as options. +

+ +

39.22 chromahold

+

Remove all color information for all colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral chroma. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +0.0 makes pixels either fully gray, or not gray at all. +Higher values result in more preserved color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

39.22.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.23 chromakey

+

YUV colorspace color/chroma keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

39.23.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.23.2 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf chromakey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static black background. +
    +
    ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
    +
    +
+ + +

39.24 chromanr

+

Reduce chrominance noise. +

+

The filter accepts the following options: +

+
+
thres
+

Set threshold for averaging chrominance values. +Sum of absolute difference of Y, U and V pixel components of current +pixel and neighbour pixels lower than this threshold will be used in +averaging. Luma component is left unchanged and is copied to output. +Default value is 30. Allowed range is from 1 to 200. +

+
+
sizew
+

Set horizontal radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
sizeh
+

Set vertical radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
stepw
+

Set horizontal step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
steph
+

Set vertical step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
threy
+

Set Y threshold for averaging chrominance values. +Set finer control for max allowed difference between Y components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threu
+

Set U threshold for averaging chrominance values. +Set finer control for max allowed difference between U components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threv
+

Set V threshold for averaging chrominance values. +Set finer control for max allowed difference between V components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
distance
+

Set distance type used in calculations. +

+
+
‘manhattan’
+

Absolute difference. +

+
‘euclidean’
+

Difference squared. +

+
+ +

Default distance type is manhattan. +

+
+ + +

39.24.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+ +

39.25 chromashift

+

Shift chroma pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
cbh
+

Set amount to shift chroma-blue horizontally. +

+
cbv
+

Set amount to shift chroma-blue vertically. +

+
crh
+

Set amount to shift chroma-red horizontally. +

+
crv
+

Set amount to shift chroma-red vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

39.25.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.26 ciescope

+ +

Display CIE color diagram with pixels overlaid onto it. +

+

The filter accepts the following options: +

+
+
system
+

Set color system. +

+
+
‘ntsc, 470m’
+
‘ebu, 470bg’
+
‘smpte’
+
‘240m’
+
‘apple’
+
‘widergb’
+
‘cie1931’
+
‘rec709, hdtv’
+
‘uhdtv, rec2020’
+
‘dcip3’
+
+ +
+
cie
+

Set CIE system. +

+
+
‘xyy’
+
‘ucs’
+
‘luv’
+
+ +
+
gamuts
+

Set what gamuts to draw. +

+

See system option for available values. +

+
+
size, s
+

Set ciescope size, by default set to 512. +

+
+
intensity, i
+

Set intensity used to map input pixel values to CIE diagram. +

+
+
contrast
+

Set contrast used to draw tongue colors that are out of active color system gamut. +

+
+
corrgamma
+

Correct gamma displayed on scope, by default enabled. +

+
+
showwhite
+

Show white point on CIE diagram, by default disabled. +

+
+
gamma
+

Set input gamma. Used only with XYZ input color space. +

+
+
fill
+

Fill with CIE colors. By default is enabled. +

+
+ + +

39.27 codecview

+ +

Visualize information exported by some codecs. +

+

Some codecs can export information through frames using side-data or other +means. For example, some MPEG based codecs export motion vectors through the +export_mvs flag in the codec flags2 option. +

+

The filter accepts the following option: +

+
+
block
+

Display block partition structure using the luma plane. +

+
+
mv
+

Set motion vectors to visualize. +

+

Available flags for mv are: +

+
+
‘pf’
+

forward predicted MVs of P-frames +

+
‘bf’
+

forward predicted MVs of B-frames +

+
‘bb’
+

backward predicted MVs of B-frames +

+
+ +
+
qp
+

Display quantization parameters using the chroma planes. +

+
+
mv_type, mvt
+

Set motion vectors type to visualize. Includes MVs from all frames unless specified by frame_type option. +

+

Available flags for mv_type are: +

+
+
‘fp’
+

forward predicted MVs +

+
‘bp’
+

backward predicted MVs +

+
+ +
+
frame_type, ft
+

Set frame type to visualize motion vectors of. +

+

Available flags for frame_type are: +

+
+
‘if’
+

intra-coded frames (I-frames) +

+
‘pf’
+

predicted frames (P-frames) +

+
‘bf’
+

bi-directionally predicted frames (B-frames) +

+
+
+
+ + +

39.27.1 Examples

+ +
    +
  • Visualize forward predicted MVs of all frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
    +
    + +
  • Visualize multi-directionals MVs of P and B-Frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
    +
    +
+ + +

39.28 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: +

+
+
rs
+
gs
+
bs
+

Adjust red, green and blue shadows (darkest pixels). +

+
+
rm
+
gm
+
bm
+

Adjust red, green and blue midtones (medium pixels). +

+
+
rh
+
gh
+
bh
+

Adjust red, green and blue highlights (brightest pixels). +

+

Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
pl
+

Preserve lightness when changing color balance. Default is disabled. +

+
+ + +

39.28.1 Examples

+ +
    +
  • Add red color cast to shadows: +
    +
    colorbalance=rs=.3
    +
    +
+ + +

39.28.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.29 colorcontrast

+ +

Adjust color contrast between RGB components. +

+

The filter accepts the following options: +

+
+
rc
+

Set the red-cyan contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
gm
+

Set the green-magenta contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
by
+

Set the blue-yellow contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
rcw
+
gmw
+
byw
+

Set the weight of each rc, gm, by option value. Default value is 0.0. +Allowed range is from 0.0 to 1.0. If all weights are 0.0 filtering is disabled. +

+
+
pl
+

Set the amount of preserving lightness. Default value is 0.0. Allowed range is from 0.0 to 1.0. +

+
+ + +

39.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.30 colorcorrect

+ +

Adjust color white balance selectively for blacks and whites. +This filter operates in YUV colorspace. +

+

The filter accepts the following options: +

+
+
rl
+

Set the red shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bl
+

Set the blue shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
rh
+

Set the red highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bh
+

Set the blue highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
saturation
+

Set the amount of saturation. Allowed range is from -3.0 to 3.0. +Default value is 1. +

+
+
analyze
+

If set to anything other than manual it will analyze every frame and use derived +parameters for filtering output frame. +

+

Possible values are: +

+
‘manual’
+
‘average’
+
‘minmax’
+
‘median’
+
+

Default value is manual. +

+
+ + +

39.30.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.31 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: +

+
red=red*rr + blue*rb + green*rg + alpha*ra
+
+ +

The filter accepts the following options: +

+
+
rr
+
rg
+
rb
+
ra
+

Adjust contribution of input red, green, blue and alpha channels for output red channel. +Default is 1 for rr, and 0 for rg, rb and ra. +

+
+
gr
+
gg
+
gb
+
ga
+

Adjust contribution of input red, green, blue and alpha channels for output green channel. +Default is 1 for gg, and 0 for gr, gb and ga. +

+
+
br
+
bg
+
bb
+
ba
+

Adjust contribution of input red, green, blue and alpha channels for output blue channel. +Default is 1 for bb, and 0 for br, bg and ba. +

+
+
ar
+
ag
+
ab
+
aa
+

Adjust contribution of input red, green, blue and alpha channels for output alpha channel. +Default is 1 for aa, and 0 for ar, ag and ab. +

+

Allowed ranges for options are [-2.0, 2.0]. +

+
+
pc
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+ +
+
pa
+

Set the preserve color amount when changing colors. Allowed range is from [0.0, 1.0]. +Default is 0.0, thus disabled. +

+
+ + +

39.31.1 Examples

+ +
    +
  • Convert source to grayscale: +
    +
    colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
    +
    +
  • Simulate sepia tones: +
    +
    colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
    +
    +
+ + +

39.31.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.32 colordetect

+

Analyze the video frames to determine the effective value range and alpha +mode. +

+

The filter accepts the following options: +

+
+
mode
+

Set of properties to detect. Unavailable properties, such as alpha mode for +an input image without an alpha channel, will be ignored automatically. +

+

Accepts a combination of the following flags: +

+
+
‘color_range’
+

Detect if the source contains luma pixels outside the limited (MPEG) range, +which indicates that this is a full range YUV source. +

+
‘alpha_mode’
+

Detect if the source contains color values above the alpha channel, which +indicates that the alpha channel is independent (straight), rather than +premultiplied. Also detects if the alpha plane is fully opaque or not. +

+
‘all’
+

Enable detection of all of the above properties. This is the default. +

+
+ +
+
+ + +

39.33 colorize

+

Overlay a solid color on the video stream. +

+

The filter accepts the following options: +

+
+
hue
+

Set the color hue. Allowed range is from 0 to 360. +Default value is 0. +

+
+
saturation
+

Set the color saturation. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
lightness
+

Set the color lightness. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
mix
+

Set the mix of source lightness. By default is set to 1.0. +Allowed range is from 0.0 to 1.0. +

+
+ + +

39.33.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.34 colorkey

+

RGB colorspace color keying. +This filter operates on 8-bit RGB format frames by setting the alpha component of each pixel +which falls within the similarity radius of the key color to 0. The alpha value for pixels outside +the similarity radius depends on the value of the blend option. +

+

The filter accepts the following options: +

+
+
color
+

Set the color for which alpha will be set to 0 (full transparency). +See "Color" section in the ffmpeg-utils manual. +Default is black. +

+
+
similarity
+

Set the radius from the key color within which other colors also have full transparency. +The computed distance is related to the unit fractional distance in 3D space between the RGB values +of the key color and the pixel’s color. Range is 0.01 to 1.0. 0.01 matches within a very small radius +around the exact key color, while 1.0 matches everything. +Default is 0.01. +

+
+
blend
+

Set how the alpha value for pixels that fall outside the similarity radius is computed. +0.0 makes pixels either fully transparent or fully opaque. +Higher values result in semi-transparent pixels, with greater transparency +the more similar the pixel color is to the key color. +Range is 0.0 to 1.0. Default is 0.0. +

+
+ + +

39.34.1 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf colorkey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static background image. +
    +
    ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv
    +
    +
+ + +

39.34.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.35 colorhold

+

Remove all color information for all RGB colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral gray. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. 0.0 makes pixels fully gray. +Higher values result in more preserved color. +

+
+ + +

39.35.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.36 colorlevels

+ +

Adjust video input frames using levels. +

+

The filter accepts the following options: +

+
+
rimin
+
gimin
+
bimin
+
aimin
+

Adjust red, green, blue and alpha input black point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
rimax
+
gimax
+
bimax
+
aimax
+

Adjust red, green, blue and alpha input white point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 1. +

+

Input levels are used to lighten highlights (bright tones), darken shadows +(dark tones), change the balance of bright and dark tones. +

+
+
romin
+
gomin
+
bomin
+
aomin
+

Adjust red, green, blue and alpha output black point. +Allowed ranges for options are [0, 1.0]. Defaults are 0. +

+
+
romax
+
gomax
+
bomax
+
aomax
+

Adjust red, green, blue and alpha output white point. +Allowed ranges for options are [0, 1.0]. Defaults are 1. +

+

Output levels allows manual selection of a constrained output level range. +

+
+
preserve
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+
+
+ + +

39.36.1 Examples

+ +
    +
  • Make video output darker: +
    +
    colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
    +
    + +
  • Increase contrast: +
    +
    colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
    +
    + +
  • Make video output lighter: +
    +
    colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
    +
    + +
  • Increase brightness: +
    +
    colorlevels=romin=0.5:gomin=0.5:bomin=0.5
    +
    +
+ + +

39.36.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.37 colormap

+

Apply custom color maps to video stream. +

+

This filter needs three input video streams. +First stream is video stream that is going to be filtered out. +Second and third video stream specify color patches for source +color to target color mapping. +

+

The filter accepts the following options: +

+
+
patch_size
+

Set the source and target video stream patch size in pixels. +

+
+
nb_patches
+

Set the max number of used patches from source and target video stream. +Default value is number of patches available in additional video streams. +Max allowed number of patches is 64. +

+
+
type
+

Set the adjustments used for target colors. Can be relative or absolute. +Defaults is absolute. +

+
+
kernel
+

Set the kernel used to measure color differences between mapped colors. +

+

The accepted values are: +

+
‘euclidean’
+
‘weuclidean’
+
+ +

Default is euclidean. +

+
+ + +

39.38 colormatrix

+ +

Convert color matrix. +

+

The filter accepts the following options: +

+
+
src
+
dst
+

Specify the source and destination color matrix. Both values must be +specified. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt601’
+

BT.601 +

+
+
‘bt470’
+

BT.470 +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+
+ +

For example to convert from BT.601 to SMPTE-240M, use the command: +

+
colormatrix=bt601:smpte240m
+
+ + +

39.39 colorspace

+ +

Convert colorspace, transfer characteristics or color primaries. +Input video needs to have an even size. +

+

The filter accepts the following options: +

+
+
+
all
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘bt601-6-525’
+

BT.601-6 525 +

+
+
‘bt601-6-625’
+

BT.601-6 625 +

+
+
‘bt709’
+

BT.709 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
space
+

Specify output colorspace. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘ycgco’
+

YCgCo +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M, BT.601-6 625 or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘srgb’
+

SRGB +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘xvycc’
+

xvycc +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+ +
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
format
+

Specify output color format. +

+

The accepted values are: +

+
‘yuv420p’
+

YUV 4:2:0 planar 8-bits +

+
+
‘yuv420p10’
+

YUV 4:2:0 planar 10-bits +

+
+
‘yuv420p12’
+

YUV 4:2:0 planar 12-bits +

+
+
‘yuv422p’
+

YUV 4:2:2 planar 8-bits +

+
+
‘yuv422p10’
+

YUV 4:2:2 planar 10-bits +

+
+
‘yuv422p12’
+

YUV 4:2:2 planar 12-bits +

+
+
‘yuv444p’
+

YUV 4:4:4 planar 8-bits +

+
+
‘yuv444p10’
+

YUV 4:4:4 planar 10-bits +

+
+
‘yuv444p12’
+

YUV 4:4:4 planar 12-bits +

+
+
+ +
+
fast
+

Do a fast conversion, which skips gamma/primary correction. This will take +significantly less CPU, but will be mathematically incorrect. To get output +compatible with that produced by the colormatrix filter, use fast=1. +

+
+
dither
+

Specify dithering mode. +

+

The accepted values are: +

+
‘none’
+

No dithering +

+
+
‘fsb’
+

Floyd-Steinberg dithering +

+
+ +
+
wpadapt
+

Whitepoint adaptation mode. +

+

The accepted values are: +

+
‘bradford’
+

Bradford whitepoint adaptation +

+
+
‘vonkries’
+

von Kries whitepoint adaptation +

+
+
‘identity’
+

identity whitepoint adaptation (i.e. no whitepoint adaptation) +

+
+ +
+
clipgamut
+

Controls how to clip out-of-gamut colors that arise as a result of colorspace conversion. +

+

The accepted values are: +

+
‘none’
+

No clipping of out of gamut colors. +

+
+
‘rgb’
+

Clips the RGB values to the [0, 1] range when building the gamma transfer LUTs. +

+
+ +
+
iall
+

Override all input properties at once. Same accepted values as all. +

+
+
ispace
+

Override input colorspace. Same accepted values as space. +

+
+
iprimaries
+

Override input color primaries. Same accepted values as primaries. +

+
+
itrc
+

Override input transfer characteristics. Same accepted values as trc. +

+
+
irange
+

Override input color range. Same accepted values as range. +

+
+
+ +

The filter converts the transfer characteristics, color space and color +primaries to the specified user values. The output value, if not specified, +is set to a default value based on the "all" property. If that property is +also not specified, the filter will log an error. The output color range and +format default to the same value as the input color range and format. The +input transfer characteristics, color space, color primaries and color range +should be set on the input data. If any of these are missing, the filter will +log an error and no conversion will take place. +

+

For example to convert the input to SMPTE-240M, use the command: +

+
colorspace=smpte240m
+
+ + +

39.40 colortemperature

+

Adjust color temperature in video to simulate variations in ambient color temperature. +

+

The filter accepts the following options: +

+
+
temperature
+

Set the temperature in Kelvin. Allowed range is from 1000 to 40000. +Default value is 6500 K. +

+
+
mix
+

Set mixing with filtered output. Allowed range is from 0 to 1. +Default value is 1. +

+
+
pl
+

Set the amount of preserving lightness. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

39.40.1 Commands

+

This filter supports same commands as options. +

+ +

39.41 convolution

+ +

Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed integers in square mode, +and from 1 to 49 odd number of signed integers in row mode. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be 1/sum of all matrix elements. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. Default is 0.0. +

+
+
0mode
+
1mode
+
2mode
+
3mode
+

Set matrix mode for each plane. Can be square, row or column. +Default is square. +

+
+ + +

39.41.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.41.2 Examples

+ +
    +
  • Apply sharpen: +
    +
    convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
    +
    + +
  • Apply blur: +
    +
    convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
    +
    + +
  • Apply edge enhance: +
    +
    convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
    +
    + +
  • Apply edge detect: +
    +
    convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"
    +
    + +
  • Apply emboss: +
    +
    convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
    +
    +
+ + +

39.42 convolve

+ +

Apply 2D convolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+ +

The convolve filter also supports the framesync options. +

+ +

39.43 copy

+ +

Copy the input video source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

39.44 coreimage

+

Video filtering on GPU using Apple’s CoreImage API on OSX. +

+

Hardware acceleration is based on an OpenGL context. Usually, this means it is +processed by video hardware. However, software-based OpenGL implementations +exist which means there is no guarantee for hardware processing. It depends on +the respective OSX. +

+

There are many filters and image generators provided by Apple that come with a +large variety of options. The filter has to be referenced by its name along +with its options. +

+

The coreimage filter accepts the following options: +

+
list_filters
+

List all available filters and generators along with all their respective +options as well as possible minimum and maximum values along with the default +values. +

+
list_filters=true
+
+ +
+
filter
+

Specify all filters by their respective name and options. +Use list_filters to determine all valid filter names and options. +Numerical options are specified by a float value and are automatically clamped +to their respective value range. Vector and color options have to be specified +by a list of space separated float values. Character escaping has to be done. +A special option name default is available to use default options for a +filter. +

+

It is required to specify either default or at least one of the filter options. +All omitted options are used with their default values. +The syntax of the filter string is as follows: +

+
filter=<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...][#<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...]][#...]
+
+ +
+
output_rect
+

Specify a rectangle where the output of the filter chain is copied into the +input image. It is given by a list of space separated float values: +

+
output_rect=x\ y\ width\ height
+
+

If not given, the output rectangle equals the dimensions of the input image. +The output rectangle is automatically cropped at the borders of the input +image. Negative values are valid for each component. +

+
output_rect=25\ 25\ 100\ 100
+
+
+
+ +

Several filters can be chained for successive processing without GPU-HOST +transfers allowing for fast processing of complex filter chains. +Currently, only filters with zero (generators) or exactly one (filters) input +image and one output image are supported. Also, transition filters are not yet +usable as intended. +

+

Some filters generate output images with additional padding depending on the +respective filter kernel. The padding is automatically removed to ensure the +filter output has the same size as the input image. +

+

For image generators, the size of the output image is determined by the +previous output image of the filter chain or the input image of the whole +filterchain, respectively. The generators do not use the pixel information of +this image to generate their output. However, the generated output is +blended onto this image, resulting in partial or complete coverage of the +output image. +

+

The coreimagesrc video source can be used for generating input images +which are directly fed into the filter chain. By using it, providing input +images by another video source or an input video is not required. +

+ +

39.44.1 Examples

+ +
    +
  • List all filters available: +
    +
    coreimage=list_filters=true
    +
    + +
  • Use the CIBoxBlur filter with default options to blur an image: +
    +
    coreimage=filter=CIBoxBlur@default
    +
    + +
  • Use a filter chain with CISepiaTone at default values and CIVignetteEffect with +its center at 100x100 and a radius of 50 pixels: +
    +
    coreimage=filter=CIBoxBlur@default#CIVignetteEffect@inputCenter=100\ 100@inputRadius=50
    +
    + +
  • Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +
+ + +

39.45 corr

+ +

Obtain the correlation between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max correlation is printed through +the logging system. +

+

The filter stores the calculated correlation of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi corr -f null -
+
+ + +

39.46 cover_rect

+ +

Cover a rectangular object +

+

It accepts the following options: +

+
+
cover
+

Filepath of the optional cover image, needs to be in yuv420. +

+
+
mode
+

Set covering mode. +

+

It accepts the following values: +

+
‘cover’
+

cover it by the supplied image +

+
‘blur’
+

cover it by interpolating the surrounding pixels +

+
+ +

Default value is blur. +

+
+ + +

39.46.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    +
+ + +

39.47 crop

+ +

Crop the input video to given dimensions. +

+

It accepts the following parameters: +

+
+
w, out_w
+

The width of the output video. It defaults to iw. +This expression is evaluated only once during the filter +configuration, or when the ‘w’ or ‘out_w’ command is sent. +

+
+
h, out_h
+

The height of the output video. It defaults to ih. +This expression is evaluated only once during the filter +configuration, or when the ‘h’ or ‘out_h’ command is sent. +

+
+
x
+

The horizontal position, in the input video, of the left edge of the output +video. It defaults to (in_w-out_w)/2. +This expression is evaluated per-frame. +

+
+
y
+

The vertical position, in the input video, of the top edge of the output video. +It defaults to (in_h-out_h)/2. +This expression is evaluated per-frame. +

+
+
keep_aspect
+

If set to 1 will force the output display aspect ratio +to be the same of the input, by changing the output sample aspect +ratio. It defaults to 0. +

+
+
exact
+

Enable exact cropping. If enabled, subsampled videos will be cropped at exact +width/height/x/y as specified and will not be rounded to nearest smaller value. +It defaults to 0. +

+
+ +

The out_w, out_h, x, y parameters are +expressions containing the following constants: +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
in_w
+
in_h
+

The input width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (cropped) width and height. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

The expression for out_w may depend on the value of out_h, +and the expression for out_h may depend on out_w, but they +cannot depend on x and y, as x and y are +evaluated after out_w and out_h. +

+

The x and y parameters specify the expressions for the +position of the top-left corner of the output (non-cropped) area. They +are evaluated for each frame. If the evaluated value is not valid, it +is approximated to the nearest valid value. +

+

The expression for x may depend on y, and the expression +for y may depend on x. +

+ +

39.47.1 Examples

+ +
    +
  • Crop area with size 100x100 at position (12,34). +
    +
    crop=100:100:12:34
    +
    + +

    Using named options, the example above becomes: +

    +
    crop=w=100:h=100:x=12:y=34
    +
    + +
  • Crop the central input area with size 100x100: +
    +
    crop=100:100
    +
    + +
  • Crop the central input area with size 2/3 of the input video: +
    +
    crop=2/3*in_w:2/3*in_h
    +
    + +
  • Crop the input video central square: +
    +
    crop=out_w=in_h
    +crop=in_h
    +
    + +
  • Delimit the rectangle with the top-left corner placed at position +100:100 and the right-bottom corner corresponding to the right-bottom +corner of the input image. +
    +
    crop=in_w-100:in_h-100:100:100
    +
    + +
  • Crop 10 pixels from the left and right borders, and 20 pixels from +the top and bottom borders +
    +
    crop=in_w-2*10:in_h-2*20
    +
    + +
  • Keep only the bottom right quarter of the input image: +
    +
    crop=in_w/2:in_h/2:in_w/2:in_h/2
    +
    + +
  • Crop height for getting Greek harmony: +
    +
    crop=in_w:1/PHI*in_w
    +
    + +
  • Apply trembling effect: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)
    +
    + +
  • Apply erratic camera effect depending on timestamp: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)
    +
    + +
  • Set x depending on the value of y: +
    +
    crop=in_w/2:in_h/2:y:10+10*sin(n/10)
    +
    +
+ + +

39.47.2 Commands

+ +

This filter supports the following commands: +

+
w, out_w
+
h, out_h
+
x
+
y
+

Set width/height of the output video and the horizontal/vertical position +in the input video. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+
+ + +

39.48 cropdetect

+ +

Auto-detect the crop size. +

+

It calculates the necessary cropping parameters and prints the +recommended parameters via the logging system. The detected dimensions +correspond to the non-black or video area of the input video according to mode. +

+

It accepts the following parameters: +

+
+
mode
+

Depending on mode crop detection is based on either the mere black value of surrounding pixels or a combination of motion vectors and edge pixels. +

+
+
‘black’
+

Detect black pixels surrounding the playing video. For fine control use option limit. +

+
+
‘mvedges’
+

Detect the playing video by the motion vectors inside the video and scanning for edge pixels typically forming the border of a playing video. +

+
+ +
+
limit
+

Set higher black value threshold, which can be optionally specified +from nothing (0) to everything (255 for 8-bit based formats). An intensity +value greater to the set value is considered non-black. It defaults to 24. +You can also specify a value between 0.0 and 1.0 which will be scaled depending +on the bitdepth of the pixel format. +

+
+
round
+

The value which the width/height should be divisible by. It defaults to +16. The 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. +

+
+
skip
+

Set the number of initial frames for which evaluation is skipped. +Default is 2. Range is 0 to INT_MAX. +

+
+
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. +

+

This can be useful when channel logos distort the video area. 0 +indicates ’never reset’, and returns the largest area encountered during +playback. +

+
+
mv_threshold
+

Set motion in pixel units as threshold for motion detection. It defaults to 8. +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 5/255, and default value for high +is 15/255. +

+
+ + +

39.48.1 Examples

+ +
    +
  • Find video area surrounded by black borders: +
    +
    ffmpeg -i file.mp4 -vf cropdetect,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, generate motion vectors beforehand: +
    +
    ffmpeg -i file.mp4 -vf mestimate,cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, use motion vectors from decoder: +
    +
    ffmpeg -flags2 +export_mvs -i file.mp4 -vf cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    +
+ + +

39.48.2 Commands

+ +

This filter supports the following commands: +

+
+
limit
+

The command accepts the same syntax of the corresponding option. +If the specified expression is not valid, it is kept at its current value. +

+
+ + +

39.49 cue

+ +

Delay video filtering until a given wallclock timestamp. The filter first +passes on preroll amount of frames, then it buffers at most +buffer amount of frames and waits for the cue. After reaching the cue +it forwards the buffered frames and also any subsequent frames coming in its +input. +

+

The filter can be used synchronize the output of multiple ffmpeg processes for +realtime output devices like decklink. By putting the delay in the filtering +chain and pre-buffering frames the process can pass on data to output almost +immediately after the target wallclock timestamp is reached. +

+

Perfect frame accuracy cannot be guaranteed, but the result is good enough for +some use cases. +

+
+
cue
+

The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. +

+
+
preroll
+

The duration of content to pass on as preroll expressed in seconds. Default is 0. +

+
+
buffer
+

The maximum duration of content to buffer before waiting for the cue expressed +in seconds. Default is 0. +

+
+
+ + +

39.50 curves

+ +

Apply color adjustments using curves. +

+

This filter is similar to the Adobe Photoshop and GIMP curves tools. Each +component (red, green and blue) has its values defined by N key points +tied from each other using a smooth curve. The x-axis represents the pixel +values from the input frame, and the y-axis the new pixel values to be set for +the output frame. +

+

By default, a component curve is defined by the two points (0;0) and +(1;1). This creates a straight line where each original pixel value is +"adjusted" to its own value, which means no change to the image. +

+

The filter allows you to redefine these two points and add some more. A new +curve will be defined to pass smoothly through all these new coordinates. The +new defined points need to be strictly increasing over the x-axis, and their +x and y values must be in the [0;1] interval. The curve is +formed by using a natural or monotonic cubic spline interpolation, depending +on the interp option (default: natural). The natural +spline produces a smoother curve in general while the monotonic (pchip) +spline guarantees the transitions between the specified points to be +monotonic. If the computed curves happened to go outside the vector spaces, +the values will be clipped accordingly. +

+

The filter accepts the following options: +

+
+
preset
+

Select one of the available color presets. This option can be used in addition +to the r, g, b parameters; in this case, the later +options takes priority on the preset values. +Available presets are: +

+
‘none’
+
‘color_negative’
+
‘cross_process’
+
‘darker’
+
‘increase_contrast’
+
‘lighter’
+
‘linear_contrast’
+
‘medium_contrast’
+
‘negative’
+
‘strong_contrast’
+
‘vintage’
+
+

Default is none. +

+
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 +r, g, b or all since it acts like a +post-processing LUT. +

+
red, r
+

Set the key points for the red component. +

+
green, g
+

Set the key points for the green component. +

+
blue, b
+

Set the key points for the blue component. +

+
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 +all setting. +

+
psfile
+

Specify a Photoshop curves file (.acv) to import the settings from. +

+
plot
+

Save Gnuplot script of the curves in specified file. +

+
interp
+

Specify the kind of interpolation. Available algorithms are: +

+
‘natural’
+

Natural cubic spline using a piece-wise cubic polynomial that is twice continuously differentiable. +

+
‘pchip’
+

Monotonic cubic spline using a piecewise cubic Hermite interpolating polynomial (PCHIP). +

+
+ +
+
+ +

To avoid some filtergraph syntax conflicts, each key points list need to be +defined using the following syntax: x0/y0 x1/y1 x2/y2 .... +

+ +

39.50.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.50.2 Examples

+ +
    +
  • Increase slightly the middle level of blue: +
    +
    curves=blue='0/0 0.5/0.58 1/1'
    +
    + +
  • Vintage effect: +
    +
    curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'
    +
    +

    Here we obtain the following coordinates for each components: +

    +
    red
    +

    (0;0.11) (0.42;0.51) (1;0.95) +

    +
    green
    +

    (0;0) (0.50;0.48) (1;1) +

    +
    blue
    +

    (0;0.22) (0.49;0.44) (1;0.80) +

    +
    + +
  • The previous example can also be achieved with the associated built-in preset: +
    +
    curves=preset=vintage
    +
    + +
  • Or simply: +
    +
    curves=vintage
    +
    + +
  • Use a Photoshop preset and redefine the points of the green component: +
    +
    curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
    +
    + +
  • Check out the curves of the cross_process profile using ffmpeg +and gnuplot: +
    +
    ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
    +gnuplot -p /tmp/curves.plt
    +
    +
+ + +

39.51 datascope

+ +

Video data analysis filter. +

+

This filter shows hexadecimal pixel values of part of video. +

+

The filter accepts the following options: +

+
+
size, s
+

Set output video size. +

+
+
x
+

Set x offset from where to pick pixels. +

+
+
y
+

Set y offset from where to pick pixels. +

+
+
mode
+

Set scope mode, can be one of the following: +

+
‘mono’
+

Draw hexadecimal pixel values with white color on black background. +

+
+
‘color’
+

Draw hexadecimal pixel values with input video pixel color on black +background. +

+
+
‘color2’
+

Draw hexadecimal pixel values on color background picked from input video, +the text color is picked in such way so its always visible. +

+
+ +
+
axis
+

Draw rows and columns numbers on left and top of video. +

+
+
opacity
+

Set background opacity. +

+
+
format
+

Set display number format. Can be hex, or dec. Default is hex. +

+
+
components
+

Set pixel components to display. By default all pixel components are displayed. +

+
+ + +

39.51.1 Commands

+ +

This filter supports same commands as options excluding size option. +

+ +

39.52 dblur

+

Apply Directional blur filter. +

+

The filter accepts the following options: +

+
+
angle
+

Set angle of directional blur. Default is 45. +

+
+
radius
+

Set radius of directional blur. Default is 5. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+ + +

39.52.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.53 dctdnoiz

+ +

Denoise frames using 2D DCT (frequency domain filtering). +

+

This filter is not designed for real time. +

+

The filter accepts the following options: +

+
+
sigma, s
+

Set the noise sigma constant. +

+

This sigma defines a hard threshold of 3 * sigma; every DCT +coefficient (absolute value) below this threshold with be dropped. +

+

If you need a more advanced filtering, see expr. +

+

Default is 0. +

+
+
overlap
+

Set number overlapping pixels for each block. 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 permit processing the whole input width or +height, a warning will be displayed and according borders won’t be denoised. +

+

Default value is blocksize-1, which is the best possible setting. +

+
+
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 sigma option will be ignored. +

+

The absolute value of the coefficient can be accessed through the c +variable. +

+
+
n
+

Set the blocksize using the number of bits. 1<<n defines the +blocksize, which is the width and height of the processed blocks. +

+

The default value is 3 (8x8) and can be raised to 4 for a +blocksize of 16x16. Note that changing this setting has huge consequences +on the speed processing. Also, a larger block size does not necessarily means a +better de-noising. +

+
+ + +

39.53.1 Examples

+ +

Apply a denoise with a sigma of 4.5: +

+
dctdnoiz=4.5
+
+ +

The same operation can be achieved using the expression system: +

+
dctdnoiz=e='gte(c, 4.5*3)'
+
+ +

Violent denoise using a block size of 16x16: +

+
dctdnoiz=15:n=4
+
+ + +

39.54 deband

+ +

Remove banding artifacts from input video. +It works by replacing banded pixels with average value of referenced pixels. +

+

The filter accepts the following options: +

+
+
1thr
+
2thr
+
3thr
+
4thr
+

Set banding detection threshold for each plane. Default is 0.02. +Valid range is 0.00003 to 0.5. +If difference between current pixel and reference pixel is less than threshold, +it will be considered as banded. +

+
+
range, r
+

Banding detection range in pixels. Default is 16. If positive, random number +in range 0 to set value will be used. If negative, exact absolute value +will be used. +The range defines square of four pixels around current pixel. +

+
+
direction, d
+

Set direction in radians from which four pixel will be compared. If positive, +random direction from 0 to set direction will be picked. If negative, exact of +absolute value will be picked. For example direction 0, -PI or -2*PI radians +will pick only pixels on same row and -PI/2 will pick only pixels on same +column. +

+
+
blur, b
+

If enabled, current pixel is compared with average value of all four +surrounding pixels. The default is enabled. If disabled current pixel is +compared with all four surrounding pixels. The pixel is considered banded +if only all four differences with surrounding pixels are less than threshold. +

+
+
coupling, c
+

If enabled, current pixel is changed if and only if all pixel components are banded, +e.g. banding detection threshold is triggered for all color components. +The default is disabled. +

+
+ + +

39.54.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.55 deblock

+ +

Remove blocking artifacts from input video. +

+

The filter accepts the following options: +

+
+
filter
+

Set filter type, can be weak or strong. Default is strong. +This controls what kind of deblocking is applied. +

+
+
block
+

Set size of block, allowed range is from 4 to 512. Default is 8. +

+
+
alpha
+
beta
+
gamma
+
delta
+

Set blocking detection thresholds. Allowed range is 0 to 1. +Defaults are: 0.098 for alpha and 0.05 for the rest. +Using higher threshold gives more deblocking strength. +Setting alpha controls threshold detection at exact edge of block. +Remaining options controls threshold detection near the edge. Each one for +below/above or left/right. Setting any of those to 0 disables +deblocking. +

+
+
planes
+

Set planes to filter. Default is to filter all available planes. +

+
+ + +

39.55.1 Examples

+ +
    +
  • Deblock using weak filter and block size of 4 pixels. +
    +
    deblock=filter=weak:block=4
    +
    + +
  • Deblock using strong filter, block size of 4 pixels and custom thresholds for +deblocking more edges. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
    +
    + +
  • Similar as above, but filter only first plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
    +
    + +
  • Similar as above, but filter only second and third plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
    +
    +
+ + +

39.55.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.56 decimate

+ +

Drop duplicated frames at regular intervals. +

+

The filter accepts the following options: +

+
+
cycle
+

Set the number of frames from which one will be dropped. Setting this to +N means one frame in every batch of N frames will be dropped. +Default is 5. +

+
+
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 1.1 +

+
+
scthresh
+

Set scene change threshold. Default is 15. +

+
+
blockx
+
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 32. +

+
+
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 +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 +0. +

+
+
chroma
+

Set whether or not chroma is considered in the metric calculations. Default is +1. +

+
+
mixed
+

Set whether or not the input only partially contains content to be decimated. +Default is false. +If enabled video output stream will be in variable frame rate. +

+
+ + +

39.57 deconvolve

+ +

Apply 2D deconvolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+
noise
+

Set noise when doing divisions. Default is 0.0000001. Useful when width +and height are not same and not power of 2 or if stream prior to convolving +had noise. +

+
+ +

The deconvolve filter also supports the framesync options. +

+ +

39.58 dedot

+ +

Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video. +

+

It accepts the following options: +

+
+
m
+

Set mode of operation. Can be combination of dotcrawl for cross-luminance reduction and/or +rainbows for cross-color reduction. +

+
+
lt
+

Set spatial luma threshold. Lower values increases reduction of cross-luminance. +

+
+
tl
+

Set tolerance for temporal luma. Higher values increases reduction of cross-luminance. +

+
+
tc
+

Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color. +

+
+
ct
+

Set temporal chroma threshold. Lower values increases reduction of cross-color. +

+
+ + +

39.59 deflate

+ +

Apply deflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values lower than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

39.59.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.60 deflicker

+ +

Remove temporal frame luminance variations. +

+

It accepts the following options: +

+
+
size, s
+

Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. +

+
+
mode, m
+

Set averaging mode to smooth temporal luminance variations. +

+

Available values are: +

+
‘am’
+

Arithmetic mean +

+
+
‘gm’
+

Geometric mean +

+
+
‘hm’
+

Harmonic mean +

+
+
‘qm’
+

Quadratic mean +

+
+
‘cm’
+

Cubic mean +

+
+
‘pm’
+

Power mean +

+
+
‘median’
+

Median +

+
+ +
+
bypass
+

Do not actually modify frame. Useful when one only wants metadata. +

+
+ + +

39.61 deinterlace_d3d12

+ +

Deinterlace the input video using D3D12 hardware-accelerated video processing. +

+

This filter uses the DirectX 12 Video Processor to perform deinterlacing on +GPU, supporting both simple bob and driver-defined advanced (motion-adaptive) +algorithms. It requires the input to be in d3d12 hardware pixel format. +

+

The filter automatically queries the hardware for the required number of +temporal reference frames (if needed) and manages a frame queue to supply them. +

+

It accepts the following options: +

+
+
method
+

The deinterlacing method. It accepts one of the following values: +

+
+
‘default’
+

Select the best deinterlacing method available on the hardware. +If the driver supports custom, that method is used; otherwise +falls back to bob. This is the default. +

+
+
‘bob’
+

Bob deinterlacing. Each field is independently scaled to full +frame height. Simple and fast, but may produce visible bob artifacts +on moving content. +

+
+
‘custom’
+

Driver-defined advanced deinterlacing. The exact algorithm is +hardware-specific and typically employs motion-adaptive techniques +with temporal reference frames for higher quality. +

+
+ +

The default value is default. +

+
+
mode
+

Specify the interlacing mode. It accepts one of the following values: +

+
+
‘frame’
+

Send one frame for each frame. The output frame rate equals the input +frame rate. This is the default. +

+
+
‘field’
+

Send one frame for each field. The output frame rate is double the +input frame rate. +

+
+ +

The default value is frame. +

+
+
deint
+

Specify which frames to deinterlace. It accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames. This is the default. +

+
+
‘interlaced’
+

Only deinterlace frames marked as interlaced; progressive frames are +passed through unchanged. +

+
+ +

The default value is all. +

+
+ + +

39.61.1 Examples

+ +
    +
  • Deinterlace an interlaced video using software decoding and the best +available hardware deinterlacing method: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=method=default,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
  • Deinterlace at field rate (double the frame rate) using bob method with +hardware decoding (full d3d12 pipeline): +
    +
    ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.ts \
    +       -vf "deinterlace_d3d12=method=bob:mode=field" \
    +       -c:v h264_d3d12va output.mp4
    +
    + +
  • Deinterlace only interlaced frames, passing progressive frames through: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=deint=interlaced,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
+ + +

39.62 dejudder

+ +

Remove judder produced by partially interlaced telecined content. +

+

Judder can be introduced, for instance, by pullup filter. If the original +source was partially telecined content then the output of pullup,dejudder +will have a variable frame rate. May change the recorded frame rate of the +container. Aside from that change, this filter will not affect constant frame +rate video. +

+

The option available in this filter is: +

+
cycle
+

Specify the length of the window over which the judder repeats. +

+

Accepts any integer greater than 1. Useful values are: +

+
‘4’
+

If the original was telecined from 24 to 30 fps (Film to NTSC). +

+
+
‘5’
+

If the original was telecined from 25 to 30 fps (PAL to NTSC). +

+
+
‘20’
+

If a mixture of the two. +

+
+ +

The default is ‘4’. +

+
+ + +

39.63 delogo

+ +

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). +

+

It accepts the following parameters: +

+
x
+
y
+

Specify the top left corner coordinates of the logo. They must be +specified. +

+
+
w
+
h
+

Specify the width and height of the logo to clear. They must be +specified. +

+
+
show
+

When set to 1, a green rectangle is drawn on the screen to simplify +finding the right x, y, w, and 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. +

+
+
+ + +

39.63.1 Examples

+ +
    +
  • Set a rectangle covering the area with top left corner coordinates 0,0 +and size 100x77: +
    +
    delogo=x=0:y=0:w=100:h=77
    +
    + +
+ + +

39.64 derain

+ +

Remove the rain in the input image/video by applying the derain methods based on +convolutional neural networks. Supported models: +

+ + +

Training as well as model generation scripts are provided in +the repository at https://github.com/XueweiMeng/derain_filter.git. +

+

The filter accepts the following options: +

+
+
filter_type
+

Specify which filter to use. This option accepts the following values: +

+
+
‘derain’
+

Derain filter. To conduct derain filter, you need to use a derain model. +

+
+
‘dehaze’
+

Dehaze filter. To conduct dehaze filter, you need to use a dehaze model. +

+
+

Default value is ‘derain’. +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow can load files for only its format. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

39.65 deshake

+ +

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 the following options: +

+
+
x
+
y
+
w
+
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 +rectangular area of the frame defined by its top left corner, width +and height. These parameters have the same meaning as the drawbox +filter which can be used to visualise the position of the bounding +box. +

+

This is useful when simultaneous movement of subjects within the frame +might be confused for camera motion by the motion vector search. +

+

If any or all of x, y, w and h are set to -1 +then the full frame is used. This allows later options to be set +without specifying the bounding box for the motion vector search. +

+

Default - search the whole frame. +

+
+
rx
+
ry
+

Specify the maximum extent of movement in x and y directions in the +range 0-64 pixels. Default 16. +

+
+
edge
+

Specify how to generate pixels to fill blanks at the edge of the +frame. Available values are: +

+
‘blank, 0’
+

Fill zeroes at blank locations +

+
‘original, 1’
+

Original image at blank locations +

+
‘clamp, 2’
+

Extruded edge value at blank locations +

+
‘mirror, 3’
+

Mirrored edge at blank locations +

+
+

Default value is ‘mirror’. +

+
+
blocksize
+

Specify the blocksize to use for motion search. Range 4-128 pixels, +default 8. +

+
+
contrast
+

Specify the contrast threshold for blocks. Only blocks with more than +the specified contrast (difference between darkest and lightest +pixels) will be considered. Range 1-255, default 125. +

+
+
search
+

Specify the search strategy. Available values are: +

+
‘exhaustive, 0’
+

Set exhaustive search +

+
‘less, 1’
+

Set less exhaustive search. +

+
+

Default value is ‘exhaustive’. +

+
+
filename
+

If set then a detailed log of the motion search is written to the +specified file. +

+
+
+ + +

39.66 despill

+ +

Remove unwanted contamination of foreground colors, caused by reflected color of +greenscreen or bluescreen. +

+

This filter accepts the following options: +

+
+
type
+

Set what type of despill to use. +

+
+
mix
+

Set how spillmap will be generated. +

+
+
expand
+

Set how much to get rid of still remaining spill. +

+
+
red
+

Controls amount of red in spill area. +

+
+
green
+

Controls amount of green in spill area. +Should be -1 for greenscreen. +

+
+
blue
+

Controls amount of blue in spill area. +Should be -1 for bluescreen. +

+
+
brightness
+

Controls brightness of spill area, preserving colors. +

+
+
alpha
+

Modify alpha from generated spillmap. +

+
+ + +

39.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.67 detelecine

+ +

Apply an exact inverse of the telecine operation. It requires a predefined +pattern specified using the pattern option which must be the same as that passed +to the telecine filter. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+
start_frame
+

A number representing position of the first frame with respect to the telecine +pattern. This is to be used if the stream is cut. The default value is 0. +

+
+ + +

39.68 dilation

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

39.68.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.69 displace

+ +

Displace pixels as indicated by second and third input stream. +

+

It takes three input streams and outputs one stream, the first input is the +source, and second and third input are displacement maps. +

+

The second input specifies how much to displace pixels along the +x-axis, while the third input specifies how much to displace pixels +along the y-axis. +If one of displacement map streams terminates, last frame from that +displacement map will be used. +

+

Note that once generated, displacements maps can be reused over and over again. +

+

A description of the accepted options follows. +

+
+
edge
+

Set displace behavior for pixels that are out of range. +

+

Available values are: +

+
‘blank’
+

Missing pixels are replaced by black pixels. +

+
+
‘smear’
+

Adjacent pixels will spread out to replace missing pixels. +

+
+
‘wrap’
+

Out of range pixels are wrapped so they point to pixels of other side. +

+
+
‘mirror’
+

Out of range pixels will be replaced with mirrored pixels. +

+
+

Default is ‘smear’. +

+
+
+ + +

39.69.1 Examples

+ +
    +
  • Add ripple effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT
    +
    + +
  • Add wave effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT
    +
    +
+ + +

39.70 dnn_classify

+ +

Do classification with deep neural networks based on bounding boxes. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0, +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs for your system. +

+
+
+ + +

39.71 dnn_detect

+ +

Do object detection with deep neural networks. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0 (usually it is ’background’), +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+
+
+ + +

39.72 dnn_processing

+ +

Do image processing with deep neural networks. It works together with another filter +which converts the pixel format of the Frame to what the dnn network requires. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+
‘openvino’
+

OpenVINO backend. To enable this backend you +need to build and install the OpenVINO for C library (see +https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md) and configure FFmpeg with +--enable-libopenvino (–extra-cflags=-I... –extra-ldflags=-L... might +be needed if the header files and libraries are not installed into system path) +

+
+
‘torch’
+

Libtorch backend. To enable this backend you need to build and install Libtroch +for C++ library. Please download cxx11 ABI version (see +https://pytorch.org/get-started/locally) +and configure FFmpeg with --enable-libtorch +--extra-cflags=-I/libtorch_root/libtorch/include +--extra-cflags=-I/libtorch_root/libtorch/include/torch/csrc/api/include +--extra-ldflags=-L/libtorch_root/libtorch/lib/ +

+
+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO +and Libtorch backend can load files for only its format. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +

+
+
+ + +

39.72.1 Examples

+ +
    +
  • Remove rain in rgb24 frame with can.pb (see derain filter): +
    +
    ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
    +
    + +
  • Handle the Y channel with srcnn.pb (see sr filter) for frame with yuv420p (planar YUV formats supported): +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
    +
    + +
  • Handle the Y channel with espcn.pb (see sr filter), which changes frame size, for format yuv420p (planar YUV formats supported), +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y:backend_configs=sess_config=0x10022805320e09cdccccccccccec3f20012a01303801 -y tmp.espcn.jpg
    +
    + +
+ + +

39.73 drawbox

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

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 invert is used, the box edge color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With value 1, the pixels of the painted box +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
box_source
+

Box source can be set as side_data_detection_bboxes if you want to use box data in +detection bboxes of side data. +

+

If box_source is set, the x, y, width and height will be ignored and +still use box data in detection bboxes of side data. So please do not use this parameter if you were +not sure about the box source. +

+
+
t
+

The thickness of the drawn box. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

39.73.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + +

39.73.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.74 drawgraph

+

Draw a graph using input video metadata. +

+

It accepts the following parameters: +

+
+
m1
+

Set 1st frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg1
+

Set 1st foreground color expression. +

+
+
m2
+

Set 2nd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg2
+

Set 2nd foreground color expression. +

+
+
m3
+

Set 3rd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg3
+

Set 3rd foreground color expression. +

+
+
m4
+

Set 4th frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg4
+

Set 4th foreground color expression. +

+
+
min
+

Set minimal value of metadata value. +

+
+
max
+

Set maximal value of metadata value. +

+
+
bg
+

Set graph background color. Default is white. +

+
+
mode
+

Set graph mode. +

+

Available values for mode is: +

+
‘bar’
+
‘dot’
+
‘line’
+
+ +

Default is line. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is frame. +

+
+
size
+

Set size of graph video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +The default value is 900x256. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+

The foreground color expressions can use the following variables: +

+
MIN
+

Minimal value of metadata value. +

+
+
MAX
+

Maximal value of metadata value. +

+
+
VAL
+

Current metadata key value. +

+
+ +

The color is defined as 0xAABBGGRR. +

+
+ +

Example using metadata from signalstats filter: +

+
signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
+
+ +

Example using metadata from ebur128 filter: +

+
ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
+
+ + +

39.75 drawgrid

+ +

Draw a grid on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. +

+
+
width, w
+
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 thickness, so image gets +framed. Default to 0. +

+
+
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 invert is used, the grid color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the grid line. Default value is 1. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With 1 the pixels of the painted grid +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the grid onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input grid cell width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y coordinates of some point of grid intersection (meant to configure offset). +

+
+
w
+
h
+

The width and height of the drawn cell. +

+
+
t
+

The thickness of the drawn cell. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

39.75.1 Examples

+ +
    +
  • Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: +
    +
    drawgrid=width=100:height=100:thickness=2:color=red@0.5
    +
    + +
  • Draw a white 3x3 grid with an opacity of 50%: +
    +
    drawgrid=w=iw/3:h=ih/3:t=2:c=white@0.5
    +
    +
+ + +

39.75.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.76 drawtext

+ +

Draw a text string or text from a specified file on top of a video, using the +libfreetype library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-libfreetype and --enable-libharfbuzz. +To enable default font fallback and the font option you need to +configure FFmpeg with --enable-libfontconfig. +To enable the text_shaping option, you need to configure FFmpeg with +--enable-libfribidi. +

+ +

39.76.1 Syntax

+ +

It accepts the following parameters: +

+
+
box
+

Used to draw a box around text using the background color. +The value must be either 1 (enable) or 0 (disable). +The default value of box is 0. +

+
+
boxborderw
+

Set the width of the border to be drawn around the box using boxcolor. +The value must be specified using one of the following formats: +

    +
  • boxborderw=10 set the width of all the borders to 10 +
  • boxborderw=10|20 set the width of the top and bottom borders to 10 + and the width of the left and right borders to 20 +
  • boxborderw=10|20|30 set the width of the top border to 10, the width + of the bottom border to 30 and the width of the left and right borders to 20 +
  • boxborderw=10|20|30|40 set the borders width to 10 (top), 20 (right), + 30 (bottom), 40 (left) +
+

The default value of boxborderw is "0". +

+
+
boxcolor
+

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. +

+

The default value of boxcolor is "white". +

+
+
line_spacing
+

Set the line spacing in pixels. The default value of line_spacing is 0. +

+
+
text_align
+

Set the vertical and horizontal alignment of the text with respect to the box boundaries. +The value is combination of flags, one for the vertical alignment (T=top, +M=middle, B=bottom) and one for the horizontal alignment (L=left, C=center, R=right). +Please note that tab characters are only supported with the left horizontal alignment. +

+
+
y_align
+

Specify what the y value is referred to. Possible values are: +

    +
  • text the top of the highest glyph of the first text line is placed at y +
  • baseline the baseline of the first text line is placed at y +
  • font the baseline of the first text line is placed at y plus the + ascent (in pixels) defined in the font metrics +
+

The default value of y_align is "text" for backward compatibility. +

+
+
borderw
+

Set the width of the border to be drawn around the text using bordercolor. +The default value of borderw is 0. +

+
+
bordercolor
+

Set the color to be used for drawing border around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. +

+

The default value of bordercolor is "black". +

+
+
expansion
+

Select how the text is expanded. Can be either none, +strftime (deprecated) or normal (default). See the +Text expansion section below for details. +

+
+
basetime
+

Set a start time for the count. Value is in microseconds. Only applied +in the deprecated strftime expansion mode. To emulate in normal expansion +mode use the pts function, supplying the start time (in seconds) +as the second argument. +

+
+
fix_bounds
+

If true, check and fix text coords to avoid clipping. +

+
+
fontcolor
+

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 fontcolor is "black". +

+
+
fontcolor_expr
+

String which is expanded the same way as text to obtain dynamic +fontcolor value. By default this option has empty value and is not +processed. When this option is set, it overrides fontcolor option. +

+
+
font
+

The font family to be used for drawing text. By default Sans. +

+
+
fontfile
+

The font file to be used for drawing text. The path must be included. +This parameter is mandatory if the fontconfig support is disabled. +

+
+
alpha
+

Draw the text applying alpha blending. The value can +be a number between 0.0 and 1.0. +The expression accepts the same variables x, y as well. +The default value is 1. +Please see fontcolor_expr. +

+
+
fontsize
+

The font size to be used for drawing text. +The default value of fontsize is 16. +

+
+
text_shaping
+

If set to 1, attempt to shape the text (for example, reverse the order of +right-to-left text and join Arabic characters) before drawing it. +Otherwise, just draw the text exactly as given. +By default 1 (if supported). +

+
+
ft_load_flags
+

The flags to be used for loading the fonts. +

+

The flags map the corresponding flags supported by libfreetype, and are +a combination of the following values: +

+
default
+
no_scale
+
no_hinting
+
render
+
no_bitmap
+
vertical_layout
+
force_autohint
+
crop_bitmap
+
pedantic
+
ignore_global_advance_width
+
no_recurse
+
ignore_transform
+
monochrome
+
linear_design
+
no_autohint
+
+ +

Default value is "default". +

+

For more information consult the documentation for the FT_LOAD_* +libfreetype flags. +

+
+
shadowcolor
+

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 shadowcolor is "black". +

+
+
boxw
+

Set the width of the box to be drawn around text. +The default value of boxw is computed automatically to match the text width +

+
+
boxh
+

Set the height of the box to be drawn around text. +The default value of boxh is computed automatically to match the text height +

+
+
shadowx
+
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. The default value for both is "0". +

+
+
start_number
+

The starting frame number for the n/frame_num variable. The default value +is "0". +

+
+
tabsize
+

The size in number of spaces to use for rendering the tab. +Default value is 4. +

+
+
timecode
+

Set the initial timecode representation in "hh:mm:ss[:;.]ff" +format. It can be used with or without text parameter. timecode_rate +option must be specified. +

+
+
timecode_rate, rate, r
+

Set the timecode frame rate (timecode only). Value will be rounded to nearest +integer. Minimum value is "1". +Drop-frame timecode is supported for frame rates 30 & 60. +

+
+
tc24hmax
+

If set to 1, the output of the timecode option will wrap around at 24 hours. +Default is 0 (disabled). +

+
+
text
+

The text string to be drawn. The text must be a sequence of UTF-8 +encoded characters. +This parameter is mandatory if no file is specified with the parameter +textfile. +

+
+
textfile
+

A text file containing text to be drawn. The text must be a sequence +of UTF-8 encoded characters. +

+

This parameter is mandatory if no text string is specified with the +parameter text. +

+

If both text and textfile are specified, an error is thrown. +

+
+
text_source
+

Text source should be set as side_data_detection_bboxes if you want to use text data in +detection bboxes of side data. +

+

If text source is set, text and textfile will be ignored and still use +text data in detection bboxes of side data. So please do not use this parameter +if you are not sure about the text source. +

+
+
reload
+

The textfile will be reloaded at specified frame interval. +Be sure to update textfile atomically, or it may be read partially, +or even fail. +Range is 0 to INT_MAX. Default is 0. +

+
+
x
+
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. +

+

The default value of x and y is "0". +

+

See below for the list of accepted constants and functions. +

+
+ +

The parameters for x and y are expressions containing the +following constants and functions: +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
line_h, lh
+

the height of each text line +

+
+
main_h, h, H
+

the input height +

+
+
main_w, w, W
+

the input width +

+
+
max_glyph_a, ascent
+

the maximum distance from the baseline to the highest/upper grid +coordinate used to place a glyph outline point, for all the rendered +glyphs. +It is a positive value, due to the grid’s orientation with the Y axis +upwards. +

+
+
max_glyph_d, descent
+

the maximum distance from the baseline to the lowest grid coordinate +used to place a glyph outline point, for all the rendered glyphs. +This is a negative value, due to the grid’s orientation, with the Y axis +upwards. +

+
+
max_glyph_h
+

maximum glyph height, that is the maximum height for all the glyphs +contained in the rendered text, it is equivalent to ascent - +descent. +

+
+
max_glyph_w
+

maximum glyph width, that is the maximum width for all the glyphs +contained in the rendered text +

+
+
font_a
+

the ascent size defined in the font metrics +

+
+
font_d
+

the descent size defined in the font metrics +

+
+
top_a
+

the maximum ascender of the glyphs of the first text line +

+
+
bottom_d
+

the maximum descender of the glyphs of the last text line +

+
+
n
+

the number of input frame, starting from 0 +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

The input sample aspect ratio. +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
text_h, th
+

the height of the rendered text +

+
+
text_w, tw
+

the width of the rendered text +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer +to each other, so you can for example specify y=x/dar. +

+
+
pict_type
+

A one character description of the current frame’s picture type. +

+
+
pkt_pos
+

The current packet’s position in the input file or stream +(in bytes, from the start of the input). A value of -1 indicates +this info is not available. +

+
+
duration
+

The current packet’s duration, in seconds. +

+
+
pkt_size
+

The current packet’s size (in bytes). +

+
+ + +

39.76.2 Text expansion

+ +

If expansion is set to strftime, the filter recognizes +sequences accepted by the strftime C function in the provided +text and expands them accordingly. Check the documentation of +strftime. This feature is deprecated in favor of normal +expansion with the gmtime or localtime expansion +functions. +

+

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
expr, e
+

The expression evaluation result. +

+

It must take one argument specifying the expression to be evaluated, +which accepts the same constants and functions as the x and +y values. Note that not all constants should be used, for +example the text size is not known when evaluating the expression, so +the constants text_w and text_h will have an undefined +value. +

+
+
expr_int_format, eif
+

Evaluate the expression’s value and output as formatted integer. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries +starting with TAG included within each frame section +printed by running ffprobe -show_frames. +

+

String metadata generated in filters leading to +the drawtext filter are also available. +

+
+
n, frame_num
+

The frame number, starting from 0. +

+
+
pict_type
+

A one character description of the current picture type. +

+
+
pts
+

The timestamp of the current frame. +It can take up to three arguments. +

+

The first argument is the format of the timestamp; it defaults to flt +for seconds as a decimal number with microsecond accuracy; hms stands +for a formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as +local time zone time. +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to hms, a third argument 24HH may be +supplied to present the hour part of the formatted timestamp in 24h format +(00-23). +

+

If the format is set to localtime or gmtime, a third +argument may be supplied: a strftime C function format string. +By default, YYYY-MM-DD HH:MM:SS format will be used. +

+
+ + +

39.76.3 Commands

+ +

This filter supports altering parameters via commands: +

+
reinit
+

Alter existing filter parameters. +

+

Syntax for the argument is the same as for filter invocation, e.g. +

+
+
fontsize=56:fontcolor=green:text='Hello World'
+
+ +

Full filter invocation with sendcmd would look like this: +

+
+
sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
+
+ +

If the entire argument can’t be parsed or applied as valid values then the filter will +continue with its existing parameters. +

+
+
+ +

The following options are also supported as commands: +

+
    +
  • x +
  • y +
  • alpha +
  • fontsize +
  • fontcolor +
  • boxcolor +
  • bordercolor +
  • shadowcolor +
  • box +
  • boxw +
  • boxh +
  • boxborderw +
  • line_spacing +
  • text_align +
  • shadowx +
  • shadowy +
  • borderw +
+ + +

39.76.4 Examples

+ +
    +
  • Draw "Test Text" with font FreeSerif, using the default values for the +optional parameters. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
    +
    + +
  • Draw ’Test Text’ with font FreeSerif of size 24 at position x=100 +and y=50 (counting from the top-left corner of the screen), text is +yellow with a red box around it. Both the text and the box have an +opacity of 20%. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
    +          x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"
    +
    + +

    Note that the double quotes are not necessary if spaces are not used +within the parameter list. +

    +
  • Show the text at the center of the video frame: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
    +
    + +
  • Show the text at a random position, switching to a new position every 30 seconds: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"
    +
    + +
  • Show a text line sliding from right to left in the last row of the video +frame. The file LONG_LINE is assumed to contain a single line +with no newlines. +
    +
    drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
    +
    + +
  • Show the content of file CREDITS off the bottom of the frame and scroll up. +
    +
    drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
    +
    + +
  • Draw a single green letter "g", at the center of the input video. +The glyph baseline is placed at half screen height. +
    +
    drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
    +
    + +
  • Show text for 1 second every 3 seconds: +
    +
    drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
    +
    + +
  • Use fontconfig to set the font. Note that the colons need to be escaped. +
    +
    drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg'
    +
    + +
  • Draw "Test Text" with font size dependent on height of the video. +
    +
    drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
    +
    + +
  • Print the date of a real-time encoding (see documentation for the +strftime C function): +
    +
    drawtext='fontfile=FreeSans.ttf:text=%{localtime\:%a %b %d %Y}'
    +
    + +
  • Show text fading in and out (appearing/disappearing): +
    +
    #!/bin/sh
    +DS=1.0 # display start
    +DE=10.0 # display end
    +FID=1.5 # fade in duration
    +FOD=5 # fade out duration
    +ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 }"
    +
    + +
  • Horizontally align multiple separate texts. Note that max_glyph_a +and the fontsize value are included in the y offset. +
    +
    drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
    +drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
    +
    + +
  • Plot special lavf.image2dec.source_basename metadata onto each frame if +such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer +must have option -export_path_metadata 1 for the special metadata fields +to be available for filters. +
    +
    drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%{metadata\:lavf.image2dec.source_basename\:NA}':x=10:y=10"
    +
    + +
+ +

For more information about libfreetype, check: +http://www.freetype.org/. +

+

For more information about fontconfig, check: +http://freedesktop.org/software/fontconfig/fontconfig-user.html. +

+

For more information about libfribidi, check: +http://fribidi.org/. +

+

For more information about libharfbuzz, check: +https://github.com/harfbuzz/harfbuzz. +

+ +

39.77 drawvg

+ +

Draw vector graphics on top of video frames, by executing a script written in +a custom language called VGS (Vector Graphics Script). +

+

The documentation for the language can be found in +drawvg - Language Reference. A version of this reference +with rendered examples can be found at the +author’s site. +

+

Graphics are rendered using the cario 2D +graphics library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-cairo. +

+ +

39.77.1 Parameters

+ +

Either script or file must be set. +

+
+
s, script
+

Script source to draw the graphics. +

+
+
file
+

Path of the file to load the script source. +

+
+
+ + +

39.77.2 Pixel Formats

+ +

Since Cairo only supports RGB images, if the input video is something else (like +YUV 4:2:0), before executing the script the video is converted to a format +compatible with Cairo. Then, you have to use either the format filter, +or the -pix_fmt option, to convert it to the expected format in the +output. +

+ +

39.77.3 Examples

+ +
    +
  • Draw the outline of an ellipse. + +
    +
    ffmpeg -i input.webm \
    +    -vf 'drawvg=ellipse (w/2) (h/2) (w/3) (h/3) stroke' \
    +    -pix_fmt yuv420p \
    +    output.webm
    +
    + +
  • +Draw a square rotating in the middle of the frame. + +

    The script for drawvg is in a file draw.vgs: +

    +
    +
    translate (w/2) (h/2)
    +rotate t
    +rect -100 -100 200 200
    +setcolor red@0.5
    +fill
    +
    + +

    Then: +

    +
    +
    ffmpeg -i input.webm -vf 'drawvg=file=draw.vgs,format=yuv420p' output.webm
    +
    + +
+ + +

39.78 edgedetect

+ +

Detect and draw edges. The filter uses the Canny Edge Detection algorithm. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
mode
+

Define the drawing mode. +

+
+
‘wires’
+

Draw white/gray wires on black background. +

+
+
‘colormix’
+

Mix the colors to create a paint/cartoon effect. +

+
+
‘canny’
+

Apply Canny edge detector on all selected planes. +

+
+

Default value is wires. +

+
+
planes
+

Select planes for filtering. By default all available planes are filtered. +

+
+ + +

39.78.1 Examples

+ +
    +
  • Standard edge detection with custom values for the hysteresis thresholding: +
    +
    edgedetect=low=0.1:high=0.4
    +
    + +
  • Painting effect without thresholding: +
    +
    edgedetect=mode=colormix:high=0
    +
    +
+ + +

39.79 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. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
pal8
+

Set pal8 output pixel format. This option does not work with codebook +length greater than 256. Default is disabled. +

+
+
use_alpha
+

Include alpha values in the quantization calculation. Allows creating +palettized output images (e.g. PNG8) with multiple alpha smooth blending. +

+
+ + +

39.80 entropy

+ +

Measure graylevel entropy in histogram of color channels of video frames. +

+

It accepts the following parameters: +

+
+
mode
+

Can be either normal or diff. Default is normal. +

+

diff mode measures entropy of histogram delta values, absolute differences +between neighbour histogram values. +

+
+ + +

39.81 epx

+

Apply the EPX magnification filter which is designed for pixel art. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xEPX, 3 for +3xEPX. +Default is 3. +

+
+ + +

39.82 eq

+

Set brightness, contrast, saturation and approximate gamma adjustment. +

+

The filter accepts the following options: +

+
+
contrast
+

Set the contrast expression. The value must be a float value in range +-1000.0 to 1000.0. The default value is "1". +

+
+
brightness
+

Set the brightness expression. The value must be a float value in +range -1.0 to 1.0. The default value is "0". +

+
+
saturation
+

Set the saturation expression. The value must be a float in +range 0.0 to 3.0. The default value is "1". +

+
+
gamma
+

Set the gamma expression. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_r
+

Set the gamma expression for red. The value must be a float in +range 0.1 to 10.0. The default value is "1". +

+
+
gamma_g
+

Set the gamma expression for green. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_b
+

Set the gamma expression for blue. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_weight
+

Set the gamma weight expression. It can be used to reduce the effect +of a high gamma value on bright image areas, e.g. keep them from +getting overamplified and just plain white. The value must be a float +in range 0.0 to 1.0. A value of 0.0 turns the +gamma correction all the way down while 1.0 leaves it at its +full strength. Default is "1". +

+
+
eval
+

Set when the expressions for brightness, contrast, saturation and +gamma expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ +

The expressions accept the following parameters: +

+
n
+

frame count of the input frame starting from 0 +

+
+
pos
+

byte position of the corresponding packet in the input file, NAN if +unspecified; deprecated, do not use +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+ + +

39.82.1 Commands

+

The filter supports the following commands: +

+
+
contrast
+

Set the contrast expression. +

+
+
brightness
+

Set the brightness expression. +

+
+
saturation
+

Set the saturation expression. +

+
+
gamma
+

Set the gamma expression. +

+
+
gamma_r
+

Set the gamma_r expression. +

+
+
gamma_g
+

Set gamma_g expression. +

+
+
gamma_b
+

Set gamma_b expression. +

+
+
gamma_weight
+

Set gamma_weight 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. +

+
+
+ + +

39.83 erosion

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

39.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.84 estdif

+ +

Deinterlace the input video ("estdif" stands for "Edge Slope +Tracing Deinterlacing Filter"). +

+

Spatial only filter that uses edge slope tracing algorithm +to interpolate missing lines. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
all
+

Deinterlace all frames. +

+
interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+
rslope
+

Specify the search radius for edge slope tracing. Default value is 1. +Allowed range is from 1 to 15. +

+
+
redge
+

Specify the search radius for best edge matching. Default value is 2. +Allowed range is from 0 to 15. +

+
+
ecost
+

Specify the edge cost for edge matching. Default value is 2. +Allowed range is from 0 to 50. +

+
+
mcost
+

Specify the middle cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
dcost
+

Specify the distance cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
interp
+

Specify the interpolation used. Default is 4-point interpolation. It accepts one +of the following values: +

+
+
2p
+

Two-point interpolation. +

+
4p
+

Four-point interpolation. +

+
6p
+

Six-point interpolation. +

+
+
+
+ + +

39.84.1 Commands

+

This filter supports same commands as options. +

+ +

39.85 exposure

+

Adjust exposure of the video stream. +

+

The filter accepts the following options: +

+
+
exposure
+

Set the exposure correction in EV. Allowed range is from -3.0 to 3.0 EV +Default value is 0 EV. +

+
+
black
+

Set the black level correction. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+ + +

39.85.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.86 extractplanes

+ +

Extract color channel components from input video stream into +separate grayscale video streams. +

+

The filter accepts the following option: +

+
+
planes
+

Set plane(s) to extract. +

+

Available values for planes are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +

Choosing planes not available in the input will result in an error. +That means you cannot select r, g, b planes +with y, u, v planes at same time. +

+
+ + +

39.86.1 Examples

+ +
    +
  • Extract luma, u and v color channel component from input video frame +into 3 grayscale outputs: +
    +
    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
    +
    +
+ + +

39.87 fade

+ +

Apply a fade-in/out effect to the input video. +

+

It accepts the following parameters: +

+
+
type, t
+

The effect type can be either "in" for a fade-in, or "out" for a fade-out +effect. +Default is in. +

+
+
start_frame, s
+

Specify the number of the frame to start applying the fade +effect at. Default is 0. +

+
+
nb_frames, n
+

The number of frames that the fade effect lasts. 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 color. +Default is 25. +

+
+
alpha
+

If set to 1, fade only alpha channel, if one exists on the input. +Default value is 0. +

+
+
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. +

+
+
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 color. +If both duration and nb_frames are specified, duration is used. Default is 0 +(nb_frames is used by default). +

+
+
color, c
+

Specify the color of the fade. Default is "black". +

+
+ + +

39.87.1 Examples

+ +
    +
  • Fade in the first 30 frames of video: +
    +
    fade=in:0:30
    +
    + +

    The command above is equivalent to: +

    +
    fade=t=in:s=0:n=30
    +
    + +
  • Fade out the last 45 frames of a 200-frame video: +
    +
    fade=out:155:45
    +fade=type=out:start_frame=155:nb_frames=45
    +
    + +
  • Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: +
    +
    fade=in:0:25, fade=out:975:25
    +
    + +
  • Make the first 5 frames yellow, then fade in from frame 5-24: +
    +
    fade=in:5:20:color=yellow
    +
    + +
  • Fade in alpha over first 25 frames of video: +
    +
    fade=in:0:25:alpha=1
    +
    + +
  • Make the first 5.5 seconds black, then fade in for 0.5 seconds: +
    +
    fade=t=in:st=5.5:d=0.5
    +
    + +
+ + +

39.88 feedback

+

Apply feedback video filter. +

+

This filter pass cropped input frames to 2nd output. +From there it can be filtered with other video filters. +After filter receives frame from 2nd input, that frame +is combined on top of original frame from 1st input and passed +to 1st output. +

+

The typical usage is filter only part of frame. +

+

The filter accepts the following options: +

+
x
+
y
+

Set the top left crop position. +

+
+
w
+
h
+

Set the crop size. +

+
+ + +

39.88.1 Examples

+ +
    +
  • Blur only top left rectangular part of video frame size 100x100 with gblur filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]gblur=8[blurin]
    +
    + +
  • Draw black box on top left part of video frame of size 100x100 with drawbox filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]drawbox=x=0:y=0:w=100:h=100:t=100[blurin]
    +
    + +
  • Pixelize rectangular part of video frame of size 100x100 with pixelize filter. +
    +
    [in][blurin]feedback=x=320:y=240:w=100:h=100[out][blurout];[blurout]pixelize[blurin]
    +
    +
+ + +

39.89 fftdnoiz

+

Denoise frames using 3D FFT (frequency domain filtering). +

+

The filter accepts the following options: +

+
+
sigma
+

Set the noise sigma constant. This sets denoising strength. +Default value is 1. Allowed range is from 0 to 30. +Using very high sigma with low overlap may give blocking artifacts. +

+
+
amount
+

Set amount of denoising. By default all detected noise is reduced. +Default value is 1. Allowed range is from 0 to 1. +

+
+
block
+

Set size of block in pixels, Default is 32, can be 8 to 256. +

+
+
overlap
+

Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. +

+
+
method
+

Set denoising method. Default is wiener, can also be hard. +

+
+
prev
+

Set number of previous frames to use for denoising. By default is set to 0. +

+
+
next
+

Set number of next frames to to use for denoising. By default is set to 0. +

+
+
planes
+

Set planes which will be filtered, by default are all available filtered +except alpha. +

+
+ + +

39.90 fftfilt

+

Apply arbitrary expressions to samples in frequency domain +

+
+
dc_Y
+

Adjust the dc value (gain) of the luma plane of the image. The filter +accepts an integer value in range 0 to 1000. The default +value is set to 0. +

+
+
dc_U
+

Adjust the dc value (gain) of the 1st chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
dc_V
+

Adjust the dc value (gain) of the 2nd chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
weight_Y
+

Set the frequency domain weight expression for the luma plane. +

+
+
weight_U
+

Set the frequency domain weight expression for the 1st chroma plane. +

+
+
weight_V
+

Set the frequency domain weight expression for the 2nd chroma plane. +

+
+
eval
+

Set when the expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

Only evaluate expressions once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+ +

Default value is ‘init’. +

+

The filter accepts the following variables: +

+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
N
+

The number of input frame, starting from 0. +

+
+
WS
+
HS
+

The size of FFT array for horizontal and vertical processing. +

+
+ + +

39.90.1 Examples

+ +
    +
  • High-pass: +
    +
    fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
    +
    + +
  • Low-pass: +
    +
    fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
    +
    + +
  • Sharpen: +
    +
    fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
    +
    + +
  • Blur: +
    +
    fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
    +
    + +
+ + +

39.91 field

+ +

Extract a single field from an interlaced image using stride +arithmetic to avoid wasting CPU time. The output frames are marked as +non-interlaced. +

+

The filter accepts the following options: +

+
+
type
+

Specify whether to extract the top (if the value is 0 or +top) or the bottom field (if the value is 1 or +bottom). +

+
+ + +

39.92 fieldhint

+ +

Create new frames by copying the top and bottom fields from surrounding frames +supplied as numbers by the hint file. +

+
+
hint
+

Set file containing hints: absolute/relative frame numbers. +

+

There must be one line for each frame in a clip. Each line must contain two +numbers separated by the comma, optionally followed by - or +. +Numbers supplied on each line of file can not be out of [N-1,N+1] where N +is current frame number for absolute mode or out of [-1, 1] range +for relative mode. First number tells from which frame to pick up top +field and second number tells from which frame to pick up bottom field. +

+

If optionally followed by + output frame will be marked as interlaced, +else if followed by - output frame will be marked as progressive, else +it will be marked same as input frame. +If optionally followed by t output frame will use only top field, or in +case of b it will use only bottom field. +If line starts with # or ; that line is skipped. +

+
+
mode
+

Can be item absolute or relative or pattern. Default is absolute. +The pattern mode is same as relative mode, except at last entry of file if there +are more frames to process than hint file is seek back to start. +

+
+ +

Example of first several lines of hint file for relative mode: +

+
0,0 - # first frame
+1,0 - # second frame, use third's frame top field and second's frame bottom field
+1,0 - # third frame, use fourth's frame top field and third's frame bottom field
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+
+ + +

39.93 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 fieldmatch needs to be +followed by a decimation filter such as 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, +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 yadif before decimation. +

+

In addition to the various configuration options, fieldmatch can take an +optional second stream, activated through the 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 fieldmatch is based on. While the semantic and usage are very +close, some behaviour and options names can differ. +

+

The decimate filter currently only works for constant frame rate input. +If your input has mixed telecined (30fps) and progressive content with a lower +framerate like 24fps use the following filterchain to produce the necessary cfr +stream: dejudder,fps=30000/1001,fieldmatch,decimate. +

+

The filter accepts the following options: +

+
+
order
+

Specify the assumed field order of the input stream. Available values are: +

+
+
‘auto’
+

Auto detect parity (use FFmpeg’s internal parity value). +

+
‘bff’
+

Assume bottom field first. +

+
‘tff’
+

Assume top field first. +

+
+ +

Note that it is sometimes recommended not to trust the parity announced by the +stream. +

+

Default value is auto. +

+
+
mode
+

Set the matching mode or strategy to use. 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, 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 pc and 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 p/c/n/u/b meaning section. +

+

Available values are: +

+
+
‘pc’
+

2-way matching (p/c) +

+
‘pc_n’
+

2-way matching, and trying 3rd match if still combed (p/c + n) +

+
‘pc_u’
+

2-way matching, and trying 3rd match (same order) if still combed (p/c + u) +

+
‘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) +

+
‘pcn’
+

3-way matching (p/c/n) +

+
‘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) +

+
+ +

The parenthesis at the end indicate the matches that would be used for that +mode assuming order=tff (and field on auto or +top). +

+

In terms of speed pc mode is by far the fastest and pcn_ub is +the slowest. +

+

Default value is pc_n. +

+
+
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 clip2 feature from +VFM/TFM. +

+

Default value is 0 (disabled). +

+
+
field
+

Set the field to match from. It is recommended to set this to the same value as +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: +

+
+
‘auto’
+

Automatic (same value as order). +

+
‘bottom’
+

Match from the bottom field. +

+
‘top’
+

Match from the top field. +

+
+ +

Default value is auto. +

+
+
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 0 +only if your clip has bad chroma problems such as heavy rainbowing or other +artifacts. Setting this to 0 could also be used to speed things up at +the cost of some accuracy. +

+

Default value is 1. +

+
+
y0
+
y1
+

These define an exclusion band which excludes the lines between y0 and +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. y0 sets the starting scan line and +y1 sets the ending line; all lines in between y0 and +y1 (including y0 and y1) will be ignored. Setting +y0 and y1 to the same value will disable the feature. +y0 and y1 defaults to 0. +

+
+
scthresh
+

Set the scene change detection threshold as a percentage of maximum change on +the luma plane. Good values are in the [8.0, 14.0] range. Scene change +detection is only relevant in case combmatch=sc. The range for +scthresh is [0.0, 100.0]. +

+

Default value is 12.0. +

+
+
combmatch
+

When combatch is not none, fieldmatch will take into +account the combed scores of matches when deciding what match to use as the +final match. Available values are: +

+
+
‘none’
+

No final matching based on combed scores. +

+
‘sc’
+

Combed scores are only used when a scene change is detected. +

+
‘full’
+

Use combed scores all the time. +

+
+ +

Default is sc. +

+
+
combdbg
+

Force fieldmatch to calculate the combed metrics for certain matches and +print them. This setting is known as micout in TFM/VFM vocabulary. +Available values are: +

+
+
‘none’
+

No forced calculation. +

+
‘pcn’
+

Force p/c/n calculations. +

+
‘pcnub’
+

Force p/c/n/u/b calculations. +

+
+ +

Default value is none. +

+
+
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 +-1 (every pixel will be detected as combed) to 255 (no pixel will +be detected as combed). This is basically a pixel difference value. A good +range is [8, 12]. +

+

Default value is 9. +

+
+
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 chroma=0 is usually more reliable, except for the case +where there is chroma only combing in the source. +

+

Default value is 0. +

+
+
blockx
+
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 +combpel pixels are required to be detected as combed for a frame to be +declared combed. See the 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 16. +

+
+
combpel
+

The number of combed pixels inside any of the blocky by +blockx size blocks on the frame for the frame to be detected as +combed. While 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 blockx and blocky settings) on the +frame. Minimum value is 0 and maximum is blocky x blockx (at +which point no frames will ever be detected as combed). This setting is known +as MI in TFM/VFM vocabulary. +

+

Default value is 80. +

+
+ + +

39.93.1 p/c/n/u/b meaning

+ + +

39.93.1.1 p/c/n

+ +

We assume the following telecined stream: +

+
+
Top fields:     1 2 2 3 4
+Bottom fields:  1 2 3 4 4
+
+ +

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 fieldmatch is configured to run a matching from bottom +(field=bottom) this is how this input stream get transformed: +

+
+
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
+
+ +

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 decimate filter. +

+

The same operation now matching from top fields (field=top) +looks like this: +

+
+
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
+
+ +

In these examples, we can see what p, c and n mean; +basically, they refer to the frame and field of the opposite parity: +

+
    +
  • p matches the field of the opposite parity in the previous frame +
  • c matches the field of the opposite parity in the current frame +
  • n matches the field of the opposite parity in the next frame +
+ + +

39.93.1.2 u/b

+ +

The u and 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 (field=bottom): +

+
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
+
+ +

With top matching (field=top): +

+
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
+
+ + +

39.93.2 Examples

+ +

Simple IVTC of a top field first telecined stream: +

+
fieldmatch=order=tff:combmatch=none, decimate
+
+ +

Advanced IVTC, with fallback on yadif for still combed frames: +

+
fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
+
+ + +

39.94 fieldorder

+ +

Transform the field order of the input video. +

+

It accepts the following parameters: +

+
+
order
+

The output field order. Valid values are tff for top field first or bff +for bottom field first. +

+
+ +

The default value is ‘tff’. +

+

The transformation is done by shifting the picture content up or down +by one line, and filling the remaining line with appropriate picture content. +This method is consistent with most broadcast field order converters. +

+

If the input video is not flagged as being interlaced, or it is already +flagged as being of the required output field order, then this filter does +not alter the incoming video. +

+

It is very useful when converting to or from PAL DV material, +which is bottom field first. +

+

For example: +

+
ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
+
+ + +

39.95 fillborders

+ +

Fill borders of the input video, without changing video stream dimensions. +Sometimes video can have garbage at the four edges and you may not want to +crop video input to keep size multiple of some number. +

+

This filter accepts the following options: +

+
+
left
+

Number of pixels to fill from left border. +

+
+
right
+

Number of pixels to fill from right border. +

+
+
top
+

Number of pixels to fill from top border. +

+
+
bottom
+

Number of pixels to fill from bottom border. +

+
+
mode
+

Set fill mode. +

+

It accepts the following values: +

+
‘smear’
+

fill pixels using outermost pixels +

+
+
‘mirror’
+

fill pixels using mirroring (half sample symmetric) +

+
+
‘fixed’
+

fill pixels with constant value +

+
+
‘reflect’
+

fill pixels using reflecting (whole sample symmetric) +

+
+
‘wrap’
+

fill pixels using wrapping +

+
+
‘fade’
+

fade pixels to constant value +

+
+
‘margins’
+

fill pixels at top and bottom with weighted averages pixels near borders +

+
+ +

Default is smear. +

+
+
color
+

Set color for pixels in fixed or fade mode. Default is black. +

+
+ + +

39.95.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.96 find_rect

+ +

Find a rectangular object in the input video. +

+

The object to search for must be specified as a gray8 image specified with the +object option. +

+

For each possible match, a score is computed. If the score reaches the specified +threshold, the object is considered found. +

+

If the input video contains multiple instances of the object, the filter will +find only one of them. +

+

When an object is found, the following metadata entries are set in the matching +frame: +

+
lavfi.rect.w
+

width of object +

+
+
lavfi.rect.h
+

height of object +

+
+
lavfi.rect.x
+

x position of object +

+
+
lavfi.rect.y
+

y position of object +

+
+
lavfi.rect.score
+

match score of the found object +

+
+ +

It accepts the following options: +

+
+
object
+

Filepath of the object image, needs to be in gray8. +

+
+
threshold
+

Detection threshold, expressed as a decimal number in the range 0-1. +

+

A threshold value of 0.01 means only exact matches, a threshold of 0.99 means +almost everything matches. +

+

Default value is 0.5. +

+
+
mipmaps
+

Number of mipmaps, default is 3. +

+
+
xmin, ymin, xmax, ymax
+

Specifies the rectangle in which to search. +

+
+
discard
+

Discard frames where object is not detected. Default is disabled. +

+
+ + +

39.96.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    + +
  • Find the position of an object in each frame using ffprobe and write +it to a log file: +
    +
    ffprobe -f lavfi movie=test.mp4,find_rect=object=object.pgm:threshold=0.3 \
    +  -show_entries frame=pkt_pts_time:frame_tags=lavfi.rect.x,lavfi.rect.y \
    +  -of csv -o find_rect.csv
    +
    + +
+ + +

39.97 floodfill

+ +

Flood area with values of same pixel components with another values. +

+

It accepts the following options: +

+
x
+

Set pixel x coordinate. +

+
+
y
+

Set pixel y coordinate. +

+
+
s0
+

Set source #0 component value. +

+
+
s1
+

Set source #1 component value. +

+
+
s2
+

Set source #2 component value. +

+
+
s3
+

Set source #3 component value. +

+
+
d0
+

Set destination #0 component value. +

+
+
d1
+

Set destination #1 component value. +

+
+
d2
+

Set destination #2 component value. +

+
+
d3
+

Set destination #3 component value. +

+
+ + +

39.98 format

+ +

Convert the input video to one of the specified pixel formats. +Libavfilter will try to pick one that is suitable as input to +the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +"pix_fmts=yuv420p|monow|rgb24". +

+
+
color_spaces
+

A ’|’-separated list of color space names, such as +"color_spaces=bt709|bt470bg|bt2020nc". +

+
+
color_ranges
+

A ’|’-separated list of color range names, such as +"color_ranges=tv|pc". +

+
+
alpha_modes
+

A ’|’-separated list of color range names, such as +"alpha_modes=straight|premultiplied". +

+
+
+ + +

39.98.1 Examples

+ +
    +
  • Convert the input video to the yuv420p format +
    +
    format=pix_fmts=yuv420p
    +
    + +

    Convert the input video to any of the formats in the list +

    +
    format=pix_fmts=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

39.99 fps

+ +

Convert the video to specified constant frame rate by duplicating or dropping +frames as necessary. +

+

It accepts the following parameters: +

+
fps
+

The desired output frame rate. It accepts expressions containing the following +constants: +

+
+
‘source_fps’
+

The input’s frame rate +

+
+
‘ntsc’
+

NTSC frame rate of 30000/1001 +

+
+
‘pal’
+

PAL frame rate of 25.0 +

+
+
‘film’
+

Film frame rate of 24.0 +

+
+
‘ntsc_film’
+

NTSC-film frame rate of 24000/1001 +

+
+ +

The default is 25. +

+
+
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. +

+
+
round
+

Timestamp (PTS) rounding method. +

+

Possible values are: +

+
zero
+

round towards 0 +

+
inf
+

round away from 0 +

+
down
+

round towards -infinity +

+
up
+

round towards +infinity +

+
near
+

round to nearest +

+
+

The default is near. +

+
+
eof_action
+

Action performed when reading the last frame. +

+

Possible values are: +

+
round
+

Use same timestamp rounding method as used for other frames. +

+
pass
+

Pass through last frame if input duration has not been reached yet. +

+
+

The default is round. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +fps[:start_time[:round]]. +

+

See also the setpts filter. +

+ +

39.99.1 Examples

+ +
    +
  • A typical usage in order to set the fps to 25: +
    +
    fps=fps=25
    +
    + +
  • Sets the fps to 24, using abbreviation and rounding method to round to nearest: +
    +
    fps=fps=film:round=near
    +
    +
+ + +

39.100 framepack

+ +

Pack two different video streams into a stereoscopic video, setting proper +metadata on supported codecs. The two views should have the same size and +framerate and processing will stop when the shorter video ends. Please note +that you may conveniently adjust view properties with the scale and +fps filters. +

+

It accepts the following parameters: +

+
format
+

The desired packing format. Supported values are: +

+
+
sbs
+

The views are next to each other (default). +

+
+
tab
+

The views are on top of each other. +

+
+
lines
+

The views are packed by line. +

+
+
columns
+

The views are packed by column. +

+
+
frameseq
+

The views are temporally interleaved. +

+
+
+ +
+
+ +

Some examples: +

+
+
# Convert left and right views into a frame-sequential video
+ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
+
+# Convert views into a side-by-side video with the same output resolution as the input
+ffmpeg -i LEFT -i RIGHT -filter_complex [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/2[right],[left][right]framepack=sbs OUTPUT
+
+ + +

39.101 framerate

+ +

Change the frame rate by interpolating new video output frames from the source +frames. +

+

This filter is not designed to function correctly with interlaced media. If +you wish to change the frame rate of interlaced media then you are required +to deinterlace before this filter and re-interlace after this filter. +

+

A description of the accepted options follows. +

+
+
fps
+

Specify the output frames per second. This option can also be specified +as a value alone. The default is 50. +

+
+
interp_start
+

Specify the start of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 15. +

+
+
interp_end
+

Specify the end of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 240. +

+
+
scene
+

Specify the level at which a scene change is detected as a value between +0 and 100 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one. +The default is 8.2. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
scene_change_detect, scd
+

Enable scene change detection using the value of the option scene. +This flag is enabled by default. +

+
+
+
+ + +

39.102 framestep

+ +

Select one frame every N-th frame. +

+

This filter accepts the following option: +

+
step
+

Select frame after every step frames. +Allowed values are positive integers higher than 0. Default value is 1. +

+
+ + +

39.103 freezedetect

+ +

Detect frozen video. +

+

This filter logs a message and sets frame metadata when it detects that the +input video has no significant change in content during a specified duration. +Video freeze detection calculates the mean average absolute difference of all +the components of video frames and compares it to a noise floor. +

+

The printed times and duration are expressed in seconds. The +lavfi.freezedetect.freeze_start metadata key is set on the first frame +whose timestamp equals or exceeds the detection duration and it contains the +timestamp of the first frame of the freeze. The +lavfi.freezedetect.freeze_duration and +lavfi.freezedetect.freeze_end metadata keys are set on the first frame +after the freeze. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or as a difference ratio between 0 and 1. Default is -60dB, or +0.001. +

+
+
duration, d
+

Set freeze duration until notification (default is 2 seconds). +

+
+ + +

39.104 freezeframes

+ +

Freeze video frames. +

+

This filter freezes video frames using frame from 2nd input. +

+

The filter accepts the following options: +

+
+
first
+

Set number of first frame from which to start freeze. +

+
+
last
+

Set number of last frame from which to end freeze. +

+
+
replace
+

Set number of frame from 2nd input which will be used instead of replaced frames. +

+
+ + +

39.105 frei0r

+ +

Apply a frei0r effect to the input video. +

+

To enable the compilation of this filter, you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the frei0r effect to load. If the environment variable +FREI0R_PATH is defined, the frei0r effect is searched for in each of the +directories specified by the colon-separated list in FREI0R_PATH. +Otherwise, the standard frei0r paths are searched, in this order: +HOME/.frei0r-1/lib/, /usr/local/lib/frei0r-1/, +/usr/lib/frei0r-1/. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r effect. +

+
+
+ +

A frei0r effect parameter can be a boolean (its value is either +"y" or "n"), a double, a color (specified as +R/G/B, where R, G, and B are floating point +numbers between 0.0 and 1.0, inclusive) or a color description as specified in the +"Color" section in the ffmpeg-utils manual, +a position (specified as X/Y, where +X and Y are floating point numbers) and/or a string. +

+

The number and types of parameters depend on the loaded effect. If an +effect parameter is not specified, the default value is set. +

+ +

39.105.1 Examples

+ +
    +
  • Apply the distort0r effect, setting the first two double parameters: +
    +
    frei0r=filter_name=distort0r:filter_params=0.5|0.01
    +
    + +
  • Apply the colordistance effect, taking a color as the first parameter: +
    +
    frei0r=colordistance:0.2/0.3/0.4
    +frei0r=colordistance:violet
    +frei0r=colordistance:0x112233
    +
    + +
  • Apply the perspective effect, specifying the top left and top right image +positions: +
    +
    frei0r=perspective:0.2/0.2|0.8/0.2
    +
    +
+ +

For more information, see +http://frei0r.dyne.org +

+ +

39.105.2 Commands

+ +

This filter supports the filter_params option as commands. +

+ +

39.106 fspp

+ +

Apply fast and simple postprocessing. It is a faster version of spp. +

+

It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- +processing filter, one of them is performed once per block, not per pixel. +This allows for much higher speed. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 4-5. Default value is 4. +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range 0-63. +If not set, the filter will use the QP from the video stream (if available). +

+
+
strength
+

Set filter strength. It accepts an integer in range -15 to 32. Lower values mean +more details but also more artifacts, while higher values make the image smoother +but also blurrier. Default value is 0 − PSNR optimal. +

+
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+
+ + +

39.107 fsync

+ +

Synchronize video frames with an external mapping from a file. +

+

For each input PTS given in the map file it either drops or creates as many +frames as necessary to recreate the sequence of output frames given in the +map file. +

+

This filter is useful to recreate the output frames of a framerate conversion +by the fps filter, recorded into a map file using the ffmpeg option +-stats_mux_pre, and do further processing to the corresponding frames +e.g. quality comparison. +

+

Each line of the map file must contain three items per input frame, the input +PTS (decimal), the output PTS (decimal) and the +output TIMEBASE (decimal/decimal), separated by a space. +This file format corresponds to the output +of -stats_mux_pre_fmt="{ptsi} {pts} {tb}". +

+

The filter assumes the map file is sorted by increasing input PTS. +

+

The filter accepts the following options: +

+
file, f
+

The filename of the map file to be used. +

+
+ +

Example: +

+
# Convert a video to 25 fps and record a MAP_FILE file with the default format of this filter
+ffmpeg -i INPUT -vf fps=fps=25 -stats_mux_pre MAP_FILE -stats_mux_pre_fmt "{ptsi} {pts} {tb}" OUTPUT
+
+# Sort MAP_FILE by increasing input PTS
+sort -n MAP_FILE
+
+# Use INPUT, OUTPUT and the MAP_FILE from above to compare the corresponding frames in INPUT and OUTPUT via SSIM
+ffmpeg -i INPUT -i OUTPUT -filter_complex '[0:v]fsync=file=MAP_FILE[ref];[1:v][ref]ssim' -f null -
+
+ + +

39.108 gblur

+ +

Apply Gaussian blur filter. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
steps
+

Set number of steps for Gaussian approximation. Default is 1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+ + +

39.108.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.109 geq

+ +

Apply generic equation to each pixel. +

+

The filter accepts the following options: +

+
+
lum_expr, lum
+

Set the luma expression. +

+
cb_expr, cb
+

Set the chrominance blue expression. +

+
cr_expr, cr
+

Set the chrominance red expression. +

+
alpha_expr, a
+

Set the alpha expression. +

+
red_expr, r
+

Set the red expression. +

+
green_expr, g
+

Set the green expression. +

+
blue_expr, b
+

Set the blue expression. +

+
+ +

The colorspace is selected according to the specified options. If one +of the lum_expr, cb_expr, or cr_expr +options is specified, the filter will automatically select a YCbCr +colorspace. If one of the red_expr, green_expr, or +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 +to the luma expression. +

+

The expressions can use the following variables and functions: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
SW
+
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 1,1 for the luma plane, and +0.5,0.5 for chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
p(x, y)
+

Return the value of the pixel at location (x,y) of the current +plane. +

+
+
lum(x, y)
+

Return the value of the pixel at location (x,y) of the luma +plane. +

+
+
cb(x, y)
+

Return the value of the pixel at location (x,y) of the +blue-difference chroma plane. Return 0 if there is no such plane. +

+
+
cr(x, y)
+

Return the value of the pixel at location (x,y) of the +red-difference chroma plane. Return 0 if there is no such plane. +

+
+
r(x, y)
+
g(x, y)
+
b(x, y)
+

Return the value of the pixel at location (x,y) of the +red/green/blue component. Return 0 if there is no such component. +

+
+
alpha(x, y)
+

Return the value of the pixel at location (x,y) of the alpha +plane. Return 0 if there is no such plane. +

+
+
psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
+

Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining +sums of samples within a rectangle. See the functions without the sum postfix. +

+
+
interpolation
+

Set one of interpolation methods: +

+
nearest, n
+
bilinear, b
+
+

Default is bilinear. +

+
+ +

For functions, if x and y are outside the area, the value will be +automatically clipped to the closer edge. +

+

Please note that this filter can use multiple threads in which case each slice +will have its own expression state. If you want to use only a single expression +state because your expressions depend on previous state then you should limit +the number of filter threads to 1. +

+ +

39.109.1 Examples

+ +
    +
  • Flip the image horizontally: +
    +
    geq=p(W-X\,Y)
    +
    + +
  • Generate a bidimensional sine wave, with angle PI/3 and a +wavelength of 100 pixels: +
    +
    geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
    +
    + +
  • Generate a fancy enigmatic moving light: +
    +
    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
    +
    + +
  • Generate a quick emboss effect: +
    +
    format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
    +
    + +
  • Modify RGB components depending on pixel position: +
    +
    geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
    +
    + +
  • Create a radial gradient that is the same size as the input (also see +the vignette filter): +
    +
    geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
    +
    +
+ + +

39.110 gradfun

+ +

Fix the banding artifacts that are sometimes introduced into nearly flat +regions by truncation to 8-bit color depth. +Interpolate the gradients that should go where the bands are, and +dither them. +

+

It 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. +

+

It accepts the following parameters: +

+
+
strength
+

The maximum amount by which the filter will change any one pixel. This is also +the threshold for detecting nearly flat regions. Acceptable values range from +.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the +valid range. +

+
+
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 8-32; the default value is 16. Out-of-range +values will be clipped to the valid range. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +strength[:radius] +

+ +

39.110.1 Examples

+ +
    +
  • Apply the filter with a 3.5 strength and radius of 8: +
    +
    gradfun=3.5:8
    +
    + +
  • Specify radius, omitting the strength (which will fall-back to the default +value): +
    +
    gradfun=radius=8
    +
    + +
+ + +

39.111 graphmonitor

+

Show various filtergraph stats. +

+

With this filter one can debug complete filtergraph. +Especially issues with links filling with queued frames. +

+

The filter accepts the following options: +

+
+
size, s
+

Set video output size. Default is hd720. +

+
+
opacity, o
+

Set video opacity. Default is 0.9. Allowed range is from 0 to 1. +

+
+
mode, m
+

Set output mode flags. +

+

Available values for flags are: +

+
‘full’
+

No any filtering. Default. +

+
‘compact’
+

Show only filters with queued frames. +

+
‘nozero’
+

Show only filters with non-zero stats. +

+
‘noeof’
+

Show only filters with non-eof stat. +

+
‘nodisabled’
+

Show only filters that are enabled in timeline. +

+
+ +
+
flags, f
+

Set flags which enable which stats are shown in video. +

+

Available values for flags are: +

+
‘none’
+

All flags turned off. +

+
+
‘all’
+

All flags turned on. +

+
+
‘queue’
+

Display number of queued frames in each link. +

+
+
‘frame_count_in’
+

Display number of frames taken from filter. +

+
+
‘frame_count_out’
+

Display number of frames given out from filter. +

+
+
‘frame_count_delta’
+

Display delta number of frames between above two values. +

+
+
‘pts’
+

Display current filtered frame pts. +

+
+
‘pts_delta’
+

Display pts delta between current and previous frame. +

+
+
‘time’
+

Display current filtered frame time. +

+
+
‘time_delta’
+

Display time delta between current and previous frame. +

+
+
‘timebase’
+

Display time base for filter link. +

+
+
‘format’
+

Display used format for filter link. +

+
+
‘size’
+

Display video size or number of audio channels in case of audio used by filter link. +

+
+
‘rate’
+

Display video frame rate or sample rate in case of audio used by filter link. +

+
+
‘eof’
+

Display link output status. +

+
+
‘sample_count_in’
+

Display number of samples taken from filter. +

+
+
‘sample_count_out’
+

Display number of samples given out from filter. +

+
+
‘sample_count_delta’
+

Display delta number of samples between above two values. +

+
+
‘disabled’
+

Show the timeline filter status. +

+
+ +
+
rate, r
+

Set upper limit for video rate of output stream, Default value is 25. +This guarantee that output video frame rate will not be higher than this value. +

+
+ + +

39.112 grayworld

+

A color constancy filter that applies color correction based on the grayworld assumption +

+

See: https://www.researchgate.net/publication/275213614_A_New_Color_Correction_Method_for_Underwater_Imaging +

+

The algorithm uses linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,grayworld,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

39.113 greyedge

+

A color constancy variation filter which estimates scene illumination via grey edge algorithm +and corrects the scene colors accordingly. +

+

See: https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf +

+

The filter accepts the following options: +

+
+
difford
+

The order of differentiation to be applied on the scene. Must be chosen in the range +[0,2] and default value is 1. +

+
+
minknorm
+

The Minkowski parameter to be used for calculating the Minkowski distance. Must +be chosen in the range [0,20] and default value is 1. Set to 0 for getting +max value instead of calculating Minkowski distance. +

+
+
sigma
+

The standard deviation of Gaussian blur to be applied on the scene. Must be +chosen in the range [0,1024.0] and default value = 1. floor( sigma * break_off_sigma(3) ) +can’t be equal to 0 if difford is greater than 0. +

+
+ + +

39.113.1 Examples

+
    +
  • Grey Edge: +
    +
    greyedge=difford=1:minknorm=5:sigma=2
    +
    + +
  • Max Edge: +
    +
    greyedge=difford=1:minknorm=0:sigma=2
    +
    + +
+ + +

39.114 guided

+

Apply guided filter for edge-preserving smoothing, dehazing and so on. +

+

The filter accepts the following options: +

+
radius
+

Set the box radius in pixels. +Allowed range is 1 to 20. Default is 3. +

+
+
eps
+

Set regularization parameter (with square). +Allowed range is 0 to 1. Default is 0.01. +

+
+
mode
+

Set filter mode. Can be basic or fast. +Default is basic. +

+
+
sub
+

Set subsampling ratio for fast mode. +Range is 2 to 64. Default is 4. +No subsampling occurs in basic mode. +

+
+
guidance
+

Set guidance mode. Can be off or on. Default is off. +If off, single input is required. +If on, two inputs of the same resolution and pixel format are required. +The second input serves as the guidance. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

39.114.1 Commands

+

This filter supports the all above options as commands. +

+ +

39.114.2 Examples

+
    +
  • Edge-preserving smoothing with guided filter: +
    +
    ffmpeg -i in.png -vf guided out.png
    +
    + +
  • Dehazing, structure-transferring filtering, detail enhancement with guided filter. +For the generation of guidance image, refer to paper "Guided Image Filtering". +See: http://kaiminghe.com/publications/pami12guidedfilter.pdf. +
    +
    ffmpeg -i in.png -i guidance.png -filter_complex guided=guidance=on out.png
    +
    + +
+ + +

39.115 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: +

+
+
clut
+

Set which CLUT video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+
shortest
+

Force termination when the shortest input terminates. Default is 0. +

+
repeatlast
+

Continue applying the last CLUT after the end of the stream. A value of +0 disable the filter after the last frame of the CLUT is reached. +Default is 1. +

+
+ +

haldclut also has the same interpolation options as lut3d (both +filters share the same internals). +

+

This filter also supports the framesync options. +

+

More information about the Hald CLUT can be found on Eskil Steenberg’s website +(Hald CLUT author) at http://www.quelsolaar.com/technology/clut.html. +

+ +

39.115.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

39.115.2 Workflow examples

+ + +

39.115.2.1 Hald CLUT video stream

+ +

Generate an identity Hald CLUT stream altered with various effects: +

+
ffmpeg -f lavfi -i haldclutsrc=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut
+
+ +

Note: make sure you use a lossless codec. +

+

Then use it with haldclut to apply it on some random stream: +

+
ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
+
+ +

The Hald CLUT will be applied to the 10 first seconds (duration of +clut.nut), then the latest picture of that CLUT stream will be applied +to the remaining frames of the mandelbrot stream. +

+ +

39.115.2.2 Hald CLUT with preview

+ +

A Hald CLUT is supposed to be a squared image of Level*Level*Level by +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 +haldclut filter: +

+
+
ffmpeg -f lavfi -i 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
+
+ +

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: +

+
ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
+
+ + +

39.116 hflip

+ +

Flip the input video horizontally. +

+

For example, to horizontally flip the input video with ffmpeg: +

+
ffmpeg -i in.avi -vf "hflip" out.avi
+
+ + +

39.117 histeq

+

This filter applies a global color histogram equalization on a +per-frame basis. +

+

It can be used to correct video that has a compressed range of pixel +intensities. The filter redistributes the pixel intensities to +equalize their distribution across the intensity range. It may be +viewed as an "automatically adjusting contrast filter". This filter is +useful only for correcting degraded or poorly captured source +video. +

+

The filter accepts the following options: +

+
+
strength
+

Determine the amount of equalization to be applied. As the strength +is reduced, the distribution of pixel intensities more-and-more +approaches that of the input frame. The value must be a float number +in the range [0,1] and defaults to 0.200. +

+
+
intensity
+

Set the maximum intensity that can generated and scale the output +values appropriately. The strength should be set as desired and then +the intensity can be limited if needed to avoid washing-out. The value +must be a float number in the range [0,1] and defaults to 0.210. +

+
+
antibanding
+

Set the antibanding level. If enabled the filter will randomly vary +the luminance of output pixels by a small amount to avoid banding of +the histogram. Possible values are none, weak or +strong. It defaults to none. +

+
+ + +

39.118 histogram

+ +

Compute and draw a color distribution histogram for the input video. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

Standard histogram displays the color components distribution in an image. +Displays color graph for each color component. Shows distribution of +the Y, U, V, A or R, G, B components, depending on input format, in the +current frame. Below each graph a color component scale meter is shown. +

+

The filter accepts the following options: +

+
+
level_height
+

Set height of level. Default value is 200. +Allowed range is [50, 2048]. +

+
+
scale_height
+

Set height of color scale. Default value is 12. +Allowed range is [0, 40]. +

+
+
display_mode
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components
+

Set what color components to display. +Default is 7. +

+
+
fgopacity
+

Set foreground opacity. Default is 0.7. +

+
+
bgopacity
+

Set background opacity. Default is 0.5. +

+
+
colors_mode
+

Set colors mode. +It accepts the following values: +

+
‘whiteonblack’
+
‘blackonwhite’
+
‘whiteongray’
+
‘blackongray’
+
‘coloronblack’
+
‘coloronwhite’
+
‘colorongray’
+
‘blackoncolor’
+
‘whiteoncolor’
+
‘grayoncolor’
+
+

Default is whiteonblack. +

+
+ + +

39.118.1 Examples

+ +
    +
  • Calculate and draw histogram: +
    +
    ffplay -i input -vf histogram
    +
    + +
+ + +

39.119 hqdn3d

+ +

This is a high precision/quality 3d denoise filter. It aims to reduce +image noise, producing smooth images and making still images really +still. It should enhance compressibility. +

+

It accepts the following optional parameters: +

+
+
luma_spatial
+

A non-negative floating point number which specifies spatial luma strength. +It defaults to 4.0. +

+
+
chroma_spatial
+

A non-negative floating point number which specifies spatial chroma strength. +It defaults to 3.0*luma_spatial/4.0. +

+
+
luma_tmp
+

A floating point number which specifies luma temporal strength. It defaults to +6.0*luma_spatial/4.0. +

+
+
chroma_tmp
+

A floating point number which specifies chroma temporal strength. It defaults to +luma_tmp*chroma_spatial/luma_spatial. +

+
+ + +

39.119.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.120 hwdownload

+ +

Download hardware frames to system memory. +

+

The input must be in hardware frames, and the output a non-hardware format. +Not all formats will be supported on the output - it may be necessary to insert +an additional format filter immediately following in the graph to get +the output in a supported format. +

+ +

39.121 hwmap

+ +

Map hardware frames to system memory or to another device. +

+

This filter has several different modes of operation; which one is used depends +on the input and output formats: +

    +
  • Hardware frame input, normal frame output + +

    Map the input frames to system memory and pass them to the output. If the +original hardware frame is later required (for example, after overlaying +something else on part of it), the hwmap filter can be used again +in the next mode to retrieve it. +

  • Normal frame input, hardware frame output + +

    If the input is actually a software-mapped hardware frame, then unmap it - +that is, return the original hardware frame. +

    +

    Otherwise, a device must be provided. Create new hardware surfaces on that +device for the output, then map them back to the software format at the input +and give those frames to the preceding filter. This will then act like the +hwupload filter, but may be able to avoid an additional copy when +the input is already in a compatible format. +

  • Hardware frame input and output + +

    A device must be supplied for the output, either directly or with the +derive_device option. The input and output devices must be of +different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

    +

    If the input frames were originally created on the output device, then unmap +to retrieve the original frames. +

    +

    Otherwise, map the frames to the output device - create new hardware frames +on the output corresponding to the frames on the input. +

+ +

The following additional parameters are accepted: +

+
+
mode
+

Set the frame mapping mode. Some combination of: +

+
read
+

The mapped frame should be readable. +

+
write
+

The mapped frame should be writeable. +

+
overwrite
+

The mapping will always overwrite the entire frame. +

+

This may improve performance in some cases, as the original contents of the +frame need not be loaded. +

+
direct
+

The mapping must not involve any copying. +

+

Indirect mappings to copies of frames are created in some cases where either +direct mapping is not possible or it would have unexpected properties. +Setting this flag ensures that the mapping is direct and will fail if that is +not possible. +

+
+

Defaults to read+write if not specified. +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+
reverse
+

In a hardware to hardware mapping, map in reverse - create frames in the sink +and map them back to the source. This may be necessary in some cases where +a mapping in one direction is required but only the opposite direction is +supported by the devices being used. +

+

This option is dangerous - it may break the preceding filter in undefined +ways if there are any additional constraints on that filter’s output. +Do not use it without fully understanding the implications of its use. +

+
+ + +

39.122 hwupload

+ +

Upload system memory frames to hardware surfaces. +

+

The device to upload to must be supplied when the filter is initialised. If +using ffmpeg, select the appropriate device with the -filter_hw_device +option or with the derive_device option. The input and output devices +must be of different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

+

The following additional parameters are accepted: +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+ + +

39.123 hwupload_cuda

+ +

Upload system memory frames to a CUDA device. +

+

It accepts the following optional parameters: +

+
+
device
+

The number of the CUDA device to use +

+
+ + +

39.124 hqx

+ +

Apply a high-quality magnification filter designed for pixel art. This filter +was originally created by Maxim Stepin. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for hq2x, 3 for +hq3x and 4 for hq4x. +Default is 3. +

+
+ + +

39.125 hstack

+

Stack input videos horizontally. +

+

All streams must be of same pixel format and of same height. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following option: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

39.126 hsvhold

+

Turns a certain HSV range into gray values. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to be gray or not. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully gray, or not gray at all. +

+

Higher values result in more gray pixels, with a higher gray pixel +the more similar the pixels color is to the key color. +

+
+ + +

39.127 hsvkey

+

Turns a certain HSV range into transparency. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to transparent by adding alpha channel. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

39.128 hue

+ +

Modify the hue and/or the saturation of the input. +

+

It accepts the following parameters: +

+
+
h
+

Specify the hue angle as a number of degrees. It accepts an expression, +and defaults to "0". +

+
+
s
+

Specify the saturation in the [-10,10] range. It accepts an expression and +defaults to "1". +

+
+
H
+

Specify the hue angle as a number of radians. It accepts an +expression, and defaults to "0". +

+
+
b
+

Specify the brightness in the [-10,10] range. It accepts an expression and +defaults to "0". +

+
+ +

h and H are mutually exclusive, and can’t be +specified at the same time. +

+

The b, h, H and s option values are +expressions containing the following constants: +

+
+
n
+

frame count of the input frame starting from 0 +

+
+
pts
+

presentation timestamp of the input frame expressed in time base units +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
tb
+

time base of the input video +

+
+ + +

39.128.1 Examples

+ +
    +
  • Set the hue to 90 degrees and the saturation to 1.0: +
    +
    hue=h=90:s=1
    +
    + +
  • Same command but expressing the hue in radians: +
    +
    hue=H=PI/2:s=1
    +
    + +
  • Rotate hue and make the saturation swing between 0 +and 2 over a period of 1 second: +
    +
    hue="H=2*PI*t: s=sin(2*PI*t)+1"
    +
    + +
  • Apply a 3 seconds saturation fade-in effect starting at 0: +
    +
    hue="s=min(t/3\,1)"
    +
    + +

    The general fade-in expression can be written as: +

    +
    hue="s=min(0\, max((t-START)/DURATION\, 1))"
    +
    + +
  • Apply a 3 seconds saturation fade-out effect starting at 5 seconds: +
    +
    hue="s=max(0\, min(1\, (8-t)/3))"
    +
    + +

    The general fade-out expression can be written as: +

    +
    hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
    +
    + +
+ + +

39.128.2 Commands

+ +

This filter supports the following commands: +

+
b
+
s
+
h
+
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 the specified expression is not valid, it is kept at its current +value. +

+
+ + +

39.129 huesaturation

+

Apply hue-saturation-intensity adjustments to input video stream. +

+

This filter operates in RGB colorspace. +

+

This filter accepts the following options: +

+
+
hue
+

Set the hue shift in degrees to apply. Default is 0. +Allowed range is from -180 to 180. +

+
+
saturation
+

Set the saturation shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
intensity
+

Set the intensity shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
colors
+

Set which primary and complementary colors are going to be adjusted. +This options is set by providing one or multiple values. +This can select multiple colors at once. By default all colors are selected. +

+
‘r’
+

Adjust reds. +

+
‘y’
+

Adjust yellows. +

+
‘g’
+

Adjust greens. +

+
‘c’
+

Adjust cyans. +

+
‘b’
+

Adjust blues. +

+
‘m’
+

Adjust magentas. +

+
‘a’
+

Adjust all colors. +

+
+ +
+
strength
+

Set strength of filtering. Allowed range is from 0 to 100. +Default value is 1. +

+
+
rw, gw, bw
+

Set weight for each RGB component. Allowed range is from 0 to 1. +By default is set to 0.333, 0.334, 0.333. +Those options are used in saturation and lightess processing. +

+
+
lightness
+

Set preserving lightness, by default is disabled. +Adjusting hues can change lightness from original RGB triplet, +with this option enabled lightness is kept at same value. +

+
+ + +

39.130 hysteresis

+ +

Grow first stream into second stream by connecting components. +This makes it possible to build more robust edge masks. +

+

This filter accepts the following options: +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+
threshold
+

Set threshold which is used in filtering. If pixel component value is higher than +this value filter algorithm for connecting components is activated. +By default value is 0. +

+
+ +

The hysteresis filter also supports the framesync options. +

+ +

39.131 iccdetect

+ +

Detect the colorspace from an embedded ICC profile (if present), and update +the frame’s tags accordingly. +

+

This filter accepts the following options: +

+
+
force
+

If true, the frame’s existing colorspace tags will always be overridden by +values detected from an ICC profile. Otherwise, they will only be assigned if +they contain unknown. Enabled by default. +

+
+ + +

39.132 iccgen

+ +

Generate ICC profiles and attach them to frames. +

+

This filter accepts the following options: +

+
+
color_primaries
+
color_trc
+

Configure the colorspace that the ICC profile will be generated for. The +default value of auto infers the value from the input frame’s metadata, +defaulting to BT.709/sRGB as appropriate. +

+

See the setparams filter for a list of possible values, but note that +unknown are not valid values for this filter. +

+
+
force
+

If true, an ICC profile will be generated even if it would overwrite an +already existing ICC profile. Disabled by default. +

+
+ + +

39.133 identity

+ +

Obtain the identity score between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max identity score is printed through +the logging system. +

+

The filter stores the calculated identity scores of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi identity -f null -
+
+ + +

39.134 idet

+ +

Detect video interlacing type. +

+

This filter tries to detect if the input frames are interlaced, progressive, +top or bottom field first. It will also try to detect fields that are +repeated between adjacent frames (a sign of telecine). +

+

Single frame detection considers only immediately adjacent frames when classifying each frame. +Multiple frame detection incorporates the classification history of previous frames. +

+

The filter will log these metadata values: +

+
+
single.current_frame
+

Detected type of current frame using single-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
single.tff
+

Cumulative number of frames detected as top field first using single-frame detection. +

+
+
multiple.tff
+

Cumulative number of frames detected as top field first using multiple-frame detection. +

+
+
single.bff
+

Cumulative number of frames detected as bottom field first using single-frame detection. +

+
+
multiple.current_frame
+

Detected type of current frame using multiple-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
multiple.bff
+

Cumulative number of frames detected as bottom field first using multiple-frame detection. +

+
+
single.progressive
+

Cumulative number of frames detected as progressive using single-frame detection. +

+
+
multiple.progressive
+

Cumulative number of frames detected as progressive using multiple-frame detection. +

+
+
single.undetermined
+

Cumulative number of frames that could not be classified using single-frame detection. +

+
+
multiple.undetermined
+

Cumulative number of frames that could not be classified using multiple-frame detection. +

+
+
repeated.current_frame
+

Which field in the current frame is repeated from the last. One of “neither”, “top”, or “bottom”. +

+
+
repeated.neither
+

Cumulative number of frames with no repeated field. +

+
+
repeated.top
+

Cumulative number of frames with the top field repeated from the previous frame’s top field. +

+
+
repeated.bottom
+

Cumulative number of frames with the bottom field repeated from the previous frame’s bottom field. +

+
+ +

The filter accepts the following options: +

+
+
intl_thres
+

Set interlacing threshold. +

+
prog_thres
+

Set progressive threshold. +

+
rep_thres
+

Threshold for repeated field detection. +

+
half_life
+

Number of frames after which a given frame’s contribution to the +statistics is halved (i.e., it contributes only 0.5 to its +classification). The default of 0 means that all frames seen are given +full weight of 1.0 forever. +

+
analyze_interlaced_flag
+

When this is not 0 then idet will use the specified number of frames to determine +if the interlaced flag is accurate, it will not count undetermined frames. +If the flag is found to be accurate it will be used without any further +computations, if it is found to be inaccurate it will be cleared without any +further computations. This allows inserting the idet filter as a low computational +method to clean up the interlaced flag +

+
+ + +

39.134.1 Examples

+ +

Inspect the field order of the first 360 frames in a video, in verbose detail: +

+
ffmpeg -i INPUT -filter:v idet,metadata=mode=print -frames:v 360 -an -f null -
+
+

The idet filter will add analysis metadata to each frame, which will then be +discarded. At the end, the filter will also print a final report with statistics. +

+ +

39.135 il

+ +

Deinterleave or interleave fields. +

+

This filter allows one to process interlaced images fields without +deinterlacing them. Deinterleaving splits the input frame into 2 +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. +

+

The filter accepts the following options: +

+
+
luma_mode, l
+
chroma_mode, c
+
alpha_mode, a
+

Available values for luma_mode, chroma_mode and +alpha_mode are: +

+
+
‘none’
+

Do nothing. +

+
+
‘deinterleave, d’
+

Deinterleave fields, placing one above the other. +

+
+
‘interleave, i’
+

Interleave fields. Reverse the effect of deinterleaving. +

+
+

Default value is none. +

+
+
luma_swap, ls
+
chroma_swap, cs
+
alpha_swap, as
+

Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is 0. +

+
+ + +

39.135.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.136 inflate

+ +

Apply inflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values higher than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

39.136.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.137 interlace, interlace_vulkan

+ +

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. +

+
+
   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
+
+ +

It accepts the following optional parameters: +

+
+
scan
+

This determines whether the interlaced frame is taken from the even +(tff - default) or odd (bff) lines of the progressive frame. +

+
+
lowpass
+

Vertical lowpass filter to avoid twitter interlacing and +reduce moire patterns. +

+
+
‘0, off’
+

Disable vertical lowpass filter +

+
+
‘1, linear’
+

Enable linear filter (default) +

+
+
‘2, complex’
+

Enable complex filter. This will slightly less reduce twitter and moire +but better retain detail and subjective sharpness impression. +

+
+
+
+
+ + +

39.138 kerndeint

+ +

Deinterlace input video by applying Donald Graft’s adaptive kernel +deinterling. Work on interlaced parts of a video to produce +progressive frames. +

+

The description of the accepted parameters follows. +

+
+
thresh
+

Set the threshold which affects the filter’s tolerance when +determining if a pixel line must be processed. It must be an integer +in the range [0,255] and defaults to 10. A value of 0 will result in +applying the process on every pixels. +

+
+
map
+

Paint pixels exceeding the threshold value to white if set to 1. +Default is 0. +

+
+
order
+

Set the fields order. Swap fields if set to 1, leave fields alone if +0. Default is 0. +

+
+
sharp
+

Enable additional sharpening if set to 1. Default is 0. +

+
+
twoway
+

Enable twoway sharpening if set to 1. Default is 0. +

+
+ + +

39.138.1 Examples

+ +
    +
  • Apply default values: +
    +
    kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
    +
    + +
  • Enable additional sharpening: +
    +
    kerndeint=sharp=1
    +
    + +
  • Paint processed pixels in white: +
    +
    kerndeint=map=1
    +
    +
+ + +

39.139 kirsch

+

Apply kirsch operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

39.139.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.140 lagfun

+ +

Slowly update darker pixels. +

+

This filter makes short flashes of light appear longer. +This filter accepts the following options: +

+
+
decay
+

Set factor for decaying. Default is .95. Allowed range is from 0 to 1. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

39.140.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.141 lenscorrection

+ +

Correct radial lens distortion +

+

This filter can be used to correct for radial distortion as can result from the use +of wide angle lenses, and thereby re-rectify the image. To find the right parameters +one can use tools available for example as part of opencv or simply trial-and-error. +To use opencv use the calibration sample (under samples/cpp) from the opencv sources +and extract the k1 and k2 coefficients from the resulting matrix. +

+

Note that effectively the same filter is available in the open-source tools Krita and +Digikam from the KDE project. +

+

In contrast to the vignette filter, which can also be used to compensate lens errors, +this filter corrects the distortion of the image, whereas vignette corrects the +brightness distribution, so you may want to use both filters together in certain +cases, though you will have to take care of ordering, i.e. whether vignetting should +be applied before or after lens correction. +

+ +

39.141.1 Options

+ +

The filter accepts the following options: +

+
+
cx
+

Relative x-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +width. Default is 0.5. +

+
cy
+

Relative y-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +height. Default is 0.5. +

+
k1
+

Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means +no correction. Default is 0. +

+
k2
+

Coefficient of the double quadratic correction term. This value has a range [-1,1]. +0 means no correction. Default is 0. +

+
i
+

Set interpolation type. Can be nearest or bilinear. +Default is nearest. +

+
fc
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black@0. +

+
+ +

The formula that generates the correction is: +

+

r_src = r_tgt * (1 + k1 * (r_tgt / r_0)^2 + k2 * (r_tgt / r_0)^4) +

+

where r_0 is halve of the image diagonal and r_src and r_tgt are the +distances from the focal point in the source and target images, respectively. +

+ +

39.141.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.142 lensfun

+ +

Apply lens correction via the lensfun library (http://lensfun.sourceforge.net/). +

+

The lensfun filter requires the camera make, camera model, and lens model +to apply the lens correction. The filter will load the lensfun database and +query it to find the corresponding camera and lens entries in the database. As +long as these entries can be found with the given options, the filter can +perform corrections on frames. Note that incomplete strings will result in the +filter choosing the best match with the given options, and the filter will +output the chosen camera and lens models (logged with level "info"). You must +provide the make, camera model, and lens model as they are required. +

+

To obtain a list of available makes and models, leave out one or both of make and +model options. The filter will send the full list to the log with level INFO. +The first column is the make and the second column is the model. +To obtain a list of available lenses, set any values for make and model and leave out the +lens_model option. The filter will send the full list of lenses in the log with level +INFO. The ffmpeg tool will exit after the list is printed. +

+

The filter accepts the following options: +

+
+
make
+

The make of the camera (for example, "Canon"). This option is required. +

+
+
model
+

The model of the camera (for example, "Canon EOS 100D"). This option is +required. +

+
+
lens_model
+

The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This +option is required. +

+
+
db_path
+

The full path to the lens database folder. If not set, the filter will attempt to +load the database from the install path when the library was built. Default is unset. +

+
+
mode
+

The type of correction to apply. The following values are valid options: +

+
+
‘vignetting’
+

Enables fixing lens vignetting. +

+
+
‘geometry’
+

Enables fixing lens geometry. This is the default. +

+
+
‘subpixel’
+

Enables fixing chromatic aberrations. +

+
+
‘vig_geo’
+

Enables fixing lens vignetting and lens geometry. +

+
+
‘vig_subpixel’
+

Enables fixing lens vignetting and chromatic aberrations. +

+
+
‘distortion’
+

Enables fixing both lens geometry and chromatic aberrations. +

+
+
‘all’
+

Enables all possible corrections. +

+
+
+
+
focal_length
+

The focal length of the image/video (zoom; expected constant for video). For +example, a 18–55mm lens has focal length range of [18–55], so a value in that +range should be chosen when using that lens. Default 18. +

+
+
aperture
+

The aperture of the image/video (expected constant for video). Note that +aperture is only used for vignetting correction. Default 3.5. +

+
+
focus_distance
+

The focus distance of the image/video (expected constant for video). Note that +focus distance is only used for vignetting and only slightly affects the +vignetting correction process. If unknown, leave it at the default value (which +is 1000). +

+
+
scale
+

The scale factor which is applied after transformation. After correction the +video is no longer necessarily rectangular. This parameter controls how much of +the resulting image is visible. The value 0 means that a value will be chosen +automatically such that there is little or no unmapped area in the output +image. 1.0 means that no additional scaling is done. Lower values may result +in more of the corrected image being visible, while higher values may avoid +unmapped areas in the output. +

+
+
target_geometry
+

The target geometry of the output image/video. The following values are valid +options: +

+
+
‘rectilinear (default)’
+
‘fisheye’
+
‘panoramic’
+
‘equirectangular’
+
‘fisheye_orthographic’
+
‘fisheye_stereographic’
+
‘fisheye_equisolid’
+
‘fisheye_thoby’
+
+
+
reverse
+

Apply the reverse of image correction (instead of correcting distortion, apply +it). +

+
+
interpolation
+

The type of interpolation used when correcting distortion. The following values +are valid options: +

+
+
‘nearest’
+
‘linear (default)’
+
‘lanczos’
+
+
+
+ + +

39.142.1 Examples

+ +
    +
  • Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens +model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and +aperture of "8.0". + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
    +
    + +
  • Apply the same as before, but only for the first 5 seconds of video. + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov
    +
    + +
+ + +

39.143 lcevc

+ +

Low Complexity Enhancement Video Codec filter based on liblcevc_dec +(https://github.com/v-novaltd/LCEVCdec). +

+ +

39.144 libplacebo

+ +

Flexible GPU-accelerated processing filter based on libplacebo +(https://code.videolan.org/videolan/libplacebo). +

+ +

39.144.1 Options

+ +

The options for this filter are divided into the following sections: +

+ +

39.144.1.1 Output mode

+

These options control the overall output mode. By default, libplacebo will try +to preserve the source colorimetry and size as best as it can, but it will +apply any embedded film grain, dolby vision metadata or anamorphic SAR present +in source frames. +

+
inputs
+

Set the number of inputs. This can be used, alongside the idx variable, +to allow placing/blending multiple inputs inside the output frame. This +effectively enables functionality similar to hstack, overlay, etc. +

+
+
w
+
h
+

Set the output video dimension expression. Default values are iw and +ih. +

+

Allows for the same expressions as the scale filter. +

+
+
crop_x
+
crop_y
+

Set the input crop x/y expressions, default values are (iw-cw)/2 and +(ih-ch)/2. +

+
+
crop_w
+
crop_h
+

Set the input crop width/height expressions, default values are iw and +ih. +

+
+
pos_x
+
pos_y
+

Set the output placement x/y expressions, default values are (ow-pw)/2 +and (oh-ph)/2. +

+
+
pos_w
+
pos_h
+

Set the output placement width/height expressions, default values are ow +and oh. +

+
+
rotate
+

Rotate the input frame clockwise by the specified angle. +

+
+
‘0, 360’
+
‘90’
+
‘180’
+
‘270’
+
+ +
+
fps
+

Set the output frame rate. This can be rational, e.g. 60000/1001. If +set to the special string none (the default), input timestamps will +instead be passed through to the output unmodified. Otherwise, the input video +frames will be interpolated as necessary to rescale the video to the specified +target framerate, in a manner as determined by the frame_mixer option. +

+
+
format
+

Set the output format override. If unset (the default), frames will be output +in the same format as the respective input frames. Otherwise, format conversion +will be performed. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. Note that +force_divisible_by also works with fit_sense=constraint. +

+
+
reset_sar
+

If enabled, output frames will always have a pixel aspect ratio of 1:1. If +disabled (the default), any aspect ratio mismatches, including those from +e.g. anamorphic video sources, are forwarded to the output pixel aspect ratio. +

+
+
normalize_sar
+

Like reset_sar, but instead of stretching the video content to fill +the new output aspect ratio, the content is instead padded or cropped as +necessary. Mutually exclusive with fit_mode. Disabled by default. +

+
+
pad_crop_ratio
+

Specifies a ratio (between 0.0 and 1.0) between padding and +cropping when the input aspect ratio does not match the output aspect ratio and +normalize_sar is in effect. The default of 0.0 always pads the +content with black borders, while a value of 1.0 always crops off parts +of the content. Intermediate values are possible, leading to a mix of the two +approaches. +

+
+
fit_mode
+

Specify the content fit strategy according to a list of predefined modes. +Determines how the input image is to be placed inside the destination crop +rectangle (as defined by pos_x/y and pos_w/h). The names and +their implementations are taken from the CSS ’object-fit’ property. Note that +this option is mutually exclusive with normalize_sar. Defaults to +fill. Valid values are: +

+
+
‘fill’
+

Stretch the input to the output rectangle, ignoring aspect ratio mismatches. +Note that unless reset_sar is also enabled, the output will still +have the correct pixel aspect ratio tagged. +

+
+
‘contain’
+

Scale the input to fit inside the output, preserving aspect ratio by padding. +Equivalent to normalize_sar with pad_crop_ratio set to +0.0. +

+
+
‘cover’
+

Scale the input to fill the output, preserving aspect ratio by cropping. +Equivalent to normalize_sar with pad_crop_ratio set to +1.0. +

+
+
‘none, place’
+

Don’t scale the input. The input will be placed inside the output rectangle at +its natural size; which may result in additional padding or cropping. +

+
+
‘scale_down’
+

Scale the input down as much as needed to fit inside the output. Equivalent +to either contain or none, depending on whether the input is +larger than the output or not. +

+
+ +
+
fit_sense
+

When fit_mode is in use, this option controls how the fit strategy +is applied against the specified output resolution. Mutually exclusive with +force_original_aspect_ratio. Valid values are: +

+
+
‘target’
+

The computed output resolution is taken as the exact size of the output frame. +This is the default behavior. +

+
+
‘constraint’
+

The computed output resolution is a size reference against which the fit mode +is applied, enlarging or decreasing the true frame size as needed to fit the +content. +

+
+ +
+
fillcolor
+

Set the color used to fill the output area not covered by the output image, for +example as a result of normalize_sar. For the general syntax of this +option, check the "Color" section in the ffmpeg-utils +manual. Defaults to black@0. +

+
+
corner_rounding
+

Render frames with rounded corners. The value, given as a float ranging from +0.0 to 1.0, indicates the relative degree of rounding, from fully +square to fully circular. In other words, it gives the radius divided by half +the smaller side length. Defaults to 0.0. +

+
+
lut
+

Specifies a custom LUT (in Adobe .cube format) to apply to the colors +as part of color conversion. The exact interpretation depends on the value +of lut_type. +

+
+
lut_type
+

Controls the interpretation of color values fed to and from the LUT +specified as lut. Valid values are: +

+
+
‘auto’
+

Chooses the interpretation of the LUT automatically from tagged +metadata, and otherwise falls back to ‘native’. (Default) +

+
+
‘native’
+

Applied to raw image contents in its native RGB colorspace (non-linear +light), before conversion to the output color space. +

+
+
‘normalized’
+

Applied to the normalized RGB image contents, in linear light, before +conversion to the output color space. +

+
+
‘conversion’
+

Fully replaces the conversion from the image color space to the output +color space. If such a LUT is present, it has the highest priority, and +overrides any ICC profiles, as well as options related to tone mapping +and output colorimetry (color_primaries, color_trc). +

+
+
+ +
+
extra_opts
+

Pass extra libplacebo internal configuration options. These can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to configure a custom filter kernel ("EWA LanczosSharp") and use it +to double the input image resolution: +

+
+
-vf "libplacebo=w=iw*2:h=ih*2:extra_opts='upscaler=custom\:upscaler_preset=ewa_lanczos\:upscaler_blur=0.9812505644269356'"
+
+ + +
+
shader_cache
+

File path of a cache directory that libplacebo will use to store and load +cached shader objects. This cache is not cleaned up automatically. If the +path does not end in a directory separator, the generated filenames will be +effectively prefixed by the last path component. All directories must already +exist. +

+
+
-vf "libplacebo=shader_cache=/tmp/pl-shader-"
+
+ +
+
colorspace
+
color_primaries
+
color_trc
+
range
+
chroma_location
+

Configure the colorspace that output frames will be delivered in. The default +value of auto outputs frames in the same format as the input frames, +leading to no change. For any other value, conversion will be performed. +

+

See the setparams filter for a list of possible values. +

+
+
alpha_mode
+

Choose the desired output alpha mode, when the output format has an alpha +channel. See the setparams filter for a list of possible values. +

+
+
apply_filmgrain
+

Apply film grain (e.g. AV1 or H.274) if present in source frames, and strip +it from the output. Enabled by default. +

+
+
apply_dolbyvision
+

Apply Dolby Vision RPU metadata if present in source frames, and strip it from +the output. Enabled by default. Note that Dolby Vision will always output +BT.2020+PQ, overriding the usual input frame metadata. These will also be +picked as the values of auto for the respective frame output options. +

+
+ +

In addition to the expression constants documented for the scale filter, +the crop_w, crop_h, crop_x, crop_y, +pos_w, pos_h, pos_x and pos_y options can +also contain the following constants: +

+
+
in_idx, idx
+

The (0-based) numeric index of the currently active input stream. +

+
crop_w, cw
+
crop_h, ch
+

The computed values of crop_w and crop_h. +

+
+
pos_w, pw
+
pos_h, ph
+

The computed values of pos_w and pos_h. +

+
+
in_t, t
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
out_t, ot
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
n
+

The input frame number, starting with 0. +

+
+ + +

39.144.1.2 Scaling

+

The options in this section control how libplacebo performs upscaling and (if +necessary) downscaling. Note that libplacebo will always internally operate on +4:4:4 content, so any sub-sampled chroma formats such as yuv420p will +necessarily be upsampled and downsampled as part of the rendering process. That +means scaling might be in effect even if the source and destination resolution +are the same. +

+
upscaler
+
downscaler
+

Configure the filter kernel used for upscaling and downscaling. The respective +defaults are spline36 and mitchell. For a full list of possible +values, pass help to these options. The most important values are: +

+
‘none’
+

Forces the use of built-in GPU texture sampling (typically bilinear). Extremely +fast but poor quality, especially when downscaling. +

+
+
‘bilinear’
+

Bilinear interpolation. Can generally be done for free on GPUs, except when +doing so would lead to aliasing. Fast and low quality. +

+
+
‘nearest’
+

Nearest-neighbour interpolation. Sharp but highly aliasing. +

+
+
‘oversample’
+

Algorithm that looks visually similar to nearest-neighbour interpolation but +tries to preserve pixel aspect ratio. Good for pixel art, since it results in +minimal distortion of the artistic appearance. +

+
+
‘lanczos’
+

Standard sinc-sinc interpolation kernel. +

+
+
‘spline36’
+

Cubic spline approximation of lanczos. No difference in performance, but has +very slightly less ringing. +

+
+
‘ewa_lanczos’
+

Elliptically weighted average version of lanczos, based on a jinc-jinc kernel. +This is also popularly referred to as just "Jinc scaling". Slow but very high +quality. +

+
+
‘gaussian’
+

Gaussian kernel. Has certain ideal mathematical properties, but subjectively +very blurry. +

+
+
‘mitchell’
+

Cubic BC spline with parameters recommended by Mitchell and Netravali. Very +little ringing. +

+
+ +
+
frame_mixer
+

Controls the kernel used for mixing frames temporally. The default value is +none, which disables frame mixing. For a full list of possible values, +pass help to this option. The most important values are: +

+
‘none’
+

Disables frame mixing, giving a result equivalent to "nearest neighbour" +semantics. +

+
+
‘oversample’
+

Oversamples the input video to create a "Smooth Motion"-type effect: if an +output frame would exactly fall on the transition between two video frames, it +is blended according to the relative overlap. This is the recommended option +whenever preserving the original subjective appearance is desired. +

+
+
‘mitchell_clamp’
+

Larger filter kernel that smoothly interpolates multiple frames in a manner +designed to eliminate ringing and other artefacts as much as possible. This is +the recommended option wherever maximum visual smoothness is desired. +

+
+
‘linear’
+

Linear blend/fade between frames. Especially useful for constructing e.g. +slideshows. +

+
+ +
+
antiringing
+

Enables anti-ringing (for non-EWA filters). The value (between 0.0 and +1.0) configures the strength of the anti-ringing algorithm. May increase +aliasing if set too high. Disabled by default. +

+
+
sigmoid
+

Enable sigmoidal compression during upscaling. Reduces ringing slightly. +Enabled by default. +

+
+ + +

39.144.1.3 Deinterlacing

+

Deinterlacing is automatically supported when frames are tagged as interlaced, +however frames are not deinterlaced unless a deinterlacing algorithm is chosen. +

+
deinterlace
+

The the deinterlacing algorithm to use. +

+
‘weave’
+

No deinterlacing, weave fields together into a single frame. This is the default. +

+
‘bob’
+

Naive bob deinterlacing, simply repeat each field line twice. +

+
‘yadif’
+

Yet another deinterlacing filter. See the yadif filter for more details. +

+
‘bwdif’
+

Bob weaver deinterlacing filter. See the bwdif filter for more details. +

+
+ +
+
skip_spatial_check
+

Skip the spatial deinterlacing check when using yadif deinterlacing. +

+
+
send_fields
+

Output a frame for each field, rather than for each frame. Note that this will +always double the tagged output frame rate, even if the input does not contain +any interlaced frames. Disabled by default. +

+
+ + +

39.144.1.4 Debanding

+

Libplacebo comes with a built-in debanding filter that is good at counteracting +many common sources of banding and blocking. Turning this on is highly +recommended whenever quality is desired. +

+
deband
+

Enable (fast) debanding algorithm. Disabled by default. +

+
+
deband_iterations
+

Number of deband iterations of the debanding algorithm. Each iteration is +performed with progressively increased radius (and diminished threshold). +Recommended values are in the range 1 to 4. Defaults to 1. +

+
+
deband_threshold
+

Debanding filter strength. Higher numbers lead to more aggressive debanding. +Defaults to 4.0. +

+
+
deband_radius
+

Debanding filter radius. A higher radius is better for slow gradients, while +a lower radius is better for steep gradients. Defaults to 16.0. +

+
+
deband_grain
+

Amount of extra output grain to add. Helps hide imperfections. Defaults to +6.0. +

+
+ + +

39.144.1.5 Color adjustment

+

A collection of subjective color controls. Not very rigorous, so the exact +effect will vary somewhat depending on the input primaries and colorspace. +

+
brightness
+

Brightness boost, between -1.0 and 1.0. Defaults to 0.0. +

+
+
contrast
+

Contrast gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
saturation
+

Saturation gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
hue
+

Hue shift in radians, between -3.14 and 3.14. Defaults to +0.0. This will rotate the UV subvector, defaulting to BT.709 +coefficients for RGB inputs. +

+
+
gamma
+

Gamma adjustment, between 0.0 and 16.0. Defaults to 1.0. +

+
+
temperature
+

Color temperature adjustment. Lower values make the output warmer/redder, +down to 1667, while higher values make the output cooler/bluer, up to +25000. Defaults to 6500 (neutral white). +

+
+
cones
+

Cone model to use for color blindness simulation. Accepts any combination of +l, m and s. Here are some examples: +

+
‘m’
+

Deuteranomaly / deuteranopia (affecting 3%-4% of the population) +

+
‘l’
+

Protanomaly / protanopia (affecting 1%-2% of the population) +

+
‘l+m’
+

Monochromacy (very rare) +

+
‘l+m+s’
+

Achromatopsy (complete loss of daytime vision, extremely rare) +

+
+ +
+
cone-strength
+

Gain factor for the cones specified by cones, between 0.0 and +10.0. A value of 1.0 results in no change to color vision. A +value of 0.0 (the default) simulates complete loss of those cones. Values +above 1.0 result in exaggerating the differences between cones, which +may help compensate for reduced color vision. +

+
+ + +

39.144.1.6 Peak detection

+

To help deal with sources that only have static HDR10 metadata (or no tagging +whatsoever), libplacebo uses its own internal frame analysis compute shader to +analyze source frames and adapt the tone mapping function in realtime. If this +is too slow, or if exactly reproducible frame-perfect results are needed, it’s +recommended to turn this feature off. +

+
peak_detect
+

Enable HDR peak detection. Ignores static MaxCLL/MaxFALL values in favor of +dynamic detection from the input. Note that the detected values do not get +written back to the output frames, they merely guide the internal tone mapping +process. Enabled by default. +

+
+
smoothing_period
+

Peak detection smoothing period, between 0.0 and 1000.0. Higher +values result in peak detection becoming less responsive to changes in the +input. Defaults to 20.0. +

+
+
scene_threshold_low
+
scene_threshold_high
+

Lower and upper thresholds for scene change detection. Expressed in a +logarithmic scale between 0.0 and 100.0. Default to 1.0 +and 3.0, respectively. Setting either to a negative value disables +this functionality. +

+
+
percentile
+

Which percentile of the frame brightness histogram to use as the source peak +for tone-mapping. Defaults to 99.995, a fairly conservative value. +Setting this to 100.0 disables frame histogram measurement and instead +uses the true peak brightness for tone-mapping. +

+
+ + +

39.144.1.7 Tone mapping

+

The options in this section control how libplacebo performs tone-mapping and +gamut-mapping when dealing with mismatches between wide-gamut or HDR content. +In general, libplacebo relies on accurate source tagging and mastering display +gamut information to produce the best results. +

+
gamut_mode
+

How to handle out-of-gamut colors that can occur as a result of colorimetric +gamut mapping. +

+
‘clip’
+

Do nothing, simply clip out-of-range colors to the RGB volume. Low quality but +extremely fast. +

+
‘perceptual’
+

Perceptually soft-clip colors to the gamut volume. This is the default. +

+
‘relative’
+

Relative colorimetric hard-clip. Similar to perceptual but without +the soft knee. +

+
‘saturation’
+

Saturation mapping, maps primaries directly to primaries in RGB space. +Not recommended except for artificial computer graphics for which a bright, +saturated display is desired. +

+
‘absolute’
+

Absolute colorimetric hard-clip. Performs no adjustment of the white point. +

+
‘desaturate’
+

Hard-desaturates out-of-gamut colors towards white, while preserving the +luminance. Has a tendency to distort the visual appearance of bright objects. +

+
‘darken’
+

Linearly reduces content brightness to preserves saturated details, followed by +clipping the remaining out-of-gamut colors. +

+
‘warn’
+

Highlight out-of-gamut pixels (by inverting/marking them). +

+
‘linear’
+

Linearly reduces chromaticity of the entire image to make it fit within the +target color volume. Be careful when using this on BT.2020 sources without +proper mastering metadata, as doing so will lead to excessive desaturation. +

+
+ +
+
tonemapping
+

Tone-mapping algorithm to use. Available values are: +

+
‘auto’
+

Automatic selection based on internal heuristics. This is the default. +

+
‘clip’
+

Performs no tone-mapping, just clips out-of-range colors. Retains perfect color +accuracy for in-range colors but completely destroys out-of-range information. +Does not perform any black point adaptation. Not configurable. +

+
‘st2094-40’
+

EETF from SMPTE ST 2094-40 Annex B, which applies the Bezier curves from HDR10+ +dynamic metadata based on Bezier curves to perform tone-mapping. The OOTF used +is adjusted based on the ratio between the targeted and actual display peak +luminances. +

+
‘st2094-10’
+

EETF from SMPTE ST 2094-10 Annex B.2, which takes into account the input signal +average luminance in addition to the maximum/minimum. The configurable contrast +parameter influences the slope of the linear output segment, defaulting to +1.0 for no increase/decrease in contrast. Note that this does not +currently include the subjective gain/offset/gamma controls defined in Annex +B.3. +

+
‘bt.2390’
+

EETF from the ITU-R Report BT.2390, a hermite spline roll-off with linear +segment. The knee point offset is configurable. Note that this parameter +defaults to 1.0, rather than the value of 0.5 from the ITU-R +spec. +

+
‘bt.2446a’
+

EETF from ITU-R Report BT.2446, method A. Designed for well-mastered HDR +sources. Can be used for both forward and inverse tone mapping. Not +configurable. +

+
‘spline’
+

Simple spline consisting of two polynomials, joined by a single pivot point. +The parameter gives the pivot point (in PQ space), defaulting to 0.30. +Can be used for both forward and inverse tone mapping. +

+
‘reinhard’
+

Simple non-linear, global tone mapping algorithm. The parameter specifies the +local contrast coefficient at the display peak. Essentially, a parameter of +0.5 implies that the reference white will be about half as bright as +when clipping. Defaults to 0.5, which results in the simplest +formulation of this function. +

+
‘mobius’
+

Generalization of the reinhard tone mapping algorithm to support an additional +linear slope near black. The tone mapping parameter indicates the trade-off +between the linear section and the non-linear section. Essentially, for a given +parameter x, every color value below x will be mapped linearly, +while higher values get non-linearly tone-mapped. Values near 1.0 make +this curve behave like clip, while values near 0.0 make this +curve behave like reinhard. The default value is 0.3, which +provides a good balance between colorimetric accuracy and preserving +out-of-gamut details. +

+
‘hable’
+

Piece-wise, filmic tone-mapping algorithm developed by John Hable for use in +Uncharted 2, inspired by a similar tone-mapping algorithm used by Kodak. +Popularized by its use in video games with HDR rendering. Preserves both dark +and bright details very well, but comes with the drawback of changing the +average brightness quite significantly. This is sort of similar to +reinhard with parameter 0.24. +

+
‘gamma’
+

Fits a gamma (power) function to transfer between the source and target color +spaces, effectively resulting in a perceptual hard-knee joining two roughly +linear sections. This preserves details at all scales fairly accurately, but +can result in an image with a muted or dull appearance. The parameter is used +as the cutoff point, defaulting to 0.5. +

+
‘linear’
+

Linearly stretches the input range to the output range, in PQ space. This will +preserve all details accurately, but results in a significantly different +average brightness. Can be used for inverse tone-mapping in addition to regular +tone-mapping. The parameter can be used as an additional linear gain +coefficient (defaulting to 1.0). +

+
+ +
+
tonemapping_param
+

For tunable tone mapping functions, this parameter can be used to fine-tune the +curve behavior. Refer to the documentation of tonemapping. The default +value of 0.0 is replaced by the curve’s preferred default setting. +

+
+
inverse_tonemapping
+

If enabled, this filter will also attempt stretching SDR signals to fill HDR +output color volumes. Disabled by default. +

+
+
tonemapping_lut_size
+

Size of the tone-mapping LUT, between 2 and 1024. Defaults to +256. Note that this figure is squared when combined with +peak_detect. +

+
+
contrast_recovery
+

Contrast recovery strength. If set to a value above 0.0, the source +image will be divided into high-frequency and low-frequency components, and a +portion of the high-frequency image is added back onto the tone-mapped output. +May cause excessive ringing artifacts for some HDR sources, but can improve the +subjective sharpness and detail left over in the image after tone-mapping. +Defaults to 0.30. +

+
+
contrast_smoothness
+

Contrast recovery lowpass kernel size. Defaults to 3.5. Increasing or +decreasing this will affect the visual appearance substantially. Has no effect +when contrast_recovery is disabled. +

+
+ + +

39.144.1.8 Dithering

+

By default, libplacebo will dither whenever necessary, which includes rendering +to any integer format below 16-bit precision. It’s recommended to always leave +this on, since not doing so may result in visible banding in the output, even +if the debanding filter is enabled. If maximum performance is needed, +use ordered_fixed instead of disabling dithering. +

+
dithering
+

Dithering method to use. Accepts the following values: +

+
‘none’
+

Disables dithering completely. May result in visible banding. +

+
‘blue’
+

Dither with pseudo-blue noise. This is the default. +

+
‘ordered’
+

Tunable ordered dither pattern. +

+
‘ordered_fixed’
+

Faster ordered dither with a fixed size of 6. Texture-less. +

+
‘white’
+

Dither with white noise. Texture-less. +

+
+ +
+
dither_lut_size
+

Dither LUT size, as log base2 between 1 and 8. Defaults to +6, corresponding to a LUT size of 64x64. +

+
+
dither_temporal
+

Enables temporal dithering. Disabled by default. +

+
+ + +

39.144.1.9 Custom shaders

+

libplacebo supports a number of custom shaders based on the mpv .hook GLSL +syntax. A collection of such shaders can be found here: +https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders +

+

A full description of the mpv shader format is beyond the scope of this +section, but a summary can be found here: +https://mpv.io/manual/master/#options-glsl-shader +

+
custom_shader_path
+

Specifies a path to a custom shader file to load at runtime. +

+
+
custom_shader_bin
+

Specifies a complete custom shader as a raw string. +

+
+ + +

39.144.1.10 Debugging / performance

+

All of the options in this section default off. They may be of assistance when +attempting to squeeze the maximum performance at the cost of quality. +

+
skip_aa
+

Disable anti-aliasing when downscaling. +

+
+
disable_linear
+

Disable linear light scaling. +

+
+
disable_builtin
+

Disable built-in GPU sampling (forces LUT). +

+
+
disable_fbos
+

Forcibly disable FBOs, resulting in loss of almost all functionality, but +offering the maximum possible speed. +

+
+ + +

39.144.2 Commands

+

This filter supports almost all of the above options as commands. +

+ +

39.144.3 Examples

+
    +
  • Tone-map input to standard gamut BT.709 output: +
    +
    libplacebo=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv
    +
    + +
  • Rescale input to fit into standard 1080p, with high quality scaling: +
    +
    libplacebo=w=1920:h=1080:force_original_aspect_ratio=decrease:normalize_sar=true:upscaler=ewa_lanczos:downscaler=ewa_lanczos
    +
    + +
  • Interpolate low FPS / VFR input to smoothed constant 60 fps output: +
    +
    libplacebo=fps=60:frame_mixer=mitchell_clamp
    +
    + +
  • Convert input to standard sRGB JPEG: +
    +
    libplacebo=format=yuv420p:colorspace=bt470bg:color_primaries=bt709:color_trc=iec61966-2-1:range=pc
    +
    + +
  • Use higher quality debanding settings: +
    +
    libplacebo=deband=true:deband_iterations=3:deband_radius=8:deband_threshold=6
    +
    + +
  • Run this filter on the CPU, on systems with Mesa installed (and with the most +expensive options disabled): +
    +
    ffmpeg ... -init_hw_device vulkan:llvmpipe ... -vf libplacebo=upscaler=none:downscaler=none:peak_detect=false
    +
    + +
  • Suppress CPU-based AV1/H.274 film grain application in the decoder, in favor of +doing it with this filter. Note that this is only a gain if the frames are +either already on the GPU, or if you’re using libplacebo for other purposes, +since otherwise the VRAM roundtrip will more than offset any expected speedup. +
    +
    ffmpeg -export_side_data +film_grain ... -vf libplacebo=apply_filmgrain=true
    +
    + +
  • Interop with VAAPI hwdec to avoid round-tripping through RAM: +
    +
    ffmpeg -init_hw_device vulkan -hwaccel vaapi -hwaccel_output_format vaapi ... -vf libplacebo
    +
    +
+ + +

39.145 libvmaf

+ +

Calculate the VMAF (Video Multi-Method Assessment Fusion) score for a +reference/distorted pair of input videos. +

+

The first input is the distorted video, and the second input is the reference video. +

+

The obtained VMAF score is printed through the logging system. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-libvmaf. +

+

The filter has following options: +

+
+
model
+

A ‘|‘ delimited list of vmaf models. Each model can be configured with a number of parameters. +Default value: "version=vmaf_v0.6.1" +

+
+
feature
+

A ‘|‘ delimited list of features. Each feature can be configured with a number of parameters. +

+
+
log_path
+

Set the file path to be used to store log files. +

+
+
log_fmt
+

Set the format of the log file (xml, json, csv, or sub). +

+
+
pool
+

Set the pool method to be used for computing vmaf. +Options are min, harmonic_mean or mean (default). +

+
+
n_threads
+

Set number of threads to be used when initializing libvmaf. +Default value: 0, no threads. +

+
+
n_subsample
+

Set frame subsampling interval to be used. +

+
+ +

This filter also supports the framesync options. +

+ +

39.145.1 Examples

+
    +
  • In the examples below, a distorted video distorted.mpg is +compared with a reference file reference.mpg. + +
  • Basic usage: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf=log_path=output.xml -f null -
    +
    + +
  • Example with multiple models: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='model=version=vmaf_v0.6.1\\:name=vmaf|version=vmaf_v0.6.1neg\\:name=vmaf_neg' -f null -
    +
    + +
  • Example with multiple additional features: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr|name=ciede' -f null -
    +
    + +
  • Example with options and different containers: +
    +
    ffmpeg -i distorted.mpg -i reference.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=log_fmt=json:log_path=output.json" -f null -
    +
    +
+ + +

39.146 libvmaf_cuda

+ +

This is the CUDA variant of the libvmaf filter. It only accepts CUDA frames. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-nonfree --enable-ffnvcodec --enable-libvmaf. +

+ +

39.146.1 Examples

+
    +
  • Basic usage showing CUVID hardware decoding and CUDA scaling with scale_cuda: +
    +
    ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i dis.obu \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i ref.obu \
    +    -filter_complex "
    +        [0:v]scale_cuda=format=yuv420p[dis]; \
    +        [1:v]scale_cuda=format=yuv420p[ref]; \
    +        [dis][ref]libvmaf_cuda=log_fmt=json:log_path=output.json
    +    " \
    +    -f null -
    +
    +
+ + +

39.147 limitdiff

+

Apply limited difference filter using second and optionally third video stream. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the threshold to use when allowing certain differences between video streams. +Any absolute difference value lower or exact than this threshold will pick pixel components from +first video stream. +

+
+
elasticity
+

Set the elasticity of soft thresholding when processing video streams. +This value multiplied with first one sets second threshold. +Any absolute difference value greater or exact than second threshold will pick pixel components +from second video stream. For values between those two threshold +linear interpolation between first and second video stream will be used. +

+
+
reference
+

Enable the reference (third) video stream processing. By default is disabled. +If set, this video stream will be used for calculating absolute difference with first video +stream. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

39.147.1 Commands

+ +

This filter supports the all above options as commands except option ‘reference’. +

+ +

39.148 limiter

+ +

Limits the pixel components values to the specified range [min, max]. +

+

The filter accepts the following options: +

+
+
min
+

Lower bound. Defaults to the lowest allowed value for the input. +

+
+
max
+

Upper bound. Defaults to the highest allowed value for the input. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

39.148.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.149 loop

+ +

Loop video frames. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal size in number of frames. Default is 0. +

+
+
start
+

Set first frame of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

39.149.1 Examples

+ +
    +
  • Loop single first frame infinitely: +
    +
    loop=loop=-1:size=1:start=0
    +
    + +
  • Loop single first frame 10 times: +
    +
    loop=loop=10:size=1:start=0
    +
    + +
  • Loop 10 first frames 5 times: +
    +
    loop=loop=5:size=10:start=0
    +
    +
+ + +

39.150 lut1d

+ +

Apply a 1D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 1D LUT file name. +

+

Currently supported formats: +

+
‘cube’
+

Iridas +

+
‘csp’
+

cineSpace +

+
+ +
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘linear’
+

Interpolate values using the linear interpolation. +

+
‘cosine’
+

Interpolate values using the cosine interpolation. +

+
‘cubic’
+

Interpolate values using the cubic interpolation. +

+
‘spline’
+

Interpolate values using the spline interpolation. +

+
+
+
+ + +

39.150.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.151 lut3d

+ +

Apply a 3D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 3D LUT file name. +

+

Currently supported formats: +

+
‘3dl’
+

AfterEffects +

+
‘cube’
+

Iridas +

+
‘dat’
+

DaVinci +

+
‘m3d’
+

Pandora +

+
‘csp’
+

cineSpace +

+
+
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘trilinear’
+

Interpolate values using the 8 points defining a cube. +

+
‘tetrahedral’
+

Interpolate values using a tetrahedron. +

+
‘pyramid’
+

Interpolate values using a pyramid. +

+
‘prism’
+

Interpolate values using a prism. +

+
+
+
+ + +

39.151.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

39.152 lumakey

+ +

Turn certain luma values into transparency. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the luma which will be used as base for transparency. +Default value is 0. +

+
+
tolerance
+

Set the range of luma values to be keyed out. +Default value is 0.01. +

+
+
softness
+

Set the range of softness. Default value is 0. +Use this to control gradual transition from zero to full transparency. +

+
+ + +

39.152.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.153 lut, lutrgb, lutyuv

+ +

Compute a look-up table for binding each pixel component input value +to an output value, and apply it to the input video. +

+

lutyuv applies a lookup table to a YUV input video, lutrgb +to an RGB input video. +

+

These filters accept the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
r
+

set red component expression +

+
g
+

set green component expression +

+
b
+

set blue component expression +

+
a
+

alpha component expression +

+
+
y
+

set Y/luma component expression +

+
u
+

set U/Cb component expression +

+
v
+

set V/Cr component expression +

+
+ +

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 c* options depends on the +format in input. +

+

The lut filter requires either YUV or RGB pixel formats in input, +lutrgb requires RGB pixel formats in input, and lutyuv requires YUV. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
clipval
+

The input value, clipped to the minval-maxval range. +

+
+
maxval
+

The maximum value for the pixel component. +

+
+
minval
+

The minimum value for the pixel component. +

+
+
negval
+

The negated value for the pixel component value, clipped to the +minval-maxval range; it corresponds to the expression +"maxval-clipval+minval". +

+
+
clip(val)
+

The computed value in val, clipped to the +minval-maxval range. +

+
+
gammaval(gamma)
+

The computed gamma correction value of the pixel component value, +clipped to the minval-maxval range. It corresponds to the +expression +"pow((clipval-minval)/(maxval-minval)\,gamma)*(maxval-minval)+minval" +

+
+
+ +

All expressions default to "clipval". +

+ +

39.153.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.153.2 Examples

+ +
    +
  • Negate input video: +
    +
    lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
    +lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
    +
    + +

    The above is the same as: +

    +
    lutrgb="r=negval:g=negval:b=negval"
    +lutyuv="y=negval:u=negval:v=negval"
    +
    + +
  • Negate luma: +
    +
    lutyuv=y=negval
    +
    + +
  • Remove chroma components, turning the video into a graytone image: +
    +
    lutyuv="u=128:v=128"
    +
    + +
  • Apply a luma burning effect: +
    +
    lutyuv="y=2*val"
    +
    + +
  • Remove green and blue components: +
    +
    lutrgb="g=0:b=0"
    +
    + +
  • Set a constant alpha channel value on input: +
    +
    format=rgba,lutrgb=a="maxval-minval/2"
    +
    + +
  • Correct luma gamma by a factor of 0.5: +
    +
    lutyuv=y=gammaval(0.5)
    +
    + +
  • Discard least significant bits of luma: +
    +
    lutyuv=y='bitand(val, 128+64+32)'
    +
    + +
  • Technicolor like effect: +
    +
    lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
    +
    +
+ + +

39.154 lut2, tlut2

+ +

The lut2 filter takes two input streams and outputs one +stream. +

+

The tlut2 (time lut2) filter takes two consecutive frames +from one single stream. +

+

This filter accepts the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
d
+

set output bit depth, only available for lut2 filter. By default is 0, +which means bit depth is automatically picked from first input format. +

+
+ +

The lut2 filter also supports the framesync options. +

+

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 c* options depends on the +format in inputs. +

+

The expressions can contain the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
x
+

The first input value for the pixel component. +

+
+
y
+

The second input value for the pixel component. +

+
+
bdx
+

The first input video bit depth. +

+
+
bdy
+

The second input video bit depth. +

+
+ +

All expressions default to "x". +

+ +

39.154.1 Commands

+ +

This filter supports the all above options as commands except option d. +

+ +

39.154.2 Examples

+ +
    +
  • Highlight differences between two RGB video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'
    +
    + +
  • Highlight differences between two YUV video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'
    +
    + +
  • Show max difference between two video streams: +
    +
    lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'
    +
    +
+ + +

39.155 maskedclamp

+ +

Clamp the first input stream with the second input and third input stream. +

+

Returns the value of first stream to be between second input +stream - undershoot and third input stream + overshoot. +

+

This filter accepts the following options: +

+
undershoot
+

Default value is 0. +

+
+
overshoot
+

Default value is 0. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

39.155.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.156 maskedmax

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is greater than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

39.156.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.157 maskedmerge

+ +

Merge the first input stream with the second input stream using per pixel +weights in the third input stream. +

+

A value of 0 in the third stream pixel component means that pixel component +from first stream is returned unchanged, while maximum value (eg. 255 for +8-bit videos) means that pixel component from second stream is returned +unchanged. Intermediate values define the amount of merging between both +input stream’s pixel components. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

39.157.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.158 maskedmin

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is less than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

39.158.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.159 maskedthreshold

+

Pick pixels comparing absolute difference of two video streams with fixed +threshold. +

+

If absolute difference between pixel component of first and second video +stream is equal or lower than user supplied threshold than pixel component +from first video stream is picked, otherwise pixel component from second +video stream is picked. +

+

This filter accepts the following options: +

+
threshold
+

Set threshold used when picking pixels from absolute difference from two input +video streams. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from second stream. +By default value 0xf, all planes will be processed. +

+
+
mode
+

Set mode of filter operation. Can be abs or diff. +Default is abs. +

+
+ + +

39.159.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.160 maskfun

+

Create mask from input video. +

+

For example it is useful to create motion masks after tblend filter. +

+

This filter accepts the following options: +

+
+
low
+

Set low threshold. Any pixel component lower or exact than this value will be set to 0. +

+
+
high
+

Set high threshold. Any pixel component higher than this value will be set to max value +allowed for current pixel format. +

+
+
planes
+

Set planes to filter, by default all available planes are filtered. +

+
+
fill
+

Fill all frame pixels with this value. +

+
+
sum
+

Set max average pixel value for frame. If sum of all pixel components is higher that this +average, output frame will be completely filled with value set by fill option. +Typically useful for scene changes when used in combination with tblend filter. +

+
+ + +

39.160.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.161 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: +

+
mode
+

Set the deinterlacing mode. +

+

It accepts one of the following values: +

+
‘fast’
+
‘medium’
+
‘slow’
+

use iterative motion estimation +

+
‘extra_slow’
+

like ‘slow’, but use multiple reference frames. +

+
+

Default value is ‘fast’. +

+
+
parity
+

Set the picture field parity assumed for the input video. It must be +one of the following values: +

+
+
‘0, tff’
+

assume top field first +

+
‘1, bff’
+

assume bottom field first +

+
+ +

Default value is ‘bff’. +

+
+
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. +

+
+ + +

39.162 median

+ +

Pick median pixel from certain rectangle defined by radius. +

+

This filter accepts the following options: +

+
+
radius
+

Set horizontal radius size. Default value is 1. +Allowed range is integer from 1 to 127. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+
radiusV
+

Set vertical radius size. Default value is 0. +Allowed range is integer from 0 to 127. +If it is 0, value will be picked from horizontal radius option. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

39.162.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.163 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: +

+
mapping
+

Set input to output plane mapping. Default is 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. +

+
+
format
+

Set output pixel format. Default is yuva444p. +

+
+
map0s
+
map1s
+
map2s
+
map3s
+

Set input to output stream mapping for output Nth plane. Default is 0. +

+
+
map0p
+
map1p
+
map2p
+
map3p
+

Set input to output plane mapping for output Nth plane. Default is 0. +

+
+ + +

39.163.1 Examples

+ +
    +
  • Merge three gray video streams of same width and height into single video stream: +
    +
    [a0][a1][a2]mergeplanes=0x001020:yuv444p
    +
    + +
  • Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: +
    +
    [a0][a1]mergeplanes=0x00010210:yuva444p
    +
    + +
  • Swap Y and A plane in yuva444p stream: +
    +
    format=yuva444p,mergeplanes=0x03010200:yuva444p
    +
    + +
  • Swap U and V plane in yuv420p stream: +
    +
    format=yuv420p,mergeplanes=0x000201:yuv420p
    +
    + +
  • Cast a rgb24 clip to yuv444p: +
    +
    format=rgb24,mergeplanes=0x000102:yuv444p
    +
    +
+ + +

39.164 mestimate

+ +

Estimate and export motion vectors using block matching algorithms. +Motion vectors are stored in frame side data to be used by other filters. +

+

This filter accepts the following options: +

+
method
+

Specify the motion estimation method. Accepts one of the following values: +

+
+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default value is ‘esa’. +

+
+
mb_size
+

Macroblock size. Default 16. +

+
+
search_param
+

Search parameter. Default 7. +

+
+ + +

39.165 mestimate_d3d12

+ +

Estimate and export motion vectors using D3D12 hardware-accelerated motion estimation. +This filter uses GPU hardware motion estimation capabilities available in +DirectX 12 Video APIs to achieve significant performance improvements +over the software-based mestimate filter. +

+

Motion vectors are stored in frame side data to be used by other filters. +

+

This filter requires the input to be in d3d12 hardware pixel format. +The filter uses quarter-pixel precision for motion vector estimation. +

+

This filter accepts the following options: +

+
mb_size
+

Macroblock size. Only 8 and 16 are supported. +Default 16. +

+
+ + +

39.165.1 Examples

+ +

Estimate motion vectors using D3D12 hardware acceleration with 16x16 blocks, +and visualize them: +

+
ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.mp4 \
+        -vf mestimate_d3d12=mb_size=16,hwdownload,format=nv12,codecview=mv=pf \
+        -c:v libx264 -preset fast -b:v 5M output.mp4
+
+ + +

39.166 midequalizer

+ +

Apply Midway Image Equalization effect using two video streams. +

+

Midway Image Equalization adjusts a pair of images to have the same +histogram, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a pair of stereo cameras. +

+

This filter has two inputs and one output, which must be of same pixel format, but +may be of different sizes. The output of filter is first input adjusted with +midway histogram of both inputs. +

+

This filter accepts the following option: +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

39.167 minterpolate

+ +

Convert the video to specified frame rate using motion interpolation. +

+

This filter accepts the following options: +

+
fps
+

Specify the output frame rate. This can be rational e.g. 60000/1001. Frames are dropped if fps is lower than source fps. Default 60. +

+
+
mi_mode
+

Motion interpolation mode. Following values are accepted: +

+
‘dup’
+

Duplicate previous or next frame for interpolating new ones. +

+
‘blend’
+

Blend source frames. Interpolated frame is mean of previous and next frames. +

+
‘mci’
+

Motion compensated interpolation. Following options are effective when this mode is selected: +

+
+
‘mc_mode’
+

Motion compensation mode. Following values are accepted: +

+
‘obmc’
+

Overlapped block motion compensation. +

+
‘aobmc’
+

Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. +

+
+

Default mode is ‘obmc’. +

+
+
‘me_mode’
+

Motion estimation mode. Following values are accepted: +

+
‘bidir’
+

Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. +

+
‘bilat’
+

Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. +

+
+

Default mode is ‘bilat’. +

+
+
‘me’
+

The algorithm to be used for motion estimation. Following values are accepted: +

+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default algorithm is ‘epzs’. +

+
+
‘mb_size’
+

Macroblock size. Default 16. +

+
+
‘search_param’
+

Motion estimation search parameter. Default 32. +

+
+
‘vsbmc’
+

Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make them less blurry. Default is 0 (disabled). +

+
+
+
+ +
+
scd
+

Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted: +

+
‘none’
+

Disable scene change detection. +

+
‘fdiff’
+

Frame difference. Corresponding pixel values are compared and if it satisfies scd_threshold scene change is detected. +

+
+

Default method is ‘fdiff’. +

+
+
scd_threshold
+

Scene change detection threshold. Default is 10.. +

+
+ + +

39.168 mix

+ +

Mix several video input streams into one video stream. +

+

A description of the accepted options follows. +

+
+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
weights
+

Specify weight of each input video stream as sequence. +Each weight is separated by space. If number of weights +is smaller than number of frames last specified +weight will be used for all remaining unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+
duration
+

Specify how end of stream is determined. +

+
‘longest’
+

The duration of the longest input. (default) +

+
+
‘shortest’
+

The duration of the shortest input. +

+
+
‘first’
+

The duration of the first input. +

+
+
+
+ + +

39.168.1 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

39.169 monochrome

+

Convert video to gray using custom color filter. +

+

A description of the accepted options follows. +

+
+
cb
+

Set the chroma blue spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
cr
+

Set the chroma red spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
size
+

Set the color filter size. Allowed range is from .1 to 10. +Default value is 1. +

+
+
high
+

Set the highlights strength. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

39.169.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.170 morpho

+ +

This filter allows to apply main morphological grayscale transforms, +erode and dilate with arbitrary structures set in second input stream. +

+

Unlike naive implementation and much slower performance in erosion +and dilation filters, when speed is critical morpho filter +should be used instead. +

+

A description of accepted options follows, +

+
+
mode
+

Set morphological transform to apply, can be: +

+
+
‘erode’
+
‘dilate’
+
‘open’
+
‘close’
+
‘gradient’
+
‘tophat’
+
‘blackhat’
+
+

Default is erode. +

+
+
planes
+

Set planes to filter, by default all planes except alpha are filtered. +

+
+
structure
+

Set which structure video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+ +

The morpho filter also supports the framesync options. +

+ +

39.170.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.171 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. +

+
+
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 disregarding the +number of previous sequentially dropped frames. +

+

Default value is 0. +

+
+
keep
+

Set the maximum number of consecutive similar frames to ignore before to start dropping them. +If the value is 0, the frame is dropped disregarding the +number of previous sequentially similar frames. +

+

Default value is 0. +

+
+
hi
+
lo
+
frac
+

Set the dropping threshold values. +

+

Values for hi and 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 hi, and if no more than frac blocks (1 +meaning the whole image) differ by more than a threshold of lo. +

+

Default value for hi is 64*12, default value for lo is +64*5, and default value for frac is 0.33. +

+
+ + +

39.172 msad

+ +

Obtain the MSAD (Mean Sum of Absolute Differences) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max MSAD is printed through +the logging system. +

+

The filter stores the calculated MSAD of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi msad -f null -
+
+ + +

39.173 multiply

+

Multiply first video stream pixels values with second video stream pixels values. +

+

The filter accepts the following options: +

+
+
scale
+

Set the scale applied to second video stream. By default is 1. +Allowed range is from 0 to 9. +

+
+
offset
+

Set the offset applied to second video stream. By default is 0.5. +Allowed range is from -1 to 1. +

+
+
planes
+

Specify planes from input video stream that will be processed. +By default all planes are processed. +

+
+ + +

39.173.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.174 negate

+ +

Negate (invert) the input video. +

+

It accepts the following option: +

+
+
components
+

Set components to negate. +

+

Available values for components are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +
+
negate_alpha
+

With value 1, it negates the alpha component, if present. Default value is 0. +

+
+ + +

39.174.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.175 nlmeans

+ +

Denoise frames using Non-Local Means algorithm. +

+

Each pixel is adjusted by looking for other pixels with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +pxp. Patches are searched in an area of rxr +around the pixel. +

+

Note that the research area defines centers for patches, which means some +patches will be made of pixels outside that research area. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0]. +

+
+
p
+

Set patch size. Default is 7. Must be odd number in range [0, 99]. +

+
+
pc
+

Same as p but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
rc
+

Same as r but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+ + +

39.176 nnedi

+ +

Deinterlace video using neural network edge directed interpolation. +

+

This filter accepts the following options: +

+
+
weights
+

Mandatory option, without binary file filter can not work. +Currently file can be found here: +https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin +

+
+
deint
+

Set which frames to deinterlace, by default it is all. +Can be all or interlaced. +

+
+
field
+

Set mode of operation. +

+

Can be one of the following: +

+
+
‘af’
+

Use frame flags, both fields. +

+
‘a’
+

Use frame flags, single field. +

+
‘t’
+

Use top field only. +

+
‘b’
+

Use bottom field only. +

+
‘tf’
+

Use both fields, top first. +

+
‘bf’
+

Use both fields, bottom first. +

+
+ +
+
planes
+

Set which planes to process, by default filter process all frames. +

+
+
nsize
+

Set size of local neighborhood around each pixel, used by the predictor neural +network. +

+

Can be one of the following: +

+
+
‘s8x6’
+
‘s16x6’
+
‘s32x6’
+
‘s48x6’
+
‘s8x4’
+
‘s16x4’
+
‘s32x4’
+
+ +
+
nns
+

Set the number of neurons in predictor neural network. +Can be one of the following: +

+
+
‘n16’
+
‘n32’
+
‘n64’
+
‘n128’
+
‘n256’
+
+ +
+
qual
+

Controls the number of different neural network predictions that are blended +together to compute the final output value. Can be fast, default or +slow. +

+
+
etype
+

Set which set of weights to use in the predictor. +Can be one of the following: +

+
+
‘a, abs’
+

weights trained to minimize absolute error +

+
‘s, mse’
+

weights trained to minimize squared error +

+
+ +
+
pscrn
+

Controls whether or not the prescreener neural network is used to decide +which pixels should be processed by the predictor neural network and which +can be handled by simple cubic interpolation. +The prescreener is trained to know whether cubic interpolation will be +sufficient for a pixel or whether it should be predicted by the predictor nn. +The computational complexity of the prescreener nn is much less than that of +the predictor nn. Since most pixels can be handled by cubic interpolation, +using the prescreener generally results in much faster processing. +The prescreener is pretty accurate, so the difference between using it and not +using it is almost always unnoticeable. +

+

Can be one of the following: +

+
+
‘none’
+
‘original’
+
‘new’
+
‘new2’
+
‘new3’
+
+ +

Default is new. +

+
+ + +

39.176.1 Commands

+

This filter supports same commands as options, excluding weights option. +

+ +

39.177 noformat

+ +

Force libavfilter not to use any of the specified pixel formats for the +input to the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +pix_fmts=yuv420p|monow|rgb24". +

+
+
+ + +

39.177.1 Examples

+ +
    +
  • Force libavfilter to use a format different from yuv420p for the +input to the vflip filter: +
    +
    noformat=pix_fmts=yuv420p,vflip
    +
    + +
  • Convert the input video to any of the formats not contained in the list: +
    +
    noformat=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

39.178 noise

+ +

Add noise on video input frame. +

+

The filter accepts the following options: +

+
+
all_seed
+
c0_seed
+
c1_seed
+
c2_seed
+
c3_seed
+

Set noise seed for specific pixel component or all pixel components in case +of all_seed. Default value is 123457. +

+
+
all_strength, alls
+
c0_strength, c0s
+
c1_strength, c1s
+
c2_strength, c2s
+
c3_strength, c3s
+

Set noise strength for specific pixel component or all pixel components in case +all_strength. Default value is 0. Allowed range is [0, 100]. +

+
+
all_flags, allf
+
c0_flags, c0f
+
c1_flags, c1f
+
c2_flags, c2f
+
c3_flags, c3f
+

Set pixel component flags or set flags for all components if all_flags. +Available values for component flags are: +

+
‘a’
+

averaged temporal noise (smoother) +

+
‘p’
+

mix random noise with a (semi)regular pattern +

+
‘t’
+

temporal noise (noise pattern changes between frames) +

+
‘u’
+

uniform noise (gaussian otherwise) +

+
+
+
+ + +

39.178.1 Examples

+ +

Add temporal and uniform noise to input video: +

+
noise=alls=20:allf=t+u
+
+ + +

39.179 normalize

+ +

Normalize RGB video (aka histogram stretching, contrast stretching). +See: https://en.wikipedia.org/wiki/Normalization_(image_processing) +

+

For each channel of each frame, the filter computes the input range and maps +it linearly to the user-specified output range. The output range defaults +to the full dynamic range from pure black to pure white. +

+

Temporal smoothing can be used on the input range to reduce flickering (rapid +changes in brightness) caused when small dark or bright objects enter or leave +the scene. This is similar to the auto-exposure (automatic gain control) on a +video camera, and, like a video camera, it may cause a period of over- or +under-exposure of the video. +

+

The R,G,B channels can be normalized independently, which may cause some +color shifting, or linked together as a single channel, which prevents +color shifting. Linked normalization preserves hue. Independent normalization +does not, so it can be used to remove some color casts. Independent and linked +normalization can be combined in any ratio. +

+

The normalize filter accepts the following options: +

+
+
blackpt
+
whitept
+

Colors which define the output range. The minimum input value is mapped to +the blackpt. The maximum input value is mapped to the whitept. +The defaults are black and white respectively. Specifying white for +blackpt and black for whitept will give color-inverted, +normalized video. Shades of grey can be used to reduce the dynamic range +(contrast). Specifying saturated colors here can create some interesting +effects. +

+
+
smoothing
+

The number of previous frames to use for temporal smoothing. The input range +of each channel is smoothed using a rolling average over the current frame +and the smoothing previous frames. The default is 0 (no temporal +smoothing). +

+
+
independence
+

Controls the ratio of independent (color shifting) channel normalization to +linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully +independent. Defaults to 1.0 (fully independent). +

+
+
strength
+

Overall strength of the filter. 1.0 is full strength. 0.0 is a rather +expensive no-op. Defaults to 1.0 (full strength). +

+
+
+ + +

39.179.1 Commands

+

This filter supports same commands as options, excluding smoothing option. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.179.2 Examples

+ +

Stretch video contrast to use the full dynamic range, with no temporal +smoothing; may flicker depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=0
+
+ +

As above, but with 50 frames of temporal smoothing; flicker should be +reduced, depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=50
+
+ +

As above, but with hue-preserving linked channel normalization: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0
+
+ +

As above, but with half strength: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
+
+ +

Map the darkest input color to red, the brightest input color to cyan: +

+
normalize=blackpt=red:whitept=cyan
+
+ + +

39.180 null

+ +

Pass the video source unchanged to the output. +

+ +

39.181 ocio

+

OpenColorIO library filter +

+

This filter allows you to do color management using the OpenColorIO library. +See https://opencolorio.org/ for more details. To Enable +compilation of this filter, you need to configure FFmpeg with --enable-libopencolorio. +

+

It accepts the following options: +

+
+
config
+

By default the filter will use the OCIO config defined by the OCIO environment variable, but this parameter allows you to explicitly specify its location. +If you are getting started, you can use config=ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1 which specifies one of the built in defaults. +

+
+
input
+

Set the input colorspace. +

+
+
output
+

Set the output colorspace. +

+
+
display
+

Set the display colorspace, used in combination with view. +

+
+
view
+

Set the view colorspace, used in combination with display. +

+
+
inverse
+

When used in combination with display and view, this inverts the transform, so going from a display/view to the "input colorspace". +

+
+
filetransform
+

Allows you to specify an external file-transform to use instead of the OCIO config file. This is useful for applying a single transform without needing a full OCIO config file. +

+
+
format
+

Allow you to specify the output pix_fmt of the OCIO filter. This *has* to be a RGB colorspace, so you really are limited to rgb24, rgba, rgb48, rgba48, gbrp10, gbrp12, gbrpf32le, gbrapf32le, for most encoding we would recommend rgb48 +

+
+
context_params
+

Allow you to specify additional context parameters for the OCIO filter. This is a list of key=value pairs, separated by colons. +

+
+
+ + +

39.181.1 Examples

+ +

Map from ACEScg to ACEScct, this assumes the OCIO file is defined with the OCIO environment variable. +

+
input=ACEScg:output=ACEScct:format=rgb48
+
+ +

Map from ACEScg to a sRGB display using the "ACES 1.0 - SDR Video" view transform, this assumes the OCIO file is defined with the OCIO environment variable. Note you will need to wrap the argument in quotes to ensure that the spaces are interpreted correctly. +

+
input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ + +

As above but using the OCIO file studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio rather than the OCIO environment variable. +

+
config=studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio:input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ +

If you are converting to YCrCb you still will want to set the color matrix for the conversion. This is a good example of combining the two. +

+
ffmpeg -y -i SOURCEFRAMES.%05d.exr -c:v libx265 -vf "ocio=input=ACEScg:output=ACEScct:format=rgb48,scale=in_color_matrix=bt709:out_color_matrix=bt709,format=yuv444p10"  OUTPUTFILE.mov
+
+ + +

39.182 ocr

+

Optical Character Recognition +

+

This filter uses Tesseract for optical character recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-libtesseract. +

+

It accepts the following options: +

+
+
datapath
+

Set datapath to tesseract data. Default is to use whatever was +set at installation. +

+
+
language
+

Set language, default is "eng". +

+
+
whitelist
+

Set character whitelist. +

+
+
blacklist
+

Set character blacklist. +

+
+ +

The filter exports recognized text as the frame metadata lavfi.ocr.text. +The filter exports confidence of recognized words as the frame metadata lavfi.ocr.confidence. +

+ +

39.183 ocv

+ +

Apply a video transform using libopencv. +

+

To enable this filter, install the libopencv library and headers and +configure FFmpeg with --enable-libopencv. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the libopencv filter to apply. +

+
+
filter_params
+

The parameters to pass to the libopencv filter. If not specified, the default +values are assumed. +

+
+
+ +

Refer to the official libopencv documentation for more precise +information: +http://docs.opencv.org/master/modules/imgproc/doc/filtering.html +

+

Several libopencv filters are supported; see the following subsections. +

+ +

39.183.1 dilate

+ +

Dilate an image by using a specific structuring element. +It corresponds to the libopencv function cvDilate. +

+

It accepts the parameters: struct_el|nb_iterations. +

+

struct_el represents a structuring element, and has the syntax: +colsxrows+anchor_xxanchor_y/shape +

+

cols and rows represent the number of columns and rows of +the structuring element, anchor_x and anchor_y the anchor +point, and shape the shape for the structuring element. shape +must be "rect", "cross", "ellipse", or "custom". +

+

If the value for shape is "custom", it must be followed by a +string of the form "=filename". The file with name +filename is assumed to represent a binary image, with each +printable character corresponding to a bright pixel. When a custom +shape is used, cols and rows are ignored, the number +or columns and rows of the read file are assumed instead. +

+

The default value for struct_el is "3x3+0x0/rect". +

+

nb_iterations specifies the number of times the transform is +applied to the image, and defaults to 1. +

+

Some examples: +

+
# Use the default values
+ocv=dilate
+
+# Dilate using a structuring element with a 5x5 cross, iterating two times
+ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
+
+# Read the shape from the file diamond.shape, iterating two times.
+# The file diamond.shape may contain a pattern of characters like this
+#   *
+#  ***
+# *****
+#  ***
+#   *
+# The specified columns and rows are ignored
+# but the anchor point coordinates are not
+ocv=dilate:0x0+2x2/custom=diamond.shape|2
+
+ + +

39.183.2 erode

+ +

Erode an image by using a specific structuring element. +It corresponds to the libopencv function cvErode. +

+

It accepts the parameters: struct_el:nb_iterations, +with the same syntax and semantics as the dilate filter. +

+ +

39.183.3 smooth

+ +

Smooth the input video. +

+

The filter takes the following parameters: +type|param1|param2|param3|param4. +

+

type is the type of smooth filter to apply, and must be one of +the following values: "blur", "blur_no_scale", "median", "gaussian", +or "bilateral". The default value is "gaussian". +

+

The meaning of param1, param2, param3, and param4 +depends on the smooth type. param1 and +param2 accept integer positive values or 0. param3 and +param4 accept floating point values. +

+

The default value for param1 is 3. The default value for the +other parameters is 0. +

+

These parameters correspond to the parameters assigned to the +libopencv function cvSmooth. +

+ +

39.184 oscilloscope

+ +

2D Video Oscilloscope. +

+

Useful to measure spatial impulse, step responses, chroma delays, etc. +

+

It accepts the following parameters: +

+
+
x
+

Set scope center x position. +

+
+
y
+

Set scope center y position. +

+
+
s
+

Set scope size, relative to frame diagonal. +

+
+
t
+

Set scope tilt/rotation. +

+
+
o
+

Set trace opacity. +

+
+
tx
+

Set trace center x position. +

+
+
ty
+

Set trace center y position. +

+
+
tw
+

Set trace width, relative to width of frame. +

+
+
th
+

Set trace height, relative to height of frame. +

+
+
c
+

Set which components to trace. By default it traces first three components. +

+
+
g
+

Draw trace grid. By default is enabled. +

+
+
st
+

Draw some statistics. By default is enabled. +

+
+
sc
+

Draw scope. By default is enabled. +

+
+ + +

39.184.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

39.184.2 Examples

+ +
    +
  • Inspect full first row of video frame. +
    +
    oscilloscope=x=0.5:y=0:s=1
    +
    + +
  • Inspect full last row of video frame. +
    +
    oscilloscope=x=0.5:y=1:s=1
    +
    + +
  • Inspect full 5th line of video frame of height 1080. +
    +
    oscilloscope=x=0.5:y=5/1080:s=1
    +
    + +
  • Inspect full last column of video frame. +
    +
    oscilloscope=x=1:y=0.5:s=1:t=1
    +
    + +
+ + +

39.185 overlay

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+

A description of the accepted options follows. +

+
+
x
+
y
+

Set the expression for the x and y coordinates of the overlaid video +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). +

+
+
eof_action
+

See framesync. +

+
+
eval
+

Set when the expressions for x, and y are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘frame’. +

+
+
shortest
+

See framesync. +

+
+
format
+

Set the format for the output video. +

+

It accepts the following values: +

+
‘yuv420’
+

force YUV 4:2:0 8-bit planar output +

+
+
‘yuv420p10’
+

force YUV 4:2:0 10-bit planar output +

+
+
‘yuv422’
+

force YUV 4:2:2 8-bit planar output +

+
+
‘yuv422p10’
+

force YUV 4:2:2 10-bit planar output +

+
+
‘yuv444’
+

force YUV 4:4:4 8-bit planar output +

+
+
‘yuv444p10’
+

force YUV 4:4:4 10-bit planar output +

+
+
‘rgb’
+

force RGB 8-bit packed output +

+
+
‘gbrp’
+

force RGB 8-bit planar output +

+
+
‘auto’
+

automatically pick format +

+
+ +

Default value is ‘yuv420’. +

+
+
repeatlast
+

See framesync. +

+
+
alpha
+

Set format of alpha of the overlaid video, it can be straight or +premultiplied, or auto to choose the alpha mode automatically. +Default is auto. +

+
+ +

The x, and y expressions can contain the following +parameters. +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values of the output +format. For example for the pixel format "yuv422p" hsub is 2 and +vsub is 1. +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp, expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

This filter also supports the framesync options. +

+

Note that the n, t variables are available only +when evaluation is done per frame, and will evaluate to NAN +when eval is set to ‘init’. +

+

Be aware that frames are taken from each input video in timestamp +order, hence, if their initial timestamps differ, it is a good idea +to pass the two inputs through a setpts=PTS-STARTPTS filter to +have them begin in the same zero timestamp, as the example for +the movie filter does. +

+

You can chain together more overlays but you should test the +efficiency of such approach. +

+ +

39.185.1 Commands

+ +

This filter supports the following commands: +

+
x
+
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. +

+
+ + +

39.185.2 Examples

+ +
    +
  • Draw the overlay at 10 pixels from the bottom right corner of the main +video: +
    +
    overlay=main_w-overlay_w-10:main_h-overlay_h-10
    +
    + +

    Using named options the example above becomes: +

    +
    overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
    +
    + +
  • Insert a transparent PNG logo in the bottom left corner of the input, +using the ffmpeg tool with the -filter_complex option: +
    +
    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 ffmpeg tool: +
    +
    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
    +
    + +
  • Add a transparent color layer on top of the main video; WxH +must specify the size of the main input to the overlay filter: +
    +
    color=color=red@.3:size=WxH [over]; [in][over] overlay [out]
    +
    + +
  • Play an original video and a filtered version (here with the deshake +filter) side by side using the ffplay tool: +
    +
    ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
    +
    + +

    The above command is the same as: +

    +
    ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
    +
    + +
  • Make a sliding overlay appearing from the left to the right top part of the +screen starting since time 2: +
    +
    overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
    +
    + +
  • Compose output by putting two input videos side to side: +
    +
    ffmpeg -i left.avi -i right.avi -filter_complex "
    +nullsrc=size=200x100 [background];
    +[0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
    +[1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
    +[background][left]       overlay=shortest=1       [background+left];
    +[background+left][right] overlay=shortest=1:x=100 [left+right]
    +"
    +
    + +
  • Mask 10-20 seconds of a video by applying the delogo filter to a section +
    +
    ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
    +-vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
    +masked.avi
    +
    + +
  • Chain several overlays in cascade: +
    +
    nullsrc=s=200x200 [bg];
    +testsrc=s=100x100, split=4 [in0][in1][in2][in3];
    +[in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
    +[in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
    +[in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
    +[in3] null,       [mid2] overlay=100:100 [out0]
    +
    + +
+ + +

39.186 owdenoise

+ +

Apply Overcomplete Wavelet denoiser. +

+

The filter accepts the following options: +

+
+
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 8. +

+
+
luma_strength, ls
+

Set luma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+
chroma_strength, cs
+

Set chroma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+ + +

39.187 pad

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following parameters: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

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 color is "black". +

+
+
eval
+

Specify when to evaluate width, height, x and y expression. +

+

It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when +a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+
+
aspect
+

Pad to aspect instead to a resolution. +

+
+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

39.187.1 Examples

+ +
    +
  • Add paddings with the color "violet" to the input video. The output video +size is 640x480, and the top-left corner of the input video is placed at +column 0, row 40 +
    +
    pad=640:480:0:40:violet
    +
    + +

    The example above is equivalent to the following command: +

    +
    pad=width=640:height=480:x=0:y=40:color=violet
    +
    + +
  • Pad the input to get an output with dimensions increased by 3/2, +and put the input video at the center of the padded area: +
    +
    pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a squared output with size equal to the maximum +value between the input width and height, and put the input video at +the center of the padded area: +
    +
    pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a final w/h ratio of 16:9: +
    +
    pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • In case of anamorphic video, in order to set the output display aspect +correctly, it is necessary to use sar in the expression, +according to the relation: +
    +
    (ih * X / ih) * sar = output_dar
    +X = output_dar / sar
    +
    + +

    Thus the previous example needs to be modified to: +

    +
    pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Double the output size and put the input video in the bottom-right +corner of the output padded area: +
    +
    pad="2*iw:2*ih:ow-iw:oh-ih"
    +
    +
+ + +

39.188 palettegen

+ +

Generate one palette for a whole video stream. +

+

It accepts the following options: +

+
+
max_colors
+

Set the maximum number of colors to quantize in the palette. +Note: the palette will still contain 256 colors; the unused palette entries +will be black. +

+
+
reserve_transparent
+

Create a palette of 255 colors maximum and reserve the last one for +transparency. Reserving the transparency color is useful for GIF optimization. +If not set, the maximum of colors in the palette will be 256. You probably want +to disable this option for a standalone image. +Set by default. +

+
+
transparency_color
+

Set the color that will be used as background for transparency. +

+
+
stats_mode
+

Set statistics mode. +

+

It accepts the following values: +

+
‘full’
+

Compute full frame histograms. +

+
‘diff’
+

Compute histograms only for the part that differs from previous frame. This +might be relevant to give more importance to the moving part of your input if +the background is static. +

+
‘single’
+

Compute new histogram for each frame. +

+
+ +

Default value is full. +

+
+ +

The filter also exports the frame metadata lavfi.color_quant_ratio +(nb_color_in / nb_color_out) which you can use to evaluate the degree of +color quantization of the palette. This information is also visible at +info logging level. +

+ +

39.188.1 Examples

+ +
    +
  • Generate a representative palette of a given video using ffmpeg: +
    +
    ffmpeg -i input.mkv -vf palettegen palette.png
    +
    +
+ + +

39.189 paletteuse

+ +

Use a palette to downsample an input video stream. +

+

The filter takes two inputs: one video stream and a palette. The palette must +be a 256 pixels image. +

+

It accepts the following options: +

+
+
dither
+

Select dithering mode. Available algorithms are: +

+
‘bayer’
+

Ordered 8x8 bayer dithering (deterministic) +

+
‘heckbert’
+

Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). +Note: this dithering is sometimes considered "wrong" and is included as a +reference. +

+
‘floyd_steinberg’
+

Floyd and Steingberg dithering (error diffusion) +

+
‘sierra2’
+

Frankie Sierra dithering v2 (error diffusion) +

+
‘sierra2_4a’
+

Frankie Sierra dithering v2 "Lite" (error diffusion) +

+
‘sierra3’
+

Frankie Sierra dithering v3 (error diffusion) +

+
‘burkes’
+

Burkes dithering (error diffusion) +

+
‘atkinson’
+

Atkinson dithering by Bill Atkinson at Apple Computer (error diffusion) +

+
‘none’
+

Disable dithering. +

+
+ +

Default is sierra2_4a. +

+
+
bayer_scale
+

When bayer dithering is selected, this option defines the scale of the +pattern (how much the crosshatch pattern is visible). A low value means more +visible pattern for less banding, and higher value means less visible pattern +at the cost of more banding. +

+

The option must be an integer value in the range [0,5]. Default is 2. +

+
+
diff_mode
+

If set, define the zone to process +

+
+
‘rectangle’
+

Only the changing rectangle will be reprocessed. This is similar to GIF +cropping/offsetting compression mechanism. This option can be useful for speed +if only a part of the image is changing, and has use cases such as limiting the +scope of the error diffusal dither to the rectangle that bounds the +moving scene (it leads to more deterministic output if the scene doesn’t change +much, and as a result less moving noise and better GIF compression). +

+
+ +

Default is none. +

+
+
new
+

Take new palette for each output frame. +

+
+
alpha_threshold
+

Sets the alpha threshold for transparency. Alpha values above this threshold +will be treated as completely opaque, and values below this threshold will be +treated as completely transparent. +

+

The option must be an integer value in the range [0,255]. Default is 128. +

+
+ + +

39.189.1 Examples

+ +
    +
  • Use a palette (generated for example with palettegen) to encode a GIF +using ffmpeg: +
    +
    ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
    +
    +
+ + +

39.190 perspective

+ +

Correct perspective of video not recorded perpendicular to the screen. +

+

A description of the accepted parameters follows. +

+
+
x0
+
y0
+
x1
+
y1
+
x2
+
y2
+
x3
+
y3
+

Set coordinates expression for top left, top right, bottom left and bottom right corners. +Default values are 0:0:W:0:0:H:W:H with which perspective will remain unchanged. +If the sense option is set to source, then the specified points will be sent +to the corners of the destination. If the sense option is set to destination, +then the corners of the source will be sent to the specified coordinates. +

+

The expressions can use the following variables: +

+
+
W
+
H
+

the width and height of video frame. +

+
in
+

Input frame count. +

+
on
+

Output frame count. +

+
+ +
+
interpolation
+

Set interpolation for perspective correction. +

+

It accepts the following values: +

+
‘linear’
+
‘cubic’
+
+ +

Default value is ‘linear’. +

+
+
sense
+

Set interpretation of coordinate options. +

+

It accepts the following values: +

+
‘0, source’
+
+

Send point in the source specified by the given coordinates to +the corners of the destination. +

+
+
‘1, destination’
+
+

Send the corners of the source to the point in the destination specified +by the given coordinates. +

+

Default value is ‘source’. +

+
+ +
+
eval
+

Set when the expressions for coordinates x0,y0,...x3,y3 are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ + +

39.191 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. +

+
+
mode
+

Set phase mode. +

+

It accepts the following values: +

+
‘t’
+

Capture field order top-first, transfer bottom-first. +Filter will delay the bottom field. +

+
+
‘b’
+

Capture field order bottom-first, transfer top-first. +Filter will delay the top field. +

+
+
‘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. +

+
+
‘a’
+

Capture field order determined automatically by field flags, transfer +opposite. +Filter selects among ‘t’ and ‘b’ modes on a frame by frame +basis using field flags. If no field information is available, +then this works just like ‘u’. +

+
+
‘u’
+

Capture unknown or varying, transfer opposite. +Filter selects among ‘t’ and ‘b’ on a frame by frame basis by +analyzing the images and selecting the alternative that produces best +match between the fields. +

+
+
‘T’
+

Capture top-first, transfer unknown or varying. +Filter selects among ‘t’ and ‘p’ using image analysis. +

+
+
‘B’
+

Capture bottom-first, transfer unknown or varying. +Filter selects among ‘b’ and ‘p’ using image analysis. +

+
+
‘A’
+

Capture determined by field flags, transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using field flags and +image analysis. If no field information is available, then this works just +like ‘U’. This is the default mode. +

+
+
‘U’
+

Both capture and transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using image analysis only. +

+
+
+
+ + +

39.191.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.192 photosensitivity

+

Reduce various flashes in video, so to help users with epilepsy. +

+

It accepts the following options: +

+
frames, f
+

Set how many frames to use when filtering. Default is 30. +

+
+
threshold, t
+

Set detection threshold factor. Default is 1. +Lower is stricter. +

+
+
skip
+

Set how many pixels to skip when sampling frames. Default is 1. +Allowed range is from 1 to 1024. +

+
+
bypass
+

Leave frames unchanged. Default is disabled. +

+
+ + +

39.193 pixdesctest

+ +

Pixel format descriptor test filter, mainly useful for internal +testing. The output video should be equal to the input video. +

+

For example: +

+
format=monow, pixdesctest
+
+ +

can be used to test the monowhite pixel format descriptor definition. +

+ +

39.194 pixelize

+

Apply pixelization to video stream. +

+

The filter accepts the following options: +

+
width, w
+
height, h
+

Set block dimensions that will be used for pixelization. +Default value is 16. +

+
+
mode, m
+

Set the mode of pixelization used. +

+

Possible values are: +

+
‘avg’
+
‘min’
+
‘max’
+
+

Default value is avg. +

+
+
planes, p
+

Set what planes to filter. Default is to filter all planes. +

+
+ + +

39.194.1 Commands

+ +

This filter supports all options as commands. +

+ +

39.195 pixscope

+ +

Display sample values of color channels. Mainly useful for checking color +and levels. Minimum supported resolution is 640x480. +

+

The filters accept the following options: +

+
+
x
+

Set scope X position, relative offset on X axis. +

+
+
y
+

Set scope Y position, relative offset on Y axis. +

+
+
w
+

Set scope width. +

+
+
h
+

Set scope height. +

+
+
o
+

Set window opacity. This window also holds statistics about pixel area. +

+
+
wx
+

Set window X position, relative offset on X axis. +

+
+
wy
+

Set window Y position, relative offset on Y axis. +

+
+ + +

39.195.1 Commands

+ +

This filter supports same commands as options. +

+ +

39.196 pp7

+

Apply Postprocessing filter 7. It is variant of the spp filter, +similar to spp = 6 with 7 point DCT, where only the center sample is +used after IDCT. +

+

The filter accepts the following options: +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range +0 to 63. If not set, the filter will use the QP from the video stream +(if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding. +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
‘medium’
+

Set medium thresholding (good results, default). +

+
+
+
+ + +

39.197 premultiply

+

Apply alpha premultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

39.198 premultiply_dynamic

+

Dynamically premultiply or unpremultiply the input video stream as needed, +to match the requirements of the downstream filter graph. This is roughly +equivalent to either premultiply:inplace=yes or +unpremultiply:inplace=yes, or otherwise a noop. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ + +

39.199 prewitt

+

Apply prewitt operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

39.199.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.200 pseudocolor

+ +

Alter frame colors in video with pseudocolors. +

+

This filter accepts the following options: +

+
+
c0
+

set pixel first component expression +

+
+
c1
+

set pixel second component expression +

+
+
c2
+

set pixel third component expression +

+
+
c3
+

set pixel fourth component expression, corresponds to the alpha component +

+
+
index, i
+

set component to use as base for altering colors +

+
+
preset, p
+

Pick one of built-in LUTs. By default is set to none. +

+

Available LUTs: +

+
‘magma’
+
‘inferno’
+
‘plasma’
+
‘viridis’
+
‘turbo’
+
‘cividis’
+
‘range1’
+
‘range2’
+
‘shadows’
+
‘highlights’
+
‘solar’
+
‘nominal’
+
‘preferred’
+
‘total’
+
‘spectral’
+
‘cool’
+
‘heat’
+
‘fiery’
+
‘blues’
+
‘green’
+
‘helix’
+
+ +
+
opacity
+

Set opacity of output colors. Allowed range is from 0 to 1. +Default value is set to 1. +

+
+ +

Each of the expression options specifies the expression to use for computing +the lookup table for the corresponding pixel component values. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
ymin, umin, vmin, amin
+

The minimum allowed component value. +

+
+
ymax, umax, vmax, amax
+

The maximum allowed component value. +

+
+ +

All expressions default to "val". +

+ +

39.200.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.200.2 Examples

+ +
    +
  • Change too high luma values to gradient: +
    +
    pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
    +
    +
+ + +

39.201 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: +

+
+
PSNR = 10*log10(MAX^2/MSE)
+
+ +

Where MAX is the average of the maximum values of each component of the +image. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the PSNR of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+
stats_version
+

Specifies which version of the stats file format to use. Details of +each format are written below. +Default value is 1. +

+
+
output_max
+

Determines whether the max value is output to the stats log. +Default value is 0. +Requires stats_version >= 2. If this is set and stats_version < 2, +the filter will return an error. +

+
+ +

This filter also supports the framesync options. +

+

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

If a stats_version greater than 1 is specified, a header line precedes +the list of per-frame-pair stats, with key value pairs following the frame +format with the following parameters: +

+
+
psnr_log_version
+

The version of the log file format. Will match stats_version. +

+
+
fields
+

A comma separated list of the per-frame-pair parameters included in +the log. +

+
+ +

A description of each shown per-frame-pair parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
mse_avg
+

Mean Square Error pixel-by-pixel average difference of the compared +frames, averaged over all the image components. +

+
+
mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
+

Mean Square Error pixel-by-pixel average difference of the compared +frames for the component specified by the suffix. +

+
+
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. +

+
+
max_avg, max_y, max_u, max_v
+

Maximum allowed value for each channel, and average over all +channels. +

+
+ + +

39.201.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] psnr="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The PSNR of each individual frame +is stored in stats.log. +

    +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -
    +
    +
+ + +

39.202 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 fps=24000/1001 if the input frame rate is 29.97fps, +fps=24 for 30fps and the (rare) telecined 25fps input. +

+

The filter accepts the following options: +

+
+
jl
+
jr
+
jt
+
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. +

+
+
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 0. +

+
+
mp
+

Set the metric plane to use. It accepts the following values: +

+
‘l’
+

Use luma plane. +

+
+
‘u’
+

Use chroma blue plane. +

+
+
‘v’
+

Use chroma red plane. +

+
+ +

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 mp to a chroma plane is to reduce CPU +load and make pullup usable in realtime on slow machines. +

+
+ +

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: +

+
ffmpeg -i input -vf pullup -r 24000/1001 ...
+
+ + +

39.203 qp

+ +

Change video quantization parameters (QP). +

+

The filter accepts the following option: +

+
+
qp
+

Set expression for quantization parameter. +

+
+ +

The expression is evaluated through the eval API and can contain, among others, +the following constants: +

+
+
known
+

1 if index is not 129, 0 otherwise. +

+
+
qp
+

Sequential index starting from -129 to 128. +

+
+ + +

39.203.1 Examples

+ +
    +
  • Some equation like: +
    +
    qp=2+2*sin(PI*qp)
    +
    +
+ + +

39.204 qrencode

+

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/), and overlay it on top of the current +frame. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and overlaid into the video output according to +the specified options. +

+

In case no text is specified, no QR code is overlaied. +

+

This filter accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
x
+
y
+

Specify an expression for positioning the padded QR code top-left corner. The +x expression can reference the value set by the y expression, and +vice. +

+

By default x and y are set set to 0, meaning that the QR code +is placed in the top left corner of the input. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section below for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section below for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

39.204.1 qrencode Expressions

+ +

The expressions set by the options contain the following constants and functions. +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
duration
+

the current frame’s duration, in seconds +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
main_h, H
+

the input height +

+
+
main_w, W
+

the input width +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pict_type
+

a number representing the picture type +

+
+
qr_w, w
+

the width of the encoded QR code +

+
+
rendered_qr_w, q
+
rendered_padded_qr_w, Q
+

the width of the rendered QR code, without and without padding. +

+

These parameters allow the q and Q expressions to refer to each +other, so you can for example specify q=3/4*Q. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

the input sample aspect ratio +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer to each +other, so you can for example specify y=x/dar. +

+
+ + +

39.204.2 qrencode Text expansion

+ +

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
n, frame_num
+

return the frame number +

+
+
pts
+

Return the presentation timestamp of the current frame. +

+

It can take up to two arguments. +

+

The first argument is the format of the timestamp; it defaults to flt for +seconds as a decimal number with microsecond accuracy; hms stands for a +formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as local time +zone time. If the format is set to hms24hh, the time is formatted in 24h +format (00-23). +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to localtime or gmtime, a third argument may +be supplied: a strftime C function format string. By default, +YYYY-MM-DD HH:MM:SS format will be used. +

+
+
expr, e
+

Evaluate the expression’s value and output as a double. +

+

It must take one argument specifying the expression to be evaluated, accepting +the constants and functions defined in qrencode_expressions. +

+
+
expr_formatted, ef
+

Evaluate the expression’s value and output as a formatted string. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries starting with TAG +included within each frame section printed by running ffprobe +-show_frames. +

+

String metadata generated in filters leading to the qrencode filter are also +available. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+ + +

39.204.3 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size, overalaid +in the top left corner of the input video, with the default size: +
    +
    qrencode=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencode=text=www.ffmpeg.org:bc=pink@0.5:fc=blue
    +
    + +
  • Place the QR code in the bottom right corner of the input video: +
    +
    qrencode=text=www.ffmpeg.org:x=W-Q:y=H-Q
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencode=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencode=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Make the QR code a fraction of the input video width: +
    +
    qrencode=text=www.ffmpeg.org:q=W/5
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencode=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencode=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencode=text=%{pts}
    +
    + +
+ + +

39.205 quirc

+ +

Identify and decode a QR code using the libquirc library (see +https://github.com/dlbeer/quirc/), and print the identified QR codes +positions and payload as metadata. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libquirc. +

+

For each found QR code in the input video, some metadata entries are added with +the prefix lavfi.quirc.N, where N is the index, starting from 0, +associated to the QR code. +

+

A description of each metadata value follows: +

+
+
lavfi.quirc.count
+

the number of found QR codes, it is not set in case none was found +

+
+
lavfi.quirc.N.corner.M.x
+
lavfi.quirc.N.coreer.M.y
+

the x/y positions of the four corners of the square containing the QR code, +where M is the index of the corner starting from 0 +

+
+
lavfi.quirc.N.payload
+

the payload of the QR code +

+
+ + +

39.206 random

+ +

Flush video frames from internal cache of frames into a random order. +No frame is discarded. +Inspired by frei0r nervous filter. +

+
+
frames
+

Set size in number of frames of internal cache, in range from 2 to +512. Default is 30. +

+
+
seed
+

Set seed for random number generator, must be an integer included between +0 and UINT32_MAX. If not specified, or if explicitly set to +less than 0, the filter will try to use a good random seed on a +best effort basis. +

+
+ + +

39.207 readeia608

+ +

Read closed captioning (EIA-608) information from the top lines of a video frame. +

+

This filter adds frame metadata for lavfi.readeia608.X.cc and +lavfi.readeia608.X.line, where X is the number of the identified line +with EIA-608 data (starting from 0). A description of each metadata value follows: +

+
+
lavfi.readeia608.X.cc
+

The two bytes stored as EIA-608 data (printed in hexadecimal). +

+
+
lavfi.readeia608.X.line
+

The number of the line on which the EIA-608 data was identified and read. +

+
+ +

This filter accepts the following options: +

+
+
scan_min
+

Set the line to start scanning for EIA-608 data. Default is 0. +

+
+
scan_max
+

Set the line to end scanning for EIA-608 data. Default is 29. +

+
+
spw
+

Set the ratio of width reserved for sync code detection. +Default is 0.27. Allowed range is [0.1 - 0.7]. +

+
+
chp
+

Enable checking the parity bit. In the event of a parity error, the filter will output +0x00 for that character. Default is false. +

+
+
lp
+

Lowpass lines prior to further processing. Default is enabled. +

+
+ + +

39.207.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.207.2 Examples

+ +
    +
  • Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. +
    +
    ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv
    +
    +
+ + +

39.208 readvitc

+ +

Read vertical interval timecode (VITC) information from the top lines of a +video frame. +

+

The filter adds frame metadata key lavfi.readvitc.tc_str with the +timecode value, if a valid timecode has been detected. Further metadata key +lavfi.readvitc.found is set to 0/1 depending on whether +timecode data has been found or not. +

+

This filter accepts the following options: +

+
+
scan_max
+

Set the maximum number of lines to scan for VITC data. If the value is set to +-1 the full video frame is scanned. Default is 45. +

+
+
thr_b
+

Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], +default value is 0.2. The value must be equal or less than thr_w. +

+
+
thr_w
+

Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], +default value is 0.6. The value must be equal or greater than thr_b. +

+
+ + +

39.208.1 Examples

+ +
    +
  • Detect and draw VITC data onto the video frame; if no valid VITC is detected, +draw --:--:--:-- as a placeholder: +
    +
    ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--}:x=(w-tw)/2:y=400-ascent'
    +
    +
+ + +

39.209 remap

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 16bit depth, single channel. +

+
+
format
+

Specify pixel format of output from this filter. Can be color or gray. +Default is color. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

39.210 removegrain

+ +

The removegrain filter is a spatial denoiser for progressive video. +

+
+
m0
+

Set mode for the first plane. +

+
+
m1
+

Set mode for the second plane. +

+
+
m2
+

Set mode for the third plane. +

+
+
m3
+

Set mode for the fourth plane. +

+
+ +

Range of mode is from 0 to 24. Description of each mode follows: +

+
+
0
+

Leave input plane unchanged. Default. +

+
+
1
+

Clips the pixel with the minimum and maximum of the 8 neighbour pixels. +

+
+
2
+

Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. +

+
+
3
+

Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. +

+
+
4
+

Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. +This is equivalent to a median filter. +

+
+
5
+

Line-sensitive clipping giving the minimal change. +

+
+
6
+

Line-sensitive clipping, intermediate. +

+
+
7
+

Line-sensitive clipping, intermediate. +

+
+
8
+

Line-sensitive clipping, intermediate. +

+
+
9
+

Line-sensitive clipping on a line where the neighbours pixels are the closest. +

+
+
10
+

Replaces the target pixel with the closest neighbour. +

+
+
11
+

[1 2 1] horizontal and vertical kernel blur. +

+
+
12
+

Same as mode 11. +

+
+
13
+

Bob mode, interpolates top field from the line where the neighbours +pixels are the closest. +

+
+
14
+

Bob mode, interpolates bottom field from the line where the neighbours +pixels are the closest. +

+
+
15
+

Bob mode, interpolates top field. Same as 13 but with a more complicated +interpolation formula. +

+
+
16
+

Bob mode, interpolates bottom field. Same as 14 but with a more complicated +interpolation formula. +

+
+
17
+

Clips the pixel with the minimum and maximum of respectively the maximum and +minimum of each pair of opposite neighbour pixels. +

+
+
18
+

Line-sensitive clipping using opposite neighbours whose greatest distance from +the current pixel is minimal. +

+
+
19
+

Replaces the pixel with the average of its 8 neighbours. +

+
+
20
+

Averages the 9 pixels ([1 1 1] horizontal and vertical blur). +

+
+
21
+

Clips pixels using the averages of opposite neighbour. +

+
+
22
+

Same as mode 21 but simpler and faster. +

+
+
23
+

Small edge and halo removal, but reputed useless. +

+
+
24
+

Similar as 23. +

+
+ + +

39.211 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. +

+

The filter accepts the following options: +

+
+
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. +

+
+ +

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 +the logo. If you use white (255) for the logo and black (0) for the +rest, you will be safe. For making the filter bitmap, it is +recommended to take a screen capture of a black frame with the logo +visible, and then using a threshold filter followed by the erode +filter once or twice. +

+

If needed, little splotches can be fixed manually. Remember that if +logo pixels are not covered, the filter quality will be much +reduced. Marking too many pixels as part of the logo does not hurt as +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. +

+ +

39.212 repeatfields

+ +

This filter uses the repeat_field flag from the Video ES headers and hard repeats +fields based on its value. +

+ +

39.213 reverse

+ +

Reverse a video clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

39.213.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    trim=end=5,reverse
    +
    +
+ + +

39.214 rgbashift

+

Shift R/G/B/A pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
rh
+

Set amount to shift red horizontally. +

+
rv
+

Set amount to shift red vertically. +

+
gh
+

Set amount to shift green horizontally. +

+
gv
+

Set amount to shift green vertically. +

+
bh
+

Set amount to shift blue horizontally. +

+
bv
+

Set amount to shift blue vertically. +

+
ah
+

Set amount to shift alpha horizontally. +

+
av
+

Set amount to shift alpha vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

39.214.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.215 roberts

+

Apply roberts cross operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

39.215.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.216 rotate

+ +

Rotate video by an arbitrary angle expressed in radians. +

+

The filter accepts the following options: +

+

A description of the optional parameters follows. +

+
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. +

+
+
out_w, ow
+

Set the output width expression, default value is "iw". +This expression is evaluated just once during configuration. +

+
+
out_h, oh
+

Set the output height expression, default value is "ih". +This expression is evaluated just once during configuration. +

+
+
bilinear
+

Enable bilinear interpolation if set to 1, a value of 0 disables +it. Default value is 1. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the rotated +image. For the general syntax 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". +

+
+ +

The expressions for the angle and the output size can contain the +following constants and functions: +

+
+
n
+

sequential number of the input frame, starting from 0. It is always NAN +before the first frame is filtered. +

+
+
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. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_w, iw
+
in_h, ih
+

the input video width and height +

+
+
out_w, ow
+
out_h, oh
+

the output width and height, that is the size of the padded area as +specified by the width and height expressions +

+
+
rotw(a)
+
roth(a)
+

the minimal width/height required for completely containing the input +video rotated by a radians. +

+

These are only available when computing the out_w and +out_h expressions. +

+
+ + +

39.216.1 Examples

+ +
    +
  • Rotate the input by PI/6 radians clockwise: +
    +
    rotate=PI/6
    +
    + +
  • Rotate the input by PI/6 radians counter-clockwise: +
    +
    rotate=-PI/6
    +
    + +
  • Rotate the input by 45 degrees clockwise: +
    +
    rotate=45*PI/180
    +
    + +
  • Apply a constant rotation with period T, starting from an angle of PI/3: +
    +
    rotate=PI/3+2*PI*t/T
    +
    + +
  • Make the input video rotation oscillating with a period of T +seconds and an amplitude of A radians: +
    +
    rotate=A*sin(2*PI/T*t)
    +
    + +
  • Rotate the video, output size is chosen so that the whole rotating +input video is always completely contained in the output: +
    +
    rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
    +
    + +
  • Rotate the video, reduce the output size so that no background is ever +shown: +
    +
    rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
    +
    +
+ + +

39.216.2 Commands

+ +

The filter supports the following commands: +

+
+
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. +

+
+ + +

39.217 sab

+ +

Apply Shape Adaptive Blur. +

+

The filter accepts the following options: +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
chroma_radius, cr
+

Set chroma blur filter strength, must be a value in range -0.9-4.0. A +greater value will result in a more blurred image, and in slower +processing. +

+
+
chroma_pre_filter_radius, cpfr
+

Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. +

+
+
chroma_strength, cs
+

Set chroma maximum difference between pixels to still be considered, +must be a value in the -0.9-100.0 range. +

+
+ +

Each chroma option value, if not explicitly specified, is set to the +corresponding luma option value. +

+ +

39.218 scale

+ +

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. +

+

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. +

+ +

39.218.1 Options

+

The filter accepts the following options, any of the options supported +by the libswscale scaler, as well as any of the framesync options. +

+

See the ffmpeg-scaler manual for +the complete list of scaler options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the scale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+ +
+
interl
+

Set the interlacing mode. It accepts the following values: +

+
+
‘1’
+

Force interlaced aware scaling. +

+
+
‘0’
+

Do not apply interlaced scaling. +

+
+
‘-1’
+

Select interlaced aware scaling depending on whether the source frames +are flagged as interlaced or not. +

+
+ +

Default value is ‘0’. +

+
+
flags
+

Set libswscale scaling flags. See +the ffmpeg-scaler manual for the +complete list of values. If not explicitly specified the filter applies +the default flags. +

+ +
+
param0, param1
+

Set libswscale input parameters for scaling algorithms that need them. See +the ffmpeg-scaler manual for the +complete documentation. If not explicitly specified the filter applies +empty parameters. +

+
+
intent
+

Set the ICC rendering intent to use when transforming between different color +spaces. It accepts the following values: +

+
+
‘perceptual’
+

Use a perceptually guided tone and gamut mapping curve. The exact details of +the mapping used may change at any time and should not be relied on as stable. +This intent is recommended for final viewing of image/video content in typical +viewing settings. +

+
+
‘relative_colorimetric’
+

Statically clip out-of-gamut colors using a colorimetric clipping curve which +attempts to find the colorimetrically least dissimilar in-gamut color. This +intent performs white point adaptation and black point adaptation. This is +the default. This intent is recommended wherever faithful color reproduction +is of the utmost importance, even at the cost of clipping. +

+
+
‘absolute_colorimetric’
+

Hard clip out-of-gamut colors with no attempt at white or black point +reproduction. This intent will reproduce in-gamut colors 1:1 on the output +display as they would appear on the reference display, assuming the output +display is appropriately calibrated. +

+
+
‘saturation’
+

Performs saturation mapping - that is, stretches the input color volume +directly onto the output color volume, in non-linear fashion that preserves the +original signal appearance as much as possible. This intent is recommended for +signal content evaluation, as it will not lead to any clipping. It is roughly +analogous to not performing any color mapping, although it still takes into +account the mastering display primaries and any differences in encoding TRC. +

+
+ +
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
in_color_matrix
+
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: +

+
+
‘auto’
+

Choose automatically. +

+
+
‘bt709’
+

Format conforming to International Telecommunication Union (ITU) +Recommendation BT.709. +

+
+
‘fcc’
+

Set color space conforming to the United States Federal Communications +Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). +

+
+
‘bt601’
+
‘bt470’
+
‘smpte170m’
+

Set color space conforming to: +

+
    +
  • ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 + +
  • ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G + +
  • Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 + +
+ +
+
‘smpte240m’
+

Set color space conforming to SMPTE ST 240:1999. +

+
+
‘bt2020’
+

Set color space conforming to ITU-R BT.2020 non-constant luminance system. +

+
+ +
+
in_range
+
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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
in_chroma_loc
+
out_chroma_loc
+

Set in/output chroma sample location. If not specified, center-sited chroma +is used by default. Possible values: +

+
+
‘auto, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
in_primaries
+
out_primaries
+

Set in/output RGB primaries. +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
‘ebu3213’
+
+ +
+
in_transfer
+
out_transfer
+

Set in/output transfer response curve (TRC). +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘gamma22’
+
‘bt470bg’
+
‘gamma28’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘iec61966-2-1’
+
‘srgb’
+
‘iec61966-2-4’
+
‘xvycc’
+
‘bt1361e’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Enabling this option leads to the output SAR being reset to 1. +Additionally, if the user requests proportional scaling either +through the width or height expressions, e.g. w=-4:h=360 or w=iw/2:h=-1 +or by enabling force_original_aspect_ratio, then the input DAR is taken into +account and the output is scaled to produce square pixels. +Default is false. +

+
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+
ref_w, rw
+
ref_h, rh
+
ref_a
+
ref_dar, rdar
+
ref_n
+
ref_t
+
ref_pos
+

Eqvuialent to the above, but for a second reference input. If any of these +variables are present, this filter accepts two inputs. +

+
+ + +

39.218.2 Examples

+ +
    +
  • Scale the input video to a size of 200x100 +
    +
    scale=w=200:h=100
    +
    + +

    This is equivalent to: +

    +
    scale=200:100
    +
    + +

    or: +

    +
    scale=200x100
    +
    + +
  • Specify a size abbreviation for the output size: +
    +
    scale=qcif
    +
    + +

    which can also be written as: +

    +
    scale=size=qcif
    +
    + +
  • Scale the input to 2x: +
    +
    scale=w=2*iw:h=2*ih
    +
    + +
  • The above is the same as: +
    +
    scale=2*in_w:2*in_h
    +
    + +
  • Scale the input to 2x with forced interlaced scaling: +
    +
    scale=2*iw:2*ih:interl=1
    +
    + +
  • Scale the input to half size: +
    +
    scale=w=iw/2:h=ih/2
    +
    + +
  • Increase the width, and set the height to the same size: +
    +
    scale=3/2*iw:ow
    +
    + +
  • Seek Greek harmony: +
    +
    scale=iw:1/PHI*iw
    +scale=ih*PHI:ih
    +
    + +
  • Increase the height, and set the width to 3/2 of the height: +
    +
    scale=w=3/2*oh:h=3/5*ih
    +
    + +
  • Increase the size, making the size a multiple of the chroma +subsample values: +
    +
    scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
    +
    + +
  • Increase the width to a maximum of 500 pixels, +keeping the same aspect ratio as the input: +
    +
    scale=w='min(500\, iw*3/2):h=-1'
    +
    + +
  • Make pixels square by combining scale and setsar: +
    +
    scale='trunc(ih*dar):ih',setsar=1/1
    +
    + +
  • Make pixels square using reset_sar, +making sure the resulting resolution is even (required by some codecs): +
    +
    scale='-2:ih-mod(ih,2):reset_sar=1'
    +
    + +
  • Scale to target exactly, however reset SAR to 1: +
    +
    scale='400:300:reset_sar=1'
    +
    + +
  • Scale to even dimensions that fit within 400x300, preserving input SAR: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2'
    +
    + +
  • Scale to produce square pixels with even dimensions that fit within 400x300: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2:reset_sar=1'
    +
    + +
  • Scale a subtitle stream (sub) to match the main video (main) in size before +overlaying. ("scale2ref") +
    +
    '[main]split[a][b]; [ref][a]scale=rw:rh[c]; [b][c]overlay'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display +aspect ratio. +
    +
    [logo-in][video-in]scale=w=oh*dar:h=rh/10[logo-out]
    +
    +
+ + +

39.218.3 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + +

39.219 scharr

+

Apply scharr operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

39.219.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.220 scroll

+

Scroll input video horizontally and/or vertically by constant speed. +

+

The filter accepts the following options: +

+
horizontal, h
+

Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
vertical, v
+

Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
hpos
+

Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+
vpos
+

Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+ + +

39.220.1 Commands

+ +

This filter supports the following commands: +

+
horizontal, h
+

Set the horizontal scrolling speed. +

+
vertical, v
+

Set the vertical scrolling speed. +

+
+ + +

39.221 scdet

+ +

Detect video scene change. +

+

This filter sets frame metadata with mafd between frame, the scene score, and +forward the frame to the next filter, so they can use these metadata to detect +scene change or others. +

+

In addition, this filter logs a message and sets frame metadata when it detects +a scene change by threshold. +

+

lavfi.scd.mafd metadata keys are set with mafd for every frame. +

+

lavfi.scd.score metadata keys are set with scene change score for every frame +to detect scene change. +

+

lavfi.scd.time metadata keys are set with current filtered frame time which +detect scene change with threshold. +

+

The filter accepts the following options: +

+
+
threshold, t
+

Set the scene change detection threshold as a percentage of maximum change. Good +values are in the [8.0, 14.0] range. The range for threshold is +[0., 100.]. +

+

Default value is 10.. +

+
+
sc_pass, s
+

Set the flag to pass scene change frames to the next filter. Default value is 0 +You can enable it if you want to get snapshot of scene change frames only. +

+
+ + +

39.222 selectivecolor

+ +

Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such +as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined +by the "purity" of the color (that is, how saturated it already is). +

+

This filter is similar to the Adobe Photoshop Selective Color tool. +

+

The filter accepts the following options: +

+
+
correction_method
+

Select color correction method. +

+

Available values are: +

+
‘absolute’
+

Specified adjustments are applied "as-is" (added/subtracted to original pixel +component value). +

+
‘relative’
+

Specified adjustments are relative to the original component value. +

+
+

Default is absolute. +

+
reds
+

Adjustments for red pixels (pixels where the red component is the maximum) +

+
yellows
+

Adjustments for yellow pixels (pixels where the blue component is the minimum) +

+
greens
+

Adjustments for green pixels (pixels where the green component is the maximum) +

+
cyans
+

Adjustments for cyan pixels (pixels where the red component is the minimum) +

+
blues
+

Adjustments for blue pixels (pixels where the blue component is the maximum) +

+
magentas
+

Adjustments for magenta pixels (pixels where the green component is the minimum) +

+
whites
+

Adjustments for white pixels (pixels where all components are greater than 128) +

+
neutrals
+

Adjustments for all pixels except pure black and pure white +

+
blacks
+

Adjustments for black pixels (pixels where all components are lesser than 128) +

+
psfile
+

Specify a Photoshop selective color file (.asv) to import the settings from. +

+
+ +

All the adjustment settings (reds, yellows, ...) accept up to +4 space separated floating point adjustment values in the [-1,1] range, +respectively to adjust the amount of cyan, magenta, yellow and black for the +pixels of its range. +

+ +

39.222.1 Examples

+ +
    +
  • Increase cyan by 50% and reduce yellow by 33% in every green areas, and +increase magenta by 27% in blue areas: +
    +
    selectivecolor=greens=.5 0 -.33 0:blues=0 .27
    +
    + +
  • Use a Photoshop selective color preset: +
    +
    selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
    +
    +
+ + +

39.223 separatefields

+ +

The 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 setfield filter before separatefields filter. +

+ +

39.224 setdar, setsar

+ +

The setdar filter sets the Display Aspect Ratio for the filter +output video. +

+

This is done by changing the specified Sample (aka Pixel) Aspect +Ratio, according to the following equation: +

+
DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR
+
+ +

Keep in mind that the setdar filter does not modify the pixel +dimensions of the video frame. Also, the display aspect ratio set by +this filter may be changed by later filters in the filterchain, +e.g. in case of scaling or if another "setdar" or a "setsar" filter is +applied. +

+

The setsar filter sets the Sample (aka Pixel) Aspect Ratio for +the filter output video. +

+

Note that as a consequence of the application of this filter, the +output display aspect ratio will change according to the equation +above. +

+

Keep in mind that the sample aspect ratio set by the setsar +filter may be changed by later filters in the filterchain, e.g. if +another "setsar" or a "setdar" filter is applied. +

+

It accepts the following parameters: +

+
+
r, ratio, dar (setdar only), sar (setsar only)
+

Set the aspect ratio used by the filter. +

+

The parameter can be a floating point number string, or an expression. If the +parameter is not specified, the value "0" is assumed, meaning that the same +input value is used. +

+
+
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 100. +

+
+
+ +

The parameter sar is an expression containing the following constants: +

+
+
w, h
+

The input width and height. +

+
+
a
+

Same as w / h. +

+
+
sar
+

The input sample aspect ratio. +

+
+
dar
+

The input display aspect ratio. It is the same as +(w / h) * sar. +

+
+
hsub, vsub
+

Horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

39.224.1 Examples

+ +
    +
  • To change the display aspect ratio to 16:9, specify one of the following: +
    +
    setdar=dar=1.77777
    +setdar=dar=16/9
    +
    + +
  • To change the sample aspect ratio to 10:11, specify: +
    +
    setsar=sar=10/11
    +
    + +
  • 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: +
    +
    setdar=ratio=16/9:max=1000
    +
    + +
+ + +

39.225 setfield

+ +

Force field for the output video frame. +

+

The setfield filter marks the interlace type field for the +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. fieldorder or yadif). +

+

The filter accepts the following options: +

+
+
mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property. +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+
+
+ + +

39.226 setparams

+ +

Force frame parameter for the output video frame. +

+

The setparams filter marks interlace and color range for the +output frames. It does not change the input frame, but only sets the +corresponding property, which affects how the frame is treated by +filters/encoders. +

+
+
field_mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property (default). +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+ +
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property (default). +

+
+
‘unspecified, unknown’
+

Mark the frame as unspecified color range. +

+
+
‘limited, tv, mpeg’
+

Mark the frame as limited range. +

+
+
‘full, pc, jpeg’
+

Mark the frame as full range. +

+
+ +
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
+ +
+
color_trc
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same color trc property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘log100’
+
‘log316’
+
‘iec61966-2-4’
+
‘bt1361e’
+
‘iec61966-2-1’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
colorspace
+

Set the colorspace. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘gbr’
+
‘bt709’
+
‘unknown’
+
‘fcc’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘ycgco’
+
‘bt2020nc’
+
‘bt2020c’
+
‘smpte2085’
+
‘chroma-derived-nc’
+
‘chroma-derived-c’
+
‘ictcp’
+
+ +
+
chroma_location
+

Set the chroma sample location. +Available values are: +

+
+
‘auto’
+

Keep the same chroma location (default). +

+
+
‘unspecified, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode
+

Set the alpha moda. +Available values are: +

+
+
‘auto’
+

Keep the same alpha mode (default). +

+
+
‘unspecified, unknown’
+
‘premultiplied’
+
‘straight’
+
+
+
+ + +

39.227 shear

+

Apply shear transform to input video. +

+

This filter supports the following options: +

+
+
shx
+

Shear factor in X-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
shy
+

Shear factor in Y-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the transformed +video. For the general syntax 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". +

+
+
interp
+

Set interpolation type. Can be bilinear or nearest. Default is bilinear. +

+
+ + +

39.227.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.228 showinfo

+ +

Show a line containing various information for each input video frame. +The input video is not modified. +

+

This filter supports the following options: +

+
+
checksum
+

Calculate checksums of each plane. By default enabled. +

+
+
udu_sei_as_ascii
+

Try to print user data unregistered SEI as ascii character when possible, +in hex format otherwise. +

+
+ +

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The Presentation TimeStamp of the input frame, expressed as a number of +time base units. The time base unit depends on the filter input pad. +

+
+
pts_time
+

The Presentation TimeStamp of the input frame, expressed as a number of +seconds. +

+
+
fmt
+

The pixel format name. +

+
+
sar
+

The sample aspect ratio of the input frame, expressed in the form +num/den. +

+
+
s
+

The size of the input frame. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
i
+

The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" +for bottom field first). +

+
+
iskey
+

This is 1 if the frame is a key frame, 0 otherwise. +

+
+
type
+

The picture type of the input frame ("I" for an I-frame, "P" for a +P-frame, "B" for a B-frame, or "?" for an unknown type). +Also refer to the documentation of the AVPictureType enum and of +the av_get_picture_type_char function defined in +libavutil/avutil.h. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. +

+
+
plane_checksum
+

The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, +expressed in the form "[c0 c1 c2 c3]". +

+
+
mean
+

The mean value of pixels in each plane of the input frame, expressed in the form +"[mean0 mean1 mean2 mean3]". +

+
+
stdev
+

The standard deviation of pixel values in each plane of the input frame, expressed +in the form "[stdev0 stdev1 stdev2 stdev3]". +

+
+
+ + +

39.229 showpalette

+ +

Displays the 256 colors palette of each frame. This filter is only relevant for +pal8 pixel format frames. +

+

It accepts the following option: +

+
+
s
+

Set the size of the box used to represent one palette color entry. Default is +30 (for a 30x30 pixel box). +

+
+ + +

39.230 shuffleframes

+ +

Reorder and/or duplicate and/or drop video frames. +

+

It accepts the following parameters: +

+
+
mapping
+

Set the destination indexes of input frames. +This is space or ’|’ separated list of indexes that maps input frames to output +frames. Number of indexes also sets maximal value that each index may have. +’-1’ index have special meaning and that is to drop frame. +

+
+ +

The first frame has the index 0. The default is to keep the input unchanged. +

+ +

39.230.1 Examples

+ +
    +
  • Swap second and third frame of every three frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
    +
    + +
  • Swap 10th and 1st frame of every ten frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
    +
    +
+ + +

39.231 shufflepixels

+ +

Reorder pixels in video frames. +

+

This filter accepts the following options: +

+
+
direction, d
+

Set shuffle direction. Can be forward or inverse direction. +Default direction is forward. +

+
+
mode, m
+

Set shuffle mode. Can be horizontal, vertical or block mode. +

+
+
width, w
+
height, h
+

Set shuffle block_size. In case of horizontal shuffle mode only width +part of size is used, and in case of vertical shuffle mode only height +part of size is used. +

+
+
seed, s
+

Set random seed used with shuffling pixels. Mainly useful to set to be able +to reverse filtering process to get original input. +For example, to reverse forward shuffle you need to use same parameters +and exact same seed and to set direction to inverse. +

+
+ + +

39.232 shuffleplanes

+ +

Reorder and/or duplicate video planes. +

+

It accepts the following parameters: +

+
+
map0
+

The index of the input plane to be used as the first output plane. +

+
+
map1
+

The index of the input plane to be used as the second output plane. +

+
+
map2
+

The index of the input plane to be used as the third output plane. +

+
+
map3
+

The index of the input plane to be used as the fourth output plane. +

+
+
+ +

The first plane has the index 0. The default is to keep the input unchanged. +

+ +

39.232.1 Examples

+ +
    +
  • Swap the second and third planes of the input: +
    +
    ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
    +
    +
+ + +

39.233 signalstats

+

Evaluate various visual metrics that assist in determining issues associated +with the digitization of analog video media. +

+

By default the filter will log these metadata values: +

+
+
YMIN
+

Display the minimal Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
YLOW
+

Display the Y value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YAVG
+

Display the average Y value within the input frame. Expressed in range of +[0-255]. +

+
+
YHIGH
+

Display the Y value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YMAX
+

Display the maximum Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
UMIN
+

Display the minimal U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
ULOW
+

Display the U value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UAVG
+

Display the average U value within the input frame. Expressed in range of +[0-255]. +

+
+
UHIGH
+

Display the U value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UMAX
+

Display the maximum U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VMIN
+

Display the minimal V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VLOW
+

Display the V value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VAVG
+

Display the average V value within the input frame. Expressed in range of +[0-255]. +

+
+
VHIGH
+

Display the V value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VMAX
+

Display the maximum V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
SATMIN
+

Display the minimal saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATLOW
+

Display the saturation value at the 10% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATAVG
+

Display the average saturation value within the input frame. Expressed in range +of [0-~181.02]. +

+
+
SATHIGH
+

Display the saturation value at the 90% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATMAX
+

Display the maximum saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
HUEMED
+

Display the median value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
HUEAVG
+

Display the average value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
YDIF
+

Display the average of sample value difference between all values of the Y +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
UDIF
+

Display the average of sample value difference between all values of the U +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
VDIF
+

Display the average of sample value difference between all values of the V +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
YBITDEPTH
+

Display bit depth of Y plane in current frame. +Expressed in range of [0-16]. +

+
+
UBITDEPTH
+

Display bit depth of U plane in current frame. +Expressed in range of [0-16]. +

+
+
VBITDEPTH
+

Display bit depth of V plane in current frame. +Expressed in range of [0-16]. +

+
+ +

The filter accepts the following options: +

+
+
stat
+
out
+
+

stat specify an additional form of image analysis. +out output video with the specified type of pixel highlighted. +

+

Both options accept the following values: +

+
+
‘tout’
+

Identify temporal outliers pixels. A temporal outlier is a pixel +unlike the neighboring pixels of the same field. Examples of temporal outliers +include the results of video dropouts, head clogs, or tape tracking issues. +

+
+
‘vrep’
+

Identify vertical line repetition. Vertical line repetition includes +similar rows of pixels within a frame. In born-digital video vertical line +repetition is common, but this pattern is uncommon in video digitized from an +analog source. When it occurs in video that results from the digitization of an +analog source it can indicate concealment from a dropout compensator. +

+
+
‘brng’
+

Identify pixels that fall outside of legal broadcast range. +

+
+ +
+
color, c
+

Set the highlight color for the out option. The default color is +yellow. +

+
+ + +

39.233.1 Examples

+ +
    +
  • Output data of various video metrics: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
    +
    + +
  • Output specific data about the minimum and maximum values of the Y plane per frame: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
    +
    + +
  • Playback video while highlighting pixels that are outside of broadcast range in red. +
    +
    ffplay example.mov -vf signalstats="out=brng:color=red"
    +
    + +
  • Playback video with signalstats metadata drawn over the frame. +
    +
    ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
    +
    + +

    The contents of signalstat_drawtext.txt used in the command are: +

    +
    time %{pts:hms}
    +Y (%{metadata:lavfi.signalstats.YMIN}-%{metadata:lavfi.signalstats.YMAX})
    +U (%{metadata:lavfi.signalstats.UMIN}-%{metadata:lavfi.signalstats.UMAX})
    +V (%{metadata:lavfi.signalstats.VMIN}-%{metadata:lavfi.signalstats.VMAX})
    +saturation maximum: %{metadata:lavfi.signalstats.SATMAX}
    +
    +
    +
+ + +

39.234 signature

+ +

Calculates the MPEG-7 Video Signature. The filter can handle more than one +input. In this case the matching between the inputs can be calculated additionally. +The filter always passes through the first input. The signature of each stream can +be written into a file. +

+

It accepts the following options: +

+
+
detectmode
+

Enable or disable the matching process. +

+

Available values are: +

+
+
‘off’
+

Disable the calculation of a matching (default). +

+
‘full’
+

Calculate the matching for the whole video and output whether the whole video +matches or only parts. +

+
‘fast’
+

Calculate only until a matching is found or the video ends. Should be faster in +some cases. +

+
+ +
+
nb_inputs
+

Set the number of inputs. The option value must be a non negative integer. +Default value is 1. +

+
+
filename
+

Set the path to which the output is written. If there is more than one input, +the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive +integer), that will be replaced with the input number. If no filename is +specified, no output will be written. This is the default. +

+
+
format
+

Choose the output format. +

+

Available values are: +

+
+
‘binary’
+

Use the specified binary representation (default). +

+
‘xml’
+

Use the specified xml representation. +

+
+ +
+
th_d
+

Set threshold to detect one word as similar. The option value must be an integer +greater than zero. The default value is 9000. +

+
+
th_dc
+

Set threshold to detect all words as similar. The option value must be an integer +greater than zero. The default value is 60000. +

+
+
th_xh
+

Set threshold to detect frames as similar. The option value must be an integer +greater than zero. The default value is 116. +

+
+
th_di
+

Set the minimum length of a sequence in frames to recognize it as matching +sequence. The option value must be a non negative integer value. +The default value is 0. +

+
+
th_it
+

Set the minimum relation, that matching frames to all frames must have. +The option value must be a double value between 0 and 1. The default value is 0.5. +

+
+ + +

39.234.1 Examples

+ +
    +
  • To calculate the signature of an input video and store it in signature.bin: +
    +
    ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
    +
    + +
  • To detect whether two videos match and store the signatures in XML format in +signature0.xml and signature1.xml: +
    +
    ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -
    +
    + +
+ + +

39.235 siti

+ +

Calculate Spatial Information (SI) and Temporal Information (TI) scores for a video, +as defined in ITU-T Rec. P.910 (11/21): Subjective video quality assessment methods +for multimedia applications. Available PDF at https://www.itu.int/rec/T-REC-P.910-202111-S/en. +Note that this is a legacy implementation that corresponds to a superseded recommendation. +Refer to ITU-T Rec. P.910 (07/22) for the latest version: https://www.itu.int/rec/T-REC-P.910-202207-I/en +

+

It accepts the following option: +

+
+
print_summary
+

If set to 1, Summary statistics will be printed to the console. Default 0. +

+
+ + +

39.235.1 Examples

+
    +
  • To calculate SI/TI metrics and print summary: +
    +
    ffmpeg -i input.mp4 -vf siti=print_summary=1 -f null -
    +
    +
+ + +

39.236 smartblur

+ +

Blur the input video without impacting the outlines. +

+

It accepts the following options: +

+
+
luma_radius, lr
+

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. +

+
+
luma_strength, ls
+

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. +

+
+
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. +

+
+
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 luma_radius. +

+
+
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 luma_strength. +

+
+
chroma_threshold, ct
+

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 +in [-30,0] will filter edges. Default value is luma_threshold. +

+
+
alpha_radius, ar
+

Set the alpha 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 luma_radius. +

+
+
alpha_strength, as
+

Set the alpha 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 luma_strength. +

+
+
alpha_threshold, at
+

Set the alpha 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 luma_threshold. +

+
+ +

If a chroma or alpha option is not explicitly set, the corresponding luma value +is set. +

+ +

39.237 sobel

+

Apply sobel operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

39.237.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.238 spp

+ +

Apply a simple postprocessing filter that compresses and decompresses the image +at several (or - in the case of quality level 6 - all) shifts +and average the results. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-6. If set to 0, the filter will have no +effect. A value of 6 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding (default). +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
+ +
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+ + +

39.238.1 Commands

+ +

This filter supports the following commands: +

+
quality, level
+

Set quality level. The value max can be used to set the maximum level, +currently 6. +

+
+ + +

39.239 sr

+ +

Scale the input by applying one of the super-resolution methods based on +convolutional neural networks. Supported models: +

+ + +

Training scripts as well as scripts for model file (.pb) saving can be found at +https://github.com/XueweiMeng/sr/tree/sr_dnn_native. Original repository +is at https://github.com/HighVoltageRocknRoll/sr.git. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO backend +can load files for only its format. +

+
+
scale_factor
+

Set scale factor for SRCNN model. Allowed values are 2, 3 and 4. +Default value is 2. Scale factor is necessary for SRCNN model, because it accepts +input upscaled using bicubic upscaling with proper scale factor. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

39.240 sr_amf

+ +

Upscale (size increasing) for the input video using AMD Advanced Media Framework library for hardware acceleration. +Use advanced algorithms for upscaling with higher output quality. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
algorithm
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+
+
sr1-0
+

Video SR1.0 +This is a default value +

+
+
point
+

Point +

+
+
sr1-1
+

Video SR1.1 +

+
+
+ +
+
sharpness
+

Control hq scaler sharpening. The value is a float in the range of [0.0, 2.0] +

+
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+
+
keep-ratio
+

Force the scaler to keep the aspect ratio of the input image when the output size has a different aspect ratio. +Default value is false. +

+
+
fill
+

Specifies whether the output image outside the region of interest, +which does not fill the entire output surface should be filled with a solid color. +

+
+
+ + +

39.240.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    sr_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K with algorithm video SR1.1. +
    +
    sr_amf=4096:2160:algorithm=sr1-1
    +
    +
+ + +

39.241 ssim

+ +

Obtain the SSIM (Structural SImilarity Metric) 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 SSIM. +

+

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 filter stores the calculated SSIM of each frame. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the SSIM of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+ +

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

A description of each shown parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
Y, U, V, R, G, B
+

SSIM of the compared frames for the component specified by the suffix. +

+
+
All
+

SSIM of the compared frames for the whole frame. +

+
+
dB
+

Same as above but in dB representation. +

+
+ +

This filter also supports the framesync options. +

+ +

39.241.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] ssim="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The SSIM of each individual frame +is stored in stats.log. +

    +
  • Another example with both psnr and ssim at same time: +
    +
    ffmpeg -i main.mpg -i ref.mpg -lavfi  "ssim;[0:v][1:v]psnr" -f null -
    +
    + +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -
    +
    +
+ + +

39.242 stereo3d

+ +

Convert between different stereoscopic image formats. +

+

The filters accept the following options: +

+
+
in
+

Set stereoscopic image format of input. +

+

Available values for input image formats are: +

+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+

Default value is ‘sbsl’. +

+
+ +
+
out
+

Set stereoscopic image format of output. +

+
+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘arbg’
+

anaglyph red/blue gray +(red filter on left eye, blue filter on right eye) +

+
+
‘argg’
+

anaglyph red/green gray +(red filter on left eye, green filter on right eye) +

+
+
‘arcg’
+

anaglyph red/cyan gray +(red filter on left eye, cyan filter on right eye) +

+
+
‘arch’
+

anaglyph red/cyan half colored +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcc’
+

anaglyph red/cyan color +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcd’
+

anaglyph red/cyan color optimized with the least squares projection of dubois +(red filter on left eye, cyan filter on right eye) +

+
+
‘agmg’
+

anaglyph green/magenta gray +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmh’
+

anaglyph green/magenta half colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmc’
+

anaglyph green/magenta colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmd’
+

anaglyph green/magenta color optimized with the least squares projection of dubois +(green filter on left eye, magenta filter on right eye) +

+
+
‘aybg’
+

anaglyph yellow/blue gray +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybh’
+

anaglyph yellow/blue half colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybc’
+

anaglyph yellow/blue colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybd’
+

anaglyph yellow/blue color optimized with the least squares projection of dubois +(yellow filter on left eye, blue filter on right eye) +

+
+
‘ml’
+

mono output (left eye only) +

+
+
‘mr’
+

mono output (right eye only) +

+
+
‘chl’
+

checkerboard, left eye first +

+
+
‘chr’
+

checkerboard, right eye first +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+
+
‘hdmi’
+

HDMI frame pack +

+
+ +

Default value is ‘arcd’. +

+
+ + +

39.242.1 Examples

+ +
    +
  • Convert input video from side by side parallel to anaglyph yellow/blue dubois: +
    +
    stereo3d=sbsl:aybd
    +
    + +
  • Convert input video from above below (left eye above, right eye below) to side by side crosseye. +
    +
    stereo3d=abl:sbsr
    +
    +
+ + +

39.243 streamselect, astreamselect

+

Select video or audio streams. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. Default is 2. +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

39.243.1 Commands

+ +

The streamselect and astreamselect filter supports the following +commands: +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

39.243.2 Examples

+ +
    +
  • Select first 5 seconds 1st stream and rest of time 2nd stream: +
    +
    sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
    +
    + +
  • Same as above, but for audio: +
    +
    asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
    +
    +
+ + +

39.244 subtitles

+ +

Draw subtitles on top of input video using the libass library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libass. This filter also requires a build with libavcodec and +libavformat to convert the passed subtitles file to ASS (Advanced Substation +Alpha) subtitles format. +

+

The filter accepts the following options: +

+
+
filename, f
+

Set the filename of the subtitle file to read. It must be specified. +

+
+
original_size
+

Specify the size of the original video, the video for which the ASS file +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. +

+
+
fontsdir
+

Set a directory path containing fonts that can be used by the filter. +These fonts will be used in addition to whatever the font provider uses. +

+
+
alpha
+

Process alpha channel, by default alpha channel is untouched. +

+
+
charenc
+

Set subtitles input character encoding. subtitles filter only. Only +useful if not UTF-8. +

+
+
stream_index, si
+

Set subtitles stream index. subtitles filter only. +

+
+
force_style
+

Override default style or script info parameters of the subtitles. It accepts a +string containing ASS style format KEY=VALUE couples separated by ",". +

+
+
wrap_unicode
+

Break lines according to the Unicode Line Breaking Algorithm. Availability requires +at least libass release 0.17.0 (or LIBASS_VERSION 0x01600010), and libass must +have been built with libunibreak. +

+

The option is enabled by default except for native ASS. +

+
+ +

If the first key is not specified, it is assumed that the first value +specifies the filename. +

+

For example, to render the file sub.srt on top of the input +video, use the command: +

+
subtitles=sub.srt
+
+ +

which is equivalent to: +

+
subtitles=filename=sub.srt
+
+ +

To render the default subtitles stream from file video.mkv, use: +

+
subtitles=video.mkv
+
+ +

To render the second subtitles stream from that file, use: +

+
subtitles=video.mkv:si=1
+
+ +

To make the subtitles stream from sub.srt appear in 80% transparent blue +DejaVu Serif, use: +

+
subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
+
+ + +

39.245 super2xsai

+ +

Scale the input by 2x and smooth using the Super2xSaI (Scale and +Interpolate) pixel art scaling algorithm. +

+

Useful for enlarging pixel art images without reducing sharpness. +

+ +

39.246 swaprect

+ +

Swap two rectangular objects in video. +

+

This filter accepts the following options: +

+
+
w
+

Set object width. +

+
+
h
+

Set object height. +

+
+
x1
+

Set 1st rect x coordinate. +

+
+
y1
+

Set 1st rect y coordinate. +

+
+
x2
+

Set 2nd rect x coordinate. +

+
+
y2
+

Set 2nd rect y coordinate. +

+

All expressions are evaluated once for each frame. +

+
+ +

The all options are expressions containing the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
a
+

same as w / h +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+ + +

39.246.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.247 swapuv

+

Swap U & V plane. +

+ +

39.248 tblend

+

Blend successive video frames. +

+

See blend +

+ +

39.249 telecine

+ +

Apply telecine process to the video. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+ +
+
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
+
+ + +

39.250 thistogram

+ +

Compute and draw a color distribution histogram for the input video across time. +

+

Unlike histogram video filter which only shows histogram of single input frame +at certain time, this filter shows also past histograms of number of frames defined +by width option. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

The filter accepts the following options: +

+
+
width, w
+

Set width of single color component output. Default value is 0. +Value of 0 means width will be picked from input video. +This also set number of passed histograms to keep. +Allowed range is [0, 8192]. +

+
+
display_mode, d
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode, m
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components, c
+

Set what color components to display. +Default is 7. +

+
+
bgopacity, b
+

Set background opacity. Default is 0.9. +

+
+
envelope, e
+

Show envelope. Default is disabled. +

+
+
ecolor, ec
+

Set envelope color. Default is gold. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is replace. +

+
+ + +

39.251 threshold

+ +

Apply threshold effect to video stream. +

+

This filter needs four video streams to perform thresholding. +First stream is stream we are filtering. +Second stream is holding threshold values, third stream is holding min values, +and last, fourth stream is holding max values. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ +

For example if first stream pixel’s component value is less then threshold value +of pixel component from 2nd threshold stream, third stream value will picked, +otherwise fourth stream pixel component value will be picked. +

+

Using color source filter one can perform various types of thresholding: +

+ +

39.251.1 Commands

+ +

This filter supports the all options as commands. +

+ +

39.251.2 Examples

+ +
    +
  • Binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
    +
    + +
  • Inverted binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
    +
    + +
  • Truncate binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
    +
    + +
  • Threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
    +
    + +
  • Inverted threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
    +
    +
+ + +

39.252 thumbnail

+

Select the most representative frame in a given sequence of consecutive frames. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+
log
+

Set the log level to display picked frame stats. +Default is info. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

39.252.1 Examples

+ +
    +
  • Extract one picture each 50 frames: +
    +
    thumbnail=50
    +
    + +
  • Complete example of a thumbnail creation with ffmpeg: +
    +
    ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
    +
    +
+ + +

39.253 tile

+ +

Tile several successive frames together. +

+

The untile filter can do the reverse. +

+

The filter accepts the following options: +

+
+
layout
+

Set the grid size in the form COLUMNSxROWS. Range is up to UINT_MAX cells. +Default is 6x5. +

+
+
nb_frames
+

Set the maximum number of frames to render in the given area. It must be less +than or equal to wxh. The default value is 0, meaning all +the area will be used. +

+
+
margin
+

Set the outer border margin in pixels. Range is 0 to 1024. Default is 0. +

+
+
padding
+

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. Range is 0 to 1024. Default is 0. +

+
+
color
+

Specify the color of the unused area. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +The default value of color is "black". +

+
+
overlap
+

Set the number of frames to overlap when tiling several successive frames together. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+
init_padding
+

Set the number of frames to initially be empty before displaying first output frame. +This controls how soon will one get first output frame. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+ + +

39.253.1 Examples

+ +
    +
  • Produce 8x8 PNG tiles of all keyframes (-skip_frame nokey) in a movie: +
    +
    ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
    +
    +

    The -vsync 0 is necessary to prevent ffmpeg from +duplicating each output frame to accommodate the originally detected frame +rate. +

    +
  • Display 5 pictures in an area of 3x2 frames, +with 7 pixels between them, and 2 pixels of initial margin, using +mixed flat and named options: +
    +
    tile=3x2:nb_frames=5:padding=7:margin=2
    +
    +
+ + +

39.254 tiltandshift

+

Apply tilt-and-shift effect. +

+

What happens when you invert time and space? +

+

Normally a video is composed of several frames that represent a different +instant of time and shows a scene that evolves in the space captured by the +frame. This filter is the antipode of that concept, taking inspiration from +tilt and shift photography. +

+

A filtered frame contains the whole timeline of events composing the sequence, +and this is obtained by placing a slice of pixels from each frame into a single +one. However, since there are no infinite-width frames, this is done up the +width of the input frame, and a video is recomposed by shifting away one +column for each subsequent frame. In order to map space to time, the filter +tilts each input frame as well, so that motion is preserved. This is accomplished +by progressively selecting a different column from each input frame. +

+

The end result is a sort of inverted parallax, so that far away objects move +much faster that the ones in the front. The ideal conditions for this video +effect are when there is either very little motion and the background is static, +or when there is a lot of motion and a very wide depth of field (e.g. wide +panorama, while moving on a train). +

+

The filter accepts the following parameters: +

+
+
tilt
+

Tilt video while shifting (default). When unset, video will be sliding a +static image, composed of the first column of each frame. +

+
+
start
+

What to do at the start of filtering (see below). +

+
+
end
+

What to do at the end of filtering (see below). +

+
+
hold
+

How many columns should pass through before start of filtering. +

+
+
pad
+

How many columns should be inserted before end of filtering. +

+
+
+ +

Normally the filter shifts and tilts from the very first frame, and stops when +the last one is received. However, before filtering starts, normal video may +be preserved, so that the effect is slowly shifted in its place. Similarly, +the last video frame may be reconstructed at the end. Alternatively it is +possible to just start and end with black. +

+
+
‘none’
+

Filtering starts immediately and ends when the last frame is received. +

+
+
‘frame’
+

The first frames or the very last frame are kept intact during processing. +

+
+
‘black’
+

Black is padded at the beginning or at the end of filtering. +

+
+
+ + +

39.255 tinterlace

+ +

Perform various types of temporal field interlacing. +

+

Frames are counted starting from 1, so the first input frame is +considered odd. +

+

The filter accepts the following options: +

+
+
mode
+

Specify the mode of the interlacing. This option can also be specified +as a value alone. See below for a list of values for this option. +

+

Available values are: +

+
+
‘merge, 0’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at half frame rate. +

+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ +
+
‘drop_even, 1’
+

Only output odd frames, even frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+11111                           33333
+11111                           33333
+11111                           33333
+
+ +
+
‘drop_odd, 2’
+

Only output even frames, odd frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+                22222                           44444
+                22222                           44444
+                22222                           44444
+                22222                           44444
+
+ +
+
‘pad, 3’
+

Expand each frame to full height, but pad alternate lines with black, +generating a frame with double height at the same input frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+
+Output:
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+
+ + +
+
‘interlacex2, 6’
+

Double frame rate with unchanged height. Frames are inserted each +containing the second temporal field from the previous input frame and +the first temporal field from the next input frame. This mode relies on +the top_field_first flag. Useful for interlaced video displays with no +field synchronisation. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+
+Output:
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+
+ + +
+
‘mergex2, 7’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at same frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+
+ +
+
+ +

Numeric values are deprecated but are accepted for backward +compatibility reasons. +

+

Default mode is merge. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
low_pass_filter, vlpf
+

Enable linear vertical low-pass filtering in the filter. +Vertical low-pass filtering is required when creating an interlaced +destination from a progressive source which contains high-frequency +vertical detail. Filtering will reduce interlace ’twitter’ and Moire +patterning. +

+
+
complex_filter, cvlpf
+

Enable complex vertical low-pass filtering. +This will slightly less reduce interlace ’twitter’ and Moire +patterning but better retain detail and subjective sharpness impression. +

+
+
bypass_il
+

Bypass already interlaced frames, only adjust the frame rate. +

+
+ +

Vertical low-pass filtering and bypassing already interlaced frames can only be +enabled for mode interleave_top and interleave_bottom. +

+
+
+ + +

39.256 tmedian

+

Pick median pixels from several successive input video frames. +

+

The filter accepts the following options: +

+
+
radius
+

Set radius of median filter. +Default is 1. Allowed range is from 1 to 127. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

39.256.1 Commands

+ +

This filter supports all above options as commands, excluding option radius. +

+ +

39.257 tmidequalizer

+ +

Apply Temporal Midway Video Equalization effect. +

+

Midway Video Equalization adjusts a sequence of video frames to have the same +histograms, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a video frames sequence. +

+

This filter accepts the following option: +

+
+
radius
+

Set filtering radius. Default is 5. Allowed range is from 1 to 127. +

+
+
sigma
+

Set filtering sigma. Default is 0.5. This controls strength of filtering. +Setting this option to 0 effectively does nothing. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

39.258 tmix

+ +

Mix successive video frames. +

+

A description of the accepted options follows. +

+
+
frames
+

The number of successive frames to mix. If unspecified, it defaults to 3. +

+
+
weights
+

Specify weight of each input video frame. +Each weight is separated by space. If number of weights is smaller than +number of frames last specified weight will be used for all remaining +unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

39.258.1 Examples

+ +
    +
  • Average 7 successive frames: +
    +
    tmix=frames=7:weights="1 1 1 1 1 1 1"
    +
    + +
  • Apply simple temporal convolution: +
    +
    tmix=frames=3:weights="-1 3 -1"
    +
    + +
  • Similar as above but only showing temporal differences: +
    +
    tmix=frames=3:weights="-1 2 -1":scale=1
    +
    +
+ + +

39.258.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

39.259 tonemap

+

Tone map colors from different dynamic ranges. +

+

This filter expects data in single precision floating point, as it needs to +operate on (and can output) out-of-range values. Another filter, such as +zscale, is needed to convert the resulting frame to a usable format. +

+

The tonemapping algorithms implemented only work on linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

39.259.1 Options

+

The filter accepts the following options. +

+
+
tonemap
+

Set the tone map algorithm to use. +

+

Possible values are: +

+
none
+

Do not apply any tone map, only desaturate overbright pixels. +

+
+
clip
+

Hard-clip any out-of-range values. Use it for perfect color accuracy for +in-range values, while distorting out-of-range values. +

+
+
linear
+

Stretch the entire reference gamut to a linear multiple of the display. +

+
+
gamma
+

Fit a logarithmic transfer between the tone curves. +

+
+
reinhard
+

Preserve overall image brightness with a simple curve, using nonlinear +contrast, which results in flattening details and degrading color accuracy. +

+
+
hable
+

Preserve both dark and bright details better than reinhard, at the cost +of slightly darkening everything. Use it when detail preservation is more +important than color and brightness accuracy. +

+
+
mobius
+

Smoothly map out-of-range values, while retaining contrast and colors for +in-range material as much as possible. Use it when color accuracy is more +important than detail preservation. +

+
+ +

Default is none. +

+
+
param
+

Tune the tone mapping algorithm. +

+

This affects the following algorithms: +

+
none
+

Ignored. +

+
+
linear
+

Specifies the scale factor to use while stretching. +Default to 1.0. +

+
+
gamma
+

Specifies the exponent of the function. +Default to 1.8. +

+
+
clip
+

Specify an extra linear coefficient to multiply into the signal before clipping. +Default to 1.0. +

+
+
reinhard
+

Specify the local contrast coefficient at the display peak. +Default to 0.5, which means that in-gamut values will be about half as bright +as when clipping. +

+
+
hable
+

Ignored. +

+
+
mobius
+

Specify the transition point from linear to mobius transform. Every value +below this point is guaranteed to be mapped 1:1. The higher the value, the +more accurate the result will be, at the cost of losing bright details. +Default to 0.3, which due to the steep initial slope still preserves in-range +colors fairly accurately. +

+
+ +
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default of 2.0 is somewhat conservative and will mostly just apply to +skies or directly sunlit surfaces. A setting of 0.0 disables this option. +

+

This option works only if the input frame has a supported color tag. +

+
+
peak
+

Override signal/nominal/reference peak with this value. Useful when the +embedded peak information in display metadata is not reliable or when tone +mapping from a lower range to a higher range. +

+
+ + +

39.260 tpad

+ +

Temporarily pad video frames. +

+

The filter accepts the following options: +

+
+
start
+

Specify number of delay frames before input video stream. Default is 0. +

+
+
stop
+

Specify number of padding frames after input video stream. +Set to -1 to pad indefinitely. Default is 0. +

+
+
start_mode
+

Set kind of frames added to beginning of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of first frame. +Default is add. +

+
+
stop_mode
+

Set kind of frames added to end of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of last frame. +Default is add. +

+
+
start_duration, stop_duration
+

Specify the duration of the start/stop delay. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +These options override start and stop. Default is 0. +

+
+
color
+

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 color is "black". +

+
+ + +

39.261 transpose

+ +

Transpose rows with columns in the input video and optionally flip it. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘0, 4, cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip (default), that is: +

+
L.R     L.l
+. . ->  . .
+l.r     R.r
+
+ +
+
‘1, 5, clock’
+

Rotate by 90 degrees clockwise, that is: +

+
L.R     l.L
+. . ->  . .
+l.r     r.R
+
+ +
+
‘2, 6, cclock’
+

Rotate by 90 degrees counterclockwise, that is: +

+
L.R     R.r
+. . ->  . .
+l.r     L.l
+
+ +
+
‘3, 7, clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip, that is: +

+
L.R     r.R
+. . ->  . .
+l.r     l.L
+
+
+
+ +

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 passthrough option should be used instead. +

+

Numerical values are deprecated, and should be dropped in favor of +symbolic constants. +

+
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +

Default value is none. +

+
+ +

For example to rotate by 90 degrees clockwise and preserve portrait +layout: +

+
transpose=dir=1:passthrough=portrait
+
+ +

The command above can also be specified as: +

+
transpose=1:portrait
+
+ + +

39.262 trim

+

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Specify the time of the start of the kept section, i.e. the frame with the +timestamp start will be the first frame in the output. +

+
+
end
+

Specify the time of the first frame that will be dropped, i.e. the frame +immediately preceding the one with the timestamp end will be the last +frame in the output. +

+
+
start_pts
+

This is the same as start, except this option sets the start timestamp +in timebase units instead of seconds. +

+
+
end_pts
+

This is the same as end, except this option sets the end timestamp +in timebase units instead of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_frame
+

The number of the first frame that should be passed to the output. +

+
+
end_frame
+

The number of the first frame that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

Note that the first two sets of the start/end options and the 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 for the output timestamps to 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -vf trim=60:120
    +
    + +
  • Keep only the first second: +
    +
    ffmpeg -i INPUT -vf trim=duration=1
    +
    + +
+ + +

39.263 unpremultiply

+

Apply alpha unpremultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+

If the format has 1 or 2 components, then luma is bit 0. +If the format has 3 or 4 components: +for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; +for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. +If present, the alpha channel is always the last bit. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

39.264 unsharp

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. It must be an odd integer between +3 and 23. The default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. It must be an odd integer between 3 +and 23. The default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. It must be a floating point 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. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. It must be a floating point 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 0.0. +

+
+
alpha_msize_x, ax
+

Set the alpha matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_msize_y, ay
+

Set the alpha matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_amount, aa
+

Set the alpha effect strength. It must be a floating point 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 0.0. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

39.264.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    unsharp=7:7:-2:7:7:-2
    +
    +
+ + +

39.265 untile

+ +

Decompose a video made of tiled images into the individual images. +

+

The frame rate of the output video is the frame rate of the input video +multiplied by the number of tiles. +

+

This filter does the reverse of tile. +

+

The filter accepts the following options: +

+
+
layout
+

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. +

+
+ + +

39.265.1 Examples

+ +
    +
  • Produce a 1-second video from a still image file made of 25 frames stacked +vertically, like an analogic film reel: +
    +
    ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
    +
    +
+ + +

39.266 uspp

+ +

Apply ultra slow/simple postprocessing filter that compresses and decompresses +the image at several (or - in the case of quality level 8 - all) +shifts and average the results. +

+

The way this differs from the behavior of spp is that uspp actually encodes & +decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 +DCT similar to MJPEG. +

+

This filter is not available in ffmpeg versions between 5.0 and 6.0. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-8. If set to 0, the filter will have no +effect. A value of 8 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
codec
+

Use specified codec instead of snow. +

+
+ + +

39.267 v360

+ +

Convert 360 videos between various formats. +

+

The filter accepts the following options: +

+
+
input
+
output
+

Set format of the input/output video. +

+

Available formats: +

+
+
‘e’
+
‘equirect’
+

Equirectangular projection. +

+
+
‘c3x2’
+
‘c6x1’
+
‘c1x6’
+

Cubemap with 3x2/6x1/1x6 layout. +

+

Format specific options: +

+
+
in_pad
+
out_pad
+

Set padding proportion for the input/output cubemap. Values in decimals. +

+

Example values: +

+
‘0’
+

No padding. +

+
‘0.01’
+

1% of face is padding. For example, with 1920x1280 resolution face size would be 640x640 and padding would be 3 pixels from each side. (640 * 0.01 = 6 pixels) +

+
+ +

Default value is ‘0’. +Maximum value is ‘0.1’. +

+
+
fin_pad
+
fout_pad
+

Set fixed padding for the input/output cubemap. Values in pixels. +

+

Default value is ‘0’. If greater than zero it overrides other padding options. +

+
+
in_forder
+
out_forder
+

Set order of faces for the input/output cubemap. Choose one direction for each position. +

+

Designation of directions: +

+
‘r’
+

right +

+
‘l’
+

left +

+
‘u’
+

up +

+
‘d’
+

down +

+
‘f’
+

forward +

+
‘b’
+

back +

+
+ +

Default value is ‘rludfb’. +

+
+
in_frot
+
out_frot
+

Set rotation of faces for the input/output cubemap. Choose one angle for each position. +

+

Designation of angles: +

+
‘0’
+

0 degrees clockwise +

+
‘1’
+

90 degrees clockwise +

+
‘2’
+

180 degrees clockwise +

+
‘3’
+

270 degrees clockwise +

+
+ +

Default value is ‘000000’. +

+
+ +
+
‘eac’
+

Equi-Angular Cubemap. +

+
+
‘flat’
+
‘gnomonic’
+
‘rectilinear’
+

Regular video. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘dfisheye’
+

Dual fisheye. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘barrel’
+
‘fb’
+
‘barrelsplit’
+

Facebook’s 360 formats. +

+
+
‘sg’
+

Stereographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘mercator’
+

Mercator format. +

+
+
‘ball’
+

Ball format, gives significant distortion toward the back. +

+
+
‘hammer’
+

Hammer-Aitoff map projection format. +

+
+
‘sinusoidal’
+

Sinusoidal map projection format. +

+
+
‘fisheye’
+

Fisheye projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘pannini’
+

Pannini projection. +

+

Format specific options: +

+
h_fov
+

Set output pannini parameter. +

+
+
ih_fov
+

Set input pannini parameter. +

+
+ +
+
‘cylindrical’
+

Cylindrical projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘perspective’
+

Perspective projection. (output only) +

+

Format specific options: +

+
v_fov
+

Set perspective parameter. +

+
+ +
+
‘tetrahedron’
+

Tetrahedron projection. +

+
+
‘tsp’
+

Truncated square pyramid projection. +

+
+
‘he’
+
‘hequirect’
+

Half equirectangular projection. +

+
+
‘equisolid’
+

Equisolid format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘og’
+

Orthographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘octahedron’
+

Octahedron projection. +

+
+
‘cylindricalea’
+

Cylindrical Equal Area projection. +

+
+ +
+
interp
+

Set interpolation method.
+Note: more complex interpolation methods require much more memory to run. +

+

Available methods: +

+
+
‘near’
+
‘nearest’
+

Nearest neighbour. +

+
‘line’
+
‘linear’
+

Bilinear interpolation. +

+
‘lagrange9’
+

Lagrange9 interpolation. +

+
‘cube’
+
‘cubic’
+

Bicubic interpolation. +

+
‘lanc’
+
‘lanczos’
+

Lanczos interpolation. +

+
‘sp16’
+
‘spline16’
+

Spline16 interpolation. +

+
‘gauss’
+
‘gaussian’
+

Gaussian interpolation. +

+
‘mitchell’
+

Mitchell interpolation. +

+
+ +

Default value is ‘line’. +

+
+
w
+
h
+

Set the output video resolution. +

+

Default resolution depends on formats. +

+
+
in_stereo
+
out_stereo
+

Set the input/output stereo format. +

+
+
‘2d’
+

2D mono +

+
‘sbs’
+

Side by side +

+
‘tb’
+

Top bottom +

+
+ +

Default value is ‘2d’ for input and output format. +

+
+
yaw
+
pitch
+
roll
+

Set rotation for the output video. Values in degrees. +

+
+
rorder
+

Set rotation order for the output video. Choose one item for each position. +

+
+
‘y, Y’
+

yaw +

+
‘p, P’
+

pitch +

+
‘r, R’
+

roll +

+
+ +

Default value is ‘ypr’. +

+
+
h_flip
+
v_flip
+
d_flip
+

Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values. +

+
+
ih_flip
+
iv_flip
+

Set if input video is flipped horizontally/vertically. Boolean values. +

+
+
in_trans
+

Set if input video is transposed. Boolean value, by default disabled. +

+
+
out_trans
+

Set if output video needs to be transposed. Boolean value, by default disabled. +

+
+
h_offset
+
v_offset
+

Set output horizontal/vertical off-axis offset. Default is set to 0. +Allowed range is from -1 to 1. +

+
+
alpha_mask
+

Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled. +

+
+
reset_rot
+

Reset rotation of output video. Boolean value, by default disabled. +

+
+ + +

39.267.1 Examples

+ +
    +
  • Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation: +
    +
    ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
    +
    +
  • Extract back view of Equi-Angular Cubemap: +
    +
    ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
    +
    +
  • Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format: +
    +
    v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
    +
    +
+ + +

39.267.2 Commands

+ +

This filter supports subset of above options as commands. +

+ +

39.268 vaguedenoiser

+ +

Apply a wavelet based denoiser. +

+

It transforms each frame from the video input into the wavelet domain, +using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to +the obtained coefficients. It does an inverse wavelet transform after. +Due to wavelet properties, it should give a nice smoothed result, and +reduced noise, without blurring picture features. +

+

This filter accepts the following options: +

+
+
threshold
+

The filtering strength. The higher, the more filtered the video will be. +Hard thresholding can use a higher threshold than soft thresholding +before the video looks overfiltered. Default value is 2. +

+
+
method
+

The filtering method the filter will use. +

+

It accepts the following values: +

+
‘hard’
+

All values under the threshold will be zeroed. +

+
+
‘soft’
+

All values under the threshold will be zeroed. All values above will be +reduced by the threshold. +

+
+
‘garrote’
+

Scales or nullifies coefficients - intermediary between (more) soft and +(less) hard thresholding. +

+
+ +

Default is garrote. +

+
+
nsteps
+

Number of times, the wavelet will decompose the picture. Picture can’t +be decomposed beyond a particular point (typically, 8 for a 640x480 +frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. +

+
+
percent
+

Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. +

+
+
planes
+

A list of the planes to process. By default all planes are processed. +

+
+
type
+

The threshold type the filter will use. +

+

It accepts the following values: +

+
‘universal’
+

Threshold used is same for all decompositions. +

+
+
‘bayes’
+

Threshold used depends also on each decomposition coefficients. +

+
+ +

Default is universal. +

+
+ + +

39.269 varblur

+

Apply variable blur filter by using 2nd video stream to set blur radius. +The 2nd stream must have the same dimensions. +

+

This filter accepts the following options: +

+
+
min_r
+

Set min allowed radius. Allowed range is from 0 to 254. Default is 0. +

+
max_r
+

Set max allowed radius. Allowed range is from 1 to 255. Default is 8. +

+
planes
+

Set which planes to process. By default, all are used. +

+
+ +

The varblur filter also supports the framesync options. +

+ +

39.269.1 Commands

+ +

This filter supports all the above options as commands. +

+ +

39.270 vectorscope

+ +

Display 2 color component values in the two dimensional graph (which is called +a vectorscope). +

+

This filter accepts the following options: +

+
+
mode, m
+

Set vectorscope mode. +

+

It accepts the following values: +

+
‘gray’
+
‘tint’
+

Gray values are displayed on graph, higher brightness means more pixels have +same component color value on location in graph. This is the default mode. +

+
+
‘color’
+

Gray values are displayed on graph. Surrounding pixels values which are not +present in video frame are drawn in gradient of 2 color components which are +set by option x and y. The 3rd color component is static. +

+
+
‘color2’
+

Actual color components values present in video frame are displayed on graph. +

+
+
‘color3’
+

Similar as color2 but higher frequency of same values x and y +on graph increases value of another color component, which is luminance by +default values of x and y. +

+
+
‘color4’
+

Actual colors present in video frame are displayed on graph. If two different +colors map to same position on graph then color with higher value of component +not present in graph is picked. +

+
+
‘color5’
+

Gray values are displayed on graph. Similar to color but with 3rd color +component picked from radial gradient. +

+
+ +
+
x
+

Set which color component will be represented on X-axis. Default is 1. +

+
+
y
+

Set which color component will be represented on Y-axis. Default is 2. +

+
+
intensity, i
+

Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness +of color component which represents frequency of (X, Y) location in graph. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, even darkest single pixel will be clearly highlighted. +

+
+
‘peak’
+

Hold maximum and minimum values presented in graph over time. This way you +can still spot out of range values without constantly looking at vectorscope. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
graticule, g
+

Set what kind of graticule to draw. +

+
‘none’
+
‘green’
+
‘color’
+
‘invert’
+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, f
+

Set graticule flags. +

+
+
‘white’
+

Draw graticule for white point. +

+
+
‘black’
+

Draw graticule for black point. +

+
+
‘name’
+

Draw color points short names. +

+
+ +
+
bgopacity, b
+

Set background opacity. +

+
+
lthreshold, l
+

Set low threshold for color component not represented on X or Y axis. +Values lower than this value will be ignored. Default is 0. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and low threshold value of 0.1 actual threshold +is 0.1 * 255 = 25. +

+
+
hthreshold, h
+

Set high threshold for color component not represented on X or Y axis. +Values higher than this value will be ignored. Default is 1. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and high threshold value of 0.9 actual threshold +is 0.9 * 255 = 230. +

+
+
colorspace, c
+

Set what kind of colorspace to use when drawing graticule. +

+
‘auto’
+
‘601’
+
‘709’
+
+

Default is auto. +

+
+
tint0, t0
+
tint1, t1
+

Set color tint for gray/tint vectorscope mode. By default both options are zero. +This means no tint, and output will remain gray. +

+
+ + +

39.271 vidstabdetect

+ +

Analyze video stabilization/deshaking. Perform pass 1 of 2, see +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 vidstabtransform filter. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libvidstab. +

+

This filter accepts the following options: +

+
+
result
+

Set the path to the file used to write the transforms information. +Default value is transforms.trf. +

+
+
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. +

+
+
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 15. +

+
+
stepsize
+

Set stepsize of the search process. The region around minimum is +scanned with 1 pixel resolution. Default value is 6. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
fileformat
+

Format for the transforms data file to be written. +Acceptable values are +

+
+
‘ascii’
+

Human-readable plain text +

+
+
‘binary’
+

Binary format, roughly 40% smaller than ascii. (default) +

+
+ +
+
+ + +

39.271.1 Examples

+ +
    +
  • Use default values: +
    +
    vidstabdetect
    +
    + +
  • Analyze strongly shaky movie and put the results in file +mytransforms.trf: +
    +
    vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
    +
    + +
  • Visualize the result of internal transformations in the resulting +video: +
    +
    vidstabdetect=show=1
    +
    + +
  • Analyze a video with medium shakiness using ffmpeg: +
    +
    ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
    +
    +
+ + +

39.272 vidstabtransform

+ +

Video stabilization/deshaking: pass 2 of 2, +see vidstabdetect for pass 1. +

+

Read a file with transform information for each frame and +apply/compensate them. Together with the vidstabdetect +filter this can be used to deshake videos. See also +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 +--enable-libvidstab. +

+ +

39.272.1 Options

+ +
+
input
+

Set path to the file used to read the transforms. Default value is +transforms.trf. +

+
+
smoothing
+

Set the number of frames (value*2 + 1) used for lowpass filtering the +camera movements. Default value is 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 value leads to a smoother video, but limits the acceleration of +the camera (pan/tilt movements). 0 is a special case where a static +camera is simulated. +

+
+
optalgo
+

Set the camera path optimization algorithm. +

+

Accepted values are: +

+
‘gauss’
+

gaussian kernel low-pass filter on camera motion (default) +

+
‘avg’
+

averaging on transformations +

+
+ +
+
maxshift
+

Set maximal number of pixels to translate frames. Default value is -1, +meaning no limit. +

+
+
maxangle
+

Set maximal angle in radians (degree*PI/180) to rotate frames. Default +value is -1, meaning no limit. +

+
+
crop
+

Specify how to deal with borders that may be visible due to movement +compensation. +

+

Available values are: +

+
‘keep’
+

keep image information from previous frame (default) +

+
‘black’
+

fill the border black +

+
+ +
+
invert
+

Invert transforms if set to 1. Default value is 0. +

+
+
relative
+

Consider transforms as relative to previous frame if set to 1, +absolute if set to 0. Default value is 0. +

+
+
zoom
+

Set percentage to zoom. A positive value will result in a zoom-in +effect, a negative value in a zoom-out effect. Default value is 0 (no +zoom). +

+
+
optzoom
+

Set optimal zooming to avoid borders. +

+

Accepted values are: +

+
‘0’
+

disabled +

+
‘1’
+

optimal static zoom value is determined (only very strong movements +will lead to visible borders) (default) +

+
‘2’
+

optimal adaptive zoom value is determined (no borders will be +visible), see zoomspeed +

+
+ +

Note that the value given at zoom is added to the one calculated here. +

+
+
zoomspeed
+

Set percent to zoom maximally each frame (enabled when +optzoom is set to 2). Range is from 0 to 5, default value is +0.25. +

+
+
interpol
+

Specify type of interpolation. +

+

Available values are: +

+
‘no’
+

no interpolation +

+
‘linear’
+

linear only horizontal +

+
‘bilinear’
+

linear in both directions (default) +

+
‘bicubic’
+

cubic in both directions (slow) +

+
+ +
+
tripod
+

Enable virtual tripod mode if set to 1, which is equivalent to +relative=0:smoothing=0. Default value is 0. +

+

Use also tripod option of vidstabdetect. +

+
+
debug
+

Increase log verbosity if set to 1. Also the detected global motions +are written to the temporary file global_motions.trf. Default +value is 0. +

+
+ + +

39.272.2 Examples

+ +
    +
  • Use ffmpeg for a typical stabilization with default values: +
    +
    ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
    +
    + +

    Note the use of the unsharp filter which is always recommended. +

    +
  • Zoom in a bit more and load transform data from a given file: +
    +
    vidstabtransform=zoom=5:input="mytransforms.trf"
    +
    + +
  • Smoothen the video even more: +
    +
    vidstabtransform=smoothing=30
    +
    +
+ + +

39.273 vflip

+ +

Flip the input video vertically. +

+

For example, to vertically flip a video with ffmpeg: +

+
ffmpeg -i in.avi -vf "vflip" out.avi
+
+ + +

39.274 vfrdet

+ +

Detect variable frame rate video. +

+

This filter tries to detect if the input is variable or constant frame rate. +

+

At end it will output number of frames detected as having variable delta pts, +and ones with constant delta pts. +If there was frames with variable delta, than it will also show min, max and +average delta encountered. +

+ +

39.275 vibrance

+ +

Boost or alter saturation. +

+

The filter accepts the following options: +

+
intensity
+

Set strength of boost if positive value or strength of alter if negative value. +Default is 0. Allowed range is from -2 to 2. +

+
+
rbal
+

Set the red balance. Default is 1. Allowed range is from -10 to 10. +

+
+
gbal
+

Set the green balance. Default is 1. Allowed range is from -10 to 10. +

+
+
bbal
+

Set the blue balance. Default is 1. Allowed range is from -10 to 10. +

+
+
rlum
+

Set the red luma coefficient. +

+
+
glum
+

Set the green luma coefficient. +

+
+
blum
+

Set the blue luma coefficient. +

+
+
alternate
+

If intensity is negative and this is set to 1, colors will change, +otherwise colors will be less saturated, more towards gray. +

+
+ + +

39.275.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

39.276 vif

+ +

Obtain the average VIF (Visual Information Fidelity) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 VIF score is printed through the logging system. +

+

The filter stores the calculated VIF score of each frame. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi vif -f null -
+
+ + +

39.277 vignette

+ +

Make or reverse a natural vignetting effect. +

+

The filter accepts the following options: +

+
+
angle, a
+

Set lens angle expression as a number of radians. +

+

The value is clipped in the [0,PI/2] range. +

+

Default value: "PI/5" +

+
+
x0
+
y0
+

Set center coordinates expressions. Respectively "w/2" and "h/2" +by default. +

+
+
mode
+

Set forward/backward mode. +

+

Available modes are: +

+
‘forward’
+

The larger the distance from the central point, the darker the image becomes. +

+
+
‘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 angle and other settings (yet). It can +also be used to create a burning effect. +

+
+ +

Default value is ‘forward’. +

+
+
eval
+

Set evaluation mode for the expressions (angle, x0, y0). +

+

It accepts the following values: +

+
‘init’
+

Evaluate expressions only once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. This is way slower than the +‘init’ mode since it requires all the scalers to be re-computed, but it +allows advanced dynamic expressions. +

+
+ +

Default value is ‘init’. +

+
+
dither
+

Set dithering to reduce the circular banding effects. Default is 1 +(enabled). +

+
+
aspect
+

Set vignette aspect. This setting allows one 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 1/1. +

+
+ + +

39.277.1 Expressions

+ +

The alpha, x0 and y0 expressions can contain the +following parameters. +

+
+
w
+
h
+

input width and height +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pts
+

the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in +TB units, NAN if undefined +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined +

+
+
tb
+

time base of the input video +

+
+ + + +

39.277.2 Examples

+ +
    +
  • Apply simple strong vignetting effect: +
    +
    vignette=PI/4
    +
    + +
  • Make a flickering vignetting: +
    +
    vignette='PI/4+random(1)*PI/50':eval=frame
    +
    + +
+ + +

39.278 vmafmotion

+ +

Obtain the average VMAF motion score of a video. +It is one of the component metrics of VMAF. +

+

The obtained average motion score is printed through the logging system. +

+

The filter accepts the following options: +

+
+
stats_file
+

If specified, the filter will use the named file to save the motion score of +each frame with respect to the previous frame. +When filename equals "-" the data is sent to standard output. +

+
+ +

Example: +

+
ffmpeg -i ref.mpg -vf vmafmotion -f null -
+
+ + +

39.279 vpp_amf

+ +

Scale (resize) and convert colorspace, transfer characteristics or color primaries for the input video, using AMD Advanced Media Framework library for hardware acceleration. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
scale_type
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+

This is the default. +

+
+
bicubic
+

Bicubic +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+ +
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
color_profile
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt601’
+

BT.601 +

+
+
‘bt709’
+

BT.709 +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘linear’
+

Linear +

+
+
‘log’
+

LOG +

+
+
‘log-sqrt’
+

LOG_SQRT +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘bt1361-ecg’
+

BT1361_ECG +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
‘smpte2084’
+

SMPTE2084 +

+
+
‘smpte428’
+

SMPTE428 +

+
+
‘arib-std-b67’
+

ARIB_STD_B67 +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘smpte428’
+

SMPTE-428 +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+
+
+ + +

39.279.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    vpp_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K and change color profile to bt2020. +
    +
    vpp_amf=4096:2160:color_profile=bt2020
    +
    +
+ + +

39.280 vstack

+

Stack input videos vertically. +

+

All streams must be of same pixel format and of same width. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

39.281 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. +

+

This filter uses 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 setfield filter before w3fdif filter. +

+

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: +

+
+
filter
+

Set the interlacing filter coefficients. Accepts one of the following values: +

+
+
‘simple’
+

Simple filter coefficient set. +

+
‘complex’
+

More-complex filter coefficient set. +

+
+

Default value is ‘complex’. +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames, +

+
‘interlaced’
+

Only deinterlace frames marked as interlaced. +

+
+ +

Default value is ‘all’. +

+
+ + +

39.281.1 Commands

+

This filter supports same commands as options. +

+ +

39.282 waveform

+

Video waveform monitor. +

+

The waveform monitor plots color component intensity. By default luma +only. Each column of the waveform corresponds to a column of pixels in the +source video. +

+

It accepts the following options: +

+
+
mode, m
+

Can be either row, or column. Default is column. +In row mode, the graph on the left side represents color component value 0 and +the right side represents value = 255. In column mode, the top side represents +color component value = 0 and bottom side represents value = 255. +

+
+
intensity, i
+

Set intensity. Smaller values are useful to find out how many values of the same +luminance are distributed across input rows/columns. +Default value is 0.04. Allowed range is [0, 1]. +

+
+
mirror, r
+

Set mirroring mode. 0 means unmirrored, 1 means mirrored. +In mirrored mode, higher values will be represented on the left +side for row mode and at the top for column mode. Default is +1 (mirrored). +

+
+
display, d
+

Set display mode. +It accepts the following values: +

+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+

This display mode makes it easier to spot relative differences or similarities +in overlapping areas of the color components that are supposed to be identical, +such as neutral whites, grays, or blacks. +

+
+
‘stack’
+

Display separate graph for the color components side by side in +row mode or one below the other in column mode. +

+
+
‘parade’
+

Display separate graph for the color components side by side in +column mode or one below the other in row mode. +

+

Using this display mode makes it easy to spot color casts in the highlights +and shadows of an image, by comparing the contours of the top and the bottom +graphs of each waveform. Since whites, grays, and blacks are characterized +by exactly equal amounts of red, green, and blue, neutral areas of the picture +should display three waveforms of roughly equal width/height. If not, the +correction is easy to perform by making level adjustments the three waveforms. +

+
+

Default is stack. +

+
+
components, c
+

Set which color components to display. Default is 1, which means only luma +or red color component if input is in RGB colorspace. If is set for example to +7 it will display all 3 (if) available color components. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, minimum and maximum values presented in graph will be easily +visible even with small step value. +

+
+
‘peak’
+

Hold minimum and maximum values presented in graph across time. This way you +can still spot out of range values without constantly looking at waveforms. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
filter, f
+
+
‘lowpass’
+

No filtering, this is default. +

+
+
‘flat’
+

Luma and chroma combined together. +

+
+
‘aflat’
+

Similar as above, but shows difference between blue and red chroma. +

+
+
‘xflat’
+

Similar as above, but use different colors. +

+
+
‘yflat’
+

Similar as above, but again with different colors. +

+
+
‘chroma’
+

Displays only chroma. +

+
+
‘color’
+

Displays actual color value on waveform. +

+
+
‘acolor’
+

Similar as above, but with luma showing frequency of chroma values. +

+
+ +
+
graticule, g
+

Set which graticule to display. +

+
+
‘none’
+

Do not display graticule. +

+
+
‘green’
+

Display green graticule showing legal broadcast ranges. +

+
+
‘orange’
+

Display orange graticule showing legal broadcast ranges. +

+
+
‘invert’
+

Display invert graticule showing legal broadcast ranges. +

+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, fl
+

Set graticule flags. +

+
+
‘numbers’
+

Draw numbers above lines. By default enabled. +

+
+
‘dots’
+

Draw dots instead of lines. +

+
+ +
+
scale, s
+

Set scale used for displaying graticule. +

+
+
‘digital’
+
‘millivolts’
+
‘ire’
+
+

Default is digital. +

+
+
bgopacity, b
+

Set background opacity. +

+
+
tint0, t0
+
tint1, t1
+

Set tint for output. +Only used with lowpass filter and when display is not overlay and input +pixel formats are not RGB. +

+
+
fitmode, fm
+

Set sample aspect ratio of video output frames. +Can be used to configure waveform so it is not +stretched too much in one of directions. +

+
+
‘none’
+

Set sample aspect ration to 1/1. +

+
‘size’
+

Set sample aspect ratio to match input size of video +

+
+

Default is ‘none’. +

+
+
input
+

Set input formats for filter to pick from. +Can be ‘all’, for selecting from all available formats, +or ‘first’, for selecting first available format. +Default is ‘first’. +

+
+ + +

39.283 weave, doubleweave

+ +

The weave takes a field-based video input and join +each two sequential fields into single frame, producing a new double +height clip with half the frame rate and half the frame count. +

+

The doubleweave works same as weave but without +halving frame rate and frame count. +

+

It accepts the following option: +

+
+
first_field
+

Set first field. Available values are: +

+
+
‘top, t’
+

Set the frame as top-field-first. +

+
+
‘bottom, b’
+

Set the frame as bottom-field-first. +

+
+
+
+ + +

39.283.1 Examples

+ +
    +
  • Interlace video using select and separatefields filter: +
    +
    separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
    +
    +
+ + +

39.284 xbr

+

Apply the xBR high-quality magnification filter which is designed for pixel +art. It follows a set of edge-detection rules, see +https://forums.libretro.com/t/xbr-algorithm-tutorial/123. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xBR, 3 for +3xBR and 4 for 4xBR. +Default is 3. +

+
+ + +

39.285 xcorrelate

+

Apply normalized cross-correlation between first and second input video stream. +

+

Second input video stream dimensions must be lower than first input video stream. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
secondary
+

Set which secondary video frames will be processed from second input video stream, +can be first or all. Default is all. +

+
+ +

The xcorrelate filter also supports the framesync options. +

+ +

39.286 xfade

+ +

Apply cross fade from one input video stream to another input video stream. +The cross fade is applied for specified duration. +

+

Both inputs must be constant frame-rate and have the same resolution, pixel format, +frame rate and timebase. +

+

The filter accepts the following options: +

+
+
transition
+

Set one of available transition effects: +

+
+
‘custom’
+
‘fade’
+
‘wipeleft’
+
‘wiperight’
+
‘wipeup’
+
‘wipedown’
+
‘slideleft’
+
‘slideright’
+
‘slideup’
+
‘slidedown’
+
‘circlecrop’
+
‘rectcrop’
+
‘distance’
+
‘fadeblack’
+
‘fadewhite’
+
‘radial’
+
‘smoothleft’
+
‘smoothright’
+
‘smoothup’
+
‘smoothdown’
+
‘circleopen’
+
‘circleclose’
+
‘vertopen’
+
‘vertclose’
+
‘horzopen’
+
‘horzclose’
+
‘dissolve’
+
‘pixelize’
+
‘diagtl’
+
‘diagtr’
+
‘diagbl’
+
‘diagbr’
+
‘hlslice’
+
‘hrslice’
+
‘vuslice’
+
‘vdslice’
+
‘hblur’
+
‘fadegrays’
+
‘wipetl’
+
‘wipetr’
+
‘wipebl’
+
‘wipebr’
+
‘squeezeh’
+
‘squeezev’
+
‘zoomin’
+
‘fadefast’
+
‘fadeslow’
+
‘hlwind’
+
‘hrwind’
+
‘vuwind’
+
‘vdwind’
+
‘coverleft’
+
‘coverright’
+
‘coverup’
+
‘coverdown’
+
‘revealleft’
+
‘revealright’
+
‘revealup’
+
‘revealdown’
+
+

Default transition effect is fade. +

+
+
duration
+

Set cross fade duration in seconds. +Range is 0 to 60 seconds. +Default duration is 1 second. +

+
+
offset
+

Set cross fade start relative to first input stream in seconds. +Default offset is 0. +

+
+
expr
+

Set expression for custom transition effect. +

+

The expressions can use the following variables and functions: +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
P
+

Progress of transition effect. +

+
+
PLANE
+

Currently processed plane. +

+
+
A
+

Return value of first input at current location and plane. +

+
+
B
+

Return value of second input at current location and plane. +

+
+
a0(x, y)
+
a1(x, y)
+
a2(x, y)
+
a3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of first input. +

+
+
b0(x, y)
+
b1(x, y)
+
b2(x, y)
+
b3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of second input. +

+
+
+
+ + +

39.286.1 Examples

+ +
    +
  • Cross fade from one input video to another input video, with fade transition and duration of transition +of 2 seconds starting at offset of 5 seconds: +
    +
    ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
    +
    +
+ + +

39.287 xmedian

+

Pick median pixels from several input videos. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. +Default is 3. Allowed range is from 3 to 255. +If number of inputs is even number, than result will be mean value between two median values. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

39.287.1 Commands

+ +

This filter supports all above options as commands, excluding option inputs. +

+ +

39.288 xpsnr

+ +

Obtain the average (across all input frames) and minimum (across all color plane averages) +eXtended Perceptually weighted peak Signal-to-Noise Ratio (XPSNR) between two input videos. +

+

The XPSNR is a low-complexity psychovisually motivated distortion measurement algorithm for +assessing the difference between two video streams or images. This is especially useful for +objectively quantifying the distortions caused by video and image codecs, as an alternative +to a formal subjective test. The logarithmic XPSNR output values are in a similar range as +those of traditional psnr assessments but better reflect human impressions of visual +coding quality. More details on the XPSNR measure, which essentially represents a blockwise +weighted variant of the PSNR measure, can be found in the following freely available papers: +

+
    +
  • C. R. Helmrich, M. Siekmann, S. Becker, S. Bosse, D. Marpe, and T. Wiegand, "XPSNR: A +Low-Complexity Extension of the Perceptually Weighted Peak Signal-to-Noise Ratio for +High-Resolution Video Quality Assessment," in Proc. IEEE Int. Conf. Acoustics, Speech, +Sig. Process. (ICASSP), virt./online, May 2020. www.ecodis.de/xpsnr.htm + +
  • C. R. Helmrich, S. Bosse, H. Schwarz, D. Marpe, and T. Wiegand, "A Study of the +Extended Perceptually Weighted Peak Signal-to-Noise Ratio (XPSNR) for Video Compression +with Different Resolutions and Bit Depths," ITU Journal: ICT Discoveries, vol. 3, no. +1, pp. 65 - 72, May 2020. http://handle.itu.int/11.1002/pub/8153d78b-en +
+ +

When publishing the results of XPSNR assessments obtained using, e.g., this FFmpeg filter, a +reference to the above papers as a means of documentation is strongly encouraged. The filter +requires two input videos. The first input is considered a (usually not distorted) reference +source and is passed unchanged to the output, whereas the second input is a (distorted) test +signal. Except for the bit depth, these two video inputs must have the same pixel format. In +addition, for best performance, both compared input videos should be in YCbCr color format. +

+

The obtained overall XPSNR values mentioned above are printed through the logging system. In +case of input with multiple color planes, we suggest reporting of the minimum XPSNR average. +

+

The following parameter, which behaves like the one for the psnr filter, is accepted: +

+
+
stats_file, f
+

If specified, the filter will use the named file to save the XPSNR value of each individual +frame and color plane. When the file name equals "-", that data is sent to standard output. +

+
+ +

This filter also supports the framesync options. +

+ +

39.288.1 Examples

+
    +
  • XPSNR analysis of two 1080p HD videos, ref_source.yuv and test_video.yuv, both at 24 frames +per second, with color format 4:2:0, bit depth 8, and output of a logfile named "xpsnr.log": +
    +
    ffmpeg -s 1920x1080 -framerate 24 -pix_fmt yuv420p -i ref_source.yuv -s 1920x1080 -framerate
    +24 -pix_fmt yuv420p -i test_video.yuv -lavfi xpsnr="stats_file=xpsnr.log" -f null -
    +
    + +
  • XPSNR analysis of two 2160p UHD videos, ref_source.yuv with bit depth 8 and test_video.yuv +with bit depth 10, both at 60 frames per second with color format 4:2:0, no logfile output: +
    +
    ffmpeg -s 3840x2160 -framerate 60 -pix_fmt yuv420p -i ref_source.yuv -s 3840x2160 -framerate
    +60 -pix_fmt yuv420p10le -i test_video.yuv -lavfi xpsnr="stats_file=-" -f null -
    +
    +
+ + +

39.289 xstack

+

Stack video inputs into custom layout. +

+

All streams must be of same pixel format. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
layout
+

Specify layout of inputs. +This option requires the desired layout configuration to be explicitly set by the user. +This sets position of each video input in output. Each input +is separated by ’|’. +The first number represents the column, and the second number represents the row. +Numbers start at 0 and are separated by ’_’. Optionally one can use wX and hX, +where X is video input from which to take width or height. +Multiple values can be used when separated by ’+’. In such +case values are summed together. +

+

Note that if inputs are of different sizes gaps may appear, as not all of +the output video frame will be filled. Similarly, videos can overlap each +other if their position doesn’t leave enough space for the full frame of +adjoining videos. +

+

For 2 inputs, a default layout of 0_0|w0_0 (equivalent to +grid=2x1) is set. In all other cases, a layout or a grid must be set by +the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
grid
+

Specify a fixed size grid of inputs. +This option is used to create a fixed size grid of the input streams. Set the +grid size in the form COLUMNSxROWS. There must be ROWS * COLUMNS +input streams and they will be arranged as a grid with ROWS rows and +COLUMNS columns. When using this option, each input stream within a row +must have the same height and all the rows must have the same width. +

+

If grid is set, then inputs option is ignored and is implicitly +set to ROWS * COLUMNS. +

+

For 2 inputs, a default grid of 2x1 (equivalent to +layout=0_0|w0_0) is set. In all other cases, a layout or a grid must be +set by the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
fill
+

If set to valid color, all unused pixels will be filled with that color. +By default fill is set to none, so it is disabled. +

+
+ + +

39.289.1 Examples

+ +
    +
  • Display 4 inputs into 2x2 grid. + +

    Layout: +

    +
    input1(0, 0)  | input3(w0, 0)
    +input2(0, h0) | input4(w0, h0)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 4 inputs into 1x4 grid. + +

    Layout: +

    +
    input1(0, 0)
    +input2(0, h0)
    +input3(0, h0+h1)
    +input4(0, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
    +
    + +

    Note that if inputs are of different widths, unused space will appear. +

    +
  • Display 9 inputs into 3x3 grid. + +

    Layout: +

    +
    input1(0, 0)       | input4(w0, 0)      | input7(w0+w3, 0)
    +input2(0, h0)      | input5(w0, h0)     | input8(w0+w3, h0)
    +input3(0, h0+h1)   | input6(w0, h0+h1)  | input9(w0+w3, h0+h1)
    +
    + +
    +
    xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 16 inputs into 4x4 grid. + +

    Layout: +

    +
    input1(0, 0)       | input5(w0, 0)       | input9 (w0+w4, 0)       | input13(w0+w4+w8, 0)
    +input2(0, h0)      | input6(w0, h0)      | input10(w0+w4, h0)      | input14(w0+w4+w8, h0)
    +input3(0, h0+h1)   | input7(w0, h0+h1)   | input11(w0+w4, h0+h1)   | input15(w0+w4+w8, h0+h1)
    +input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0|
    +w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
+ + +

39.290 yadif

+ +

Deinterlace the input video ("yadif" means "yet another deinterlacing +filter"). +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

39.291 yaepblur

+ +

Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter"). +The algorithm is described in +"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980." +

+

It accepts the following parameters: +

+
+
radius, r
+

Set the window radius. Default value is 3. +

+
+
planes, p
+

Set which planes to filter. Default is only the first plane. +

+
+
sigma, s
+

Set blur strength. Default value is 128. +

+
+ + +

39.291.1 Commands

+

This filter supports same commands as options. +

+ +

39.292 zoompan

+ +

Apply Zoom & Pan effect. +

+

This filter accepts the following options: +

+
+
zoom, z
+

Set the zoom expression. Range is 1-10. Default is 1. +

+
+
x
+
y
+

Set the x and y expression. Default is 0. +

+
+
d
+

Set the duration expression in number of frames. +This sets for how many number of frames effect will last for +single input image. Default is 90. +

+
+
s
+

Set the output image size, default is ’hd720’. +

+
+
fps
+

Set the output frame rate, default is ’25’. +

+
+ +

Each expression can contain the following constants: +

+
+
in_w, iw
+

Input width. +

+
+
in_h, ih
+

Input height. +

+
+
out_w, ow
+

Output width. +

+
+
out_h, oh
+

Output height. +

+
+
in
+

Input frame count. +

+
+
on
+

Output frame count. +

+
+
in_time, it
+

The input timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
out_time, time, ot
+

The output timestamp expressed in seconds. +

+
+
x
+
y
+

Last calculated ’x’ and ’y’ position from ’x’ and ’y’ expression +for current input frame. +

+
+
px
+
py
+

’x’ and ’y’ of last output frame of previous input frame or 0 when there was +not yet such frame (first input frame). +

+
+
zoom
+

Last calculated zoom from ’z’ expression for current input frame. +

+
+
pzoom
+

Last calculated zoom of last output frame of previous input frame. +

+
+
duration
+

Number of output frames for current input frame. Calculated from ’d’ expression +for each input frame. +

+
+
pduration
+

number of output frames created for previous input frame +

+
+
a
+

Rational number: input width / input height +

+
+
sar
+

sample aspect ratio +

+
+
dar
+

display aspect ratio +

+
+
+ + +

39.292.1 Examples

+ +
    +
  • Zoom in up to 1.5x and pan at same time to some spot near center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360
    +
    + +
  • Zoom in up to 1.5x and pan always at center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Same as above but without pausing: +
    +
    zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Zoom in 2x into center of picture only for the first second of the input video: +
    +
    zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
+ + +

39.293 zscale

+

Scale (resize) the input video, using the z.lib library: +https://github.com/sekrit-twc/zimg. To enable compilation of this +filter, you need to configure FFmpeg with --enable-libzimg. +

+

The zscale filter forces the output display aspect ratio to be the same +as the input, by changing the output sample aspect ratio. +

+

If the input image format is different from the format requested by +the next filter, the zscale filter will convert the input to the +requested format. +

+ +

39.293.1 Options

+

The filter accepts the following options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the zscale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
dither, d
+

Set the dither type. +

+

Possible values are: +

+
none
+
ordered
+
random
+
error_diffusion
+
+ +

Default is none. +

+
+
filter, f
+

Set the resize filter type. +

+

Possible values are: +

+
point
+
bilinear
+
bicubic
+
spline16
+
spline36
+
spline64
+
lanczos
+
+ +

Default is bilinear. +

+
+
range, r
+

Set the color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
smpte2084
+
iec61966-2-1
+
arib-std-b67
+
+ +

Default is same as input. +

+
+
matrix, m
+

Set the colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +

Default is same as input. +

+
+
rangein, rin
+

Set the input color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primariesin, pin
+

Set the input color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transferin, tin
+

Set the input transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
+ +

Default is same as input. +

+
+
matrixin, min
+

Set the input colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +
+
chromal, c
+

Set the output chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
chromalin, cin
+

Set the input chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
npl
+

Set the nominal peak luminance. +

+
+
param_a
+

Parameter A for scaling filters. Parameter "b" for bicubic, and the number of +filter taps for lanczos. +

+
+
param_b
+

Parameter B for scaling filters. Parameter "c" for bicubic. +

+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

39.293.2 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + + +

40 CUDA Video Filters

+ +

To enable CUDA and/or NPP filters please refer to configuration guidelines for CUDA and for CUDA NPP filters. +

+

Running CUDA filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device cuda[=name][:device[,key=value...]]
+

Initialise a new hardware device of type cuda called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of initializing second CUDA device on the system and running scale_cuda and bilateral_cuda filters. +
    +
    ./ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -init_hw_device cuda:1 -filter_complex \
    +"[0:v]scale_cuda=format=yuv444p[scaled_video];[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    +
+ +

Since CUDA filters operate exclusively on GPU memory, frame data must sometimes be uploaded (hwupload) to hardware surfaces associated with the appropriate CUDA device before processing, and downloaded (hwdownload) back to normal memory afterward, if required. Whether hwupload or hwdownload is necessary depends on the specific workflow: +

+
    +
  • If the input frames are already in GPU memory (e.g., when using -hwaccel cuda or -hwaccel_output_format cuda), explicit use of hwupload is not needed, as the data is already in the appropriate memory space. +
  • If the input frames are in CPU memory (e.g., software-decoded frames or frames processed by CPU-based filters), it is necessary to use hwupload to transfer the data to GPU memory for CUDA processing. +
  • If the output of the CUDA filters needs to be further processed by software-based filters or saved in a format not supported by GPU-based encoders, hwdownload is required to transfer the data back to CPU memory. +
+

Note that hwupload uploads data to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before hwupload to ensure the input is in the correct format. Similarly, hwdownload may not support all output formats, so an additional format filter may need to be inserted immediately after hwdownload in the filter graph to ensure compatibility. +

+ +

40.1 CUDA

+

Below is a description of the currently available Nvidia CUDA video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
+ +

Note: If FFmpeg detects the Nvidia CUDA Toolkit during configuration, it will enable CUDA filters automatically without requiring any additional flags. If you want to explicitly enable them, use the following options: +

+
    +
  • Configure FFmpeg with --enable-cuda-nvcc --enable-nonfree. +
  • Configure FFmpeg with --enable-cuda-llvm. Additional requirement: llvm lib must be installed. +
+ + +

40.1.1 bilateral_cuda

+

CUDA accelerated bilateral filter, an edge preserving filter. +This filter is mathematically accurate thanks to the use of GPU acceleration. +For best output quality, use one to one chroma subsampling, i.e. yuv444p format. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight, also called sigma space. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate color range weight, also called sigma color. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
window_size
+

Set window size of the bilateral function to determine the number of neighbours to loop on. +If the number entered is even, one will be added automatically. +Allowed range is 1 to 255. Default is 1. +

+
+ +

40.1.1.1 Examples

+ +
    +
  • Apply the bilateral filter on a video. + +
    +
    ./ffmpeg -v verbose \
    +-hwaccel cuda -hwaccel_output_format cuda -i input.mp4  \
    +-init_hw_device cuda \
    +-filter_complex \
    +" \
    +[0:v]scale_cuda=format=yuv444p[scaled_video];
    +[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    + +
+ + +

40.1.2 bwdif_cuda

+ +

Deinterlace the input video using the bwdif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

40.1.3 chromakey_cuda

+

CUDA accelerated YUV colorspace color/chroma keying. +

+

This filter works like normal chromakey filter but operates on CUDA frames. +for more details and parameters see chromakey. +

+ +

40.1.3.1 Examples

+ +
    +
  • Make all the green pixels in the input video transparent and use it as an overlay for another video: + +
    +
    ./ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -i input_green.mp4  \
    +    -hwaccel cuda -hwaccel_output_format cuda -i base_video.mp4 \
    +    -init_hw_device cuda \
    +    -filter_complex \
    +    " \
    +        [0:v]chromakey_cuda=0x25302D:0.1:0.12:1[overlay_video]; \
    +        [1:v]scale_cuda=format=yuv420p[base]; \
    +        [base][overlay_video]overlay_cuda" \
    +    -an -sn -c:v h264_nvenc -cq 20 output.mp4
    +
    + +
  • Process two software sources, explicitly uploading the frames: + +
    +
    ./ffmpeg -init_hw_device cuda=cuda -filter_hw_device cuda \
    +    -f lavfi -i color=size=800x600:color=white,format=yuv420p \
    +    -f lavfi -i yuvtestsrc=size=200x200,format=yuv420p \
    +    -filter_complex \
    +    " \
    +        [0]hwupload[under]; \
    +        [1]hwupload,chromakey_cuda=green:0.1:0.12[over]; \
    +        [under][over]overlay_cuda" \
    +    -c:v hevc_nvenc -cq 18 -preset slow output.mp4
    +
    + +
+ + +

40.1.4 colorspace_cuda

+ +

CUDA accelerated implementation of the colorspace filter. +

+

It is by no means feature complete compared to the software colorspace filter, +and at the current time only supports color range conversion between jpeg/full +and mpeg/limited range. +

+

The filter accepts the following options: +

+
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
+ + +

40.1.5 overlay_cuda

+ +

Overlay one video on top of another. +

+

This is the CUDA variant of the overlay filter. +It only accepts CUDA frames. The underlying input pixel formats have to match. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

They can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
n
+

The ordinal index of the main input frame, starting from 0. +

+
+
pos
+

The byte offset position in the file of the main input frame, NAN if unknown. +Deprecated, do not use. +

+
+
t
+

The timestamp of the main input frame, expressed in seconds, NAN if unknown. +

+
+
+ +

Default value is "0" for both expressions. +

+
+
eval
+

Set when the expressions for x and y are evaluated. +

+

It accepts the following values: +

+
init
+

Evaluate expressions once during filter initialization or +when a command is processed. +

+
+
frame
+

Evaluate expressions for each incoming frame +

+
+ +

Default value is frame. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+ + +

40.1.6 pad_cuda

+

Add paddings to an input video stream using CUDA. +

+

This filter is the CUDA-accelerated version of the pad filter. It accepts the same options and expressions and provides the same core functionality. +For a detailed description of available options, please see the documentation for the pad filter. +

+ +

40.1.6.1 Examples

+ +
    +
  • Add a 200-pixel black border to all sides of a video frame: +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=iw+400:h=ih+400:x=200:y=200" -c:v h264_nvenc out.mp4
    +
    + +
  • Pad the input video to a 16:9 aspect ratio, filling with the color "blue": +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=ih*16/9/sar:h=ih:x=(ow-iw)/2:y=(oh-ih)/2:color=blue" -c:v h264_nvenc out.mp4
    +
    +
+ + +

40.1.7 scale_cuda

+ +

Scale (resize) and convert (pixel format) the input video, using accelerated CUDA kernels. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
interp_algo
+

Sets the algorithm used for scaling: +

+
+
nearest
+

Nearest neighbour +

+

Used by default if input parameters match the desired output. +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+

This is the default. +

+
+
lanczos
+

Lanczos +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+

The filter does not support converting between YUV and RGB pixel formats. +

+
+
passthrough
+

If set to 0, every frame is processed, even if no conversion is necessary. +This mode can be useful to use the filter as a buffer for a downstream +frame-consumer that exhausts the limited decoder frame pool. +

+

If set to 1, frames are passed through as-is if they match the desired output +parameters. This is the default behaviour. +

+
+
param
+

Algorithm-Specific parameter. +

+

Affects the curves of the bicubic algorithm. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
+ + +

40.1.7.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    scale_cuda=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K using nearest neighbour algorithm. +
    +
    scale_cuda=4096:2160:interp_algo=nearest
    +
    + +
  • Don’t do any conversion or scaling, but copy all input frames into newly allocated ones. +This can be useful to deal with a filter and encode chain that otherwise exhausts the +decoders frame pool. +
    +
    scale_cuda=passthrough=0
    +
    +
+ + +

40.1.8 thumbnail_cuda

+ +

Select the most representative frame in a given sequence of consecutive frames using CUDA. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

40.1.8.1 Example

+ +
    +
  • Thumbnails are extracted from every n=150-frame batch, selecting one per batch. Chosen frames are then scaled with scale_cuda. +
    +
    ./ffmpeg  -hwaccel cuda -hwaccel_output_format cuda  -i ./input.mp4 -vf "thumbnail_cuda=150,scale_cuda=1920:1080,hwdownload,format=nv12" ./output/out%03d.png
    +
    + +
+ + +

40.1.9 yadif_cuda

+ +

Deinterlace the input video using the yadif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

40.2 CUDA NPP

+

Below is a description of the currently available NVIDIA Performance Primitives (libnpp) video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
  • Install libnpp +
+ +

To enable CUDA NPP filters: +

+
    +
  • Configure FFmpeg with --enable-nonfree --enable-libnpp. +
+ + + +

40.2.1 scale_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel +format conversion on CUDA video frames. Setting the output width and height +works in the same way as for the scale filter. +

+

The following additional options are accepted: +

+
format
+

The pixel format of the output CUDA frames. If set to the string "same" (the +default), the input format will be kept. Note that automatic format negotiation +and conversion is not yet supported for hardware frames +

+
+
interp_algo
+

The interpolation algorithm used for resizing. One of the following: +

+
nn
+

Nearest neighbour. +

+
+
linear
+
cubic
+
cubic2p_bspline
+

2-parameter cubic (B=1, C=0) +

+
+
cubic2p_catmullrom
+

2-parameter cubic (B=0, C=1/2) +

+
+
cubic2p_b05c03
+

2-parameter cubic (B=1/2, C=3/10) +

+
+
super
+

Supersampling +

+
+
lanczos
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+ + +

40.2.2 scale2ref_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to scale (resize) the input +video, based on a reference video. +

+

See the scale_npp filter for available options, scale2ref_npp supports the same +but uses the reference video instead of the main input as basis. scale2ref_npp +also supports the following additional constants for the w and +h options: +

+
+
main_w
+
main_h
+

The main input video’s width and height +

+
+
main_a
+

The same as main_w / main_h +

+
+
main_sar
+

The main input video’s sample aspect ratio +

+
+
main_dar, mdar
+

The main input video’s display aspect ratio. Calculated from +(main_w / main_h) * main_sar. +

+
+
main_n
+

The (sequential) number of the main input frame, starting from 0. +Only available with eval=frame. +

+
+
main_t
+

The presentation timestamp of the main input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
main_pos
+

The position (byte offset) of the frame in the main input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +

+
+ + +

40.2.2.1 Examples

+ +
    +
  • Scale a subtitle stream (b) to match the main video (a) in size before overlaying +
    +
    'scale2ref_npp[b][a];[a][b]overlay_cuda'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio. +
    +
    [logo-in][video-in]scale2ref_npp=w=oh*mdar:h=ih/10[logo-out][video-out]
    +
    +
+ + +

40.2.3 sharpen_npp

+

Use the NVIDIA Performance Primitives (libnpp) to perform image sharpening with +border control. +

+

The following additional options are accepted: +

+
border_type
+

Type of sampling to be used ad frame borders. One of the following: +

+
replicate
+

Replicate pixel values. +

+
+
+
+
+ + +

40.2.4 transpose_npp

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

41 OpenCL Video Filters

+ +

Below is a description of the currently available OpenCL video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-opencl. +

+

Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device opencl[=name][:device[,key=value...]]
+

Initialise a new hardware device of type opencl called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it. +
    +
    -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
    +
    +
+ +

Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded(hwdownload) back to normal memory. Note that hwupload will upload to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it may be necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

41.1 avgblur_opencl

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 1024] and default value is 1. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 1024] and default value is 0. If zero, sizeX value will be used. +

+
+ + +

41.1.1 Example

+ +
    +
  • Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +
    +
    -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
    +
    +
+ + +

41.2 boxblur_opencl

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

41.2.1 Examples

+ +

Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses luma_radius, chroma_radius, alpha_radius for each plane respectively. The filter will apply luma_power, chroma_power, alpha_power times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +

+
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radius +set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image. +
    +
    -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
    +-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
    +
    + +
  • Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7. + +

    For the luma plane, a 2x2 box radius will be run once. +

    +

    For the chroma plane, a 4x4 box radius will be run 5 times. +

    +

    For the alpha plane, a 3x3 box radius will be run 7 times. +

    +
    -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
    +
    +
+ + +

41.3 colorkey_opencl

+

RGB colorspace color keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

41.3.1 Examples

+ +
    +
  • Make every semi-green pixel in the input transparent with some slight blending: +
    +
    -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
    +
    +
+ + +

41.4 convolution_opencl

+ +

Apply convolution of 3x3, 5x5, 7x7 matrix. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed numbers. +Default value for each plane is 0 0 0 0 1 0 0 0 0. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be sum of all matrix elements. +The option value must be a float number greater or equal to 0.0. Default value is 1.0. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. +The option value must be a float number greater or equal to 0.0. Default value is 0.0. +

+
+
+ + +

41.4.1 Examples

+ +
    +
  • Apply sharpen: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0, hwdownload" OUTPUT
    +
    + +
  • Apply blur: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9, hwdownload" OUTPUT
    +
    + +
  • Apply edge enhance: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply edge detect: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT
    +
    + +
  • Apply emboss: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2, hwdownload" OUTPUT
    +
    +
+ + +

41.5 erosion_opencl

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

41.5.1 Example

+ +
    +
  • Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

41.6 deshake_opencl

+

Feature-point based video stabilization filter. +

+

The filter accepts the following options: +

+
+
tripod
+

Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to 0. +

+
+
debug
+

Whether or not additional debug info should be displayed, both in the processed output and in the console. +

+

Note that in order to see console debug output you will also need to pass -v verbose to ffmpeg. +

+

Viewing point matches in the output video is only supported for RGB input. +

+

Defaults to 0. +

+
+
adaptive_crop
+

Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels. +

+

Defaults to 1. +

+
+
refine_features
+

Whether or not feature points should be refined at a sub-pixel level. +

+

This can be turned off for a slight performance gain at the cost of precision. +

+

Defaults to 1. +

+
+
smooth_strength
+

The strength of the smoothing applied to the camera path from 0.0 to 1.0. +

+

1.0 is the maximum smoothing strength while values less than that result in less smoothing. +

+

0.0 causes the filter to adaptively choose a smoothing strength on a per-frame basis. +

+

Defaults to 0.0. +

+
+
smooth_window_multiplier
+

Controls the size of the smoothing window (the number of frames buffered to determine motion information from). +

+

The size of the smoothing window is determined by multiplying the framerate of the video by this number. +

+

Acceptable values range from 0.1 to 10.0. +

+

Larger values increase the amount of motion data available for determining how to smooth the camera path, +potentially improving smoothness, but also increase latency and memory usage. +

+

Defaults to 2.0. +

+
+
+ + +

41.6.1 Examples

+ +
    +
  • Stabilize a video with a fixed, medium smoothing strength: +
    +
    -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
    +
    + +
  • Stabilize a video with debugging (both in console and in rendered video): +
    +
    -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
    +
    +
+ + +

41.7 dilation_opencl

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

41.7.1 Example

+ +
    +
  • Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

41.8 nlmeans_opencl

+ +

Non-local Means denoise filter through OpenCL, this filter accepts same options as nlmeans. +

+ +

41.9 overlay_opencl

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires same memory layout for all the inputs. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

41.9.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    +
  • The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    + +
+ + +

41.10 pad_opencl

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

41.11 prewitt_opencl

+ +

Apply the Prewitt operator (https://en.wikipedia.org/wiki/Prewitt_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

41.11.1 Example

+ +
    +
  • Apply the Prewitt operator with scale set to 2 and delta set to 10. +
    +
    -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

41.12 program_opencl

+ +

Filter video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
inputs
+

Number of inputs to the filter. Defaults to 1. +

+
+
size, s
+

Size of output frames. Defaults to the same as the first input. +

+
+
+ +

The program_opencl filter also supports the framesync options. +

+

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

  • Frame index, unsigned int. + +

    This is a counter starting from zero and increasing by one for each frame. +

  • Source images, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

+ +

Example programs: +

+
    +
  • Copy the input to the output (output must be the same size as the input). +
    __kernel void copy(__write_only image2d_t destination,
    +                   unsigned int index,
    +                   __read_only  image2d_t source)
    +{
    +    const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
    +
    +    int2 location = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = read_imagef(source, sampler, location);
    +
    +    write_imagef(destination, location, value);
    +}
    +
    +
  • Apply a simple transformation, rotating the input by an amount increasing +with the index counter. Pixel values are linearly interpolated by the +sampler, and the output need not have the same dimensions as the input. +
    __kernel void rotate_image(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float angle = (float)index / 100.0f;
    +
    +    float2 dst_dim = convert_float2(get_image_dim(dst));
    +    float2 src_dim = convert_float2(get_image_dim(src));
    +
    +    float2 dst_cen = dst_dim / 2.0f;
    +    float2 src_cen = src_dim / 2.0f;
    +
    +    int2   dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float2 dst_pos = convert_float2(dst_loc) - dst_cen;
    +    float2 src_pos = {
    +        cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
    +        sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
    +    };
    +    src_pos = src_pos * src_dim / dst_dim;
    +
    +    float2 src_loc = src_pos + src_cen;
    +
    +    if (src_loc.x < 0.0f      || src_loc.y < 0.0f ||
    +        src_loc.x > src_dim.x || src_loc.y > src_dim.y)
    +        write_imagef(dst, dst_loc, 0.5f);
    +    else
    +        write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
    +}
    +
    +
  • Blend two inputs together, with the amount of each input used varying +with the index counter. +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
    +
    +    int2  dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +    int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
    +    int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
    +
    +    float4 val1 = read_imagef(src1, sampler, src1_loc);
    +    float4 val2 = read_imagef(src2, sampler, src2_loc);
    +
    +    write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
    +}
    +
    +
+ + +

41.13 remap_opencl

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 32bit float pixel format, single channel. +

+
+
interp
+

Specify interpolation used for remapping of pixels. +Allowed values are near and linear. +Default value is linear. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

41.14 roberts_opencl

+

Apply the Roberts cross operator (https://en.wikipedia.org/wiki/Roberts_cross) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

41.14.1 Example

+ +
    +
  • Apply the Roberts cross operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

41.15 sobel_opencl

+ +

Apply the Sobel operator (https://en.wikipedia.org/wiki/Sobel_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

41.15.1 Example

+ +
    +
  • Apply sobel operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

41.16 tonemap_opencl

+ +

Perform HDR(PQ/HLG) to SDR conversion with tone-mapping. +

+

It accepts the following parameters: +

+
+
tonemap
+

Specify the tone-mapping operator to be used. Same as tonemap option in tonemap. +

+
+
param
+

Tune the tone mapping algorithm. same as param option in tonemap. +

+
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default value is 0.5, and the algorithm here is a little different from +the cpu version tonemap currently. A setting of 0.0 disables this option. +

+
+
threshold
+

The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold +is used to detect whether the scene has changed or not. If the distance between +the current frame average brightness and the current running average exceeds +a threshold value, we would re-calculate scene average and peak brightness. +The default value is 0.2. +

+
+
format
+

Specify the output pixel format. +

+

Currently supported formats are: +

+
p010
+
nv12
+
+ +
+
range, r
+

Set the output color range. +

+

Possible values are: +

+
tv/mpeg
+
pc/jpeg
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the output color primaries. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is bt709. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Possible value are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
+ + +

41.16.1 Example

+ +
    +
  • Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator. +
    +
    -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
    +
    +
+ + +

41.17 unsharp_opencl

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. +Range is [-10, 10] and default value is 1.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. +Range is [-10, 10] and default value is 0.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

41.17.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
    +
    +
+ + +

41.18 xfade_opencl

+ +

Cross fade two videos with custom transition effect by using OpenCL. +

+

It accepts the following options: +

+
+
transition
+

Set one of possible transition effects. +

+
+
custom
+

Select custom transition effect, the actual transition description +will be picked from source and kernel options. +

+
+
fade
+
wipeleft
+
wiperight
+
wipeup
+
wipedown
+
slideleft
+
slideright
+
slideup
+
slidedown
+
+

Default transition is fade. +

+
+ +
+
source
+

OpenCL program source file for custom transition. +

+
+
kernel
+

Set name of kernel to use for custom transition from program source file. +

+
+
duration
+

Set duration of video transition. +

+
+
offset
+

Set time of start of transition relative to first video. +

+
+ +

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

    +
  • First Source image, __read_only image2d_t. +Second Source image, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

    +
  • Transition progress, float. This value is always between 0 and 1 inclusive. +
+ +

Example programs: +

+
    +
  • Apply dots curtain transition effect: +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2,
    +                           float progress)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +    int2  p = (int2)(get_global_id(0), get_global_id(1));
    +    float2 rp = (float2)(get_global_id(0), get_global_id(1));
    +    float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
    +    rp = rp / dim;
    +
    +    float2 dots = (float2)(20.0, 20.0);
    +    float2 center = (float2)(0,0);
    +    float2 unused;
    +
    +    float4 val1 = read_imagef(src1, sampler, p);
    +    float4 val2 = read_imagef(src2, sampler, p);
    +    bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
    +
    +    write_imagef(dst, p, next ? val1 : val2);
    +}
    +
    +
+ + + +

42 VAAPI Video Filters

+ +

VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vaapi. +

+

To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/VAAPI +

+ +

42.1 overlay_vaapi

+ +

Overlay one video on the top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +

+

The filter accepts the following options: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

Default value is "0" for both expressions. +

+
+
w
+
h
+

Set expressions for the width and height the overlaid video +on the main video. +

+

Default values are ’overlay_iw’ for ’w’ and ’overlay_ih*w/overlay_iw’ for ’h’. +

+

The expressions can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_iw
+
overlay_ih
+

The overlay input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay output width and height. +

+
+
overlay_x, x
+
overlay_y, y
+

Position of the overlay layer inside of main +

+
+
+ +
+
alpha
+

Set transparency of overlaid video. Allowed range is 0.0 to 1.0. +Higher value means lower transparency. +Default value is 1.0. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+

42.1.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs for this filter are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_vaapi" OUTPUT
    +
    +
  • Overlay an image LOGO at the offset (200, 100) from the top-left corner of the INPUT video. +The inputs have same memory layout for color channels, the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_vaapi=x=200:y=100:w=400:h=300:alpha=1.0, hwdownload, format=nv12" OUTPUT
    +
    + +
+ + +

42.2 tonemap_vaapi

+ +

Perform HDR-to-SDR or HDR-to-HDR tone-mapping. +It currently only accepts HDR10 as input. +

+

It accepts the following parameters: +

+
+
format
+

Specify the output pixel format. +

+

Default is nv12 for HDR-to-SDR tone-mapping and p010 for HDR-to-HDR +tone-mapping. +

+
+
primaries, p
+

Set the output color primaries. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
display
+

Set the output mastering display colour volume. It is given by a ’|’-separated +list of two values, two values are space separated. It set display primaries +x & y in G, B, R order, then white point x & y, the nominal minimum & maximum +display luminances. +

+

HDR-to-HDR tone-mapping will be performed when this option is set. +

+
+
light
+

Set the output content light level information. It accepts 2 space-separated +values, the first input is the maximum light level and the second input is +the maximum average light level. +

+

It is ignored for HDR-to-SDR tone-mapping, and optional for HDR-to-HDR +tone-mapping. +

+
+
+ + +

42.2.1 Example

+ +
    +
  • Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format +
    +
    tonemap_vaapi=format=p010:t=bt2020-10
    +
    +
  • Convert HDR video to HDR video +
    +
    tonemap_vaapi=display=7500\ 3000|34000\ 16000|13250\ 34500|15635\ 16450|500\ 10000000
    +
    +
+ + +

42.3 hstack_vaapi

+

Stack input videos horizontally. +

+

This is the VA-API variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

42.4 vstack_vaapi

+

Stack input videos vertically. +

+

This is the VA-API variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

42.5 xstack_vaapi

+

Stack video inputs into custom layout. +

+

This is the VA-API variant of the xstack filter, each input stream may +have different size, this filter will scale down/up each input stream to the +given output size, or the size of the first input stream. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_vaapi=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + +

42.6 pad_vaapi

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

42.7 drawbox_vaapi

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

Specify the color of the box to write. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

With value 1, the pixels of the painted box will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input video. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
t
+

The thickness of the drawn box. +

+
+
+ + +

42.7.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + + +

43 VideoToolbox Video Filters

+ +

Below is a description of the currently available VideoToolbox video filters. +

+

VideoToolbox filter depends on VideoToolbox framework, and is auto detected +when building ffmpeg for an Apple platform such as macOS. Add +--enable-videotoolbox to configure if autodetect is disabled. +

+ +

43.1 scale_vt

+ +

Scale and convert the color parameters using VTPixelTransferSession. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+
+
color_matrix
+

Set the output colorspace matrix. +

+
+
color_primaries
+

Set the output color primaries. +

+
+
color_transfer
+

Set the output transfer characteristics. +

+
+
+ + +

43.1.1 Examples

+ +
    +
  • Perform HDR to SDR conversion, and scale to half size of input +
    +
    ffmpeg -hwaccel videotoolbox \
    +        -hwaccel_output_format videotoolbox_vld \
    +        -i hdr.mov \
    +        -c:v hevc_videotoolbox \
    +        -profile:v main \
    +        -b:v 3M \
    +        -vf scale_vt=w=iw/2:h=ih/2:color_matrix=bt709:color_primaries=bt709:color_transfer=bt709 \
    +        -c:a copy \
    +        -tag:v hvc1 \
    +        sdr.mp4
    +
    + +
+ + +

43.2 transpose_vt

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+
‘hflip’
+

Flip the input video horizontally. +

+
+
‘vflip’
+

Flip the input video vertically. +

+
+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

44 Vulkan Video Filters

+ +

Below is a description of the currently available Vulkan video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vulkan and either --enable-libglslang or --enable-libshaderc. +

+

Running Vulkan filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device vulkan[=name][:device[,key=value...]]
+

Initialise a new hardware device of type vulkan called name, using the +given device parameters and options in key=value. The following options +are supported: +

+
+
debug
+

Switches validation layers on if set to 1. +

+
+
linear_images
+

Allocates linear images. Does not apply to decoding. +

+
+
disable_multiplane
+

Disables multiplane images. Does not apply to decoding. +

+
+
avoid_host_import
+

Avoids the use of dynamic host memory imports, in favor of a regular memcpy() +into a previously mapped buffer. +

+
+ +
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device and running nlmeans_vulkan filter with default parameters on it. +
    +
    -init_hw_device vulkan=vk:0 -filter_hw_device vk -i INPUT -vf "hwupload,nlmeans_vulkan,hwdownload" OUTPUT
    +
    +
+ +

As Vulkan filters are not able to access frame data in normal memory, all frame data needs to be uploaded (hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded (hwdownload) back to normal memory. Note that hwupload will upload to a frame with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it is usually necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

44.1 avgblur_vulkan

+ +

Apply an average blur filter, implemented on the GPU using Vulkan. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 32] and default value is 3. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 32] and default value is 3. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+ + +

44.2 blend_vulkan

+ +

Blend two Vulkan frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘normal’
+
‘multiply’
+
+ +
+
+ + +

44.3 bwdif_vulkan

+ +

Deinterlacer using bwdif, the "Bob Weaver Deinterlacing Filter" algorithm, implemented +on the GPU using Vulkan. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

44.4 chromaber_vulkan

+ +

Apply an effect that emulates chromatic aberration. Works best with RGB inputs, +but provides a similar effect with YCbCr inputs too. +

+
+
dist_x
+

Horizontal displacement multiplier. Each chroma pixel’s position will be multiplied +by this amount, starting from the center of the image. Default is 0. +

+
+
dist_y
+

Similarly, this sets the vertical displacement multiplier. Default is 0. +

+
+
+ + +

44.5 color_vulkan

+ +

Video source that creates a Vulkan frame of a solid color. +Useful for benchmarking, or overlaying. +

+

It accepts the following parameters: +

+
+
color
+

The color to use. Either a name, or a hexadecimal value. +The default value is black. +

+
+
size
+

The size of the output frame. Default value is 1920x1080. +

+
+
rate
+

The framerate to output at. Default value is 60 frames per second. +

+
+
duration
+

The video duration. Default value is -0.000001. +

+
+
sar
+

The video signal aspect ratio. Default value is 1/1. +

+
+
format
+

The pixel format of the output Vulkan frames. Default value is yuv444p. +

+
+
out_range
+

Set the 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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
+ + +

44.6 vflip_vulkan

+ +

Flips an image vertically. +

+ +

44.7 hflip_vulkan

+ +

Flips an image horizontally. +

+ +

44.8 flip_vulkan

+ +

Flips an image along both the vertical and horizontal axis. +

+ +

44.9 gblur_vulkan

+ +

Apply Gaussian blur filter on Vulkan frames. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
size
+

Set the kernel size along the horizontal axis. Default is 19. +

+
+
sizeV
+

Set the kernel size along the vertical axis. Default is 0, +which sets to use the same value as size. +

+
+
+ + +

44.10 nlmeans_vulkan

+ +

Denoise frames using Non-Local Means algorithm, implemented on the GPU using +Vulkan. +Supports more pixel formats than nlmeans or nlmeans_opencl, including +alpha channel support. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength for all components. Default is 1.0. Must be in range [0.0, 100.0]. +

+
+
p
+

Set patch size for all planes. Default is 7. Must be odd number in range [0, 99]. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
t
+

Set parallelism. Default is 8. Must be a number in the range [1, 64]. +Larger values will use more VRAM but may not result in greater speed. +The optimal value is hardware and input dependent. +

+
+
s0
+
s1
+
s2
+
s3
+

Set denoising strength for a specific component. Default is 1.0, equal to s. +Must be in range [0.0, 100.0]. 0.0 disables denoising in that component. +

+
+
p0
+
p1
+
p2
+
p3
+

Set patch size for a specific component. Default is 7, equal to p. +Must be odd number in range [0, 99]. +

+
+
+ + +

44.11 overlay_vulkan

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires all inputs to use the same pixel format. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

44.12 transpose_vulkan

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

45 QSV Video Filters

+ +

Below is a description of the currently available QSV video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-libmfx or --enable-libvpl. +

+

To use QSV filters, you need to setup the QSV device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/QuickSync +

+ +

45.1 hstack_qsv

+

Stack input videos horizontally. +

+

This is the QSV variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

45.2 vstack_qsv

+

Stack input videos vertically. +

+

This is the QSV variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

45.3 xstack_qsv

+

Stack video inputs into custom layout. +

+

This is the QSV variant of the xstack filter. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_qsv=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + + +

46 Video Sources

+ +

Below is a description of the currently available video sources. +

+ +

46.1 buffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
+
video_size
+

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. +

+
+
width
+

The input video width. +

+
+
height
+

The input video height. +

+
+
pix_fmt
+

A string representing the pixel format of the buffered video frames. +It may be a number corresponding to a pixel format, or a pixel format +name. +

+
+
time_base
+

Specify the timebase assumed by the timestamps of the buffered frames. +

+
+
frame_rate
+

Specify the frame rate expected for the video stream. +

+
+
colorspace
+

A string representing the color space of the buffered video frames. +It may be a number corresponding to a color space, or a color space +name. +

+
+
range
+

A string representing the color range of the buffered video frames. +It may be a number corresponding to a color range, or a color range +name. +

+
+
alpha_mode
+

A string representing the alpha mode of the buffered video frames. +It may be a number corresponding to an alpha mode, or an alpha mode +name. +

+
+
pixel_aspect, sar
+

The sample (pixel) aspect ratio of the input video. +

+
+
hw_frames_ctx
+

When using a hardware pixel format, this should be a reference to an +AVHWFramesContext describing input frames. +

+
+ +

For example: +

+
buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
+
+ +

will instruct the source to accept video frames with size 320x240 and +with format "yuv410p", assuming 1/24 as the timestamps timebase and +square pixels (1:1 sample aspect ratio). +Since the pixel format with name "yuv410p" corresponds to the number 6 +(check the enum AVPixelFormat definition in libavutil/pixfmt.h), +this example corresponds to: +

+
buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
+
+ +

Alternatively, the options can be specified as a flat string, but this +syntax is deprecated: +

+

width:height:pix_fmt:time_base.num:time_base.den:pixel_aspect.num:pixel_aspect.den +

+ +

46.2 cellauto

+ +

Create a pattern generated by an elementary cellular automaton. +

+

The initial state of the cellular automaton can be defined through the +filename and pattern options. If such options are +not specified an initial state is created randomly. +

+

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 scroll option. +

+

This source accepts the following options: +

+
+
filename, f
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified file. +In the file, each non-whitespace character is considered an alive +cell, a newline will terminate the row, and further characters in the +file will be ignored. +

+
+
pattern, p
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified string. +

+

Each non-whitespace character in the string is considered an alive +cell, a newline will terminate the row, and further characters in the +string will be ignored. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial cellular automaton row. It +is a floating point number value ranging from 0 to 1, defaults to +1/PHI. +

+

This option is ignored when a file or a pattern is specified. +

+
+
random_seed, seed
+

Set the seed for filling randomly the initial row, 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. +

+
+
rule
+

Set the cellular automaton rule, it is a number ranging from 0 to 255. +Default value is 110. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename or pattern is specified, the size is set +by default to the width of the specified initial state row, and the +height is set to width * PHI. +

+

If size is set, it must contain the width of the specified +pattern string, and the specified pattern will be centered in the +larger row. +

+

If a filename or a pattern string is not specified, the size value +defaults to "320x518" (used for a randomly generated initial state). +

+
+
scroll
+

If set to 1, scroll the output upward when all the rows in the output +have been already filled. If set to 0, the new generated row will be +written over the top row just after the bottom row is filled. +Defaults to 1. +

+
+
start_full, full
+

If set to 1, completely fill the output with generated rows before +outputting the first frame. +This is the default behavior, for disabling set the value to 0. +

+
+
stitch
+

If set to 1, stitch the left and right row edges together. +This is the default behavior, for disabling set the value to 0. +

+
+ + +

46.2.1 Examples

+ +
    +
  • Read the initial state from pattern, and specify an output of +size 200x400. +
    +
    cellauto=f=pattern:s=200x400
    +
    + +
  • Generate a random initial row with a width of 200 cells, with a fill +ratio of 2/3: +
    +
    cellauto=ratio=2/3:s=200x200
    +
    + +
  • Create a pattern generated by rule 18 starting by a single alive cell +centered on an initial row with width 100: +
    +
    cellauto=p=@:s=100x400:full=0:rule=18
    +
    + +
  • Specify a more elaborated initial pattern: +
    +
    cellauto=p='@@ @ @@':s=100x400:full=0:rule=18
    +
    + +
+ + +

46.3 coreimagesrc

+

Video source generated on GPU using Apple’s CoreImage API on OSX. +

+

This video source is a specialized version of the coreimage video filter. +Use a core image generator at the beginning of the applied filterchain to +generate the content. +

+

The coreimagesrc video source accepts the following options: +

+
list_generators
+

List all available generators along with all their respective options as well as +possible minimum and maximum values along with the default values. +

+
list_generators=true
+
+ +
+
size, s
+

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. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+ +

Additionally, all options of the coreimage video filter are accepted. +A complete filterchain can be used for further processing of the +generated input without CPU-HOST transfer. See coreimage documentation +and examples for details. +

+ +

46.3.1 Examples

+ +
    +
  • Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +

    This example is equivalent to the QRCode example of coreimage without the +need for a nullsrc video source. +

+ + + +

46.4 ddagrab

+ +

Captures the Windows Desktop via Desktop Duplication API. +

+

The filter exclusively returns D3D11 Hardware Frames, for on-gpu encoding +or processing. So an explicit hwdownload is needed for any kind of +software processing. +

+

It accepts the following options: +

+
+
output_idx
+

DXGI Output Index to capture. +

+

Usually corresponds to the index Windows has given the screen minus one, +so it’s starting at 0. +

+

Defaults to output 0. +

+
+
draw_mouse
+

Whether to draw the mouse cursor. +

+

Defaults to true. +

+

Only affects hardware cursors. If a game or application renders its own cursor, +it’ll always be captured. +

+
+
framerate
+

Maximum framerate at which the desktop will be captured - the interval between +successive frames will not be smaller than the inverse of the framerate. When +dup_frames is true (the default) and the desktop is not being updated +often enough, the filter will duplicate a previous frame. Note that there is no +background buffering going on, so when the filter is not polled often enough +then the actual inter-frame interval may be significantly larger. +

+

Defaults to 30 FPS. +

+
+
video_size
+

Specify the size of the captured video. +

+

Defaults to the full size of the screen. +

+

Cropped from the bottom/right if smaller than screen size. +

+
+
offset_x
+

Horizontal offset of the captured video. +

+
+
offset_y
+

Vertical offset of the captured video. +

+
+
output_fmt
+

Desired filter output format. +Defaults to 8 Bit BGRA. +

+

It accepts the following values: +

+
‘auto’
+

Passes all supported output formats to DDA and returns what DDA decides to use. +

+
‘8bit’
+
‘bgra’
+

8 Bit formats always work, and DDA will convert to them if necessary. +

+
‘10bit’
+
‘x2bgr10’
+

Filter initialization will fail if 10 bit format is requested but unavailable. +

+
+ +
+
dup_frames
+

When this option is set to true (the default), the filter will duplicate frames +when the desktop has not been updated in order to maintain approximately +constant target framerate. When this option is set to false, the filter will +wait for the desktop to be updated (inter-frame intervals may vary significantly +in this case). +

+
+
+ + +

46.4.1 Examples

+ +

Capture primary screen and encode using nvenc: +

+
ffmpeg -f lavfi -i ddagrab -c:v h264_nvenc -cq 18 output.mp4
+
+ +

You can also skip the lavfi device and directly use the filter. +Also demonstrates downloading the frame and encoding with libx264. +Explicit output format specification is required in this case: +

+
ffmpeg -filter_complex ddagrab=output_idx=1:framerate=60,hwdownload,format=bgra -c:v libx264 -crf 18 output.mp4
+
+ +

If you want to capture only a subsection of the desktop, this can be achieved +by specifying a smaller size and its offsets into the screen: +

+
ddagrab=video_size=800x600:offset_x=100:offset_y=100
+
+ + + +

46.5 gfxcapture

+ +

Capture windows or monitors using Windows.Graphics.Capture API. +

+

This source provides low overhead capture of application windows or entire monitors. +The filter outputs hardware frames in d3d11 format; use hwdownload,format= +if system memory frames are required. +

+

The window to be captured can be selected via regular expressions on its title, +class name or backing executable name, by explicit native handles, or by monitor +index or explicit native handle. A window must match all provided expressions to be +selected. The first matching window will be picked, in whatever order Windows +returns them. +

+

Explicit handles (hwnd, hmonitor) override pattern or index +based selection. If neither handles nor a monitor index are given, the first +window matching the provided regular expressions is captured. +

+

This source does NOT hold a stable FPS. It returns frames at whatever rate the compositor +provides them, only capped by the max_framerate. +If you need a stable rate, you need to add an fps filter to drop/duplicate frames as needed. +

+

If the capture source disappears mid-capture (window closed, monitor disconnected), the filter will return EOF. +

+

This source accepts the following options: +

+
window_title
+

ECMAScript regular expression matched against the window title. Supports a +PCRE style (?i) prefix for case-insensitive matching. +

+
+
window_class
+

As window_title, but matched against the window class name. +

+
+
window_exe
+

As window_title, but matched against the executable file name of the +window’s process. +

+
+
monitor_idx
+

Zero-based index of the monitor to capture. +

+

Can also be set to window to capture the monitor the selected window +is displayed on at filter initialization time. +

+
+
hwnd
+

Explicit native window handle (HWND). +

+
+
hmonitor
+

Explicit native monitor handle (HMONITOR). +

+
+
capture_cursor
+

Capture the mouse cursor. Enabled by default. +

+
+
capture_border
+

Capture the full area of the window, including its window decorarions/border. +Disabled by default. +

+
+
display_border
+

Draw a yellow highlight border around the captured window. Disabled by default. +

+
+
max_framerate
+

Maximum capture frame rate. Accepts a video rate (e.g. 30, 60/1, +24000/1001). The default is 60 FPS. +The actual rate is the rate at which the compositor renders the window/monitor, +capped by this option. +

+
+
width
+

Force the output canvas width. If zero (default) the initial captured source +width is used. If a negative number is provided, the width will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
height
+

Force the output canvas height. If zero (default) the initial captured source +height is used. If a negative number is provided, the height will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
crop_left
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_top
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_right
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_bottom
+

Crop this many pixels from the left side of the captured frames. +

+
+
premultiplied
+

If set to 1, return frames with premultiplied alpha. Default is 0 (straight +alpha). +

+
+
resize_mode
+

Defines how the captured content is fitted into the output canvas size. +Possible values: +

+
‘crop’
+

Crop (or pad with black) to the canvas size. (default) +

+
‘scale’
+

Scale the source to fill the canvas, potentially altering aspect ratio. +

+
‘scale_aspect’
+

Scale the source to fit inside the canvas while preserving aspect ratio. +Remaining area is filled with black. +

+
+ +
+
scale_mode
+

Scaling algorithm used when resizing is required. +

+

Possible values: +

+
‘point’
+

Nearest neighbour (pixelated) scaling. +

+
‘bilinear’
+

Bilinear filtering. (default) +

+
‘bicubic’
+

Bicubic filtering. Potentially more blurry, but fewer scaling artifacts depending on contents. +

+
+ +
+
output_fmt
+

Desired output pixel format inside the D3D11 hardware frames. +

+

Possible values: +

+
‘bgra’
+
‘8bit’
+

8 bit BGRA output (default) +

+
‘x2bgr10’
+
‘10bit’
+

10 bit BGR output +

+
‘rgbaf16’
+
‘16bit’
+

16bit float RGBA output +

+
+ +
+
+ + +

46.5.1 Examples

+
    +
  • Capture a window by title (case-insensitive) at a maximum of 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_title='(?i)My Application':max_framerate=60,hwdownload,format=bgra,format=yuv420p -c:v libx264 -crf 15 capture.mp4
    +
    + +
  • Capture monitor 1 at native refresh, 10bit color depth, scale to 1920x1080 preserving aspect: +
    +
    ffmpeg -filter_complex gfxcapture=monitor_idx=1:width=1920:height=1080:resize_mode=scale_aspect:output_fmt=10bit -c:v hevc_nvenc -cq 15 capture.mp4
    +
    + +
  • Capture a window by executable name, draw border, force point scaling, fixed 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_exe='^firefox.exe$':display_border=1:scale_mode=point,fps=60 -rc qvbr -qvbr_quality_level 15 -c:v h264_amf capture.mp4
    +
    + +
+ + + +

46.6 gradients

+

Generate several gradients. +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
c0, c1, c2, c3, c4, c5, c6, c7
+

Set 8 colors. Default values for colors is to pick random one. +

+
+
x0, y0, y0, y1
+

Set gradient line source and destination points. If negative or out of range, random ones +are picked. +

+
+
nb_colors, n
+

Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2. +

+
+
seed
+

Set seed for picking gradient line points. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
speed
+

Set speed of gradients rotation. +

+
+
type, t
+

Set type of gradients. +Available values are: +

+
‘linear’
+
‘radial’
+
‘circular’
+
‘spiral’
+
‘square’
+
+ +

Default type is linear. +

+
+ + +

46.6.1 Commands

+ +

This source supports the some above options as commands. +

+ +

46.7 mandelbrot

+ +

Generate a Mandelbrot set fractal, and progressively zoom towards the +point specified with start_x and start_y. +

+

This source accepts the following options: +

+
+
end_pts
+

Set the terminal pts value. Default value is 400. +

+
+
end_scale
+

Set the terminal scale value. +Must be a floating point value. Default value is 0.3. +

+
+
inner
+

Set the inner coloring mode, that is the algorithm used to draw the +Mandelbrot fractal internal region. +

+

It shall assume one of the following values: +

+
black
+

Set black mode. +

+
convergence
+

Show time until convergence. +

+
mincol
+

Set color based on point closest to the origin of the iterations. +

+
period
+

Set period mode. +

+
+ +

Default value is mincol. +

+
+
bailout
+

Set the bailout value. Default value is 10.0. +

+
+
maxiter
+

Set the maximum of iterations performed by the rendering +algorithm. Default value is 7189. +

+
+
outer
+

Set outer coloring mode. +It shall assume one of following values: +

+
iteration_count
+

Set iteration count mode. +

+
normalized_iteration_count
+

set normalized iteration count mode. +

+
+

Default value is normalized_iteration_count. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
start_scale
+

Set the initial scale value. Default value is 3.0. +

+
+
start_x
+

Set the initial x position. Must be a floating point value between +-100 and 100. Default value is -0.743643887037158704752191506114774. +

+
+
start_y
+

Set the initial y position. Must be a floating point value between +-100 and 100. Default value is -0.131825904205311970493132056385139. +

+
+ + +

46.8 mptestsrc

+ +

Generate various test patterns, as generated by the MPlayer test filter. +

+

The size of the generated video is fixed, and is 512x512. +This source is useful in particular for testing encoding features. +

+

This source accepts the following options: +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
test, t
+
+

Set the number or the name of the test to perform. Supported tests are: +

+
dc_luma
+
dc_chroma
+
freq_luma
+
freq_chroma
+
amp_luma
+
amp_chroma
+
cbp
+
mv
+
ring1
+
ring2
+
all
+
max_frames, m
+

Set the maximum number of frames generated for each test, default value is 30. +

+
+
+ +

Default value is "all", which will cycle through the list of all tests. +

+
+ +

Some examples: +

+
mptestsrc=t=dc_luma
+
+ +

will generate a "dc_luma" test pattern. +

+ +

46.9 frei0r_src

+ +

Provide a frei0r source. +

+

To enable compilation of this filter you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

This source accepts the following parameters: +

+
+
size
+

The size of the video to generate. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
framerate
+

The framerate of the generated video. It may be a string of the form +num/den or a frame rate abbreviation. +

+
+
filter_name
+

The name to the frei0r source to load. For more information regarding frei0r and +how to set the parameters, read the frei0r section in the video filters +documentation. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r source. +

+
+
+ +

For example, to generate a frei0r partik0l source with size 200x200 +and frame rate 10 which is overlaid on the overlay filter main input: +

+
frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
+
+ + +

46.10 life

+ +

Generate a life pattern. +

+

This source is based on a generalization of John Conway’s life game. +

+

The sourced input represents a life grid, each pixel represents a cell +which can be in one of two possible states, alive or dead. Every cell +interacts with its eight neighbours, which are the cells that are +horizontally, vertically, or diagonally adjacent. +

+

At each interaction the grid evolves according to the adopted rule, +which specifies the number of neighbor alive cells which will make a +cell stay alive or born. The rule option allows one to specify +the rule to adopt. +

+

This source accepts the following options: +

+
+
filename, f
+

Set the file from which to read the initial grid state. In the file, +each non-whitespace character is considered an alive cell, and newline +is used to delimit the end of each row. +

+

If this option is not specified, the initial grid is generated +randomly. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial random grid. It is a +floating point number value ranging from 0 to 1, defaults to 1/PHI. +It is ignored when a file is specified. +

+
+
random_seed, seed
+

Set the seed for filling the initial random grid, 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. +

+
+
rule
+

Set the life rule. +

+

A rule can be specified with a code of the kind "SNS/BNB", +where NS and NB are sequences of numbers in the range 0-8, +NS specifies the number of alive neighbor cells which make a +live cell stay alive, and NB the number of alive neighbor cells +which make a dead cell to become alive (i.e. to "born"). +"s" and "b" can be used in place of "S" and "B", respectively. +

+

Alternatively a rule can be specified by an 18-bits integer. The 9 +high order bits are used to encode the next cell state if it is alive +for each number of neighbor alive cells, the low order bits specify +the rule for "borning" new cells. Higher order bits encode for an +higher number of neighbor cells. +For example the number 6153 = (12<<9)+9 specifies a stay alive +rule of 12 and a born rule of 9, which corresponds to "S23/B03". +

+

Default value is "S23/B3", which is the original Conway’s game of life +rule, and will keep a cell alive if it has 2 or 3 neighbor alive +cells, and will born a new cell if there are three alive cells around +a dead cell. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename is specified, the size is set by default to the +same size of the input file. If size is set, it must contain +the size specified in the input file, and the initial grid defined in +that file is centered in the larger resulting area. +

+

If a filename is not specified, the size value defaults to "320x240" +(used for a randomly generated initial grid). +

+
+
stitch
+

If set to 1, stitch the left and right grid edges together, and the +top and bottom edges also. Defaults to 1. +

+
+
mold
+

Set cell mold speed. If set, a dead cell will go from death_color to +mold_color with a step of mold. mold can have a +value from 0 to 255. +

+
+
life_color
+

Set the color of living (or new born) cells. +

+
+
death_color
+

Set the color of dead cells. If mold is set, this is the first color +used to represent a dead cell. +

+
+
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. +

+
+ + +

46.10.1 Examples

+ +
    +
  • Read a grid from pattern, and center it on a grid of size +300x300 pixels: +
    +
    life=f=pattern:s=300x300
    +
    + +
  • Generate a random grid of size 200x200, with a fill ratio of 2/3: +
    +
    life=ratio=2/3:s=200x200
    +
    + +
  • Specify a custom rule for evolving a randomly generated grid: +
    +
    life=rule=S14/B34
    +
    + +
  • Full example with slow death effect (mold) using ffplay: +
    +
    ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
    +
    +
+ + +

46.11 perlin

+

Generate Perlin noise. +

+

Perlin noise is a kind of noise with local continuity in space. This +can be used to generate patterns with continuity in space and time, +e.g. to simulate smoke, fluids, or terrain. +

+

In case more than one octave is specified through the octaves +option, Perlin noise is generated as a sum of components, each one +with doubled frequency. In this case the persistence option +specify the ratio of the amplitude with respect to the previous +component. More octave components enable to specify more high +frequency details in the generated noise (e.g. small size variations +due to boulders in a generated terrain). +

+ +

46.11.1 Options

+
+
size, s
+

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. +Default value is 320x240. +

+
+
rate, r
+

Specify the frame rate expected for the video stream, expressed as a +number of frames per second. Default value is 25. +

+
+
octaves
+

Specify the total number of components making up the noise, each one +with doubled frequency. Default value is 1. +

+
+
persistence
+

Set the ratio used to compute the amplitude of the next octave +component with respect to the previous component amplitude. Default +value is 1. +

+
+
xscale
+
yscale
+

Define a scale factor used to multiple the x, y coordinates. This can +be useful to define an effect with a pattern stretched along the x or +y axis. Default value is 1. +

+
+
tscale
+

Define a scale factor used to multiple the time coordinate. This can +be useful to change the time variation speed. Default value is 1. +

+
+
random_mode
+

Set random mode used to compute initial pattern. +

+

Supported values are: +

+
random
+

Compute and use random seed. +

+
+
ken
+

Use the predefined initial pattern defined by Ken Perlin in the +original article, can be useful to compare the output with other +sources. +

+
+
seed
+

Use the value specified by random_seed option. +

+
+ +

Default value is random. +

+
+
random_seed, seed
+

When random_mode is set to random_seed, use this value +to compute the initial pattern. Default value is 0. +

+
+ + +

46.11.2 Examples

+
    +
  • Generate single component: +
    +
    perlin
    +
    + +
  • Use Perlin noise with 7 components, each one with a halved contribution +to total amplitude: +
    +
    perlin=octaves=7:persistence=0.5
    +
    + +
  • Chain Perlin noise with the lutyuv to generate a black&white +effect: +
    +
    perlin=octaves=3:tscale=0.3,lutyuv=y='if(lt(val\,128)\,255\,0)'
    +
    + +
  • Stretch noise along the y axis, and convert gray level to red-only +signal: +
    +
    perlin=octaves=7:tscale=0.4:yscale=0.3,lutrgb=r=val:b=0:g=0
    +
    +
+ + +

46.12 qrencodesrc

+ +

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/). +

+

To enable the compilation of this source, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and put in the video output according to the +specified output size options. +

+

In case no text is specified, the QR code is not generated, but an empty colored +output is returned instead. +

+

This source accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated only once, when initializing the source. +See the qrencode Expressions section for details. +

+

Note that some of the constants are missing for the source (for example the +x or t or ¸n), since they only makes sense when evaluating the +expression for each frame rather than at initialization time. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

46.12.1 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size: +
    +
    qrencodesrc=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencodesrc=text=www.ffmpeg.org:bc=pink:fc=blue
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencodesrc=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencodesrc=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencodesrc=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencodesrc=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencodesrc=text=%{pts}
    +
    + +
+ + +

46.13 allrgb, allyuv, color, colorchart, colorspectrum, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc

+ +

The allrgb source returns frames of size 4096x4096 of all rgb colors. +

+

The allyuv source returns frames of size 4096x4096 of all yuv colors. +

+

The color source provides an uniformly colored input. +

+

The colorchart source provides a colors checker chart. +

+

The colorspectrum source provides a color spectrum input. +

+

The haldclutsrc source provides an identity Hald CLUT. See also +haldclut filter. +

+

The 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. +

+

The pal75bars source generates a color bars pattern, based on +EBU PAL recommendations with 75% color levels. +

+

The pal100bars source generates a color bars pattern, based on +EBU PAL recommendations with 100% color levels. +

+

The rgbtestsrc source generates an RGB test pattern useful for +detecting RGB vs BGR issues. You should see a red, green and blue +stripe from top to bottom. +

+

The smptebars source generates a color bars pattern, based on +the SMPTE Engineering Guideline EG 1-1990. +

+

The smptehdbars source generates a color bars pattern, based on +the SMPTE RP 219-2002. +

+

The testsrc source generates a test video pattern, showing a +color pattern, a scrolling gradient and a timestamp. This is mainly +intended for testing purposes. +

+

The testsrc2 source is similar to testsrc, but supports more +pixel formats instead of just rgb24. This allows using it as an +input for other tests without requiring a format conversion. +

+

The yuvtestsrc source generates an YUV test pattern. You should +see a y, cb and cr stripe from top to bottom. +

+

The sources accept the following parameters: +

+
+
level
+

Specify the level of the Hald CLUT, only available in the haldclutsrc +source. A level of N generates a picture of N*N*N by N*N*N +pixels to be used as identity matrix for 3D lookup tables. Each component is +coded on a 1/(N*N) scale. +

+
+
color, c
+

Specify the color of the source, only available in the color +source. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +

+
+
size, s
+

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 allrgb, allyuv, and +haldclutsrc filters. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+

Since the frame rate is used as time base, all frames including the last one +will have their full duration. If the specified duration is not a multiple +of the frame duration, it will be rounded up. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
alpha
+

Specify the alpha (opacity) of the background, only available in the +testsrc2 source. The value must be between 0 (fully transparent) and +255 (fully opaque, the default). +

+
+
decimals, n
+

Set the number of decimals to show in the timestamp, only available in the +testsrc source. +

+

The displayed timestamp value will correspond to the original +timestamp value multiplied by the power of 10 of the specified +value. Default value is 0. +

+
+
type
+

Set the type of the color spectrum, only available in the +colorspectrum source. Can be one of the following: +

+
+
‘black’
+
‘white’
+
‘all’
+
+ +
+
patch_size
+

Set patch size of single color patch, only available in the +colorchart source. Default is 64x64. +

+
+
preset
+

Set colorchecker colors preset, only available in the +colorchart source. +

+

Available values are: +

+
‘reference’
+
‘skintones’
+
+ +

Default value is reference. +

+
+ + +

46.13.1 Examples

+ +
    +
  • Generate a video with a duration of 5.3 seconds, with size +176x144 and a frame rate of 10 frames per second: +
    +
    testsrc=duration=5.3:size=qcif:rate=10
    +
    + +
  • The following graph description will generate a red source +with an opacity of 0.2, with size "qcif" and a frame rate of 10 +frames per second: +
    +
    color=c=red@0.2:s=qcif:r=10
    +
    + +
  • If the input content is to be ignored, nullsrc can be used. The +following command generates noise in the luma plane by employing +the geq filter: +
    +
    nullsrc=s=256x256, geq=random(1)*255:128:128
    +
    +
+ + +

46.13.2 Commands

+ +

The color source supports the following commands: +

+
+
c, color
+

Set the color of the created image. Accepts the same syntax of the +corresponding color option. +

+
+ + +

46.14 openclsrc

+ +

Generate video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
size, s
+

Size of frames to generate. This must be set. +

+
+
format
+

Pixel format to use for the generated frames. This must be set. +

+
+
rate, r
+

Number of frames generated every second. Default value is ’25’. +

+
+
+ +

For details of how the program loading works, see the program_opencl +filter. +

+

Example programs: +

+
    +
  • Generate a colour ramp by setting pixel values from the position of the pixel +in the output image. (Note that this will work with all pixel formats, but +the generated output will not be the same.) +
    __kernel void ramp(__write_only image2d_t dst,
    +                   unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 val;
    +    val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
    +
    +    write_imagef(dst, loc, val);
    +}
    +
    +
  • Generate a Sierpinski carpet pattern, panning by a single pixel each frame. +
    __kernel void sierpinski_carpet(__write_only image2d_t dst,
    +                                unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = 0.0f;
    +    int x = loc.x + index;
    +    int y = loc.y + index;
    +    while (x > 0 || y > 0) {
    +        if (x % 3 == 1 && y % 3 == 1) {
    +            value = 1.0f;
    +            break;
    +        }
    +        x /= 3;
    +        y /= 3;
    +    }
    +
    +    write_imagef(dst, loc, value);
    +}
    +
    +
+ + +

46.15 sierpinski

+ +

Generate a Sierpinski carpet/triangle fractal, and randomly pan around. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
seed
+

Set seed which is used for random panning. +

+
+
jump
+

Set max jump for single pan destination. Allowed range is from 1 to 10000. +

+
+
type
+

Set fractal type, can be default carpet or triangle. +

+
+ + +

46.16 zoneplate

+

Generate a zoneplate test video pattern. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "320x240". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
precision
+

Set precision in bits for look-up table for sine calculations. Default value is 10. +Allowed range is from 4 to 16. +

+
+
xo
+

Set horizontal axis offset for output signal. Default value is 0. +

+
+
yo
+

Set vertical axis offset for output signal. Default value is 0. +

+
+
to
+

Set time axis offset for output signal. Default value is 0. +

+
+
k0
+

Set 0-order, constant added to signal phase. Default value is 0. +

+
+
kx
+

Set 1-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky
+

Set 1-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt
+

Set 1-order, phase factor multiplier for time axis. Default value is 0. +

+
+
kxt, kyt, kxy
+

Set phase factor multipliers for combination of spatial and temporal axis. +Default value is 0. +

+
+
kx2
+

Set 2-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky2
+

Set 2-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt2
+

Set 2-order, phase factor multiplier for time axis. Default value is 0. +

+
+
ku
+

Set the constant added to final phase to produce chroma-blue component of signal. +Default value is 0. +

+
+
kv
+

Set the constant added to final phase to produce chroma-red component of signal. +Default value is 0. +

+
+ + +

46.16.1 Commands

+ +

This source supports the some above options as commands. +

+ +

46.16.2 Examples

+ +
    +
  • Generate horizontal color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:kx2=256:s=wvga:xo=-426:kt=11
    +
    + +
  • Generate vertical color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:ky2=156:s=wvga:yo=-240:kt=11
    +
    + +
  • Generate circular zone-plate: +
    +
    zoneplate=ku=512:kv=100:kt2=0:ky2=256:kx2=556:s=wvga:yo=0:kt=11
    +
    +
+ + + +

47 Video Sinks

+ +

Below is a description of the currently available video sinks. +

+ +

47.1 buffersink

+ +

Buffer video frames, and make them available to the end of the filter +graph. +

+

This sink is mainly intended for programmatic use, in particular +through the interface defined in libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVBufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+ +

47.2 nullsink

+ +

Null video sink: do absolutely nothing with the input video. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

48 Multimedia Filters

+ +

Below is a description of the currently available multimedia filters. +

+ +

48.1 a3dscope

+ +

Convert input audio to 3d scope video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
fov
+

Set the camera field of view. Default is 90 degrees. +Allowed range is from 40 to 150. +

+
+
roll
+

Set the camera roll. +

+
+
pitch
+

Set the camera pitch. +

+
+
yaw
+

Set the camera yaw. +

+
+
xzoom
+

Set the camera zoom on X-axis. +

+
+
yzoom
+

Set the camera zoom on Y-axis. +

+
+
zzoom
+

Set the camera zoom on Z-axis. +

+
+
xpos
+

Set the camera position on X-axis. +

+
+
ypos
+

Set the camera position on Y-axis. +

+
+
zpos
+

Set the camera position on Z-axis. +

+
+
length
+

Set the length of displayed audio waves in number of frames. +

+
+ + +

48.1.1 Commands

+ +

Filter supports the some above options as commands. +

+ +

48.2 abitscope

+ +

Convert input audio to a video output, displaying the audio bit scope. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 1024x256. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channels. Unrecognized or missing colors will be replaced +by white color. +

+
+
mode, m
+

Set output mode. Can be bars or trace. Default is bars. +

+
+ + +

48.3 adrawgraph

+

Draw a graph using input audio metadata. +

+

See drawgraph +

+ +

48.4 agraphmonitor

+ +

See graphmonitor. +

+ +

48.5 ahistogram

+ +

Convert input audio to a video output, displaying the volume histogram. +

+

The filter accepts the following options: +

+
+
dmode
+

Specify how histogram is calculated. +

+

It accepts the following values: +

+
‘single’
+

Use single histogram for all channels. +

+
‘separate’
+

Use separate histogram for each channel. +

+
+

Default is single. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
scale
+

Set display scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘sqrt’
+

square root +

+
‘cbrt’
+

cubic root +

+
‘lin’
+

linear +

+
‘rlog’
+

reverse logarithmic +

+
+

Default is log. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘lin’
+

linear +

+
+

Default is log. +

+
+
acount
+

Set how much frames to accumulate in histogram. +Default is 1. Setting this to -1 accumulates all frames. +

+
+
rheight
+

Set histogram ratio of window height. +

+
+
slide
+

Set sonogram sliding. +

+

It accepts the following values: +

+
‘replace’
+

replace old rows with new ones. +

+
‘scroll’
+

scroll from top to bottom. +

+
+

Default is replace. +

+
+
hmode
+

Set histogram mode. +

+

It accepts the following values: +

+
‘abs’
+

Use absolute values of samples. +

+
‘sign’
+

Use untouched values of samples. +

+
+

Default is abs. +

+
+ + +

48.6 aphasemeter

+ +

Measures phase of input audio, which is exported as metadata lavfi.aphasemeter.phase, +representing mean phase of current audio frame. A video output can also be produced and is +enabled by default. The audio is passed through as first output. +

+

Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in +range [-1, 1] where -1 means left and right channels are completely out of phase +and 1 means channels are in phase. +

+

The filter accepts the following options, all related to its video output: +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
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 800x400. +

+
+
rc
+
gc
+
bc
+

Specify the red, green, blue contrast. Default values are 2, +7 and 1. +Allowed range is [0, 255]. +

+
+
mpc
+

Set color which will be used for drawing median phase. If color is +none which is default, no median phase value will be drawn. +

+
+
video
+

Enable video output. Default is enabled. +

+
+ + +

48.6.1 phasing detection

+ +

The filter also detects out of phase and mono sequences in stereo streams. +It logs the sequence start, end and duration when it lasts longer or as long as the minimum set. +

+

The filter accepts the following options for this detection: +

+
+
phasing
+

Enable mono and out of phase detection. Default is disabled. +

+
+
tolerance, t
+

Set phase tolerance for mono detection, in amplitude ratio. Default is 0. +Allowed range is [0, 1]. +

+
+
angle, a
+

Set angle threshold for out of phase detection, in degree. Default is 170. +Allowed range is [90, 180]. +

+
+
duration, d
+

Set mono or out of phase duration until notification, expressed in seconds. Default is 2. +

+
+ + +

48.6.2 Examples

+ +
    +
  • Complete example with ffmpeg to detect 1 second of mono with 0.001 phase tolerance: +
    +
    ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
    +
    +
+ + +

48.7 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 monaural 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: +

+
+
mode, m
+

Set the vectorscope mode. +

+

Available values are: +

+
‘lissajous’
+

Lissajous rotated by 45 degrees. +

+
+
‘lissajous_xy’
+

Same as above but not rotated. +

+
+
‘polar’
+

Shape resembling half of circle. +

+
+ +

Default value is ‘lissajous’. +

+
+
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 400x400. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
rc
+
gc
+
bc
+
ac
+

Specify the red, green, blue and alpha contrast. Default values are 40, +160, 80 and 255. +Allowed range is [0, 255]. +

+
+
rf
+
gf
+
bf
+
af
+

Specify the red, green, blue and alpha fade. Default values are 15, +10, 5 and 5. +Allowed range is [0, 255]. +

+
+
zoom
+

Set the zoom factor. Default value is 1. Allowed range is [0, 10]. +Values lower than 1 will auto adjust zoom factor to maximal possible value. +

+
+
draw
+

Set the vectorscope drawing mode. +

+

Available values are: +

+
‘dot’
+

Draw dot for each sample. +

+
+
‘line’
+

Draw line between previous and current sample. +

+
+
‘aaline’
+

Draw anti-aliased line between previous and current sample. +

+
+ +

Default value is ‘dot’. +

+
+
scale
+

Specify amplitude scale of audio samples. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+
‘log’
+

Logarithmic. +

+
+ +
+
swap
+

Swap left channel axis with right channel axis. +

+
+
mirror
+

Mirror axis. +

+
+
‘none’
+

No mirror. +

+
+
‘x’
+

Mirror only x axis. +

+
+
‘y’
+

Mirror only y axis. +

+
+
‘xy’
+

Mirror both axis. +

+
+ +
+
+ + +

48.7.1 Examples

+ +
    +
  • Complete example using ffplay: +
    +
    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]'
    +
    +
+ + +

48.7.2 Commands

+ +

This filter supports the all above options as commands except options size and rate. +

+ +

48.8 bench, abench

+ +

Benchmark part of a filtergraph. +

+

The filter accepts the following options: +

+
+
action
+

Start or stop a timer. +

+

Available values are: +

+
‘start’
+

Get the current time, set it as frame metadata (using the key +lavfi.bench.start_time), and forward the frame to the next filter. +

+
+
‘stop’
+

Get the current time and fetch the lavfi.bench.start_time metadata from +the input frame metadata to get the time difference. Time difference, average, +maximum and minimum time (respectively t, avg, max and +min) are then printed. The timestamps are expressed in seconds. +

+
+
+
+ + +

48.8.1 Examples

+ +
    +
  • Benchmark selectivecolor filter: +
    +
    bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
    +
    +
+ + +

48.9 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: +

+
+
n
+

Set the number of segments. Default is 2. +

+
+
v
+

Set the number of output video streams, that is also the number of video +streams in each segment. Default is 1. +

+
+
a
+

Set the number of output audio streams, that is also the number of audio +streams in each segment. Default is 0. +

+
+
unsafe
+

Activate unsafe mode: do not fail if segments have a different format. +

+
+
+ +

The filter has v+a outputs: first v video outputs, then +a audio outputs. +

+

There are nx(v+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. +

+ +

48.9.1 Examples

+ +
    +
  • Concatenate an opening, an episode and an ending, all in bilingual version +(video in stream 0, audio in streams 1 and 2): +
    +
    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
    +
    + +
  • Concatenate two parts, handling audio and video separately, using the +(a)movie sources, and adjusting the resolution: +
    +
    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]
    +
    +

    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. +

    +
+ + +

48.9.2 Commands

+ +

This filter supports the following commands: +

+
next
+

Close the current segment and step to the next one +

+
+ + +

48.10 ebur128

+ +

EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness +level. By default, it logs a message at a frequency of 10Hz with the +Momentary loudness (identified by M), Short-term loudness (S), +Integrated loudness (I) and Loudness Range (LRA). +

+

The filter can only analyze streams which have +sample format is double-precision floating point. The input stream will be converted to +this specification, if needed. Users may need to insert aformat and/or aresample filters +after this filter to obtain the original parameters. +

+

The filter also has a video output (see the 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), but can optionally be configured +to instead display short-term loudness (see gauge). +

+

The green area marks a +/- 1LU target range around the target loudness +(-23LUFS by default, unless modified through target). +

+

More information about the Loudness Recommendation EBU R128 on +http://tech.ebu.ch/loudness. +

+

The filter accepts the following options: +

+
+
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 0. +

+
+
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 640x480. +

+
+
meter
+

Set the EBU scale meter. Default is 9. Common values are 9 and +18, respectively for EBU scale meter +9 and EBU scale meter +18. Any +other integer value between this range is allowed. +

+
+
metadata
+

Set metadata injection. If set to 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 lavfi.r128.. +

+

Default is 0. +

+
+
framelog
+

Force the frame logging level. +

+

Available values are: +

+
‘quiet’
+

logging disabled +

+
‘info’
+

information logging level +

+
‘verbose’
+

verbose logging level +

+
+ +

By default, the logging level is set to info. If the video or +the metadata options are set, it switches to verbose. +

+
+
peak
+

Set peak mode(s). +

+

Available modes can be cumulated (the option is a flag type). Possible +values are: +

+
‘none’
+

Disable any peak mode (default). +

+
‘sample’
+

Enable sample-peak mode. +

+

Simple peak mode looking for the higher sample value. It logs a message +for sample-peak (identified by SPK). +

+
‘true’
+

Enable true-peak mode. +

+

If enabled, the peak lookup is done on an over-sampled version of the input +stream for better peak accuracy. It logs a message for true-peak. +(identified by TPK) and true-peak per frame (identified by FTPK). +This mode requires a build with libswresample. +

+
+ +
+
dualmono
+

Treat mono input files as "dual mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +

+
+
panlaw
+

Set a specific pan law to be used for the measurement of dual mono files. +This parameter is optional, and has a default value of -3.01dB. +

+
+
target
+

Set a specific target level (in LUFS) used as relative zero in the visualization. +This parameter is optional and has a default value of -23LUFS as specified +by EBU R128. However, material published online may prefer a level of -16LUFS +(e.g. for use with podcasts or video platforms). +

+
+
gauge
+

Set the value displayed by the gauge. Valid values are momentary and s +shortterm. By default the momentary value will be used, but in certain +scenarios it may be more useful to observe the short term value instead (e.g. +live mixing). +

+
+
scale
+

Sets the display scale for the loudness. Valid parameters are absolute +(in LUFS) or relative (LU) relative to the target. This only affects the +video output, not the summary or continuous log output. +

+
+
integrated
+

Read-only exported value for measured integrated loudness, in LUFS. +

+
+
range
+

Read-only exported value for measured loudness range, in LU. +

+
+
lra_low
+

Read-only exported value for measured LRA low, in LUFS. +

+
+
lra_high
+

Read-only exported value for measured LRA high, in LUFS. +

+
+
sample_peak
+

Read-only exported value for measured sample peak, in dBFS. +

+
+
true_peak
+

Read-only exported value for measured true peak, in dBFS. +

+
+ + +

48.10.1 Examples

+ +
    +
  • Real-time graph using ffplay, with a EBU scale meter +18: +
    +
    ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
    +
    + +
  • Run an analysis with ffmpeg: +
    +
    ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
    +
    +
+ + +

48.11 interleave, ainterleave

+ +

Temporally interleave frames from several inputs. +

+

interleave works with video inputs, ainterleave with audio. +

+

These filters read frames from several inputs and send the oldest +queued frame to the output. +

+

Input streams must have 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 select filter +which always drops input frames. The interleave filter will keep +reading from that input, but it will never be able to send new frames +to output until the input sends 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: +

+
+
nb_inputs, n
+

Set the number of different inputs, it is 2 by default. +

+
+
duration
+

How to determine the end-of-stream. +

+
+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+ +
+
+ + +

48.11.1 Examples

+ +
    +
  • Interleave frames belonging to different streams using ffmpeg: +
    +
    ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
    +
    + +
  • Add flickering blur effect: +
    +
    select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
    +
    +
+ + +

48.12 latency, alatency

+

Measure filtering latency. +

+

Report previous filter filtering latency, delay in number of audio samples for audio filters +or number of video frames for video filters. +

+

On end of input stream, filter will report min and max measured latency for previous running filter +in filtergraph. +

+ +

48.13 metadata, ametadata

+ +

Manipulate frame metadata. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

If both value and key is set, select frames +which have such metadata. If only key is set, select +every frame that has such key in metadata. +

+
+
‘add’
+

Add new metadata key and value. If key is already available +do nothing. +

+
+
‘modify’
+

Modify value of already present key. +

+
+
‘delete’
+

If value is set, delete only keys that have such value. +Otherwise, delete key. If key is not set, delete all metadata values in +the frame. +

+
+
‘print’
+

Print key and its value if metadata was found. If key is not set print all +metadata values available in frame. +

+
+ +
+
key
+

Set key used with all modes. Must be set for all modes except print and delete. +

+
+
value
+

Set metadata value which will be used. This option is mandatory for +modify and add mode. +

+
+
function
+

Which function to use when comparing metadata value and value. +

+

Can be one of following: +

+
+
‘same_str’
+

Values are interpreted as strings, returns true if metadata value is same as value. +

+
+
‘starts_with’
+

Values are interpreted as strings, returns true if metadata value starts with +the value option string. +

+
+
‘less’
+

Values are interpreted as floats, returns true if metadata value is less than value. +

+
+
‘equal’
+

Values are interpreted as floats, returns true if value is equal with metadata value. +

+
+
‘greater’
+

Values are interpreted as floats, returns true if metadata value is greater than value. +

+
+
‘expr’
+

Values are interpreted as floats, returns true if expression from option expr +evaluates to true. +

+
+
‘ends_with’
+

Values are interpreted as strings, returns true if metadata value ends with +the value option string. +

+
+ +
+
expr
+

Set expression which is used when function is set to expr. +The expression is evaluated through the eval API and can contain the following +constants: +

+
+
VALUE1, FRAMEVAL
+

Float representation of value from metadata key. +

+
+
VALUE2, USERVAL
+

Float representation of value as supplied by user in value option. +

+
+ +
+
file
+

If specified in print mode, output is written to the named file. Instead of +plain filename any writable url can be specified. Filename “-” is a shorthand +for standard output. If file option is not set, output is written to the log +with AV_LOG_INFO loglevel. +

+
+
direct
+

Reduces buffering in print mode when output is written to a URL set using file. +

+
+
+ + +

48.13.1 Examples

+ +
    +
  • Print all metadata values for frames with key lavfi.signalstats.YDIF with values +between 0 and 1. +
    +
    signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
    +
    +
  • Print silencedetect output to file metadata.txt. +
    +
    silencedetect,ametadata=mode=print:file=metadata.txt
    +
    +
  • Direct all metadata to a pipe with file descriptor 4. +
    +
    metadata=mode=print:file='pipe\:4'
    +
    +
+ + +

48.14 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 the following options: +

+
+
mode
+

Select the permissions mode. +

+

It accepts the following values: +

+
‘none’
+

Do nothing. This is the default. +

+
‘ro’
+

Set all the output frames read-only. +

+
‘rw’
+

Set all the output frames directly writable. +

+
‘toggle’
+

Make the frame read-only if writable, and writable if read-only. +

+
‘random’
+

Set each output frame read-only or writable randomly. +

+
+ +
+
seed
+

Set the seed for the random mode, 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. +

+
+ +

Note: in case of auto-inserted filter between the permission filter and the +following one, the permission might not be received as expected in that +following filter. Inserting a format or aformat filter before the +perms/aperms filter can avoid this problem. +

+ +

48.15 realtime, arealtime

+ +

Slow down filtering to match real time approximately. +

+

These filters will pause the filtering for a variable amount of time to +match the output rate with the input timestamps. +They are similar to the re option to ffmpeg. +

+

They accept the following options: +

+
+
limit
+

Time limit for the pauses. Any pause longer than that will be considered +a timestamp discontinuity and reset the timer. Default is 2 seconds. +

+
speed
+

Speed factor for processing. The value must be a float larger than zero. +Values larger than 1.0 will result in faster than realtime processing, +smaller will slow processing down. The limit is automatically adapted +accordingly. Default is 1.0. +

+

A processing speed faster than what is possible without these filters cannot +be achieved. +

+
+ + +

48.15.1 Commands

+ +

Both filters supports the all above options as commands. +

+ +

48.16 segment, asegment

+ +

Split single input stream into multiple streams. +

+

This filter does opposite of concat filters. +

+

segment works on video frames, asegment on audio samples. +

+

This filter accepts the following options: +

+
+
timestamps
+

Timestamps of output segments separated by ’|’. The first segment will run +from the beginning of the input stream. The last segment will run until +the end of the input stream +

+
+
frames, samples
+

Exact frame/sample count to split the segments. +

+
+ +

In all cases, prefixing an each segment with ’+’ will make it relative to the +previous segment. +

+ +

48.16.1 Examples

+ +
    +
  • Split input audio stream into three output audio streams, starting at start of input audio stream +and storing that in 1st output audio stream, then following at 60th second and storing than in 2nd +output audio stream, and last after 150th second of input audio stream store in 3rd output audio stream: +
    +
    asegment=timestamps="60|150"
    +
    + +
+ + +

48.17 select, aselect

+ +

Select frames to pass in output. +

+

This filter accepts the following options: +

+
+
expr, e
+

Set expression, which is evaluated for each input frame. +

+

If the expression is evaluated to zero, the frame 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 +ceil(val)-1, assuming that the input index starts from 0. +

+

For example a value of 1.2 corresponds to the output with index +ceil(1.2)-1 = 2-1 = 1, that is the second output. +

+
+
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. +

+
+ +

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the filtered frame, starting from 0. +

+
+
selected_n
+

The (sequential) number of the selected frame, starting from 0. +

+
+
prev_selected_n
+

The sequential number of the last selected frame. It’s NAN if undefined. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the filtered frame, +expressed in TB units. It’s NAN if undefined. +

+
+
t
+

The PTS of the filtered frame, +expressed in seconds. It’s NAN if undefined. +

+
+
prev_pts
+

The PTS of the previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_pts
+

The PTS of the last previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_t
+

The PTS of the last previously selected frame, expressed in seconds. It’s NAN if undefined. +

+
+
start_pts
+

The first PTS in the stream which is not NAN. It remains NAN if not found. +

+
+
start_t
+

The first PTS, in seconds, in the stream which is not NAN. It remains NAN if not found. +

+
+
pict_type (video only)
+

The type of the filtered frame. It can assume one of the following +values: +

+
I
+
P
+
B
+
S
+
SI
+
SP
+
BI
+
+ +
+
interlace_type (video only)
+

The frame interlace type. It can assume one of the following values: +

+
PROGRESSIVE
+

The frame is progressive (not interlaced). +

+
TOPFIRST
+

The frame is top-field-first. +

+
BOTTOMFIRST
+

The frame is bottom-field-first. +

+
+ +
+
consumed_sample_n (audio only)
+

the number of selected samples before the current frame +

+
+
samples_n (audio only)
+

the number of samples in the current frame +

+
+
sample_rate (audio only)
+

the input sample rate +

+
+
key
+

This is 1 if the filtered frame is a key-frame, 0 otherwise. +

+
+
pos
+

the position in the file of the filtered frame, -1 if the information +is not available (e.g. for synthetic video); deprecated, do not use +

+
+
scene (video only)
+

value between 0 and 1 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one (see the example below) +

+
+
concatdec_select
+

The concat demuxer can select only part of a concat input file by setting an +inpoint and an outpoint, but the output packets may not be entirely contained +in the selected interval. By using this variable, it is possible to skip frames +generated by the concat demuxer which are not exactly contained in the selected +interval. +

+

This works by comparing the frame pts against the lavf.concat.start_time +and the lavf.concat.duration packet metadata values which are also +present in the decoded frames. +

+

The concatdec_select variable is -1 if the frame pts is at least +start_time and either the duration metadata is missing or the frame pts is less +than start_time + duration, 0 otherwise, and NaN if the start_time metadata is +missing. +

+

That basically means that an input frame is selected if its pts is within the +interval set by the concat demuxer. +

+
+
iw (video only)
+

Represents the width of the input video frame. +

+
+
ih (video only)
+

Represents the height of the input video frame. +

+
+
view (video only)
+

View ID for multi-view video. +

+
+
+ +

The default value of the select expression is "1". +

+ +

48.17.1 Examples

+ +
    +
  • Select all frames in input: +
    +
    select
    +
    + +

    The example above is the same as: +

    +
    select=1
    +
    + +
  • Skip all frames: +
    +
    select=0
    +
    + +
  • Select only I-frames: +
    +
    select='eq(pict_type\,I)'
    +
    + +
  • Select one frame every 100: +
    +
    select='not(mod(n\,100))'
    +
    + +
  • Select only frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)
    +
    + +
  • Select only I-frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)*eq(pict_type\,I)
    +
    + +
  • Select frames with a minimum distance of 10 seconds: +
    +
    select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
    +
    + +
  • Use aselect to select only audio frames with samples number > 100: +
    +
    aselect='gt(samples_n\,100)'
    +
    + +
  • Create a mosaic of the first scenes: +
    +
    ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
    +
    + +

    Comparing scene against a value between 0.3 and 0.5 is generally a sane +choice. +

    +
  • Send even and odd frames to separate outputs, and compose them: +
    +
    select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
    +
    + +
  • Select useful frames from an ffconcat file which is using inpoints and +outpoints but where the source files are not intra frame only. +
    +
    ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
    +
    +
+ + +

48.18 sendcmd, asendcmd

+ +

Send commands to filters in the filtergraph. +

+

These filters read commands to be sent to other filters in the +filtergraph. +

+

sendcmd must be inserted between two video filters, +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 +with the commands option, or in a file specified by the +filename option. +

+

These filters accept the following options: +

+
commands, c
+

Set the commands to be read and sent to the other filters. +

+
filename, f
+

Set the filename of the commands to be read and sent to the other +filters. +

+
+ + +

48.18.1 Commands syntax

+ +

A commands description consists of a sequence of interval +specifications, comprising a list of commands to be executed when a +particular event related to that interval occurs. The occurring event +is typically the current frame time entering or leaving a given time +interval. +

+

An interval is specified by the following syntax: +

+
START[-END] COMMANDS;
+
+ +

The time interval is specified by the START and END times. +END is optional and defaults to the maximum time. +

+

The current frame time is considered within the specified interval if +it is included in the interval [START, END), that is when +the time is greater or equal to START and is lesser than +END. +

+

COMMANDS consists of a sequence of one or more command +specifications, separated by ",", relating to that interval. The +syntax of a command specification is given by: +

+
[FLAGS] TARGET COMMAND ARG
+
+ +

FLAGS is optional and specifies the type of events relating to +the time interval which enable sending the specified command, and must +be a non-null sequence of identifier flags separated by "+" or "|" and +enclosed between "[" and "]". +

+

The following flags are recognized: +

+
enter
+

The command is sent when the current frame timestamp enters the +specified interval. In other words, the command is sent when the +previous frame timestamp was not in the given interval, and the +current is. +

+
+
leave
+

The command is sent when the current frame timestamp leaves the +specified interval. In other words, the command is sent when the +previous frame timestamp was in the given interval, and the +current is not. +

+
+
expr
+

The command ARG is interpreted as expression and result of +expression is passed as ARG. +

+

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
POS
+

Original position in the file of the frame, or undefined if undefined +for the current frame. Deprecated, do not use. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
N
+

The count of the input frame for video or audio, starting from 0. +

+
+
T
+

The time in seconds of the current frame. +

+
+
TS
+

The start time in seconds of the current command interval. +

+
+
TE
+

The end time in seconds of the current command interval. +

+
+
TI
+

The interpolated time of the current command interval, TI = (T - TS) / (TE - TS). +

+
+
W
+

The video frame width. +

+
+
H
+

The video frame height. +

+
+ +
+
+ +

If FLAGS is not specified, a default value of [enter] is +assumed. +

+

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional list of argument for +the given COMMAND. +

+

Between one interval specification and another, whitespaces, or +sequences of characters starting with # until the end of line, +are ignored and can be used to annotate comments. +

+

A simplified BNF description of the commands specification syntax +follows: +

+
COMMAND_FLAG  ::= "enter" | "leave"
+COMMAND_FLAGS ::= COMMAND_FLAG [(+|"|")COMMAND_FLAG]
+COMMAND       ::= ["[" COMMAND_FLAGS "]"] TARGET COMMAND [ARG]
+COMMANDS      ::= COMMAND [,COMMANDS]
+INTERVAL      ::= START[-END] COMMANDS
+INTERVALS     ::= INTERVAL[;INTERVALS]
+
+ + +

48.18.2 Examples

+ +
    +
  • Specify audio tempo change at second 4: +
    +
    asendcmd=c='4.0 atempo tempo 1.5',atempo
    +
    + +
  • Target a specific filter instance: +
    +
    asendcmd=c='4.0 atempo@my tempo 1.5',atempo@my
    +
    + +
  • Specify a list of drawtext and hue commands in a file. +
    +
    # show text in the interval 5-10
    +5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
    +         [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
    +
    +# desaturate the image in the interval 15-20
    +15.0-20.0 [enter] hue s 0,
    +          [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
    +          [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(25-t)
    +
    + +

    A filtergraph allowing to read and process the above command list +stored in a file test.cmd, can be specified with: +

    +
    sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
    +
    +
+ + +

48.19 setpts, asetpts

+ +

Change the PTS (presentation timestamp) of the input frames. +

+

setpts works on video frames, asetpts on audio frames. +

+

This filter accepts the following options: +

+
+
expr
+

The expression which is evaluated for each frame to construct its timestamp. +

+
+
strip_fps (video only)
+

Boolean option which determines if the original framerate and frame duration +metadata is unset. If set to true, be advised that a sane frame rate should be +explicitly specified if output is sent to a constant frame rate muxer. +Default is false. +

+
+
+ +

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
FRAME_RATE, FR
+

frame rate, only defined for constant frame-rate video +

+
+
PTS
+

The presentation timestamp in input +

+
+
N
+

The count of the input frame for video or the number of consumed samples, +not including the current frame for audio, starting from 0. +

+
+
NB_CONSUMED_SAMPLES
+

The number of consumed samples, not including the current frame (only +audio) +

+
+
NB_SAMPLES, S
+

The number of samples in the current frame (only audio) +

+
+
SAMPLE_RATE, SR
+

The audio sample rate. +

+
+
STARTPTS
+

The PTS of the first frame. +

+
+
STARTT
+

the time in seconds of the first frame +

+
+
INTERLACED
+

State whether the current frame is interlaced. +

+
+
T
+

the time in seconds of the current frame +

+
+
POS
+

original position in the file of the frame, or undefined if undefined +for the current frame; deprecated, do not use +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INT
+

previous input time in seconds +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTT
+

previous output time in seconds +

+
+
RTCTIME
+

The wallclock (RTC) time in microseconds. This is deprecated, use time(0) +instead. +

+
+
RTCSTART
+

The wallclock (RTC) time at the start of the movie in microseconds. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
T_CHANGE
+

Time of the first frame after command was applied or time of the first frame if no commands. +

+
+
+ + +

48.19.1 Examples

+ +
    +
  • Start counting PTS from zero +
    +
    setpts=PTS-STARTPTS
    +
    + +
  • Apply fast motion effect: +
    +
    setpts=0.5*PTS
    +
    + +
  • Apply slow motion effect: +
    +
    setpts=2.0*PTS
    +
    + +
  • Set fixed rate of 25 frames per second: +
    +
    setpts=N/(25*TB)
    +
    + +
  • Apply a random jitter effect of +/-100 TB units: +
    +
    setpts=PTS+randomi(0, -100\,100)
    +
    + +
  • Set fixed rate 25 fps with some jitter: +
    +
    setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
    +
    + +
  • Apply an offset of 10 seconds to the input PTS: +
    +
    setpts=PTS+10/TB
    +
    + +
  • Generate timestamps from a "live source" and rebase onto the current timebase: +
    +
    setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
    +
    + +
  • Generate timestamps by counting samples: +
    +
    asetpts=N/SR/TB
    +
    + +
+ + +

48.19.2 Commands

+ +

Both filters support all above options as commands. +

+ +

48.20 setrange

+ +

Force color range for the output video frame. +

+

The setrange filter marks the color range property for the +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. +

+

The filter accepts the following options: +

+
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property. +

+
+
‘unspecified, unknown’
+

Set the color range as unspecified. +

+
+
‘limited, tv, mpeg’
+

Set the color range as limited. +

+
+
‘full, pc, jpeg’
+

Set the color range as full. +

+
+
+
+ + +

48.21 settb, asettb

+ +

Set the timebase to use for the output frames timestamps. +It is mainly useful for testing timebase configuration. +

+

It accepts the following parameters: +

+
+
expr, tb
+

The expression which is evaluated into the output timebase. +

+
+
+ +

The value for tb is an arithmetic expression representing a +rational. The expression can contain the constants "AVTB" (the default +timebase), "intb" (the input timebase) and "sr" (the sample rate, +audio only). Default value is "intb". +

+ +

48.21.1 Examples

+ +
    +
  • Set the timebase to 1/25: +
    +
    settb=expr=1/25
    +
    + +
  • Set the timebase to 1/10: +
    +
    settb=expr=0.1
    +
    + +
  • Set the timebase to 1001/1000: +
    +
    settb=1+0.001
    +
    + +
  • Set the timebase to 2*intb: +
    +
    settb=2*intb
    +
    + +
  • Set the default timebase value: +
    +
    settb=AVTB
    +
    +
+ + +

48.22 showcqt

+

Convert input audio to a video output representing frequency spectrum +logarithmically using Brown-Puckette constant Q transform algorithm with +direct frequency domain coefficient calculation (but the transform itself +is not really constant Q, instead the Q factor is actually variable/clamped), +with musical tone scale, from E0 to D#10. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify the video size for the output. It must be even. For the syntax of this option, +check the "Video size" section in the ffmpeg-utils manual. +Default value is 1920x1080. +

+
+
fps, rate, r
+

Set the output frame rate. Default value is 25. +

+
+
bar_h
+

Set the bargraph height. It must be even. Default value is -1 which +computes the bargraph height automatically. +

+
+
axis_h
+

Set the axis height. It must be even. Default value is -1 which computes +the axis height automatically. +

+
+
sono_h
+

Set the sonogram height. It must be even. Default value is -1 which +computes the sonogram height automatically. +

+
+
fullhd
+

Set the fullhd resolution. This option is deprecated, use size, s +instead. Default value is 1. +

+
+
sono_v, volume
+

Specify the sonogram volume expression. It can contain variables: +

+
bar_v
+

the bar_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is 16. +

+
+
bar_v, volume2
+

Specify the bargraph volume expression. It can contain variables: +

+
sono_v
+

the sono_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is sono_v. +

+
+
sono_g, gamma
+

Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, +higher gamma makes the spectrum having more range. Default value is 3. +Acceptable range is [1, 7]. +

+
+
bar_g, gamma2
+

Specify the bargraph gamma. Default value is 1. Acceptable range is +[1, 7]. +

+
+
bar_t
+

Specify the bargraph transparency level. Lower value makes the bargraph sharper. +Default value is 1. Acceptable range is [0, 1]. +

+
+
timeclamp, tc
+

Specify the transform timeclamp. At low frequency, there is trade-off between +accuracy in time domain and frequency domain. If timeclamp is lower, +event in time domain is represented more accurately (such as fast bass drum), +otherwise event in frequency domain is represented more accurately +(such as bass guitar). Acceptable range is [0.002, 1]. Default value is 0.17. +

+
+
attack
+

Set attack time in seconds. The default is 0 (disabled). Otherwise, it +limits future samples by applying asymmetric windowing in time domain, useful +when low latency is required. Accepted range is [0, 1]. +

+
+
basefreq
+

Specify the transform base frequency. Default value is 20.01523126408007475, +which is frequency 50 cents below E0. Acceptable range is [10, 100000]. +

+
+
endfreq
+

Specify the transform end frequency. Default value is 20495.59681441799654, +which is frequency 50 cents above D#10. Acceptable range is [10, 100000]. +

+
+
coeffclamp
+

This option is deprecated and ignored. +

+
+
tlength
+

Specify the transform length in time domain. Use this option to control accuracy +trade-off between time domain and frequency domain at every frequency sample. +It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option. +

+
+

Default value is 384*tc/(384+tc*f). +

+
+
count
+

Specify the transform count for every video frame. Default value is 6. +Acceptable range is [1, 30]. +

+
+
fcount
+

Specify the transform count for every single pixel. Default value is 0, +which makes it computed automatically. Acceptable range is [0, 10]. +

+
+
fontfile
+

Specify font file for use with freetype to draw the axis. If not specified, +use embedded font. Note that drawing with font file or embedded font is not +implemented with custom basefreq and endfreq, use axisfile +option instead. +

+
+
font
+

Specify fontconfig pattern. This has lower priority than fontfile. The +: in the pattern may be replaced by | to avoid unnecessary +escaping. +

+
+
fontcolor
+

Specify font color expression. This is arithmetic expression that should return +integer value 0xRRGGBB. It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
midi(f)
+

midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) +

+
r(x), g(x), b(x)
+

red, green, and blue value of intensity x. +

+
+

Default value is st(0, (midi(f)-59.5)/12); +st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); +r(1-ld(1)) + b(ld(1)). +

+
+
axisfile
+

Specify image file to draw the axis. This option override fontfile and +fontcolor option. +

+
+
axis, text
+

Enable/disable drawing text to the axis. If it is set to 0, drawing to +the axis is disabled, ignoring fontfile and axisfile option. +Default value is 1. +

+
+
csp
+

Set colorspace. The accepted values are: +

+
‘unspecified’
+

Unspecified (default) +

+
+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
cscheme
+

Set spectrogram color scheme. This is list of floating point values with format +left_r|left_g|left_b|right_r|right_g|right_b. +The default is 1|0.5|0|0|0.5|1. +

+
+
+ + +

48.22.1 Examples

+ +
    +
  • Playing audio while showing the spectrum: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with frame rate 30 fps: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
    +
    + +
  • Playing at 1280x720: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
    +
    + +
  • Disable sonogram display: +
    +
    sono_h=0
    +
    + +
  • A1 and its harmonics: A1, A2, (near)E3, A3: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with more accuracy in frequency domain: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
    +
    + +
  • Custom volume: +
    +
    bar_v=10:sono_v=bar_v*a_weighting(f)
    +
    + +
  • Custom gamma, now spectrum is linear to the amplitude. +
    +
    bar_g=2:sono_g=2
    +
    + +
  • Custom tlength equation: +
    +
    tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'
    +
    + +
  • Custom fontcolor and fontfile, C-note is colored green, others are colored blue: +
    +
    fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
    +
    + +
  • Custom font using fontconfig: +
    +
    font='Courier New,Monospace,mono|bold'
    +
    + +
  • Custom frequency range with custom axis using image file: +
    +
    axisfile=myaxis.png:basefreq=40:endfreq=10000
    +
    +
+ + +

48.23 showcwt

+ +

Convert input audio to video output representing frequency spectrum +using Continuous Wavelet Transform and Morlet wavelet. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
scale
+

Set the frequency scale used. Allowed values are: +

+
+
linear
+
log
+
bark
+
mel
+
erbs
+
sqrt
+
cbrt
+
qdrt
+
fm
+
+

Default value is linear. +

+
+
iscale
+

Set the intensity scale used. Allowed values are: +

+
+
linear
+
log
+
sqrt
+
cbrt
+
qdrt
+
+

Default value is log. +

+
+
min
+

Set the minimum frequency that will be used in output. +Default is 20 Hz. +

+
+
max
+

Set the maximum frequency that will be used in output. +Default is 20000 Hz. The real frequency upper limit +depends on input audio’s sample rate and such will be enforced +on this value when it is set to value greater than Nyquist frequency. +

+
+
imin
+

Set the minimum intensity that will be used in output. +

+
+
imax
+

Set the maximum intensity that will be used in output. +

+
+
logb
+

Set the logarithmic basis for brightness strength when +mapping calculated magnitude values to pixel values. +Allowed range is from 0 to 1. +Default value is 0.0001. +

+
+
deviation
+

Set the frequency deviation. +Lower values than 1 are more frequency oriented, +while higher values than 1 are more time oriented. +Allowed range is from 0 to 10. +Default value is 1. +

+
+
pps
+

Set the number of pixel output per each second in one row. +Allowed range is from 1 to 1024. +Default value is 64. +

+
+
mode
+

Set the output visual mode. Allowed values are: +

+
+
magnitude
+

Show magnitude. +

+
phase
+

Show only phase. +

+
magphase
+

Show combination of magnitude and phase. +Magnitude is mapped to brightness and phase to color. +

+
channel
+

Show unique color per channel magnitude. +

+
stereo
+

Show unique color per stereo difference. +

+
+ +

Default value is magnitude. +

+
+
slide
+

Set the output slide method. Allowed values are: +

+
+
replace
+
scroll
+
frame
+
+ +
+
direction
+

Set the direction method for output slide method. Allowed values are: +

+
+
lr
+

Direction from left to right. +

+
rl
+

Direction from right to left. +

+
ud
+

Direction from up to down. +

+
du
+

Direction from down to up. +

+
+ +
+
bar
+

Set the ratio of bargraph display to display size. Default is 0. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+ + +

48.24 showfreqs

+ +

Convert input audio to video output representing the audio power spectrum. +Audio amplitude is on Y-axis while frequency is on X-axis. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify size of video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +Default is 1024x512. +

+
+
rate, r
+

Set video rate. Default is 25. +

+
+
mode
+

Set display mode. +This set how each frequency bin will be represented. +

+

It accepts the following values: +

+
‘line’
+
‘bar’
+
‘dot’
+
+

Default is bar. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘sqrt’
+

Square root scale. +

+
+
‘cbrt’
+

Cubic root scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+

Default is log. +

+
+
fscale
+

Set frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+
‘rlog’
+

Reverse logarithmic scale. +

+
+

Default is lin. +

+
+
win_size
+

Set window size. Allowed range is from 16 to 65536. +

+

Default is 2048 +

+
+
win_func
+

Set windowing function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hanning. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
averaging
+

Set time averaging. Setting this to 0 will display current maximal peaks. +Default is 1, which means time averaging is disabled. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channel frequencies. Unrecognized or missing colors will be replaced +by white color. +

+
+
cmode
+

Set channel display mode. +

+

It accepts the following values: +

+
‘combined’
+
‘separate’
+
+

Default is combined. +

+
+
minamp
+

Set minimum amplitude used in log amplitude scaler. +

+
+
data
+

Set data display mode. +

+

It accepts the following values: +

+
‘magnitude’
+
‘phase’
+
‘delay’
+
+

Default is magnitude. +

+
+
channels
+

Set channels to use when processing audio. By default all are processed. +

+
+ + +

48.25 showspatial

+ +

Convert stereo input audio to a video output, representing the spatial relationship +between two channels. +

+

The filter accepts the following options: +

+
+
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 512x512. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
rate, r
+

Set output framerate. +

+
+ + +

48.26 showspectrum

+ +

Convert input audio to a video output, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
slide
+

Specify how the spectrum should slide along the window. +

+

It accepts the following values: +

+
‘replace’
+

the samples start again on the left when they reach the right +

+
‘scroll’
+

the samples scroll from right to left +

+
‘fullframe’
+

frames are only produced when the samples reach the right +

+
‘rscroll’
+

the samples scroll from left to right +

+
‘lreplace’
+

the samples start again on the right when they reach the left +

+
+ +

Default value is replace. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+ +

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+ +

Default value is ‘channel’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+ +

Default value is ‘sqrt’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
overlap
+

Set ratio of overlap window. Default value is 0. +When value is 1 overlap is set to recommended size for specific +window function currently used. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
data
+

Set which data to display. Can be magnitude, default or phase, +or unwrapped phase: uphase. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
fps
+

Set upper frame rate limit. Default is auto, unlimited. +

+
+
legend
+

Draw time and frequency axes and legends. Default is disabled. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ +

The usage is very similar to the showwaves filter; see the examples in that +section. +

+ +

48.26.1 Examples

+ +
    +
  • Large window with logarithmic color scaling: +
    +
    showspectrum=s=1280x480:scale=log
    +
    + +
  • Complete example for a colored and sliding spectrum per channel using ffplay: +
    +
    ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
    +             [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
    +
    +
+ + +

48.27 showspectrumpic

+ +

Convert input audio to a single video frame, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 4096x2048. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+

Default value is ‘intensity’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+

Default value is ‘log’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
legend
+

Draw time and frequency axes and legends. Default is enabled. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ + +

48.27.1 Examples

+ +
    +
  • Extract an audio spectrogram of a whole audio track +in a 1024x1024 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
    +
    +
+ + +

48.28 showvolume

+ +

Convert input audio volume to a video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set video rate. +

+
+
b
+

Set border width, allowed range is [0, 5]. Default is 1. +

+
+
w
+

Set channel width, allowed range is [80, 8192]. Default is 400. +

+
+
h
+

Set channel height, allowed range is [1, 900]. Default is 20. +

+
+
f
+

Set fade, allowed range is [0, 1]. Default is 0.95. +

+
+
c
+

Set volume color expression. +

+

The expression can use the following variables: +

+
+
VOLUME
+

Current max volume of channel in dB. +

+
+
PEAK
+

Current peak. +

+
+
CHANNEL
+

Current channel number, starting from 0. +

+
+ +
+
t
+

If set, displays channel names. Default is enabled. +

+
+
v
+

If set, displays volume values. Default is enabled. +

+
+
o
+

Set orientation, can be horizontal: h or vertical: v, +default is h. +

+
+
s
+

Set step size, allowed range is [0, 5]. Default is 0, which means +step is disabled. +

+
+
p
+

Set background opacity, allowed range is [0, 1]. Default is 0. +

+
+
m
+

Set metering mode, can be peak: p or rms: r, +default is p. +

+
+
ds
+

Set display scale, can be linear: lin or log: log, +default is lin. +

+
+
dm
+

In second. +If set to > 0., display a line for the max level +in the previous seconds. +default is disabled: 0. +

+
+
dmc
+

The color of the max line. Use when dm option is set to > 0. +default is: orange +

+
+ + +

48.29 showwaves

+ +

Convert input audio to a video output, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
mode
+

Set display mode. +

+

Available values are: +

+
‘point’
+

Draw a point for each sample. +

+
+
‘line’
+

Draw a vertical line for each sample. +

+
+
‘p2p’
+

Draw a point for each sample and a line between them. +

+
+
‘cline’
+

Draw a centered vertical line for each sample. +

+
+ +

Default value is point. +

+
+
n
+

Set the number of samples which are printed on the same column. A +larger value will decrease the frame rate. Must be a positive +integer. This option can be set only if the value for rate +is not explicitly specified. +

+
+
rate, r
+

Set the (approximate) output frame rate. This is done by setting the +option n. Default value is "25". +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. This is mostly useful to set for high n. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+ + +

48.29.1 Examples

+ +
    +
  • Output the input file audio and the corresponding video representation +at the same time: +
    +
    amovie=a.mp3,asplit[out0],showwaves[out1]
    +
    + +
  • Create a synthetic signal and show it with showwaves, forcing a +frame rate of 30 frames per second: +
    +
    aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
    +
    +
+ + +

48.30 showwavespic

+ +

Convert input audio to a single video frame, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+
filter
+

Set the filter mode. +

+

Available values are: +

+
‘average’
+

Use average samples values for each drawn sample. +

+
+
‘peak’
+

Use peak samples values for each drawn sample. +

+
+ +

Default value is average. +

+
+ + +

48.30.1 Examples

+ +
    +
  • Extract a channel split representation of the wave form of a whole audio track +in a 1024x800 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
    +
    +
+ + +

48.31 sidedata, asidedata

+ +

Delete frame side data, or select frames based on it. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

Select every frame with side data of type. +

+
+
‘delete’
+

Delete side data of type. If type is not set, delete all side +data in the frame. +

+
+
+ +
+
type
+

Set side data type used with all modes. Must be set for select mode. +

+

Possible values are: +

+
+
‘PANSCAN’
+
‘A53_CC’
+
‘STEREO3D’
+
‘MATRIXENCODING’
+
‘DOWNMIX_INFO’
+
‘REPLAYGAIN’
+
‘DISPLAYMATRIX’
+
‘AFD’
+
‘MOTION_VECTORS’
+
‘SKIP_SAMPLES’
+
‘AUDIO_SERVICE_TYPE’
+
‘MASTERING_DISPLAY_METADATA’
+
‘GOP_TIMECODE’
+
‘SPHERICAL’
+
‘CONTENT_LIGHT_LEVEL’
+
‘ICC_PROFILE’
+
‘S12M_TIMECODE’
+
‘DYNAMIC_HDR_PLUS’
+
‘REGIONS_OF_INTEREST’
+
‘VIDEO_ENC_PARAMS’
+
‘SEI_UNREGISTERED’
+
‘FILM_GRAIN_PARAMS’
+
‘DETECTION_BOUNDING_BOXES’
+
‘DETECTION_BBOXES’
+
‘DOVI_RPU_BUFFER’
+
‘DOVI_METADATA’
+
‘DYNAMIC_HDR_VIVID’
+
‘AMBIENT_VIEWING_ENVIRONMENT’
+
‘VIDEO_HINT’
+
+ +
+
+ + +

48.32 spectrumsynth

+ +

Synthesize audio from 2 input video spectrums, first input stream represents +magnitude across time and second represents phase across time. +The filter will transform from frequency domain as displayed in videos back +to time domain as presented in audio output. +

+

This filter is primarily created for reversing processed showspectrum +filter outputs, but can synthesize sound from other spectrograms too. +But in such case results are going to be poor if the phase data is not +available, because in such cases phase data need to be recreated, usually +it’s just recreated from random noise. +For best results use gray only output (channel color mode in +showspectrum filter) and log scale for magnitude video and +lin scale for phase video. To produce phase, for 2nd video, use +data option. Inputs videos should generally use fullframe +slide mode as that saves resources needed for decoding video. +

+

The filter accepts the following options: +

+
+
sample_rate
+

Specify sample rate of output audio, the sample rate of audio from which +spectrum was generated may differ. +

+
+
channels
+

Set number of channels represented in input video spectrums. +

+
+
scale
+

Set scale which was used when generating magnitude input spectrum. +Can be lin or log. Default is log. +

+
+
slide
+

Set slide which was used when generating inputs spectrums. +Can be replace, scroll, fullframe or rscroll. +Default is fullframe. +

+
+
win_func
+

Set window function used for resynthesis. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
orientation
+

Set orientation of input videos. Can be vertical or horizontal. +Default is vertical. +

+
+ + +

48.32.1 Examples

+ +
    +
  • First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, +then resynthesize videos back to audio with spectrumsynth: +
    +
    ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
    +ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
    +ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
    +
    +
+ + +

48.33 split, asplit

+ +

Split input into several identical outputs. +

+

asplit works with audio input, split with video. +

+

The filter accepts a single parameter which specifies the number of outputs. If +unspecified, it defaults to 2. +

+ +

48.33.1 Examples

+ +
    +
  • Create two separate outputs from the same input: +
    +
    [in] split [out0][out1]
    +
    + +
  • To create 3 or more outputs, you need to specify the number of +outputs, like in: +
    +
    [in] asplit=3 [out0][out1][out2]
    +
    + +
  • Create two separate outputs from the same input, one cropped and +one padded: +
    +
    [in] split [splitout1][splitout2];
    +[splitout1] crop=100:100:0:0    [cropout];
    +[splitout2] pad=200:200:100:100 [padout];
    +
    + +
  • Create 5 copies of the input audio with ffmpeg: +
    +
    ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
    +
    +
+ + +

48.34 zmq, azmq

+ +

Receive commands sent through a libzmq client, and forward them to +filters in the filtergraph. +

+

zmq and azmq work as a pass-through filters. zmq +must be inserted between two video filters, azmq between two +audio filters. Both are capable to send messages to any filter type. +

+

To enable these filters you need to install the libzmq library and +headers and configure FFmpeg with --enable-libzmq. +

+

For more information about libzmq see: +http://www.zeromq.org/ +

+

The zmq and azmq filters work as a libzmq server, which +receives messages sent through a network interface defined by the +bind_address (or the abbreviation "b") option. +Default value of this option is tcp://localhost:5555. You may +want to alter this value to your needs, but do not forget to escape any +’:’ signs (see filtergraph escaping). +

+

The received message must be in the form: +

+
TARGET COMMAND [ARG]
+
+ +

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. The default +filter instance name uses the pattern ‘Parsed_<filter_name>_<index>’, +but you can override this by using the ‘filter_name@id’ syntax +(see Filtergraph syntax). +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional argument list for the +given 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: +

+
ERROR_CODE ERROR_REASON
+MESSAGE
+
+ +

MESSAGE is optional. +

+ +

48.34.1 Examples

+ +

Look at 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 ffplay. +In this example the last overlay filter has an instance name. All other +filters will have default instance names. +

+
+
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@my=x=100 "
+
+ +

To change the color of the left side of the video, the following +command can be used: +

+
echo Parsed_color_0 c yellow | tools/zmqsend
+
+ +

To change the right side: +

+
echo Parsed_color_1 c pink | tools/zmqsend
+
+ +

To change the position of the right side: +

+
echo overlay@my x 150 | tools/zmqsend
+
+ + + + +

49 Multimedia Sources

+ +

Below is a description of the currently available multimedia sources. +

+ +

49.1 amovie

+ +

This is the same as movie source, except it selects an audio +stream by default. +

+ +

49.2 avsynctest

+

Generate an Audio/Video Sync Test. +

+

Generated stream periodically shows flash video frame and emits beep in audio. +Useful to inspect A/V sync issues. +

+

It accepts the following options: +

+
+
size, s
+

Set output video size. Default value is hd720. +

+
+
framerate, fr
+

Set output video frame rate. Default value is 30. +

+
+
samplerate, sr
+

Set output audio sample rate. Default value is 44100. +

+
+
amplitude, a
+

Set output audio beep amplitude. Default value is 0.7. +

+
+
period, p
+

Set output audio beep period in seconds. Default value is 3. +

+
+
delay, dl
+

Set output video flash delay in number of frames. Default value is 0. +

+
+
cycle, c
+

Enable cycling of video delays, by default is disabled. +

+
+
duration, d
+

Set stream output duration. By default duration is unlimited. +

+
+
fg, bg, ag
+

Set foreground/background/additional color. +

+
+ + +

49.2.1 Commands

+ +

This source supports the some above options as commands. +

+ +

49.3 movie

+ +

Read audio and/or video stream(s) from a movie container. +

+

It accepts the following parameters: +

+
+
filename
+

The name of the resource to read (not necessarily a file; it can also be a +device or a stream accessed through some protocol). +

+
+
format_name, f
+

Specifies the format assumed for the movie to read, and can be either +the name of a container or an input device. If not specified, the +format is guessed from movie_name or by probing. +

+
+
seek_point, sp
+

Specifies the seek point in seconds. The frames will be output +starting from this seek point. The parameter is evaluated with +av_strtod, so the numerical value may be suffixed by an IS +postfix. The default value is "0". +

+
+
streams, s
+

Specifies the streams to read. Several streams can be specified, +separated by "+". The source will then have as many outputs, in the +same order. The syntax is explained in the "Stream specifiers" +section in the ffmpeg manual. Two special names, "dv" and "da" specify +respectively the default (best suited) video and audio stream. Default +is "dv", or "da" if the filter is called as "amovie". +

+
+
stream_index, si
+

Specifies the index of the video stream to read. If the value is -1, +the most suitable video stream will be automatically selected. The default +value is "-1". Deprecated. If the filter is called "amovie", it will select +audio instead of video. +

+
+
loop
+

Specifies how many times to read the stream in sequence. +If the value is 0, the stream will be looped infinitely. +Default value is "1". +

+

Note that when the movie is looped the source timestamps are not +changed, so it will generate non monotonically increasing timestamps. +

+
+
discontinuity
+

Specifies the time difference between frames above which the point is +considered a timestamp discontinuity which is removed by adjusting the later +timestamps. +

+
+
dec_threads
+

Specifies the number of threads for decoding +

+
+
format_opts
+

Specify format options for the opened file. Format options can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to add protocol_whitelist and protocol_blacklist options: +

+
ffplay -f lavfi
+"movie=filename='1.sdp':format_opts='protocol_whitelist=file,rtp,udp\:protocol_blacklist=http'"
+
+
+
+ +

It allows overlaying a second video on top of the main input of +a filtergraph, as shown in this graph: +

+
input -----------> deltapts0 --> overlay --> output
+                                    ^
+                                    |
+movie --> scale--> deltapts1 -------+
+
+ +

49.3.1 Examples

+ +
    +
  • Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it +on top of the input labelled "in": +
    +
    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]
    +
    + +
  • Read from a video4linux2 device, and overlay it on top of the input +labelled "in": +
    +
    movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
    +[in] setpts=PTS-STARTPTS [main];
    +[main][over] overlay=16:16 [out]
    +
    + +
  • Read the first video stream and the audio stream with id 0x81 from +dvd.vob; the video is connected to the pad named "video" and the audio is +connected to the pad named "audio": +
    +
    movie=dvd.vob:s=v:0+#0x81 [video] [audio]
    +
    +
+ + +

49.3.2 Commands

+ +

Both movie and amovie support the following commands: +

+
seek
+

Perform seek using "av_seek_frame". +The syntax is: seek stream_index|timestamp|flags +

    +
  • stream_index: If stream_index is -1, a default +stream is selected, and timestamp is automatically converted +from AV_TIME_BASE units to the stream specific time_base. +
  • timestamp: Timestamp in AVStream.time_base units +or, if no stream is specified, in AV_TIME_BASE units. +
  • flags: Flags which select direction and seeking mode. +
+ +
+
get_duration
+

Get movie duration in AV_TIME_BASE units. +

+
+
+ + +

50 External libraries

+ +

FFmpeg can be hooked up with a number of external libraries to add support +for more formats. None of them are used by default, their use has to be +explicitly requested by passing the appropriate flags to +./configure. +

+ +

50.1 Alliance for Open Media (AOM)

+ +

FFmpeg can make use of the AOM library for AV1 decoding and encoding. +

+

Go to http://aomedia.org/ and follow the instructions for +installing the library. Then pass --enable-libaom to configure to +enable it. +

+ +

50.2 AMD AMF/VCE

+ +

FFmpeg can use the AMD Advanced Media Framework library +for accelerated H.264 and HEVC(only windows) encoding on hardware with Video Coding Engine (VCE). +

+

To enable support you must obtain the AMF framework header files(version 1.4.9+) from +https://github.com/GPUOpen-LibrariesAndSDKs/AMF.git. +

+

Create an AMF/ directory in the system include path. +Copy the contents of AMF/amf/public/include/ into that directory. +Then configure FFmpeg with --enable-amf. +

+

Initialization of amf encoder occurs in this order: +1) trying to initialize through dx11(only windows) +2) trying to initialize through dx9(only windows) +3) trying to initialize through vulkan +

+

To use h.264(AMD VCE) encoder on linux amdgru-pro version 19.20+ and amf-amdgpu-pro +package(amdgru-pro contains, but does not install automatically) are required. +

+

This driver can be installed using amdgpu-pro-install script in official amd driver archive. +

+ +

50.3 AviSynth

+ +

FFmpeg can read AviSynth scripts as input. To enable support, pass +--enable-avisynth to configure after installing the headers +provided by AviSynth+. +AviSynth+ can be configured to install only the headers by either +passing -DHEADERS_ONLY:bool=on to the normal CMake-based build +system, or by using the supplied GNUmakefile. +

+

For Windows, supported AviSynth variants are +AviSynth 2.6 RC1 or higher for 32-bit builds and +AviSynth+ r1718 or higher for 32-bit and 64-bit builds. +

+

For Linux, macOS, and BSD, the only supported AviSynth variant is +AviSynth+, starting with version 3.5. +

+
+

In 2016, AviSynth+ added support for building with GCC. However, due to +the eccentricities of Windows’ calling conventions, 32-bit GCC builds +of AviSynth+ are not compatible with typical 32-bit builds of FFmpeg. +

+

By default, FFmpeg assumes compatibility with 32-bit MSVC builds of +AviSynth+ since that is the most widely-used and entrenched build +configuration. Users can override this and enable support for 32-bit +GCC builds of AviSynth+ by passing -DAVSC_WIN32_GCC32 to +--extra-cflags when configuring FFmpeg. +

+

64-bit builds of FFmpeg are not affected, and can use either MSVC or +GCC builds of AviSynth+ without any special flags. +

+
+

AviSynth(+) is loaded dynamically. Distributors can build FFmpeg +with --enable-avisynth, and the binaries will work regardless +of the end user having AviSynth installed. If/when an end user +would like to use AviSynth scripts, then they can install AviSynth(+) +and FFmpeg will be able to find and use it to open scripts. +

+ +

50.4 Chromaprint

+ +

FFmpeg can make use of the Chromaprint library for generating audio fingerprints. +Pass --enable-chromaprint to configure to +enable it. See https://acoustid.org/chromaprint. +

+ +

50.5 codec2

+ +

FFmpeg can make use of the codec2 library for codec2 decoding and encoding. +There is currently no native decoder, so libcodec2 must be used for decoding. +

+

Go to http://freedv.org/, download "Codec 2 source archive". +Build and install using CMake. Debian users can install the libcodec2-dev package instead. +Once libcodec2 is installed you can pass --enable-libcodec2 to configure to enable it. +

+

The easiest way to use codec2 is with .c2 files, since they contain the mode information required for decoding. +To encode such a file, use a .c2 file extension and give the libcodec2 encoder the -mode option: +ffmpeg -i input.wav -mode 700C output.c2. +Playback is as simple as ffplay output.c2. +For a list of supported modes, run ffmpeg -h encoder=libcodec2. +Raw codec2 files are also supported. +To make sense of them the mode in use needs to be specified as a format option: +ffmpeg -f codec2raw -mode 1300 -i input.raw output.wav. +

+ +

50.6 dav1d

+ +

FFmpeg can make use of the dav1d library for AV1 video decoding. +

+

Go to https://code.videolan.org/videolan/dav1d and follow the instructions for +installing the library. Then pass --enable-libdav1d to configure to enable it. +

+ +

50.7 davs2

+ +

FFmpeg can make use of the davs2 library for AVS2-P2/IEEE1857.4 video decoding. +

+

Go to https://github.com/pkuvcl/davs2 and follow the instructions for +installing the library. Then pass --enable-libdavs2 to configure to +enable it. +

+
+

libdavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

50.8 uavs3d

+ +

FFmpeg can make use of the uavs3d library for AVS3-P2/IEEE1857.10 video decoding. +

+

Go to https://github.com/uavs3/uavs3d and follow the instructions for +installing the library. Then pass --enable-libuavs3d to configure to +enable it. +

+ +

50.9 Game Music Emu

+ +

FFmpeg can make use of the Game Music Emu library to read audio from supported video game +music file formats. Pass --enable-libgme to configure to +enable it. See https://bitbucket.org/mpyne/game-music-emu/overview. +

+ +

50.10 Intel QuickSync Video

+ +

FFmpeg can use Intel QuickSync Video (QSV) for accelerated decoding and encoding +of multiple codecs. To use QSV, FFmpeg must be linked against the libmfx +dispatcher, which loads the actual decoding libraries. +

+

The dispatcher is open source and can be downloaded from +https://github.com/lu-zero/mfx_dispatch.git. FFmpeg needs to be configured +with the --enable-libmfx option and pkg-config needs to be able to +locate the dispatcher’s .pc files. +

+ +

50.11 Kvazaar

+ +

FFmpeg can make use of the Kvazaar library for HEVC encoding. +

+

Go to https://github.com/ultravideo/kvazaar and follow the +instructions for installing the library. Then pass +--enable-libkvazaar to configure to enable it. +

+ +

50.12 LAME

+ +

FFmpeg can make use of the LAME library for MP3 encoding. +

+

Go to http://lame.sourceforge.net/ and follow the +instructions for installing the library. +Then pass --enable-libmp3lame to configure to enable it. +

+ +

50.13 LCEVCdec

+ +

FFmpeg can make use of the liblcevc_dec library for LCEVC enhancement layer +decoding on supported bitstreams. +

+

Go to https://github.com/v-novaltd/LCEVCdec and follow the instructions +for installing the library. Then pass --enable-liblcevc-dec to configure to +enable it. +

+
+

LCEVCdec is under the BSD-3-Clause-Clear License. +

+ +

50.14 libilbc

+ +

iLBC is a narrowband speech codec that has been made freely available +by Google as part of the WebRTC project. libilbc is a packaging friendly +copy of the iLBC codec. FFmpeg can make use of the libilbc library for +iLBC decoding and encoding. +

+

Go to https://github.com/TimothyGu/libilbc and follow the instructions for +installing the library. Then pass --enable-libilbc to configure to +enable it. +

+ +

50.15 libjxl

+ +

JPEG XL is an image format intended to fully replace legacy JPEG for an extended +period of life. See https://jpegxl.info/ for more information, and see +https://github.com/libjxl/libjxl for the library source. You can pass +--enable-libjxl to configure in order enable the libjxl wrapper. +

+ +

50.16 libvpx

+ +

FFmpeg can make use of the libvpx library for VP8/VP9 decoding and encoding. +

+

Go to http://www.webmproject.org/ and follow the instructions for +installing the library. Then pass --enable-libvpx to configure to +enable it. +

+ +

50.17 ModPlug

+ +

FFmpeg can make use of this library, originating in Modplug-XMMS, to read from MOD-like music files. +See https://github.com/Konstanty/libmodplug. Pass --enable-libmodplug to configure to +enable it. +

+ +

50.18 OpenCORE, VisualOn, and Fraunhofer libraries

+ +

Spun off Google Android sources, OpenCore, VisualOn and Fraunhofer +libraries provide encoders for a number of audio codecs. +

+
+

OpenCORE and VisualOn libraries are under the Apache License 2.0 +(see http://www.apache.org/licenses/LICENSE-2.0 for details), which is +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) by passing --enable-version3 to configure in +order to use it. +

+

The license of the Fraunhofer AAC library is incompatible with the GPL. +Therefore, for GPL builds, you have to pass --enable-nonfree to +configure in order to use it. To the best of our knowledge, it is +compatible with the LGPL. +

+ +

50.18.1 OpenCORE AMR

+ +

FFmpeg can make use of the OpenCORE libraries for AMR-NB +decoding/encoding and AMR-WB decoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the libraries. +Then pass --enable-libopencore-amrnb and/or +--enable-libopencore-amrwb to configure to enable them. +

+ +

50.18.2 VisualOn AMR-WB encoder library

+ +

FFmpeg can make use of the VisualOn AMR-WBenc library for AMR-WB encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libvo-amrwbenc to configure to enable it. +

+ +

50.18.3 Fraunhofer AAC library

+ +

FFmpeg can make use of the Fraunhofer AAC library for AAC decoding & encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libfdk-aac to configure to enable it. +

+ +

50.18.4 Fraunhofer MPEG-H 3D Audio decoder library

+ +

FFmpeg can make use of the Fraunhofer MPEG-H decoder library for MPEG-H 3DA decoding. +

+

Go to https://github.com/Fraunhofer-IIS/mpeghdec and follow the +instructions for installing the library. +Then pass --enable-libmpeghdec --enable-nonfree to configure to enable it. +

+ +

50.18.5 LC3 library

+ +

FFmpeg can make use of the Google LC3 library for LC3 decoding & encoding. +

+

Go to https://github.com/google/liblc3/ and follow the instructions for +installing the library. +Then pass --enable-liblc3 to configure to enable it. +

+ +

50.19 OpenH264

+ +

FFmpeg can make use of the OpenH264 library for H.264 decoding and encoding. +

+

Go to http://www.openh264.org/ and follow the instructions for +installing the library. Then pass --enable-libopenh264 to configure to +enable it. +

+

For decoding, this library is much more limited than the built-in decoder +in libavcodec; currently, this library lacks support for decoding B-frames +and some other main/high profile features. (It currently only supports +constrained baseline profile and CABAC.) Using it is mostly useful for +testing and for taking advantage of Cisco’s patent portfolio license +(http://www.openh264.org/BINARY_LICENSE.txt). +

+ +

50.20 OpenJPEG

+ +

FFmpeg can use the OpenJPEG libraries for decoding/encoding J2K videos. Go to +http://www.openjpeg.org/ to get the libraries and follow the installation +instructions. To enable using OpenJPEG in FFmpeg, pass --enable-libopenjpeg to +./configure. +

+ +

50.21 rav1e

+ +

FFmpeg can make use of rav1e (Rust AV1 Encoder) via its C bindings to encode videos. +Go to https://github.com/xiph/rav1e/ and follow the instructions to build +the C library. To enable using rav1e in FFmpeg, pass --enable-librav1e +to ./configure. +

+ +

50.22 SVT-AV1

+ +

FFmpeg can make use of the Scalable Video Technology for AV1 library for AV1 encoding. +

+

Go to https://gitlab.com/AOMediaCodec/SVT-AV1/ and follow the instructions +for installing the library. Then pass --enable-libsvtav1 to configure to +enable it. +

+ +

50.23 SVT-JPEG-XS

+ +

FFmpeg can make use of the Scalable Video Technology for JPEG-XS library for JPEG-XS +decoding and encoding. +

+

Go to https://github.com/OpenVisualCloud/SVT-JPEG-XS and follow the instructions +for installing the library. Then pass --enable-libsvtjpegxs to configure to +enable it. +

+ +

50.24 TwoLAME

+ +

FFmpeg can make use of the TwoLAME library for MP2 encoding. +

+

Go to http://www.twolame.org/ and follow the +instructions for installing the library. +Then pass --enable-libtwolame to configure to enable it. +

+ +

50.25 VapourSynth

+ +

FFmpeg can read VapourSynth scripts as input. To enable support, pass +--enable-vapoursynth to configure. Vapoursynth is detected via +pkg-config. Versions 42 or greater supported. +See http://www.vapoursynth.com/. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+ +

50.26 x264

+ +

FFmpeg can make use of the x264 library for H.264 encoding. +

+

Go to http://www.videolan.org/developers/x264.html and follow the +instructions for installing the library. Then pass --enable-libx264 to +configure to enable it. +

+
+

x264 is under the GNU Public License Version 2 or later +(see 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. +

+ +

50.27 x265

+ +

FFmpeg can make use of the x265 library for HEVC encoding. +

+

Go to http://x265.org/developers.html and follow the instructions +for installing the library. Then pass --enable-libx265 to configure +to enable it. +

+
+

x265 is under the GNU Public License Version 2 or later +(see 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. +

+ +

50.28 xavs

+ +

FFmpeg can make use of the xavs library for AVS encoding. +

+

Go to http://xavs.sf.net/ and follow the instructions for +installing the library. Then pass --enable-libxavs to configure to +enable it. +

+ +

50.29 xavs2

+ +

FFmpeg can make use of the xavs2 library for AVS2-P2/IEEE1857.4 video encoding. +

+

Go to https://github.com/pkuvcl/xavs2 and follow the instructions for +installing the library. Then pass --enable-libxavs2 to configure to +enable it. +

+
+

libxavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

50.30 eXtra-fast Essential Video Encoder (XEVE)

+ +

FFmpeg can make use of the XEVE library for EVC video encoding. +

+

Go to https://github.com/mpeg5/xeve and follow the instructions for +installing the XEVE library. Then pass --enable-libxeve to configure to +enable it. +

+ +

50.31 eXtra-fast Essential Video Decoder (XEVD)

+ +

FFmpeg can make use of the XEVD library for EVC video decoding. +

+

Go to https://github.com/mpeg5/xevd and follow the instructions for +installing the XEVD library. Then pass --enable-libxevd to configure to +enable it. +

+ +

50.32 ZVBI

+ +

ZVBI is a VBI decoding library which can be used by FFmpeg to decode DVB +teletext pages and DVB teletext subtitles. +

+

Go to http://sourceforge.net/projects/zapping/ and follow the instructions for +installing the library. Then pass --enable-libzvbi to configure to +enable it. +

+ +

51 Supported File Formats, Codecs or Features

+ +

You can use the -formats and -codecs options to have an exhaustive list. +

+ +

51.1 File Formats

+ +

FFmpeg supports the following file formats through the libavformat +library: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
3dostrX
4xmX4X Technologies format, used in some games.
8088flex TMVX
AAXXAudible Enhanced Audio format, used in audiobooks.
AAXAudible Format 2, 3, and 4, used in audiobooks.
ACT VoiceXcontains G.729 audio
Adobe FilmstripXX
Audio IFF (AIFF)XX
American Laser Games MMXMultimedia format used in games like Mad Dog McCree.
3GPP AMRXX
Amazing Studio Packed Animation FileXMultimedia format used in game Heart Of Darkness.
Apple HTTP Live StreamingX
Artworx Data FormatX
Interplay ACMXAudio only format used in some Interplay games.
ADPXAudio format used on the Nintendo Gamecube.
AFCXAudio format used on the Nintendo Gamecube.
ADS/SS2XAudio format used on the PS2.
APNGXX
ASFXXAdvanced / Active Streaming Format.
ASTXXAudio format used on the Nintendo Wii.
AVIXX
AviSynthX
AVRXAudio format used on Mac.
AVSXMultimedia format used by the Creature Shock game.
Beam Software SIFFXAudio and video format used in some games by Beam Software.
Bethesda Softworks VIDXUsed in some games from Bethesda Softworks.
Binary textX
BinkXMultimedia format used by many games.
Bink AudioXAudio only multimedia format used by some games.
Bitmap Brothers JVXUsed in Z and Z95 games.
BRPXArgonaut Games format.
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
BFSTMXAudio format used on the Nintendo WiiU (based on BRSTM).
BRSTMXAudio format used on the Nintendo Wii.
BW64XBroadcast Wave 64bit.
BWFXX
codec2 (raw)XXMust be given -mode format option to decode correctly.
codec2 (.c2 files)XXContains header with version and mode info, simplifying playback.
CRI ADXXXAudio-only format used in console video games.
CRI AIXX
CRI HCAXAudio-only format used in console video games.
Discworld II BMVX
Interplay C93XUsed in the game Cyberia from Interplay.
Delphine Software International CINXMultimedia format used by Delphine Software games.
Digital Speech Standard (DSS)X
CD+GXVideo format used by CD+G karaoke disks
Phantom CineX
Commodore CDXLXAmiga CD video format
Core Audio FormatXXApple Core Audio Format
CRC testing formatX
Creative VoiceXXCreated for the Sound Blaster Pro.
CRYO APCXAudio format used in some games by CRYO Interactive Entertainment.
D-Cinema audioXX
Deluxe Paint AnimationX
DCSTRX
DFAXThis format is used in Chronomaster game
DirectDraw SurfaceX
DSD Stream File (DSF)X
DV videoXX
DXAXThis format is used in the non-Windows version of the Feeble Files + game and different game cutscenes repacked for use with ScummVM.
Electronic Arts cdataX
Electronic Arts MultimediaXUsed in various EA games; files have extensions like WVE and UV2.
Ensoniq Paris Audio FileX
FFM (FFserver live feed)XX
Flash (SWF)XX
Flash 9 (AVM2)XXOnly embedded audio is decoded.
FLI/FLC/FLX animationX.fli/.flc files
Flash Video (FLV)XXMacromedia Flash video files
framecrc testing formatX
FunCom ISSXAudio format used in various games from FunCom like The Longest Journey.
G.723.1XX
G.726XBoth left- and right-justified.
G.729 BITXX
G.729 rawX
GENHXAudio format for various games.
GIF AnimationXX
GXFXXGeneral eXchange Format SMPTE 360M, used by Thomson Grass Valley + playout servers.
HNMXOnly version 4 supported, used in some games from Cryo Interactive
iCEDraw FileX
ICOXXMicrosoft Windows ICO
id Quake II CIN videoX
id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
IEC61937 encapsulationXX
IFFXInterchange File Format
IFVXA format used by some old CCTV DVRs.
iLBCXX
Interplay MVEXFormat used in various Interplay computer games.
Iterated Systems ClearVideoXI-frames only
IV8XA format generated by IndigoVision 8000 video server.
IVF (On2)XXA format used by libvpx
Internet Video RecordingX
IRCAMXX
LAFXLimitless Audio Format
LATMXX
LMLM4XUsed by Linux Media Labs MPEG-4 PCI boards
LOASXcontains LATM multiplexed AAC audio
LRCXX
LVFX
LXFXVR native stream format, used by Leitch/Harris’ video servers.
Magic Lantern Video (MLV)X
MatroskaXX
Matroska audioX
FFmpeg metadataXXMetadata in text format.
MAXIS XAXUsed in Sim City 3000; file extension .xa.
MCAXUsed in some games from Capcom; file extension .mca.
MD StudioX
Metal Gear Solid: The Twin SnakesX
Megalux FrameXUsed by Megalux Ultimate Paint
MobiClip MODSX
MobiClip MOFLEXX
Mobotix .mxgX
Monkey’s AudioX
Motion Pixels MVIX
MOV/QuickTime/MP4XX3GP, 3GP2, PSP, iPod variants supported
MP2XX
MP3XX
MPEG-1 SystemXXmuxed audio and video, VCD format supported
MPEG-PS (program stream)XXalso known as VOB file, SVCD and DVD format supported
MPEG-TS (transport stream)XXalso known as DVB Transport Stream
MPEG-4XXMPEG-4 is a variant of QuickTime.
MSFXAudio format used on the PS3.
Mirillis FIC videoXNo cursor rendering.
MIDI Sample Dump StandardX
MIME multipart JPEGX
MSN TCP webcamXUsed by MSN Messenger webcam streams.
MTVX
MusepackX
Musepack SV8X
Material eXchange Format (MXF)XXSMPTE 377M, used by D-Cinema, broadcast industry.
Material eXchange Format (MXF), D-10 MappingXXSMPTE 386M, D-10/IMX Mapping.
NC camera feedXNC (AVIP NC4600) camera streams
NIST SPeech HEader REsourcesX
Computerized Speech Lab NSPX
NTT TwinVQ (VQF)XNippon Telegraph and Telephone Corporation TwinVQ.
Nullsoft Streaming VideoX
NuppelVideoX
NUTXXNUT Open Container Format
OggXX
Playstation Portable PMPX
Portable Voice FormatX
RK Audio (RKA)X
TechnoTrend PVAXUsed by TechnoTrend DVB PCI boards.
QCPX
raw ADTS (AAC)XX
raw AC-3XX
raw AMR-NBX
raw AMR-WBX
raw APACX
raw APVXX
raw aptXXX
raw aptX HDXX
raw BonkX
raw Chinese AVS videoXX
raw DFPWMXX
raw DiracXX
raw DNxHDXX
raw DTSXX
raw DTS-HDX
raw E-AC-3XX
raw EVCXX
raw FLACXX
raw G.728X
raw GSMX
raw H.261XX
raw H.263XX
raw H.264XX
raw HEVCXX
raw Ingenient MJPEGX
raw MJPEGXX
raw MLPX
raw MPEGX
raw MPEG-1X
raw MPEG-2X
raw MPEG-4XX
raw NULLX
raw videoXX
raw id RoQX
raw OBUXX
raw OSQX
raw SBCXX
raw ShortenX
raw TAKX
raw TrueHDXX
raw VC-1XX
raw PCM A-lawXX
raw PCM mu-lawXX
raw PCM Archimedes VIDCXX
raw PCM signed 8 bitXX
raw PCM signed 16 bit big-endianXX
raw PCM signed 16 bit little-endianXX
raw PCM signed 24 bit big-endianXX
raw PCM signed 24 bit little-endianXX
raw PCM signed 32 bit big-endianXX
raw PCM signed 32 bit little-endianXX
raw PCM signed 64 bit big-endianXX
raw PCM signed 64 bit little-endianXX
raw PCM unsigned 8 bitXX
raw PCM unsigned 16 bit big-endianXX
raw PCM unsigned 16 bit little-endianXX
raw PCM unsigned 24 bit big-endianXX
raw PCM unsigned 24 bit little-endianXX
raw PCM unsigned 32 bit big-endianXX
raw PCM unsigned 32 bit little-endianXX
raw PCM 16.8 floating point little-endianX
raw PCM 24.0 floating point little-endianX
raw PCM floating-point 32 bit big-endianXX
raw PCM floating-point 32 bit little-endianXX
raw PCM floating-point 64 bit big-endianXX
raw PCM floating-point 64 bit little-endianXX
RDTX
REDCODE R3DXFile format used by RED Digital cameras, contains JPEG 2000 frames and PCM audio.
RealMediaXX
RedirectorX
RedSparkX
Renderware TeXture DictionaryX
Resolume DXVXXEncoding is only supported for the DXT1 (Normal Quality, No Alpha) texture format.
RF64X
RL2XAudio and video format used in some games by Entertainment Software Partners.
RPL/ARMovieX
Lego Mindstorms RSOXX
RSDX
RTMPXXOutput is performed by publishing stream to RTMP server
RTPXX
RTSPXX
Sample Dump eXchangeX
SAPXX
SBGX
SDNSX
SDPX
SERX
Digital Pictures SGAX
Sega FILM/CPKXXUsed in many Sega Saturn console games.
Silicon Graphics MovieX
Sierra SOLX.sol files used in Sierra Online games.
Sierra VMDXUsed in Sierra CD-ROM games.
SmackerXMultimedia format used by many games.
SMJPEGXXUsed in certain Loki game ports.
SMPTE 337M encapsulationX
SmushXMultimedia format used in some LucasArts games.
Sony OpenMG (OMA)XXAudio format used in Sony Sonic Stage and Sony Vegas.
Sony PlayStation STRX
Sony Wave64 (W64)XX
SoX native formatXX
SUN AU formatXX
SUP raw PGS subtitlesXX
SVAGXAudio format used in Konami PS2 games.
TDSCX
Text filesX
THPXUsed on the Nintendo GameCube.
Tiertex Limited SEQXTiertex .seq files used in the DOS CD-ROM version of the game Flashback.
True AudioXX
VAGXAudio format used in many Sony PS2 games.
VC-1 test bitstreamXX
Vidvox HapXX
VivoX
VPKXAudio format used in Sony PS games.
Marble WADYX
WAVXX
Waveform ArchiverX
WavPackXX
WebMXX
Windows Televison (WTV)XX
Wing Commander III movieXMultimedia format used in Origin’s Wing Commander III computer game.
Westwood Studios audioXXMultimedia format used in Westwood Studios games.
Westwood Studios VQAXMultimedia format used in Westwood Studios games.
Wideband Single-bit Data (WSD)X
WVEX
Konami XMDX
XMVXMicrosoft video container used in Xbox games.
XVAGXAudio format used on the PS3.
xWMAXMicrosoft audio container used by XAudio 2.
eXtended BINary text (XBIN)X
YUV4MPEG pipeXX
Psygnosis YOPX
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+ +

51.2 Image Formats

+ +

FFmpeg can read and write images for each frame of a video sequence. The +following image formats are supported: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
.Y.U.VXXone raw file per component
Alias PIXXXAlias/Wavefront PIX image format
animated GIFXX
APNGXXAnimated Portable Network Graphics
BMPXXMicrosoft BMP image
BRender PIXXArgonaut BRender 3D engine image format.
CRIXCintel RAW
DPXXXDigital Picture Exchange
EXRXOpenEXR
FITSXXFlexible Image Transport System
HDRXXRadiance HDR RGBE Image format
IMGXGEM Raster image
JPEGXXProgressive JPEG is not supported.
JPEG 2000XX
JPEG-LSXX
JPEG-XSEESupported through external library libsvtjpegxs
LJPEGXLossless JPEG
Media 100X
MSPXMicrosoft Paint image
PAMXXPAM is a PNM extension with alpha support.
PBMXXPortable BitMap image
PCDXPhotoCD
PCXXXPC Paintbrush
PFMXXPortable FloatMap image
PGMXXPortable GrayMap image
PGMYUVXXPGM with U and V components in YUV 4:2:0
PGXXPGX file decoder
PHMXXPortable HalfFloatMap image
PICXPictor/PC Paint
PNGXXPortable Network Graphics image
PPMXXPortable PixelMap image
PSDXPhotoshop
PTXXV.Flash PTX format
QOIXXQuite OK Image format
SGIXXSGI RGB image format
Sun RasterfileXXSun RAS image format
TIFFXXYUV, JPEG and some extension is not supported yet.
Truevision TargaXXTarga (.TGA) image format
VBNXXVizrt Binary Image format
WBMPXXWireless Application Protocol Bitmap image format
WebPEXWebP image format, encoding supported through external library libwebp
XBMXXX BitMap image format
XFaceXXX-Face image format
XPMXX PixMap image format
XWDXXX Window Dump image format
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

51.3 Video Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
4X MovieXUsed in certain computer games.
8088flex TMVX
A64 multicolorXCreates video suitable to be played on a commodore 64 (multicolor mode).
Amazing Studio PAF VideoX
American Laser Games MMXUsed in games like Mad Dog McCree.
Amuse Graphics MovieX
AMV VideoXXUsed in Chinese MP3 players.
ANSI/ASCII artX
Apple Intermediate CodecX
Apple MJPEG-BX
Apple PixletX
Apple ProResXXfourcc: apch,apcn,apcs,apco,ap4h,ap4x
Apple QuickDrawXfourcc: qdrw
APVX
Argonaut VideoXUsed in some Argonaut games.
Asus v1XXfourcc: ASV1
Asus v2XXfourcc: ASV2
ATI VCR1Xfourcc: VCR1
ATI VCR2Xfourcc: VCR2
Auravision AuraX
Auravision Aura 2X
Autodesk Animator Flic videoX
Autodesk RLEXfourcc: AASC
AV1EESupported through external libraries libaom, libdav1d, librav1e and libsvtav1
Avid 1:1 10-bit RGB PackerXXfourcc: AVrp
AVS (Audio Video Standard) videoXVideo encoding used by the Creature Shock game.
AVS2-P2/IEEE1857.4EESupported through external libraries libxavs2 and libdavs2
AVS3-P2/IEEE1857.10ESupported through external library libuavs3d
AYUVXXMicrosoft uncompressed packed 4:4:4:4
Beam Software VBX
Bethesda VID videoXUsed in some games from Bethesda Softworks.
Bink VideoX
BitJazz SheerVideoX
Bitmap Brothers JV videoX
y41p Brooktree uncompressed 4:1:1 12-bitXX
Brooktree ProSumer VideoXfourcc: BT20
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
C93 videoXCodec used in Cyberia game.
CamStudioXfourcc: CSCD
CD+GXVideo codec for CD+G karaoke disks
CDXLXAmiga CD video codec
Chinese AVS videoEXAVS1-P2, JiZhun profile, encoding through external library libxavs
Delphine Software International CIN videoXCodec used in Delphine Software International games.
Discworld II BMV VideoX
CineForm HDXX
Canopus HQX
Canopus HQAX
Canopus HQXX
Canopus Lossless CodecX
CDToonsXCodec used in various Broderbund games.
CinepakX
Cirrus Logic AccuPakXXfourcc: CLJR
CPiA Video FormatX
Creative YUV (CYUV)X
DFAXCodec used in Chronomaster game.
DiracEXsupported though the native vc2 (Dirac Pro) encoder
Deluxe Paint AnimationX
DNxHDXXaka SMPTE VC3
Duck TrueMotion 1.0Xfourcc: DUCK
Duck TrueMotion 2.0Xfourcc: TM20
Duck TrueMotion 2.0 RTXfourcc: TR20
DV (Digital Video)XX
Dxtory capture formatX
Feeble Files/ScummVM DXAXCodec originally used in Feeble Files game.
Electronic Arts CMV videoXUsed in NHL 95 game.
Electronic Arts Madcow videoX
Electronic Arts TGV videoX
Electronic Arts TGQ videoX
Electronic Arts TQI videoX
Escape 124X
Escape 130X
EVC / MPEG-5 Part 1EEencoding and decoding supported through external libraries libxeve and libxevd
FFmpeg video codec #1XXlossless codec (fourcc: FFV1)
Flash Screen Video v1XXfourcc: FSV1
Flash Screen Video v2XX
Flash Video (FLV)XXSorenson H.263 used in Flash
FM Screen Capture CodecX
Forward UncompressedX
FrapsX
Go2MeetingXfourcc: G2M2, G2M3
Go2WebinarXfourcc: G2M4
Gremlin Digital VideoX
H.261XX
H.263 / H.263-1996XX
H.263+ / H.263-1998 / H.263 version 2XX
H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10EXencoding supported through external library libx264 and OpenH264
HEVCXXencoding supported through external library libx265 and libkvazaar
HNM version 4X
HuffYUVXX
HuffYUV FFmpeg variantXX
IBM UltimotionXfourcc: ULTI
id Cinematic videoXUsed in Quake II.
id RoQ videoXXUsed in Quake III, Jedi Knight 2, other computer games.
IFF ILBMXIFF interleaved bitmap
IFF ByteRun1XIFF run length encoded bitmap
Infinity IMM4X
Intel H.263X
Intel Indeo 2X
Intel Indeo 3X
Intel Indeo 4X
Intel Indeo 5X
Interplay C93XUsed in the game Cyberia from Interplay.
Interplay MVE videoXUsed in Interplay .MVE files.
J2KXX
Karl Morton’s video codecXCodec used in Worms games.
Kega Game Video (KGV1)XKega emulator screen capture codec.
LagarithX
LCEVC / MPEG-5 LCEVC / MPEG-5 Part 2Edecoding supported through external library liblcevc-dec
LCL (LossLess Codec Library) MSZHX
LCL (LossLess Codec Library) ZLIBEE
LEAD MCMPX
LOCOX
LucasArts SANM/SmushXUsed in LucasArts games / SMUSH animations.
lossless MJPEGXX
MagicYUV VideoXX
Mandsoft Screen Capture CodecX
Microsoft ATC ScreenXAlso known as Microsoft Screen 3.
Microsoft Expression Encoder ScreenXAlso known as Microsoft Titanium Screen 2.
Microsoft RLEXX
Microsoft Screen 1XAlso known as Windows Media Video V7 Screen.
Microsoft Screen 2XAlso known as Windows Media Video V9 Screen.
Microsoft Video 1X
MimicXUsed in MSN Messenger Webcam streams.
Miro VideoXLXfourcc: VIXL
MJPEG (Motion JPEG)XX
Mobotix MxPEG videoX
Motion Pixels videoX
MPEG-1 videoXX
MPEG-2 videoXX
MPEG-4 part 2XXlibxvidcore can be used alternatively for encoding.
MPEG-4 part 2 Microsoft variant version 1X
MPEG-4 part 2 Microsoft variant version 2XX
MPEG-4 part 2 Microsoft variant version 3XX
Newtek SpeedHQXX
Nintendo Gamecube THP videoX
NotchLCX
NuppelVideo/RTjpegXVideo encoding used in NuppelVideo files.
On2 VP3Xstill experimental
On2 VP4Xfourcc: VP40
On2 VP5Xfourcc: VP50
On2 VP6Xfourcc: VP60,VP61,VP62
On2 VP7Xfourcc: VP70,VP71
VP8EXfourcc: VP80, encoding supported through external library libvpx
VP9EXencoding supported through external library libvpx
Pinnacle TARGA CineWave YUV16Xfourcc: Y216
Q-team QPEGXfourccs: QPEG, Q1.0, Q1.1
QuickTime 8BPS videoX
QuickTime Animation (RLE) videoXXfourcc: ’rle ’
QuickTime Graphics (SMC)XXfourcc: ’smc ’
QuickTime video (RPZA)XXfourcc: rpza
R10K AJA Kona 10-bit RGB CodecXX
R210 Quicktime Uncompressed RGB 10-bitXX
Raw VideoXX
RealVideo 1.0XX
RealVideo 2.0XX
RealVideo 3.0Xstill far from ideal
RealVideo 4.0X
RealVideo 6.0X
Renderware TXD (TeXture Dictionary)XTexture dictionaries used by the Renderware Engine.
RivaTuner VideoXfourcc: ’RTV1’
RL2 videoXused in some games by Entertainment Software Partners
ScreenPressorX
ScreenpressoX
Screen Recorder Gold CodecX
Sierra VMD videoXUsed in Sierra VMD files.
Silicon Graphics Motion Video Compressor 1 (MVC1)X
Silicon Graphics Motion Video Compressor 2 (MVC2)X
Silicon Graphics RLE 8-bit videoX
Smacker videoXVideo encoding used in Smacker.
SMPTE VC-1X
SnowXXexperimental wavelet codec (fourcc: SNOW)
Sony PlayStation MDEC (Motion DECoder)X
Sorenson Vector Quantizer 1XXfourcc: SVQ1
Sorenson Vector Quantizer 3Xfourcc: SVQ3
Sunplus JPEG (SP5X)Xfourcc: SP5X
TechSmith Screen Capture CodecXfourcc: TSCC
TechSmith Screen Capture Codec 2Xfourcc: TSC2
TheoraEXencoding supported through external library libtheora
Tiertex Limited SEQ videoXCodec used in DOS CD-ROM FlashBack game.
Ut VideoXX
v210 QuickTime uncompressed 4:2:2 10-bitXX
v308 QuickTime uncompressed 4:4:4XX
v408 QuickTime uncompressed 4:4:4:4XX
v410 QuickTime uncompressed 4:4:4 10-bitXX
VBLE Lossless CodecX
vMix VideoXfourcc: ’VMX1’
VMware Screen Codec / VMware VideoXCodec used in videos captured by VMware.
Westwood Studios VQA (Vector Quantized Animation) videoX
Windows Media ImageX
Windows Media Video 7XX
Windows Media Video 8XX
Windows Media Video 9Xnot completely working
Wing Commander III / XanXUsed in Wing Commander III .MVE files.
Wing Commander IV / XanXUsed in Wing Commander IV.
Winnov WNV1X
WMV7XX
YAMAHA SMAFXX
Psygnosis YOP VideoX
yuv4XXlibquicktime uncompressed packed 4:2:0
ZeroCodec Lossless VideoX
ZLIBXXpart of LCL, encoder experimental
Zip Motion Blocks VideoXXEncoder works only in PAL8.
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

51.4 Audio Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
8SVX exponentialX
8SVX fibonacciX
AACEXXencoding supported through internal encoder and external library libfdk-aac
AAC+EIXencoding supported through external library libfdk-aac
AC-3IXIX
ACELP.KELVINX
ADPCM 4X MovieX
ADPCM Yamaha AICAX
ADPCM AmuseGraphics MovieX
ADPCM Argonaut GamesXX
ADPCM CDROM XAX
ADPCM Creative TechnologyX16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
ADPCM Electronic ArtsXUsed in various EA titles.
ADPCM Electronic Arts Maxis CDROM XSXUsed in Sim City 3000.
ADPCM Electronic Arts R1X
ADPCM Electronic Arts R2X
ADPCM Electronic Arts R3X
ADPCM Electronic Arts XASX
ADPCM G.722XX
ADPCM G.726XX
ADPCM IMA Acorn ReplayX
ADPCM IMA AMVXXUsed in AMV files
ADPCM IMA Cunning DevelopmentsX
ADPCM IMA Electronic Arts EACSX
ADPCM IMA Electronic Arts SEADX
ADPCM IMA FuncomX
ADPCM IMA High Voltage Software ALPXX
ADPCM IMA Mobiclip MOFLEXX
ADPCM IMA QuickTimeXX
ADPCM IMA Simon & Schuster InteractiveXX
ADPCM IMA Ubisoft APMXX
ADPCM IMA Loki SDL MJPEGX
ADPCM IMA WAVXX
ADPCM IMA WestwoodX
ADPCM ISS IMAXUsed in FunCom games.
ADPCM IMA DialogicX
ADPCM IMA Duck DK3XUsed in some Sega Saturn console games.
ADPCM IMA Duck DK4XUsed in some Sega Saturn console games.
ADPCM IMA RadicalX
ADPCM IMA XboxX
ADPCM MicrosoftXX
ADPCM MS IMAXX
ADPCM Nintendo Gamecube AFCX
ADPCM Nintendo Gamecube DTKX
ADPCM Nintendo THPX
ADPCM PlaystationX
ADPCM QT IMAXX
ADPCM SanyoX
ADPCM SEGA CRI ADXXXUsed in Sega Dreamcast games.
ADPCM Shockwave FlashXX
ADPCM Sound Blaster Pro 2-bitX
ADPCM Sound Blaster Pro 2.6-bitX
ADPCM Sound Blaster Pro 4-bitX
ADPCM VIMAXUsed in LucasArts SMUSH animations.
ADPCM Konami XMDX
ADPCM Westwood Studios IMAXXUsed in Westwood Studios games like Command and Conquer.
ADPCM YamahaXX
ADPCM ZorkX
AMR-NBEXencoding supported through external library libopencore-amrnb
AMR-WBEXencoding supported through external library libvo-amrwbenc
Amazing Studio PAF AudioX
Apple lossless audioXXQuickTime fourcc ’alac’
aptXXXUsed in Bluetooth A2DP
aptX HDXXUsed in Bluetooth A2DP
ATRAC1X
ATRAC3X
ATRAC3+X
ATRAC9X
Bink AudioXUsed in Bink and Smacker files in many games.
Bonk audioX
CELTEdecoding supported through external library libcelt
codec2EEen/decoding supported through external library libcodec2
CRI HCAX
Delphine Software International CIN audioXCodec used in Delphine Software International games.
DFPWMXX
Digital Speech Standard - Standard Play mode (DSS SP)X
Discworld II BMV AudioX
COOKXAll versions except 5.1 are supported.
DCA (DTS Coherent Acoustics)XXsupported extensions: XCh, XXCH, X96, XBR, XLL, LBR (partially)
Dolby EX
DPCM Cuberoot-Delta-ExactXUsed in few games.
DPCM GremlinX
DPCM id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
DPCM Marble WADYX
DPCM InterplayXUsed in various Interplay computer games.
DPCM Squareroot-Delta-ExactXUsed in various games.
DPCM Sierra OnlineXUsed in Sierra Online game audio files.
DPCM SolX
DPCM XanXUsed in Origin’s Wing Commander IV AVI files.
DPCM Xilam DERFX
DSD (Direct Stream Digital), least significant bit firstX
DSD (Direct Stream Digital), most significant bit firstX
DSD (Direct Stream Digital), least significant bit first, planarX
DSD (Direct Stream Digital), most significant bit first, planarX
DSP Group TrueSpeechX
DST (Direct Stream Transfer)X
DV audioX
Enhanced AC-3XX
EVRC (Enhanced Variable Rate Codec)X
FLAC (Free Lossless Audio Codec)XIX
FTR VoiceX
G.723.1XX
G.728X
G.729X
GSMEXencoding supported through external library libgsm
GSM Microsoft variantEXencoding supported through external library libgsm
IAC (Indeo Audio Coder)X
iLBC (Internet Low Bitrate Codec)EEXencoding and decoding supported through external library libilbc
IMC (Intel Music Coder)X
Interplay ACMX
LC3EEsupported through external library liblc3
MACE (Macintosh Audio Compression/Expansion) 6:1X
Marian’s A-pac audioX
MI-SC4 (Micronas SC-4 Audio)X
MLP (Meridian Lossless Packing)XXUsed in DVD-Audio discs.
Monkey’s AudioX
MP1 (MPEG audio layer 1)IX
MP2 (MPEG audio layer 2)IXIXencoding supported also through external library TwoLAME
MP3 (MPEG audio layer 3)EIXencoding supported through external library LAME, ADU MP3 and MP3onMP4 also supported
MPEG-4 Audio Lossless Coding (ALS)X
MPEG-H 3D AudioEdecoding supported through external library libmpeghdec
MobiClip FastAudioX
Musepack SV7X
Musepack SV8X
Nellymoser AsaoXX
On2 AVC (Audio for Video Codec)X
OpusEXencoding supported through external library libopus
OSQ (Original Sound Quality)X
PCM A-lawXX
PCM mu-lawXX
PCM Archimedes VIDCXX
PCM signed 8-bit planarXX
PCM signed 16-bit big-endian planarXX
PCM signed 16-bit little-endian planarXX
PCM signed 24-bit little-endian planarXX
PCM signed 32-bit little-endian planarXX
PCM 32-bit floating point big-endianXX
PCM 32-bit floating point little-endianXX
PCM 64-bit floating point big-endianXX
PCM 64-bit floating point little-endianXX
PCM D-Cinema audio signed 24-bitXX
PCM signed 8-bitXX
PCM signed 16-bit big-endianXX
PCM signed 16-bit little-endianXX
PCM signed 24-bit big-endianXX
PCM signed 24-bit little-endianXX
PCM signed 32-bit big-endianXX
PCM signed 32-bit little-endianXX
PCM signed 16/20/24-bit big-endian in MPEG-TSX
PCM unsigned 8-bitXX
PCM unsigned 16-bit big-endianXX
PCM unsigned 16-bit little-endianXX
PCM unsigned 24-bit big-endianXX
PCM unsigned 24-bit little-endianXX
PCM unsigned 32-bit big-endianXX
PCM unsigned 32-bit little-endianXX
PCM SGAX
QCELP / PureVoiceX
QDesign Music Codec 1X
QDesign Music Codec 2XThere are still some distortions.
RealAudio 1.0 (14.4K)XXReal 14400 bit/s codec
RealAudio 2.0 (28.8K)XReal 28800 bit/s codec
RealAudio 3.0 (dnet)IXXReal low bitrate AC-3 codec
RealAudio LosslessX
RealAudio SIPR / ACELP.NETX
RK Audio (RKA)X
SBC (low-complexity subband codec)XXUsed in Bluetooth A2DP
ShortenX
Sierra VMD audioXUsed in Sierra VMD files.
Smacker audioX
SMPTE 302M AES3 audioXX
SonicXXexperimental codec
Sonic losslessXXexperimental codec
SpeexEEXsupported through external library libspeex
TAK (Tom’s lossless Audio Kompressor)X
True Audio (TTA)XX
TrueHDXXUsed in HD-DVD and Blu-Ray discs.
TwinVQ (VQF flavor)X
VIMAXUsed in LucasArts SMUSH animations.
ViewQuest VQCX
VorbisEXA native but very primitive encoder exists.
Voxware MetaSoundX
Waveform ArchiverX
WavPackXX
Westwood Audio (SND1)X
Windows Media Audio 1XX
Windows Media Audio 2XX
Windows Media Audio LosslessX
Windows Media Audio ProX
Windows Media Audio VoiceX
Xbox Media Audio 1X
Xbox Media Audio 2X
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+

I means that an integer-only version is available, too (ensures high +performance on systems without hardware floating point support). +

+ +

51.5 Subtitle Formats

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameMuxingDemuxingEncodingDecoding
3GPP Timed TextXX
AQTitleXX
DVBXXXX
DVB teletextXE
DVDXXXX
JACOsubXXX
MicroDVDXXX
MPL2XX
MPsub (MPlayer)XX
PGSX
PJS (Phoenix)XX
RealTextXX
SAMIXX
Spruce format (STL)XX
SSA/ASSXXXX
SubRip (SRT)XXXX
SubViewer v1XX
SubViewerXX
TED Talks captionsXX
TTMLXX
VobSub (IDX+SUB)XX
VPlayerXX
WebVTTXXXX
XSUBXX
+ +

X means that the feature is supported. +

+

E means that support is provided through an external library. +

+ +

51.6 Network Protocols

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSupport
AMQPE
fileX
FTPX
GopherX
GophersX
HLSX
HTTPX
HTTPSX
IcecastX
MMSHX
MMSTX
pipeX
Pro-MPEG FECX
RTMPX
RTMPEX
RTMPSX
RTMPTX
RTMPTEX
RTMPTSX
RTPX
SAMBAE
SCTPX
SFTPE
TCPX
TLSX
UDPX
ZMQE
+ +

X means that the protocol is supported. +

+

E means that support is provided through an external library. +

+ + +

51.7 Input/Output Devices

+ + + + + + + + + + + + + + + + + + + + + + +
NameInputOutput
ALSAXX
BKTRX
cacaX
DV1394X
Lavfi virtual deviceX
Linux framebufferXX
JACKX
LIBCDIOX
LIBDC1394X
OpenALX
OpenGLX
OSSXX
PulseAudioXX
SDLX
Video4Linux2XX
VfW captureX
X11 grabbingX
Win32 grabbingX
+ +

X means that input/output is supported. +

+ +

51.8 Timecode

+ + + + + + + + + + +
Codec/formatReadWrite
AVIXX
DVXX
GXFXX
MOVXX
MPEG1/2XX
MXFXX
+ + +

52 See Also

+ +

ffmpeg +ffplay, ffprobe, +ffmpeg-utils, +ffmpeg-scaler, +ffmpeg-resampler, +ffmpeg-codecs, +ffmpeg-bitstream-filters, +ffmpeg-formats, +ffmpeg-devices, +ffmpeg-protocols, +ffmpeg-filters +

+ + +

53 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-bitstream-filters.html b/ffmpeg-n8.1/doc/ffmpeg-bitstream-filters.html new file mode 100644 index 00000000..2fd3c5dc --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-bitstream-filters.html @@ -0,0 +1,1363 @@ + + + + + + + FFmpeg Bitstream Filters Documentation + + + + + + +
+

+ FFmpeg Bitstream Filters Documentation +

+ + + + + + + +

1 Description

+ +

This document describes the bitstream filters provided by the +libavcodec library. +

+

A bitstream filter operates on the encoded stream data, and performs +bitstream level modifications without performing decoding. +

+ + +

2 Bitstream Filters

+ +

When you configure your FFmpeg build, all the supported bitstream +filters are enabled by default. You can list all available ones using +the configure option --list-bsfs. +

+

You can disable all the bitstream filters using the configure option +--disable-bsfs, and selectively enable any bitstream filter using +the option --enable-bsf=BSF, or you can disable a particular +bitstream filter using the option --disable-bsf=BSF. +

+

The option -bsfs of the ff* tools will display the list of +all the supported bitstream filters included in your build. +

+

The ff* tools have a -bsf option applied per stream, taking a +comma-separated list of filters, whose parameters follow the filter +name after a ’=’. +

+
+
ffmpeg -i INPUT -c:v copy -bsf:v filter1[=opt1=str1:opt2=str2][,filter2] OUTPUT
+
+ +

Below is a description of the currently available bitstream filters, +with their parameters, if any. +

+ +

2.1 aac_adtstoasc

+ +

Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration +bitstream. +

+

This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4 +ADTS header and removes the ADTS header. +

+

This filter is required for example when copying an AAC stream from a +raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or +to MOV/MP4 files and related formats such as 3GP or M4A. Please note +that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats. +

+ +

2.2 av1_metadata

+ +

Modify metadata embedded in an AV1 stream. +

+
+
td
+

Insert or remove temporal delimiter OBUs in all temporal units of the +stream. +

+
+
‘insert’
+

Insert a TD at the beginning of every TU which does not already have one. +

+
‘remove’
+

Remove the TD from the beginning of every TU which has one. +

+
+ +
+
color_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the color description fields in the stream (see AV1 section 6.4.2). +

+
+
color_range
+

Set the color range in the stream (see AV1 section 6.4.2; note that +this cannot be set for streams using BT.709 primaries, sRGB transfer +characteristic and identity (RGB) matrix coefficients). +

+
‘tv’
+

Limited range. +

+
‘pc’
+

Full range. +

+
+ +
+
chroma_sample_position
+

Set the chroma sample location in the stream (see AV1 section 6.4.2). +This can only be set for 4:2:0 streams. +

+
+
‘vertical’
+

Left position (matching the default in MPEG-2 and H.264). +

+
‘colocated’
+

Top-left position. +

+
+ +
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_display_tick) in +the timing info in the sequence header. +

+
num_ticks_per_picture
+

Set the number of ticks in each picture, to indicate that the stream +has a fixed framerate. Ignored if tick_rate is not also set. +

+
+
delete_padding
+

Deletes Padding OBUs. +

+
+
+ + +

2.3 chomp

+ +

Remove zero padding at the end of a packet. +

+ +

2.4 dca_core

+ +

Extract the core from a DCA/DTS stream, dropping extensions such as +DTS-HD. +

+ +

2.5 dovi_rpu

+ +

Manipulate Dolby Vision metadata in a HEVC/AV1 bitstream, optionally enabling +metadata compression. +

+
+
strip
+

If enabled, strip all Dolby Vision metadata (configuration record + RPU data +blocks) from the stream. +

+
compression
+

Which compression level to enable. +

+
‘none’
+

No metadata compression. +

+
‘limited’
+

Limited metadata compression scheme. Should be compatible with most devices. +This is the default. +

+
‘extended’
+

Extended metadata compression. Devices are not required to support this. Note +that this level currently behaves the same as ‘limited’ in libavcodec. +

+
+
+
+ + +

2.6 dump_extra

+ +

Add extradata to the beginning of the filtered packets except when +said packets already exactly begin with the extradata that is intended +to be added. +

+
+
freq
+

The additional argument specifies which packets should be filtered. +It accepts the values: +

+
‘k’
+
‘keyframe’
+

add extradata to all key packets +

+
+
‘e’
+
‘all’
+

add extradata to all packets +

+
+
+
+ +

If not specified it is assumed ‘k’. +

+

For example the following ffmpeg command forces a global +header (thus disabling individual packet headers) in the H.264 packets +generated by the libx264 encoder, but corrects them by adding +the header stored in extradata to the key packets: +

+
ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts
+
+ + +

2.7 dv_error_marker

+ +

Blocks in DV which are marked as damaged are replaced by blocks of the specified color. +

+
+
color
+

The color to replace damaged blocks by +

+
sta
+

A 16 bit mask which specifies which of the 16 possible error status values are +to be replaced by colored blocks. 0xFFFE is the default which replaces all non 0 +error status values. +

+
‘ok’
+

No error, no concealment +

+
‘err’
+

Error, No concealment +

+
‘res’
+

Reserved +

+
‘notok’
+

Error or concealment +

+
‘notres’
+

Not reserved +

+
‘Aa, Ba, Ca, Ab, Bb, Cb, A, B, C, a, b, erri, erru’
+

The specific error status code +

+
+

see page 44-46 or section 5.5 of +http://web.archive.org/web/20060927044735/http://www.smpte.org/smpte_store/standards/pdf/s314m.pdf +

+
+
+ + +

2.8 eac3_core

+ +

Extract the core from a E-AC-3 stream, dropping extra channels. +

+ +

2.9 eia608_to_smpte436m

+ +

Convert from a EIA_608 stream to a SMPTE_436M_ANC data stream, wrapping the closed captions in CTA-708 CDP VANC packets. +

+
+
line_number
+

Choose which line number the generated VANC packets should go on. You generally want either line 9 (the default) or 11. +

+
wrapping_type
+

Choose the SMPTE 436M wrapping type, defaults to ‘vanc_frame’. +It accepts the values: +

+
‘vanc_frame’
+

VANC frame (interlaced or segmented progressive frame) +

+
‘vanc_field_1’
+
‘vanc_field_2’
+
‘vanc_progressive_frame’
+
+
+
sample_coding
+

Choose the SMPTE 436M sample coding, defaults to ‘8bit_luma’. +It accepts the values: +

+
‘8bit_luma’
+

8-bit component luma samples +

+
‘8bit_color_diff’
+

8-bit component color difference samples +

+
‘8bit_luma_and_color_diff’
+

8-bit component luma and color difference samples +

+
‘10bit_luma’
+

10-bit component luma samples +

+
‘10bit_color_diff’
+

10-bit component color difference samples +

+
‘10bit_luma_and_color_diff’
+

10-bit component luma and color difference samples +

+
‘8bit_luma_parity_error’
+

8-bit component luma samples with parity error +

+
‘8bit_color_diff_parity_error’
+

8-bit component color difference samples with parity error +

+
‘8bit_luma_and_color_diff_parity_error’
+

8-bit component luma and color difference samples with parity error +

+
+
+
initial_cdp_sequence_cntr
+

The initial value of the CDP’s 16-bit unsigned integer cdp_hdr_sequence_cntr and cdp_ftr_sequence_cntr fields. Defaults to 0. +

+
cdp_frame_rate
+

Set the CDP’s cdp_frame_rate field. This doesn’t actually change the timing of the data stream, it just changes the values inserted in that field in the generated CDP packets. Defaults to ‘30000/1001’. +

+
+ + +

2.10 extract_extradata

+ +

Extract the in-band extradata. +

+

Certain codecs allow the long-term headers (e.g. MPEG-2 sequence headers, +or H.264/HEVC (VPS/)SPS/PPS) to be transmitted either "in-band" (i.e. as a part +of the bitstream containing the coded frames) or "out of band" (e.g. on the +container level). This latter form is called "extradata" in FFmpeg terminology. +

+

This bitstream filter detects the in-band headers and makes them available as +extradata. +

+
+
remove
+

When this option is enabled, the long-term headers are removed from the +bitstream after extraction. +

+
+ + +

2.11 filter_units

+ +

Remove units with types in or not in a given set from the stream. +

+
+
pass_types
+

List of unit types or ranges of unit types to pass through while removing +all others. This is specified as a ’|’-separated list of unit type values +or ranges of values with ’-’. +

+
+
remove_types
+

Identical to pass_types, except the units in the given set +removed and all others passed through. +

+
+ +

The types used by pass_types and remove_types correspond to NAL unit types +(nal_unit_type) in H.264, HEVC and H.266 (see Table 7-1 in the H.264 +and HEVC specifications or Table 5 in the H.266 specification), to +marker values for JPEG (without 0xFF prefix) and to start codes without +start code prefix (i.e. the byte following the 0x000001) for MPEG-2. +For VP8 and VP9, every unit has type zero. +

+

Extradata is unchanged by this transformation, but note that if the stream +contains inline parameter sets then the output may be unusable if they are +removed. +

+

For example, to remove all non-VCL NAL units from an H.264 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=pass_types=1-5' OUTPUT
+
+ +

To remove all AUDs, SEI and filler from an H.265 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=35|38-40' OUTPUT
+
+ +

To remove all user data from a MPEG-2 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=178' OUTPUT
+
+ +

To remove all SEI from a H264 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=6' OUTPUT
+
+ +

To remove all prefix and suffix SEI from a HEVC stream, including Closed Captions and dynamic HDR: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=39|40' OUTPUT
+
+ + +

2.12 hapqa_extract

+ +

Extract Rgb or Alpha part of an HAPQA file, without recompression, in order to create an HAPQ or an HAPAlphaOnly file. +

+
+
texture
+

Specifies the texture to keep. +

+
+
color
+
alpha
+
+ +
+
+ +

Convert HAPQA to HAPQ +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=color -tag:v HapY -metadata:s:v:0 encoder="HAPQ" hapq_file.mov
+
+ +

Convert HAPQA to HAPAlphaOnly +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=alpha -tag:v HapA -metadata:s:v:0 encoder="HAPAlpha Only" hapalphaonly_file.mov
+
+ + +

2.13 h264_metadata

+ +

Modify metadata embedded in an H.264 stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
+ +

Default is pass. +

+
+
sample_aspect_ratio
+

Set the sample aspect ratio of the stream in the VUI parameters. +See H.264 table E-1. +

+
+
overscan_appropriate_flag
+

Set whether the stream is suitable for display using overscan +or not (see H.264 section E.2.1). +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.264 section E.2.1 and +table E-2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.264 section E.2.1 +and tables E-3, E-4 and E-5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.264 section +E.2.1 and figure E-1). +

+
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_tick) in the VUI +parameters. This is the smallest time unit representable in the +stream, and in many cases represents the field rate of the stream +(double the frame rate). +

+
fixed_frame_rate_flag
+

Set whether the stream has fixed framerate - typically this indicates +that the framerate is exactly half the tick rate, but the exact +meaning is dependent on interlacing and the picture structure (see +H.264 section E.2.1 and table E-6). +

+
zero_new_constraint_set_flags
+

Zero constraint_set4_flag and constraint_set5_flag in the SPS. These +bits were reserved in a previous version of the H.264 spec, and thus +some hardware decoders require these to be zero. The result of zeroing +this is still a valid bitstream. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the frame cropping offsets in the SPS. These values will replace +the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled or the stream is interlaced +(see H.264 section 7.4.2.1.1). +

+
+
sei_user_data
+

Insert a string as SEI unregistered user data. The argument must +be of the form UUID+string, where the UUID is as hex digits +possibly separated by hyphens, and the string can be anything. +

+

For example, ‘086f3693-b7b3-4f2c-9653-21492feee5b8+hello’ will +insert the string “hello” associated with the given UUID. +

+
+
delete_filler
+

Deletes both filler NAL units and filler SEI messages. +

+
+
display_orientation
+

Insert, extract or remove Display orientation SEI messages. +See H.264 section D.1.27 and D.2.27 for syntax and semantics. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
‘extract’
+
+ +

Default is pass. +

+

Insert mode works in conjunction with rotate and flip options. +Any pre-existing Display orientation messages will be removed in insert or remove mode. +Extract mode attaches the display matrix to the packet as side data. +

+
+
rotate
+

Set rotation in display orientation SEI (anticlockwise angle in degrees). +Range is -360 to +360. Default is NaN. +

+
+
flip
+

Set flip in display orientation SEI. +

+
+
‘horizontal’
+
‘vertical’
+
+ +

Default is unset. +

+
+
level
+

Set the level in the SPS. Refer to H.264 section A.3 and tables A-1 +to A-5. +

+

The argument must be the name of a level (for example, ‘4.2’), a +level_idc value (for example, ‘42’), or the special name ‘auto’ +indicating that the filter should attempt to guess the level from the +input stream properties. +

+
+
+ + +

2.14 h264_mp4toannexb

+ +

Convert an H.264 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.264 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an H.264 stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw H.264 (muxer h264) output formats. +

+ +

2.15 h264_redundant_pps

+ +

This applies a specific fixup to some Blu-ray BDMV H264 streams +which contain redundant PPSs. The PPSs modify irrelevant parameters +of the stream, confusing other transformations which require +the correct extradata. +

+

The encoder used on these impacted streams adds extra PPSs throughout +the stream, varying the initial QP and whether weighted prediction +was enabled. This causes issues after copying the stream into +a global header container, as the starting PPS is not suitable +for the rest of the stream. One side effect, for example, +is seeking will return garbled output until a new PPS appears. +

+

This BSF removes the extra PPSs and rewrites the slice headers +such that the stream uses a single leading PPS in the global header, +which resolves the issue. +

+ +

2.16 hevc_metadata

+ +

Modify metadata embedded in an HEVC stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘insert’
+
‘remove’
+
+ +
+
sample_aspect_ratio
+

Set the sample aspect ratio in the stream in the VUI parameters. +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.265 section E.3.1 and +table E.2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.265 section E.3.1 +and tables E.3, E.4 and E.5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.265 section +E.3.1 and figure E.1). +

+
+
tick_rate
+

Set the tick rate in the VPS and VUI parameters (time_scale / +num_units_in_tick). Combined with num_ticks_poc_diff_one, this can +set a constant framerate in the stream. Note that it is likely to be +overridden by container parameters when the stream is in a container. +

+
+
num_ticks_poc_diff_one
+

Set poc_proportional_to_timing_flag in VPS and VUI and use this value +to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and +E.3.1). Ignored if tick_rate is not also set. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the conformance window cropping offsets in the SPS. These values +will replace the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled (H.265 section 7.4.3.2.1). +

+
+
width
+
height
+

Set width and height after crop. +

+
+
level
+

Set the level in the VPS and SPS. See H.265 section A.4 and tables +A.6 and A.7. +

+

The argument must be the name of a level (for example, ‘5.1’), a +general_level_idc value (for example, ‘153’ for level 5.1), +or the special name ‘auto’ indicating that the filter should +attempt to guess the level from the input stream properties. +

+
+
+ + +

2.17 hevc_mp4toannexb

+ +

Convert an HEVC/H.265 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.265 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an HEVC stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw HEVC/H.265 (muxer h265 or +hevc) output formats. +

+ +

2.18 imxdump

+ +

Modifies the bitstream to fit in MOV and to be usable by the Final Cut +Pro decoder. This filter only applies to the mpeg2video codec, and is +likely not needed for Final Cut Pro 7 and newer with the appropriate +-tag:v. +

+

For example, to remux 30 MB/sec NTSC IMX to MOV: +

+
+
ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov
+
+ + +

2.19 mjpeg2jpeg

+ +

Convert MJPEG/AVI1 packets to full JPEG/JFIF packets. +

+

MJPEG is a video codec wherein each video frame is essentially a +JPEG image. The individual frames can be extracted without loss, +e.g. by +

+
+
ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg
+
+ +

Unfortunately, these chunks are incomplete JPEG images, because +they lack the DHT segment required for decoding. Quoting from +http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml: +

+

Avery Lee, writing in the rec.video.desktop newsgroup in 2001, +commented that "MJPEG, or at least the MJPEG in AVIs having the +MJPG fourcc, is restricted JPEG with a fixed – and *omitted* – +Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2, +and it must use basic Huffman encoding, not arithmetic or +progressive. . . . You can indeed extract the MJPEG frames and +decode them with a regular JPEG decoder, but you have to prepend +the DHT segment to them, or else the decoder won’t have any idea +how to decompress the data. The exact table necessary is given in +the OpenDML spec." +

+

This bitstream filter patches the header of frames extracted from an MJPEG +stream (carrying the AVI1 header ID and lacking a DHT segment) to +produce fully qualified JPEG images. +

+
+
ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg
+exiftran -i -9 frame*.jpg
+ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
+
+ + +

2.20 mjpegadump

+ +

Add an MJPEG A header to the bitstream, to enable decoding by +Quicktime. +

+ +

2.21 mov2textsub

+ +

Extract a representable text file from MOV subtitles, stripping the +metadata header from each subtitle packet. +

+

See also the text2movsub filter. +

+ +

2.22 mpeg2_metadata

+ +

Modify metadata embedded in an MPEG-2 stream. +

+
+
display_aspect_ratio
+

Set the display aspect ratio in the stream. +

+

The following fixed values are supported: +

+
4/3
+
16/9
+
221/100
+
+

Any other value will result in square pixels being signalled instead +(see H.262 section 6.3.3 and table 6-3). +

+
+
frame_rate
+

Set the frame rate in the stream. This is constructed from a table +of known values combined with a small multiplier and divisor - if +the supplied value is not exactly representable, the nearest +representable value will be used instead (see H.262 section 6.3.3 +and table 6-4). +

+
+
video_format
+

Set the video format in the stream (see H.262 section 6.3.6 and +table 6-6). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.262 section 6.3.6 +and tables 6-7, 6-8 and 6-9). +

+
+
+ + +

2.23 mpeg4_unpack_bframes

+ +

Unpack DivX-style packed B-frames. +

+

DivX-style packed B-frames are not valid MPEG-4 and were only a +workaround for the broken Video for Windows subsystem. +They use more space, can cause minor AV sync issues, require more +CPU power to decode (unless the player has some decoded picture queue +to compensate the 2,0,2,0 frame per packet style) and cause +trouble if copied into a standard container like mp4 or mpeg-ps/ts, +because MPEG-4 decoders may not be able to decode them, since they are +not valid MPEG-4. +

+

For example to fix an AVI file containing an MPEG-4 stream with +DivX-style packed B-frames using ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi
+
+ + +

2.24 noise

+ +

Damages the contents of packets or simply drops them without damaging the +container. Can be used for fuzzing or testing error resilience/concealment. +

+

Parameters: +

+
amount
+

Accepts an expression whose evaluation per-packet determines how often bytes in that +packet will be modified. A value below 0 will result in a variable frequency. +Default is 0 which results in no modification. However, if neither amount nor drop is specified, +amount will be set to -1. See below for accepted variables. +

+
drop
+

Accepts an expression evaluated per-packet whose value determines whether that packet is dropped. +Evaluation to a positive value results in the packet being dropped. Evaluation to a negative +value results in a variable chance of it being dropped, roughly inverse in proportion to the magnitude +of the value. Default is 0 which results in no drops. See below for accepted variables. +

+
dropamount
+

Accepts a non-negative integer, which assigns a variable chance of it being dropped, roughly inverse +in proportion to the value. Default is 0 which results in no drops. This option is kept for backwards +compatibility and is equivalent to setting drop to a negative value with the same magnitude +i.e. dropamount=4 is the same as drop=-4. Ignored if drop is also specified. +

+
+ +

Both amount and drop accept expressions containing the following variables: +

+
+
‘n’
+

The index of the packet, starting from zero. +

+
‘tb’
+

The timebase for packet timestamps. +

+
‘pts’
+

Packet presentation timestamp. +

+
‘dts’
+

Packet decoding timestamp. +

+
‘nopts’
+

Constant representing AV_NOPTS_VALUE. +

+
‘startpts’
+

First non-AV_NOPTS_VALUE PTS seen in the stream. +

+
‘startdts’
+

First non-AV_NOPTS_VALUE DTS seen in the stream. +

+
‘duration’
+
‘d’
+

Packet duration, in timebase units. +

+
‘pos’
+

Packet position in input; may be -1 when unknown or not set. +

+
‘size’
+

Packet size, in bytes. +

+
‘key’
+

Whether packet is marked as a keyframe. +

+
‘state’
+

A pseudo random integer, primarily derived from the content of packet payload. +

+
+ + +

2.24.1 Examples

+

Apply modification to every byte but don’t drop any packets. +

+
ffmpeg -i INPUT -c copy -bsf noise=1 output.mkv
+
+ +

Drop every video packet not marked as a keyframe after timestamp 30s but do not +modify any of the remaining packets. +

+
ffmpeg -i INPUT -c copy -bsf:v noise=drop='gt(pts*tb\,30)*not(key)' output.mkv
+
+ +

Drop one second of audio every 10 seconds and add some random noise to the rest. +

+
ffmpeg -i INPUT -c copy -bsf:a noise=amount=-1:drop='between(mod(pts*tb\,10)\,9\,10)' output.mkv
+
+ + +

2.25 null

+

This bitstream filter passes the packets through unchanged. +

+ +

2.26 pcm_rechunk

+ +

Repacketize PCM audio to a fixed number of samples per packet or a fixed packet +rate per second. This is similar to the asetnsamples audio +filter but works on audio packets instead of audio frames. +

+
+
nb_out_samples, n
+

Set the number of samples per each output audio packet. The number is intended +as the number of samples per each channel. Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio packet with silence, so that it +will contain the same number of samples (or roughly the same number of samples, +see frame_rate) as the previous ones. Default value is 1. +

+
+
frame_rate, r
+

This option makes the filter output a fixed number of packets per second instead +of a fixed number of samples per packet. If the audio sample rate is not +divisible by the frame rate then the number of samples will not be constant but +will vary slightly so that each packet will start as close to the frame +boundary as possible. Using this option has precedence over nb_out_samples. +

+
+ +

You can generate the well known 1602-1601-1602-1601-1602 pattern of 48kHz audio +for NTSC frame rate using the frame_rate option. +

+
ffmpeg -f lavfi -i sine=r=48000:d=1 -c pcm_s16le -bsf pcm_rechunk=r=30000/1001 -f framecrc -
+
+ + +

2.27 pgs_frame_merge

+ +

Merge a sequence of PGS Subtitle segments ending with an "end of display set" +segment into a single packet. +

+

This is required by some containers that support PGS subtitles +(muxer matroska). +

+ +

2.28 prores_metadata

+ +

Modify color property metadata embedded in prores stream. +

+
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘bt470bg’
+

BT601 625 +

+
+
‘smpte170m’
+

BT601 525 +

+
+
‘bt2020’
+
‘smpte431’
+

DCI P3 +

+
+
‘smpte432’
+

P3 D65 +

+
+
+ +
+
transfer_characteristics
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same transfer characteristics property (default). +

+
+
‘unknown’
+
‘bt709’
+

BT 601, BT 709, BT 2020 +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ + +
+
matrix_coefficients
+

Set the matrix coefficient. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘smpte170m’
+

BT 601 +

+
+
‘bt2020nc’
+
+
+
+ +

Set Rec709 colorspace for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt709:color_trc=bt709:colorspace=bt709 output.mov
+
+ +

Set Hybrid Log-Gamma parameters for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt2020:color_trc=arib-std-b67:colorspace=bt2020nc output.mov
+
+ + +

2.29 remove_extra

+ +

Remove extradata from packets. +

+

It accepts the following parameter: +

+
freq
+

Set which frame types to remove extradata from. +

+
+
‘k’
+

Remove extradata from non-keyframes only. +

+
+
‘keyframe’
+

Remove extradata from keyframes only. +

+
+
‘e, all’
+

Remove extradata from all frames. +

+
+
+
+
+ + +

2.30 setts

+

Set PTS and DTS in packets. +

+

It accepts the following parameters: +

+
ts
+
pts
+
dts
+

Set expressions for PTS, DTS or both. +

+
duration
+

Set expression for duration. +

+
time_base
+

Set output time base. +

+
prescale
+

Set whether to convert time fields to user-set output time base before evaluation of expressions. Defaults to 0. +

+
+ +

The expressions are evaluated through the eval API and can contain the following +constants: +

+
+
N
+

The count of the input packet. Starting from 0. +

+
+
TS
+

The demux timestamp in input in case of ts or dts option or presentation +timestamp in case of pts option. +

+
+
POS
+

The original position in the file of the packet, or undefined if undefined +for the current packet +

+
+
DTS
+

The demux timestamp in input. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
DURATION
+

The duration in input. +

+
+
STARTDTS
+

The DTS of the first packet. +

+
+
STARTPTS
+

The PTS of the first packet. +

+
+
PREV_INDTS
+

The previous input DTS. +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INDURATION
+

The previous input duration. +

+
+
PREV_OUTDTS
+

The previous output DTS. +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTDURATION
+

The previous output duration. +

+
+
NEXT_DTS
+

The next input DTS. +

+
+
NEXT_PTS
+

The next input PTS. +

+
+
NEXT_DURATION
+

The next input duration. +

+
+
TB
+

The timebase in which time fields are denominated. The user-set output timebase if prescale is enabled, else the input timebase. +

+
+
TB_OUT
+

The output timebase. +

+
+
SR
+

The sample rate of stream packet belongs. +

+
+
NOPTS
+

The AV_NOPTS_VALUE constant. +

+
+ +

For example, to set PTS equal to DTS (not recommended if B-frames are involved): +

+
ffmpeg -i INPUT -c:a copy -bsf:a setts=pts=DTS out.mkv
+
+ + +

2.31 showinfo

+

Log basic packet information. Mainly useful for testing, debugging, +and development. +

+ +

2.32 smpte436m_to_eia608

+ +

Convert from a SMPTE_436M_ANC data stream to a EIA_608 stream, +extracting the closed captions from CTA-708 CDP VANC packets, and ignoring all other data. +

+ +

2.33 text2movsub

+ +

Convert text subtitles to MOV subtitles (as used by the mov_text +codec) with metadata headers. +

+

See also the mov2textsub filter. +

+ +

2.34 trace_headers

+ +

Log trace output containing all syntax elements in the coded stream +headers (everything above the level of individual coded blocks). +This can be useful for debugging low-level stream issues. +

+

Supports AV1, H.264, H.265, (M)JPEG, MPEG-2 and VP9, but depending +on the build only a subset of these may be available. +

+ +

2.35 truehd_core

+ +

Extract the core from a TrueHD stream, dropping ATMOS data. +

+ +

2.36 vp9_metadata

+ +

Modify metadata embedded in a VP9 stream. +

+
+
color_space
+

Set the color space value in the frame header. Note that any frame +set to RGB will be implicitly set to PC range and that RGB is +incompatible with profiles 0 and 2. +

+
‘unknown’
+
‘bt601’
+
‘bt709’
+
‘smpte170’
+
‘smpte240’
+
‘bt2020’
+
‘rgb’
+
+ +
+
color_range
+

Set the color range value in the frame header. Note that any value +imposed by the color space will take precedence over this value. +

+
‘tv’
+
‘pc’
+
+
+
+ + +

2.37 vp9_superframe

+ +

Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This +fixes merging of split/segmented VP9 streams where the alt-ref frame +was split from its visible counterpart. +

+ +

2.38 vp9_superframe_split

+ +

Split VP9 superframes into single frames. +

+ +

2.39 vp9_raw_reorder

+ +

Given a VP9 stream with correct timestamps but possibly out of order, +insert additional show-existing-frame packets to correct the ordering. +

+ + +

3 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavcodec +

+ + +

4 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-codecs.html b/ffmpeg-n8.1/doc/ffmpeg-codecs.html new file mode 100644 index 00000000..b41a2fe9 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-codecs.html @@ -0,0 +1,8116 @@ + + + + + + + FFmpeg Codecs Documentation + + + + + + +
+

+ FFmpeg Codecs Documentation +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 Description

+ +

This document describes the codecs (decoders and encoders) provided by +the libavcodec library. +

+ + +

2 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 nonsensical 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVCodecContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follow: +

+
+
b integer (encoding,audio,video)
+

Set bitrate in bits/s. Default value is 200K. +

+
+
ab integer (encoding,audio)
+

Set audio bitrate (in bits/s). Default value is 128K. +

+
+
bt integer (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. +

+
+
flags flags (decoding/encoding,audio,video,subtitles)
+

Set generic flags. +

+

Possible values: +

+
‘mv4’
+

Use four motion vector by macroblock (mpeg4). +

+
‘qpel’
+

Use 1/4 pel motion compensation. +

+
‘loop’
+

Use loop filter. +

+
‘qscale’
+

Use fixed qscale. +

+
‘pass1’
+

Use internal 2pass ratecontrol in first pass mode. +

+
‘pass2’
+

Use internal 2pass ratecontrol in second pass mode. +

+
‘gray’
+

Only decode/encode grayscale. +

+
‘psnr’
+

Set error[?] variables during encoding. +

+
‘truncated’
+

Input bitstream might be randomly truncated. +

+
‘drop_changed’
+

Don’t output frames whose parameters differ from first decoded frame in stream. +Error AVERROR_INPUT_CHANGED is returned when a frame is dropped. +

+
+
‘ildct’
+

Use interlaced DCT. +

+
‘low_delay’
+

Force low delay. +

+
‘global_header’
+

Place global headers in extradata instead of every keyframe. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. (except (I)DCT). +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘aic’
+

Apply H263 advanced intra coding / mpeg4 ac prediction. +

+
‘ilme’
+

Apply interlaced motion estimation. +

+
‘cgop’
+

Use closed gop. +

+
‘output_corrupt’
+

Output even potentially corrupted frames. +

+
+ +
+
time_base 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 / frame_rate and timestamp increments should be +identically 1. +

+
+
g integer (encoding,video)
+

Set the group of picture (GOP) size. Default value is 12. +

+
+
ar integer (decoding/encoding,audio)
+

Set audio sampling rate (in Hz). +

+
+
ac integer (decoding/encoding,audio)
+

Set number of audio channels. +

+
+
cutoff integer (encoding,audio)
+

Set cutoff bandwidth. (Supported only by selected encoders, see +their respective documentation sections.) +

+
+
frame_size integer (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. +

+
+
frame_number integer
+

Set the frame number. +

+
+
delay integer
+
qcomp float (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. +

+
+
qblur float (encoding,video)
+

Set video quantizer scale blur (VBR). +

+
+
qmin integer (encoding,video)
+

Set min video quantizer scale (VBR). Must be included between -1 and +69, default value is 2. +

+
+
qmax integer (encoding,video)
+

Set max video quantizer scale (VBR). Must be included between -1 and +1024, default value is 31. +

+
+
qdiff integer (encoding,video)
+

Set max difference between the quantizer scale (VBR). +

+
+
bf integer (encoding,video)
+

Set max number of B frames between non-B-frames. +

+

Must be an integer between -1 and 16. 0 means that B-frames are +disabled. If a value of -1 is used, it will choose an automatic value +depending on the encoder. +

+

Default value is 0. +

+
+
b_qfactor float (encoding,video)
+

Set qp factor between P and B frames. +

+
+
codec_tag integer
+
bug flags (decoding,video)
+

Workaround not auto detected encoder bugs. +

+

Possible values: +

+
‘autodetect’
+
‘xvid_ilace’
+

Xvid interlacing bug (autodetected if fourcc==XVIX) +

+
‘ump4’
+

(autodetected if fourcc==UMP4) +

+
‘no_padding’
+

padding bug (autodetected) +

+
‘amv’
+
‘qpel_chroma’
+
‘std_qpel’
+

old standard qpel (autodetected per fourcc/version) +

+
‘qpel_chroma2’
+
‘direct_blocksize’
+

direct-qpel-blocksize bug (autodetected per fourcc/version) +

+
‘edge’
+

edge padding bug (autodetected per fourcc/version) +

+
‘hpel_chroma’
+
‘dc_clip’
+
‘ms’
+

Workaround various bugs in microsoft broken decoders. +

+
‘trunc’
+

trancated frames +

+
+ +
+
strict integer (decoding/encoding,audio,video)
+

Specify how strictly to follow the standards. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
b_qoffset float (encoding,video)
+

Set QP offset between P and B frames. +

+
+
err_detect flags (decoding,audio,video)
+

Set error detection flags. +

+

Possible values: +

+
‘crccheck’
+

verify embedded CRCs +

+
‘bitstream’
+

detect bitstream specification deviations +

+
‘buffer’
+

detect improper bitstream length +

+
‘explode’
+

abort decoding on minor error detection +

+
‘ignore_err’
+

ignore decoding errors, and continue decoding. +This is useful if you want to analyze the content of a video and thus want +everything to be decoded no matter what. This option will not result in a video +that is pleasing to watch in case of errors. +

+
‘careful’
+

consider things that violate the spec and have not been seen in the wild as errors +

+
‘compliant’
+

consider all spec non compliancies as errors +

+
‘aggressive’
+

consider things that a sane encoder should not do as an error +

+
+ +
+
has_b_frames integer
+
block_align integer
+
rc_override_count integer
+
maxrate integer (encoding,audio,video)
+

Set max bitrate tolerance (in bits/s). Requires bufsize to be set. +

+
+
minrate integer (encoding,audio,video)
+

Set min bitrate tolerance (in bits/s). Most useful in setting up a CBR +encode. It is of little use elsewise. +

+
+
bufsize integer (encoding,audio,video)
+

Set ratecontrol buffer size (in bits). +

+
+
i_qfactor float (encoding,video)
+

Set QP factor between P and I frames. +

+
+
i_qoffset float (encoding,video)
+

Set QP offset between P and I frames. +

+
+
dct integer (encoding,video)
+

Set DCT algorithm. +

+

Possible values: +

+
‘auto’
+

autoselect a good one (default) +

+
‘fastint’
+

fast integer +

+
‘int’
+

accurate integer +

+
‘mmx’
+
‘altivec’
+
‘faan’
+

floating point AAN DCT +

+
+ +
+
lumi_mask float (encoding,video)
+

Compress bright areas stronger than medium ones. +

+
+
tcplx_mask float (encoding,video)
+

Set temporal complexity masking. +

+
+
scplx_mask float (encoding,video)
+

Set spatial complexity masking. +

+
+
p_mask float (encoding,video)
+

Set inter masking. +

+
+
dark_mask float (encoding,video)
+

Compress dark areas stronger than medium ones. +

+
+
idct integer (decoding/encoding,video)
+

Select IDCT implementation. +

+

Possible values: +

+
‘auto’
+
‘int’
+
‘simple’
+
‘simplemmx’
+
‘simpleauto’
+

Automatically pick a IDCT compatible with the simple one +

+
+
‘arm’
+
‘altivec’
+
‘sh4’
+
‘simplearm’
+
‘simplearmv5te’
+
‘simplearmv6’
+
‘simpleneon’
+
‘xvid’
+
‘faani’
+

floating point AAN IDCT +

+
+ +
+
slice_count integer
+
ec flags (decoding,video)
+

Set error concealment strategy. +

+

Possible values: +

+
‘guess_mvs’
+

iterative motion vector (MV) search (slow) +

+
‘deblock’
+

use strong deblock filter for damaged MBs +

+
‘favor_inter’
+

favor predicting from the previous frame instead of the current +

+
+ +
+
bits_per_coded_sample integer
+
aspect rational number (encoding,video)
+

Set sample aspect ratio. +

+
+
sar rational number (encoding,video)
+

Set sample aspect ratio. Alias to aspect. +

+
+
debug flags (decoding/encoding,audio,video,subtitles)
+

Print specific debug info. +

+

Possible values: +

+
‘pict’
+

picture info +

+
‘rc’
+

rate control +

+
‘bitstream’
+
‘mb_type’
+

macroblock (MB) type +

+
‘qp’
+

per-block quantization parameter (QP) +

+
‘dct_coeff’
+
‘green_metadata’
+

display complexity metadata for the upcoming frame, GoP or for a given duration. +

+
+
‘skip’
+
‘startcode’
+
‘er’
+

error recognition +

+
‘mmco’
+

memory management control operations (H.264) +

+
‘bugs’
+
‘buffers’
+

picture buffer allocations +

+
‘thread_ops’
+

threading operations +

+
‘nomc’
+

skip motion compensation +

+
+ +
+
cmp integer (encoding,video)
+

Set full pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
subcmp integer (encoding,video)
+

Set sub pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
mbcmp integer (encoding,video)
+

Set macroblock compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
ildctcmp integer (encoding,video)
+

Set interlaced dct compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation. +

+
‘(1024, INT_MAX)’
+

full motion estimation(slowest) +

+
‘(768, 1024]’
+

umh motion estimation +

+
‘(512, 768]’
+

hex motion estimation +

+
‘(256, 512]’
+

l2s diamond motion estimation +

+
‘[2,256]’
+

var diamond motion estimation +

+
‘(-1, 2)’
+

small diamond motion estimation +

+
‘-1’
+

funny diamond motion estimation +

+
‘(INT_MIN, -1)’
+

sab diamond motion estimation +

+
+ +
+
last_pred integer (encoding,video)
+

Set amount of motion predictors from the previous frame. +

+
+
precmp integer (encoding,video)
+

Set pre motion estimation compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
pre_dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation pre-pass. +

+
+
subq integer (encoding,video)
+

Set sub pel motion estimation quality. +

+
+
me_range integer (encoding,video)
+

Set limit motion vectors range (1023 for DivX player). +

+
+
global_quality integer (encoding,audio,video)
+
slice_flags integer
+
mbd integer (encoding,video)
+

Set macroblock decision algorithm (high quality mode). +

+

Possible values: +

+
‘simple’
+

use mbcmp (default) +

+
‘bits’
+

use fewest bits +

+
‘rd’
+

use best rate distortion +

+
+ +
+
rc_init_occupancy integer (encoding,video)
+

Set number of bits which should be loaded into the rc buffer before +decoding starts. +

+
+
flags2 flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘fast’
+

Allow non spec compliant speedup tricks. +

+
‘noout’
+

Skip bitstream encoding. +

+
‘ignorecrop’
+

Ignore cropping information from sps. +

+
‘local_header’
+

Place global headers at every keyframe instead of in extradata. +

+
‘chunks’
+

Frame data might be split into multiple chunks. +

+
‘showall’
+

Show all frames before the first keyframe. +

+
‘export_mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘skip_manual’
+

Do not skip samples and export skip information as frame side data. +

+
‘ass_ro_flush_noop’
+

Do not reset ASS ReadOrder field on flush. +

+
‘icc_profiles’
+

Generate/parse embedded ICC profiles from/to colorimetry tags. +

+
+ +
+
export_side_data flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘prft’
+

Export encoder Producer Reference Time into packet side-data (see AV_PKT_DATA_PRFT) +for codecs that support it. +

+
‘venc_params’
+

Export video encoding parameters through frame side data (see AV_FRAME_DATA_VIDEO_ENC_PARAMS) +for codecs that support it. At present, those are H.264 and VP9. +

+
‘film_grain’
+

Export film grain parameters through frame side data (see AV_FRAME_DATA_FILM_GRAIN_PARAMS). +Supported at present by AV1 decoders. +

+
‘enhancements’
+

Export picture enhancement metadata through frame side data, e.g. LCEVC (see AV_FRAME_DATA_LCEVC). +

+
+ +
+
threads integer (decoding/encoding,video)
+

Set the number of threads to be used, in case the selected codec +implementation supports multi-threading. +

+

Possible values: +

+
‘auto, 0’
+

automatically select the number of threads to set +

+
+ +

Default value is ‘auto’. +

+
+
dc integer (encoding,video)
+

Set intra_dc_precision. +

+
+
nssew integer (encoding,video)
+

Set nsse weight. +

+
+
skip_top integer (decoding,video)
+

Set number of macroblock rows at the top which are skipped. +

+
+
skip_bottom integer (decoding,video)
+

Set number of macroblock rows at the bottom which are skipped. +

+
+
profile integer (encoding,audio,video)
+
+

Set encoder codec profile. Default value is ‘unknown’. Encoder specific +profiles are documented in the relevant encoder documentation. +

+
+
level integer (encoding,audio,video)
+
+

Set the encoder level. This level depends on the specific codec, and +might correspond to the profile level. It is set by default to +‘unknown’. +

+

Possible values: +

+
‘unknown’
+
+ +
+
lowres integer (decoding,audio,video)
+

Decode at 1= 1/2, 2=1/4, 3=1/8 resolutions. +

+
+
mblmin integer (encoding,video)
+

Set min macroblock lagrange factor (VBR). +

+
+
mblmax integer (encoding,video)
+

Set max macroblock lagrange factor (VBR). +

+
+
skip_loop_filter integer (decoding,video)
+
skip_idct integer (decoding,video)
+
skip_frame integer (decoding,video)
+
+

Make decoder discard processing depending on the frame type selected +by the option value. +

+

skip_loop_filter skips frame loop filtering, skip_idct +skips frame IDCT/dequantization, skip_frame skips decoding. +

+

Possible values: +

+
‘none’
+

Discard no frame. +

+
+
‘default’
+

Discard useless frames like 0-sized frames. +

+
+
‘noref’
+

Discard all non-reference frames. +

+
+
‘bidir’
+

Discard all bidirectional frames. +

+
+
‘nokey’
+

Discard all frames excepts keyframes. +

+
+
‘nointra’
+

Discard all frames except I frames. +

+
+
‘all’
+

Discard all frames. +

+
+ +

Default value is ‘default’. +

+
+
bidir_refine integer (encoding,video)
+

Refine the two motion vectors used in bidirectional macroblocks. +

+
+
keyint_min integer (encoding,video)
+

Set minimum interval between IDR-frames. +

+
+
refs integer (encoding,video)
+

Set reference frames to consider for motion compensation. +

+
+
trellis integer (encoding,audio,video)
+

Set rate-distortion optimal quantization. +

+
+
mv0_threshold integer (encoding,video)
+
compression_level integer (encoding,audio,video)
+
bits_per_raw_sample integer
+
channel_layout integer (decoding/encoding,audio)
+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
rc_max_vbv_use float (encoding,video)
+
rc_min_vbv_use float (encoding,video)
+
color_primaries integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘bt470m’
+

BT.470 M +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘film’
+

Film +

+
‘bt2020’
+

BT.2020 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘smpte431’
+

SMPTE 431-2 +

+
‘smpte432’
+

SMPTE 432-1 +

+
‘jedec-p22’
+

JEDEC P22 +

+
+ +
+
color_trc integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘gamma22’
+

BT.470 M +

+
‘gamma28’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘linear’
+

Linear +

+
‘log’
+
‘log100’
+

Log +

+
‘log_sqrt’
+
‘log316’
+

Log square root +

+
‘iec61966_2_4’
+
‘iec61966-2-4’
+

IEC 61966-2-4 +

+
‘bt1361’
+
‘bt1361e’
+

BT.1361 +

+
‘iec61966_2_1’
+
‘iec61966-2-1’
+

IEC 61966-2-1 +

+
‘bt2020_10’
+
‘bt2020_10bit’
+

BT.2020 - 10 bit +

+
‘bt2020_12’
+
‘bt2020_12bit’
+

BT.2020 - 12 bit +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ +
+
colorspace integer (decoding/encoding,video)
+

Possible values: +

+
‘rgb’
+

RGB +

+
‘bt709’
+

BT.709 +

+
‘fcc’
+

FCC +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘ycocg’
+

YCOCG +

+
‘bt2020nc’
+
‘bt2020_ncl’
+

BT.2020 NCL +

+
‘bt2020c’
+
‘bt2020_cl’
+

BT.2020 CL +

+
‘smpte2085’
+

SMPTE 2085 +

+
‘chroma-derived-nc’
+

Chroma-derived NCL +

+
‘chroma-derived-c’
+

Chroma-derived CL +

+
‘ictcp’
+

ICtCp +

+
+ +
+
color_range integer (decoding/encoding,video)
+

If used as input parameter, it serves as a hint to the decoder, which +color_range the input has. +Possible values: +

+
‘tv’
+
‘mpeg’
+
‘limited’
+

MPEG (219*2^(n-8)) +

+
‘pc’
+
‘jpeg’
+
‘full’
+

JPEG (2^n-1) +

+
+ +
+
chroma_sample_location integer (decoding/encoding,video)
+

Possible values: +

+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode integer (decoding/encoding,video)
+

Possible values: +

+
‘premultiplied’
+
‘straight’
+
+ + +
+
log_level_offset integer
+

Set the log level offset. +

+
+
slices integer (encoding,video)
+

Number of slices, used in parallelized encoding. +

+
+
thread_type flags (decoding/encoding,video)
+

Select which multithreading methods to use. +

+

Use of ‘frame’ will increase decoding delay by one frame per +thread, so clients which cannot provide future frames should not use +it. +

+

Possible values: +

+
‘slice’
+

Decode more than one part of a single frame at once. +

+

Multithreading using slices works only when the video was encoded with +slices. +

+
+
‘frame’
+

Decode more than one frame at once. +

+
+ +

Default value is ‘slice+frame’. +

+
+
audio_service_type integer (encoding,audio)
+

Set audio service type. +

+

Possible values: +

+
‘ma’
+

Main Audio Service +

+
‘ef’
+

Effects +

+
‘vi’
+

Visually Impaired +

+
‘hi’
+

Hearing Impaired +

+
‘di’
+

Dialogue +

+
‘co’
+

Commentary +

+
‘em’
+

Emergency +

+
‘vo’
+

Voice Over +

+
‘ka’
+

Karaoke +

+
+ +
+
request_sample_fmt sample_fmt (decoding,audio)
+

Set sample format audio decoders should prefer. Default value is +none. +

+
+
pkt_timebase rational number
+
sub_charenc encoding (decoding,subtitles)
+

Set the input subtitles character encoding. +

+
+
field_order field_order (video)
+

Set/override the field order of the video. +Possible values: +

+
‘progressive’
+

Progressive video +

+
‘tt’
+

Interlaced video, top field coded and displayed first +

+
‘bb’
+

Interlaced video, bottom field coded and displayed first +

+
‘tb’
+

Interlaced video, top coded first, bottom displayed first +

+
‘bt’
+

Interlaced video, bottom coded first, top displayed first +

+
+ +
+
skip_alpha bool (decoding,video)
+

Set to 1 to disable processing alpha (transparency). This works like the +‘gray’ flag in the flags option which skips chroma information +instead of alpha. Default is 0. +

+
+
codec_whitelist list (input)
+

"," separated list of allowed decoders. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_pixels integer (decoding/encoding,video)
+

Maximum number of pixels per image. This value can be used to avoid out of +memory failures due to large images. +

+
+
apply_cropping bool (decoding,video)
+

Enable cropping if cropping parameters are multiples of the required +alignment for the left and top parameters. If the alignment is not met the +cropping will be partially applied to maintain alignment. +Default is 1 (enabled). +Note: The required alignment depends on if AV_CODEC_FLAG_UNALIGNED is set and the +CPU. AV_CODEC_FLAG_UNALIGNED cannot be changed from the command line. Also hardware +decoders will not apply left/top Cropping. +

+ +
+
+ + + +

3 Decoders

+ +

Decoders are configured elements in FFmpeg which allow the decoding of +multimedia streams. +

+

When you configure your FFmpeg build, all the supported native decoders +are enabled by default. Decoders requiring an external library must be enabled +manually via the corresponding --enable-lib option. You can list all +available decoders using the configure option --list-decoders. +

+

You can disable all the decoders with the configure option +--disable-decoders and selectively enable / disable single decoders +with the options --enable-decoder=DECODER / +--disable-decoder=DECODER. +

+

The option -decoders of the ff* tools will display the list of +enabled decoders. +

+ + +

4 Video Decoders

+ +

A description of some of the currently available video decoders +follows. +

+ +

4.1 av1

+ +

AOMedia Video 1 (AV1) decoder. +

+ +

4.1.1 Options

+ +
+
operating_point
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Default is 0. +

+
+
+ + +

4.2 hevc

+

HEVC (AKA ITU-T H.265 or ISO/IEC 23008-2) decoder. +

+

The decoder supports MV-HEVC multiview streams with at most two views. Views to +be output are selected by supplying a list of view IDs to the decoder (the +view_ids option). This option may be set either statically before +decoder init, or from the get_format() callback - useful for the case +when the view count or IDs change dynamically during decoding. +

+

Only the base layer is decoded by default. +

+

Note that if you are using the ffmpeg CLI tool, you should be using view +specifiers as documented in its manual, rather than the options documented here. +

+ +

4.2.1 Options

+ +
+
view_ids (MV-HEVC)
+

Specify a list of view IDs that should be output. This option can also be set to +a single ’-1’, which will cause all views defined in the VPS to be decoded and +output. +

+
+
view_ids_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view IDs available +in the active VPS. The array is empty for single-layer video. +

+

The value of this option is guaranteed to be accurate when read from the +get_format() callback. It may also be set at other times (e.g. after +opening the decoder), but the value is informational only and may be incorrect +(e.g. when the stream contains multiple distinct VPS NALUs). +

+
+
view_pos_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view positions +(left, right, or unspecified) available in the active VPS, as +AVStereo3DView values. When the array is available, its elements apply to +the corresponding elements of view_ids_available, i.e. +view_pos_available[i] contains the position of view with ID +view_ids_available[i]. +

+

Same validity restrictions as for view_ids_available apply to +this option. +

+
+
+ + +

4.3 rawvideo

+ +

Raw video decoder. +

+

This decoder decodes rawvideo streams. +

+ +

4.3.1 Options

+ +
+
top top_field_first
+

Specify the assumed field type of the input video. +

+
-1
+

the video is assumed to be progressive (default) +

+
0
+

bottom-field-first is assumed +

+
1
+

top-field-first is assumed +

+
+ +
+
+ + +

4.4 libdav1d

+ +

dav1d AV1 decoder. +

+

libdav1d allows libavcodec to decode the AOMedia Video 1 (AV1) codec. +Requires the presence of the libdav1d headers and library during configuration. +You need to explicitly configure the build with --enable-libdav1d. +

+ +

4.4.1 Options

+ +

The following options are supported by the libdav1d wrapper. +

+
+
max_frame_delay
+

Set max amount of frames the decoder may buffer internally. The default value is 0 +(autodetect). +

+
+
filmgrain
+

Apply film grain to the decoded video if present in the bitstream. Defaults to the +internal default of the library. +This option is deprecated and will be removed in the future. See the global option +export_side_data to export Film Grain parameters instead of applying it. +

+
+
oppoint
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Defaults to the +internal default of the library. +

+
+
alllayers
+

Output all spatial layers of a scalable AV1 bitstream. The default value is false. +

+
+
+ + +

4.5 libdavs2

+ +

AVS2-P2/IEEE1857.4 video decoder wrapper. +

+

This decoder allows libavcodec to decode AVS2 streams with davs2 library. +

+ + +

4.6 libuavs3d

+ +

AVS3-P2/IEEE1857.10 video decoder. +

+

libuavs3d allows libavcodec to decode AVS3 streams. +Requires the presence of the libuavs3d headers and library during configuration. +You need to explicitly configure the build with --enable-libuavs3d. +

+ +

4.6.1 Options

+ +

The following option is supported by the libuavs3d wrapper. +

+
+
frame_threads
+

Set amount of frame threads to use during decoding. The default value is 0 (autodetect). +

+
+
+ + +

4.7 libxevd

+ +

eXtra-fast Essential Video Decoder (XEVD) MPEG-5 EVC decoder wrapper. +

+

This decoder requires the presence of the libxevd headers and library +during configuration. You need to explicitly configure the build with +--enable-libxevd. +

+

The xevd project website is at https://github.com/mpeg5/xevd. +

+ +

4.7.1 Options

+ +

The following options are supported by the libxevd wrapper. +The xevd-equivalent options or values are listed in parentheses for easy migration. +

+

To get a more accurate and extensive documentation of the libxevd options, +invoke the command xevd_app --help or consult the libxevd documentation. +

+
+
threads (threads)
+

Force to use a specific number of threads +

+
+
+ + +

4.8 QSV Decoders

+ +

The family of Intel QuickSync Video decoders (VC1, MPEG-2, H.264, HEVC, +JPEG/MJPEG, VP8, VP9, AV1, VVC). +

+ +

4.8.1 Common Options

+ +

The following options are supported by all qsv decoders. +

+
+
async_depth
+

Internal parallelization depth, the higher the value the higher the latency. +

+
+
gpu_copy
+

A GPU-accelerated copy between video and system memory +

+
‘default’
+
‘on’
+
‘off’
+
+ +
+
+ + +

4.8.2 HEVC Options

+

Extra options for hevc_qsv. +

+
+
load_plugin
+

A user plugin to load in an internal session +

+
‘none’
+
‘hevc_sw’
+
‘hevc_hw’
+
+ +
+
load_plugins
+

A :-separate list of hexadecimal plugin UIDs to load in an internal session +

+
+
+ + +

4.9 v210

+ +

Uncompressed 4:2:2 10-bit decoder. +

+ +

4.9.1 Options

+ +
+
custom_stride
+

Set the line size of the v210 data in bytes. The default value is 0 +(autodetect). You can use the special -1 value for a strideless v210 as seen in +BOXX files. +

+
+
+ + + +

5 Audio Decoders

+ +

A description of some of the currently available audio decoders +follows. +

+ +

5.1 ac3

+ +

AC-3 audio decoder. +

+

This decoder implements part of ATSC A/52:2010 and ETSI TS 102 366, as well as +the undocumented RealAudio 3 (a.k.a. dnet). +

+ +

5.1.1 AC-3 Decoder Options

+ +
+
-drc_scale value
+

Dynamic Range Scale Factor. The factor to apply to dynamic range values +from the AC-3 stream. This factor is applied exponentially. The default value is 1. +There are 3 notable scale factor ranges: +

+
drc_scale == 0
+

DRC disabled. Produces full range audio. +

+
0 < drc_scale <= 1
+

DRC enabled. Applies a fraction of the stream DRC value. +Audio reproduction is between full range and full compression. +

+
drc_scale > 1
+

DRC enabled. Applies drc_scale asymmetrically. +Loud sounds are fully compressed. Soft sounds are enhanced. +

+
+ +
+
+ + +

5.2 flac

+ +

FLAC audio decoder. +

+

This decoder aims to implement the complete FLAC specification from Xiph. +

+ +

5.2.1 FLAC Decoder options

+ +
+
-use_buggy_lpc
+

The lavc FLAC encoder used to produce buggy streams with high lpc values +(like the default value). This option makes it possible to decode such streams +correctly by using lavc’s old buggy lpc logic for decoding. +

+
+
+ + +

5.3 ffwavesynth

+ +

Internal wave synthesizer. +

+

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. +

+ +

5.4 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 --enable-libcelt. +

+ +

5.5 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 --enable-libgsm. +

+

This decoder supports both the ordinary GSM and the Microsoft variant. +

+ +

5.6 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 +--enable-libilbc. +

+ +

5.6.1 Options

+ +

The following option is supported by the libilbc wrapper. +

+
+
enhance
+
+

Enable the enhancement of the decoded audio when set to 1. The default +value is 0 (disabled). +

+
+
+ + +

5.7 libmpeghdec

+ +

libmpeghdec decoder wrapper. +

+

libmpeghdec allows libmpeghdec to decode the MPEG-H 3D audio codec. +Requires the presence of the libmpeghdec headers and library during +configuration. You need to explicitly configure the build with +--enable-libmpeghdec --enable-nonfree. +

+ +

5.8 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 --enable-libopencore-amrnb. +

+

An FFmpeg native decoder for AMR-NB exists, so users can decode AMR-NB +without this library. +

+ +

5.9 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 --enable-libopencore-amrwb. +

+

An FFmpeg native decoder for AMR-WB exists, so users can decode AMR-WB +without this library. +

+ +

5.10 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 +--enable-libopus. +

+

An FFmpeg native decoder for Opus exists, so users can decode Opus +without this library. +

+ + +

6 Subtitles Decoders

+ + +

6.1 libaribb24

+ +

ARIB STD-B24 caption decoder. +

+

Implements profiles A and C of the ARIB STD-B24 standard. +

+ +

6.1.1 libaribb24 Decoder Options

+ +
+
-aribb24-base-path path
+

Sets the base path for the libaribb24 library. This is utilized for reading of +configuration files (for custom unicode conversions), and for dumping of +non-text symbols as images under that location. +

+

Unset by default. +

+
+
-aribb24-skip-ruby-text boolean
+

Tells the decoder wrapper to skip text blocks that contain half-height ruby +text. +

+

Enabled by default. +

+
+
+ + +

6.2 libaribcaption

+ +

Yet another ARIB STD-B24 caption decoder using external libaribcaption +library. +

+

Implements profiles A and C of the Japanese ARIB STD-B24 standard, +Brazilian ABNT NBR 15606-1, and Philippines version of ISDB-T. +

+

Requires the presence of the libaribcaption headers and library +(https://github.com/xqq/libaribcaption) during configuration. +You need to explicitly configure the build with --enable-libaribcaption. +If both libaribb24 and libaribcaption are enabled, libaribcaption +decoder precedes. +

+ +

6.2.1 libaribcaption Decoder Options

+ +
+
-sub_type subtitle_type
+

Specifies the format of the decoded subtitles. +

+
+
‘bitmap’
+

Graphical image. +

+
‘ass’
+

ASS formatted text. +

+
‘text’
+

Simple text based output without formatting. +

+
+ +

The default is ass as same as libaribb24 decoder. +Some present players (e.g., mpv) expect ASS format for ARIB caption. +

+
+
-caption_encoding encoding_scheme
+

Specifies the encoding scheme of input subtitle text. +

+
+
‘auto’
+

Automatically detect text encoding (default). +

+
‘jis’
+

8bit-char JIS encoding defined in ARIB STD B24. +This encoding used in Japan for ISDB captions. +

+
‘utf8’
+

UTF-8 encoding defined in ARIB STD B24. +This encoding is used in Philippines for ISDB-T captions. +

+
‘latin’
+

Latin character encoding defined in ABNT NBR 15606-1. +This encoding is used in South America for SBTVD / ISDB-Tb captions. +

+
+ +
+
-font font_name[,font_name2,...]
+

Specify comma-separated list of font family names to be used for bitmap +or ass type subtitle rendering. +Only first font name is used for ass type subtitle. +

+

If not specified, use internally defined default font family. +

+
+
-ass_single_rect boolean
+

ARIB STD-B24 specifies that some captions may be displayed at different +positions at a time (multi-rectangle subtitle). +Since some players (e.g., old mpv) can’t handle multiple ASS rectangles +in a single AVSubtitle, or multiple ASS rectangles of indeterminate duration +with the same start timestamp, this option can change the behavior so that +all the texts are displayed in a single ASS rectangle. +

+

The default is false. +

+

If your player cannot handle AVSubtitles with multiple ASS rectangles properly, +set this option to true or define ASS_SINGLE_RECT=1 to change +default behavior at compilation. +

+
+
-force_outline_text boolean
+

Specify whether always render outline text for all characters regardless of +the indication by character style. +

+

The default is false. +

+
+
-outline_width number (0.0 - 3.0)
+

Specify width for outline text, in dots (relative). +

+

The default is 1.5. +

+
+
-ignore_background boolean
+

Specify whether to ignore background color rendering. +

+

The default is false. +

+
+
-ignore_ruby boolean
+

Specify whether to ignore rendering for ruby-like (furigana) characters. +

+

The default is false. +

+
+
-replace_drcs boolean
+

Specify whether to render replaced DRCS characters as Unicode characters. +

+

The default is true. +

+
+
-replace_msz_ascii boolean
+

Specify whether to replace MSZ (Middle Size; half width) fullwidth +alphanumerics with halfwidth alphanumerics. +

+

The default is true. +

+
+
-replace_msz_japanese boolean
+

Specify whether to replace some MSZ (Middle Size; half width) fullwidth +japanese special characters with halfwidth ones. +

+

The default is true. +

+
+
-replace_msz_glyph boolean
+

Specify whether to replace MSZ (Middle Size; half width) characters +with halfwidth glyphs if the fonts supports it. +This option works under FreeType or DirectWrite renderer +with Adobe-Japan1 compliant fonts. +e.g., IBM Plex Sans JP, Morisawa BIZ UDGothic, Morisawa BIZ UDMincho, +Yu Gothic, Yu Mincho, and Meiryo. +

+

The default is true. +

+
+
-canvas_size image_size
+

Specify the resolution of the canvas to render subtitles to; usually, this +should be frame size of input video. +This only applies when -subtitle_type is set to bitmap. +

+

The libaribcaption decoder assumes input frame size for bitmap rendering as below: +

    +
  1. PROFILE_A : 1440 x 1080 with SAR (PAR) 4:3 +
  2. PROFILE_C : 320 x 180 with SAR (PAR) 1:1 +
+ +

If actual frame size of input video does not match above assumption, +the rendered captions may be distorted. +To make the captions undistorted, add -canvas_size option to specify +actual input video size. +

+

Note that the -canvas_size option is not required for video with +different size but same aspect ratio. +In such cases, the caption will be stretched or shrunk to actual video size +if -canvas_size option is not specified. +If -canvas_size option is specified with different size, +the caption will be stretched or shrunk as specified size with calculated SAR. +

+
+
+ + +

6.2.2 libaribcaption decoder usage examples

+ +

Display MPEG-TS file with ARIB subtitle by ffplay tool: +

+
ffplay -sub_type bitmap MPEG.TS
+
+ +

Display MPEG-TS file with input frame size 1920x1080 by ffplay tool: +

+
ffplay -sub_type bitmap -canvas_size 1920x1080 MPEG.TS
+
+ +

Embed ARIB subtitle in transcoded video: +

+
ffmpeg -sub_type bitmap -i src.m2t -filter_complex "[0:v][0:s]overlay" -vcodec h264 dest.mp4
+
+ + +

6.3 dvbsub

+ + +

6.3.1 Options

+ +
+
compute_clut
+
+
-2
+

Compute clut once if no matching CLUT is in the stream. +

+
-1
+

Compute clut if no matching CLUT is in the stream. +

+
0
+

Never compute CLUT +

+
1
+

Always compute CLUT and override the one provided in the stream. +

+
+
+
dvb_substream
+

Selects the dvb substream, or all substreams if -1 which is default. +

+
+
+ + +

6.4 dvdsub

+ +

This codec decodes the bitmap subtitles used in DVDs; the same subtitles can +also be found in VobSub file pairs and in some Matroska files. +

+ +

6.4.1 Options

+ +
+
palette
+

Specify the global palette used by the bitmaps. When stored in VobSub, the +palette is normally specified in the index file; in Matroska, the palette is +stored in the codec extra-data in the same format as in VobSub. In DVDs, the +palette is stored in the IFO file, and therefore not available when reading +from dumped VOB files. +

+

The format for this option is a string containing 16 24-bits hexadecimal +numbers (without 0x prefix) separated by commas, for example 0d00ee, +ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, +7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b. +

+
+
ifo_palette
+

Specify the IFO file from which the global palette is obtained. +(experimental) +

+
+
forced_subs_only
+

Only decode subtitle entries marked as forced. Some titles have forced +and non-forced subtitles in the same track. Setting this flag to 1 +will only keep the forced subtitles. Default value is 0. +

+
+ + +

6.5 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 +--enable-libzvbi. +

+ +

6.5.1 Options

+ +
+
txt_page
+

List of teletext page numbers to decode. Pages that do not match the specified +list are dropped. You may use the special * string to match all pages, +or subtitle to match all subtitle pages. +Default value is *. +

+
txt_default_region
+

Set default character set used for decoding, a value between 0 and 87 (see +ETS 300 706, Section 15, Table 32). Default value is -1, which does not +override the libzvbi default. This option is needed for some legacy level 1.0 +transmissions which cannot signal the proper charset. +

+
txt_chop_top
+

Discards the top teletext line. Default value is 1. +

+
txt_format
+

Specifies the format of the decoded subtitles. +

+
bitmap
+

The default format, you should use this for teletext pages, because certain +graphics and colors cannot be expressed in simple text or even ASS. +

+
text
+

Simple text based output without formatting. +

+
ass
+

Formatted ASS output, subtitle pages and teletext pages are returned in +different styles, subtitle pages are stripped down to text, but an effort is +made to keep the text alignment and the formatting. +

+
+
+
txt_left
+

X offset of generated bitmaps, default is 0. +

+
txt_top
+

Y offset of generated bitmaps, default is 0. +

+
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 characters. +Default value is 1. +

+
txt_duration
+

Sets the display duration of the decoded teletext pages or subtitles in +milliseconds. Default value is -1 which means infinity or until the next +subtitle event comes. +

+
txt_transparent
+

Force transparent background of the generated teletext bitmaps. Default value +is 0 which means an opaque background. +

+
txt_opacity
+

Sets the opacity (0-255) of the teletext background. If +txt_transparent is not set, it only affects characters between a start +box and an end box, typically subtitles. Default value is 0 if +txt_transparent is set, 255 otherwise. +

+
+
+ + +

7 Encoders

+ +

Encoders are configured elements in FFmpeg which allow the encoding of +multimedia streams. +

+

When you configure your FFmpeg build, all the supported native encoders +are enabled by default. Encoders requiring an external library must be enabled +manually via the corresponding --enable-lib option. You can list all +available encoders using the configure option --list-encoders. +

+

You can disable all the encoders with the configure option +--disable-encoders and selectively enable / disable single encoders +with the options --enable-encoder=ENCODER / +--disable-encoder=ENCODER. +

+

The option -encoders of the ff* tools will display the list of +enabled encoders. +

+ + +

8 Audio Encoders

+ +

A description of some of the currently available audio encoders +follows. +

+ +

8.1 aac

+ +

Advanced Audio Coding (AAC) encoder. +

+

This encoder is the default AAC encoder, natively implemented into FFmpeg. +

+ +

8.1.1 Options

+ +
+
b
+

Set bit rate in bits/s. Setting this automatically activates constant bit rate +(CBR) mode. If this option is unspecified it is set to 128kbps. +

+
+
q
+

Set quality for variable bit rate (VBR) mode. This option is valid only using +the ffmpeg command-line tool. For library interface users, use +global_quality. +

+
+
cutoff
+

Set cutoff frequency. If unspecified will allow the encoder to dynamically +adjust the cutoff to improve clarity on low bitrates. +

+
+
aac_coder
+

Set AAC encoder coding method. Possible values: +

+
+
‘twoloop’
+

Two loop searching (TLS) method. This is the default 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. Will tune +itself based on whether aac_is, aac_ms and aac_pns +are enabled. +

+
+
‘anmr’
+

Average noise to mask ratio (ANMR) trellis-based solution. +

+

This is an experimental coder which currently produces a lower quality, is more +unstable and is slower than the default twoloop coder but has potential. +Currently has no support for the aac_is or aac_pns options. +Not currently recommended. +

+
+
‘fast’
+

Constant quantizer method. +

+

Uses a cheaper version of twoloop algorithm that doesn’t try to do as many +clever adjustments. Worse with low bitrates (less than 64kbps), but is better +and much faster at higher bitrates. +

+
+
+ +
+
aac_ms
+

Sets mid/side coding mode. The default value of "auto" will automatically use +M/S with bands which will benefit from such coding. Can be forced for all bands +using the value "enable", which is mainly useful for debugging or disabled using +"disable". +

+
+
aac_is
+

Sets intensity stereo coding tool usage. By default, it’s enabled and will +automatically toggle IS for similar pairs of stereo bands if it’s beneficial. +Can be disabled for debugging by setting the value to "disable". +

+
+
aac_pns
+

Uses perceptual noise substitution to replace low entropy high frequency bands +with imperceptible white noise during the decoding process. By default, it’s +enabled, but can be disabled for debugging purposes by using "disable". +

+
+
aac_tns
+

Enables the use of a multitap FIR filter which spans through the high frequency +bands to hide quantization noise during the encoding process and is reverted +by the decoder. As well as decreasing unpleasant artifacts in the high range +this also reduces the entropy in the high bands and allows for more bits to +be used by the mid-low bands. By default it’s enabled but can be disabled for +debugging by setting the option to "disable". +

+
+
aac_ltp
+

Enables the use of the long term prediction extension which increases coding +efficiency in very low bandwidth situations such as encoding of voice or +solo piano music by extending constant harmonic peaks in bands throughout +frames. This option is implied by profile:a aac_low. +Use in conjunction with -ar to decrease the samplerate. +

+
+
profile
+

Sets the encoding profile, possible values: +

+
+
‘aac_low’
+

The default, AAC "Low-complexity" profile. Is the most compatible and produces +decent quality. +

+
+
‘mpeg2_aac_low’
+

Equivalent to -profile:a aac_low -aac_pns 0. PNS was introduced with the +MPEG4 specifications. +

+
+
‘aac_ltp’
+

Long term prediction profile, is enabled by and will enable the aac_ltp +option. Introduced in MPEG4. +

+
+
+

If this option is unspecified it is set to ‘aac_low’. +

+
+ + +

8.2 ac3 and ac3_fixed

+ +

AC-3 audio encoders. +

+

These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366. +

+

The ac3 encoder uses floating-point math, while the ac3_fixed +encoder only uses fixed-point integer math. This does not mean that one is +always faster, just that one or the other may be better suited to a +particular system. The ac3_fixed encoder is not the default codec for +any of the output formats, so it must be specified explicitly using the option +-acodec ac3_fixed in order to use it. +

+ +

8.2.1 AC-3 Metadata

+ +

The AC-3 metadata options are used to set parameters that describe the audio, +but in most cases do not affect the audio encoding itself. Some of the options +do directly affect or influence the decoding and playback of the resulting +bitstream, while others are just for informational purposes. A few of the +options will add bits to the output stream that could otherwise be used for +audio data, and will thus affect the quality of the output. Those will be +indicated accordingly with a note in the option list below. +

+

These parameters are described in detail in several publicly-available +documents. +

+ + +

8.2.1.1 Metadata Control Options

+ +
+
-per_frame_metadata boolean
+

Allow Per-Frame Metadata. Specifies if the encoder should check for changing +metadata for each frame. +

+
0
+

The metadata values set at initialization will be used for every frame in the +stream. (default) +

+
1
+

Metadata values can be changed before encoding each frame. +

+
+ +
+
+ + +

8.2.1.2 Downmix Levels

+ +
+
-center_mixlev level
+

Center Mix Level. The amount of gain the decoder should apply to the center +channel when downmixing to stereo. This field will only be written to the +bitstream if a center channel is present. The value is specified as a scale +factor. There are 3 valid values: +

+
0.707
+

Apply -3dB gain +

+
0.595
+

Apply -4.5dB gain (default) +

+
0.500
+

Apply -6dB gain +

+
+ +
+
-surround_mixlev level
+

Surround Mix Level. The amount of gain the decoder should apply to the surround +channel(s) when downmixing to stereo. This field will only be written to the +bitstream if one or more surround channels are present. The value is specified +as a scale factor. There are 3 valid values: +

+
0.707
+

Apply -3dB gain +

+
0.500
+

Apply -6dB gain (default) +

+
0.000
+

Silence Surround Channel(s) +

+
+ +
+
+ + +

8.2.1.3 Audio Production Information

+

Audio Production Information is optional information describing the mixing +environment. Either none or both of the fields are written to the bitstream. +

+
+
-mixing_level number
+

Mixing Level. Specifies peak sound pressure level (SPL) in the production +environment when the mix was mastered. Valid values are 80 to 111, or -1 for +unknown or not indicated. The default value is -1, but that value cannot be +used if the Audio Production Information is written to the bitstream. Therefore, +if the room_type option is not the default value, the mixing_level +option must not be -1. +

+
+
-room_type type
+

Room Type. Describes the equalization used during the final mixing session at +the studio or on the dubbing stage. A large room is a dubbing stage with the +industry standard X-curve equalization; a small room has flat equalization. +This field will not be written to the bitstream if both the mixing_level +option and the room_type option have the default values. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
large
+

Large Room +

+
2
+
small
+

Small Room +

+
+ +
+
+ + +

8.2.1.4 Other Metadata Options

+ +
+
-copyright boolean
+

Copyright Indicator. Specifies whether a copyright exists for this audio. +

+
0
+
off
+

No Copyright Exists (default) +

+
1
+
on
+

Copyright Exists +

+
+ +
+
-dialnorm value
+

Dialogue Normalization. Indicates how far the average dialogue level of the +program is below digital 100% full scale (0 dBFS). This parameter determines a +level shift during audio reproduction that sets the average volume of the +dialogue to a preset level. The goal is to match volume level between program +sources. A value of -31dB will result in no volume level change, relative to +the source volume, during audio reproduction. Valid values are whole numbers in +the range -31 to -1, with -31 being the default. +

+
+
-dsur_mode mode
+

Dolby Surround Mode. Specifies whether the stereo signal uses Dolby Surround +(Pro Logic). This field will only be written to the bitstream if the audio +stream is stereo. Using this option does NOT mean the encoder will actually +apply Dolby Surround processing. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
off
+

Not Dolby Surround Encoded +

+
2
+
on
+

Dolby Surround Encoded +

+
+ +
+
-original boolean
+

Original Bit Stream Indicator. Specifies whether this audio is from the +original source and not a copy. +

+
0
+
off
+

Not Original Source +

+
1
+
on
+

Original Source (default) +

+
+ +
+
+ + +

8.2.2 Extended Bitstream Information

+

The extended bitstream options are part of the Alternate Bit Stream Syntax as +specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts. +If any one parameter in a group is specified, all values in that group will be +written to the bitstream. Default values are used for those that are written +but have not been specified. If the mixing levels are written, the decoder +will use these values instead of the ones specified in the center_mixlev +and surround_mixlev options if it supports the Alternate Bit Stream +Syntax. +

+ +

8.2.2.1 Extended Bitstream Information - Part 1

+ +
+
-dmix_mode mode
+

Preferred Stereo Downmix Mode. Allows the user to select either Lt/Rt +(Dolby Surround) or Lo/Ro (normal stereo) as the preferred stereo downmix mode. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
ltrt
+

Lt/Rt Downmix Preferred +

+
2
+
loro
+

Lo/Ro Downmix Preferred +

+
+ +
+
-ltrt_cmixlev level
+

Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the +center channel when downmixing to stereo in Lt/Rt mode. +

+
1.414
+

Apply +3dB gain +

+
1.189
+

Apply +1.5dB gain +

+
1.000
+

Apply 0dB gain +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain (default) +

+
0.500
+

Apply -6.0dB gain +

+
0.000
+

Silence Center Channel +

+
+ +
+
-ltrt_surmixlev level
+

Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the +surround channel(s) when downmixing to stereo in Lt/Rt mode. +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain +

+
0.500
+

Apply -6.0dB gain (default) +

+
0.000
+

Silence Surround Channel(s) +

+
+ +
+
-loro_cmixlev level
+

Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the +center channel when downmixing to stereo in Lo/Ro mode. +

+
1.414
+

Apply +3dB gain +

+
1.189
+

Apply +1.5dB gain +

+
1.000
+

Apply 0dB gain +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain (default) +

+
0.500
+

Apply -6.0dB gain +

+
0.000
+

Silence Center Channel +

+
+ +
+
-loro_surmixlev level
+

Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the +surround channel(s) when downmixing to stereo in Lo/Ro mode. +

+
0.841
+

Apply -1.5dB gain +

+
0.707
+

Apply -3.0dB gain +

+
0.595
+

Apply -4.5dB gain +

+
0.500
+

Apply -6.0dB gain (default) +

+
0.000
+

Silence Surround Channel(s) +

+
+ +
+
+ + +

8.2.2.2 Extended Bitstream Information - Part 2

+ +
+
-dsurex_mode mode
+

Dolby Surround EX Mode. Indicates whether the stream uses Dolby Surround EX +(7.1 matrixed to 5.1). Using this option does NOT mean the encoder will actually +apply Dolby Surround EX processing. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
on
+

Dolby Surround EX Off +

+
2
+
off
+

Dolby Surround EX On +

+
+ +
+
-dheadphone_mode mode
+

Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone +encoding (multi-channel matrixed to 2.0 for use with headphones). Using this +option does NOT mean the encoder will actually apply Dolby Headphone +processing. +

+
0
+
notindicated
+

Not Indicated (default) +

+
1
+
on
+

Dolby Headphone Off +

+
2
+
off
+

Dolby Headphone On +

+
+ +
+
-ad_conv_type type
+

A/D Converter Type. Indicates whether the audio has passed through HDCD A/D +conversion. +

+
0
+
standard
+

Standard A/D Converter (default) +

+
1
+
hdcd
+

HDCD A/D Converter +

+
+ +
+
+ + +

8.2.3 Other AC-3 Encoding Options

+ +
+
-stereo_rematrixing boolean
+

Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This +is an optional AC-3 feature that increases quality by selectively encoding +the left/right channels as mid/side. This option is enabled by default, and it +is highly recommended that it be left as enabled except for testing purposes. +

+
+
cutoff frequency
+

Set lowpass cutoff frequency. If unspecified, the encoder selects a default +determined by various other encoding parameters. +

+
+
+ + +

8.2.4 Floating-Point-Only AC-3 Encoding Options

+ +

These options are only valid for the floating-point encoder and do not exist +for the fixed-point encoder due to the corresponding features not being +implemented in fixed-point. +

+
+
-channel_coupling boolean
+

Enables/Disables use of channel coupling, which is an optional AC-3 feature +that increases quality by combining high frequency information from multiple +channels into a single channel. The per-channel high frequency information is +sent with less accuracy in both the frequency and time domains. This allows +more bits to be used for lower frequencies while preserving enough information +to reconstruct the high frequencies. This option is enabled by default for the +floating-point encoder and should generally be left as enabled except for +testing purposes or to increase encoding speed. +

+
-1
+
auto
+

Selected by Encoder (default) +

+
0
+
off
+

Disable Channel Coupling +

+
1
+
on
+

Enable Channel Coupling +

+
+ +
+
-cpl_start_band number
+

Coupling Start Band. Sets the channel coupling start band, from 1 to 15. If a +value higher than the bandwidth is used, it will be reduced to 1 less than the +coupling end band. If auto is used, the start band will be determined by +the encoder based on the bit rate, sample rate, and channel layout. This option +has no effect if channel coupling is disabled. +

+
-1
+
auto
+

Selected by Encoder (default) +

+
+ +
+
+ + +

8.3 flac

+ +

FLAC (Free Lossless Audio Codec) Encoder +

+ +

8.3.1 Options

+ +

The following options are supported by FFmpeg’s flac encoder. +

+
+
compression_level
+

Sets the compression level, which chooses defaults for many other options +if they are not set explicitly. Valid values are from 0 to 12, 5 is the +default. +

+
+
frame_size
+

Sets the size of the frames in samples per channel. +

+
+
lpc_coeff_precision
+

Sets the LPC coefficient precision, valid values are from 1 to 15, 15 is the +default. +

+
+
lpc_type
+

Sets the first stage LPC algorithm +

+
‘none’
+

LPC is not used +

+
+
‘fixed’
+

fixed LPC coefficients +

+
+
‘levinson’
+
‘cholesky’
+
+ +
+
lpc_passes
+

Number of passes to use for Cholesky factorization during LPC analysis +

+
+
min_partition_order
+

The minimum partition order +

+
+
max_partition_order
+

The maximum partition order +

+
+
prediction_order_method
+
+
‘estimation’
+
‘2level’
+
‘4level’
+
‘8level’
+
‘search’
+

Bruteforce search +

+
‘log’
+
+ +
+
ch_mode
+

Channel mode +

+
‘auto’
+

The mode is chosen automatically for each frame +

+
‘indep’
+

Channels are independently coded +

+
‘left_side’
+
‘right_side’
+
‘mid_side’
+
+ +
+
exact_rice_parameters
+

Chooses if rice parameters are calculated exactly or approximately. +if set to 1 then they are chosen exactly, which slows the code down slightly and +improves compression slightly. +

+
+
multi_dim_quant
+

Multi Dimensional Quantization. If set to 1 then a 2nd stage LPC algorithm is +applied after the first stage to finetune the coefficients. This is quite slow +and slightly improves compression. +

+
+
+ + +

8.4 opus

+ +

Opus encoder. +

+

This is a native FFmpeg encoder for the Opus format. Currently, it’s in development and +only implements the CELT part of the codec. Its quality is usually worse and at best +is equal to the libopus encoder. +

+ +

8.4.1 Options

+ +
+
b
+

Set bit rate in bits/s. If unspecified it uses the number of channels and the layout +to make a good guess. +

+
+
opus_delay
+

Sets the maximum delay in milliseconds. Lower delays than 20ms will very quickly +decrease quality. +

+
+ + +

8.5 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 +--enable-libfdk-aac. The library is also incompatible with GPL, +so if you allow the use of GPL, you should configure with +--enable-gpl --enable-nonfree --enable-libfdk-aac. +

+

This encoder has support for the AAC-HE profiles. +

+

VBR encoding, enabled through the vbr or flags ++qscale options, is experimental and only works with some +combinations of parameters. +

+

Support for encoding 7.1 audio is only available with libfdk-aac 0.1.3 or +higher. +

+

For more information see the fdk-aac project at +http://sourceforge.net/p/opencore-amr/fdk-aac/. +

+ +

8.5.1 Options

+ +

The following options are mapped on the shared FFmpeg codec options. +

+
+
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. +

+
+
ar
+

Set audio sampling rate (in Hz). +

+
+
channels
+

Set the number of audio channels. +

+
+
flags +qscale
+

Enable fixed quality, VBR (Variable Bit Rate) mode. +Note that VBR is implicitly enabled when the vbr value is +positive. +

+
+
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. +

+
+
profile
+

Set audio profile. +

+

The following profiles are recognized: +

+
‘aac_low’
+

Low Complexity AAC (LC) +

+
+
‘aac_he’
+

High Efficiency AAC (HE-AAC) +

+
+
‘aac_he_v2’
+

High Efficiency AAC version 2 (HE-AACv2) +

+
+
‘aac_ld’
+

Low Delay AAC (LD) +

+
+
‘aac_eld’
+

Enhanced Low Delay AAC (ELD) +

+
+ +

If not specified it is set to ‘aac_low’. +

+
+ +

The following are private options of the libfdk_aac encoder. +

+
+
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. +

+
+
eld_sbr
+

Enable SBR (Spectral Band Replication) for ELD if set to 1, disabled +if set to 0. +

+

Default value is 0. +

+
+
eld_v2
+

Enable ELDv2 (LD-MPS extension for ELD stereo signals) for ELDv2 if set to 1, +disabled if set to 0. +

+

Note that option is available when fdk-aac version (AACENCODER_LIB_VL0.AACENCODER_LIB_VL1.AACENCODER_LIB_VL2) > (4.0.0). +

+

Default value is 0. +

+
+
signaling
+

Set SBR/PS signaling style. +

+

It can assume one of the following values: +

+
‘default’
+

choose signaling implicitly (explicit hierarchical by default, +implicit if global header is disabled) +

+
+
‘implicit’
+

implicit backwards compatible signaling +

+
+
‘explicit_sbr’
+

explicit SBR, implicit PS signaling +

+
+
‘explicit_hierarchical’
+

explicit hierarchical signaling +

+
+ +

Default value is ‘default’. +

+
+
latm
+

Output LATM/LOAS encapsulated data if set to 1, disabled if set to 0. +

+

Default value is 0. +

+
+
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. +

+
+
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 ‘aac_low’ profile supports VBR encoding. +

+

VBR modes 1-5 correspond to roughly the following average bit rates: +

+
+
‘1’
+

32 kbps/channel +

+
‘2’
+

40 kbps/channel +

+
‘3’
+

48-56 kbps/channel +

+
‘4’
+

64 kbps/channel +

+
‘5’
+

about 80-96 kbps/channel +

+
+ +

Default value is 0. +

+
+
frame_length
+

Set the audio frame length in samples. Default value is the internal +default of the library. Refer to the library’s documentation for information +about supported values. +

+
+ + +

8.5.2 Examples

+ +
    +
  • Use ffmpeg to convert an audio file to VBR AAC in an M4A (MP4) +container: +
    +
    ffmpeg -i input.wav -codec:a libfdk_aac -vbr 3 output.m4a
    +
    + +
  • Use ffmpeg to convert an audio file to CBR 64k kbps AAC, using the +High-Efficiency AAC profile: +
    +
    ffmpeg -i input.wav -c:a libfdk_aac -profile:a aac_he -b:a 64k output.m4a
    +
    +
+ + +

8.6 liblc3

+ +

liblc3 LC3 (Low Complexity Communication Codec) encoder wrapper. +

+

Requires the presence of the liblc3 headers and library during configuration. +You need to explicitly configure the build with --enable-liblc3. +

+

This encoder has support for the Bluetooth SIG LC3 codec for the LE Audio +protocol, and the following features of LC3plus: +

    +
  • Frame duration of 2.5 and 5ms. +
  • High-Resolution mode, 48 KHz, and 96 kHz sampling rates. +
+ +

For more information see the liblc3 project at +https://github.com/google/liblc3. +

+ +

8.6.1 Options

+ +

The following options are mapped on the shared FFmpeg codec options. +

+
+
b bitrate
+

Set the bit rate in bits/s. This will determine the fixed size of the encoded +frames, for a selected frame duration. +

+
+
ar frequency
+

Set the audio sampling rate (in Hz). +

+
+
channels
+

Set the number of audio channels. +

+
+
frame_duration
+

Set the audio frame duration in milliseconds. Default value is 10ms. +Allowed frame durations are 2.5ms, 5ms, 7.5ms and 10ms. +LC3 (Bluetooth LE Audio), allows 7.5ms and 10ms; and LC3plus 2.5ms, 5ms +and 10ms. +

+

The 10ms frame duration is available in LC3 and LC3 plus standard. +In this mode, the produced bitstream can be referenced either as LC3 or LC3plus. +

+
+
high_resolution boolean
+

Enable the high-resolution mode if set to 1. The high-resolution mode is +available with all LC3plus frame durations and for a sampling rate of 48 KHz, +and 96 KHz. +

+

The encoder automatically turns off this mode at lower sampling rates and +activates it at 96 KHz. +

+

This mode should be preferred at high bitrates. In this mode, the audio +bandwidth is always up to the Nyquist frequency, compared to LC3 at 48 KHz, +which limits the bandwidth to 20 KHz. +

+
+ + +

8.7 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 +--enable-libmp3lame. +

+

See libshine for a fixed-point MP3 encoder, although with a +lower quality. +

+ +

8.7.1 Options

+ +

The following options are supported by the libmp3lame wrapper. The +lame-equivalent of the options are listed in parentheses. +

+
+
b (-b)
+

Set bitrate expressed in bits/s for CBR or ABR. LAME bitrate is +expressed in kilobits/s. +

+
+
q (-V)
+

Set constant quality setting for VBR. This option is valid only +using the ffmpeg command-line tool. For library interface +users, use global_quality. +

+
+
compression_level (-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. +

+
+
cutoff (--lowpass)
+

Set lowpass cutoff frequency. If unspecified, the encoder dynamically +adjusts the cutoff. +

+
+
reservoir
+

Enable use of bit reservoir when set to 1. Default value is 1. LAME +has this enabled by default, but can be overridden by use +--nores option. +

+
+
joint_stereo (-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. +

+
+
abr (--abr)
+

Enable the encoder to use ABR when set to 1. The lame +--abr sets the target bitrate, while this options only +tells FFmpeg to use ABR still relies on b to set bitrate. +

+
+
copyright (-c)
+

Set MPEG audio copyright flag when set to 1. The default value is 0 +(disabled). +

+
+
original (-o)
+

Set MPEG audio original flag when set to 1. The default value is 1 +(enabled). +

+
+ + +

8.8 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 +--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 strict to ‘unofficial’ or +lower. +

+ +

8.8.1 Options

+ +
+
b
+

Set bitrate in bits per second. Only the following bitrates are supported, +otherwise libavcodec will round to the nearest valid bitrate. +

+
+
4750
+
5150
+
5900
+
6700
+
7400
+
7950
+
10200
+
12200
+
+ +
+
dtx
+

Allow discontinuous transmission (generate comfort noise) when set to 1. The +default value is 0 (disabled). +

+
+
+ + +

8.9 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 +--enable-libopus. +

+ +

8.9.1 Option Mapping

+ +

Most libopus options are modelled after the opusenc utility from +opus-tools. The following is an option mapping chart describing options +supported by the libopus wrapper, and their opusenc-equivalent +in parentheses. +

+
+
b (bitrate)
+

Set the bit rate in bits/s. FFmpeg’s b option is +expressed in bits/s, while opusenc’s bitrate in +kilobits/s. +

+
+
vbr (vbr, hard-cbr, and cvbr)
+

Set VBR mode. The FFmpeg vbr option has the following +valid arguments, with the opusenc equivalent options +in parentheses: +

+
+
‘off (hard-cbr)’
+

Use constant bit rate encoding. +

+
+
‘on (vbr)’
+

Use variable bit rate encoding (the default). +

+
+
‘constrained (cvbr)’
+

Use constrained variable bit rate encoding. +

+
+ +
+
compression_level (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. +

+
+
frame_duration (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. +

+
+
packet_loss (expect-loss)
+

Set expected packet loss percentage. The default is 0. +

+
+
fec (n/a)
+

Enable inband forward error correction. packet_loss must be non-zero +to take advantage - frequency of FEC ’side-data’ is proportional to expected packet loss. +Default is disabled. +

+
+
application (N.A.)
+

Set intended application type. Valid options are listed below: +

+
+
‘voip’
+

Favor improved speech intelligibility. +

+
‘audio’
+

Favor faithfulness to the input (the default). +

+
‘lowdelay’
+

Restrict to only the lowest delay modes by disabling voice-optimized +modes. +

+
+ +
+
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). Note that libopus +forces a wideband cutoff for bitrates < 15 kbps, unless CELT-only +(application set to ‘lowdelay’) mode is used. +

+
+
mapping_family (mapping_family)
+

Set channel mapping family to be used by the encoder. The default value of -1 +uses mapping family 0 for mono and stereo inputs, and mapping family 1 +otherwise. The default also disables the surround masking and LFE bandwidth +optimizations in libopus, and requires that the input contains 8 channels or +fewer. +

+

Other values include 0 for mono and stereo, 1 for surround sound with masking +and LFE bandwidth optimizations, and 255 for independent streams with an +unspecified channel layout. +

+
+
apply_phase_inv (N.A.) (requires libopus >= 1.2)
+

If set to 0, disables the use of phase inversion for intensity stereo, +improving the quality of mono downmixes, but slightly reducing normal stereo +quality. The default is 1 (phase inversion enabled). +

+
+
+ + +

8.10 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 +http://sourceforge.net/projects/libshine-fxp/. We only support the +updated fork by the Savonet/Liquidsoap project at https://github.com/savonet/shine. +

+

Requires the presence of the libshine headers and library during +configuration. You need to explicitly configure the build with +--enable-libshine. +

+

See also libmp3lame. +

+ +

8.10.1 Options

+ +

The following options are supported by the libshine wrapper. The +shineenc-equivalent of the options are listed in parentheses. +

+
+
b (-b)
+

Set bitrate expressed in bits/s for CBR. shineenc -b option +is expressed in kilobits/s. +

+
+
+ + +

8.11 libtwolame

+ +

TwoLAME MP2 encoder wrapper. +

+

Requires the presence of the libtwolame headers and library during +configuration. You need to explicitly configure the build with +--enable-libtwolame. +

+ +

8.11.1 Options

+ +

The following options are supported by the libtwolame wrapper. The +twolame-equivalent options follow the FFmpeg ones and are in +parentheses. +

+
+
b (-b)
+

Set bitrate expressed in bits/s for CBR. twolame b +option is expressed in kilobits/s. Default value is 128k. +

+
+
q (-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 +ffmpeg command-line tool. For library interface users, +use global_quality. +

+
+
mode (--mode)
+

Set the mode of the resulting audio. Possible values: +

+
+
‘auto’
+

Choose mode automatically based on the input. This is the default. +

+
‘stereo’
+

Stereo +

+
‘joint_stereo’
+

Joint stereo +

+
‘dual_channel’
+

Dual channel +

+
‘mono’
+

Mono +

+
+ +
+
psymodel (--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. +

+
+
energy_levels (--energy)
+

Enable energy levels extensions when set to 1. The default value is +0 (disabled). +

+
+
error_protection (--protect)
+

Enable CRC error protection when set to 1. The default value is 0 +(disabled). +

+
+
copyright (--copyright)
+

Set MPEG audio copyright flag when set to 1. The default value is 0 +(disabled). +

+
+
original (--original)
+

Set MPEG audio original flag when set to 1. The default value is 0 +(disabled). +

+
+
+ + +

8.12 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 +--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 strict to +‘unofficial’ or lower. +

+ +

8.12.1 Options

+ +
+
b
+

Set bitrate in bits/s. Only the following bitrates are supported, otherwise +libavcodec will round to the nearest valid bitrate. +

+
+
‘6600’
+
‘8850’
+
‘12650’
+
‘14250’
+
‘15850’
+
‘18250’
+
‘19850’
+
‘23050’
+
‘23850’
+
+ +
+
dtx
+

Allow discontinuous transmission (generate comfort noise) when set to 1. The +default value is 0 (disabled). +

+
+
+ + +

8.13 libvorbis

+ +

libvorbis encoder wrapper. +

+

Requires the presence of the libvorbisenc headers and library during +configuration. You need to explicitly configure the build with +--enable-libvorbis. +

+ +

8.13.1 Options

+ +

The following options are supported by the libvorbis wrapper. The +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 oggenc’s documentations. +See http://xiph.org/vorbis/, +http://wiki.xiph.org/Vorbis-tools, and oggenc(1). +

+
+
b (-b)
+

Set bitrate expressed in bits/s for ABR. oggenc -b is +expressed in kilobits/s. +

+
+
q (-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 ‘3.0’. +

+

This option is valid only using the ffmpeg command-line tool. +For library interface users, use global_quality. +

+
+
cutoff (--advanced-encode-option lowpass_frequency=N)
+

Set cutoff bandwidth in Hz, a value of 0 disables cutoff. oggenc’s +related option is expressed in kHz. The default value is ‘0’ (cutoff +disabled). +

+
+
minrate (-m)
+

Set minimum bitrate expressed in bits/s. oggenc -m is +expressed in kilobits/s. +

+
+
maxrate (-M)
+

Set maximum bitrate expressed in bits/s. oggenc -M is +expressed in kilobits/s. This only has effect on ABR mode. +

+
+
iblock (--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. +

+
+
+ + +

8.14 mjpeg

+ +

Motion JPEG encoder. +

+ +

8.14.1 Options

+ +
+
huffman
+

Set the huffman encoding strategy. Possible values: +

+
+
‘default’
+

Use the default huffman tables. This is the default strategy. +

+
+
‘optimal’
+

Compute and use optimal huffman tables. +

+
+
+
+
+ + +

8.15 wavpack

+ +

WavPack lossless audio encoder. +

+ +

8.15.1 Options

+ +

The equivalent options for wavpack command line utility are listed in +parentheses. +

+ +

8.15.1.1 Shared options

+ +

The following shared options are effective for this encoder. Only special notes +about this particular encoder will be documented here. For the general meaning +of the options, see the Codec Options chapter. +

+
+
frame_size (--blocksize)
+

For this encoder, the range for this option is between 128 and 131072. Default +is automatically decided based on sample rate and number of channel. +

+

For the complete formula of calculating default, see +libavcodec/wavpackenc.c. +

+
+
compression_level (-f, -h, -hh, and -x)
+
+ + +

8.15.1.2 Private options

+ +
+
joint_stereo (-j)
+

Set whether to enable joint stereo. Valid values are: +

+
+
‘on (1)’
+

Force mid/side audio encoding. +

+
‘off (0)’
+

Force left/right audio encoding. +

+
‘auto’
+

Let the encoder decide automatically. +

+
+ +
+
optimize_mono
+

Set whether to enable optimization for mono. This option is only effective for +non-mono streams. Available values: +

+
+
‘on’
+

enabled +

+
‘off’
+

disabled +

+
+ +
+
+ + + +

9 Video Encoders

+ +

A description of some of the currently available video encoders +follows. +

+ +

9.1 a64_multi, a64_multi5

+ +

A64 / Commodore 64 multicolor charset encoder. a64_multi5 is extended with 5th color (colram). +

+ +

9.2 Cinepak

+ +

Cinepak aka CVID encoder. +Compatible with Windows 3.1 and vintage MacOS. +

+ +

9.2.1 Options

+ +
+
g integer
+

Keyframe interval. +A keyframe is inserted at least every -g frames, sometimes sooner. +

+
+
q:v integer
+

Quality factor. Lower is better. Higher gives lower bitrate. +The following table lists bitrates when encoding akiyo_cif.y4m for various values of -q:v with -g 100: +

+
+
-q:v 1 1918 kb/s
+
-q:v 2 1735 kb/s
+
-q:v 4 1500 kb/s
+
-q:v 10 1041 kb/s
+
-q:v 20 826 kb/s
+
-q:v 40 553 kb/s
+
-q:v 100 394 kb/s
+
-q:v 200 312 kb/s
+
-q:v 400 266 kb/s
+
-q:v 1000 237 kb/s
+
+ +
+
max_extra_cb_iterations integer
+

Max extra codebook recalculation passes, more is better and slower. +

+
+
skip_empty_cb boolean
+

Avoid wasting bytes, ignore vintage MacOS decoder. +

+
+
max_strips integer
+
min_strips integer
+

The minimum and maximum number of strips to use. +Wider range sometimes improves quality. +More strips is generally better quality but costs more bits. +Fewer strips tend to yield more keyframes. +Vintage compatible is 1..3. +

+
+
strip_number_adaptivity integer
+

How much number of strips is allowed to change between frames. +Higher is better but slower. +

+
+
+ + +

9.3 ffv1

+ +

FFv1 Encoder +

+ +

9.3.1 Options

+ +

The following options are supported by FFmpeg’s FFv1 encoder. +

+
+
context
+

Sets the context size, 0 (default) is small, 1 is big. +

+
+
coder
+

Set the coder, +

+
‘rice’
+

Golomb rice coder +

+
‘range_def’
+

Range coder with default table +

+
‘range_tab’
+

Range coder with custom table +

+
+ +
+
slicecrc
+

-1 (default, automatic), 1 use crc with zero initial and final state, 2 use crc with non zero initial and final state +

+
+
qtable
+
+
‘default’
+

default, automatic +

+
‘8bit’
+

use 8bit default +

+
‘greater8bit’
+

use >8bit default +

+
+ +
+
remap_optimizer
+

0 - 5, default 3, how much effort the encoder puts into optimizing the remap table. +

+
+
+ + +

9.4 GIF

+ +

GIF image/animation encoder. +

+ +

9.4.1 Options

+ +
+
gifflags integer
+

Sets the flags used for GIF encoding. +

+
+
offsetting
+

Enables picture offsetting. +

+

Default is enabled. +

+
+
transdiff
+

Enables transparency detection between frames. +

+

Default is enabled. +

+
+
+ +
+
gifimage integer
+

Enables encoding one full GIF image per frame, rather than an animated GIF. +

+

Default value is 0. +

+
+
global_palette integer
+

Writes a palette to the global GIF header where feasible. +

+

If disabled, every frame will always have a palette written, even if there +is a global palette supplied. +

+

Default value is 1. +

+
+
+ + +

9.5 Hap

+ +

Vidvox Hap video encoder. +

+ +

9.5.1 Options

+ +
+
format integer
+

Specifies the Hap format to encode. +

+
+
hap
+
hap_alpha
+
hap_q
+
+ +

Default value is hap. +

+
+
chunks integer
+

Specifies the number of chunks to split frames into, between 1 and 64. This +permits multithreaded decoding of large frames, potentially at the cost of +data-rate. The encoder may modify this value to divide frames evenly. +

+

Default value is 1. +

+
+
compressor integer
+

Specifies the second-stage compressor to use. If set to none, +chunks will be limited to 1, as chunked uncompressed frames offer no +benefit. +

+
+
none
+
snappy
+
+ +

Default value is snappy. +

+
+
+ + +

9.6 jpeg2000

+ +

The native jpeg 2000 encoder is lossy by default, the -q:v +option can be used to set the encoding quality. Lossless encoding +can be selected with -pred 1. +

+ +

9.6.1 Options

+ +
+
format integer
+

Can be set to either j2k or jp2 (the default) that +makes it possible to store non-rgb pix_fmts. +

+
+
tile_width integer
+

Sets tile width. Range is 1 to 1073741824. Default is 256. +

+
+
tile_height integer
+

Sets tile height. Range is 1 to 1073741824. Default is 256. +

+
+
pred integer
+

Allows setting the discrete wavelet transform (DWT) type +

+
dwt97int (Lossy)
+
dwt53 (Lossless)
+
+

Default is dwt97int +

+
+
sop boolean
+

Enable this to add SOP marker at the start of each packet. Disabled by default. +

+
+
eph boolean
+

Enable this to add EPH marker at the end of each packet header. Disabled by default. +

+
+
prog integer
+

Sets the progression order to be used by the encoder. +Possible values are: +

+
lrcp
+
rlcp
+
rpcl
+
pcrl
+
cprl
+
+

Set to lrcp by default. +

+
+
layer_rates string
+

By default, when this option is not used, compression is done using the quality metric. +This option allows for compression using compression ratio. The compression ratio for each +level could be specified. The compression ratio of a layer l species the what ratio of +total file size is contained in the first l layers. +

+

Example usage: +

+
+
ffmpeg -i input.bmp -c:v jpeg2000 -layer_rates "100,10,1" output.j2k
+
+ +

This would compress the image to contain 3 layers, where the data contained in the +first layer would be compressed by 1000 times, compressed by 100 in the first two layers, +and shall contain all data while using all 3 layers. +

+
+
+ + +

9.7 librav1e

+ +

rav1e AV1 encoder wrapper. +

+

Requires the presence of the rav1e headers and library during configuration. +You need to explicitly configure the build with --enable-librav1e. +

+ +

9.7.1 Options

+ +
+
qmax
+

Sets the maximum quantizer to use when using bitrate mode. +

+
+
qmin
+

Sets the minimum quantizer to use when using bitrate mode. +

+
+
qp
+

Uses quantizer mode to encode at the given quantizer (0-255). +

+
+
speed
+

Selects the speed preset (0-10) to encode with. +

+
+
tiles
+

Selects how many tiles to encode with. +

+
+
tile-rows
+

Selects how many rows of tiles to encode with. +

+
+
tile-columns
+

Selects how many columns of tiles to encode with. +

+
+
rav1e-params
+

Set rav1e options using a list of key=value pairs separated +by ":". See rav1e --help for a list of options. +

+

For example to specify librav1e encoding options with -rav1e-params: +

+
+
ffmpeg -i input -c:v librav1e -b:v 500K -rav1e-params speed=5:low_latency=true output.mp4
+
+ +
+
+ + +

9.8 libaom-av1

+ +

libaom AV1 encoder wrapper. +

+

Requires the presence of the libaom headers and library during +configuration. You need to explicitly configure the build with +--enable-libaom. +

+ +

9.8.1 Options

+ +

The wrapper supports the following standard libavcodec options: +

+
+
b
+

Set bitrate target in bits/second. By default this will use +variable-bitrate mode. If maxrate and minrate are +also set to the same value then it will use constant-bitrate mode, +otherwise if crf is set as well then it will use +constrained-quality mode. +

+
+
g keyint_min
+

Set key frame placement. The GOP size sets the maximum distance between +key frames; if zero the output stream will be intra-only. The minimum +distance is ignored unless it is the same as the GOP size, in which case +key frames will always appear at a fixed interval. Not set by default, +so without this option the library has completely free choice about +where to place key frames. +

+
+
qmin qmax
+

Set minimum/maximum quantisation values. Valid range is from 0 to 63 +(warning: this does not match the quantiser values actually used by AV1 +- divide by four to map real quantiser values to this range). Defaults +to min/max (no constraint). +

+
+
minrate maxrate bufsize rc_init_occupancy
+

Set rate control buffering parameters. Not used if not set - defaults +to unconstrained variable bitrate. +

+
+
threads
+

Set the number of threads to use while encoding. This may require the +tiles or row-mt options to also be set to actually +use the specified number of threads fully. Defaults to the number of +hardware threads supported by the host machine. +

+
+
profile
+

Set the encoding profile. Defaults to using the profile which matches +the bit depth and chroma subsampling of the input. +

+
+
+ +

The wrapper also has some specific options: +

+
+
cpu-used
+

Set the quality/encoding speed tradeoff. Valid range is from 0 to 8, +higher numbers indicating greater speed and lower quality. The default +value is 1, which will be slow and high quality. +

+
+
auto-alt-ref
+

Enable use of alternate reference frames. Defaults to the internal +default of the library. +

+
+
arnr-max-frames (frames)
+

Set altref noise reduction max frame count. Default is -1. +

+
+
arnr-strength (strength)
+

Set altref noise reduction filter strength. Range is -1 to 6. Default is -1. +

+
+
aq-mode (aq-mode)
+

Set adaptive quantization mode. Possible values: +

+
+
‘none (0)’
+

Disabled. +

+
+
‘variance (1)’
+

Variance-based. +

+
+
‘complexity (2)’
+

Complexity-based. +

+
+
‘cyclic (3)’
+

Cyclic refresh. +

+
+ +
+
tune (tune)
+

Set the distortion metric the encoder is tuned with. Default is psnr. +

+
+
‘psnr (0)’
+
‘ssim (1)’
+
+ +
+
lag-in-frames
+

Set the maximum number of frames which the encoder may keep in flight +at any one time for lookahead purposes. Defaults to the internal +default of the library. +

+
+
error-resilience
+

Enable error resilience features: +

+
default
+

Improve resilience against losses of whole frames. +

+
+

Not enabled by default. +

+
+
crf
+

Set the quality/size tradeoff for constant-quality (no bitrate target) +and constrained-quality (with maximum bitrate target) modes. Valid +range is 0 to 63, higher numbers indicating lower quality and smaller +output size. Only used if set; by default only the bitrate target is +used. +

+
+
static-thresh
+

Set a change threshold on blocks below which they will be skipped by +the encoder. Defined in arbitrary units as a nonnegative integer, +defaulting to zero (no blocks are skipped). +

+
+
drop-threshold
+

Set a threshold for dropping frames when close to rate control bounds. +Defined as a percentage of the target buffer - when the rate control +buffer falls below this percentage, frames will be dropped until it +has refilled above the threshold. Defaults to zero (no frames are +dropped). +

+
+
denoise-noise-level (level)
+

Amount of noise to be removed for grain synthesis. Grain synthesis is disabled if +this option is not set or set to 0. +

+
+
denoise-block-size (pixels)
+

Block size used for denoising for grain synthesis. If not set, AV1 codec +uses the default value of 32. +

+
+
undershoot-pct (pct)
+

Set datarate undershoot (min) percentage of the target bitrate. Range is -1 to 100. +Default is -1. +

+
+
overshoot-pct (pct)
+

Set datarate overshoot (max) percentage of the target bitrate. Range is -1 to 1000. +Default is -1. +

+
+
minsection-pct (pct)
+

Minimum percentage variation of the GOP bitrate from the target bitrate. If minsection-pct +is not set, the libaomenc wrapper computes it as follows: (minrate * 100 / bitrate). +Range is -1 to 100. Default is -1 (unset). +

+
+
maxsection-pct (pct)
+

Maximum percentage variation of the GOP bitrate from the target bitrate. If maxsection-pct +is not set, the libaomenc wrapper computes it as follows: (maxrate * 100 / bitrate). +Range is -1 to 5000. Default is -1 (unset). +

+
+
frame-parallel (boolean)
+

Enable frame parallel decodability features. Default is true. +

+
+
tiles
+

Set the number of tiles to encode the input video with, as columns x +rows. Larger numbers allow greater parallelism in both encoding and +decoding, but may decrease coding efficiency. Defaults to the minimum +number of tiles required by the size of the input video (this is 1x1 +(that is, a single tile) for sizes up to and including 4K). +

+
+
tile-columns tile-rows
+

Set the number of tiles as log2 of the number of tile rows and columns. +Provided for compatibility with libvpx/VP9. +

+
+
row-mt (Requires libaom >= 1.0.0-759-g90a15f4f2)
+

Enable row based multi-threading. Disabled by default. +

+
+
enable-cdef (boolean)
+

Enable Constrained Directional Enhancement Filter. The libaom-av1 +encoder enables CDEF by default. +

+
+
enable-restoration (boolean)
+

Enable Loop Restoration Filter. Default is true for libaom-av1. +

+
+
enable-global-motion (boolean)
+

Enable the use of global motion for block prediction. Default is true. +

+
+
enable-intrabc (boolean)
+

Enable block copy mode for intra block prediction. This mode is +useful for screen content. Default is true. +

+
+
enable-rect-partitions (boolean) (Requires libaom >= v2.0.0)
+

Enable rectangular partitions. Default is true. +

+
+
enable-1to4-partitions (boolean) (Requires libaom >= v2.0.0)
+

Enable 1:4/4:1 partitions. Default is true. +

+
+
enable-ab-partitions (boolean) (Requires libaom >= v2.0.0)
+

Enable AB shape partitions. Default is true. +

+
+
enable-angle-delta (boolean) (Requires libaom >= v2.0.0)
+

Enable angle delta intra prediction. Default is true. +

+
+
enable-cfl-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable chroma predicted from luma intra prediction. Default is true. +

+
+
enable-filter-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable filter intra predictor. Default is true. +

+
+
enable-intra-edge-filter (boolean) (Requires libaom >= v2.0.0)
+

Enable intra edge filter. Default is true. +

+
+
enable-smooth-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable smooth intra prediction mode. Default is true. +

+
+
enable-paeth-intra (boolean) (Requires libaom >= v2.0.0)
+

Enable paeth predictor in intra prediction. Default is true. +

+
+
enable-palette (boolean) (Requires libaom >= v2.0.0)
+

Enable palette prediction mode. Default is true. +

+
+
enable-flip-idtx (boolean) (Requires libaom >= v2.0.0)
+

Enable extended transform type, including FLIPADST_DCT, DCT_FLIPADST, +FLIPADST_FLIPADST, ADST_FLIPADST, FLIPADST_ADST, IDTX, V_DCT, H_DCT, +V_ADST, H_ADST, V_FLIPADST, H_FLIPADST. Default is true. +

+
+
enable-tx64 (boolean) (Requires libaom >= v2.0.0)
+

Enable 64-pt transform. Default is true. +

+
+
reduced-tx-type-set (boolean) (Requires libaom >= v2.0.0)
+

Use reduced set of transform types. Default is false. +

+
+
use-intra-dct-only (boolean) (Requires libaom >= v2.0.0)
+

Use DCT only for INTRA modes. Default is false. +

+
+
use-inter-dct-only (boolean) (Requires libaom >= v2.0.0)
+

Use DCT only for INTER modes. Default is false. +

+
+
use-intra-default-tx-only (boolean) (Requires libaom >= v2.0.0)
+

Use Default-transform only for INTRA modes. Default is false. +

+
+
enable-ref-frame-mvs (boolean) (Requires libaom >= v2.0.0)
+

Enable temporal mv prediction. Default is true. +

+
+
enable-reduced-reference-set (boolean) (Requires libaom >= v2.0.0)
+

Use reduced set of single and compound references. Default is false. +

+
+
enable-obmc (boolean) (Requires libaom >= v2.0.0)
+

Enable obmc. Default is true. +

+
+
enable-dual-filter (boolean) (Requires libaom >= v2.0.0)
+

Enable dual filter. Default is true. +

+
+
enable-diff-wtd-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable difference-weighted compound. Default is true. +

+
+
enable-dist-wtd-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable distance-weighted compound. Default is true. +

+
+
enable-onesided-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable one sided compound. Default is true. +

+
+
enable-interinter-wedge (boolean) (Requires libaom >= v2.0.0)
+

Enable interinter wedge compound. Default is true. +

+
+
enable-interintra-wedge (boolean) (Requires libaom >= v2.0.0)
+

Enable interintra wedge compound. Default is true. +

+
+
enable-masked-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable masked compound. Default is true. +

+
+
enable-interintra-comp (boolean) (Requires libaom >= v2.0.0)
+

Enable interintra compound. Default is true. +

+
+
enable-smooth-interintra (boolean) (Requires libaom >= v2.0.0)
+

Enable smooth interintra mode. Default is true. +

+
+
aom-params
+

Set libaom options using a list of key=value pairs separated +by ":". For a list of supported options, see aomenc --help under the +section "AV1 Specific Options". +

+

For example to specify libaom encoding options with -aom-params: +

+
+
ffmpeg -i input -c:v libaom-av1 -b:v 500K -aom-params tune=psnr:enable-tpl-model=1 output.mp4
+
+ +
+
+ + +

9.9 liboapv

+ +

Advanced Professional Video codec encoder wrapper. +

+

This encoder requires the presence of the liboapv headers and library +during configuration. You need to explicitly configure the build with +--enable-liboapv. +

+
+

Many liboapv encoder options are mapped to FFmpeg global codec options, +while unique encoder options are provided through private options. +

+

The apv project website is at https://github.com/AcademySoftwareFoundation/openapv. +

+ +

9.9.1 Options

+ +

The following options are supported by the liboapv wrapper. +

+
+

To get a more extensive documentation of the liboapv options, consult the +liboapv documentation. +

+
+
preset
+

Set the quality-speed tradeoff [fastest, fast, medium, slow, placebo, default] +

+
+
qp
+

Set the quantization parameter value for CQP rate control mode. +

+
+
oapv-params (parse_apv_params)
+

Set liboapvenc options using a list of key=value pairs separated +by ":". See the liboapv encoder user guide for a list of accepted parameters. +

+
+ + +

9.10 libsvtav1

+ +

SVT-AV1 encoder wrapper. +

+

Requires the presence of the SVT-AV1 headers and library during configuration. +You need to explicitly configure the build with --enable-libsvtav1. +

+ +

9.10.1 Options

+ +
+
profile
+

Set the encoding profile. +

+
‘main’
+
‘high’
+
‘professional’
+
+ +
+
level
+

Set the operating point level. For example: ’4.0’ +

+
+
hielevel
+

Set the Hierarchical prediction levels. +

+
‘3level’
+
‘4level’
+

This is the default. +

+
+ +
+
tier
+

Set the operating point tier. +

+
‘main’
+

This is the default. +

+
‘high’
+
+ +
+
qmax
+

Set the maximum quantizer to use when using a bitrate mode. +

+
+
qmin
+

Set the minimum quantizer to use when using a bitrate mode. +

+
+
crf
+

Constant rate factor value used in crf rate control mode (0-63). +

+
+
qp
+

Set the quantizer used in cqp rate control mode (0-63). +

+
+
sc_detection
+

Enable scene change detection. +

+
+
la_depth
+

Set number of frames to look ahead (0-120). +

+
+
preset
+

Set the quality-speed tradeoff, in the range 0 to 13. Higher values are +faster but lower quality. +

+
+
tile_rows
+

Set log2 of the number of rows of tiles to use (0-6). +

+
+
tile_columns
+

Set log2 of the number of columns of tiles to use (0-4). +

+
+
svtav1-params
+

Set SVT-AV1 options using a list of key=value pairs separated +by ":". See the SVT-AV1 encoder user guide for a list of accepted parameters. +

+
+
+ + +

9.11 libsvtjpegxs

+ +

SVT-JPEG-XS encoder wrapper. +

+

Requires the presence of the SVT-JPEG-XS headers and library during configuration. +You need to explicitly configure the build with --enable-libsvtjpegxs. +

+ +

9.11.1 Options

+ +
+
decomp_v
+

Set vertical decomposition level +

+
decomp_h
+

Set horizontal decomposition level +

+
+
quantization
+

Set the quantization algorithm. +

+
‘deadzone’
+
‘uniform’
+
+ +
+
coding-signs
+

Enable Signs handling strategy +

+
‘disable’
+
‘fast’
+
‘full’
+
+ +
+
coding-sigf
+

Enable Significance coding +

+
+
coding-vpred
+

Enable Vertical Prediction coding +

+
‘disable’
+
‘no_residuals’
+
‘no_coeffs’
+
+ +
+
+ + +

9.12 libjxl

+ +

libjxl JPEG XL encoder wrapper. +

+

Requires the presence of the libjxl headers and library during +configuration. You need to explicitly configure the build with +--enable-libjxl. +

+ +

9.12.1 Options

+ +

The libjxl wrapper supports the following options: +

+
+
distance
+

Set the target Butteraugli distance. This is a quality setting: lower +distance yields higher quality, with distance=1.0 roughly comparable to +libjpeg Quality 90 for photographic content. Setting distance=0.0 yields +true lossless encoding. Valid values range between 0.0 and 15.0, and sane +values rarely exceed 5.0. Setting distance=0.1 usually attains +transparency for most input. The default is 1.0. +

+
+
effort
+

Set the encoding effort used. Higher effort values produce more consistent +quality and usually produces a better quality/bpp curve, at the cost of +more CPU time required. Valid values range from 1 to 9, and the default is 7. +

+
+
modular
+

Force the encoder to use Modular mode instead of choosing automatically. The +default is to use VarDCT for lossy encoding and Modular for lossless. VarDCT +is generally superior to Modular for lossy encoding but does not support +lossless encoding. +

+
+
+ + +

9.13 libkvazaar

+ +

Kvazaar H.265/HEVC encoder. +

+

Requires the presence of the libkvazaar headers and library during +configuration. You need to explicitly configure the build with +--enable-libkvazaar. +

+ +

9.13.1 Options

+ +
+
b
+

Set target video bitrate in bit/s and enable rate control. +

+
+
kvazaar-params
+

Set kvazaar parameters as a list of name=value pairs separated +by commas (,). See kvazaar documentation for a list of options. +

+
+
+ + +

9.14 libopenh264

+ +

Cisco libopenh264 H.264/MPEG-4 AVC encoder wrapper. +

+

This encoder requires the presence of the libopenh264 headers and +library during configuration. You need to explicitly configure the +build with --enable-libopenh264. The library is detected using +pkg-config. +

+

For more information about the library see +http://www.openh264.org. +

+ +

9.14.1 Options

+ +

The following FFmpeg global options affect the configurations of the +libopenh264 encoder. +

+
+
b
+

Set the bitrate (as a number of bits per second). +

+
+
g
+

Set the GOP size. +

+
+
maxrate
+

Set the max bitrate (as a number of bits per second). +

+
+
flags +global_header
+

Set global header in the bitstream. +

+
+
slices
+

Set the number of slices, used in parallelized encoding. Default value +is 0. This is only used when slice_mode is set to +‘fixed’. +

+
+
loopfilter
+

Enable loop filter, if set to 1 (automatically enabled). To disable +set a value of 0. +

+
+
profile
+

Set profile restrictions. If set to the value of ‘main’ enable +CABAC (set the SEncParamExt.iEntropyCodingModeFlag flag to 1). +

+
+
max_nal_size
+

Set maximum NAL size in bytes. +

+
+
allow_skip_frames
+

Allow skipping frames to hit the target bitrate if set to 1. +

+
+ + +

9.15 libtheora

+ +

libtheora Theora encoder wrapper. +

+

Requires the presence of the libtheora headers and library during +configuration. You need to explicitly configure the build with +--enable-libtheora. +

+

For more information about the libtheora project see +http://www.theora.org/. +

+ +

9.15.1 Options

+ +

The following global options are mapped to internal libtheora options +which affect the quality and the bitrate of the encoded stream. +

+
+
b
+

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. +

+
+
flags
+

Used to enable constant quality mode (VBR) encoding through the +qscale flag, and to enable the pass1 and pass2 +modes. +

+
+
g
+

Set the GOP size. +

+
+
global_quality
+

Set the global quality as an integer in lambda units. +

+

Only relevant when VBR mode is enabled with flags +qscale. The +value is converted to QP units by dividing it by 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. +

+
+
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 ffmpeg command-line +tool. For library interface users, use global_quality. +

+
+ + +

9.15.2 Examples

+ +
    +
  • Set maximum constant quality (VBR) encoding with ffmpeg: +
    +
    ffmpeg -i INPUT -codec:v libtheora -q:v 10 OUTPUT.ogg
    +
    + +
  • Use ffmpeg to convert a CBR 1000 kbps Theora video stream: +
    +
    ffmpeg -i INPUT -codec:v libtheora -b:v 1000k OUTPUT.ogg
    +
    +
+ + +

9.16 libvpx

+ +

VP8/VP9 format supported through libvpx. +

+

Requires the presence of the libvpx headers and library during configuration. +You need to explicitly configure the build with --enable-libvpx. +

+ +

9.16.1 Options

+ +

The following options are supported by the libvpx wrapper. The +vpxenc-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 +the Codec Options chapter. +

+

To get more documentation of the libvpx options, invoke the command +ffmpeg -h encoder=libvpx, ffmpeg -h encoder=libvpx-vp9 or +vpxenc --help. Further information is available in the libvpx API +documentation. +

+
+
b (target-bitrate)
+

Set bitrate in bits/s. Note that FFmpeg’s b option is +expressed in bits/s, while vpxenc’s target-bitrate is in +kilobits/s. +

+
+
g (kf-max-dist)
+
keyint_min (kf-min-dist)
+
qmin (min-q)
+

Minimum (Best Quality) Quantizer. +

+
+
qmax (max-q)
+

Maximum (Worst Quality) Quantizer. +Can be changed per-frame. +

+
+
bufsize (buf-sz, buf-optimal-sz)
+

Set ratecontrol buffer size (in bits). Note vpxenc’s options are +specified in milliseconds, the libvpx wrapper converts this value as follows: +buf-sz = bufsize * 1000 / bitrate, +buf-optimal-sz = bufsize * 1000 / bitrate * 5 / 6. +

+
+
rc_init_occupancy (buf-initial-sz)
+

Set number of bits which should be loaded into the rc buffer before decoding +starts. Note vpxenc’s option is specified in milliseconds, the libvpx +wrapper converts this value as follows: +rc_init_occupancy * 1000 / bitrate. +

+
+
undershoot-pct
+

Set datarate undershoot (min) percentage of the target bitrate. +

+
+
overshoot-pct
+

Set datarate overshoot (max) percentage of the target bitrate. +

+
+
skip_threshold (drop-frame)
+
qcomp (bias-pct)
+
maxrate (maxsection-pct)
+

Set GOP max bitrate in bits/s. Note vpxenc’s option is specified as a +percentage of the target bitrate, the libvpx wrapper converts this value as +follows: (maxrate * 100 / bitrate). +

+
+
minrate (minsection-pct)
+

Set GOP min bitrate in bits/s. Note vpxenc’s option is specified as a +percentage of the target bitrate, the libvpx wrapper converts this value as +follows: (minrate * 100 / bitrate). +

+
+
minrate, maxrate, b end-usage=cbr
+

(minrate == maxrate == bitrate). +

+
+
crf (end-usage=cq, cq-level)
+
tune (tune)
+
+
‘psnr (psnr)’
+
‘ssim (ssim)’
+
+ +
+
quality, deadline (deadline)
+
+
‘best’
+

Use best quality deadline. Poorly named and quite slow, this option should be +avoided as it may give worse quality output than good. +

+
‘good’
+

Use good quality deadline. This is a good trade-off between speed and quality +when used with the cpu-used option. +

+
‘realtime’
+

Use realtime quality deadline. +

+
+ +
+
speed, cpu-used (cpu-used)
+

Set quality/speed ratio modifier. Higher values speed up the encode at the cost +of quality. +

+
+
nr (noise-sensitivity)
+
static-thresh
+

Set a change threshold on blocks below which they will be skipped by the +encoder. +

+
+
slices (token-parts)
+

Note that FFmpeg’s slices option gives the total number of partitions, +while vpxenc’s token-parts is given as +log2(partitions). +

+
+
max-intra-rate
+

Set maximum I-frame bitrate as a percentage of the target bitrate. A value of 0 +means unlimited. +

+
+
force_key_frames
+

VPX_EFLAG_FORCE_KF +

+
+
Alternate reference frame related
+
+
auto-alt-ref
+

Enable use of alternate reference frames (2-pass only). +Values greater than 1 enable multi-layer alternate reference frames (VP9 only). +

+
arnr-maxframes
+

Set altref noise reduction max frame count. +

+
arnr-type
+

Set altref noise reduction filter type: backward, forward, centered. +

+
arnr-strength
+

Set altref noise reduction filter strength. +

+
rc-lookahead, lag-in-frames (lag-in-frames)
+

Set number of frames to look ahead for frametype and ratecontrol. +

+
min-gf-interval
+

Set minimum golden/alternate reference frame interval (VP9 only). +

+
+ +
+
error-resilient
+

Enable error resiliency features. +

+
+
sharpness integer
+

Increase sharpness at the expense of lower PSNR. +The valid range is [0, 7]. +

+
+
ts-parameters
+

Sets the temporal scalability configuration using a :-separated list of +key=value pairs. For example, to specify temporal scalability parameters +with ffmpeg: +

+
ffmpeg -i INPUT -c:v libvpx -ts-parameters ts_number_layers=3:\
+ts_target_bitrate=250,500,1000:ts_rate_decimator=4,2,1:\
+ts_periodicity=4:ts_layer_id=0,2,1,2:ts_layering_mode=3 OUTPUT
+
+

Below is a brief explanation of each of the parameters, please +refer to struct vpx_codec_enc_cfg in vpx/vpx_encoder.h for more +details. +

+
ts_number_layers
+

Number of temporal coding layers. +

+
ts_target_bitrate
+

Target bitrate for each temporal layer (in kbps). +(bitrate should be inclusive of the lower temporal layer). +

+
ts_rate_decimator
+

Frame rate decimation factor for each temporal layer. +

+
ts_periodicity
+

Length of the sequence defining frame temporal layer membership. +

+
ts_layer_id
+

Template defining the membership of frames to temporal layers. +

+
ts_layering_mode
+

(optional) Selecting the temporal structure from a set of pre-defined temporal layering modes. +Currently supports the following options. +

+
0
+

No temporal layering flags are provided internally, +relies on flags being passed in using metadata field in AVFrame +with following keys. +

+
vp8-flags
+

Sets the flags passed into the encoder to indicate the referencing scheme for +the current frame. +Refer to function vpx_codec_encode in vpx/vpx_encoder.h for more +details. +

+
temporal_id
+

Explicitly sets the temporal id of the current frame to encode. +

+
+
+
2
+

Two temporal layers. 0-1... +

+
3
+

Three temporal layers. 0-2-1-2...; with single reference frame. +

+
4
+

Same as option "3", except there is a dependency between +the two temporal layer 2 frames within the temporal period. +

+
+
+
+ +
+
VP8-specific options
+
+
screen-content-mode
+

Screen content mode, one of: 0 (off), 1 (screen), 2 (screen with more aggressive rate control). +

+
+ +
+
VP9-specific options
+
+
lossless
+

Enable lossless mode. +

+
tile-columns
+

Set number of tile columns to use. Note this is given as +log2(tile_columns). For example, 8 tile columns would be requested by +setting the tile-columns option to 3. +

+
tile-rows
+

Set number of tile rows to use. Note this is given as log2(tile_rows). +For example, 4 tile rows would be requested by setting the tile-rows +option to 2. +

+
frame-parallel
+

Enable frame parallel decodability features. +

+
aq-mode
+

Set adaptive quantization mode (0: off (default), 1: variance 2: complexity, 3: +cyclic refresh, 4: equator360). +

+
colorspace color-space
+

Set input color space. The VP9 bitstream supports signaling the following +colorspaces: +

+
‘rgb’ sRGB
+
‘bt709’ bt709
+
‘unspecified’ unknown
+
‘bt470bg’ bt601
+
‘smpte170m’ smpte170
+
‘smpte240m’ smpte240
+
‘bt2020_ncl’ bt2020
+
+
+
row-mt boolean
+

Enable row based multi-threading. +

+
tune-content
+

Set content type: default (0), screen (1), film (2). +

+
corpus-complexity
+

Corpus VBR mode is a variant of standard VBR where the complexity distribution +midpoint is passed in rather than calculated for a specific clip or chunk. +

+

The valid range is [0, 10000]. 0 (default) uses standard VBR. +

+
enable-tpl boolean
+

Enable temporal dependency model. +

+
ref-frame-config
+

Using per-frame metadata, set members of the structure vpx_svc_ref_frame_config_t in vpx/vp8cx.h to fine-control referencing schemes and frame buffer management. +
Use a :-separated list of key=value pairs. +For example, +

+
av_dict_set(&av_frame->metadata, "ref-frame-config", \
+"rfc_update_buffer_slot=7:rfc_lst_fb_idx=0:rfc_gld_fb_idx=1:rfc_alt_fb_idx=2:rfc_reference_last=0:rfc_reference_golden=0:rfc_reference_alt_ref=0");
+
+
+
rfc_update_buffer_slot
+

Indicates the buffer slot number to update +

+
rfc_update_last
+

Indicates whether to update the LAST frame +

+
rfc_update_golden
+

Indicates whether to update GOLDEN frame +

+
rfc_update_alt_ref
+

Indicates whether to update ALT_REF frame +

+
rfc_lst_fb_idx
+

LAST frame buffer index +

+
rfc_gld_fb_idx
+

GOLDEN frame buffer index +

+
rfc_alt_fb_idx
+

ALT_REF frame buffer index +

+
rfc_reference_last
+

Indicates whether to reference LAST frame +

+
rfc_reference_golden
+

Indicates whether to reference GOLDEN frame +

+
rfc_reference_alt_ref
+

Indicates whether to reference ALT_REF frame +

+
rfc_reference_duration
+

Indicates frame duration +

+
+
+
+ +
+
+ +

For more information about libvpx see: +http://www.webmproject.org/ +

+ +

9.17 libvvenc

+ +

VVenC H.266/VVC encoder wrapper. +

+

This encoder requires the presence of the libvvenc headers and library +during configuration. You need to explicitly configure the build with +--enable-libvvenc. +

+

The VVenC project website is at +https://github.com/fraunhoferhhi/vvenc. +

+ +

9.17.1 Supported Pixel Formats

+ +

VVenC supports only 10-bit color spaces as input. But the internal (encoded) +bit depth can be set to 8-bit or 10-bit at runtime. +

+ +

9.17.2 Options

+ +
+
b
+

Sets target video bitrate. +

+
+
g
+

Set the GOP size. Currently support for g=1 (Intra only) or default. +

+
+
preset
+

Set the VVenC preset. +

+
+
levelidc
+

Set level idc. +

+
+
tier
+

Set vvc tier. +

+
+
qp
+

Set constant quantization parameter. +

+
+
subopt boolean
+

Set subjective (perceptually motivated) optimization. Default is 1 (on). +

+
+
bitdepth8 boolean
+

Set 8bit coding mode instead of using 10bit. Default is 0 (off). +

+
+
period
+

set (intra) refresh period in seconds. +

+
+
vvenc-params
+

Set vvenc options using a list of key=value couples separated +by ":". See vvencapp --fullhelp or vvencFFapp --fullhelp for a list of options. +

+

For example, the options might be provided as: +

+
+
intraperiod=64:decodingrefreshtype=idr:poc0idr=1:internalbitdepth=8
+
+ +

For example the encoding options might be provided with -vvenc-params: +

+
+
ffmpeg -i input -c:v libvvenc -b 1M -vvenc-params intraperiod=64:decodingrefreshtype=idr:poc0idr=1:internalbitdepth=8 output.mp4
+
+ +
+
+ + +

9.18 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. +

+ +

9.18.1 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. +

+ +

9.18.2 Options

+ +
+
-lossless boolean
+

Enables/Disables use of lossless mode. Default is 0. +

+
+
-compression_level 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 method option in libwebp. The valid range is 0 to 6. +Default is 4. +

+
+
-quality float
+

For lossy encoding, this controls image quality. For lossless encoding, this +controls the effort and time spent in compression. +Range is 0 to 100. Default is 75. +

+
+
-preset type
+

Configuration preset. This does some automatic settings based on the general +type of the image. +

+
none
+

Do not use a preset. +

+
default
+

Use the encoder default. +

+
picture
+

Digital picture, like portrait, inner shot +

+
photo
+

Outdoor photograph, with natural lighting +

+
drawing
+

Hand or line drawing, with high-contrast details +

+
icon
+

Small-sized colorful images +

+
text
+

Text-like +

+
+ +
+
+ + +

9.19 libx264, libx264rgb

+ +

x264 H.264/MPEG-4 AVC encoder wrapper. +

+

This encoder requires the presence of the libx264 headers and library +during configuration. You need to explicitly configure the build with +--enable-libx264. +

+

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). +

+

Many libx264 encoder options are mapped to FFmpeg global codec +options, while unique encoder options are provided through private +options. Additionally the x264opts and x264-params +private options allows one to pass a list of key=value tuples as accepted +by the libx264 x264_param_parse function. +

+

The x264 project website is at +http://www.videolan.org/developers/x264.html. +

+

The libx264rgb encoder is the same as libx264, except it accepts packed RGB +pixel formats as input instead of YUV. +

+ +

9.19.1 Supported Pixel Formats

+ +

x264 supports 8- to 10-bit color spaces. The exact bit depth is controlled at +x264’s configure time. +

+ +

9.19.2 Options

+ +

The following options are supported by the libx264 wrapper. The +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 +the Codec Options chapter. +

+

To get a more accurate and extensive documentation of the libx264 +options, invoke the command x264 --fullhelp or consult +the libx264 documentation. +

+

In the list below, note that the x264 option name is shown +in parentheses after the libavcodec corresponding name, in case there +is a direct mapping. +

+
+
b (bitrate)
+

Set bitrate in bits/s. Note that FFmpeg’s b option is +expressed in bits/s, while x264’s bitrate is in +kilobits/s. +

+
+
bf (bframes)
+

Number of B-frames between I and P-frames +

+
+
g (keyint)
+

Maximum GOP size +

+
+
qmin (qpmin)
+

Minimum quantizer scale +

+
+
qmax (qpmax)
+

Maximum quantizer scale +

+
+
qdiff (qpstep)
+

Maximum difference between quantizer scales +

+
+
qblur (qblur)
+

Quantizer curve blur +

+
+
qcomp (qcomp)
+

Quantizer curve compression factor +

+
+
refs (ref)
+

Number of reference frames each P-frame can use. The range is 0-16. +

+
+
level (level)
+

Set the x264_param_t.i_level_idc value in case the value is +positive, it is ignored otherwise. +

+

This value can be set using the AVCodecContext API (e.g. by +setting the AVCodecContext value directly), and is specified as +an integer mapped on a corresponding level (e.g. the value 31 maps +to H.264 level IDC "3.1", as defined in the x264_levels +table). It is ignored when set to a non positive value. +

+

Alternatively it can be set as a private option, overriding the value +set in AVCodecContext, and in this case must be specified as +the level IDC identifier (e.g. "3.1"), as defined by H.264 Annex A. +

+
+
sc_threshold (scenecut)
+

Sets the threshold for the scene change detection. +

+
+
trellis (trellis)
+

Performs Trellis quantization to increase efficiency. Enabled by default. +

+
+
nr (nr)
+

Noise reduction +

+
+
me_range (merange)
+

Maximum range of the motion search in pixels. +

+
+
me_method (me)
+

Set motion estimation method. Possible values in the decreasing order +of speed: +

+
+
‘dia (dia)’
+
‘epzs (dia)’
+

Diamond search with radius 1 (fastest). ‘epzs’ is an alias for +‘dia’. +

+
‘hex (hex)’
+

Hexagonal search with radius 2. +

+
‘umh (umh)’
+

Uneven multi-hexagon search. +

+
‘esa (esa)’
+

Exhaustive search. +

+
‘tesa (tesa)’
+

Hadamard exhaustive search (slowest). +

+
+ +
+
forced-idr
+

Normally, when forcing a I-frame type, the encoder can select any type +of I-frame. This option forces it to choose an IDR-frame. +

+
+
subq (subme)
+

Sub-pixel motion estimation method. +

+
+
b_strategy (b-adapt)
+

Adaptive B-frame placement decision algorithm. Use only on first-pass. +

+
+
keyint_min (min-keyint)
+

Minimum GOP size. +

+
+
coder
+

Set entropy encoder. Possible values: +

+
+
‘ac’
+

Enable CABAC. +

+
+
‘vlc’
+

Enable CAVLC and disable CABAC. It generates the same effect as +x264’s --no-cabac option. +

+
+ +
+
cmp
+

Set full pixel motion estimation comparison algorithm. Possible values: +

+
+
‘chroma’
+

Enable chroma in motion estimation. +

+
+
‘sad’
+

Ignore chroma in motion estimation. It generates the same effect as +x264’s --no-chroma-me option. +

+
+ +
+
threads (threads)
+

Number of encoding threads. +

+
+
thread_type
+

Set multithreading technique. Possible values: +

+
+
‘slice’
+

Slice-based multithreading. It generates the same effect as +x264’s --sliced-threads option. +

+
‘frame’
+

Frame-based multithreading. +

+
+ +
+
flags
+

Set encoding flags. It can be used to disable closed GOP and enable +open GOP by setting it to -cgop. The result is similar to +the behavior of x264’s --open-gop option. +

+
+
rc_init_occupancy (vbv-init)
+

Initial VBV buffer occupancy +

+
+
preset (preset)
+

Set the encoding preset. +

+
+
tune (tune)
+

Set tuning of the encoding params. +

+
+
profile (profile)
+

Set profile restrictions. +

+
+
fastfirstpass
+

Enable fast settings when encoding first pass, when set to 1. When set +to 0, it has the same effect of x264’s +--slow-firstpass option. +

+
+
crf (crf)
+

Set the quality for constant quality mode. +

+
+
crf_max (crf-max)
+

In CRF mode, prevents VBV from lowering quality beyond this point. +

+
+
qp (qp)
+

Set constant quantization rate control method parameter. +

+
+
aq-mode (aq-mode)
+

Set AQ method. Possible values: +

+
+
‘none (0)’
+

Disabled. +

+
+
‘variance (1)’
+

Variance AQ (complexity mask). +

+
+
‘autovariance (2)’
+

Auto-variance AQ (experimental). +

+
+ +
+
aq-strength (aq-strength)
+

Set AQ strength, reduce blocking and blurring in flat and textured areas. +

+
+
psy
+

Use psychovisual optimizations when set to 1. When set to 0, it has the +same effect as x264’s --no-psy option. +

+
+
psy-rd (psy-rd)
+

Set strength of psychovisual optimization, in +psy-rd:psy-trellis format. +

+
+
rc-lookahead (rc-lookahead)
+

Set number of frames to look ahead for frametype and ratecontrol. +

+
+
weightb
+

Enable weighted prediction for B-frames when set to 1. When set to 0, +it has the same effect as x264’s --no-weightb option. +

+
+
weightp (weightp)
+

Set weighted prediction method for P-frames. Possible values: +

+
+
‘none (0)’
+

Disabled +

+
‘simple (1)’
+

Enable only weighted refs +

+
‘smart (2)’
+

Enable both weighted refs and duplicates +

+
+ +
+
ssim (ssim)
+

Enable calculation and printing SSIM stats after the encoding. +

+
+
intra-refresh (intra-refresh)
+

Enable the use of Periodic Intra Refresh instead of IDR frames when set +to 1. +

+
+
avcintra-class (class)
+

Configure the encoder to generate AVC-Intra. +Valid values are 50, 100 and 200 +

+
+
bluray-compat (bluray-compat)
+

Configure the encoder to be compatible with the bluray standard. +It is a shorthand for setting "bluray-compat=1 force-cfr=1". +

+
+
b-bias (b-bias)
+

Set the influence on how often B-frames are used. +

+
+
b-pyramid (b-pyramid)
+

Set method for keeping of some B-frames as references. Possible values: +

+
+
‘none (none)’
+

Disabled. +

+
‘strict (strict)’
+

Strictly hierarchical pyramid. +

+
‘normal (normal)’
+

Non-strict (not Blu-ray compatible). +

+
+ +
+
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 x264’s --no-mixed-refs option. +

+
+
8x8dct
+

Enable adaptive spatial transform (high profile 8x8 transform) +when set to 1. When set to 0, it has the same effect as +x264’s --no-8x8dct option. +

+
+
fast-pskip
+

Enable early SKIP detection on P-frames when set to 1. When set +to 0, it has the same effect as x264’s +--no-fast-pskip option. +

+
+
aud (aud)
+

Enable use of access unit delimiters when set to 1. +

+
+
mbtree
+

Enable use macroblock tree ratecontrol when set to 1. When set +to 0, it has the same effect as x264’s +--no-mbtree option. +

+
+
deblock (deblock)
+

Set loop filter parameters, in alpha:beta form. +

+
+
cplxblur (cplxblur)
+

Set fluctuations reduction in QP (before curve compression). +

+
+
partitions (partitions)
+

Set partitions to consider as a comma-separated list of values. +Possible values in the list: +

+
+
‘p8x8’
+

8x8 P-frame partition. +

+
‘p4x4’
+

4x4 P-frame partition. +

+
‘b8x8’
+

4x4 B-frame partition. +

+
‘i8x8’
+

8x8 I-frame partition. +

+
‘i4x4’
+

4x4 I-frame partition. +(Enabling ‘p4x4’ requires ‘p8x8’ to be enabled. Enabling +‘i8x8’ requires adaptive spatial transform (8x8dct +option) to be enabled.) +

+
‘none (none)’
+

Do not consider any partitions. +

+
‘all (all)’
+

Consider every partition. +

+
+ +
+
direct-pred (direct)
+

Set direct MV prediction mode. Possible values: +

+
+
‘none (none)’
+

Disable MV prediction. +

+
‘spatial (spatial)’
+

Enable spatial predicting. +

+
‘temporal (temporal)’
+

Enable temporal predicting. +

+
‘auto (auto)’
+

Automatically decided. +

+
+ +
+
slice-max-size (slice-max-size)
+

Set the limit of the size of each slice in bytes. If not specified +but RTP payload size (ps) is specified, that is used. +

+
+
stats (stats)
+

Set the file name for multi-pass stats. +

+
+
nal-hrd (nal-hrd)
+

Set signal HRD information (requires vbv-bufsize to be set). +Possible values: +

+
+
‘none (none)’
+

Disable HRD information signaling. +

+
‘vbr (vbr)’
+

Variable bit rate. +

+
‘cbr (cbr)’
+

Constant bit rate (not allowed in MP4 container). +

+
+ +
+
x264opts opts
+
x264-params opts
+

Override the x264 configuration using a :-separated list of key=value +options. +

+

The argument for both options is a list of key=value +couples separated by ":". With x264opts the value can be +omitted, and the value 1 is assumed in that case. +

+

For filter and psy-rd options values that use ":" as a +separator themselves, use "," instead. They accept it as well since +long ago but this is kept undocumented for some reason. +

+

For example, the options might be provided as: +

+
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
+
+ +

For example to specify libx264 encoding options with ffmpeg: +

+
ffmpeg -i foo.mpg -c:v libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
+
+ +

To get the complete list of the libx264 options, invoke the command +x264 --fullhelp or consult the libx264 documentation. +

+
+
a53cc boolean
+

Import closed captions (which must be ATSC compatible format) into output. +Only the mpeg2 and h264 decoders provide these. Default is 1 (on). +

+
+
udu_sei boolean
+

Import user data unregistered SEI if available into output. Default is 0 (off). +

+
+
mb_info boolean
+

Set mb_info data through AVFrameSideData, only useful when used from the +API. Default is 0 (off). +

+
+ +

Encoding ffpresets for common usages are provided so they can be used with the +general presets system (e.g. passing the pre option). +

+ +

9.20 libx265

+ +

x265 H.265/HEVC encoder wrapper. +

+

This encoder requires the presence of the libx265 headers and library +during configuration. You need to explicitly configure the build with +--enable-libx265. +

+ +

9.20.1 Options

+ +
+
b
+

Sets target video bitrate. +

+
+
bf
+
g
+

Set the GOP size. +

+
+
keyint_min
+

Minimum GOP size. +

+
+
refs
+

Number of reference frames each P-frame can use. The range is from 1-16. +

+
+
preset
+

Set the x265 preset. +

+
+
tune
+

Set the x265 tune parameter. +

+
+
profile
+

Set profile restrictions. +

+
+
crf
+

Set the quality for constant quality mode. +

+
+
qp
+

Set constant quantization rate control method parameter. +

+
+
qmin
+

Minimum quantizer scale. +

+
+
qmax
+

Maximum quantizer scale. +

+
+
qdiff
+

Maximum difference between quantizer scales. +

+
+
qblur
+

Quantizer curve blur +

+
+
qcomp
+

Quantizer curve compression factor +

+
+
i_qfactor
+
b_qfactor
+
forced-idr
+

Normally, when forcing a I-frame type, the encoder can select any type +of I-frame. This option forces it to choose an IDR-frame. +

+
+
x265-stats
+

Specify the file name for 2-pass stats. This is set automatically when using +the -passlogfile option. +

+
+
udu_sei boolean
+

Import user data unregistered SEI if available into output. Default is 0 (off). +

+
+
x265-params
+

Set x265 options using a list of key=value couples separated +by ":". See x265 --help for a list of options. +

+

For example to specify libx265 encoding options with -x265-params: +

+
+
ffmpeg -i input -c:v libx265 -x265-params crf=26:psy-rd=1 output.mp4
+
+
+
+ + +

9.21 libxavs2

+ +

xavs2 AVS2-P2/IEEE1857.4 encoder wrapper. +

+

This encoder requires the presence of the libxavs2 headers and library +during configuration. You need to explicitly configure the build with +--enable-libxavs2. +

+

The following standard libavcodec options are used: +

    +
  • b / bit_rate +
  • g / gop_size +
  • bf / max_b_frames +
+ +

The encoder also has its own specific options: +

+

9.21.1 Options

+ +
+
lcu_row_threads
+

Set the number of parallel threads for rows from 1 to 8 (default 5). +

+
+
initial_qp
+

Set the xavs2 quantization parameter from 1 to 63 (default 34). This is +used to set the initial qp for the first frame. +

+
+
qp
+

Set the xavs2 quantization parameter from 1 to 63 (default 34). This is +used to set the qp value under constant-QP mode. +

+
+
max_qp
+

Set the max qp for rate control from 1 to 63 (default 55). +

+
+
min_qp
+

Set the min qp for rate control from 1 to 63 (default 20). +

+
+
speed_level
+

Set the Speed level from 0 to 9 (default 0). Higher is better but slower. +

+
+
log_level
+

Set the log level from -1 to 3 (default 0). -1: none, 0: error, +1: warning, 2: info, 3: debug. +

+
+
xavs2-params
+

Set xavs2 options using a list of key=value couples separated +by ":". +

+

For example to specify libxavs2 encoding options with -xavs2-params: +

+
+
ffmpeg -i input -c:v libxavs2 -xavs2-params RdoqLevel=0 output.avs2
+
+
+
+ + +

9.22 libxeve

+ +

eXtra-fast Essential Video Encoder (XEVE) MPEG-5 EVC encoder wrapper. +The xeve-equivalent options or values are listed in parentheses for easy migration. +

+

This encoder requires the presence of the libxeve headers and library +during configuration. You need to explicitly configure the build with +--enable-libxeve. +

+
+

Many libxeve encoder options are mapped to FFmpeg global codec options, +while unique encoder options are provided through private options. +Additionally the xeve-params private options allows one to pass a list +of key=value tuples as accepted by the libxeve parse_xeve_params function. +

+

The xeve project website is at https://github.com/mpeg5/xeve. +

+ +

9.22.1 Options

+ +

The following options are supported by the libxeve wrapper. +The xeve-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 +the Codec Options chapter. +

+
+

To get a more accurate and extensive documentation of the libxeve options, +invoke the command xeve_app --help or consult the libxeve documentation. +

+
+
b (bitrate)
+

Set target video bitrate in bits/s. +Note that FFmpeg’s b option is expressed in bits/s, while xeve’s bitrate is in kilobits/s. +

+
+
bf (bframes)
+

Set the maximum number of B frames (1,3,7,15). +

+
+
g (keyint)
+

Set the GOP size (I-picture period). +

+
+
preset (preset)
+

Set the xeve preset. +Set the encoder preset value to determine encoding speed [fast, medium, slow, placebo] +

+
+
tune (tune)
+

Set the encoder tune parameter [psnr, zerolatency] +

+
+
profile (profile)
+

Set the encoder profile [0: baseline; 1: main] +

+
+
crf (crf)
+

Set the quality for constant quality mode. +Constant rate factor <10..49> [default: 32] +

+
+
qp (qp)
+

Set constant quantization rate control method parameter. +Quantization parameter qp <0..51> [default: 32] +

+
+
threads (threads)
+

Force to use a specific number of threads +

+
+
+ + +

9.23 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 +--enable-libxvid --enable-gpl. +

+

The native mpeg4 encoder supports the MPEG-4 Part 2 format, so +users can encode to this format without this library. +

+ +

9.23.1 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 the Codec +Options chapter for their documentation. The other shared options +which are not listed have no effect for the libxvid encoder. +

+
+
b
+
g
+
qmin
+
qmax
+
mpeg_quant
+
threads
+
bf
+
b_qfactor
+
b_qoffset
+
flags
+

Set specific encoding flags. Possible values: +

+
+
‘mv4’
+

Use four motion vector by macroblock. +

+
+
‘aic’
+

Enable high quality AC prediction. +

+
+
‘gray’
+

Only encode grayscale. +

+
+
‘qpel’
+

Enable quarter-pixel motion compensation. +

+
+
‘cgop’
+

Enable closed GOP. +

+
+
‘global_header’
+

Place global headers in extradata instead of every keyframe. +

+
+
+ +
+
gmc
+

Enable the use of global motion compensation (GMC). Default is 0 +(disabled). +

+
+
me_quality
+

Set motion estimation quality level. Possible values in decreasing order of +speed and increasing order of quality: +

+
+
‘0’
+

Use no motion estimation (default). +

+
+
‘1, 2’
+

Enable advanced diamond zonal search for 16x16 blocks and half-pixel +refinement for 16x16 blocks. +

+
+
‘3, 4’
+

Enable all of the things described above, plus advanced diamond zonal +search for 8x8 blocks and half-pixel refinement for 8x8 blocks, also +enable motion estimation on chroma planes for P and B-frames. +

+
+
‘5, 6’
+

Enable all of the things described above, plus extended 16x16 and 8x8 +blocks search. +

+
+ +
+
mbd
+

Set macroblock decision algorithm. Possible values in the increasing +order of quality: +

+
+
‘simple’
+

Use macroblock comparing function algorithm (default). +

+
+
‘bits’
+

Enable rate distortion-based half pixel and quarter pixel refinement for +16x16 blocks. +

+
+
‘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. +

+
+ +
+
lumi_aq
+

Enable lumi masking adaptive quantization when set to 1. Default is 0 +(disabled). +

+
+
variance_aq
+

Enable variance adaptive quantization when set to 1. Default is 0 +(disabled). +

+

When combined with 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. +

+
+
trellis
+

Set rate-distortion optimal quantization. +

+
+
ssim
+

Set structural similarity (SSIM) displaying method. Possible values: +

+
+
‘off’
+

Disable displaying of SSIM information. +

+
+
‘avg’
+

Output average SSIM at the end of encoding to stdout. The format of +showing the average SSIM is: +

+
+
Average SSIM: %f
+
+ +

For users who are not familiar with C, %f means a float number, or +a decimal (e.g. 0.939232). +

+
+
‘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: +

+
+
       SSIM: avg: %1.3f min: %1.3f max: %1.3f
+
+ +

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). +

+
+
+ +
+
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. +

+
+
+ + +

9.24 MediaCodec

+ +

MediaCodec encoder wrapper enables hardware-accelerated video encoding on +Android device. It supports H.264, H.265 (HEVC), VP8, VP9, MPEG-4, and AV1 +encoding (whether works or not is device dependent). +

+

Android provides two sets of APIs: Java MediaCodec and NDK MediaCodec. The +MediaCodec encoder wrapper supports both. Note that the NDK MediaCodec API +operates without requiring JVM, but may fail to function outside the JVM +environment due to dependencies on system framework services, particularly +after Android 15. +

+
+
ndk_codec boolean
+

Use the NDK-based MediaCodec API instead of the Java API. Enabled by default +if av_jni_get_java_vm() return NULL. +

+
+
ndk_async boolean
+

Use NDK MediaCodec in async mode. Async mode has less overhead than poll in a +loop in sync mode. The drawback of async mode is AV_CODEC_FLAG_GLOBAL_HEADER +doesn’t work (use extract_extradata bsf when necessary). It doesn’t work and +will be disabled automatically on devices below Android 8.0. +

+
+
codec_name string
+

A codec type can have multiple implementations on a single device, this option +specify which backend to use (via MediaCodec createCodecByName API). It’s NULL +by default, and encoder is created by createEncoderByType. +

+
+
bitrate_mode integer
+
+

Possible values: +

+
‘cq’
+

Constant quality mode +

+
‘vbr’
+

Variable bitrate mode +

+
‘cbr’
+

Constant bitrate mode +

+
‘cbr_fd’
+

Constant bitrate mode with frame drops +

+
+ +
+
pts_as_dts boolean
+

Use PTS as DTS. This is a workaround since MediaCodec API doesn’t provide +decoding timestamp. It is enabled automatically if B frame is 0. +

+
+
operating_rate integer
+

The desired operating rate that the codec will need to operate at, zero for +unspecified. This is used for cases like high-speed/slow-motion video capture, +where the video encoder format contains the target playback rate (e.g. 30fps), +but the component must be able to handle the high operating capture rate (e.g. +240fps). This rate will be used by codec for resource planning and setting the +operating points. +

+
+
qp_i_min integer
+

Minimum quantization parameter for I frame. +

+
qp_p_min integer
+

Minimum quantization parameter for P frame. +

+
qp_b_min integer
+

Minimum quantization parameter for B frame. +

+
qp_i_max integer
+

Maximum quantization parameter for I frame. +

+
qp_p_max integer
+

Maximum quantization parameter for P frame. +

+
qp_b_max integer
+

Maximum quantization parameter for B frame. +

+
+
+ + +

9.25 MediaFoundation

+ +

The following wrappers for encoders in the MediaFoundation framework are +available: +

+
    +
  • h264_mf +
  • hevc_mf +
  • av1_mf +
+ +

These support both software and hardware encoding. +

+

Video encoders can take input in either of nv12 or yuv420p form +(some encoders support both, some support only either - in practice, +nv12 is the safer choice, especially among HW encoders). +

+

Hardware-accelerated encoding requires D3D11, including hardware +scaling capabilities through the scale_d3d11 filter. +

+

To list all available options for the MediaFoundation encoders, use: +ffmpeg -h encoder=<encoder> e.g. ffmpeg -h encoder=h264_mf +

+ +

9.25.1 Options

+ +
+
rate_control
+

Select rate control mode. Available modes: +

+
+
‘default’
+

Default mode +

+
‘cbr’
+

CBR mode +

+
‘pc_vbr’
+

Peak constrained VBR mode +

+
‘u_vbr’
+

Unconstrained VBR mode +

+
‘quality’
+

Quality mode +

+
‘ld_vbr’
+

Low delay VBR mode (requires Windows 8+) +

+
‘g_vbr’
+

Global VBR mode (requires Windows 8+) +

+
‘gld_vbr’
+

Global low delay VBR mode (requires Windows 8+) +

+
+ +
+
scenario
+

Select usage scenario. Available scenarios: +

+
+
‘default’
+

Default scenario +

+
‘display_remoting’
+

Display remoting scenario +

+
‘video_conference’
+

Video conference scenario +

+
‘archive’
+

Archive scenario +

+
‘live_streaming’
+

Live streaming scenario +

+
‘camera_record’
+

Camera record scenario +

+
‘display_remoting_with_feature_map’
+

Display remoting with feature map scenario +

+
+ +
+
quality
+

Set encoding quality (0-100). -1 means default quality. +

+
+
hw_encoding
+

Force hardware encoding (0-1). Default is 0 (disabled). +

+
+
+ + +

9.25.2 Examples

+ +

Hardware encoding: +

+
ffmpeg -i input.mp4 -c:v h264_mf -hw_encoding 1 output.mp4
+
+ +

Hardware-accelerated decoding with hardware encoding: +

+
ffmpeg -hwaccel d3d11va -i input.mp4 -c:v h264_mf -hw_encoding 1 output.mp4
+
+ +

Hardware-accelerated decoding, HW scaling and encoding with quality setting: +

+
ffmpeg -hwaccel d3d11va -hwaccel_output_format d3d11 -i input.mp4 -vf scale_d3d11=1920:1080 -c:v hevc_mf -hw_encoding 1 -quality 80 output.mp4
+
+ + +

9.26 Microsoft RLE

+ +

Microsoft RLE aka MSRLE encoder. +Only 8-bit palette mode supported. +Compatible with Windows 3.1 and Windows 95. +

+ +

9.26.1 Options

+ +
+
g integer
+

Keyframe interval. +A keyframe is inserted at least every -g frames, sometimes sooner. +

+
+ + +

9.27 mpeg2

+ +

MPEG-2 video encoder. +

+ +

9.27.1 Options

+ +
+
profile
+

Select the mpeg2 profile to encode: +

+
+
‘422’
+
‘high’
+
‘ss’
+

Spatially Scalable +

+
‘snr’
+

SNR Scalable +

+
‘main’
+
‘simple’
+
+ +
+
level
+

Select the mpeg2 level to encode: +

+
+
‘high’
+
‘high1440’
+
‘main’
+
‘low’
+
+ +
+
seq_disp_ext integer
+

Specifies if the encoder should write a sequence_display_extension to the +output. +

+
-1
+
auto
+

Decide automatically to write it or not (this is the default) by checking if +the data to be written is different from the default or unspecified values. +

+
0
+
never
+

Never write it. +

+
1
+
always
+

Always write it. +

+
+
+
video_format integer
+

Specifies the video_format written into the sequence display extension +indicating the source of the video pictures. The default is ‘unspecified’, +can be ‘component’, ‘pal’, ‘ntsc’, ‘secam’ or ‘mac’. +For maximum compatibility, use ‘component’. +

+
a53cc boolean
+

Import closed captions (which must be ATSC compatible format) into output. +Default is 1 (on). +

+
+ + +

9.28 png

+ +

PNG image encoder. +

+ +

9.28.1 Options

+ +
+
compression_level
+

Sets the compression level, from 0 to 9(default) +

+
+ + +

9.28.2 Private options

+ +
+
dpi integer
+

Set physical density of pixels, in dots per inch, unset by default +

+
dpm integer
+

Set physical density of pixels, in dots per meter, unset by default +

+
pred method
+

Set prediction method (none, sub, up, avg, paeth, mixed), default is paeth +

+
+ + +

9.29 ProRes

+ +

Apple ProRes encoder. +

+

FFmpeg contains 2 ProRes encoders, the prores-aw and prores-ks encoder. +The used encoder can be chosen with the -vcodec option. +

+ +

9.29.1 Private Options for prores-ks

+ +
+
profile integer
+

Select the ProRes profile to encode +

+
‘proxy’
+
‘lt’
+
‘standard’
+
‘hq’
+
‘4444’
+
‘4444xq’
+
+ +
+
quant_mat integer
+

Select quantization matrix. +

+
‘auto’
+
‘default’
+
‘proxy’
+
‘lt’
+
‘standard’
+
‘hq’
+
+

If set to auto, the matrix matching the profile will be picked. +If not set, the matrix providing the highest quality, default, will be +picked. +

+
+
bits_per_mb integer
+

How many bits to allot for coding one macroblock. Different profiles use +between 200 and 2400 bits per macroblock, the maximum is 8000. +

+
+
mbs_per_slice integer
+

Number of macroblocks in each slice (1-8); the default value (8) +should be good in almost all situations. +

+
+
vendor string
+

Override the 4-byte vendor ID. +A custom vendor ID like apl0 would claim the stream was produced by +the Apple encoder. +

+
+
alpha_bits integer
+

Specify number of bits for alpha component. +Possible values are 0, 8 and 16. +Use 0 to disable alpha plane coding. +

+
+
+ + +

9.29.2 Speed considerations

+ +

In the default mode of operation the encoder has to honor frame constraints +(i.e. not produce 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 bits_per_mb limit will improve the speed. +

+

For the fastest encoding speed set the qscale parameter (4 is the +recommended value) and do not set a size constraint. +

+ +

9.30 QSV Encoders

+ +

The family of Intel QuickSync Video encoders (MPEG-2, H.264, HEVC, JPEG/MJPEG, +VP9, AV1) +

+ +

9.30.1 Ratecontrol Method

+

The ratecontrol method is selected as follows: +

    +
  • When global_quality is specified, a quality-based mode is used. +Specifically this means either +
      +
    • CQP - constant quantizer scale, when the qscale codec flag is +also set (the -qscale ffmpeg option). + +
    • LA_ICQ - intelligent constant quality with lookahead, when the +look_ahead option is also set. + +
    • ICQ – intelligent constant quality otherwise. For the ICQ modes, global +quality range is 1 to 51, with 1 being the best quality. +
    + +
  • Otherwise when the desired average bitrate is specified with the b +option, a bitrate-based mode is used. +
      +
    • LA - VBR with lookahead, when the look_ahead option is specified. + +
    • VCM - video conferencing mode, when the vcm option is set. + +
    • CBR - constant bitrate, when maxrate is specified and equal to +the average bitrate. + +
    • VBR - variable bitrate, when maxrate is specified, but is higher +than the average bitrate. + +
    • AVBR - average VBR mode, when maxrate is not specified, both +avbr_accuracy and avbr_convergence are set to non-zero. This +mode is available for H264 and HEVC on Windows. +
    + +
  • Otherwise the default ratecontrol method CQP is used. +
+ +

Note that depending on your system, a different mode than the one you specified +may be selected by the encoder. Set the verbosity level to verbose or +higher to see the actual settings used by the QSV runtime. +

+ +

9.30.2 Global Options -> MSDK Options

+

Additional libavcodec global options are mapped to MSDK options as follows: +

+
    +
  • g/gop_size -> GopPicSize + +
  • bf/max_b_frames+1 -> GopRefDist + +
  • rc_init_occupancy/rc_initial_buffer_occupancy -> +InitialDelayInKB + +
  • slices -> NumSlice + +
  • refs -> NumRefFrame + +
  • b_strategy/b_frame_strategy -> BRefType + +
  • cgop/CLOSED_GOP codec flag -> GopOptFlag + +
  • For the CQP mode, the i_qfactor/i_qoffset and +b_qfactor/b_qoffset set the difference between QPP and QPI, +and QPP and QPB respectively. + +
  • Setting the coder option to the value vlc will make the H.264 +encoder use CAVLC instead of CABAC. + +
+ + +

9.30.3 Common Options

+

Following options are used by all qsv encoders. +

+
+
async_depth
+

Specifies how many asynchronous operations an application performs +before the application explicitly synchronizes the result. If zero, +the value is not specified. +

+
+
preset
+

This option itemizes a range of choices from veryfast (best speed) to veryslow +(best quality). +

+
‘veryfast’
+
‘faster’
+
‘fast’
+
‘medium’
+
‘slow’
+
‘slower’
+
‘veryslow’
+
+ +
+
forced_idr
+

Forcing I frames as IDR frames. +

+
+
low_power
+

For encoders set this flag to ON to reduce power consumption and GPU usage. +

+
+ + +

9.30.4 Runtime Options

+

Following options can be used during qsv encoding. +

+
+
global_quality
+
i_quant_factor
+
i_quant_offset
+
b_quant_factor
+
b_quant_offset
+

Supported in h264_qsv and hevc_qsv. +Change these value to reset qsv codec’s qp configuration. +

+
+
max_frame_size
+

Supported in h264_qsv and hevc_qsv. +Change this value to reset qsv codec’s MaxFrameSize configuration. +

+
+
gop_size
+

Change this value to reset qsv codec’s gop configuration. +

+
+
int_ref_type
+
int_ref_cycle_size
+
int_ref_qp_delta
+
int_ref_cycle_dist
+

Supported in h264_qsv and hevc_qsv. +Change these value to reset qsv codec’s Intra Refresh configuration. +

+
+
qmax
+
qmin
+
max_qp_i
+
min_qp_i
+
max_qp_p
+
min_qp_p
+
max_qp_b
+
min_qp_b
+

Supported in h264_qsv. +Change these value to reset qsv codec’s max/min qp configuration. +

+
+
low_delay_brc
+

Supported in h264_qsv, hevc_qsv and av1_qsv. +Change this value to reset qsv codec’s low_delay_brc configuration. +

+
+
framerate
+

Change this value to reset qsv codec’s framerate configuration. +

+
+
bit_rate
+
rc_buffer_size
+
rc_initial_buffer_occupancy
+
rc_max_rate
+

Change these value to reset qsv codec’s bitrate control configuration. +

+
+
pic_timing_sei
+

Supported in h264_qsv and hevc_qsv. +Change this value to reset qsv codec’s pic_timing_sei configuration. +

+
+
qsv_params
+

Set QSV encoder parameters as a colon-separated list of key-value pairs. +

+

The qsv_params should be formatted as key1=value1:key2=value2:.... +

+

These parameters are passed directly to the underlying Intel Quick Sync Video (QSV) encoder using the MFXSetParameter function. +

+

Example: +

+
ffmpeg -i input.mp4 -c:v h264_qsv -qsv_params "CodingOption1=1:CodingOption2=2" output.mp4
+
+ +

This option allows fine-grained control over various encoder-specific settings provided by the QSV encoder. +

+
+ + +

9.30.5 H264 options

+

These options are used by h264_qsv +

+
+
extbrc
+

Extended bitrate control. +

+
+
recovery_point_sei
+

Set this flag to insert the recovery point SEI message at the beginning of every +intra refresh cycle. +

+
+
rdo
+

Enable rate distortion optimization. +

+
+
max_frame_size
+

Maximum encoded frame size in bytes. +

+
+
max_frame_size_i
+

Maximum encoded frame size for I frames in bytes. If this value is set as larger +than zero, then for I frames the value set by max_frame_size is ignored. +

+
+
max_frame_size_p
+

Maximum encoded frame size for P frames in bytes. If this value is set as larger +than zero, then for P frames the value set by max_frame_size is ignored. +

+
+
max_slice_size
+

Maximum encoded slice size in bytes. +

+
+
bitrate_limit
+

Toggle bitrate limitations. +Modifies bitrate to be in the range imposed by the QSV encoder. Setting this +flag off may lead to violation of HRD conformance. Mind that specifying bitrate +below the QSV encoder range might significantly affect quality. If on this +option takes effect in non CQP modes: if bitrate is not in the range imposed +by the QSV encoder, it will be changed to be in the range. +

+
+
mbbrc
+

Setting this flag enables macroblock level bitrate control that generally +improves subjective visual quality. Enabling this flag may have negative impact +on performance and objective visual quality metric. +

+
+
low_delay_brc
+

Setting this flag turns on or off LowDelayBRC feature in qsv plugin, which provides +more accurate bitrate control to minimize the variance of bitstream size frame +by frame. Value: -1-default 0-off 1-on +

+
+
adaptive_i
+

This flag controls insertion of I frames by the QSV encoder. Turn ON this flag +to allow changing of frame type from P and B to I. +

+
+
adaptive_b
+

This flag controls changing of frame type from B to P. +

+
+
p_strategy
+

Enable P-pyramid: 0-default 1-simple 2-pyramid(bf need to be set to 0). +

+
+
b_strategy
+

This option controls usage of B frames as reference. +

+
+
dblk_idc
+

This option disable deblocking. It has value in range 0~2. +

+
+
cavlc
+

If set, CAVLC is used; if unset, CABAC is used for encoding. +

+
+
vcm
+

Video conferencing mode, please see ratecontrol method. +

+
+
idr_interval
+

Distance (in I-frames) between IDR frames. +

+
+
pic_timing_sei
+

Insert picture timing SEI with pic_struct_syntax element. +

+
+
single_sei_nal_unit
+

Put all the SEI messages into one NALU. +

+
+
max_dec_frame_buffering
+

Maximum number of frames buffered in the DPB. +

+
+
look_ahead
+

Use VBR algorithm with look ahead. +

+
+
look_ahead_depth
+

Depth of look ahead in number frames. +

+
+
look_ahead_downsampling
+

Downscaling factor for the frames saved for the lookahead analysis. +

+
‘unknown’
+
‘auto’
+
‘off’
+
‘2x’
+
‘4x’
+
+ +
+
int_ref_type
+

Specifies intra refresh type. The major goal of intra refresh is improvement of +error resilience without significant impact on encoded bitstream size caused by +I frames. The SDK encoder achieves this by encoding part of each frame in +refresh cycle using intra MBs. none means no refresh. vertical means +vertical refresh, by column of MBs. horizontal means horizontal refresh, +by rows of MBs. slice means horizontal refresh by slices without +overlapping. In case of slice, in_ref_cycle_size is ignored. To enable +intra refresh, B frame should be set to 0. +

+
+
int_ref_cycle_size
+

Specifies number of pictures within refresh cycle starting from 2. 0 and 1 are +invalid values. +

+
+
int_ref_qp_delta
+

Specifies QP difference for inserted intra MBs. This is signed value in +[-51, 51] range if target encoding bit-depth for luma samples is 8 and this +range is [-63, 63] for 10 bit-depth or [-75, 75] for 12 bit-depth respectively. +

+
+
int_ref_cycle_dist
+

Distance between the beginnings of the intra-refresh cycles in frames. +

+
+
profile
+
+
‘unknown’
+
‘baseline’
+
‘main’
+
‘high’
+
+ +
+
a53cc
+

Use A53 Closed Captions (if available). +

+
+
aud
+

Insert the Access Unit Delimiter NAL. +

+
+
mfmode
+

Multi-Frame Mode. +

+
‘off’
+
‘auto’
+
+ +
+
repeat_pps
+

Repeat pps for every frame. +

+
+
max_qp_i
+

Maximum video quantizer scale for I frame. +

+
+
min_qp_i
+

Minimum video quantizer scale for I frame. +

+
+
max_qp_p
+

Maximum video quantizer scale for P frame. +

+
+
min_qp_p
+

Minimum video quantizer scale for P frame. +

+
+
max_qp_b
+

Maximum video quantizer scale for B frame. +

+
+
min_qp_b
+

Minimum video quantizer scale for B frame. +

+
+
scenario
+

Provides a hint to encoder about the scenario for the encoding session. +

+
‘unknown’
+
‘displayremoting’
+
‘videoconference’
+
‘archive’
+
‘livestreaming’
+
‘cameracapture’
+
‘videosurveillance’
+
‘gamestreaming’
+
‘remotegaming’
+
+ +
+
avbr_accuracy
+

Accuracy of the AVBR ratecontrol (unit of tenth of percent). +

+
+
avbr_convergence
+

Convergence of the AVBR ratecontrol (unit of 100 frames) +

+

The parameters avbr_accuracy and avbr_convergence are for the +average variable bitrate control (AVBR) algorithm. +The algorithm focuses on overall encoding quality while meeting the specified +bitrate, target_bitrate, within the accuracy range avbr_accuracy, +after a avbr_Convergence period. This method does not follow HRD and the +instant bitrate is not capped or padded. +

+
+
skip_frame
+

Use per-frame metadata "qsv_skip_frame" to skip frame when encoding. This option +defines the usage of this metadata. +

+
‘no_skip’
+

Frame skipping is disabled. +

+
‘insert_dummy’
+

Encoder inserts into bitstream frame where all macroblocks are encoded as +skipped. +

+
‘insert_nothing’
+

Similar to insert_dummy, but encoder inserts nothing into bitstream. The skipped +frames are still used in brc. For example, gop still include skipped frames, and +the frames after skipped frames will be larger in size. +

+
‘brc_only’
+

skip_frame metadata indicates the number of missed frames before the current +frame. +

+
+ +
+
+ + +

9.30.6 HEVC Options

+

These options are used by hevc_qsv +

+
+
extbrc
+

Extended bitrate control. +

+
+
recovery_point_sei
+

Set this flag to insert the recovery point SEI message at the beginning of every +intra refresh cycle. +

+
+
rdo
+

Enable rate distortion optimization. +

+
+
max_frame_size
+

Maximum encoded frame size in bytes. +

+
+
max_frame_size_i
+

Maximum encoded frame size for I frames in bytes. If this value is set as larger +than zero, then for I frames the value set by max_frame_size is ignored. +

+
+
max_frame_size_p
+

Maximum encoded frame size for P frames in bytes. If this value is set as larger +than zero, then for P frames the value set by max_frame_size is ignored. +

+
+
max_slice_size
+

Maximum encoded slice size in bytes. +

+
+
mbbrc
+

Setting this flag enables macroblock level bitrate control that generally +improves subjective visual quality. Enabling this flag may have negative impact +on performance and objective visual quality metric. +

+
+
low_delay_brc
+

Setting this flag turns on or off LowDelayBRC feature in qsv plugin, which provides +more accurate bitrate control to minimize the variance of bitstream size frame +by frame. Value: -1-default 0-off 1-on +

+
+
adaptive_i
+

This flag controls insertion of I frames by the QSV encoder. Turn ON this flag +to allow changing of frame type from P and B to I. +

+
+
adaptive_b
+

This flag controls changing of frame type from B to P. +

+
+
p_strategy
+

Enable P-pyramid: 0-default 1-simple 2-pyramid(bf need to be set to 0). +

+
+
b_strategy
+

This option controls usage of B frames as reference. +

+
+
dblk_idc
+

This option disable deblocking. It has value in range 0~2. +

+
+
idr_interval
+

Distance (in I-frames) between IDR frames. +

+
‘begin_only’
+

Output an IDR-frame only at the beginning of the stream. +

+
+ +
+
load_plugin
+

A user plugin to load in an internal session. +

+
‘none’
+
‘hevc_sw’
+
‘hevc_hw’
+
+ +
+
load_plugins
+

A :-separate list of hexadecimal plugin UIDs to load in +an internal session. +

+
+
look_ahead_depth
+

Depth of look ahead in number frames, available when extbrc option is enabled. +

+
+
profile
+

Set the encoding profile (scc requires libmfx >= 1.32). +

+
+
‘unknown’
+
‘main’
+
‘main10’
+
‘mainsp’
+
‘rext’
+
‘scc’
+
+ +
+
tier
+

Set the encoding tier (only level >= 4 can support high tier). +This option only takes effect when the level option is specified. +

+
+
‘main’
+
‘high’
+
+ +
+
gpb
+

1: GPB (generalized P/B frame) +

+

0: regular P frame. +

+
+
tile_cols
+

Number of columns for tiled encoding. +

+
+
tile_rows
+

Number of rows for tiled encoding. +

+
+
aud
+

Insert the Access Unit Delimiter NAL. +

+
+
pic_timing_sei
+

Insert picture timing SEI with pic_struct_syntax element. +

+
+
transform_skip
+

Turn this option ON to enable transformskip. It is supported on platform equal +or newer than ICL. +

+
+
int_ref_type
+

Specifies intra refresh type. The major goal of intra refresh is improvement of +error resilience without significant impact on encoded bitstream size caused by +I frames. The SDK encoder achieves this by encoding part of each frame in +refresh cycle using intra MBs. none means no refresh. vertical means +vertical refresh, by column of MBs. horizontal means horizontal refresh, +by rows of MBs. slice means horizontal refresh by slices without +overlapping. In case of slice, in_ref_cycle_size is ignored. To enable +intra refresh, B frame should be set to 0. +

+
+
int_ref_cycle_size
+

Specifies number of pictures within refresh cycle starting from 2. 0 and 1 are +invalid values. +

+
+
int_ref_qp_delta
+

Specifies QP difference for inserted intra MBs. This is signed value in +[-51, 51] range if target encoding bit-depth for luma samples is 8 and this +range is [-63, 63] for 10 bit-depth or [-75, 75] for 12 bit-depth respectively. +

+
+
int_ref_cycle_dist
+

Distance between the beginnings of the intra-refresh cycles in frames. +

+
+
max_qp_i
+

Maximum video quantizer scale for I frame. +

+
+
min_qp_i
+

Minimum video quantizer scale for I frame. +

+
+
max_qp_p
+

Maximum video quantizer scale for P frame. +

+
+
min_qp_p
+

Minimum video quantizer scale for P frame. +

+
+
max_qp_b
+

Maximum video quantizer scale for B frame. +

+
+
min_qp_b
+

Minimum video quantizer scale for B frame. +

+
+
scenario
+

Provides a hint to encoder about the scenario for the encoding session. +

+
‘unknown’
+
‘displayremoting’
+
‘videoconference’
+
‘archive’
+
‘livestreaming’
+
‘cameracapture’
+
‘videosurveillance’
+
‘gamestreaming’
+
‘remotegaming’
+
+ +
+
avbr_accuracy
+

Accuracy of the AVBR ratecontrol (unit of tenth of percent). +

+
+
avbr_convergence
+

Convergence of the AVBR ratecontrol (unit of 100 frames) +

+

The parameters avbr_accuracy and avbr_convergence are for the +average variable bitrate control (AVBR) algorithm. +The algorithm focuses on overall encoding quality while meeting the specified +bitrate, target_bitrate, within the accuracy range avbr_accuracy, +after a avbr_Convergence period. This method does not follow HRD and the +instant bitrate is not capped or padded. +

+
+
skip_frame
+

Use per-frame metadata "qsv_skip_frame" to skip frame when encoding. This option +defines the usage of this metadata. +

+
‘no_skip’
+

Frame skipping is disabled. +

+
‘insert_dummy’
+

Encoder inserts into bitstream frame where all macroblocks are encoded as +skipped. +

+
‘insert_nothing’
+

Similar to insert_dummy, but encoder inserts nothing into bitstream. The skipped +frames are still used in brc. For example, gop still include skipped frames, and +the frames after skipped frames will be larger in size. +

+
‘brc_only’
+

skip_frame metadata indicates the number of missed frames before the current +frame. +

+
+ +
+
+ + +

9.30.7 MPEG2 Options

+

These options are used by mpeg2_qsv +

+
profile
+
+
‘unknown’
+
‘simple’
+
‘main’
+
‘high’
+
+
+
+ + +

9.30.8 VP9 Options

+

These options are used by vp9_qsv +

+
profile
+
+
‘unknown’
+
‘profile0’
+
‘profile1’
+
‘profile2’
+
‘profile3’
+
+ +
+
tile_cols
+

Number of columns for tiled encoding (requires libmfx >= 1.29). +

+
+
tile_rows
+

Number of rows for tiled encoding (requires libmfx >= 1.29). +

+
+ + +

9.30.9 AV1 Options

+

These options are used by av1_qsv (requires libvpl). +

+
profile
+
+
‘unknown’
+
‘main’
+
+ +
+
tile_cols
+

Number of columns for tiled encoding. +

+
+
tile_rows
+

Number of rows for tiled encoding. +

+
+
adaptive_i
+

This flag controls insertion of I frames by the QSV encoder. Turn ON this flag +to allow changing of frame type from P and B to I. +

+
+
adaptive_b
+

This flag controls changing of frame type from B to P. +

+
+
b_strategy
+

This option controls usage of B frames as reference. +

+
+
extbrc
+

Extended bitrate control. +

+
+
look_ahead_depth
+

Depth of look ahead in number frames, available when extbrc option is enabled. +

+
+
low_delay_brc
+

Setting this flag turns on or off LowDelayBRC feature in qsv plugin, which provides +more accurate bitrate control to minimize the variance of bitstream size frame +by frame. Value: -1-default 0-off 1-on +

+
+
max_frame_size
+

Set the allowed max size in bytes for each frame. If the frame size exceeds +the limitation, encoder will adjust the QP value to control the frame size. +Invalid in CQP rate control mode. +

+
+
max_frame_size_i
+

Maximum encoded frame size for I frames in bytes. If this value is set as larger +than zero, then for I frames the value set by max_frame_size is ignored. +

+
+
max_frame_size_p
+

Maximum encoded frame size for P frames in bytes. If this value is set as larger +than zero, then for P frames the value set by max_frame_size is ignored. +

+
+ + +

9.31 snow

+ + +

9.31.1 Options

+ +
+
iterative_dia_size
+

dia size for the iterative motion estimation +

+
+ + +

9.32 VAAPI encoders

+ +

Wrappers for hardware encoders accessible via VAAPI. +

+

These encoders only accept input in VAAPI hardware surfaces. If you have input +in software frames, use the hwupload filter to upload them to the GPU. +

+

The following standard libavcodec options are used: +

    +
  • g / gop_size +
  • bf / max_b_frames +
  • profile + +

    If not set, this will be determined automatically from the format of the input +frames and the profiles supported by the driver. +

  • level +
  • b / bit_rate +
  • maxrate / rc_max_rate +
  • bufsize / rc_buffer_size +
  • rc_init_occupancy / rc_initial_buffer_occupancy +
  • compression_level + +

    Speed / quality tradeoff: higher values are faster / worse quality. +

  • q / global_quality + +

    Size / quality tradeoff: higher values are smaller / worse quality. +

  • qmin +
  • qmax +
  • i_qfactor / i_quant_factor +
  • i_qoffset / i_quant_offset +
  • b_qfactor / b_quant_factor +
  • b_qoffset / b_quant_offset +
  • slices +
+ +

All encoders support the following options: +

+
low_power
+

Some drivers/platforms offer a second encoder for some codecs intended to use +less power than the default encoder; setting this option will attempt to use +that encoder. Note that it may support a reduced feature set, so some other +options may not be available in this mode. +

+
+
idr_interval
+

Set the number of normal intra frames between full-refresh (IDR) frames in +open-GOP mode. The intra frames are still IRAPs, but will not include global +headers and may have non-decodable leading pictures. +

+
+
b_depth
+

Set the B-frame reference depth. When set to one (the default), all B-frames +will refer only to P- or I-frames. When set to greater values multiple layers +of B-frames will be present, frames in each layer only referring to frames in +higher layers. +

+
+
async_depth
+

Maximum processing parallelism. Increase this to improve single channel +performance. This option doesn’t work if driver doesn’t implement vaSyncBuffer +function. Please make sure there are enough hw_frames allocated if a large +number of async_depth is used. +

+
+
max_frame_size
+

Set the allowed max size in bytes for each frame. If the frame size exceeds +the limitation, encoder will adjust the QP value to control the frame size. +Invalid in CQP rate control mode. +

+
+
rc_mode
+

Set the rate control mode to use. A given driver may only support a subset of +modes. +

+

Possible modes: +

+
auto
+

Choose the mode automatically based on driver support and the other options. +This is the default. +

+
CQP
+

Constant-quality. +

+
CBR
+

Constant-bitrate. +

+
VBR
+

Variable-bitrate. +

+
ICQ
+

Intelligent constant-quality. +

+
QVBR
+

Quality-defined variable-bitrate. +

+
AVBR
+

Average variable bitrate. +

+
+ +
+
blbrc
+

Enable block level rate control, which assigns different bitrate block by block. +Invalid for CQP mode. +

+
+
+ +

Each encoder also has its own specific options: +

+
av1_vaapi
+

profile sets the value of seq_profile. +tier sets the value of seq_tier. +level sets the value of seq_level_idx. +

+
+
tiles
+

Set the number of tiles to encode the input video with, as columns x rows. +(default is auto, which means use minimal tile column/row number). +

+
tile_groups
+

Set tile groups number. All the tiles will be distributed as evenly as possible to +each tile group. (default is 1). +

+
+ +
+
h264_vaapi
+

profile sets the value of profile_idc and the constraint_set*_flags. +level sets the value of level_idc. +

+
+
coder
+

Set entropy encoder (default is cabac). Possible values: +

+
+
‘ac’
+
‘cabac’
+

Use CABAC. +

+
+
‘vlc’
+
‘cavlc’
+

Use CAVLC. +

+
+ +
+
aud
+

Include access unit delimiters in the stream (not included by default). +

+
+
sei
+

Set SEI message types to include. +Some combination of the following values: +

+
‘identifier’
+

Include a user_data_unregistered message containing information about +the encoder. +

+
‘timing’
+

Include picture timing parameters (buffering_period and +pic_timing messages). +

+
‘recovery_point’
+

Include recovery points where appropriate (recovery_point messages). +

+
+ +
+
+ +
+
hevc_vaapi
+

profile and level set the values of +general_profile_idc and general_level_idc respectively. +

+
+
aud
+

Include access unit delimiters in the stream (not included by default). +

+
+
tier
+

Set general_tier_flag. This may affect the level chosen for the stream +if it is not explicitly specified. +

+
+
sei
+

Set SEI message types to include. +Some combination of the following values: +

+
‘hdr’
+

Include HDR metadata if the input frames have it +(mastering_display_colour_volume and content_light_level +messages). +

+
+ +
+
tiles
+

Set the number of tiles to encode the input video with, as columns x rows. +Larger numbers allow greater parallelism in both encoding and decoding, but +may decrease coding efficiency. +

+
+
+ +
+
mjpeg_vaapi
+

Only baseline DCT encoding is supported. The encoder always uses the standard +quantisation and huffman tables - global_quality scales the standard +quantisation table (range 1-100). +

+

For YUV, 4:2:0, 4:2:2 and 4:4:4 subsampling modes are supported. RGB is also +supported, and will create an RGB JPEG. +

+
+
jfif
+

Include JFIF header in each frame (not included by default). +

+
huffman
+

Include standard huffman tables (on by default). Turning this off will save +a few hundred bytes in each output frame, but may lose compatibility with some +JPEG decoders which don’t fully handle MJPEG. +

+
+ +
+
mpeg2_vaapi
+

profile and level set the value of profile_and_level_indication. +

+
+
vp8_vaapi
+

B-frames are not supported. +

+

global_quality sets the q_idx used for non-key frames (range 0-127). +

+
+
loop_filter_level
+
loop_filter_sharpness
+

Manually set the loop filter parameters. +

+
+ +
+
vp9_vaapi
+

global_quality sets the q_idx used for P-frames (range 0-255). +

+
+
loop_filter_level
+
loop_filter_sharpness
+

Manually set the loop filter parameters. +

+
+ +

B-frames are supported, but the output stream is always in encode order rather than display +order. If B-frames are enabled, it may be necessary to use the vp9_raw_reorder +bitstream filter to modify the output stream to display frames in the correct order. +

+

Only normal frames are produced - the vp9_superframe bitstream filter may be +required to produce a stream usable with all decoders. +

+
+
+ + +

9.33 vbn

+ +

Vizrt Binary Image encoder. +

+

This format is used by the broadcast vendor Vizrt for quick texture streaming. +Advanced features of the format such as LZW compression of texture data or +generation of mipmaps are not supported. +

+ +

9.33.1 Options

+ +
+
format string
+

Sets the texture compression used by the VBN file. Can be dxt1, +dxt5 or raw. Default is dxt5. +

+
+ + +

9.34 vc2

+ +

SMPTE VC-2 (previously BBC Dirac Pro). This codec was primarily aimed at +professional broadcasting but since it supports yuv420, yuv422 and yuv444 at +8 (limited range or full range), 10 or 12 bits, this makes it suitable for +other tasks which require low overhead and low compression (like screen +recording). +

+ +

9.34.1 Options

+ +
+
b
+

Sets target video bitrate. Usually that’s around 1:6 of the uncompressed +video bitrate (e.g. for 1920x1080 50fps yuv422p10 that’s around 400Mbps). Higher +values (close to the uncompressed bitrate) turn on lossless compression mode. +

+
+
field_order
+

Enables field coding when set (e.g. to tt - top field first) for interlaced +inputs. Should increase compression with interlaced content as it splits the +fields and encodes each separately. +

+
+
wavelet_depth
+

Sets the total amount of wavelet transforms to apply, between 1 and 5 (default). +Lower values reduce compression and quality. Less capable decoders may not be +able to handle values of wavelet_depth over 3. +

+
+
wavelet_type
+

Sets the transform type. Currently only 5_3 (LeGall) and 9_7 +(Deslauriers-Dubuc) +are implemented, with 9_7 being the one with better compression and thus +is the default. +

+
+
slice_width
+
slice_height
+

Sets the slice size for each slice. Larger values result in better compression. +For compatibility with other more limited decoders use slice_width of +32 and slice_height of 8. +

+
+
tolerance
+

Sets the undershoot tolerance of the rate control system in percent. This is +to prevent an expensive search from being run. +

+
+
qm
+

Sets the quantization matrix preset to use by default or when wavelet_depth +is set to 5 +

    +
  • default +Uses the default quantization matrix from the specifications, extended with +values for the fifth level. This provides a good balance between keeping detail +and omitting artifacts. + +
  • flat +Use a completely zeroed out quantization matrix. This increases PSNR but might +reduce perception. Use in bogus benchmarks. + +
  • color +Reduces detail but attempts to preserve color at extremely low bitrates. +
+ +
+
+ + + +

10 Subtitles Encoders

+ + +

10.1 dvbsub

+ +

This codec encodes the bitmap subtitle format that is used in DVB +broadcasts and recordings. The bitmaps are typically embedded in a +container such as MPEG-TS as a separate stream. +

+ +

10.1.1 Options

+ +
+
min_bpp integer (2, 4, or 8)
+

Set a minimum bits-per-pixel value for the subtitle color lookup tables. +

+

DVB supports 2, 4, and 8 bits-per-pixel color lookup tables. This +option enables forcing a particular bits-per-pixel value regardless of +the number of colors. Since not all players support or properly +support 2 bits-per-pixel, this value defaults to 4. +

+
+
+ + +

10.2 dvdsub

+ +

This codec encodes the bitmap subtitle format that is used in DVDs. +Typically they are stored in VOBSUB file pairs (*.idx + *.sub), +and they can also be used in Matroska files. +

+ +

10.2.1 Options

+ +
+
palette
+

Specify the global palette used by the bitmaps. +

+

The format for this option is a string containing 16 24-bits hexadecimal +numbers (without 0x prefix) separated by commas, for example 0d00ee, +ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, +7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b. +

+
+
even_rows_fix
+

When set to 1, enable a work-around that makes the number of pixel rows +even in all subtitles. This fixes a problem with some players that +cut off the bottom row if the number is odd. The work-around just adds +a fully transparent row if needed. The overhead is low, typically +one byte per subtitle on average. +

+

By default, this work-around is disabled. +

+
+ + +

10.3 lrc

+ +

This codec encodes the LRC lyrics format. +

+ +

10.3.1 Options

+ +
+
precision
+

Specify the precision of the fractional part of the timestamp. Time base is +determined based on this value. +

+

Defaults to 2 for centiseconds. +

+
+ + + +

11 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavcodec +

+ + +

12 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-devices.html b/ffmpeg-n8.1/doc/ffmpeg-devices.html new file mode 100644 index 00000000..292ce3d1 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-devices.html @@ -0,0 +1,2438 @@ + + + + + + + FFmpeg Devices Documentation + + + + + + +
+

+ FFmpeg Devices Documentation +

+ + + + + + + +

1 Description

+ +

This document describes the input and output devices provided by the +libavdevice library. +

+ + +

2 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the device +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+ + +

3 Input Devices

+ +

Input devices are configured elements in FFmpeg which enable accessing +the data coming from a multimedia device attached to your system. +

+

When you configure your FFmpeg build, all the supported input devices +are enabled by default. You can list all available ones using the +configure option "–list-indevs". +

+

You can disable all the input devices using the configure option +"–disable-indevs", and selectively enable an input device using the +option "–enable-indev=INDEV", or you can disable a particular +input device using the option "–disable-indev=INDEV". +

+

The option "-devices" of the ff* tools will display the list of +supported input devices. +

+

A description of the currently available input devices follows. +

+ +

3.1 alsa

+ +

ALSA (Advanced Linux Sound Architecture) input device. +

+

To enable this input device during configuration you need libasound +installed on your system. +

+

This device allows capturing from an ALSA device. The name of the +device to capture has to be an ALSA card identifier. +

+

An ALSA identifier has the syntax: +

+
hw:CARD[,DEV[,SUBDEV]]
+
+ +

where the DEV and SUBDEV components are optional. +

+

The three arguments (in order: CARD,DEV,SUBDEV) +specify card number or identifier, device number and subdevice number +(-1 means any). +

+

To see the list of cards currently recognized by your system check the +files /proc/asound/cards and /proc/asound/devices. +

+

For example to capture with ffmpeg from an ALSA device with +card id 0, you may run the command: +

+
ffmpeg -f alsa -i hw:0 alsaout.wav
+
+ +

For more information see: +http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html +

+ +

3.1.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

3.2 android_camera

+ +

Android camera input device. +

+

This input devices uses the Android Camera2 NDK API which is +available on devices with API level 24+. The availability of +android_camera is autodetected during configuration. +

+

This device allows capturing from all cameras on an Android device, +which are integrated into the Camera2 NDK API. +

+

The available cameras are enumerated internally and can be selected +with the camera_index parameter. The input file string is +discarded. +

+

Generally the back facing camera has index 0 while the front facing +camera has index 1. +

+ +

3.2.1 Options

+ +
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Falls back to the first available configuration reported by +Android if requested video size is not available or by default. +

+
+
framerate
+

Set the video framerate. +Falls back to the first available configuration reported by +Android if requested framerate is not available or by default (-1). +

+
+
camera_index
+

Set the index of the camera to use. Default is 0. +

+
+
input_queue_size
+

Set the maximum number of frames to buffer. Default is 5. +

+
+
+ + +

3.3 avfoundation

+ +

AVFoundation input device. +

+

AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS. +

+

The input filename has to be given in the following syntax: +

+
-i "[[VIDEO]:[AUDIO]]"
+
+

The first entry selects the video input while the latter selects the audio input. +The stream has to be specified by the device name or the device index as shown by the device list. +Alternatively, the video and/or audio input device can be chosen by index using the + + -video_device_index <INDEX> + +and/or + + -audio_device_index <INDEX> + +, overriding any +device name or index given in the input filename. +

+

All available devices can be enumerated by using -list_devices true, listing +all device names and corresponding indices. +

+

There are two device name aliases: +

+
default
+

Select the AVFoundation default device of the corresponding type. +

+
+
none
+

Do not record the corresponding media type. +This is equivalent to specifying an empty device name or index. +

+
+
+ + +

3.3.1 Options

+ +

AVFoundation supports the following options: +

+
+
-list_devices <TRUE|FALSE>
+

If set to true, a list of all available input devices is given showing all +device names and indices. +

+
+
-video_device_index <INDEX>
+

Specify the video device by its index. Overrides anything given in the input filename. +

+
+
-audio_device_index <INDEX>
+

Specify the audio device by its index. Overrides anything given in the input filename. +

+
+
-pixel_format <FORMAT>
+

Request the video device to use a specific pixel format. +If the specified format is not supported, a list of available formats is given +and the first one in this list is used instead. Available pixel formats are: +monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0, + bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10, + yuv420p, nv12, yuyv422, gray +

+
+
-framerate
+

Set the grabbing frame rate. Default is ntsc, corresponding to a +frame rate of 30000/1001. +

+
+
-video_size
+

Set the video frame size. +

+
+
-capture_cursor
+

Capture the mouse pointer. Default is 0. +

+
+
-capture_mouse_clicks
+

Capture the screen mouse clicks. Default is 0. +

+
+
-capture_raw_data
+

Capture the raw device data. Default is 0. +Using this option may result in receiving the underlying data delivered to the AVFoundation framework. E.g. for muxed devices that sends raw DV data to the framework (like tape-based camcorders), setting this option to false results in extracted video frames captured in the designated pixel format only. Setting this option to true results in receiving the raw DV stream untouched. +

+
+ + +

3.3.2 Examples

+ +
    +
  • Print the list of AVFoundation supported devices and exit: +
    +
    $ ffmpeg -f avfoundation -list_devices true -i ""
    +
    + +
  • Record video from video device 0 and audio from audio device 0 into out.avi: +
    +
    $ ffmpeg -f avfoundation -i "0:0" out.avi
    +
    + +
  • Record video from video device 2 and audio from audio device 1 into out.avi: +
    +
    $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi
    +
    + +
  • Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi: +
    +
    $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi
    +
    + +
  • Record raw DV data from a suitable input device and write the output into out.dv: +
    +
    $ ffmpeg -f avfoundation -capture_raw_data true -i "zr100:none" out.dv
    +
    + + +
+ + +

3.4 decklink

+ +

The decklink input device provides capture capabilities for Blackmagic +DeckLink devices. +

+

To enable this input device, you need the Blackmagic DeckLink SDK and you +need to configure with the appropriate --extra-cflags +and --extra-ldflags. +On Windows, you need to run the IDL files through widl. +

+

DeckLink is very picky about the formats it supports. Pixel format of the +input can be set with raw_format. +Framerate and video size must be determined for your device with +-list_formats 1. Audio sample rate is always 48 kHz and the number +of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single +audio track. +

+ +

3.4.1 Options

+ +
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. This option is deprecated, please use the +-sources option of ffmpeg to list the available input devices. +

+
+
list_formats
+

If set to true, print a list of supported formats and exit. +Defaults to false. +

+
+
format_code <FourCC>
+

This sets the input video format to the format given by the FourCC. To see +the supported values of your device(s) use list_formats. +Note that there is a FourCC 'pal ' that can also be used +as pal (3 letters). +Default behavior is autodetection of the input video format, if the hardware +supports it. +

+
+
raw_format
+

Set the pixel format of the captured video. +Available values are: +

+
‘auto’
+
+

This is the default which means 8-bit YUV 422 or 8-bit ARGB if format +autodetection is used, 8-bit YUV 422 otherwise. +

+
+
‘uyvy422’
+
+

8-bit YUV 422. +

+
+
‘yuv422p10’
+
+

10-bit YUV 422. +

+
+
‘argb’
+
+

8-bit RGB. +

+
+
‘bgra’
+
+

8-bit RGB. +

+
+
‘rgb10’
+
+

10-bit RGB. +

+
+
+ +
+
teletext_lines
+

If set to nonzero, an additional teletext stream will be captured from the +vertical ancillary data. Both SD PAL (576i) and HD (1080i or 1080p) +sources are supported. In case of HD sources, OP47 packets are decoded. +

+

This option is a bitmask of the SD PAL VBI lines captured, specifically lines 6 +to 22, and lines 318 to 335. Line 6 is the LSB in the mask. Selected lines +which do not contain teletext information will be ignored. You can use the +special all constant to select all possible lines, or +standard to skip lines 6, 318 and 319, which are not compatible with +all receivers. +

+

For SD sources, ffmpeg needs to be compiled with --enable-libzvbi. For +HD sources, on older (pre-4K) DeckLink card models you have to capture in 10 +bit mode. +

+
+
channels
+

Defines number of audio channels to capture. Must be ‘2’, ‘8’ or ‘16’. +Defaults to ‘2’. +

+
+
duplex_mode
+

Sets the decklink device duplex/profile mode. Must be ‘unset’, ‘half’, ‘full’, +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +Defaults to ‘unset’. +

+

Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property. +For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 +sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile +is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles. +

+

Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0): +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +

+

Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2: +‘half’, ‘full’ +

+
+
timecode_format
+

Timecode type to include in the frame and video stream metadata. Must be +‘none’, ‘rp188vitc’, ‘rp188vitc2’, ‘rp188ltc’, +‘rp188hfr’, ‘rp188any’, ‘vitc’, ‘vitc2’, or ‘serial’. +Defaults to ‘none’ (not included). +

+

In order to properly support 50/60 fps timecodes, the ordering of the queried +timecode types for ‘rp188any’ is HFR, VITC1, VITC2 and LTC for >30 fps +content. Note that this is slightly different to the ordering used by the +DeckLink API, which is HFR, VITC1, LTC, VITC2. +

+
+
video_input
+

Sets the video input source. Must be ‘unset’, ‘sdi’, ‘hdmi’, +‘optical_sdi’, ‘component’, ‘composite’ or ‘s_video’. +Defaults to ‘unset’. +

+
+
audio_input
+

Sets the audio input source. Must be ‘unset’, ‘embedded’, +‘aes_ebu’, ‘analog’, ‘analog_xlr’, ‘analog_rca’ or +‘microphone’. Defaults to ‘unset’. +

+
+
video_pts
+

Sets the video packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘video’. +

+
+
audio_pts
+

Sets the audio packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘audio’. +

+
+
draw_bars
+

If set to ‘true’, color bars are drawn in the event of a signal loss. +Defaults to ‘true’. +This option is deprecated, please use the signal_loss_action option. +

+
+
signal_loss_action
+

Sets the action to take in the event of a signal loss. Accepts one of the +following values: +

+
+
1, none
+

Do nothing on signal loss. This usually results in black frames. +

+
2, bars
+

Draw color bars on signal loss. Only supported for 8-bit input signals. +

+
3, repeat
+

Repeat the last video frame on signal loss. +

+
+ +

Defaults to ‘bars’. +

+
+
queue_size
+

Sets maximum input buffer size in bytes. If the buffering reaches this value, +incoming frames will be dropped. +Defaults to ‘1073741824’. +

+
+
audio_depth
+

Sets the audio sample bit depth. Must be ‘16’ or ‘32’. +Defaults to ‘16’. +

+
+
decklink_copyts
+

If set to true, timestamps are forwarded as they are without removing +the initial offset. +Defaults to false. +

+
+
timestamp_align
+

Capture start time alignment in seconds. If set to nonzero, input frames are +dropped till the system timestamp aligns with configured value. +Alignment difference of up to one frame duration is tolerated. +This is useful for maintaining input synchronization across N different +hardware devices deployed for ’N-way’ redundancy. The system time of different +hardware devices should be synchronized with protocols such as NTP or PTP, +before using this option. +Note that this method is not foolproof. In some border cases input +synchronization may not happen due to thread scheduling jitters in the OS. +Either sync could go wrong by 1 frame or in a rarer case +timestamp_align seconds. +Defaults to ‘0’. +

+
+
wait_for_tc (bool)
+

Drop frames till a frame with timecode is received. Sometimes serial timecode +isn’t received with the first input frame. If that happens, the stored stream +timecode will be inaccurate. If this option is set to true, input frames +are dropped till a frame with timecode is received. +Option timecode_format must be specified. +Defaults to false. +

+
+
enable_klv(bool)
+

If set to true, extracts KLV data from VANC and outputs KLV packets. +KLV VANC packets are joined based on MID and PSC fields and aggregated into +one KLV packet. +Defaults to false. +

+
+
+ + +

3.4.2 Examples

+ +
    +
  • List input devices: +
    +
    ffmpeg -sources decklink
    +
    + +
  • List supported formats: +
    +
    ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'
    +
    + +
  • Capture video clip at 1080i50: +
    +
    ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 10 bit: +
    +
    ffmpeg -raw_format yuv422p10 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 with 16 audio channels: +
    +
    ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
+ + +

3.5 dshow

+ +

Windows DirectShow input device. +

+

DirectShow support is enabled when FFmpeg is built with the mingw-w64 project. +Currently only audio and video devices are supported. +

+

Multiple devices may be opened as separate inputs, but they may also be +opened on the same input, which should improve synchronism between them. +

+

The input name should be in the format: +

+
+
TYPE=NAME[:TYPE=NAME]
+
+ +

where TYPE can be either audio or video, +and NAME is the device’s name or alternative name.. +

+ +

3.5.1 Options

+ +

If no options are specified, the device’s defaults are used. +If the device does not support the requested options, it will +fail to open. +

+
+
video_size
+

Set the video size in the captured video. +

+
+
framerate
+

Set the frame rate in the captured video. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. +

+
+
channels
+

Set the number of channels in the captured audio. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +

+
+
list_options
+

If set to true, print a list of selected device’s options +and exit. +

+
+
video_device_number
+

Set video device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
audio_device_number
+

Set audio device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
pixel_format
+

Select pixel format to be used by DirectShow. This may only be set when +the video codec is not set or set to rawvideo. +

+
+
audio_buffer_size
+

Set audio device buffer size in milliseconds (which can directly +impact latency, depending on the device). +Defaults to using the audio device’s +default buffer size (typically some multiple of 500ms). +Setting this value too low can degrade performance. +See also +http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx +

+
+
video_pin_name
+

Select video capture pin to use by name or alternative name. +

+
+
audio_pin_name
+

Select audio capture pin to use by name or alternative name. +

+
+
crossbar_video_input_pin_number
+

Select video input pin number for crossbar device. This will be +routed to the crossbar device’s Video Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
crossbar_audio_input_pin_number
+

Select audio input pin number for crossbar device. This will be +routed to the crossbar device’s Audio Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
show_video_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change video filter properties +and configurations manually. +Note that for crossbar devices, adjusting values in this dialog +may be needed at times to toggle between PAL (25 fps) and NTSC (29.97) +input frame rates, sizes, interlacing, etc. Changing these values can +enable different scan rates/frame rates and avoiding green bars at +the bottom, flickering scan lines, etc. +Note that with some devices, changing these properties can also affect future +invocations (sets new defaults) until system reboot occurs. +

+
+
show_audio_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change audio filter properties +and configurations manually. +

+
+
show_video_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens a video device. +

+
+
show_audio_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens an audio device. +

+
+
show_analog_tv_tuner_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV channels and frequencies. +

+
+
show_analog_tv_tuner_audio_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV audio (like mono vs. stereo, Language A,B or C). +

+
+
audio_device_load
+

Load an audio capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this an audio capture source has to be specified, but it can +be anything even fake one. +

+
+
audio_device_save
+

Save the currently used audio capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
video_device_load
+

Load a video capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this a video capture source has to be specified, but it can +be anything even fake one. +

+
+
video_device_save
+

Save the currently used video capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
use_video_device_timestamps
+

If set to false, the timestamp for video frames will be +derived from the wallclock instead of the timestamp provided by +the capture device. This allows working around devices that +provide unreliable timestamps. +

+
+
+ + +

3.5.2 Examples

+ +
    +
  • Print the list of DirectShow supported devices and exit: +
    +
    $ ffmpeg -list_devices true -f dshow -i dummy
    +
    + +
  • Open video device Camera: +
    +
    $ ffmpeg -f dshow -i video="Camera"
    +
    + +
  • Open second video device with name Camera: +
    +
    $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"
    +
    + +
  • Open video device Camera and audio device Microphone: +
    +
    $ ffmpeg -f dshow -i video="Camera":audio="Microphone"
    +
    + +
  • Print the list of supported options in selected device and exit: +
    +
    $ ffmpeg -list_options true -f dshow -i video="Camera"
    +
    + +
  • Specify pin names to capture by name or alternative name, specify alternative device name: +
    +
    $ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\{ca465100-deb0-4d59-818f-8c477184adf6}":audio="Microphone"
    +
    + +
  • Configure a crossbar device, specifying crossbar pins, allow user to adjust video capture properties at startup: +
    +
    $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0
    +     -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"
    +
    + +
+ + +

3.6 fbdev

+ +

Linux framebuffer input 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 +/dev/fb0. +

+

For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. +

+

See also http://linux-fbdev.sourceforge.net/, and fbset(1). +

+

To record from the framebuffer device /dev/fb0 with +ffmpeg: +

+
ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi
+
+ +

You can take a single screenshot image with the command: +

+
ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg
+
+ + +

3.6.1 Options

+ +
+
framerate
+

Set the frame rate. Default is 25. +

+
+
+ + +

3.7 gdigrab

+ +

Win32 GDI-based screen capture device. +

+

This device allows you to capture a region of the display on Windows. +

+

Amongst options for the input filenames are such elements as: +

+
desktop
+
+

or +

+
title=window_title
+
+

or +

+
hwnd=window_hwnd
+
+ +

The first option will capture the entire desktop, or a fixed region of the +desktop. The second and third options will instead capture the contents of a single +window, regardless of its position on the screen. +

+

For example, to grab the entire desktop using ffmpeg: +

+
ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg
+
+ +

Grab a 640x480 region at position 10,20: +

+
ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg
+
+ +

Grab the contents of the window named "Calculator" +

+
ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg
+
+ + +

3.7.1 Options

+ +
+
draw_mouse
+

Specify whether to draw the mouse pointer. Use the value 0 to +not draw the pointer. Default value is 1. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+

Note that show_region is incompatible with grabbing the contents +of a single window. +

+

For example: +

+
ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg
+
+ +
+
video_size
+

Set the video frame size. The default is to capture the full screen if desktop is selected, or the full window size if title=window_title is selected. +

+
+
offset_x
+

When capturing a region with video_size, set the distance from the left edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned to the left of your primary monitor, you will need to use a negative offset_x value to move the region to that monitor. +

+
+
offset_y
+

When capturing a region with video_size, set the distance from the top edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned above your primary monitor, you will need to use a negative offset_y value to move the region to that monitor. +

+
+
+ + +

3.8 iec61883

+ +

FireWire DV/HDV input device using libiec61883. +

+

To enable this input device, you need libiec61883, libraw1394 and +libavc1394 installed on your system. Use the configure option +--enable-libiec61883 to compile with the device enabled. +

+

The iec61883 capture device supports capturing from a video device +connected via IEEE1394 (FireWire), using libiec61883 and the new Linux +FireWire stack (juju). This is the default DV/HDV input method in Linux +Kernel 2.6.37 and later, since the old FireWire stack was removed. +

+

Specify the FireWire port to be used as input file, or "auto" +to choose the first port connected. +

+ +

3.8.1 Options

+ +
+
dvtype
+

Override autodetection of DV/HDV. This should only be used if auto +detection does not work, or if usage of a different device type +should be prohibited. Treating a DV device as HDV (or vice versa) will +not work and result in undefined behavior. +The values auto, dv and hdv are supported. +

+
+
dvbuffer
+

Set maximum size of buffer for incoming data, in frames. For DV, this +is an exact value. For HDV, it is not frame exact, since HDV does +not have a fixed frame size. +

+
+
dvguid
+

Select the capture device by specifying its GUID. Capturing will only +be performed from the specified device and fails if no device with the +given GUID is found. This is useful to select the input if multiple +devices are connected at the same time. +Look at /sys/bus/firewire/devices to find out the GUIDs. +

+
+
+ + +

3.8.2 Examples

+ +
    +
  • Grab and show the input of a FireWire DV/HDV device. +
    +
    ffplay -f iec61883 -i auto
    +
    + +
  • Grab and record the input of a FireWire DV/HDV device, +using a packet buffer of 100000 packets if the source is HDV. +
    +
    ffmpeg -f iec61883 -i auto -dvbuffer 100000 out.mpg
    +
    + +
+ + +

3.9 jack

+ +

JACK input device. +

+

To enable this input device during configuration you need libjack +installed on your system. +

+

A JACK input device creates one or more JACK writable clients, one for +each audio channel, with name client_name:input_N, where +client_name is the name provided by the application, and N +is a number which identifies the channel. +Each writable client will send the acquired data to the FFmpeg input +device. +

+

Once you have created one or more JACK readable clients, you need to +connect them to one or more JACK writable clients. +

+

To connect or disconnect JACK clients you can use the jack_connect +and jack_disconnect programs, or do it through a graphical interface, +for example with qjackctl. +

+

To list the JACK clients and their properties you can invoke the command +jack_lsp. +

+

Follows an example which shows how to capture a JACK readable client +with ffmpeg. +

+
# Create a JACK writable client with name "ffmpeg".
+$ ffmpeg -f jack -i ffmpeg -y out.wav
+
+# Start the sample jack_metro readable client.
+$ jack_metro -b 120 -d 0.2 -f 4000
+
+# List the current JACK clients.
+$ jack_lsp -c
+system:capture_1
+system:capture_2
+system:playback_1
+system:playback_2
+ffmpeg:input_1
+metro:120_bpm
+
+# Connect metro to the ffmpeg writable client.
+$ jack_connect metro:120_bpm ffmpeg:input_1
+
+ +

For more information read: +http://jackaudio.org/ +

+ +

3.9.1 Options

+ +
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

3.10 kmsgrab

+ +

KMS video input device. +

+

Captures the KMS scanout framebuffer associated with a specified CRTC or plane as a +DRM object that can be passed to other hardware functions. +

+

Requires either DRM master or CAP_SYS_ADMIN to run. +

+

If you don’t understand what all of that means, you probably don’t want this. Look at +x11grab instead. +

+ +

3.10.1 Options

+ +
+
device
+

DRM device to capture on. Defaults to /dev/dri/card0. +

+
+
format
+

Pixel format of the framebuffer. This can be autodetected if you are running Linux 5.7 +or later, but needs to be provided for earlier versions. Defaults to bgr0, +which is the most common format used by the Linux console and Xorg X server. +

+
+
format_modifier
+

Format modifier to signal on output frames. This is necessary to import correctly into +some APIs. It can be autodetected if you are running Linux 5.7 or later, but will need +to be provided explicitly when needed in earlier versions. See the libdrm documentation +for possible values. +

+
+
crtc_id
+

KMS CRTC ID to define the capture source. The first active plane on the given CRTC +will be used. +

+
+
plane_id
+

KMS plane ID to define the capture source. Defaults to the first active plane found if +neither crtc_id nor plane_id are specified. +

+
+
framerate
+

Framerate to capture at. This is not synchronised to any page flipping or framebuffer +changes - it just defines the interval at which the framebuffer is sampled. Sampling +faster than the framebuffer update rate will generate independent frames with the same +content. Defaults to 30. +

+
+
+ + +

3.10.2 Examples

+ +
    +
  • Capture from the first active plane, download the result to normal frames and encode. +This will only work if the framebuffer is both linear and mappable - if not, the result +may be scrambled or fail to download. +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwdownload,format=bgr0' output.mp4
    +
    + +
  • Capture from CRTC ID 42 at 60fps, map the result to VAAPI, convert to NV12 and encode as H.264. +
    +
    ffmpeg -crtc_id 42 -framerate 60 -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,scale_vaapi=w=1920:h=1080:format=nv12' -c:v h264_vaapi output.mp4
    +
    + +
  • To capture only part of a plane the output can be cropped - this can be used to capture +a single window, as long as it has a known absolute position and size. For example, to +capture and encode the middle quarter of a 1920x1080 plane: +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,crop=960:540:480:270,scale_vaapi=960:540:nv12' -c:v h264_vaapi output.mp4
    +
    + +
+ + +

3.11 lavfi

+ +

Libavfilter input virtual device. +

+

This input device reads data from the open output pads of a libavfilter +filtergraph. +

+

For each filtergraph open output, the input device will create a +corresponding stream which is mapped to the generated output. +The filtergraph is specified through the option graph. +

+ +

3.11.1 Options

+ +
+
graph
+

Specify the filtergraph to use as input. Each video open output must be +labelled by a unique string of the form "outN", where N is a +number starting from 0 corresponding to the mapped input stream +generated by the device. +The first unlabelled output is automatically assigned to the "out0" +label, but all the others need to be specified explicitly. +

+

The suffix "+subcc" can be appended to the output label to create an extra +stream with the closed captions packets attached to that output +(experimental; only for EIA-608 / CEA-708 for now). +The subcc streams are created after all the normal streams, in the order of +the corresponding stream. +For example, if there is "out19+subcc", "out7+subcc" and up to "out42", the +stream #43 is subcc for stream #7 and stream #44 is subcc for stream #19. +

+

If not specified defaults to the filename specified for the input +device. +

+
+
graph_file
+

Set the filename of the filtergraph to be read and sent to the other +filters. Syntax of the filtergraph is the same as the one specified by +the option graph. +

+
+
dumpgraph
+

Dump graph to stderr. +

+
+
+ + +

3.11.2 Examples

+ +
    +
  • Create a color video stream and play it back with ffplay: +
    +
    ffplay -f lavfi -graph "color=c=pink [out0]" dummy
    +
    + +
  • As the previous example, but use filename for specifying the graph +description, and omit the "out0" label: +
    +
    ffplay -f lavfi color=c=pink
    +
    + +
  • Create three different video test filtered sources and play them: +
    +
    ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3
    +
    + +
  • Read an audio stream from a file using the amovie source and play it +back with ffplay: +
    +
    ffplay -f lavfi "amovie=test.wav"
    +
    + +
  • Read an audio stream and a video stream and play it back with +ffplay: +
    +
    ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"
    +
    + +
  • Dump decoded frames to images and Closed Captions to an RCWT backup: +
    +
    ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rcwt subcc.bin
    +
    + +
+ + +

3.12 libcdio

+ +

Audio-CD input device based on libcdio. +

+

To enable this input device during configuration you need libcdio +installed on your system. It requires the configure option +--enable-libcdio. +

+

This device allows playing and grabbing from an Audio-CD. +

+

For example to copy with ffmpeg the entire Audio-CD in /dev/sr0, +you may run the command: +

+
ffmpeg -f libcdio -i /dev/sr0 cd.wav
+
+ + +

3.12.1 Options

+
+
speed
+

Set drive reading speed. Default value is 0. +

+

The speed is specified CD-ROM speed units. The speed is set through +the libcdio cdio_cddap_speed_set function. On many CD-ROM +drives, specifying a value too large will result in using the fastest +speed. +

+
+
paranoia_mode
+

Set paranoia recovery mode flags. It accepts one of the following values: +

+
+
‘disable’
+
‘verify’
+
‘overlap’
+
‘neverskip’
+
‘full’
+
+ +

Default value is ‘disable’. +

+

For more information about the available recovery modes, consult the +paranoia project documentation. +

+
+ + +

3.13 libdc1394

+ +

IIDC1394 input device, based on libdc1394 and libraw1394. +

+

Requires the configure option --enable-libdc1394. +

+ +

3.13.1 Options

+
+
framerate
+

Set the frame rate. Default is ntsc, corresponding to a frame +rate of 30000/1001. +

+
+
pixel_format
+

Select the pixel format. Default is uyvy422. +

+
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Default is qvga. +

+
+ + +

3.14 openal

+ +

The OpenAL input device provides audio capture on all systems with a +working OpenAL 1.1 implementation. +

+

To enable this input device during configuration, you need OpenAL +headers and libraries installed on your system, and need to configure +FFmpeg with --enable-openal. +

+

OpenAL headers and libraries should be provided as part of your OpenAL +implementation, or as an additional download (an SDK). Depending on your +installation you may need to specify additional flags via the +--extra-cflags and --extra-ldflags for allowing the build +system to locate the OpenAL headers and libraries. +

+

An incomplete list of OpenAL implementations follows: +

+
+
Creative
+

The official Windows implementation, providing hardware acceleration +with supported devices and software fallback. +See http://openal.org/. +

+
OpenAL Soft
+

Portable, open source (LGPL) software implementation. Includes +backends for the most common sound APIs on the Windows, Linux, +Solaris, and BSD operating systems. +See http://kcat.strangesoft.net/openal.html. +

+
Apple
+

OpenAL is part of Core Audio, the official Mac OS X Audio interface. +See http://developer.apple.com/technologies/mac/audio-and-video.html +

+
+ +

This device allows one to capture from an audio input device handled +through OpenAL. +

+

You need to specify the name of the device to capture in the provided +filename. If the empty string is provided, the device will +automatically select the default device. You can get the list of the +supported devices by using the option list_devices. +

+ +

3.14.1 Options

+ +
+
channels
+

Set the number of channels in the captured audio. Only the values +1 (monaural) and 2 (stereo) are currently supported. +Defaults to 2. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. Only the values +8 and 16 are currently supported. Defaults to +16. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +Defaults to 44.1k. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. +

+
+
+ + +

3.14.2 Examples

+ +

Print the list of OpenAL supported devices and exit: +

+
$ ffmpeg -list_devices true -f openal -i dummy out.ogg
+
+ +

Capture from the OpenAL device DR-BT101 via PulseAudio: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg
+
+ +

Capture from the default device (note the empty string ” as filename): +

+
$ ffmpeg -f openal -i '' out.ogg
+
+ +

Capture from two devices simultaneously, writing to two different files, +within the same ffmpeg command: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg
+
+

Note: not all OpenAL implementations support multiple simultaneous capture - +try the latest OpenAL Soft if the above does not work. +

+ +

3.15 oss

+ +

Open Sound System input device. +

+

The filename to provide to the input device is the device node +representing the OSS input device, and is usually set to +/dev/dsp. +

+

For example to grab from /dev/dsp using ffmpeg use the +command: +

+
ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
+
+ +

For more information about OSS see: +http://manuals.opensound.com/usersguide/dsp.html +

+ +

3.15.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

3.16 pulse

+ +

PulseAudio input device. +

+

To enable this output device you need to configure FFmpeg with --enable-libpulse. +

+

The filename to provide to the input device is a source device or the +string "default" +

+

To list the PulseAudio source devices and their properties you can invoke +the command pactl list sources. +

+

More information about PulseAudio can be found on http://www.pulseaudio.org. +

+ +

3.16.1 Options

+
+
server
+

Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. +

+
+
name
+

Specify the application name PulseAudio will use when showing active clients, +by default it is the LIBAVFORMAT_IDENT string. +

+
+
stream_name
+

Specify the stream name PulseAudio will use when showing active streams, +by default it is "record". +

+
+
sample_rate
+

Specify the samplerate in Hz, by default 48kHz is used. +

+
+
channels
+

Specify the channels in use, by default 2 (stereo) is set. +

+
+
frame_size
+

This option does nothing and is deprecated. +

+
+
fragment_size
+

Specify the size in bytes of the minimal buffering fragment in PulseAudio, it +will affect the audio latency. By default it is set to 50 ms amount of data. +

+
+
wallclock
+

Set the initial PTS using the current time. Default is 1. +

+
+
+ + +

3.16.2 Examples

+

Record a stream from default device: +

+
ffmpeg -f pulse -i default /tmp/pulse.wav
+
+ + +

3.17 sndio

+ +

sndio input device. +

+

To enable this input device during configuration you need libsndio +installed on your system. +

+

The filename to provide to the input device is the device node +representing the sndio input device, and is usually set to +/dev/audio0. +

+

For example to grab from /dev/audio0 using ffmpeg use the +command: +

+
ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
+
+ + +

3.17.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

3.18 video4linux2, v4l2

+ +

Video4Linux2 input video device. +

+

"v4l2" can be used as alias for "video4linux2". +

+

If FFmpeg is built with v4l-utils support (by using the +--enable-libv4l2 configure option), it is possible to use it with the +-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 +(e.g. an USB webcam) is plugged into the system, and has a name of the +kind /dev/videoN, where N is a number associated to +the device. +

+

Video4Linux2 devices usually support a limited set of +widthxheight sizes and frame rates. You can check which are +supported using -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 -list_standards all. +

+

The time base for the timestamps is 1 microsecond. Depending on the kernel +version and configuration, the timestamps may be derived from the real time +clock (origin at the Unix Epoch) or the monotonic clock (origin usually at +boot time, unaffected by NTP or manual changes to the clock). The +-timestamps abs or -ts abs option can be used to force +conversion into the real time clock. +

+

Some usage examples of the video4linux2 device with ffmpeg +and ffplay: +

    +
  • List supported formats for a video4linux2 device: +
    +
    ffplay -f video4linux2 -list_formats all /dev/video0
    +
    + +
  • Grab and show the input of a video4linux2 device: +
    +
    ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
    +
    + +
  • Grab and record the input of a video4linux2 device, leave the +frame rate and size as previously set: +
    +
    ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
    +
    +
+ +

For more information about Video4Linux, check http://linuxtv.org/. +

+ +

3.18.1 Options

+ +
+
standard
+

Set the standard. Must be the name of a supported standard. To get a +list of the supported standards, use the list_standards +option. +

+
+
channel
+

Set the input channel number. Default to -1, which means using the +previously selected channel. +

+
+
video_size
+

Set the video frame size. The argument must be a string in the form +WIDTHxHEIGHT or a valid size abbreviation. +

+
+
pixel_format
+

Select the pixel format (only valid for raw video input). +

+
+
input_format
+

Set the preferred pixel format (for raw video) or a codec name. +This option allows one to select the input format, when several are +available. +

+
+
framerate
+

Set the preferred video frame rate. +

+
+
list_formats
+

List available formats (supported pixel formats, codecs, and frame +sizes) and exit. +

+

Available values are: +

+
‘all’
+

Show all available (compressed and non-compressed) formats. +

+
+
‘raw’
+

Show only raw video (non-compressed) formats. +

+
+
‘compressed’
+

Show only compressed formats. +

+
+ +
+
list_standards
+

List supported standards and exit. +

+

Available values are: +

+
‘all’
+

Show all supported standards. +

+
+ +
+
timestamps, ts
+

Set type of timestamps for grabbed frames. +

+

Available values are: +

+
‘default’
+

Use timestamps from the kernel. +

+
+
‘abs’
+

Use absolute timestamps (wall clock). +

+
+
‘mono2abs’
+

Force conversion from monotonic to absolute timestamps. +

+
+ +

Default value is default. +

+
+
use_libv4l2
+

Use libv4l2 (v4l-utils) conversion functions. Default is 0. +

+
+
+ + +

3.19 vfwcap

+ +

VfW (Video for Windows) capture input device. +

+

The filename passed as input is the capture driver number, ranging from +0 to 9. You may use "list" as filename to print a list of drivers. Any +other filename will be interpreted as device number 0. +

+ +

3.19.1 Options

+ +
+
video_size
+

Set the video frame size. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
+ + +

3.20 x11grab

+ +

X11 video input device. +

+

To enable this input device during configuration you need libxcb +installed on your system. It will be automatically detected during +configuration. +

+

This device allows one to capture a region of an X11 display. +

+

The filename passed as input has the syntax: +

+
[hostname]:display_number.screen_number[+x_offset,y_offset]
+
+ +

hostname:display_number.screen_number specifies the +X11 display name of the screen to grab from. hostname can be +omitted, and defaults to "localhost". The environment variable +DISPLAY contains the default display name. +

+

x_offset and y_offset specify the offsets of the grabbed +area with respect to the top-left border of the X11 screen. They +default to 0. +

+

Check the X11 documentation (e.g. man X) for more detailed +information. +

+

Use the xdpyinfo program for getting basic information about +the properties of your X11 display (e.g. grep for "name" or +"dimensions"). +

+

For example to grab from :0.0 using ffmpeg: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

Grab at position 10,20: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ + +

3.20.1 Options

+ +
+
select_region
+

Specify whether to select the grabbing area graphically using the pointer. +A value of 1 prompts the user to select the grabbing area graphically +by clicking and dragging. A single click with no dragging will select the +whole screen. A region with zero width or height will also select the whole +screen. This option overwrites the video_size, grab_x, and +grab_y options. Default value is 0. +

+
+
draw_mouse
+

Specify whether to draw the mouse pointer. A value of 0 specifies +not to draw the pointer. Default value is 1. +

+
+
follow_mouse
+

Make the grabbed area follow the mouse. The argument can be +centered or a number of pixels PIXELS. +

+

When it is specified with "centered", the grabbing region follows the mouse +pointer and keeps the pointer at the center of region; otherwise, the region +follows only when the mouse pointer reaches within PIXELS (greater than +zero) to the edge of region. +

+

For example: +

+
ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

To follow only when the mouse pointer reaches within 100 pixels to edge: +

+
ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+
+
region_border
+

Set the region border thickness if -show_region 1 is used. +Range is 1 to 128 and default is 3 (XCB-based x11grab only). +

+

For example: +

+
ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ +

With follow_mouse: +

+
ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
window_id
+

Grab this window, instead of the whole screen. Default value is 0, which maps to +the whole screen (root window). +

+

The id of a window can be found using the xwininfo program, possibly with options -tree and +-root. +

+

If the window is later enlarged, the new area is not recorded. Video ends when +the window is closed, unmapped (i.e., iconified) or shrunk beyond the video +size (which defaults to the initial window size). +

+

This option disables options follow_mouse and select_region. +

+
+
video_size
+

Set the video frame size. Default is the full desktop or window. +

+
+
grab_x
+
grab_y
+

Set the grabbing region coordinates. They are expressed as offset from +the top left corner of the X11 window and correspond to the +x_offset and y_offset parameters in the device name. The +default value for both options is 0. +

+
+ + +

4 Output Devices

+ +

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 +are enabled by default. You can list all available ones using the +configure option "–list-outdevs". +

+

You can disable all the output devices using the configure option +"–disable-outdevs", and selectively enable an output device using the +option "–enable-outdev=OUTDEV", or you can disable a particular +input device using the option "–disable-outdev=OUTDEV". +

+

The option "-devices" of the ff* tools will display the list of +enabled output devices. +

+

A description of the currently available output devices follows. +

+ +

4.1 alsa

+ +

ALSA (Advanced Linux Sound Architecture) output device. +

+ +

4.1.1 Examples

+ +
    +
  • Play a file on default ALSA device: +
    +
    ffmpeg -i INPUT -f alsa default
    +
    + +
  • Play a file on soundcard 1, audio device 7: +
    +
    ffmpeg -i INPUT -f alsa hw:1,7
    +
    +
+ + +

4.2 AudioToolbox

+ +

AudioToolbox output device. +

+

Allows native output to CoreAudio devices on OSX. +

+

The output filename can be empty (or -) to refer to the default system output device or a number that refers to the device index as shown using: -list_devices true. +

+

Alternatively, the audio input device can be chosen by index using the + + -audio_device_index <INDEX> + +, overriding any device name or index given in the input filename. +

+

All available devices can be enumerated by using -list_devices true, listing +all device names, UIDs and corresponding indices. +

+ +

4.2.1 Options

+ +

AudioToolbox supports the following options: +

+
+
-audio_device_index <INDEX>
+

Specify the audio device by its index. Overrides anything given in the output filename. +

+
+
+ + +

4.2.2 Examples

+ +
    +
  • Print the list of supported devices and output a sine wave to the default device: +
    +
    $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -list_devices true -
    +
    + +
  • Output a sine wave to the device with the index 2, overriding any output filename: +
    +
    $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -audio_device_index 2 -
    +
    + +
+ + +

4.3 caca

+ +

CACA output device. +

+

This output device allows one 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. +

+

To enable this output device you need to configure FFmpeg with +--enable-libcaca. +libcaca is a graphics library that outputs text instead of pixels. +

+

For more information about libcaca, check: +http://caca.zoy.org/wiki/libcaca +

+ +

4.3.1 Options

+ +
+
window_title
+

Set the CACA window title, if not specified default to the filename +specified for the output device. +

+
+
window_size
+

Set the CACA window size, can be a string of the form +widthxheight or a video size abbreviation. +If not specified it defaults to the size of the input video. +

+
+
driver
+

Set display driver. +

+
+
algorithm
+

Set dithering algorithm. Dithering is necessary +because the picture being rendered has usually far more colours than +the available palette. +The accepted values are listed with -list_dither algorithms. +

+
+
antialias
+

Set antialias method. Antialiasing smoothens the rendered +image and avoids the commonly seen staircase effect. +The accepted values are listed with -list_dither antialiases. +

+
+
charset
+

Set which characters are going to be used when rendering text. +The accepted values are listed with -list_dither charsets. +

+
+
color
+

Set color to be used when rendering text. +The accepted values are listed with -list_dither colors. +

+
+
list_drivers
+

If set to true, print a list of available drivers and exit. +

+
+
list_dither
+

List available dither options related to the argument. +The argument must be one of algorithms, antialiases, +charsets, colors. +

+
+ + +

4.3.2 Examples

+ +
    +
  • The following command shows the ffmpeg output is an +CACA window, forcing its size to 80x25: +
    +
    ffmpeg -i INPUT -c:v rawvideo -pix_fmt rgb24 -window_size 80x25 -f caca -
    +
    + +
  • Show the list of available drivers and exit: +
    +
    ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_drivers true -
    +
    + +
  • Show the list of available dither colors and exit: +
    +
    ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_dither colors -
    +
    +
+ + +

4.4 decklink

+ +

The decklink output device provides playback capabilities for Blackmagic +DeckLink devices. +

+

To enable this output device, you need the Blackmagic DeckLink SDK and you +need to configure with the appropriate --extra-cflags +and --extra-ldflags. +On Windows, you need to run the IDL files through widl. +

+

DeckLink is very picky about the formats it supports. Pixel format is always +uyvy422, framerate, field order and video size must be determined for your +device with -list_formats 1. Audio sample rate is always 48 kHz. +

+ +

4.4.1 Options

+ +
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. This option is deprecated, please use the +-sinks option of ffmpeg to list the available output devices. +

+
+
list_formats
+

If set to true, print a list of supported formats and exit. +Defaults to false. +

+
+
preroll
+

Amount of time to preroll video in seconds. +Defaults to 0.5. +

+
+
duplex_mode
+

Sets the decklink device duplex/profile mode. Must be ‘unset’, ‘half’, ‘full’, +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +Defaults to ‘unset’. +

+

Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property. +For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 +sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile +is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles. +

+

Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0): +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +

+

Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2: +‘half’, ‘full’ +

+
+
timing_offset
+

Sets the genlock timing pixel offset on the used output. +Defaults to ‘unset’. +

+
+
link
+

Sets the SDI video link configuration on the used output. Must be +‘unset’, ‘single’ link SDI, ‘dual’ link SDI or ‘quad’ link +SDI. +Defaults to ‘unset’. +

+
+
sqd
+

Enable Square Division Quad Split mode for Quad-link SDI output. +Must be ‘unset’, ‘true’ or ‘false’. +Defaults to unset. +

+
+
level_a
+

Enable SMPTE Level A mode on the used output. +Must be ‘unset’, ‘true’ or ‘false’. +Defaults to unset. +

+
+
vanc_queue_size
+

Sets maximum output buffer size in bytes for VANC data. If the buffering reaches this value, +outgoing VANC data will be dropped. +Defaults to ‘1048576’. +

+
+
+ + +

4.4.2 Examples

+ +
    +
  • List output devices: +
    +
    ffmpeg -sinks decklink
    +
    + +
  • List supported formats: +
    +
    ffmpeg -i test.avi -f decklink -list_formats 1 'DeckLink Mini Monitor'
    +
    + +
  • Play video clip: +
    +
    ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 'DeckLink Mini Monitor'
    +
    + +
  • Play video clip with non-standard framerate or video size: +
    +
    ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 -s 720x486 -r 24000/1001 'DeckLink Mini Monitor'
    +
    + +
+ + +

4.5 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 +/dev/fb0. +

+

For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. +

+ +

4.5.1 Options

+
+
xoffset
+
yoffset
+

Set x/y coordinate of top left corner. Default is 0. +

+
+ + +

4.5.2 Examples

+

Play a file on framebuffer device /dev/fb0. +Required pixel format depends on current framebuffer settings. +

+
ffmpeg -re -i INPUT -c:v rawvideo -pix_fmt bgra -f fbdev /dev/fb0
+
+ +

See also http://linux-fbdev.sourceforge.net/, and fbset(1). +

+ +

4.6 oss

+ +

OSS (Open Sound System) output device. +

+ +

4.7 pulse

+ +

PulseAudio output device. +

+

To enable this output device you need to configure FFmpeg with --enable-libpulse. +

+

More information about PulseAudio can be found on http://www.pulseaudio.org +

+ +

4.7.1 Options

+
+
server
+

Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. +

+
+
name
+

Specify the application name PulseAudio will use when showing active clients, +by default it is the LIBAVFORMAT_IDENT string. +

+
+
stream_name
+

Specify the stream name PulseAudio will use when showing active streams, +by default it is set to the specified output name. +

+
+
device
+

Specify the device to use. Default device is used when not provided. +List of output devices can be obtained with command pactl list sinks. +

+
+
buffer_size
+
buffer_duration
+

Control the size and duration of the PulseAudio buffer. A small buffer +gives more control, but requires more frequent updates. +

+

buffer_size specifies size in bytes while +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. +

+
+
prebuf
+

Specify pre-buffering size in bytes. The server does not start with +playback before at least prebuf bytes are available in the +buffer. By default this option is initialized to the same value as +buffer_size or buffer_duration (whichever is bigger). +

+
+
minreq
+

Specify minimum request size in bytes. The server does not request less +than minreq bytes from the client, instead waits until the buffer +is free enough to request more bytes at once. It is recommended to not set +this option, which will initialize this to a value that is deemed sensible +by the server. +

+
+
+ + +

4.7.2 Examples

+

Play a file on default device on default server: +

+
ffmpeg  -i INPUT -f pulse "stream name"
+
+ + +

4.8 sndio

+ +

sndio audio output device. +

+ +

4.9 v4l2

+ +

Video4Linux2 output device. +

+ +

4.10 xv

+ +

XV (XVideo) output device. +

+

This output device allows one to show a video stream in a X Window System +window. +

+ +

4.10.1 Options

+ +
+
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 hostname[:number[.screen_number]]. +

+

hostname specifies the name of the host machine on which the +display is physically attached. number specifies the number of +the display server on that host machine. 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, 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. +

+
+
window_id
+

When set to non-zero value then device doesn’t create new window, +but uses existing one with provided window_id. By default +this options is set to zero and device creates its own window. +

+
+
window_size
+

Set the created window size, can be a string of the form +widthxheight or a video size abbreviation. If not +specified it defaults to the size of the input video. +Ignored when window_id is set. +

+
+
window_x
+
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. +Ignored when window_id is set. +

+
+
window_title
+

Set the window title, if not specified default to the filename +specified for the output device. Ignored when window_id is set. +

+
+ +

For more information about XVideo see http://www.x.org/. +

+ +

4.10.2 Examples

+ +
    +
  • Decode, display and encode video input with ffmpeg at the +same time: +
    +
    ffmpeg -i INPUT OUTPUT -f xv display
    +
    + +
  • Decode and display the input video to multiple X11 windows: +
    +
    ffmpeg -i INPUT -f xv normal -vf negate -f xv negated
    +
    +
+ + + +

5 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavdevice +

+ + +

6 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-filters.html b/ffmpeg-n8.1/doc/ffmpeg-filters.html new file mode 100644 index 00000000..22c77870 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-filters.html @@ -0,0 +1,40775 @@ + + + + + + + FFmpeg Filters Documentation + + + + + + +
+

+ FFmpeg Filters Documentation +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 Description

+ +

This document describes filters, sources, and sinks provided by the +libavfilter library. +

+ + +

2 Filtering Introduction

+ +

Filtering in FFmpeg is enabled through the libavfilter library. +

+

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. +

+
                [main]
+input --> split ---------------------> overlay --> output
+            |                             ^
+            |[tmp]                  [flip]|
+            +-----> crop --> vflip -------+
+
+

This filtergraph splits the input stream in two streams, then 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: +

+
+
ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
+
+ +

The result will be that the top half of the video is mirrored +onto the bottom half of the output video. +

+

Filters in the same linear chain are separated by commas, and distinct +linear chains of filters are separated by semicolons. In our example, +crop,vflip are in one linear chain, split and +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 [main] and [tmp]. +

+

The stream sent to the second output of split, labelled as +[tmp], is processed through the crop filter, which crops +away the lower half part of the video, and then vertically flipped. The +overlay filter takes in input the first unchanged output of the +split filter (which was labelled as [main]), and overlay on its +lower half the output generated by the 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 +by a colon. +

+

There exist so-called source filters that do not have an +audio/video input, and sink filters that will not have audio/video +output. +

+ + +

3 graph2dot

+ +

The graph2dot program included in the FFmpeg tools +directory can be used to parse a filtergraph description and issue a +corresponding textual representation in the dot language. +

+

Invoke the command: +

+
graph2dot -h
+
+ +

to see how to use graph2dot. +

+

You can then pass the dot description to the dot program (from +the graphviz suite of programs) and obtain a graphical representation +of the filtergraph. +

+

For example the sequence of commands: +

+
echo GRAPH_DESCRIPTION | \
+tools/graph2dot -o graph.tmp && \
+dot -Tpng graph.tmp -o graph.png && \
+display graph.png
+
+ +

can be used to create and display an image representing the graph +described by the GRAPH_DESCRIPTION string. Note that this string must be +a complete self-contained graph, with its inputs and outputs explicitly defined. +For example if your command line is of the form: +

+
ffmpeg -i infile -vf scale=640:360 outfile
+
+

your GRAPH_DESCRIPTION string will need to be of the form: +

+
nullsrc,scale=640:360,nullsink
+
+

you may also need to set the nullsrc parameters and add a format +filter in order to simulate a specific input file. +

+ + +

4 Filtergraph description

+ +

A filtergraph is a directed graph of connected filters. It can contain +cycles, and there can be multiple links between a pair of +filters. Each link has one input pad on one side connecting it to one +filter from which it takes its input, and one output pad on the other +side connecting it to one filter accepting its output. +

+

Each filter in a filtergraph is an instance of a filter class +registered in the application, which defines the features and the +number of input and output pads of the filter. +

+

A filter with no input pads is called a "source", and a filter with no +output pads is called a "sink". +

+ +

4.1 Filtergraph syntax

+ +

A filtergraph has a textual representation, which is recognized by the +-filter/-vf/-af and +-filter_complex options in ffmpeg and +-vf/-af in ffplay, and by the +avfilter_graph_parse_ptr() function defined in +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 +represented by a list of ","-separated filter descriptions. +

+

A filtergraph consists of a sequence of filterchains. A sequence of +filterchains is represented by a list of ";"-separated filterchain +descriptions. +

+

A filter is represented by a string of the form: +[in_link_1]...[in_link_N]filter_name@id=arguments[out_link_1]...[out_link_M] +

+

filter_name is the name of the filter class of which the +described filter is an instance of, and has to be the name of one of +the filter classes registered in the program optionally followed by "@id". +The name of the filter class is optionally followed by a string +"=arguments". +

+

arguments is a string which contains the parameters used to +initialize the filter instance. It may have one of two forms: +

    +
  • A ’:’-separated list of key=value pairs. + +
  • A ’:’-separated list of value. In this case, the keys are assumed to be +the option names in the order they are declared. E.g. the fade filter +declares three options in this order – type, start_frame and +nb_frames. Then the parameter list in:0:30 means that the value +in is assigned to the option type, 0 to +start_frame and 30 to nb_frames. + +
  • A ’:’-separated list of mixed direct value and long key=value +pairs. The direct value must precede the key=value pairs, and +follow the same constraints order of the previous point. The following +key=value pairs can be set in any preferred order. + +
+ +

If the option value itself is a list of items (e.g. the 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 +within the quoted text; otherwise the argument string is considered +terminated when the next special character (belonging to the set +‘[]=;,’) is encountered. +

+

A special syntax implemented in the ffmpeg CLI tool allows loading +option values from files. This is done be prepending a slash ’/’ to the option +name, then the supplied value is interpreted as a path from which the actual +value is loaded. E.g. +

+
ffmpeg -i <INPUT> -vf drawtext=/text=/tmp/some_text <OUTPUT>
+
+

will load the text to be drawn from /tmp/some_text. API users wishing to +implement a similar feature should use the avfilter_graph_segment_*() +functions together with custom IO code. +

+

The name and arguments of the filter are optionally preceded and +followed by a list of link labels. +A link label allows one to name a link and associate it to a filter output +or input pad. The preceding labels in_link_1 +... in_link_N, are associated to the filter input pads, +the following labels out_link_1 ... out_link_M, are +associated to the output pads. +

+

When two link labels with the same name are found in the +filtergraph, a link between the corresponding input and output pad is +created. +

+

If an output pad is not labelled, it is linked by default to the first +unlabelled input pad of the next filter in the filterchain. +For example in the filterchain +

+
nullsrc, split[L1], [L2]overlay, nullsink
+
+

the split filter instance has two output pads, and the overlay filter +instance two input pads. The first output pad of split is labelled +"L1", the first input pad of overlay is labelled "L2", and the second +output pad of split is linked to the second input pad of overlay, +which are both unlabelled. +

+

In a filter description, if the input label of the first filter is not +specified, "in" is assumed; if the output label of the last filter is not +specified, "out" is assumed. +

+

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. +

+

Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens +in the filtergraph specification are ignored. This means that the filtergraph +can be expressed using empty lines and spaces to improve readability. +

+

For example, the filtergraph: +

+
testsrc,split[L1],hflip[L2];[L1][L2] hstack
+
+ +

can be represented as: +

+
testsrc,
+split [L1], hflip [L2];
+
+[L1][L2] hstack
+
+ +

Libavfilter will automatically insert scale filters where format +conversion is required. It is possible to specify swscale flags +for those automatically inserted scalers by prepending +sws_flags=flags; +to the filtergraph description. +

+

Here is a BNF description of the filtergraph syntax: +

+
NAME             ::= sequence of alphanumeric characters and '_'
+FILTER_NAME      ::= NAME["@"NAME]
+LINKLABEL        ::= "[" NAME "]"
+LINKLABELS       ::= LINKLABEL [LINKLABELS]
+FILTER_ARGUMENTS ::= sequence of chars (possibly quoted)
+FILTER           ::= [LINKLABELS] FILTER_NAME ["=" FILTER_ARGUMENTS] [LINKLABELS]
+FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
+FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]
+
+ + +

4.2 Notes on filtergraph escaping

+ +

Filtergraph description composition entails several levels of +escaping. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual for more +information about the employed escaping procedure. +

+

A first level escaping affects the content of each filter option +value, which may contain the special character : used to +separate values, or one of the escaping characters \'. +

+

A second level escaping affects the whole filter description, which +may contain the escaping characters \' or the special +characters [],; used by the filtergraph description. +

+

Finally, when you specify a filtergraph on a shell commandline, you +need to perform a third level escaping for the shell special +characters contained within it. +

+

For example, consider the following string to be embedded in +the drawtext filter description text value: +

+
this is a 'string': may contain one, or more, special characters
+
+ +

This string contains the ' special escaping character, and the +: special character, so it needs to be escaped in this way: +

+
text=this is a \'string\'\: may contain one, or more, special characters
+
+ +

A second level of escaping is required when embedding the filter +description in a filtergraph description, in order to escape all the +filtergraph special characters. Thus the example above becomes: +

+
drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
+
+

(note that in addition to the \' escaping special characters, +also , needs to be escaped). +

+

Finally an additional level of escaping is needed when writing the +filtergraph description in a shell command, which depends on the +escaping rules of the adopted shell. For example, assuming that +\ is special and needs to be escaped with another \, the +previous string will finally result in: +

+
-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
+
+ +

In order to avoid cumbersome escaping when using a commandline tool accepting a +filter specification as input, it is advisable to avoid direct inclusion of the +filter or options specification in the shell. +

+

For example, in case of the drawtext filter, you might prefer to +use the textfile option in place of text to specify the text +to render. +

+ +

5 Timeline editing

+ +

Some filters support a generic 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: +

+
‘t’
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
‘n’
+

sequential number of the input frame, starting from 0 +

+
+
‘pos’
+

the position in the file of the input frame, NAN if unknown; deprecated, do +not use +

+
+
‘w’
+
‘h’
+

width and height of the input frame if video +

+
+ +

Additionally, these filters support an enable command that can be used +to re-define the expression. +

+

Like any other filtering option, the enable option follows the same +rules. +

+

For example, to enable a blur filter (smartblur) from 10 seconds to 3 +minutes, and a curves filter starting at 3 seconds: +

+
smartblur = enable='between(t,10,3*60)',
+curves    = enable='gte(t,3)' : preset=cross_process
+
+ +

See ffmpeg -filters to view which filters have timeline support. +

+ + +

6 Changing options at runtime with a command

+ +

Some options can be changed during the operation of the filter using +a command. These options are marked ’T’ on the output of +ffmpeg -h filter=<name of filter>. +The name of the command is the name of the option and the argument is +the new value. +

+ +

7 Options for filters with several inputs (framesync)

+ +

Some filters with several inputs support a common set of options. +These options can only be set by name, not with the short notation. +

+
+
eof_action
+

The action to take when EOF is encountered on the secondary input; it accepts +one of the following values: +

+
+
repeat
+

Repeat the last frame (the default). +

+
endall
+

End both streams. +

+
pass
+

Pass the main input through. +

+
+ +
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
repeatlast
+

If set to 1, force the filter to extend the last frame of secondary streams +until the end of the primary stream. A value of 0 disables this behavior. +Default value is 1. +

+
+
ts_sync_mode
+

How strictly to sync streams based on secondary input timestamps; it accepts +one of the following values: +

+
+
default
+

Frame from secondary input with the nearest lower or equal timestamp to the +primary input frame. +

+
nearest
+

Frame from secondary input with the absolute nearest timestamp to the primary +input frame. +

+
+
+
+ + + +

8 Audio Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the audio filters included in your +build. +

+

Below is a description of the currently available audio filters. +

+ +

8.1 aap

+

Apply Affine Projection algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to estimate unknown audio based on multiple input audio samples. +Affine projection algorithm can make trade-offs between computation complexity with convergence speed. +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
projection
+

Set the projection order. +

+
+
mu
+

Set the filter mu. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

8.2 acompressor

+ +

A compressor is mainly used to reduce the dynamic range of a signal. +Especially modern music is mostly compressed at a high ratio to +improve the overall loudness. It’s done to get the highest attention +of a listener, "fatten" the sound and bring more "power" to the track. +If a signal is compressed too much it may sound dull or "dead" +afterwards or it may start to "pump" (which could be a powerful effect +but can also destroy a track completely). +The right compression is the key to reach a professional sound and is +the high art of mixing and mastering. Because of its complex settings +it may take a long time to get the right feeling for this kind of effect. +

+

Compression is done by detecting the volume above a chosen level +threshold and dividing it by the factor set with ratio. +So if you set the threshold to -12dB and your signal reaches -6dB a ratio +of 2:1 will result in a signal at -9dB. Because an exact manipulation of +the signal would cause distortion of the waveform the reduction can be +levelled over the time. This is done by setting "Attack" and "Release". +attack determines how long the signal has to rise above the threshold +before any reduction will occur and release sets the time the signal +has to fall below the threshold to reduce the reduction again. Shorter signals +than the chosen attack time will be left untouched. +The overall reduction of the signal can be made up afterwards with the +makeup setting. So compressing the peaks of a signal about 6dB and +raising the makeup to this level results in a signal twice as loud than the +source. To gain a softer entry in the compression the knee flattens the +hard edge at the threshold in the range of the chosen decibels. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of stream rises above this level it will affect the gain +reduction. +By default it is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. 1:2 means that if the level +rose 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of input stream +or the louder(maximum) channel of input stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mostly smoother. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

8.2.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.3 acontrast

+

Simple audio dynamic range compression/expansion filter. +

+

The filter accepts the following options: +

+
+
contrast
+

Set contrast. Default is 33. Allowed range is between 0 and 100. +

+
+ + +

8.4 acopy

+ +

Copy the input audio source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

8.5 acrossfade

+ +

Apply cross fade from one input audio stream to another input audio stream. +The cross fade is applied for specified duration near the end of first stream. +

+

The filter accepts the following options: +

+
+
inputs, n
+

Specify the number of inputs to crossfade. When crossfading multiple inputs, +each input will be concatenated and crossfaded in sequence, similar to the +concat filter. Default is 2. +

+
+
nb_samples, ns
+

Specify the number of samples for which the cross fade effect has to last. +At the end of the cross fade effect the first input audio will be completely +silent. Default is 44100. +

+
+
duration, d
+

Specify the duration of the cross fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
overlap, o
+

Should first stream end overlap with second stream start. Default is enabled. +

+
+
curve1
+

Set curve for cross fade transition for first stream. +

+
+
curve2
+

Set curve for cross fade transition for second stream. +

+

For description of available curve types see afade filter description. +

+
+ + +

8.5.1 Examples

+ +
    +
  • Cross fade from one input to another: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
    +
    + +
  • Cross fade from one input to another but without overlapping: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
    +
    + +

    Concatenate multiple inputs with cross fade between each: +

    +
    ffmpeg -i first.flac -i second.flac -i third.flac -filter_complex acrossfade=n=3 output.flac
    +
    +
+ + +

8.6 acrossover

+

Split audio stream into several bands. +

+

This filter splits audio stream into two or more frequency ranges. +Summing all streams back will give flat output. +

+

The filter accepts the following options: +

+
+
split
+

Set split frequencies. Those must be positive and increasing. +

+
+
order
+

Set filter order for each band split. This controls filter roll-off or steepness +of filter transfer function. +Available values are: +

+
+
‘2nd’
+

12 dB per octave. +

+
‘4th’
+

24 dB per octave. +

+
‘6th’
+

36 dB per octave. +

+
‘8th’
+

48 dB per octave. +

+
‘10th’
+

60 dB per octave. +

+
‘12th’
+

72 dB per octave. +

+
‘14th’
+

84 dB per octave. +

+
‘16th’
+

96 dB per octave. +

+
‘18th’
+

108 dB per octave. +

+
‘20th’
+

120 dB per octave. +

+
+ +

Default is 4th. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+
gains
+

Set output gain for each band. Default value is 1 for all bands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+ + +

8.6.1 Examples

+ +
    +
  • Split input audio stream into two bands (low and high) with split frequency of 1500 Hz, +each band will be in separate stream: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but with higher filter order: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but also with additional middle band (frequencies between 1500 and 8000): +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav
    +
    +
+ + +

8.7 acrusher

+ +

Reduce audio bit resolution. +

+

This filter is bit crusher with enhanced functionality. A bit crusher +is used to audibly reduce number of bits an audio signal is sampled +with. This doesn’t change the bit depth at all, it just produces the +effect. Material reduced in bit depth sounds more harsh and "digital". +This filter is able to even round to continuous values instead of discrete +bit depths. +Additionally it has a D/C offset which results in different crushing of +the lower and the upper half of the signal. +An Anti-Aliasing setting is able to produce "softer" crushing sounds. +

+

Another feature of this filter is the logarithmic mode. +This setting switches from linear distances between bits to logarithmic ones. +The result is a much more "natural" sounding crusher which doesn’t gate low +signals for example. The human ear has a logarithmic perception, +so this kind of crushing is much more pleasant. +Logarithmic crushing is also able to get anti-aliased. +

+

The filter accepts the following options: +

+
+
level_in
+

Set level in. +

+
+
level_out
+

Set level out. +

+
+
bits
+

Set bit reduction. +

+
+
mix
+

Set mixing amount. +

+
+
mode
+

Can be linear: lin or logarithmic: log. +

+
+
dc
+

Set DC. +

+
+
aa
+

Set anti-aliasing. +

+
+
samples
+

Set sample reduction. +

+
+
lfo
+

Enable LFO. By default disabled. +

+
+
lforange
+

Set LFO range. +

+
+
lforate
+

Set LFO rate. +

+
+ + +

8.7.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.8 acue

+ +

Delay audio filtering until a given wallclock timestamp. See the cue +filter. +

+ +

8.9 adeclick

+

Remove impulsive noise from input audio. +

+

Samples detected as impulsive noise are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to +100. Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from +50 to 95. Default value is 75 percent. +Setting this to a very high value increases impulsive noise removal but makes +whole process much slower. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 2 percent. This option also +controls quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 2. +This controls the strength of impulsive noise which is going to be removed. +The lower value, the more samples will be detected as impulsive noise. +

+
+
burst, b
+

Set burst fusion, in percentage of window size. Allowed range is 0 to +10. Default value is 2. +If any two samples detected as noise are spaced less than this value then any +sample between those two samples will be also detected as noise. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly +changed with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

8.10 adeclip

+

Remove clipped samples from input audio. +

+

Samples detected as clipped are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to 100. +Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from 50 +to 95. Default value is 75 percent. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 8 percent. This option also controls +quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 10. Higher values make clip detection less aggressive. +

+
+
hsize, n
+

Set size of histogram used to detect clips. Allowed range is from 100 to 9999. +Default value is 1000. Higher values make clip detection less aggressive. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly changed +with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

8.11 adecorrelate

+

Apply decorrelation to input audio stream. +

+

The filter accepts the following options: +

+
+
stages
+

Set decorrelation stages of filtering. Allowed +range is from 1 to 16. Default value is 6. +

+
+
seed
+

Set random seed used for setting delay in samples across channels. +

+
+ + +

8.12 adelay

+ +

Delay one or more audio channels. +

+

Samples in delayed channel are filled with silence. +

+

The filter accepts the following option: +

+
+
delays
+

Set list of delays in milliseconds for each channel separated by ’|’. +Unused delays will be silently ignored. If number of given delays is +smaller than number of channels all remaining channels will not be delayed. +If you want to delay exact number of samples, append ’S’ to number. +If you want instead to delay in seconds, append ’s’ to number. +

+
+
all
+

Use last set delay for all remaining channels. By default is disabled. +This option if enabled changes how option delays is interpreted. +

+
+ + +

8.12.1 Examples

+ +
    +
  • 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. +
    +
    adelay=1500|0|500
    +
    + +
  • Delay second channel by 500 samples, the third channel by 700 samples and leave +the first channel (and any other channels that may be present) unchanged. +
    +
    adelay=0|500S|700S
    +
    + +
  • Delay all channels by same number of samples: +
    +
    adelay=delays=64S:all=1
    +
    +
+ + +

8.13 adenorm

+

Remedy denormals in audio by adding extremely low-level noise. +

+

This filter shall be placed before any filter that can produce denormals. +

+

A description of the accepted parameters follows. +

+
+
level
+

Set level of added noise in dB. Default is -351. +Allowed range is from -451 to -90. +

+
+
type
+

Set type of added noise. +

+
+
dc
+

Add DC signal. +

+
ac
+

Add AC signal. +

+
square
+

Add square signal. +

+
pulse
+

Add pulse signal. +

+
+ +

Default is dc. +

+
+ + +

8.13.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.14 aderivative, aintegral

+ +

Compute derivative/integral of audio stream. +

+

Applying both filters one after another produces original audio. +

+ +

8.15 adrc

+ +

Apply spectral dynamic range controller filter to input audio stream. +

+

A description of the accepted options follows. +

+
+
transfer
+

Set the transfer expression. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frequency power value, in dB +

+
+
f
+

current frequency in Hz +

+
+ +

Default value is p. +

+
+
attack
+

Set the attack in milliseconds. Default is 50 milliseconds. +Allowed range is from 1 to 1000 milliseconds. +

+
release
+

Set the release in milliseconds. Default is 100 milliseconds. +Allowed range is from 5 to 2000 milliseconds. +

+
channels
+

Set which channels to filter, by default all channels in audio stream are filtered. +

+
+ + +

8.15.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.15.2 Examples

+ +
    +
  • Apply spectral compression to all frequencies with threshold of -50 dB and 1:6 ratio: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/6,p)':attack=50:release=100
    +
    + +
  • Similar to above but with 1:2 ratio and filtering only front center channel: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/2,p)':attack=50:release=100:channels=FC
    +
    + +
  • Apply spectral noise gate to all frequencies with threshold of -85 dB and with short attack time and short release time: +
    +
    adrc=transfer='if(lte(p,-85),p-800,p)':attack=1:release=5
    +
    + +
  • Apply spectral expansion to all frequencies with threshold of -10 dB and 1:2 ratio: +
    +
    adrc=transfer='if(lt(p,-10),-10+(p-(-10))*2,p)':attack=50:release=100
    +
    + +
  • Apply limiter to max -60 dB to all frequencies, with attack of 2 ms and release of 10 ms: +
    +
    adrc=transfer='min(p,-60)':attack=2:release=10
    +
    +
+ + +

8.16 adynamicequalizer

+ +

Apply dynamic equalization to input audio stream. +

+

A description of the accepted options follows. +

+
+
threshold
+

Set the detection threshold used to trigger equalization. +Threshold detection is using detection filter. +Default value is 0. Allowed range is from 0 to 100. +

+
+
dfrequency
+

Set the detection frequency in Hz used for detection filter used to trigger equalization. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
dqfactor
+

Set the detection resonance factor for detection filter used to trigger equalization. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
tfrequency
+

Set the target frequency of equalization filter. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
tqfactor
+

Set the target resonance factor for target equalization filter. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
attack
+

Set the amount of milliseconds the signal from detection has to rise above +the detection threshold before equalization starts. +Default is 20. Allowed range is between 1 and 2000. +

+
+
release
+

Set the amount of milliseconds the signal from detection has to fall below the +detection threshold before equalization ends. +Default is 200. Allowed range is between 1 and 2000. +

+
+
ratio
+

Set the ratio by which the equalization gain is raised. +Default is 1. Allowed range is between 0 and 30. +

+
+
makeup
+

Set the makeup offset by which the equalization gain is raised. +Default is 0. Allowed range is between 0 and 100. +

+
+
range
+

Set the max allowed cut/boost amount. Default is 50. +Allowed range is from 1 to 200. +

+
+
mode
+

Set the mode of filter operation, can be one of the following: +

+
+
‘listen’
+

Output only isolated detection signal. +

+
‘cutbelow’
+

Cut frequencies below detection threshold. +

+
‘cutabove’
+

Cut frequencies above detection threshold. +

+
‘boostbelow’
+

Boost frequencies below detection threshold. +

+
‘boostabove’
+

Boost frequencies above detection threshold. +

+
+

Default mode is ‘cutbelow’. +

+
+
dftype
+

Set the type of detection filter, can be one of the following: +

+
+
‘bandpass’
+
‘lowpass’
+
‘highpass’
+
‘peak’
+
+

Default type is ‘bandpass’. +

+
+
tftype
+

Set the type of target filter, can be one of the following: +

+
+
‘bell’
+
‘lowshelf’
+
‘highshelf’
+
+

Default type is ‘bell’. +

+
+
auto
+

Automatically gather threshold from detection filter. By default +is ‘disabled’. +This option is useful to detect threshold in certain time frame of +input audio stream, in such case option value is changed at runtime. +

+

Available values are: +

+
‘disabled’
+

Disable using automatically gathered threshold value. +

+
‘off’
+

Stop picking threshold value. +

+
‘on’
+

Start picking threshold value. +

+
‘adaptive’
+

Adaptively pick threshold value, by calculating sliding window entropy. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

8.16.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.17 adynamicsmooth

+ +

Apply dynamic smoothing to input audio stream. +

+

A description of the accepted options follows. +

+
+
sensitivity
+

Set an amount of sensitivity to frequency fluctations. Default is 2. +Allowed range is from 0 to 1e+06. +

+
+
basefreq
+

Set a base frequency for smoothing. Default value is 22050. +Allowed range is from 2 to 1e+06. +

+
+ + +

8.17.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.18 aecho

+ +

Apply echoing to the input audio. +

+

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 delay, and the +loudness of the reflected signal is the decay. +Multiple echoes can have different delays and decays. +

+

A description of the accepted parameters follows. +

+
+
in_gain
+

Set input gain of reflected signal. Default is 0.6. +

+
+
out_gain
+

Set output gain of reflected signal. Default is 0.3. +

+
+
delays
+

Set list of time intervals in milliseconds between original signal and reflections +separated by ’|’. Allowed range for each delay is (0 - 90000.0]. +Default is 1000. +

+
+
decays
+

Set list of loudness of reflected signals separated by ’|’. +Allowed range for each decay is (0 - 1.0]. +Default is 0.5. +

+
+ + +

8.18.1 Examples

+ +
    +
  • Make it sound as if there are twice as many instruments as are actually playing: +
    +
    aecho=0.8:0.88:60:0.4
    +
    + +
  • If delay is very short, then it sounds like a (metallic) robot playing music: +
    +
    aecho=0.8:0.88:6:0.4
    +
    + +
  • A longer delay will sound like an open air concert in the mountains: +
    +
    aecho=0.8:0.9:1000:0.3
    +
    + +
  • Same as above but with one more mountain: +
    +
    aecho=0.8:0.9:1000|1800:0.3|0.25
    +
    +
+ + +

8.19 aemphasis

+

Audio emphasis filter creates or restores material directly taken from LPs or +emphased CDs with different filter curves. E.g. to store music on vinyl the +signal has to be altered by a filter first to even out the disadvantages of +this recording medium. +Once the material is played back the inverse filter has to be applied to +restore the distortion of the frequency response. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. +

+
+
level_out
+

Set output gain. +

+
+
mode
+

Set filter mode. For restoring material use reproduction mode, otherwise +use production mode. Default is reproduction mode. +

+
+
type
+

Set filter type. Selects medium. Can be one of the following: +

+
+
col
+

select Columbia. +

+
emi
+

select EMI. +

+
bsi
+

select BSI (78RPM). +

+
riaa
+

select RIAA. +

+
cd
+

select Compact Disc (CD). +

+
50fm
+

select 50µs (FM). +

+
75fm
+

select 75µs (FM). +

+
50kf
+

select 50µs (FM-KF). +

+
75kf
+

select 75µs (FM-KF). +

+
+
+
+ + +

8.19.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.20 aeval

+ +

Modify an audio signal according to the specified expressions. +

+

This filter accepts one or more expressions (one for each channel), +which are evaluated and used to modify a corresponding audio signal. +

+

It accepts the following parameters: +

+
+
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. +

+
+
channel_layout, c
+

Set output channel layout. If not specified, the channel layout is +specified by the number of expressions. If set to ‘same’, it will +use by default the same input channel layout. +

+
+ +

Each expression in exprs can contain the following constants and functions: +

+
+
ch
+

channel number of the current expression +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
s
+

sample rate +

+
+
t
+

time of the evaluated sample expressed in seconds +

+
+
nb_in_channels
+
nb_out_channels
+

input and output number of channels +

+
+
val(CH)
+

the value of input channel with number CH +

+
+ +

Note: this filter is slow. For faster processing you should use a +dedicated filter. +

+ +

8.20.1 Examples

+ +
    +
  • Half volume: +
    +
    aeval=val(ch)/2:c=same
    +
    + +
  • Invert phase of the second channel: +
    +
    aeval=val(0)|-val(1)
    +
    +
+ + +

8.21 aexciter

+ +

An exciter is used to produce high sound that is not present in the +original signal. This is done by creating harmonic distortions of the +signal which are restricted in range and added to the original signal. +An Exciter raises the upper end of an audio signal without simply raising +the higher frequencies like an equalizer would do to create a more +"crisp" or "brilliant" sound. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level prior processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
level_out
+

Set output level after processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
amount
+

Set the amount of harmonics added to original signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
drive
+

Set the amount of newly created harmonics. +Allowed range is from 0.1 to 10. +Default value is 8.5. +

+
+
blend
+

Set the octave of newly created harmonics. +Allowed range is from -10 to 10. +Default value is 0. +

+
+
freq
+

Set the lower frequency limit of producing harmonics in Hz. +Allowed range is from 2000 to 12000 Hz. +Default is 7500 Hz. +

+
+
ceil
+

Set the upper frequency limit of producing harmonics. +Allowed range is from 9999 to 20000 Hz. +If value is lower than 10000 Hz no limit is applied. +

+
+
listen
+

Mute the original signal and output only added harmonics. +By default is disabled. +

+
+ + +

8.21.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.22 afade

+ +

Apply fade-in/out effect to input audio. +

+

A description of the accepted parameters follows. +

+
+
type, t
+

Specify the effect type, can be either in for fade-in, or +out for a fade-out effect. Default is in. +

+
+
start_sample, ss
+

Specify the number of the start sample for starting to apply the fade +effect. Default is 0. +

+
+
nb_samples, ns
+

Specify the number of samples for which the fade effect has to last. 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 44100. +

+
+
start_time, st
+

Specify the start time of the fade effect. Default is 0. +The value must be specified as a time duration; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +If set this option is used instead of start_sample. +

+
+
duration, d
+

Specify the duration of the fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
curve
+

Set curve for fade transition. +

+

It accepts the following values: +

+
tri
+

select triangular, linear slope (default) +

+
qsin
+

select quarter of sine wave +

+
hsin
+

select half of sine wave +

+
esin
+

select exponential sine wave +

+
log
+

select logarithmic +

+
ipar
+

select inverted parabola +

+
qua
+

select quadratic +

+
cub
+

select cubic +

+
squ
+

select square root +

+
cbr
+

select cubic root +

+
par
+

select parabola +

+
exp
+

select exponential +

+
iqsin
+

select inverted quarter of sine wave +

+
ihsin
+

select inverted half of sine wave +

+
dese
+

select double-exponential seat +

+
desi
+

select double-exponential sigmoid +

+
losi
+

select logistic sigmoid +

+
sinc
+

select sine cardinal function +

+
isinc
+

select inverted sine cardinal function +

+
quat
+

select quartic +

+
quatr
+

select quartic root +

+
qsin2
+

select squared quarter of sine wave +

+
hsin2
+

select squared half of sine wave +

+
nofade
+

no fade applied +

+
+ +
+
silence
+

Set the initial gain for fade-in or final gain for fade-out. +Default value is 0.0. +

+
+
unity
+

Set the initial gain for fade-out or final gain for fade-in. +Default value is 1.0. +

+
+ + +

8.22.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.22.2 Examples

+ +
    +
  • Fade in first 15 seconds of audio: +
    +
    afade=t=in:ss=0:d=15
    +
    + +
  • Fade out last 25 seconds of a 900 seconds audio: +
    +
    afade=t=out:st=875:d=25
    +
    +
+ + +

8.23 afftdn

+

Denoise audio samples with FFT. +

+

A description of the accepted parameters follows. +

+
+
noise_reduction, nr
+

Set the noise reduction in dB, allowed range is 0.01 to 97. +Default value is 12 dB. +

+
+
noise_floor, nf
+

Set the noise floor in dB, allowed range is -80 to -20. +Default value is -50 dB. +

+
+
noise_type, nt
+

Set the noise type. +

+

It accepts the following values: +

+
white, w
+

Select white noise. +

+
+
vinyl, v
+

Select vinyl noise. +

+
+
shellac, s
+

Select shellac noise. +

+
+
custom, c
+

Select custom noise, defined in bn option. +

+

Default value is white noise. +

+
+ +
+
band_noise, bn
+

Set custom band noise profile for every one of 15 bands. +Bands are separated by ’ ’ or ’|’. +

+
+
residual_floor, rf
+

Set the residual floor in dB, allowed range is -80 to -20. +Default value is -38 dB. +

+
+
track_noise, tn
+

Enable noise floor tracking. By default is disabled. +With this enabled, noise floor is automatically adjusted. +

+
+
track_residual, tr
+

Enable residual tracking. By default is disabled. +

+
+
output_mode, om
+

Set the output mode. +

+

It accepts the following values: +

+
input, i
+

Pass input unchanged. +

+
+
output, o
+

Pass noise filtered out. +

+
+
noise, n
+

Pass only noise. +

+

Default value is output. +

+
+ +
+
adaptivity, ad
+

Set the adaptivity factor, used how fast to adapt gains adjustments per +each frequency bin. Value 0 enables instant adaptation, while higher values +react much slower. +Allowed range is from 0 to 1. Default value is 0.5. +

+
+
floor_offset, fo
+

Set the noise floor offset factor. This option is used to adjust offset applied to measured +noise floor. It is only effective when noise floor tracking is enabled. +Allowed range is from -2.0 to 2.0. Default value is 1.0. +

+
+
noise_link, nl
+

Set the noise link used for multichannel audio. +

+

It accepts the following values: +

+
none
+

Use unchanged channel’s noise floor. +

+
+
min
+

Use measured min noise floor of all channels. +

+
+
max
+

Use measured max noise floor of all channels. +

+
+
average
+

Use measured average noise floor of all channels. +

+

Default value is min. +

+
+ +
+
band_multiplier, bm
+

Set the band multiplier factor, used how much to spread bands across frequency bins. +Allowed range is from 0.2 to 5. Default value is 1.25. +

+
+
sample_noise, sn
+

Toggle capturing and measurement of noise profile from input audio. +

+

It accepts the following values: +

+
start, begin
+

Start sample noise capture. +

+
+
stop, end
+

Stop sample noise capture and measure new noise band profile. +

+

Default value is none. +

+
+ +
+
gain_smooth, gs
+

Set gain smooth spatial radius, used to smooth gains applied to each frequency bin. +Useful to reduce random music noise artefacts. +Higher values increases smoothing of gains. +Allowed range is from 0 to 50. +Default value is 0. +

+
+ + +

8.23.1 Commands

+ +

This filter supports the some above mentioned options as commands. +

+ +

8.23.2 Examples

+ +
    +
  • Reduce white noise by 10dB, and use previously measured noise floor of -40dB: +
    +
    afftdn=nr=10:nf=-40
    +
    + +
  • Reduce white noise by 10dB, also set initial noise floor to -80dB and enable automatic +tracking of noise floor so noise floor will gradually change during processing: +
    +
    afftdn=nr=10:nf=-80:tn=1
    +
    + +
  • Reduce noise by 20dB, using noise floor of -40dB and using commands to take noise profile +of first 0.4 seconds of input audio: +
    +
    asendcmd=0.0 afftdn sn start,asendcmd=0.4 afftdn sn stop,afftdn=nr=20:nf=-40
    +
    +
+ + +

8.24 afftfilt

+

Apply arbitrary expressions to samples in frequency domain. +

+
+
real
+

Set frequency domain real expression for each separate channel separated +by ’|’. Default is "re". +If the number of input channels is greater than the number of +expressions, the last specified expression is used for the remaining +output channels. +

+
+
imag
+

Set frequency domain imaginary expression for each separate channel +separated by ’|’. Default is "im". +

+

Each expression in real and imag can contain the following +constants and functions: +

+
+
sr
+

sample rate +

+
+
b
+

current frequency bin number +

+
+
nb
+

number of available bins +

+
+
ch
+

channel number of the current expression +

+
+
chs
+

number of channels +

+
+
pts
+

current frame pts +

+
+
re
+

current real part of frequency bin of current channel +

+
+
im
+

current imaginary part of frequency bin of current channel +

+
+
real(b, ch)
+

Return the value of real part of frequency bin at location (bin,channel) +

+
+
imag(b, ch)
+

Return the value of imaginary part of frequency bin at location (bin,channel) +

+
+ +
+
win_size
+

Set window size. Allowed range is from 16 to 131072. +Default is 4096 +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.75. +

+
+ + +

8.24.1 Examples

+ +
    +
  • Leave almost only low frequencies in audio: +
    +
    afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
    +
    + +
  • Apply robotize effect: +
    +
    afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
    +
    + +
  • Apply whisper effect: +
    +
    afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8"
    +
    + +
  • Apply phase shift: +
    +
    afftfilt="real=re*cos(1)-im*sin(1):imag=re*sin(1)+im*cos(1)"
    +
    +
+ + +

8.25 afir

+ +

Apply an arbitrary Finite Impulse Response filter. +

+

This filter is designed for applying long FIR filters, +up to 60 seconds long. +

+

It can be used as component for digital crossover filters, +room equalization, cross talk cancellation, wavefield synthesis, +auralization, ambiophonics, ambisonics and spatialization. +

+

This filter uses the streams higher than first one as FIR coefficients. +If the non-first stream holds a single channel, it will be used +for all input channels in the first stream, otherwise +the number of channels in the non-first stream must be same as +the number of channels in the first stream. +

+

It accepts the following parameters: +

+
+
dry
+

Set dry gain. This sets input gain. +

+
+
wet
+

Set wet gain. This sets final output gain. +

+
+
length
+

Set Impulse Response filter length. Default is 1, which means whole IR is processed. +

+
+
gtype
+

This option is deprecated, and does nothing. +

+
+
irnorm
+

Set norm to be applied to IR coefficients before filtering. +Allowed range is from -1 to 2. +IR coefficients are normalized with calculated vector norm set by this option. +For negative values, no norm is calculated, and IR coefficients are not modified at all. +Default is 1. +

+
+
irlink
+

For multichannel IR if this option is set to true, all IR channels will be +normalized with maximal measured gain of all IR channels coefficients as set by irnorm option. +When disabled, all IR coefficients in each IR channel will be normalized independently. +Default is true. +

+
+
irgain
+

Set gain to be applied to IR coefficients before filtering. +Allowed range is 0 to 1. This gain is applied after any gain applied with irnorm option. +

+
+
irfmt
+

Set format of IR stream. Can be mono or input. +Default is input. +

+
+
maxir
+

Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. +Allowed range is 0.1 to 60 seconds. +

+
+
response
+

This option is deprecated, and does nothing. +

+
+
channel
+

This option is deprecated, and does nothing. +

+
+
size
+

This option is deprecated, and does nothing. +

+
+
rate
+

This option is deprecated, and does nothing. +

+
+
minp
+

Set minimal partition size used for convolution. Default is 8192. +Allowed range is from 1 to 65536. +Lower values decreases latency at cost of higher CPU usage. +

+
+
maxp
+

Set maximal partition size used for convolution. Default is 8192. +Allowed range is from 8 to 65536. +Lower values may increase CPU usage. +

+
+
nbirs
+

Set number of input impulse responses streams which will be switchable at runtime. +Allowed range is from 1 to 32. Default is 1. +

+
+
ir
+

Set IR stream which will be used for convolution, starting from 0, should always be +lower than supplied value by nbirs option. Default is 0. +This option can be changed at runtime via commands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+
irload
+

Set when to load IR stream. Can be init or access. +First one load and prepares all IRs on initialization, second one +once on first access of specific IR. +Default is init. +

+
+ + +

8.25.1 Examples

+ +
    +
  • Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: +
    +
    ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
    +
    + +
  • Apply true stereo processing given input stereo stream, and two stereo impulse responses for left and right channel, +the impulse response files are files with names l_ir.wav and r_ir.wav, and setting irnorm option value: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irnorm=1.2,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    + +
  • Similar to above example, but with irgain explicitly set to estimated value and with irnorm disabled: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irgain=-5dB:irnom=-1,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    +
+ + +

8.26 aformat

+ +

Set output format constraints for the input audio. The framework will +negotiate the most appropriate format to minimize conversions. +

+

It accepts the following parameters: +

+
sample_fmts, f
+

A ’|’-separated list of requested sample formats. +

+
+
sample_rates, r
+

A ’|’-separated list of requested sample rates. +

+
+
channel_layouts, cl
+

A ’|’-separated list of requested channel layouts. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+ +

If a parameter is omitted, all values are allowed. +

+

Force the output to either unsigned 8-bit or signed 16-bit stereo +

+
aformat=sample_fmts=u8|s16:channel_layouts=stereo
+
+ + +

8.27 afreqshift

+

Apply frequency shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify frequency shift. Allowed range is -INT_MAX to INT_MAX. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

8.27.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.28 afwtdn

+

Reduce broadband noise from input samples using Wavelets. +

+

A description of the accepted options follows. +

+
+
sigma
+

Set the noise sigma, allowed range is from 0 to 1. +Default value is 0. +This option controls strength of denoising applied to input samples. +Most useful way to set this option is via decibels, eg. -45dB. +

+
+
levels
+

Set the number of wavelet levels of decomposition. +Allowed range is from 1 to 12. +Default value is 10. +Setting this too low make denoising performance very poor. +

+
+
wavet
+

Set wavelet type for decomposition of input frame. +They are sorted by number of coefficients, from lowest to highest. +More coefficients means worse filtering speed, but overall better quality. +Available wavelets are: +

+
+
‘sym2’
+
‘sym4’
+
‘rbior68’
+
‘deb10’
+
‘sym10’
+
‘coif5’
+
‘bl3’
+
+ +
+
percent
+

Set percent of full denoising. Allowed range is from 0 to 100 percent. +Default value is 85 percent or partial denoising. +

+
+
profile
+

If enabled, first input frame will be used as noise profile. +If first frame samples contain non-noise performance will be very poor. +

+
+
adaptive
+

If enabled, input frames are analyzed for presence of noise. +If noise is detected with high possibility then input frame profile will be +used for processing following frames, until new noise frame is detected. +

+
+
samples
+

Set size of single frame in number of samples. Allowed range is from 512 to +65536. Default frame size is 8192 samples. +

+
+
softness
+

Set softness applied inside thresholding function. Allowed range is from 0 to +10. Default softness is 1. +

+
+ + +

8.28.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.29 agate

+ +

A gate is mainly used to reduce lower parts of a signal. This kind of signal +processing reduces disturbing noise between useful signals. +

+

Gating is done by detecting the volume below a chosen level threshold +and dividing it by the factor set with ratio. The bottom of the noise +floor is set via range. Because an exact manipulation of the signal +would cause distortion of the waveform the reduction can be levelled over +time. This is done by setting attack and release. +

+

attack determines how long the signal has to fall below the threshold +before any reduction will occur and release sets the time the signal +has to rise above the threshold to reduce the reduction again. +Shorter signals than the chosen attack time will be left untouched. +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+ + +

8.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.30 aiir

+ +

Apply an arbitrary Infinite Impulse Response filter. +

+

It accepts the following parameters: +

+
+
zeros, z
+

Set B/numerator/zeros/reflection coefficients. +

+
+
poles, p
+

Set A/denominator/poles/ladder coefficients. +

+
+
gains, k
+

Set channels gains. +

+
+
dry_gain
+

Set input gain. +

+
+
wet_gain
+

Set output gain. +

+
+
format, f
+

Set coefficients format. +

+
+
‘ll’
+

lattice-ladder function +

+
‘sf’
+

analog transfer function +

+
‘tf’
+

digital transfer function +

+
‘zp’
+

Z-plane zeros/poles, cartesian (default) +

+
‘pr’
+

Z-plane zeros/poles, polar radians +

+
‘pd’
+

Z-plane zeros/poles, polar degrees +

+
‘sp’
+

S-plane zeros/poles +

+
+ +
+
process, r
+

Set type of processing. +

+
+
‘d’
+

direct processing +

+
‘s’
+

serial processing +

+
‘p’
+

parallel processing +

+
+ +
+
precision, e
+

Set filtering precision. +

+
+
‘dbl’
+

double-precision floating-point (default) +

+
‘flt’
+

single-precision floating-point +

+
‘i32’
+

32-bit integers +

+
‘i16’
+

16-bit integers +

+
+ +
+
normalize, n
+

Normalize filter coefficients, by default is enabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
mix
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
response
+

Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. +By default it is disabled. +

+
+
channel
+

Set for which IR channel to display frequency response. By default is first channel +displayed. This option is used only when response is enabled. +

+
+
size
+

Set video stream size. This option is used only when response is enabled. +

+
+ +

Coefficients in tf and sf format are separated by spaces and are in ascending +order. +

+

Coefficients in zp format are separated by spaces and order of coefficients +doesn’t matter. Coefficients in zp format are complex numbers with i +imaginary unit. +

+

Different coefficients and gains can be provided for every channel, in such case +use ’|’ to separate coefficients or gains. Last provided coefficients will be +used for all remaining channels. +

+ +

8.30.1 Examples

+ +
    +
  • Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate: +
    +
    aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
    +
    + +
  • Same as above but in zp format: +
    +
    aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
    +
    + +
  • Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format: +
    +
    aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
    +
    +
+ + +

8.31 alimiter

+ +

The limiter prevents an input signal from rising over a desired threshold. +This limiter uses lookahead technology to prevent your signal from distorting. +It means that there is a small delay after the signal is processed. Keep in mind +that the delay it produces is the attack time you set. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
limit
+

Don’t let signals above this level pass the limiter. Default is 1. +

+
+
attack
+

The limiter will reach its attenuation level in this amount of time in +milliseconds. Default is 5 milliseconds. +

+
+
release
+

Come back from limiting to attenuation 1.0 in this amount of milliseconds. +Default is 50 milliseconds. +

+
+
asc
+

When gain reduction is always needed ASC takes care of releasing to an +average reduction level rather than reaching a reduction of 0 in the release +time. +

+
+
asc_level
+

Select how much the release time is affected by ASC, 0 means nearly no changes +in release time while 1 produces higher release times. +

+
+
level
+

Auto level output signal. Default is enabled. +This normalizes audio back to 0dB if enabled. +

+
+
latency
+

Compensate the delay introduced by using the lookahead buffer set with attack +parameter. Also flush the valid audio data in the lookahead buffer when the +stream hits EOF. +

+
+ +

Depending on picked setting it is recommended to upsample input 2x or 4x times +with aresample before applying this filter. +

+ +

8.32 allpass

+ +

Apply a two-pole all-pass filter with central frequency (in Hz) +frequency, and filter-width 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: +

+
+
frequency, f
+

Set frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
order, o
+

Set the filter order, can be 1 or 2. Default is 2. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+
+
+ + +

8.32.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change allpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change allpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change allpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change allpass mix. +Syntax for the command is : "mix" +

+
+ + +

8.33 aloop

+ +

Loop audio samples. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal number of samples. Default is 0. +

+
+
start
+

Set first sample of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

8.34 amerge

+ +

Merge two or more audio streams into a single multi-channel stream. +

+

All inputs must have the same sample rate, and format. +

+

If inputs do not have the same duration, the output will stop with the +shortest. +

+

The filter accepts the following options: +

+
+
inputs
+

Set the number of inputs. Default is 2. +

+
+
layout_mode
+
+

This option controls how the output channel layout is determined and if the +audio channels are reordered during merge. +

+
+
legacy
+
+

This is the mode how the filter behaved historically so it is the default. +

+

If the channel layouts of the inputs are known and disjoint, and therefore +compatible, the channel layout of the output will be set accordingly and the +channels will be reordered as necessary. If the channel layouts of the inputs +are not disjoint, some of them are unknown, or they are using special channel +layouts, such as ambisonics, the output will have all the channels of the first +input then all the channels of the second input, in that order, and the channel +layout of the output will be the default value corresponding to the total +number of channels. +

+

For example, if the first input is in 2.1 (FL+FR+LF) and the second input +is FC+BL+BR, then the output will be in 5.1, with the channels in the +following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the +first input, b1 is the first channel of the second input). +

+

On the other hand, if both input are in stereo, the output channels will be +in the default order: a1, a2, b1, b2, and the channel layout will be +arbitrarily set to 4.0, which may or may not be the expected value. +

+
+
reset
+

This mode ignores the input channel layouts and does no channel reordering. +The output will have all the channels of the first input, then all the channels +of the second input, in that order, and so on. +

+

The output channel layout will only specify the total channel count. +

+
+
normal
+

This mode keeps channel name and designation information from the input +channels and does no channel reordering. The output will have all the channels +of the first input, then all the channels of the second input, in that order, +and so on. +

+
+
+ +
+
+ + +

8.34.1 Examples

+ +
    +
  • Merge two mono files into a stereo stream: +
    +
    amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
    +
    + +
  • Multiple merges assuming 1 video stream and 6 audio streams in input.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
    +
    +
+ + +

8.35 amix

+ +

Mixes multiple audio inputs into a single output. +

+

Note that this filter only supports float samples (the amerge +and pan audio filters support many formats). If the amix +input has integer samples then aresample will be automatically +inserted to perform the conversion to float samples. +

+

It accepts the following parameters: +

+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
duration
+

How to determine the end-of-stream. +

+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+
+ +
+
dropout_transition
+

The transition time, in seconds, for volume renormalization when an input +stream ends. The default value is 2 seconds. +

+
+
weights
+

Specify weight of each input audio stream as a sequence of numbers separated +by a space. If fewer weights are specified compared to number of inputs, the +last weight is assigned to the remaining inputs. +Default weight for each input is 1. +

+
+
normalize
+

Always scale inputs instead of only doing summation of samples. +Beware of heavy clipping if inputs are not normalized prior or after filtering +by this filter if this option is disabled. By default is enabled. +

+
+ + +

8.35.1 Examples

+ +
    +
  • This will mix 3 input audio streams to a single output with the same duration as the +first input and a dropout transition time of 3 seconds: +
    +
    ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
    +
    + +
  • This will mix one vocal and one music input audio stream to a single output with the same duration as the +longest input. The music will have quarter the weight as the vocals, and the inputs are not normalized: +
    +
    ffmpeg -i VOCALS -i MUSIC -filter_complex amix=inputs=2:duration=longest:dropout_transition=0:weights="1 0.25":normalize=0 OUTPUT
    +
    + +
+ + +

8.35.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
normalize
+

Syntax is same as option with same name. +

+
+ + +

8.36 amultiply

+ +

Multiply first audio stream with second audio stream and store result +in output audio stream. Multiplication is done by multiplying each +sample from first stream with sample at same position from second stream. +

+

With this element-wise multiplication one can create amplitude fades and +amplitude modulations. +

+ +

8.37 anequalizer

+ +

High-order parametric multiband equalizer for each channel. +

+

It accepts the following parameters: +

+
params
+
+

This option string is in format: +"cchn f=cf w=w g=g t=f | ..." +Each equalizer band is separated by ’|’. +

+
+
chn
+

Set channel number to which equalization will be applied. +If input doesn’t have that channel the entry is ignored. +

+
+
f
+

Set central frequency for band. +If input doesn’t have that frequency the entry is ignored. +

+
+
w
+

Set band width in Hertz. +

+
+
g
+

Set band gain in dB. +

+
+
t
+

Set filter type for band, optional, can be: +

+
+
‘0’
+

Butterworth, this is default. +

+
+
‘1’
+

Chebyshev type 1. +

+
+
‘2’
+

Chebyshev type 2. +

+
+
+
+ +
+
curves
+

With this option activated frequency response of anequalizer is displayed +in video stream. +

+
+
size
+

Set video stream size. Only useful if curves option is activated. +

+
+
mgain
+

Set max gain that will be displayed. Only useful if curves option is activated. +Setting this to a reasonable value makes it possible to display gain which is derived from +neighbour bands which are too close to each other and thus produce higher gain +when both are activated. +

+
+
fscale
+

Set frequency scale used to draw frequency response in video output. +Can be linear or logarithmic. Default is logarithmic. +

+
+
colors
+

Set color for each channel curve which is going to be displayed in video stream. +This is list of color names separated by space or by ’|’. +Unrecognised or missing colors will be replaced by white color. +

+
+ + +

8.37.1 Examples

+ +
    +
  • Lower gain by 10 of central frequency 200Hz and width 100 Hz +for first 2 channels using Chebyshev type 1 filter: +
    +
    anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
    +
    +
+ + +

8.37.2 Commands

+ +

This filter supports the following commands: +

+
change
+

Alter existing filter parameters. +Syntax for the commands is : "fN|f=freq|w=width|g=gain" +

+

fN is existing filter number, starting from 0, if no such filter is available +error is returned. +freq set new frequency parameter. +width set new width parameter in Hertz. +gain set new gain parameter in dB. +

+

Full filter invocation with asendcmd may look like this: +asendcmd=c=’4.0 anequalizer change 0|f=200|w=50|g=1’,anequalizer=... +

+
+ + +

8.38 anlmdn

+ +

Reduce broadband noise in audio samples using Non-Local Means algorithm. +

+

Each sample is adjusted by looking for other samples with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +p. Patches are searched in an area of r around the sample. +

+

The filter accepts the following options: +

+
+
strength, s
+

Set denoising strength. Allowed range is from 0.00001 to 10000. Default value is 0.00001. +

+
+
patch, p
+

Set patch radius duration. Allowed range is from 1 to 100 milliseconds. +Default value is 2 milliseconds. +

+
+
research, r
+

Set research radius duration. Allowed range is from 2 to 300 milliseconds. +Default value is 6 milliseconds. +

+
+
output, o
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass noise filtered out. +

+
+
n
+

Pass only noise. +

+

Default value is o. +

+
+ +
+
smooth, m
+

Set smooth factor. Default value is 11. Allowed range is from 1 to 1000. +

+
+ + +

8.38.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.39 anlmf, anlms

+

Apply Normalized Least-Mean-(Squares|Fourth) algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by finding the filter coefficients that +relate to producing the least mean square of the error signal (difference between the desired, +2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set filter order. +

+
+
mu
+

Set filter mu. +

+
+
eps
+

Set the filter eps. +

+
+
leakage
+

Set the filter leakage. +

+
+
out_mode
+

It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

8.39.1 Examples

+ +
    +
  • One of many usages of this filter is noise reduction, input audio is filtered +with same samples that are delayed by fixed amount, one such example for stereo audio is: +
    +
    asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
    +
    +
+ + +

8.39.2 Commands

+ +

This filter supports the same commands as options, excluding option order. +

+ +

8.40 anull

+ +

Pass the audio source unchanged to the output. +

+ +

8.41 apad

+ +

Pad the end of an audio stream with silence. +

+

This can be used together with ffmpeg -shortest to +extend audio streams to the same length as the video stream. +

+

A description of the accepted options follows. +

+
+
packet_size
+

Set silence packet size. Default value is 4096. +

+
+
pad_len
+

Set the number of samples of silence to add to the end. After the +value is reached, the stream is terminated. This option is mutually +exclusive with whole_len. +

+
+
whole_len
+

Set the minimum total number of samples in the output audio stream. If +the value is longer than the input audio length, silence is added to +the end, until the value is reached. This option is mutually exclusive +with pad_len. +

+
+
pad_dur
+

Specify the duration of samples of silence to add. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. +

+
+
whole_dur
+

Specify the minimum total duration in the output audio stream. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. If the value is longer than +the input audio length, silence is added to the end, until the value is reached. +This option is mutually exclusive with pad_dur +

+
+ +

If neither the pad_len nor the whole_len nor pad_dur +nor whole_dur option is set, the filter will add silence to the end of +the input stream indefinitely. +

+

Note that for ffmpeg 4.4 and earlier a zero pad_dur or +whole_dur also caused the filter to add silence indefinitely. +

+ +

8.41.1 Examples

+ +
    +
  • Add 1024 samples of silence to the end of the input: +
    +
    apad=pad_len=1024
    +
    + +
  • Make sure the audio output will contain at least 10000 samples, pad +the input with silence if required: +
    +
    apad=whole_len=10000
    +
    + +
  • Use ffmpeg to pad the audio input with silence, so that the +video stream will always result the shortest and will be converted +until the end in the output file when using the shortest +option: +
    +
    ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
    +
    +
+ + +

8.42 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. +

+
+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.74 +

+
+
delay
+

Set delay in milliseconds. Default is 3.0. +

+
+
decay
+

Set decay. Default is 0.4. +

+
+
speed
+

Set modulation speed in Hz. Default is 0.5. +

+
+
type
+

Set modulation type. Default is triangular. +

+

It accepts the following values: +

+
‘triangular, t’
+
‘sinusoidal, s’
+
+
+
+ + +

8.43 aphaseshift

+

Apply phase shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify phase shift. Allowed range is from -1.0 to 1.0. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

8.43.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.44 apsnr

+

Measure Audio Peak Signal-to-Noise Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

8.45 apsyclip

+

Apply Psychoacoustic clipper to input audio stream. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
clip
+

Set the clipping start value. Default value is 0dBFS or 1. +

+
+
diff
+

Output only difference samples, useful to hear introduced distortions. +By default is disabled. +

+
+
adaptive
+

Set strength of adaptive distortion applied. Default value is 0.5. +Allowed range is from 0 to 1. +

+
+
iterations
+

Set number of iterations of psychoacoustic clipper. +Allowed range is from 1 to 20. Default value is 10. +

+
+
level
+

Auto level output signal. Default is disabled. +This normalizes audio back to 0dBFS if enabled. +

+
+ + +

8.45.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.46 apulsator

+ +

Audio pulsator is something between an autopanner and a tremolo. +But it can produce funny stereo effects as well. Pulsator changes the volume +of the left and right channel based on a LFO (low frequency oscillator) with +different waveforms and shifted phases. +This filter have the ability to define an offset between left and right +channel. An offset of 0 means that both LFO shapes match each other. +The left and right channel are altered equally - a conventional tremolo. +An offset of 50% means that the shape of the right channel is exactly shifted +in phase (or moved backwards about half of the frequency) - pulsator acts as +an autopanner. At 1 both curves match again. Every setting in between moves the +phase shift gapless between all stages and produces some "bypassing" sounds with +sine and triangle waveforms. The more you set the offset near 1 (starting from +the 0.5) the faster the signal passes from the left to the right speaker. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
mode
+

Set waveform shape the LFO will use. Can be one of: sine, triangle, square, +sawup or sawdown. Default is sine. +

+
+
amount
+

Set modulation. Define how much of original signal is affected by the LFO. +

+
+
offset_l
+

Set left channel offset. Default is 0. Allowed range is [0 - 1]. +

+
+
offset_r
+

Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. +

+
+
width
+

Set pulse width. Default is 1. Allowed range is [0 - 2]. +

+
+
timing
+

Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. +

+
+
bpm
+

Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing +is set to bpm. +

+
+
ms
+

Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing +is set to ms. +

+
+
hz
+

Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used +if timing is set to hz. +

+
+ + +

8.47 aresample

+ +

Resample the input audio to the specified parameters, using the +libswresample library. If none are specified then the filter will +automatically convert between its input and output. +

+

This filter is also able to stretch/squeeze the audio data to make it match +the timestamps or to inject silence / cut out audio to make it match the +timestamps, do a combination of both or do neither. +

+

The filter accepts the syntax +[sample_rate:]resampler_options, where sample_rate +expresses a sample rate and resampler_options is a list of +key=value pairs, separated by ":". See the +"Resampler Options" section in the +ffmpeg-resampler(1) manual +for the complete list of supported options. +

+ +

8.47.1 Examples

+ +
    +
  • Resample the input audio to 44100Hz: +
    +
    aresample=44100
    +
    + +
  • Stretch/squeeze samples to the given timestamps, with a maximum of 1000 +samples per second compensation: +
    +
    aresample=async=1000
    +
    +
+ + +

8.48 areverse

+ +

Reverse an audio clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

8.48.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    atrim=end=5,areverse
    +
    +
+ + +

8.49 arls

+

Apply Recursive Least Squares algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by recursively finding the filter coefficients that +relate to producing the minimal weighted linear least squares cost function of the error signal (difference +between the desired, 2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
lambda
+

Set the forgetting factor. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

8.50 arnndn

+ +

Reduce noise from speech using Recurrent Neural Networks. +

+

This filter accepts the following options: +

+
+
model, m
+

Set train model file to load. This option is always required. +

+
+
mix
+

Set how much to mix filtered samples into final output. +Allowed range is from -1 to 1. Default value is 1. +Negative values are special, they set how much to keep filtered noise +in the final filter output. Set this option to -1 to hear actual +noise removed from input signal. +

+
+ + +

8.50.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.51 asdr

+

Measure Audio Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

8.52 asetnsamples

+ +

Set the number of samples per each output audio frame. +

+

The last output packet may contain a different number of samples, as +the filter will flush all the remaining samples when the input audio +signals its end. +

+

The filter accepts the following options: +

+
+
nb_out_samples, n
+

Set the number of frames per each output audio frame. The number is +intended as the number of samples per each channel. +Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio frame with zeroes, so +that the last frame will contain the same number of samples as the +previous ones. Default value is 1. +

+
+ +

For example, to set the number of per-frame samples to 1234 and +disable padding for the last frame, use: +

+
asetnsamples=n=1234:p=0
+
+ + +

8.53 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: +

+
+
sample_rate, r
+

Set the output sample rate. Default is 44100 Hz. +

+
+ + +

8.54 ashowinfo

+ +

Show a line containing various information for each input audio frame. +The input audio is not modified. +

+

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The presentation timestamp of the input frame, in time base units; the time base +depends on the filter input pad, and is usually 1/sample_rate. +

+
+
pts_time
+

The presentation timestamp of the input frame in seconds. +

+
+
fmt
+

The sample format. +

+
+
chlayout
+

The channel layout. +

+
+
rate
+

The sample rate for the audio frame. +

+
+
nb_samples
+

The number of samples (per channel) in the frame. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar +audio, the data is treated as if all the planes were concatenated. +

+
+
plane_checksums
+

A list of Adler-32 checksums for each data plane. +

+
+ + +

8.55 asisdr

+

Measure Audio Scaled-Invariant Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

8.56 asoftclip

+

Apply audio soft clipping. +

+

Soft clipping is a type of distortion effect where the amplitude of a signal is saturated +along a smooth curve, rather than the abrupt shape of hard-clipping. +

+

This filter accepts the following options: +

+
+
type
+

Set type of soft-clipping. +

+

It accepts the following values: +

+
hard
+
tanh
+
atan
+
cubic
+
exp
+
alg
+
quintic
+
sin
+
erf
+
+ +
+
threshold
+

Set threshold from where to start clipping. Default value is 0dB or 1. +

+
+
output
+

Set gain applied to output. Default value is 0dB or 1. +

+
+
param
+

Set additional parameter which controls sigmoid function. +

+
+
oversample
+

Set oversampling factor. +

+
+ + +

8.56.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.57 aspectralstats

+ +

Display frequency domain statistical information about the audio channels. +Statistics are calculated and stored as metadata for each audio channel and for each audio frame. +

+

It accepts the following option: +

+
win_size
+

Set the window length in samples. Default value is 2048. +Allowed range is from 32 to 65536. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. Allowed range is from 0 +to 1. Default value is 0.5. +

+
+
measure
+

Select the parameters which are measured. The metadata keys can +be used as flags, default is all which measures everything. +none disables all measurement. +

+
+ +

A list of each metadata key follows: +

+
+
mean
+
variance
+
centroid
+
spread
+
skewness
+
kurtosis
+
entropy
+
flatness
+
crest
+
flux
+
slope
+
decrease
+
rolloff
+
+ + +

8.58 asr

+

Automatic Speech Recognition +

+

This filter uses PocketSphinx for speech recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-pocketsphinx. +

+

It accepts the following options: +

+
+
rate
+

Set sampling rate of input audio. Defaults is 16000. +This need to match speech models, otherwise one will get poor results. +

+
+
hmm
+

Set dictionary containing acoustic model files. +

+
+
dict
+

Set pronunciation dictionary. +

+
+
lm
+

Set language model file. +

+
+
lmctl
+

Set language model set. +

+
+
lmname
+

Set which language model to use. +

+
+
logfn
+

Set output for log messages. +

+
+ +

The filter exports recognized speech as the frame metadata lavfi.asr.text. +

+ +

8.59 astats

+ +

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. +

+

It accepts the following option: +

+
length
+

Short window length in seconds, used for peak and through RMS measurement. +Default is 0.05 (50 milliseconds). Allowed range is [0 - 10]. +

+
+
metadata
+
+

Set metadata injection. All the metadata keys are prefixed with lavfi.astats.X, +where X is channel number starting from 1 or string Overall. Default is +disabled. +

+

Available keys for each channel are: +Bit_depth +Crest_factor +DC_offset +Dynamic_range +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_peak +RMS_trough +Zero_crossings +Zero_crossings_rate +

+

and for Overall: +Bit_depth +DC_offset +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Number_of_samples +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_level +RMS_peak +RMS_trough +

+

For example, a full key looks like lavfi.astats.1.DC_offset or +lavfi.astats.Overall.Peak_count. +

+

Read below for the description of the keys. +

+
+
reset
+

Set the number of frames over which cumulative stats are calculated before +being reset. Default is disabled. +

+
+
measure_perchannel
+

Select the parameters which are measured per channel. The metadata keys can +be used as flags, default is all which measures everything. +none disables all per channel measurement. +

+
+
measure_overall
+

Select the parameters which are measured overall. The metadata keys can +be used as flags, default is all which measures everything. +none disables all overall measurement. +

+
+
+ +

A description of the measure keys follow: +

+
+
none
+

no measures +

+
+
all
+

all measures +

+
+
Bit_depth
+

overall bit depth of audio, i.e. number of bits used for each sample +

+
+
Crest_factor
+

standard ratio of peak to RMS level (note: not in dB) +

+
+
DC_offset
+

mean amplitude displacement from zero +

+
+
Dynamic_range
+

measured dynamic range of audio in dB +

+
+
Entropy
+

entropy measured across whole audio, entropy of value near 1.0 is typically measured for white noise +

+
+
Flat_factor
+

flatness (i.e. consecutive samples with the same value) of the signal at its peak levels +(i.e. either Min_level or Max_level) +

+
+
Max_difference
+

maximal difference between two consecutive samples +

+
+
Max_level
+

maximal sample level +

+
+
Mean_difference
+

mean difference between two consecutive samples, i.e. the average of each difference between two consecutive samples +

+
+
Min_difference
+

minimal difference between two consecutive samples +

+
+
Min_level
+

minimal sample level +

+
+
Noise_floor
+

minimum local peak measured in dBFS over a short window +

+
+
Noise_floor_count
+

number of occasions (not the number of samples) that the signal attained +Noise floor +

+
+
Number_of_Infs
+

number of samples with an infinite value +

+
+
Number_of_NaNs
+

number of samples with a NaN (not a number) value +

+
+
Number_of_denormals
+

number of samples with a subnormal value +

+
+
Number_of_samples
+

number of samples +

+
+
Peak_count
+

number of occasions (not the number of samples) that the signal attained either +Min_level or Max_level +

+
+
Abs_Peak_count
+

number of occasions that the absolute samples taken from the signal attained +max absolute value of Min_level and Max_level +

+
+
Peak_level
+

standard peak level measured in dBFS +

+
+
RMS_difference
+

Root Mean Square difference between two consecutive samples +

+
+
RMS_level
+

standard RMS level measured in dBFS +

+
+
RMS_peak
+
RMS_trough
+

peak and through values for RMS level measured over a short window, +measured in dBFS. +

+
+
Zero crossings
+

number of points where the waveform crosses the zero level axis +

+
+
Zero crossings rate
+

rate of Zero crossings and number of audio samples +

+
+ + +

8.60 asubboost

+

Boost subwoofer frequencies. +

+

The filter accepts the following options: +

+
+
dry
+

Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
wet
+

Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
boost
+

Set max boost factor. Allowed range is from 1 to 12. Default value is 2. +

+
+
decay
+

Set delay line decay gain value. Allowed range is from 0 to 1. +Default value is 0.0. +

+
+
feedback
+

Set delay line feedback gain value. Allowed range is from 0 to 1. +Default value is 0.9. +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 50 to 900. +Default value is 100. +

+
+
slope
+

Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1. +Default value is 0.5. +

+
+
delay
+

Set delay. Allowed range is from 1 to 100. +Default value is 20. +

+
+
channels
+

Set the channels to process. Default value is all available. +

+
+ + +

8.60.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.61 asubcut

+

Cut subwoofer frequencies. +

+

This filter allows to set custom, steeper +roll off than highpass filter, and thus is able to more attenuate +frequency content in stop-band. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 2 to 200. +Default value is 20. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

8.61.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.62 asupercut

+

Cut super frequencies. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 20000 to 192000. +Default value is 20000. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

8.62.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.63 asuperpass

+

Apply high order Butterworth band-pass filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

8.63.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.64 asuperstop

+

Apply high order Butterworth band-stop filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

8.64.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.65 atempo

+ +

Adjust audio tempo. +

+

The filter accepts exactly one parameter, the audio tempo. If not +specified then the filter will assume nominal 1.0 tempo. Tempo must +be in the [0.5, 100.0] range. +

+

Note that tempo greater than 2 will skip some samples rather than +blend them in. If for any reason this is a concern it is always +possible to daisy-chain several instances of atempo to achieve the +desired product tempo. +

+ +

8.65.1 Examples

+ +
    +
  • Slow down audio to 80% tempo: +
    +
    atempo=0.8
    +
    + +
  • To speed up audio to 300% tempo: +
    +
    atempo=3
    +
    + +
  • To speed up audio to 300% tempo by daisy-chaining two atempo instances: +
    +
    atempo=sqrt(3),atempo=sqrt(3)
    +
    +
+ + +

8.65.2 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+ + +

8.66 atilt

+

Apply spectral tilt filter to audio stream. +

+

This filter apply any spectral roll-off slope over any specified frequency band. +

+

The filter accepts the following options: +

+
+
freq
+

Set central frequency of tilt in Hz. Default is 10000 Hz. +

+
+
slope
+

Set slope direction of tilt. Default is 0. Allowed range is from -1 to 1. +

+
+
width
+

Set width of tilt. Default is 1000. Allowed range is from 100 to 10000. +

+
+
order
+

Set order of tilt filter. +

+
+
level
+

Set input volume level. Allowed range is from 0 to 4. +Default is 1. +

+
+ + +

8.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.67 atrim

+ +

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Timestamp (in seconds) of the start of the section to keep. I.e. the audio +sample with the timestamp start will be the first sample in the output. +

+
+
end
+

Specify time of the first audio sample that will be dropped, i.e. the +audio sample immediately preceding the one with the timestamp end will be +the last sample in the output. +

+
+
start_pts
+

Same as start, except this option sets the start timestamp in samples +instead of seconds. +

+
+
end_pts
+

Same as end, except this option sets the end timestamp in samples instead +of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_sample
+

The number of the first sample that should be output. +

+
+
end_sample
+

The number of the first sample that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual. +

+

Note that the first two sets of the start/end options and the 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 +to have 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -af atrim=60:120
    +
    + +
  • Keep only the first 1000 samples: +
    +
    ffmpeg -i INPUT -af atrim=end_sample=1000
    +
    + +
+ + +

8.68 axcorrelate

+

Calculate normalized windowed cross-correlation between two input audio streams. +

+

Resulted samples are always between -1 and 1 inclusive. +If result is 1 it means two input samples are highly correlated in that selected segment. +Result 0 means they are not correlated at all. +If result is -1 it means two input samples are out of phase, which means they cancel each +other. +

+

The filter accepts the following options: +

+
+
size
+

Set size of segment over which cross-correlation is calculated. +Default is 256. Allowed range is from 2 to 131072. +

+
+
algo
+

Set algorithm for cross-correlation. Can be slow or fast or best. +Default is best. Fast algorithm assumes mean values over any given segment +are always zero and thus need much less calculations to make. +This is generally not true, but is valid for typical audio streams. +

+
+ + +

8.68.1 Examples

+ +
    +
  • Calculate correlation between channels in stereo audio stream: +
    +
    ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
    +
    +
+ + +

8.69 bandpass

+ +

Apply a two-pole Butterworth band-pass filter with central +frequency frequency, and (3dB-point) band-width width. +The 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: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
csg
+

Constant skirt gain if set to 1. Defaults to 0. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.69.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandpass mix. +Syntax for the command is : "mix" +

+
+ + +

8.70 bandreject

+ +

Apply a two-pole Butterworth band-reject filter with central +frequency frequency, and (3dB-point) band-width width. +The filter roll off at 6dB per octave (20dB per decade). +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.70.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandreject frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandreject width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandreject width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandreject mix. +Syntax for the command is : "mix" +

+
+ + +

8.71 bass, lowshelf

+ +

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: +

+
+
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. +

+
+
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 100 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.71.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bass width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change bass gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change bass mix. +Syntax for the command is : "mix" +

+
+ + +

8.72 biquad

+ +

Apply a biquad IIR filter with the given coefficients. +Where b0, b1, b2 and a0, a1, a2 +are the numerator and denominator coefficients respectively. +and channels, c specify which channels to filter, by default all +available are filtered. +

+ +

8.72.1 Commands

+ +

This filter supports the following commands: +

+
a0
+
a1
+
a2
+
b0
+
b1
+
b2
+

Change biquad parameter. +Syntax for the command is : "value" +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.73 bs2b

+

Bauer stereo to binaural transformation, which improves headphone listening of +stereo audio records. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libbs2b. +

+

It accepts the following parameters: +

+
profile
+

Pre-defined crossfeed level. +

+
default
+

Default level (fcut=700, feed=50). +

+
+
cmoy
+

Chu Moy circuit (fcut=700, feed=60). +

+
+
jmeier
+

Jan Meier circuit (fcut=650, feed=95). +

+
+
+ +
+
fcut
+

Cut frequency (in Hz). +

+
+
feed
+

Feed level (in Hz). +

+
+
+ + +

8.74 channelmap

+ +

Remap input channels to new locations. +

+

It accepts the following parameters: +

+
map
+

Map channels from input to output. The argument is a ’|’-separated list of +mappings, each in the in_channel-out_channel or +in_channel form. 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. out_channel is the name of the output channel or its index in the +output channel layout. If out_channel is not given then it is implicitly +an index, starting with zero and increasing by one for each mapping. Mixing +different types of mappings is not allowed and will result in a parse error. +

+
+
channel_layout
+

The channel layout of the output stream. If not specified, then filter will +guess it based on the out_channel names or the number of mappings. +Guessed layouts will not necessarily contain channels in the order of the +mappings. +

+
+ +

If no mapping is present, the filter will implicitly map input channels to +output channels, preserving indices. +

+ +

8.74.1 Examples

+ +
    +
  • For example, assuming a 5.1+downmix input MOV file, +
    +
    ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
    +
    +

    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 +
    +
    ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
    +
    +
+ + +

8.75 channelsplit

+ +

Split each channel from an input audio stream into a separate output stream. +

+

It accepts the following parameters: +

+
channel_layout
+

The channel layout of the input stream. The default is "stereo". +

+
channels
+

A channel layout describing the channels to be extracted as separate output streams +or "all" to extract each input channel as a separate stream. The default is "all". +

+

Choosing channels not present in channel layout in the input will result in an error. +

+
+ + +

8.75.1 Examples

+ +
    +
  • For example, assuming a stereo input MP3 file, +
    +
    ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
    +
    +

    will create an output Matroska file with two audio streams, one containing only +the left channel and the other the right channel. +

    +
  • Split a 5.1 WAV file into per-channel files: +
    +
    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
    +
    + +
  • Extract only LFE from a 5.1 WAV file: +
    +
    ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
    +-map '[LFE]' lfe.wav
    +
    +
+ + +

8.76 chorus

+

Add a chorus effect to the audio. +

+

Can make a single vocal sound like a chorus, but can also be applied to instrumentation. +

+

Chorus resembles an echo effect with a short delay, but whereas with echo the delay is +constant, with chorus, it is varied using sinusoidal or triangular modulation. +The modulation depth defines the range the modulated delay is played before or after +the delay. Hence the delayed sound will sound slower or faster, that is the delayed +sound tuned around the original one, like in a chorus where some vocals are slightly +off key. +

+

It accepts the following parameters: +

+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.4. +

+
+
delays
+

Set delays. A typical delay is around 40ms to 60ms. +

+
+
decays
+

Set decays. +

+
+
speeds
+

Set speeds. +

+
+
depths
+

Set depths. +

+
+ + +

8.76.1 Examples

+ +
    +
  • A single delay: +
    +
    chorus=0.7:0.9:55:0.4:0.25:2
    +
    + +
  • Two delays: +
    +
    chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
    +
    + +
  • Fuller sounding chorus with three delays: +
    +
    chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3
    +
    +
+ + +

8.77 compand

+

Compress or expand the audio’s dynamic range. +

+

It accepts the following parameters: +

+
+
attacks
+
decays
+

A list of times in seconds for each channel over which the instantaneous level +of the input signal is averaged to determine its volume. attacks refers to +increase of volume and 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. A typical value for attack is 0.3 seconds and +a typical value for decay is 0.8 seconds. +If specified number of attacks & decays is lower than number of channels, the last +set attack/decay will be used for all remaining channels. +

+
+
points
+

A list of points for the transfer function, specified in dB relative to the +maximum possible signal amplitude. Each key points list must be defined using +the following syntax: x0/y0|x1/y1|x2/y2|.... or +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 0/0 is assumed but +may be overridden (by 0/out-dBn). Typical values for the transfer +function are -70/-70|-60/-20|1/0. +

+
+
soft-knee
+

Set the curve radius in dB for all joints. It defaults to 0.01. +

+
+
gain
+

Set the additional gain in dB to be applied at all points on the transfer +function. This allows for easy adjustment of the overall gain. +It defaults to 0. +

+
+
volume
+

Set an 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. It defaults to 0. +

+
+
delay
+

Set a delay, in seconds. The input audio is analyzed 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. It defaults to 0. +

+
+
+ + +

8.77.1 Examples

+ +
    +
  • Make music with both quiet and loud passages suitable for listening to in a +noisy environment: +
    +
    compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
    +
    + +

    Another example for audio with whisper and explosion parts: +

    +
    compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
    +
    + +
  • A noise gate for when the noise is at a lower level than the signal: +
    +
    compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
    +
    + +
  • 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): +
    +
    compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
    +
    + +
  • 2:1 compression starting at -6dB: +
    +
    compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
    +
    + +
  • 2:1 compression starting at -9dB: +
    +
    compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
    +
    + +
  • 2:1 compression starting at -12dB: +
    +
    compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
    +
    + +
  • 2:1 compression starting at -18dB: +
    +
    compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
    +
    + +
  • 3:1 compression starting at -15dB: +
    +
    compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
    +
    + +
  • Compressor/Gate: +
    +
    compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
    +
    + +
  • Expander: +
    +
    compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
    +
    + +
  • Hard limiter at -6dB: +
    +
    compand=attacks=0:points=-80/-80|-6/-6|20/-6
    +
    + +
  • Hard limiter at -12dB: +
    +
    compand=attacks=0:points=-80/-80|-12/-12|20/-12
    +
    + +
  • Hard noise gate at -35 dB: +
    +
    compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
    +
    + +
  • Soft limiter: +
    +
    compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
    +
    +
+ + +

8.78 compensationdelay

+ +

Compensation Delay Line is a metric based delay to compensate differing +positions of microphones or speakers. +

+

For example, you have recorded guitar with two microphones placed in +different locations. Because the front of sound wave has fixed speed in +normal conditions, the phasing of microphones can vary and depends on +their location and interposition. The best sound mix can be achieved when +these microphones are in phase (synchronized). Note that a distance of +~30 cm between microphones makes one microphone capture the signal in +antiphase to the other microphone. That makes the final mix sound moody. +This filter helps to solve phasing problems by adding different delays +to each microphone track and make them synchronized. +

+

The best result can be reached when you take one track as base and +synchronize other tracks one by one with it. +Remember that synchronization/delay tolerance depends on sample rate, too. +Higher sample rates will give more tolerance. +

+

The filter accepts the following parameters: +

+
+
mm
+

Set millimeters distance. This is compensation distance for fine tuning. +Default is 0. +

+
+
cm
+

Set cm distance. This is compensation distance for tightening distance setup. +Default is 0. +

+
+
m
+

Set meters distance. This is compensation distance for hard distance setup. +Default is 0. +

+
+
dry
+

Set dry amount. Amount of unprocessed (dry) signal. +Default is 0. +

+
+
wet
+

Set wet amount. Amount of processed (wet) signal. +Default is 1. +

+
+
temp
+

Set temperature in degrees Celsius. This is the temperature of the environment. +Default is 20. +

+
+ + +

8.78.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.79 crossfeed

+

Apply headphone crossfeed filter. +

+

Crossfeed is the process of blending the left and right channels of stereo +audio recording. +It is mainly used to reduce extreme stereo separation of low frequencies. +

+

The intent is to produce more speaker like sound to the listener. +

+

The filter accepts the following options: +

+
+
strength
+

Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. +This sets gain of low shelf filter for side part of stereo image. +Default is -6dB. Max allowed is -30db when strength is set to 1. +

+
+
range
+

Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. +This sets cut off frequency of low shelf filter. Default is cut off near +1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. +

+
+
slope
+

Set curve slope of low shelf filter. Default is 0.5. +Allowed range is from 0.01 to 1. +

+
+
level_in
+

Set input gain. Default is 0.9. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
block_size
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.79.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.80 crystalizer

+

Simple algorithm for audio noise sharpening. +

+

This filter linearly increases differences between each audio sample. +

+

The filter accepts the following options: +

+
+
i
+

Sets the intensity of effect (default: 2.0). Must be in range between -10.0 to 0 +(unchanged sound) to 10.0 (maximum effect). +To inverse filtering use negative value. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

8.80.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.81 dcshift

+

Apply a DC shift to the audio. +

+

This can be useful to remove a DC offset (caused perhaps by a hardware problem +in the recording chain) from the audio. The effect of a DC offset is reduced +headroom and hence volume. The astats filter can be used to determine if +a signal has a DC offset. +

+
+
shift
+

Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift +the audio. +

+
+
limitergain
+

Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is +used to prevent clipping. +

+
+ + +

8.82 deesser

+ +

Apply de-essing to the audio samples. +

+
+
i
+

Set intensity for triggering de-essing. Allowed range is from 0 to 1. +Default is 0. +

+
+
m
+

Set amount of ducking on treble part of sound. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
f
+

How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
s
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass ess filtered out. +

+
+
e
+

Pass only ess. +

+

Default value is o. +

+
+ +
+
+ + +

8.83 dialoguenhance

+

Enhance dialogue in stereo audio. +

+

This filter accepts stereo input and produce surround (3.0) channels output. +The newly produced front center channel have enhanced speech dialogue originally +available in both stereo channels. +This filter outputs front left and front right channels same as available in stereo input. +

+

The filter accepts the following options: +

+
+
original
+

Set the original center factor to keep in front center channel output. +Allowed range is from 0 to 1. Default value is 1. +

+
+
enhance
+

Set the dialogue enhance factor to put in front center channel output. +Allowed range is from 0 to 3. Default value is 1. +

+
+
voice
+

Set the voice detection factor. +Allowed range is from 2 to 32. Default value is 2. +

+
+ + +

8.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.84 drmeter

+

Measure audio dynamic range. +

+

DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 +is found in transition material. And anything less that 8 have very poor dynamics +and is very compressed. +

+

The filter accepts the following options: +

+
+
length
+

Set window length in seconds used to split audio into segments of equal length. +Default is 3 seconds. +

+
+ + +

8.85 dynaudnorm

+

Dynamic Audio Normalizer. +

+

This filter applies a certain amount of gain to the input audio in order +to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in +contrast to more "simple" normalization algorithms, the Dynamic Audio +Normalizer *dynamically* re-adjusts the gain factor to the input audio. +This allows for applying extra gain to the "quiet" sections of the audio +while avoiding distortions or clipping the "loud" sections. In other words: +The Dynamic Audio Normalizer will "even out" the volume of quiet and loud +sections, in the sense that the volume of each section is brought to the +same target level. Note, however, that the Dynamic Audio Normalizer achieves +this goal *without* applying "dynamic range compressing". It will retain 100% +of the dynamic range *within* each section of the audio file. +

+
+
framelen, f
+

Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. +Default is 500 milliseconds. +The Dynamic Audio Normalizer processes the input audio in small chunks, +referred to as frames. This is required, because a peak magnitude has no +meaning for just a single sample value. Instead, we need to determine the +peak magnitude for a contiguous sequence of sample values. While a "standard" +normalizer would simply use the peak magnitude of the complete file, the +Dynamic Audio Normalizer determines the peak magnitude individually for each +frame. The length of a frame is specified in milliseconds. By default, the +Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has +been found to give good results with most files. +Note that the exact frame length, in number of samples, will be determined +automatically, based on the sampling rate of the individual input audio file. +

+
+
gausssize, g
+

Set the Gaussian filter window size. In range from 3 to 301, must be odd +number. Default is 31. +Probably the most important parameter of the Dynamic Audio Normalizer is the +window size of the Gaussian smoothing filter. The filter’s window size +is specified in frames, centered around the current frame. For the sake of +simplicity, this must be an odd number. Consequently, the default value of 31 +takes into account the current frame, as well as the 15 preceding frames and +the 15 subsequent frames. Using a larger window results in a stronger +smoothing effect and thus in less gain variation, i.e. slower gain +adaptation. Conversely, using a smaller window results in a weaker smoothing +effect and thus in more gain variation, i.e. faster gain adaptation. +In other words, the more you increase this value, the more the Dynamic Audio +Normalizer will behave like a "traditional" normalization filter. On the +contrary, the more you decrease this value, the more the Dynamic Audio +Normalizer will behave like a dynamic range compressor. +

+
+
peak, p
+

Set the target peak value. This specifies the highest permissible magnitude +level for the normalized audio input. This filter will try to approach the +target peak magnitude as closely as possible, but at the same time it also +makes sure that the normalized signal will never exceed the peak magnitude. +A frame’s maximum local gain factor is imposed directly by the target peak +magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. +It is not recommended to go above this value. +

+
+
maxgain, m
+

Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. +The Dynamic Audio Normalizer determines the maximum possible (local) gain +factor for each input frame, i.e. the maximum gain factor that does not +result in clipping or distortion. The maximum gain factor is determined by +the frame’s highest magnitude sample. However, the Dynamic Audio Normalizer +additionally bounds the frame’s maximum gain factor by a predetermined +(global) maximum gain factor. This is done in order to avoid excessive gain +factors in "silent" or almost silent frames. By default, the maximum gain +factor is 10.0, For most inputs the default value should be sufficient and +it usually is not recommended to increase this value. Though, for input +with an extremely low overall volume level, it may be necessary to allow even +higher gain factors. Note, however, that the Dynamic Audio Normalizer does +not simply apply a "hard" threshold (i.e. cut off values above the threshold). +Instead, a "sigmoid" threshold function will be applied. This way, the +gain factors will smoothly approach the threshold value, but never exceed that +value. +

+
+
targetrms, r
+

Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. +By default, the Dynamic Audio Normalizer performs "peak" normalization. +This means that the maximum local gain factor for each frame is defined +(only) by the frame’s highest magnitude sample. This way, the samples can +be amplified as much as possible without exceeding the maximum signal +level, i.e. without clipping. Optionally, however, the Dynamic Audio +Normalizer can also take into account the frame’s root mean square, +abbreviated RMS. In electrical engineering, the RMS is commonly used to +determine the power of a time-varying signal. It is therefore considered +that the RMS is a better approximation of the "perceived loudness" than +just looking at the signal’s peak magnitude. Consequently, by adjusting all +frames to a constant RMS value, a uniform "perceived loudness" can be +established. If a target RMS value has been specified, a frame’s local gain +factor is defined as the factor that would result in exactly that RMS value. +Note, however, that the maximum local gain factor is still restricted by the +frame’s highest magnitude sample, in order to prevent clipping. +

+
+
coupling, n
+

Enable channels coupling. By default is enabled. +By default, the Dynamic Audio Normalizer will amplify all channels by the same +amount. This means the same gain factor will be applied to all channels, i.e. +the maximum possible gain factor is determined by the "loudest" channel. +However, in some recordings, it may happen that the volume of the different +channels is uneven, e.g. one channel may be "quieter" than the other one(s). +In this case, this option can be used to disable the channel coupling. This way, +the gain factor will be determined independently for each channel, depending +only on the individual channel’s highest magnitude sample. This allows for +harmonizing the volume of the different channels. +

+
+
correctdc, c
+

Enable DC bias correction. By default is disabled. +An audio signal (in the time domain) is a sequence of sample values. +In the Dynamic Audio Normalizer these sample values are represented in the +-1.0 to 1.0 range, regardless of the original input format. Normally, the +audio signal, or "waveform", should be centered around the zero point. +That means if we calculate the mean value of all samples in a file, or in a +single frame, then the result should be 0.0 or at least very close to that +value. If, however, there is a significant deviation of the mean value from +0.0, in either positive or negative direction, this is referred to as a +DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic +Audio Normalizer provides optional DC bias correction. +With DC bias correction enabled, the Dynamic Audio Normalizer will determine +the mean value, or "DC correction" offset, of each input frame and subtract +that value from all of the frame’s sample values which ensures those samples +are centered around 0.0 again. Also, in order to avoid "gaps" at the frame +boundaries, the DC correction offset values will be interpolated smoothly +between neighbouring frames. +

+
+
altboundary, b
+

Enable alternative boundary mode. By default is disabled. +The Dynamic Audio Normalizer takes into account a certain neighbourhood +around each frame. This includes the preceding frames as well as the +subsequent frames. However, for the "boundary" frames, located at the very +beginning and at the very end of the audio file, not all neighbouring +frames are available. In particular, for the first few frames in the audio +file, the preceding frames are not known. And, similarly, for the last few +frames in the audio file, the subsequent frames are not known. Thus, the +question arises which gain factors should be assumed for the missing frames +in the "boundary" region. The Dynamic Audio Normalizer implements two modes +to deal with this situation. The default boundary mode assumes a gain factor +of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and +"fade out" at the beginning and at the end of the input, respectively. +

+
+
compress, s
+

Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. +By default, the Dynamic Audio Normalizer does not apply "traditional" +compression. This means that signal peaks will not be pruned and thus the +full dynamic range will be retained within each local neighbourhood. However, +in some cases it may be desirable to combine the Dynamic Audio Normalizer’s +normalization algorithm with a more "traditional" compression. +For this purpose, the Dynamic Audio Normalizer provides an optional compression +(thresholding) function. If (and only if) the compression feature is enabled, +all input frames will be processed by a soft knee thresholding function prior +to the actual normalization process. Put simply, the thresholding function is +going to prune all samples whose magnitude exceeds a certain threshold value. +However, the Dynamic Audio Normalizer does not simply apply a fixed threshold +value. Instead, the threshold value will be adjusted for each individual +frame. +In general, smaller parameters result in stronger compression, and vice versa. +Values below 3.0 are not recommended, because audible distortion may appear. +

+
+
threshold, t
+

Set the target threshold value. This specifies the lowest permissible +magnitude level for the audio input which will be normalized. +If input frame volume is above this value frame will be normalized. +Otherwise frame may not be normalized at all. The default value is set +to 0, which means all input frames will be normalized. +This option is mostly useful if digital noise is not wanted to be amplified. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
overlap, o
+

Specify overlap for frames. If set to 0 (default) no frame overlapping is done. +Using >0 and <1 values will make less conservative gain adjustments, like +when framelen option is set to smaller value, if framelen option value is +compensated for non-zero overlap then gain adjustments will be smoother across time +compared to zero overlap case. +

+
+
curve, v
+

Specify the peak mapping curve expression which is going to be used when calculating +gain applied to frames. The max output frame gain will still be limited by other +options mentioned previously for this filter. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frame peak value +

+
+
+
+ + +

8.85.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.86 earwax

+ +

Make audio easier to listen to on headphones. +

+

This filter adds ‘cues’ to 44.1kHz stereo (i.e. audio CD format) audio +so that when listened to on headphones the stereo image is moved from +inside your head (standard for headphones) to outside and in front of +the listener (standard for speakers). +

+

Ported from SoX. +

+ +

8.87 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: +

+
+
frequency, f
+

Set the filter’s central frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
gain, g
+

Set the required gain or attenuation in dB. +Beware of clipping when using a positive gain. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.87.1 Examples

+
    +
  • Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: +
    +
    equalizer=f=1000:t=h:width=200:g=-10
    +
    + +
  • Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: +
    +
    equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
    +
    +
+ + +

8.87.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change equalizer frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change equalizer width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change equalizer width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change equalizer gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change equalizer mix. +Syntax for the command is : "mix" +

+
+ + +

8.88 extrastereo

+ +

Linearly increases the difference between left and right channels which +adds some sort of "live" effect to playback. +

+

The filter accepts the following options: +

+
+
m
+

Sets the difference coefficient (default: 2.5). 0.0 means mono sound +(average of both channels), with 1.0 sound will be unchanged, with +-1.0 left and right channels will be swapped. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

8.88.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.89 firequalizer

+

Apply FIR Equalization using arbitrary frequency response. +

+

The filter accepts the following option: +

+
+
gain
+

Set gain curve equation (in dB). The expression can contain variables: +

+
f
+

the evaluated frequency +

+
sr
+

sample rate +

+
ch
+

channel number, set to 0 when multichannels evaluation is disabled +

+
chid
+

channel id, see libavutil/channel_layout.h, set to the first channel id when +multichannels evaluation is disabled +

+
chs
+

number of channels +

+
chlayout
+

channel_layout, see libavutil/channel_layout.h +

+
+
+

and functions: +

+
gain_interpolate(f)
+

interpolate gain on frequency f based on gain_entry +

+
cubic_interpolate(f)
+

same as gain_interpolate, but smoother +

+
+

This option is also available as command. Default is gain_interpolate(f). +

+
+
gain_entry
+

Set gain entry for gain_interpolate function. The expression can +contain functions: +

+
entry(f, g)
+

store gain entry at frequency f with value g +

+
+

This option is also available as command. +

+
+
delay
+

Set filter delay in seconds. Higher value means more accurate. +Default is 0.01. +

+
+
accuracy
+

Set filter accuracy in Hz. Lower value means more accurate. +Default is 5. +

+
+
wfunc
+

Set window function. Acceptable values are: +

+
rectangular
+

rectangular window, useful when gain curve is already smooth +

+
hann
+

hann window (default) +

+
hamming
+

hamming window +

+
blackman
+

blackman window +

+
nuttall3
+

3-terms continuous 1st derivative nuttall window +

+
mnuttall3
+

minimum 3-terms discontinuous nuttall window +

+
nuttall
+

4-terms continuous 1st derivative nuttall window +

+
bnuttall
+

minimum 4-terms discontinuous nuttall (blackman-nuttall) window +

+
bharris
+

blackman-harris window +

+
tukey
+

tukey window +

+
+ +
+
fixed
+

If enabled, use fixed number of audio samples. This improves speed when +filtering with large delay. Default is disabled. +

+
+
multi
+

Enable multichannels evaluation on gain. Default is disabled. +

+
+
zero_phase
+

Enable zero phase mode by subtracting timestamp to compensate delay. +Default is disabled. +

+
+
scale
+

Set scale used by gain. Acceptable values are: +

+
linlin
+

linear frequency, linear gain +

+
linlog
+

linear frequency, logarithmic (in dB) gain (default) +

+
loglin
+

logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain +

+
loglog
+

logarithmic frequency, logarithmic gain +

+
+ +
+
dumpfile
+

Set file for dumping, suitable for gnuplot. +

+
+
dumpscale
+

Set scale for dumpfile. Acceptable values are same with scale option. +Default is linlog. +

+
+
fft2
+

Enable 2-channel convolution using complex FFT. This improves speed significantly. +Default is disabled. +

+
+
min_phase
+

Enable minimum phase impulse response. Default is disabled. +

+
+ + +

8.89.1 Examples

+
    +
  • lowpass at 1000 Hz: +
    +
    firequalizer=gain='if(lt(f,1000), 0, -INF)'
    +
    +
  • lowpass at 1000 Hz with gain_entry: +
    +
    firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
    +
    +
  • custom equalization: +
    +
    firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
    +
    +
  • higher delay with zero phase to compensate delay: +
    +
    firequalizer=delay=0.1:fixed=on:zero_phase=on
    +
    +
  • lowpass on left channel, highpass on right channel: +
    +
    firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
    +:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
    +
    +
+ + +

8.90 flanger

+

Apply a flanging effect to the audio. +

+

The filter accepts the following options: +

+
+
delay
+

Set base delay in milliseconds. Range from 0 to 30. Default value is 0. +

+
+
depth
+

Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. +

+
+
regen
+

Set percentage regeneration (delayed signal feedback). Range from -95 to 95. +Default value is 0. +

+
+
width
+

Set percentage of delayed signal mixed with original. Range from 0 to 100. +Default value is 71. +

+
+
speed
+

Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. +

+
+
shape
+

Set swept wave shape, can be triangular or sinusoidal. +Default value is sinusoidal. +

+
+
phase
+

Set swept wave percentage-shift for multi channel. Range from 0 to 100. +Default value is 25. +

+
+
interp
+

Set delay-line interpolation, linear or quadratic. +Default is linear. +

+
+ + +

8.91 haas

+

Apply Haas effect to audio. +

+

Note that this makes most sense to apply on mono signals. +With this filter applied to mono signals it give some directionality and +stretches its stereo image. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level. By default is 1, or 0dB +

+
+
level_out
+

Set output level. By default is 1, or 0dB. +

+
+
side_gain
+

Set gain applied to side part of signal. By default is 1. +

+
+
middle_source
+

Set kind of middle source. Can be one of the following: +

+
+
‘left’
+

Pick left channel. +

+
+
‘right’
+

Pick right channel. +

+
+
‘mid’
+

Pick middle part signal of stereo image. +

+
+
‘side’
+

Pick side part signal of stereo image. +

+
+ +
+
middle_phase
+

Change middle phase. By default is disabled. +

+
+
left_delay
+

Set left channel delay. By default is 2.05 milliseconds. +

+
+
left_balance
+

Set left channel balance. By default is -1. +

+
+
left_gain
+

Set left channel gain. By default is 1. +

+
+
left_phase
+

Change left phase. By default is disabled. +

+
+
right_delay
+

Set right channel delay. By defaults is 2.12 milliseconds. +

+
+
right_balance
+

Set right channel balance. By default is 1. +

+
+
right_gain
+

Set right channel gain. By default is 1. +

+
+
right_phase
+

Change right phase. By default is enabled. +

+
+ + +

8.92 hdcd

+ +

Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with +embedded HDCD codes is expanded into a 20-bit PCM stream. +

+

The filter supports the Peak Extend and Low-level Gain Adjustment features +of HDCD, and detects the Transient Filter flag. +

+
+
ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
+
+ +

When using the filter with wav, note the default encoding for wav is 16-bit, +so the resulting 20-bit stream will be truncated back to 16-bit. Use something +like -acodec pcm_s24le after the filter to get 24-bit PCM output. +

+
ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
+ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
+
+ +

The filter accepts the following options: +

+
+
disable_autoconvert
+

Disable any automatic format conversion or resampling in the filter graph. +

+
+
process_stereo
+

Process the stereo channels together. If target_gain does not match between +channels, consider it invalid and use the last valid target_gain. +

+
+
cdt_ms
+

Set the code detect timer period in ms. +

+
+
force_pe
+

Always extend peaks above -3dBFS even if PE isn’t signaled. +

+
+
analyze_mode
+

Replace audio with a solid tone and adjust the amplitude to signal some +specific aspect of the decoding process. The output file can be loaded in +an audio editor alongside the original to aid analysis. +

+

analyze_mode=pe:force_pe=true can be used to see all samples above the PE level. +

+

Modes are: +

+
‘0, off’
+

Disabled +

+
‘1, lle’
+

Gain adjustment level at each sample +

+
‘2, pe’
+

Samples where peak extend occurs +

+
‘3, cdt’
+

Samples where the code detect timer is active +

+
‘4, tgm’
+

Samples where the target gain does not match between channels +

+
+
+
+ + +

8.93 headphone

+ +

Apply head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones. +The HRIRs are provided via additional streams, for each channel +one stereo input stream is needed. +

+

The filter accepts the following options: +

+
+
map
+

Set mapping of input streams for convolution. +The argument is a ’|’-separated list of channel names in order as they +are given as additional stream inputs for filter. +This also specify number of input streams. Number of input streams +must be not less than number of channels in first stream plus one. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
lfe
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
size
+

Set size of frame in number of samples which will be processed at once. +Default value is 1024. Allowed range is from 1024 to 96000. +

+
+
hrir
+

Set format of hrir stream. +Default value is stereo. Alternative value is multich. +If value is set to stereo, number of additional streams should +be greater or equal to number of input channels in first input stream. +Also each additional stream should have stereo number of channels. +If value is set to multich, number of additional streams should +be exactly one. Also number of input channels of additional stream +should be equal or greater than twice number of channels of first input +stream. +

+
+ + +

8.93.1 Examples

+ +
    +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +each amovie filter use stereo file with IR coefficients as input. +The files give coefficients for each position of virtual loudspeaker: +
    +
    ffmpeg -i input.wav
    +-filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
    +output.wav
    +
    + +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +but now in multich hrir format. +
    +
    ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
    +output.wav
    +
    +
+ + +

8.94 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 3000. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.94.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change highpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change highpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change highpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change highpass mix. +Syntax for the command is : "mix" +

+
+ + +

8.95 join

+ +

Join multiple input streams into one multi-channel stream. +

+

It accepts the following parameters: +

+
inputs
+

The number of input streams. It defaults to 2. +

+
+
channel_layout
+

The desired output channel layout. It defaults to stereo. +

+
+
map
+

Map channels from inputs to output. The argument is a ’|’-separated list of +mappings, each in the input_idx.in_channel-out_channel +form. input_idx is the 0-based index of the input stream. 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. out_channel is the name of the output +channel. +

+
+ +

The filter will attempt to guess the mappings when they 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. +

+

Join 3 inputs (with properly set channel layouts): +

+
ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
+
+ +

Build a 5.1 output from 6 single-channel streams: +

+
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
+
+ + +

8.96 ladspa

+ +

Load a LADSPA (Linux Audio Developer’s Simple Plugin API) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-ladspa. +

+
+
file, f
+

Specifies the name of LADSPA plugin library to load. If the environment +variable LADSPA_PATH is defined, the LADSPA plugin is searched in +each one of the directories specified by the colon separated list in +LADSPA_PATH, otherwise in the standard LADSPA paths, which are in +this order: HOME/.ladspa/lib/, /usr/local/lib/ladspa/, +/usr/lib/ladspa/. +

+
+
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. +

+
+
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=value0|c1=value1|c2=value2|..., where +valuei is the value set on the i-th control. +Alternatively they can be also defined using the following syntax: +value0|value1|value2|..., where +valuei is the value set on the i-th control. +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
latency, l
+

Enable latency compensation, by default is disabled. +Only used if plugin have inputs. +

+
+ + +

8.96.1 Examples

+ +
    +
  • List all available plugins within amp (LADSPA example plugin) library: +
    +
    ladspa=file=amp
    +
    + +
  • List all available controls and their valid ranges for vcf_notch +plugin from VCF library: +
    +
    ladspa=f=vcf:p=vcf_notch:c=help
    +
    + +
  • Simulate low quality audio equipment using Computer Music Toolkit (CMT) +plugin library: +
    +
    ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
    +
    + +
  • Add reverberation to the audio using TAP-plugins +(Tom’s Audio Processing plugins): +
    +
    ladspa=file=tap_reverb:tap_reverb
    +
    + +
  • Generate white noise, with 0.2 amplitude: +
    +
    ladspa=file=cmt:noise_source_white:c=c0=.2
    +
    + +
  • Generate 20 bpm clicks using plugin C* Click - Metronome from the +C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=file=caps:Click:c=c1=20'
    +
    + +
  • Apply C* Eq10X2 - Stereo 10-band equaliser effect: +
    +
    ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
    +
    + +
  • Increase volume by 20dB using fast lookahead limiter from Steve Harris +SWH Plugins collection: +
    +
    ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
    +
    + +
  • Attenuate low frequencies using Multiband EQ from Steve Harris +SWH Plugins collection: +
    +
    ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
    +
    + +
  • Reduce stereo image using Narrower from the C* Audio Plugin Suite +(CAPS) library: +
    +
    ladspa=caps:Narrower
    +
    + +
  • Another white noise, now using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:White:.2
    +
    + +
  • Some fractal noise, using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:Fractal:c=c1=1
    +
    + +
  • Dynamic volume normalization using VLevel plugin: +
    +
    ladspa=vlevel-ladspa:vlevel_mono
    +
    +
+ + +

8.96.2 Commands

+ +

This filter supports the following commands: +

+
cN
+

Modify the N-th control value. +

+

If the specified value is not valid, it is ignored and prior one is kept. +

+
+ + +

8.97 loudnorm

+ +

EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. +Support for both single pass (livestreams, files) and double pass (files) modes. +This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately +detect true peaks, the audio stream will be upsampled to 192 kHz. +Use the -ar option or aresample filter to explicitly set an output sample rate. +

+

The filter accepts the following options: +

+
+
I, i
+

Set integrated loudness target. +Range is -70.0 - -5.0. Default value is -24.0. +

+
+
LRA, lra
+

Set loudness range target. +Range is 1.0 - 50.0. Default value is 7.0. +

+
+
TP, tp
+

Set maximum true peak. +Range is -9.0 - +0.0. Default value is -2.0. +

+
+
measured_I, measured_i
+

Measured IL of input file. +Range is -99.0 - +0.0. +

+
+
measured_LRA, measured_lra
+

Measured LRA of input file. +Range is 0.0 - 99.0. +

+
+
measured_TP, measured_tp
+

Measured true peak of input file. +Range is -99.0 - +99.0. +

+
+
measured_thresh
+

Measured threshold of input file. +Range is -99.0 - +0.0. +

+
+
offset
+

Set offset gain. Gain is applied before the true-peak limiter. +Range is -99.0 - +99.0. Default is +0.0. +

+
+
linear
+

Normalize by linearly scaling the source audio. +measured_I, measured_LRA, measured_TP, +and measured_thresh must all be specified. Target LRA shouldn’t +be lower than source LRA and the change in integrated loudness shouldn’t +result in a true peak which exceeds the target TP. If any of these +conditions aren’t met, normalization mode will revert to dynamic. +Options are true or false. Default is true. +

+
+
dual_mono
+

Treat mono input files as "dual-mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +Options are true or false. Default is false. +

+
+
print_format
+

Set print format for stats. Options are summary, json, or none. +Default value is none. +

+
+
stats_file
+

Write stats to specified file. Format is controlled by print_format, +which must be set. Specify - to write to standard output. +Default is unset. +

+
+ + +

8.98 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 500. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.98.1 Examples

+
    +
  • Lowpass only LFE channel, it LFE is not present it does nothing: +
    +
    lowpass=c=LFE
    +
    +
+ + +

8.98.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change lowpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change lowpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change lowpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change lowpass mix. +Syntax for the command is : "mix" +

+
+ + +

8.99 lv2

+ +

Load a LV2 (LADSPA Version 2) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-lv2. +

+
+
plugin, p
+

Specifies the plugin URI. You may need to escape ’:’. +

+
+
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). +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+ + +

8.99.1 Examples

+ +
    +
  • Apply bass enhancer plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
    +
    + +
  • Apply vinyl plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
    +
    + +
  • Apply bit crusher plugin from ArtyFX: +
    +
    lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
    +
    +
+ + +

8.99.2 Commands

+ +

This filter supports all options that are exported by plugin as commands. +

+ +

8.100 mcompand

+

Multiband Compress or expand the audio’s dynamic range. +

+

The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. +This is akin to the crossover of a loudspeaker, and results in flat frequency +response when absent compander action. +

+

It accepts the following parameters: +

+
+
args
+

This option syntax is: +attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... +For explanation of each item refer to compand filter documentation. +

+
+ + +

8.101 pan

+ +

Mix channels with specific gain levels. The filter accepts the output +channel layout followed by a set of channels definitions. +

+

This filter is also designed to efficiently remap the channels of an audio +stream. +

+

The filter accepts parameters of the form: +"l|outdef|outdef|..." +

+
+
l
+

output channel layout or number of channels +

+
+
outdef
+

output channel specification, of the form: +"out_name=[gain*]in_name[(+-)[gain*]in_name...]" +

+
+
out_name
+

output channel to define, either a channel name (FL, FR, etc.) or a channel +number (c0, c1, etc.) +

+
+
gain
+

multiplicative coefficient for the channel, 1 leaving the volume unchanged +

+
+
in_name
+

input channel to use, see out_name for details; it is not possible to mix +named and numbered input channels +

+
+ +

If the ‘=’ in a channel specification is replaced by ‘<’, then the gains for +that specification will be renormalized so that the total is 1, thus +avoiding clipping noise. +

+ +

8.101.1 Mixing examples

+ +

For example, if you want to down-mix from stereo to mono, but with a bigger +factor for the left channel: +

+
pan=1c|c0=0.9*c0+0.1*c1
+
+ +

A customized down-mix to stereo that works automatically for 3-, 4-, 5- and +7-channels surround: +

+
pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
+
+ +

Note that ffmpeg integrates a default down-mix (and up-mix) system +that should be preferred (see "-ac" option) unless you have very specific +needs. +

+ +

8.101.2 Remapping examples

+ +

The channel remapping will be effective if, and only if: +

+
    +
  • gain coefficients are zeroes or ones, +
  • only one input per channel output, +
+ +

If all these conditions are satisfied, the filter will notify the user ("Pure +channel mapping detected"), and use an optimized and lossless method to do the +remapping. +

+

For example, if you have a 5.1 source and want a stereo audio stream by +dropping the extra channels: +

+
pan="stereo| c0=FL | c1=FR"
+
+ +

Given the same source, you can also switch front left and front right channels +and keep the input channel layout: +

+
pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
+
+ +

If the input is a stereo audio stream, you can mute the front left channel (and +still keep the stereo channel layout) with: +

+
pan="stereo|c1=c1"
+
+ +

Still with a stereo audio stream input, you can copy the right channel in both +front left and right: +

+
pan="stereo| c0=FR | c1=FR"
+
+ + +

8.102 replaygain

+ +

ReplayGain scanner filter. This filter takes an audio stream as an input and +outputs it unchanged. +At end of filtering it displays track_gain and track_peak. +

+

The filter accepts the following exported read-only options: +

+
+
track_gain
+

Exported track gain in dB at end of stream. +

+
+
track_peak
+

Exported track peak at end of stream. +

+
+ + +

8.103 resample

+ +

Convert the audio sample format, sample rate and channel layout. It is +not meant to be used directly. +

+ +

8.104 rubberband

+

Apply time-stretching and pitch-shifting with librubberband. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-librubberband. +

+

The filter accepts the following options: +

+
+
tempo
+

Set tempo scale factor. +

+
+
pitch
+

Set pitch scale factor. +

+
+
transients
+

Set transients detector. +Possible values are: +

+
crisp
+
mixed
+
smooth
+
+ +
+
detector
+

Set detector. +Possible values are: +

+
compound
+
percussive
+
soft
+
+ +
+
phase
+

Set phase. +Possible values are: +

+
laminar
+
independent
+
+ +
+
window
+

Set processing window size. +Possible values are: +

+
standard
+
short
+
long
+
+ +
+
smoothing
+

Set smoothing. +Possible values are: +

+
off
+
on
+
+ +
+
formant
+

Enable formant preservation when shift pitching. +Possible values are: +

+
shifted
+
preserved
+
+ +
+
pitchq
+

Set pitch quality. +Possible values are: +

+
quality
+
speed
+
consistency
+
+ +
+
channels
+

Set channels. +Possible values are: +

+
apart
+
together
+
+
+
+ + +

8.104.1 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+
pitch
+

Change filter pitch scale factor. +Syntax for the command is : "pitch" +

+
+ + +

8.105 sidechaincompress

+ +

This filter acts like normal compressor but has the ability to compress +detected signal using second input signal. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +The filtered signal then can be filtered with other filters in later stages of +processing. See pan and amerge filter. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of second stream raises above this level it will affect the gain +reduction of first stream. +By default is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. 1:2 means that if the level +raised 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of side-chain stream +or the louder(maximum) channel of side-chain stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mainly smoother. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

8.105.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.105.2 Examples

+ +
    +
  • Full ffmpeg example taking 2 audio inputs, 1st input to be compressed +depending on the signal of 2nd input and later compressed signal to be +merged with 2nd input: +
    +
    ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
    +
    +
+ + +

8.106 sidechaingate

+ +

A sidechain gate acts like a normal (wideband) gate but has the ability to +filter the detected signal before sending it to the gain reduction stage. +Normally a gate uses the full range signal to detect a level above the +threshold. +For example: If you cut all lower frequencies from your sidechain signal +the gate will decrease the volume of your track only if not enough highs +appear. With this technique you are able to reduce the resonation of a +natural drum or remove "rumbling" of muted strokes from a heavily distorted +guitar. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is from 0.015625 to 64. +

+
+ + +

8.106.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.107 silencedetect

+ +

Detect silence in an audio stream. +

+

This filter logs a message when it detects that the input audio volume is less +or equal to a noise tolerance value for a duration greater or equal to the +minimum detected noise duration. +

+

The printed times and duration are expressed in seconds. The +lavfi.silence_start or lavfi.silence_start.X metadata key +is set on the first frame whose timestamp equals or exceeds the detection +duration and it contains the timestamp of the first frame of the silence. +

+

The lavfi.silence_duration or lavfi.silence_duration.X +and lavfi.silence_end or lavfi.silence_end.X metadata +keys are set on the first frame after the silence. If mono is +enabled, and each channel is evaluated separately, the .X +suffixed keys are used, and X corresponds to the channel number. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or amplitude ratio. Default is -60dB, or 0.001. +

+
+
duration, d
+

Set silence duration until notification (default is 2 seconds). See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+
+
mono, m
+

Process each channel separately, instead of combined. By default is disabled. +

+
+ + +

8.107.1 Examples

+ +
    +
  • Detect 5 seconds of silence with -50dB noise tolerance: +
    +
    silencedetect=n=-50dB:d=5
    +
    + +
  • Complete example with ffmpeg to detect silence with 0.0001 noise +tolerance in silence.mp3: +
    +
    ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
    +
    +
+ + +

8.108 silenceremove

+ +

Remove silence from the beginning, middle or end of the audio. +

+

The filter accepts the following options: +

+
+
start_periods
+

This value is used to indicate if audio should be trimmed at beginning of +the audio. A value of zero indicates no silence should be trimmed from the +beginning. When specifying a non-zero value, it trims audio up until it +finds non-silence. Normally, when trimming silence from beginning of audio +the start_periods will be 1 but it can be increased to higher +values to trim all audio up to specific count of non-silence periods. +Default value is 0. +

+
+
start_duration
+

Specify the amount of time that non-silence must be detected before it stops +trimming audio. By increasing the duration, bursts of noises can be treated +as silence and trimmed off. Default value is 0. +

+
+
start_threshold
+

This indicates what sample value should be treated as silence. For digital +audio, a value of 0 may be fine but for audio recorded from analog, +you may wish to increase the value to account for background noise. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
start_silence
+

Specify max duration of silence at beginning that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
start_mode
+

Specify mode of detection of silence end at start of multi-channel audio. +Can be any or all. Default is any. +With any, any sample from any channel that is detected as non-silence +will trigger end of silence trimming at start of audio stream. +With all, only if every sample from every channel is detected as non-silence +will trigger end of silence trimming at start of audio stream, limited usage. +

+
+
stop_periods
+

Set the count for trimming silence from the end of audio. When specifying a +positive value, it trims audio after it finds specified silence period. +To remove silence from the middle of a file, specify a stop_periods +that is negative. This value is then treated as a positive value and is +used to indicate the effect should restart processing as specified by +stop_periods, making it suitable for removing periods of silence +in the middle of the audio. +Default value is 0. +

+
+
stop_duration
+

Specify a duration of silence that must exist before audio is not copied any +more. By specifying a higher duration, silence that is wanted can be left in +the audio. +Default value is 0. +

+
+
stop_threshold
+

This is the same as start_threshold but for trimming silence from +the end of audio. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
stop_silence
+

Specify max duration of silence at end that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
stop_mode
+

Specify mode of detection of silence start after start of multi-channel audio. +Can be any or all. Default is all. +With any, any sample from any channel that is detected as silence +will trigger start of silence trimming after start of audio stream, limited usage. +With all, only if every sample from every channel is detected as silence +will trigger start of silence trimming after start of audio stream. +

+
+
detection
+

Set how is silence detected. +

+
avg
+

Mean of absolute values of samples in moving window. +

+
rms
+

Root squared mean of absolute values of samples in moving window. +

+
peak
+

Maximum of absolute values of samples in moving window. +

+
median
+

Median of absolute values of samples in moving window. +

+
ptp
+

Absolute of max peak to min peak difference of samples in moving window. +

+
dev
+

Standard deviation of values of samples in moving window. +

+
+

Default value is rms. +

+
+
window
+

Set duration in number of seconds used to calculate size of window in number +of samples for detecting silence. Using 0 will effectively disable +any windowing and use only single sample per channel for silence detection. +In that case it may be needed to also set start_silence and/or +stop_silence to nonzero values with also start_duration and/or +stop_duration to nonzero values. +Default value is 0.02. Allowed range is from 0 to 10. +

+
+
timestamp
+

Set processing mode of every audio frame output timestamp. +

+
write
+

Full timestamps rewrite, keep only the start time for the first output frame. +

+
copy
+

Non-dropped frames are left with same timestamp as input audio frame. +

+
+

Defaults value is write. +

+
+ + +

8.108.1 Examples

+ +
    +
  • The following example shows how this filter can be used to start a recording +that does not contain the delay at the start which usually occurs between +pressing the record button and the start of the performance: +
    +
    silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
    +
    + +
  • Trim all silence encountered from beginning to end where there is more than 1 +second of silence in audio: +
    +
    silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Trim all digital silence samples, using peak detection, from beginning to end +where there is more than 0 samples of digital silence in audio and digital +silence is detected in all channels at same positions in stream: +
    +
    silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
    +
    + +
  • Trim every 2nd encountered silence period from beginning to end where there is +more than 1 second of silence per silence period in audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Similar as above, but keep maximum of 0.5 seconds of silence from each trimmed period: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5
    +
    + +
  • Similar as above, but keep maximum of 1.5 seconds of silence from start of audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5:start_periods=1:start_duration=1:start_silence=1.5:stop_threshold=-90dB
    +
    +
+ + +

8.108.2 Commands

+ +

This filter supports some above options as commands. +

+ +

8.109 sofalizer

+ +

SOFAlizer uses head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones (audio +formats up to 9 channels supported). +The HRTFs are stored in SOFA files (see http://www.sofacoustics.org/ for a database). +SOFAlizer is developed at the Acoustics Research Institute (ARI) of the +Austrian Academy of Sciences. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libmysofa. +

+

The filter accepts the following options: +

+
+
sofa
+

Set the SOFA file used for rendering. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
rotation
+

Set rotation of virtual loudspeakers in deg. Default is 0. +

+
+
elevation
+

Set elevation of virtual speakers in deg. Default is 0. +

+
+
radius
+

Set distance in meters between loudspeakers and the listener with near-field +HRTFs. Default is 1. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
speakers
+

Set custom positions of virtual loudspeakers. Syntax for this option is: +<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. +Each virtual loudspeaker is described with short channel name following with +azimuth and elevation in degrees. +Each virtual loudspeaker description is separated by ’|’. +For example to override front left and front right channel positions use: +’speakers=FL 45 15|FR 345 15’. +Descriptions with unrecognised channel names are ignored. +

+
+
lfegain
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
framesize
+

Set custom frame size in number of samples. Default is 1024. +Allowed range is from 1024 to 96000. Only used if option ‘type’ +is set to freq. +

+
+
normalize
+

Should all IRs be normalized upon importing SOFA file. +By default is enabled. +

+
+
interpolate
+

Should nearest IRs be interpolated with neighbor IRs if exact position +does not match. By default is disabled. +

+
+
minphase
+

Minphase all IRs upon loading of SOFA file. By default is disabled. +

+
+
anglestep
+

Set neighbor search angle step. Only used if option interpolate is enabled. +

+
+
radstep
+

Set neighbor search radius step. Only used if option interpolate is enabled. +

+
+ + +

8.109.1 Examples

+ +
    +
  • Using ClubFritz6 sofa file: +
    +
    sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
    +
    + +
  • Using ClubFritz12 sofa file and bigger radius with small rotation: +
    +
    sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
    +
    + +
  • Similar as above but with custom speaker positions for front left, front right, back left and back right +and also with custom gain: +
    +
    "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
    +
    +
+ + +

8.110 speechnorm

+

Speech Normalizer. +

+

This filter expands or compresses each half-cycle of audio samples +(local set of samples all above or all below zero and between two nearest zero crossings) depending +on threshold value, so audio reaches target peak value under conditions controlled by below options. +

+

The filter accepts the following options: +

+
+
peak, p
+

Set the expansion target peak value. This specifies the highest allowed absolute amplitude +level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0. +

+
+
expansion, e
+

Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples expansion. The maximum expansion +would be such that local peak value reaches target peak value but never to surpass it and that +ratio between new and previous peak value does not surpass this option value. +

+
+
compression, c
+

Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples compression. This option is used +only if threshold option is set to value greater than 0.0, then in such cases +when local peak is lower or same as value set by threshold all samples belonging to +that peak’s half-cycle will be compressed by current compression factor. +

+
+
threshold, t
+

Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0. +This option specifies which half-cycles of samples will be compressed and which will be expanded. +Any half-cycle samples with their local peak value below or same as this option value will be +compressed by current compression factor, otherwise, if greater than threshold value they will be +expanded with expansion factor so that it could reach peak target value but never surpass it. +

+
+
raise, r
+

Set the expansion raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per +each new half-cycle until it reaches expansion value. +Setting this options too high may lead to distortions. +

+
+
fall, f
+

Set the compression raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per +each new half-cycle until it reaches compression value. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
invert, i
+

Enable inverted filtering, by default is disabled. This inverts interpretation of threshold +option. When enabled any half-cycle of samples with their local peak value below or same as +threshold option will be expanded otherwise it will be compressed. +

+
+
link, l
+

Link channels when calculating gain applied to each filtered channel sample, by default is disabled. +When disabled each filtered channel gain calculation is independent, otherwise when this option +is enabled the minimum of all possible gains for each filtered channel is used. +

+
+
rms, m
+

Set the expansion target RMS value. This specifies the highest allowed RMS level for the normalized +audio input. Default value is 0.0, thus disabled. Allowed range is from 0.0 to 1.0. +

+
+ + +

8.110.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.110.2 Examples

+ +
    +
  • Weak and slow amplification: +
    +
    speechnorm=e=3:r=0.00001:l=1
    +
    + +
  • Moderate and slow amplification: +
    +
    speechnorm=e=6.25:r=0.00001:l=1
    +
    + +
  • Strong and fast amplification: +
    +
    speechnorm=e=12.5:r=0.0001:l=1
    +
    + +
  • Very strong and fast amplification: +
    +
    speechnorm=e=25:r=0.0001:l=1
    +
    + +
  • Extreme and fast amplification: +
    +
    speechnorm=e=50:r=0.0001:l=1
    +
    +
+ + +

8.111 stereotools

+ +

This filter has some handy utilities to manage stereo signals, for converting +M/S stereo recordings to L/R signal while having control over the parameters +or spreading the stereo image of master track. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
level_out
+

Set output level after filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
balance_in
+

Set input balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
balance_out
+

Set output balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
softclip
+

Enable softclipping. Results in analog distortion instead of harsh digital 0dB +clipping. Disabled by default. +

+
+
mutel
+

Mute the left channel. Disabled by default. +

+
+
muter
+

Mute the right channel. Disabled by default. +

+
+
phasel
+

Change the phase of the left channel. Disabled by default. +

+
+
phaser
+

Change the phase of the right channel. Disabled by default. +

+
+
mode
+

Set stereo mode. Available values are: +

+
+
‘lr>lr’
+

Left/Right to Left/Right, this is default. +

+
+
‘lr>ms’
+

Left/Right to Mid/Side. +

+
+
‘ms>lr’
+

Mid/Side to Left/Right. +

+
+
‘lr>ll’
+

Left/Right to Left/Left. +

+
+
‘lr>rr’
+

Left/Right to Right/Right. +

+
+
‘lr>l+r’
+

Left/Right to Left + Right. +

+
+
‘lr>rl’
+

Left/Right to Right/Left. +

+
+
‘ms>ll’
+

Mid/Side to Left/Left. +

+
+
‘ms>rr’
+

Mid/Side to Right/Right. +

+
+
‘ms>rl’
+

Mid/Side to Right/Left. +

+
+
‘lr>l-r’
+

Left/Right to Left - Right. +

+
+ +
+
slev
+

Set level of side signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
sbal
+

Set balance of side signal. Default is 0. +Allowed range is from -1 to 1. +

+
+
mlev
+

Set level of the middle signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
mpan
+

Set middle signal pan. Default is 0. Allowed range is from -1 to 1. +

+
+
base
+

Set stereo base between mono and inversed channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
delay
+

Set delay in milliseconds how much to delay left from right channel and +vice versa. Default is 0. Allowed range is from -20 to 20. +

+
+
sclevel
+

Set S/C level. Default is 1. Allowed range is from 1 to 100. +

+
+
phase
+

Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. +

+
+
bmode_in, bmode_out
+

Set balance mode for balance_in/balance_out option. +

+

Can be one of the following: +

+
+
‘balance’
+

Classic balance mode. Attenuate one channel at time. +Gain is raised up to 1. +

+
+
‘amplitude’
+

Similar as classic mode above but gain is raised up to 2. +

+
+
‘power’
+

Equal power distribution, from -6dB to +6dB range. +

+
+
+
+ + +

8.111.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

8.111.2 Examples

+ +
    +
  • Apply karaoke like effect: +
    +
    stereotools=mlev=0.015625
    +
    + +
  • Convert M/S signal to L/R: +
    +
    "stereotools=mode=ms>lr"
    +
    +
+ + +

8.112 stereowiden

+ +

This filter enhance the stereo effect by suppressing signal common to both +channels and by delaying the signal of left into right and vice versa, +thereby widening the stereo effect. +

+

The filter accepts the following options: +

+
+
delay
+

Time in milliseconds of the delay of left signal into right and vice versa. +Default is 20 milliseconds. +

+
+
feedback
+

Amount of gain in delayed signal into right and vice versa. Gives a delay +effect of left signal in right output and vice versa which gives widening +effect. Default is 0.3. +

+
+
crossfeed
+

Cross feed of left into right with inverted phase. This helps in suppressing +the mono. If the value is 1 it will cancel all the signal common to both +channels. Default is 0.3. +

+
+
drymix
+

Set level of input signal of original channel. Default is 0.8. +

+
+ + +

8.112.1 Commands

+ +

This filter supports the all above options except delay as commands. +

+ +

8.113 superequalizer

+

Apply 18 band equalizer. +

+

The filter accepts the following options: +

+
1b
+

Set 65Hz band gain. +

+
2b
+

Set 92Hz band gain. +

+
3b
+

Set 131Hz band gain. +

+
4b
+

Set 185Hz band gain. +

+
5b
+

Set 262Hz band gain. +

+
6b
+

Set 370Hz band gain. +

+
7b
+

Set 523Hz band gain. +

+
8b
+

Set 740Hz band gain. +

+
9b
+

Set 1047Hz band gain. +

+
10b
+

Set 1480Hz band gain. +

+
11b
+

Set 2093Hz band gain. +

+
12b
+

Set 2960Hz band gain. +

+
13b
+

Set 4186Hz band gain. +

+
14b
+

Set 5920Hz band gain. +

+
15b
+

Set 8372Hz band gain. +

+
16b
+

Set 11840Hz band gain. +

+
17b
+

Set 16744Hz band gain. +

+
18b
+

Set 20000Hz band gain. +

+
+ + +

8.114 surround

+

Apply audio surround upmix filter. +

+

This filter allows to produce multichannel output from audio stream. +

+

The filter accepts the following options: +

+
+
chl_out
+

Set output channel layout. By default, this is 5.1. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
chl_in
+

Set input channel layout. By default, this is stereo. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
level_in
+

Set input volume level. By default, this is 1. +

+
+
level_out
+

Set output volume level. By default, this is 1. +

+
+
lfe
+

Enable LFE channel output if output channel layout has it. By default, this is enabled. +

+
+
lfe_low
+

Set LFE low cut off frequency. By default, this is 128 Hz. +

+
+
lfe_high
+

Set LFE high cut off frequency. By default, this is 256 Hz. +

+
+
lfe_mode
+

Set LFE mode, can be add or sub. Default is add. +In add mode, LFE channel is created from input audio and added to output. +In sub mode, LFE channel is created from input audio and added to output but +also all non-LFE output channels are subtracted with output LFE channel. +

+
+
smooth
+

Set temporal smoothness strength, used to gradually change factors when transforming +stereo sound in time. Allowed range is from 0.0 to 1.0. +Useful to improve output quality with focus option values greater than 0.0. +Default is 0.0. Only values inside this range and without edges are effective. +

+
+
angle
+

Set angle of stereo surround transform, Allowed range is from 0 to 360. +Default is 90. +

+
+
focus
+

Set focus of stereo surround transform, Allowed range is from -1 to 1. +Default is 0. +

+
+
fc_in
+

Set front center input volume. By default, this is 1. +

+
+
fc_out
+

Set front center output volume. By default, this is 1. +

+
+
fl_in
+

Set front left input volume. By default, this is 1. +

+
+
fl_out
+

Set front left output volume. By default, this is 1. +

+
+
fr_in
+

Set front right input volume. By default, this is 1. +

+
+
fr_out
+

Set front right output volume. By default, this is 1. +

+
+
sl_in
+

Set side left input volume. By default, this is 1. +

+
+
sl_out
+

Set side left output volume. By default, this is 1. +

+
+
sr_in
+

Set side right input volume. By default, this is 1. +

+
+
sr_out
+

Set side right output volume. By default, this is 1. +

+
+
bl_in
+

Set back left input volume. By default, this is 1. +

+
+
bl_out
+

Set back left output volume. By default, this is 1. +

+
+
br_in
+

Set back right input volume. By default, this is 1. +

+
+
br_out
+

Set back right output volume. By default, this is 1. +

+
+
bc_in
+

Set back center input volume. By default, this is 1. +

+
+
bc_out
+

Set back center output volume. By default, this is 1. +

+
+
lfe_in
+

Set LFE input volume. By default, this is 1. +

+
+
lfe_out
+

Set LFE output volume. By default, this is 1. +

+
+
allx
+

Set spread usage of stereo image across X axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
ally
+

Set spread usage of stereo image across Y axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
fcx, flx, frx, blx, brx, slx, srx, bcx
+

Set spread usage of stereo image across X axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
fcy, fly, fry, bly, bry, sly, sry, bcy
+

Set spread usage of stereo image across Y axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.5. +

+
+ + +

8.115 tiltshelf

+ +

Boost or cut the lower frequencies and cut or boost higher 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: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.115.1 Commands

+ +

This filter supports some options as commands. +

+ +

8.116 treble, highshelf

+ +

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). +

+

The filter accepts the following options: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

8.116.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change treble frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change treble width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change treble width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change treble gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change treble mix. +Syntax for the command is : "mix" +

+
+ + +

8.117 tremolo

+ +

Sinusoidal amplitude modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. Modulation frequencies in the subharmonic range +(20 Hz or lower) will result in a tremolo effect. +This filter may also be used as a ring modulator by specifying +a modulation frequency higher than 20 Hz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

8.118 vibrato

+ +

Sinusoidal phase modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

8.119 virtualbass

+ +

Apply audio Virtual Bass filter. +

+

This filter accepts stereo input and produce stereo with LFE (2.1) channels output. +The newly produced LFE channel have enhanced virtual bass originally obtained from both stereo channels. +This filter outputs front left and front right channels unchanged as available in stereo input. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set the virtual bass cutoff frequency. Default value is 250 Hz. +Allowed range is from 100 to 500 Hz. +

+
+
strength
+

Set the virtual bass strength. Allowed range is from 0.5 to 3. +Default value is 3. +

+
+ + +

8.120 volume

+ +

Adjust the input audio volume. +

+

It accepts the following parameters: +

+
volume
+

Set audio volume expression. +

+

Output values are clipped to the maximum value. +

+

The output audio volume is given by the relation: +

+
output_volume = volume * input_volume
+
+ +

The default value for volume is "1.0". +

+
+
precision
+

This parameter represents the mathematical precision. +

+

It determines which input sample formats will be allowed, which affects the +precision of the volume scaling. +

+
+
fixed
+

8-bit fixed-point; this limits input sample format to U8, S16, and S32. +

+
float
+

32-bit floating-point; this limits input sample format to FLT. (default) +

+
double
+

64-bit floating-point; this limits input sample format to DBL. +

+
+ +
+
replaygain
+

Choose the behaviour on encountering ReplayGain side data in input frames. +

+
+
drop
+

Remove ReplayGain side data, ignoring its contents (the default). +

+
+
ignore
+

Ignore ReplayGain side data, but leave it in the frame. +

+
+
track
+

Prefer the track gain, if present. +

+
+
album
+

Prefer the album gain, if present. +

+
+ +
+
replaygain_preamp
+

Pre-amplification gain in dB to apply to the selected replaygain gain. +

+

Default value for replaygain_preamp is 0.0. +

+
+
replaygain_noclip
+

Prevent clipping by limiting the gain applied. +

+

Default value for replaygain_noclip is 1. +

+
+
eval
+

Set when the volume expression is evaluated. +

+

It accepts the following values: +

+
‘once’
+

only evaluate expression once during the filter initialization, or +when the ‘volume’ command is sent +

+
+
‘frame’
+

evaluate expression for each incoming frame +

+
+ +

Default value is ‘once’. +

+
+ +

The volume expression can contain the following parameters. +

+
+
n
+

frame number (starting at zero) +

+
nb_channels
+

number of channels +

+
nb_consumed_samples
+

number of samples consumed by the filter +

+
nb_samples
+

number of samples in the current frame +

+
pos
+

original frame position in the file; deprecated, do not use +

+
pts
+

frame PTS +

+
sample_rate
+

sample rate +

+
startpts
+

PTS at start of stream +

+
startt
+

time at start of stream +

+
t
+

frame time +

+
tb
+

timestamp timebase +

+
volume
+

last set volume value +

+
+ +

Note that when eval is set to ‘once’ only the +sample_rate and tb variables are available, all other +variables will evaluate to NAN. +

+ +

8.120.1 Commands

+ +

This filter supports the following commands: +

+
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. +

+
+ + +

8.120.2 Examples

+ +
    +
  • Halve the input audio volume: +
    +
    volume=volume=0.5
    +volume=volume=1/2
    +volume=volume=-6.0206dB
    +
    + +

    In all the above example the named key for volume can be +omitted, for example like in: +

    +
    volume=0.5
    +
    + +
  • Increase input audio power by 6 decibels using fixed-point precision: +
    +
    volume=volume=6dB:precision=fixed
    +
    + +
  • Fade volume after time 10 with an annihilation period of 5 seconds: +
    +
    volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
    +
    +
+ + +

8.121 volumedetect

+ +

Detect the volume of the input video. +

+

The filter has no parameters. It supports only 16-bit signed integer samples, +so the input will be converted when needed. 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 a histogram of the +registered volume values (from the maximum value to a cumulated 1/1000 of +the samples). +

+

All volumes are in decibels relative to the maximum PCM value. +

+ +

8.121.1 Examples

+ +

Here is an excerpt of the output: +

+
[Parsed_volumedetect_0  0xa23120] mean_volume: -27 dB
+[Parsed_volumedetect_0  0xa23120] max_volume: -4 dB
+[Parsed_volumedetect_0  0xa23120] histogram_4db: 6
+[Parsed_volumedetect_0  0xa23120] histogram_5db: 62
+[Parsed_volumedetect_0  0xa23120] histogram_6db: 286
+[Parsed_volumedetect_0  0xa23120] histogram_7db: 1042
+[Parsed_volumedetect_0  0xa23120] histogram_8db: 2551
+[Parsed_volumedetect_0  0xa23120] histogram_9db: 4609
+[Parsed_volumedetect_0  0xa23120] histogram_10db: 8409
+
+ +

It means that: +

    +
  • The mean square energy is approximately -27 dB, or 10^-2.7. +
  • The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. +
  • There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. +
+ +

In other words, raising the volume by +4 dB does not cause any clipping, +raising it by +5 dB causes clipping for 6 samples, etc. +

+ +

8.122 whisper

+ +

It runs automatic speech recognition using the OpenAI’s Whisper model. +

+

It requires the whisper.cpp library (https://github.com/ggml-org/whisper.cpp) +as a prerequisite. After installing the library it can be enabled using: +./configure --enable-whisper. +

+

The filter has following options: +

+
+
model
+

The file path of the downloaded whisper.cpp model (mandatory). +

+
+
language
+

The language to use for transcription (’auto’ for auto-detect). +Default value: "auto" +

+
+
queue
+

The maximum size that will be queued into the filter before processing the audio +with whisper. Using a small value the audio stream will be processed more often, +but the transcription quality will be lower and the required processing power +will be higher. Using a large value (e.g. 10-20s) will produce more accurate +results using less CPU (as using the whisper-cli tool), but the transcription +latency will be higher, thus not useful to process real-time streams. +Consider using the vad_model option associated with a large queue value. +Default value: "3" +

+
+
use_gpu
+

If the GPU support should be enabled. +Default value: "true" +

+
+
gpu_device
+

The GPU device index to use. +Default value: "0" +

+
+
destination
+

If set, the transcription output will be sent to the specified file or URL +(use one of the FFmpeg AVIO protocols); otherwise, the output will be logged as +info messages. +The output will also be set in the "lavfi.whisper.text" frame metadata. +If the destination is a file and it already exists, it will be overwritten. +

+
+
format
+

The destination format string; it could be "text" (only the transcribed text +will be sent to the destination), "srt" (subtitle format) or "json". +Default value: "text" +

+
+
max_len
+

Maximum segment length in characters. When set to a value greater than 0, +transcription segments will be split to not exceed this length. This is useful +for generating subtitles with shorter lines. +Default value: "0" +

+
+
vad_model
+

Path to the VAD model file. If set, the filter will load an additional voice +activity detection module (https://github.com/snakers4/silero-vad) that will be +used to fragment the audio queue; use this option setting a valid path obtained +from the whisper.cpp repository (e.g. "../whisper.cpp/models/ggml-silero-v5.1.2.bin") +and increase the queue parameter to a higher value (e.g. 20). +

+
+
vad_threshold
+

The VAD threshold to use. +Default value: "0.5" +

+
+
vad_min_speech_duration
+

The minimum VAD speaking duration. +Default value: "0.1" +

+
+
vad_min_silence_duration
+

The minimum VAD silence duration. +Default value: "0.5" +

+
+
+ + +

8.122.1 Examples

+
    +
  • Run a transcription with srt file generation: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=output.srt\
    +:format=srt" -f null -
    +
    + +
  • Run a transcription and send the output in JSON format to an HTTP service: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=http\\://localhost\\:3000\
    +:format=json' -f null -
    +
    + +
  • Transcribe the microphone input using the VAD option: +
    +
    ffmpeg -loglevel warning -f pulse -i default \
    +-af 'highpass=f=200,lowpass=f=3000,whisper=model=../whisper.cpp/models/ggml-medium.bin\
    +:language=en\
    +:queue=10\
    +:destination=-\
    +:format=json\
    +:vad_model=../whisper.cpp/models/ggml-silero-v5.1.2.bin' -f null -
    +
    + +
+ + + +

9 Audio Sources

+ +

Below is a description of the currently available audio sources. +

+ +

9.1 abuffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
time_base
+

The timebase which will be used for timestamps of submitted frames. It must be +either a floating-point number or in numerator/denominator form. +

+
+
sample_rate
+

The sample rate of the incoming audio buffers. +

+
+
sample_fmt
+

The sample format of the incoming audio buffers. +Either a sample format name or its corresponding integer representation from +the enum AVSampleFormat in libavutil/samplefmt.h +

+
+
channel_layout
+

The channel layout of the incoming audio buffers. +Either a channel layout name from channel_layout_map in +libavutil/channel_layout.c or its corresponding integer representation +from the AV_CH_LAYOUT_* macros in libavutil/channel_layout.h +

+
+
channels
+

The number of channels of the incoming audio buffers. +If both channels and channel_layout are specified, then they +must be consistent. +

+
+
+ + +

9.1.1 Examples

+ +
+
abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
+
+ +

will instruct the source to accept planar 16bit signed stereo at 44100Hz. +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: +

+
abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
+
+ + +

9.2 aevalsrc

+ +

Generate an audio signal specified by an expression. +

+

This source accepts in input one or more expressions (one for each +channel), which are evaluated and used to generate a corresponding +audio signal. +

+

This source accepts the following options: +

+
+
exprs
+

Set the ’|’-separated expressions list for each separate channel. In case the +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. +

+
+
channel_layout, c
+

Set the channel layout. The number of channels in the specified layout +must be equal to the number of specified expressions. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, +default to 1024. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. +

+
+ +

Each expression in exprs can contain the following constants: +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
t
+

time of the evaluated sample expressed in seconds, starting from 0 +

+
+
s
+

sample rate +

+
+
+ + +

9.2.1 Examples

+ +
    +
  • Generate silence: +
    +
    aevalsrc=0
    +
    + +
  • Generate a sin signal with frequency of 440 Hz, set sample rate to +8000 Hz: +
    +
    aevalsrc="sin(440*2*PI*t):s=8000"
    +
    + +
  • Generate a two channels signal, specify the channel layout (Front +Center + Back Center) explicitly: +
    +
    aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
    +
    + +
  • Generate white noise: +
    +
    aevalsrc="-2+random(0)"
    +
    + +
  • Generate an amplitude modulated signal: +
    +
    aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
    +
    + +
  • Generate 2.5 Hz binaural beats on a 360 Hz carrier: +
    +
    aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
    +
    + +
+ + +

9.3 afdelaysrc

+ +

Generate a fractional delay FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
delay, d
+

Set the fractional delay. Default is 0. +

+
+
sample_rate, r
+

Set the sample rate, default is 44100. +

+
+
nb_samples, n
+

Set the number of samples per each frame. Default is 1024. +

+
+
taps, t
+

Set the number of filter coefficients in output audio stream. +Default value is 0. +

+
+
channel_layout, c
+

Specifies the channel layout, and can be a string representing a channel layout. +The default value of channel_layout is "stereo". +

+
+ + +

9.4 afireqsrc

+ +

Generate a FIR equalizer coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
preset, p
+

Set equalizer preset. +Default preset is flat. +

+

Available presets are: +

+
‘custom’
+
‘flat’
+
‘acoustic’
+
‘bass’
+
‘beats’
+
‘classic’
+
‘clear’
+
‘deep bass’
+
‘dubstep’
+
‘electronic’
+
‘hard-style’
+
‘hip-hop’
+
‘jazz’
+
‘metal’
+
‘movie’
+
‘pop’
+
‘r&b’
+
‘rock’
+
‘vocal booster’
+
+ +
+
gains, g
+

Set custom gains for each band. Only used if the preset option is set to custom. +Gains are separated by white spaces and each gain is set in dBFS. +Default is 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0. +

+
+
bands, b
+

Set the custom bands from where custom equalizer gains are set. +This must be in strictly increasing order. Only used if the preset option is set to custom. +Bands are separated by white spaces and each band represent frequency in Hz. +Default is 25 40 63 100 160 250 400 630 1000 1600 2500 4000 6300 10000 16000 24000. +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 4096. +

+
+
sample_rate, r
+

Set sample rate of output audio stream, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame in output audio stream. Default is 1024. +

+
+
interp, i
+

Set interpolation method for FIR equalizer coefficients. Can be linear or cubic. +

+
+
phase, h
+

Set phase type of FIR filter. Can be linear or min: minimum-phase. +Default is minimum-phase filter. +

+
+ + +

9.5 afirsrc

+ +

Generate a FIR coefficients using frequency sampling method. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 1025. +

+
+
frequency, f
+

Set frequency points from where magnitude and phase are set. +This must be in non decreasing order, and first element must be 0, while last element +must be 1. Elements are separated by white spaces. +

+
+
magnitude, m
+

Set magnitude value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
phase, p
+

Set phase value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
win_func, w
+

Set window function. Default is blackman. +

+
+ + +

9.6 anullsrc

+ +

The null audio source, return unprocessed audio frames. It is mainly useful +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). +

+

This source accepts the following options: +

+
+
channel_layout, cl
+
+

Specifies the channel layout, and can be either an integer or a string +representing a channel layout. The default value of channel_layout +is "stereo". +

+

Check the channel_layout_map definition in +libavutil/channel_layout.c for the mapping between strings and +channel layout values. +

+
+
sample_rate, r
+

Specifies the sample rate, and defaults to 44100. +

+
+
nb_samples, n
+

Set the number of samples per requested frames. +

+
+
duration, d
+

Set the duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. +

+
+ + +

9.6.1 Examples

+ +
    +
  • Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. +
    +
    anullsrc=r=48000:cl=4
    +
    + +
  • Do the same operation with a more obvious syntax: +
    +
    anullsrc=r=48000:cl=mono
    +
    +
+ +

All the parameters need to be explicitly defined. +

+ +

9.7 flite

+ +

Synthesize a voice utterance using the libflite library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libflite. +

+

Note that versions of the flite library prior to 2.0 are not thread-safe. +

+

The filter accepts the following options: +

+
+
list_voices
+

If set to 1, list the names of the available voices and exit +immediately. Default value is 0. +

+
+
nb_samples, n
+

Set the maximum number of samples per frame. Default value is 512. +

+
+
textfile
+

Set the filename containing the text to speak. +

+
+
text
+

Set the text to speak. +

+
+
voice, v
+

Set the voice to use for the speech synthesis. Default value is +kal. See also the list_voices option. +

+
+ + +

9.7.1 Examples

+ +
    +
  • Read from file speech.txt, and synthesize the text using the +standard flite voice: +
    +
    flite=textfile=speech.txt
    +
    + +
  • Read the specified text selecting the slt voice: +
    +
    flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Input text to ffmpeg: +
    +
    ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Make ffplay speak the specified text, using flite and +the lavfi device: +
    +
    ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
    +
    +
+ +

For more information about libflite, check: +http://www.festvox.org/flite/ +

+ +

9.8 anoisesrc

+ +

Generate a noise audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Specify the sample rate. Default value is 48000 Hz. +

+
+
amplitude, a
+

Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value +is 1.0. +

+
+
duration, d
+

Specify the duration of the generated audio stream. Not specifying this option +results in noise with an infinite length. +

+
+
color, colour, c
+

Specify the color of noise. Available noise colors are white, pink, brown, +blue, violet and velvet. Default color is white. +

+
+
seed, s
+

Specify a value used to seed the PRNG. +

+
+
nb_samples, n
+

Set the number of samples per each output frame, default is 1024. +

+
+
density
+

Set the density (0.0 - 1.0) for the velvet noise generator, default is 0.05. +

+
+ + +

9.8.1 Examples

+ +
    +
  • Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: +
    +
    anoisesrc=d=60:c=pink:r=44100:a=0.5
    +
    +
+ + +

9.9 hilbert

+ +

Generate odd-tap Hilbert transform FIR coefficients. +

+

The resulting stream can be used with afir filter for phase-shifting +the signal by 90 degrees. +

+

This is used in many matrix coding schemes and for analytic signal generation. +The process is often written as a multiplication by i (or j), the imaginary unit. +

+

The filter accepts the following options: +

+
+
sample_rate, s
+

Set sample rate, default is 44100. +

+
+
taps, t
+

Set length of FIR filter, default is 22051. +

+
+
nb_samples, n
+

Set number of samples per each frame. +

+
+
win_func, w
+

Set window function to be used when generating FIR coefficients. +

+
+ + +

9.10 sinc

+ +

Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
hp
+

Set high-pass frequency. Default is 0. +

+
+
lp
+

Set low-pass frequency. Default is 0. +If high-pass frequency is lower than low-pass frequency and low-pass frequency +is higher than 0 then filter will create band-pass filter coefficients, +otherwise band-reject filter coefficients. +

+
+
phase
+

Set filter phase response. Default is 50. Allowed range is from 0 to 100. +

+
+
beta
+

Set Kaiser window beta. +

+
+
att
+

Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. +

+
+
round
+

Enable rounding, by default is disabled. +

+
+
hptaps
+

Set number of taps for high-pass filter. +

+
+
lptaps
+

Set number of taps for low-pass filter. +

+
+ + +

9.11 sine

+ +

Generate an audio signal made of a sine wave with amplitude 1/8. +

+

The audio signal is bit-exact. +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the carrier frequency. Default is 440 Hz. +

+
+
beep_factor, b
+

Enable a periodic beep every second with frequency beep_factor times +the carrier frequency. Default is 0, meaning the beep is disabled. +

+
+
sample_rate, r
+

Specify the sample rate, default is 44100. +

+
+
duration, d
+

Specify the duration of the generated audio stream. +

+
+
samples_per_frame
+

Set the number of samples per output frame. +

+

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the output audio frame, starting from 0. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the output audio frame, +expressed in TB units. +

+
+
t
+

The PTS of the output audio frame, expressed in seconds. +

+
+
TB
+

The timebase of the output audio frames. +

+
+ +

Default is 1024. +

+
+ + +

9.11.1 Examples

+ +
    +
  • Generate a simple 440 Hz sine wave: +
    +
    sine
    +
    + +
  • Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: +
    +
    sine=220:4:d=5
    +sine=f=220:b=4:d=5
    +sine=frequency=220:beep_factor=4:duration=5
    +
    + +
  • Generate a 1 kHz sine wave following 1602,1601,1602,1601,1602 NTSC +pattern: +
    +
    sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
    +
    +
+ + + +

10 Audio Sinks

+ +

Below is a description of the currently available audio sinks. +

+ +

10.1 abuffersink

+ +

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 libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVABufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+

10.2 anullsink

+ +

Null audio sink; do absolutely nothing with the input audio. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

11 Video Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the video filters included in your +build. +

+

Below is a description of the currently available video filters. +

+ +

11.1 addroi

+ +

Mark a region of interest in a video frame. +

+

The frame data is passed through unchanged, but metadata is attached +to the frame indicating regions of interest which can affect the +behaviour of later encoding. Multiple regions can be marked by +applying the filter multiple times. +

+
+
x
+

Region distance in pixels from the left edge of the frame. +

+
y
+

Region distance in pixels from the top edge of the frame. +

+
w
+

Region width in pixels. +

+
h
+

Region height in pixels. +

+

The parameters x, y, w and h are expressions, +and may contain the following variables: +

+
iw
+

Width of the input frame. +

+
ih
+

Height of the input frame. +

+
+ +
+
qoffset
+

Quantisation offset to apply within the region. +

+

This must be a real value in the range -1 to +1. A value of zero +indicates no quality change. A negative value asks for better quality +(less quantisation), while a positive value asks for worse quality +(greater quantisation). +

+

The range is calibrated so that the extreme values indicate the +largest possible offset - if the rest of the frame is encoded with the +worst possible quality, an offset of -1 indicates that this region +should be encoded with the best possible quality anyway. Intermediate +values are then interpolated in some codec-dependent way. +

+

For example, in 10-bit H.264 the quantisation parameter varies between +-12 and 51. A typical qoffset value of -1/10 therefore indicates that +this region should be encoded with a QP around one-tenth of the full +range better than the rest of the frame. So, if most of the frame +were to be encoded with a QP of around 30, this region would get a QP +of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). +An extreme value of -1 would indicate that this region should be +encoded with the best possible quality regardless of the treatment of +the rest of the frame - that is, should be encoded at a QP of -12. +

+
clear
+

If set to true, remove any existing regions of interest marked on the +frame before adding the new one. +

+
+ + +

11.1.1 Examples

+ +
    +
  • Mark the centre quarter of the frame as interesting. +
    +
    addroi=iw/4:ih/4:iw/2:ih/2:-1/10
    +
    +
  • Mark the 100-pixel-wide region on the left edge of the frame as very +uninteresting (to be encoded at much lower quality than the rest of +the frame). +
    +
    addroi=0:0:100:ih:+1/5
    +
    +
+ + +

11.2 alphaextract

+ +

Extract the alpha component from the input as a grayscale video. This +is especially useful with the alphamerge filter. +

+ +

11.3 alphamerge

+ +

Add or replace the alpha component of the primary input with the +grayscale value of a second input. This is intended for use with +alphaextract to allow the transmission or storage of frame +sequences that have alpha in a format that doesn’t support an alpha +channel. +

+

For example, to reconstruct full frames from a normal YUV-encoded video +and a separate video created with alphaextract, you might use: +

+
movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
+
+ + +

11.4 amplify

+ +

Amplify differences between current pixel and pixels of adjacent frames in +same pixel location. +

+

This filter accepts the following options: +

+
+
radius
+

Set frame radius. Default is 2. Allowed range is from 1 to 63. +For example radius of 3 will instruct filter to calculate average of 7 frames. +

+
+
factor
+

Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. +

+
+
threshold
+

Set threshold for difference amplification. Any difference greater or equal to +this value will not alter source pixel. Default is 10. +Allowed range is from 0 to 65535. +

+
+
tolerance
+

Set tolerance for difference amplification. Any difference lower to +this value will not alter source pixel. Default is 0. +Allowed range is from 0 to 65535. +

+
+
low
+

Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will decrease source pixel value. +

+
+
high
+

Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will increase source pixel value. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

11.4.1 Commands

+ +

This filter supports the following commands that corresponds to option of same name: +

+
factor
+
threshold
+
tolerance
+
low
+
high
+
planes
+
+ + +

11.5 ass

+ +

Same as the subtitles filter, except that it doesn’t require libavcodec +and libavformat to work. On the other hand, it is limited to ASS (Advanced +Substation Alpha) subtitles files. +

+

This filter accepts the following option in addition to the common options from +the subtitles filter: +

+
+
shaping
+

Set the shaping engine +

+

Available values are: +

+
‘auto’
+

The default libass shaping engine, which is the best available. +

+
‘simple’
+

Fast, font-agnostic shaper that can do only substitutions +

+
‘complex’
+

Slower shaper using OpenType for substitutions and positioning +

+
+ +

The default is auto. +

+
+ + +

11.6 atadenoise

+

Apply an Adaptive Temporal Averaging Denoiser to the video input. +

+

The filter accepts the following options: +

+
+
0a
+

Set threshold A for 1st plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
0b
+

Set threshold B for 1st plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
1a
+

Set threshold A for 2nd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
1b
+

Set threshold B for 2nd plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
2a
+

Set threshold A for 3rd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
2b
+

Set threshold B for 3rd plane. Default is 0.04. +Valid range is 0 to 5. +

+

Threshold A is designed to react on abrupt changes in the input signal and +threshold B is designed to react on continuous changes in the input signal. +

+
+
s
+

Set number of frames filter will use for averaging. Default is 9. Must be odd +number in range [5, 129]. +

+
+
p
+

Set what planes of frame filter will use for averaging. Default is all. +

+
+
a
+

Set what variant of algorithm filter will use for averaging. Default is p parallel. +Alternatively can be set to s serial. +

+

Parallel can be faster then serial, while other way around is never true. +Parallel will abort early on first change being greater then thresholds, while serial +will continue processing other side of frames if they are equal or below thresholds. +

+
+
0s
+
1s
+
2s
+

Set sigma for 1st plane, 2nd plane or 3rd plane. Default is 32767. +Valid range is from 0 to 32767. +This options controls weight for each pixel in radius defined by size. +Default value means every pixel have same weight. +Setting this option to 0 effectively disables filtering. +

+
+ + +

11.6.1 Commands

+

This filter supports same commands as options except option s. +The command accepts the same syntax of the corresponding option. +

+ +

11.7 avgblur

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sizeY
+

Set vertical radius size, if zero it will be same as sizeX. +Default is 0. +

+
+ + +

11.7.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.8 backgroundkey

+ +

Turns a static background into transparency. +

+

The filter accepts the following option: +

+
+
threshold
+

Threshold for scene change detection. +

+
similarity
+

Similarity percentage with the background. +

+
blend
+

Set the blend amount for pixels that are not similar. +

+
+ + +

11.8.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.9 bbox

+ +

Compute the bounding box for the non-black pixels in the input frame +luma plane. +

+

This filter computes the bounding box containing all the pixels with a +luma 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: +

+
+
min_val
+

Set the minimal luma value. Default is 16. +

+
+ + +

11.9.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.10 bilateral

+

Apply bilateral filter, spatial smoothing while preserving edges. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight. +Allowed range is 0 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate range weight. +Allowed range is 0 to 1. Default is 0.1. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

11.10.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.11 bitplanenoise

+ +

Show and measure bit plane noise. +

+

The filter accepts the following options: +

+
+
bitplane
+

Set which plane to analyze. Default is 1. +

+
+
filter
+

Filter out noisy pixels from bitplane set above. +Default is disabled. +

+
+ + +

11.12 blackdetect, blackdetect_vulkan

+ +

Detect video intervals that are (almost) completely black. Can be +useful to detect chapter transitions, commercials, or invalid +recordings. +

+

The filter outputs its detection analysis to both the log as well as +frame metadata. If a black segment of at least the specified minimum +duration is found, a line with the start and end timestamps as well +as duration is printed to the log with level info. In addition, +a log line with level debug is printed per frame showing the +black amount detected for that frame. +

+

The filter also attaches metadata to the first frame of a black +segment with key lavfi.black_start and to the first frame +after the black segment ends with key lavfi.black_end. The +value is the frame’s timestamp. This metadata is added regardless +of the minimum duration specified. +

+

The filter accepts the following options: +

+
+
black_min_duration, d
+

Set the minimum detected black duration expressed in seconds. It must +be a non-negative floating point number. +

+

Default value is 2.0. +

+
+
picture_black_ratio_th, pic_th
+

Set the threshold for considering a picture "black". +Express the minimum value for the ratio: +

+
nb_black_pixels / nb_pixels
+
+ +

for which a picture is considered black. +Default value is 0.98. +

+
+
pixel_black_th, pix_th
+

Set the threshold for considering a pixel "black". +

+

The threshold expresses the maximum pixel luma value for which a +pixel is considered "black". The provided value is scaled according to +the following equation: +

+
absolute_threshold = luma_minimum_value + pixel_black_th * luma_range_size
+
+ +

luma_range_size and luma_minimum_value depend on +the input video format, the range is [0-255] for YUV full-range +formats and [16-235] for YUV non full-range formats. +

+

Default value is 0.10. +

+
+
alpha
+

If true, check the alpha channel instead of the luma channel. Detects frames +which are (almost) transparent, instead of frames which are almost black. +

+

Default value is disabled. +

+
+ +

The following example sets the maximum pixel threshold to the minimum +value, and detects only black intervals of 2 or more seconds: +

+
blackdetect=d=2:pix_th=0.00
+
+ + +

11.13 blackframe

+ +

Detect frames that are (almost) completely black. Can be useful to +detect chapter transitions or commercials. Output lines consist of +the frame number of the detected frame, the percentage of blackness, +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. +

+

This filter exports frame metadata lavfi.blackframe.pblack. +The value represents the percentage of pixels in the picture that +are below the threshold value. +

+

It accepts the following parameters: +

+
+
amount
+

The percentage of the pixels that have to be below the threshold; it defaults to +98. +

+
+
threshold, thresh
+

The threshold below which a pixel value is considered black; it defaults to +32. +

+
+
+ + +

11.14 blend

+ +

Blend two video frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

The tblend (time blend) filter takes two consecutive frames +from one single stream, and outputs the result obtained by blending +the new frame on top of the old frame. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘addition’
+
‘and’
+
‘average’
+
‘bleach’
+
‘burn’
+
‘darken’
+
‘difference’
+
‘divide’
+
‘dodge’
+
‘exclusion’
+
‘extremity’
+
‘freeze’
+
‘geometric’
+
‘glow’
+
‘grainextract’
+
‘grainmerge’
+
‘hardlight’
+
‘hardmix’
+
‘hardoverlay’
+
‘harmonic’
+
‘heat’
+
‘interpolate’
+
‘lighten’
+
‘linearlight’
+
‘multiply’
+
‘multiply128’
+
‘negation’
+
‘normal’
+
‘or’
+
‘overlay’
+
‘phoenix’
+
‘pinlight’
+
‘reflect’
+
‘screen’
+
‘softdifference’
+
‘softlight’
+
‘stain’
+
‘subtract’
+
‘vividlight’
+
‘xor’
+
+ +
+
c0_opacity
+
c1_opacity
+
c2_opacity
+
c3_opacity
+
all_opacity
+

Set blend opacity for specific pixel component or all pixel components in case +of all_opacity. Only used in combination with pixel component blend modes. +

+
+
c0_expr
+
c1_expr
+
c2_expr
+
c3_expr
+
all_expr
+

Set blend expression for specific pixel component or all pixel components in case +of all_expr. Note that related mode options will be ignored if those are set. +

+

The expressions can use the following variables: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

the coordinates of the current sample +

+
+
W
+
H
+

the width and height of currently filtered plane +

+
+
SW
+
SH
+

Width and height scale for the plane being filtered. It is the +ratio between the dimensions of the current plane to the luma plane, +e.g. for a yuv420p frame, the values are 1,1 for +the luma plane and 0.5,0.5 for the chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
TOP, A
+

Value of pixel component at current location for first video frame (top layer). +

+
+
BOTTOM, B
+

Value of pixel component at current location for second video frame (bottom layer). +

+
+
+
+ +

The blend filter also supports the framesync options. +

+ +

11.14.1 Examples

+ +
    +
  • Apply transition from bottom layer to top layer in first 10 seconds: +
    +
    blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
    +
    + +
  • Apply linear horizontal transition from top layer to bottom layer: +
    +
    blend=all_expr='A*(X/W)+B*(1-X/W)'
    +
    + +
  • Apply 1x1 checkerboard effect: +
    +
    blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
    +
    + +
  • Apply uncover left effect: +
    +
    blend=all_expr='if(gte(N*SW+X,W),A,B)'
    +
    + +
  • Apply uncover down effect: +
    +
    blend=all_expr='if(gte(Y-N*SH,0),A,B)'
    +
    + +
  • Apply uncover up-left effect: +
    +
    blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
    +
    + +
  • Split diagonally video and shows top and bottom layer on each side: +
    +
    blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
    +
    + +
  • Display differences between the current and the previous frame: +
    +
    tblend=all_mode=grainextract
    +
    +
+ + +

11.14.2 Commands

+

This filter supports same commands as options. +

+ +

11.15 blockdetect

+ +

Determines blockiness of frames without altering the input frames. +

+

Based on Remco Muijs and Ihor Kirenko: "A no-reference blocking artifact measure for adaptive video processing." 2005 13th European signal processing conference. +

+

The filter accepts the following options: +

+
+
period_min
+
period_max
+

Set minimum and maximum values for determining pixel grids (periods). +Default values are [3,24]. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

11.15.1 Examples

+ +
    +
  • Determine blockiness for the first plane and search for periods within [8,32]: +
    +
    blockdetect=period_min=8:period_max=32:planes=1
    +
    +
+ + +

11.16 blurdetect

+ +

Determines blurriness of frames without altering the input frames. +

+

Based on Marziliano, Pina, et al. "A no-reference perceptual blur metric." +Allows for a block-based abbreviation. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
radius
+

Define the radius to search around an edge pixel for local maxima. +

+
+
block_pct
+

Determine blurriness only for the most significant blocks, given in percentage. +

+
+
block_width
+

Determine blurriness for blocks of width block_width. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_height. +

+
+
block_height
+

Determine blurriness for blocks of height block_height. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_width. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

11.16.1 Examples

+ +
    +
  • Determine blur for 80% of most significant 32x32 blocks: +
    +
    blurdetect=block_width=32:block_height=32:block_pct=80
    +
    +
+ + +

11.17 bm3d

+ +

Denoise frames using Block-Matching 3D algorithm. +

+

The filter accepts the following options. +

+
+
sigma
+

Set denoising strength. Default value is 1. +Allowed range is from 0 to 999.9. +The denoising algorithm is very sensitive to sigma, so adjust it +according to the source. +

+
+
block
+

Set local patch size. This sets dimensions in 2D. +

+
+
bstep
+

Set sliding step for processing blocks. Default value is 4. +Allowed range is from 1 to 64. +Smaller values allows processing more reference blocks and is slower. +

+
+
group
+

Set maximal number of similar blocks for 3rd dimension. Default value is 1. +When set to 1, no block matching is done. Larger values allows more blocks +in single group. +Allowed range is from 1 to 256. +

+
+
range
+

Set radius for search block matching. Default is 9. +Allowed range is from 1 to INT32_MAX. +

+
+
mstep
+

Set step between two search locations for block matching. Default is 1. +Allowed range is from 1 to 64. Smaller is slower. +

+
+
thmse
+

Set threshold of mean square error for block matching. Valid range is 0 to +INT32_MAX. +

+
+
hdthr
+

Set thresholding parameter for hard thresholding in 3D transformed domain. +Larger values results in stronger hard-thresholding filtering in frequency +domain. +

+
+
estim
+

Set filtering estimation mode. Can be basic or final. +Default is basic. +

+
+
ref
+

If enabled, filter will use 2nd stream for block matching. +Default is disabled for basic value of estim option, +and always enabled if value of estim is final. +

+
+
planes
+

Set planes to filter. Default is all available except alpha. +

+
+ + +

11.17.1 Examples

+ +
    +
  • Basic filtering with bm3d: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
    +
    + +
  • Same as above, but filtering only luma: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
    +
    + +
  • Same as above, but with both estimation modes: +
    +
    split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    + +
  • Same as above, but prefilter with nlmeans filter instead: +
    +
    split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    +
+ + +

11.18 boxblur

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

11.18.1 Examples

+ +
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radii +set to 2: +
    +
    boxblur=luma_radius=2:luma_power=1
    +boxblur=2:1
    +
    + +
  • Set the luma radius to 2, and alpha and chroma radius to 0: +
    +
    boxblur=2:1:cr=0:ar=0
    +
    + +
  • Set the luma and chroma radii to a fraction of the video dimension: +
    +
    boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
    +
    +
+ + +

11.19 bwdif

+ +

Deinterlace the input video ("bwdif" stands for "Bob Weaver +Deinterlacing Filter"). +

+

Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic +interpolation algorithms. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

11.20 ccrepack

+ +

Repack CEA-708 closed captioning side data +

+

This filter fixes various issues seen with commercial encoders +related to upstream malformed CEA-708 payloads, specifically +incorrect number of tuples (wrong cc_count for the target FPS), +and incorrect ordering of tuples (i.e. the CEA-608 tuples are not at +the first entries in the payload). +

+ +

11.21 cas

+ +

Apply Contrast Adaptive Sharpen filter to video stream. +

+

The filter accepts the following options: +

+
+
strength
+

Set the sharpening strength. Default value is 0. +

+
+
planes
+

Set planes to filter. Default value is to filter all +planes except alpha plane. +

+
+ + +

11.21.1 Commands

+

This filter supports same commands as options. +

+ +

11.22 chromahold

+

Remove all color information for all colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral chroma. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +0.0 makes pixels either fully gray, or not gray at all. +Higher values result in more preserved color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

11.22.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.23 chromakey

+

YUV colorspace color/chroma keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

11.23.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.23.2 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf chromakey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static black background. +
    +
    ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
    +
    +
+ + +

11.24 chromanr

+

Reduce chrominance noise. +

+

The filter accepts the following options: +

+
+
thres
+

Set threshold for averaging chrominance values. +Sum of absolute difference of Y, U and V pixel components of current +pixel and neighbour pixels lower than this threshold will be used in +averaging. Luma component is left unchanged and is copied to output. +Default value is 30. Allowed range is from 1 to 200. +

+
+
sizew
+

Set horizontal radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
sizeh
+

Set vertical radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
stepw
+

Set horizontal step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
steph
+

Set vertical step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
threy
+

Set Y threshold for averaging chrominance values. +Set finer control for max allowed difference between Y components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threu
+

Set U threshold for averaging chrominance values. +Set finer control for max allowed difference between U components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threv
+

Set V threshold for averaging chrominance values. +Set finer control for max allowed difference between V components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
distance
+

Set distance type used in calculations. +

+
+
‘manhattan’
+

Absolute difference. +

+
‘euclidean’
+

Difference squared. +

+
+ +

Default distance type is manhattan. +

+
+ + +

11.24.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+ +

11.25 chromashift

+

Shift chroma pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
cbh
+

Set amount to shift chroma-blue horizontally. +

+
cbv
+

Set amount to shift chroma-blue vertically. +

+
crh
+

Set amount to shift chroma-red horizontally. +

+
crv
+

Set amount to shift chroma-red vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

11.25.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.26 ciescope

+ +

Display CIE color diagram with pixels overlaid onto it. +

+

The filter accepts the following options: +

+
+
system
+

Set color system. +

+
+
‘ntsc, 470m’
+
‘ebu, 470bg’
+
‘smpte’
+
‘240m’
+
‘apple’
+
‘widergb’
+
‘cie1931’
+
‘rec709, hdtv’
+
‘uhdtv, rec2020’
+
‘dcip3’
+
+ +
+
cie
+

Set CIE system. +

+
+
‘xyy’
+
‘ucs’
+
‘luv’
+
+ +
+
gamuts
+

Set what gamuts to draw. +

+

See system option for available values. +

+
+
size, s
+

Set ciescope size, by default set to 512. +

+
+
intensity, i
+

Set intensity used to map input pixel values to CIE diagram. +

+
+
contrast
+

Set contrast used to draw tongue colors that are out of active color system gamut. +

+
+
corrgamma
+

Correct gamma displayed on scope, by default enabled. +

+
+
showwhite
+

Show white point on CIE diagram, by default disabled. +

+
+
gamma
+

Set input gamma. Used only with XYZ input color space. +

+
+
fill
+

Fill with CIE colors. By default is enabled. +

+
+ + +

11.27 codecview

+ +

Visualize information exported by some codecs. +

+

Some codecs can export information through frames using side-data or other +means. For example, some MPEG based codecs export motion vectors through the +export_mvs flag in the codec flags2 option. +

+

The filter accepts the following option: +

+
+
block
+

Display block partition structure using the luma plane. +

+
+
mv
+

Set motion vectors to visualize. +

+

Available flags for mv are: +

+
+
‘pf’
+

forward predicted MVs of P-frames +

+
‘bf’
+

forward predicted MVs of B-frames +

+
‘bb’
+

backward predicted MVs of B-frames +

+
+ +
+
qp
+

Display quantization parameters using the chroma planes. +

+
+
mv_type, mvt
+

Set motion vectors type to visualize. Includes MVs from all frames unless specified by frame_type option. +

+

Available flags for mv_type are: +

+
+
‘fp’
+

forward predicted MVs +

+
‘bp’
+

backward predicted MVs +

+
+ +
+
frame_type, ft
+

Set frame type to visualize motion vectors of. +

+

Available flags for frame_type are: +

+
+
‘if’
+

intra-coded frames (I-frames) +

+
‘pf’
+

predicted frames (P-frames) +

+
‘bf’
+

bi-directionally predicted frames (B-frames) +

+
+
+
+ + +

11.27.1 Examples

+ +
    +
  • Visualize forward predicted MVs of all frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
    +
    + +
  • Visualize multi-directionals MVs of P and B-Frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
    +
    +
+ + +

11.28 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: +

+
+
rs
+
gs
+
bs
+

Adjust red, green and blue shadows (darkest pixels). +

+
+
rm
+
gm
+
bm
+

Adjust red, green and blue midtones (medium pixels). +

+
+
rh
+
gh
+
bh
+

Adjust red, green and blue highlights (brightest pixels). +

+

Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
pl
+

Preserve lightness when changing color balance. Default is disabled. +

+
+ + +

11.28.1 Examples

+ +
    +
  • Add red color cast to shadows: +
    +
    colorbalance=rs=.3
    +
    +
+ + +

11.28.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.29 colorcontrast

+ +

Adjust color contrast between RGB components. +

+

The filter accepts the following options: +

+
+
rc
+

Set the red-cyan contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
gm
+

Set the green-magenta contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
by
+

Set the blue-yellow contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
rcw
+
gmw
+
byw
+

Set the weight of each rc, gm, by option value. Default value is 0.0. +Allowed range is from 0.0 to 1.0. If all weights are 0.0 filtering is disabled. +

+
+
pl
+

Set the amount of preserving lightness. Default value is 0.0. Allowed range is from 0.0 to 1.0. +

+
+ + +

11.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.30 colorcorrect

+ +

Adjust color white balance selectively for blacks and whites. +This filter operates in YUV colorspace. +

+

The filter accepts the following options: +

+
+
rl
+

Set the red shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bl
+

Set the blue shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
rh
+

Set the red highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bh
+

Set the blue highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
saturation
+

Set the amount of saturation. Allowed range is from -3.0 to 3.0. +Default value is 1. +

+
+
analyze
+

If set to anything other than manual it will analyze every frame and use derived +parameters for filtering output frame. +

+

Possible values are: +

+
‘manual’
+
‘average’
+
‘minmax’
+
‘median’
+
+

Default value is manual. +

+
+ + +

11.30.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.31 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: +

+
red=red*rr + blue*rb + green*rg + alpha*ra
+
+ +

The filter accepts the following options: +

+
+
rr
+
rg
+
rb
+
ra
+

Adjust contribution of input red, green, blue and alpha channels for output red channel. +Default is 1 for rr, and 0 for rg, rb and ra. +

+
+
gr
+
gg
+
gb
+
ga
+

Adjust contribution of input red, green, blue and alpha channels for output green channel. +Default is 1 for gg, and 0 for gr, gb and ga. +

+
+
br
+
bg
+
bb
+
ba
+

Adjust contribution of input red, green, blue and alpha channels for output blue channel. +Default is 1 for bb, and 0 for br, bg and ba. +

+
+
ar
+
ag
+
ab
+
aa
+

Adjust contribution of input red, green, blue and alpha channels for output alpha channel. +Default is 1 for aa, and 0 for ar, ag and ab. +

+

Allowed ranges for options are [-2.0, 2.0]. +

+
+
pc
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+ +
+
pa
+

Set the preserve color amount when changing colors. Allowed range is from [0.0, 1.0]. +Default is 0.0, thus disabled. +

+
+ + +

11.31.1 Examples

+ +
    +
  • Convert source to grayscale: +
    +
    colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
    +
    +
  • Simulate sepia tones: +
    +
    colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
    +
    +
+ + +

11.31.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.32 colordetect

+

Analyze the video frames to determine the effective value range and alpha +mode. +

+

The filter accepts the following options: +

+
+
mode
+

Set of properties to detect. Unavailable properties, such as alpha mode for +an input image without an alpha channel, will be ignored automatically. +

+

Accepts a combination of the following flags: +

+
+
‘color_range’
+

Detect if the source contains luma pixels outside the limited (MPEG) range, +which indicates that this is a full range YUV source. +

+
‘alpha_mode’
+

Detect if the source contains color values above the alpha channel, which +indicates that the alpha channel is independent (straight), rather than +premultiplied. Also detects if the alpha plane is fully opaque or not. +

+
‘all’
+

Enable detection of all of the above properties. This is the default. +

+
+ +
+
+ + +

11.33 colorize

+

Overlay a solid color on the video stream. +

+

The filter accepts the following options: +

+
+
hue
+

Set the color hue. Allowed range is from 0 to 360. +Default value is 0. +

+
+
saturation
+

Set the color saturation. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
lightness
+

Set the color lightness. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
mix
+

Set the mix of source lightness. By default is set to 1.0. +Allowed range is from 0.0 to 1.0. +

+
+ + +

11.33.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.34 colorkey

+

RGB colorspace color keying. +This filter operates on 8-bit RGB format frames by setting the alpha component of each pixel +which falls within the similarity radius of the key color to 0. The alpha value for pixels outside +the similarity radius depends on the value of the blend option. +

+

The filter accepts the following options: +

+
+
color
+

Set the color for which alpha will be set to 0 (full transparency). +See "Color" section in the ffmpeg-utils manual. +Default is black. +

+
+
similarity
+

Set the radius from the key color within which other colors also have full transparency. +The computed distance is related to the unit fractional distance in 3D space between the RGB values +of the key color and the pixel’s color. Range is 0.01 to 1.0. 0.01 matches within a very small radius +around the exact key color, while 1.0 matches everything. +Default is 0.01. +

+
+
blend
+

Set how the alpha value for pixels that fall outside the similarity radius is computed. +0.0 makes pixels either fully transparent or fully opaque. +Higher values result in semi-transparent pixels, with greater transparency +the more similar the pixel color is to the key color. +Range is 0.0 to 1.0. Default is 0.0. +

+
+ + +

11.34.1 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf colorkey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static background image. +
    +
    ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv
    +
    +
+ + +

11.34.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.35 colorhold

+

Remove all color information for all RGB colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral gray. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. 0.0 makes pixels fully gray. +Higher values result in more preserved color. +

+
+ + +

11.35.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.36 colorlevels

+ +

Adjust video input frames using levels. +

+

The filter accepts the following options: +

+
+
rimin
+
gimin
+
bimin
+
aimin
+

Adjust red, green, blue and alpha input black point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
rimax
+
gimax
+
bimax
+
aimax
+

Adjust red, green, blue and alpha input white point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 1. +

+

Input levels are used to lighten highlights (bright tones), darken shadows +(dark tones), change the balance of bright and dark tones. +

+
+
romin
+
gomin
+
bomin
+
aomin
+

Adjust red, green, blue and alpha output black point. +Allowed ranges for options are [0, 1.0]. Defaults are 0. +

+
+
romax
+
gomax
+
bomax
+
aomax
+

Adjust red, green, blue and alpha output white point. +Allowed ranges for options are [0, 1.0]. Defaults are 1. +

+

Output levels allows manual selection of a constrained output level range. +

+
+
preserve
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+
+
+ + +

11.36.1 Examples

+ +
    +
  • Make video output darker: +
    +
    colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
    +
    + +
  • Increase contrast: +
    +
    colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
    +
    + +
  • Make video output lighter: +
    +
    colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
    +
    + +
  • Increase brightness: +
    +
    colorlevels=romin=0.5:gomin=0.5:bomin=0.5
    +
    +
+ + +

11.36.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.37 colormap

+

Apply custom color maps to video stream. +

+

This filter needs three input video streams. +First stream is video stream that is going to be filtered out. +Second and third video stream specify color patches for source +color to target color mapping. +

+

The filter accepts the following options: +

+
+
patch_size
+

Set the source and target video stream patch size in pixels. +

+
+
nb_patches
+

Set the max number of used patches from source and target video stream. +Default value is number of patches available in additional video streams. +Max allowed number of patches is 64. +

+
+
type
+

Set the adjustments used for target colors. Can be relative or absolute. +Defaults is absolute. +

+
+
kernel
+

Set the kernel used to measure color differences between mapped colors. +

+

The accepted values are: +

+
‘euclidean’
+
‘weuclidean’
+
+ +

Default is euclidean. +

+
+ + +

11.38 colormatrix

+ +

Convert color matrix. +

+

The filter accepts the following options: +

+
+
src
+
dst
+

Specify the source and destination color matrix. Both values must be +specified. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt601’
+

BT.601 +

+
+
‘bt470’
+

BT.470 +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+
+ +

For example to convert from BT.601 to SMPTE-240M, use the command: +

+
colormatrix=bt601:smpte240m
+
+ + +

11.39 colorspace

+ +

Convert colorspace, transfer characteristics or color primaries. +Input video needs to have an even size. +

+

The filter accepts the following options: +

+
+
+
all
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘bt601-6-525’
+

BT.601-6 525 +

+
+
‘bt601-6-625’
+

BT.601-6 625 +

+
+
‘bt709’
+

BT.709 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
space
+

Specify output colorspace. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘ycgco’
+

YCgCo +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M, BT.601-6 625 or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘srgb’
+

SRGB +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘xvycc’
+

xvycc +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+ +
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
format
+

Specify output color format. +

+

The accepted values are: +

+
‘yuv420p’
+

YUV 4:2:0 planar 8-bits +

+
+
‘yuv420p10’
+

YUV 4:2:0 planar 10-bits +

+
+
‘yuv420p12’
+

YUV 4:2:0 planar 12-bits +

+
+
‘yuv422p’
+

YUV 4:2:2 planar 8-bits +

+
+
‘yuv422p10’
+

YUV 4:2:2 planar 10-bits +

+
+
‘yuv422p12’
+

YUV 4:2:2 planar 12-bits +

+
+
‘yuv444p’
+

YUV 4:4:4 planar 8-bits +

+
+
‘yuv444p10’
+

YUV 4:4:4 planar 10-bits +

+
+
‘yuv444p12’
+

YUV 4:4:4 planar 12-bits +

+
+
+ +
+
fast
+

Do a fast conversion, which skips gamma/primary correction. This will take +significantly less CPU, but will be mathematically incorrect. To get output +compatible with that produced by the colormatrix filter, use fast=1. +

+
+
dither
+

Specify dithering mode. +

+

The accepted values are: +

+
‘none’
+

No dithering +

+
+
‘fsb’
+

Floyd-Steinberg dithering +

+
+ +
+
wpadapt
+

Whitepoint adaptation mode. +

+

The accepted values are: +

+
‘bradford’
+

Bradford whitepoint adaptation +

+
+
‘vonkries’
+

von Kries whitepoint adaptation +

+
+
‘identity’
+

identity whitepoint adaptation (i.e. no whitepoint adaptation) +

+
+ +
+
clipgamut
+

Controls how to clip out-of-gamut colors that arise as a result of colorspace conversion. +

+

The accepted values are: +

+
‘none’
+

No clipping of out of gamut colors. +

+
+
‘rgb’
+

Clips the RGB values to the [0, 1] range when building the gamma transfer LUTs. +

+
+ +
+
iall
+

Override all input properties at once. Same accepted values as all. +

+
+
ispace
+

Override input colorspace. Same accepted values as space. +

+
+
iprimaries
+

Override input color primaries. Same accepted values as primaries. +

+
+
itrc
+

Override input transfer characteristics. Same accepted values as trc. +

+
+
irange
+

Override input color range. Same accepted values as range. +

+
+
+ +

The filter converts the transfer characteristics, color space and color +primaries to the specified user values. The output value, if not specified, +is set to a default value based on the "all" property. If that property is +also not specified, the filter will log an error. The output color range and +format default to the same value as the input color range and format. The +input transfer characteristics, color space, color primaries and color range +should be set on the input data. If any of these are missing, the filter will +log an error and no conversion will take place. +

+

For example to convert the input to SMPTE-240M, use the command: +

+
colorspace=smpte240m
+
+ + +

11.40 colortemperature

+

Adjust color temperature in video to simulate variations in ambient color temperature. +

+

The filter accepts the following options: +

+
+
temperature
+

Set the temperature in Kelvin. Allowed range is from 1000 to 40000. +Default value is 6500 K. +

+
+
mix
+

Set mixing with filtered output. Allowed range is from 0 to 1. +Default value is 1. +

+
+
pl
+

Set the amount of preserving lightness. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

11.40.1 Commands

+

This filter supports same commands as options. +

+ +

11.41 convolution

+ +

Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed integers in square mode, +and from 1 to 49 odd number of signed integers in row mode. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be 1/sum of all matrix elements. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. Default is 0.0. +

+
+
0mode
+
1mode
+
2mode
+
3mode
+

Set matrix mode for each plane. Can be square, row or column. +Default is square. +

+
+ + +

11.41.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.41.2 Examples

+ +
    +
  • Apply sharpen: +
    +
    convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
    +
    + +
  • Apply blur: +
    +
    convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
    +
    + +
  • Apply edge enhance: +
    +
    convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
    +
    + +
  • Apply edge detect: +
    +
    convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"
    +
    + +
  • Apply emboss: +
    +
    convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
    +
    +
+ + +

11.42 convolve

+ +

Apply 2D convolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+ +

The convolve filter also supports the framesync options. +

+ +

11.43 copy

+ +

Copy the input video source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

11.44 coreimage

+

Video filtering on GPU using Apple’s CoreImage API on OSX. +

+

Hardware acceleration is based on an OpenGL context. Usually, this means it is +processed by video hardware. However, software-based OpenGL implementations +exist which means there is no guarantee for hardware processing. It depends on +the respective OSX. +

+

There are many filters and image generators provided by Apple that come with a +large variety of options. The filter has to be referenced by its name along +with its options. +

+

The coreimage filter accepts the following options: +

+
list_filters
+

List all available filters and generators along with all their respective +options as well as possible minimum and maximum values along with the default +values. +

+
list_filters=true
+
+ +
+
filter
+

Specify all filters by their respective name and options. +Use list_filters to determine all valid filter names and options. +Numerical options are specified by a float value and are automatically clamped +to their respective value range. Vector and color options have to be specified +by a list of space separated float values. Character escaping has to be done. +A special option name default is available to use default options for a +filter. +

+

It is required to specify either default or at least one of the filter options. +All omitted options are used with their default values. +The syntax of the filter string is as follows: +

+
filter=<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...][#<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...]][#...]
+
+ +
+
output_rect
+

Specify a rectangle where the output of the filter chain is copied into the +input image. It is given by a list of space separated float values: +

+
output_rect=x\ y\ width\ height
+
+

If not given, the output rectangle equals the dimensions of the input image. +The output rectangle is automatically cropped at the borders of the input +image. Negative values are valid for each component. +

+
output_rect=25\ 25\ 100\ 100
+
+
+
+ +

Several filters can be chained for successive processing without GPU-HOST +transfers allowing for fast processing of complex filter chains. +Currently, only filters with zero (generators) or exactly one (filters) input +image and one output image are supported. Also, transition filters are not yet +usable as intended. +

+

Some filters generate output images with additional padding depending on the +respective filter kernel. The padding is automatically removed to ensure the +filter output has the same size as the input image. +

+

For image generators, the size of the output image is determined by the +previous output image of the filter chain or the input image of the whole +filterchain, respectively. The generators do not use the pixel information of +this image to generate their output. However, the generated output is +blended onto this image, resulting in partial or complete coverage of the +output image. +

+

The coreimagesrc video source can be used for generating input images +which are directly fed into the filter chain. By using it, providing input +images by another video source or an input video is not required. +

+ +

11.44.1 Examples

+ +
    +
  • List all filters available: +
    +
    coreimage=list_filters=true
    +
    + +
  • Use the CIBoxBlur filter with default options to blur an image: +
    +
    coreimage=filter=CIBoxBlur@default
    +
    + +
  • Use a filter chain with CISepiaTone at default values and CIVignetteEffect with +its center at 100x100 and a radius of 50 pixels: +
    +
    coreimage=filter=CIBoxBlur@default#CIVignetteEffect@inputCenter=100\ 100@inputRadius=50
    +
    + +
  • Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +
+ + +

11.45 corr

+ +

Obtain the correlation between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max correlation is printed through +the logging system. +

+

The filter stores the calculated correlation of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi corr -f null -
+
+ + +

11.46 cover_rect

+ +

Cover a rectangular object +

+

It accepts the following options: +

+
+
cover
+

Filepath of the optional cover image, needs to be in yuv420. +

+
+
mode
+

Set covering mode. +

+

It accepts the following values: +

+
‘cover’
+

cover it by the supplied image +

+
‘blur’
+

cover it by interpolating the surrounding pixels +

+
+ +

Default value is blur. +

+
+ + +

11.46.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    +
+ + +

11.47 crop

+ +

Crop the input video to given dimensions. +

+

It accepts the following parameters: +

+
+
w, out_w
+

The width of the output video. It defaults to iw. +This expression is evaluated only once during the filter +configuration, or when the ‘w’ or ‘out_w’ command is sent. +

+
+
h, out_h
+

The height of the output video. It defaults to ih. +This expression is evaluated only once during the filter +configuration, or when the ‘h’ or ‘out_h’ command is sent. +

+
+
x
+

The horizontal position, in the input video, of the left edge of the output +video. It defaults to (in_w-out_w)/2. +This expression is evaluated per-frame. +

+
+
y
+

The vertical position, in the input video, of the top edge of the output video. +It defaults to (in_h-out_h)/2. +This expression is evaluated per-frame. +

+
+
keep_aspect
+

If set to 1 will force the output display aspect ratio +to be the same of the input, by changing the output sample aspect +ratio. It defaults to 0. +

+
+
exact
+

Enable exact cropping. If enabled, subsampled videos will be cropped at exact +width/height/x/y as specified and will not be rounded to nearest smaller value. +It defaults to 0. +

+
+ +

The out_w, out_h, x, y parameters are +expressions containing the following constants: +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
in_w
+
in_h
+

The input width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (cropped) width and height. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

The expression for out_w may depend on the value of out_h, +and the expression for out_h may depend on out_w, but they +cannot depend on x and y, as x and y are +evaluated after out_w and out_h. +

+

The x and y parameters specify the expressions for the +position of the top-left corner of the output (non-cropped) area. They +are evaluated for each frame. If the evaluated value is not valid, it +is approximated to the nearest valid value. +

+

The expression for x may depend on y, and the expression +for y may depend on x. +

+ +

11.47.1 Examples

+ +
    +
  • Crop area with size 100x100 at position (12,34). +
    +
    crop=100:100:12:34
    +
    + +

    Using named options, the example above becomes: +

    +
    crop=w=100:h=100:x=12:y=34
    +
    + +
  • Crop the central input area with size 100x100: +
    +
    crop=100:100
    +
    + +
  • Crop the central input area with size 2/3 of the input video: +
    +
    crop=2/3*in_w:2/3*in_h
    +
    + +
  • Crop the input video central square: +
    +
    crop=out_w=in_h
    +crop=in_h
    +
    + +
  • Delimit the rectangle with the top-left corner placed at position +100:100 and the right-bottom corner corresponding to the right-bottom +corner of the input image. +
    +
    crop=in_w-100:in_h-100:100:100
    +
    + +
  • Crop 10 pixels from the left and right borders, and 20 pixels from +the top and bottom borders +
    +
    crop=in_w-2*10:in_h-2*20
    +
    + +
  • Keep only the bottom right quarter of the input image: +
    +
    crop=in_w/2:in_h/2:in_w/2:in_h/2
    +
    + +
  • Crop height for getting Greek harmony: +
    +
    crop=in_w:1/PHI*in_w
    +
    + +
  • Apply trembling effect: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)
    +
    + +
  • Apply erratic camera effect depending on timestamp: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)
    +
    + +
  • Set x depending on the value of y: +
    +
    crop=in_w/2:in_h/2:y:10+10*sin(n/10)
    +
    +
+ + +

11.47.2 Commands

+ +

This filter supports the following commands: +

+
w, out_w
+
h, out_h
+
x
+
y
+

Set width/height of the output video and the horizontal/vertical position +in the input video. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+
+ + +

11.48 cropdetect

+ +

Auto-detect the crop size. +

+

It calculates the necessary cropping parameters and prints the +recommended parameters via the logging system. The detected dimensions +correspond to the non-black or video area of the input video according to mode. +

+

It accepts the following parameters: +

+
+
mode
+

Depending on mode crop detection is based on either the mere black value of surrounding pixels or a combination of motion vectors and edge pixels. +

+
+
‘black’
+

Detect black pixels surrounding the playing video. For fine control use option limit. +

+
+
‘mvedges’
+

Detect the playing video by the motion vectors inside the video and scanning for edge pixels typically forming the border of a playing video. +

+
+ +
+
limit
+

Set higher black value threshold, which can be optionally specified +from nothing (0) to everything (255 for 8-bit based formats). An intensity +value greater to the set value is considered non-black. It defaults to 24. +You can also specify a value between 0.0 and 1.0 which will be scaled depending +on the bitdepth of the pixel format. +

+
+
round
+

The value which the width/height should be divisible by. It defaults to +16. The 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. +

+
+
skip
+

Set the number of initial frames for which evaluation is skipped. +Default is 2. Range is 0 to INT_MAX. +

+
+
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. +

+

This can be useful when channel logos distort the video area. 0 +indicates ’never reset’, and returns the largest area encountered during +playback. +

+
+
mv_threshold
+

Set motion in pixel units as threshold for motion detection. It defaults to 8. +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 5/255, and default value for high +is 15/255. +

+
+ + +

11.48.1 Examples

+ +
    +
  • Find video area surrounded by black borders: +
    +
    ffmpeg -i file.mp4 -vf cropdetect,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, generate motion vectors beforehand: +
    +
    ffmpeg -i file.mp4 -vf mestimate,cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, use motion vectors from decoder: +
    +
    ffmpeg -flags2 +export_mvs -i file.mp4 -vf cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    +
+ + +

11.48.2 Commands

+ +

This filter supports the following commands: +

+
+
limit
+

The command accepts the same syntax of the corresponding option. +If the specified expression is not valid, it is kept at its current value. +

+
+ + +

11.49 cue

+ +

Delay video filtering until a given wallclock timestamp. The filter first +passes on preroll amount of frames, then it buffers at most +buffer amount of frames and waits for the cue. After reaching the cue +it forwards the buffered frames and also any subsequent frames coming in its +input. +

+

The filter can be used synchronize the output of multiple ffmpeg processes for +realtime output devices like decklink. By putting the delay in the filtering +chain and pre-buffering frames the process can pass on data to output almost +immediately after the target wallclock timestamp is reached. +

+

Perfect frame accuracy cannot be guaranteed, but the result is good enough for +some use cases. +

+
+
cue
+

The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. +

+
+
preroll
+

The duration of content to pass on as preroll expressed in seconds. Default is 0. +

+
+
buffer
+

The maximum duration of content to buffer before waiting for the cue expressed +in seconds. Default is 0. +

+
+
+ + +

11.50 curves

+ +

Apply color adjustments using curves. +

+

This filter is similar to the Adobe Photoshop and GIMP curves tools. Each +component (red, green and blue) has its values defined by N key points +tied from each other using a smooth curve. The x-axis represents the pixel +values from the input frame, and the y-axis the new pixel values to be set for +the output frame. +

+

By default, a component curve is defined by the two points (0;0) and +(1;1). This creates a straight line where each original pixel value is +"adjusted" to its own value, which means no change to the image. +

+

The filter allows you to redefine these two points and add some more. A new +curve will be defined to pass smoothly through all these new coordinates. The +new defined points need to be strictly increasing over the x-axis, and their +x and y values must be in the [0;1] interval. The curve is +formed by using a natural or monotonic cubic spline interpolation, depending +on the interp option (default: natural). The natural +spline produces a smoother curve in general while the monotonic (pchip) +spline guarantees the transitions between the specified points to be +monotonic. If the computed curves happened to go outside the vector spaces, +the values will be clipped accordingly. +

+

The filter accepts the following options: +

+
+
preset
+

Select one of the available color presets. This option can be used in addition +to the r, g, b parameters; in this case, the later +options takes priority on the preset values. +Available presets are: +

+
‘none’
+
‘color_negative’
+
‘cross_process’
+
‘darker’
+
‘increase_contrast’
+
‘lighter’
+
‘linear_contrast’
+
‘medium_contrast’
+
‘negative’
+
‘strong_contrast’
+
‘vintage’
+
+

Default is none. +

+
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 +r, g, b or all since it acts like a +post-processing LUT. +

+
red, r
+

Set the key points for the red component. +

+
green, g
+

Set the key points for the green component. +

+
blue, b
+

Set the key points for the blue component. +

+
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 +all setting. +

+
psfile
+

Specify a Photoshop curves file (.acv) to import the settings from. +

+
plot
+

Save Gnuplot script of the curves in specified file. +

+
interp
+

Specify the kind of interpolation. Available algorithms are: +

+
‘natural’
+

Natural cubic spline using a piece-wise cubic polynomial that is twice continuously differentiable. +

+
‘pchip’
+

Monotonic cubic spline using a piecewise cubic Hermite interpolating polynomial (PCHIP). +

+
+ +
+
+ +

To avoid some filtergraph syntax conflicts, each key points list need to be +defined using the following syntax: x0/y0 x1/y1 x2/y2 .... +

+ +

11.50.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.50.2 Examples

+ +
    +
  • Increase slightly the middle level of blue: +
    +
    curves=blue='0/0 0.5/0.58 1/1'
    +
    + +
  • Vintage effect: +
    +
    curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'
    +
    +

    Here we obtain the following coordinates for each components: +

    +
    red
    +

    (0;0.11) (0.42;0.51) (1;0.95) +

    +
    green
    +

    (0;0) (0.50;0.48) (1;1) +

    +
    blue
    +

    (0;0.22) (0.49;0.44) (1;0.80) +

    +
    + +
  • The previous example can also be achieved with the associated built-in preset: +
    +
    curves=preset=vintage
    +
    + +
  • Or simply: +
    +
    curves=vintage
    +
    + +
  • Use a Photoshop preset and redefine the points of the green component: +
    +
    curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
    +
    + +
  • Check out the curves of the cross_process profile using ffmpeg +and gnuplot: +
    +
    ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
    +gnuplot -p /tmp/curves.plt
    +
    +
+ + +

11.51 datascope

+ +

Video data analysis filter. +

+

This filter shows hexadecimal pixel values of part of video. +

+

The filter accepts the following options: +

+
+
size, s
+

Set output video size. +

+
+
x
+

Set x offset from where to pick pixels. +

+
+
y
+

Set y offset from where to pick pixels. +

+
+
mode
+

Set scope mode, can be one of the following: +

+
‘mono’
+

Draw hexadecimal pixel values with white color on black background. +

+
+
‘color’
+

Draw hexadecimal pixel values with input video pixel color on black +background. +

+
+
‘color2’
+

Draw hexadecimal pixel values on color background picked from input video, +the text color is picked in such way so its always visible. +

+
+ +
+
axis
+

Draw rows and columns numbers on left and top of video. +

+
+
opacity
+

Set background opacity. +

+
+
format
+

Set display number format. Can be hex, or dec. Default is hex. +

+
+
components
+

Set pixel components to display. By default all pixel components are displayed. +

+
+ + +

11.51.1 Commands

+ +

This filter supports same commands as options excluding size option. +

+ +

11.52 dblur

+

Apply Directional blur filter. +

+

The filter accepts the following options: +

+
+
angle
+

Set angle of directional blur. Default is 45. +

+
+
radius
+

Set radius of directional blur. Default is 5. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+ + +

11.52.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.53 dctdnoiz

+ +

Denoise frames using 2D DCT (frequency domain filtering). +

+

This filter is not designed for real time. +

+

The filter accepts the following options: +

+
+
sigma, s
+

Set the noise sigma constant. +

+

This sigma defines a hard threshold of 3 * sigma; every DCT +coefficient (absolute value) below this threshold with be dropped. +

+

If you need a more advanced filtering, see expr. +

+

Default is 0. +

+
+
overlap
+

Set number overlapping pixels for each block. 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 permit processing the whole input width or +height, a warning will be displayed and according borders won’t be denoised. +

+

Default value is blocksize-1, which is the best possible setting. +

+
+
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 sigma option will be ignored. +

+

The absolute value of the coefficient can be accessed through the c +variable. +

+
+
n
+

Set the blocksize using the number of bits. 1<<n defines the +blocksize, which is the width and height of the processed blocks. +

+

The default value is 3 (8x8) and can be raised to 4 for a +blocksize of 16x16. Note that changing this setting has huge consequences +on the speed processing. Also, a larger block size does not necessarily means a +better de-noising. +

+
+ + +

11.53.1 Examples

+ +

Apply a denoise with a sigma of 4.5: +

+
dctdnoiz=4.5
+
+ +

The same operation can be achieved using the expression system: +

+
dctdnoiz=e='gte(c, 4.5*3)'
+
+ +

Violent denoise using a block size of 16x16: +

+
dctdnoiz=15:n=4
+
+ + +

11.54 deband

+ +

Remove banding artifacts from input video. +It works by replacing banded pixels with average value of referenced pixels. +

+

The filter accepts the following options: +

+
+
1thr
+
2thr
+
3thr
+
4thr
+

Set banding detection threshold for each plane. Default is 0.02. +Valid range is 0.00003 to 0.5. +If difference between current pixel and reference pixel is less than threshold, +it will be considered as banded. +

+
+
range, r
+

Banding detection range in pixels. Default is 16. If positive, random number +in range 0 to set value will be used. If negative, exact absolute value +will be used. +The range defines square of four pixels around current pixel. +

+
+
direction, d
+

Set direction in radians from which four pixel will be compared. If positive, +random direction from 0 to set direction will be picked. If negative, exact of +absolute value will be picked. For example direction 0, -PI or -2*PI radians +will pick only pixels on same row and -PI/2 will pick only pixels on same +column. +

+
+
blur, b
+

If enabled, current pixel is compared with average value of all four +surrounding pixels. The default is enabled. If disabled current pixel is +compared with all four surrounding pixels. The pixel is considered banded +if only all four differences with surrounding pixels are less than threshold. +

+
+
coupling, c
+

If enabled, current pixel is changed if and only if all pixel components are banded, +e.g. banding detection threshold is triggered for all color components. +The default is disabled. +

+
+ + +

11.54.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.55 deblock

+ +

Remove blocking artifacts from input video. +

+

The filter accepts the following options: +

+
+
filter
+

Set filter type, can be weak or strong. Default is strong. +This controls what kind of deblocking is applied. +

+
+
block
+

Set size of block, allowed range is from 4 to 512. Default is 8. +

+
+
alpha
+
beta
+
gamma
+
delta
+

Set blocking detection thresholds. Allowed range is 0 to 1. +Defaults are: 0.098 for alpha and 0.05 for the rest. +Using higher threshold gives more deblocking strength. +Setting alpha controls threshold detection at exact edge of block. +Remaining options controls threshold detection near the edge. Each one for +below/above or left/right. Setting any of those to 0 disables +deblocking. +

+
+
planes
+

Set planes to filter. Default is to filter all available planes. +

+
+ + +

11.55.1 Examples

+ +
    +
  • Deblock using weak filter and block size of 4 pixels. +
    +
    deblock=filter=weak:block=4
    +
    + +
  • Deblock using strong filter, block size of 4 pixels and custom thresholds for +deblocking more edges. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
    +
    + +
  • Similar as above, but filter only first plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
    +
    + +
  • Similar as above, but filter only second and third plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
    +
    +
+ + +

11.55.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.56 decimate

+ +

Drop duplicated frames at regular intervals. +

+

The filter accepts the following options: +

+
+
cycle
+

Set the number of frames from which one will be dropped. Setting this to +N means one frame in every batch of N frames will be dropped. +Default is 5. +

+
+
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 1.1 +

+
+
scthresh
+

Set scene change threshold. Default is 15. +

+
+
blockx
+
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 32. +

+
+
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 +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 +0. +

+
+
chroma
+

Set whether or not chroma is considered in the metric calculations. Default is +1. +

+
+
mixed
+

Set whether or not the input only partially contains content to be decimated. +Default is false. +If enabled video output stream will be in variable frame rate. +

+
+ + +

11.57 deconvolve

+ +

Apply 2D deconvolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+
noise
+

Set noise when doing divisions. Default is 0.0000001. Useful when width +and height are not same and not power of 2 or if stream prior to convolving +had noise. +

+
+ +

The deconvolve filter also supports the framesync options. +

+ +

11.58 dedot

+ +

Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video. +

+

It accepts the following options: +

+
+
m
+

Set mode of operation. Can be combination of dotcrawl for cross-luminance reduction and/or +rainbows for cross-color reduction. +

+
+
lt
+

Set spatial luma threshold. Lower values increases reduction of cross-luminance. +

+
+
tl
+

Set tolerance for temporal luma. Higher values increases reduction of cross-luminance. +

+
+
tc
+

Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color. +

+
+
ct
+

Set temporal chroma threshold. Lower values increases reduction of cross-color. +

+
+ + +

11.59 deflate

+ +

Apply deflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values lower than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

11.59.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.60 deflicker

+ +

Remove temporal frame luminance variations. +

+

It accepts the following options: +

+
+
size, s
+

Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. +

+
+
mode, m
+

Set averaging mode to smooth temporal luminance variations. +

+

Available values are: +

+
‘am’
+

Arithmetic mean +

+
+
‘gm’
+

Geometric mean +

+
+
‘hm’
+

Harmonic mean +

+
+
‘qm’
+

Quadratic mean +

+
+
‘cm’
+

Cubic mean +

+
+
‘pm’
+

Power mean +

+
+
‘median’
+

Median +

+
+ +
+
bypass
+

Do not actually modify frame. Useful when one only wants metadata. +

+
+ + +

11.61 deinterlace_d3d12

+ +

Deinterlace the input video using D3D12 hardware-accelerated video processing. +

+

This filter uses the DirectX 12 Video Processor to perform deinterlacing on +GPU, supporting both simple bob and driver-defined advanced (motion-adaptive) +algorithms. It requires the input to be in d3d12 hardware pixel format. +

+

The filter automatically queries the hardware for the required number of +temporal reference frames (if needed) and manages a frame queue to supply them. +

+

It accepts the following options: +

+
+
method
+

The deinterlacing method. It accepts one of the following values: +

+
+
‘default’
+

Select the best deinterlacing method available on the hardware. +If the driver supports custom, that method is used; otherwise +falls back to bob. This is the default. +

+
+
‘bob’
+

Bob deinterlacing. Each field is independently scaled to full +frame height. Simple and fast, but may produce visible bob artifacts +on moving content. +

+
+
‘custom’
+

Driver-defined advanced deinterlacing. The exact algorithm is +hardware-specific and typically employs motion-adaptive techniques +with temporal reference frames for higher quality. +

+
+ +

The default value is default. +

+
+
mode
+

Specify the interlacing mode. It accepts one of the following values: +

+
+
‘frame’
+

Send one frame for each frame. The output frame rate equals the input +frame rate. This is the default. +

+
+
‘field’
+

Send one frame for each field. The output frame rate is double the +input frame rate. +

+
+ +

The default value is frame. +

+
+
deint
+

Specify which frames to deinterlace. It accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames. This is the default. +

+
+
‘interlaced’
+

Only deinterlace frames marked as interlaced; progressive frames are +passed through unchanged. +

+
+ +

The default value is all. +

+
+ + +

11.61.1 Examples

+ +
    +
  • Deinterlace an interlaced video using software decoding and the best +available hardware deinterlacing method: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=method=default,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
  • Deinterlace at field rate (double the frame rate) using bob method with +hardware decoding (full d3d12 pipeline): +
    +
    ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.ts \
    +       -vf "deinterlace_d3d12=method=bob:mode=field" \
    +       -c:v h264_d3d12va output.mp4
    +
    + +
  • Deinterlace only interlaced frames, passing progressive frames through: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=deint=interlaced,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
+ + +

11.62 dejudder

+ +

Remove judder produced by partially interlaced telecined content. +

+

Judder can be introduced, for instance, by pullup filter. If the original +source was partially telecined content then the output of pullup,dejudder +will have a variable frame rate. May change the recorded frame rate of the +container. Aside from that change, this filter will not affect constant frame +rate video. +

+

The option available in this filter is: +

+
cycle
+

Specify the length of the window over which the judder repeats. +

+

Accepts any integer greater than 1. Useful values are: +

+
‘4’
+

If the original was telecined from 24 to 30 fps (Film to NTSC). +

+
+
‘5’
+

If the original was telecined from 25 to 30 fps (PAL to NTSC). +

+
+
‘20’
+

If a mixture of the two. +

+
+ +

The default is ‘4’. +

+
+ + +

11.63 delogo

+ +

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). +

+

It accepts the following parameters: +

+
x
+
y
+

Specify the top left corner coordinates of the logo. They must be +specified. +

+
+
w
+
h
+

Specify the width and height of the logo to clear. They must be +specified. +

+
+
show
+

When set to 1, a green rectangle is drawn on the screen to simplify +finding the right x, y, w, and 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. +

+
+
+ + +

11.63.1 Examples

+ +
    +
  • Set a rectangle covering the area with top left corner coordinates 0,0 +and size 100x77: +
    +
    delogo=x=0:y=0:w=100:h=77
    +
    + +
+ + +

11.64 derain

+ +

Remove the rain in the input image/video by applying the derain methods based on +convolutional neural networks. Supported models: +

+ + +

Training as well as model generation scripts are provided in +the repository at https://github.com/XueweiMeng/derain_filter.git. +

+

The filter accepts the following options: +

+
+
filter_type
+

Specify which filter to use. This option accepts the following values: +

+
+
‘derain’
+

Derain filter. To conduct derain filter, you need to use a derain model. +

+
+
‘dehaze’
+

Dehaze filter. To conduct dehaze filter, you need to use a dehaze model. +

+
+

Default value is ‘derain’. +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow can load files for only its format. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

11.65 deshake

+ +

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 the following options: +

+
+
x
+
y
+
w
+
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 +rectangular area of the frame defined by its top left corner, width +and height. These parameters have the same meaning as the drawbox +filter which can be used to visualise the position of the bounding +box. +

+

This is useful when simultaneous movement of subjects within the frame +might be confused for camera motion by the motion vector search. +

+

If any or all of x, y, w and h are set to -1 +then the full frame is used. This allows later options to be set +without specifying the bounding box for the motion vector search. +

+

Default - search the whole frame. +

+
+
rx
+
ry
+

Specify the maximum extent of movement in x and y directions in the +range 0-64 pixels. Default 16. +

+
+
edge
+

Specify how to generate pixels to fill blanks at the edge of the +frame. Available values are: +

+
‘blank, 0’
+

Fill zeroes at blank locations +

+
‘original, 1’
+

Original image at blank locations +

+
‘clamp, 2’
+

Extruded edge value at blank locations +

+
‘mirror, 3’
+

Mirrored edge at blank locations +

+
+

Default value is ‘mirror’. +

+
+
blocksize
+

Specify the blocksize to use for motion search. Range 4-128 pixels, +default 8. +

+
+
contrast
+

Specify the contrast threshold for blocks. Only blocks with more than +the specified contrast (difference between darkest and lightest +pixels) will be considered. Range 1-255, default 125. +

+
+
search
+

Specify the search strategy. Available values are: +

+
‘exhaustive, 0’
+

Set exhaustive search +

+
‘less, 1’
+

Set less exhaustive search. +

+
+

Default value is ‘exhaustive’. +

+
+
filename
+

If set then a detailed log of the motion search is written to the +specified file. +

+
+
+ + +

11.66 despill

+ +

Remove unwanted contamination of foreground colors, caused by reflected color of +greenscreen or bluescreen. +

+

This filter accepts the following options: +

+
+
type
+

Set what type of despill to use. +

+
+
mix
+

Set how spillmap will be generated. +

+
+
expand
+

Set how much to get rid of still remaining spill. +

+
+
red
+

Controls amount of red in spill area. +

+
+
green
+

Controls amount of green in spill area. +Should be -1 for greenscreen. +

+
+
blue
+

Controls amount of blue in spill area. +Should be -1 for bluescreen. +

+
+
brightness
+

Controls brightness of spill area, preserving colors. +

+
+
alpha
+

Modify alpha from generated spillmap. +

+
+ + +

11.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.67 detelecine

+ +

Apply an exact inverse of the telecine operation. It requires a predefined +pattern specified using the pattern option which must be the same as that passed +to the telecine filter. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+
start_frame
+

A number representing position of the first frame with respect to the telecine +pattern. This is to be used if the stream is cut. The default value is 0. +

+
+ + +

11.68 dilation

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

11.68.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.69 displace

+ +

Displace pixels as indicated by second and third input stream. +

+

It takes three input streams and outputs one stream, the first input is the +source, and second and third input are displacement maps. +

+

The second input specifies how much to displace pixels along the +x-axis, while the third input specifies how much to displace pixels +along the y-axis. +If one of displacement map streams terminates, last frame from that +displacement map will be used. +

+

Note that once generated, displacements maps can be reused over and over again. +

+

A description of the accepted options follows. +

+
+
edge
+

Set displace behavior for pixels that are out of range. +

+

Available values are: +

+
‘blank’
+

Missing pixels are replaced by black pixels. +

+
+
‘smear’
+

Adjacent pixels will spread out to replace missing pixels. +

+
+
‘wrap’
+

Out of range pixels are wrapped so they point to pixels of other side. +

+
+
‘mirror’
+

Out of range pixels will be replaced with mirrored pixels. +

+
+

Default is ‘smear’. +

+
+
+ + +

11.69.1 Examples

+ +
    +
  • Add ripple effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT
    +
    + +
  • Add wave effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT
    +
    +
+ + +

11.70 dnn_classify

+ +

Do classification with deep neural networks based on bounding boxes. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0, +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs for your system. +

+
+
+ + +

11.71 dnn_detect

+ +

Do object detection with deep neural networks. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0 (usually it is ’background’), +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+
+
+ + +

11.72 dnn_processing

+ +

Do image processing with deep neural networks. It works together with another filter +which converts the pixel format of the Frame to what the dnn network requires. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+
‘openvino’
+

OpenVINO backend. To enable this backend you +need to build and install the OpenVINO for C library (see +https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md) and configure FFmpeg with +--enable-libopenvino (–extra-cflags=-I... –extra-ldflags=-L... might +be needed if the header files and libraries are not installed into system path) +

+
+
‘torch’
+

Libtorch backend. To enable this backend you need to build and install Libtroch +for C++ library. Please download cxx11 ABI version (see +https://pytorch.org/get-started/locally) +and configure FFmpeg with --enable-libtorch +--extra-cflags=-I/libtorch_root/libtorch/include +--extra-cflags=-I/libtorch_root/libtorch/include/torch/csrc/api/include +--extra-ldflags=-L/libtorch_root/libtorch/lib/ +

+
+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO +and Libtorch backend can load files for only its format. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +

+
+
+ + +

11.72.1 Examples

+ +
    +
  • Remove rain in rgb24 frame with can.pb (see derain filter): +
    +
    ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
    +
    + +
  • Handle the Y channel with srcnn.pb (see sr filter) for frame with yuv420p (planar YUV formats supported): +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
    +
    + +
  • Handle the Y channel with espcn.pb (see sr filter), which changes frame size, for format yuv420p (planar YUV formats supported), +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y:backend_configs=sess_config=0x10022805320e09cdccccccccccec3f20012a01303801 -y tmp.espcn.jpg
    +
    + +
+ + +

11.73 drawbox

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

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 invert is used, the box edge color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With value 1, the pixels of the painted box +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
box_source
+

Box source can be set as side_data_detection_bboxes if you want to use box data in +detection bboxes of side data. +

+

If box_source is set, the x, y, width and height will be ignored and +still use box data in detection bboxes of side data. So please do not use this parameter if you were +not sure about the box source. +

+
+
t
+

The thickness of the drawn box. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

11.73.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + +

11.73.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.74 drawgraph

+

Draw a graph using input video metadata. +

+

It accepts the following parameters: +

+
+
m1
+

Set 1st frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg1
+

Set 1st foreground color expression. +

+
+
m2
+

Set 2nd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg2
+

Set 2nd foreground color expression. +

+
+
m3
+

Set 3rd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg3
+

Set 3rd foreground color expression. +

+
+
m4
+

Set 4th frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg4
+

Set 4th foreground color expression. +

+
+
min
+

Set minimal value of metadata value. +

+
+
max
+

Set maximal value of metadata value. +

+
+
bg
+

Set graph background color. Default is white. +

+
+
mode
+

Set graph mode. +

+

Available values for mode is: +

+
‘bar’
+
‘dot’
+
‘line’
+
+ +

Default is line. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is frame. +

+
+
size
+

Set size of graph video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +The default value is 900x256. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+

The foreground color expressions can use the following variables: +

+
MIN
+

Minimal value of metadata value. +

+
+
MAX
+

Maximal value of metadata value. +

+
+
VAL
+

Current metadata key value. +

+
+ +

The color is defined as 0xAABBGGRR. +

+
+ +

Example using metadata from signalstats filter: +

+
signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
+
+ +

Example using metadata from ebur128 filter: +

+
ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
+
+ + +

11.75 drawgrid

+ +

Draw a grid on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. +

+
+
width, w
+
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 thickness, so image gets +framed. Default to 0. +

+
+
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 invert is used, the grid color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the grid line. Default value is 1. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With 1 the pixels of the painted grid +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the grid onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input grid cell width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y coordinates of some point of grid intersection (meant to configure offset). +

+
+
w
+
h
+

The width and height of the drawn cell. +

+
+
t
+

The thickness of the drawn cell. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

11.75.1 Examples

+ +
    +
  • Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: +
    +
    drawgrid=width=100:height=100:thickness=2:color=red@0.5
    +
    + +
  • Draw a white 3x3 grid with an opacity of 50%: +
    +
    drawgrid=w=iw/3:h=ih/3:t=2:c=white@0.5
    +
    +
+ + +

11.75.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.76 drawtext

+ +

Draw a text string or text from a specified file on top of a video, using the +libfreetype library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-libfreetype and --enable-libharfbuzz. +To enable default font fallback and the font option you need to +configure FFmpeg with --enable-libfontconfig. +To enable the text_shaping option, you need to configure FFmpeg with +--enable-libfribidi. +

+ +

11.76.1 Syntax

+ +

It accepts the following parameters: +

+
+
box
+

Used to draw a box around text using the background color. +The value must be either 1 (enable) or 0 (disable). +The default value of box is 0. +

+
+
boxborderw
+

Set the width of the border to be drawn around the box using boxcolor. +The value must be specified using one of the following formats: +

    +
  • boxborderw=10 set the width of all the borders to 10 +
  • boxborderw=10|20 set the width of the top and bottom borders to 10 + and the width of the left and right borders to 20 +
  • boxborderw=10|20|30 set the width of the top border to 10, the width + of the bottom border to 30 and the width of the left and right borders to 20 +
  • boxborderw=10|20|30|40 set the borders width to 10 (top), 20 (right), + 30 (bottom), 40 (left) +
+

The default value of boxborderw is "0". +

+
+
boxcolor
+

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. +

+

The default value of boxcolor is "white". +

+
+
line_spacing
+

Set the line spacing in pixels. The default value of line_spacing is 0. +

+
+
text_align
+

Set the vertical and horizontal alignment of the text with respect to the box boundaries. +The value is combination of flags, one for the vertical alignment (T=top, +M=middle, B=bottom) and one for the horizontal alignment (L=left, C=center, R=right). +Please note that tab characters are only supported with the left horizontal alignment. +

+
+
y_align
+

Specify what the y value is referred to. Possible values are: +

    +
  • text the top of the highest glyph of the first text line is placed at y +
  • baseline the baseline of the first text line is placed at y +
  • font the baseline of the first text line is placed at y plus the + ascent (in pixels) defined in the font metrics +
+

The default value of y_align is "text" for backward compatibility. +

+
+
borderw
+

Set the width of the border to be drawn around the text using bordercolor. +The default value of borderw is 0. +

+
+
bordercolor
+

Set the color to be used for drawing border around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. +

+

The default value of bordercolor is "black". +

+
+
expansion
+

Select how the text is expanded. Can be either none, +strftime (deprecated) or normal (default). See the +Text expansion section below for details. +

+
+
basetime
+

Set a start time for the count. Value is in microseconds. Only applied +in the deprecated strftime expansion mode. To emulate in normal expansion +mode use the pts function, supplying the start time (in seconds) +as the second argument. +

+
+
fix_bounds
+

If true, check and fix text coords to avoid clipping. +

+
+
fontcolor
+

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 fontcolor is "black". +

+
+
fontcolor_expr
+

String which is expanded the same way as text to obtain dynamic +fontcolor value. By default this option has empty value and is not +processed. When this option is set, it overrides fontcolor option. +

+
+
font
+

The font family to be used for drawing text. By default Sans. +

+
+
fontfile
+

The font file to be used for drawing text. The path must be included. +This parameter is mandatory if the fontconfig support is disabled. +

+
+
alpha
+

Draw the text applying alpha blending. The value can +be a number between 0.0 and 1.0. +The expression accepts the same variables x, y as well. +The default value is 1. +Please see fontcolor_expr. +

+
+
fontsize
+

The font size to be used for drawing text. +The default value of fontsize is 16. +

+
+
text_shaping
+

If set to 1, attempt to shape the text (for example, reverse the order of +right-to-left text and join Arabic characters) before drawing it. +Otherwise, just draw the text exactly as given. +By default 1 (if supported). +

+
+
ft_load_flags
+

The flags to be used for loading the fonts. +

+

The flags map the corresponding flags supported by libfreetype, and are +a combination of the following values: +

+
default
+
no_scale
+
no_hinting
+
render
+
no_bitmap
+
vertical_layout
+
force_autohint
+
crop_bitmap
+
pedantic
+
ignore_global_advance_width
+
no_recurse
+
ignore_transform
+
monochrome
+
linear_design
+
no_autohint
+
+ +

Default value is "default". +

+

For more information consult the documentation for the FT_LOAD_* +libfreetype flags. +

+
+
shadowcolor
+

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 shadowcolor is "black". +

+
+
boxw
+

Set the width of the box to be drawn around text. +The default value of boxw is computed automatically to match the text width +

+
+
boxh
+

Set the height of the box to be drawn around text. +The default value of boxh is computed automatically to match the text height +

+
+
shadowx
+
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. The default value for both is "0". +

+
+
start_number
+

The starting frame number for the n/frame_num variable. The default value +is "0". +

+
+
tabsize
+

The size in number of spaces to use for rendering the tab. +Default value is 4. +

+
+
timecode
+

Set the initial timecode representation in "hh:mm:ss[:;.]ff" +format. It can be used with or without text parameter. timecode_rate +option must be specified. +

+
+
timecode_rate, rate, r
+

Set the timecode frame rate (timecode only). Value will be rounded to nearest +integer. Minimum value is "1". +Drop-frame timecode is supported for frame rates 30 & 60. +

+
+
tc24hmax
+

If set to 1, the output of the timecode option will wrap around at 24 hours. +Default is 0 (disabled). +

+
+
text
+

The text string to be drawn. The text must be a sequence of UTF-8 +encoded characters. +This parameter is mandatory if no file is specified with the parameter +textfile. +

+
+
textfile
+

A text file containing text to be drawn. The text must be a sequence +of UTF-8 encoded characters. +

+

This parameter is mandatory if no text string is specified with the +parameter text. +

+

If both text and textfile are specified, an error is thrown. +

+
+
text_source
+

Text source should be set as side_data_detection_bboxes if you want to use text data in +detection bboxes of side data. +

+

If text source is set, text and textfile will be ignored and still use +text data in detection bboxes of side data. So please do not use this parameter +if you are not sure about the text source. +

+
+
reload
+

The textfile will be reloaded at specified frame interval. +Be sure to update textfile atomically, or it may be read partially, +or even fail. +Range is 0 to INT_MAX. Default is 0. +

+
+
x
+
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. +

+

The default value of x and y is "0". +

+

See below for the list of accepted constants and functions. +

+
+ +

The parameters for x and y are expressions containing the +following constants and functions: +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
line_h, lh
+

the height of each text line +

+
+
main_h, h, H
+

the input height +

+
+
main_w, w, W
+

the input width +

+
+
max_glyph_a, ascent
+

the maximum distance from the baseline to the highest/upper grid +coordinate used to place a glyph outline point, for all the rendered +glyphs. +It is a positive value, due to the grid’s orientation with the Y axis +upwards. +

+
+
max_glyph_d, descent
+

the maximum distance from the baseline to the lowest grid coordinate +used to place a glyph outline point, for all the rendered glyphs. +This is a negative value, due to the grid’s orientation, with the Y axis +upwards. +

+
+
max_glyph_h
+

maximum glyph height, that is the maximum height for all the glyphs +contained in the rendered text, it is equivalent to ascent - +descent. +

+
+
max_glyph_w
+

maximum glyph width, that is the maximum width for all the glyphs +contained in the rendered text +

+
+
font_a
+

the ascent size defined in the font metrics +

+
+
font_d
+

the descent size defined in the font metrics +

+
+
top_a
+

the maximum ascender of the glyphs of the first text line +

+
+
bottom_d
+

the maximum descender of the glyphs of the last text line +

+
+
n
+

the number of input frame, starting from 0 +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

The input sample aspect ratio. +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
text_h, th
+

the height of the rendered text +

+
+
text_w, tw
+

the width of the rendered text +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer +to each other, so you can for example specify y=x/dar. +

+
+
pict_type
+

A one character description of the current frame’s picture type. +

+
+
pkt_pos
+

The current packet’s position in the input file or stream +(in bytes, from the start of the input). A value of -1 indicates +this info is not available. +

+
+
duration
+

The current packet’s duration, in seconds. +

+
+
pkt_size
+

The current packet’s size (in bytes). +

+
+ + +

11.76.2 Text expansion

+ +

If expansion is set to strftime, the filter recognizes +sequences accepted by the strftime C function in the provided +text and expands them accordingly. Check the documentation of +strftime. This feature is deprecated in favor of normal +expansion with the gmtime or localtime expansion +functions. +

+

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
expr, e
+

The expression evaluation result. +

+

It must take one argument specifying the expression to be evaluated, +which accepts the same constants and functions as the x and +y values. Note that not all constants should be used, for +example the text size is not known when evaluating the expression, so +the constants text_w and text_h will have an undefined +value. +

+
+
expr_int_format, eif
+

Evaluate the expression’s value and output as formatted integer. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries +starting with TAG included within each frame section +printed by running ffprobe -show_frames. +

+

String metadata generated in filters leading to +the drawtext filter are also available. +

+
+
n, frame_num
+

The frame number, starting from 0. +

+
+
pict_type
+

A one character description of the current picture type. +

+
+
pts
+

The timestamp of the current frame. +It can take up to three arguments. +

+

The first argument is the format of the timestamp; it defaults to flt +for seconds as a decimal number with microsecond accuracy; hms stands +for a formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as +local time zone time. +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to hms, a third argument 24HH may be +supplied to present the hour part of the formatted timestamp in 24h format +(00-23). +

+

If the format is set to localtime or gmtime, a third +argument may be supplied: a strftime C function format string. +By default, YYYY-MM-DD HH:MM:SS format will be used. +

+
+ + +

11.76.3 Commands

+ +

This filter supports altering parameters via commands: +

+
reinit
+

Alter existing filter parameters. +

+

Syntax for the argument is the same as for filter invocation, e.g. +

+
+
fontsize=56:fontcolor=green:text='Hello World'
+
+ +

Full filter invocation with sendcmd would look like this: +

+
+
sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
+
+ +

If the entire argument can’t be parsed or applied as valid values then the filter will +continue with its existing parameters. +

+
+
+ +

The following options are also supported as commands: +

+
    +
  • x +
  • y +
  • alpha +
  • fontsize +
  • fontcolor +
  • boxcolor +
  • bordercolor +
  • shadowcolor +
  • box +
  • boxw +
  • boxh +
  • boxborderw +
  • line_spacing +
  • text_align +
  • shadowx +
  • shadowy +
  • borderw +
+ + +

11.76.4 Examples

+ +
    +
  • Draw "Test Text" with font FreeSerif, using the default values for the +optional parameters. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
    +
    + +
  • Draw ’Test Text’ with font FreeSerif of size 24 at position x=100 +and y=50 (counting from the top-left corner of the screen), text is +yellow with a red box around it. Both the text and the box have an +opacity of 20%. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
    +          x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"
    +
    + +

    Note that the double quotes are not necessary if spaces are not used +within the parameter list. +

    +
  • Show the text at the center of the video frame: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
    +
    + +
  • Show the text at a random position, switching to a new position every 30 seconds: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"
    +
    + +
  • Show a text line sliding from right to left in the last row of the video +frame. The file LONG_LINE is assumed to contain a single line +with no newlines. +
    +
    drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
    +
    + +
  • Show the content of file CREDITS off the bottom of the frame and scroll up. +
    +
    drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
    +
    + +
  • Draw a single green letter "g", at the center of the input video. +The glyph baseline is placed at half screen height. +
    +
    drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
    +
    + +
  • Show text for 1 second every 3 seconds: +
    +
    drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
    +
    + +
  • Use fontconfig to set the font. Note that the colons need to be escaped. +
    +
    drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg'
    +
    + +
  • Draw "Test Text" with font size dependent on height of the video. +
    +
    drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
    +
    + +
  • Print the date of a real-time encoding (see documentation for the +strftime C function): +
    +
    drawtext='fontfile=FreeSans.ttf:text=%{localtime\:%a %b %d %Y}'
    +
    + +
  • Show text fading in and out (appearing/disappearing): +
    +
    #!/bin/sh
    +DS=1.0 # display start
    +DE=10.0 # display end
    +FID=1.5 # fade in duration
    +FOD=5 # fade out duration
    +ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 }"
    +
    + +
  • Horizontally align multiple separate texts. Note that max_glyph_a +and the fontsize value are included in the y offset. +
    +
    drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
    +drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
    +
    + +
  • Plot special lavf.image2dec.source_basename metadata onto each frame if +such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer +must have option -export_path_metadata 1 for the special metadata fields +to be available for filters. +
    +
    drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%{metadata\:lavf.image2dec.source_basename\:NA}':x=10:y=10"
    +
    + +
+ +

For more information about libfreetype, check: +http://www.freetype.org/. +

+

For more information about fontconfig, check: +http://freedesktop.org/software/fontconfig/fontconfig-user.html. +

+

For more information about libfribidi, check: +http://fribidi.org/. +

+

For more information about libharfbuzz, check: +https://github.com/harfbuzz/harfbuzz. +

+ +

11.77 drawvg

+ +

Draw vector graphics on top of video frames, by executing a script written in +a custom language called VGS (Vector Graphics Script). +

+

The documentation for the language can be found in +drawvg - Language Reference. A version of this reference +with rendered examples can be found at the +author’s site. +

+

Graphics are rendered using the cario 2D +graphics library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-cairo. +

+ +

11.77.1 Parameters

+ +

Either script or file must be set. +

+
+
s, script
+

Script source to draw the graphics. +

+
+
file
+

Path of the file to load the script source. +

+
+
+ + +

11.77.2 Pixel Formats

+ +

Since Cairo only supports RGB images, if the input video is something else (like +YUV 4:2:0), before executing the script the video is converted to a format +compatible with Cairo. Then, you have to use either the format filter, +or the -pix_fmt option, to convert it to the expected format in the +output. +

+ +

11.77.3 Examples

+ +
    +
  • Draw the outline of an ellipse. + +
    +
    ffmpeg -i input.webm \
    +    -vf 'drawvg=ellipse (w/2) (h/2) (w/3) (h/3) stroke' \
    +    -pix_fmt yuv420p \
    +    output.webm
    +
    + +
  • +Draw a square rotating in the middle of the frame. + +

    The script for drawvg is in a file draw.vgs: +

    +
    +
    translate (w/2) (h/2)
    +rotate t
    +rect -100 -100 200 200
    +setcolor red@0.5
    +fill
    +
    + +

    Then: +

    +
    +
    ffmpeg -i input.webm -vf 'drawvg=file=draw.vgs,format=yuv420p' output.webm
    +
    + +
+ + +

11.78 edgedetect

+ +

Detect and draw edges. The filter uses the Canny Edge Detection algorithm. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
mode
+

Define the drawing mode. +

+
+
‘wires’
+

Draw white/gray wires on black background. +

+
+
‘colormix’
+

Mix the colors to create a paint/cartoon effect. +

+
+
‘canny’
+

Apply Canny edge detector on all selected planes. +

+
+

Default value is wires. +

+
+
planes
+

Select planes for filtering. By default all available planes are filtered. +

+
+ + +

11.78.1 Examples

+ +
    +
  • Standard edge detection with custom values for the hysteresis thresholding: +
    +
    edgedetect=low=0.1:high=0.4
    +
    + +
  • Painting effect without thresholding: +
    +
    edgedetect=mode=colormix:high=0
    +
    +
+ + +

11.79 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. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
pal8
+

Set pal8 output pixel format. This option does not work with codebook +length greater than 256. Default is disabled. +

+
+
use_alpha
+

Include alpha values in the quantization calculation. Allows creating +palettized output images (e.g. PNG8) with multiple alpha smooth blending. +

+
+ + +

11.80 entropy

+ +

Measure graylevel entropy in histogram of color channels of video frames. +

+

It accepts the following parameters: +

+
+
mode
+

Can be either normal or diff. Default is normal. +

+

diff mode measures entropy of histogram delta values, absolute differences +between neighbour histogram values. +

+
+ + +

11.81 epx

+

Apply the EPX magnification filter which is designed for pixel art. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xEPX, 3 for +3xEPX. +Default is 3. +

+
+ + +

11.82 eq

+

Set brightness, contrast, saturation and approximate gamma adjustment. +

+

The filter accepts the following options: +

+
+
contrast
+

Set the contrast expression. The value must be a float value in range +-1000.0 to 1000.0. The default value is "1". +

+
+
brightness
+

Set the brightness expression. The value must be a float value in +range -1.0 to 1.0. The default value is "0". +

+
+
saturation
+

Set the saturation expression. The value must be a float in +range 0.0 to 3.0. The default value is "1". +

+
+
gamma
+

Set the gamma expression. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_r
+

Set the gamma expression for red. The value must be a float in +range 0.1 to 10.0. The default value is "1". +

+
+
gamma_g
+

Set the gamma expression for green. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_b
+

Set the gamma expression for blue. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_weight
+

Set the gamma weight expression. It can be used to reduce the effect +of a high gamma value on bright image areas, e.g. keep them from +getting overamplified and just plain white. The value must be a float +in range 0.0 to 1.0. A value of 0.0 turns the +gamma correction all the way down while 1.0 leaves it at its +full strength. Default is "1". +

+
+
eval
+

Set when the expressions for brightness, contrast, saturation and +gamma expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ +

The expressions accept the following parameters: +

+
n
+

frame count of the input frame starting from 0 +

+
+
pos
+

byte position of the corresponding packet in the input file, NAN if +unspecified; deprecated, do not use +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+ + +

11.82.1 Commands

+

The filter supports the following commands: +

+
+
contrast
+

Set the contrast expression. +

+
+
brightness
+

Set the brightness expression. +

+
+
saturation
+

Set the saturation expression. +

+
+
gamma
+

Set the gamma expression. +

+
+
gamma_r
+

Set the gamma_r expression. +

+
+
gamma_g
+

Set gamma_g expression. +

+
+
gamma_b
+

Set gamma_b expression. +

+
+
gamma_weight
+

Set gamma_weight 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. +

+
+
+ + +

11.83 erosion

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

11.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.84 estdif

+ +

Deinterlace the input video ("estdif" stands for "Edge Slope +Tracing Deinterlacing Filter"). +

+

Spatial only filter that uses edge slope tracing algorithm +to interpolate missing lines. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
all
+

Deinterlace all frames. +

+
interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+
rslope
+

Specify the search radius for edge slope tracing. Default value is 1. +Allowed range is from 1 to 15. +

+
+
redge
+

Specify the search radius for best edge matching. Default value is 2. +Allowed range is from 0 to 15. +

+
+
ecost
+

Specify the edge cost for edge matching. Default value is 2. +Allowed range is from 0 to 50. +

+
+
mcost
+

Specify the middle cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
dcost
+

Specify the distance cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
interp
+

Specify the interpolation used. Default is 4-point interpolation. It accepts one +of the following values: +

+
+
2p
+

Two-point interpolation. +

+
4p
+

Four-point interpolation. +

+
6p
+

Six-point interpolation. +

+
+
+
+ + +

11.84.1 Commands

+

This filter supports same commands as options. +

+ +

11.85 exposure

+

Adjust exposure of the video stream. +

+

The filter accepts the following options: +

+
+
exposure
+

Set the exposure correction in EV. Allowed range is from -3.0 to 3.0 EV +Default value is 0 EV. +

+
+
black
+

Set the black level correction. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+ + +

11.85.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.86 extractplanes

+ +

Extract color channel components from input video stream into +separate grayscale video streams. +

+

The filter accepts the following option: +

+
+
planes
+

Set plane(s) to extract. +

+

Available values for planes are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +

Choosing planes not available in the input will result in an error. +That means you cannot select r, g, b planes +with y, u, v planes at same time. +

+
+ + +

11.86.1 Examples

+ +
    +
  • Extract luma, u and v color channel component from input video frame +into 3 grayscale outputs: +
    +
    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
    +
    +
+ + +

11.87 fade

+ +

Apply a fade-in/out effect to the input video. +

+

It accepts the following parameters: +

+
+
type, t
+

The effect type can be either "in" for a fade-in, or "out" for a fade-out +effect. +Default is in. +

+
+
start_frame, s
+

Specify the number of the frame to start applying the fade +effect at. Default is 0. +

+
+
nb_frames, n
+

The number of frames that the fade effect lasts. 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 color. +Default is 25. +

+
+
alpha
+

If set to 1, fade only alpha channel, if one exists on the input. +Default value is 0. +

+
+
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. +

+
+
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 color. +If both duration and nb_frames are specified, duration is used. Default is 0 +(nb_frames is used by default). +

+
+
color, c
+

Specify the color of the fade. Default is "black". +

+
+ + +

11.87.1 Examples

+ +
    +
  • Fade in the first 30 frames of video: +
    +
    fade=in:0:30
    +
    + +

    The command above is equivalent to: +

    +
    fade=t=in:s=0:n=30
    +
    + +
  • Fade out the last 45 frames of a 200-frame video: +
    +
    fade=out:155:45
    +fade=type=out:start_frame=155:nb_frames=45
    +
    + +
  • Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: +
    +
    fade=in:0:25, fade=out:975:25
    +
    + +
  • Make the first 5 frames yellow, then fade in from frame 5-24: +
    +
    fade=in:5:20:color=yellow
    +
    + +
  • Fade in alpha over first 25 frames of video: +
    +
    fade=in:0:25:alpha=1
    +
    + +
  • Make the first 5.5 seconds black, then fade in for 0.5 seconds: +
    +
    fade=t=in:st=5.5:d=0.5
    +
    + +
+ + +

11.88 feedback

+

Apply feedback video filter. +

+

This filter pass cropped input frames to 2nd output. +From there it can be filtered with other video filters. +After filter receives frame from 2nd input, that frame +is combined on top of original frame from 1st input and passed +to 1st output. +

+

The typical usage is filter only part of frame. +

+

The filter accepts the following options: +

+
x
+
y
+

Set the top left crop position. +

+
+
w
+
h
+

Set the crop size. +

+
+ + +

11.88.1 Examples

+ +
    +
  • Blur only top left rectangular part of video frame size 100x100 with gblur filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]gblur=8[blurin]
    +
    + +
  • Draw black box on top left part of video frame of size 100x100 with drawbox filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]drawbox=x=0:y=0:w=100:h=100:t=100[blurin]
    +
    + +
  • Pixelize rectangular part of video frame of size 100x100 with pixelize filter. +
    +
    [in][blurin]feedback=x=320:y=240:w=100:h=100[out][blurout];[blurout]pixelize[blurin]
    +
    +
+ + +

11.89 fftdnoiz

+

Denoise frames using 3D FFT (frequency domain filtering). +

+

The filter accepts the following options: +

+
+
sigma
+

Set the noise sigma constant. This sets denoising strength. +Default value is 1. Allowed range is from 0 to 30. +Using very high sigma with low overlap may give blocking artifacts. +

+
+
amount
+

Set amount of denoising. By default all detected noise is reduced. +Default value is 1. Allowed range is from 0 to 1. +

+
+
block
+

Set size of block in pixels, Default is 32, can be 8 to 256. +

+
+
overlap
+

Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. +

+
+
method
+

Set denoising method. Default is wiener, can also be hard. +

+
+
prev
+

Set number of previous frames to use for denoising. By default is set to 0. +

+
+
next
+

Set number of next frames to to use for denoising. By default is set to 0. +

+
+
planes
+

Set planes which will be filtered, by default are all available filtered +except alpha. +

+
+ + +

11.90 fftfilt

+

Apply arbitrary expressions to samples in frequency domain +

+
+
dc_Y
+

Adjust the dc value (gain) of the luma plane of the image. The filter +accepts an integer value in range 0 to 1000. The default +value is set to 0. +

+
+
dc_U
+

Adjust the dc value (gain) of the 1st chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
dc_V
+

Adjust the dc value (gain) of the 2nd chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
weight_Y
+

Set the frequency domain weight expression for the luma plane. +

+
+
weight_U
+

Set the frequency domain weight expression for the 1st chroma plane. +

+
+
weight_V
+

Set the frequency domain weight expression for the 2nd chroma plane. +

+
+
eval
+

Set when the expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

Only evaluate expressions once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+ +

Default value is ‘init’. +

+

The filter accepts the following variables: +

+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
N
+

The number of input frame, starting from 0. +

+
+
WS
+
HS
+

The size of FFT array for horizontal and vertical processing. +

+
+ + +

11.90.1 Examples

+ +
    +
  • High-pass: +
    +
    fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
    +
    + +
  • Low-pass: +
    +
    fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
    +
    + +
  • Sharpen: +
    +
    fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
    +
    + +
  • Blur: +
    +
    fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
    +
    + +
+ + +

11.91 field

+ +

Extract a single field from an interlaced image using stride +arithmetic to avoid wasting CPU time. The output frames are marked as +non-interlaced. +

+

The filter accepts the following options: +

+
+
type
+

Specify whether to extract the top (if the value is 0 or +top) or the bottom field (if the value is 1 or +bottom). +

+
+ + +

11.92 fieldhint

+ +

Create new frames by copying the top and bottom fields from surrounding frames +supplied as numbers by the hint file. +

+
+
hint
+

Set file containing hints: absolute/relative frame numbers. +

+

There must be one line for each frame in a clip. Each line must contain two +numbers separated by the comma, optionally followed by - or +. +Numbers supplied on each line of file can not be out of [N-1,N+1] where N +is current frame number for absolute mode or out of [-1, 1] range +for relative mode. First number tells from which frame to pick up top +field and second number tells from which frame to pick up bottom field. +

+

If optionally followed by + output frame will be marked as interlaced, +else if followed by - output frame will be marked as progressive, else +it will be marked same as input frame. +If optionally followed by t output frame will use only top field, or in +case of b it will use only bottom field. +If line starts with # or ; that line is skipped. +

+
+
mode
+

Can be item absolute or relative or pattern. Default is absolute. +The pattern mode is same as relative mode, except at last entry of file if there +are more frames to process than hint file is seek back to start. +

+
+ +

Example of first several lines of hint file for relative mode: +

+
0,0 - # first frame
+1,0 - # second frame, use third's frame top field and second's frame bottom field
+1,0 - # third frame, use fourth's frame top field and third's frame bottom field
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+
+ + +

11.93 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 fieldmatch needs to be +followed by a decimation filter such as 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, +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 yadif before decimation. +

+

In addition to the various configuration options, fieldmatch can take an +optional second stream, activated through the 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 fieldmatch is based on. While the semantic and usage are very +close, some behaviour and options names can differ. +

+

The decimate filter currently only works for constant frame rate input. +If your input has mixed telecined (30fps) and progressive content with a lower +framerate like 24fps use the following filterchain to produce the necessary cfr +stream: dejudder,fps=30000/1001,fieldmatch,decimate. +

+

The filter accepts the following options: +

+
+
order
+

Specify the assumed field order of the input stream. Available values are: +

+
+
‘auto’
+

Auto detect parity (use FFmpeg’s internal parity value). +

+
‘bff’
+

Assume bottom field first. +

+
‘tff’
+

Assume top field first. +

+
+ +

Note that it is sometimes recommended not to trust the parity announced by the +stream. +

+

Default value is auto. +

+
+
mode
+

Set the matching mode or strategy to use. 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, 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 pc and 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 p/c/n/u/b meaning section. +

+

Available values are: +

+
+
‘pc’
+

2-way matching (p/c) +

+
‘pc_n’
+

2-way matching, and trying 3rd match if still combed (p/c + n) +

+
‘pc_u’
+

2-way matching, and trying 3rd match (same order) if still combed (p/c + u) +

+
‘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) +

+
‘pcn’
+

3-way matching (p/c/n) +

+
‘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) +

+
+ +

The parenthesis at the end indicate the matches that would be used for that +mode assuming order=tff (and field on auto or +top). +

+

In terms of speed pc mode is by far the fastest and pcn_ub is +the slowest. +

+

Default value is pc_n. +

+
+
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 clip2 feature from +VFM/TFM. +

+

Default value is 0 (disabled). +

+
+
field
+

Set the field to match from. It is recommended to set this to the same value as +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: +

+
+
‘auto’
+

Automatic (same value as order). +

+
‘bottom’
+

Match from the bottom field. +

+
‘top’
+

Match from the top field. +

+
+ +

Default value is auto. +

+
+
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 0 +only if your clip has bad chroma problems such as heavy rainbowing or other +artifacts. Setting this to 0 could also be used to speed things up at +the cost of some accuracy. +

+

Default value is 1. +

+
+
y0
+
y1
+

These define an exclusion band which excludes the lines between y0 and +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. y0 sets the starting scan line and +y1 sets the ending line; all lines in between y0 and +y1 (including y0 and y1) will be ignored. Setting +y0 and y1 to the same value will disable the feature. +y0 and y1 defaults to 0. +

+
+
scthresh
+

Set the scene change detection threshold as a percentage of maximum change on +the luma plane. Good values are in the [8.0, 14.0] range. Scene change +detection is only relevant in case combmatch=sc. The range for +scthresh is [0.0, 100.0]. +

+

Default value is 12.0. +

+
+
combmatch
+

When combatch is not none, fieldmatch will take into +account the combed scores of matches when deciding what match to use as the +final match. Available values are: +

+
+
‘none’
+

No final matching based on combed scores. +

+
‘sc’
+

Combed scores are only used when a scene change is detected. +

+
‘full’
+

Use combed scores all the time. +

+
+ +

Default is sc. +

+
+
combdbg
+

Force fieldmatch to calculate the combed metrics for certain matches and +print them. This setting is known as micout in TFM/VFM vocabulary. +Available values are: +

+
+
‘none’
+

No forced calculation. +

+
‘pcn’
+

Force p/c/n calculations. +

+
‘pcnub’
+

Force p/c/n/u/b calculations. +

+
+ +

Default value is none. +

+
+
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 +-1 (every pixel will be detected as combed) to 255 (no pixel will +be detected as combed). This is basically a pixel difference value. A good +range is [8, 12]. +

+

Default value is 9. +

+
+
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 chroma=0 is usually more reliable, except for the case +where there is chroma only combing in the source. +

+

Default value is 0. +

+
+
blockx
+
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 +combpel pixels are required to be detected as combed for a frame to be +declared combed. See the 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 16. +

+
+
combpel
+

The number of combed pixels inside any of the blocky by +blockx size blocks on the frame for the frame to be detected as +combed. While 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 blockx and blocky settings) on the +frame. Minimum value is 0 and maximum is blocky x blockx (at +which point no frames will ever be detected as combed). This setting is known +as MI in TFM/VFM vocabulary. +

+

Default value is 80. +

+
+ + +

11.93.1 p/c/n/u/b meaning

+ + +

11.93.1.1 p/c/n

+ +

We assume the following telecined stream: +

+
+
Top fields:     1 2 2 3 4
+Bottom fields:  1 2 3 4 4
+
+ +

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 fieldmatch is configured to run a matching from bottom +(field=bottom) this is how this input stream get transformed: +

+
+
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
+
+ +

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 decimate filter. +

+

The same operation now matching from top fields (field=top) +looks like this: +

+
+
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
+
+ +

In these examples, we can see what p, c and n mean; +basically, they refer to the frame and field of the opposite parity: +

+
    +
  • p matches the field of the opposite parity in the previous frame +
  • c matches the field of the opposite parity in the current frame +
  • n matches the field of the opposite parity in the next frame +
+ + +

11.93.1.2 u/b

+ +

The u and 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 (field=bottom): +

+
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
+
+ +

With top matching (field=top): +

+
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
+
+ + +

11.93.2 Examples

+ +

Simple IVTC of a top field first telecined stream: +

+
fieldmatch=order=tff:combmatch=none, decimate
+
+ +

Advanced IVTC, with fallback on yadif for still combed frames: +

+
fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
+
+ + +

11.94 fieldorder

+ +

Transform the field order of the input video. +

+

It accepts the following parameters: +

+
+
order
+

The output field order. Valid values are tff for top field first or bff +for bottom field first. +

+
+ +

The default value is ‘tff’. +

+

The transformation is done by shifting the picture content up or down +by one line, and filling the remaining line with appropriate picture content. +This method is consistent with most broadcast field order converters. +

+

If the input video is not flagged as being interlaced, or it is already +flagged as being of the required output field order, then this filter does +not alter the incoming video. +

+

It is very useful when converting to or from PAL DV material, +which is bottom field first. +

+

For example: +

+
ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
+
+ + +

11.95 fillborders

+ +

Fill borders of the input video, without changing video stream dimensions. +Sometimes video can have garbage at the four edges and you may not want to +crop video input to keep size multiple of some number. +

+

This filter accepts the following options: +

+
+
left
+

Number of pixels to fill from left border. +

+
+
right
+

Number of pixels to fill from right border. +

+
+
top
+

Number of pixels to fill from top border. +

+
+
bottom
+

Number of pixels to fill from bottom border. +

+
+
mode
+

Set fill mode. +

+

It accepts the following values: +

+
‘smear’
+

fill pixels using outermost pixels +

+
+
‘mirror’
+

fill pixels using mirroring (half sample symmetric) +

+
+
‘fixed’
+

fill pixels with constant value +

+
+
‘reflect’
+

fill pixels using reflecting (whole sample symmetric) +

+
+
‘wrap’
+

fill pixels using wrapping +

+
+
‘fade’
+

fade pixels to constant value +

+
+
‘margins’
+

fill pixels at top and bottom with weighted averages pixels near borders +

+
+ +

Default is smear. +

+
+
color
+

Set color for pixels in fixed or fade mode. Default is black. +

+
+ + +

11.95.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.96 find_rect

+ +

Find a rectangular object in the input video. +

+

The object to search for must be specified as a gray8 image specified with the +object option. +

+

For each possible match, a score is computed. If the score reaches the specified +threshold, the object is considered found. +

+

If the input video contains multiple instances of the object, the filter will +find only one of them. +

+

When an object is found, the following metadata entries are set in the matching +frame: +

+
lavfi.rect.w
+

width of object +

+
+
lavfi.rect.h
+

height of object +

+
+
lavfi.rect.x
+

x position of object +

+
+
lavfi.rect.y
+

y position of object +

+
+
lavfi.rect.score
+

match score of the found object +

+
+ +

It accepts the following options: +

+
+
object
+

Filepath of the object image, needs to be in gray8. +

+
+
threshold
+

Detection threshold, expressed as a decimal number in the range 0-1. +

+

A threshold value of 0.01 means only exact matches, a threshold of 0.99 means +almost everything matches. +

+

Default value is 0.5. +

+
+
mipmaps
+

Number of mipmaps, default is 3. +

+
+
xmin, ymin, xmax, ymax
+

Specifies the rectangle in which to search. +

+
+
discard
+

Discard frames where object is not detected. Default is disabled. +

+
+ + +

11.96.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    + +
  • Find the position of an object in each frame using ffprobe and write +it to a log file: +
    +
    ffprobe -f lavfi movie=test.mp4,find_rect=object=object.pgm:threshold=0.3 \
    +  -show_entries frame=pkt_pts_time:frame_tags=lavfi.rect.x,lavfi.rect.y \
    +  -of csv -o find_rect.csv
    +
    + +
+ + +

11.97 floodfill

+ +

Flood area with values of same pixel components with another values. +

+

It accepts the following options: +

+
x
+

Set pixel x coordinate. +

+
+
y
+

Set pixel y coordinate. +

+
+
s0
+

Set source #0 component value. +

+
+
s1
+

Set source #1 component value. +

+
+
s2
+

Set source #2 component value. +

+
+
s3
+

Set source #3 component value. +

+
+
d0
+

Set destination #0 component value. +

+
+
d1
+

Set destination #1 component value. +

+
+
d2
+

Set destination #2 component value. +

+
+
d3
+

Set destination #3 component value. +

+
+ + +

11.98 format

+ +

Convert the input video to one of the specified pixel formats. +Libavfilter will try to pick one that is suitable as input to +the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +"pix_fmts=yuv420p|monow|rgb24". +

+
+
color_spaces
+

A ’|’-separated list of color space names, such as +"color_spaces=bt709|bt470bg|bt2020nc". +

+
+
color_ranges
+

A ’|’-separated list of color range names, such as +"color_ranges=tv|pc". +

+
+
alpha_modes
+

A ’|’-separated list of color range names, such as +"alpha_modes=straight|premultiplied". +

+
+
+ + +

11.98.1 Examples

+ +
    +
  • Convert the input video to the yuv420p format +
    +
    format=pix_fmts=yuv420p
    +
    + +

    Convert the input video to any of the formats in the list +

    +
    format=pix_fmts=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

11.99 fps

+ +

Convert the video to specified constant frame rate by duplicating or dropping +frames as necessary. +

+

It accepts the following parameters: +

+
fps
+

The desired output frame rate. It accepts expressions containing the following +constants: +

+
+
‘source_fps’
+

The input’s frame rate +

+
+
‘ntsc’
+

NTSC frame rate of 30000/1001 +

+
+
‘pal’
+

PAL frame rate of 25.0 +

+
+
‘film’
+

Film frame rate of 24.0 +

+
+
‘ntsc_film’
+

NTSC-film frame rate of 24000/1001 +

+
+ +

The default is 25. +

+
+
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. +

+
+
round
+

Timestamp (PTS) rounding method. +

+

Possible values are: +

+
zero
+

round towards 0 +

+
inf
+

round away from 0 +

+
down
+

round towards -infinity +

+
up
+

round towards +infinity +

+
near
+

round to nearest +

+
+

The default is near. +

+
+
eof_action
+

Action performed when reading the last frame. +

+

Possible values are: +

+
round
+

Use same timestamp rounding method as used for other frames. +

+
pass
+

Pass through last frame if input duration has not been reached yet. +

+
+

The default is round. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +fps[:start_time[:round]]. +

+

See also the setpts filter. +

+ +

11.99.1 Examples

+ +
    +
  • A typical usage in order to set the fps to 25: +
    +
    fps=fps=25
    +
    + +
  • Sets the fps to 24, using abbreviation and rounding method to round to nearest: +
    +
    fps=fps=film:round=near
    +
    +
+ + +

11.100 framepack

+ +

Pack two different video streams into a stereoscopic video, setting proper +metadata on supported codecs. The two views should have the same size and +framerate and processing will stop when the shorter video ends. Please note +that you may conveniently adjust view properties with the scale and +fps filters. +

+

It accepts the following parameters: +

+
format
+

The desired packing format. Supported values are: +

+
+
sbs
+

The views are next to each other (default). +

+
+
tab
+

The views are on top of each other. +

+
+
lines
+

The views are packed by line. +

+
+
columns
+

The views are packed by column. +

+
+
frameseq
+

The views are temporally interleaved. +

+
+
+ +
+
+ +

Some examples: +

+
+
# Convert left and right views into a frame-sequential video
+ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
+
+# Convert views into a side-by-side video with the same output resolution as the input
+ffmpeg -i LEFT -i RIGHT -filter_complex [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/2[right],[left][right]framepack=sbs OUTPUT
+
+ + +

11.101 framerate

+ +

Change the frame rate by interpolating new video output frames from the source +frames. +

+

This filter is not designed to function correctly with interlaced media. If +you wish to change the frame rate of interlaced media then you are required +to deinterlace before this filter and re-interlace after this filter. +

+

A description of the accepted options follows. +

+
+
fps
+

Specify the output frames per second. This option can also be specified +as a value alone. The default is 50. +

+
+
interp_start
+

Specify the start of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 15. +

+
+
interp_end
+

Specify the end of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 240. +

+
+
scene
+

Specify the level at which a scene change is detected as a value between +0 and 100 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one. +The default is 8.2. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
scene_change_detect, scd
+

Enable scene change detection using the value of the option scene. +This flag is enabled by default. +

+
+
+
+ + +

11.102 framestep

+ +

Select one frame every N-th frame. +

+

This filter accepts the following option: +

+
step
+

Select frame after every step frames. +Allowed values are positive integers higher than 0. Default value is 1. +

+
+ + +

11.103 freezedetect

+ +

Detect frozen video. +

+

This filter logs a message and sets frame metadata when it detects that the +input video has no significant change in content during a specified duration. +Video freeze detection calculates the mean average absolute difference of all +the components of video frames and compares it to a noise floor. +

+

The printed times and duration are expressed in seconds. The +lavfi.freezedetect.freeze_start metadata key is set on the first frame +whose timestamp equals or exceeds the detection duration and it contains the +timestamp of the first frame of the freeze. The +lavfi.freezedetect.freeze_duration and +lavfi.freezedetect.freeze_end metadata keys are set on the first frame +after the freeze. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or as a difference ratio between 0 and 1. Default is -60dB, or +0.001. +

+
+
duration, d
+

Set freeze duration until notification (default is 2 seconds). +

+
+ + +

11.104 freezeframes

+ +

Freeze video frames. +

+

This filter freezes video frames using frame from 2nd input. +

+

The filter accepts the following options: +

+
+
first
+

Set number of first frame from which to start freeze. +

+
+
last
+

Set number of last frame from which to end freeze. +

+
+
replace
+

Set number of frame from 2nd input which will be used instead of replaced frames. +

+
+ + +

11.105 frei0r

+ +

Apply a frei0r effect to the input video. +

+

To enable the compilation of this filter, you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the frei0r effect to load. If the environment variable +FREI0R_PATH is defined, the frei0r effect is searched for in each of the +directories specified by the colon-separated list in FREI0R_PATH. +Otherwise, the standard frei0r paths are searched, in this order: +HOME/.frei0r-1/lib/, /usr/local/lib/frei0r-1/, +/usr/lib/frei0r-1/. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r effect. +

+
+
+ +

A frei0r effect parameter can be a boolean (its value is either +"y" or "n"), a double, a color (specified as +R/G/B, where R, G, and B are floating point +numbers between 0.0 and 1.0, inclusive) or a color description as specified in the +"Color" section in the ffmpeg-utils manual, +a position (specified as X/Y, where +X and Y are floating point numbers) and/or a string. +

+

The number and types of parameters depend on the loaded effect. If an +effect parameter is not specified, the default value is set. +

+ +

11.105.1 Examples

+ +
    +
  • Apply the distort0r effect, setting the first two double parameters: +
    +
    frei0r=filter_name=distort0r:filter_params=0.5|0.01
    +
    + +
  • Apply the colordistance effect, taking a color as the first parameter: +
    +
    frei0r=colordistance:0.2/0.3/0.4
    +frei0r=colordistance:violet
    +frei0r=colordistance:0x112233
    +
    + +
  • Apply the perspective effect, specifying the top left and top right image +positions: +
    +
    frei0r=perspective:0.2/0.2|0.8/0.2
    +
    +
+ +

For more information, see +http://frei0r.dyne.org +

+ +

11.105.2 Commands

+ +

This filter supports the filter_params option as commands. +

+ +

11.106 fspp

+ +

Apply fast and simple postprocessing. It is a faster version of spp. +

+

It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- +processing filter, one of them is performed once per block, not per pixel. +This allows for much higher speed. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 4-5. Default value is 4. +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range 0-63. +If not set, the filter will use the QP from the video stream (if available). +

+
+
strength
+

Set filter strength. It accepts an integer in range -15 to 32. Lower values mean +more details but also more artifacts, while higher values make the image smoother +but also blurrier. Default value is 0 − PSNR optimal. +

+
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+
+ + +

11.107 fsync

+ +

Synchronize video frames with an external mapping from a file. +

+

For each input PTS given in the map file it either drops or creates as many +frames as necessary to recreate the sequence of output frames given in the +map file. +

+

This filter is useful to recreate the output frames of a framerate conversion +by the fps filter, recorded into a map file using the ffmpeg option +-stats_mux_pre, and do further processing to the corresponding frames +e.g. quality comparison. +

+

Each line of the map file must contain three items per input frame, the input +PTS (decimal), the output PTS (decimal) and the +output TIMEBASE (decimal/decimal), separated by a space. +This file format corresponds to the output +of -stats_mux_pre_fmt="{ptsi} {pts} {tb}". +

+

The filter assumes the map file is sorted by increasing input PTS. +

+

The filter accepts the following options: +

+
file, f
+

The filename of the map file to be used. +

+
+ +

Example: +

+
# Convert a video to 25 fps and record a MAP_FILE file with the default format of this filter
+ffmpeg -i INPUT -vf fps=fps=25 -stats_mux_pre MAP_FILE -stats_mux_pre_fmt "{ptsi} {pts} {tb}" OUTPUT
+
+# Sort MAP_FILE by increasing input PTS
+sort -n MAP_FILE
+
+# Use INPUT, OUTPUT and the MAP_FILE from above to compare the corresponding frames in INPUT and OUTPUT via SSIM
+ffmpeg -i INPUT -i OUTPUT -filter_complex '[0:v]fsync=file=MAP_FILE[ref];[1:v][ref]ssim' -f null -
+
+ + +

11.108 gblur

+ +

Apply Gaussian blur filter. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
steps
+

Set number of steps for Gaussian approximation. Default is 1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+ + +

11.108.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.109 geq

+ +

Apply generic equation to each pixel. +

+

The filter accepts the following options: +

+
+
lum_expr, lum
+

Set the luma expression. +

+
cb_expr, cb
+

Set the chrominance blue expression. +

+
cr_expr, cr
+

Set the chrominance red expression. +

+
alpha_expr, a
+

Set the alpha expression. +

+
red_expr, r
+

Set the red expression. +

+
green_expr, g
+

Set the green expression. +

+
blue_expr, b
+

Set the blue expression. +

+
+ +

The colorspace is selected according to the specified options. If one +of the lum_expr, cb_expr, or cr_expr +options is specified, the filter will automatically select a YCbCr +colorspace. If one of the red_expr, green_expr, or +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 +to the luma expression. +

+

The expressions can use the following variables and functions: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
SW
+
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 1,1 for the luma plane, and +0.5,0.5 for chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
p(x, y)
+

Return the value of the pixel at location (x,y) of the current +plane. +

+
+
lum(x, y)
+

Return the value of the pixel at location (x,y) of the luma +plane. +

+
+
cb(x, y)
+

Return the value of the pixel at location (x,y) of the +blue-difference chroma plane. Return 0 if there is no such plane. +

+
+
cr(x, y)
+

Return the value of the pixel at location (x,y) of the +red-difference chroma plane. Return 0 if there is no such plane. +

+
+
r(x, y)
+
g(x, y)
+
b(x, y)
+

Return the value of the pixel at location (x,y) of the +red/green/blue component. Return 0 if there is no such component. +

+
+
alpha(x, y)
+

Return the value of the pixel at location (x,y) of the alpha +plane. Return 0 if there is no such plane. +

+
+
psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
+

Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining +sums of samples within a rectangle. See the functions without the sum postfix. +

+
+
interpolation
+

Set one of interpolation methods: +

+
nearest, n
+
bilinear, b
+
+

Default is bilinear. +

+
+ +

For functions, if x and y are outside the area, the value will be +automatically clipped to the closer edge. +

+

Please note that this filter can use multiple threads in which case each slice +will have its own expression state. If you want to use only a single expression +state because your expressions depend on previous state then you should limit +the number of filter threads to 1. +

+ +

11.109.1 Examples

+ +
    +
  • Flip the image horizontally: +
    +
    geq=p(W-X\,Y)
    +
    + +
  • Generate a bidimensional sine wave, with angle PI/3 and a +wavelength of 100 pixels: +
    +
    geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
    +
    + +
  • Generate a fancy enigmatic moving light: +
    +
    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
    +
    + +
  • Generate a quick emboss effect: +
    +
    format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
    +
    + +
  • Modify RGB components depending on pixel position: +
    +
    geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
    +
    + +
  • Create a radial gradient that is the same size as the input (also see +the vignette filter): +
    +
    geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
    +
    +
+ + +

11.110 gradfun

+ +

Fix the banding artifacts that are sometimes introduced into nearly flat +regions by truncation to 8-bit color depth. +Interpolate the gradients that should go where the bands are, and +dither them. +

+

It 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. +

+

It accepts the following parameters: +

+
+
strength
+

The maximum amount by which the filter will change any one pixel. This is also +the threshold for detecting nearly flat regions. Acceptable values range from +.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the +valid range. +

+
+
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 8-32; the default value is 16. Out-of-range +values will be clipped to the valid range. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +strength[:radius] +

+ +

11.110.1 Examples

+ +
    +
  • Apply the filter with a 3.5 strength and radius of 8: +
    +
    gradfun=3.5:8
    +
    + +
  • Specify radius, omitting the strength (which will fall-back to the default +value): +
    +
    gradfun=radius=8
    +
    + +
+ + +

11.111 graphmonitor

+

Show various filtergraph stats. +

+

With this filter one can debug complete filtergraph. +Especially issues with links filling with queued frames. +

+

The filter accepts the following options: +

+
+
size, s
+

Set video output size. Default is hd720. +

+
+
opacity, o
+

Set video opacity. Default is 0.9. Allowed range is from 0 to 1. +

+
+
mode, m
+

Set output mode flags. +

+

Available values for flags are: +

+
‘full’
+

No any filtering. Default. +

+
‘compact’
+

Show only filters with queued frames. +

+
‘nozero’
+

Show only filters with non-zero stats. +

+
‘noeof’
+

Show only filters with non-eof stat. +

+
‘nodisabled’
+

Show only filters that are enabled in timeline. +

+
+ +
+
flags, f
+

Set flags which enable which stats are shown in video. +

+

Available values for flags are: +

+
‘none’
+

All flags turned off. +

+
+
‘all’
+

All flags turned on. +

+
+
‘queue’
+

Display number of queued frames in each link. +

+
+
‘frame_count_in’
+

Display number of frames taken from filter. +

+
+
‘frame_count_out’
+

Display number of frames given out from filter. +

+
+
‘frame_count_delta’
+

Display delta number of frames between above two values. +

+
+
‘pts’
+

Display current filtered frame pts. +

+
+
‘pts_delta’
+

Display pts delta between current and previous frame. +

+
+
‘time’
+

Display current filtered frame time. +

+
+
‘time_delta’
+

Display time delta between current and previous frame. +

+
+
‘timebase’
+

Display time base for filter link. +

+
+
‘format’
+

Display used format for filter link. +

+
+
‘size’
+

Display video size or number of audio channels in case of audio used by filter link. +

+
+
‘rate’
+

Display video frame rate or sample rate in case of audio used by filter link. +

+
+
‘eof’
+

Display link output status. +

+
+
‘sample_count_in’
+

Display number of samples taken from filter. +

+
+
‘sample_count_out’
+

Display number of samples given out from filter. +

+
+
‘sample_count_delta’
+

Display delta number of samples between above two values. +

+
+
‘disabled’
+

Show the timeline filter status. +

+
+ +
+
rate, r
+

Set upper limit for video rate of output stream, Default value is 25. +This guarantee that output video frame rate will not be higher than this value. +

+
+ + +

11.112 grayworld

+

A color constancy filter that applies color correction based on the grayworld assumption +

+

See: https://www.researchgate.net/publication/275213614_A_New_Color_Correction_Method_for_Underwater_Imaging +

+

The algorithm uses linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,grayworld,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

11.113 greyedge

+

A color constancy variation filter which estimates scene illumination via grey edge algorithm +and corrects the scene colors accordingly. +

+

See: https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf +

+

The filter accepts the following options: +

+
+
difford
+

The order of differentiation to be applied on the scene. Must be chosen in the range +[0,2] and default value is 1. +

+
+
minknorm
+

The Minkowski parameter to be used for calculating the Minkowski distance. Must +be chosen in the range [0,20] and default value is 1. Set to 0 for getting +max value instead of calculating Minkowski distance. +

+
+
sigma
+

The standard deviation of Gaussian blur to be applied on the scene. Must be +chosen in the range [0,1024.0] and default value = 1. floor( sigma * break_off_sigma(3) ) +can’t be equal to 0 if difford is greater than 0. +

+
+ + +

11.113.1 Examples

+
    +
  • Grey Edge: +
    +
    greyedge=difford=1:minknorm=5:sigma=2
    +
    + +
  • Max Edge: +
    +
    greyedge=difford=1:minknorm=0:sigma=2
    +
    + +
+ + +

11.114 guided

+

Apply guided filter for edge-preserving smoothing, dehazing and so on. +

+

The filter accepts the following options: +

+
radius
+

Set the box radius in pixels. +Allowed range is 1 to 20. Default is 3. +

+
+
eps
+

Set regularization parameter (with square). +Allowed range is 0 to 1. Default is 0.01. +

+
+
mode
+

Set filter mode. Can be basic or fast. +Default is basic. +

+
+
sub
+

Set subsampling ratio for fast mode. +Range is 2 to 64. Default is 4. +No subsampling occurs in basic mode. +

+
+
guidance
+

Set guidance mode. Can be off or on. Default is off. +If off, single input is required. +If on, two inputs of the same resolution and pixel format are required. +The second input serves as the guidance. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

11.114.1 Commands

+

This filter supports the all above options as commands. +

+ +

11.114.2 Examples

+
    +
  • Edge-preserving smoothing with guided filter: +
    +
    ffmpeg -i in.png -vf guided out.png
    +
    + +
  • Dehazing, structure-transferring filtering, detail enhancement with guided filter. +For the generation of guidance image, refer to paper "Guided Image Filtering". +See: http://kaiminghe.com/publications/pami12guidedfilter.pdf. +
    +
    ffmpeg -i in.png -i guidance.png -filter_complex guided=guidance=on out.png
    +
    + +
+ + +

11.115 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: +

+
+
clut
+

Set which CLUT video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+
shortest
+

Force termination when the shortest input terminates. Default is 0. +

+
repeatlast
+

Continue applying the last CLUT after the end of the stream. A value of +0 disable the filter after the last frame of the CLUT is reached. +Default is 1. +

+
+ +

haldclut also has the same interpolation options as lut3d (both +filters share the same internals). +

+

This filter also supports the framesync options. +

+

More information about the Hald CLUT can be found on Eskil Steenberg’s website +(Hald CLUT author) at http://www.quelsolaar.com/technology/clut.html. +

+ +

11.115.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

11.115.2 Workflow examples

+ + +

11.115.2.1 Hald CLUT video stream

+ +

Generate an identity Hald CLUT stream altered with various effects: +

+
ffmpeg -f lavfi -i haldclutsrc=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut
+
+ +

Note: make sure you use a lossless codec. +

+

Then use it with haldclut to apply it on some random stream: +

+
ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
+
+ +

The Hald CLUT will be applied to the 10 first seconds (duration of +clut.nut), then the latest picture of that CLUT stream will be applied +to the remaining frames of the mandelbrot stream. +

+ +

11.115.2.2 Hald CLUT with preview

+ +

A Hald CLUT is supposed to be a squared image of Level*Level*Level by +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 +haldclut filter: +

+
+
ffmpeg -f lavfi -i 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
+
+ +

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: +

+
ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
+
+ + +

11.116 hflip

+ +

Flip the input video horizontally. +

+

For example, to horizontally flip the input video with ffmpeg: +

+
ffmpeg -i in.avi -vf "hflip" out.avi
+
+ + +

11.117 histeq

+

This filter applies a global color histogram equalization on a +per-frame basis. +

+

It can be used to correct video that has a compressed range of pixel +intensities. The filter redistributes the pixel intensities to +equalize their distribution across the intensity range. It may be +viewed as an "automatically adjusting contrast filter". This filter is +useful only for correcting degraded or poorly captured source +video. +

+

The filter accepts the following options: +

+
+
strength
+

Determine the amount of equalization to be applied. As the strength +is reduced, the distribution of pixel intensities more-and-more +approaches that of the input frame. The value must be a float number +in the range [0,1] and defaults to 0.200. +

+
+
intensity
+

Set the maximum intensity that can generated and scale the output +values appropriately. The strength should be set as desired and then +the intensity can be limited if needed to avoid washing-out. The value +must be a float number in the range [0,1] and defaults to 0.210. +

+
+
antibanding
+

Set the antibanding level. If enabled the filter will randomly vary +the luminance of output pixels by a small amount to avoid banding of +the histogram. Possible values are none, weak or +strong. It defaults to none. +

+
+ + +

11.118 histogram

+ +

Compute and draw a color distribution histogram for the input video. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

Standard histogram displays the color components distribution in an image. +Displays color graph for each color component. Shows distribution of +the Y, U, V, A or R, G, B components, depending on input format, in the +current frame. Below each graph a color component scale meter is shown. +

+

The filter accepts the following options: +

+
+
level_height
+

Set height of level. Default value is 200. +Allowed range is [50, 2048]. +

+
+
scale_height
+

Set height of color scale. Default value is 12. +Allowed range is [0, 40]. +

+
+
display_mode
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components
+

Set what color components to display. +Default is 7. +

+
+
fgopacity
+

Set foreground opacity. Default is 0.7. +

+
+
bgopacity
+

Set background opacity. Default is 0.5. +

+
+
colors_mode
+

Set colors mode. +It accepts the following values: +

+
‘whiteonblack’
+
‘blackonwhite’
+
‘whiteongray’
+
‘blackongray’
+
‘coloronblack’
+
‘coloronwhite’
+
‘colorongray’
+
‘blackoncolor’
+
‘whiteoncolor’
+
‘grayoncolor’
+
+

Default is whiteonblack. +

+
+ + +

11.118.1 Examples

+ +
    +
  • Calculate and draw histogram: +
    +
    ffplay -i input -vf histogram
    +
    + +
+ + +

11.119 hqdn3d

+ +

This is a high precision/quality 3d denoise filter. It aims to reduce +image noise, producing smooth images and making still images really +still. It should enhance compressibility. +

+

It accepts the following optional parameters: +

+
+
luma_spatial
+

A non-negative floating point number which specifies spatial luma strength. +It defaults to 4.0. +

+
+
chroma_spatial
+

A non-negative floating point number which specifies spatial chroma strength. +It defaults to 3.0*luma_spatial/4.0. +

+
+
luma_tmp
+

A floating point number which specifies luma temporal strength. It defaults to +6.0*luma_spatial/4.0. +

+
+
chroma_tmp
+

A floating point number which specifies chroma temporal strength. It defaults to +luma_tmp*chroma_spatial/luma_spatial. +

+
+ + +

11.119.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.120 hwdownload

+ +

Download hardware frames to system memory. +

+

The input must be in hardware frames, and the output a non-hardware format. +Not all formats will be supported on the output - it may be necessary to insert +an additional format filter immediately following in the graph to get +the output in a supported format. +

+ +

11.121 hwmap

+ +

Map hardware frames to system memory or to another device. +

+

This filter has several different modes of operation; which one is used depends +on the input and output formats: +

    +
  • Hardware frame input, normal frame output + +

    Map the input frames to system memory and pass them to the output. If the +original hardware frame is later required (for example, after overlaying +something else on part of it), the hwmap filter can be used again +in the next mode to retrieve it. +

  • Normal frame input, hardware frame output + +

    If the input is actually a software-mapped hardware frame, then unmap it - +that is, return the original hardware frame. +

    +

    Otherwise, a device must be provided. Create new hardware surfaces on that +device for the output, then map them back to the software format at the input +and give those frames to the preceding filter. This will then act like the +hwupload filter, but may be able to avoid an additional copy when +the input is already in a compatible format. +

  • Hardware frame input and output + +

    A device must be supplied for the output, either directly or with the +derive_device option. The input and output devices must be of +different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

    +

    If the input frames were originally created on the output device, then unmap +to retrieve the original frames. +

    +

    Otherwise, map the frames to the output device - create new hardware frames +on the output corresponding to the frames on the input. +

+ +

The following additional parameters are accepted: +

+
+
mode
+

Set the frame mapping mode. Some combination of: +

+
read
+

The mapped frame should be readable. +

+
write
+

The mapped frame should be writeable. +

+
overwrite
+

The mapping will always overwrite the entire frame. +

+

This may improve performance in some cases, as the original contents of the +frame need not be loaded. +

+
direct
+

The mapping must not involve any copying. +

+

Indirect mappings to copies of frames are created in some cases where either +direct mapping is not possible or it would have unexpected properties. +Setting this flag ensures that the mapping is direct and will fail if that is +not possible. +

+
+

Defaults to read+write if not specified. +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+
reverse
+

In a hardware to hardware mapping, map in reverse - create frames in the sink +and map them back to the source. This may be necessary in some cases where +a mapping in one direction is required but only the opposite direction is +supported by the devices being used. +

+

This option is dangerous - it may break the preceding filter in undefined +ways if there are any additional constraints on that filter’s output. +Do not use it without fully understanding the implications of its use. +

+
+ + +

11.122 hwupload

+ +

Upload system memory frames to hardware surfaces. +

+

The device to upload to must be supplied when the filter is initialised. If +using ffmpeg, select the appropriate device with the -filter_hw_device +option or with the derive_device option. The input and output devices +must be of different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

+

The following additional parameters are accepted: +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+ + +

11.123 hwupload_cuda

+ +

Upload system memory frames to a CUDA device. +

+

It accepts the following optional parameters: +

+
+
device
+

The number of the CUDA device to use +

+
+ + +

11.124 hqx

+ +

Apply a high-quality magnification filter designed for pixel art. This filter +was originally created by Maxim Stepin. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for hq2x, 3 for +hq3x and 4 for hq4x. +Default is 3. +

+
+ + +

11.125 hstack

+

Stack input videos horizontally. +

+

All streams must be of same pixel format and of same height. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following option: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

11.126 hsvhold

+

Turns a certain HSV range into gray values. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to be gray or not. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully gray, or not gray at all. +

+

Higher values result in more gray pixels, with a higher gray pixel +the more similar the pixels color is to the key color. +

+
+ + +

11.127 hsvkey

+

Turns a certain HSV range into transparency. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to transparent by adding alpha channel. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

11.128 hue

+ +

Modify the hue and/or the saturation of the input. +

+

It accepts the following parameters: +

+
+
h
+

Specify the hue angle as a number of degrees. It accepts an expression, +and defaults to "0". +

+
+
s
+

Specify the saturation in the [-10,10] range. It accepts an expression and +defaults to "1". +

+
+
H
+

Specify the hue angle as a number of radians. It accepts an +expression, and defaults to "0". +

+
+
b
+

Specify the brightness in the [-10,10] range. It accepts an expression and +defaults to "0". +

+
+ +

h and H are mutually exclusive, and can’t be +specified at the same time. +

+

The b, h, H and s option values are +expressions containing the following constants: +

+
+
n
+

frame count of the input frame starting from 0 +

+
+
pts
+

presentation timestamp of the input frame expressed in time base units +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
tb
+

time base of the input video +

+
+ + +

11.128.1 Examples

+ +
    +
  • Set the hue to 90 degrees and the saturation to 1.0: +
    +
    hue=h=90:s=1
    +
    + +
  • Same command but expressing the hue in radians: +
    +
    hue=H=PI/2:s=1
    +
    + +
  • Rotate hue and make the saturation swing between 0 +and 2 over a period of 1 second: +
    +
    hue="H=2*PI*t: s=sin(2*PI*t)+1"
    +
    + +
  • Apply a 3 seconds saturation fade-in effect starting at 0: +
    +
    hue="s=min(t/3\,1)"
    +
    + +

    The general fade-in expression can be written as: +

    +
    hue="s=min(0\, max((t-START)/DURATION\, 1))"
    +
    + +
  • Apply a 3 seconds saturation fade-out effect starting at 5 seconds: +
    +
    hue="s=max(0\, min(1\, (8-t)/3))"
    +
    + +

    The general fade-out expression can be written as: +

    +
    hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
    +
    + +
+ + +

11.128.2 Commands

+ +

This filter supports the following commands: +

+
b
+
s
+
h
+
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 the specified expression is not valid, it is kept at its current +value. +

+
+ + +

11.129 huesaturation

+

Apply hue-saturation-intensity adjustments to input video stream. +

+

This filter operates in RGB colorspace. +

+

This filter accepts the following options: +

+
+
hue
+

Set the hue shift in degrees to apply. Default is 0. +Allowed range is from -180 to 180. +

+
+
saturation
+

Set the saturation shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
intensity
+

Set the intensity shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
colors
+

Set which primary and complementary colors are going to be adjusted. +This options is set by providing one or multiple values. +This can select multiple colors at once. By default all colors are selected. +

+
‘r’
+

Adjust reds. +

+
‘y’
+

Adjust yellows. +

+
‘g’
+

Adjust greens. +

+
‘c’
+

Adjust cyans. +

+
‘b’
+

Adjust blues. +

+
‘m’
+

Adjust magentas. +

+
‘a’
+

Adjust all colors. +

+
+ +
+
strength
+

Set strength of filtering. Allowed range is from 0 to 100. +Default value is 1. +

+
+
rw, gw, bw
+

Set weight for each RGB component. Allowed range is from 0 to 1. +By default is set to 0.333, 0.334, 0.333. +Those options are used in saturation and lightess processing. +

+
+
lightness
+

Set preserving lightness, by default is disabled. +Adjusting hues can change lightness from original RGB triplet, +with this option enabled lightness is kept at same value. +

+
+ + +

11.130 hysteresis

+ +

Grow first stream into second stream by connecting components. +This makes it possible to build more robust edge masks. +

+

This filter accepts the following options: +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+
threshold
+

Set threshold which is used in filtering. If pixel component value is higher than +this value filter algorithm for connecting components is activated. +By default value is 0. +

+
+ +

The hysteresis filter also supports the framesync options. +

+ +

11.131 iccdetect

+ +

Detect the colorspace from an embedded ICC profile (if present), and update +the frame’s tags accordingly. +

+

This filter accepts the following options: +

+
+
force
+

If true, the frame’s existing colorspace tags will always be overridden by +values detected from an ICC profile. Otherwise, they will only be assigned if +they contain unknown. Enabled by default. +

+
+ + +

11.132 iccgen

+ +

Generate ICC profiles and attach them to frames. +

+

This filter accepts the following options: +

+
+
color_primaries
+
color_trc
+

Configure the colorspace that the ICC profile will be generated for. The +default value of auto infers the value from the input frame’s metadata, +defaulting to BT.709/sRGB as appropriate. +

+

See the setparams filter for a list of possible values, but note that +unknown are not valid values for this filter. +

+
+
force
+

If true, an ICC profile will be generated even if it would overwrite an +already existing ICC profile. Disabled by default. +

+
+ + +

11.133 identity

+ +

Obtain the identity score between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max identity score is printed through +the logging system. +

+

The filter stores the calculated identity scores of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi identity -f null -
+
+ + +

11.134 idet

+ +

Detect video interlacing type. +

+

This filter tries to detect if the input frames are interlaced, progressive, +top or bottom field first. It will also try to detect fields that are +repeated between adjacent frames (a sign of telecine). +

+

Single frame detection considers only immediately adjacent frames when classifying each frame. +Multiple frame detection incorporates the classification history of previous frames. +

+

The filter will log these metadata values: +

+
+
single.current_frame
+

Detected type of current frame using single-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
single.tff
+

Cumulative number of frames detected as top field first using single-frame detection. +

+
+
multiple.tff
+

Cumulative number of frames detected as top field first using multiple-frame detection. +

+
+
single.bff
+

Cumulative number of frames detected as bottom field first using single-frame detection. +

+
+
multiple.current_frame
+

Detected type of current frame using multiple-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
multiple.bff
+

Cumulative number of frames detected as bottom field first using multiple-frame detection. +

+
+
single.progressive
+

Cumulative number of frames detected as progressive using single-frame detection. +

+
+
multiple.progressive
+

Cumulative number of frames detected as progressive using multiple-frame detection. +

+
+
single.undetermined
+

Cumulative number of frames that could not be classified using single-frame detection. +

+
+
multiple.undetermined
+

Cumulative number of frames that could not be classified using multiple-frame detection. +

+
+
repeated.current_frame
+

Which field in the current frame is repeated from the last. One of “neither”, “top”, or “bottom”. +

+
+
repeated.neither
+

Cumulative number of frames with no repeated field. +

+
+
repeated.top
+

Cumulative number of frames with the top field repeated from the previous frame’s top field. +

+
+
repeated.bottom
+

Cumulative number of frames with the bottom field repeated from the previous frame’s bottom field. +

+
+ +

The filter accepts the following options: +

+
+
intl_thres
+

Set interlacing threshold. +

+
prog_thres
+

Set progressive threshold. +

+
rep_thres
+

Threshold for repeated field detection. +

+
half_life
+

Number of frames after which a given frame’s contribution to the +statistics is halved (i.e., it contributes only 0.5 to its +classification). The default of 0 means that all frames seen are given +full weight of 1.0 forever. +

+
analyze_interlaced_flag
+

When this is not 0 then idet will use the specified number of frames to determine +if the interlaced flag is accurate, it will not count undetermined frames. +If the flag is found to be accurate it will be used without any further +computations, if it is found to be inaccurate it will be cleared without any +further computations. This allows inserting the idet filter as a low computational +method to clean up the interlaced flag +

+
+ + +

11.134.1 Examples

+ +

Inspect the field order of the first 360 frames in a video, in verbose detail: +

+
ffmpeg -i INPUT -filter:v idet,metadata=mode=print -frames:v 360 -an -f null -
+
+

The idet filter will add analysis metadata to each frame, which will then be +discarded. At the end, the filter will also print a final report with statistics. +

+ +

11.135 il

+ +

Deinterleave or interleave fields. +

+

This filter allows one to process interlaced images fields without +deinterlacing them. Deinterleaving splits the input frame into 2 +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. +

+

The filter accepts the following options: +

+
+
luma_mode, l
+
chroma_mode, c
+
alpha_mode, a
+

Available values for luma_mode, chroma_mode and +alpha_mode are: +

+
+
‘none’
+

Do nothing. +

+
+
‘deinterleave, d’
+

Deinterleave fields, placing one above the other. +

+
+
‘interleave, i’
+

Interleave fields. Reverse the effect of deinterleaving. +

+
+

Default value is none. +

+
+
luma_swap, ls
+
chroma_swap, cs
+
alpha_swap, as
+

Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is 0. +

+
+ + +

11.135.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.136 inflate

+ +

Apply inflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values higher than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

11.136.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.137 interlace, interlace_vulkan

+ +

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. +

+
+
   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
+
+ +

It accepts the following optional parameters: +

+
+
scan
+

This determines whether the interlaced frame is taken from the even +(tff - default) or odd (bff) lines of the progressive frame. +

+
+
lowpass
+

Vertical lowpass filter to avoid twitter interlacing and +reduce moire patterns. +

+
+
‘0, off’
+

Disable vertical lowpass filter +

+
+
‘1, linear’
+

Enable linear filter (default) +

+
+
‘2, complex’
+

Enable complex filter. This will slightly less reduce twitter and moire +but better retain detail and subjective sharpness impression. +

+
+
+
+
+ + +

11.138 kerndeint

+ +

Deinterlace input video by applying Donald Graft’s adaptive kernel +deinterling. Work on interlaced parts of a video to produce +progressive frames. +

+

The description of the accepted parameters follows. +

+
+
thresh
+

Set the threshold which affects the filter’s tolerance when +determining if a pixel line must be processed. It must be an integer +in the range [0,255] and defaults to 10. A value of 0 will result in +applying the process on every pixels. +

+
+
map
+

Paint pixels exceeding the threshold value to white if set to 1. +Default is 0. +

+
+
order
+

Set the fields order. Swap fields if set to 1, leave fields alone if +0. Default is 0. +

+
+
sharp
+

Enable additional sharpening if set to 1. Default is 0. +

+
+
twoway
+

Enable twoway sharpening if set to 1. Default is 0. +

+
+ + +

11.138.1 Examples

+ +
    +
  • Apply default values: +
    +
    kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
    +
    + +
  • Enable additional sharpening: +
    +
    kerndeint=sharp=1
    +
    + +
  • Paint processed pixels in white: +
    +
    kerndeint=map=1
    +
    +
+ + +

11.139 kirsch

+

Apply kirsch operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

11.139.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.140 lagfun

+ +

Slowly update darker pixels. +

+

This filter makes short flashes of light appear longer. +This filter accepts the following options: +

+
+
decay
+

Set factor for decaying. Default is .95. Allowed range is from 0 to 1. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

11.140.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.141 lenscorrection

+ +

Correct radial lens distortion +

+

This filter can be used to correct for radial distortion as can result from the use +of wide angle lenses, and thereby re-rectify the image. To find the right parameters +one can use tools available for example as part of opencv or simply trial-and-error. +To use opencv use the calibration sample (under samples/cpp) from the opencv sources +and extract the k1 and k2 coefficients from the resulting matrix. +

+

Note that effectively the same filter is available in the open-source tools Krita and +Digikam from the KDE project. +

+

In contrast to the vignette filter, which can also be used to compensate lens errors, +this filter corrects the distortion of the image, whereas vignette corrects the +brightness distribution, so you may want to use both filters together in certain +cases, though you will have to take care of ordering, i.e. whether vignetting should +be applied before or after lens correction. +

+ +

11.141.1 Options

+ +

The filter accepts the following options: +

+
+
cx
+

Relative x-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +width. Default is 0.5. +

+
cy
+

Relative y-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +height. Default is 0.5. +

+
k1
+

Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means +no correction. Default is 0. +

+
k2
+

Coefficient of the double quadratic correction term. This value has a range [-1,1]. +0 means no correction. Default is 0. +

+
i
+

Set interpolation type. Can be nearest or bilinear. +Default is nearest. +

+
fc
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black@0. +

+
+ +

The formula that generates the correction is: +

+

r_src = r_tgt * (1 + k1 * (r_tgt / r_0)^2 + k2 * (r_tgt / r_0)^4) +

+

where r_0 is halve of the image diagonal and r_src and r_tgt are the +distances from the focal point in the source and target images, respectively. +

+ +

11.141.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.142 lensfun

+ +

Apply lens correction via the lensfun library (http://lensfun.sourceforge.net/). +

+

The lensfun filter requires the camera make, camera model, and lens model +to apply the lens correction. The filter will load the lensfun database and +query it to find the corresponding camera and lens entries in the database. As +long as these entries can be found with the given options, the filter can +perform corrections on frames. Note that incomplete strings will result in the +filter choosing the best match with the given options, and the filter will +output the chosen camera and lens models (logged with level "info"). You must +provide the make, camera model, and lens model as they are required. +

+

To obtain a list of available makes and models, leave out one or both of make and +model options. The filter will send the full list to the log with level INFO. +The first column is the make and the second column is the model. +To obtain a list of available lenses, set any values for make and model and leave out the +lens_model option. The filter will send the full list of lenses in the log with level +INFO. The ffmpeg tool will exit after the list is printed. +

+

The filter accepts the following options: +

+
+
make
+

The make of the camera (for example, "Canon"). This option is required. +

+
+
model
+

The model of the camera (for example, "Canon EOS 100D"). This option is +required. +

+
+
lens_model
+

The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This +option is required. +

+
+
db_path
+

The full path to the lens database folder. If not set, the filter will attempt to +load the database from the install path when the library was built. Default is unset. +

+
+
mode
+

The type of correction to apply. The following values are valid options: +

+
+
‘vignetting’
+

Enables fixing lens vignetting. +

+
+
‘geometry’
+

Enables fixing lens geometry. This is the default. +

+
+
‘subpixel’
+

Enables fixing chromatic aberrations. +

+
+
‘vig_geo’
+

Enables fixing lens vignetting and lens geometry. +

+
+
‘vig_subpixel’
+

Enables fixing lens vignetting and chromatic aberrations. +

+
+
‘distortion’
+

Enables fixing both lens geometry and chromatic aberrations. +

+
+
‘all’
+

Enables all possible corrections. +

+
+
+
+
focal_length
+

The focal length of the image/video (zoom; expected constant for video). For +example, a 18–55mm lens has focal length range of [18–55], so a value in that +range should be chosen when using that lens. Default 18. +

+
+
aperture
+

The aperture of the image/video (expected constant for video). Note that +aperture is only used for vignetting correction. Default 3.5. +

+
+
focus_distance
+

The focus distance of the image/video (expected constant for video). Note that +focus distance is only used for vignetting and only slightly affects the +vignetting correction process. If unknown, leave it at the default value (which +is 1000). +

+
+
scale
+

The scale factor which is applied after transformation. After correction the +video is no longer necessarily rectangular. This parameter controls how much of +the resulting image is visible. The value 0 means that a value will be chosen +automatically such that there is little or no unmapped area in the output +image. 1.0 means that no additional scaling is done. Lower values may result +in more of the corrected image being visible, while higher values may avoid +unmapped areas in the output. +

+
+
target_geometry
+

The target geometry of the output image/video. The following values are valid +options: +

+
+
‘rectilinear (default)’
+
‘fisheye’
+
‘panoramic’
+
‘equirectangular’
+
‘fisheye_orthographic’
+
‘fisheye_stereographic’
+
‘fisheye_equisolid’
+
‘fisheye_thoby’
+
+
+
reverse
+

Apply the reverse of image correction (instead of correcting distortion, apply +it). +

+
+
interpolation
+

The type of interpolation used when correcting distortion. The following values +are valid options: +

+
+
‘nearest’
+
‘linear (default)’
+
‘lanczos’
+
+
+
+ + +

11.142.1 Examples

+ +
    +
  • Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens +model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and +aperture of "8.0". + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
    +
    + +
  • Apply the same as before, but only for the first 5 seconds of video. + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov
    +
    + +
+ + +

11.143 lcevc

+ +

Low Complexity Enhancement Video Codec filter based on liblcevc_dec +(https://github.com/v-novaltd/LCEVCdec). +

+ +

11.144 libplacebo

+ +

Flexible GPU-accelerated processing filter based on libplacebo +(https://code.videolan.org/videolan/libplacebo). +

+ +

11.144.1 Options

+ +

The options for this filter are divided into the following sections: +

+ +

11.144.1.1 Output mode

+

These options control the overall output mode. By default, libplacebo will try +to preserve the source colorimetry and size as best as it can, but it will +apply any embedded film grain, dolby vision metadata or anamorphic SAR present +in source frames. +

+
inputs
+

Set the number of inputs. This can be used, alongside the idx variable, +to allow placing/blending multiple inputs inside the output frame. This +effectively enables functionality similar to hstack, overlay, etc. +

+
+
w
+
h
+

Set the output video dimension expression. Default values are iw and +ih. +

+

Allows for the same expressions as the scale filter. +

+
+
crop_x
+
crop_y
+

Set the input crop x/y expressions, default values are (iw-cw)/2 and +(ih-ch)/2. +

+
+
crop_w
+
crop_h
+

Set the input crop width/height expressions, default values are iw and +ih. +

+
+
pos_x
+
pos_y
+

Set the output placement x/y expressions, default values are (ow-pw)/2 +and (oh-ph)/2. +

+
+
pos_w
+
pos_h
+

Set the output placement width/height expressions, default values are ow +and oh. +

+
+
rotate
+

Rotate the input frame clockwise by the specified angle. +

+
+
‘0, 360’
+
‘90’
+
‘180’
+
‘270’
+
+ +
+
fps
+

Set the output frame rate. This can be rational, e.g. 60000/1001. If +set to the special string none (the default), input timestamps will +instead be passed through to the output unmodified. Otherwise, the input video +frames will be interpolated as necessary to rescale the video to the specified +target framerate, in a manner as determined by the frame_mixer option. +

+
+
format
+

Set the output format override. If unset (the default), frames will be output +in the same format as the respective input frames. Otherwise, format conversion +will be performed. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. Note that +force_divisible_by also works with fit_sense=constraint. +

+
+
reset_sar
+

If enabled, output frames will always have a pixel aspect ratio of 1:1. If +disabled (the default), any aspect ratio mismatches, including those from +e.g. anamorphic video sources, are forwarded to the output pixel aspect ratio. +

+
+
normalize_sar
+

Like reset_sar, but instead of stretching the video content to fill +the new output aspect ratio, the content is instead padded or cropped as +necessary. Mutually exclusive with fit_mode. Disabled by default. +

+
+
pad_crop_ratio
+

Specifies a ratio (between 0.0 and 1.0) between padding and +cropping when the input aspect ratio does not match the output aspect ratio and +normalize_sar is in effect. The default of 0.0 always pads the +content with black borders, while a value of 1.0 always crops off parts +of the content. Intermediate values are possible, leading to a mix of the two +approaches. +

+
+
fit_mode
+

Specify the content fit strategy according to a list of predefined modes. +Determines how the input image is to be placed inside the destination crop +rectangle (as defined by pos_x/y and pos_w/h). The names and +their implementations are taken from the CSS ’object-fit’ property. Note that +this option is mutually exclusive with normalize_sar. Defaults to +fill. Valid values are: +

+
+
‘fill’
+

Stretch the input to the output rectangle, ignoring aspect ratio mismatches. +Note that unless reset_sar is also enabled, the output will still +have the correct pixel aspect ratio tagged. +

+
+
‘contain’
+

Scale the input to fit inside the output, preserving aspect ratio by padding. +Equivalent to normalize_sar with pad_crop_ratio set to +0.0. +

+
+
‘cover’
+

Scale the input to fill the output, preserving aspect ratio by cropping. +Equivalent to normalize_sar with pad_crop_ratio set to +1.0. +

+
+
‘none, place’
+

Don’t scale the input. The input will be placed inside the output rectangle at +its natural size; which may result in additional padding or cropping. +

+
+
‘scale_down’
+

Scale the input down as much as needed to fit inside the output. Equivalent +to either contain or none, depending on whether the input is +larger than the output or not. +

+
+ +
+
fit_sense
+

When fit_mode is in use, this option controls how the fit strategy +is applied against the specified output resolution. Mutually exclusive with +force_original_aspect_ratio. Valid values are: +

+
+
‘target’
+

The computed output resolution is taken as the exact size of the output frame. +This is the default behavior. +

+
+
‘constraint’
+

The computed output resolution is a size reference against which the fit mode +is applied, enlarging or decreasing the true frame size as needed to fit the +content. +

+
+ +
+
fillcolor
+

Set the color used to fill the output area not covered by the output image, for +example as a result of normalize_sar. For the general syntax of this +option, check the "Color" section in the ffmpeg-utils +manual. Defaults to black@0. +

+
+
corner_rounding
+

Render frames with rounded corners. The value, given as a float ranging from +0.0 to 1.0, indicates the relative degree of rounding, from fully +square to fully circular. In other words, it gives the radius divided by half +the smaller side length. Defaults to 0.0. +

+
+
lut
+

Specifies a custom LUT (in Adobe .cube format) to apply to the colors +as part of color conversion. The exact interpretation depends on the value +of lut_type. +

+
+
lut_type
+

Controls the interpretation of color values fed to and from the LUT +specified as lut. Valid values are: +

+
+
‘auto’
+

Chooses the interpretation of the LUT automatically from tagged +metadata, and otherwise falls back to ‘native’. (Default) +

+
+
‘native’
+

Applied to raw image contents in its native RGB colorspace (non-linear +light), before conversion to the output color space. +

+
+
‘normalized’
+

Applied to the normalized RGB image contents, in linear light, before +conversion to the output color space. +

+
+
‘conversion’
+

Fully replaces the conversion from the image color space to the output +color space. If such a LUT is present, it has the highest priority, and +overrides any ICC profiles, as well as options related to tone mapping +and output colorimetry (color_primaries, color_trc). +

+
+
+ +
+
extra_opts
+

Pass extra libplacebo internal configuration options. These can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to configure a custom filter kernel ("EWA LanczosSharp") and use it +to double the input image resolution: +

+
+
-vf "libplacebo=w=iw*2:h=ih*2:extra_opts='upscaler=custom\:upscaler_preset=ewa_lanczos\:upscaler_blur=0.9812505644269356'"
+
+ + +
+
shader_cache
+

File path of a cache directory that libplacebo will use to store and load +cached shader objects. This cache is not cleaned up automatically. If the +path does not end in a directory separator, the generated filenames will be +effectively prefixed by the last path component. All directories must already +exist. +

+
+
-vf "libplacebo=shader_cache=/tmp/pl-shader-"
+
+ +
+
colorspace
+
color_primaries
+
color_trc
+
range
+
chroma_location
+

Configure the colorspace that output frames will be delivered in. The default +value of auto outputs frames in the same format as the input frames, +leading to no change. For any other value, conversion will be performed. +

+

See the setparams filter for a list of possible values. +

+
+
alpha_mode
+

Choose the desired output alpha mode, when the output format has an alpha +channel. See the setparams filter for a list of possible values. +

+
+
apply_filmgrain
+

Apply film grain (e.g. AV1 or H.274) if present in source frames, and strip +it from the output. Enabled by default. +

+
+
apply_dolbyvision
+

Apply Dolby Vision RPU metadata if present in source frames, and strip it from +the output. Enabled by default. Note that Dolby Vision will always output +BT.2020+PQ, overriding the usual input frame metadata. These will also be +picked as the values of auto for the respective frame output options. +

+
+ +

In addition to the expression constants documented for the scale filter, +the crop_w, crop_h, crop_x, crop_y, +pos_w, pos_h, pos_x and pos_y options can +also contain the following constants: +

+
+
in_idx, idx
+

The (0-based) numeric index of the currently active input stream. +

+
crop_w, cw
+
crop_h, ch
+

The computed values of crop_w and crop_h. +

+
+
pos_w, pw
+
pos_h, ph
+

The computed values of pos_w and pos_h. +

+
+
in_t, t
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
out_t, ot
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
n
+

The input frame number, starting with 0. +

+
+ + +

11.144.1.2 Scaling

+

The options in this section control how libplacebo performs upscaling and (if +necessary) downscaling. Note that libplacebo will always internally operate on +4:4:4 content, so any sub-sampled chroma formats such as yuv420p will +necessarily be upsampled and downsampled as part of the rendering process. That +means scaling might be in effect even if the source and destination resolution +are the same. +

+
upscaler
+
downscaler
+

Configure the filter kernel used for upscaling and downscaling. The respective +defaults are spline36 and mitchell. For a full list of possible +values, pass help to these options. The most important values are: +

+
‘none’
+

Forces the use of built-in GPU texture sampling (typically bilinear). Extremely +fast but poor quality, especially when downscaling. +

+
+
‘bilinear’
+

Bilinear interpolation. Can generally be done for free on GPUs, except when +doing so would lead to aliasing. Fast and low quality. +

+
+
‘nearest’
+

Nearest-neighbour interpolation. Sharp but highly aliasing. +

+
+
‘oversample’
+

Algorithm that looks visually similar to nearest-neighbour interpolation but +tries to preserve pixel aspect ratio. Good for pixel art, since it results in +minimal distortion of the artistic appearance. +

+
+
‘lanczos’
+

Standard sinc-sinc interpolation kernel. +

+
+
‘spline36’
+

Cubic spline approximation of lanczos. No difference in performance, but has +very slightly less ringing. +

+
+
‘ewa_lanczos’
+

Elliptically weighted average version of lanczos, based on a jinc-jinc kernel. +This is also popularly referred to as just "Jinc scaling". Slow but very high +quality. +

+
+
‘gaussian’
+

Gaussian kernel. Has certain ideal mathematical properties, but subjectively +very blurry. +

+
+
‘mitchell’
+

Cubic BC spline with parameters recommended by Mitchell and Netravali. Very +little ringing. +

+
+ +
+
frame_mixer
+

Controls the kernel used for mixing frames temporally. The default value is +none, which disables frame mixing. For a full list of possible values, +pass help to this option. The most important values are: +

+
‘none’
+

Disables frame mixing, giving a result equivalent to "nearest neighbour" +semantics. +

+
+
‘oversample’
+

Oversamples the input video to create a "Smooth Motion"-type effect: if an +output frame would exactly fall on the transition between two video frames, it +is blended according to the relative overlap. This is the recommended option +whenever preserving the original subjective appearance is desired. +

+
+
‘mitchell_clamp’
+

Larger filter kernel that smoothly interpolates multiple frames in a manner +designed to eliminate ringing and other artefacts as much as possible. This is +the recommended option wherever maximum visual smoothness is desired. +

+
+
‘linear’
+

Linear blend/fade between frames. Especially useful for constructing e.g. +slideshows. +

+
+ +
+
antiringing
+

Enables anti-ringing (for non-EWA filters). The value (between 0.0 and +1.0) configures the strength of the anti-ringing algorithm. May increase +aliasing if set too high. Disabled by default. +

+
+
sigmoid
+

Enable sigmoidal compression during upscaling. Reduces ringing slightly. +Enabled by default. +

+
+ + +

11.144.1.3 Deinterlacing

+

Deinterlacing is automatically supported when frames are tagged as interlaced, +however frames are not deinterlaced unless a deinterlacing algorithm is chosen. +

+
deinterlace
+

The the deinterlacing algorithm to use. +

+
‘weave’
+

No deinterlacing, weave fields together into a single frame. This is the default. +

+
‘bob’
+

Naive bob deinterlacing, simply repeat each field line twice. +

+
‘yadif’
+

Yet another deinterlacing filter. See the yadif filter for more details. +

+
‘bwdif’
+

Bob weaver deinterlacing filter. See the bwdif filter for more details. +

+
+ +
+
skip_spatial_check
+

Skip the spatial deinterlacing check when using yadif deinterlacing. +

+
+
send_fields
+

Output a frame for each field, rather than for each frame. Note that this will +always double the tagged output frame rate, even if the input does not contain +any interlaced frames. Disabled by default. +

+
+ + +

11.144.1.4 Debanding

+

Libplacebo comes with a built-in debanding filter that is good at counteracting +many common sources of banding and blocking. Turning this on is highly +recommended whenever quality is desired. +

+
deband
+

Enable (fast) debanding algorithm. Disabled by default. +

+
+
deband_iterations
+

Number of deband iterations of the debanding algorithm. Each iteration is +performed with progressively increased radius (and diminished threshold). +Recommended values are in the range 1 to 4. Defaults to 1. +

+
+
deband_threshold
+

Debanding filter strength. Higher numbers lead to more aggressive debanding. +Defaults to 4.0. +

+
+
deband_radius
+

Debanding filter radius. A higher radius is better for slow gradients, while +a lower radius is better for steep gradients. Defaults to 16.0. +

+
+
deband_grain
+

Amount of extra output grain to add. Helps hide imperfections. Defaults to +6.0. +

+
+ + +

11.144.1.5 Color adjustment

+

A collection of subjective color controls. Not very rigorous, so the exact +effect will vary somewhat depending on the input primaries and colorspace. +

+
brightness
+

Brightness boost, between -1.0 and 1.0. Defaults to 0.0. +

+
+
contrast
+

Contrast gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
saturation
+

Saturation gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
hue
+

Hue shift in radians, between -3.14 and 3.14. Defaults to +0.0. This will rotate the UV subvector, defaulting to BT.709 +coefficients for RGB inputs. +

+
+
gamma
+

Gamma adjustment, between 0.0 and 16.0. Defaults to 1.0. +

+
+
temperature
+

Color temperature adjustment. Lower values make the output warmer/redder, +down to 1667, while higher values make the output cooler/bluer, up to +25000. Defaults to 6500 (neutral white). +

+
+
cones
+

Cone model to use for color blindness simulation. Accepts any combination of +l, m and s. Here are some examples: +

+
‘m’
+

Deuteranomaly / deuteranopia (affecting 3%-4% of the population) +

+
‘l’
+

Protanomaly / protanopia (affecting 1%-2% of the population) +

+
‘l+m’
+

Monochromacy (very rare) +

+
‘l+m+s’
+

Achromatopsy (complete loss of daytime vision, extremely rare) +

+
+ +
+
cone-strength
+

Gain factor for the cones specified by cones, between 0.0 and +10.0. A value of 1.0 results in no change to color vision. A +value of 0.0 (the default) simulates complete loss of those cones. Values +above 1.0 result in exaggerating the differences between cones, which +may help compensate for reduced color vision. +

+
+ + +

11.144.1.6 Peak detection

+

To help deal with sources that only have static HDR10 metadata (or no tagging +whatsoever), libplacebo uses its own internal frame analysis compute shader to +analyze source frames and adapt the tone mapping function in realtime. If this +is too slow, or if exactly reproducible frame-perfect results are needed, it’s +recommended to turn this feature off. +

+
peak_detect
+

Enable HDR peak detection. Ignores static MaxCLL/MaxFALL values in favor of +dynamic detection from the input. Note that the detected values do not get +written back to the output frames, they merely guide the internal tone mapping +process. Enabled by default. +

+
+
smoothing_period
+

Peak detection smoothing period, between 0.0 and 1000.0. Higher +values result in peak detection becoming less responsive to changes in the +input. Defaults to 20.0. +

+
+
scene_threshold_low
+
scene_threshold_high
+

Lower and upper thresholds for scene change detection. Expressed in a +logarithmic scale between 0.0 and 100.0. Default to 1.0 +and 3.0, respectively. Setting either to a negative value disables +this functionality. +

+
+
percentile
+

Which percentile of the frame brightness histogram to use as the source peak +for tone-mapping. Defaults to 99.995, a fairly conservative value. +Setting this to 100.0 disables frame histogram measurement and instead +uses the true peak brightness for tone-mapping. +

+
+ + +

11.144.1.7 Tone mapping

+

The options in this section control how libplacebo performs tone-mapping and +gamut-mapping when dealing with mismatches between wide-gamut or HDR content. +In general, libplacebo relies on accurate source tagging and mastering display +gamut information to produce the best results. +

+
gamut_mode
+

How to handle out-of-gamut colors that can occur as a result of colorimetric +gamut mapping. +

+
‘clip’
+

Do nothing, simply clip out-of-range colors to the RGB volume. Low quality but +extremely fast. +

+
‘perceptual’
+

Perceptually soft-clip colors to the gamut volume. This is the default. +

+
‘relative’
+

Relative colorimetric hard-clip. Similar to perceptual but without +the soft knee. +

+
‘saturation’
+

Saturation mapping, maps primaries directly to primaries in RGB space. +Not recommended except for artificial computer graphics for which a bright, +saturated display is desired. +

+
‘absolute’
+

Absolute colorimetric hard-clip. Performs no adjustment of the white point. +

+
‘desaturate’
+

Hard-desaturates out-of-gamut colors towards white, while preserving the +luminance. Has a tendency to distort the visual appearance of bright objects. +

+
‘darken’
+

Linearly reduces content brightness to preserves saturated details, followed by +clipping the remaining out-of-gamut colors. +

+
‘warn’
+

Highlight out-of-gamut pixels (by inverting/marking them). +

+
‘linear’
+

Linearly reduces chromaticity of the entire image to make it fit within the +target color volume. Be careful when using this on BT.2020 sources without +proper mastering metadata, as doing so will lead to excessive desaturation. +

+
+ +
+
tonemapping
+

Tone-mapping algorithm to use. Available values are: +

+
‘auto’
+

Automatic selection based on internal heuristics. This is the default. +

+
‘clip’
+

Performs no tone-mapping, just clips out-of-range colors. Retains perfect color +accuracy for in-range colors but completely destroys out-of-range information. +Does not perform any black point adaptation. Not configurable. +

+
‘st2094-40’
+

EETF from SMPTE ST 2094-40 Annex B, which applies the Bezier curves from HDR10+ +dynamic metadata based on Bezier curves to perform tone-mapping. The OOTF used +is adjusted based on the ratio between the targeted and actual display peak +luminances. +

+
‘st2094-10’
+

EETF from SMPTE ST 2094-10 Annex B.2, which takes into account the input signal +average luminance in addition to the maximum/minimum. The configurable contrast +parameter influences the slope of the linear output segment, defaulting to +1.0 for no increase/decrease in contrast. Note that this does not +currently include the subjective gain/offset/gamma controls defined in Annex +B.3. +

+
‘bt.2390’
+

EETF from the ITU-R Report BT.2390, a hermite spline roll-off with linear +segment. The knee point offset is configurable. Note that this parameter +defaults to 1.0, rather than the value of 0.5 from the ITU-R +spec. +

+
‘bt.2446a’
+

EETF from ITU-R Report BT.2446, method A. Designed for well-mastered HDR +sources. Can be used for both forward and inverse tone mapping. Not +configurable. +

+
‘spline’
+

Simple spline consisting of two polynomials, joined by a single pivot point. +The parameter gives the pivot point (in PQ space), defaulting to 0.30. +Can be used for both forward and inverse tone mapping. +

+
‘reinhard’
+

Simple non-linear, global tone mapping algorithm. The parameter specifies the +local contrast coefficient at the display peak. Essentially, a parameter of +0.5 implies that the reference white will be about half as bright as +when clipping. Defaults to 0.5, which results in the simplest +formulation of this function. +

+
‘mobius’
+

Generalization of the reinhard tone mapping algorithm to support an additional +linear slope near black. The tone mapping parameter indicates the trade-off +between the linear section and the non-linear section. Essentially, for a given +parameter x, every color value below x will be mapped linearly, +while higher values get non-linearly tone-mapped. Values near 1.0 make +this curve behave like clip, while values near 0.0 make this +curve behave like reinhard. The default value is 0.3, which +provides a good balance between colorimetric accuracy and preserving +out-of-gamut details. +

+
‘hable’
+

Piece-wise, filmic tone-mapping algorithm developed by John Hable for use in +Uncharted 2, inspired by a similar tone-mapping algorithm used by Kodak. +Popularized by its use in video games with HDR rendering. Preserves both dark +and bright details very well, but comes with the drawback of changing the +average brightness quite significantly. This is sort of similar to +reinhard with parameter 0.24. +

+
‘gamma’
+

Fits a gamma (power) function to transfer between the source and target color +spaces, effectively resulting in a perceptual hard-knee joining two roughly +linear sections. This preserves details at all scales fairly accurately, but +can result in an image with a muted or dull appearance. The parameter is used +as the cutoff point, defaulting to 0.5. +

+
‘linear’
+

Linearly stretches the input range to the output range, in PQ space. This will +preserve all details accurately, but results in a significantly different +average brightness. Can be used for inverse tone-mapping in addition to regular +tone-mapping. The parameter can be used as an additional linear gain +coefficient (defaulting to 1.0). +

+
+ +
+
tonemapping_param
+

For tunable tone mapping functions, this parameter can be used to fine-tune the +curve behavior. Refer to the documentation of tonemapping. The default +value of 0.0 is replaced by the curve’s preferred default setting. +

+
+
inverse_tonemapping
+

If enabled, this filter will also attempt stretching SDR signals to fill HDR +output color volumes. Disabled by default. +

+
+
tonemapping_lut_size
+

Size of the tone-mapping LUT, between 2 and 1024. Defaults to +256. Note that this figure is squared when combined with +peak_detect. +

+
+
contrast_recovery
+

Contrast recovery strength. If set to a value above 0.0, the source +image will be divided into high-frequency and low-frequency components, and a +portion of the high-frequency image is added back onto the tone-mapped output. +May cause excessive ringing artifacts for some HDR sources, but can improve the +subjective sharpness and detail left over in the image after tone-mapping. +Defaults to 0.30. +

+
+
contrast_smoothness
+

Contrast recovery lowpass kernel size. Defaults to 3.5. Increasing or +decreasing this will affect the visual appearance substantially. Has no effect +when contrast_recovery is disabled. +

+
+ + +

11.144.1.8 Dithering

+

By default, libplacebo will dither whenever necessary, which includes rendering +to any integer format below 16-bit precision. It’s recommended to always leave +this on, since not doing so may result in visible banding in the output, even +if the debanding filter is enabled. If maximum performance is needed, +use ordered_fixed instead of disabling dithering. +

+
dithering
+

Dithering method to use. Accepts the following values: +

+
‘none’
+

Disables dithering completely. May result in visible banding. +

+
‘blue’
+

Dither with pseudo-blue noise. This is the default. +

+
‘ordered’
+

Tunable ordered dither pattern. +

+
‘ordered_fixed’
+

Faster ordered dither with a fixed size of 6. Texture-less. +

+
‘white’
+

Dither with white noise. Texture-less. +

+
+ +
+
dither_lut_size
+

Dither LUT size, as log base2 between 1 and 8. Defaults to +6, corresponding to a LUT size of 64x64. +

+
+
dither_temporal
+

Enables temporal dithering. Disabled by default. +

+
+ + +

11.144.1.9 Custom shaders

+

libplacebo supports a number of custom shaders based on the mpv .hook GLSL +syntax. A collection of such shaders can be found here: +https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders +

+

A full description of the mpv shader format is beyond the scope of this +section, but a summary can be found here: +https://mpv.io/manual/master/#options-glsl-shader +

+
custom_shader_path
+

Specifies a path to a custom shader file to load at runtime. +

+
+
custom_shader_bin
+

Specifies a complete custom shader as a raw string. +

+
+ + +

11.144.1.10 Debugging / performance

+

All of the options in this section default off. They may be of assistance when +attempting to squeeze the maximum performance at the cost of quality. +

+
skip_aa
+

Disable anti-aliasing when downscaling. +

+
+
disable_linear
+

Disable linear light scaling. +

+
+
disable_builtin
+

Disable built-in GPU sampling (forces LUT). +

+
+
disable_fbos
+

Forcibly disable FBOs, resulting in loss of almost all functionality, but +offering the maximum possible speed. +

+
+ + +

11.144.2 Commands

+

This filter supports almost all of the above options as commands. +

+ +

11.144.3 Examples

+
    +
  • Tone-map input to standard gamut BT.709 output: +
    +
    libplacebo=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv
    +
    + +
  • Rescale input to fit into standard 1080p, with high quality scaling: +
    +
    libplacebo=w=1920:h=1080:force_original_aspect_ratio=decrease:normalize_sar=true:upscaler=ewa_lanczos:downscaler=ewa_lanczos
    +
    + +
  • Interpolate low FPS / VFR input to smoothed constant 60 fps output: +
    +
    libplacebo=fps=60:frame_mixer=mitchell_clamp
    +
    + +
  • Convert input to standard sRGB JPEG: +
    +
    libplacebo=format=yuv420p:colorspace=bt470bg:color_primaries=bt709:color_trc=iec61966-2-1:range=pc
    +
    + +
  • Use higher quality debanding settings: +
    +
    libplacebo=deband=true:deband_iterations=3:deband_radius=8:deband_threshold=6
    +
    + +
  • Run this filter on the CPU, on systems with Mesa installed (and with the most +expensive options disabled): +
    +
    ffmpeg ... -init_hw_device vulkan:llvmpipe ... -vf libplacebo=upscaler=none:downscaler=none:peak_detect=false
    +
    + +
  • Suppress CPU-based AV1/H.274 film grain application in the decoder, in favor of +doing it with this filter. Note that this is only a gain if the frames are +either already on the GPU, or if you’re using libplacebo for other purposes, +since otherwise the VRAM roundtrip will more than offset any expected speedup. +
    +
    ffmpeg -export_side_data +film_grain ... -vf libplacebo=apply_filmgrain=true
    +
    + +
  • Interop with VAAPI hwdec to avoid round-tripping through RAM: +
    +
    ffmpeg -init_hw_device vulkan -hwaccel vaapi -hwaccel_output_format vaapi ... -vf libplacebo
    +
    +
+ + +

11.145 libvmaf

+ +

Calculate the VMAF (Video Multi-Method Assessment Fusion) score for a +reference/distorted pair of input videos. +

+

The first input is the distorted video, and the second input is the reference video. +

+

The obtained VMAF score is printed through the logging system. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-libvmaf. +

+

The filter has following options: +

+
+
model
+

A ‘|‘ delimited list of vmaf models. Each model can be configured with a number of parameters. +Default value: "version=vmaf_v0.6.1" +

+
+
feature
+

A ‘|‘ delimited list of features. Each feature can be configured with a number of parameters. +

+
+
log_path
+

Set the file path to be used to store log files. +

+
+
log_fmt
+

Set the format of the log file (xml, json, csv, or sub). +

+
+
pool
+

Set the pool method to be used for computing vmaf. +Options are min, harmonic_mean or mean (default). +

+
+
n_threads
+

Set number of threads to be used when initializing libvmaf. +Default value: 0, no threads. +

+
+
n_subsample
+

Set frame subsampling interval to be used. +

+
+ +

This filter also supports the framesync options. +

+ +

11.145.1 Examples

+
    +
  • In the examples below, a distorted video distorted.mpg is +compared with a reference file reference.mpg. + +
  • Basic usage: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf=log_path=output.xml -f null -
    +
    + +
  • Example with multiple models: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='model=version=vmaf_v0.6.1\\:name=vmaf|version=vmaf_v0.6.1neg\\:name=vmaf_neg' -f null -
    +
    + +
  • Example with multiple additional features: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr|name=ciede' -f null -
    +
    + +
  • Example with options and different containers: +
    +
    ffmpeg -i distorted.mpg -i reference.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=log_fmt=json:log_path=output.json" -f null -
    +
    +
+ + +

11.146 libvmaf_cuda

+ +

This is the CUDA variant of the libvmaf filter. It only accepts CUDA frames. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-nonfree --enable-ffnvcodec --enable-libvmaf. +

+ +

11.146.1 Examples

+
    +
  • Basic usage showing CUVID hardware decoding and CUDA scaling with scale_cuda: +
    +
    ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i dis.obu \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i ref.obu \
    +    -filter_complex "
    +        [0:v]scale_cuda=format=yuv420p[dis]; \
    +        [1:v]scale_cuda=format=yuv420p[ref]; \
    +        [dis][ref]libvmaf_cuda=log_fmt=json:log_path=output.json
    +    " \
    +    -f null -
    +
    +
+ + +

11.147 limitdiff

+

Apply limited difference filter using second and optionally third video stream. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the threshold to use when allowing certain differences between video streams. +Any absolute difference value lower or exact than this threshold will pick pixel components from +first video stream. +

+
+
elasticity
+

Set the elasticity of soft thresholding when processing video streams. +This value multiplied with first one sets second threshold. +Any absolute difference value greater or exact than second threshold will pick pixel components +from second video stream. For values between those two threshold +linear interpolation between first and second video stream will be used. +

+
+
reference
+

Enable the reference (third) video stream processing. By default is disabled. +If set, this video stream will be used for calculating absolute difference with first video +stream. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

11.147.1 Commands

+ +

This filter supports the all above options as commands except option ‘reference’. +

+ +

11.148 limiter

+ +

Limits the pixel components values to the specified range [min, max]. +

+

The filter accepts the following options: +

+
+
min
+

Lower bound. Defaults to the lowest allowed value for the input. +

+
+
max
+

Upper bound. Defaults to the highest allowed value for the input. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

11.148.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.149 loop

+ +

Loop video frames. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal size in number of frames. Default is 0. +

+
+
start
+

Set first frame of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

11.149.1 Examples

+ +
    +
  • Loop single first frame infinitely: +
    +
    loop=loop=-1:size=1:start=0
    +
    + +
  • Loop single first frame 10 times: +
    +
    loop=loop=10:size=1:start=0
    +
    + +
  • Loop 10 first frames 5 times: +
    +
    loop=loop=5:size=10:start=0
    +
    +
+ + +

11.150 lut1d

+ +

Apply a 1D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 1D LUT file name. +

+

Currently supported formats: +

+
‘cube’
+

Iridas +

+
‘csp’
+

cineSpace +

+
+ +
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘linear’
+

Interpolate values using the linear interpolation. +

+
‘cosine’
+

Interpolate values using the cosine interpolation. +

+
‘cubic’
+

Interpolate values using the cubic interpolation. +

+
‘spline’
+

Interpolate values using the spline interpolation. +

+
+
+
+ + +

11.150.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.151 lut3d

+ +

Apply a 3D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 3D LUT file name. +

+

Currently supported formats: +

+
‘3dl’
+

AfterEffects +

+
‘cube’
+

Iridas +

+
‘dat’
+

DaVinci +

+
‘m3d’
+

Pandora +

+
‘csp’
+

cineSpace +

+
+
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘trilinear’
+

Interpolate values using the 8 points defining a cube. +

+
‘tetrahedral’
+

Interpolate values using a tetrahedron. +

+
‘pyramid’
+

Interpolate values using a pyramid. +

+
‘prism’
+

Interpolate values using a prism. +

+
+
+
+ + +

11.151.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

11.152 lumakey

+ +

Turn certain luma values into transparency. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the luma which will be used as base for transparency. +Default value is 0. +

+
+
tolerance
+

Set the range of luma values to be keyed out. +Default value is 0.01. +

+
+
softness
+

Set the range of softness. Default value is 0. +Use this to control gradual transition from zero to full transparency. +

+
+ + +

11.152.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.153 lut, lutrgb, lutyuv

+ +

Compute a look-up table for binding each pixel component input value +to an output value, and apply it to the input video. +

+

lutyuv applies a lookup table to a YUV input video, lutrgb +to an RGB input video. +

+

These filters accept the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
r
+

set red component expression +

+
g
+

set green component expression +

+
b
+

set blue component expression +

+
a
+

alpha component expression +

+
+
y
+

set Y/luma component expression +

+
u
+

set U/Cb component expression +

+
v
+

set V/Cr component expression +

+
+ +

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 c* options depends on the +format in input. +

+

The lut filter requires either YUV or RGB pixel formats in input, +lutrgb requires RGB pixel formats in input, and lutyuv requires YUV. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
clipval
+

The input value, clipped to the minval-maxval range. +

+
+
maxval
+

The maximum value for the pixel component. +

+
+
minval
+

The minimum value for the pixel component. +

+
+
negval
+

The negated value for the pixel component value, clipped to the +minval-maxval range; it corresponds to the expression +"maxval-clipval+minval". +

+
+
clip(val)
+

The computed value in val, clipped to the +minval-maxval range. +

+
+
gammaval(gamma)
+

The computed gamma correction value of the pixel component value, +clipped to the minval-maxval range. It corresponds to the +expression +"pow((clipval-minval)/(maxval-minval)\,gamma)*(maxval-minval)+minval" +

+
+
+ +

All expressions default to "clipval". +

+ +

11.153.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.153.2 Examples

+ +
    +
  • Negate input video: +
    +
    lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
    +lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
    +
    + +

    The above is the same as: +

    +
    lutrgb="r=negval:g=negval:b=negval"
    +lutyuv="y=negval:u=negval:v=negval"
    +
    + +
  • Negate luma: +
    +
    lutyuv=y=negval
    +
    + +
  • Remove chroma components, turning the video into a graytone image: +
    +
    lutyuv="u=128:v=128"
    +
    + +
  • Apply a luma burning effect: +
    +
    lutyuv="y=2*val"
    +
    + +
  • Remove green and blue components: +
    +
    lutrgb="g=0:b=0"
    +
    + +
  • Set a constant alpha channel value on input: +
    +
    format=rgba,lutrgb=a="maxval-minval/2"
    +
    + +
  • Correct luma gamma by a factor of 0.5: +
    +
    lutyuv=y=gammaval(0.5)
    +
    + +
  • Discard least significant bits of luma: +
    +
    lutyuv=y='bitand(val, 128+64+32)'
    +
    + +
  • Technicolor like effect: +
    +
    lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
    +
    +
+ + +

11.154 lut2, tlut2

+ +

The lut2 filter takes two input streams and outputs one +stream. +

+

The tlut2 (time lut2) filter takes two consecutive frames +from one single stream. +

+

This filter accepts the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
d
+

set output bit depth, only available for lut2 filter. By default is 0, +which means bit depth is automatically picked from first input format. +

+
+ +

The lut2 filter also supports the framesync options. +

+

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 c* options depends on the +format in inputs. +

+

The expressions can contain the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
x
+

The first input value for the pixel component. +

+
+
y
+

The second input value for the pixel component. +

+
+
bdx
+

The first input video bit depth. +

+
+
bdy
+

The second input video bit depth. +

+
+ +

All expressions default to "x". +

+ +

11.154.1 Commands

+ +

This filter supports the all above options as commands except option d. +

+ +

11.154.2 Examples

+ +
    +
  • Highlight differences between two RGB video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'
    +
    + +
  • Highlight differences between two YUV video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'
    +
    + +
  • Show max difference between two video streams: +
    +
    lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'
    +
    +
+ + +

11.155 maskedclamp

+ +

Clamp the first input stream with the second input and third input stream. +

+

Returns the value of first stream to be between second input +stream - undershoot and third input stream + overshoot. +

+

This filter accepts the following options: +

+
undershoot
+

Default value is 0. +

+
+
overshoot
+

Default value is 0. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

11.155.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.156 maskedmax

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is greater than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

11.156.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.157 maskedmerge

+ +

Merge the first input stream with the second input stream using per pixel +weights in the third input stream. +

+

A value of 0 in the third stream pixel component means that pixel component +from first stream is returned unchanged, while maximum value (eg. 255 for +8-bit videos) means that pixel component from second stream is returned +unchanged. Intermediate values define the amount of merging between both +input stream’s pixel components. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

11.157.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.158 maskedmin

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is less than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

11.158.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.159 maskedthreshold

+

Pick pixels comparing absolute difference of two video streams with fixed +threshold. +

+

If absolute difference between pixel component of first and second video +stream is equal or lower than user supplied threshold than pixel component +from first video stream is picked, otherwise pixel component from second +video stream is picked. +

+

This filter accepts the following options: +

+
threshold
+

Set threshold used when picking pixels from absolute difference from two input +video streams. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from second stream. +By default value 0xf, all planes will be processed. +

+
+
mode
+

Set mode of filter operation. Can be abs or diff. +Default is abs. +

+
+ + +

11.159.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.160 maskfun

+

Create mask from input video. +

+

For example it is useful to create motion masks after tblend filter. +

+

This filter accepts the following options: +

+
+
low
+

Set low threshold. Any pixel component lower or exact than this value will be set to 0. +

+
+
high
+

Set high threshold. Any pixel component higher than this value will be set to max value +allowed for current pixel format. +

+
+
planes
+

Set planes to filter, by default all available planes are filtered. +

+
+
fill
+

Fill all frame pixels with this value. +

+
+
sum
+

Set max average pixel value for frame. If sum of all pixel components is higher that this +average, output frame will be completely filled with value set by fill option. +Typically useful for scene changes when used in combination with tblend filter. +

+
+ + +

11.160.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.161 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: +

+
mode
+

Set the deinterlacing mode. +

+

It accepts one of the following values: +

+
‘fast’
+
‘medium’
+
‘slow’
+

use iterative motion estimation +

+
‘extra_slow’
+

like ‘slow’, but use multiple reference frames. +

+
+

Default value is ‘fast’. +

+
+
parity
+

Set the picture field parity assumed for the input video. It must be +one of the following values: +

+
+
‘0, tff’
+

assume top field first +

+
‘1, bff’
+

assume bottom field first +

+
+ +

Default value is ‘bff’. +

+
+
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. +

+
+ + +

11.162 median

+ +

Pick median pixel from certain rectangle defined by radius. +

+

This filter accepts the following options: +

+
+
radius
+

Set horizontal radius size. Default value is 1. +Allowed range is integer from 1 to 127. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+
radiusV
+

Set vertical radius size. Default value is 0. +Allowed range is integer from 0 to 127. +If it is 0, value will be picked from horizontal radius option. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

11.162.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.163 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: +

+
mapping
+

Set input to output plane mapping. Default is 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. +

+
+
format
+

Set output pixel format. Default is yuva444p. +

+
+
map0s
+
map1s
+
map2s
+
map3s
+

Set input to output stream mapping for output Nth plane. Default is 0. +

+
+
map0p
+
map1p
+
map2p
+
map3p
+

Set input to output plane mapping for output Nth plane. Default is 0. +

+
+ + +

11.163.1 Examples

+ +
    +
  • Merge three gray video streams of same width and height into single video stream: +
    +
    [a0][a1][a2]mergeplanes=0x001020:yuv444p
    +
    + +
  • Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: +
    +
    [a0][a1]mergeplanes=0x00010210:yuva444p
    +
    + +
  • Swap Y and A plane in yuva444p stream: +
    +
    format=yuva444p,mergeplanes=0x03010200:yuva444p
    +
    + +
  • Swap U and V plane in yuv420p stream: +
    +
    format=yuv420p,mergeplanes=0x000201:yuv420p
    +
    + +
  • Cast a rgb24 clip to yuv444p: +
    +
    format=rgb24,mergeplanes=0x000102:yuv444p
    +
    +
+ + +

11.164 mestimate

+ +

Estimate and export motion vectors using block matching algorithms. +Motion vectors are stored in frame side data to be used by other filters. +

+

This filter accepts the following options: +

+
method
+

Specify the motion estimation method. Accepts one of the following values: +

+
+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default value is ‘esa’. +

+
+
mb_size
+

Macroblock size. Default 16. +

+
+
search_param
+

Search parameter. Default 7. +

+
+ + +

11.165 mestimate_d3d12

+ +

Estimate and export motion vectors using D3D12 hardware-accelerated motion estimation. +This filter uses GPU hardware motion estimation capabilities available in +DirectX 12 Video APIs to achieve significant performance improvements +over the software-based mestimate filter. +

+

Motion vectors are stored in frame side data to be used by other filters. +

+

This filter requires the input to be in d3d12 hardware pixel format. +The filter uses quarter-pixel precision for motion vector estimation. +

+

This filter accepts the following options: +

+
mb_size
+

Macroblock size. Only 8 and 16 are supported. +Default 16. +

+
+ + +

11.165.1 Examples

+ +

Estimate motion vectors using D3D12 hardware acceleration with 16x16 blocks, +and visualize them: +

+
ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.mp4 \
+        -vf mestimate_d3d12=mb_size=16,hwdownload,format=nv12,codecview=mv=pf \
+        -c:v libx264 -preset fast -b:v 5M output.mp4
+
+ + +

11.166 midequalizer

+ +

Apply Midway Image Equalization effect using two video streams. +

+

Midway Image Equalization adjusts a pair of images to have the same +histogram, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a pair of stereo cameras. +

+

This filter has two inputs and one output, which must be of same pixel format, but +may be of different sizes. The output of filter is first input adjusted with +midway histogram of both inputs. +

+

This filter accepts the following option: +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

11.167 minterpolate

+ +

Convert the video to specified frame rate using motion interpolation. +

+

This filter accepts the following options: +

+
fps
+

Specify the output frame rate. This can be rational e.g. 60000/1001. Frames are dropped if fps is lower than source fps. Default 60. +

+
+
mi_mode
+

Motion interpolation mode. Following values are accepted: +

+
‘dup’
+

Duplicate previous or next frame for interpolating new ones. +

+
‘blend’
+

Blend source frames. Interpolated frame is mean of previous and next frames. +

+
‘mci’
+

Motion compensated interpolation. Following options are effective when this mode is selected: +

+
+
‘mc_mode’
+

Motion compensation mode. Following values are accepted: +

+
‘obmc’
+

Overlapped block motion compensation. +

+
‘aobmc’
+

Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. +

+
+

Default mode is ‘obmc’. +

+
+
‘me_mode’
+

Motion estimation mode. Following values are accepted: +

+
‘bidir’
+

Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. +

+
‘bilat’
+

Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. +

+
+

Default mode is ‘bilat’. +

+
+
‘me’
+

The algorithm to be used for motion estimation. Following values are accepted: +

+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default algorithm is ‘epzs’. +

+
+
‘mb_size’
+

Macroblock size. Default 16. +

+
+
‘search_param’
+

Motion estimation search parameter. Default 32. +

+
+
‘vsbmc’
+

Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make them less blurry. Default is 0 (disabled). +

+
+
+
+ +
+
scd
+

Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted: +

+
‘none’
+

Disable scene change detection. +

+
‘fdiff’
+

Frame difference. Corresponding pixel values are compared and if it satisfies scd_threshold scene change is detected. +

+
+

Default method is ‘fdiff’. +

+
+
scd_threshold
+

Scene change detection threshold. Default is 10.. +

+
+ + +

11.168 mix

+ +

Mix several video input streams into one video stream. +

+

A description of the accepted options follows. +

+
+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
weights
+

Specify weight of each input video stream as sequence. +Each weight is separated by space. If number of weights +is smaller than number of frames last specified +weight will be used for all remaining unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+
duration
+

Specify how end of stream is determined. +

+
‘longest’
+

The duration of the longest input. (default) +

+
+
‘shortest’
+

The duration of the shortest input. +

+
+
‘first’
+

The duration of the first input. +

+
+
+
+ + +

11.168.1 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

11.169 monochrome

+

Convert video to gray using custom color filter. +

+

A description of the accepted options follows. +

+
+
cb
+

Set the chroma blue spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
cr
+

Set the chroma red spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
size
+

Set the color filter size. Allowed range is from .1 to 10. +Default value is 1. +

+
+
high
+

Set the highlights strength. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

11.169.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.170 morpho

+ +

This filter allows to apply main morphological grayscale transforms, +erode and dilate with arbitrary structures set in second input stream. +

+

Unlike naive implementation and much slower performance in erosion +and dilation filters, when speed is critical morpho filter +should be used instead. +

+

A description of accepted options follows, +

+
+
mode
+

Set morphological transform to apply, can be: +

+
+
‘erode’
+
‘dilate’
+
‘open’
+
‘close’
+
‘gradient’
+
‘tophat’
+
‘blackhat’
+
+

Default is erode. +

+
+
planes
+

Set planes to filter, by default all planes except alpha are filtered. +

+
+
structure
+

Set which structure video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+ +

The morpho filter also supports the framesync options. +

+ +

11.170.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.171 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. +

+
+
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 disregarding the +number of previous sequentially dropped frames. +

+

Default value is 0. +

+
+
keep
+

Set the maximum number of consecutive similar frames to ignore before to start dropping them. +If the value is 0, the frame is dropped disregarding the +number of previous sequentially similar frames. +

+

Default value is 0. +

+
+
hi
+
lo
+
frac
+

Set the dropping threshold values. +

+

Values for hi and 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 hi, and if no more than frac blocks (1 +meaning the whole image) differ by more than a threshold of lo. +

+

Default value for hi is 64*12, default value for lo is +64*5, and default value for frac is 0.33. +

+
+ + +

11.172 msad

+ +

Obtain the MSAD (Mean Sum of Absolute Differences) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max MSAD is printed through +the logging system. +

+

The filter stores the calculated MSAD of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi msad -f null -
+
+ + +

11.173 multiply

+

Multiply first video stream pixels values with second video stream pixels values. +

+

The filter accepts the following options: +

+
+
scale
+

Set the scale applied to second video stream. By default is 1. +Allowed range is from 0 to 9. +

+
+
offset
+

Set the offset applied to second video stream. By default is 0.5. +Allowed range is from -1 to 1. +

+
+
planes
+

Specify planes from input video stream that will be processed. +By default all planes are processed. +

+
+ + +

11.173.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.174 negate

+ +

Negate (invert) the input video. +

+

It accepts the following option: +

+
+
components
+

Set components to negate. +

+

Available values for components are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +
+
negate_alpha
+

With value 1, it negates the alpha component, if present. Default value is 0. +

+
+ + +

11.174.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.175 nlmeans

+ +

Denoise frames using Non-Local Means algorithm. +

+

Each pixel is adjusted by looking for other pixels with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +pxp. Patches are searched in an area of rxr +around the pixel. +

+

Note that the research area defines centers for patches, which means some +patches will be made of pixels outside that research area. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0]. +

+
+
p
+

Set patch size. Default is 7. Must be odd number in range [0, 99]. +

+
+
pc
+

Same as p but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
rc
+

Same as r but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+ + +

11.176 nnedi

+ +

Deinterlace video using neural network edge directed interpolation. +

+

This filter accepts the following options: +

+
+
weights
+

Mandatory option, without binary file filter can not work. +Currently file can be found here: +https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin +

+
+
deint
+

Set which frames to deinterlace, by default it is all. +Can be all or interlaced. +

+
+
field
+

Set mode of operation. +

+

Can be one of the following: +

+
+
‘af’
+

Use frame flags, both fields. +

+
‘a’
+

Use frame flags, single field. +

+
‘t’
+

Use top field only. +

+
‘b’
+

Use bottom field only. +

+
‘tf’
+

Use both fields, top first. +

+
‘bf’
+

Use both fields, bottom first. +

+
+ +
+
planes
+

Set which planes to process, by default filter process all frames. +

+
+
nsize
+

Set size of local neighborhood around each pixel, used by the predictor neural +network. +

+

Can be one of the following: +

+
+
‘s8x6’
+
‘s16x6’
+
‘s32x6’
+
‘s48x6’
+
‘s8x4’
+
‘s16x4’
+
‘s32x4’
+
+ +
+
nns
+

Set the number of neurons in predictor neural network. +Can be one of the following: +

+
+
‘n16’
+
‘n32’
+
‘n64’
+
‘n128’
+
‘n256’
+
+ +
+
qual
+

Controls the number of different neural network predictions that are blended +together to compute the final output value. Can be fast, default or +slow. +

+
+
etype
+

Set which set of weights to use in the predictor. +Can be one of the following: +

+
+
‘a, abs’
+

weights trained to minimize absolute error +

+
‘s, mse’
+

weights trained to minimize squared error +

+
+ +
+
pscrn
+

Controls whether or not the prescreener neural network is used to decide +which pixels should be processed by the predictor neural network and which +can be handled by simple cubic interpolation. +The prescreener is trained to know whether cubic interpolation will be +sufficient for a pixel or whether it should be predicted by the predictor nn. +The computational complexity of the prescreener nn is much less than that of +the predictor nn. Since most pixels can be handled by cubic interpolation, +using the prescreener generally results in much faster processing. +The prescreener is pretty accurate, so the difference between using it and not +using it is almost always unnoticeable. +

+

Can be one of the following: +

+
+
‘none’
+
‘original’
+
‘new’
+
‘new2’
+
‘new3’
+
+ +

Default is new. +

+
+ + +

11.176.1 Commands

+

This filter supports same commands as options, excluding weights option. +

+ +

11.177 noformat

+ +

Force libavfilter not to use any of the specified pixel formats for the +input to the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +pix_fmts=yuv420p|monow|rgb24". +

+
+
+ + +

11.177.1 Examples

+ +
    +
  • Force libavfilter to use a format different from yuv420p for the +input to the vflip filter: +
    +
    noformat=pix_fmts=yuv420p,vflip
    +
    + +
  • Convert the input video to any of the formats not contained in the list: +
    +
    noformat=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

11.178 noise

+ +

Add noise on video input frame. +

+

The filter accepts the following options: +

+
+
all_seed
+
c0_seed
+
c1_seed
+
c2_seed
+
c3_seed
+

Set noise seed for specific pixel component or all pixel components in case +of all_seed. Default value is 123457. +

+
+
all_strength, alls
+
c0_strength, c0s
+
c1_strength, c1s
+
c2_strength, c2s
+
c3_strength, c3s
+

Set noise strength for specific pixel component or all pixel components in case +all_strength. Default value is 0. Allowed range is [0, 100]. +

+
+
all_flags, allf
+
c0_flags, c0f
+
c1_flags, c1f
+
c2_flags, c2f
+
c3_flags, c3f
+

Set pixel component flags or set flags for all components if all_flags. +Available values for component flags are: +

+
‘a’
+

averaged temporal noise (smoother) +

+
‘p’
+

mix random noise with a (semi)regular pattern +

+
‘t’
+

temporal noise (noise pattern changes between frames) +

+
‘u’
+

uniform noise (gaussian otherwise) +

+
+
+
+ + +

11.178.1 Examples

+ +

Add temporal and uniform noise to input video: +

+
noise=alls=20:allf=t+u
+
+ + +

11.179 normalize

+ +

Normalize RGB video (aka histogram stretching, contrast stretching). +See: https://en.wikipedia.org/wiki/Normalization_(image_processing) +

+

For each channel of each frame, the filter computes the input range and maps +it linearly to the user-specified output range. The output range defaults +to the full dynamic range from pure black to pure white. +

+

Temporal smoothing can be used on the input range to reduce flickering (rapid +changes in brightness) caused when small dark or bright objects enter or leave +the scene. This is similar to the auto-exposure (automatic gain control) on a +video camera, and, like a video camera, it may cause a period of over- or +under-exposure of the video. +

+

The R,G,B channels can be normalized independently, which may cause some +color shifting, or linked together as a single channel, which prevents +color shifting. Linked normalization preserves hue. Independent normalization +does not, so it can be used to remove some color casts. Independent and linked +normalization can be combined in any ratio. +

+

The normalize filter accepts the following options: +

+
+
blackpt
+
whitept
+

Colors which define the output range. The minimum input value is mapped to +the blackpt. The maximum input value is mapped to the whitept. +The defaults are black and white respectively. Specifying white for +blackpt and black for whitept will give color-inverted, +normalized video. Shades of grey can be used to reduce the dynamic range +(contrast). Specifying saturated colors here can create some interesting +effects. +

+
+
smoothing
+

The number of previous frames to use for temporal smoothing. The input range +of each channel is smoothed using a rolling average over the current frame +and the smoothing previous frames. The default is 0 (no temporal +smoothing). +

+
+
independence
+

Controls the ratio of independent (color shifting) channel normalization to +linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully +independent. Defaults to 1.0 (fully independent). +

+
+
strength
+

Overall strength of the filter. 1.0 is full strength. 0.0 is a rather +expensive no-op. Defaults to 1.0 (full strength). +

+
+
+ + +

11.179.1 Commands

+

This filter supports same commands as options, excluding smoothing option. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.179.2 Examples

+ +

Stretch video contrast to use the full dynamic range, with no temporal +smoothing; may flicker depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=0
+
+ +

As above, but with 50 frames of temporal smoothing; flicker should be +reduced, depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=50
+
+ +

As above, but with hue-preserving linked channel normalization: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0
+
+ +

As above, but with half strength: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
+
+ +

Map the darkest input color to red, the brightest input color to cyan: +

+
normalize=blackpt=red:whitept=cyan
+
+ + +

11.180 null

+ +

Pass the video source unchanged to the output. +

+ +

11.181 ocio

+

OpenColorIO library filter +

+

This filter allows you to do color management using the OpenColorIO library. +See https://opencolorio.org/ for more details. To Enable +compilation of this filter, you need to configure FFmpeg with --enable-libopencolorio. +

+

It accepts the following options: +

+
+
config
+

By default the filter will use the OCIO config defined by the OCIO environment variable, but this parameter allows you to explicitly specify its location. +If you are getting started, you can use config=ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1 which specifies one of the built in defaults. +

+
+
input
+

Set the input colorspace. +

+
+
output
+

Set the output colorspace. +

+
+
display
+

Set the display colorspace, used in combination with view. +

+
+
view
+

Set the view colorspace, used in combination with display. +

+
+
inverse
+

When used in combination with display and view, this inverts the transform, so going from a display/view to the "input colorspace". +

+
+
filetransform
+

Allows you to specify an external file-transform to use instead of the OCIO config file. This is useful for applying a single transform without needing a full OCIO config file. +

+
+
format
+

Allow you to specify the output pix_fmt of the OCIO filter. This *has* to be a RGB colorspace, so you really are limited to rgb24, rgba, rgb48, rgba48, gbrp10, gbrp12, gbrpf32le, gbrapf32le, for most encoding we would recommend rgb48 +

+
+
context_params
+

Allow you to specify additional context parameters for the OCIO filter. This is a list of key=value pairs, separated by colons. +

+
+
+ + +

11.181.1 Examples

+ +

Map from ACEScg to ACEScct, this assumes the OCIO file is defined with the OCIO environment variable. +

+
input=ACEScg:output=ACEScct:format=rgb48
+
+ +

Map from ACEScg to a sRGB display using the "ACES 1.0 - SDR Video" view transform, this assumes the OCIO file is defined with the OCIO environment variable. Note you will need to wrap the argument in quotes to ensure that the spaces are interpreted correctly. +

+
input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ + +

As above but using the OCIO file studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio rather than the OCIO environment variable. +

+
config=studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio:input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ +

If you are converting to YCrCb you still will want to set the color matrix for the conversion. This is a good example of combining the two. +

+
ffmpeg -y -i SOURCEFRAMES.%05d.exr -c:v libx265 -vf "ocio=input=ACEScg:output=ACEScct:format=rgb48,scale=in_color_matrix=bt709:out_color_matrix=bt709,format=yuv444p10"  OUTPUTFILE.mov
+
+ + +

11.182 ocr

+

Optical Character Recognition +

+

This filter uses Tesseract for optical character recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-libtesseract. +

+

It accepts the following options: +

+
+
datapath
+

Set datapath to tesseract data. Default is to use whatever was +set at installation. +

+
+
language
+

Set language, default is "eng". +

+
+
whitelist
+

Set character whitelist. +

+
+
blacklist
+

Set character blacklist. +

+
+ +

The filter exports recognized text as the frame metadata lavfi.ocr.text. +The filter exports confidence of recognized words as the frame metadata lavfi.ocr.confidence. +

+ +

11.183 ocv

+ +

Apply a video transform using libopencv. +

+

To enable this filter, install the libopencv library and headers and +configure FFmpeg with --enable-libopencv. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the libopencv filter to apply. +

+
+
filter_params
+

The parameters to pass to the libopencv filter. If not specified, the default +values are assumed. +

+
+
+ +

Refer to the official libopencv documentation for more precise +information: +http://docs.opencv.org/master/modules/imgproc/doc/filtering.html +

+

Several libopencv filters are supported; see the following subsections. +

+ +

11.183.1 dilate

+ +

Dilate an image by using a specific structuring element. +It corresponds to the libopencv function cvDilate. +

+

It accepts the parameters: struct_el|nb_iterations. +

+

struct_el represents a structuring element, and has the syntax: +colsxrows+anchor_xxanchor_y/shape +

+

cols and rows represent the number of columns and rows of +the structuring element, anchor_x and anchor_y the anchor +point, and shape the shape for the structuring element. shape +must be "rect", "cross", "ellipse", or "custom". +

+

If the value for shape is "custom", it must be followed by a +string of the form "=filename". The file with name +filename is assumed to represent a binary image, with each +printable character corresponding to a bright pixel. When a custom +shape is used, cols and rows are ignored, the number +or columns and rows of the read file are assumed instead. +

+

The default value for struct_el is "3x3+0x0/rect". +

+

nb_iterations specifies the number of times the transform is +applied to the image, and defaults to 1. +

+

Some examples: +

+
# Use the default values
+ocv=dilate
+
+# Dilate using a structuring element with a 5x5 cross, iterating two times
+ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
+
+# Read the shape from the file diamond.shape, iterating two times.
+# The file diamond.shape may contain a pattern of characters like this
+#   *
+#  ***
+# *****
+#  ***
+#   *
+# The specified columns and rows are ignored
+# but the anchor point coordinates are not
+ocv=dilate:0x0+2x2/custom=diamond.shape|2
+
+ + +

11.183.2 erode

+ +

Erode an image by using a specific structuring element. +It corresponds to the libopencv function cvErode. +

+

It accepts the parameters: struct_el:nb_iterations, +with the same syntax and semantics as the dilate filter. +

+ +

11.183.3 smooth

+ +

Smooth the input video. +

+

The filter takes the following parameters: +type|param1|param2|param3|param4. +

+

type is the type of smooth filter to apply, and must be one of +the following values: "blur", "blur_no_scale", "median", "gaussian", +or "bilateral". The default value is "gaussian". +

+

The meaning of param1, param2, param3, and param4 +depends on the smooth type. param1 and +param2 accept integer positive values or 0. param3 and +param4 accept floating point values. +

+

The default value for param1 is 3. The default value for the +other parameters is 0. +

+

These parameters correspond to the parameters assigned to the +libopencv function cvSmooth. +

+ +

11.184 oscilloscope

+ +

2D Video Oscilloscope. +

+

Useful to measure spatial impulse, step responses, chroma delays, etc. +

+

It accepts the following parameters: +

+
+
x
+

Set scope center x position. +

+
+
y
+

Set scope center y position. +

+
+
s
+

Set scope size, relative to frame diagonal. +

+
+
t
+

Set scope tilt/rotation. +

+
+
o
+

Set trace opacity. +

+
+
tx
+

Set trace center x position. +

+
+
ty
+

Set trace center y position. +

+
+
tw
+

Set trace width, relative to width of frame. +

+
+
th
+

Set trace height, relative to height of frame. +

+
+
c
+

Set which components to trace. By default it traces first three components. +

+
+
g
+

Draw trace grid. By default is enabled. +

+
+
st
+

Draw some statistics. By default is enabled. +

+
+
sc
+

Draw scope. By default is enabled. +

+
+ + +

11.184.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

11.184.2 Examples

+ +
    +
  • Inspect full first row of video frame. +
    +
    oscilloscope=x=0.5:y=0:s=1
    +
    + +
  • Inspect full last row of video frame. +
    +
    oscilloscope=x=0.5:y=1:s=1
    +
    + +
  • Inspect full 5th line of video frame of height 1080. +
    +
    oscilloscope=x=0.5:y=5/1080:s=1
    +
    + +
  • Inspect full last column of video frame. +
    +
    oscilloscope=x=1:y=0.5:s=1:t=1
    +
    + +
+ + +

11.185 overlay

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+

A description of the accepted options follows. +

+
+
x
+
y
+

Set the expression for the x and y coordinates of the overlaid video +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). +

+
+
eof_action
+

See framesync. +

+
+
eval
+

Set when the expressions for x, and y are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘frame’. +

+
+
shortest
+

See framesync. +

+
+
format
+

Set the format for the output video. +

+

It accepts the following values: +

+
‘yuv420’
+

force YUV 4:2:0 8-bit planar output +

+
+
‘yuv420p10’
+

force YUV 4:2:0 10-bit planar output +

+
+
‘yuv422’
+

force YUV 4:2:2 8-bit planar output +

+
+
‘yuv422p10’
+

force YUV 4:2:2 10-bit planar output +

+
+
‘yuv444’
+

force YUV 4:4:4 8-bit planar output +

+
+
‘yuv444p10’
+

force YUV 4:4:4 10-bit planar output +

+
+
‘rgb’
+

force RGB 8-bit packed output +

+
+
‘gbrp’
+

force RGB 8-bit planar output +

+
+
‘auto’
+

automatically pick format +

+
+ +

Default value is ‘yuv420’. +

+
+
repeatlast
+

See framesync. +

+
+
alpha
+

Set format of alpha of the overlaid video, it can be straight or +premultiplied, or auto to choose the alpha mode automatically. +Default is auto. +

+
+ +

The x, and y expressions can contain the following +parameters. +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values of the output +format. For example for the pixel format "yuv422p" hsub is 2 and +vsub is 1. +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp, expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

This filter also supports the framesync options. +

+

Note that the n, t variables are available only +when evaluation is done per frame, and will evaluate to NAN +when eval is set to ‘init’. +

+

Be aware that frames are taken from each input video in timestamp +order, hence, if their initial timestamps differ, it is a good idea +to pass the two inputs through a setpts=PTS-STARTPTS filter to +have them begin in the same zero timestamp, as the example for +the movie filter does. +

+

You can chain together more overlays but you should test the +efficiency of such approach. +

+ +

11.185.1 Commands

+ +

This filter supports the following commands: +

+
x
+
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. +

+
+ + +

11.185.2 Examples

+ +
    +
  • Draw the overlay at 10 pixels from the bottom right corner of the main +video: +
    +
    overlay=main_w-overlay_w-10:main_h-overlay_h-10
    +
    + +

    Using named options the example above becomes: +

    +
    overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
    +
    + +
  • Insert a transparent PNG logo in the bottom left corner of the input, +using the ffmpeg tool with the -filter_complex option: +
    +
    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 ffmpeg tool: +
    +
    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
    +
    + +
  • Add a transparent color layer on top of the main video; WxH +must specify the size of the main input to the overlay filter: +
    +
    color=color=red@.3:size=WxH [over]; [in][over] overlay [out]
    +
    + +
  • Play an original video and a filtered version (here with the deshake +filter) side by side using the ffplay tool: +
    +
    ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
    +
    + +

    The above command is the same as: +

    +
    ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
    +
    + +
  • Make a sliding overlay appearing from the left to the right top part of the +screen starting since time 2: +
    +
    overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
    +
    + +
  • Compose output by putting two input videos side to side: +
    +
    ffmpeg -i left.avi -i right.avi -filter_complex "
    +nullsrc=size=200x100 [background];
    +[0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
    +[1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
    +[background][left]       overlay=shortest=1       [background+left];
    +[background+left][right] overlay=shortest=1:x=100 [left+right]
    +"
    +
    + +
  • Mask 10-20 seconds of a video by applying the delogo filter to a section +
    +
    ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
    +-vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
    +masked.avi
    +
    + +
  • Chain several overlays in cascade: +
    +
    nullsrc=s=200x200 [bg];
    +testsrc=s=100x100, split=4 [in0][in1][in2][in3];
    +[in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
    +[in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
    +[in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
    +[in3] null,       [mid2] overlay=100:100 [out0]
    +
    + +
+ + +

11.186 owdenoise

+ +

Apply Overcomplete Wavelet denoiser. +

+

The filter accepts the following options: +

+
+
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 8. +

+
+
luma_strength, ls
+

Set luma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+
chroma_strength, cs
+

Set chroma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+ + +

11.187 pad

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following parameters: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

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 color is "black". +

+
+
eval
+

Specify when to evaluate width, height, x and y expression. +

+

It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when +a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+
+
aspect
+

Pad to aspect instead to a resolution. +

+
+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

11.187.1 Examples

+ +
    +
  • Add paddings with the color "violet" to the input video. The output video +size is 640x480, and the top-left corner of the input video is placed at +column 0, row 40 +
    +
    pad=640:480:0:40:violet
    +
    + +

    The example above is equivalent to the following command: +

    +
    pad=width=640:height=480:x=0:y=40:color=violet
    +
    + +
  • Pad the input to get an output with dimensions increased by 3/2, +and put the input video at the center of the padded area: +
    +
    pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a squared output with size equal to the maximum +value between the input width and height, and put the input video at +the center of the padded area: +
    +
    pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a final w/h ratio of 16:9: +
    +
    pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • In case of anamorphic video, in order to set the output display aspect +correctly, it is necessary to use sar in the expression, +according to the relation: +
    +
    (ih * X / ih) * sar = output_dar
    +X = output_dar / sar
    +
    + +

    Thus the previous example needs to be modified to: +

    +
    pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Double the output size and put the input video in the bottom-right +corner of the output padded area: +
    +
    pad="2*iw:2*ih:ow-iw:oh-ih"
    +
    +
+ + +

11.188 palettegen

+ +

Generate one palette for a whole video stream. +

+

It accepts the following options: +

+
+
max_colors
+

Set the maximum number of colors to quantize in the palette. +Note: the palette will still contain 256 colors; the unused palette entries +will be black. +

+
+
reserve_transparent
+

Create a palette of 255 colors maximum and reserve the last one for +transparency. Reserving the transparency color is useful for GIF optimization. +If not set, the maximum of colors in the palette will be 256. You probably want +to disable this option for a standalone image. +Set by default. +

+
+
transparency_color
+

Set the color that will be used as background for transparency. +

+
+
stats_mode
+

Set statistics mode. +

+

It accepts the following values: +

+
‘full’
+

Compute full frame histograms. +

+
‘diff’
+

Compute histograms only for the part that differs from previous frame. This +might be relevant to give more importance to the moving part of your input if +the background is static. +

+
‘single’
+

Compute new histogram for each frame. +

+
+ +

Default value is full. +

+
+ +

The filter also exports the frame metadata lavfi.color_quant_ratio +(nb_color_in / nb_color_out) which you can use to evaluate the degree of +color quantization of the palette. This information is also visible at +info logging level. +

+ +

11.188.1 Examples

+ +
    +
  • Generate a representative palette of a given video using ffmpeg: +
    +
    ffmpeg -i input.mkv -vf palettegen palette.png
    +
    +
+ + +

11.189 paletteuse

+ +

Use a palette to downsample an input video stream. +

+

The filter takes two inputs: one video stream and a palette. The palette must +be a 256 pixels image. +

+

It accepts the following options: +

+
+
dither
+

Select dithering mode. Available algorithms are: +

+
‘bayer’
+

Ordered 8x8 bayer dithering (deterministic) +

+
‘heckbert’
+

Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). +Note: this dithering is sometimes considered "wrong" and is included as a +reference. +

+
‘floyd_steinberg’
+

Floyd and Steingberg dithering (error diffusion) +

+
‘sierra2’
+

Frankie Sierra dithering v2 (error diffusion) +

+
‘sierra2_4a’
+

Frankie Sierra dithering v2 "Lite" (error diffusion) +

+
‘sierra3’
+

Frankie Sierra dithering v3 (error diffusion) +

+
‘burkes’
+

Burkes dithering (error diffusion) +

+
‘atkinson’
+

Atkinson dithering by Bill Atkinson at Apple Computer (error diffusion) +

+
‘none’
+

Disable dithering. +

+
+ +

Default is sierra2_4a. +

+
+
bayer_scale
+

When bayer dithering is selected, this option defines the scale of the +pattern (how much the crosshatch pattern is visible). A low value means more +visible pattern for less banding, and higher value means less visible pattern +at the cost of more banding. +

+

The option must be an integer value in the range [0,5]. Default is 2. +

+
+
diff_mode
+

If set, define the zone to process +

+
+
‘rectangle’
+

Only the changing rectangle will be reprocessed. This is similar to GIF +cropping/offsetting compression mechanism. This option can be useful for speed +if only a part of the image is changing, and has use cases such as limiting the +scope of the error diffusal dither to the rectangle that bounds the +moving scene (it leads to more deterministic output if the scene doesn’t change +much, and as a result less moving noise and better GIF compression). +

+
+ +

Default is none. +

+
+
new
+

Take new palette for each output frame. +

+
+
alpha_threshold
+

Sets the alpha threshold for transparency. Alpha values above this threshold +will be treated as completely opaque, and values below this threshold will be +treated as completely transparent. +

+

The option must be an integer value in the range [0,255]. Default is 128. +

+
+ + +

11.189.1 Examples

+ +
    +
  • Use a palette (generated for example with palettegen) to encode a GIF +using ffmpeg: +
    +
    ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
    +
    +
+ + +

11.190 perspective

+ +

Correct perspective of video not recorded perpendicular to the screen. +

+

A description of the accepted parameters follows. +

+
+
x0
+
y0
+
x1
+
y1
+
x2
+
y2
+
x3
+
y3
+

Set coordinates expression for top left, top right, bottom left and bottom right corners. +Default values are 0:0:W:0:0:H:W:H with which perspective will remain unchanged. +If the sense option is set to source, then the specified points will be sent +to the corners of the destination. If the sense option is set to destination, +then the corners of the source will be sent to the specified coordinates. +

+

The expressions can use the following variables: +

+
+
W
+
H
+

the width and height of video frame. +

+
in
+

Input frame count. +

+
on
+

Output frame count. +

+
+ +
+
interpolation
+

Set interpolation for perspective correction. +

+

It accepts the following values: +

+
‘linear’
+
‘cubic’
+
+ +

Default value is ‘linear’. +

+
+
sense
+

Set interpretation of coordinate options. +

+

It accepts the following values: +

+
‘0, source’
+
+

Send point in the source specified by the given coordinates to +the corners of the destination. +

+
+
‘1, destination’
+
+

Send the corners of the source to the point in the destination specified +by the given coordinates. +

+

Default value is ‘source’. +

+
+ +
+
eval
+

Set when the expressions for coordinates x0,y0,...x3,y3 are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ + +

11.191 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. +

+
+
mode
+

Set phase mode. +

+

It accepts the following values: +

+
‘t’
+

Capture field order top-first, transfer bottom-first. +Filter will delay the bottom field. +

+
+
‘b’
+

Capture field order bottom-first, transfer top-first. +Filter will delay the top field. +

+
+
‘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. +

+
+
‘a’
+

Capture field order determined automatically by field flags, transfer +opposite. +Filter selects among ‘t’ and ‘b’ modes on a frame by frame +basis using field flags. If no field information is available, +then this works just like ‘u’. +

+
+
‘u’
+

Capture unknown or varying, transfer opposite. +Filter selects among ‘t’ and ‘b’ on a frame by frame basis by +analyzing the images and selecting the alternative that produces best +match between the fields. +

+
+
‘T’
+

Capture top-first, transfer unknown or varying. +Filter selects among ‘t’ and ‘p’ using image analysis. +

+
+
‘B’
+

Capture bottom-first, transfer unknown or varying. +Filter selects among ‘b’ and ‘p’ using image analysis. +

+
+
‘A’
+

Capture determined by field flags, transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using field flags and +image analysis. If no field information is available, then this works just +like ‘U’. This is the default mode. +

+
+
‘U’
+

Both capture and transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using image analysis only. +

+
+
+
+ + +

11.191.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.192 photosensitivity

+

Reduce various flashes in video, so to help users with epilepsy. +

+

It accepts the following options: +

+
frames, f
+

Set how many frames to use when filtering. Default is 30. +

+
+
threshold, t
+

Set detection threshold factor. Default is 1. +Lower is stricter. +

+
+
skip
+

Set how many pixels to skip when sampling frames. Default is 1. +Allowed range is from 1 to 1024. +

+
+
bypass
+

Leave frames unchanged. Default is disabled. +

+
+ + +

11.193 pixdesctest

+ +

Pixel format descriptor test filter, mainly useful for internal +testing. The output video should be equal to the input video. +

+

For example: +

+
format=monow, pixdesctest
+
+ +

can be used to test the monowhite pixel format descriptor definition. +

+ +

11.194 pixelize

+

Apply pixelization to video stream. +

+

The filter accepts the following options: +

+
width, w
+
height, h
+

Set block dimensions that will be used for pixelization. +Default value is 16. +

+
+
mode, m
+

Set the mode of pixelization used. +

+

Possible values are: +

+
‘avg’
+
‘min’
+
‘max’
+
+

Default value is avg. +

+
+
planes, p
+

Set what planes to filter. Default is to filter all planes. +

+
+ + +

11.194.1 Commands

+ +

This filter supports all options as commands. +

+ +

11.195 pixscope

+ +

Display sample values of color channels. Mainly useful for checking color +and levels. Minimum supported resolution is 640x480. +

+

The filters accept the following options: +

+
+
x
+

Set scope X position, relative offset on X axis. +

+
+
y
+

Set scope Y position, relative offset on Y axis. +

+
+
w
+

Set scope width. +

+
+
h
+

Set scope height. +

+
+
o
+

Set window opacity. This window also holds statistics about pixel area. +

+
+
wx
+

Set window X position, relative offset on X axis. +

+
+
wy
+

Set window Y position, relative offset on Y axis. +

+
+ + +

11.195.1 Commands

+ +

This filter supports same commands as options. +

+ +

11.196 pp7

+

Apply Postprocessing filter 7. It is variant of the spp filter, +similar to spp = 6 with 7 point DCT, where only the center sample is +used after IDCT. +

+

The filter accepts the following options: +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range +0 to 63. If not set, the filter will use the QP from the video stream +(if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding. +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
‘medium’
+

Set medium thresholding (good results, default). +

+
+
+
+ + +

11.197 premultiply

+

Apply alpha premultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

11.198 premultiply_dynamic

+

Dynamically premultiply or unpremultiply the input video stream as needed, +to match the requirements of the downstream filter graph. This is roughly +equivalent to either premultiply:inplace=yes or +unpremultiply:inplace=yes, or otherwise a noop. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ + +

11.199 prewitt

+

Apply prewitt operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

11.199.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.200 pseudocolor

+ +

Alter frame colors in video with pseudocolors. +

+

This filter accepts the following options: +

+
+
c0
+

set pixel first component expression +

+
+
c1
+

set pixel second component expression +

+
+
c2
+

set pixel third component expression +

+
+
c3
+

set pixel fourth component expression, corresponds to the alpha component +

+
+
index, i
+

set component to use as base for altering colors +

+
+
preset, p
+

Pick one of built-in LUTs. By default is set to none. +

+

Available LUTs: +

+
‘magma’
+
‘inferno’
+
‘plasma’
+
‘viridis’
+
‘turbo’
+
‘cividis’
+
‘range1’
+
‘range2’
+
‘shadows’
+
‘highlights’
+
‘solar’
+
‘nominal’
+
‘preferred’
+
‘total’
+
‘spectral’
+
‘cool’
+
‘heat’
+
‘fiery’
+
‘blues’
+
‘green’
+
‘helix’
+
+ +
+
opacity
+

Set opacity of output colors. Allowed range is from 0 to 1. +Default value is set to 1. +

+
+ +

Each of the expression options specifies the expression to use for computing +the lookup table for the corresponding pixel component values. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
ymin, umin, vmin, amin
+

The minimum allowed component value. +

+
+
ymax, umax, vmax, amax
+

The maximum allowed component value. +

+
+ +

All expressions default to "val". +

+ +

11.200.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.200.2 Examples

+ +
    +
  • Change too high luma values to gradient: +
    +
    pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
    +
    +
+ + +

11.201 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: +

+
+
PSNR = 10*log10(MAX^2/MSE)
+
+ +

Where MAX is the average of the maximum values of each component of the +image. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the PSNR of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+
stats_version
+

Specifies which version of the stats file format to use. Details of +each format are written below. +Default value is 1. +

+
+
output_max
+

Determines whether the max value is output to the stats log. +Default value is 0. +Requires stats_version >= 2. If this is set and stats_version < 2, +the filter will return an error. +

+
+ +

This filter also supports the framesync options. +

+

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

If a stats_version greater than 1 is specified, a header line precedes +the list of per-frame-pair stats, with key value pairs following the frame +format with the following parameters: +

+
+
psnr_log_version
+

The version of the log file format. Will match stats_version. +

+
+
fields
+

A comma separated list of the per-frame-pair parameters included in +the log. +

+
+ +

A description of each shown per-frame-pair parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
mse_avg
+

Mean Square Error pixel-by-pixel average difference of the compared +frames, averaged over all the image components. +

+
+
mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
+

Mean Square Error pixel-by-pixel average difference of the compared +frames for the component specified by the suffix. +

+
+
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. +

+
+
max_avg, max_y, max_u, max_v
+

Maximum allowed value for each channel, and average over all +channels. +

+
+ + +

11.201.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] psnr="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The PSNR of each individual frame +is stored in stats.log. +

    +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -
    +
    +
+ + +

11.202 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 fps=24000/1001 if the input frame rate is 29.97fps, +fps=24 for 30fps and the (rare) telecined 25fps input. +

+

The filter accepts the following options: +

+
+
jl
+
jr
+
jt
+
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. +

+
+
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 0. +

+
+
mp
+

Set the metric plane to use. It accepts the following values: +

+
‘l’
+

Use luma plane. +

+
+
‘u’
+

Use chroma blue plane. +

+
+
‘v’
+

Use chroma red plane. +

+
+ +

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 mp to a chroma plane is to reduce CPU +load and make pullup usable in realtime on slow machines. +

+
+ +

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: +

+
ffmpeg -i input -vf pullup -r 24000/1001 ...
+
+ + +

11.203 qp

+ +

Change video quantization parameters (QP). +

+

The filter accepts the following option: +

+
+
qp
+

Set expression for quantization parameter. +

+
+ +

The expression is evaluated through the eval API and can contain, among others, +the following constants: +

+
+
known
+

1 if index is not 129, 0 otherwise. +

+
+
qp
+

Sequential index starting from -129 to 128. +

+
+ + +

11.203.1 Examples

+ +
    +
  • Some equation like: +
    +
    qp=2+2*sin(PI*qp)
    +
    +
+ + +

11.204 qrencode

+

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/), and overlay it on top of the current +frame. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and overlaid into the video output according to +the specified options. +

+

In case no text is specified, no QR code is overlaied. +

+

This filter accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
x
+
y
+

Specify an expression for positioning the padded QR code top-left corner. The +x expression can reference the value set by the y expression, and +vice. +

+

By default x and y are set set to 0, meaning that the QR code +is placed in the top left corner of the input. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section below for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section below for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

11.204.1 qrencode Expressions

+ +

The expressions set by the options contain the following constants and functions. +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
duration
+

the current frame’s duration, in seconds +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
main_h, H
+

the input height +

+
+
main_w, W
+

the input width +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pict_type
+

a number representing the picture type +

+
+
qr_w, w
+

the width of the encoded QR code +

+
+
rendered_qr_w, q
+
rendered_padded_qr_w, Q
+

the width of the rendered QR code, without and without padding. +

+

These parameters allow the q and Q expressions to refer to each +other, so you can for example specify q=3/4*Q. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

the input sample aspect ratio +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer to each +other, so you can for example specify y=x/dar. +

+
+ + +

11.204.2 qrencode Text expansion

+ +

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
n, frame_num
+

return the frame number +

+
+
pts
+

Return the presentation timestamp of the current frame. +

+

It can take up to two arguments. +

+

The first argument is the format of the timestamp; it defaults to flt for +seconds as a decimal number with microsecond accuracy; hms stands for a +formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as local time +zone time. If the format is set to hms24hh, the time is formatted in 24h +format (00-23). +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to localtime or gmtime, a third argument may +be supplied: a strftime C function format string. By default, +YYYY-MM-DD HH:MM:SS format will be used. +

+
+
expr, e
+

Evaluate the expression’s value and output as a double. +

+

It must take one argument specifying the expression to be evaluated, accepting +the constants and functions defined in qrencode_expressions. +

+
+
expr_formatted, ef
+

Evaluate the expression’s value and output as a formatted string. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries starting with TAG +included within each frame section printed by running ffprobe +-show_frames. +

+

String metadata generated in filters leading to the qrencode filter are also +available. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+ + +

11.204.3 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size, overalaid +in the top left corner of the input video, with the default size: +
    +
    qrencode=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencode=text=www.ffmpeg.org:bc=pink@0.5:fc=blue
    +
    + +
  • Place the QR code in the bottom right corner of the input video: +
    +
    qrencode=text=www.ffmpeg.org:x=W-Q:y=H-Q
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencode=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencode=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Make the QR code a fraction of the input video width: +
    +
    qrencode=text=www.ffmpeg.org:q=W/5
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencode=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencode=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencode=text=%{pts}
    +
    + +
+ + +

11.205 quirc

+ +

Identify and decode a QR code using the libquirc library (see +https://github.com/dlbeer/quirc/), and print the identified QR codes +positions and payload as metadata. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libquirc. +

+

For each found QR code in the input video, some metadata entries are added with +the prefix lavfi.quirc.N, where N is the index, starting from 0, +associated to the QR code. +

+

A description of each metadata value follows: +

+
+
lavfi.quirc.count
+

the number of found QR codes, it is not set in case none was found +

+
+
lavfi.quirc.N.corner.M.x
+
lavfi.quirc.N.coreer.M.y
+

the x/y positions of the four corners of the square containing the QR code, +where M is the index of the corner starting from 0 +

+
+
lavfi.quirc.N.payload
+

the payload of the QR code +

+
+ + +

11.206 random

+ +

Flush video frames from internal cache of frames into a random order. +No frame is discarded. +Inspired by frei0r nervous filter. +

+
+
frames
+

Set size in number of frames of internal cache, in range from 2 to +512. Default is 30. +

+
+
seed
+

Set seed for random number generator, must be an integer included between +0 and UINT32_MAX. If not specified, or if explicitly set to +less than 0, the filter will try to use a good random seed on a +best effort basis. +

+
+ + +

11.207 readeia608

+ +

Read closed captioning (EIA-608) information from the top lines of a video frame. +

+

This filter adds frame metadata for lavfi.readeia608.X.cc and +lavfi.readeia608.X.line, where X is the number of the identified line +with EIA-608 data (starting from 0). A description of each metadata value follows: +

+
+
lavfi.readeia608.X.cc
+

The two bytes stored as EIA-608 data (printed in hexadecimal). +

+
+
lavfi.readeia608.X.line
+

The number of the line on which the EIA-608 data was identified and read. +

+
+ +

This filter accepts the following options: +

+
+
scan_min
+

Set the line to start scanning for EIA-608 data. Default is 0. +

+
+
scan_max
+

Set the line to end scanning for EIA-608 data. Default is 29. +

+
+
spw
+

Set the ratio of width reserved for sync code detection. +Default is 0.27. Allowed range is [0.1 - 0.7]. +

+
+
chp
+

Enable checking the parity bit. In the event of a parity error, the filter will output +0x00 for that character. Default is false. +

+
+
lp
+

Lowpass lines prior to further processing. Default is enabled. +

+
+ + +

11.207.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.207.2 Examples

+ +
    +
  • Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. +
    +
    ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv
    +
    +
+ + +

11.208 readvitc

+ +

Read vertical interval timecode (VITC) information from the top lines of a +video frame. +

+

The filter adds frame metadata key lavfi.readvitc.tc_str with the +timecode value, if a valid timecode has been detected. Further metadata key +lavfi.readvitc.found is set to 0/1 depending on whether +timecode data has been found or not. +

+

This filter accepts the following options: +

+
+
scan_max
+

Set the maximum number of lines to scan for VITC data. If the value is set to +-1 the full video frame is scanned. Default is 45. +

+
+
thr_b
+

Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], +default value is 0.2. The value must be equal or less than thr_w. +

+
+
thr_w
+

Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], +default value is 0.6. The value must be equal or greater than thr_b. +

+
+ + +

11.208.1 Examples

+ +
    +
  • Detect and draw VITC data onto the video frame; if no valid VITC is detected, +draw --:--:--:-- as a placeholder: +
    +
    ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--}:x=(w-tw)/2:y=400-ascent'
    +
    +
+ + +

11.209 remap

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 16bit depth, single channel. +

+
+
format
+

Specify pixel format of output from this filter. Can be color or gray. +Default is color. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

11.210 removegrain

+ +

The removegrain filter is a spatial denoiser for progressive video. +

+
+
m0
+

Set mode for the first plane. +

+
+
m1
+

Set mode for the second plane. +

+
+
m2
+

Set mode for the third plane. +

+
+
m3
+

Set mode for the fourth plane. +

+
+ +

Range of mode is from 0 to 24. Description of each mode follows: +

+
+
0
+

Leave input plane unchanged. Default. +

+
+
1
+

Clips the pixel with the minimum and maximum of the 8 neighbour pixels. +

+
+
2
+

Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. +

+
+
3
+

Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. +

+
+
4
+

Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. +This is equivalent to a median filter. +

+
+
5
+

Line-sensitive clipping giving the minimal change. +

+
+
6
+

Line-sensitive clipping, intermediate. +

+
+
7
+

Line-sensitive clipping, intermediate. +

+
+
8
+

Line-sensitive clipping, intermediate. +

+
+
9
+

Line-sensitive clipping on a line where the neighbours pixels are the closest. +

+
+
10
+

Replaces the target pixel with the closest neighbour. +

+
+
11
+

[1 2 1] horizontal and vertical kernel blur. +

+
+
12
+

Same as mode 11. +

+
+
13
+

Bob mode, interpolates top field from the line where the neighbours +pixels are the closest. +

+
+
14
+

Bob mode, interpolates bottom field from the line where the neighbours +pixels are the closest. +

+
+
15
+

Bob mode, interpolates top field. Same as 13 but with a more complicated +interpolation formula. +

+
+
16
+

Bob mode, interpolates bottom field. Same as 14 but with a more complicated +interpolation formula. +

+
+
17
+

Clips the pixel with the minimum and maximum of respectively the maximum and +minimum of each pair of opposite neighbour pixels. +

+
+
18
+

Line-sensitive clipping using opposite neighbours whose greatest distance from +the current pixel is minimal. +

+
+
19
+

Replaces the pixel with the average of its 8 neighbours. +

+
+
20
+

Averages the 9 pixels ([1 1 1] horizontal and vertical blur). +

+
+
21
+

Clips pixels using the averages of opposite neighbour. +

+
+
22
+

Same as mode 21 but simpler and faster. +

+
+
23
+

Small edge and halo removal, but reputed useless. +

+
+
24
+

Similar as 23. +

+
+ + +

11.211 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. +

+

The filter accepts the following options: +

+
+
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. +

+
+ +

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 +the logo. If you use white (255) for the logo and black (0) for the +rest, you will be safe. For making the filter bitmap, it is +recommended to take a screen capture of a black frame with the logo +visible, and then using a threshold filter followed by the erode +filter once or twice. +

+

If needed, little splotches can be fixed manually. Remember that if +logo pixels are not covered, the filter quality will be much +reduced. Marking too many pixels as part of the logo does not hurt as +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. +

+ +

11.212 repeatfields

+ +

This filter uses the repeat_field flag from the Video ES headers and hard repeats +fields based on its value. +

+ +

11.213 reverse

+ +

Reverse a video clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

11.213.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    trim=end=5,reverse
    +
    +
+ + +

11.214 rgbashift

+

Shift R/G/B/A pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
rh
+

Set amount to shift red horizontally. +

+
rv
+

Set amount to shift red vertically. +

+
gh
+

Set amount to shift green horizontally. +

+
gv
+

Set amount to shift green vertically. +

+
bh
+

Set amount to shift blue horizontally. +

+
bv
+

Set amount to shift blue vertically. +

+
ah
+

Set amount to shift alpha horizontally. +

+
av
+

Set amount to shift alpha vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

11.214.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.215 roberts

+

Apply roberts cross operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

11.215.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.216 rotate

+ +

Rotate video by an arbitrary angle expressed in radians. +

+

The filter accepts the following options: +

+

A description of the optional parameters follows. +

+
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. +

+
+
out_w, ow
+

Set the output width expression, default value is "iw". +This expression is evaluated just once during configuration. +

+
+
out_h, oh
+

Set the output height expression, default value is "ih". +This expression is evaluated just once during configuration. +

+
+
bilinear
+

Enable bilinear interpolation if set to 1, a value of 0 disables +it. Default value is 1. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the rotated +image. For the general syntax 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". +

+
+ +

The expressions for the angle and the output size can contain the +following constants and functions: +

+
+
n
+

sequential number of the input frame, starting from 0. It is always NAN +before the first frame is filtered. +

+
+
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. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_w, iw
+
in_h, ih
+

the input video width and height +

+
+
out_w, ow
+
out_h, oh
+

the output width and height, that is the size of the padded area as +specified by the width and height expressions +

+
+
rotw(a)
+
roth(a)
+

the minimal width/height required for completely containing the input +video rotated by a radians. +

+

These are only available when computing the out_w and +out_h expressions. +

+
+ + +

11.216.1 Examples

+ +
    +
  • Rotate the input by PI/6 radians clockwise: +
    +
    rotate=PI/6
    +
    + +
  • Rotate the input by PI/6 radians counter-clockwise: +
    +
    rotate=-PI/6
    +
    + +
  • Rotate the input by 45 degrees clockwise: +
    +
    rotate=45*PI/180
    +
    + +
  • Apply a constant rotation with period T, starting from an angle of PI/3: +
    +
    rotate=PI/3+2*PI*t/T
    +
    + +
  • Make the input video rotation oscillating with a period of T +seconds and an amplitude of A radians: +
    +
    rotate=A*sin(2*PI/T*t)
    +
    + +
  • Rotate the video, output size is chosen so that the whole rotating +input video is always completely contained in the output: +
    +
    rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
    +
    + +
  • Rotate the video, reduce the output size so that no background is ever +shown: +
    +
    rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
    +
    +
+ + +

11.216.2 Commands

+ +

The filter supports the following commands: +

+
+
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. +

+
+ + +

11.217 sab

+ +

Apply Shape Adaptive Blur. +

+

The filter accepts the following options: +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
chroma_radius, cr
+

Set chroma blur filter strength, must be a value in range -0.9-4.0. A +greater value will result in a more blurred image, and in slower +processing. +

+
+
chroma_pre_filter_radius, cpfr
+

Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. +

+
+
chroma_strength, cs
+

Set chroma maximum difference between pixels to still be considered, +must be a value in the -0.9-100.0 range. +

+
+ +

Each chroma option value, if not explicitly specified, is set to the +corresponding luma option value. +

+ +

11.218 scale

+ +

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. +

+

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. +

+ +

11.218.1 Options

+

The filter accepts the following options, any of the options supported +by the libswscale scaler, as well as any of the framesync options. +

+

See the ffmpeg-scaler manual for +the complete list of scaler options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the scale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+ +
+
interl
+

Set the interlacing mode. It accepts the following values: +

+
+
‘1’
+

Force interlaced aware scaling. +

+
+
‘0’
+

Do not apply interlaced scaling. +

+
+
‘-1’
+

Select interlaced aware scaling depending on whether the source frames +are flagged as interlaced or not. +

+
+ +

Default value is ‘0’. +

+
+
flags
+

Set libswscale scaling flags. See +the ffmpeg-scaler manual for the +complete list of values. If not explicitly specified the filter applies +the default flags. +

+ +
+
param0, param1
+

Set libswscale input parameters for scaling algorithms that need them. See +the ffmpeg-scaler manual for the +complete documentation. If not explicitly specified the filter applies +empty parameters. +

+
+
intent
+

Set the ICC rendering intent to use when transforming between different color +spaces. It accepts the following values: +

+
+
‘perceptual’
+

Use a perceptually guided tone and gamut mapping curve. The exact details of +the mapping used may change at any time and should not be relied on as stable. +This intent is recommended for final viewing of image/video content in typical +viewing settings. +

+
+
‘relative_colorimetric’
+

Statically clip out-of-gamut colors using a colorimetric clipping curve which +attempts to find the colorimetrically least dissimilar in-gamut color. This +intent performs white point adaptation and black point adaptation. This is +the default. This intent is recommended wherever faithful color reproduction +is of the utmost importance, even at the cost of clipping. +

+
+
‘absolute_colorimetric’
+

Hard clip out-of-gamut colors with no attempt at white or black point +reproduction. This intent will reproduce in-gamut colors 1:1 on the output +display as they would appear on the reference display, assuming the output +display is appropriately calibrated. +

+
+
‘saturation’
+

Performs saturation mapping - that is, stretches the input color volume +directly onto the output color volume, in non-linear fashion that preserves the +original signal appearance as much as possible. This intent is recommended for +signal content evaluation, as it will not lead to any clipping. It is roughly +analogous to not performing any color mapping, although it still takes into +account the mastering display primaries and any differences in encoding TRC. +

+
+ +
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
in_color_matrix
+
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: +

+
+
‘auto’
+

Choose automatically. +

+
+
‘bt709’
+

Format conforming to International Telecommunication Union (ITU) +Recommendation BT.709. +

+
+
‘fcc’
+

Set color space conforming to the United States Federal Communications +Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). +

+
+
‘bt601’
+
‘bt470’
+
‘smpte170m’
+

Set color space conforming to: +

+
    +
  • ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 + +
  • ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G + +
  • Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 + +
+ +
+
‘smpte240m’
+

Set color space conforming to SMPTE ST 240:1999. +

+
+
‘bt2020’
+

Set color space conforming to ITU-R BT.2020 non-constant luminance system. +

+
+ +
+
in_range
+
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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
in_chroma_loc
+
out_chroma_loc
+

Set in/output chroma sample location. If not specified, center-sited chroma +is used by default. Possible values: +

+
+
‘auto, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
in_primaries
+
out_primaries
+

Set in/output RGB primaries. +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
‘ebu3213’
+
+ +
+
in_transfer
+
out_transfer
+

Set in/output transfer response curve (TRC). +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘gamma22’
+
‘bt470bg’
+
‘gamma28’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘iec61966-2-1’
+
‘srgb’
+
‘iec61966-2-4’
+
‘xvycc’
+
‘bt1361e’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Enabling this option leads to the output SAR being reset to 1. +Additionally, if the user requests proportional scaling either +through the width or height expressions, e.g. w=-4:h=360 or w=iw/2:h=-1 +or by enabling force_original_aspect_ratio, then the input DAR is taken into +account and the output is scaled to produce square pixels. +Default is false. +

+
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+
ref_w, rw
+
ref_h, rh
+
ref_a
+
ref_dar, rdar
+
ref_n
+
ref_t
+
ref_pos
+

Eqvuialent to the above, but for a second reference input. If any of these +variables are present, this filter accepts two inputs. +

+
+ + +

11.218.2 Examples

+ +
    +
  • Scale the input video to a size of 200x100 +
    +
    scale=w=200:h=100
    +
    + +

    This is equivalent to: +

    +
    scale=200:100
    +
    + +

    or: +

    +
    scale=200x100
    +
    + +
  • Specify a size abbreviation for the output size: +
    +
    scale=qcif
    +
    + +

    which can also be written as: +

    +
    scale=size=qcif
    +
    + +
  • Scale the input to 2x: +
    +
    scale=w=2*iw:h=2*ih
    +
    + +
  • The above is the same as: +
    +
    scale=2*in_w:2*in_h
    +
    + +
  • Scale the input to 2x with forced interlaced scaling: +
    +
    scale=2*iw:2*ih:interl=1
    +
    + +
  • Scale the input to half size: +
    +
    scale=w=iw/2:h=ih/2
    +
    + +
  • Increase the width, and set the height to the same size: +
    +
    scale=3/2*iw:ow
    +
    + +
  • Seek Greek harmony: +
    +
    scale=iw:1/PHI*iw
    +scale=ih*PHI:ih
    +
    + +
  • Increase the height, and set the width to 3/2 of the height: +
    +
    scale=w=3/2*oh:h=3/5*ih
    +
    + +
  • Increase the size, making the size a multiple of the chroma +subsample values: +
    +
    scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
    +
    + +
  • Increase the width to a maximum of 500 pixels, +keeping the same aspect ratio as the input: +
    +
    scale=w='min(500\, iw*3/2):h=-1'
    +
    + +
  • Make pixels square by combining scale and setsar: +
    +
    scale='trunc(ih*dar):ih',setsar=1/1
    +
    + +
  • Make pixels square using reset_sar, +making sure the resulting resolution is even (required by some codecs): +
    +
    scale='-2:ih-mod(ih,2):reset_sar=1'
    +
    + +
  • Scale to target exactly, however reset SAR to 1: +
    +
    scale='400:300:reset_sar=1'
    +
    + +
  • Scale to even dimensions that fit within 400x300, preserving input SAR: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2'
    +
    + +
  • Scale to produce square pixels with even dimensions that fit within 400x300: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2:reset_sar=1'
    +
    + +
  • Scale a subtitle stream (sub) to match the main video (main) in size before +overlaying. ("scale2ref") +
    +
    '[main]split[a][b]; [ref][a]scale=rw:rh[c]; [b][c]overlay'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display +aspect ratio. +
    +
    [logo-in][video-in]scale=w=oh*dar:h=rh/10[logo-out]
    +
    +
+ + +

11.218.3 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + +

11.219 scharr

+

Apply scharr operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

11.219.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.220 scroll

+

Scroll input video horizontally and/or vertically by constant speed. +

+

The filter accepts the following options: +

+
horizontal, h
+

Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
vertical, v
+

Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
hpos
+

Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+
vpos
+

Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+ + +

11.220.1 Commands

+ +

This filter supports the following commands: +

+
horizontal, h
+

Set the horizontal scrolling speed. +

+
vertical, v
+

Set the vertical scrolling speed. +

+
+ + +

11.221 scdet

+ +

Detect video scene change. +

+

This filter sets frame metadata with mafd between frame, the scene score, and +forward the frame to the next filter, so they can use these metadata to detect +scene change or others. +

+

In addition, this filter logs a message and sets frame metadata when it detects +a scene change by threshold. +

+

lavfi.scd.mafd metadata keys are set with mafd for every frame. +

+

lavfi.scd.score metadata keys are set with scene change score for every frame +to detect scene change. +

+

lavfi.scd.time metadata keys are set with current filtered frame time which +detect scene change with threshold. +

+

The filter accepts the following options: +

+
+
threshold, t
+

Set the scene change detection threshold as a percentage of maximum change. Good +values are in the [8.0, 14.0] range. The range for threshold is +[0., 100.]. +

+

Default value is 10.. +

+
+
sc_pass, s
+

Set the flag to pass scene change frames to the next filter. Default value is 0 +You can enable it if you want to get snapshot of scene change frames only. +

+
+ + +

11.222 selectivecolor

+ +

Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such +as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined +by the "purity" of the color (that is, how saturated it already is). +

+

This filter is similar to the Adobe Photoshop Selective Color tool. +

+

The filter accepts the following options: +

+
+
correction_method
+

Select color correction method. +

+

Available values are: +

+
‘absolute’
+

Specified adjustments are applied "as-is" (added/subtracted to original pixel +component value). +

+
‘relative’
+

Specified adjustments are relative to the original component value. +

+
+

Default is absolute. +

+
reds
+

Adjustments for red pixels (pixels where the red component is the maximum) +

+
yellows
+

Adjustments for yellow pixels (pixels where the blue component is the minimum) +

+
greens
+

Adjustments for green pixels (pixels where the green component is the maximum) +

+
cyans
+

Adjustments for cyan pixels (pixels where the red component is the minimum) +

+
blues
+

Adjustments for blue pixels (pixels where the blue component is the maximum) +

+
magentas
+

Adjustments for magenta pixels (pixels where the green component is the minimum) +

+
whites
+

Adjustments for white pixels (pixels where all components are greater than 128) +

+
neutrals
+

Adjustments for all pixels except pure black and pure white +

+
blacks
+

Adjustments for black pixels (pixels where all components are lesser than 128) +

+
psfile
+

Specify a Photoshop selective color file (.asv) to import the settings from. +

+
+ +

All the adjustment settings (reds, yellows, ...) accept up to +4 space separated floating point adjustment values in the [-1,1] range, +respectively to adjust the amount of cyan, magenta, yellow and black for the +pixels of its range. +

+ +

11.222.1 Examples

+ +
    +
  • Increase cyan by 50% and reduce yellow by 33% in every green areas, and +increase magenta by 27% in blue areas: +
    +
    selectivecolor=greens=.5 0 -.33 0:blues=0 .27
    +
    + +
  • Use a Photoshop selective color preset: +
    +
    selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
    +
    +
+ + +

11.223 separatefields

+ +

The 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 setfield filter before separatefields filter. +

+ +

11.224 setdar, setsar

+ +

The setdar filter sets the Display Aspect Ratio for the filter +output video. +

+

This is done by changing the specified Sample (aka Pixel) Aspect +Ratio, according to the following equation: +

+
DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR
+
+ +

Keep in mind that the setdar filter does not modify the pixel +dimensions of the video frame. Also, the display aspect ratio set by +this filter may be changed by later filters in the filterchain, +e.g. in case of scaling or if another "setdar" or a "setsar" filter is +applied. +

+

The setsar filter sets the Sample (aka Pixel) Aspect Ratio for +the filter output video. +

+

Note that as a consequence of the application of this filter, the +output display aspect ratio will change according to the equation +above. +

+

Keep in mind that the sample aspect ratio set by the setsar +filter may be changed by later filters in the filterchain, e.g. if +another "setsar" or a "setdar" filter is applied. +

+

It accepts the following parameters: +

+
+
r, ratio, dar (setdar only), sar (setsar only)
+

Set the aspect ratio used by the filter. +

+

The parameter can be a floating point number string, or an expression. If the +parameter is not specified, the value "0" is assumed, meaning that the same +input value is used. +

+
+
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 100. +

+
+
+ +

The parameter sar is an expression containing the following constants: +

+
+
w, h
+

The input width and height. +

+
+
a
+

Same as w / h. +

+
+
sar
+

The input sample aspect ratio. +

+
+
dar
+

The input display aspect ratio. It is the same as +(w / h) * sar. +

+
+
hsub, vsub
+

Horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

11.224.1 Examples

+ +
    +
  • To change the display aspect ratio to 16:9, specify one of the following: +
    +
    setdar=dar=1.77777
    +setdar=dar=16/9
    +
    + +
  • To change the sample aspect ratio to 10:11, specify: +
    +
    setsar=sar=10/11
    +
    + +
  • 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: +
    +
    setdar=ratio=16/9:max=1000
    +
    + +
+ + +

11.225 setfield

+ +

Force field for the output video frame. +

+

The setfield filter marks the interlace type field for the +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. fieldorder or yadif). +

+

The filter accepts the following options: +

+
+
mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property. +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+
+
+ + +

11.226 setparams

+ +

Force frame parameter for the output video frame. +

+

The setparams filter marks interlace and color range for the +output frames. It does not change the input frame, but only sets the +corresponding property, which affects how the frame is treated by +filters/encoders. +

+
+
field_mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property (default). +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+ +
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property (default). +

+
+
‘unspecified, unknown’
+

Mark the frame as unspecified color range. +

+
+
‘limited, tv, mpeg’
+

Mark the frame as limited range. +

+
+
‘full, pc, jpeg’
+

Mark the frame as full range. +

+
+ +
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
+ +
+
color_trc
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same color trc property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘log100’
+
‘log316’
+
‘iec61966-2-4’
+
‘bt1361e’
+
‘iec61966-2-1’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
colorspace
+

Set the colorspace. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘gbr’
+
‘bt709’
+
‘unknown’
+
‘fcc’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘ycgco’
+
‘bt2020nc’
+
‘bt2020c’
+
‘smpte2085’
+
‘chroma-derived-nc’
+
‘chroma-derived-c’
+
‘ictcp’
+
+ +
+
chroma_location
+

Set the chroma sample location. +Available values are: +

+
+
‘auto’
+

Keep the same chroma location (default). +

+
+
‘unspecified, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode
+

Set the alpha moda. +Available values are: +

+
+
‘auto’
+

Keep the same alpha mode (default). +

+
+
‘unspecified, unknown’
+
‘premultiplied’
+
‘straight’
+
+
+
+ + +

11.227 shear

+

Apply shear transform to input video. +

+

This filter supports the following options: +

+
+
shx
+

Shear factor in X-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
shy
+

Shear factor in Y-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the transformed +video. For the general syntax 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". +

+
+
interp
+

Set interpolation type. Can be bilinear or nearest. Default is bilinear. +

+
+ + +

11.227.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.228 showinfo

+ +

Show a line containing various information for each input video frame. +The input video is not modified. +

+

This filter supports the following options: +

+
+
checksum
+

Calculate checksums of each plane. By default enabled. +

+
+
udu_sei_as_ascii
+

Try to print user data unregistered SEI as ascii character when possible, +in hex format otherwise. +

+
+ +

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The Presentation TimeStamp of the input frame, expressed as a number of +time base units. The time base unit depends on the filter input pad. +

+
+
pts_time
+

The Presentation TimeStamp of the input frame, expressed as a number of +seconds. +

+
+
fmt
+

The pixel format name. +

+
+
sar
+

The sample aspect ratio of the input frame, expressed in the form +num/den. +

+
+
s
+

The size of the input frame. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
i
+

The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" +for bottom field first). +

+
+
iskey
+

This is 1 if the frame is a key frame, 0 otherwise. +

+
+
type
+

The picture type of the input frame ("I" for an I-frame, "P" for a +P-frame, "B" for a B-frame, or "?" for an unknown type). +Also refer to the documentation of the AVPictureType enum and of +the av_get_picture_type_char function defined in +libavutil/avutil.h. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. +

+
+
plane_checksum
+

The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, +expressed in the form "[c0 c1 c2 c3]". +

+
+
mean
+

The mean value of pixels in each plane of the input frame, expressed in the form +"[mean0 mean1 mean2 mean3]". +

+
+
stdev
+

The standard deviation of pixel values in each plane of the input frame, expressed +in the form "[stdev0 stdev1 stdev2 stdev3]". +

+
+
+ + +

11.229 showpalette

+ +

Displays the 256 colors palette of each frame. This filter is only relevant for +pal8 pixel format frames. +

+

It accepts the following option: +

+
+
s
+

Set the size of the box used to represent one palette color entry. Default is +30 (for a 30x30 pixel box). +

+
+ + +

11.230 shuffleframes

+ +

Reorder and/or duplicate and/or drop video frames. +

+

It accepts the following parameters: +

+
+
mapping
+

Set the destination indexes of input frames. +This is space or ’|’ separated list of indexes that maps input frames to output +frames. Number of indexes also sets maximal value that each index may have. +’-1’ index have special meaning and that is to drop frame. +

+
+ +

The first frame has the index 0. The default is to keep the input unchanged. +

+ +

11.230.1 Examples

+ +
    +
  • Swap second and third frame of every three frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
    +
    + +
  • Swap 10th and 1st frame of every ten frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
    +
    +
+ + +

11.231 shufflepixels

+ +

Reorder pixels in video frames. +

+

This filter accepts the following options: +

+
+
direction, d
+

Set shuffle direction. Can be forward or inverse direction. +Default direction is forward. +

+
+
mode, m
+

Set shuffle mode. Can be horizontal, vertical or block mode. +

+
+
width, w
+
height, h
+

Set shuffle block_size. In case of horizontal shuffle mode only width +part of size is used, and in case of vertical shuffle mode only height +part of size is used. +

+
+
seed, s
+

Set random seed used with shuffling pixels. Mainly useful to set to be able +to reverse filtering process to get original input. +For example, to reverse forward shuffle you need to use same parameters +and exact same seed and to set direction to inverse. +

+
+ + +

11.232 shuffleplanes

+ +

Reorder and/or duplicate video planes. +

+

It accepts the following parameters: +

+
+
map0
+

The index of the input plane to be used as the first output plane. +

+
+
map1
+

The index of the input plane to be used as the second output plane. +

+
+
map2
+

The index of the input plane to be used as the third output plane. +

+
+
map3
+

The index of the input plane to be used as the fourth output plane. +

+
+
+ +

The first plane has the index 0. The default is to keep the input unchanged. +

+ +

11.232.1 Examples

+ +
    +
  • Swap the second and third planes of the input: +
    +
    ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
    +
    +
+ + +

11.233 signalstats

+

Evaluate various visual metrics that assist in determining issues associated +with the digitization of analog video media. +

+

By default the filter will log these metadata values: +

+
+
YMIN
+

Display the minimal Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
YLOW
+

Display the Y value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YAVG
+

Display the average Y value within the input frame. Expressed in range of +[0-255]. +

+
+
YHIGH
+

Display the Y value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YMAX
+

Display the maximum Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
UMIN
+

Display the minimal U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
ULOW
+

Display the U value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UAVG
+

Display the average U value within the input frame. Expressed in range of +[0-255]. +

+
+
UHIGH
+

Display the U value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UMAX
+

Display the maximum U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VMIN
+

Display the minimal V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VLOW
+

Display the V value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VAVG
+

Display the average V value within the input frame. Expressed in range of +[0-255]. +

+
+
VHIGH
+

Display the V value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VMAX
+

Display the maximum V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
SATMIN
+

Display the minimal saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATLOW
+

Display the saturation value at the 10% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATAVG
+

Display the average saturation value within the input frame. Expressed in range +of [0-~181.02]. +

+
+
SATHIGH
+

Display the saturation value at the 90% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATMAX
+

Display the maximum saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
HUEMED
+

Display the median value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
HUEAVG
+

Display the average value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
YDIF
+

Display the average of sample value difference between all values of the Y +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
UDIF
+

Display the average of sample value difference between all values of the U +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
VDIF
+

Display the average of sample value difference between all values of the V +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
YBITDEPTH
+

Display bit depth of Y plane in current frame. +Expressed in range of [0-16]. +

+
+
UBITDEPTH
+

Display bit depth of U plane in current frame. +Expressed in range of [0-16]. +

+
+
VBITDEPTH
+

Display bit depth of V plane in current frame. +Expressed in range of [0-16]. +

+
+ +

The filter accepts the following options: +

+
+
stat
+
out
+
+

stat specify an additional form of image analysis. +out output video with the specified type of pixel highlighted. +

+

Both options accept the following values: +

+
+
‘tout’
+

Identify temporal outliers pixels. A temporal outlier is a pixel +unlike the neighboring pixels of the same field. Examples of temporal outliers +include the results of video dropouts, head clogs, or tape tracking issues. +

+
+
‘vrep’
+

Identify vertical line repetition. Vertical line repetition includes +similar rows of pixels within a frame. In born-digital video vertical line +repetition is common, but this pattern is uncommon in video digitized from an +analog source. When it occurs in video that results from the digitization of an +analog source it can indicate concealment from a dropout compensator. +

+
+
‘brng’
+

Identify pixels that fall outside of legal broadcast range. +

+
+ +
+
color, c
+

Set the highlight color for the out option. The default color is +yellow. +

+
+ + +

11.233.1 Examples

+ +
    +
  • Output data of various video metrics: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
    +
    + +
  • Output specific data about the minimum and maximum values of the Y plane per frame: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
    +
    + +
  • Playback video while highlighting pixels that are outside of broadcast range in red. +
    +
    ffplay example.mov -vf signalstats="out=brng:color=red"
    +
    + +
  • Playback video with signalstats metadata drawn over the frame. +
    +
    ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
    +
    + +

    The contents of signalstat_drawtext.txt used in the command are: +

    +
    time %{pts:hms}
    +Y (%{metadata:lavfi.signalstats.YMIN}-%{metadata:lavfi.signalstats.YMAX})
    +U (%{metadata:lavfi.signalstats.UMIN}-%{metadata:lavfi.signalstats.UMAX})
    +V (%{metadata:lavfi.signalstats.VMIN}-%{metadata:lavfi.signalstats.VMAX})
    +saturation maximum: %{metadata:lavfi.signalstats.SATMAX}
    +
    +
    +
+ + +

11.234 signature

+ +

Calculates the MPEG-7 Video Signature. The filter can handle more than one +input. In this case the matching between the inputs can be calculated additionally. +The filter always passes through the first input. The signature of each stream can +be written into a file. +

+

It accepts the following options: +

+
+
detectmode
+

Enable or disable the matching process. +

+

Available values are: +

+
+
‘off’
+

Disable the calculation of a matching (default). +

+
‘full’
+

Calculate the matching for the whole video and output whether the whole video +matches or only parts. +

+
‘fast’
+

Calculate only until a matching is found or the video ends. Should be faster in +some cases. +

+
+ +
+
nb_inputs
+

Set the number of inputs. The option value must be a non negative integer. +Default value is 1. +

+
+
filename
+

Set the path to which the output is written. If there is more than one input, +the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive +integer), that will be replaced with the input number. If no filename is +specified, no output will be written. This is the default. +

+
+
format
+

Choose the output format. +

+

Available values are: +

+
+
‘binary’
+

Use the specified binary representation (default). +

+
‘xml’
+

Use the specified xml representation. +

+
+ +
+
th_d
+

Set threshold to detect one word as similar. The option value must be an integer +greater than zero. The default value is 9000. +

+
+
th_dc
+

Set threshold to detect all words as similar. The option value must be an integer +greater than zero. The default value is 60000. +

+
+
th_xh
+

Set threshold to detect frames as similar. The option value must be an integer +greater than zero. The default value is 116. +

+
+
th_di
+

Set the minimum length of a sequence in frames to recognize it as matching +sequence. The option value must be a non negative integer value. +The default value is 0. +

+
+
th_it
+

Set the minimum relation, that matching frames to all frames must have. +The option value must be a double value between 0 and 1. The default value is 0.5. +

+
+ + +

11.234.1 Examples

+ +
    +
  • To calculate the signature of an input video and store it in signature.bin: +
    +
    ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
    +
    + +
  • To detect whether two videos match and store the signatures in XML format in +signature0.xml and signature1.xml: +
    +
    ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -
    +
    + +
+ + +

11.235 siti

+ +

Calculate Spatial Information (SI) and Temporal Information (TI) scores for a video, +as defined in ITU-T Rec. P.910 (11/21): Subjective video quality assessment methods +for multimedia applications. Available PDF at https://www.itu.int/rec/T-REC-P.910-202111-S/en. +Note that this is a legacy implementation that corresponds to a superseded recommendation. +Refer to ITU-T Rec. P.910 (07/22) for the latest version: https://www.itu.int/rec/T-REC-P.910-202207-I/en +

+

It accepts the following option: +

+
+
print_summary
+

If set to 1, Summary statistics will be printed to the console. Default 0. +

+
+ + +

11.235.1 Examples

+
    +
  • To calculate SI/TI metrics and print summary: +
    +
    ffmpeg -i input.mp4 -vf siti=print_summary=1 -f null -
    +
    +
+ + +

11.236 smartblur

+ +

Blur the input video without impacting the outlines. +

+

It accepts the following options: +

+
+
luma_radius, lr
+

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. +

+
+
luma_strength, ls
+

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. +

+
+
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. +

+
+
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 luma_radius. +

+
+
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 luma_strength. +

+
+
chroma_threshold, ct
+

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 +in [-30,0] will filter edges. Default value is luma_threshold. +

+
+
alpha_radius, ar
+

Set the alpha 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 luma_radius. +

+
+
alpha_strength, as
+

Set the alpha 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 luma_strength. +

+
+
alpha_threshold, at
+

Set the alpha 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 luma_threshold. +

+
+ +

If a chroma or alpha option is not explicitly set, the corresponding luma value +is set. +

+ +

11.237 sobel

+

Apply sobel operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

11.237.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.238 spp

+ +

Apply a simple postprocessing filter that compresses and decompresses the image +at several (or - in the case of quality level 6 - all) shifts +and average the results. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-6. If set to 0, the filter will have no +effect. A value of 6 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding (default). +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
+ +
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+ + +

11.238.1 Commands

+ +

This filter supports the following commands: +

+
quality, level
+

Set quality level. The value max can be used to set the maximum level, +currently 6. +

+
+ + +

11.239 sr

+ +

Scale the input by applying one of the super-resolution methods based on +convolutional neural networks. Supported models: +

+ + +

Training scripts as well as scripts for model file (.pb) saving can be found at +https://github.com/XueweiMeng/sr/tree/sr_dnn_native. Original repository +is at https://github.com/HighVoltageRocknRoll/sr.git. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO backend +can load files for only its format. +

+
+
scale_factor
+

Set scale factor for SRCNN model. Allowed values are 2, 3 and 4. +Default value is 2. Scale factor is necessary for SRCNN model, because it accepts +input upscaled using bicubic upscaling with proper scale factor. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

11.240 sr_amf

+ +

Upscale (size increasing) for the input video using AMD Advanced Media Framework library for hardware acceleration. +Use advanced algorithms for upscaling with higher output quality. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
algorithm
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+
+
sr1-0
+

Video SR1.0 +This is a default value +

+
+
point
+

Point +

+
+
sr1-1
+

Video SR1.1 +

+
+
+ +
+
sharpness
+

Control hq scaler sharpening. The value is a float in the range of [0.0, 2.0] +

+
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+
+
keep-ratio
+

Force the scaler to keep the aspect ratio of the input image when the output size has a different aspect ratio. +Default value is false. +

+
+
fill
+

Specifies whether the output image outside the region of interest, +which does not fill the entire output surface should be filled with a solid color. +

+
+
+ + +

11.240.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    sr_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K with algorithm video SR1.1. +
    +
    sr_amf=4096:2160:algorithm=sr1-1
    +
    +
+ + +

11.241 ssim

+ +

Obtain the SSIM (Structural SImilarity Metric) 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 SSIM. +

+

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 filter stores the calculated SSIM of each frame. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the SSIM of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+ +

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

A description of each shown parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
Y, U, V, R, G, B
+

SSIM of the compared frames for the component specified by the suffix. +

+
+
All
+

SSIM of the compared frames for the whole frame. +

+
+
dB
+

Same as above but in dB representation. +

+
+ +

This filter also supports the framesync options. +

+ +

11.241.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] ssim="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The SSIM of each individual frame +is stored in stats.log. +

    +
  • Another example with both psnr and ssim at same time: +
    +
    ffmpeg -i main.mpg -i ref.mpg -lavfi  "ssim;[0:v][1:v]psnr" -f null -
    +
    + +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -
    +
    +
+ + +

11.242 stereo3d

+ +

Convert between different stereoscopic image formats. +

+

The filters accept the following options: +

+
+
in
+

Set stereoscopic image format of input. +

+

Available values for input image formats are: +

+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+

Default value is ‘sbsl’. +

+
+ +
+
out
+

Set stereoscopic image format of output. +

+
+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘arbg’
+

anaglyph red/blue gray +(red filter on left eye, blue filter on right eye) +

+
+
‘argg’
+

anaglyph red/green gray +(red filter on left eye, green filter on right eye) +

+
+
‘arcg’
+

anaglyph red/cyan gray +(red filter on left eye, cyan filter on right eye) +

+
+
‘arch’
+

anaglyph red/cyan half colored +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcc’
+

anaglyph red/cyan color +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcd’
+

anaglyph red/cyan color optimized with the least squares projection of dubois +(red filter on left eye, cyan filter on right eye) +

+
+
‘agmg’
+

anaglyph green/magenta gray +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmh’
+

anaglyph green/magenta half colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmc’
+

anaglyph green/magenta colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmd’
+

anaglyph green/magenta color optimized with the least squares projection of dubois +(green filter on left eye, magenta filter on right eye) +

+
+
‘aybg’
+

anaglyph yellow/blue gray +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybh’
+

anaglyph yellow/blue half colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybc’
+

anaglyph yellow/blue colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybd’
+

anaglyph yellow/blue color optimized with the least squares projection of dubois +(yellow filter on left eye, blue filter on right eye) +

+
+
‘ml’
+

mono output (left eye only) +

+
+
‘mr’
+

mono output (right eye only) +

+
+
‘chl’
+

checkerboard, left eye first +

+
+
‘chr’
+

checkerboard, right eye first +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+
+
‘hdmi’
+

HDMI frame pack +

+
+ +

Default value is ‘arcd’. +

+
+ + +

11.242.1 Examples

+ +
    +
  • Convert input video from side by side parallel to anaglyph yellow/blue dubois: +
    +
    stereo3d=sbsl:aybd
    +
    + +
  • Convert input video from above below (left eye above, right eye below) to side by side crosseye. +
    +
    stereo3d=abl:sbsr
    +
    +
+ + +

11.243 streamselect, astreamselect

+

Select video or audio streams. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. Default is 2. +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

11.243.1 Commands

+ +

The streamselect and astreamselect filter supports the following +commands: +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

11.243.2 Examples

+ +
    +
  • Select first 5 seconds 1st stream and rest of time 2nd stream: +
    +
    sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
    +
    + +
  • Same as above, but for audio: +
    +
    asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
    +
    +
+ + +

11.244 subtitles

+ +

Draw subtitles on top of input video using the libass library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libass. This filter also requires a build with libavcodec and +libavformat to convert the passed subtitles file to ASS (Advanced Substation +Alpha) subtitles format. +

+

The filter accepts the following options: +

+
+
filename, f
+

Set the filename of the subtitle file to read. It must be specified. +

+
+
original_size
+

Specify the size of the original video, the video for which the ASS file +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. +

+
+
fontsdir
+

Set a directory path containing fonts that can be used by the filter. +These fonts will be used in addition to whatever the font provider uses. +

+
+
alpha
+

Process alpha channel, by default alpha channel is untouched. +

+
+
charenc
+

Set subtitles input character encoding. subtitles filter only. Only +useful if not UTF-8. +

+
+
stream_index, si
+

Set subtitles stream index. subtitles filter only. +

+
+
force_style
+

Override default style or script info parameters of the subtitles. It accepts a +string containing ASS style format KEY=VALUE couples separated by ",". +

+
+
wrap_unicode
+

Break lines according to the Unicode Line Breaking Algorithm. Availability requires +at least libass release 0.17.0 (or LIBASS_VERSION 0x01600010), and libass must +have been built with libunibreak. +

+

The option is enabled by default except for native ASS. +

+
+ +

If the first key is not specified, it is assumed that the first value +specifies the filename. +

+

For example, to render the file sub.srt on top of the input +video, use the command: +

+
subtitles=sub.srt
+
+ +

which is equivalent to: +

+
subtitles=filename=sub.srt
+
+ +

To render the default subtitles stream from file video.mkv, use: +

+
subtitles=video.mkv
+
+ +

To render the second subtitles stream from that file, use: +

+
subtitles=video.mkv:si=1
+
+ +

To make the subtitles stream from sub.srt appear in 80% transparent blue +DejaVu Serif, use: +

+
subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
+
+ + +

11.245 super2xsai

+ +

Scale the input by 2x and smooth using the Super2xSaI (Scale and +Interpolate) pixel art scaling algorithm. +

+

Useful for enlarging pixel art images without reducing sharpness. +

+ +

11.246 swaprect

+ +

Swap two rectangular objects in video. +

+

This filter accepts the following options: +

+
+
w
+

Set object width. +

+
+
h
+

Set object height. +

+
+
x1
+

Set 1st rect x coordinate. +

+
+
y1
+

Set 1st rect y coordinate. +

+
+
x2
+

Set 2nd rect x coordinate. +

+
+
y2
+

Set 2nd rect y coordinate. +

+

All expressions are evaluated once for each frame. +

+
+ +

The all options are expressions containing the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
a
+

same as w / h +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+ + +

11.246.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.247 swapuv

+

Swap U & V plane. +

+ +

11.248 tblend

+

Blend successive video frames. +

+

See blend +

+ +

11.249 telecine

+ +

Apply telecine process to the video. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+ +
+
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
+
+ + +

11.250 thistogram

+ +

Compute and draw a color distribution histogram for the input video across time. +

+

Unlike histogram video filter which only shows histogram of single input frame +at certain time, this filter shows also past histograms of number of frames defined +by width option. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

The filter accepts the following options: +

+
+
width, w
+

Set width of single color component output. Default value is 0. +Value of 0 means width will be picked from input video. +This also set number of passed histograms to keep. +Allowed range is [0, 8192]. +

+
+
display_mode, d
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode, m
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components, c
+

Set what color components to display. +Default is 7. +

+
+
bgopacity, b
+

Set background opacity. Default is 0.9. +

+
+
envelope, e
+

Show envelope. Default is disabled. +

+
+
ecolor, ec
+

Set envelope color. Default is gold. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is replace. +

+
+ + +

11.251 threshold

+ +

Apply threshold effect to video stream. +

+

This filter needs four video streams to perform thresholding. +First stream is stream we are filtering. +Second stream is holding threshold values, third stream is holding min values, +and last, fourth stream is holding max values. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ +

For example if first stream pixel’s component value is less then threshold value +of pixel component from 2nd threshold stream, third stream value will picked, +otherwise fourth stream pixel component value will be picked. +

+

Using color source filter one can perform various types of thresholding: +

+ +

11.251.1 Commands

+ +

This filter supports the all options as commands. +

+ +

11.251.2 Examples

+ +
    +
  • Binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
    +
    + +
  • Inverted binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
    +
    + +
  • Truncate binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
    +
    + +
  • Threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
    +
    + +
  • Inverted threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
    +
    +
+ + +

11.252 thumbnail

+

Select the most representative frame in a given sequence of consecutive frames. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+
log
+

Set the log level to display picked frame stats. +Default is info. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

11.252.1 Examples

+ +
    +
  • Extract one picture each 50 frames: +
    +
    thumbnail=50
    +
    + +
  • Complete example of a thumbnail creation with ffmpeg: +
    +
    ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
    +
    +
+ + +

11.253 tile

+ +

Tile several successive frames together. +

+

The untile filter can do the reverse. +

+

The filter accepts the following options: +

+
+
layout
+

Set the grid size in the form COLUMNSxROWS. Range is up to UINT_MAX cells. +Default is 6x5. +

+
+
nb_frames
+

Set the maximum number of frames to render in the given area. It must be less +than or equal to wxh. The default value is 0, meaning all +the area will be used. +

+
+
margin
+

Set the outer border margin in pixels. Range is 0 to 1024. Default is 0. +

+
+
padding
+

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. Range is 0 to 1024. Default is 0. +

+
+
color
+

Specify the color of the unused area. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +The default value of color is "black". +

+
+
overlap
+

Set the number of frames to overlap when tiling several successive frames together. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+
init_padding
+

Set the number of frames to initially be empty before displaying first output frame. +This controls how soon will one get first output frame. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+ + +

11.253.1 Examples

+ +
    +
  • Produce 8x8 PNG tiles of all keyframes (-skip_frame nokey) in a movie: +
    +
    ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
    +
    +

    The -vsync 0 is necessary to prevent ffmpeg from +duplicating each output frame to accommodate the originally detected frame +rate. +

    +
  • Display 5 pictures in an area of 3x2 frames, +with 7 pixels between them, and 2 pixels of initial margin, using +mixed flat and named options: +
    +
    tile=3x2:nb_frames=5:padding=7:margin=2
    +
    +
+ + +

11.254 tiltandshift

+

Apply tilt-and-shift effect. +

+

What happens when you invert time and space? +

+

Normally a video is composed of several frames that represent a different +instant of time and shows a scene that evolves in the space captured by the +frame. This filter is the antipode of that concept, taking inspiration from +tilt and shift photography. +

+

A filtered frame contains the whole timeline of events composing the sequence, +and this is obtained by placing a slice of pixels from each frame into a single +one. However, since there are no infinite-width frames, this is done up the +width of the input frame, and a video is recomposed by shifting away one +column for each subsequent frame. In order to map space to time, the filter +tilts each input frame as well, so that motion is preserved. This is accomplished +by progressively selecting a different column from each input frame. +

+

The end result is a sort of inverted parallax, so that far away objects move +much faster that the ones in the front. The ideal conditions for this video +effect are when there is either very little motion and the background is static, +or when there is a lot of motion and a very wide depth of field (e.g. wide +panorama, while moving on a train). +

+

The filter accepts the following parameters: +

+
+
tilt
+

Tilt video while shifting (default). When unset, video will be sliding a +static image, composed of the first column of each frame. +

+
+
start
+

What to do at the start of filtering (see below). +

+
+
end
+

What to do at the end of filtering (see below). +

+
+
hold
+

How many columns should pass through before start of filtering. +

+
+
pad
+

How many columns should be inserted before end of filtering. +

+
+
+ +

Normally the filter shifts and tilts from the very first frame, and stops when +the last one is received. However, before filtering starts, normal video may +be preserved, so that the effect is slowly shifted in its place. Similarly, +the last video frame may be reconstructed at the end. Alternatively it is +possible to just start and end with black. +

+
+
‘none’
+

Filtering starts immediately and ends when the last frame is received. +

+
+
‘frame’
+

The first frames or the very last frame are kept intact during processing. +

+
+
‘black’
+

Black is padded at the beginning or at the end of filtering. +

+
+
+ + +

11.255 tinterlace

+ +

Perform various types of temporal field interlacing. +

+

Frames are counted starting from 1, so the first input frame is +considered odd. +

+

The filter accepts the following options: +

+
+
mode
+

Specify the mode of the interlacing. This option can also be specified +as a value alone. See below for a list of values for this option. +

+

Available values are: +

+
+
‘merge, 0’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at half frame rate. +

+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ +
+
‘drop_even, 1’
+

Only output odd frames, even frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+11111                           33333
+11111                           33333
+11111                           33333
+
+ +
+
‘drop_odd, 2’
+

Only output even frames, odd frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+                22222                           44444
+                22222                           44444
+                22222                           44444
+                22222                           44444
+
+ +
+
‘pad, 3’
+

Expand each frame to full height, but pad alternate lines with black, +generating a frame with double height at the same input frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+
+Output:
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+
+ + +
+
‘interlacex2, 6’
+

Double frame rate with unchanged height. Frames are inserted each +containing the second temporal field from the previous input frame and +the first temporal field from the next input frame. This mode relies on +the top_field_first flag. Useful for interlaced video displays with no +field synchronisation. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+
+Output:
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+
+ + +
+
‘mergex2, 7’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at same frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+
+ +
+
+ +

Numeric values are deprecated but are accepted for backward +compatibility reasons. +

+

Default mode is merge. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
low_pass_filter, vlpf
+

Enable linear vertical low-pass filtering in the filter. +Vertical low-pass filtering is required when creating an interlaced +destination from a progressive source which contains high-frequency +vertical detail. Filtering will reduce interlace ’twitter’ and Moire +patterning. +

+
+
complex_filter, cvlpf
+

Enable complex vertical low-pass filtering. +This will slightly less reduce interlace ’twitter’ and Moire +patterning but better retain detail and subjective sharpness impression. +

+
+
bypass_il
+

Bypass already interlaced frames, only adjust the frame rate. +

+
+ +

Vertical low-pass filtering and bypassing already interlaced frames can only be +enabled for mode interleave_top and interleave_bottom. +

+
+
+ + +

11.256 tmedian

+

Pick median pixels from several successive input video frames. +

+

The filter accepts the following options: +

+
+
radius
+

Set radius of median filter. +Default is 1. Allowed range is from 1 to 127. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

11.256.1 Commands

+ +

This filter supports all above options as commands, excluding option radius. +

+ +

11.257 tmidequalizer

+ +

Apply Temporal Midway Video Equalization effect. +

+

Midway Video Equalization adjusts a sequence of video frames to have the same +histograms, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a video frames sequence. +

+

This filter accepts the following option: +

+
+
radius
+

Set filtering radius. Default is 5. Allowed range is from 1 to 127. +

+
+
sigma
+

Set filtering sigma. Default is 0.5. This controls strength of filtering. +Setting this option to 0 effectively does nothing. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

11.258 tmix

+ +

Mix successive video frames. +

+

A description of the accepted options follows. +

+
+
frames
+

The number of successive frames to mix. If unspecified, it defaults to 3. +

+
+
weights
+

Specify weight of each input video frame. +Each weight is separated by space. If number of weights is smaller than +number of frames last specified weight will be used for all remaining +unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

11.258.1 Examples

+ +
    +
  • Average 7 successive frames: +
    +
    tmix=frames=7:weights="1 1 1 1 1 1 1"
    +
    + +
  • Apply simple temporal convolution: +
    +
    tmix=frames=3:weights="-1 3 -1"
    +
    + +
  • Similar as above but only showing temporal differences: +
    +
    tmix=frames=3:weights="-1 2 -1":scale=1
    +
    +
+ + +

11.258.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

11.259 tonemap

+

Tone map colors from different dynamic ranges. +

+

This filter expects data in single precision floating point, as it needs to +operate on (and can output) out-of-range values. Another filter, such as +zscale, is needed to convert the resulting frame to a usable format. +

+

The tonemapping algorithms implemented only work on linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

11.259.1 Options

+

The filter accepts the following options. +

+
+
tonemap
+

Set the tone map algorithm to use. +

+

Possible values are: +

+
none
+

Do not apply any tone map, only desaturate overbright pixels. +

+
+
clip
+

Hard-clip any out-of-range values. Use it for perfect color accuracy for +in-range values, while distorting out-of-range values. +

+
+
linear
+

Stretch the entire reference gamut to a linear multiple of the display. +

+
+
gamma
+

Fit a logarithmic transfer between the tone curves. +

+
+
reinhard
+

Preserve overall image brightness with a simple curve, using nonlinear +contrast, which results in flattening details and degrading color accuracy. +

+
+
hable
+

Preserve both dark and bright details better than reinhard, at the cost +of slightly darkening everything. Use it when detail preservation is more +important than color and brightness accuracy. +

+
+
mobius
+

Smoothly map out-of-range values, while retaining contrast and colors for +in-range material as much as possible. Use it when color accuracy is more +important than detail preservation. +

+
+ +

Default is none. +

+
+
param
+

Tune the tone mapping algorithm. +

+

This affects the following algorithms: +

+
none
+

Ignored. +

+
+
linear
+

Specifies the scale factor to use while stretching. +Default to 1.0. +

+
+
gamma
+

Specifies the exponent of the function. +Default to 1.8. +

+
+
clip
+

Specify an extra linear coefficient to multiply into the signal before clipping. +Default to 1.0. +

+
+
reinhard
+

Specify the local contrast coefficient at the display peak. +Default to 0.5, which means that in-gamut values will be about half as bright +as when clipping. +

+
+
hable
+

Ignored. +

+
+
mobius
+

Specify the transition point from linear to mobius transform. Every value +below this point is guaranteed to be mapped 1:1. The higher the value, the +more accurate the result will be, at the cost of losing bright details. +Default to 0.3, which due to the steep initial slope still preserves in-range +colors fairly accurately. +

+
+ +
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default of 2.0 is somewhat conservative and will mostly just apply to +skies or directly sunlit surfaces. A setting of 0.0 disables this option. +

+

This option works only if the input frame has a supported color tag. +

+
+
peak
+

Override signal/nominal/reference peak with this value. Useful when the +embedded peak information in display metadata is not reliable or when tone +mapping from a lower range to a higher range. +

+
+ + +

11.260 tpad

+ +

Temporarily pad video frames. +

+

The filter accepts the following options: +

+
+
start
+

Specify number of delay frames before input video stream. Default is 0. +

+
+
stop
+

Specify number of padding frames after input video stream. +Set to -1 to pad indefinitely. Default is 0. +

+
+
start_mode
+

Set kind of frames added to beginning of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of first frame. +Default is add. +

+
+
stop_mode
+

Set kind of frames added to end of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of last frame. +Default is add. +

+
+
start_duration, stop_duration
+

Specify the duration of the start/stop delay. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +These options override start and stop. Default is 0. +

+
+
color
+

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 color is "black". +

+
+ + +

11.261 transpose

+ +

Transpose rows with columns in the input video and optionally flip it. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘0, 4, cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip (default), that is: +

+
L.R     L.l
+. . ->  . .
+l.r     R.r
+
+ +
+
‘1, 5, clock’
+

Rotate by 90 degrees clockwise, that is: +

+
L.R     l.L
+. . ->  . .
+l.r     r.R
+
+ +
+
‘2, 6, cclock’
+

Rotate by 90 degrees counterclockwise, that is: +

+
L.R     R.r
+. . ->  . .
+l.r     L.l
+
+ +
+
‘3, 7, clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip, that is: +

+
L.R     r.R
+. . ->  . .
+l.r     l.L
+
+
+
+ +

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 passthrough option should be used instead. +

+

Numerical values are deprecated, and should be dropped in favor of +symbolic constants. +

+
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +

Default value is none. +

+
+ +

For example to rotate by 90 degrees clockwise and preserve portrait +layout: +

+
transpose=dir=1:passthrough=portrait
+
+ +

The command above can also be specified as: +

+
transpose=1:portrait
+
+ + +

11.262 trim

+

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Specify the time of the start of the kept section, i.e. the frame with the +timestamp start will be the first frame in the output. +

+
+
end
+

Specify the time of the first frame that will be dropped, i.e. the frame +immediately preceding the one with the timestamp end will be the last +frame in the output. +

+
+
start_pts
+

This is the same as start, except this option sets the start timestamp +in timebase units instead of seconds. +

+
+
end_pts
+

This is the same as end, except this option sets the end timestamp +in timebase units instead of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_frame
+

The number of the first frame that should be passed to the output. +

+
+
end_frame
+

The number of the first frame that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

Note that the first two sets of the start/end options and the 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 for the output timestamps to 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -vf trim=60:120
    +
    + +
  • Keep only the first second: +
    +
    ffmpeg -i INPUT -vf trim=duration=1
    +
    + +
+ + +

11.263 unpremultiply

+

Apply alpha unpremultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+

If the format has 1 or 2 components, then luma is bit 0. +If the format has 3 or 4 components: +for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; +for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. +If present, the alpha channel is always the last bit. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

11.264 unsharp

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. It must be an odd integer between +3 and 23. The default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. It must be an odd integer between 3 +and 23. The default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. It must be a floating point 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. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. It must be a floating point 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 0.0. +

+
+
alpha_msize_x, ax
+

Set the alpha matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_msize_y, ay
+

Set the alpha matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_amount, aa
+

Set the alpha effect strength. It must be a floating point 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 0.0. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

11.264.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    unsharp=7:7:-2:7:7:-2
    +
    +
+ + +

11.265 untile

+ +

Decompose a video made of tiled images into the individual images. +

+

The frame rate of the output video is the frame rate of the input video +multiplied by the number of tiles. +

+

This filter does the reverse of tile. +

+

The filter accepts the following options: +

+
+
layout
+

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. +

+
+ + +

11.265.1 Examples

+ +
    +
  • Produce a 1-second video from a still image file made of 25 frames stacked +vertically, like an analogic film reel: +
    +
    ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
    +
    +
+ + +

11.266 uspp

+ +

Apply ultra slow/simple postprocessing filter that compresses and decompresses +the image at several (or - in the case of quality level 8 - all) +shifts and average the results. +

+

The way this differs from the behavior of spp is that uspp actually encodes & +decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 +DCT similar to MJPEG. +

+

This filter is not available in ffmpeg versions between 5.0 and 6.0. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-8. If set to 0, the filter will have no +effect. A value of 8 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
codec
+

Use specified codec instead of snow. +

+
+ + +

11.267 v360

+ +

Convert 360 videos between various formats. +

+

The filter accepts the following options: +

+
+
input
+
output
+

Set format of the input/output video. +

+

Available formats: +

+
+
‘e’
+
‘equirect’
+

Equirectangular projection. +

+
+
‘c3x2’
+
‘c6x1’
+
‘c1x6’
+

Cubemap with 3x2/6x1/1x6 layout. +

+

Format specific options: +

+
+
in_pad
+
out_pad
+

Set padding proportion for the input/output cubemap. Values in decimals. +

+

Example values: +

+
‘0’
+

No padding. +

+
‘0.01’
+

1% of face is padding. For example, with 1920x1280 resolution face size would be 640x640 and padding would be 3 pixels from each side. (640 * 0.01 = 6 pixels) +

+
+ +

Default value is ‘0’. +Maximum value is ‘0.1’. +

+
+
fin_pad
+
fout_pad
+

Set fixed padding for the input/output cubemap. Values in pixels. +

+

Default value is ‘0’. If greater than zero it overrides other padding options. +

+
+
in_forder
+
out_forder
+

Set order of faces for the input/output cubemap. Choose one direction for each position. +

+

Designation of directions: +

+
‘r’
+

right +

+
‘l’
+

left +

+
‘u’
+

up +

+
‘d’
+

down +

+
‘f’
+

forward +

+
‘b’
+

back +

+
+ +

Default value is ‘rludfb’. +

+
+
in_frot
+
out_frot
+

Set rotation of faces for the input/output cubemap. Choose one angle for each position. +

+

Designation of angles: +

+
‘0’
+

0 degrees clockwise +

+
‘1’
+

90 degrees clockwise +

+
‘2’
+

180 degrees clockwise +

+
‘3’
+

270 degrees clockwise +

+
+ +

Default value is ‘000000’. +

+
+ +
+
‘eac’
+

Equi-Angular Cubemap. +

+
+
‘flat’
+
‘gnomonic’
+
‘rectilinear’
+

Regular video. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘dfisheye’
+

Dual fisheye. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘barrel’
+
‘fb’
+
‘barrelsplit’
+

Facebook’s 360 formats. +

+
+
‘sg’
+

Stereographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘mercator’
+

Mercator format. +

+
+
‘ball’
+

Ball format, gives significant distortion toward the back. +

+
+
‘hammer’
+

Hammer-Aitoff map projection format. +

+
+
‘sinusoidal’
+

Sinusoidal map projection format. +

+
+
‘fisheye’
+

Fisheye projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘pannini’
+

Pannini projection. +

+

Format specific options: +

+
h_fov
+

Set output pannini parameter. +

+
+
ih_fov
+

Set input pannini parameter. +

+
+ +
+
‘cylindrical’
+

Cylindrical projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘perspective’
+

Perspective projection. (output only) +

+

Format specific options: +

+
v_fov
+

Set perspective parameter. +

+
+ +
+
‘tetrahedron’
+

Tetrahedron projection. +

+
+
‘tsp’
+

Truncated square pyramid projection. +

+
+
‘he’
+
‘hequirect’
+

Half equirectangular projection. +

+
+
‘equisolid’
+

Equisolid format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘og’
+

Orthographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘octahedron’
+

Octahedron projection. +

+
+
‘cylindricalea’
+

Cylindrical Equal Area projection. +

+
+ +
+
interp
+

Set interpolation method.
+Note: more complex interpolation methods require much more memory to run. +

+

Available methods: +

+
+
‘near’
+
‘nearest’
+

Nearest neighbour. +

+
‘line’
+
‘linear’
+

Bilinear interpolation. +

+
‘lagrange9’
+

Lagrange9 interpolation. +

+
‘cube’
+
‘cubic’
+

Bicubic interpolation. +

+
‘lanc’
+
‘lanczos’
+

Lanczos interpolation. +

+
‘sp16’
+
‘spline16’
+

Spline16 interpolation. +

+
‘gauss’
+
‘gaussian’
+

Gaussian interpolation. +

+
‘mitchell’
+

Mitchell interpolation. +

+
+ +

Default value is ‘line’. +

+
+
w
+
h
+

Set the output video resolution. +

+

Default resolution depends on formats. +

+
+
in_stereo
+
out_stereo
+

Set the input/output stereo format. +

+
+
‘2d’
+

2D mono +

+
‘sbs’
+

Side by side +

+
‘tb’
+

Top bottom +

+
+ +

Default value is ‘2d’ for input and output format. +

+
+
yaw
+
pitch
+
roll
+

Set rotation for the output video. Values in degrees. +

+
+
rorder
+

Set rotation order for the output video. Choose one item for each position. +

+
+
‘y, Y’
+

yaw +

+
‘p, P’
+

pitch +

+
‘r, R’
+

roll +

+
+ +

Default value is ‘ypr’. +

+
+
h_flip
+
v_flip
+
d_flip
+

Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values. +

+
+
ih_flip
+
iv_flip
+

Set if input video is flipped horizontally/vertically. Boolean values. +

+
+
in_trans
+

Set if input video is transposed. Boolean value, by default disabled. +

+
+
out_trans
+

Set if output video needs to be transposed. Boolean value, by default disabled. +

+
+
h_offset
+
v_offset
+

Set output horizontal/vertical off-axis offset. Default is set to 0. +Allowed range is from -1 to 1. +

+
+
alpha_mask
+

Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled. +

+
+
reset_rot
+

Reset rotation of output video. Boolean value, by default disabled. +

+
+ + +

11.267.1 Examples

+ +
    +
  • Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation: +
    +
    ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
    +
    +
  • Extract back view of Equi-Angular Cubemap: +
    +
    ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
    +
    +
  • Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format: +
    +
    v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
    +
    +
+ + +

11.267.2 Commands

+ +

This filter supports subset of above options as commands. +

+ +

11.268 vaguedenoiser

+ +

Apply a wavelet based denoiser. +

+

It transforms each frame from the video input into the wavelet domain, +using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to +the obtained coefficients. It does an inverse wavelet transform after. +Due to wavelet properties, it should give a nice smoothed result, and +reduced noise, without blurring picture features. +

+

This filter accepts the following options: +

+
+
threshold
+

The filtering strength. The higher, the more filtered the video will be. +Hard thresholding can use a higher threshold than soft thresholding +before the video looks overfiltered. Default value is 2. +

+
+
method
+

The filtering method the filter will use. +

+

It accepts the following values: +

+
‘hard’
+

All values under the threshold will be zeroed. +

+
+
‘soft’
+

All values under the threshold will be zeroed. All values above will be +reduced by the threshold. +

+
+
‘garrote’
+

Scales or nullifies coefficients - intermediary between (more) soft and +(less) hard thresholding. +

+
+ +

Default is garrote. +

+
+
nsteps
+

Number of times, the wavelet will decompose the picture. Picture can’t +be decomposed beyond a particular point (typically, 8 for a 640x480 +frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. +

+
+
percent
+

Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. +

+
+
planes
+

A list of the planes to process. By default all planes are processed. +

+
+
type
+

The threshold type the filter will use. +

+

It accepts the following values: +

+
‘universal’
+

Threshold used is same for all decompositions. +

+
+
‘bayes’
+

Threshold used depends also on each decomposition coefficients. +

+
+ +

Default is universal. +

+
+ + +

11.269 varblur

+

Apply variable blur filter by using 2nd video stream to set blur radius. +The 2nd stream must have the same dimensions. +

+

This filter accepts the following options: +

+
+
min_r
+

Set min allowed radius. Allowed range is from 0 to 254. Default is 0. +

+
max_r
+

Set max allowed radius. Allowed range is from 1 to 255. Default is 8. +

+
planes
+

Set which planes to process. By default, all are used. +

+
+ +

The varblur filter also supports the framesync options. +

+ +

11.269.1 Commands

+ +

This filter supports all the above options as commands. +

+ +

11.270 vectorscope

+ +

Display 2 color component values in the two dimensional graph (which is called +a vectorscope). +

+

This filter accepts the following options: +

+
+
mode, m
+

Set vectorscope mode. +

+

It accepts the following values: +

+
‘gray’
+
‘tint’
+

Gray values are displayed on graph, higher brightness means more pixels have +same component color value on location in graph. This is the default mode. +

+
+
‘color’
+

Gray values are displayed on graph. Surrounding pixels values which are not +present in video frame are drawn in gradient of 2 color components which are +set by option x and y. The 3rd color component is static. +

+
+
‘color2’
+

Actual color components values present in video frame are displayed on graph. +

+
+
‘color3’
+

Similar as color2 but higher frequency of same values x and y +on graph increases value of another color component, which is luminance by +default values of x and y. +

+
+
‘color4’
+

Actual colors present in video frame are displayed on graph. If two different +colors map to same position on graph then color with higher value of component +not present in graph is picked. +

+
+
‘color5’
+

Gray values are displayed on graph. Similar to color but with 3rd color +component picked from radial gradient. +

+
+ +
+
x
+

Set which color component will be represented on X-axis. Default is 1. +

+
+
y
+

Set which color component will be represented on Y-axis. Default is 2. +

+
+
intensity, i
+

Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness +of color component which represents frequency of (X, Y) location in graph. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, even darkest single pixel will be clearly highlighted. +

+
+
‘peak’
+

Hold maximum and minimum values presented in graph over time. This way you +can still spot out of range values without constantly looking at vectorscope. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
graticule, g
+

Set what kind of graticule to draw. +

+
‘none’
+
‘green’
+
‘color’
+
‘invert’
+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, f
+

Set graticule flags. +

+
+
‘white’
+

Draw graticule for white point. +

+
+
‘black’
+

Draw graticule for black point. +

+
+
‘name’
+

Draw color points short names. +

+
+ +
+
bgopacity, b
+

Set background opacity. +

+
+
lthreshold, l
+

Set low threshold for color component not represented on X or Y axis. +Values lower than this value will be ignored. Default is 0. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and low threshold value of 0.1 actual threshold +is 0.1 * 255 = 25. +

+
+
hthreshold, h
+

Set high threshold for color component not represented on X or Y axis. +Values higher than this value will be ignored. Default is 1. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and high threshold value of 0.9 actual threshold +is 0.9 * 255 = 230. +

+
+
colorspace, c
+

Set what kind of colorspace to use when drawing graticule. +

+
‘auto’
+
‘601’
+
‘709’
+
+

Default is auto. +

+
+
tint0, t0
+
tint1, t1
+

Set color tint for gray/tint vectorscope mode. By default both options are zero. +This means no tint, and output will remain gray. +

+
+ + +

11.271 vidstabdetect

+ +

Analyze video stabilization/deshaking. Perform pass 1 of 2, see +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 vidstabtransform filter. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libvidstab. +

+

This filter accepts the following options: +

+
+
result
+

Set the path to the file used to write the transforms information. +Default value is transforms.trf. +

+
+
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. +

+
+
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 15. +

+
+
stepsize
+

Set stepsize of the search process. The region around minimum is +scanned with 1 pixel resolution. Default value is 6. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
fileformat
+

Format for the transforms data file to be written. +Acceptable values are +

+
+
‘ascii’
+

Human-readable plain text +

+
+
‘binary’
+

Binary format, roughly 40% smaller than ascii. (default) +

+
+ +
+
+ + +

11.271.1 Examples

+ +
    +
  • Use default values: +
    +
    vidstabdetect
    +
    + +
  • Analyze strongly shaky movie and put the results in file +mytransforms.trf: +
    +
    vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
    +
    + +
  • Visualize the result of internal transformations in the resulting +video: +
    +
    vidstabdetect=show=1
    +
    + +
  • Analyze a video with medium shakiness using ffmpeg: +
    +
    ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
    +
    +
+ + +

11.272 vidstabtransform

+ +

Video stabilization/deshaking: pass 2 of 2, +see vidstabdetect for pass 1. +

+

Read a file with transform information for each frame and +apply/compensate them. Together with the vidstabdetect +filter this can be used to deshake videos. See also +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 +--enable-libvidstab. +

+ +

11.272.1 Options

+ +
+
input
+

Set path to the file used to read the transforms. Default value is +transforms.trf. +

+
+
smoothing
+

Set the number of frames (value*2 + 1) used for lowpass filtering the +camera movements. Default value is 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 value leads to a smoother video, but limits the acceleration of +the camera (pan/tilt movements). 0 is a special case where a static +camera is simulated. +

+
+
optalgo
+

Set the camera path optimization algorithm. +

+

Accepted values are: +

+
‘gauss’
+

gaussian kernel low-pass filter on camera motion (default) +

+
‘avg’
+

averaging on transformations +

+
+ +
+
maxshift
+

Set maximal number of pixels to translate frames. Default value is -1, +meaning no limit. +

+
+
maxangle
+

Set maximal angle in radians (degree*PI/180) to rotate frames. Default +value is -1, meaning no limit. +

+
+
crop
+

Specify how to deal with borders that may be visible due to movement +compensation. +

+

Available values are: +

+
‘keep’
+

keep image information from previous frame (default) +

+
‘black’
+

fill the border black +

+
+ +
+
invert
+

Invert transforms if set to 1. Default value is 0. +

+
+
relative
+

Consider transforms as relative to previous frame if set to 1, +absolute if set to 0. Default value is 0. +

+
+
zoom
+

Set percentage to zoom. A positive value will result in a zoom-in +effect, a negative value in a zoom-out effect. Default value is 0 (no +zoom). +

+
+
optzoom
+

Set optimal zooming to avoid borders. +

+

Accepted values are: +

+
‘0’
+

disabled +

+
‘1’
+

optimal static zoom value is determined (only very strong movements +will lead to visible borders) (default) +

+
‘2’
+

optimal adaptive zoom value is determined (no borders will be +visible), see zoomspeed +

+
+ +

Note that the value given at zoom is added to the one calculated here. +

+
+
zoomspeed
+

Set percent to zoom maximally each frame (enabled when +optzoom is set to 2). Range is from 0 to 5, default value is +0.25. +

+
+
interpol
+

Specify type of interpolation. +

+

Available values are: +

+
‘no’
+

no interpolation +

+
‘linear’
+

linear only horizontal +

+
‘bilinear’
+

linear in both directions (default) +

+
‘bicubic’
+

cubic in both directions (slow) +

+
+ +
+
tripod
+

Enable virtual tripod mode if set to 1, which is equivalent to +relative=0:smoothing=0. Default value is 0. +

+

Use also tripod option of vidstabdetect. +

+
+
debug
+

Increase log verbosity if set to 1. Also the detected global motions +are written to the temporary file global_motions.trf. Default +value is 0. +

+
+ + +

11.272.2 Examples

+ +
    +
  • Use ffmpeg for a typical stabilization with default values: +
    +
    ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
    +
    + +

    Note the use of the unsharp filter which is always recommended. +

    +
  • Zoom in a bit more and load transform data from a given file: +
    +
    vidstabtransform=zoom=5:input="mytransforms.trf"
    +
    + +
  • Smoothen the video even more: +
    +
    vidstabtransform=smoothing=30
    +
    +
+ + +

11.273 vflip

+ +

Flip the input video vertically. +

+

For example, to vertically flip a video with ffmpeg: +

+
ffmpeg -i in.avi -vf "vflip" out.avi
+
+ + +

11.274 vfrdet

+ +

Detect variable frame rate video. +

+

This filter tries to detect if the input is variable or constant frame rate. +

+

At end it will output number of frames detected as having variable delta pts, +and ones with constant delta pts. +If there was frames with variable delta, than it will also show min, max and +average delta encountered. +

+ +

11.275 vibrance

+ +

Boost or alter saturation. +

+

The filter accepts the following options: +

+
intensity
+

Set strength of boost if positive value or strength of alter if negative value. +Default is 0. Allowed range is from -2 to 2. +

+
+
rbal
+

Set the red balance. Default is 1. Allowed range is from -10 to 10. +

+
+
gbal
+

Set the green balance. Default is 1. Allowed range is from -10 to 10. +

+
+
bbal
+

Set the blue balance. Default is 1. Allowed range is from -10 to 10. +

+
+
rlum
+

Set the red luma coefficient. +

+
+
glum
+

Set the green luma coefficient. +

+
+
blum
+

Set the blue luma coefficient. +

+
+
alternate
+

If intensity is negative and this is set to 1, colors will change, +otherwise colors will be less saturated, more towards gray. +

+
+ + +

11.275.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

11.276 vif

+ +

Obtain the average VIF (Visual Information Fidelity) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 VIF score is printed through the logging system. +

+

The filter stores the calculated VIF score of each frame. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi vif -f null -
+
+ + +

11.277 vignette

+ +

Make or reverse a natural vignetting effect. +

+

The filter accepts the following options: +

+
+
angle, a
+

Set lens angle expression as a number of radians. +

+

The value is clipped in the [0,PI/2] range. +

+

Default value: "PI/5" +

+
+
x0
+
y0
+

Set center coordinates expressions. Respectively "w/2" and "h/2" +by default. +

+
+
mode
+

Set forward/backward mode. +

+

Available modes are: +

+
‘forward’
+

The larger the distance from the central point, the darker the image becomes. +

+
+
‘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 angle and other settings (yet). It can +also be used to create a burning effect. +

+
+ +

Default value is ‘forward’. +

+
+
eval
+

Set evaluation mode for the expressions (angle, x0, y0). +

+

It accepts the following values: +

+
‘init’
+

Evaluate expressions only once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. This is way slower than the +‘init’ mode since it requires all the scalers to be re-computed, but it +allows advanced dynamic expressions. +

+
+ +

Default value is ‘init’. +

+
+
dither
+

Set dithering to reduce the circular banding effects. Default is 1 +(enabled). +

+
+
aspect
+

Set vignette aspect. This setting allows one 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 1/1. +

+
+ + +

11.277.1 Expressions

+ +

The alpha, x0 and y0 expressions can contain the +following parameters. +

+
+
w
+
h
+

input width and height +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pts
+

the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in +TB units, NAN if undefined +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined +

+
+
tb
+

time base of the input video +

+
+ + + +

11.277.2 Examples

+ +
    +
  • Apply simple strong vignetting effect: +
    +
    vignette=PI/4
    +
    + +
  • Make a flickering vignetting: +
    +
    vignette='PI/4+random(1)*PI/50':eval=frame
    +
    + +
+ + +

11.278 vmafmotion

+ +

Obtain the average VMAF motion score of a video. +It is one of the component metrics of VMAF. +

+

The obtained average motion score is printed through the logging system. +

+

The filter accepts the following options: +

+
+
stats_file
+

If specified, the filter will use the named file to save the motion score of +each frame with respect to the previous frame. +When filename equals "-" the data is sent to standard output. +

+
+ +

Example: +

+
ffmpeg -i ref.mpg -vf vmafmotion -f null -
+
+ + +

11.279 vpp_amf

+ +

Scale (resize) and convert colorspace, transfer characteristics or color primaries for the input video, using AMD Advanced Media Framework library for hardware acceleration. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
scale_type
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+

This is the default. +

+
+
bicubic
+

Bicubic +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+ +
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
color_profile
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt601’
+

BT.601 +

+
+
‘bt709’
+

BT.709 +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘linear’
+

Linear +

+
+
‘log’
+

LOG +

+
+
‘log-sqrt’
+

LOG_SQRT +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘bt1361-ecg’
+

BT1361_ECG +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
‘smpte2084’
+

SMPTE2084 +

+
+
‘smpte428’
+

SMPTE428 +

+
+
‘arib-std-b67’
+

ARIB_STD_B67 +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘smpte428’
+

SMPTE-428 +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+
+
+ + +

11.279.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    vpp_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K and change color profile to bt2020. +
    +
    vpp_amf=4096:2160:color_profile=bt2020
    +
    +
+ + +

11.280 vstack

+

Stack input videos vertically. +

+

All streams must be of same pixel format and of same width. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

11.281 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. +

+

This filter uses 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 setfield filter before w3fdif filter. +

+

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: +

+
+
filter
+

Set the interlacing filter coefficients. Accepts one of the following values: +

+
+
‘simple’
+

Simple filter coefficient set. +

+
‘complex’
+

More-complex filter coefficient set. +

+
+

Default value is ‘complex’. +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames, +

+
‘interlaced’
+

Only deinterlace frames marked as interlaced. +

+
+ +

Default value is ‘all’. +

+
+ + +

11.281.1 Commands

+

This filter supports same commands as options. +

+ +

11.282 waveform

+

Video waveform monitor. +

+

The waveform monitor plots color component intensity. By default luma +only. Each column of the waveform corresponds to a column of pixels in the +source video. +

+

It accepts the following options: +

+
+
mode, m
+

Can be either row, or column. Default is column. +In row mode, the graph on the left side represents color component value 0 and +the right side represents value = 255. In column mode, the top side represents +color component value = 0 and bottom side represents value = 255. +

+
+
intensity, i
+

Set intensity. Smaller values are useful to find out how many values of the same +luminance are distributed across input rows/columns. +Default value is 0.04. Allowed range is [0, 1]. +

+
+
mirror, r
+

Set mirroring mode. 0 means unmirrored, 1 means mirrored. +In mirrored mode, higher values will be represented on the left +side for row mode and at the top for column mode. Default is +1 (mirrored). +

+
+
display, d
+

Set display mode. +It accepts the following values: +

+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+

This display mode makes it easier to spot relative differences or similarities +in overlapping areas of the color components that are supposed to be identical, +such as neutral whites, grays, or blacks. +

+
+
‘stack’
+

Display separate graph for the color components side by side in +row mode or one below the other in column mode. +

+
+
‘parade’
+

Display separate graph for the color components side by side in +column mode or one below the other in row mode. +

+

Using this display mode makes it easy to spot color casts in the highlights +and shadows of an image, by comparing the contours of the top and the bottom +graphs of each waveform. Since whites, grays, and blacks are characterized +by exactly equal amounts of red, green, and blue, neutral areas of the picture +should display three waveforms of roughly equal width/height. If not, the +correction is easy to perform by making level adjustments the three waveforms. +

+
+

Default is stack. +

+
+
components, c
+

Set which color components to display. Default is 1, which means only luma +or red color component if input is in RGB colorspace. If is set for example to +7 it will display all 3 (if) available color components. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, minimum and maximum values presented in graph will be easily +visible even with small step value. +

+
+
‘peak’
+

Hold minimum and maximum values presented in graph across time. This way you +can still spot out of range values without constantly looking at waveforms. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
filter, f
+
+
‘lowpass’
+

No filtering, this is default. +

+
+
‘flat’
+

Luma and chroma combined together. +

+
+
‘aflat’
+

Similar as above, but shows difference between blue and red chroma. +

+
+
‘xflat’
+

Similar as above, but use different colors. +

+
+
‘yflat’
+

Similar as above, but again with different colors. +

+
+
‘chroma’
+

Displays only chroma. +

+
+
‘color’
+

Displays actual color value on waveform. +

+
+
‘acolor’
+

Similar as above, but with luma showing frequency of chroma values. +

+
+ +
+
graticule, g
+

Set which graticule to display. +

+
+
‘none’
+

Do not display graticule. +

+
+
‘green’
+

Display green graticule showing legal broadcast ranges. +

+
+
‘orange’
+

Display orange graticule showing legal broadcast ranges. +

+
+
‘invert’
+

Display invert graticule showing legal broadcast ranges. +

+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, fl
+

Set graticule flags. +

+
+
‘numbers’
+

Draw numbers above lines. By default enabled. +

+
+
‘dots’
+

Draw dots instead of lines. +

+
+ +
+
scale, s
+

Set scale used for displaying graticule. +

+
+
‘digital’
+
‘millivolts’
+
‘ire’
+
+

Default is digital. +

+
+
bgopacity, b
+

Set background opacity. +

+
+
tint0, t0
+
tint1, t1
+

Set tint for output. +Only used with lowpass filter and when display is not overlay and input +pixel formats are not RGB. +

+
+
fitmode, fm
+

Set sample aspect ratio of video output frames. +Can be used to configure waveform so it is not +stretched too much in one of directions. +

+
+
‘none’
+

Set sample aspect ration to 1/1. +

+
‘size’
+

Set sample aspect ratio to match input size of video +

+
+

Default is ‘none’. +

+
+
input
+

Set input formats for filter to pick from. +Can be ‘all’, for selecting from all available formats, +or ‘first’, for selecting first available format. +Default is ‘first’. +

+
+ + +

11.283 weave, doubleweave

+ +

The weave takes a field-based video input and join +each two sequential fields into single frame, producing a new double +height clip with half the frame rate and half the frame count. +

+

The doubleweave works same as weave but without +halving frame rate and frame count. +

+

It accepts the following option: +

+
+
first_field
+

Set first field. Available values are: +

+
+
‘top, t’
+

Set the frame as top-field-first. +

+
+
‘bottom, b’
+

Set the frame as bottom-field-first. +

+
+
+
+ + +

11.283.1 Examples

+ +
    +
  • Interlace video using select and separatefields filter: +
    +
    separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
    +
    +
+ + +

11.284 xbr

+

Apply the xBR high-quality magnification filter which is designed for pixel +art. It follows a set of edge-detection rules, see +https://forums.libretro.com/t/xbr-algorithm-tutorial/123. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xBR, 3 for +3xBR and 4 for 4xBR. +Default is 3. +

+
+ + +

11.285 xcorrelate

+

Apply normalized cross-correlation between first and second input video stream. +

+

Second input video stream dimensions must be lower than first input video stream. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
secondary
+

Set which secondary video frames will be processed from second input video stream, +can be first or all. Default is all. +

+
+ +

The xcorrelate filter also supports the framesync options. +

+ +

11.286 xfade

+ +

Apply cross fade from one input video stream to another input video stream. +The cross fade is applied for specified duration. +

+

Both inputs must be constant frame-rate and have the same resolution, pixel format, +frame rate and timebase. +

+

The filter accepts the following options: +

+
+
transition
+

Set one of available transition effects: +

+
+
‘custom’
+
‘fade’
+
‘wipeleft’
+
‘wiperight’
+
‘wipeup’
+
‘wipedown’
+
‘slideleft’
+
‘slideright’
+
‘slideup’
+
‘slidedown’
+
‘circlecrop’
+
‘rectcrop’
+
‘distance’
+
‘fadeblack’
+
‘fadewhite’
+
‘radial’
+
‘smoothleft’
+
‘smoothright’
+
‘smoothup’
+
‘smoothdown’
+
‘circleopen’
+
‘circleclose’
+
‘vertopen’
+
‘vertclose’
+
‘horzopen’
+
‘horzclose’
+
‘dissolve’
+
‘pixelize’
+
‘diagtl’
+
‘diagtr’
+
‘diagbl’
+
‘diagbr’
+
‘hlslice’
+
‘hrslice’
+
‘vuslice’
+
‘vdslice’
+
‘hblur’
+
‘fadegrays’
+
‘wipetl’
+
‘wipetr’
+
‘wipebl’
+
‘wipebr’
+
‘squeezeh’
+
‘squeezev’
+
‘zoomin’
+
‘fadefast’
+
‘fadeslow’
+
‘hlwind’
+
‘hrwind’
+
‘vuwind’
+
‘vdwind’
+
‘coverleft’
+
‘coverright’
+
‘coverup’
+
‘coverdown’
+
‘revealleft’
+
‘revealright’
+
‘revealup’
+
‘revealdown’
+
+

Default transition effect is fade. +

+
+
duration
+

Set cross fade duration in seconds. +Range is 0 to 60 seconds. +Default duration is 1 second. +

+
+
offset
+

Set cross fade start relative to first input stream in seconds. +Default offset is 0. +

+
+
expr
+

Set expression for custom transition effect. +

+

The expressions can use the following variables and functions: +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
P
+

Progress of transition effect. +

+
+
PLANE
+

Currently processed plane. +

+
+
A
+

Return value of first input at current location and plane. +

+
+
B
+

Return value of second input at current location and plane. +

+
+
a0(x, y)
+
a1(x, y)
+
a2(x, y)
+
a3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of first input. +

+
+
b0(x, y)
+
b1(x, y)
+
b2(x, y)
+
b3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of second input. +

+
+
+
+ + +

11.286.1 Examples

+ +
    +
  • Cross fade from one input video to another input video, with fade transition and duration of transition +of 2 seconds starting at offset of 5 seconds: +
    +
    ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
    +
    +
+ + +

11.287 xmedian

+

Pick median pixels from several input videos. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. +Default is 3. Allowed range is from 3 to 255. +If number of inputs is even number, than result will be mean value between two median values. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

11.287.1 Commands

+ +

This filter supports all above options as commands, excluding option inputs. +

+ +

11.288 xpsnr

+ +

Obtain the average (across all input frames) and minimum (across all color plane averages) +eXtended Perceptually weighted peak Signal-to-Noise Ratio (XPSNR) between two input videos. +

+

The XPSNR is a low-complexity psychovisually motivated distortion measurement algorithm for +assessing the difference between two video streams or images. This is especially useful for +objectively quantifying the distortions caused by video and image codecs, as an alternative +to a formal subjective test. The logarithmic XPSNR output values are in a similar range as +those of traditional psnr assessments but better reflect human impressions of visual +coding quality. More details on the XPSNR measure, which essentially represents a blockwise +weighted variant of the PSNR measure, can be found in the following freely available papers: +

+
    +
  • C. R. Helmrich, M. Siekmann, S. Becker, S. Bosse, D. Marpe, and T. Wiegand, "XPSNR: A +Low-Complexity Extension of the Perceptually Weighted Peak Signal-to-Noise Ratio for +High-Resolution Video Quality Assessment," in Proc. IEEE Int. Conf. Acoustics, Speech, +Sig. Process. (ICASSP), virt./online, May 2020. www.ecodis.de/xpsnr.htm + +
  • C. R. Helmrich, S. Bosse, H. Schwarz, D. Marpe, and T. Wiegand, "A Study of the +Extended Perceptually Weighted Peak Signal-to-Noise Ratio (XPSNR) for Video Compression +with Different Resolutions and Bit Depths," ITU Journal: ICT Discoveries, vol. 3, no. +1, pp. 65 - 72, May 2020. http://handle.itu.int/11.1002/pub/8153d78b-en +
+ +

When publishing the results of XPSNR assessments obtained using, e.g., this FFmpeg filter, a +reference to the above papers as a means of documentation is strongly encouraged. The filter +requires two input videos. The first input is considered a (usually not distorted) reference +source and is passed unchanged to the output, whereas the second input is a (distorted) test +signal. Except for the bit depth, these two video inputs must have the same pixel format. In +addition, for best performance, both compared input videos should be in YCbCr color format. +

+

The obtained overall XPSNR values mentioned above are printed through the logging system. In +case of input with multiple color planes, we suggest reporting of the minimum XPSNR average. +

+

The following parameter, which behaves like the one for the psnr filter, is accepted: +

+
+
stats_file, f
+

If specified, the filter will use the named file to save the XPSNR value of each individual +frame and color plane. When the file name equals "-", that data is sent to standard output. +

+
+ +

This filter also supports the framesync options. +

+ +

11.288.1 Examples

+
    +
  • XPSNR analysis of two 1080p HD videos, ref_source.yuv and test_video.yuv, both at 24 frames +per second, with color format 4:2:0, bit depth 8, and output of a logfile named "xpsnr.log": +
    +
    ffmpeg -s 1920x1080 -framerate 24 -pix_fmt yuv420p -i ref_source.yuv -s 1920x1080 -framerate
    +24 -pix_fmt yuv420p -i test_video.yuv -lavfi xpsnr="stats_file=xpsnr.log" -f null -
    +
    + +
  • XPSNR analysis of two 2160p UHD videos, ref_source.yuv with bit depth 8 and test_video.yuv +with bit depth 10, both at 60 frames per second with color format 4:2:0, no logfile output: +
    +
    ffmpeg -s 3840x2160 -framerate 60 -pix_fmt yuv420p -i ref_source.yuv -s 3840x2160 -framerate
    +60 -pix_fmt yuv420p10le -i test_video.yuv -lavfi xpsnr="stats_file=-" -f null -
    +
    +
+ + +

11.289 xstack

+

Stack video inputs into custom layout. +

+

All streams must be of same pixel format. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
layout
+

Specify layout of inputs. +This option requires the desired layout configuration to be explicitly set by the user. +This sets position of each video input in output. Each input +is separated by ’|’. +The first number represents the column, and the second number represents the row. +Numbers start at 0 and are separated by ’_’. Optionally one can use wX and hX, +where X is video input from which to take width or height. +Multiple values can be used when separated by ’+’. In such +case values are summed together. +

+

Note that if inputs are of different sizes gaps may appear, as not all of +the output video frame will be filled. Similarly, videos can overlap each +other if their position doesn’t leave enough space for the full frame of +adjoining videos. +

+

For 2 inputs, a default layout of 0_0|w0_0 (equivalent to +grid=2x1) is set. In all other cases, a layout or a grid must be set by +the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
grid
+

Specify a fixed size grid of inputs. +This option is used to create a fixed size grid of the input streams. Set the +grid size in the form COLUMNSxROWS. There must be ROWS * COLUMNS +input streams and they will be arranged as a grid with ROWS rows and +COLUMNS columns. When using this option, each input stream within a row +must have the same height and all the rows must have the same width. +

+

If grid is set, then inputs option is ignored and is implicitly +set to ROWS * COLUMNS. +

+

For 2 inputs, a default grid of 2x1 (equivalent to +layout=0_0|w0_0) is set. In all other cases, a layout or a grid must be +set by the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
fill
+

If set to valid color, all unused pixels will be filled with that color. +By default fill is set to none, so it is disabled. +

+
+ + +

11.289.1 Examples

+ +
    +
  • Display 4 inputs into 2x2 grid. + +

    Layout: +

    +
    input1(0, 0)  | input3(w0, 0)
    +input2(0, h0) | input4(w0, h0)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 4 inputs into 1x4 grid. + +

    Layout: +

    +
    input1(0, 0)
    +input2(0, h0)
    +input3(0, h0+h1)
    +input4(0, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
    +
    + +

    Note that if inputs are of different widths, unused space will appear. +

    +
  • Display 9 inputs into 3x3 grid. + +

    Layout: +

    +
    input1(0, 0)       | input4(w0, 0)      | input7(w0+w3, 0)
    +input2(0, h0)      | input5(w0, h0)     | input8(w0+w3, h0)
    +input3(0, h0+h1)   | input6(w0, h0+h1)  | input9(w0+w3, h0+h1)
    +
    + +
    +
    xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 16 inputs into 4x4 grid. + +

    Layout: +

    +
    input1(0, 0)       | input5(w0, 0)       | input9 (w0+w4, 0)       | input13(w0+w4+w8, 0)
    +input2(0, h0)      | input6(w0, h0)      | input10(w0+w4, h0)      | input14(w0+w4+w8, h0)
    +input3(0, h0+h1)   | input7(w0, h0+h1)   | input11(w0+w4, h0+h1)   | input15(w0+w4+w8, h0+h1)
    +input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0|
    +w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
+ + +

11.290 yadif

+ +

Deinterlace the input video ("yadif" means "yet another deinterlacing +filter"). +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

11.291 yaepblur

+ +

Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter"). +The algorithm is described in +"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980." +

+

It accepts the following parameters: +

+
+
radius, r
+

Set the window radius. Default value is 3. +

+
+
planes, p
+

Set which planes to filter. Default is only the first plane. +

+
+
sigma, s
+

Set blur strength. Default value is 128. +

+
+ + +

11.291.1 Commands

+

This filter supports same commands as options. +

+ +

11.292 zoompan

+ +

Apply Zoom & Pan effect. +

+

This filter accepts the following options: +

+
+
zoom, z
+

Set the zoom expression. Range is 1-10. Default is 1. +

+
+
x
+
y
+

Set the x and y expression. Default is 0. +

+
+
d
+

Set the duration expression in number of frames. +This sets for how many number of frames effect will last for +single input image. Default is 90. +

+
+
s
+

Set the output image size, default is ’hd720’. +

+
+
fps
+

Set the output frame rate, default is ’25’. +

+
+ +

Each expression can contain the following constants: +

+
+
in_w, iw
+

Input width. +

+
+
in_h, ih
+

Input height. +

+
+
out_w, ow
+

Output width. +

+
+
out_h, oh
+

Output height. +

+
+
in
+

Input frame count. +

+
+
on
+

Output frame count. +

+
+
in_time, it
+

The input timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
out_time, time, ot
+

The output timestamp expressed in seconds. +

+
+
x
+
y
+

Last calculated ’x’ and ’y’ position from ’x’ and ’y’ expression +for current input frame. +

+
+
px
+
py
+

’x’ and ’y’ of last output frame of previous input frame or 0 when there was +not yet such frame (first input frame). +

+
+
zoom
+

Last calculated zoom from ’z’ expression for current input frame. +

+
+
pzoom
+

Last calculated zoom of last output frame of previous input frame. +

+
+
duration
+

Number of output frames for current input frame. Calculated from ’d’ expression +for each input frame. +

+
+
pduration
+

number of output frames created for previous input frame +

+
+
a
+

Rational number: input width / input height +

+
+
sar
+

sample aspect ratio +

+
+
dar
+

display aspect ratio +

+
+
+ + +

11.292.1 Examples

+ +
    +
  • Zoom in up to 1.5x and pan at same time to some spot near center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360
    +
    + +
  • Zoom in up to 1.5x and pan always at center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Same as above but without pausing: +
    +
    zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Zoom in 2x into center of picture only for the first second of the input video: +
    +
    zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
+ + +

11.293 zscale

+

Scale (resize) the input video, using the z.lib library: +https://github.com/sekrit-twc/zimg. To enable compilation of this +filter, you need to configure FFmpeg with --enable-libzimg. +

+

The zscale filter forces the output display aspect ratio to be the same +as the input, by changing the output sample aspect ratio. +

+

If the input image format is different from the format requested by +the next filter, the zscale filter will convert the input to the +requested format. +

+ +

11.293.1 Options

+

The filter accepts the following options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the zscale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
dither, d
+

Set the dither type. +

+

Possible values are: +

+
none
+
ordered
+
random
+
error_diffusion
+
+ +

Default is none. +

+
+
filter, f
+

Set the resize filter type. +

+

Possible values are: +

+
point
+
bilinear
+
bicubic
+
spline16
+
spline36
+
spline64
+
lanczos
+
+ +

Default is bilinear. +

+
+
range, r
+

Set the color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
smpte2084
+
iec61966-2-1
+
arib-std-b67
+
+ +

Default is same as input. +

+
+
matrix, m
+

Set the colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +

Default is same as input. +

+
+
rangein, rin
+

Set the input color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primariesin, pin
+

Set the input color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transferin, tin
+

Set the input transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
+ +

Default is same as input. +

+
+
matrixin, min
+

Set the input colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +
+
chromal, c
+

Set the output chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
chromalin, cin
+

Set the input chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
npl
+

Set the nominal peak luminance. +

+
+
param_a
+

Parameter A for scaling filters. Parameter "b" for bicubic, and the number of +filter taps for lanczos. +

+
+
param_b
+

Parameter B for scaling filters. Parameter "c" for bicubic. +

+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

11.293.2 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + + +

12 CUDA Video Filters

+ +

To enable CUDA and/or NPP filters please refer to configuration guidelines for CUDA and for CUDA NPP filters. +

+

Running CUDA filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device cuda[=name][:device[,key=value...]]
+

Initialise a new hardware device of type cuda called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of initializing second CUDA device on the system and running scale_cuda and bilateral_cuda filters. +
    +
    ./ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -init_hw_device cuda:1 -filter_complex \
    +"[0:v]scale_cuda=format=yuv444p[scaled_video];[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    +
+ +

Since CUDA filters operate exclusively on GPU memory, frame data must sometimes be uploaded (hwupload) to hardware surfaces associated with the appropriate CUDA device before processing, and downloaded (hwdownload) back to normal memory afterward, if required. Whether hwupload or hwdownload is necessary depends on the specific workflow: +

+
    +
  • If the input frames are already in GPU memory (e.g., when using -hwaccel cuda or -hwaccel_output_format cuda), explicit use of hwupload is not needed, as the data is already in the appropriate memory space. +
  • If the input frames are in CPU memory (e.g., software-decoded frames or frames processed by CPU-based filters), it is necessary to use hwupload to transfer the data to GPU memory for CUDA processing. +
  • If the output of the CUDA filters needs to be further processed by software-based filters or saved in a format not supported by GPU-based encoders, hwdownload is required to transfer the data back to CPU memory. +
+

Note that hwupload uploads data to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before hwupload to ensure the input is in the correct format. Similarly, hwdownload may not support all output formats, so an additional format filter may need to be inserted immediately after hwdownload in the filter graph to ensure compatibility. +

+ +

12.1 CUDA

+

Below is a description of the currently available Nvidia CUDA video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
+ +

Note: If FFmpeg detects the Nvidia CUDA Toolkit during configuration, it will enable CUDA filters automatically without requiring any additional flags. If you want to explicitly enable them, use the following options: +

+
    +
  • Configure FFmpeg with --enable-cuda-nvcc --enable-nonfree. +
  • Configure FFmpeg with --enable-cuda-llvm. Additional requirement: llvm lib must be installed. +
+ + +

12.1.1 bilateral_cuda

+

CUDA accelerated bilateral filter, an edge preserving filter. +This filter is mathematically accurate thanks to the use of GPU acceleration. +For best output quality, use one to one chroma subsampling, i.e. yuv444p format. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight, also called sigma space. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate color range weight, also called sigma color. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
window_size
+

Set window size of the bilateral function to determine the number of neighbours to loop on. +If the number entered is even, one will be added automatically. +Allowed range is 1 to 255. Default is 1. +

+
+ +

12.1.1.1 Examples

+ +
    +
  • Apply the bilateral filter on a video. + +
    +
    ./ffmpeg -v verbose \
    +-hwaccel cuda -hwaccel_output_format cuda -i input.mp4  \
    +-init_hw_device cuda \
    +-filter_complex \
    +" \
    +[0:v]scale_cuda=format=yuv444p[scaled_video];
    +[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    + +
+ + +

12.1.2 bwdif_cuda

+ +

Deinterlace the input video using the bwdif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

12.1.3 chromakey_cuda

+

CUDA accelerated YUV colorspace color/chroma keying. +

+

This filter works like normal chromakey filter but operates on CUDA frames. +for more details and parameters see chromakey. +

+ +

12.1.3.1 Examples

+ +
    +
  • Make all the green pixels in the input video transparent and use it as an overlay for another video: + +
    +
    ./ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -i input_green.mp4  \
    +    -hwaccel cuda -hwaccel_output_format cuda -i base_video.mp4 \
    +    -init_hw_device cuda \
    +    -filter_complex \
    +    " \
    +        [0:v]chromakey_cuda=0x25302D:0.1:0.12:1[overlay_video]; \
    +        [1:v]scale_cuda=format=yuv420p[base]; \
    +        [base][overlay_video]overlay_cuda" \
    +    -an -sn -c:v h264_nvenc -cq 20 output.mp4
    +
    + +
  • Process two software sources, explicitly uploading the frames: + +
    +
    ./ffmpeg -init_hw_device cuda=cuda -filter_hw_device cuda \
    +    -f lavfi -i color=size=800x600:color=white,format=yuv420p \
    +    -f lavfi -i yuvtestsrc=size=200x200,format=yuv420p \
    +    -filter_complex \
    +    " \
    +        [0]hwupload[under]; \
    +        [1]hwupload,chromakey_cuda=green:0.1:0.12[over]; \
    +        [under][over]overlay_cuda" \
    +    -c:v hevc_nvenc -cq 18 -preset slow output.mp4
    +
    + +
+ + +

12.1.4 colorspace_cuda

+ +

CUDA accelerated implementation of the colorspace filter. +

+

It is by no means feature complete compared to the software colorspace filter, +and at the current time only supports color range conversion between jpeg/full +and mpeg/limited range. +

+

The filter accepts the following options: +

+
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
+ + +

12.1.5 overlay_cuda

+ +

Overlay one video on top of another. +

+

This is the CUDA variant of the overlay filter. +It only accepts CUDA frames. The underlying input pixel formats have to match. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

They can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
n
+

The ordinal index of the main input frame, starting from 0. +

+
+
pos
+

The byte offset position in the file of the main input frame, NAN if unknown. +Deprecated, do not use. +

+
+
t
+

The timestamp of the main input frame, expressed in seconds, NAN if unknown. +

+
+
+ +

Default value is "0" for both expressions. +

+
+
eval
+

Set when the expressions for x and y are evaluated. +

+

It accepts the following values: +

+
init
+

Evaluate expressions once during filter initialization or +when a command is processed. +

+
+
frame
+

Evaluate expressions for each incoming frame +

+
+ +

Default value is frame. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+ + +

12.1.6 pad_cuda

+

Add paddings to an input video stream using CUDA. +

+

This filter is the CUDA-accelerated version of the pad filter. It accepts the same options and expressions and provides the same core functionality. +For a detailed description of available options, please see the documentation for the pad filter. +

+ +

12.1.6.1 Examples

+ +
    +
  • Add a 200-pixel black border to all sides of a video frame: +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=iw+400:h=ih+400:x=200:y=200" -c:v h264_nvenc out.mp4
    +
    + +
  • Pad the input video to a 16:9 aspect ratio, filling with the color "blue": +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=ih*16/9/sar:h=ih:x=(ow-iw)/2:y=(oh-ih)/2:color=blue" -c:v h264_nvenc out.mp4
    +
    +
+ + +

12.1.7 scale_cuda

+ +

Scale (resize) and convert (pixel format) the input video, using accelerated CUDA kernels. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
interp_algo
+

Sets the algorithm used for scaling: +

+
+
nearest
+

Nearest neighbour +

+

Used by default if input parameters match the desired output. +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+

This is the default. +

+
+
lanczos
+

Lanczos +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+

The filter does not support converting between YUV and RGB pixel formats. +

+
+
passthrough
+

If set to 0, every frame is processed, even if no conversion is necessary. +This mode can be useful to use the filter as a buffer for a downstream +frame-consumer that exhausts the limited decoder frame pool. +

+

If set to 1, frames are passed through as-is if they match the desired output +parameters. This is the default behaviour. +

+
+
param
+

Algorithm-Specific parameter. +

+

Affects the curves of the bicubic algorithm. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
+ + +

12.1.7.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    scale_cuda=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K using nearest neighbour algorithm. +
    +
    scale_cuda=4096:2160:interp_algo=nearest
    +
    + +
  • Don’t do any conversion or scaling, but copy all input frames into newly allocated ones. +This can be useful to deal with a filter and encode chain that otherwise exhausts the +decoders frame pool. +
    +
    scale_cuda=passthrough=0
    +
    +
+ + +

12.1.8 thumbnail_cuda

+ +

Select the most representative frame in a given sequence of consecutive frames using CUDA. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

12.1.8.1 Example

+ +
    +
  • Thumbnails are extracted from every n=150-frame batch, selecting one per batch. Chosen frames are then scaled with scale_cuda. +
    +
    ./ffmpeg  -hwaccel cuda -hwaccel_output_format cuda  -i ./input.mp4 -vf "thumbnail_cuda=150,scale_cuda=1920:1080,hwdownload,format=nv12" ./output/out%03d.png
    +
    + +
+ + +

12.1.9 yadif_cuda

+ +

Deinterlace the input video using the yadif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

12.2 CUDA NPP

+

Below is a description of the currently available NVIDIA Performance Primitives (libnpp) video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
  • Install libnpp +
+ +

To enable CUDA NPP filters: +

+
    +
  • Configure FFmpeg with --enable-nonfree --enable-libnpp. +
+ + + +

12.2.1 scale_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel +format conversion on CUDA video frames. Setting the output width and height +works in the same way as for the scale filter. +

+

The following additional options are accepted: +

+
format
+

The pixel format of the output CUDA frames. If set to the string "same" (the +default), the input format will be kept. Note that automatic format negotiation +and conversion is not yet supported for hardware frames +

+
+
interp_algo
+

The interpolation algorithm used for resizing. One of the following: +

+
nn
+

Nearest neighbour. +

+
+
linear
+
cubic
+
cubic2p_bspline
+

2-parameter cubic (B=1, C=0) +

+
+
cubic2p_catmullrom
+

2-parameter cubic (B=0, C=1/2) +

+
+
cubic2p_b05c03
+

2-parameter cubic (B=1/2, C=3/10) +

+
+
super
+

Supersampling +

+
+
lanczos
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+ + +

12.2.2 scale2ref_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to scale (resize) the input +video, based on a reference video. +

+

See the scale_npp filter for available options, scale2ref_npp supports the same +but uses the reference video instead of the main input as basis. scale2ref_npp +also supports the following additional constants for the w and +h options: +

+
+
main_w
+
main_h
+

The main input video’s width and height +

+
+
main_a
+

The same as main_w / main_h +

+
+
main_sar
+

The main input video’s sample aspect ratio +

+
+
main_dar, mdar
+

The main input video’s display aspect ratio. Calculated from +(main_w / main_h) * main_sar. +

+
+
main_n
+

The (sequential) number of the main input frame, starting from 0. +Only available with eval=frame. +

+
+
main_t
+

The presentation timestamp of the main input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
main_pos
+

The position (byte offset) of the frame in the main input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +

+
+ + +

12.2.2.1 Examples

+ +
    +
  • Scale a subtitle stream (b) to match the main video (a) in size before overlaying +
    +
    'scale2ref_npp[b][a];[a][b]overlay_cuda'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio. +
    +
    [logo-in][video-in]scale2ref_npp=w=oh*mdar:h=ih/10[logo-out][video-out]
    +
    +
+ + +

12.2.3 sharpen_npp

+

Use the NVIDIA Performance Primitives (libnpp) to perform image sharpening with +border control. +

+

The following additional options are accepted: +

+
border_type
+

Type of sampling to be used ad frame borders. One of the following: +

+
replicate
+

Replicate pixel values. +

+
+
+
+
+ + +

12.2.4 transpose_npp

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

13 OpenCL Video Filters

+ +

Below is a description of the currently available OpenCL video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-opencl. +

+

Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device opencl[=name][:device[,key=value...]]
+

Initialise a new hardware device of type opencl called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it. +
    +
    -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
    +
    +
+ +

Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded(hwdownload) back to normal memory. Note that hwupload will upload to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it may be necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

13.1 avgblur_opencl

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 1024] and default value is 1. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 1024] and default value is 0. If zero, sizeX value will be used. +

+
+ + +

13.1.1 Example

+ +
    +
  • Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +
    +
    -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
    +
    +
+ + +

13.2 boxblur_opencl

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

13.2.1 Examples

+ +

Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses luma_radius, chroma_radius, alpha_radius for each plane respectively. The filter will apply luma_power, chroma_power, alpha_power times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +

+
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radius +set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image. +
    +
    -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
    +-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
    +
    + +
  • Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7. + +

    For the luma plane, a 2x2 box radius will be run once. +

    +

    For the chroma plane, a 4x4 box radius will be run 5 times. +

    +

    For the alpha plane, a 3x3 box radius will be run 7 times. +

    +
    -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
    +
    +
+ + +

13.3 colorkey_opencl

+

RGB colorspace color keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

13.3.1 Examples

+ +
    +
  • Make every semi-green pixel in the input transparent with some slight blending: +
    +
    -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
    +
    +
+ + +

13.4 convolution_opencl

+ +

Apply convolution of 3x3, 5x5, 7x7 matrix. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed numbers. +Default value for each plane is 0 0 0 0 1 0 0 0 0. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be sum of all matrix elements. +The option value must be a float number greater or equal to 0.0. Default value is 1.0. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. +The option value must be a float number greater or equal to 0.0. Default value is 0.0. +

+
+
+ + +

13.4.1 Examples

+ +
    +
  • Apply sharpen: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0, hwdownload" OUTPUT
    +
    + +
  • Apply blur: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9, hwdownload" OUTPUT
    +
    + +
  • Apply edge enhance: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply edge detect: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT
    +
    + +
  • Apply emboss: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2, hwdownload" OUTPUT
    +
    +
+ + +

13.5 erosion_opencl

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

13.5.1 Example

+ +
    +
  • Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

13.6 deshake_opencl

+

Feature-point based video stabilization filter. +

+

The filter accepts the following options: +

+
+
tripod
+

Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to 0. +

+
+
debug
+

Whether or not additional debug info should be displayed, both in the processed output and in the console. +

+

Note that in order to see console debug output you will also need to pass -v verbose to ffmpeg. +

+

Viewing point matches in the output video is only supported for RGB input. +

+

Defaults to 0. +

+
+
adaptive_crop
+

Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels. +

+

Defaults to 1. +

+
+
refine_features
+

Whether or not feature points should be refined at a sub-pixel level. +

+

This can be turned off for a slight performance gain at the cost of precision. +

+

Defaults to 1. +

+
+
smooth_strength
+

The strength of the smoothing applied to the camera path from 0.0 to 1.0. +

+

1.0 is the maximum smoothing strength while values less than that result in less smoothing. +

+

0.0 causes the filter to adaptively choose a smoothing strength on a per-frame basis. +

+

Defaults to 0.0. +

+
+
smooth_window_multiplier
+

Controls the size of the smoothing window (the number of frames buffered to determine motion information from). +

+

The size of the smoothing window is determined by multiplying the framerate of the video by this number. +

+

Acceptable values range from 0.1 to 10.0. +

+

Larger values increase the amount of motion data available for determining how to smooth the camera path, +potentially improving smoothness, but also increase latency and memory usage. +

+

Defaults to 2.0. +

+
+
+ + +

13.6.1 Examples

+ +
    +
  • Stabilize a video with a fixed, medium smoothing strength: +
    +
    -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
    +
    + +
  • Stabilize a video with debugging (both in console and in rendered video): +
    +
    -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
    +
    +
+ + +

13.7 dilation_opencl

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

13.7.1 Example

+ +
    +
  • Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

13.8 nlmeans_opencl

+ +

Non-local Means denoise filter through OpenCL, this filter accepts same options as nlmeans. +

+ +

13.9 overlay_opencl

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires same memory layout for all the inputs. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

13.9.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    +
  • The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    + +
+ + +

13.10 pad_opencl

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

13.11 prewitt_opencl

+ +

Apply the Prewitt operator (https://en.wikipedia.org/wiki/Prewitt_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

13.11.1 Example

+ +
    +
  • Apply the Prewitt operator with scale set to 2 and delta set to 10. +
    +
    -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

13.12 program_opencl

+ +

Filter video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
inputs
+

Number of inputs to the filter. Defaults to 1. +

+
+
size, s
+

Size of output frames. Defaults to the same as the first input. +

+
+
+ +

The program_opencl filter also supports the framesync options. +

+

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

  • Frame index, unsigned int. + +

    This is a counter starting from zero and increasing by one for each frame. +

  • Source images, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

+ +

Example programs: +

+
    +
  • Copy the input to the output (output must be the same size as the input). +
    __kernel void copy(__write_only image2d_t destination,
    +                   unsigned int index,
    +                   __read_only  image2d_t source)
    +{
    +    const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
    +
    +    int2 location = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = read_imagef(source, sampler, location);
    +
    +    write_imagef(destination, location, value);
    +}
    +
    +
  • Apply a simple transformation, rotating the input by an amount increasing +with the index counter. Pixel values are linearly interpolated by the +sampler, and the output need not have the same dimensions as the input. +
    __kernel void rotate_image(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float angle = (float)index / 100.0f;
    +
    +    float2 dst_dim = convert_float2(get_image_dim(dst));
    +    float2 src_dim = convert_float2(get_image_dim(src));
    +
    +    float2 dst_cen = dst_dim / 2.0f;
    +    float2 src_cen = src_dim / 2.0f;
    +
    +    int2   dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float2 dst_pos = convert_float2(dst_loc) - dst_cen;
    +    float2 src_pos = {
    +        cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
    +        sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
    +    };
    +    src_pos = src_pos * src_dim / dst_dim;
    +
    +    float2 src_loc = src_pos + src_cen;
    +
    +    if (src_loc.x < 0.0f      || src_loc.y < 0.0f ||
    +        src_loc.x > src_dim.x || src_loc.y > src_dim.y)
    +        write_imagef(dst, dst_loc, 0.5f);
    +    else
    +        write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
    +}
    +
    +
  • Blend two inputs together, with the amount of each input used varying +with the index counter. +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
    +
    +    int2  dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +    int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
    +    int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
    +
    +    float4 val1 = read_imagef(src1, sampler, src1_loc);
    +    float4 val2 = read_imagef(src2, sampler, src2_loc);
    +
    +    write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
    +}
    +
    +
+ + +

13.13 remap_opencl

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 32bit float pixel format, single channel. +

+
+
interp
+

Specify interpolation used for remapping of pixels. +Allowed values are near and linear. +Default value is linear. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

13.14 roberts_opencl

+

Apply the Roberts cross operator (https://en.wikipedia.org/wiki/Roberts_cross) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

13.14.1 Example

+ +
    +
  • Apply the Roberts cross operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

13.15 sobel_opencl

+ +

Apply the Sobel operator (https://en.wikipedia.org/wiki/Sobel_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

13.15.1 Example

+ +
    +
  • Apply sobel operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

13.16 tonemap_opencl

+ +

Perform HDR(PQ/HLG) to SDR conversion with tone-mapping. +

+

It accepts the following parameters: +

+
+
tonemap
+

Specify the tone-mapping operator to be used. Same as tonemap option in tonemap. +

+
+
param
+

Tune the tone mapping algorithm. same as param option in tonemap. +

+
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default value is 0.5, and the algorithm here is a little different from +the cpu version tonemap currently. A setting of 0.0 disables this option. +

+
+
threshold
+

The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold +is used to detect whether the scene has changed or not. If the distance between +the current frame average brightness and the current running average exceeds +a threshold value, we would re-calculate scene average and peak brightness. +The default value is 0.2. +

+
+
format
+

Specify the output pixel format. +

+

Currently supported formats are: +

+
p010
+
nv12
+
+ +
+
range, r
+

Set the output color range. +

+

Possible values are: +

+
tv/mpeg
+
pc/jpeg
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the output color primaries. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is bt709. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Possible value are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
+ + +

13.16.1 Example

+ +
    +
  • Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator. +
    +
    -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
    +
    +
+ + +

13.17 unsharp_opencl

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. +Range is [-10, 10] and default value is 1.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. +Range is [-10, 10] and default value is 0.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

13.17.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
    +
    +
+ + +

13.18 xfade_opencl

+ +

Cross fade two videos with custom transition effect by using OpenCL. +

+

It accepts the following options: +

+
+
transition
+

Set one of possible transition effects. +

+
+
custom
+

Select custom transition effect, the actual transition description +will be picked from source and kernel options. +

+
+
fade
+
wipeleft
+
wiperight
+
wipeup
+
wipedown
+
slideleft
+
slideright
+
slideup
+
slidedown
+
+

Default transition is fade. +

+
+ +
+
source
+

OpenCL program source file for custom transition. +

+
+
kernel
+

Set name of kernel to use for custom transition from program source file. +

+
+
duration
+

Set duration of video transition. +

+
+
offset
+

Set time of start of transition relative to first video. +

+
+ +

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

    +
  • First Source image, __read_only image2d_t. +Second Source image, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

    +
  • Transition progress, float. This value is always between 0 and 1 inclusive. +
+ +

Example programs: +

+
    +
  • Apply dots curtain transition effect: +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2,
    +                           float progress)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +    int2  p = (int2)(get_global_id(0), get_global_id(1));
    +    float2 rp = (float2)(get_global_id(0), get_global_id(1));
    +    float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
    +    rp = rp / dim;
    +
    +    float2 dots = (float2)(20.0, 20.0);
    +    float2 center = (float2)(0,0);
    +    float2 unused;
    +
    +    float4 val1 = read_imagef(src1, sampler, p);
    +    float4 val2 = read_imagef(src2, sampler, p);
    +    bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
    +
    +    write_imagef(dst, p, next ? val1 : val2);
    +}
    +
    +
+ + + +

14 VAAPI Video Filters

+ +

VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vaapi. +

+

To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/VAAPI +

+ +

14.1 overlay_vaapi

+ +

Overlay one video on the top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +

+

The filter accepts the following options: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

Default value is "0" for both expressions. +

+
+
w
+
h
+

Set expressions for the width and height the overlaid video +on the main video. +

+

Default values are ’overlay_iw’ for ’w’ and ’overlay_ih*w/overlay_iw’ for ’h’. +

+

The expressions can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_iw
+
overlay_ih
+

The overlay input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay output width and height. +

+
+
overlay_x, x
+
overlay_y, y
+

Position of the overlay layer inside of main +

+
+
+ +
+
alpha
+

Set transparency of overlaid video. Allowed range is 0.0 to 1.0. +Higher value means lower transparency. +Default value is 1.0. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+

14.1.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs for this filter are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_vaapi" OUTPUT
    +
    +
  • Overlay an image LOGO at the offset (200, 100) from the top-left corner of the INPUT video. +The inputs have same memory layout for color channels, the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_vaapi=x=200:y=100:w=400:h=300:alpha=1.0, hwdownload, format=nv12" OUTPUT
    +
    + +
+ + +

14.2 tonemap_vaapi

+ +

Perform HDR-to-SDR or HDR-to-HDR tone-mapping. +It currently only accepts HDR10 as input. +

+

It accepts the following parameters: +

+
+
format
+

Specify the output pixel format. +

+

Default is nv12 for HDR-to-SDR tone-mapping and p010 for HDR-to-HDR +tone-mapping. +

+
+
primaries, p
+

Set the output color primaries. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
display
+

Set the output mastering display colour volume. It is given by a ’|’-separated +list of two values, two values are space separated. It set display primaries +x & y in G, B, R order, then white point x & y, the nominal minimum & maximum +display luminances. +

+

HDR-to-HDR tone-mapping will be performed when this option is set. +

+
+
light
+

Set the output content light level information. It accepts 2 space-separated +values, the first input is the maximum light level and the second input is +the maximum average light level. +

+

It is ignored for HDR-to-SDR tone-mapping, and optional for HDR-to-HDR +tone-mapping. +

+
+
+ + +

14.2.1 Example

+ +
    +
  • Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format +
    +
    tonemap_vaapi=format=p010:t=bt2020-10
    +
    +
  • Convert HDR video to HDR video +
    +
    tonemap_vaapi=display=7500\ 3000|34000\ 16000|13250\ 34500|15635\ 16450|500\ 10000000
    +
    +
+ + +

14.3 hstack_vaapi

+

Stack input videos horizontally. +

+

This is the VA-API variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

14.4 vstack_vaapi

+

Stack input videos vertically. +

+

This is the VA-API variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

14.5 xstack_vaapi

+

Stack video inputs into custom layout. +

+

This is the VA-API variant of the xstack filter, each input stream may +have different size, this filter will scale down/up each input stream to the +given output size, or the size of the first input stream. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_vaapi=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + +

14.6 pad_vaapi

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

14.7 drawbox_vaapi

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

Specify the color of the box to write. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

With value 1, the pixels of the painted box will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input video. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
t
+

The thickness of the drawn box. +

+
+
+ + +

14.7.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + + +

15 VideoToolbox Video Filters

+ +

Below is a description of the currently available VideoToolbox video filters. +

+

VideoToolbox filter depends on VideoToolbox framework, and is auto detected +when building ffmpeg for an Apple platform such as macOS. Add +--enable-videotoolbox to configure if autodetect is disabled. +

+ +

15.1 scale_vt

+ +

Scale and convert the color parameters using VTPixelTransferSession. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+
+
color_matrix
+

Set the output colorspace matrix. +

+
+
color_primaries
+

Set the output color primaries. +

+
+
color_transfer
+

Set the output transfer characteristics. +

+
+
+ + +

15.1.1 Examples

+ +
    +
  • Perform HDR to SDR conversion, and scale to half size of input +
    +
    ffmpeg -hwaccel videotoolbox \
    +        -hwaccel_output_format videotoolbox_vld \
    +        -i hdr.mov \
    +        -c:v hevc_videotoolbox \
    +        -profile:v main \
    +        -b:v 3M \
    +        -vf scale_vt=w=iw/2:h=ih/2:color_matrix=bt709:color_primaries=bt709:color_transfer=bt709 \
    +        -c:a copy \
    +        -tag:v hvc1 \
    +        sdr.mp4
    +
    + +
+ + +

15.2 transpose_vt

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+
‘hflip’
+

Flip the input video horizontally. +

+
+
‘vflip’
+

Flip the input video vertically. +

+
+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

16 Vulkan Video Filters

+ +

Below is a description of the currently available Vulkan video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vulkan and either --enable-libglslang or --enable-libshaderc. +

+

Running Vulkan filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device vulkan[=name][:device[,key=value...]]
+

Initialise a new hardware device of type vulkan called name, using the +given device parameters and options in key=value. The following options +are supported: +

+
+
debug
+

Switches validation layers on if set to 1. +

+
+
linear_images
+

Allocates linear images. Does not apply to decoding. +

+
+
disable_multiplane
+

Disables multiplane images. Does not apply to decoding. +

+
+
avoid_host_import
+

Avoids the use of dynamic host memory imports, in favor of a regular memcpy() +into a previously mapped buffer. +

+
+ +
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device and running nlmeans_vulkan filter with default parameters on it. +
    +
    -init_hw_device vulkan=vk:0 -filter_hw_device vk -i INPUT -vf "hwupload,nlmeans_vulkan,hwdownload" OUTPUT
    +
    +
+ +

As Vulkan filters are not able to access frame data in normal memory, all frame data needs to be uploaded (hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded (hwdownload) back to normal memory. Note that hwupload will upload to a frame with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it is usually necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

16.1 avgblur_vulkan

+ +

Apply an average blur filter, implemented on the GPU using Vulkan. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 32] and default value is 3. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 32] and default value is 3. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+ + +

16.2 blend_vulkan

+ +

Blend two Vulkan frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘normal’
+
‘multiply’
+
+ +
+
+ + +

16.3 bwdif_vulkan

+ +

Deinterlacer using bwdif, the "Bob Weaver Deinterlacing Filter" algorithm, implemented +on the GPU using Vulkan. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

16.4 chromaber_vulkan

+ +

Apply an effect that emulates chromatic aberration. Works best with RGB inputs, +but provides a similar effect with YCbCr inputs too. +

+
+
dist_x
+

Horizontal displacement multiplier. Each chroma pixel’s position will be multiplied +by this amount, starting from the center of the image. Default is 0. +

+
+
dist_y
+

Similarly, this sets the vertical displacement multiplier. Default is 0. +

+
+
+ + +

16.5 color_vulkan

+ +

Video source that creates a Vulkan frame of a solid color. +Useful for benchmarking, or overlaying. +

+

It accepts the following parameters: +

+
+
color
+

The color to use. Either a name, or a hexadecimal value. +The default value is black. +

+
+
size
+

The size of the output frame. Default value is 1920x1080. +

+
+
rate
+

The framerate to output at. Default value is 60 frames per second. +

+
+
duration
+

The video duration. Default value is -0.000001. +

+
+
sar
+

The video signal aspect ratio. Default value is 1/1. +

+
+
format
+

The pixel format of the output Vulkan frames. Default value is yuv444p. +

+
+
out_range
+

Set the 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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
+ + +

16.6 vflip_vulkan

+ +

Flips an image vertically. +

+ +

16.7 hflip_vulkan

+ +

Flips an image horizontally. +

+ +

16.8 flip_vulkan

+ +

Flips an image along both the vertical and horizontal axis. +

+ +

16.9 gblur_vulkan

+ +

Apply Gaussian blur filter on Vulkan frames. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
size
+

Set the kernel size along the horizontal axis. Default is 19. +

+
+
sizeV
+

Set the kernel size along the vertical axis. Default is 0, +which sets to use the same value as size. +

+
+
+ + +

16.10 nlmeans_vulkan

+ +

Denoise frames using Non-Local Means algorithm, implemented on the GPU using +Vulkan. +Supports more pixel formats than nlmeans or nlmeans_opencl, including +alpha channel support. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength for all components. Default is 1.0. Must be in range [0.0, 100.0]. +

+
+
p
+

Set patch size for all planes. Default is 7. Must be odd number in range [0, 99]. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
t
+

Set parallelism. Default is 8. Must be a number in the range [1, 64]. +Larger values will use more VRAM but may not result in greater speed. +The optimal value is hardware and input dependent. +

+
+
s0
+
s1
+
s2
+
s3
+

Set denoising strength for a specific component. Default is 1.0, equal to s. +Must be in range [0.0, 100.0]. 0.0 disables denoising in that component. +

+
+
p0
+
p1
+
p2
+
p3
+

Set patch size for a specific component. Default is 7, equal to p. +Must be odd number in range [0, 99]. +

+
+
+ + +

16.11 overlay_vulkan

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires all inputs to use the same pixel format. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

16.12 transpose_vulkan

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

17 QSV Video Filters

+ +

Below is a description of the currently available QSV video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-libmfx or --enable-libvpl. +

+

To use QSV filters, you need to setup the QSV device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/QuickSync +

+ +

17.1 hstack_qsv

+

Stack input videos horizontally. +

+

This is the QSV variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

17.2 vstack_qsv

+

Stack input videos vertically. +

+

This is the QSV variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

17.3 xstack_qsv

+

Stack video inputs into custom layout. +

+

This is the QSV variant of the xstack filter. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_qsv=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + + +

18 Video Sources

+ +

Below is a description of the currently available video sources. +

+ +

18.1 buffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
+
video_size
+

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. +

+
+
width
+

The input video width. +

+
+
height
+

The input video height. +

+
+
pix_fmt
+

A string representing the pixel format of the buffered video frames. +It may be a number corresponding to a pixel format, or a pixel format +name. +

+
+
time_base
+

Specify the timebase assumed by the timestamps of the buffered frames. +

+
+
frame_rate
+

Specify the frame rate expected for the video stream. +

+
+
colorspace
+

A string representing the color space of the buffered video frames. +It may be a number corresponding to a color space, or a color space +name. +

+
+
range
+

A string representing the color range of the buffered video frames. +It may be a number corresponding to a color range, or a color range +name. +

+
+
alpha_mode
+

A string representing the alpha mode of the buffered video frames. +It may be a number corresponding to an alpha mode, or an alpha mode +name. +

+
+
pixel_aspect, sar
+

The sample (pixel) aspect ratio of the input video. +

+
+
hw_frames_ctx
+

When using a hardware pixel format, this should be a reference to an +AVHWFramesContext describing input frames. +

+
+ +

For example: +

+
buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
+
+ +

will instruct the source to accept video frames with size 320x240 and +with format "yuv410p", assuming 1/24 as the timestamps timebase and +square pixels (1:1 sample aspect ratio). +Since the pixel format with name "yuv410p" corresponds to the number 6 +(check the enum AVPixelFormat definition in libavutil/pixfmt.h), +this example corresponds to: +

+
buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
+
+ +

Alternatively, the options can be specified as a flat string, but this +syntax is deprecated: +

+

width:height:pix_fmt:time_base.num:time_base.den:pixel_aspect.num:pixel_aspect.den +

+ +

18.2 cellauto

+ +

Create a pattern generated by an elementary cellular automaton. +

+

The initial state of the cellular automaton can be defined through the +filename and pattern options. If such options are +not specified an initial state is created randomly. +

+

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 scroll option. +

+

This source accepts the following options: +

+
+
filename, f
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified file. +In the file, each non-whitespace character is considered an alive +cell, a newline will terminate the row, and further characters in the +file will be ignored. +

+
+
pattern, p
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified string. +

+

Each non-whitespace character in the string is considered an alive +cell, a newline will terminate the row, and further characters in the +string will be ignored. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial cellular automaton row. It +is a floating point number value ranging from 0 to 1, defaults to +1/PHI. +

+

This option is ignored when a file or a pattern is specified. +

+
+
random_seed, seed
+

Set the seed for filling randomly the initial row, 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. +

+
+
rule
+

Set the cellular automaton rule, it is a number ranging from 0 to 255. +Default value is 110. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename or pattern is specified, the size is set +by default to the width of the specified initial state row, and the +height is set to width * PHI. +

+

If size is set, it must contain the width of the specified +pattern string, and the specified pattern will be centered in the +larger row. +

+

If a filename or a pattern string is not specified, the size value +defaults to "320x518" (used for a randomly generated initial state). +

+
+
scroll
+

If set to 1, scroll the output upward when all the rows in the output +have been already filled. If set to 0, the new generated row will be +written over the top row just after the bottom row is filled. +Defaults to 1. +

+
+
start_full, full
+

If set to 1, completely fill the output with generated rows before +outputting the first frame. +This is the default behavior, for disabling set the value to 0. +

+
+
stitch
+

If set to 1, stitch the left and right row edges together. +This is the default behavior, for disabling set the value to 0. +

+
+ + +

18.2.1 Examples

+ +
    +
  • Read the initial state from pattern, and specify an output of +size 200x400. +
    +
    cellauto=f=pattern:s=200x400
    +
    + +
  • Generate a random initial row with a width of 200 cells, with a fill +ratio of 2/3: +
    +
    cellauto=ratio=2/3:s=200x200
    +
    + +
  • Create a pattern generated by rule 18 starting by a single alive cell +centered on an initial row with width 100: +
    +
    cellauto=p=@:s=100x400:full=0:rule=18
    +
    + +
  • Specify a more elaborated initial pattern: +
    +
    cellauto=p='@@ @ @@':s=100x400:full=0:rule=18
    +
    + +
+ + +

18.3 coreimagesrc

+

Video source generated on GPU using Apple’s CoreImage API on OSX. +

+

This video source is a specialized version of the coreimage video filter. +Use a core image generator at the beginning of the applied filterchain to +generate the content. +

+

The coreimagesrc video source accepts the following options: +

+
list_generators
+

List all available generators along with all their respective options as well as +possible minimum and maximum values along with the default values. +

+
list_generators=true
+
+ +
+
size, s
+

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. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+ +

Additionally, all options of the coreimage video filter are accepted. +A complete filterchain can be used for further processing of the +generated input without CPU-HOST transfer. See coreimage documentation +and examples for details. +

+ +

18.3.1 Examples

+ +
    +
  • Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +

    This example is equivalent to the QRCode example of coreimage without the +need for a nullsrc video source. +

+ + + +

18.4 ddagrab

+ +

Captures the Windows Desktop via Desktop Duplication API. +

+

The filter exclusively returns D3D11 Hardware Frames, for on-gpu encoding +or processing. So an explicit hwdownload is needed for any kind of +software processing. +

+

It accepts the following options: +

+
+
output_idx
+

DXGI Output Index to capture. +

+

Usually corresponds to the index Windows has given the screen minus one, +so it’s starting at 0. +

+

Defaults to output 0. +

+
+
draw_mouse
+

Whether to draw the mouse cursor. +

+

Defaults to true. +

+

Only affects hardware cursors. If a game or application renders its own cursor, +it’ll always be captured. +

+
+
framerate
+

Maximum framerate at which the desktop will be captured - the interval between +successive frames will not be smaller than the inverse of the framerate. When +dup_frames is true (the default) and the desktop is not being updated +often enough, the filter will duplicate a previous frame. Note that there is no +background buffering going on, so when the filter is not polled often enough +then the actual inter-frame interval may be significantly larger. +

+

Defaults to 30 FPS. +

+
+
video_size
+

Specify the size of the captured video. +

+

Defaults to the full size of the screen. +

+

Cropped from the bottom/right if smaller than screen size. +

+
+
offset_x
+

Horizontal offset of the captured video. +

+
+
offset_y
+

Vertical offset of the captured video. +

+
+
output_fmt
+

Desired filter output format. +Defaults to 8 Bit BGRA. +

+

It accepts the following values: +

+
‘auto’
+

Passes all supported output formats to DDA and returns what DDA decides to use. +

+
‘8bit’
+
‘bgra’
+

8 Bit formats always work, and DDA will convert to them if necessary. +

+
‘10bit’
+
‘x2bgr10’
+

Filter initialization will fail if 10 bit format is requested but unavailable. +

+
+ +
+
dup_frames
+

When this option is set to true (the default), the filter will duplicate frames +when the desktop has not been updated in order to maintain approximately +constant target framerate. When this option is set to false, the filter will +wait for the desktop to be updated (inter-frame intervals may vary significantly +in this case). +

+
+
+ + +

18.4.1 Examples

+ +

Capture primary screen and encode using nvenc: +

+
ffmpeg -f lavfi -i ddagrab -c:v h264_nvenc -cq 18 output.mp4
+
+ +

You can also skip the lavfi device and directly use the filter. +Also demonstrates downloading the frame and encoding with libx264. +Explicit output format specification is required in this case: +

+
ffmpeg -filter_complex ddagrab=output_idx=1:framerate=60,hwdownload,format=bgra -c:v libx264 -crf 18 output.mp4
+
+ +

If you want to capture only a subsection of the desktop, this can be achieved +by specifying a smaller size and its offsets into the screen: +

+
ddagrab=video_size=800x600:offset_x=100:offset_y=100
+
+ + + +

18.5 gfxcapture

+ +

Capture windows or monitors using Windows.Graphics.Capture API. +

+

This source provides low overhead capture of application windows or entire monitors. +The filter outputs hardware frames in d3d11 format; use hwdownload,format= +if system memory frames are required. +

+

The window to be captured can be selected via regular expressions on its title, +class name or backing executable name, by explicit native handles, or by monitor +index or explicit native handle. A window must match all provided expressions to be +selected. The first matching window will be picked, in whatever order Windows +returns them. +

+

Explicit handles (hwnd, hmonitor) override pattern or index +based selection. If neither handles nor a monitor index are given, the first +window matching the provided regular expressions is captured. +

+

This source does NOT hold a stable FPS. It returns frames at whatever rate the compositor +provides them, only capped by the max_framerate. +If you need a stable rate, you need to add an fps filter to drop/duplicate frames as needed. +

+

If the capture source disappears mid-capture (window closed, monitor disconnected), the filter will return EOF. +

+

This source accepts the following options: +

+
window_title
+

ECMAScript regular expression matched against the window title. Supports a +PCRE style (?i) prefix for case-insensitive matching. +

+
+
window_class
+

As window_title, but matched against the window class name. +

+
+
window_exe
+

As window_title, but matched against the executable file name of the +window’s process. +

+
+
monitor_idx
+

Zero-based index of the monitor to capture. +

+

Can also be set to window to capture the monitor the selected window +is displayed on at filter initialization time. +

+
+
hwnd
+

Explicit native window handle (HWND). +

+
+
hmonitor
+

Explicit native monitor handle (HMONITOR). +

+
+
capture_cursor
+

Capture the mouse cursor. Enabled by default. +

+
+
capture_border
+

Capture the full area of the window, including its window decorarions/border. +Disabled by default. +

+
+
display_border
+

Draw a yellow highlight border around the captured window. Disabled by default. +

+
+
max_framerate
+

Maximum capture frame rate. Accepts a video rate (e.g. 30, 60/1, +24000/1001). The default is 60 FPS. +The actual rate is the rate at which the compositor renders the window/monitor, +capped by this option. +

+
+
width
+

Force the output canvas width. If zero (default) the initial captured source +width is used. If a negative number is provided, the width will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
height
+

Force the output canvas height. If zero (default) the initial captured source +height is used. If a negative number is provided, the height will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
crop_left
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_top
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_right
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_bottom
+

Crop this many pixels from the left side of the captured frames. +

+
+
premultiplied
+

If set to 1, return frames with premultiplied alpha. Default is 0 (straight +alpha). +

+
+
resize_mode
+

Defines how the captured content is fitted into the output canvas size. +Possible values: +

+
‘crop’
+

Crop (or pad with black) to the canvas size. (default) +

+
‘scale’
+

Scale the source to fill the canvas, potentially altering aspect ratio. +

+
‘scale_aspect’
+

Scale the source to fit inside the canvas while preserving aspect ratio. +Remaining area is filled with black. +

+
+ +
+
scale_mode
+

Scaling algorithm used when resizing is required. +

+

Possible values: +

+
‘point’
+

Nearest neighbour (pixelated) scaling. +

+
‘bilinear’
+

Bilinear filtering. (default) +

+
‘bicubic’
+

Bicubic filtering. Potentially more blurry, but fewer scaling artifacts depending on contents. +

+
+ +
+
output_fmt
+

Desired output pixel format inside the D3D11 hardware frames. +

+

Possible values: +

+
‘bgra’
+
‘8bit’
+

8 bit BGRA output (default) +

+
‘x2bgr10’
+
‘10bit’
+

10 bit BGR output +

+
‘rgbaf16’
+
‘16bit’
+

16bit float RGBA output +

+
+ +
+
+ + +

18.5.1 Examples

+
    +
  • Capture a window by title (case-insensitive) at a maximum of 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_title='(?i)My Application':max_framerate=60,hwdownload,format=bgra,format=yuv420p -c:v libx264 -crf 15 capture.mp4
    +
    + +
  • Capture monitor 1 at native refresh, 10bit color depth, scale to 1920x1080 preserving aspect: +
    +
    ffmpeg -filter_complex gfxcapture=monitor_idx=1:width=1920:height=1080:resize_mode=scale_aspect:output_fmt=10bit -c:v hevc_nvenc -cq 15 capture.mp4
    +
    + +
  • Capture a window by executable name, draw border, force point scaling, fixed 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_exe='^firefox.exe$':display_border=1:scale_mode=point,fps=60 -rc qvbr -qvbr_quality_level 15 -c:v h264_amf capture.mp4
    +
    + +
+ + + +

18.6 gradients

+

Generate several gradients. +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
c0, c1, c2, c3, c4, c5, c6, c7
+

Set 8 colors. Default values for colors is to pick random one. +

+
+
x0, y0, y0, y1
+

Set gradient line source and destination points. If negative or out of range, random ones +are picked. +

+
+
nb_colors, n
+

Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2. +

+
+
seed
+

Set seed for picking gradient line points. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
speed
+

Set speed of gradients rotation. +

+
+
type, t
+

Set type of gradients. +Available values are: +

+
‘linear’
+
‘radial’
+
‘circular’
+
‘spiral’
+
‘square’
+
+ +

Default type is linear. +

+
+ + +

18.6.1 Commands

+ +

This source supports the some above options as commands. +

+ +

18.7 mandelbrot

+ +

Generate a Mandelbrot set fractal, and progressively zoom towards the +point specified with start_x and start_y. +

+

This source accepts the following options: +

+
+
end_pts
+

Set the terminal pts value. Default value is 400. +

+
+
end_scale
+

Set the terminal scale value. +Must be a floating point value. Default value is 0.3. +

+
+
inner
+

Set the inner coloring mode, that is the algorithm used to draw the +Mandelbrot fractal internal region. +

+

It shall assume one of the following values: +

+
black
+

Set black mode. +

+
convergence
+

Show time until convergence. +

+
mincol
+

Set color based on point closest to the origin of the iterations. +

+
period
+

Set period mode. +

+
+ +

Default value is mincol. +

+
+
bailout
+

Set the bailout value. Default value is 10.0. +

+
+
maxiter
+

Set the maximum of iterations performed by the rendering +algorithm. Default value is 7189. +

+
+
outer
+

Set outer coloring mode. +It shall assume one of following values: +

+
iteration_count
+

Set iteration count mode. +

+
normalized_iteration_count
+

set normalized iteration count mode. +

+
+

Default value is normalized_iteration_count. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
start_scale
+

Set the initial scale value. Default value is 3.0. +

+
+
start_x
+

Set the initial x position. Must be a floating point value between +-100 and 100. Default value is -0.743643887037158704752191506114774. +

+
+
start_y
+

Set the initial y position. Must be a floating point value between +-100 and 100. Default value is -0.131825904205311970493132056385139. +

+
+ + +

18.8 mptestsrc

+ +

Generate various test patterns, as generated by the MPlayer test filter. +

+

The size of the generated video is fixed, and is 512x512. +This source is useful in particular for testing encoding features. +

+

This source accepts the following options: +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
test, t
+
+

Set the number or the name of the test to perform. Supported tests are: +

+
dc_luma
+
dc_chroma
+
freq_luma
+
freq_chroma
+
amp_luma
+
amp_chroma
+
cbp
+
mv
+
ring1
+
ring2
+
all
+
max_frames, m
+

Set the maximum number of frames generated for each test, default value is 30. +

+
+
+ +

Default value is "all", which will cycle through the list of all tests. +

+
+ +

Some examples: +

+
mptestsrc=t=dc_luma
+
+ +

will generate a "dc_luma" test pattern. +

+ +

18.9 frei0r_src

+ +

Provide a frei0r source. +

+

To enable compilation of this filter you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

This source accepts the following parameters: +

+
+
size
+

The size of the video to generate. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
framerate
+

The framerate of the generated video. It may be a string of the form +num/den or a frame rate abbreviation. +

+
+
filter_name
+

The name to the frei0r source to load. For more information regarding frei0r and +how to set the parameters, read the frei0r section in the video filters +documentation. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r source. +

+
+
+ +

For example, to generate a frei0r partik0l source with size 200x200 +and frame rate 10 which is overlaid on the overlay filter main input: +

+
frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
+
+ + +

18.10 life

+ +

Generate a life pattern. +

+

This source is based on a generalization of John Conway’s life game. +

+

The sourced input represents a life grid, each pixel represents a cell +which can be in one of two possible states, alive or dead. Every cell +interacts with its eight neighbours, which are the cells that are +horizontally, vertically, or diagonally adjacent. +

+

At each interaction the grid evolves according to the adopted rule, +which specifies the number of neighbor alive cells which will make a +cell stay alive or born. The rule option allows one to specify +the rule to adopt. +

+

This source accepts the following options: +

+
+
filename, f
+

Set the file from which to read the initial grid state. In the file, +each non-whitespace character is considered an alive cell, and newline +is used to delimit the end of each row. +

+

If this option is not specified, the initial grid is generated +randomly. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial random grid. It is a +floating point number value ranging from 0 to 1, defaults to 1/PHI. +It is ignored when a file is specified. +

+
+
random_seed, seed
+

Set the seed for filling the initial random grid, 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. +

+
+
rule
+

Set the life rule. +

+

A rule can be specified with a code of the kind "SNS/BNB", +where NS and NB are sequences of numbers in the range 0-8, +NS specifies the number of alive neighbor cells which make a +live cell stay alive, and NB the number of alive neighbor cells +which make a dead cell to become alive (i.e. to "born"). +"s" and "b" can be used in place of "S" and "B", respectively. +

+

Alternatively a rule can be specified by an 18-bits integer. The 9 +high order bits are used to encode the next cell state if it is alive +for each number of neighbor alive cells, the low order bits specify +the rule for "borning" new cells. Higher order bits encode for an +higher number of neighbor cells. +For example the number 6153 = (12<<9)+9 specifies a stay alive +rule of 12 and a born rule of 9, which corresponds to "S23/B03". +

+

Default value is "S23/B3", which is the original Conway’s game of life +rule, and will keep a cell alive if it has 2 or 3 neighbor alive +cells, and will born a new cell if there are three alive cells around +a dead cell. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename is specified, the size is set by default to the +same size of the input file. If size is set, it must contain +the size specified in the input file, and the initial grid defined in +that file is centered in the larger resulting area. +

+

If a filename is not specified, the size value defaults to "320x240" +(used for a randomly generated initial grid). +

+
+
stitch
+

If set to 1, stitch the left and right grid edges together, and the +top and bottom edges also. Defaults to 1. +

+
+
mold
+

Set cell mold speed. If set, a dead cell will go from death_color to +mold_color with a step of mold. mold can have a +value from 0 to 255. +

+
+
life_color
+

Set the color of living (or new born) cells. +

+
+
death_color
+

Set the color of dead cells. If mold is set, this is the first color +used to represent a dead cell. +

+
+
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. +

+
+ + +

18.10.1 Examples

+ +
    +
  • Read a grid from pattern, and center it on a grid of size +300x300 pixels: +
    +
    life=f=pattern:s=300x300
    +
    + +
  • Generate a random grid of size 200x200, with a fill ratio of 2/3: +
    +
    life=ratio=2/3:s=200x200
    +
    + +
  • Specify a custom rule for evolving a randomly generated grid: +
    +
    life=rule=S14/B34
    +
    + +
  • Full example with slow death effect (mold) using ffplay: +
    +
    ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
    +
    +
+ + +

18.11 perlin

+

Generate Perlin noise. +

+

Perlin noise is a kind of noise with local continuity in space. This +can be used to generate patterns with continuity in space and time, +e.g. to simulate smoke, fluids, or terrain. +

+

In case more than one octave is specified through the octaves +option, Perlin noise is generated as a sum of components, each one +with doubled frequency. In this case the persistence option +specify the ratio of the amplitude with respect to the previous +component. More octave components enable to specify more high +frequency details in the generated noise (e.g. small size variations +due to boulders in a generated terrain). +

+ +

18.11.1 Options

+
+
size, s
+

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. +Default value is 320x240. +

+
+
rate, r
+

Specify the frame rate expected for the video stream, expressed as a +number of frames per second. Default value is 25. +

+
+
octaves
+

Specify the total number of components making up the noise, each one +with doubled frequency. Default value is 1. +

+
+
persistence
+

Set the ratio used to compute the amplitude of the next octave +component with respect to the previous component amplitude. Default +value is 1. +

+
+
xscale
+
yscale
+

Define a scale factor used to multiple the x, y coordinates. This can +be useful to define an effect with a pattern stretched along the x or +y axis. Default value is 1. +

+
+
tscale
+

Define a scale factor used to multiple the time coordinate. This can +be useful to change the time variation speed. Default value is 1. +

+
+
random_mode
+

Set random mode used to compute initial pattern. +

+

Supported values are: +

+
random
+

Compute and use random seed. +

+
+
ken
+

Use the predefined initial pattern defined by Ken Perlin in the +original article, can be useful to compare the output with other +sources. +

+
+
seed
+

Use the value specified by random_seed option. +

+
+ +

Default value is random. +

+
+
random_seed, seed
+

When random_mode is set to random_seed, use this value +to compute the initial pattern. Default value is 0. +

+
+ + +

18.11.2 Examples

+
    +
  • Generate single component: +
    +
    perlin
    +
    + +
  • Use Perlin noise with 7 components, each one with a halved contribution +to total amplitude: +
    +
    perlin=octaves=7:persistence=0.5
    +
    + +
  • Chain Perlin noise with the lutyuv to generate a black&white +effect: +
    +
    perlin=octaves=3:tscale=0.3,lutyuv=y='if(lt(val\,128)\,255\,0)'
    +
    + +
  • Stretch noise along the y axis, and convert gray level to red-only +signal: +
    +
    perlin=octaves=7:tscale=0.4:yscale=0.3,lutrgb=r=val:b=0:g=0
    +
    +
+ + +

18.12 qrencodesrc

+ +

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/). +

+

To enable the compilation of this source, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and put in the video output according to the +specified output size options. +

+

In case no text is specified, the QR code is not generated, but an empty colored +output is returned instead. +

+

This source accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated only once, when initializing the source. +See the qrencode Expressions section for details. +

+

Note that some of the constants are missing for the source (for example the +x or t or ¸n), since they only makes sense when evaluating the +expression for each frame rather than at initialization time. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

18.12.1 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size: +
    +
    qrencodesrc=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencodesrc=text=www.ffmpeg.org:bc=pink:fc=blue
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencodesrc=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencodesrc=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencodesrc=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencodesrc=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencodesrc=text=%{pts}
    +
    + +
+ + +

18.13 allrgb, allyuv, color, colorchart, colorspectrum, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc

+ +

The allrgb source returns frames of size 4096x4096 of all rgb colors. +

+

The allyuv source returns frames of size 4096x4096 of all yuv colors. +

+

The color source provides an uniformly colored input. +

+

The colorchart source provides a colors checker chart. +

+

The colorspectrum source provides a color spectrum input. +

+

The haldclutsrc source provides an identity Hald CLUT. See also +haldclut filter. +

+

The 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. +

+

The pal75bars source generates a color bars pattern, based on +EBU PAL recommendations with 75% color levels. +

+

The pal100bars source generates a color bars pattern, based on +EBU PAL recommendations with 100% color levels. +

+

The rgbtestsrc source generates an RGB test pattern useful for +detecting RGB vs BGR issues. You should see a red, green and blue +stripe from top to bottom. +

+

The smptebars source generates a color bars pattern, based on +the SMPTE Engineering Guideline EG 1-1990. +

+

The smptehdbars source generates a color bars pattern, based on +the SMPTE RP 219-2002. +

+

The testsrc source generates a test video pattern, showing a +color pattern, a scrolling gradient and a timestamp. This is mainly +intended for testing purposes. +

+

The testsrc2 source is similar to testsrc, but supports more +pixel formats instead of just rgb24. This allows using it as an +input for other tests without requiring a format conversion. +

+

The yuvtestsrc source generates an YUV test pattern. You should +see a y, cb and cr stripe from top to bottom. +

+

The sources accept the following parameters: +

+
+
level
+

Specify the level of the Hald CLUT, only available in the haldclutsrc +source. A level of N generates a picture of N*N*N by N*N*N +pixels to be used as identity matrix for 3D lookup tables. Each component is +coded on a 1/(N*N) scale. +

+
+
color, c
+

Specify the color of the source, only available in the color +source. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +

+
+
size, s
+

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 allrgb, allyuv, and +haldclutsrc filters. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+

Since the frame rate is used as time base, all frames including the last one +will have their full duration. If the specified duration is not a multiple +of the frame duration, it will be rounded up. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
alpha
+

Specify the alpha (opacity) of the background, only available in the +testsrc2 source. The value must be between 0 (fully transparent) and +255 (fully opaque, the default). +

+
+
decimals, n
+

Set the number of decimals to show in the timestamp, only available in the +testsrc source. +

+

The displayed timestamp value will correspond to the original +timestamp value multiplied by the power of 10 of the specified +value. Default value is 0. +

+
+
type
+

Set the type of the color spectrum, only available in the +colorspectrum source. Can be one of the following: +

+
+
‘black’
+
‘white’
+
‘all’
+
+ +
+
patch_size
+

Set patch size of single color patch, only available in the +colorchart source. Default is 64x64. +

+
+
preset
+

Set colorchecker colors preset, only available in the +colorchart source. +

+

Available values are: +

+
‘reference’
+
‘skintones’
+
+ +

Default value is reference. +

+
+ + +

18.13.1 Examples

+ +
    +
  • Generate a video with a duration of 5.3 seconds, with size +176x144 and a frame rate of 10 frames per second: +
    +
    testsrc=duration=5.3:size=qcif:rate=10
    +
    + +
  • The following graph description will generate a red source +with an opacity of 0.2, with size "qcif" and a frame rate of 10 +frames per second: +
    +
    color=c=red@0.2:s=qcif:r=10
    +
    + +
  • If the input content is to be ignored, nullsrc can be used. The +following command generates noise in the luma plane by employing +the geq filter: +
    +
    nullsrc=s=256x256, geq=random(1)*255:128:128
    +
    +
+ + +

18.13.2 Commands

+ +

The color source supports the following commands: +

+
+
c, color
+

Set the color of the created image. Accepts the same syntax of the +corresponding color option. +

+
+ + +

18.14 openclsrc

+ +

Generate video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
size, s
+

Size of frames to generate. This must be set. +

+
+
format
+

Pixel format to use for the generated frames. This must be set. +

+
+
rate, r
+

Number of frames generated every second. Default value is ’25’. +

+
+
+ +

For details of how the program loading works, see the program_opencl +filter. +

+

Example programs: +

+
    +
  • Generate a colour ramp by setting pixel values from the position of the pixel +in the output image. (Note that this will work with all pixel formats, but +the generated output will not be the same.) +
    __kernel void ramp(__write_only image2d_t dst,
    +                   unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 val;
    +    val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
    +
    +    write_imagef(dst, loc, val);
    +}
    +
    +
  • Generate a Sierpinski carpet pattern, panning by a single pixel each frame. +
    __kernel void sierpinski_carpet(__write_only image2d_t dst,
    +                                unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = 0.0f;
    +    int x = loc.x + index;
    +    int y = loc.y + index;
    +    while (x > 0 || y > 0) {
    +        if (x % 3 == 1 && y % 3 == 1) {
    +            value = 1.0f;
    +            break;
    +        }
    +        x /= 3;
    +        y /= 3;
    +    }
    +
    +    write_imagef(dst, loc, value);
    +}
    +
    +
+ + +

18.15 sierpinski

+ +

Generate a Sierpinski carpet/triangle fractal, and randomly pan around. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
seed
+

Set seed which is used for random panning. +

+
+
jump
+

Set max jump for single pan destination. Allowed range is from 1 to 10000. +

+
+
type
+

Set fractal type, can be default carpet or triangle. +

+
+ + +

18.16 zoneplate

+

Generate a zoneplate test video pattern. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "320x240". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
precision
+

Set precision in bits for look-up table for sine calculations. Default value is 10. +Allowed range is from 4 to 16. +

+
+
xo
+

Set horizontal axis offset for output signal. Default value is 0. +

+
+
yo
+

Set vertical axis offset for output signal. Default value is 0. +

+
+
to
+

Set time axis offset for output signal. Default value is 0. +

+
+
k0
+

Set 0-order, constant added to signal phase. Default value is 0. +

+
+
kx
+

Set 1-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky
+

Set 1-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt
+

Set 1-order, phase factor multiplier for time axis. Default value is 0. +

+
+
kxt, kyt, kxy
+

Set phase factor multipliers for combination of spatial and temporal axis. +Default value is 0. +

+
+
kx2
+

Set 2-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky2
+

Set 2-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt2
+

Set 2-order, phase factor multiplier for time axis. Default value is 0. +

+
+
ku
+

Set the constant added to final phase to produce chroma-blue component of signal. +Default value is 0. +

+
+
kv
+

Set the constant added to final phase to produce chroma-red component of signal. +Default value is 0. +

+
+ + +

18.16.1 Commands

+ +

This source supports the some above options as commands. +

+ +

18.16.2 Examples

+ +
    +
  • Generate horizontal color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:kx2=256:s=wvga:xo=-426:kt=11
    +
    + +
  • Generate vertical color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:ky2=156:s=wvga:yo=-240:kt=11
    +
    + +
  • Generate circular zone-plate: +
    +
    zoneplate=ku=512:kv=100:kt2=0:ky2=256:kx2=556:s=wvga:yo=0:kt=11
    +
    +
+ + + +

19 Video Sinks

+ +

Below is a description of the currently available video sinks. +

+ +

19.1 buffersink

+ +

Buffer video frames, and make them available to the end of the filter +graph. +

+

This sink is mainly intended for programmatic use, in particular +through the interface defined in libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVBufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+ +

19.2 nullsink

+ +

Null video sink: do absolutely nothing with the input video. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

20 Multimedia Filters

+ +

Below is a description of the currently available multimedia filters. +

+ +

20.1 a3dscope

+ +

Convert input audio to 3d scope video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
fov
+

Set the camera field of view. Default is 90 degrees. +Allowed range is from 40 to 150. +

+
+
roll
+

Set the camera roll. +

+
+
pitch
+

Set the camera pitch. +

+
+
yaw
+

Set the camera yaw. +

+
+
xzoom
+

Set the camera zoom on X-axis. +

+
+
yzoom
+

Set the camera zoom on Y-axis. +

+
+
zzoom
+

Set the camera zoom on Z-axis. +

+
+
xpos
+

Set the camera position on X-axis. +

+
+
ypos
+

Set the camera position on Y-axis. +

+
+
zpos
+

Set the camera position on Z-axis. +

+
+
length
+

Set the length of displayed audio waves in number of frames. +

+
+ + +

20.1.1 Commands

+ +

Filter supports the some above options as commands. +

+ +

20.2 abitscope

+ +

Convert input audio to a video output, displaying the audio bit scope. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 1024x256. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channels. Unrecognized or missing colors will be replaced +by white color. +

+
+
mode, m
+

Set output mode. Can be bars or trace. Default is bars. +

+
+ + +

20.3 adrawgraph

+

Draw a graph using input audio metadata. +

+

See drawgraph +

+ +

20.4 agraphmonitor

+ +

See graphmonitor. +

+ +

20.5 ahistogram

+ +

Convert input audio to a video output, displaying the volume histogram. +

+

The filter accepts the following options: +

+
+
dmode
+

Specify how histogram is calculated. +

+

It accepts the following values: +

+
‘single’
+

Use single histogram for all channels. +

+
‘separate’
+

Use separate histogram for each channel. +

+
+

Default is single. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
scale
+

Set display scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘sqrt’
+

square root +

+
‘cbrt’
+

cubic root +

+
‘lin’
+

linear +

+
‘rlog’
+

reverse logarithmic +

+
+

Default is log. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘lin’
+

linear +

+
+

Default is log. +

+
+
acount
+

Set how much frames to accumulate in histogram. +Default is 1. Setting this to -1 accumulates all frames. +

+
+
rheight
+

Set histogram ratio of window height. +

+
+
slide
+

Set sonogram sliding. +

+

It accepts the following values: +

+
‘replace’
+

replace old rows with new ones. +

+
‘scroll’
+

scroll from top to bottom. +

+
+

Default is replace. +

+
+
hmode
+

Set histogram mode. +

+

It accepts the following values: +

+
‘abs’
+

Use absolute values of samples. +

+
‘sign’
+

Use untouched values of samples. +

+
+

Default is abs. +

+
+ + +

20.6 aphasemeter

+ +

Measures phase of input audio, which is exported as metadata lavfi.aphasemeter.phase, +representing mean phase of current audio frame. A video output can also be produced and is +enabled by default. The audio is passed through as first output. +

+

Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in +range [-1, 1] where -1 means left and right channels are completely out of phase +and 1 means channels are in phase. +

+

The filter accepts the following options, all related to its video output: +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
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 800x400. +

+
+
rc
+
gc
+
bc
+

Specify the red, green, blue contrast. Default values are 2, +7 and 1. +Allowed range is [0, 255]. +

+
+
mpc
+

Set color which will be used for drawing median phase. If color is +none which is default, no median phase value will be drawn. +

+
+
video
+

Enable video output. Default is enabled. +

+
+ + +

20.6.1 phasing detection

+ +

The filter also detects out of phase and mono sequences in stereo streams. +It logs the sequence start, end and duration when it lasts longer or as long as the minimum set. +

+

The filter accepts the following options for this detection: +

+
+
phasing
+

Enable mono and out of phase detection. Default is disabled. +

+
+
tolerance, t
+

Set phase tolerance for mono detection, in amplitude ratio. Default is 0. +Allowed range is [0, 1]. +

+
+
angle, a
+

Set angle threshold for out of phase detection, in degree. Default is 170. +Allowed range is [90, 180]. +

+
+
duration, d
+

Set mono or out of phase duration until notification, expressed in seconds. Default is 2. +

+
+ + +

20.6.2 Examples

+ +
    +
  • Complete example with ffmpeg to detect 1 second of mono with 0.001 phase tolerance: +
    +
    ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
    +
    +
+ + +

20.7 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 monaural 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: +

+
+
mode, m
+

Set the vectorscope mode. +

+

Available values are: +

+
‘lissajous’
+

Lissajous rotated by 45 degrees. +

+
+
‘lissajous_xy’
+

Same as above but not rotated. +

+
+
‘polar’
+

Shape resembling half of circle. +

+
+ +

Default value is ‘lissajous’. +

+
+
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 400x400. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
rc
+
gc
+
bc
+
ac
+

Specify the red, green, blue and alpha contrast. Default values are 40, +160, 80 and 255. +Allowed range is [0, 255]. +

+
+
rf
+
gf
+
bf
+
af
+

Specify the red, green, blue and alpha fade. Default values are 15, +10, 5 and 5. +Allowed range is [0, 255]. +

+
+
zoom
+

Set the zoom factor. Default value is 1. Allowed range is [0, 10]. +Values lower than 1 will auto adjust zoom factor to maximal possible value. +

+
+
draw
+

Set the vectorscope drawing mode. +

+

Available values are: +

+
‘dot’
+

Draw dot for each sample. +

+
+
‘line’
+

Draw line between previous and current sample. +

+
+
‘aaline’
+

Draw anti-aliased line between previous and current sample. +

+
+ +

Default value is ‘dot’. +

+
+
scale
+

Specify amplitude scale of audio samples. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+
‘log’
+

Logarithmic. +

+
+ +
+
swap
+

Swap left channel axis with right channel axis. +

+
+
mirror
+

Mirror axis. +

+
+
‘none’
+

No mirror. +

+
+
‘x’
+

Mirror only x axis. +

+
+
‘y’
+

Mirror only y axis. +

+
+
‘xy’
+

Mirror both axis. +

+
+ +
+
+ + +

20.7.1 Examples

+ +
    +
  • Complete example using ffplay: +
    +
    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]'
    +
    +
+ + +

20.7.2 Commands

+ +

This filter supports the all above options as commands except options size and rate. +

+ +

20.8 bench, abench

+ +

Benchmark part of a filtergraph. +

+

The filter accepts the following options: +

+
+
action
+

Start or stop a timer. +

+

Available values are: +

+
‘start’
+

Get the current time, set it as frame metadata (using the key +lavfi.bench.start_time), and forward the frame to the next filter. +

+
+
‘stop’
+

Get the current time and fetch the lavfi.bench.start_time metadata from +the input frame metadata to get the time difference. Time difference, average, +maximum and minimum time (respectively t, avg, max and +min) are then printed. The timestamps are expressed in seconds. +

+
+
+
+ + +

20.8.1 Examples

+ +
    +
  • Benchmark selectivecolor filter: +
    +
    bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
    +
    +
+ + +

20.9 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: +

+
+
n
+

Set the number of segments. Default is 2. +

+
+
v
+

Set the number of output video streams, that is also the number of video +streams in each segment. Default is 1. +

+
+
a
+

Set the number of output audio streams, that is also the number of audio +streams in each segment. Default is 0. +

+
+
unsafe
+

Activate unsafe mode: do not fail if segments have a different format. +

+
+
+ +

The filter has v+a outputs: first v video outputs, then +a audio outputs. +

+

There are nx(v+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. +

+ +

20.9.1 Examples

+ +
    +
  • Concatenate an opening, an episode and an ending, all in bilingual version +(video in stream 0, audio in streams 1 and 2): +
    +
    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
    +
    + +
  • Concatenate two parts, handling audio and video separately, using the +(a)movie sources, and adjusting the resolution: +
    +
    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]
    +
    +

    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. +

    +
+ + +

20.9.2 Commands

+ +

This filter supports the following commands: +

+
next
+

Close the current segment and step to the next one +

+
+ + +

20.10 ebur128

+ +

EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness +level. By default, it logs a message at a frequency of 10Hz with the +Momentary loudness (identified by M), Short-term loudness (S), +Integrated loudness (I) and Loudness Range (LRA). +

+

The filter can only analyze streams which have +sample format is double-precision floating point. The input stream will be converted to +this specification, if needed. Users may need to insert aformat and/or aresample filters +after this filter to obtain the original parameters. +

+

The filter also has a video output (see the 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), but can optionally be configured +to instead display short-term loudness (see gauge). +

+

The green area marks a +/- 1LU target range around the target loudness +(-23LUFS by default, unless modified through target). +

+

More information about the Loudness Recommendation EBU R128 on +http://tech.ebu.ch/loudness. +

+

The filter accepts the following options: +

+
+
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 0. +

+
+
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 640x480. +

+
+
meter
+

Set the EBU scale meter. Default is 9. Common values are 9 and +18, respectively for EBU scale meter +9 and EBU scale meter +18. Any +other integer value between this range is allowed. +

+
+
metadata
+

Set metadata injection. If set to 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 lavfi.r128.. +

+

Default is 0. +

+
+
framelog
+

Force the frame logging level. +

+

Available values are: +

+
‘quiet’
+

logging disabled +

+
‘info’
+

information logging level +

+
‘verbose’
+

verbose logging level +

+
+ +

By default, the logging level is set to info. If the video or +the metadata options are set, it switches to verbose. +

+
+
peak
+

Set peak mode(s). +

+

Available modes can be cumulated (the option is a flag type). Possible +values are: +

+
‘none’
+

Disable any peak mode (default). +

+
‘sample’
+

Enable sample-peak mode. +

+

Simple peak mode looking for the higher sample value. It logs a message +for sample-peak (identified by SPK). +

+
‘true’
+

Enable true-peak mode. +

+

If enabled, the peak lookup is done on an over-sampled version of the input +stream for better peak accuracy. It logs a message for true-peak. +(identified by TPK) and true-peak per frame (identified by FTPK). +This mode requires a build with libswresample. +

+
+ +
+
dualmono
+

Treat mono input files as "dual mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +

+
+
panlaw
+

Set a specific pan law to be used for the measurement of dual mono files. +This parameter is optional, and has a default value of -3.01dB. +

+
+
target
+

Set a specific target level (in LUFS) used as relative zero in the visualization. +This parameter is optional and has a default value of -23LUFS as specified +by EBU R128. However, material published online may prefer a level of -16LUFS +(e.g. for use with podcasts or video platforms). +

+
+
gauge
+

Set the value displayed by the gauge. Valid values are momentary and s +shortterm. By default the momentary value will be used, but in certain +scenarios it may be more useful to observe the short term value instead (e.g. +live mixing). +

+
+
scale
+

Sets the display scale for the loudness. Valid parameters are absolute +(in LUFS) or relative (LU) relative to the target. This only affects the +video output, not the summary or continuous log output. +

+
+
integrated
+

Read-only exported value for measured integrated loudness, in LUFS. +

+
+
range
+

Read-only exported value for measured loudness range, in LU. +

+
+
lra_low
+

Read-only exported value for measured LRA low, in LUFS. +

+
+
lra_high
+

Read-only exported value for measured LRA high, in LUFS. +

+
+
sample_peak
+

Read-only exported value for measured sample peak, in dBFS. +

+
+
true_peak
+

Read-only exported value for measured true peak, in dBFS. +

+
+ + +

20.10.1 Examples

+ +
    +
  • Real-time graph using ffplay, with a EBU scale meter +18: +
    +
    ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
    +
    + +
  • Run an analysis with ffmpeg: +
    +
    ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
    +
    +
+ + +

20.11 interleave, ainterleave

+ +

Temporally interleave frames from several inputs. +

+

interleave works with video inputs, ainterleave with audio. +

+

These filters read frames from several inputs and send the oldest +queued frame to the output. +

+

Input streams must have 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 select filter +which always drops input frames. The interleave filter will keep +reading from that input, but it will never be able to send new frames +to output until the input sends 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: +

+
+
nb_inputs, n
+

Set the number of different inputs, it is 2 by default. +

+
+
duration
+

How to determine the end-of-stream. +

+
+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+ +
+
+ + +

20.11.1 Examples

+ +
    +
  • Interleave frames belonging to different streams using ffmpeg: +
    +
    ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
    +
    + +
  • Add flickering blur effect: +
    +
    select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
    +
    +
+ + +

20.12 latency, alatency

+

Measure filtering latency. +

+

Report previous filter filtering latency, delay in number of audio samples for audio filters +or number of video frames for video filters. +

+

On end of input stream, filter will report min and max measured latency for previous running filter +in filtergraph. +

+ +

20.13 metadata, ametadata

+ +

Manipulate frame metadata. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

If both value and key is set, select frames +which have such metadata. If only key is set, select +every frame that has such key in metadata. +

+
+
‘add’
+

Add new metadata key and value. If key is already available +do nothing. +

+
+
‘modify’
+

Modify value of already present key. +

+
+
‘delete’
+

If value is set, delete only keys that have such value. +Otherwise, delete key. If key is not set, delete all metadata values in +the frame. +

+
+
‘print’
+

Print key and its value if metadata was found. If key is not set print all +metadata values available in frame. +

+
+ +
+
key
+

Set key used with all modes. Must be set for all modes except print and delete. +

+
+
value
+

Set metadata value which will be used. This option is mandatory for +modify and add mode. +

+
+
function
+

Which function to use when comparing metadata value and value. +

+

Can be one of following: +

+
+
‘same_str’
+

Values are interpreted as strings, returns true if metadata value is same as value. +

+
+
‘starts_with’
+

Values are interpreted as strings, returns true if metadata value starts with +the value option string. +

+
+
‘less’
+

Values are interpreted as floats, returns true if metadata value is less than value. +

+
+
‘equal’
+

Values are interpreted as floats, returns true if value is equal with metadata value. +

+
+
‘greater’
+

Values are interpreted as floats, returns true if metadata value is greater than value. +

+
+
‘expr’
+

Values are interpreted as floats, returns true if expression from option expr +evaluates to true. +

+
+
‘ends_with’
+

Values are interpreted as strings, returns true if metadata value ends with +the value option string. +

+
+ +
+
expr
+

Set expression which is used when function is set to expr. +The expression is evaluated through the eval API and can contain the following +constants: +

+
+
VALUE1, FRAMEVAL
+

Float representation of value from metadata key. +

+
+
VALUE2, USERVAL
+

Float representation of value as supplied by user in value option. +

+
+ +
+
file
+

If specified in print mode, output is written to the named file. Instead of +plain filename any writable url can be specified. Filename “-” is a shorthand +for standard output. If file option is not set, output is written to the log +with AV_LOG_INFO loglevel. +

+
+
direct
+

Reduces buffering in print mode when output is written to a URL set using file. +

+
+
+ + +

20.13.1 Examples

+ +
    +
  • Print all metadata values for frames with key lavfi.signalstats.YDIF with values +between 0 and 1. +
    +
    signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
    +
    +
  • Print silencedetect output to file metadata.txt. +
    +
    silencedetect,ametadata=mode=print:file=metadata.txt
    +
    +
  • Direct all metadata to a pipe with file descriptor 4. +
    +
    metadata=mode=print:file='pipe\:4'
    +
    +
+ + +

20.14 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 the following options: +

+
+
mode
+

Select the permissions mode. +

+

It accepts the following values: +

+
‘none’
+

Do nothing. This is the default. +

+
‘ro’
+

Set all the output frames read-only. +

+
‘rw’
+

Set all the output frames directly writable. +

+
‘toggle’
+

Make the frame read-only if writable, and writable if read-only. +

+
‘random’
+

Set each output frame read-only or writable randomly. +

+
+ +
+
seed
+

Set the seed for the random mode, 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. +

+
+ +

Note: in case of auto-inserted filter between the permission filter and the +following one, the permission might not be received as expected in that +following filter. Inserting a format or aformat filter before the +perms/aperms filter can avoid this problem. +

+ +

20.15 realtime, arealtime

+ +

Slow down filtering to match real time approximately. +

+

These filters will pause the filtering for a variable amount of time to +match the output rate with the input timestamps. +They are similar to the re option to ffmpeg. +

+

They accept the following options: +

+
+
limit
+

Time limit for the pauses. Any pause longer than that will be considered +a timestamp discontinuity and reset the timer. Default is 2 seconds. +

+
speed
+

Speed factor for processing. The value must be a float larger than zero. +Values larger than 1.0 will result in faster than realtime processing, +smaller will slow processing down. The limit is automatically adapted +accordingly. Default is 1.0. +

+

A processing speed faster than what is possible without these filters cannot +be achieved. +

+
+ + +

20.15.1 Commands

+ +

Both filters supports the all above options as commands. +

+ +

20.16 segment, asegment

+ +

Split single input stream into multiple streams. +

+

This filter does opposite of concat filters. +

+

segment works on video frames, asegment on audio samples. +

+

This filter accepts the following options: +

+
+
timestamps
+

Timestamps of output segments separated by ’|’. The first segment will run +from the beginning of the input stream. The last segment will run until +the end of the input stream +

+
+
frames, samples
+

Exact frame/sample count to split the segments. +

+
+ +

In all cases, prefixing an each segment with ’+’ will make it relative to the +previous segment. +

+ +

20.16.1 Examples

+ +
    +
  • Split input audio stream into three output audio streams, starting at start of input audio stream +and storing that in 1st output audio stream, then following at 60th second and storing than in 2nd +output audio stream, and last after 150th second of input audio stream store in 3rd output audio stream: +
    +
    asegment=timestamps="60|150"
    +
    + +
+ + +

20.17 select, aselect

+ +

Select frames to pass in output. +

+

This filter accepts the following options: +

+
+
expr, e
+

Set expression, which is evaluated for each input frame. +

+

If the expression is evaluated to zero, the frame 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 +ceil(val)-1, assuming that the input index starts from 0. +

+

For example a value of 1.2 corresponds to the output with index +ceil(1.2)-1 = 2-1 = 1, that is the second output. +

+
+
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. +

+
+ +

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the filtered frame, starting from 0. +

+
+
selected_n
+

The (sequential) number of the selected frame, starting from 0. +

+
+
prev_selected_n
+

The sequential number of the last selected frame. It’s NAN if undefined. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the filtered frame, +expressed in TB units. It’s NAN if undefined. +

+
+
t
+

The PTS of the filtered frame, +expressed in seconds. It’s NAN if undefined. +

+
+
prev_pts
+

The PTS of the previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_pts
+

The PTS of the last previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_t
+

The PTS of the last previously selected frame, expressed in seconds. It’s NAN if undefined. +

+
+
start_pts
+

The first PTS in the stream which is not NAN. It remains NAN if not found. +

+
+
start_t
+

The first PTS, in seconds, in the stream which is not NAN. It remains NAN if not found. +

+
+
pict_type (video only)
+

The type of the filtered frame. It can assume one of the following +values: +

+
I
+
P
+
B
+
S
+
SI
+
SP
+
BI
+
+ +
+
interlace_type (video only)
+

The frame interlace type. It can assume one of the following values: +

+
PROGRESSIVE
+

The frame is progressive (not interlaced). +

+
TOPFIRST
+

The frame is top-field-first. +

+
BOTTOMFIRST
+

The frame is bottom-field-first. +

+
+ +
+
consumed_sample_n (audio only)
+

the number of selected samples before the current frame +

+
+
samples_n (audio only)
+

the number of samples in the current frame +

+
+
sample_rate (audio only)
+

the input sample rate +

+
+
key
+

This is 1 if the filtered frame is a key-frame, 0 otherwise. +

+
+
pos
+

the position in the file of the filtered frame, -1 if the information +is not available (e.g. for synthetic video); deprecated, do not use +

+
+
scene (video only)
+

value between 0 and 1 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one (see the example below) +

+
+
concatdec_select
+

The concat demuxer can select only part of a concat input file by setting an +inpoint and an outpoint, but the output packets may not be entirely contained +in the selected interval. By using this variable, it is possible to skip frames +generated by the concat demuxer which are not exactly contained in the selected +interval. +

+

This works by comparing the frame pts against the lavf.concat.start_time +and the lavf.concat.duration packet metadata values which are also +present in the decoded frames. +

+

The concatdec_select variable is -1 if the frame pts is at least +start_time and either the duration metadata is missing or the frame pts is less +than start_time + duration, 0 otherwise, and NaN if the start_time metadata is +missing. +

+

That basically means that an input frame is selected if its pts is within the +interval set by the concat demuxer. +

+
+
iw (video only)
+

Represents the width of the input video frame. +

+
+
ih (video only)
+

Represents the height of the input video frame. +

+
+
view (video only)
+

View ID for multi-view video. +

+
+
+ +

The default value of the select expression is "1". +

+ +

20.17.1 Examples

+ +
    +
  • Select all frames in input: +
    +
    select
    +
    + +

    The example above is the same as: +

    +
    select=1
    +
    + +
  • Skip all frames: +
    +
    select=0
    +
    + +
  • Select only I-frames: +
    +
    select='eq(pict_type\,I)'
    +
    + +
  • Select one frame every 100: +
    +
    select='not(mod(n\,100))'
    +
    + +
  • Select only frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)
    +
    + +
  • Select only I-frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)*eq(pict_type\,I)
    +
    + +
  • Select frames with a minimum distance of 10 seconds: +
    +
    select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
    +
    + +
  • Use aselect to select only audio frames with samples number > 100: +
    +
    aselect='gt(samples_n\,100)'
    +
    + +
  • Create a mosaic of the first scenes: +
    +
    ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
    +
    + +

    Comparing scene against a value between 0.3 and 0.5 is generally a sane +choice. +

    +
  • Send even and odd frames to separate outputs, and compose them: +
    +
    select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
    +
    + +
  • Select useful frames from an ffconcat file which is using inpoints and +outpoints but where the source files are not intra frame only. +
    +
    ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
    +
    +
+ + +

20.18 sendcmd, asendcmd

+ +

Send commands to filters in the filtergraph. +

+

These filters read commands to be sent to other filters in the +filtergraph. +

+

sendcmd must be inserted between two video filters, +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 +with the commands option, or in a file specified by the +filename option. +

+

These filters accept the following options: +

+
commands, c
+

Set the commands to be read and sent to the other filters. +

+
filename, f
+

Set the filename of the commands to be read and sent to the other +filters. +

+
+ + +

20.18.1 Commands syntax

+ +

A commands description consists of a sequence of interval +specifications, comprising a list of commands to be executed when a +particular event related to that interval occurs. The occurring event +is typically the current frame time entering or leaving a given time +interval. +

+

An interval is specified by the following syntax: +

+
START[-END] COMMANDS;
+
+ +

The time interval is specified by the START and END times. +END is optional and defaults to the maximum time. +

+

The current frame time is considered within the specified interval if +it is included in the interval [START, END), that is when +the time is greater or equal to START and is lesser than +END. +

+

COMMANDS consists of a sequence of one or more command +specifications, separated by ",", relating to that interval. The +syntax of a command specification is given by: +

+
[FLAGS] TARGET COMMAND ARG
+
+ +

FLAGS is optional and specifies the type of events relating to +the time interval which enable sending the specified command, and must +be a non-null sequence of identifier flags separated by "+" or "|" and +enclosed between "[" and "]". +

+

The following flags are recognized: +

+
enter
+

The command is sent when the current frame timestamp enters the +specified interval. In other words, the command is sent when the +previous frame timestamp was not in the given interval, and the +current is. +

+
+
leave
+

The command is sent when the current frame timestamp leaves the +specified interval. In other words, the command is sent when the +previous frame timestamp was in the given interval, and the +current is not. +

+
+
expr
+

The command ARG is interpreted as expression and result of +expression is passed as ARG. +

+

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
POS
+

Original position in the file of the frame, or undefined if undefined +for the current frame. Deprecated, do not use. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
N
+

The count of the input frame for video or audio, starting from 0. +

+
+
T
+

The time in seconds of the current frame. +

+
+
TS
+

The start time in seconds of the current command interval. +

+
+
TE
+

The end time in seconds of the current command interval. +

+
+
TI
+

The interpolated time of the current command interval, TI = (T - TS) / (TE - TS). +

+
+
W
+

The video frame width. +

+
+
H
+

The video frame height. +

+
+ +
+
+ +

If FLAGS is not specified, a default value of [enter] is +assumed. +

+

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional list of argument for +the given COMMAND. +

+

Between one interval specification and another, whitespaces, or +sequences of characters starting with # until the end of line, +are ignored and can be used to annotate comments. +

+

A simplified BNF description of the commands specification syntax +follows: +

+
COMMAND_FLAG  ::= "enter" | "leave"
+COMMAND_FLAGS ::= COMMAND_FLAG [(+|"|")COMMAND_FLAG]
+COMMAND       ::= ["[" COMMAND_FLAGS "]"] TARGET COMMAND [ARG]
+COMMANDS      ::= COMMAND [,COMMANDS]
+INTERVAL      ::= START[-END] COMMANDS
+INTERVALS     ::= INTERVAL[;INTERVALS]
+
+ + +

20.18.2 Examples

+ +
    +
  • Specify audio tempo change at second 4: +
    +
    asendcmd=c='4.0 atempo tempo 1.5',atempo
    +
    + +
  • Target a specific filter instance: +
    +
    asendcmd=c='4.0 atempo@my tempo 1.5',atempo@my
    +
    + +
  • Specify a list of drawtext and hue commands in a file. +
    +
    # show text in the interval 5-10
    +5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
    +         [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
    +
    +# desaturate the image in the interval 15-20
    +15.0-20.0 [enter] hue s 0,
    +          [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
    +          [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(25-t)
    +
    + +

    A filtergraph allowing to read and process the above command list +stored in a file test.cmd, can be specified with: +

    +
    sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
    +
    +
+ + +

20.19 setpts, asetpts

+ +

Change the PTS (presentation timestamp) of the input frames. +

+

setpts works on video frames, asetpts on audio frames. +

+

This filter accepts the following options: +

+
+
expr
+

The expression which is evaluated for each frame to construct its timestamp. +

+
+
strip_fps (video only)
+

Boolean option which determines if the original framerate and frame duration +metadata is unset. If set to true, be advised that a sane frame rate should be +explicitly specified if output is sent to a constant frame rate muxer. +Default is false. +

+
+
+ +

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
FRAME_RATE, FR
+

frame rate, only defined for constant frame-rate video +

+
+
PTS
+

The presentation timestamp in input +

+
+
N
+

The count of the input frame for video or the number of consumed samples, +not including the current frame for audio, starting from 0. +

+
+
NB_CONSUMED_SAMPLES
+

The number of consumed samples, not including the current frame (only +audio) +

+
+
NB_SAMPLES, S
+

The number of samples in the current frame (only audio) +

+
+
SAMPLE_RATE, SR
+

The audio sample rate. +

+
+
STARTPTS
+

The PTS of the first frame. +

+
+
STARTT
+

the time in seconds of the first frame +

+
+
INTERLACED
+

State whether the current frame is interlaced. +

+
+
T
+

the time in seconds of the current frame +

+
+
POS
+

original position in the file of the frame, or undefined if undefined +for the current frame; deprecated, do not use +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INT
+

previous input time in seconds +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTT
+

previous output time in seconds +

+
+
RTCTIME
+

The wallclock (RTC) time in microseconds. This is deprecated, use time(0) +instead. +

+
+
RTCSTART
+

The wallclock (RTC) time at the start of the movie in microseconds. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
T_CHANGE
+

Time of the first frame after command was applied or time of the first frame if no commands. +

+
+
+ + +

20.19.1 Examples

+ +
    +
  • Start counting PTS from zero +
    +
    setpts=PTS-STARTPTS
    +
    + +
  • Apply fast motion effect: +
    +
    setpts=0.5*PTS
    +
    + +
  • Apply slow motion effect: +
    +
    setpts=2.0*PTS
    +
    + +
  • Set fixed rate of 25 frames per second: +
    +
    setpts=N/(25*TB)
    +
    + +
  • Apply a random jitter effect of +/-100 TB units: +
    +
    setpts=PTS+randomi(0, -100\,100)
    +
    + +
  • Set fixed rate 25 fps with some jitter: +
    +
    setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
    +
    + +
  • Apply an offset of 10 seconds to the input PTS: +
    +
    setpts=PTS+10/TB
    +
    + +
  • Generate timestamps from a "live source" and rebase onto the current timebase: +
    +
    setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
    +
    + +
  • Generate timestamps by counting samples: +
    +
    asetpts=N/SR/TB
    +
    + +
+ + +

20.19.2 Commands

+ +

Both filters support all above options as commands. +

+ +

20.20 setrange

+ +

Force color range for the output video frame. +

+

The setrange filter marks the color range property for the +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. +

+

The filter accepts the following options: +

+
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property. +

+
+
‘unspecified, unknown’
+

Set the color range as unspecified. +

+
+
‘limited, tv, mpeg’
+

Set the color range as limited. +

+
+
‘full, pc, jpeg’
+

Set the color range as full. +

+
+
+
+ + +

20.21 settb, asettb

+ +

Set the timebase to use for the output frames timestamps. +It is mainly useful for testing timebase configuration. +

+

It accepts the following parameters: +

+
+
expr, tb
+

The expression which is evaluated into the output timebase. +

+
+
+ +

The value for tb is an arithmetic expression representing a +rational. The expression can contain the constants "AVTB" (the default +timebase), "intb" (the input timebase) and "sr" (the sample rate, +audio only). Default value is "intb". +

+ +

20.21.1 Examples

+ +
    +
  • Set the timebase to 1/25: +
    +
    settb=expr=1/25
    +
    + +
  • Set the timebase to 1/10: +
    +
    settb=expr=0.1
    +
    + +
  • Set the timebase to 1001/1000: +
    +
    settb=1+0.001
    +
    + +
  • Set the timebase to 2*intb: +
    +
    settb=2*intb
    +
    + +
  • Set the default timebase value: +
    +
    settb=AVTB
    +
    +
+ + +

20.22 showcqt

+

Convert input audio to a video output representing frequency spectrum +logarithmically using Brown-Puckette constant Q transform algorithm with +direct frequency domain coefficient calculation (but the transform itself +is not really constant Q, instead the Q factor is actually variable/clamped), +with musical tone scale, from E0 to D#10. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify the video size for the output. It must be even. For the syntax of this option, +check the "Video size" section in the ffmpeg-utils manual. +Default value is 1920x1080. +

+
+
fps, rate, r
+

Set the output frame rate. Default value is 25. +

+
+
bar_h
+

Set the bargraph height. It must be even. Default value is -1 which +computes the bargraph height automatically. +

+
+
axis_h
+

Set the axis height. It must be even. Default value is -1 which computes +the axis height automatically. +

+
+
sono_h
+

Set the sonogram height. It must be even. Default value is -1 which +computes the sonogram height automatically. +

+
+
fullhd
+

Set the fullhd resolution. This option is deprecated, use size, s +instead. Default value is 1. +

+
+
sono_v, volume
+

Specify the sonogram volume expression. It can contain variables: +

+
bar_v
+

the bar_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is 16. +

+
+
bar_v, volume2
+

Specify the bargraph volume expression. It can contain variables: +

+
sono_v
+

the sono_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is sono_v. +

+
+
sono_g, gamma
+

Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, +higher gamma makes the spectrum having more range. Default value is 3. +Acceptable range is [1, 7]. +

+
+
bar_g, gamma2
+

Specify the bargraph gamma. Default value is 1. Acceptable range is +[1, 7]. +

+
+
bar_t
+

Specify the bargraph transparency level. Lower value makes the bargraph sharper. +Default value is 1. Acceptable range is [0, 1]. +

+
+
timeclamp, tc
+

Specify the transform timeclamp. At low frequency, there is trade-off between +accuracy in time domain and frequency domain. If timeclamp is lower, +event in time domain is represented more accurately (such as fast bass drum), +otherwise event in frequency domain is represented more accurately +(such as bass guitar). Acceptable range is [0.002, 1]. Default value is 0.17. +

+
+
attack
+

Set attack time in seconds. The default is 0 (disabled). Otherwise, it +limits future samples by applying asymmetric windowing in time domain, useful +when low latency is required. Accepted range is [0, 1]. +

+
+
basefreq
+

Specify the transform base frequency. Default value is 20.01523126408007475, +which is frequency 50 cents below E0. Acceptable range is [10, 100000]. +

+
+
endfreq
+

Specify the transform end frequency. Default value is 20495.59681441799654, +which is frequency 50 cents above D#10. Acceptable range is [10, 100000]. +

+
+
coeffclamp
+

This option is deprecated and ignored. +

+
+
tlength
+

Specify the transform length in time domain. Use this option to control accuracy +trade-off between time domain and frequency domain at every frequency sample. +It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option. +

+
+

Default value is 384*tc/(384+tc*f). +

+
+
count
+

Specify the transform count for every video frame. Default value is 6. +Acceptable range is [1, 30]. +

+
+
fcount
+

Specify the transform count for every single pixel. Default value is 0, +which makes it computed automatically. Acceptable range is [0, 10]. +

+
+
fontfile
+

Specify font file for use with freetype to draw the axis. If not specified, +use embedded font. Note that drawing with font file or embedded font is not +implemented with custom basefreq and endfreq, use axisfile +option instead. +

+
+
font
+

Specify fontconfig pattern. This has lower priority than fontfile. The +: in the pattern may be replaced by | to avoid unnecessary +escaping. +

+
+
fontcolor
+

Specify font color expression. This is arithmetic expression that should return +integer value 0xRRGGBB. It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
midi(f)
+

midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) +

+
r(x), g(x), b(x)
+

red, green, and blue value of intensity x. +

+
+

Default value is st(0, (midi(f)-59.5)/12); +st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); +r(1-ld(1)) + b(ld(1)). +

+
+
axisfile
+

Specify image file to draw the axis. This option override fontfile and +fontcolor option. +

+
+
axis, text
+

Enable/disable drawing text to the axis. If it is set to 0, drawing to +the axis is disabled, ignoring fontfile and axisfile option. +Default value is 1. +

+
+
csp
+

Set colorspace. The accepted values are: +

+
‘unspecified’
+

Unspecified (default) +

+
+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
cscheme
+

Set spectrogram color scheme. This is list of floating point values with format +left_r|left_g|left_b|right_r|right_g|right_b. +The default is 1|0.5|0|0|0.5|1. +

+
+
+ + +

20.22.1 Examples

+ +
    +
  • Playing audio while showing the spectrum: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with frame rate 30 fps: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
    +
    + +
  • Playing at 1280x720: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
    +
    + +
  • Disable sonogram display: +
    +
    sono_h=0
    +
    + +
  • A1 and its harmonics: A1, A2, (near)E3, A3: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with more accuracy in frequency domain: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
    +
    + +
  • Custom volume: +
    +
    bar_v=10:sono_v=bar_v*a_weighting(f)
    +
    + +
  • Custom gamma, now spectrum is linear to the amplitude. +
    +
    bar_g=2:sono_g=2
    +
    + +
  • Custom tlength equation: +
    +
    tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'
    +
    + +
  • Custom fontcolor and fontfile, C-note is colored green, others are colored blue: +
    +
    fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
    +
    + +
  • Custom font using fontconfig: +
    +
    font='Courier New,Monospace,mono|bold'
    +
    + +
  • Custom frequency range with custom axis using image file: +
    +
    axisfile=myaxis.png:basefreq=40:endfreq=10000
    +
    +
+ + +

20.23 showcwt

+ +

Convert input audio to video output representing frequency spectrum +using Continuous Wavelet Transform and Morlet wavelet. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
scale
+

Set the frequency scale used. Allowed values are: +

+
+
linear
+
log
+
bark
+
mel
+
erbs
+
sqrt
+
cbrt
+
qdrt
+
fm
+
+

Default value is linear. +

+
+
iscale
+

Set the intensity scale used. Allowed values are: +

+
+
linear
+
log
+
sqrt
+
cbrt
+
qdrt
+
+

Default value is log. +

+
+
min
+

Set the minimum frequency that will be used in output. +Default is 20 Hz. +

+
+
max
+

Set the maximum frequency that will be used in output. +Default is 20000 Hz. The real frequency upper limit +depends on input audio’s sample rate and such will be enforced +on this value when it is set to value greater than Nyquist frequency. +

+
+
imin
+

Set the minimum intensity that will be used in output. +

+
+
imax
+

Set the maximum intensity that will be used in output. +

+
+
logb
+

Set the logarithmic basis for brightness strength when +mapping calculated magnitude values to pixel values. +Allowed range is from 0 to 1. +Default value is 0.0001. +

+
+
deviation
+

Set the frequency deviation. +Lower values than 1 are more frequency oriented, +while higher values than 1 are more time oriented. +Allowed range is from 0 to 10. +Default value is 1. +

+
+
pps
+

Set the number of pixel output per each second in one row. +Allowed range is from 1 to 1024. +Default value is 64. +

+
+
mode
+

Set the output visual mode. Allowed values are: +

+
+
magnitude
+

Show magnitude. +

+
phase
+

Show only phase. +

+
magphase
+

Show combination of magnitude and phase. +Magnitude is mapped to brightness and phase to color. +

+
channel
+

Show unique color per channel magnitude. +

+
stereo
+

Show unique color per stereo difference. +

+
+ +

Default value is magnitude. +

+
+
slide
+

Set the output slide method. Allowed values are: +

+
+
replace
+
scroll
+
frame
+
+ +
+
direction
+

Set the direction method for output slide method. Allowed values are: +

+
+
lr
+

Direction from left to right. +

+
rl
+

Direction from right to left. +

+
ud
+

Direction from up to down. +

+
du
+

Direction from down to up. +

+
+ +
+
bar
+

Set the ratio of bargraph display to display size. Default is 0. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+ + +

20.24 showfreqs

+ +

Convert input audio to video output representing the audio power spectrum. +Audio amplitude is on Y-axis while frequency is on X-axis. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify size of video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +Default is 1024x512. +

+
+
rate, r
+

Set video rate. Default is 25. +

+
+
mode
+

Set display mode. +This set how each frequency bin will be represented. +

+

It accepts the following values: +

+
‘line’
+
‘bar’
+
‘dot’
+
+

Default is bar. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘sqrt’
+

Square root scale. +

+
+
‘cbrt’
+

Cubic root scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+

Default is log. +

+
+
fscale
+

Set frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+
‘rlog’
+

Reverse logarithmic scale. +

+
+

Default is lin. +

+
+
win_size
+

Set window size. Allowed range is from 16 to 65536. +

+

Default is 2048 +

+
+
win_func
+

Set windowing function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hanning. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
averaging
+

Set time averaging. Setting this to 0 will display current maximal peaks. +Default is 1, which means time averaging is disabled. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channel frequencies. Unrecognized or missing colors will be replaced +by white color. +

+
+
cmode
+

Set channel display mode. +

+

It accepts the following values: +

+
‘combined’
+
‘separate’
+
+

Default is combined. +

+
+
minamp
+

Set minimum amplitude used in log amplitude scaler. +

+
+
data
+

Set data display mode. +

+

It accepts the following values: +

+
‘magnitude’
+
‘phase’
+
‘delay’
+
+

Default is magnitude. +

+
+
channels
+

Set channels to use when processing audio. By default all are processed. +

+
+ + +

20.25 showspatial

+ +

Convert stereo input audio to a video output, representing the spatial relationship +between two channels. +

+

The filter accepts the following options: +

+
+
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 512x512. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
rate, r
+

Set output framerate. +

+
+ + +

20.26 showspectrum

+ +

Convert input audio to a video output, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
slide
+

Specify how the spectrum should slide along the window. +

+

It accepts the following values: +

+
‘replace’
+

the samples start again on the left when they reach the right +

+
‘scroll’
+

the samples scroll from right to left +

+
‘fullframe’
+

frames are only produced when the samples reach the right +

+
‘rscroll’
+

the samples scroll from left to right +

+
‘lreplace’
+

the samples start again on the right when they reach the left +

+
+ +

Default value is replace. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+ +

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+ +

Default value is ‘channel’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+ +

Default value is ‘sqrt’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
overlap
+

Set ratio of overlap window. Default value is 0. +When value is 1 overlap is set to recommended size for specific +window function currently used. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
data
+

Set which data to display. Can be magnitude, default or phase, +or unwrapped phase: uphase. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
fps
+

Set upper frame rate limit. Default is auto, unlimited. +

+
+
legend
+

Draw time and frequency axes and legends. Default is disabled. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ +

The usage is very similar to the showwaves filter; see the examples in that +section. +

+ +

20.26.1 Examples

+ +
    +
  • Large window with logarithmic color scaling: +
    +
    showspectrum=s=1280x480:scale=log
    +
    + +
  • Complete example for a colored and sliding spectrum per channel using ffplay: +
    +
    ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
    +             [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
    +
    +
+ + +

20.27 showspectrumpic

+ +

Convert input audio to a single video frame, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 4096x2048. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+

Default value is ‘intensity’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+

Default value is ‘log’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
legend
+

Draw time and frequency axes and legends. Default is enabled. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ + +

20.27.1 Examples

+ +
    +
  • Extract an audio spectrogram of a whole audio track +in a 1024x1024 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
    +
    +
+ + +

20.28 showvolume

+ +

Convert input audio volume to a video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set video rate. +

+
+
b
+

Set border width, allowed range is [0, 5]. Default is 1. +

+
+
w
+

Set channel width, allowed range is [80, 8192]. Default is 400. +

+
+
h
+

Set channel height, allowed range is [1, 900]. Default is 20. +

+
+
f
+

Set fade, allowed range is [0, 1]. Default is 0.95. +

+
+
c
+

Set volume color expression. +

+

The expression can use the following variables: +

+
+
VOLUME
+

Current max volume of channel in dB. +

+
+
PEAK
+

Current peak. +

+
+
CHANNEL
+

Current channel number, starting from 0. +

+
+ +
+
t
+

If set, displays channel names. Default is enabled. +

+
+
v
+

If set, displays volume values. Default is enabled. +

+
+
o
+

Set orientation, can be horizontal: h or vertical: v, +default is h. +

+
+
s
+

Set step size, allowed range is [0, 5]. Default is 0, which means +step is disabled. +

+
+
p
+

Set background opacity, allowed range is [0, 1]. Default is 0. +

+
+
m
+

Set metering mode, can be peak: p or rms: r, +default is p. +

+
+
ds
+

Set display scale, can be linear: lin or log: log, +default is lin. +

+
+
dm
+

In second. +If set to > 0., display a line for the max level +in the previous seconds. +default is disabled: 0. +

+
+
dmc
+

The color of the max line. Use when dm option is set to > 0. +default is: orange +

+
+ + +

20.29 showwaves

+ +

Convert input audio to a video output, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
mode
+

Set display mode. +

+

Available values are: +

+
‘point’
+

Draw a point for each sample. +

+
+
‘line’
+

Draw a vertical line for each sample. +

+
+
‘p2p’
+

Draw a point for each sample and a line between them. +

+
+
‘cline’
+

Draw a centered vertical line for each sample. +

+
+ +

Default value is point. +

+
+
n
+

Set the number of samples which are printed on the same column. A +larger value will decrease the frame rate. Must be a positive +integer. This option can be set only if the value for rate +is not explicitly specified. +

+
+
rate, r
+

Set the (approximate) output frame rate. This is done by setting the +option n. Default value is "25". +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. This is mostly useful to set for high n. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+ + +

20.29.1 Examples

+ +
    +
  • Output the input file audio and the corresponding video representation +at the same time: +
    +
    amovie=a.mp3,asplit[out0],showwaves[out1]
    +
    + +
  • Create a synthetic signal and show it with showwaves, forcing a +frame rate of 30 frames per second: +
    +
    aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
    +
    +
+ + +

20.30 showwavespic

+ +

Convert input audio to a single video frame, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+
filter
+

Set the filter mode. +

+

Available values are: +

+
‘average’
+

Use average samples values for each drawn sample. +

+
+
‘peak’
+

Use peak samples values for each drawn sample. +

+
+ +

Default value is average. +

+
+ + +

20.30.1 Examples

+ +
    +
  • Extract a channel split representation of the wave form of a whole audio track +in a 1024x800 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
    +
    +
+ + +

20.31 sidedata, asidedata

+ +

Delete frame side data, or select frames based on it. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

Select every frame with side data of type. +

+
+
‘delete’
+

Delete side data of type. If type is not set, delete all side +data in the frame. +

+
+
+ +
+
type
+

Set side data type used with all modes. Must be set for select mode. +

+

Possible values are: +

+
+
‘PANSCAN’
+
‘A53_CC’
+
‘STEREO3D’
+
‘MATRIXENCODING’
+
‘DOWNMIX_INFO’
+
‘REPLAYGAIN’
+
‘DISPLAYMATRIX’
+
‘AFD’
+
‘MOTION_VECTORS’
+
‘SKIP_SAMPLES’
+
‘AUDIO_SERVICE_TYPE’
+
‘MASTERING_DISPLAY_METADATA’
+
‘GOP_TIMECODE’
+
‘SPHERICAL’
+
‘CONTENT_LIGHT_LEVEL’
+
‘ICC_PROFILE’
+
‘S12M_TIMECODE’
+
‘DYNAMIC_HDR_PLUS’
+
‘REGIONS_OF_INTEREST’
+
‘VIDEO_ENC_PARAMS’
+
‘SEI_UNREGISTERED’
+
‘FILM_GRAIN_PARAMS’
+
‘DETECTION_BOUNDING_BOXES’
+
‘DETECTION_BBOXES’
+
‘DOVI_RPU_BUFFER’
+
‘DOVI_METADATA’
+
‘DYNAMIC_HDR_VIVID’
+
‘AMBIENT_VIEWING_ENVIRONMENT’
+
‘VIDEO_HINT’
+
+ +
+
+ + +

20.32 spectrumsynth

+ +

Synthesize audio from 2 input video spectrums, first input stream represents +magnitude across time and second represents phase across time. +The filter will transform from frequency domain as displayed in videos back +to time domain as presented in audio output. +

+

This filter is primarily created for reversing processed showspectrum +filter outputs, but can synthesize sound from other spectrograms too. +But in such case results are going to be poor if the phase data is not +available, because in such cases phase data need to be recreated, usually +it’s just recreated from random noise. +For best results use gray only output (channel color mode in +showspectrum filter) and log scale for magnitude video and +lin scale for phase video. To produce phase, for 2nd video, use +data option. Inputs videos should generally use fullframe +slide mode as that saves resources needed for decoding video. +

+

The filter accepts the following options: +

+
+
sample_rate
+

Specify sample rate of output audio, the sample rate of audio from which +spectrum was generated may differ. +

+
+
channels
+

Set number of channels represented in input video spectrums. +

+
+
scale
+

Set scale which was used when generating magnitude input spectrum. +Can be lin or log. Default is log. +

+
+
slide
+

Set slide which was used when generating inputs spectrums. +Can be replace, scroll, fullframe or rscroll. +Default is fullframe. +

+
+
win_func
+

Set window function used for resynthesis. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
orientation
+

Set orientation of input videos. Can be vertical or horizontal. +Default is vertical. +

+
+ + +

20.32.1 Examples

+ +
    +
  • First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, +then resynthesize videos back to audio with spectrumsynth: +
    +
    ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
    +ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
    +ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
    +
    +
+ + +

20.33 split, asplit

+ +

Split input into several identical outputs. +

+

asplit works with audio input, split with video. +

+

The filter accepts a single parameter which specifies the number of outputs. If +unspecified, it defaults to 2. +

+ +

20.33.1 Examples

+ +
    +
  • Create two separate outputs from the same input: +
    +
    [in] split [out0][out1]
    +
    + +
  • To create 3 or more outputs, you need to specify the number of +outputs, like in: +
    +
    [in] asplit=3 [out0][out1][out2]
    +
    + +
  • Create two separate outputs from the same input, one cropped and +one padded: +
    +
    [in] split [splitout1][splitout2];
    +[splitout1] crop=100:100:0:0    [cropout];
    +[splitout2] pad=200:200:100:100 [padout];
    +
    + +
  • Create 5 copies of the input audio with ffmpeg: +
    +
    ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
    +
    +
+ + +

20.34 zmq, azmq

+ +

Receive commands sent through a libzmq client, and forward them to +filters in the filtergraph. +

+

zmq and azmq work as a pass-through filters. zmq +must be inserted between two video filters, azmq between two +audio filters. Both are capable to send messages to any filter type. +

+

To enable these filters you need to install the libzmq library and +headers and configure FFmpeg with --enable-libzmq. +

+

For more information about libzmq see: +http://www.zeromq.org/ +

+

The zmq and azmq filters work as a libzmq server, which +receives messages sent through a network interface defined by the +bind_address (or the abbreviation "b") option. +Default value of this option is tcp://localhost:5555. You may +want to alter this value to your needs, but do not forget to escape any +’:’ signs (see filtergraph escaping). +

+

The received message must be in the form: +

+
TARGET COMMAND [ARG]
+
+ +

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. The default +filter instance name uses the pattern ‘Parsed_<filter_name>_<index>’, +but you can override this by using the ‘filter_name@id’ syntax +(see Filtergraph syntax). +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional argument list for the +given 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: +

+
ERROR_CODE ERROR_REASON
+MESSAGE
+
+ +

MESSAGE is optional. +

+ +

20.34.1 Examples

+ +

Look at 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 ffplay. +In this example the last overlay filter has an instance name. All other +filters will have default instance names. +

+
+
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@my=x=100 "
+
+ +

To change the color of the left side of the video, the following +command can be used: +

+
echo Parsed_color_0 c yellow | tools/zmqsend
+
+ +

To change the right side: +

+
echo Parsed_color_1 c pink | tools/zmqsend
+
+ +

To change the position of the right side: +

+
echo overlay@my x 150 | tools/zmqsend
+
+ + + + +

21 Multimedia Sources

+ +

Below is a description of the currently available multimedia sources. +

+ +

21.1 amovie

+ +

This is the same as movie source, except it selects an audio +stream by default. +

+ +

21.2 avsynctest

+

Generate an Audio/Video Sync Test. +

+

Generated stream periodically shows flash video frame and emits beep in audio. +Useful to inspect A/V sync issues. +

+

It accepts the following options: +

+
+
size, s
+

Set output video size. Default value is hd720. +

+
+
framerate, fr
+

Set output video frame rate. Default value is 30. +

+
+
samplerate, sr
+

Set output audio sample rate. Default value is 44100. +

+
+
amplitude, a
+

Set output audio beep amplitude. Default value is 0.7. +

+
+
period, p
+

Set output audio beep period in seconds. Default value is 3. +

+
+
delay, dl
+

Set output video flash delay in number of frames. Default value is 0. +

+
+
cycle, c
+

Enable cycling of video delays, by default is disabled. +

+
+
duration, d
+

Set stream output duration. By default duration is unlimited. +

+
+
fg, bg, ag
+

Set foreground/background/additional color. +

+
+ + +

21.2.1 Commands

+ +

This source supports the some above options as commands. +

+ +

21.3 movie

+ +

Read audio and/or video stream(s) from a movie container. +

+

It accepts the following parameters: +

+
+
filename
+

The name of the resource to read (not necessarily a file; it can also be a +device or a stream accessed through some protocol). +

+
+
format_name, f
+

Specifies the format assumed for the movie to read, and can be either +the name of a container or an input device. If not specified, the +format is guessed from movie_name or by probing. +

+
+
seek_point, sp
+

Specifies the seek point in seconds. The frames will be output +starting from this seek point. The parameter is evaluated with +av_strtod, so the numerical value may be suffixed by an IS +postfix. The default value is "0". +

+
+
streams, s
+

Specifies the streams to read. Several streams can be specified, +separated by "+". The source will then have as many outputs, in the +same order. The syntax is explained in the "Stream specifiers" +section in the ffmpeg manual. Two special names, "dv" and "da" specify +respectively the default (best suited) video and audio stream. Default +is "dv", or "da" if the filter is called as "amovie". +

+
+
stream_index, si
+

Specifies the index of the video stream to read. If the value is -1, +the most suitable video stream will be automatically selected. The default +value is "-1". Deprecated. If the filter is called "amovie", it will select +audio instead of video. +

+
+
loop
+

Specifies how many times to read the stream in sequence. +If the value is 0, the stream will be looped infinitely. +Default value is "1". +

+

Note that when the movie is looped the source timestamps are not +changed, so it will generate non monotonically increasing timestamps. +

+
+
discontinuity
+

Specifies the time difference between frames above which the point is +considered a timestamp discontinuity which is removed by adjusting the later +timestamps. +

+
+
dec_threads
+

Specifies the number of threads for decoding +

+
+
format_opts
+

Specify format options for the opened file. Format options can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to add protocol_whitelist and protocol_blacklist options: +

+
ffplay -f lavfi
+"movie=filename='1.sdp':format_opts='protocol_whitelist=file,rtp,udp\:protocol_blacklist=http'"
+
+
+
+ +

It allows overlaying a second video on top of the main input of +a filtergraph, as shown in this graph: +

+
input -----------> deltapts0 --> overlay --> output
+                                    ^
+                                    |
+movie --> scale--> deltapts1 -------+
+
+ +

21.3.1 Examples

+ +
    +
  • Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it +on top of the input labelled "in": +
    +
    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]
    +
    + +
  • Read from a video4linux2 device, and overlay it on top of the input +labelled "in": +
    +
    movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
    +[in] setpts=PTS-STARTPTS [main];
    +[main][over] overlay=16:16 [out]
    +
    + +
  • Read the first video stream and the audio stream with id 0x81 from +dvd.vob; the video is connected to the pad named "video" and the audio is +connected to the pad named "audio": +
    +
    movie=dvd.vob:s=v:0+#0x81 [video] [audio]
    +
    +
+ + +

21.3.2 Commands

+ +

Both movie and amovie support the following commands: +

+
seek
+

Perform seek using "av_seek_frame". +The syntax is: seek stream_index|timestamp|flags +

    +
  • stream_index: If stream_index is -1, a default +stream is selected, and timestamp is automatically converted +from AV_TIME_BASE units to the stream specific time_base. +
  • timestamp: Timestamp in AVStream.time_base units +or, if no stream is specified, in AV_TIME_BASE units. +
  • flags: Flags which select direction and seeking mode. +
+ +
+
get_duration
+

Get movie duration in AV_TIME_BASE units. +

+
+
+ + + +

22 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavfilter +

+ + +

23 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-formats.html b/ffmpeg-n8.1/doc/ffmpeg-formats.html new file mode 100644 index 00000000..2965f521 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-formats.html @@ -0,0 +1,6572 @@ + + + + + + + FFmpeg Formats Documentation + + + + + + +
+

+ FFmpeg Formats Documentation +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 Description

+ +

This document describes the supported formats (muxers and demuxers) +provided by the libavformat library. +

+ + +

2 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
avioflags flags (input/output)
+

Possible values: +

+
‘direct’
+

Reduce buffering. +

+
+ +
+
probesize integer (input)
+

Set probing size in bytes, i.e. the size of the data to analyze to get +stream information. A higher value will enable detecting 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. +

+
+
max_probe_packets integer (input)
+

Set the maximum number of buffered packets when probing a codec. +Default is 2500 packets. +

+
+
packetsize integer (output)
+

Set packet size. +

+
+
fflags flags
+

Set format flags. Some are implemented for a limited number of formats. +

+

Possible values for input files: +

+
‘discardcorrupt’
+

Discard corrupted packets. +

+
‘fastseek’
+

Enable fast, but inaccurate seeks for some formats. +

+
‘genpts’
+

Generate missing PTS if DTS is present. +

+
‘igndts’
+

Ignore DTS if PTS is also set. In case the PTS is set, the DTS value +is set to NOPTS. This is ignored when the nofillin flag is set. +

+
‘ignidx’
+

Ignore index. +

+
‘nobuffer’
+

Reduce the latency introduced by buffering during initial input streams analysis. +

+
‘nofillin’
+

Do not fill in missing values in packet fields that can be exactly calculated. +

+
‘noparse’
+

Disable AVParsers, this needs +nofillin too. +

+
‘sortdts’
+

Try to interleave output packets by DTS. At present, available only for AVIs with an index. +

+
+ +

Possible values for output files: +

+
‘autobsf’
+

Automatically apply bitstream filters as required by the output format. Enabled by default. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘flush_packets’
+

Write out packets immediately. +

+
‘shortest’
+

Stop muxing at the end of the shortest stream. +It may be needed to increase max_interleave_delta to avoid flushing the longer +streams before EOF. +

+
+ +
+
seek2any integer (input)
+

Allow seeking to non-keyframes on demuxer level when supported if set to 1. +Default is 0. +

+
+
analyzeduration integer (input)
+

Specify how many microseconds are analyzed to probe the input. A +higher value will enable detecting more accurate information, but will +increase latency. It defaults to 5,000,000 microseconds = 5 seconds. +

+
+
cryptokey hexadecimal string (input)
+

Set decryption key. +

+
+
indexmem integer (input)
+

Set max memory used for timestamp index (per stream). +

+
+
rtbufsize integer (input)
+

Set max memory used for buffering real-time frames. +

+
+
fdebug flags (input/output)
+

Print specific debug info. +

+

Possible values: +

+
‘ts’
+
+ +
+
max_delay integer (input/output)
+

Set maximum muxing or demuxing delay in microseconds. +

+
+
fpsprobesize integer (input)
+

Set number of frames used to probe fps. +

+
+
audio_preload integer (output)
+

Set microseconds by which audio packets should be interleaved earlier. +

+
+
chunk_duration integer (output)
+

Set microseconds for each chunk. +

+
+
chunk_size integer (output)
+

Set size in bytes for each chunk. +

+
+
err_detect, f_err_detect flags (input)
+

Set error detection flags. f_err_detect is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘crccheck’
+

Verify embedded CRCs. +

+
‘bitstream’
+

Detect bitstream specification deviations. +

+
‘buffer’
+

Detect improper bitstream length. +

+
‘explode’
+

Abort decoding on minor error detection. +

+
‘careful’
+

Consider things that violate the spec and have not been seen in the +wild as errors. +

+
‘compliant’
+

Consider all spec non compliancies as errors. +

+
‘aggressive’
+

Consider things that a sane encoder should not do as an error. +

+
+ +
+
max_interleave_delta integer (output)
+

Set maximum buffering duration for interleaving. The duration is +expressed in microseconds, and defaults to 10000000 (10 seconds). +

+

To ensure all the streams are interleaved correctly, libavformat will +wait until it has at least one packet for each stream before actually +writing any packets to the output file. When some streams are +"sparse" (i.e. there are large gaps between successive packets), this +can result in excessive buffering. +

+

This field specifies the maximum difference between the timestamps of the +first and the last packet in the muxing queue, above which libavformat +will output a packet regardless of whether it has queued a packet for all +the streams. +

+

If set to 0, libavformat will continue buffering packets until it has +a packet for each stream, regardless of the maximum timestamp +difference between the buffered packets. +

+
+
use_wallclock_as_timestamps integer (input)
+

Use wallclock as timestamps if set to 1. Default is 0. +

+
+
avoid_negative_ts integer (output)
+
+

Possible values: +

+
‘make_non_negative’
+

Shift timestamps to make them non-negative. +Also note that this affects only leading negative timestamps, and not +non-monotonic negative timestamps. +

+
‘make_zero’
+

Shift timestamps so that the first timestamp is 0. +

+
‘auto (default)’
+

Enables shifting when required by the target format. +

+
‘disabled’
+

Disables shifting of timestamp. +

+
+ +

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. +

+
+
skip_initial_bytes integer (input)
+

Set number of bytes to skip before reading header and frames if set to 1. +Default is 0. +

+
+
correct_ts_overflow integer (input)
+

Correct single timestamp overflows if set to 1. Default is 1. +

+
+
flush_packets integer (output)
+

Flush the underlying I/O stream after each packet. Default is -1 (auto), which +means that the underlying protocol will decide, 1 enables it, and has the +effect of reducing the latency, 0 disables it and may increase IO throughput in +some cases. +

+
+
output_ts_offset offset (output)
+

Set the output time offset. +

+

offset must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

The offset is added by the muxer to the output timestamps. +

+

Specifying a positive offset means that the corresponding streams are +delayed bt the time duration specified in offset. Default value +is 0 (meaning that no offset is applied). +

+
+
format_whitelist list (input)
+

"," separated list of allowed demuxers. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_streams integer (input)
+

Specifies the maximum number of streams. This can be used to reject files that +would require too many resources due to a large number of streams. +

+
+
skip_estimate_duration_from_pts bool (input)
+

Skip estimation of input duration if it requires an additional probing for PTS at end of file. +At present, applicable for MPEG-PS and MPEG-TS. +

+
+
duration_probesize integer (input)
+

Set probing size, in bytes, for input duration estimation when it actually requires +an additional probing for PTS at end of file (at present: MPEG-PS and MPEG-TS). +It is aimed at users interested in better durations probing for itself, or indirectly +because using the concat demuxer, for example. +The typical use case is an MPEG-TS CBR with a high bitrate, high video buffering and +ending cleaning with similar PTS for video and audio: in such a scenario, the large +physical gap between the last video packet and the last audio packet makes it necessary +to read many bytes in order to get the video stream duration. +Another use case is where the default probing behaviour only reaches a single video frame which is +not the last one of the stream due to frame reordering, so the duration is not accurate. +Setting this option has a performance impact even for small files because the probing +size is fixed. +Default behaviour is a general purpose trade-off, largely adaptive, but the probing size +will not be extended to get streams durations at all costs. +Must be an integer not lesser than 1, or 0 for default behaviour. +

+
+
strict, f_strict integer (input/output)
+

Specify how strictly to follow the standards. f_strict is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
+ + + +

2.1 Format stream specifiers

+ +

Format stream specifiers allow selection of one or more streams that +match specific properties. +

+

The exact semantics of stream specifiers is defined by the +avformat_match_stream_specifier() function declared in the +libavformat/avformat.h header and documented in the +Stream specifiers section in the ffmpeg(1) manual. +

+ +

3 Demuxers

+ +

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 +are enabled by default. You can list all available ones using the +configure option --list-demuxers. +

+

You can disable all the demuxers using the configure option +--disable-demuxers, and selectively enable a single demuxer with +the option --enable-demuxer=DEMUXER, or disable it +with the option --disable-demuxer=DEMUXER. +

+

The option -demuxers of the ff* tools will display the list of +enabled demuxers. Use -formats to view a combined list of +enabled demuxers and muxers. +

+

The description of some of the currently available demuxers follows. +

+ +

3.1 aa

+ +

Audible Format 2, 3, and 4 demuxer. +

+

This demuxer is used to demux Audible Format 2, 3, and 4 (.aa) files. +

+ +

3.2 aac

+ +

Raw Audio Data Transport Stream AAC demuxer. +

+

This demuxer is used to demux an ADTS input containing a single AAC stream +alongwith any ID3v1/2 or APE tags in it. +

+ +

3.3 apng

+ +

Animated Portable Network Graphics demuxer. +

+

This demuxer is used to demux APNG files. +All headers, but the PNG signature, up to (but not including) the first +fcTL chunk are transmitted as extradata. +Frames are then split as being all the chunks between two fcTL ones, or +between the last fcTL and IEND chunks. +

+
+
-ignore_loop bool
+

Ignore the loop variable in the file if set. Default is enabled. +

+
+
-max_fps int
+

Maximum framerate in frames per second. Default of 0 imposes no limit. +

+
+
-default_fps int
+

Default framerate in frames per second when none is specified in the file +(0 meaning as fast as possible). Default is 15. +

+
+
+ + +

3.4 asf

+ +

Advanced Systems Format demuxer. +

+

This demuxer is used to demux ASF files and MMS network streams. +

+
+
-no_resync_search bool
+

Do not try to resynchronize by looking for a certain optional start code. +

+
+ + +

3.5 concat

+ +

Virtual concatenation script demuxer. +

+

This demuxer reads a list of files and other directives from a text file and +demuxes them one after the other, as if all their packets had been muxed +together. +

+

The timestamps in the files are adjusted so that the first file starts at 0 +and each next file starts where the previous one finishes. Note that it is +done globally and may cause gaps if all streams do not have exactly the same +length. +

+

All files must have the same streams (same codecs, same time base, etc.). +

+

The duration of each file is used to adjust the timestamps of the next file: +if the duration is incorrect (because it was computed using the bit-rate or +because the file is truncated, for example), it can cause artifacts. The +duration directive can be used to override the duration stored in +each file. +

+ +

3.5.1 Syntax

+ +

The script is a text file in extended-ASCII, with one directive per line. +Empty lines, leading spaces and lines starting with ’#’ are ignored. The +following directive is recognized: +

+
+
file path
+

Path to a file to read; special characters and spaces must be escaped with +backslash or single quotes. +

+

All subsequent file-related directives apply to that file. +

+
+
ffconcat version 1.0
+

Identify the script type and version. +

+

To make FFmpeg recognize the format automatically, this directive must +appear exactly as is (no extra space or byte-order-mark) on the very first +line of the script. +

+
+
duration dur
+

Duration of the file. This information can be specified from the file; +specifying it here may be more efficient or help if the information from the +file is not available or accurate. +

+

If the duration is set for all files, then it is possible to seek in the +whole concatenated video. +

+
+
inpoint timestamp
+

In point of the file. When the demuxer opens the file it instantly seeks to the +specified timestamp. Seeking is done so that all streams can be presented +successfully at In point. +

+

This directive works best with intra frame codecs, because for non-intra frame +ones you will usually get extra packets before the actual In point and the +decoded content will most likely contain frames before In point too. +

+

For each file, packets before the file In point will have timestamps less than +the calculated start timestamp of the file (negative in case of the first +file), and the duration of the files (if not specified by the duration +directive) will be reduced based on their specified In point. +

+

Because of potential packets before the specified In point, packet timestamps +may overlap between two concatenated files. +

+
+
outpoint timestamp
+

Out point of the file. When the demuxer reaches the specified decoding +timestamp in any of the streams, it handles it as an end of file condition and +skips the current and all the remaining packets from all streams. +

+

Out point is exclusive, which means that the demuxer will not output packets +with a decoding timestamp greater or equal to Out point. +

+

This directive works best with intra frame codecs and formats where all streams +are tightly interleaved. For non-intra frame codecs you will usually get +additional packets with presentation timestamp after Out point therefore the +decoded content will most likely contain frames after Out point too. If your +streams are not tightly interleaved you may not get all the packets from all +streams before Out point and you may only will be able to decode the earliest +stream until Out point. +

+

The duration of the files (if not specified by the duration +directive) will be reduced based on their specified Out point. +

+
+
file_packet_metadata key=value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +This directive is deprecated, use file_packet_meta instead. +

+
+
file_packet_meta key value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +

+
+
option key value
+

Option to access, open and probe the file. +Can be present multiple times. +

+
+
stream
+

Introduce a stream in the virtual file. +All subsequent stream-related directives apply to the last introduced +stream. +Some streams properties must be set in order to allow identifying the +matching streams in the subfiles. +If no streams are defined in the script, the streams from the first file are +copied. +

+
+
exact_stream_id id
+

Set the id of the stream. +If this directive is given, the string with the corresponding id in the +subfiles will be used. +This is especially useful for MPEG-PS (VOB) files, where the order of the +streams is not reliable. +

+
+
stream_meta key value
+

Metadata for the stream. +Can be present multiple times. +

+
+
stream_codec value
+

Codec for the stream. +

+
+
stream_extradata hex_string
+

Extradata for the string, encoded in hexadecimal. +

+
+
chapter id start end
+

Add a chapter. id is an unique identifier, possibly small and +consecutive. +

+
+
+ + +

3.5.2 Options

+ +

This demuxer accepts the following option: +

+
+
safe
+

If set to 1, reject unsafe file paths and directives. +A file path is considered safe if it +does not contain a protocol specification and is relative and all components +only contain characters from the portable character set (letters, digits, +period, underscore and hyphen) and have no period at the beginning of a +component. +

+

If set to 0, any file name is accepted. +

+

The default is 1. +

+
+
auto_convert
+

If set to 1, try to perform automatic conversions on packet data to make the +streams concatenable. +The default is 1. +

+

Currently, the only conversion is adding the h264_mp4toannexb bitstream +filter to H.264 streams in MP4 format. This is necessary in particular if +there are resolution changes. +

+
+
segment_time_metadata
+

If set to 1, every packet will contain the lavf.concat.start_time and the +lavf.concat.duration packet metadata values which are the start_time and +the duration of the respective file segments in the concatenated output +expressed in microseconds. The duration metadata is only set if it is known +based on the concat file. +The default is 0. +

+
+
+ + +

3.5.3 Examples

+ +
    +
  • Use absolute filenames and include some comments: +
    +
    # my first filename
    +file /mnt/share/file-1.wav
    +# my second filename including whitespace
    +file '/mnt/share/file 2.wav'
    +# my third filename including whitespace plus single quote
    +file '/mnt/share/file 3'\''.wav'
    +
    + +
  • Allow for input format auto-probing, use safe filenames and set the duration of +the first file: +
    +
    ffconcat version 1.0
    +
    +file file-1.wav
    +duration 20.0
    +
    +file subdir/file-2.wav
    +
    +
+ + +

3.6 dash

+ +

Dynamic Adaptive Streaming over HTTP demuxer. +

+

This demuxer presents all AVStreams found in the manifest. +By setting the discard flags on AVStreams the caller can decide +which streams to actually receive. +Each stream mirrors the id and bandwidth properties from the +<Representation> as metadata keys named "id" and "variant_bitrate" respectively. +

+ +

3.6.1 Options

+ +

This demuxer accepts the following option: +

+
+
cenc_decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
cenc_decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
+ + +

3.7 dvdvideo

+ +

DVD-Video demuxer, powered by libdvdnav and libdvdread. +

+

Can directly ingest DVD titles, specifically sequential PGCs, into +a conversion pipeline. Menu assets, such as background video or audio, +can also be demuxed given the menu’s coordinates (at best effort). +

+

Block devices (DVD drives), ISO files, and directory structures are accepted. +Activate with -f dvdvideo in front of one of these inputs. +

+

This demuxer does NOT have decryption code of any kind. You are on your own +working with encrypted DVDs, and should not expect support on the matter. +

+

Underlying playback is handled by libdvdnav, and structure parsing by libdvdread. +FFmpeg must be built with GPL library support available as well as the +configure switches --enable-libdvdnav and --enable-libdvdread. +

+

You will need to provide either the desired "title number" or exact PGC/PG coordinates. +Many open-source DVD players and tools can aid in providing this information. +If not specified, the demuxer will default to title 1 which works for many discs. +However, due to the flexibility of the format, it is recommended to check manually. +There are many discs that are authored strangely or with invalid headers. +

+

If the input is a real DVD drive, please note that there are some drives which may +silently fail on reading bad sectors from the disc, returning random bits instead +which is effectively corrupt data. This is especially prominent on aging or rotting discs. +A second pass and integrity checks would be needed to detect the corruption. +This is not an FFmpeg issue. +

+ +

3.7.1 Background

+ +

DVD-Video is not a directly accessible, linear container format in the +traditional sense. Instead, it allows for complex and programmatic playback of +carefully muxed MPEG-PS streams that are stored in headerless VOB files. +To the end-user, these streams are known simply as "titles", but the actual +logical playback sequence is defined by one or more "PGCs", or Program Group Chains, +within the title. The PGC is in turn comprised of multiple "PGs", or Programs", +which are the actual video segments (and for a typical video feature, sequentially +ordered). The PGC structure, along with stream layout and metadata, are stored in +IFO files that need to be parsed. PGCs can be thought of as playlists in easier terms. +

+

An actual DVD player relies on user GUI interaction via menus and an internal VM +to drive the direction of demuxing. Generally, the user would either navigate (via menus) +or automatically be redirected to the PGC of their choice. During this process and +the subsequent playback, the DVD player’s internal VM also maintains a state and +executes instructions that can create jumps to different sectors during playback. +This is why libdvdnav is involved, as a linear read of the MPEG-PS blobs on the +disc (VOBs) is not enough to produce the right sequence in many cases. +

+

There are many other DVD structures (a long subject) that will not be discussed here. +NAV packets, in particular, are handled by this demuxer to build accurate timing +but not emitted as a stream. For a good high-level understanding, refer to: +https://code.videolan.org/videolan/libdvdnav/-/blob/master/doc/dvd_structures +

+ +

3.7.2 Options

+ +

This demuxer accepts the following options: +

+
+
title int
+

The title number to play. Must be set if pgc and pg are not set. +Not applicable to menus. +Default is 0 (auto), which currently only selects the first available title (title 1) +and notifies the user about the implications. +

+
+
chapter_start int
+

The chapter, or PTT (part-of-title), number to start at. Not applicable to menus. +Default is 1. +

+
+
chapter_end int
+

The chapter, or PTT (part-of-title), number to end at. Not applicable to menus. +Default is 0, which is a special value to signal end at the last possible chapter. +

+
+
angle int
+

The video angle number, referring to what is essentially an additional +video stream that is composed from alternate frames interleaved in the VOBs. +Not applicable to menus. +Default is 1. +

+
+
region int
+

The region code to use for playback. Some discs may use this to default playback +at a particular angle in different regions. This option will not affect the region code +of a real DVD drive, if used as an input. Not applicable to menus. +Default is 0, "world". +

+
+
menu bool
+

Demux menu assets instead of navigating a title. Requires exact coordinates +of the menu (menu_lu, menu_vts, pgc, pg). +Default is false. +

+
+
menu_lu int
+

The menu language to demux. In DVD, menus are grouped by language. +Default is 1, the first language unit. +

+
+
menu_vts int
+

The VTS where the menu lives, or 0 if it is a VMG menu (root-level). +Default is 1, menu of the first VTS. +

+
+
pgc int
+

The entry PGC to start playback, in conjunction with pg. +Alternative to setting title. +Chapter markers are not supported at this time. +Must be explicitly set for menus. +Default is 0, automatically resolve from value of title. +

+
+
pg int
+

The entry PG to start playback, in conjunction with pgc. +Alternative to setting title. +Chapter markers are not supported at this time. +Default is 1, the first PG of the PGC. +

+
+
preindex bool
+

Enable this to have accurate chapter (PTT) markers and duration measurement, +which requires a slow second pass read in order to index the chapter marker +timestamps from NAV packets. This is non-ideal extra work for real optical drives. +It is recommended and faster to use this option with a backup of the DVD structure +stored on a hard drive. Not compatible with pgc and pg. +Default is 0, false. +

+
+
trim bool
+

Skip padding cells (i.e. cells shorter than 1 second) from the beginning. +There exist many discs with filler segments at the beginning of the PGC, +often with junk data intended for controlling a real DVD player’s +buffering speed and with no other material data value. +Not applicable to menus. +Default is 1, true. +

+
+
+ + +

3.7.3 Examples

+ +
    +
  • Open title 3 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -title 3 -i <path to DVD> ...
    +
    + +
  • Open chapters 3-6 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 3 -chapter_end 6 -title 1 -i <path to DVD> ...
    +
    + +
  • Open only chapter 5 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 5 -chapter_end 5 -title 1 -i <path to DVD> ...
    +
    + +
  • Demux menu with language 1 from VTS 1, PGC 1, starting at PG 1: +
    +
    ffmpeg -f dvdvideo -menu 1 -menu_lu 1 -menu_vts 1 -pgc 1 -pg 1 -i <path to DVD> ...
    +
    +
+ + +

3.8 ea

+ +

Electronic Arts Multimedia format demuxer. +

+

This format is used by various Electronic Arts games. +

+ +

3.8.1 Options

+ +
+
merge_alpha bool
+
+

Normally the VP6 alpha channel (if exists) is returned as a secondary video +stream, by setting this option you can make the demuxer return a single video +stream which contains the alpha channel in addition to the ordinary video. +

+
+
+ + +

3.9 imf

+ +

Interoperable Master Format demuxer. +

+

This demuxer presents audio and video streams found in an IMF Composition, as +specified in SMPTE ST 2067-2. +

+
+
ffmpeg [-assetmaps <path of ASSETMAP1>,<path of ASSETMAP2>,...] -i <path of CPL> ...
+
+ +

If -assetmaps is not specified, the demuxer looks for a file called +ASSETMAP.xml in the same directory as the CPL. +

+ +

3.10 flv, live_flv, kux

+ +

Adobe Flash Video Format demuxer. +

+

This demuxer is used to demux FLV files and RTMP network streams. In case of live network streams, if you force format, you may use live_flv option instead of flv to survive timestamp discontinuities. +KUX is a flv variant used on the Youku platform. +

+
+
ffmpeg -f flv -i myfile.flv ...
+ffmpeg -f live_flv -i rtmp://<any.server>/anything/key ....
+
+ + +
+
-flv_metadata bool
+

Allocate the streams according to the onMetaData array content. +

+
+
-flv_ignore_prevtag bool
+

Ignore the size of previous tag value. +

+
+
-flv_full_metadata bool
+

Output all context of the onMetadata. +

+
+ + +

3.11 gif

+ +

Animated GIF demuxer. +

+

It accepts the following options: +

+
+
min_delay
+

Set the minimum valid delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 2. +

+
+
max_gif_delay
+

Set the maximum valid delay between frames in hundredth of seconds. +Range is 0 to 65535. Default value is 65535 (nearly eleven minutes), +the maximum value allowed by the specification. +

+
+
default_delay
+

Set the default delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 10. +

+
+
ignore_loop
+

GIF files can contain information to loop a certain number of times (or +infinitely). If ignore_loop is set to 1, then the loop setting +from the input will be ignored and looping will not occur. If set to 0, +then looping will occur and will cycle the number of times according to +the GIF. Default value is 1. +

+
+ +

For example, with the overlay filter, place an infinitely looping GIF +over another video: +

+
ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv
+
+ +

Note that in the above example the shortest option for overlay filter is +used to end the output video at the length of the shortest input file, +which in this case is input.mp4 as the GIF in this example loops +infinitely. +

+ +

3.12 hls

+ +

HLS demuxer +

+

Apple HTTP Live Streaming demuxer. +

+

This demuxer presents all AVStreams from all variant streams. +The id field is set to the bitrate variant index number. By setting +the discard flags on AVStreams (by pressing ’a’ or ’v’ in ffplay), +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". +

+

It accepts the following options: +

+
+
live_start_index
+

segment index to start live streams at (negative values are from the end). +

+
+
prefer_x_start
+

prefer to use #EXT-X-START if it’s in playlist instead of live_start_index. +

+
+
allowed_extensions
+

’,’ separated list of file extensions that hls is allowed to access. +

+
+
extension_picky
+

This blocks disallowed extensions from probing +It also requires all available segments to have matching extensions to the format +except mpegts, which is always allowed. +It is recommended to set the whitelists correctly instead of depending on extensions +Enabled by default. +

+
+
max_reload
+

Maximum number of times a insufficient list is attempted to be reloaded. +Default value is 1000. +

+
+
m3u8_hold_counters
+

The maximum number of times to load m3u8 when it refreshes without new segments. +Default value is 1000. +

+
+
http_persistent
+

Use persistent HTTP connections. Applicable only for HTTP streams. +Enabled by default. +

+
+
http_multiple
+

Use multiple HTTP connections for downloading HTTP segments. +Enabled by default for HTTP/1.1 servers. +

+
+
http_seekable
+

Use HTTP partial requests for downloading HTTP segments. +0 = disable, 1 = enable, -1 = auto, Default is auto. +

+
+
seg_format_options
+

Set options for the demuxer of media segments using a list of key=value pairs separated by :. +

+
+
seg_max_retry
+

Maximum number of times to reload a segment on error, useful when segment skip on network error is not desired. +Default value is 0. +

+
+ + +

3.13 image2

+ +

Image file demuxer. +

+

This demuxer reads from a list of image files specified by a pattern. +The syntax and meaning of the pattern is specified by the +option pattern_type. +

+

The pattern may contain a suffix which is used to automatically +determine the format of the images contained in the files. +

+

The size, the pixel format, and the format of each image must be the +same for all the files in the sequence. +

+

This demuxer accepts the following options: +

+
framerate
+

Set the frame rate for the video stream. It defaults to 25. +

+
loop
+

If set to 1, loop over the input. Default value is 0. +

+
pattern_type
+

Select the pattern type used to interpret the provided filename. +

+

pattern_type accepts one of the following values. +

+
none
+

Disable pattern matching, therefore the video will only contain the specified +image. You should use this option if you do not want to create sequences from +multiple images and your filenames may contain special pattern characters. +

+
sequence
+

Select a sequence pattern type, used to specify a sequence of files +indexed by sequential numbers. +

+

A sequence pattern may contain the string "%d" or "%0Nd", which +specifies the position of the characters representing a sequential +number in each filename matched by the pattern. If the form +"%d0Nd" is used, the string representing the number in each +filename is 0-padded and N is the total number of 0-padded +digits representing the number. The literal character ’%’ can be +specified in the pattern with the string "%%". +

+

If the sequence pattern contains "%d" or "%0Nd", the first filename of +the file list specified by the pattern must contain a number +inclusively contained between start_number and +start_number+start_number_range-1, and all the following +numbers must be sequential. +

+

For example the pattern "img-%03d.bmp" will match a sequence of +filenames of the form img-001.bmp, img-002.bmp, ..., +img-010.bmp, etc.; the pattern "i%%m%%g-%d.jpg" will match a +sequence of filenames of the form i%m%g-1.jpg, +i%m%g-2.jpg, ..., i%m%g-10.jpg, etc. +

+

Note that the pattern must not necessarily contain "%d" or +"%0Nd", for example to convert a single image file +img.jpeg you can employ the command: +

+
ffmpeg -i img.jpeg img.png
+
+ +
+
glob
+

Select a glob wildcard pattern type. +

+

The pattern is interpreted like a glob() pattern. This is only +selectable if libavformat was compiled with globbing support. +

+
+ +

Default value is sequence. +

+
pixel_format
+

Set the pixel format of the images to read. If not specified the pixel +format is guessed from the first image file in the sequence. +

+
start_number
+

Set the index of the file matched by the image file pattern to start +to read from. Default value is 0. +

+
start_number_range
+

Set the index interval range to check when looking for the first image +file in the sequence, starting from start_number. Default value +is 5. +

+
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. +If set to 2, will set frame timestamp to the modification time of the image file in +nanosecond precision. +

+
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. +

+
export_path_metadata
+

If set to 1, will add two extra fields to the metadata found in input, making them +also available for other filters (see drawtext filter for examples). Default +value is 0. The extra fields are described below: +

+
lavf.image2dec.source_path
+

Corresponds to the full path to the input file being read. +

+
lavf.image2dec.source_basename
+

Corresponds to the name of the file being read. +

+
+ +
+
+ + +

3.13.1 Examples

+ +
    +
  • Use ffmpeg for creating a video from the images in the file +sequence img-001.jpeg, img-002.jpeg, ..., assuming an +input frame rate of 10 frames per second: +
    +
    ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • As above, but start by reading from a file with index 100 in the sequence: +
    +
    ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • Read images matching the "*.png" glob pattern , that is all the files +terminating with the ".png" suffix: +
    +
    ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv
    +
    +
+ + +

3.14 libgme

+ +

The Game Music Emu library is a collection of video game music file emulators. +

+

See https://bitbucket.org/mpyne/game-music-emu/overview for more information. +

+

It accepts the following options: +

+
+
track_index
+

Set the index of which track to demux. The demuxer can only export one track. +Track indexes start at 0. Default is to pick the first track. Number of tracks +is exported as tracks metadata entry. +

+
+
sample_rate
+

Set the sampling rate of the exported track. Range is 1000 to 999999. Default is 44100. +

+
+
max_size (bytes)
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. +Default is 50 MiB. +

+
+
+ + +

3.15 libmodplug

+ +

ModPlug based module demuxer +

+

See https://github.com/Konstanty/libmodplug +

+

It will export one 2-channel 16-bit 44.1 kHz audio stream. +Optionally, a pal8 16-color video stream can be exported with or without printed metadata. +

+

It accepts the following options: +

+
+
noise_reduction
+

Apply a simple low-pass filter. Can be 1 (on) or 0 (off). Default is 0. +

+
+
reverb_depth
+

Set amount of reverb. Range 0-100. Default is 0. +

+
+
reverb_delay
+

Set delay in ms, clamped to 40-250 ms. Default is 0. +

+
+
bass_amount
+

Apply bass expansion a.k.a. XBass or megabass. Range is 0 (quiet) to 100 (loud). Default is 0. +

+
+
bass_range
+

Set cutoff i.e. upper-bound for bass frequencies. Range is 10-100 Hz. Default is 0. +

+
+
surround_depth
+

Apply a Dolby Pro-Logic surround effect. Range is 0 (quiet) to 100 (heavy). Default is 0. +

+
+
surround_delay
+

Set surround delay in ms, clamped to 5-40 ms. Default is 0. +

+
+
max_size
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. Range is 0 to 100 MiB. +0 removes buffer size limit (not recommended). Default is 5 MiB. +

+
+
video_stream_expr
+

String which is evaluated using the eval API to assign colors to the generated video stream. +Variables which can be used are x, y, w, h, t, speed, +tempo, order, pattern and row. +

+
+
video_stream
+

Generate video stream. Can be 1 (on) or 0 (off). Default is 0. +

+
+
video_stream_w
+

Set video frame width in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_h
+

Set video frame height in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_ptxt
+

Print metadata on video stream. Includes speed, tempo, order, pattern, +row and ts (time in ms). Can be 1 (on) or 0 (off). Default is 1. +

+
+
+ + +

3.16 libopenmpt

+ +

libopenmpt based module demuxer +

+

See https://lib.openmpt.org/libopenmpt/ for more information. +

+

Some files have multiple subsongs (tracks) this can be set with the subsong +option. +

+

It accepts the following options: +

+
+
subsong
+

Set the subsong index. This can be either ’all’, ’auto’, or the index of the +subsong. Subsong indexes start at 0. The default is ’auto’. +

+

The default value is to let libopenmpt choose. +

+
+
layout
+

Set the channel layout. Valid values are 1, 2, and 4 channel layouts. +The default value is STEREO. +

+
+
sample_rate
+

Set the sample rate for libopenmpt to output. +Range is from 1000 to INT_MAX. The value default is 48000. +

+
+ + +

3.17 mcc

+ +

Demuxer for MacCaption MCC files, it supports MCC versions 1.0 and 2.0. +MCC files store VANC data, which can include closed captions (EIA-608 and CEA-708), ancillary time code, pan-scan data, etc. +By default, for backward compatibility, the MCC demuxer extracts just the EIA-608 and CEA-708 closed captions and returns a EIA_608 stream, ignoring all other VANC data. +You can change it to return all VANC data in a SMPTE_436M_ANC data stream by setting -eia608_extract 0 +

+ +

3.17.1 Examples

+ +
    +
  • Convert a MCC file to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.mcc -c:s copy CC.scc
    +
    +

    Note that the SCC format only supports EIA-608, so this will discard all other data such as CEA-708 extensions. +

    +
  • Merge a MCC file into a MXF file: +
    +
    ffmpeg -i video_and_audio.mxf -eia608_extract 0 -i CC.mcc -c copy -map 0 -map 1 out.mxf
    +
    +

    This retains all VANC data and inserts it into the output MXF file as a SMPTE_436M_ANC data stream. +

+ + +

3.18 mov/mp4/3gp

+ +

Demuxer for Quicktime File Format & ISO/IEC Base Media File Format (ISO/IEC 14496-12 or MPEG-4 Part 12, ISO/IEC 15444-12 or JPEG 2000 Part 12). +

+

Registered extensions: mov, mp4, m4a, 3gp, 3g2, mj2, psp, m4b, ism, ismv, isma, f4v +

+ +

3.18.1 Options

+ +

This demuxer accepts the following options: +

+
enable_drefs
+

Enable loading of external tracks, disabled by default. +Enabling this can theoretically leak information in some use cases. +

+
+
use_absolute_path
+

Allows loading of external tracks via absolute paths, disabled by default. +Enabling this poses a security risk. It should only be enabled if the source +is known to be non-malicious. +

+
+
seek_streams_individually
+

When seeking, identify the closest point in each stream individually and demux packets in +that stream from identified point. This can lead to a different sequence of packets compared +to demuxing linearly from the beginning. Default is true. +

+
+
ignore_editlist
+

Ignore any edit list atoms. The demuxer, by default, modifies the stream index to reflect the +timeline described by the edit list. Default is false. +

+
+
advanced_editlist
+

Modify the stream index to reflect the timeline described by the edit list. ignore_editlist +must be set to false for this option to be effective. +If both ignore_editlist and this option are set to false, then only the +start of the stream index is modified to reflect initial dwell time or starting timestamp +described by the edit list. Default is true. +

+
+
ignore_chapters
+

Don’t parse chapters. This includes GoPro ’HiLight’ tags/moments. Note that chapters are +only parsed when input is seekable. Default is false. +

+
+
use_mfra_for
+

For seekable fragmented input, set fragment’s starting timestamp from media fragment random access box, if present. +

+

Following options are available: +

+
‘auto’
+

Auto-detect whether to set mfra timestamps as PTS or DTS (default) +

+
+
‘dts’
+

Set mfra timestamps as DTS +

+
+
‘pts’
+

Set mfra timestamps as PTS +

+
+
‘0’
+

Don’t use mfra box to set timestamps +

+
+ +
+
use_tfdt
+

For fragmented input, set fragment’s starting timestamp to baseMediaDecodeTime from the tfdt box. +Default is enabled, which will prefer to use the tfdt box to set DTS. Disable to use the earliest_presentation_time from the sidx box. +In either case, the timestamp from the mfra box will be used if it’s available and use_mfra_for is +set to pts or dts. +

+
+
export_all
+

Export unrecognized boxes within the udta box as metadata entries. The first four +characters of the box type are set as the key. Default is false. +

+
+
export_xmp
+

Export entire contents of XMP_ box and uuid box as a string with key xmp. Note that +if export_all is set and this option isn’t, the contents of XMP_ box are still exported +but with key XMP_. Default is false. +

+
+
activation_bytes
+

4-byte key required to decrypt Audible AAX and AAX+ files. See Audible AAX subsection below. +

+
+
audible_fixed_key
+

Fixed key used for handling Audible AAX/AAX+ files. It has been pre-set so should not be necessary to +specify. +

+
+
decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
max_stts_delta
+

Very high sample deltas written in a trak’s stts box may occasionally be intended but usually they are written in +error or used to store a negative value for dts correction when treated as signed 32-bit integers. This option lets +the user set an upper limit, beyond which the delta is clamped to 1. Values greater than the limit if negative when +cast to int32 are used to adjust onward dts. +

+

Unit is the track time scale. Range is 0 to UINT_MAX. Default is UINT_MAX - 48000*10 which allows up to +a 10 second dts correction for 48 kHz audio streams while accommodating 99.9% of uint32 range. +

+
+
interleaved_read
+

Interleave packets from multiple tracks at demuxer level. For badly interleaved files, this prevents playback issues +caused by large gaps between packets in different tracks, as MOV/MP4 do not have packet placement requirements. +However, this can cause excessive seeking on very badly interleaved files, due to seeking between tracks, so disabling +it may prevent I/O issues, at the expense of playback. +

+
+
+ + +

3.18.2 Audible AAX

+ +

Audible AAX files are encrypted M4B files, and they can be decrypted by specifying a 4 byte activation secret. +

+
ffmpeg -activation_bytes 1CEB00DA -i test.aax -vn -c:a copy output.mp4
+
+ + +

3.19 mpegts

+ +

MPEG-2 transport stream demuxer. +

+

This demuxer accepts the following options: +

+
resync_size
+

Set size limit for looking up a new synchronization. Default value is +65536. +

+
+
skip_unknown_pmt
+

Skip PMTs for programs not defined in the PAT. Default value is 0. +

+
+
fix_teletext_pts
+

Override 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. +

+
+
ts_packetsize
+

Output option carrying the raw packet size in bytes. +Show the detected raw packet size, cannot be set by the user. +

+
+
scan_all_pmts
+

Scan and combine all PMTs. The value is an integer with value from -1 +to 1 (-1 means automatic setting, 1 means enabled, 0 means +disabled). Default value is -1. +

+
+
merge_pmt_versions
+

Reuse existing streams when a PMT’s version is updated and elementary +streams move to different PIDs. Default value is 0. +

+
+
max_packet_size
+

Set maximum size, in bytes, of packet emitted by the demuxer. Payloads above this size +are split across multiple packets. Range is 1 to INT_MAX/2. Default is 204800 bytes. +

+
+ + +

3.20 mpjpeg

+ +

MJPEG encapsulated in multi-part MIME demuxer. +

+

This demuxer allows reading of MJPEG, where each frame is represented as a part of +multipart/x-mixed-replace stream. +

+
strict_mime_boundary
+

Default implementation applies a relaxed standard to multi-part MIME boundary detection, +to prevent regression with numerous existing endpoints not generating a proper MIME +MJPEG stream. Turning this option on by setting it to 1 will result in a stricter check +of the boundary value. +

+
+ + +

3.21 rawvideo

+ +

Raw video demuxer. +

+

This demuxer allows one to read raw video data. Since there is no header +specifying the assumed video parameters, the user must specify them +in order to be able to decode the data correctly. +

+

This demuxer accepts the following options: +

+
framerate
+

Set input video frame rate. Default value is 25. +

+
+
pixel_format
+

Set the input video pixel format. Default value is yuv420p. +

+
+
stride
+

Set frame line size in bytes, only required if there are extra padding. +For multiplane formats, stride is a list of line size for each +plane. +

+
+
video_size
+

Set the input video size. This value must be specified explicitly. +

+
+ +

For example to read a rawvideo file input.raw with +ffplay, assuming a pixel format of rgb24, a video +size of 320x240, and a frame rate of 10 images per second, use +the command: +

+
ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw
+
+ +

Read a rawvideo with ffplay, assuming a pixel format of yuv420p, +a video size of 1080x1920, has 8 bytes of padding in each line of Y plane, +and 4 bytes of padding with UV plane, +

+
ffplay -f rawvideo -pixel_format yuv420p -video_size 1080x1920 -stride 1088,544,544 input.raw
+
+ + +

3.22 rcwt

+ +

RCWT (Raw Captions With Time) is a format native to ccextractor, a commonly +used open source tool for processing 608/708 Closed Captions (CC) sources. +For more information on the format, see (ffmpeg-formats)rcwtenc. +

+

This demuxer implements the specification as of March 2024, which has +been stable and unchanged since April 2014. +

+ +

3.22.1 Examples

+ +
    +
  • Render CC to ASS using the built-in decoder: +
    +
    ffmpeg -i CC.rcwt.bin CC.ass
    +
    +

    Note that if your output appears to be empty, you may have to manually +set the decoder’s data_field option to pick the desired CC substream. +

    +
  • Convert an RCWT backup to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.rcwt.bin -c:s copy CC.scc
    +
    +

    Note that the SCC format does not support all of the possible CC extensions +that can be stored in RCWT (such as EIA-708). +

+ + +

3.23 sbg

+ +

SBaGen script demuxer. +

+

This demuxer reads the script language used by SBaGen +http://uazu.net/sbagen/ to generate binaural beats sessions. A SBG +script looks like that: +

+
-SE
+a: 300-2.5/3 440+4.5/0
+b: 300-2.5/0 440+4.5/3
+off: -
+NOW      == a
++0:07:00 == b
++0:14:00 == a
++0:21:00 == b
++0:30:00    off
+
+ +

A SBG script can mix absolute and relative timestamps. If the script uses +either only absolute timestamps (including the script start time) or only +relative ones, then its layout is fixed, and the conversion is +straightforward. On the other hand, if the script mixes both kind of +timestamps, then the NOW reference for relative timestamps will be +taken from the current time of day at the time the script is read, and the +script layout will be frozen according to that reference. That means that if +the script is directly played, the actual times will match the absolute +timestamps up to the sound controller’s clock accuracy, but if the user +somehow pauses the playback or seeks, all times will be shifted accordingly. +

+ +

3.24 tedcaptions

+ +

JSON captions used for TED Talks. +

+

TED does not provide links to the captions, but they can be guessed from the +page. The file tools/bookmarklets.html from the FFmpeg source tree +contains a bookmarklet to expose them. +

+

This demuxer accepts the following option: +

+
start_time
+

Set the start time of the TED talk, in milliseconds. The default is 15000 +(15s). It is used to sync the captions with the downloadable videos, because +they include a 15s intro. +

+
+ +

Example: convert the captions to a format most players understand: +

+
ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt
+
+ + +

3.25 vapoursynth

+ +

Vapoursynth wrapper. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+

This demuxer accepts the following option: +

+
max_script_size
+

The demuxer buffers the entire script into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of scripts that can be read. +Default is 1 MiB. +

+
+ + +

3.26 w64

+ +

Sony Wave64 Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

See the same option for the wav demuxer. +

+
+ + +

3.27 wav

+ +

RIFF Wave Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

Specify the maximum packet size in bytes for the demuxed packets. By default +this is set to 0, which means that a sensible value is chosen based on the +input format. +

+
+ + +

4 Muxers

+ +

Muxers are configured elements in FFmpeg which allow writing +multimedia streams to a particular type of file. +

+

When you configure your FFmpeg build, all the supported muxers +are enabled by default. You can list all available muxers using the +configure option --list-muxers. +

+

You can disable all the muxers with the configure option +--disable-muxers and selectively enable / disable single muxers +with the options --enable-muxer=MUXER / +--disable-muxer=MUXER. +

+

The option -muxers of the ff* tools will display the list of +enabled muxers. Use -formats to view a combined list of +enabled demuxers and muxers. +

+

A description of some of the currently available muxers follows. +

+ +

4.1 Raw muxers

+ +

This section covers raw muxers. They accept a single stream matching +the designated codec. They do not store timestamps or metadata. The +recognized extension is the same as the muxer name unless indicated +otherwise. +

+

It comprises the following muxers. The media type and the eventual +extensions used to automatically selects the muxer from the output +extensions are also shown. +

+
+
‘ac3 audio’
+

Dolby Digital, also known as AC-3. +

+
+
‘adx audio’
+

CRI Middleware ADX audio. +

+

This muxer will write out the total sample count near the start of the +first packet when the output is seekable and the count can be stored +in 32 bits. +

+
+
‘aptx audio’
+

aptX (Audio Processing Technology for Bluetooth) +

+
+
‘aptx_hd audio (aptxdh)’
+

aptX HD (Audio Processing Technology for Bluetooth) audio +

+
+
‘avs2 video (avs, avs2)’
+

AVS2-P2 (Audio Video Standard - Second generation - Part 2) / +IEEE 1857.4 video +

+
+
‘avs3 video (avs3)’
+

AVS3-P2 (Audio Video Standard - Third generation - Part 2) / +IEEE 1857.10 video +

+
+
‘cavsvideo video (cavs)’
+

Chinese AVS (Audio Video Standard - First generation) +

+
+
‘codec2raw audio’
+

Codec 2 audio. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f codec2raw. +

+
+
‘data any’
+

Generic data muxer. +

+

This muxer accepts a single stream with any codec of any type. The +input stream has to be selected using the -map option with the +ffmpeg CLI tool. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f data. +

+
+
‘dfpwm audio (dfpwm)’
+

Raw DFPWM1a (Dynamic Filter Pulse With Modulation) audio muxer. +

+
+
‘dirac video (drc, vc2)’
+

BBC Dirac video. +

+

The Dirac Pro codec is a subset and is standardized as SMPTE VC-2. +

+
+
‘dnxhd video (dnxhd, dnxhr)’
+

Avid DNxHD video. +

+

It is standardized as SMPTE VC-3. Accepts DNxHR streams. +

+
+
‘dts audio’
+

DTS Coherent Acoustics (DCA) audio +

+
+
‘eac3 audio’
+

Dolby Digital Plus, also known as Enhanced AC-3 +

+
+
‘evc video (evc)’
+

MPEG-5 Essential Video Coding (EVC) / EVC / MPEG-5 Part 1 EVC video +

+
+
‘g722 audio’
+

ITU-T G.722 audio +

+
+
‘g723_1 audio (tco, rco)’
+

ITU-T G.723.1 audio +

+
+
‘g726 audio’
+

ITU-T G.726 big-endian ("left-justified") audio. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f g726. +

+
+
‘g726le audio’
+

ITU-T G.726 little-endian ("right-justified") audio. +

+

No extension is registered so format name has to be supplied e.g. with +the ffmpeg CLI tool -f g726le. +

+
+
‘gsm audio’
+

Global System for Mobile Communications audio +

+
+
‘h261 video’
+

ITU-T H.261 video +

+
+
‘h263 video’
+

ITU-T H.263 / H.263-1996, H.263+ / H.263-1998 / H.263 version 2 video +

+
+
‘h264 video (h264, 264)’
+

ITU-T H.264 / MPEG-4 Part 10 AVC video. Bitstream shall be converted +to Annex B syntax if it’s in length-prefixed mode. +

+
+
‘hevc video (hevc, h265, 265)’
+

ITU-T H.265 / MPEG-H Part 2 HEVC video. Bitstream shall be converted +to Annex B syntax if it’s in length-prefixed mode. +

+
+
‘m4v video’
+

MPEG-4 Part 2 video +

+
+
‘mjpeg video (mjpg, mjpeg)’
+

Motion JPEG video +

+
+
‘mlp audio’
+

Meridian Lossless Packing, also known as Packed PCM +

+
+
‘mp2 audio (mp2, m2a, mpa)’
+

MPEG-1 Audio Layer II audio +

+
+
‘mpeg1video video (mpg, mpeg, m1v)’
+

MPEG-1 Part 2 video. +

+
+
‘mpeg2video video (m2v)’
+

ITU-T H.262 / MPEG-2 Part 2 video +

+
+
‘obu video’
+

AV1 low overhead Open Bitstream Units muxer. +

+

Temporal delimiter OBUs will be inserted in all temporal units of the +stream. +

+
+
‘rawvideo video (yuv, rgb)’
+

Raw uncompressed video. +

+
+
‘sbc audio (sbc, msbc)’
+

Bluetooth SIG low-complexity subband codec audio +

+
+
‘truehd audio (thd)’
+

Dolby TrueHD audio +

+
+
‘vc1 video’
+

SMPTE 421M / VC-1 video +

+
+ + +

4.1.1 Examples

+ +
    +
  • Store raw video frames with the ‘rawvideo’ muxer using ffmpeg: +
    +
    ffmpeg -f lavfi -i testsrc -t 10 -s hd1080p testsrc.yuv
    +
    + +

    Since the rawvideo muxer do not store the information related to size +and format, this information must be provided when demuxing the file: +

    +
    ffplay -video_size 1920x1080 -pixel_format rgb24 -f rawvideo testsrc.rgb
    +
    +
+ + +

4.2 Raw PCM muxers

+

This section covers raw PCM (Pulse-Code Modulation) audio muxers. +

+

They accept a single stream matching the designated codec. They do not +store timestamps or metadata. The recognized extension is the same as +the muxer name. +

+

It comprises the following muxers. The optional additional extension +used to automatically select the muxer from the output extension is +also shown in parentheses. +

+
+
‘alaw (al)’
+

PCM A-law +

+
+
‘f32be’
+

PCM 32-bit floating-point big-endian +

+
+
‘f32le’
+

PCM 32-bit floating-point little-endian +

+
+
‘f64be’
+

PCM 64-bit floating-point big-endian +

+
+
‘f64le’
+

PCM 64-bit floating-point little-endian +

+
+
‘mulaw (ul)’
+

PCM mu-law +

+
+
‘s16be’
+

PCM signed 16-bit big-endian +

+
+
‘s16le’
+

PCM signed 16-bit little-endian +

+
+
‘s24be’
+

PCM signed 24-bit big-endian +

+
+
‘s24le’
+

PCM signed 24-bit little-endian +

+
+
‘s32be’
+

PCM signed 32-bit big-endian +

+
+
‘s32le’
+

PCM signed 32-bit little-endian +

+
+
‘s8 (sb)’
+

PCM signed 8-bit +

+
+
‘u16be’
+

PCM unsigned 16-bit big-endian +

+
+
‘u16le’
+

PCM unsigned 16-bit little-endian +

+
+
‘u24be’
+

PCM unsigned 24-bit big-endian +

+
+
‘u24le’
+

PCM unsigned 24-bit little-endian +

+
+
‘u32be’
+

PCM unsigned 32-bit big-endian +

+
+
‘u32le’
+

PCM unsigned 32-bit little-endian +

+
+
‘u8 (ub)’
+

PCM unsigned 8-bit +

+
+
‘vidc’
+

PCM Archimedes VIDC +

+
+ + +

4.3 MPEG-1/MPEG-2 program stream muxers

+ +

This section covers formats belonging to the MPEG-1 and MPEG-2 Systems +family. +

+

The MPEG-1 Systems format (also known as ISO/IEEC 11172-1 or MPEG-1 +program stream) has been adopted for the format of media track stored +in VCD (Video Compact Disc). +

+

The MPEG-2 Systems standard (also known as ISO/IEEC 13818-1) covers +two containers formats, one known as transport stream and one known as +program stream; only the latter is covered here. +

+

The MPEG-2 program stream format (also known as VOB due to the +corresponding file extension) is an extension of MPEG-1 program +stream: in addition to support different codecs for the audio and +video streams, it also stores subtitles and navigation metadata. +MPEG-2 program stream has been adopted for storing media streams in +SVCD and DVD storage devices. +

+

This section comprises the following muxers. +

+
+
‘mpeg (mpg,mpeg)’
+

MPEG-1 Systems / MPEG-1 program stream muxer. +

+
+
‘vcd’
+

MPEG-1 Systems / MPEG-1 program stream (VCD) muxer. +

+

This muxer can be used to generate tracks in the format accepted by +the VCD (Video Compact Disc) storage devices. +

+

It is the same as the ‘mpeg’ muxer with a few differences. +

+
+
‘vob’
+

MPEG-2 program stream (VOB) muxer. +

+
+
‘dvd’
+

MPEG-2 program stream (DVD VOB) muxer. +

+

This muxer can be used to generate tracks in the format accepted by +the DVD (Digital Versatile Disc) storage devices. +

+

This is the same as the ‘vob’ muxer with a few differences. +

+
+
‘svcd (vob)’
+

MPEG-2 program stream (SVCD VOB) muxer. +

+

This muxer can be used to generate tracks in the format accepted by +the SVCD (Super Video Compact Disc) storage devices. +

+

This is the same as the ‘vob’ muxer with a few differences. +

+
+ + +

4.3.1 Options

+
+
muxrate rate
+

Set user-defined mux rate expressed as a number of bits/s. If not +specified the automatically computed mux rate is employed. Default value +is 0. +

+
+
preload delay
+

Set initial demux-decode delay in microseconds. Default value is +500000. +

+
+ + +

4.4 MOV/MPEG-4/ISOMBFF muxers

+ +

This section covers formats belonging to the QuickTime / MOV family, +including the MPEG-4 Part 14 format and ISO base media file format +(ISOBMFF). These formats share a common structure based on the ISO +base media file format (ISOBMFF). +

+

The MOV format was originally developed for use with Apple QuickTime. +It was later used as the basis for the MPEG-4 Part 1 (later Part 14) +format, also known as ISO/IEC 14496-1. That format was then +generalized into ISOBMFF, also named MPEG-4 Part 12 format, ISO/IEC +14496-12, or ISO/IEC 15444-12. +

+

It comprises the following muxers. +

+
+
‘3gp’
+

Third Generation Partnership Project (3GPP) format for 3G UMTS +multimedia services +

+
+
‘3g2’
+

Third Generation Partnership Project 2 (3GP2 or 3GPP2) format for 3G +CDMA2000 multimedia services, similar to ‘3gp’ with extensions +and limitations +

+
+
‘f4v’
+

Adobe Flash Video format +

+
+
‘ipod’
+

MPEG-4 audio file format, as MOV/MP4 but limited to contain only audio +streams, typically played with the Apple ipod device +

+
+
‘ismv’
+

Microsoft IIS (Internet Information Services) Smooth Streaming +Audio/Video (ISMV or ISMA) format. This is based on MPEG-4 Part 14 +format with a few incompatible variants, used to stream media files +for the Microsoft IIS server. +

+
+
‘mov’
+

QuickTime player format identified by the .mov extension +

+
+
‘mp4’
+

MP4 or MPEG-4 Part 14 format +

+
+
‘psp’
+

PlayStation Portable MP4/MPEG-4 Part 14 format variant. This is based +on MPEG-4 Part 14 format with a few incompatible variants, used to +play files on PlayStation devices. +

+
+ + +

4.4.1 Fragmentation

+ +

The ‘mov’, ‘mp4’, and ‘ismv’ muxers support +fragmentation. Normally, a MOV/MP4 file has all the metadata about all +packets stored in one location. +

+

This data is usually written at the end of the file, but it can be +moved to the start for better playback by adding +faststart to +the -movflags, or using the qt-faststart tool). +

+

A fragmented file consists of a number of fragments, where packets and +metadata about these packets are stored together. Writing a fragmented +file has the advantage that the file is decodable even if the writing +is interrupted (while a normal MOV/MP4 is undecodable if it is not +properly finished), and it requires less memory when writing very long +files (since writing normal MOV/MP4 files stores info about every +single packet in memory until the file is closed). The downside is +that it is less compatible with other applications. +

+

Fragmentation is enabled by setting one of the options that define +how to cut the file into fragments: +

+
frag_duration
+
frag_size
+
min_frag_duration
+
movflags +frag_keyframe
+
movflags +frag_custom
+
+ +

If more than one condition is specified, fragments are cut when one of +the specified conditions is fulfilled. The exception to this is the +option min_frag_duration, which has to be fulfilled for any +of the other conditions to apply. +

+ +

4.4.2 Options

+ +
+
brand brand_string
+

Override major brand. +

+
+
empty_hdlr_name bool
+

Enable to skip writing the name inside a hdlr box. +Default is false. +

+
+
encryption_key key
+

set the media encryption key in hexadecimal format +

+
+
encryption_kid kid
+

set the media encryption key identifier in hexadecimal format +

+
+
encryption_scheme scheme
+

configure the encryption scheme, allowed values are ‘none’, and +‘cenc-aes-ctr’ +

+
+
frag_duration duration
+

Create fragments that are duration microseconds long. +

+
+
frag_interleave number
+

Interleave samples within fragments (max number of consecutive +samples, lower is tighter interleaving, but with more overhead. It is +set to 0 by default. +

+
+
frag_size size
+

create fragments that contain up to size bytes of payload data +

+
+
iods_audio_profile profile
+

specify iods number for the audio profile atom (from -1 to 255), +default is -1 +

+
+
iods_video_profile profile
+

specify iods number for the video profile atom (from -1 to 255), +default is -1 +

+
+
ism_lookahead num_entries
+

specify number of lookahead entries for ISM files (from 0 to 255), +default is 0 +

+
+
min_frag_duration duration
+

do not create fragments that are shorter than duration microseconds long +

+
+
moov_size bytes
+

Reserves space for the moov atom at the beginning of the file instead of placing the +moov atom at the end. If the space reserved is insufficient, muxing will fail. +

+
+
mov_gamma gamma
+

specify gamma value for gama atom (as a decimal number from 0 to 10), +default is 0.0, must be set together with + movflags +

+
+
movflags flags
+

Set various muxing switches. The following flags can be used: +

+
‘cmaf’
+

write CMAF (Common Media Application Format) compatible fragmented +MP4 output +

+
+
‘dash’
+

write DASH (Dynamic Adaptive Streaming over HTTP) compatible fragmented +MP4 output +

+
+
‘default_base_moof’
+

Similarly to the ‘omit_tfhd_offset’ flag, this flag avoids +writing the absolute base_data_offset field in tfhd atoms, but does so +by using the new default-base-is-moof flag instead. This flag is new +from 14496-12:2012. This may make the fragments easier to parse in +certain circumstances (avoiding basing track fragment location +calculations on the implicit end of the previous track fragment). +

+
+
‘delay_moov’
+

delay writing the initial moov until the first fragment is cut, or +until the first fragment flush +

+
+
‘disable_chpl’
+

Disable Nero chapter markers (chpl atom). Normally, both Nero chapters +and a QuickTime chapter track are written to the file. With this +option set, only the QuickTime chapter track will be written. Nero +chapters can cause failures when the file is reprocessed with certain +tagging programs, like mp3Tag 2.61a and iTunes 11.3, most likely other +versions are affected as well. +

+
+
‘faststart’
+

Run a second pass moving the index (moov atom) to the beginning of the +file. This operation can take a while, and will not work in various +situations such as fragmented output, thus it is not enabled by +default. +

+
+
‘frag_custom’
+

Allow the caller to manually choose when to cut fragments, by calling +av_write_frame(ctx, NULL) to write a fragment with the packets +written so far. (This is only useful with other applications +integrating libavformat, not from ffmpeg.) +

+
+
‘frag_discont’
+

signal that the next fragment is discontinuous from earlier ones +

+
+
‘frag_every_frame’
+

fragment at every frame +

+
+
‘frag_keyframe’
+

start a new fragment at each video keyframe +

+
+
‘global_sidx’
+

write a global sidx index at the start of the file +

+
+
‘isml’
+

create a live smooth streaming feed (for pushing to a publishing point) +

+
+
‘negative_cts_offsets’
+

Enables utilization of version 1 of the CTTS box, in which the CTS offsets can +be negative. This enables the initial sample to have DTS/CTS of zero, and +reduces the need for edit lists for some cases such as video tracks with +B-frames. Additionally, eases conformance with the DASH-IF interoperability +guidelines. +

+

This option is implicitly set when writing ‘ismv’ (Smooth +Streaming) files. +

+
+
‘omit_tfhd_offset’
+

Do not write any absolute base_data_offset in tfhd atoms. This avoids +tying fragments to absolute byte positions in the file/streams. +

+
+
‘prefer_icc’
+

If writing colr atom prioritise usage of ICC profile if it exists in +stream packet side data. +

+
+
‘rtphint’
+

add RTP hinting tracks to the output file +

+
+
‘separate_moof’
+

Write a separate moof (movie fragment) atom for each track. Normally, +packets for all tracks are written in a moof atom (which is slightly +more efficient), but with this option set, the muxer writes one +moof/mdat pair for each track, making it easier to separate tracks. +

+
+
‘skip_sidx’
+

Skip writing of sidx atom. When bitrate overhead due to sidx atom is +high, this option could be used for cases where sidx atom is not +mandatory. When the ‘global_sidx’ flag is enabled, this option +is ignored. +

+
+
‘skip_trailer’
+

skip writing the mfra/tfra/mfro trailer for fragmented files +

+
+
‘use_metadata_tags’
+

use mdta atom for metadata +

+
+
‘write_colr’
+

write colr atom even if the color info is unspecified. This flag is +experimental, may be renamed or changed, do not use from scripts. +

+
+
‘write_gama’
+

write deprecated gama atom +

+
+
‘hybrid_fragmented’
+

For recoverability - write the output file as a fragmented file. +This allows the intermediate file to be read while being written +(in particular, if the writing process is aborted uncleanly). When +writing is finished, the file is converted to a regular, non-fragmented +file, which is more compatible and allows easier and quicker seeking. +

+

If writing is aborted, the intermediate file can manually be +remuxed to get a regular, non-fragmented file of what had been +written into the unfinished file. +

+
+ +
+
movie_timescale scale
+

Set the timescale written in the movie header box (mvhd). +Range is 1 to INT_MAX. Default is 1000. +

+
+
rtpflags flags
+

Add RTP hinting tracks to the output file. +

+

The following flags can be used: +

+
‘h264_mode0’
+

use mode 0 for H.264 in RTP +

+
+
‘latm’
+

use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC +

+
+
‘rfc2190’
+

use RFC 2190 packetization instead of RFC 4629 for H.263 +

+
+
‘send_bye’
+

send RTCP BYE packets when finishing +

+
+
‘skip_rtcp’
+

do not send RTCP sender reports +

+
+ +
+
skip_iods bool
+

skip writing iods atom (default value is true) +

+
+
use_editlist bool
+

use edit list (default value is auto) +

+
+
use_stream_ids_as_track_ids bool
+

use stream ids as track ids (default value is false) +

+
+
video_track_timescale scale
+

Set the timescale used for video tracks. Range is 0 to INT_MAX. If +set to 0, the timescale is automatically set based on the +native stream time base. Default is 0. +

+
+
write_btrt bool
+

Force or disable writing bitrate box inside stsd box of a track. The +box contains decoding buffer size (in bytes), maximum bitrate and +average bitrate for the track. The box will be skipped if none of +these values can be computed. Default is -1 or auto, +which will write the box only in MP4 mode. +

+
+
write_prft option
+

Write producer time reference box (PRFT) with a specified time source for the +NTP field in the PRFT box. Set value as ‘wallclock’ to specify timesource +as wallclock time and ‘pts’ to specify timesource as input packets’ PTS +values. +

+
+
write_tmcd bool
+

Specify on to force writing a timecode track, off to disable it +and auto to write a timecode track only for mov and mp4 output (default). +

+

Setting value to ‘pts’ is applicable only for a live encoding use case, +where PTS values are set as as wallclock time at the source. For example, an +encoding use case with decklink capture source where video_pts and +audio_pts are set to ‘abs_wallclock’. +

+
+ + +

4.4.3 Examples

+ +
    +
  • Push Smooth Streaming content in real time to a publishing point on +IIS with the ‘ismv’ muxer using ffmpeg: +
    +
    ffmpeg -re <normal input/transcoding options> -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
    +
    +
+ + +

4.5 a64

+

A64 Commodore 64 video muxer. +

+

This muxer accepts a single a64_multi or a64_multi5 +codec video stream. +

+ +

4.6 ac4

+

Raw AC-4 audio muxer. +

+

This muxer accepts a single ac4 audio stream. +

+ +

4.6.1 Options

+
+
write_crc bool
+

when enabled, write a CRC checksum for each packet to the output, +default is false +

+
+ + +

4.7 adts

+

Audio Data Transport Stream muxer. +

+

It accepts a single AAC stream. +

+ +

4.7.1 Options

+
+
write_id3v2 bool
+

Enable to write ID3v2.4 tags at the start of the stream. Default is +disabled. +

+
+
write_apetag bool
+

Enable to write APE tags at the end of the stream. Default is +disabled. +

+
+
write_mpeg2 bool
+

Enable to set MPEG version bit in the ADTS frame header to 1 which +indicates MPEG-2. Default is 0, which indicates MPEG-4. +

+
+ + +

4.8 aea

+

MD STUDIO audio muxer. +

+

This muxer accepts a single ATRAC1 audio stream with either one or two channels +and a sample rate of 44100Hz. +

+

As AEA supports storing the track title, this muxer will also write +the title from stream’s metadata to the container. +

+ +

4.9 aiff

+

Audio Interchange File Format muxer. +

+ +

4.9.1 Options

+
+
write_id3v2 bool
+

Enable ID3v2 tags writing when set to 1. Default is 0 (disabled). +

+
+
id3v2_version bool
+

Select ID3v2 version to write. Currently only version 3 and 4 (aka. +ID3v2.3 and ID3v2.4) are supported. The default is version 4. +

+
+ + +

4.10 alp

+

High Voltage Software’s Lego Racers game audio muxer. +

+

It accepts a single ADPCM_IMA_ALP stream with no more than 2 channels +and a sample rate not greater than 44100 Hz. +

+

Extensions: tun, pcm +

+ +

4.10.1 Options

+
+
type type
+

Set file type. +

+

type accepts the following values: +

+
‘tun’
+

Set file type as music. Must have a sample rate of 22050 Hz. +

+
+
‘pcm’
+

Set file type as sfx. +

+
+
‘auto’
+

Set file type as per output file extension. .pcm results in +type pcm else type tun is set. (default) +

+
+
+
+ + +

4.11 amr

+

3GPP AMR (Adaptive Multi-Rate) audio muxer. +

+

It accepts a single audio stream containing an AMR NB stream. +

+ +

4.12 amv

+

AMV (Actions Media Video) format muxer. +

+ +

4.13 apm

+

Ubisoft Rayman 2 APM audio muxer. +

+

It accepts a single ADPCM IMA APM audio stream. +

+ +

4.14 apng

+

Animated Portable Network Graphics muxer. +

+

It accepts a single APNG video stream. +

+ +

4.14.1 Options

+
+
final_delay delay
+

Force a delay expressed in seconds after the last frame of each +repetition. Default value is 0.0. +

+
+
plays repetitions
+

specify how many times to play the content, 0 causes an infinite +loop, with 1 there is no loop +

+
+ + +

4.14.2 Examples

+
    +
  • Use ffmpeg to generate an APNG output with 2 repetitions, +and with a delay of half a second after the first repetition: +
    +
    ffmpeg -i INPUT -final_delay 0.5 -plays 2 out.apng
    +
    +
+ + +

4.15 argo_asf

+

Argonaut Games ASF audio muxer. +

+

It accepts a single ADPCM audio stream. +

+ +

4.15.1 Options

+
+
version_major version
+

override file major version, specified as an integer, default value is +2 +

+
+
version_minor version
+

override file minor version, specified as an integer, default value is +1 +

+
+
name name
+

Embed file name into file, if not specified use the output file +name. The name is truncated to 8 characters. +

+
+ + +

4.16 argo_cvg

+

Argonaut Games CVG audio muxer. +

+

It accepts a single one-channel ADPCM 22050Hz audio stream. +

+

The loop and reverb options set the corresponding +flags in the header which can be later retrieved to process the audio +stream accordingly. +

+ +

4.16.1 Options

+
+
skip_rate_check bool
+

skip sample rate check (default is false) +

+
+
loop bool
+

set loop flag (default is false) +

+
+
reverb boolean
+

set reverb flag (default is true) +

+
+ + +

4.17 asf, asf_stream

+

Advanced / Active Systems (or Streaming) Format audio muxer. +

+

The ‘asf_stream’ variant should be selected for streaming. +

+

Note that Windows Media Audio (wma) and Windows Media Video (wmv) use this +muxer too. +

+ +

4.17.1 Options

+
+
packet_size size
+

Set the muxer packet size as a number of bytes. By tuning this setting +you may reduce data fragmentation or muxer overhead depending on your +source. Default value is 3200, minimum is 100, maximum +is 64Ki. +

+
+ + +

4.18 ass

+

ASS/SSA (SubStation Alpha) subtitles muxer. +

+

It accepts a single ASS subtitles stream. +

+ +

4.18.1 Options

+
+
ignore_readorder bool
+

Write dialogue events immediately, even if they are out-of-order, +default is false, otherwise they are cached until the expected +time event is found. +

+
+ + +

4.19 ast

+

AST (Audio Stream) muxer. +

+

This format is used to play audio on some Nintendo Wii games. +

+

It accepts a single audio stream. +

+

The loopstart and loopend options can be used to +define a section of the file to loop for players honoring such +options. +

+ +

4.19.1 Options

+
+
loopstart start
+

Specify loop start position expressesd in milliseconds, from -1 +to INT_MAX, in case -1 is set then no loop is specified +(default -1) and the loopend value is ignored. +

+
+
loopend end
+

Specify loop end position expressed in milliseconds, from 0 to +INT_MAX, default is 0, in case 0 is set it +assumes the total stream duration. +

+
+ + +

4.20 au

+

SUN AU audio muxer. +

+

It accepts a single audio stream. +

+ +

4.21 avi

+

Audio Video Interleaved muxer. +

+

AVI is a proprietary format developed by Microsoft, and later formally specified +through the Open DML specification. +

+

Because of differences in players implementations, it might be required to set +some options to make sure that the generated output can be correctly played by +the target player. +

+ +

4.21.1 Options

+
+
flipped_raw_rgb bool
+

If set to true, store positive height for raw RGB bitmaps, which +indicates bitmap is stored bottom-up. Note that this option does not flip the +bitmap which has to be done manually beforehand, e.g. by using the ‘vflip’ +filter. Default is false and indicates bitmap is stored top down. +

+
+
reserve_index_space size
+

Reserve the specified amount of bytes for the OpenDML master index of each +stream within the file header. By default additional master indexes are +embedded within the data packets if there is no space left in the first master +index and are linked together as a chain of indexes. This index structure can +cause problems for some use cases, e.g. third-party software strictly relying +on the OpenDML index specification or when file seeking is slow. Reserving +enough index space in the file header avoids these problems. +

+

The required index space depends on the output file size and should be about 16 +bytes per gigabyte. When this option is omitted or set to zero the necessary +index space is guessed. +

+

Default value is 0. +

+
+
write_channel_mask bool
+

Write the channel layout mask into the audio stream header. +

+

This option is enabled by default. Disabling the channel mask can be useful in +specific scenarios, e.g. when merging multiple audio streams into one for +compatibility with software that only supports a single audio stream in AVI +(see the "amerge" section in the ffmpeg-filters manual). +

+
+ + +

4.22 avif

+

AV1 (Alliance for Open Media Video codec 1) image format muxer. +

+

This muxers stores images encoded using the AV1 codec. +

+

It accepts one or two video streams. In case two video streams are +provided, the second one shall contain a single plane storing the +alpha mask. +

+

In case more than one image is provided, the generated output is +considered an animated AVIF and the number of loops can be specified +with the loop option. +

+

This is based on the specification by Alliance for Open Media at url +https://aomediacodec.github.io/av1-avif. +

+ +

4.22.1 Options

+
+
loop count
+

number of times to loop an animated AVIF, 0 specify an infinite +loop, default is 0 +

+
+
movie_timescale timescale
+

Set the timescale written in the movie header box (mvhd). +Range is 1 to INT_MAX. Default is 1000. +

+
+ + +

4.23 avm2

+

ShockWave Flash (SWF) / ActionScript Virtual Machine 2 (AVM2) format muxer. +

+

It accepts one audio stream, one video stream, or both. +

+ +

4.24 bit

+

G.729 (.bit) file format muxer. +

+

It accepts a single G.729 audio stream. +

+ +

4.25 caf

+

Apple CAF (Core Audio Format) muxer. +

+

It accepts a single audio stream. +

+ +

4.26 codec2

+

Codec2 audio audio muxer. +

+

It accepts a single codec2 audio stream. +

+ +

4.27 chromaprint

+

Chromaprint fingerprinter muxers. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-chromaprint. +

+

This muxer feeds audio data to the Chromaprint library, which +generates a fingerprint for the provided audio data. See: +https://acoustid.org/chromaprint +

+

It takes a single signed native-endian 16-bit raw audio stream of at +most 2 channels. +

+ +

4.27.1 Options

+
+
algorithm version
+

Select version of algorithm to fingerprint with. Range is 0 to +4. Version 3 enables silence detection. Default is 1. +

+
+
fp_format format
+

Format to output the fingerprint as. Accepts the following options: +

+
‘base64’
+

Base64 compressed fingerprint (default) +

+
+
‘compressed’
+

Binary compressed fingerprint +

+
+
‘raw’
+

Binary raw fingerprint +

+
+ +
+
silence_threshold threshold
+

Threshold for detecting silence. Range is from -1 to +32767, where -1 disables silence detection. Silence +detection can only be used with version 3 of the algorithm. +

+

Silence detection must be disabled for use with the AcoustID +service. Default is -1. +

+
+ + +

4.28 crc

+

CRC (Cyclic Redundancy Check) muxer. +

+

This muxer computes and prints the Adler-32 CRC of all the input audio +and video frames. By default audio frames are converted to signed +16-bit raw audio and video frames to raw video before computing the +CRC. +

+

The output of the muxer consists of a single line of the form: +CRC=0xCRC, where CRC is a hexadecimal number 0-padded to +8 digits containing the CRC for all the decoded input frames. +

+

See also the framecrc muxer. +

+ +

4.28.1 Examples

+
    +
  • Use ffmpeg to compute the CRC of the input, and store it in +the file out.crc: +
    +
    ffmpeg -i INPUT -f crc out.crc
    +
    + +
  • Use ffmpeg to print the CRC to stdout with the command: +
    +
    ffmpeg -i INPUT -f crc -
    +
    + +
  • You can select the output format of each frame with ffmpeg by +specifying the audio and video codec and format. For example, to +compute the CRC of the input audio converted to PCM unsigned 8-bit +and the input video converted to MPEG-2 video, use the command: +
    +
    ffmpeg -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
    +
    +
+ + +

4.29 dash

+

Dynamic Adaptive Streaming over HTTP (DASH) muxer. +

+

This muxer creates segments and manifest files according to the +MPEG-DASH standard ISO/IEC 23009-1:2014 and following standard +updates. +

+

For more information see: +

+ +

This muxer creates an MPD (Media Presentation Description) manifest +file and segment files for each stream. Segment files are placed in +the same directory of the MPD manifest file. +

+

The segment filename might contain pre-defined identifiers used in the +manifest SegmentTemplate section as defined in section +5.3.9.4.4 of the standard. +

+

Available identifiers are $RepresentationID$, $Number$, +$Bandwidth$, and $Time$. In addition to the standard +identifiers, an ffmpeg-specific $ext$ identifier is also +supported. When specified, ffmpeg will replace $ext$ +in the file name with muxing format’s extensions such as mp4, +webm etc. +

+ +

4.29.1 Options

+
+
adaptation_sets adaptation_sets
+

Assign streams to adaptation sets, specified in the MPD manifest +AdaptationSets section. +

+

An adaptation set contains a set of one or more streams accessed as a +single subset, e.g. corresponding streams encoded at different size +selectable by the user depending on the available bandwidth, or to +different audio streams with a different language. +

+

Each adaptation set is specified with the syntax: +

+
id=index,streams=streams
+
+ +

where index must be a numerical index, and streams is a +sequence of ,-separated stream indices. Multiple adaptation +sets can be specified, separated by spaces. +

+

To map all video (or audio) streams to an adaptation set, v (or +a) can be used as stream identifier instead of IDs. +

+

When no assignment is defined, this defaults to an adaptation set for +each stream. +

+

The following optional fields can also be specified: +

+
+
descriptor
+

Define the descriptor as defined by ISO/IEC 23009-1:2014/Amd.2:2015. +

+

For example: +

+
<SupplementalProperty schemeIdUri=\"urn:mpeg:dash:srd:2014\" value=\"0,0,0,1,1,2,2\"/>
+
+ +

The descriptor string should be a self-closing XML tag. +

+
+
frag_duration
+

Override the global fragment duration specified with the +frag_duration option. +

+
+
frag_type
+

Override the global fragment type specified with the +frag_type option. +

+
+
seg_duration
+

Override the global segment duration specified with the +seg_duration option. +

+
+
trick_id
+

Mark an adaptation set as containing streams meant to be used for +Trick Mode for the referenced adaptation set. +

+
+ +

A few examples of possible values for the adaptation_sets +option follow: +

+
id=0,seg_duration=2,frag_duration=1,frag_type=duration,streams=v id=1,seg_duration=2,frag_type=none,streams=a
+
+ +
+
id=0,seg_duration=2,frag_type=none,streams=0 id=1,seg_duration=10,frag_type=none,trick_id=0,streams=1
+
+ +
+
dash_segment_type type
+

Set DASH segment files type. +

+

Possible values: +

+
‘auto’
+

The dash segment files format will be selected based on the stream +codec. This is the default mode. +

+
‘mp4’
+

the dash segment files will be in ISOBMFF/MP4 format +

+
‘webm’
+

the dash segment files will be in WebM format +

+
+ +
+
extra_window_size size
+

Set the maximum number of segments kept outside of the manifest before +removing from disk. +

+
+
format_options options_list
+

Set container format (mp4/webm) options using a :-separated list of +key=value parameters. Values containing : special characters must be +escaped. +

+
+
frag_duration duration
+

Set the length in seconds of fragments within segments, fractional +value can also be set. +

+
+
frag_type type
+

Set the type of interval for fragmentation. +

+

Possible values: +

+
‘auto’
+

set one fragment per segment +

+
+
‘every_frame’
+

fragment at every frame +

+
+
‘duration’
+

fragment at specific time intervals +

+
+
‘pframes’
+

fragment at keyframes and following P-Frame reordering (Video only, +experimental) +

+
+ +
+
global_sidx bool
+

Write global SIDX atom. Applicable only for single file, mp4 +output, non-streaming mode. +

+
+
hls_master_name file_name
+

HLS master playlist name. Default is master.m3u8. +

+
+
hls_playlist bool
+

Generate HLS playlist files. The master playlist is generated with +filename specified by the hls_master_name option. One media +playlist file is generated for each stream with filenames +media_0.m3u8, media_1.m3u8, etc. +

+
+
http_opts http_opts
+

Specify a list of :-separated key=value options to pass to the +underlying HTTP protocol. Applicable only for HTTP output. +

+
+
http_persistent bool
+

Use persistent HTTP connections. Applicable only for HTTP output. +

+
+
http_user_agent user_agent
+

Override User-Agent field in HTTP header. Applicable only for HTTP +output. +

+
+
ignore_io_errors bool
+

Ignore IO errors during open and write. Useful for long-duration runs +with network output. This is disabled by default. +

+
+
index_correction bool
+

Enable or disable segment index correction logic. Applicable only when +use_template is enabled and use_timeline is +disabled. This is disabled by default. +

+

When enabled, the logic monitors the flow of segment indexes. If a +streams’s segment index value is not at the expected real time +position, then the logic corrects that index value. +

+

Typically this logic is needed in live streaming use cases. The +network bandwidth fluctuations are common during long run +streaming. Each fluctuation can cause the segment indexes fall behind +the expected real time position. +

+
+
init_seg_name init_name
+

DASH-templated name to use for the initialization segment. Default is +init-stream$RepresentationID$.$ext$. $ext$ is replaced +with the file name extension specific for the segment format. +

+
+
ldash bool
+

Enable Low-latency Dash by constraining the presence and values of +some elements. This is disabled by default. +

+
+
lhls bool
+

Enable Low-latency HLS (LHLS). Add #EXT-X-PREFETCH tag with +current segment’s URI. hls.js player folks are trying to standardize +an open LHLS spec. The draft spec is available at +https://github.com/video-dev/hlsjs-rfcs/blob/lhls-spec/proposals/0001-lhls.md. +

+

This option tries to comply with the above open spec. It enables +streaming and hls_playlist options automatically. +This is an experimental feature. +

+

Note: This is not Apple’s version LHLS. See +https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis +

+
+
master_m3u8_publish_rate segment_intervals_count
+

Publish master playlist repeatedly every after specified number of +segment intervals. +

+
+
max_playback_rate rate
+

Set the maximum playback rate indicated as appropriate for the +purposes of automatically adjusting playback latency and buffer +occupancy during normal playback by clients. +

+
+
media_seg_name segment_name
+

DASH-templated name to use for the media segments. Default is +chunk-stream$RepresentationID$-$Number%05d$.$ext$. $ext$ +is replaced with the file name extension specific for the segment +format. +

+
+
method method
+

Use the given HTTP method to create output files. Generally set to PUT +or POST. +

+
+
min_playback_rate rate
+

Set the minimum playback rate indicated as appropriate for the +purposes of automatically adjusting playback latency and buffer +occupancy during normal playback by clients. +

+
+
mpd_profile flags
+

Set one or more MPD manifest profiles. +

+

Possible values: +

+
‘dash’
+

MPEG-DASH ISO Base media file format live profile +

+
‘dvb_dash’
+

DVB-DASH profile +

+
+ +

Default value is dash. +

+
+
remove_at_exit bool
+

Enable or disable removal of all segments when finished. This is +disabled by default. +

+
+
seg_duration duration
+

Set the segment length in seconds (fractional value can be set). The +value is treated as average segment duration when the +use_template option is enabled and the use_timeline +option is disabled and as minimum segment duration for all the other +use cases. +

+

Default value is 5. +

+
+
single_file bool
+

Enable or disable storing all segments in one file, accessed using +byte ranges. This is disabled by default. +

+

The name of the single file can be specified with the +single_file_name option, if not specified assume the basename +of the manifest file with the output format extension. +

+
+
single_file_name file_name
+

DASH-templated name to use for the manifest baseURL +element. Imply that the single_file option is set to +true. In the template, $ext$ is replaced with the file +name extension specific for the segment format. +

+
+
streaming bool
+

Enable or disable chunk streaming mode of output. In chunk streaming +mode, each frame will be a moof fragment which forms a +chunk. This is disabled by default. +

+
+
target_latency target_latency
+

Set an intended target latency in seconds for serving (fractional +value can be set). Applicable only when the streaming and +write_prft options are enabled. This is an informative fields +clients can use to measure the latency of the service. +

+
+
timeout timeout
+

Set timeout for socket I/O operations expressed in seconds (fractional +value can be set). Applicable only for HTTP output. +

+
+
update_period period
+

Set the MPD update period, for dynamic content. The unit is +second. If set to 0, the period is automatically computed. +

+

Default value is 0. +

+
+
use_template bool
+

Enable or disable use of SegmentTemplate instead of +SegmentList in the manifest. This is enabled by default. +

+
+
use_timeline bool
+

Enable or disable use of SegmentTimeline within the +SegmentTemplate manifest section. This is enabled by default. +

+
+
utc_timing_url url
+

URL of the page that will return the UTC timestamp in ISO +format, for example https://time.akamai.com/?iso +

+
+
window_size size
+

Set the maximum number of segments kept in the manifest, discard the +oldest one. This is useful for live streaming. +

+

If the value is 0, all segments are kept in the +manifest. Default value is 0. +

+
+
write_prft write_prft
+

Write Producer Reference Time elements on supported streams. This also +enables writing prft boxes in the underlying muxer. Applicable only +when the utc_url option is enabled. It is set to auto by +default, in which case the muxer will attempt to enable it only in +modes that require it. +

+
+ + +

4.29.2 Example

+

Generate a DASH output reading from an input source in realtime using +ffmpeg. +

+

Two multimedia streams are generated from the input file, both +containing a video stream encoded through ‘libx264’, and an audio +stream encoded with ‘libfdk_aac’. The first multimedia stream +contains video with a bitrate of 800k and audio at the default rate, +the second with video scaled to 320x170 pixels at 300k and audio +resampled at 22005 Hz. +

+

The window_size option keeps only the latest 5 segments with +the default duration of 5 seconds. +

+
+
ffmpeg -re -i <input> -map 0 -map 0 -c:a libfdk_aac -c:v libx264 \
+-b:v:0 800k -profile:v:0 main \
+-b:v:1 300k -s:v:1 320x170 -profile:v:1 baseline -ar:a:1 22050 \
+-bf 1 -keyint_min 120 -g 120 -sc_threshold 0 -b_strategy 0 \
+-use_timeline 1 -use_template 1 -window_size 5 \
+-adaptation_sets "id=0,streams=v id=1,streams=a" \
+-f dash /path/to/out.mpd
+
+ + +

4.30 daud

+

D-Cinema audio muxer. +

+

It accepts a single 6-channels audio stream resampled at 96000 Hz +encoded with the ‘pcm_24daud’ codec. +

+ +

4.30.1 Example

+

Use ffmpeg to mux input audio to a ‘5.1’ channel layout +resampled at 96000Hz: +

+
ffmpeg -i INPUT -af aresample=96000,pan=5.1 slow.302
+
+ +

For ffmpeg versions before 7.0 you might have to use the ‘asetnsamples’ +filter to limit the muxed packet size, because this format does not support +muxing packets larger than 65535 bytes (3640 samples). For newer ffmpeg +versions audio is automatically packetized to 36000 byte (2000 sample) packets. +

+ +

4.31 dv

+

DV (Digital Video) muxer. +

+

It accepts exactly one ‘dvvideo’ video stream and at most two +‘pcm_s16’ audio streams. More constraints are defined by the +property of the video, which must correspond to a DV video supported +profile, and on the framerate. +

+ +

4.31.1 Example

+

Use ffmpeg to convert the input: +

+
ffmpeg -i INPUT -s:v 720x480 -pix_fmt yuv411p -r 29.97 -ac 2 -ar 48000 -y out.dv
+
+ + +

4.32 ffmetadata

+

FFmpeg metadata muxer. +

+

This muxer writes the streams metadata in the ‘ffmetadata’ +format. +

+

See the Metadata chapter for +information about the format. +

+ +

4.32.1 Example

+ +

Use ffmpeg to extract metadata from an input file to a metadata.ffmeta +file in ‘ffmetadata’ format: +

+
ffmpeg -i INPUT -f ffmetadata metadata.ffmeta
+
+ + +

4.33 fifo

+

FIFO (First-In First-Out) muxer. +

+

The ‘fifo’ pseudo-muxer allows the separation of encoding and +muxing by using a first-in-first-out queue and running the actual muxer +in a separate thread. +

+

This is especially useful in combination with +the tee muxer and can be used to send data to several +destinations with different reliability/writing speed/latency. +

+

The target muxer is either selected from the output name or specified +through the fifo_format option. +

+

The behavior of the ‘fifo’ muxer if the queue fills up or if the +output fails (e.g. if a packet cannot be written to the output) is +selectable: +

    +
  • Output can be transparently restarted with configurable delay between +retries based on real time or time of the processed stream. + +
  • Encoding can be blocked during temporary failure, or continue transparently +dropping packets in case the FIFO queue fills up. +
+ +

API users should be aware that callback functions +(interrupt_callback, io_open and io_close) used +within its AVFormatContext must be thread-safe. +

+ +

4.33.1 Options

+
+
attempt_recovery bool
+

If failure occurs, attempt to recover the output. This is especially +useful when used with network output, since it makes it possible to +restart streaming transparently. By default this option is set to +false. +

+
+
drop_pkts_on_overflow bool
+

If set to true, in case the fifo queue fills up, packets will +be dropped rather than blocking the encoder. This makes it possible to +continue streaming without delaying the input, at the cost of omitting +part of the stream. By default this option is set to false, so in +such cases the encoder will be blocked until the muxer processes some +of the packets and none of them is lost. +

+
+
fifo_format format_name
+

Specify the format name. Useful if it cannot be guessed from the +output name suffix. +

+
+
format_opts options
+

Specify format options for the underlying muxer. Muxer options can be +specified as a list of key=value pairs separated by ’:’. +

+
+
max_recovery_attempts count
+

Set maximum number of successive unsuccessful recovery attempts after +which the output fails permanently. By default this option is set to +0 (unlimited). +

+
+
queue_size size
+

Specify size of the queue as a number of packets. Default value is +60. +

+
+
recover_any_error bool
+

If set to true, recovery will be attempted regardless of type +of the error causing the failure. By default this option is set to +false and in case of certain (usually permanent) errors the +recovery is not attempted even when the attempt_recovery +option is set to true. +

+
+
recovery_wait_streamtime bool
+

If set to false, the real time is used when waiting for the +recovery attempt (i.e. the recovery will be attempted after the time +specified by the recovery_wait_time option). +

+

If set to true, the time of the processed stream is taken into +account instead (i.e. the recovery will be attempted after discarding +the packets corresponding to the recovery_wait_time option). +

+

By default this option is set to false. +

+
+
recovery_wait_time duration
+

Specify waiting time in seconds before the next recovery attempt after +previous unsuccessful recovery attempt. Default value is 5. +

+
+
restart_with_keyframe bool
+

Specify whether to wait for the keyframe after recovering from +queue overflow or failure. This option is set to false by default. +

+
+
timeshift duration
+

Buffer the specified amount of packets and delay writing the +output. Note that the value of the queue_size option must be +big enough to store the packets for timeshift. At the end of the input +the fifo buffer is flushed at realtime speed. +

+
+ + +

4.33.2 Example

+ +

Use ffmpeg to stream to an RTMP server, continue processing +the stream at real-time rate even in case of temporary failure +(network outage) and attempt to recover streaming every second +indefinitely: +

+
ffmpeg -re -i ... -c:v libx264 -c:a aac -f fifo -fifo_format flv \
+  -drop_pkts_on_overflow 1 -attempt_recovery 1 -recovery_wait_time 1 \
+  -map 0:v -map 0:a rtmp://example.com/live/stream_name
+
+ + +

4.34 film_cpk

+

Sega film (.cpk) muxer. +

+

This format was used as internal format for several Sega games. +

+

For more information regarding the Sega film file format, visit +http://wiki.multimedia.cx/index.php?title=Sega_FILM. +

+

It accepts at maximum one ‘cinepak’ or raw video stream, and at +maximum one audio stream. +

+ +

4.35 filmstrip

+

Adobe Filmstrip muxer. +

+

This format is used by several Adobe tools to store a generated filmstrip export. It +accepts a single raw video stream. +

+ +

4.36 fits

+

Flexible Image Transport System (FITS) muxer. +

+

This image format is used to store astronomical data. +

+

For more information regarding the format, visit +https://fits.gsfc.nasa.gov. +

+ +

4.37 flac

+

Raw FLAC audio muxer. +

+

This muxer accepts exactly one FLAC audio stream. Additionally, it is possible to add +images with disposition ‘attached_pic’. +

+ +

4.37.1 Options

+
+
write_header bool
+

write the file header if set to true, default is true +

+
+ + +

4.37.2 Example

+

Use ffmpeg to store the audio stream from an input file, +together with several pictures used with ‘attached_pic’ +disposition: +

+
ffmpeg -i INPUT -i pic1.png -i pic2.jpg -map 0:a -map 1 -map 2 -disposition:v attached_pic OUTPUT
+
+ + +

4.38 flv

+

Adobe Flash Video Format muxer. +

+ +

4.38.1 Options

+
+
flvflags flags
+

Possible values: +

+
+
‘aac_seq_header_detect’
+

Place AAC sequence header based on audio stream data. +

+
+
‘no_sequence_end’
+

Disable sequence end tag. +

+
+
‘no_metadata’
+

Disable metadata tag. +

+
+
‘no_duration_filesize’
+

Disable duration and filesize in metadata when they are equal to zero +at the end of stream. (Be used to non-seekable living stream). +

+
+
‘add_keyframe_index’
+

Used to facilitate seeking; particularly for HTTP pseudo streaming. +

+
+
+
+ + +

4.39 framecrc

+ +

Per-packet CRC (Cyclic Redundancy Check) testing format. +

+

This muxer computes and prints the Adler-32 CRC for each audio +and video packet. By default audio frames are converted to signed +16-bit raw audio and video frames to raw video before computing the +CRC. +

+

The output of the muxer consists of a line for each audio and video +packet of the form: +

+
stream_index, packet_dts, packet_pts, packet_duration, packet_size, 0xCRC
+
+ +

CRC is a hexadecimal number 0-padded to 8 digits containing the +CRC of the packet. +

+ +

4.39.1 Examples

+ +

For example to compute the CRC of the audio and video frames in +INPUT, converted to raw audio and video packets, and store it +in the file out.crc: +

+
ffmpeg -i INPUT -f framecrc out.crc
+
+ +

To print the information to stdout, use the command: +

+
ffmpeg -i INPUT -f framecrc -
+
+ +

With ffmpeg, you can select the output format to which the +audio and video frames are encoded before computing the CRC for each +packet by specifying the audio and video codec. For example, to +compute the CRC of each decoded input audio frame converted to PCM +unsigned 8-bit and of each decoded input video frame converted to +MPEG-2 video, use the command: +

+
ffmpeg -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc -
+
+ +

See also the crc muxer. +

+ +

4.40 framehash

+ +

Per-packet hash testing format. +

+

This muxer computes and prints a cryptographic hash for each audio +and video packet. This can be used for packet-by-packet equality +checks without having to individually do a binary comparison on each. +

+

By default audio frames are converted to signed 16-bit raw audio and +video frames to raw video before computing the hash, but the output +of explicit conversions to other codecs can also be used. It uses the +SHA-256 cryptographic hash function by default, but supports several +other algorithms. +

+

The output of the muxer consists of a line for each audio and video +packet of the form: +

+
stream_index, packet_dts, packet_pts, packet_duration, packet_size, hash
+
+ +

hash is a hexadecimal number representing the computed hash +for the packet. +

+
+
hash algorithm
+

Use the cryptographic hash function specified by the string algorithm. +Supported values include MD5, murmur3, RIPEMD128, +RIPEMD160, RIPEMD256, RIPEMD320, SHA160, +SHA224, SHA256 (default), SHA512/224, SHA512/256, +SHA384, SHA512, CRC32 and adler32. +

+
+
+ + +

4.40.1 Examples

+ +

To compute the SHA-256 hash of the audio and video frames in INPUT, +converted to raw audio and video packets, and store it in the file +out.sha256: +

+
ffmpeg -i INPUT -f framehash out.sha256
+
+ +

To print the information to stdout, using the MD5 hash function, use +the command: +

+
ffmpeg -i INPUT -f framehash -hash md5 -
+
+ +

See also the hash muxer. +

+ +

4.41 framemd5

+ +

Per-packet MD5 testing format. +

+

This is a variant of the framehash muxer. Unlike that muxer, +it defaults to using the MD5 hash function. +

+ +

4.41.1 Examples

+ +

To compute the MD5 hash of the audio and video frames in INPUT, +converted to raw audio and video packets, and store it in the file +out.md5: +

+
ffmpeg -i INPUT -f framemd5 out.md5
+
+ +

To print the information to stdout, use the command: +

+
ffmpeg -i INPUT -f framemd5 -
+
+ +

See also the framehash and md5 muxers. +

+ +

4.42 gif

+

Animated GIF muxer. +

+

Note that the GIF format has a very large time base: the delay between two frames can +therefore not be smaller than one centi second. +

+ +

4.42.1 Options

+
+
loop bool
+

Set the number of times to loop the output. Use -1 for no loop, 0 +for looping indefinitely (default). +

+
+
final_delay delay
+

Force the delay (expressed in centiseconds) after the last frame. Each frame +ends with a delay until the next frame. The default is -1, which is a +special value to tell the muxer to reuse the previous delay. In case of a +loop, you might want to customize this value to mark a pause for instance. +

+
+ + +

4.42.2 Example

+

Encode a gif looping 10 times, with a 5 seconds delay between +the loops: +

+
ffmpeg -i INPUT -loop 10 -final_delay 500 out.gif
+
+ +

Note 1: if you wish to extract the frames into separate GIF files, you need to +force the image2 muxer: +

+
ffmpeg -i INPUT -c:v gif -f image2 "out%d.gif"
+
+ + +

4.43 gxf

+

General eXchange Format (GXF) muxer. +

+

GXF was developed by Grass Valley Group, then standardized by SMPTE as SMPTE +360M and was extended in SMPTE RDD 14-2007 to include high-definition video +resolutions. +

+

It accepts at most one video stream with codec ‘mjpeg’, or +‘mpeg1video’, or ‘mpeg2video’, or ‘dvvideo’ with resolution +‘512x480’ or ‘608x576’, and several audio streams with rate 48000Hz +and codec ‘pcm16_le’. +

+ +

4.44 hash

+ +

Hash testing format. +

+

This muxer computes and prints a cryptographic hash of all the input +audio and video frames. This can be used for equality checks without +having to do a complete binary comparison. +

+

By default audio frames are converted to signed 16-bit raw audio and +video frames to raw video before computing the hash, but the output +of explicit conversions to other codecs can also be used. Timestamps +are ignored. It uses the SHA-256 cryptographic hash function by default, +but supports several other algorithms. +

+

The output of the muxer consists of a single line of the form: +algo=hash, where algo is a short string representing +the hash function used, and hash is a hexadecimal number +representing the computed hash. +

+
+
hash algorithm
+

Use the cryptographic hash function specified by the string algorithm. +Supported values include MD5, murmur3, RIPEMD128, +RIPEMD160, RIPEMD256, RIPEMD320, SHA160, +SHA224, SHA256 (default), SHA512/224, SHA512/256, +SHA384, SHA512, CRC32 and adler32. +

+
+
+ + +

4.44.1 Examples

+ +

To compute the SHA-256 hash of the input converted to raw audio and +video, and store it in the file out.sha256: +

+
ffmpeg -i INPUT -f hash out.sha256
+
+ +

To print an MD5 hash to stdout use the command: +

+
ffmpeg -i INPUT -f hash -hash md5 -
+
+ +

See also the framehash muxer. +

+ +

4.45 hds

+

HTTP Dynamic Streaming (HDS) muxer. +

+

HTTP dynamic streaming, or HDS, is an adaptive bitrate streaming method +developed by Adobe. HDS delivers MP4 video content over HTTP connections. HDS +can be used for on-demand streaming or live streaming. +

+

This muxer creates an .f4m (Adobe Flash Media Manifest File) manifest, an .abst +(Adobe Bootstrap File) for each stream, and segment files in a directory +specified as the output. +

+

These needs to be accessed by an HDS player through HTTPS for it to be able to +perform playback on the generated stream. +

+ +

4.45.1 Options

+
+
extra_window_size int
+

number of fragments kept outside of the manifest before removing from disk +

+
+
min_frag_duration microseconds
+

minimum fragment duration (in microseconds), default value is 1 second +(10000000) +

+
+
remove_at_exit bool
+

remove all fragments when finished when set to true +

+
+
window_size int
+

number of fragments kept in the manifest, if set to a value different from +0. By default all segments are kept in the output directory. +

+
+ + +

4.45.2 Example

+

Use ffmpeg to generate HDS files to the output.hds directory in +real-time rate: +

+
ffmpeg -re -i INPUT -f hds -b:v 200k output.hds
+
+ + +

4.46 hls

+ +

Apple HTTP Live Streaming muxer that segments MPEG-TS according to +the HTTP Live Streaming (HLS) specification. +

+

It creates a playlist file, and one or more segment files. The output filename +specifies the playlist filename. +

+

By default, the muxer creates a file for each segment produced. These files +have the same name as the playlist, followed by a sequential number and a +.ts extension. +

+

Make sure to require a closed GOP when encoding and to set the GOP +size to fit your segment time constraint. +

+

For example, to convert an input file with ffmpeg: +

+
ffmpeg -i in.mkv -c:v h264 -flags +cgop -g 30 -hls_time 1 out.m3u8
+
+

This example will produce the playlist, out.m3u8, and segment files: +out0.ts, out1.ts, out2.ts, etc. +

+

See also the segment muxer, which provides a more generic and +flexible implementation of a segmenter, and can be used to perform HLS +segmentation. +

+ +

4.46.1 Options

+
+
hls_init_time duration
+

Set the initial target segment length. Default value is 0. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

Segment will be cut on the next key frame after this time has passed on the +first m3u8 list. After the initial playlist is filled, ffmpeg will cut +segments at duration equal to hls_time. +

+
+
hls_time duration
+

Set the target segment length. Default value is 2. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +Segment will be cut on the next key frame after this time has passed. +

+
+
hls_list_size size
+

Set the maximum number of playlist entries. If set to 0 the list file +will contain all the segments. Default value is 5. +

+
+
hls_delete_threshold size
+

Set the number of unreferenced segments to keep on disk before hls_flags delete_segments +deletes them. Increase this to allow continue clients to download segments which +were recently referenced in the playlist. Default value is 1, meaning segments older than +hls_list_size+1 will be deleted. +

+
+
hls_start_number_source source
+

Start the playlist sequence number (#EXT-X-MEDIA-SEQUENCE) according to the specified source. +Unless hls_flags single_file is set, it also specifies source of starting sequence numbers of +segment and subtitle filenames. In any case, if hls_flags append_list +is set and read playlist sequence number is greater than the specified start sequence number, +then that value will be used as start value. +

+

It accepts the following values: +

+
+
generic (default)
+

Set the start numbers according to the start_number option value. +

+
+
epoch
+

Set the start number as the seconds since epoch (1970-01-01 00:00:00). +

+
+
epoch_us
+

Set the start number as the microseconds since epoch (1970-01-01 00:00:00). +

+
+
datetime
+

Set the start number based on the current date/time as YYYYmmddHHMMSS. e.g. 20161231235759. +

+
+ +
+
start_number number
+

Start the playlist sequence number (#EXT-X-MEDIA-SEQUENCE) from the specified number +when hls_start_number_source value is generic. (This is the default case.) +Unless hls_flags single_file is set, it also specifies starting sequence numbers of segment and subtitle filenames. +Default value is 0. +

+
+
hls_allow_cache bool
+

Explicitly set whether the client MAY (1) or MUST NOT (0) cache media segments. +

+
+
hls_base_url baseurl
+

Append baseurl to every entry in the playlist. +Useful to generate playlists with absolute paths. +

+

Note that the playlist sequence number must be unique for each segment +and it is not to be confused with the segment filename sequence number +which can be cyclic, for example if the wrap option is +specified. +

+
+
hls_segment_filename filename
+

Set the segment filename. Unless the hls_flags option is set with +‘single_file’, filename is used as a string format with the +segment number appended. +

+

For example: +

+
ffmpeg -i in.nut -hls_segment_filename 'file%03d.ts' out.m3u8
+
+ +

will produce the playlist, out.m3u8, and segment files: +file000.ts, file001.ts, file002.ts, etc. +

+

filename may contain a full path or relative path specification, +but only the file name part without any path will be contained in the m3u8 segment list. +Should a relative path be specified, the path of the created segment +files will be relative to the current working directory. +When strftime_mkdir is set, the whole expanded value of filename will be written into the m3u8 segment list. +

+

When var_stream_map is set with two or more variant streams, the +filename pattern must contain the string "%v", and this string will be +expanded to the position of variant stream index in the generated segment file +names. +

+

For example: +

+
ffmpeg -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
+  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
+  -hls_segment_filename 'file_%v_%03d.ts' out_%v.m3u8
+
+ +

will produce the playlists segment file sets: +file_0_000.ts, file_0_001.ts, file_0_002.ts, etc. and +file_1_000.ts, file_1_001.ts, file_1_002.ts, etc. +

+

The string "%v" may be present in the filename or in the last directory name +containing the file, but only in one of them. (Additionally, %v may appear multiple times in the last +sub-directory or filename.) If the string %v is present in the directory name, then +sub-directories are created after expanding the directory name pattern. This +enables creation of segments corresponding to different variant streams in +subdirectories. +

+

For example: +

+
ffmpeg -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
+  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
+  -hls_segment_filename 'vs%v/file_%03d.ts' vs%v/out.m3u8
+
+

will produce the playlists segment file sets: +vs0/file_000.ts, vs0/file_001.ts, vs0/file_002.ts, etc. and +vs1/file_000.ts, vs1/file_001.ts, vs1/file_002.ts, etc. +

+
+
strftime bool
+

Use strftime() on filename to expand the segment filename with +localtime. The segment number is also available in this mode, but to use it, +you need to set ‘second_level_segment_index’ in the hls_flag and +%%d will be the specifier. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -hls_segment_filename 'file-%Y%m%d-%s.ts' out.m3u8
+
+

will produce the playlist, out.m3u8, and segment files: +file-20160215-1455569023.ts, file-20160215-1455569024.ts, etc. +Note: On some systems/environments, the %s specifier is not +available. See strftime() documentation. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -hls_flags second_level_segment_index -hls_segment_filename 'file-%Y%m%d-%%04d.ts' out.m3u8
+
+

will produce the playlist, out.m3u8, and segment files: +file-20160215-0001.ts, file-20160215-0002.ts, etc. +

+
+
strftime_mkdir bool
+

Used together with strftime, it will create all subdirectories which +are present in the expanded values of option hls_segment_filename. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -strftime_mkdir 1 -hls_segment_filename '%Y%m%d/file-%Y%m%d-%s.ts' out.m3u8
+
+

will create a directory 201560215 (if it does not exist), and then +produce the playlist, out.m3u8, and segment files: +20160215/file-20160215-1455569023.ts, +20160215/file-20160215-1455569024.ts, etc. +

+

For example: +

+
ffmpeg -i in.nut -strftime 1 -strftime_mkdir 1 -hls_segment_filename '%Y/%m/%d/file-%Y%m%d-%s.ts' out.m3u8
+
+

will create a directory hierarchy 2016/02/15 (if any of them do not +exist), and then produce the playlist, out.m3u8, and segment files: +2016/02/15/file-20160215-1455569023.ts, +2016/02/15/file-20160215-1455569024.ts, etc. +

+
+
hls_segment_options options_list
+

Set output format options using a :-separated list of key=value +parameters. Values containing : special characters must be +escaped. +

+
+
hls_key_info_file key_info_file
+

Use the information in key_info_file for segment encryption. The first +line of key_info_file specifies the key URI written to the playlist. The +key URL is used to access the encryption key during playback. The second line +specifies the path to the key file used to obtain the key during the encryption +process. The key file is read as a single packed array of 16 octets in binary +format. The optional third line specifies the initialization vector (IV) as a +hexadecimal string to be used instead of the segment sequence number (default) +for encryption. Changes to key_info_file will result in segment +encryption with the new key/IV and an entry in the playlist for the new key +URI/IV if hls_flags periodic_rekey is enabled. +

+

Key info file format: +

+
key URI
+key file path
+IV (optional)
+
+ +

Example key URIs: +

+
http://server/file.key
+/path/to/file.key
+file.key
+
+ +

Example key file paths: +

+
file.key
+/path/to/file.key
+
+ +

Example IV: +

+
0123456789ABCDEF0123456789ABCDEF
+
+ +

Key info file example: +

+
http://server/file.key
+/path/to/file.key
+0123456789ABCDEF0123456789ABCDEF
+
+ +

Example shell script: +

+
#!/bin/sh
+BASE_URL=${1:-'.'}
+openssl rand 16 > file.key
+echo $BASE_URL/file.key > file.keyinfo
+echo file.key >> file.keyinfo
+echo $(openssl rand -hex 16) >> file.keyinfo
+ffmpeg -f lavfi -re -i testsrc -c:v h264 -hls_flags delete_segments \
+  -hls_key_info_file file.keyinfo out.m3u8
+
+ +
+
hls_enc bool
+

Enable (1) or disable (0) the AES128 encryption. +When enabled every segment generated is encrypted and the encryption key +is saved as playlist name.key. +

+
+
hls_enc_key key
+

Specify a 16-octet key to encrypt the segments, by default it is randomly +generated. +

+
+
hls_enc_key_url keyurl
+

If set, keyurl is prepended instead of baseurl to the key filename +in the playlist. +

+
+
hls_enc_iv iv
+

Specify the 16-octet initialization vector for every segment instead of the +autogenerated ones. +

+
+
hls_segment_type flags
+

Possible values: +

+
+
‘mpegts’
+

Output segment files in MPEG-2 Transport Stream format. This is +compatible with all HLS versions. +

+
+
‘fmp4’
+

Output segment files in fragmented MP4 format, similar to MPEG-DASH. +fmp4 files may be used in HLS version 7 and above. +

+
+ +
+
hls_fmp4_init_filename filename
+

Set filename for the fragment files header file, default filename is init.mp4. +

+

When strftime is enabled, filename is expanded to the segment filename with localtime. +

+

For example: +

+
ffmpeg -i in.nut -hls_segment_type fmp4 -strftime 1 -hls_fmp4_init_filename "%s_init.mp4" out.m3u8
+
+

will produce init like this 1602678741_init.mp4. +

+
+
hls_fmp4_init_resend bool
+

Resend init file after m3u8 file refresh every time, default is 0. +

+

When var_stream_map is set with two or more variant streams, the +filename pattern must contain the string "%v", this string specifies +the position of variant stream index in the generated init file names. +The string "%v" may be present in the filename or in the last directory name +containing the file. If the string is present in the directory name, then +sub-directories are created after expanding the directory name pattern. This +enables creation of init files corresponding to different variant streams in +subdirectories. +

+
+
hls_flags flags
+

Possible values: +

+
+
‘single_file’
+

If this flag is set, the muxer will store all segments in a single MPEG-TS +file, and will use byte ranges in the playlist. HLS playlists generated with +this way will have the version number 4. +

+

For example: +

+
ffmpeg -i in.nut -hls_flags single_file out.m3u8
+
+

will produce the playlist, out.m3u8, and a single segment file, +out.ts. +

+
+
‘delete_segments’
+

Segment files removed from the playlist are deleted after a period of time +equal to the duration of the segment plus the duration of the playlist. +

+
+
‘append_list’
+

Append new segments into the end of old segment list, +and remove the #EXT-X-ENDLIST from the old segment list. +

+
+
‘round_durations’
+

Round the duration info in the playlist file segment info to integer +values, instead of using floating point. +If there are no other features requiring higher HLS versions be used, +then this will allow ffmpeg to output a HLS version 2 m3u8. +

+
+
‘discont_start’
+

Add the #EXT-X-DISCONTINUITY tag to the playlist, before the +first segment’s information. +

+
+
‘omit_endlist’
+

Do not append the EXT-X-ENDLIST tag at the end of the playlist. +

+
+
‘periodic_rekey’
+

The file specified by hls_key_info_file will be checked periodically and +detect updates to the encryption info. Be sure to replace this file atomically, +including the file containing the AES encryption key. +

+
+
‘independent_segments’
+

Add the #EXT-X-INDEPENDENT-SEGMENTS tag to playlists that has video segments +and when all the segments of that playlist are guaranteed to start with a key frame. +

+
+
‘iframes_only’
+

Add the #EXT-X-I-FRAMES-ONLY tag to playlists that has video segments +and can play only I-frames in the #EXT-X-BYTERANGE mode. +

+
+
‘split_by_time’
+

Allow segments to start on frames other than key frames. This improves +behavior on some players when the time between key frames is inconsistent, +but may make things worse on others, and can cause some oddities during +seeking. This flag should be used with the hls_time option. +

+
+
‘program_date_time’
+

Generate EXT-X-PROGRAM-DATE-TIME tags. +

+
+
‘second_level_segment_index’
+

Make it possible to use segment indexes as %%d in the +hls_segment_filename option expression besides date/time values when +strftime option is on. To get fixed width numbers with trailing zeroes, %%0xd format +is available where x is the required width. +

+
+
‘second_level_segment_size’
+

Make it possible to use segment sizes (counted in bytes) as %%s in +hls_segment_filename option expression besides date/time values when +strftime is on. To get fixed width numbers with trailing zeroes, %%0xs format +is available where x is the required width. +

+
+
‘second_level_segment_duration’
+

Make it possible to use segment duration (calculated in microseconds) as %%t in +hls_segment_filename option expression besides date/time values when +strftime is on. To get fixed width numbers with trailing zeroes, %%0xt format +is available where x is the required width. +

+

For example: +

+
ffmpeg -i sample.mpeg \
+   -f hls -hls_time 3 -hls_list_size 5 \
+   -hls_flags second_level_segment_index+second_level_segment_size+second_level_segment_duration \
+   -strftime 1 -strftime_mkdir 1 -hls_segment_filename "segment_%Y%m%d%H%M%S_%%04d_%%08s_%%013t.ts" stream.m3u8
+
+

will produce segments like this: +segment_20170102194334_0003_00122200_0000003000000.ts, segment_20170102194334_0004_00120072_0000003000000.ts etc. +

+
+
‘temp_file’
+

Write segment data to filename.tmp and rename to filename only once the +segment is complete. +

+

A webserver serving up segments can be configured to reject requests to *.tmp to +prevent access to in-progress segments before they have been added to the m3u8 +playlist. +

+

This flag also affects how m3u8 playlist files are created. If this flag is set, +all playlist files will be written into a temporary file and renamed after they +are complete, similarly as segments are handled. But playlists with file +protocol and with hls_playlist_type type other than ‘vod’ are +always written into a temporary file regardless of this flag. +

+

Master playlist files specified with master_pl_name, if any, with +file protocol, are always written into temporary file regardless of this +flag if master_pl_publish_rate value is other than zero. +

+
+ +
+
hls_playlist_type type
+

If type is ‘event’, emit #EXT-X-PLAYLIST-TYPE:EVENT in the m3u8 +header. This forces hls_list_size to 0; the playlist can only be +appended to. +

+

If type is ‘vod’, emit #EXT-X-PLAYLIST-TYPE:VOD in the m3u8 +header. This forces hls_list_size to 0; the playlist must not change. +

+
+
method method
+

Use the given HTTP method to create the hls files. +

+

For example: +

+
ffmpeg -re -i in.ts -f hls -method PUT http://example.com/live/out.m3u8
+
+

will upload all the mpegts segment files to the HTTP server using the HTTP PUT +method, and update the m3u8 files every refresh times using the same +method. Note that the HTTP server must support the given method for uploading +files. +

+
+
http_user_agent agent
+

Override User-Agent field in HTTP header. Applicable only for HTTP output. +

+
+
var_stream_map stream_map
+

Specify a map string defining how to group the audio, video and subtitle streams +into different variant streams. The variant stream groups are separated by +space. +

+

Expected string format is like this "a:0,v:0 a:1,v:1 ....". Here a:, v:, s: are +the keys to specify audio, video and subtitle streams respectively. +Allowed values are 0 to 9 (limited just based on practical usage). +

+

When there are two or more variant streams, the output filename pattern must +contain the string "%v": this string specifies the position of variant stream +index in the output media playlist filenames. The string "%v" may be present in +the filename or in the last directory name containing the file. If the string is +present in the directory name, then sub-directories are created after expanding +the directory name pattern. This enables creation of variant streams in +subdirectories. +

+

A few examples follow. +

+
    +
  • Create two hls variant streams. The first variant stream will contain video +stream of bitrate 1000k and audio stream of bitrate 64k and the second variant +stream will contain video stream of bitrate 256k and audio stream of bitrate +32k. Here, two media playlist with file names out_0.m3u8 and +out_1.m3u8 will be created. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
    +  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • If you want something meaningful text instead of indexes in result names, you +may specify names for each or some of the variants. The following example will +create two hls variant streams as in the previous one. But here, the two media +playlist with file names out_my_hd.m3u8 and out_my_sd.m3u8 will be +created. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
    +  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0,name:my_hd v:1,a:1,name:my_sd" \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create three hls variant streams. The first variant stream will be a video only +stream with video bitrate 1000k, the second variant stream will be an audio only +stream with bitrate 64k and the third variant stream will be a video only stream +with bitrate 256k. Here, three media playlist with file names out_0.m3u8, +out_1.m3u8 and out_2.m3u8 will be created. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k \
    +  -map 0:v -map 0:a -map 0:v -f hls -var_stream_map "v:0 a:0 v:1" \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create the variant streams in subdirectories. Here, the first media playlist is +created at http://example.com/live/vs_0/out.m3u8 and the second one at +http://example.com/live/vs_1/out.m3u8. +
    +
    ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
    +  -map 0:v -map 0:a -map 0:v -map 0:a -f hls -var_stream_map "v:0,a:0 v:1,a:1" \
    +  http://example.com/live/vs_%v/out.m3u8
    +
    + +
  • Create two audio only and two video only variant streams. In addition to the +#EXT-X-STREAM-INF tag for each variant stream in the master playlist, the +#EXT-X-MEDIA tag is also added for the two audio only variant streams and +they are mapped to the two video only variant streams with audio group names +’aud_low’ and ’aud_high’. +By default, a single hls variant containing all the encoded streams is created. +
    +
    ffmpeg -re -i in.ts -b:a:0 32k -b:a:1 64k -b:v:0 1000k -b:v:1 3000k  \
    +  -map 0:a -map 0:a -map 0:v -map 0:v -f hls \
    +  -var_stream_map "a:0,agroup:aud_low a:1,agroup:aud_high v:0,agroup:aud_low v:1,agroup:aud_high" \
    +  -master_pl_name master.m3u8 \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • +Create two audio only and one video only variant streams. In addition to the +#EXT-X-STREAM-INF tag for each variant stream in the master playlist, the +#EXT-X-MEDIA tag is also added for the two audio only variant streams and +they are mapped to the one video only variant streams with audio group name +’aud_low’, and the audio group have default stat is NO or YES. +By default, a single hls variant containing all the encoded streams is created. +
    +
    ffmpeg -re -i in.ts -b:a:0 32k -b:a:1 64k -b:v:0 1000k \
    +  -map 0:a -map 0:a -map 0:v -f hls \
    +  -var_stream_map "a:0,agroup:aud_low,default:yes a:1,agroup:aud_low v:0,agroup:aud_low" \
    +  -master_pl_name master.m3u8 \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create two audio only and one video only variant streams. In addition to the +#EXT-X-STREAM-INF tag for each variant stream in the master playlist, the +#EXT-X-MEDIA tag is also added for the two audio only variant streams and +they are mapped to the one video only variant streams with audio group name +’aud_low’, and the audio group have default stat is NO or YES, and one audio +have and language is named ENG, the other audio language is named CHN. By +default, a single hls variant containing all the encoded streams is created. +
    +
    ffmpeg -re -i in.ts -b:a:0 32k -b:a:1 64k -b:v:0 1000k \
    +  -map 0:a -map 0:a -map 0:v -f hls \
    +  -var_stream_map "a:0,agroup:aud_low,default:yes,language:ENG a:1,agroup:aud_low,language:CHN v:0,agroup:aud_low" \
    +  -master_pl_name master.m3u8 \
    +  http://example.com/live/out_%v.m3u8
    +
    + +
  • Create a single variant stream. Add the #EXT-X-MEDIA tag with +TYPE=SUBTITLES in the master playlist with webvtt subtitle group name +’subtitle’ and optional subtitle name, e.g. ’English’. Make sure the input +file has one text subtitle stream at least. +
    +
    ffmpeg -y -i input_with_subtitle.mkv \
    + -b:v:0 5250k -c:v h264 -pix_fmt yuv420p -profile:v main -level 4.1 \
    + -b:a:0 256k \
    + -c:s webvtt -c:a mp2 -ar 48000 -ac 2 -map 0:v -map 0:a:0 -map 0:s:0 \
    + -f hls -var_stream_map "v:0,a:0,s:0,sgroup:subtitle,sname:English" \
    + -master_pl_name master.m3u8 -t 300 -hls_time 10 -hls_init_time 4 -hls_list_size \
    + 10 -master_pl_publish_rate 10 -hls_flags \
    + delete_segments+discont_start+split_by_time ./tmp/video.m3u8
    +
    +
+ +
+
cc_stream_map cc_stream_map
+

Map string which specifies different closed captions groups and their +attributes. The closed captions stream groups are separated by space. +

+

Expected string format is like this +"ccgroup:<group name>,instreamid:<INSTREAM-ID>,language:<language code> ....". +’ccgroup’ and ’instreamid’ are mandatory attributes. ’language’ is an optional +attribute. +

+

The closed captions groups configured using this option are mapped to different +variant streams by providing the same ’ccgroup’ name in the +var_stream_map string. +

+

For example: +

+
ffmpeg -re -i in.ts -b:v:0 1000k -b:v:1 256k -b:a:0 64k -b:a:1 32k \
+  -a53cc:0 1 -a53cc:1 1 \
+  -map 0:v -map 0:a -map 0:v -map 0:a -f hls \
+  -cc_stream_map "ccgroup:cc,instreamid:CC1,language:en ccgroup:cc,instreamid:CC2,language:sp" \
+  -var_stream_map "v:0,a:0,ccgroup:cc v:1,a:1,ccgroup:cc" \
+  -master_pl_name master.m3u8 \
+  http://example.com/live/out_%v.m3u8
+
+

will add two #EXT-X-MEDIA tags with TYPE=CLOSED-CAPTIONS in the +master playlist for the INSTREAM-IDs ’CC1’ and ’CC2’. Also, it will add +CLOSED-CAPTIONS attribute with group name ’cc’ for the two output variant +streams. +

+

If var_stream_map is not set, then the first available ccgroup in +cc_stream_map is mapped to the output variant stream. +

+

For example: +

+
ffmpeg -re -i in.ts -b:v 1000k -b:a 64k -a53cc 1 -f hls \
+  -cc_stream_map "ccgroup:cc,instreamid:CC1,language:en" \
+  -master_pl_name master.m3u8 \
+  http://example.com/live/out.m3u8
+
+

this will add #EXT-X-MEDIA tag with TYPE=CLOSED-CAPTIONS in the +master playlist with group name ’cc’, language ’en’ (english) and INSTREAM-ID +’CC1’. Also, it will add CLOSED-CAPTIONS attribute with group name ’cc’ +for the output variant stream. +

+
+
master_pl_name name
+

Create HLS master playlist with the given name. +

+

For example: +

+
ffmpeg -re -i in.ts -f hls -master_pl_name master.m3u8 http://example.com/live/out.m3u8
+
+

creates an HLS master playlist with name master.m3u8 which is published +at http://example.com/live/. +

+
+
master_pl_publish_rate count
+

Publish master play list repeatedly every after specified number of segment intervals. +

+

For example: +

+
ffmpeg -re -i in.ts -f hls -master_pl_name master.m3u8 \
+-hls_time 2 -master_pl_publish_rate 30 http://example.com/live/out.m3u8
+
+

creates an HLS master playlist with name master.m3u8 and keeps +publishing it repeatedly every after 30 segments i.e. every after 60s. +

+
+
http_persistent bool
+

Use persistent HTTP connections. Applicable only for HTTP output. +

+
+
timeout timeout
+

Set timeout for socket I/O operations. Applicable only for HTTP output. +

+
+
ignore_io_errors bool
+

Ignore IO errors during open, write and delete. Useful for long-duration runs with network output. +

+
+
headers headers
+

Set custom HTTP headers, can override built in default headers. Applicable only for HTTP output. +

+
+ + +

4.47 iamf

+

Immersive Audio Model and Formats (IAMF) muxer. +

+

IAMF is used to provide immersive audio content for presentation on a wide range +of devices in both streaming and offline applications. These applications +include internet audio streaming, multicasting/broadcasting services, file +download, gaming, communication, virtual and augmented reality, and others. In +these applications, audio may be played back on a wide range of devices, e.g., +headphones, mobile phones, tablets, TVs, sound bars, home theater systems, and +big screens. +

+

This format was promoted and designed by Alliance for Open Media. +

+

For more information about this format, see https://aomedia.org/iamf/. +

+ +

4.48 ico

+ +

ICO file muxer. +

+

Microsoft’s icon file format (ICO) has some strict limitations that should be noted: +

+
    +
  • Size cannot exceed 256 pixels in any dimension + +
  • Only BMP and PNG images can be stored + +
  • If a BMP image is used, it must be one of the following pixel formats: +
    +
    BMP Bit Depth      FFmpeg Pixel Format
    +1bit               pal8
    +4bit               pal8
    +8bit               pal8
    +16bit              rgb555le
    +24bit              bgr24
    +32bit              bgra
    +
    + +
  • If a BMP image is used, it must use the BITMAPINFOHEADER DIB header + +
  • If a PNG image is used, it must use the rgba pixel format +
+ + +

4.49 ilbc

+

Internet Low Bitrate Codec (iLBC) raw muxer. +

+

It accepts a single ‘ilbc’ audio stream. +

+ +

4.50 image2, image2pipe

+

Image file muxer. +

+

The ‘image2’ muxer writes video frames to image files. +

+

The output filenames are specified by a pattern, which can be used to +produce sequentially numbered series of files. +The pattern may contain the string "%d" or "%0Nd", this string +specifies the position of the characters representing a numbering in +the filenames. If the form "%0Nd" is used, the string +representing the number in each filename is 0-padded to N +digits. The literal character ’%’ can be specified in the pattern with +the string "%%". +

+

If the pattern contains "%d" or "%0Nd", the first filename of +the file list specified will contain the number 1, all the following +numbers will be sequential. +

+

The pattern may contain a suffix which is used to automatically +determine the format of the image files to write. +

+

For example the pattern "img-%03d.bmp" will specify a sequence of +filenames of the form img-001.bmp, img-002.bmp, ..., +img-010.bmp, etc. +The pattern "img%%-%d.jpg" will specify a sequence of filenames of the +form img%-1.jpg, img%-2.jpg, ..., img%-10.jpg, +etc. +

+

The image muxer supports the .Y.U.V image file format. This format is +special in that each image frame consists of three files, for +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. +

+

The ‘image2pipe’ muxer accepts the same options as the ‘image2’ muxer, +but ignores the pattern verification and expansion, as it is supposed to write +to the command output rather than to an actual stored file. +

+ +

4.50.1 Options

+
+
frame_pts bool
+

If set to 1, expand the filename with the packet PTS (presentation time stamp). +Default value is 0. +

+
+
start_number count
+

Start the sequence from the specified number. Default value is 1. +

+
+
update bool
+

If set to 1, the filename will always be interpreted as just a +filename, not a pattern, and the corresponding file will be continuously +overwritten with new images. Default value is 0. +

+
+
strftime bool
+

If set to 1, expand the filename with date and time information from +strftime(). Default value is 0. +

+
+
atomic_writing bool
+

Write output to a temporary file, which is renamed to target filename once +writing is completed. Default is disabled. +

+
+
protocol_opts options_list
+

Set protocol options as a :-separated list of key=value parameters. Values +containing the : special character must be escaped. +

+
+ + +

4.50.2 Examples

+
    +
  • Use ffmpeg for creating a sequence of files img-001.jpeg, +img-002.jpeg, ..., taking one image every second from the input video: +
    +
    ffmpeg -i in.avi -vsync cfr -r 1 -f image2 'img-%03d.jpeg'
    +
    + +

    Note that with ffmpeg, if the format is not specified with the +-f option and the output filename specifies an image file +format, the image2 muxer is automatically selected, so the previous +command can be written as: +

    +
    ffmpeg -i in.avi -vsync cfr -r 1 'img-%03d.jpeg'
    +
    + +

    Note also that the pattern must not necessarily contain "%d" or +"%0Nd", for example to create a single image file +img.jpeg from the start of the input video you can employ the command: +

    +
    ffmpeg -i in.avi -f image2 -frames:v 1 img.jpeg
    +
    + +
  • The strftime option allows you to expand the filename with +date and time information. Check the documentation of +the strftime() function for the syntax. + +

    To generate image files from the strftime() "%Y-%m-%d_%H-%M-%S" pattern, +the following ffmpeg command can be used: +

    +
    ffmpeg -f v4l2 -r 1 -i /dev/video0 -f image2 -strftime 1 "%Y-%m-%d_%H-%M-%S.jpg"
    +
    + +
  • Set the file name with current frame’s PTS: +
    +
    ffmpeg -f v4l2 -r 1 -i /dev/video0 -copyts -f image2 -frame_pts true %d.jpg
    +
    + +
  • Publish contents of your desktop directly to a WebDAV server every second: +
    +
    ffmpeg -f x11grab -framerate 1 -i :0.0 -q:v 6 -update 1 -protocol_opts method=PUT http://example.com/desktop.jpg
    +
    +
+ + +

4.51 ircam

+

Berkeley / IRCAM / CARL Sound Filesystem (BICSF) format muxer. +

+

The Berkeley/IRCAM/CARL Sound Format, developed in the 1980s, is a result of the +merging of several different earlier sound file formats and systems including +the csound system developed by Dr Gareth Loy at the Computer Audio Research Lab +(CARL) at UC San Diego, the IRCAM sound file system developed by Rob Gross and +Dan Timis at the Institut de Recherche et Coordination Acoustique / Musique in +Paris and the Berkeley Fast Filesystem. +

+

It was developed initially as part of the Berkeley/IRCAM/CARL Sound Filesystem, +a suite of programs designed to implement a filesystem for audio applications +running under Berkeley UNIX. It was particularly popular in academic music +research centres, and was used a number of times in the creation of early +computer-generated compositions. +

+

This muxer accepts a single audio stream containing PCM data. +

+ +

4.52 ivf

+

On2 IVF muxer. +

+

IVF was developed by On2 Technologies (formerly known as Duck +Corporation), to store internally developed codecs. +

+

This muxer accepts a single ‘vp8’, ‘vp9’, or ‘av1’ +video stream. +

+ +

4.53 jacosub

+

JACOsub subtitle format muxer. +

+

This muxer accepts a single ‘jacosub’ subtitles stream. +

+

For more information about the format, see +http://unicorn.us.com/jacosub/jscripts.html. +

+ +

4.54 kvag

+

Simon & Schuster Interactive VAG muxer. +

+

This custom VAG container is used by some Simon & Schuster Interactive +games such as "Real War", and "Real War: Rogue States". +

+

This muxer accepts a single ‘adpcm_ima_ssi’ audio stream. +

+ +

4.55 lc3

+

Bluetooth SIG Low Complexity Communication Codec audio (LC3), or +ETSI TS 103 634 Low Complexity Communication Codec plus (LC3plus). +

+

This muxer accepts a single ‘lc3’ audio stream. +

+ +

4.56 lrc

+

LRC lyrics file format muxer. +

+

LRC (short for LyRiCs) is a computer file format that synchronizes +song lyrics with an audio file, such as MP3, Vorbis, or MIDI. +

+

This muxer accepts a single ‘subrip’ or ‘text’ subtitles stream. +

+ +

4.56.1 Metadata

+

The following metadata tags are converted to the format corresponding +metadata: +

+
+
title
+
album
+
artist
+
author
+
creator
+
encoder
+
encoder_version
+
+ +

If ‘encoder_version’ is not explicitly set, it is automatically +set to the libavformat version. +

+ +

4.57 matroska

+

Matroska container muxer. +

+

This muxer implements the matroska and webm container specs. +

+ +

4.57.1 Metadata

+

The recognized metadata settings in this muxer are: +

+
+
title
+

Set title name provided to a single track. This gets mapped to +the FileDescription element for a stream written as attachment. +

+
+
language
+

Specify the language of the track in the Matroska languages form. +

+

The language can be either the 3 letters bibliographic ISO-639-2 (ISO +639-2/B) form (like "fre" for French), or a language code mixed with a +country code for specialities in languages (like "fre-ca" for Canadian +French). +

+
+
stereo_mode
+

Set stereo 3D video layout of two views in a single video track. +

+

The following values are recognized: +

+
‘mono’
+

video is not stereo +

+
‘left_right’
+

Both views are arranged side by side, Left-eye view is on the left +

+
‘bottom_top’
+

Both views are arranged in top-bottom orientation, Left-eye view is at bottom +

+
‘top_bottom’
+

Both views are arranged in top-bottom orientation, Left-eye view is on top +

+
‘checkerboard_rl’
+

Each view is arranged in a checkerboard interleaved pattern, Left-eye view being first +

+
‘checkerboard_lr’
+

Each view is arranged in a checkerboard interleaved pattern, Right-eye view being first +

+
‘row_interleaved_rl’
+

Each view is constituted by a row based interleaving, Right-eye view is first row +

+
‘row_interleaved_lr’
+

Each view is constituted by a row based interleaving, Left-eye view is first row +

+
‘col_interleaved_rl’
+

Both views are arranged in a column based interleaving manner, Right-eye view is first column +

+
‘col_interleaved_lr’
+

Both views are arranged in a column based interleaving manner, Left-eye view is first column +

+
‘anaglyph_cyan_red’
+

All frames are in anaglyph format viewable through red-cyan filters +

+
‘right_left’
+

Both views are arranged side by side, Right-eye view is on the left +

+
‘anaglyph_green_magenta’
+

All frames are in anaglyph format viewable through green-magenta filters +

+
‘block_lr’
+

Both eyes laced in one Block, Left-eye view is first +

+
‘block_rl’
+

Both eyes laced in one Block, Right-eye view is first +

+
+
+
+ +

For example a 3D WebM clip can be created using the following command line: +

+
ffmpeg -i sample_left_right_clip.mpg -an -c:v libvpx -metadata stereo_mode=left_right -y stereo_clip.webm
+
+ + +

4.57.2 Options

+
+
reserve_index_space size
+

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 size bytes +of space in the file header and then try to write the cues there when the muxing +finishes. If the reserved space does not suffice, no Cues will be written, the +file will be finalized and writing the trailer will return an error. +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. +

+
+
cues_to_front bool
+

If set, the muxer will write the index at the beginning of the file +by shifting the main data if necessary. This can be combined with +reserve_index_space in which case the data is only shifted if +the initially reserved space turns out to be insufficient. +

+

This option is ignored if the output is unseekable. +

+
+
cluster_size_limit size
+

Store at most the provided amount of bytes in a cluster. +

+

If not specified, the limit is set automatically to a sensible +hardcoded fixed value. +

+
+
cluster_time_limit duration
+

Store at most the provided number of milliseconds in a cluster. +

+

If not specified, the limit is set automatically to a sensible +hardcoded fixed value. +

+
+
dash bool
+

Create a WebM file conforming to WebM DASH specification. By default +it is set to false. +

+
+
dash_track_number index
+

Track number for the DASH stream. By default it is set to 1. +

+
+
live bool
+

Write files assuming it is a live stream. By default it is set to +false. +

+
+
allow_raw_vfw bool
+

Allow raw VFW mode. By default it is set to false. +

+
+
flipped_raw_rgb bool
+

If set to true, store positive height for raw RGB bitmaps, which indicates +bitmap is stored bottom-up. Note that this option does not flip the bitmap +which has to be done manually beforehand, e.g. by using the ‘vflip’ filter. +Default is false and indicates bitmap is stored top down. +

+
+
write_crc32 bool
+

Write a CRC32 element inside every Level 1 element. By default it is +set to true. This option is ignored for WebM. +

+
+
default_mode mode
+

Control how the FlagDefault of the output tracks will be set. +It influences which tracks players should play by default. The default mode +is ‘passthrough’. +

+
‘infer’
+

Every track with disposition default will have the FlagDefault set. +Additionally, for each type of track (audio, video or subtitle), if no track +with disposition default of this type exists, then the first track of this type +will be marked as default (if existing). This ensures that the default flag +is set in a sensible way even if the input originated from containers that +lack the concept of default tracks. +

+
‘infer_no_subs’
+

This mode is the same as infer except that if no subtitle track with +disposition default exists, no subtitle track will be marked as default. +

+
‘passthrough’
+

In this mode the FlagDefault is set if and only if the AV_DISPOSITION_DEFAULT +flag is set in the disposition of the corresponding stream. +

+
+
+
+ + +

4.58 md5

+

MD5 testing format. +

+

This is a variant of the hash muxer. Unlike that muxer, it +defaults to using the MD5 hash function. +

+

See also the hash and framemd5 muxers. +

+ +

4.58.1 Examples

+
    +
  • To compute the MD5 hash of the input converted to raw +audio and video, and store it in the file out.md5: +
    +
    ffmpeg -i INPUT -f md5 out.md5
    +
    + +
  • To print the MD5 hash to stdout: +
    +
    ffmpeg -i INPUT -f md5 -
    +
    +
+ + +

4.59 mcc

+

Muxer for MacCaption MCC files, it supports MCC versions 1.0 and 2.0. +MCC files store VANC data, which can include closed captions (EIA-608 and CEA-708), ancillary time code, pan-scan data, etc. +

+ +

4.59.1 Options

+ +

The muxer options are: +

+
+
override_time_code_rate
+

Override the Time Code Rate value in the output. Defaults to trying to deduce from the stream’s time_base, which often doesn’t work. +

+
use_u_alias
+

Use the U alias for the byte sequence E1h 00h 00h 00h. +Disabled by default because some .mcc files disagree on whether it has 2 or 3 zero bytes. +

+
mcc_version
+

The MCC file format version. Must be either 1 or 2, defaults to 2. +

+
creation_program
+

The creation program. Defaults to this version of FFmpeg. +

+
creation_time
+

The creation time. Defaults to the current time. +

+
+ + +

4.59.2 Examples

+
    +
  • Extract a MXF SMPTE_436M_ANC stream from a MXF file and write it to a MCC file at 30 fps. +
    +
    ffmpeg -i input.mxf -c copy -map 0:d -override_time_code_rate 30 out.mcc
    +
    + +
  • Extract EIA-608/CTA-708 closed captions from a .mp4 file and write them to a MCC file at 29.97 fps. +
    +
    ffmpeg -f lavfi -i "movie=input.mp4[out+subcc]" -c:s copy -map 0:s -override_time_code_rate 30000/1001 out.mcc
    +
    +
+ + +

4.60 microdvd

+

MicroDVD subtitle format muxer. +

+

This muxer accepts a single ‘microdvd’ subtitles stream. +

+ +

4.61 mmf

+

Synthetic music Mobile Application Format (SMAF) format muxer. +

+

SMAF is a music data format specified by Yamaha for portable +electronic devices, such as mobile phones and personal digital +assistants. +

+

This muxer accepts a single ‘adpcm_yamaha’ audio stream. +

+ +

4.62 mp3

+ +

The MP3 muxer writes a raw MP3 stream with the following optional features: +

    +
  • An ID3v2 metadata header at the beginning (enabled by default). Versions 2.3 and +2.4 are supported, the id3v2_version private option controls which one is +used (3 or 4). Setting id3v2_version to 0 disables the ID3v2 header +completely. + +

    The muxer supports writing attached pictures (APIC frames) to the ID3v2 header. +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 title and comment map +to APIC description and picture type respectively. See +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. +

    +
  • A Xing/LAME frame right after the ID3v2 header (if present). It is enabled by +default, but will be written only if the output is seekable. The +write_xing private option can be used to disable it. The frame contains +various information that may be useful to the decoder, like the audio duration +or encoder delay. + +
  • A legacy ID3v1 tag at the end of the file (disabled by default). It may be +enabled with the write_id3v1 private option, but as its capabilities are +very limited, its usage is not recommended. +
+ +

Examples: +

+

Write an mp3 with an ID3v2.3 header and an ID3v1 footer: +

+
ffmpeg -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3
+
+ +

To attach a picture to an mp3 file select both the audio and the picture stream +with map: +

+
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
+
+ +

Write a "clean" MP3 without any extra features: +

+
ffmpeg -i input.wav -write_xing 0 -id3v2_version 0 out.mp3
+
+ + +

4.63 mpegts

+ +

MPEG transport stream muxer. +

+

This muxer implements ISO 13818-1 and part of ETSI EN 300 468. +

+

The recognized metadata settings in mpegts muxer are service_provider +and service_name. If they are not set the default for +service_provider is ‘FFmpeg’ and the default for +service_name is ‘Service01’. +

+ +

4.63.1 Options

+ +

The muxer options are: +

+
+
mpegts_transport_stream_id integer
+

Set the ‘transport_stream_id’. This identifies a transponder in DVB. +Default is 0x0001. +

+
+
mpegts_original_network_id integer
+

Set the ‘original_network_id’. This is unique identifier of a +network in DVB. Its main use is in the unique identification of a service +through the path ‘Original_Network_ID, Transport_Stream_ID’. Default +is 0x0001. +

+
+
mpegts_service_id integer
+

Set the ‘service_id’, also known as program in DVB. Default is +0x0001. +

+
+
mpegts_service_type integer
+

Set the program ‘service_type’. Default is digital_tv. +Accepts the following options: +

+
‘hex_value’
+

Any hexadecimal value between 0x01 and 0xff as defined in +ETSI 300 468. +

+
‘digital_tv’
+

Digital TV service. +

+
‘digital_radio’
+

Digital Radio service. +

+
‘teletext’
+

Teletext service. +

+
‘advanced_codec_digital_radio’
+

Advanced Codec Digital Radio service. +

+
‘mpeg2_digital_hdtv’
+

MPEG2 Digital HDTV service. +

+
‘advanced_codec_digital_sdtv’
+

Advanced Codec Digital SDTV service. +

+
‘advanced_codec_digital_hdtv’
+

Advanced Codec Digital HDTV service. +

+
+ +
+
mpegts_pmt_start_pid integer
+

Set the first PID for PMTs. Default is 0x1000, minimum is 0x0020, +maximum is 0x1ffa. This option has no effect in m2ts mode where the PMT +PID is fixed 0x0100. +

+
+
mpegts_start_pid integer
+

Set the first PID for elementary streams. Default is 0x0100, minimum is +0x0020, maximum is 0x1ffa. This option has no effect in m2ts mode +where the elementary stream PIDs are fixed. +

+
+
mpegts_m2ts_mode boolean
+

Enable m2ts mode if set to 1. Default value is -1 which +disables m2ts mode. +

+
+
muxrate integer
+

Set a constant muxrate. Default is VBR. +

+
+
pes_payload_size integer
+

Set minimum PES packet payload in bytes. Default is 2930. +

+
+
mpegts_flags flags
+

Set mpegts flags. Accepts the following options: +

+
‘resend_headers’
+

Reemit PAT/PMT before writing the next packet. +

+
‘latm’
+

Use LATM packetization for AAC. +

+
‘pat_pmt_at_frames’
+

Reemit PAT and PMT at each video frame. +

+
‘system_b’
+

Conform to System B (DVB) instead of System A (ATSC). +

+
‘initial_discontinuity’
+

Mark the initial packet of each stream as discontinuity. +

+
‘nit’
+

Emit NIT table. +

+
‘omit_rai’
+

Disable writing of random access indicator. +

+
+ +
+
mpegts_copyts boolean
+

Preserve original timestamps, if value is set to 1. Default value +is -1, which results in shifting timestamps so that they start from 0. +

+
+
omit_video_pes_length boolean
+

Omit the PES packet length for video packets. Default is 1 (true). +

+
+
pcr_period integer
+

Override the default PCR retransmission time in milliseconds. Default is +-1 which means that the PCR interval will be determined automatically: +20 ms is used for CBR streams, the highest multiple of the frame duration which +is less than 100 ms is used for VBR streams. +

+
+
pat_period duration
+

Maximum time in seconds between PAT/PMT tables. Default is 0.1. +

+
+
sdt_period duration
+

Maximum time in seconds between SDT tables. Default is 0.5. +

+
+
nit_period duration
+

Maximum time in seconds between NIT tables. Default is 0.5. +

+
+
tables_version integer
+

Set PAT, PMT, SDT and NIT 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: +

+
+
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
+...
+
+
+
+ + +

4.63.2 Example

+ +
+
ffmpeg -i file.mpg -c copy \
+     -mpegts_original_network_id 0x1122 \
+     -mpegts_transport_stream_id 0x3344 \
+     -mpegts_service_id 0x5566 \
+     -mpegts_pmt_start_pid 0x1500 \
+     -mpegts_start_pid 0x150 \
+     -metadata service_provider="Some provider" \
+     -metadata service_name="Some Channel" \
+     out.ts
+
+ + +

4.64 mxf, mxf_d10, mxf_opatom

+ +

MXF muxer. +

+ +

4.64.1 Options

+ +

The muxer options are: +

+
+
store_user_comments bool
+

Set if user comments should be stored if available or never. +IRT D-10 does not allow user comments. The default is thus to write them for +mxf and mxf_opatom but not for mxf_d10 +

+
+ + +

4.65 null

+ +

Null muxer. +

+

This muxer does not generate any output file, it is mainly useful for +testing or benchmarking purposes. +

+

For example to benchmark decoding with ffmpeg you can use the +command: +

+
ffmpeg -benchmark -i INPUT -f null out.null
+
+ +

Note that the above command does not read or write the out.null +file, but specifying the output file is required by the ffmpeg +syntax. +

+

Alternatively you can write the command as: +

+
ffmpeg -benchmark -i INPUT -f null -
+
+ + +

4.66 nut

+ +
+
-syncpoints flags
+

Change the syncpoint usage in nut: +

+
default use the normal low-overhead seeking aids.
+
none do not use the syncpoints at all, reducing the overhead but making the stream non-seekable;
+

Use of this option is not recommended, as the resulting files are very damage + sensitive and seeking is not possible. Also in general the overhead from + syncpoints is negligible. Note, -write_index 0 can be used to disable + all growing data tables, allowing to mux endless streams with limited memory + and without these disadvantages. +

+
timestamped extend the syncpoint with a wallclock field.
+
+

The none and timestamped flags are experimental. +

+
-write_index bool
+

Write index at the end, the default is to write an index. +

+
+ +
+
ffmpeg -i INPUT -f_strict experimental -syncpoints none - | processor
+
+ + +

4.67 ogg

+ +

Ogg container muxer. +

+
+
-page_duration duration
+

Preferred page duration, in microseconds. The muxer will attempt to create +pages that are approximately 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. +

+
-serial_offset value
+

Serial value from which to set the streams serial number. +Setting it to different and sufficiently large values ensures that the produced +ogg files can be safely chained. +

+
+
+ + +

4.68 rcwt

+ +

RCWT (Raw Captions With Time) is a format native to ccextractor, a commonly +used open source tool for processing 608/708 Closed Captions (CC) sources. +It can be used to archive the original extracted CC bitstream and to produce +a source file for later processing or conversion. The format allows +for interoperability between ccextractor and FFmpeg, is simple to parse, +and can be used to create a backup of the CC presentation. +

+

This muxer implements the specification as of March 2024, which has +been stable and unchanged since April 2014. +

+

This muxer will have some nuances from the way that ccextractor muxes RCWT. +No compatibility issues when processing the output with ccextractor +have been observed as a result of this so far, but mileage may vary +and outputs will not be a bit-exact match. +

+

A free specification of RCWT can be found here: +https://github.com/CCExtractor/ccextractor/blob/master/docs/BINARY_FILE_FORMAT.TXT +

+ +

4.68.1 Examples

+ +
    +
  • Extract Closed Captions to RCWT using lavfi: +
    +
    ffmpeg -f lavfi -i "movie=INPUT.mkv[out+subcc]" -map 0:s:0 -c:s copy -f rcwt CC.rcwt.bin
    +
    +
+ + +

4.69 segment, stream_segment, ssegment

+ +

Basic stream segmenter. +

+

This muxer outputs streams to a number of separate files of nearly +fixed duration. Output filename pattern can be set in a fashion +similar to image2, or by using a strftime template if +the strftime option is enabled. +

+

stream_segment is a variant of the muxer used to write to +streaming output formats, i.e. which do not require global headers, +and is recommended for outputting e.g. to MPEG transport stream segments. +ssegment is a shorter alias for stream_segment. +

+

Every segment starts with a keyframe of the selected reference stream, +which is set through the reference_stream option. +

+

Note that if you want accurate splitting for a video file, you need to +make the input key frames correspond to the exact splitting times +expected by the segmenter, or the segment muxer will start the new +segment with the key frame found next after the specified start +time. +

+

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 segment_list. The list type is specified by the +segment_list_type option. The entry filenames in the segment +list are set by default to the basename of the corresponding segment +files. +

+

See also the hls muxer, which provides a more specific +implementation for HLS segmentation. +

+ +

4.69.1 Options

+ +

The segment muxer supports the following options: +

+
+
increment_tc 1|0
+

if set to 1, increment timecode between each segment +If this is selected, the input need to have +a timecode in the first video stream. Default value is +0. +

+
+
reference_stream specifier
+

Set the reference stream, as specified by the string specifier. +If specifier is set to auto, the reference is chosen +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. +

+
+
segment_format format
+

Override the inner container format, by default it is guessed by the filename +extension. +

+
+
segment_format_options options_list
+

Set output format options using a :-separated list of key=value +parameters. Values containing the : special character must be +escaped. +

+
+
segment_list name
+

Generate also a listfile named name. If not specified no +listfile is generated. +

+
+
segment_list_flags flags
+

Set flags affecting the segment list generation. +

+

It currently supports the following flags: +

+
‘cache’
+

Allow caching (only affects M3U8 list files). +

+
+
‘live’
+

Allow live-friendly file generation. +

+
+ +
+
segment_list_size size
+

Update the list file so that it contains at most size +segments. If 0 the list file will contain all the segments. Default +value is 0. +

+
+
segment_list_entry_prefix prefix
+

Prepend prefix to each entry. Useful to generate absolute paths. +By default no prefix is applied. +

+
+
segment_list_type type
+

Select the listing format. +

+

The following values are recognized: +

+
‘flat’
+

Generate a flat list for the created segments, one segment per line. +

+
+
‘csv, ext’
+

Generate a list for the created segments, one segment per line, +each line matching the format (comma-separated values): +

+
segment_filename,segment_start_time,segment_end_time
+
+ +

segment_filename is the name of the output file generated by the +muxer according to the provided pattern. CSV escaping (according to +RFC4180) is applied if required. +

+

segment_start_time and segment_end_time specify +the segment start and end time expressed in seconds. +

+

A list file with the suffix ".csv" or ".ext" will +auto-select this format. +

+

‘ext’ is deprecated in favor or ‘csv’. +

+
+
‘ffconcat’
+

Generate an ffconcat file for the created segments. The resulting file +can be read using the FFmpeg concat demuxer. +

+

A list file with the suffix ".ffcat" or ".ffconcat" will +auto-select this format. +

+
+
‘m3u8’
+

Generate an extended M3U8 file, version 3, compliant with +http://tools.ietf.org/id/draft-pantos-http-live-streaming. +

+

A list file with the suffix ".m3u8" will auto-select this format. +

+
+ +

If not specified the type is guessed from the list file name suffix. +

+
+
segment_time time
+

Set segment duration to time, the value must be a duration +specification. Default value is "2". See also the +segment_times option. +

+

Note that splitting may not be accurate, unless you force the +reference stream key-frames at the given time. See the introductory +notice and the examples below. +

+
+
min_seg_duration time
+

Set minimum segment duration to time, the value must be a duration +specification. This prevents the muxer ending segments at a duration below +this value. Only effective with segment_time. Default value is "0". +

+
+
segment_atclocktime 1|0
+

If set to "1" split at regular clock time intervals starting from 00:00 +o’clock. The time value specified in segment_time is +used for setting the length of the splitting interval. +

+

For example with segment_time set to "900" this makes it possible +to create files at 12:00 o’clock, 12:15, 12:30, etc. +

+

Default value is "0". +

+
+
segment_clocktime_offset duration
+

Delay the segment splitting times with the specified duration when using +segment_atclocktime. +

+

For example with segment_time set to "900" and +segment_clocktime_offset set to "300" this makes it possible to +create files at 12:05, 12:20, 12:35, etc. +

+

Default value is "0". +

+
+
segment_clocktime_wrap_duration duration
+

Force the segmenter to only start a new segment if a packet reaches the muxer +within the specified duration after the segmenting clock time. This way you +can make the segmenter more resilient to backward local time jumps, such as +leap seconds or transition to standard time from daylight savings time. +

+

Default is the maximum possible duration which means starting a new segment +regardless of the elapsed time since the last clock time. +

+
+
segment_time_delta delta
+

Specify the accuracy time when selecting the start time for a +segment, expressed as a duration specification. Default value is "0". +

+

When delta is specified a key-frame will start a new segment if its +PTS satisfies the relation: +

+
PTS >= start_time - time_delta
+
+ +

This option is useful when splitting video content, which is always +split at GOP boundaries, in case a key frame is found just before the +specified split time. +

+

In particular may be used in combination with the ffmpeg option +force_key_frames. The key frame times specified by +force_key_frames may not be set accurately because of rounding +issues, with the consequence that a key frame time may result set just +before the specified time. For constant frame rate videos a value of +1/(2*frame_rate) should address the worst case mismatch between +the specified time and the time set by force_key_frames. +

+
+
segment_times times
+

Specify a list of split points. times contains a list of comma +separated duration specifications, in increasing order. See also +the segment_time option. +

+
+
segment_frames frames
+

Specify a list of split video frame numbers. frames contains a +list of comma separated integer numbers, in increasing order. +

+

This option specifies to start a new segment whenever a reference +stream key frame is found and the sequential number (starting from 0) +of the frame is greater or equal to the next value in the list. +

+
+
segment_wrap limit
+

Wrap around segment index once it reaches limit. +

+
+
segment_start_number number
+

Set the sequence number of the first segment. Defaults to 0. +

+
+
strftime 1|0
+

Use the strftime function to define the name of the new +segments to write. If this is selected, the output segment name must +contain a strftime function template. Default value is +0. +

+
+
break_non_keyframes 1|0
+

If enabled, allow segments to start on frames other than keyframes. This +improves behavior on some players when the time between keyframes is +inconsistent, but may make things worse on others, and can cause some oddities +during seeking. Defaults to 0. +

+
+
reset_timestamps 1|0
+

Reset timestamps at the beginning 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 0 by default. +

+
+
initial_offset offset
+

Specify timestamp offset to apply to the output packet timestamps. The +argument must be a time duration specification, and defaults to 0. +

+
+
write_empty_segments 1|0
+

If enabled, write an empty segment if there are no packets during the period a +segment would usually span. Otherwise, the segment will be filled with the next +packet written. Defaults to 0. +

+
+ +

Make sure to require a closed GOP when encoding and to set the GOP +size to fit your segment time constraint. +

+ +

4.69.2 Examples

+ +
    +
  • Remux the content of file in.mkv to a list of segments +out-000.nut, out-001.nut, etc., and write the list of +generated segments to out.list: +
    +
    ffmpeg -i in.mkv -codec hevc -flags +cgop -g 60 -map 0 -f segment -segment_list out.list out%03d.nut
    +
    + +
  • Segment input and set output format options for the output segments: +
    +
    ffmpeg -i in.mkv -f segment -segment_time 10 -segment_format_options movflags=+faststart out%03d.mp4
    +
    + +
  • Segment the input file according to the split points specified by the +segment_times option: +
    +
    ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 out%03d.nut
    +
    + +
  • Use the ffmpeg force_key_frames +option to force key frames in the input at the specified location, together +with the segment option segment_time_delta to account for +possible roundings operated when setting key frame times. +
    +
    ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -codec:v mpeg4 -codec:a pcm_s16le -map 0 \
    +-f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 -segment_time_delta 0.05 out%03d.nut
    +
    +

    In order to force key frames on the input file, transcoding is +required. +

    +
  • Segment the input file by splitting the input file according to the +frame numbers sequence specified with the segment_frames option: +
    +
    ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_frames 100,200,300,500,800 out%03d.nut
    +
    + +
  • Convert the in.mkv to TS segments using the libx264 +and aac encoders: +
    +
    ffmpeg -i in.mkv -map 0 -codec:v libx264 -codec:a aac -f ssegment -segment_list out.list out%03d.ts
    +
    + +
  • Segment the input file, and create an M3U8 live playlist (can be used +as live HLS source): +
    +
    ffmpeg -re -i in.mkv -codec copy -map 0 -f segment -segment_list playlist.m3u8 \
    +-segment_list_flags +live -segment_time 10 out%03d.mkv
    +
    +
+ + +

4.70 smoothstreaming

+ +

Smooth Streaming muxer generates a set of files (Manifest, chunks) suitable for serving with conventional web server. +

+
+
window_size
+

Specify the number of fragments kept in the manifest. Default 0 (keep all). +

+
+
extra_window_size
+

Specify the number of fragments kept outside of the manifest before removing from disk. Default 5. +

+
+
lookahead_count
+

Specify the number of lookahead fragments. Default 2. +

+
+
min_frag_duration
+

Specify the minimum fragment duration (in microseconds). Default 5000000. +

+
+
remove_at_exit
+

Specify whether to remove all fragments when finished. Default 0 (do not remove). +

+
+
+ + +

4.71 streamhash

+ +

Per stream hash testing format. +

+

This muxer computes and prints a cryptographic hash of all the input frames, +on a per-stream basis. This can be used for equality checks without having +to do a complete binary comparison. +

+

By default audio frames are converted to signed 16-bit raw audio and +video frames to raw video before computing the hash, but the output +of explicit conversions to other codecs can also be used. Timestamps +are ignored. It uses the SHA-256 cryptographic hash function by default, +but supports several other algorithms. +

+

The output of the muxer consists of one line per stream of the form: +streamindex,streamtype,algo=hash, where +streamindex is the index of the mapped stream, streamtype is a +single character indicating the type of stream, algo is a short string +representing the hash function used, and hash is a hexadecimal number +representing the computed hash. +

+
+
hash algorithm
+

Use the cryptographic hash function specified by the string algorithm. +Supported values include MD5, murmur3, RIPEMD128, +RIPEMD160, RIPEMD256, RIPEMD320, SHA160, +SHA224, SHA256 (default), SHA512/224, SHA512/256, +SHA384, SHA512, CRC32 and adler32. +

+
+
+ + +

4.71.1 Examples

+ +

To compute the SHA-256 hash of the input converted to raw audio and +video, and store it in the file out.sha256: +

+
ffmpeg -i INPUT -f streamhash out.sha256
+
+ +

To print an MD5 hash to stdout use the command: +

+
ffmpeg -i INPUT -f streamhash -hash md5 -
+
+ +

See also the hash and framehash muxers. +

+ +

4.72 tee

+ +

The tee muxer can be used to write the same data to several outputs, such as files or streams. +It can be used, for example, to stream a video over a network and save it to disk at the same time. +

+

It is different from specifying several outputs to the ffmpeg +command-line tool. With the tee muxer, the audio and video data will be encoded only once. +With conventional multiple outputs, multiple encoding operations in parallel are initiated, +which can be a very expensive process. The tee muxer is not useful when using the libavformat API +directly because it is then possible to feed the same packets to several muxers directly. +

+

Since the tee muxer does not represent any particular output format, ffmpeg cannot auto-select +output streams. So all streams intended for output must be specified using -map. See +the examples below. +

+

Some encoders may need different options depending on the output format; +the auto-detection of this can not work with the tee muxer, so they need to be explicitly specified. +The main example is the global_header flag. +

+

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, those must be +escaped (see the "Quoting and escaping" +section in the ffmpeg-utils(1) manual). +

+ +

4.72.1 Options

+ +
+
use_fifo bool
+

If set to 1, slave outputs will be processed in separate threads using the fifo +muxer. This allows to compensate for different speed/latency/reliability of +outputs and setup transparent recovery. By default this feature is turned off. +

+
+
fifo_options
+

Options to pass to fifo pseudo-muxer instances. See fifo. +

+
+
+ +

Muxer options can be specified for each slave by prepending them as a list of +key=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. +

+

The following special options are also recognized: +

+
f
+

Specify the format name. Required if it cannot be guessed from the +output URL. +

+
+
bsfs[/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 +/. spec must be a stream specifier (see Format stream specifiers). +

+

If the stream specifier is not specified, the bitstream filters will be +applied to all streams in the output. This will cause that output operation +to fail if the output contains streams to which the bitstream filter cannot +be applied e.g. h264_mp4toannexb being applied to an output containing an audio stream. +

+

Options for a bitstream filter must be specified in the form of opt=value. +

+

Several bitstream filters can be specified, separated by ",". +

+
+
use_fifo bool
+

This allows to override tee muxer use_fifo option for individual slave muxer. +

+
+
fifo_options
+

This allows to override tee muxer fifo_options for individual slave muxer. +See fifo. +

+
+
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 mapped streams. This will cause that output operation to fail +if the output format does not accept all mapped streams. +

+

You may use multiple stream specifiers separated by commas (,) e.g.: a:0,v +

+
+
onfail
+

Specify behaviour on output failure. This can be set to either abort (which is +default) or ignore. abort will cause whole process to fail in case of failure +on this slave output. ignore will ignore failure on this output, so other outputs +will continue without being affected. +

+
+ + +

4.72.2 Examples

+ +
    +
  • Encode something and both archive it in a WebM file and stream it +as MPEG-TS over UDP: +
    +
    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/"
    +
    + +
  • As above, but continue streaming even if output to local file fails +(for example local drive fills up): +
    +
    ffmpeg -i ... -c:v libx264 -c:a mp2 -f tee -map 0:v -map 0:a
    +  "[onfail=ignore]archive-20121107.mkv|[f=mpegts]udp://10.0.1.255:1234/"
    +
    + +
  • Use ffmpeg to encode the input, and send the output +to three different destinations. The 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 out.aac in order to make it contain only +audio packets. +
    +
    ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac
    +       -f tee "[bsfs/v=dump_extra=freq=keyframe]out.ts|[movflags=+faststart]out.mp4|[select=a]out.aac"
    +
    + +
  • As above, but select only stream a:1 for the audio output. Note +that a second level escaping must be performed, as ":" is a special +character used to separate options. +
    +
    ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac
    +       -f tee "[bsfs/v=dump_extra=freq=keyframe]out.ts|[movflags=+faststart]out.mp4|[select=\'a:1\']out.aac"
    +
    +
+ + +

4.73 webm_chunk

+ +

WebM Live Chunk Muxer. +

+

This muxer writes out WebM headers and chunks as separate files which can be +consumed by clients that support WebM Live streams via DASH. +

+ +

4.73.1 Options

+ +

This muxer supports the following options: +

+
+
chunk_start_index
+

Index of the first chunk (defaults to 0). +

+
+
header
+

Filename of the header where the initialization data will be written. +

+
+
audio_chunk_duration
+

Duration of each audio chunk in milliseconds (defaults to 5000). +

+
+ + +

4.73.2 Example

+
+
ffmpeg -f v4l2 -i /dev/video0 \
+       -f alsa -i hw:0 \
+       -map 0:0 \
+       -c:v libvpx-vp9 \
+       -s 640x360 -keyint_min 30 -g 30 \
+       -f webm_chunk \
+       -header webm_live_video_360.hdr \
+       -chunk_start_index 1 \
+       webm_live_video_360_%d.chk \
+       -map 1:0 \
+       -c:a libvorbis \
+       -b:a 128k \
+       -f webm_chunk \
+       -header webm_live_audio_128.hdr \
+       -chunk_start_index 1 \
+       -audio_chunk_duration 1000 \
+       webm_live_audio_128_%d.chk
+
+ + +

4.74 webm_dash_manifest

+ +

WebM DASH Manifest muxer. +

+

This muxer implements the WebM DASH Manifest specification to generate the DASH +manifest XML. It also supports manifest generation for DASH live streams. +

+

For more information see: +

+ + + +

4.74.1 Options

+ +

This muxer supports the following options: +

+
+
adaptation_sets
+

This option has the following syntax: "id=x,streams=a,b,c id=y,streams=d,e" where x and y are the +unique identifiers of the adaptation sets and a,b,c,d and e are the indices of the corresponding +audio and video streams. Any number of adaptation sets can be added using this option. +

+
+
live
+

Set this to 1 to create a live stream DASH Manifest. Default: 0. +

+
+
chunk_start_index
+

Start index of the first chunk. This will go in the ‘startNumber’ attribute +of the ‘SegmentTemplate’ element in the manifest. Default: 0. +

+
+
chunk_duration_ms
+

Duration of each chunk in milliseconds. This will go in the ‘duration’ +attribute of the ‘SegmentTemplate’ element in the manifest. Default: 1000. +

+
+
utc_timing_url
+

URL of the page that will return the UTC timestamp in ISO format. This will go +in the ‘value’ attribute of the ‘UTCTiming’ element in the manifest. +Default: None. +

+
+
time_shift_buffer_depth
+

Smallest time (in seconds) shifting buffer for which any Representation is +guaranteed to be available. This will go in the ‘timeShiftBufferDepth’ +attribute of the ‘MPD’ element. Default: 60. +

+
+
minimum_update_period
+

Minimum update period (in seconds) of the manifest. This will go in the +‘minimumUpdatePeriod’ attribute of the ‘MPD’ element. Default: 0. +

+
+
+ + +

4.74.2 Example

+
+
ffmpeg -f webm_dash_manifest -i video1.webm \
+       -f webm_dash_manifest -i video2.webm \
+       -f webm_dash_manifest -i audio1.webm \
+       -f webm_dash_manifest -i audio2.webm \
+       -map 0 -map 1 -map 2 -map 3 \
+       -c copy \
+       -f webm_dash_manifest \
+       -adaptation_sets "id=0,streams=0,1 id=1,streams=2,3" \
+       manifest.xml
+
+ + +

4.75 whip

+ +

WebRTC (Real-Time Communication) muxer that supports sub-second latency streaming according to +the WHIP (WebRTC-HTTP ingestion protocol) specification. +

+

This is an experimental feature. +

+

It uses HTTP as a signaling protocol to exchange SDP capabilities and ICE lite candidates. Then, +it uses STUN binding requests and responses to establish a session over UDP. Subsequently, it +initiates a DTLS handshake to exchange the SRTP encryption keys. Lastly, it splits video and +audio frames into RTP packets and encrypts them using SRTP. +

+

Ensure that you use H.264 without B frames and Opus for the audio codec. For example, to convert +an input file with ffmpeg to WebRTC: +

+
ffmpeg -re -i input.mp4 -acodec libopus -ar 48000 -ac 2 \
+  -vcodec libx264 -profile:v baseline -tune zerolatency -threads 1 -bf 0 \
+  -f whip "http://localhost:1985/rtc/v1/whip/?app=live&stream=livestream"
+
+ +

For this example, we have employed low latency options, resulting in an end-to-end latency of +approximately 150ms. +

+ +

4.75.1 Options

+ +

This muxer supports the following options: +

+
+
handshake_timeout integer
+

Set the timeout in milliseconds for ICE and DTLS handshake. +Default value is 5000. +

+
+
pkt_size integer
+

Set the maximum size, in bytes, of RTP packets that send out. +Default value is 1200. +

+
+
ts_buffer_size integer
+

Set the buffer size, in bytes, of underlying protocol. +Default value is -1(auto). The UDP auto selects a reasonable value. +

+
+
whip_flags flags
+

Possible values: +

+
+
‘dtls_active’
+

The muxer will try to set dtls active role and send the first client hello. +

+
+ +
+
rtp_history integer
+

Set the number of RTP history items to store. +Default value is 512. +

+
+
authorization string
+

The optional Bearer token for WHIP Authorization. +

+
+
cert_file string
+

The optional certificate file path for DTLS. +

+
+
key_file string
+

The optional private key file path for DTLS. +

+
+
+ + +

5 Metadata

+ +

FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded +INI-like text file and then load it back using the metadata muxer/demuxer. +

+

The file format is as follows: +

    +
  1. A file consists of a header and a number of metadata tags divided into sections, +each on its own line. + +
  2. The header is a ‘;FFMETADATA’ string, followed by a version number (now 1). + +
  3. Metadata tags are of the form ‘key=value’ + +
  4. Immediately after header follows global metadata + +
  5. After global metadata there may be sections with per-stream/per-chapter +metadata. + +
  6. A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in +brackets (‘[’, ‘]’) and ends with next section or end of file. + +
  7. At the beginning of a chapter section there may be an optional timebase to be +used for start/end values. It must be in form +‘TIMEBASE=num/den’, where num and den are +integers. If the timebase is missing then start/end times are assumed to +be in nanoseconds. + +

    Next a chapter section must contain chapter start and end times in form +‘START=num’, ‘END=num’, where num is a positive +integer. +

    +
  8. Empty lines and lines starting with ‘;’ or ‘#’ are ignored. + +
  9. Metadata keys or values containing special characters (‘=’, ‘;’, +‘#’, ‘\’ and a newline) must be escaped with a backslash ‘\’. + +
  10. Note that whitespace in metadata (e.g. ‘foo = bar’) is considered to be +a part of the tag (in the example above key is ‘foo ’, value is +‘ bar’). +
+ +

A ffmetadata file might look like this: +

+
;FFMETADATA1
+title=bike\\shed
+;this is a comment
+artist=FFmpeg troll team
+
+[CHAPTER]
+TIMEBASE=1/1000
+START=0
+#chapter ends at 0:01:00
+END=60000
+title=chapter \#1
+[STREAM]
+title=multi\
+line
+
+ +

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 ffmpeg goes as follows: +

+
ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
+
+ +

Reinserting edited metadata information from the FFMETADATAFILE file can +be done as: +

+
ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
+
+ + + +

6 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavformat +

+ + +

7 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-protocols.html b/ffmpeg-n8.1/doc/ffmpeg-protocols.html new file mode 100644 index 00000000..3310ca60 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-protocols.html @@ -0,0 +1,2765 @@ + + + + + + + FFmpeg Protocols Documentation + + + + + + +
+

+ FFmpeg Protocols Documentation +

+ + + + + + + +

1 Description

+ +

This document describes the input and output protocols provided by the +libavformat library. +

+ + +

2 Protocol Options

+ +

The libavformat library provides some generic global options, which +can be set on all the protocols. In addition each protocol may support +so-called private options, which are specific for that component. +

+

Options may be set by specifying -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
protocol_whitelist list (input)
+

Set a ","-separated list of allowed protocols. "ALL" matches all protocols. Protocols +prefixed by "-" are disabled. +All protocols are allowed by default but protocols used by an another +protocol (nested protocols) are restricted to a per protocol subset. +

+
+ + + +

3 Protocols

+ +

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 +configure option "–list-protocols". +

+

You can disable all the protocols using the configure option +"–disable-protocols", and selectively enable a protocol using the +option "–enable-protocol=PROTOCOL", or you can disable a +particular protocol using the option +"–disable-protocol=PROTOCOL". +

+

The option "-protocols" of the ff* tools will display the list of +supported protocols. +

+

All protocols accept the following options: +

+
+
rw_timeout
+

Maximum time to wait for (network) read/write operations to complete, +in microseconds. +

+
+ +

A description of the currently available protocols follows. +

+ +

3.1 amqp

+ +

Advanced Message Queueing Protocol (AMQP) version 0-9-1 is a broker based +publish-subscribe communication protocol. +

+

FFmpeg must be compiled with –enable-librabbitmq to support AMQP. A separate +AMQP broker must also be run. An example open-source AMQP broker is RabbitMQ. +

+

After starting the broker, an FFmpeg client may stream data to the broker using +the command: +

+
+
ffmpeg -re -i input -f mpegts amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

Where hostname and port (default is 5672) is the address of the broker. The +client may also set a user/password for authentication. The default for both +fields is "guest". Name of virtual host on broker can be set with vhost. The +default value is "/". +

+

Multiple subscribers may stream from the broker using the command: +

+
ffplay amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

In RabbitMQ all data published to the broker flows through a specific exchange, +and each subscribing client has an assigned queue/buffer. When a packet arrives +at an exchange, it may be copied to a client’s queue depending on the exchange +and routing_key fields. +

+

The following options are supported: +

+
+
exchange
+

Sets the exchange to use on the broker. RabbitMQ has several predefined +exchanges: "amq.direct" is the default exchange, where the publisher and +subscriber must have a matching routing_key; "amq.fanout" is the same as a +broadcast operation (i.e. the data is forwarded to all queues on the fanout +exchange independent of the routing_key); and "amq.topic" is similar to +"amq.direct", but allows for more complex pattern matching (refer to the RabbitMQ +documentation). +

+
+
routing_key
+

Sets the routing key. The default value is "amqp". The routing key is used on +the "amq.direct" and "amq.topic" exchanges to decide whether packets are written +to the queue of a subscriber. +

+
+
pkt_size
+

Maximum size of each packet sent/received to the broker. Default is 131072. +Minimum is 4096 and max is any large value (representable by an int). When +receiving packets, this sets an internal buffer size in FFmpeg. It should be +equal to or greater than the size of the published packets to the broker. Otherwise +the received message may be truncated causing decoding errors. +

+
+
connection_timeout
+

The timeout in seconds during the initial connection to the broker. The +default value is rw_timeout, or 5 seconds if rw_timeout is not set. +

+
+
delivery_mode mode
+

Sets the delivery mode of each message sent to broker. +The following values are accepted: +

+
‘persistent’
+

Delivery mode set to "persistent" (2). This is the default value. +Messages may be written to the broker’s disk depending on its setup. +

+
+
‘non-persistent’
+

Delivery mode set to "non-persistent" (1). +Messages will stay in broker’s memory unless the broker is under memory +pressure. +

+
+
+ +
+
+ + +

3.2 async

+ +

Asynchronous data filling wrapper for input stream. +

+

Fill data in a background thread, to decouple I/O operation from demux thread. +

+
+
async:URL
+async:http://host/resource
+async:cache:http://host/resource
+
+ + +

3.3 bluray

+ +

Read BluRay playlist. +

+

The accepted options are: +

+
angle
+

BluRay angle +

+
+
chapter
+

Start chapter (1...N) +

+
+
playlist
+

Playlist to read (BDMV/PLAYLIST/?????.mpls) +

+
+
+ +

Examples: +

+

Read longest playlist from BluRay mounted to /mnt/bluray: +

+
bluray:/mnt/bluray
+
+ +

Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: +

+
-playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
+
+ + +

3.4 cache

+ +

Caching wrapper for input stream. +

+

Cache the input stream to temporary file. It brings seeking capability to live streams. +

+

The accepted options are: +

+
read_ahead_limit
+

Amount in bytes that may be read ahead when seeking isn’t supported. Range is -1 to INT_MAX. +-1 for unlimited. Default is 65536. +

+
+
+ +

URL Syntax is +

+
cache:URL
+
+ + +

3.5 concat

+ +

Physical concatenation protocol. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concat:URL1|URL2|...|URLN
+
+ +

where URL1, URL2, ..., URLN are the urls of the +resource to be concatenated, each one possibly specifying a distinct +protocol. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg with ffplay use the +command: +

+
ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+
+ +

Note that you may need to escape the character "|" which is special for +many shells. +

+ +

3.6 concatf

+ +

Physical concatenation protocol using a line break delimited list of +resources. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concatf:URL
+
+ +

where URL is the url containing a line break delimited list of +resources to be concatenated, each one possibly specifying a distinct +protocol. Special characters must be escaped with backslash or single +quotes. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg listed in separate lines within +a file split.txt with ffplay use the command: +

+
ffplay concatf:split.txt
+
+

Where split.txt contains the lines: +

+
split1.mpeg
+split2.mpeg
+split3.mpeg
+
+ + +

3.7 crypto

+ +

AES-encrypted stream reading protocol. +

+

The accepted options are: +

+
key
+

Set the AES decryption key binary block from given hexadecimal representation. +

+
+
iv
+

Set the AES decryption initialization vector binary block from given hexadecimal representation. +

+
+ +

Accepted URL formats: +

+
crypto:URL
+crypto+URL
+
+ + +

3.8 data

+ +

Data in-line in the URI. See http://en.wikipedia.org/wiki/Data_URI_scheme. +

+

For example, to convert a GIF file given inline with ffmpeg: +

+
ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
+
+ + +

3.9 fd

+ +

File descriptor access protocol. +

+

The accepted syntax is: +

+
fd: -fd file_descriptor
+
+ +

If fd is not specified, by default the stdout file descriptor will be +used for writing, stdin for reading. Unlike the pipe protocol, fd protocol has +seek support if it corresponding to a regular file. fd protocol doesn’t support +pass file descriptor via URL for security. +

+

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
fd
+

Set file descriptor. +

+
+ + +

3.10 file

+ +

File access protocol. +

+

Read from or write to a file. +

+

A file URL can have the form: +

+
file:filename
+
+ +

where filename is the path of the file to read. +

+

An URL that does not have a protocol prefix will be assumed to be a +file URL. Depending on the build, an URL that looks like a Windows +path with the drive letter at the beginning will also be assumed to be +a file URL (usually not the case in builds for unix-like systems). +

+

For example to read from a file input.mpeg with ffmpeg +use the command: +

+
ffmpeg -i file:input.mpeg output.mpeg
+
+ +

This protocol accepts the following options: +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
follow
+

If set to 1, the protocol will retry reading at the end of the file, allowing +reading files that still are being written. In order for this to terminate, +you either need to use the rw_timeout option, or use the interrupt callback +(for API users). +

+
+
seekable
+

Controls if seekability is advertised on the file. 0 means non-seekable, -1 +means auto (seekable for normal files, non-seekable for named pipes). +

+

Many demuxers handle seekable and non-seekable resources differently, +overriding this might speed up opening certain files at the cost of losing some +features (e.g. accurate seeking). +

+
+
pkt_size
+

Set the maximum packet size used for file I/O. A smaller value may reduce +memory usage. A higher value may increase throughput especially with networked +filesystems. +

+

For reading, if explicitly set, it overrides the default internal buffer size +(32 KB) and limits the maximum amount of data read per operation. +

+

For writing, this sets the size of each write operation. The default is 256 KB +for regular files, 32 KB otherwise. +

+
+ + +

3.11 ftp

+ +

FTP (File Transfer Protocol). +

+

Read from or write to remote resources using FTP protocol. +

+

Following syntax is required. +

+
ftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in microseconds 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. +

+
+
ftp-user
+

Set a user to be used for authenticating to the FTP server. This is overridden by the +user in the FTP URL. +

+
+
ftp-password
+

Set a password to be used for authenticating to the FTP server. This is overridden by +the password in the FTP URL, or by ftp-anonymous-password if no user is set. +

+
+
ftp-anonymous-password
+

Password used when login as anonymous user. Typically an e-mail address +should be used. +

+
+
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. +

+
+ +

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. +

+ +

3.12 gopher

+ +

Gopher protocol. +

+ +

3.13 gophers

+ +

Gophers protocol. +

+

The Gopher protocol with TLS encapsulation. +

+ +

3.14 http

+ +

HTTP (Hyper Text Transfer Protocol). +

+

This protocol accepts the following options: +

+
+
seekable
+

Control seekability of connection. If set to 1 the resource is +supposed to be seekable, if set to 0 it is assumed not to be seekable, +if set to -1 it will try to autodetect if it is seekable. Default +value is -1. +

+
+
chunked_post
+

If set to 1 use chunked Transfer-Encoding for posts, default is 1. +

+
+
http_proxy
+

set HTTP proxy to tunnel through e.g. http://example.com:1234 +

+
+
headers
+

Set custom HTTP headers, can override built in default headers. The +value must be a string encoding the headers. +

+
+
content_type
+

Set a specific content type for the POST messages or for listen mode. +

+
+
user_agent
+

Override the User-Agent header. If not specified the protocol will use a +string describing the libavformat build. ("Lavf/<version>") +

+
+
referer
+

Set the Referer header. Include ’Referer: URL’ header in HTTP request. +

+
+
multiple_requests
+

Use persistent connections if set to 1, default is 0. +

+
+
request_size
+

Limit the size of requests made. This is useful for some pathological servers +that throttle unbounded range requests, as well as when expecting to seek +frequently. Disabled (set to 0) by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. Doing so allows FFmpeg +to reuse a single HTTP connection wherever possible. +

+
+
initial_request_size
+

Limit the size of initial requests. Similar to request_size, but only +used during initial format parsing. Useful for formats like MXF or MOV that +require frequent seeks during header parsing. Lasts until the demuxer makes a +read request larger than this size (without a seek in between), after which +the implementation will continue using requests as usual. Disabled (set to 0) +by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. +

+
+
post_data
+

Set custom HTTP post data. +

+
+
mime_type
+

Export the MIME type. +

+
+
http_version
+

Exports the HTTP response version number. Usually "1.0" or "1.1". +

+
+
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 +delimited by a newline character. +

+
+
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 icy_metadata_headers and icy_metadata_packet options. +The default is 1. +

+
+
icy_metadata_headers
+

If the server supports ICY metadata, this contains the ICY-specific HTTP reply +headers, separated by newline characters. +

+
+
icy_metadata_packet
+

If the server supports ICY metadata, and icy was set to 1, this +contains the last non-empty metadata packet sent by the server. It should be +polled in regular intervals by applications interested in mid-stream metadata +updates. +

+
+
metadata
+

Set an exported dictionary containing Icecast metadata from the bitstream, if present. +Only useful with the C API. +

+
+
auth_type
+
+

Set HTTP authentication type. No option for Digest, since this method requires +getting nonce parameters from the server first and can’t be used straight away like +Basic. +

+
+
none
+

Choose the HTTP authentication type automatically. This is the default. +

+
basic
+
+

Choose the HTTP basic authentication. +

+

Basic authentication sends a Base64-encoded string that contains a user name and password +for the client. Base64 is not a form of encryption and should be considered the same as +sending the user name and password in clear text (Base64 is a reversible encoding). +If a resource needs to be protected, strongly consider using an authentication scheme +other than basic authentication. HTTPS/TLS should be used with basic authentication. +Without these additional security enhancements, basic authentication should not be used +to protect sensitive or valuable information. +

+
+ +
+
send_expect_100
+

Send an Expect: 100-continue header for POST. If set to 1 it will send, if set +to 0 it won’t, if set to -1 it will try to send if it is applicable. Default +value is -1. +

+
+
location
+

An exported dictionary containing the content location. Only useful with the C +API. +

+
+
offset
+

Set initial byte offset. +

+
+
end_offset
+

Try to limit the request to bytes preceding this offset. +

+
+
method
+

When used as a client option it sets the HTTP method for the request. +

+

When used as a server option it sets the HTTP method that is going to be +expected from the client(s). +If the expected and the received HTTP method do not match the client will +be given a Bad Request response. +When unset the HTTP method is not checked for now. This will be replaced by +autodetection in the future. +

+
+
reconnect
+

Reconnect automatically when disconnected before EOF is hit. +

+
+
reconnect_at_eof
+

If set then eof is treated like an error and causes reconnection, this is useful +for live / endless streams. +

+
+
reconnect_on_network_error
+

Reconnect automatically in case of TCP/TLS errors during connect. +

+
+
reconnect_on_http_error
+

A comma separated list of HTTP status codes to reconnect on. The list can +include specific status codes (e.g. ’503’) or the strings ’4xx’ / ’5xx’. +

+
+
reconnect_streamed
+

If set then even streamed/non seekable streams will be reconnected on errors. +

+
+
reconnect_delay_max
+

Set the maximum delay in seconds after which to give up reconnecting. +

+
+
reconnect_max_retries
+

Set the maximum number of times to retry a connection. Default unset. +

+
+
reconnect_delay_total_max
+

Set the maximum total delay in seconds after which to give up reconnecting. +

+
+
respect_retry_after
+

If enabled, and a Retry-After header is encountered, its requested reconnection +delay will be honored, rather than using exponential backoff. Useful for 429 and +503 errors. Default enabled. +

+
+
listen
+

If set to 1 enables experimental HTTP server. This can be used to send data when +used as an output option, or read data from a client with HTTP POST when used as +an input option. +If set to 2 enables experimental multi-client HTTP server. This is not yet implemented +in ffmpeg.c and thus must not be used as a command line option. +

+
# Server side (sending):
+ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://server:port
+
+# Client side (receiving):
+ffmpeg -i http://server:port -c copy somefile.ogg
+
+# Client can also be done with wget:
+wget http://server:port -O somefile.ogg
+
+# Server side (receiving):
+ffmpeg -listen 1 -i http://server:port -c copy somefile.ogg
+
+# Client side (sending):
+ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://server:port
+
+# Client can also be done with wget:
+wget --post-file=somefile.ogg http://server:port
+
+ +
+
resource
+

The resource requested by a client, when the experimental HTTP server is in use. +

+
+
reply_code
+

The HTTP code returned to the client, when the experimental HTTP server is in use. +

+
+
short_seek_size
+

Set the threshold, in bytes, for when a readahead should be preferred over a seek and +new HTTP request. This is useful, for example, to make sure the same connection +is used for reading large video packets with small audio packets in between. +

+
+
+ + +

3.14.1 HTTP Cookies

+ +

Some HTTP requests will be denied unless cookie values are passed in with the +request. The cookies option allows these cookies to be specified. At +the very least, each cookie must specify a value along with a path and domain. +HTTP requests that match both the domain and path will automatically include the +cookie value in the HTTP Cookie header field. Multiple cookies can be delimited +by a newline. +

+

The required syntax to play a stream specifying a cookie is: +

+
ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
+
+ + +

3.15 Icecast

+ +

Icecast protocol (stream to Icecast servers) +

+

This protocol accepts the following options: +

+
+
ice_genre
+

Set the stream genre. +

+
+
ice_name
+

Set the stream name. +

+
+
ice_description
+

Set the stream description. +

+
+
ice_url
+

Set the stream website URL. +

+
+
ice_public
+

Set if the stream should be public. +The default is 0 (not public). +

+
+
user_agent
+

Override the User-Agent header. If not specified a string of the form +"Lavf/<version>" will be used. +

+
+
password
+

Set the Icecast mountpoint password. +

+
+
content_type
+

Set the stream content type. This must be set if it is different from +audio/mpeg. +

+
+
legacy_icecast
+

This enables support for Icecast versions < 2.4.0, that do not support the +HTTP PUT method but the SOURCE method. +

+
+
tls
+

Establish a TLS (HTTPS) connection to Icecast. +

+
+
+ +
+
icecast://[username[:password]@]server:port/mountpoint
+
+ + +

3.16 ipfs

+ +

InterPlanetary File System (IPFS) protocol support. One can access files stored +on the IPFS network through so-called gateways. These are http(s) endpoints. +This protocol wraps the IPFS native protocols (ipfs:// and ipns://) to be sent +to such a gateway. Users can (and should) host their own node which means this +protocol will use one’s local gateway to access files on the IPFS network. +

+

This protocol accepts the following options: +

+
+
gateway
+

Defines the gateway to use. When not set, the protocol will first try +locating the local gateway by looking at $IPFS_GATEWAY, $IPFS_PATH +and $HOME/.ipfs/, in that order. +

+
+
+ +

One can use this protocol in 2 ways. Using IPFS: +

+
ffplay ipfs://<hash>
+
+ +

Or the IPNS protocol (IPNS is mutable IPFS): +

+
ffplay ipns://<hash>
+
+ + +

3.17 mmst

+ +

MMS (Microsoft Media Server) protocol over TCP. +

+ +

3.18 mmsh

+ +

MMS (Microsoft Media Server) protocol over HTTP. +

+

The required syntax is: +

+
mmsh://server[:port][/app][/playpath]
+
+ + +

3.19 md5

+ +

MD5 output protocol. +

+

Computes the MD5 hash of the data to be written, and on close writes +this to the designated output or stdout if none is specified. It can +be used to test muxers without writing an actual file. +

+

Some examples follow. +

+
# Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
+ffmpeg -i input.flv -f avi -y md5:output.avi.md5
+
+# Write the MD5 hash of the encoded AVI file to stdout.
+ffmpeg -i input.flv -f avi -y md5:
+
+ +

Note that some formats (typically MOV) require the output protocol to +be seekable, so they will fail with the MD5 output protocol. +

+ +

3.20 pipe

+ +

UNIX pipe access protocol. +

+

Read and write from UNIX pipes. +

+

The accepted syntax is: +

+
pipe:[number]
+
+ +

If fd isn’t specified, number is the number corresponding to the file descriptor of the +pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If number +is not specified, by default the stdout file descriptor will be used +for writing, stdin for reading. +

+

For example to read from stdin with ffmpeg: +

+
cat test.wav | ffmpeg -i pipe:0
+# ...this is the same as...
+cat test.wav | ffmpeg -i pipe:
+
+ +

For writing to stdout with ffmpeg: +

+
ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
+# ...this is the same as...
+ffmpeg -i test.wav -f avi pipe: | cat > test.avi
+
+ +

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
fd
+

Set file descriptor. +

+
+ +

Note that some formats (typically MOV), require the output protocol to +be seekable, so they will fail with the pipe output protocol. +

+ +

3.21 prompeg

+ +

Pro-MPEG Code of Practice #3 Release 2 FEC protocol. +

+

The Pro-MPEG CoP#3 FEC is a 2D parity-check forward error correction mechanism +for MPEG-2 Transport Streams sent over RTP. +

+

This protocol must be used in conjunction with the rtp_mpegts muxer and +the rtp protocol. +

+

The required syntax is: +

+
-f rtp_mpegts -fec prompeg=option=val... rtp://hostname:port
+
+ +

The destination UDP ports are port + 2 for the column FEC stream +and port + 4 for the row FEC stream. +

+

This protocol accepts the following options: +

+
l=n
+

The number of columns (4-20, LxD <= 100) +

+
+
d=n
+

The number of rows (4-20, LxD <= 100) +

+
+
+ +

Example usage: +

+
+
-f rtp_mpegts -fec prompeg=l=8:d=4 rtp://hostname:port
+
+ + +

3.22 rist

+ +

Reliable Internet Streaming Transport protocol +

+

The accepted options are: +

+
rist_profile
+

Supported values: +

+
‘simple’
+
‘main’
+

This one is default. +

+
‘advanced’
+
+ +
+
buffer_size
+

Set internal RIST buffer size in milliseconds for retransmission of data. +Default value is 0 which means the librist default (1 sec). Maximum value is 30 +seconds. +

+
+
fifo_size
+

Size of the librist receiver output fifo in number of packets. This must be a +power of 2. +Defaults to 8192 (vs the librist default of 1024). +

+
+
overrun_nonfatal=1|0
+

Survive in case of librist fifo buffer overrun. Default value is 0. +

+
+
pkt_size
+

Set maximum packet size for sending data. 1316 by default. +

+
+
log_level
+

Set loglevel for RIST logging messages. You only need to set this if you +explicitly want to enable debug level messages or packet loss simulation, +otherwise the regular loglevel is respected. +

+
+
secret
+

Set override of encryption secret, by default is unset. +

+
+
encryption
+

Set encryption type, by default is disabled. +Acceptable values are 128 and 256. +

+
+ + +

3.23 rtmp

+ +

Real-Time Messaging Protocol. +

+

The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia +content across a TCP/IP network. +

+

The required syntax is: +

+
rtmp://[username:password@]server[:port][/app][/instance][/playpath]
+
+ +

The accepted parameters are: +

+
username
+

An optional username (mostly for publishing). +

+
+
password
+

An optional password (mostly for publishing). +

+
+
server
+

The address of the RTMP server. +

+
+
port
+

The number of the TCP port to use (by default is 1935). +

+
+
app
+

It is the name of the application to access. It usually corresponds to +the path where the application is installed on the RTMP server +(e.g. /ondemand/, /flash/live/, etc.). You can override +the value parsed from the URI through the rtmp_app option, too. +

+
+
playpath
+

It is the path or name of the resource to play with reference to the +application specified in app, may be prefixed by "mp4:". You +can override the value parsed from the URI through the rtmp_playpath +option, too. +

+
+
listen
+

Act as a server, listening for an incoming connection. +

+
+
timeout
+

Maximum time to wait for the incoming connection. Implies listen. +

+
+ +

Additionally, the following parameters can be set via command line options +(or in code via AVOptions): +

+
rtmp_app
+

Name of application to connect on the RTMP server. This option +overrides the parameter specified in the URI. +

+
+
rtmp_buffer
+

Set the client buffer time in milliseconds. The default is 3000. +

+
+
rtmp_conn
+

Extra arbitrary AMF connection parameters, parsed from a string, +e.g. like B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0. +Each value is prefixed by a single character denoting the type, +B for Boolean, N for number, S for string, O for object, or Z for null, +followed by a colon. For Booleans the data must be either 0 or 1 for +FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or +1 to end or begin an object, respectively. Data items in subobjects may +be named, by prefixing the type with ’N’ and specifying the name before +the value (i.e. NB:myFlag:1). This option may be used multiple +times to construct arbitrary AMF sequences. +

+
+
rtmp_enhanced_codecs
+

Specify the list of codecs the client advertises to support in an +enhanced RTMP stream. This option should be set to a comma separated +list of fourcc values, like hvc1,av01,vp09 for multiple codecs +or hvc1 for only one codec. The specified list will be presented +in the "fourCcLive" property of the Connect Command Message. +

+
+
rtmp_flashver
+

Version of the Flash plugin used to run the SWF player. The default +is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; +<libavformat version>).) +

+
+
rtmp_flush_interval
+

Number of packets flushed in the same request (RTMPT only). The default +is 10. +

+
+
rtmp_live
+

Specify that the media is a live stream. No resuming or seeking in +live streams is possible. The default value is any, which means the +subscriber first tries to play the live stream specified in the +playpath. If a live stream of that name is not found, it plays the +recorded stream. The other possible values are live and +recorded. +

+
+
rtmp_pageurl
+

URL of the web page in which the media was embedded. By default no +value will be sent. +

+
+
rtmp_playpath
+

Stream identifier to play or to publish. This option overrides the +parameter specified in the URI. +

+
+
rtmp_subscribe
+

Name of live stream to subscribe to. By default no value will be sent. +It is only sent if the option is specified or if rtmp_live +is set to live. +

+
+
rtmp_swfhash
+

SHA256 hash of the decompressed SWF file (32 bytes). +

+
+
rtmp_swfsize
+

Size of the decompressed SWF file, required for SWFVerification. +

+
+
rtmp_swfurl
+

URL of the SWF player for the media. By default no value will be sent. +

+
+
rtmp_swfverify
+

URL to player swf file, compute hash/size automatically. +

+
+
rtmp_tcurl
+

URL of the target stream. Defaults to proto://host[:port]/app. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_keepalive=1|0
+

Enable the TCP keepalive mechanism to detect dead peers and help maintain long-lived idle connections. Default value is 0. +

+

Only the basic keepalive option (SO_KEEPALIVE) can be enabled or disabled. Platform-specific tuning parameters such as TCP_KEEPIDLE, TCP_KEEPINTVL, or TCP_KEEPCNT are not configurable and will use the operating system’s default values. +

+
+
+ +

For example to read with ffplay a multimedia resource named +"sample" from the application "vod" from an RTMP server "myserver": +

+
ffplay rtmp://myserver/vod/sample
+
+ +

To publish to a password protected server, passing the playpath and +app names separately: +

+
ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@myserver/
+
+ + +

3.24 rtmpe

+ +

Encrypted Real-Time Messaging Protocol. +

+

The Encrypted Real-Time Messaging Protocol (RTMPE) is used for +streaming multimedia content within standard cryptographic primitives, +consisting of Diffie-Hellman key exchange and HMACSHA256, generating +a pair of RC4 keys. +

+ +

3.25 rtmps

+ +

Real-Time Messaging Protocol over a secure SSL connection. +

+

The Real-Time Messaging Protocol (RTMPS) is used for streaming +multimedia content across an encrypted connection. +

+ +

3.26 rtmpt

+ +

Real-Time Messaging Protocol tunneled through HTTP. +

+

The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used +for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

3.27 rtmpte

+ +

Encrypted Real-Time Messaging Protocol tunneled through HTTP. +

+

The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) +is used for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

3.28 rtmpts

+ +

Real-Time Messaging Protocol tunneled through HTTPS. +

+

The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used +for streaming multimedia content within HTTPS requests to traverse +firewalls. +

+ +

3.29 libsmbclient

+ +

libsmbclient permits one to manipulate CIFS/SMB network resources. +

+

Following syntax is required. +

+
+
smb://[[domain:]user[:password@]]server[/share[/path[/file]]]
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in milliseconds 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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
workgroup
+

Set the workgroup used for making connections. By default workgroup is not specified. +

+
+
+ +

For more information see: http://www.samba.org/. +

+ +

3.30 libssh

+ +

Secure File Transfer Protocol via libssh +

+

Read from or write to remote resources using SFTP protocol. +

+

Following syntax is required. +

+
+
sftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
private_key
+

Specify the path of the file containing private key to use during authorization. +By default libssh searches for keys in the ~/.ssh/ directory. +

+
+
+ +

Example: Play a file stored on remote server. +

+
+
ffplay sftp://user:password@server_address:22/home/user/resource.mpeg
+
+ + +

3.31 librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte

+ +

Real-Time Messaging Protocol and its variants supported through +librtmp. +

+

Requires the presence of the librtmp headers and library during +configuration. You need to explicitly configure the build with +"–enable-librtmp". If enabled this will replace the native RTMP +protocol. +

+

This protocol provides most client functions and a few server +functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), +encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled +variants of these encrypted types (RTMPTE, RTMPTS). +

+

The required syntax is: +

+
rtmp_proto://server[:port][/app][/playpath] options
+
+ +

where rtmp_proto is one of the strings "rtmp", "rtmpt", "rtmpe", +"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and +server, port, app and playpath have the same +meaning as specified for the RTMP native protocol. +options contains a list of space-separated options of the form +key=val. +

+

See the librtmp manual page (man 3 librtmp) for more information. +

+

For example, to stream a file in real-time to an RTMP server using +ffmpeg: +

+
ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
+
+ +

To play the same stream using ffplay: +

+
ffplay "rtmp://myserver/live/mystream live=1"
+
+ + +

3.32 rtp

+ +

Real-time Transport Protocol. +

+

The required syntax for an RTP URL is: +

+
rtp://hostname[:port][?options]
+
+ +

port specifies the RTP port to use. +

+

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ttl=n
+

Set the TTL (Time-To-Live) value (for multicast only). +

+
+
rtcpport=n
+

Set the remote RTCP port to n. +

+
+
localport, local_rtpport, localrtpport=n
+

Set the local RTP port to n. +

+

Using the localport option name is deprecated and should not be used. +

+
+
local_rtcpport, localrtcpport=n'
+

Set the local RTCP port to n. +

+
+
pkt_size=n
+

Set max packet size (in bytes) to n. +

+
+
buffer_size=size
+

Set the maximum UDP socket buffer size in bytes. +

+
+
connect=0|1
+

Do a connect() on the UDP socket (if set to 1) or not (if set +to 0). +

+
+
sources=ip[,ip]
+

List allowed source IP addresses. +

+
+
block=ip[,ip]
+

List disallowed (blocked) source IP addresses. +

+
+
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). +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
timeout=n
+

Set timeout (in microseconds) of socket I/O operations to n. +

+
+ +

Important notes: +

+
    +
  1. If rtcpport is not set the RTCP port will be set to the RTP +port value plus 1. + +
  2. If localrtpport (the local RTP port) is not set any available +port will be used for the local RTP and RTCP ports. + +
  3. If localrtcpport (the local RTCP port) is not set it will be +set to the local RTP port value plus 1. +
+ + +

3.33 rtsp

+ +

Real-Time Streaming Protocol. +

+

RTSP is not technically a protocol handler in libavformat, it is a demuxer +and muxer. The demuxer supports both normal RTSP (with data transferred +over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with +data transferred over RDT). +

+

The muxer can be used to send a stream using RTSP ANNOUNCE to a server +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock’s +RTSP server). +

+

The required syntax for a RTSP url is: +

+
rtsp://hostname[:port]/path
+
+ +

Options can be set on the ffmpeg/ffplay command +line, or set in code via AVOptions or in +avformat_open_input. +

+ +

3.33.1 Muxer

+

The following options are supported. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+ +

Default value is ‘0’. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘latm’
+

Use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC. +

+
‘rfc2190’
+

Use RFC 2190 packetization instead of RFC 4629 for H.263. +

+
‘skip_rtcp’
+

Don’t send RTCP sender reports. +

+
‘h264_mode0’
+

Use mode 0 for H.264 in RTP. +

+
‘send_bye’
+

Send RTCP BYE packets when finishing. +

+
+ +

Default value is ‘0’. +

+ +
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+
pkt_size
+

Set max send packet size (in bytes). Default value is 1472. +

+
+ + +

3.33.2 Demuxer

+

The following options are supported. +

+
+
initial_pause
+

Do not start playing the stream immediately if set to 1. Default value +is 0. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+
‘udp_multicast’
+

Use UDP multicast as lower transport protocol. +

+
+
‘http’
+

Use HTTP tunneling as lower transport protocol, which is useful for +passing proxies. +

+
+
‘https’
+

Use HTTPs tunneling as lower transport protocol, which is useful for +passing proxies and widely used for security consideration. +

+
+ +

Multiple lower transport protocols may be specified, in that case they are +tried one at a time (if the setup of one fails, the next one is tried). +For the muxer, only the ‘tcp’ and ‘udp’ options are supported. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘filter_src’
+

Accept packets only from negotiated peer address and port. +

+
‘listen’
+

Act as a server, listening for an incoming connection. +

+
‘prefer_tcp’
+

Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. +

+
‘satip_raw’
+

Export raw MPEG-TS stream instead of demuxing. The flag will simply write out +the raw stream, with the original PAT/PMT/PIDs intact. +

+
+ +

Default value is ‘none’. +

+
+
allowed_media_types
+

Set media types to accept from the server. +

+

The following flags are accepted: +

+
‘video’
+
‘audio’
+
‘data’
+
‘subtitle’
+
+ +

By default it accepts all media types. +

+
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
listen_timeout
+

Set maximum timeout (in seconds) to establish an initial connection. Setting +listen_timeout > 0 sets rtsp_flags to ‘listen’. Default is -1 +which means an infinite timeout when ‘listen’ mode is set. +

+
+
reorder_queue_size
+

Set number of packets to buffer for handling of reordered packets. +

+
+
timeout
+

Set socket TCP I/O timeout in microseconds. +

+
+
user_agent
+

Override User-Agent header. If not specified, it defaults to the +libavformat identifier string. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+ +

When receiving data over UDP, the demuxer tries to reorder received packets +(since they may arrive out of order, or packets may get lost totally). This +can be disabled by setting the maximum demuxing delay to zero (via +the max_delay field of AVFormatContext). +

+

When watching multi-bitrate Real-RTSP streams with ffplay, the +streams to display can be chosen with -vst n and +-ast n for video and audio respectively, and can be switched +on the fly by pressing v and a. +

+ +

3.33.3 Examples

+ +

The following examples all make use of the ffplay and +ffmpeg tools. +

+
    +
  • Watch a stream over UDP, with a max reordering delay of 0.5 seconds: +
    +
    ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
    +
    + +
  • Watch a stream tunneled over HTTP: +
    +
    ffplay -rtsp_transport http rtsp://server/video.mp4
    +
    + +
  • Send a stream in realtime to a RTSP server, for others to watch: +
    +
    ffmpeg -re -i input -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
    +
    + +
  • Receive a stream in realtime: +
    +
    ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp output
    +
    +
+ + +

3.34 sap

+ +

Session Announcement Protocol (RFC 2974). This is not technically a +protocol handler in libavformat, it is a muxer and demuxer. +It is used for signalling of RTP streams, by announcing the SDP for the +streams regularly on a separate port. +

+ +

3.34.1 Muxer

+ +

The syntax for a SAP url given to the muxer is: +

+
sap://destination[:port][?options]
+
+ +

The RTP packets are sent to destination on port port, +or to port 5004 if no port is specified. +options is a &-separated list. The following options +are supported: +

+
+
announce_addr=address
+

Specify the destination IP address for sending the announcements to. +If omitted, the announcements are sent to the commonly used SAP +announcement multicast address 224.2.127.254 (sap.mcast.net), or +ff0e::2:7ffe if destination is an IPv6 address. +

+
+
announce_port=port
+

Specify the port to send the announcements on, defaults to +9875 if not specified. +

+
+
ttl=ttl
+

Specify the time to live value for the announcements and RTP packets, +defaults to 255. +

+
+
same_port=0|1
+

If set to 1, send all RTP streams on the same port pair. If zero (the +default), all streams are sent on unique ports, with each stream on a +port 2 numbers higher than the previous. +VLC/Live555 requires this to be set to 1, to be able to receive the stream. +The RTP stack in libavformat for receiving requires all streams to be sent +on unique ports. +

+
+ +

Example command lines follow. +

+

To broadcast a stream on the local subnet, for watching in VLC: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255?same_port=1
+
+ +

Similarly, for watching in ffplay: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255
+
+ +

And for watching in ffplay, over IPv6: +

+
+
ffmpeg -re -i input -f sap sap://[ff0e::1:2:3:4]
+
+ + +

3.34.2 Demuxer

+ +

The syntax for a SAP url given to the demuxer is: +

+
sap://[address][:port]
+
+ +

address is the multicast address to listen for announcements on, +if omitted, the default 224.2.127.254 (sap.mcast.net) is used. port +is the port that is listened on, 9875 if omitted. +

+

The demuxers listens for announcements on the given address and port. +Once an announcement is received, it tries to receive that particular stream. +

+

Example command lines follow. +

+

To play back the first stream announced on the normal SAP multicast address: +

+
+
ffplay sap://
+
+ +

To play back the first stream announced on one the default IPv6 SAP multicast address: +

+
+
ffplay sap://[ff0e::2:7ffe]
+
+ + +

3.35 sctp

+ +

Stream Control Transmission Protocol. +

+

The accepted URL syntax is: +

+
sctp://host:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen
+

If set to any value, listen for an incoming connection. Outgoing connection is done by default. +

+
+
max_streams
+

Set the maximum number of streams. By default no limit is set. +

+
+ + +

3.36 srt

+ +

Haivision Secure Reliable Transport Protocol via libsrt. +

+

The supported syntax for a SRT URL is: +

+
srt://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
connect_timeout=milliseconds
+

Connection timeout; SRT cannot connect for RTT > 1500 msec +(2 handshake exchanges) with the default connect timeout of +3 seconds. This option applies to the caller and rendezvous +connection modes. The connect timeout is 10 times the value +set for the rendezvous mode (which can be used as a +workaround for this connection problem with earlier versions). +

+
+
ffs=bytes
+

Flight Flag Size (Window Size), in bytes. FFS is actually an +internal parameter and you should set it to not less than +recv_buffer_size and mss. The default value +is relatively large, therefore unless you set a very large receiver buffer, +you do not need to change this option. Default value is 25600. +

+
+
inputbw=bytes/seconds
+

Sender nominal input rate, in bytes per seconds. Used along with +oheadbw, when maxbw is set to relative (0), to +calculate maximum sending rate when recovery packets are sent +along with the main media stream: +inputbw * (100 + oheadbw) / 100 +if inputbw is not set while maxbw is set to +relative (0), the actual input rate is evaluated inside +the library. Default value is 0. +

+
+
iptos=tos
+

IP Type of Service. Applies to sender only. Default value is 0xB8. +

+
+
ipttl=ttl
+

IP Time To Live. Applies to sender only. Default value is 64. +

+
+
latency=microseconds
+

Timestamp-based Packet Delivery Delay. +Used to absorb bursts of missed packet retransmissions. +This flag sets both rcvlatency and peerlatency +to the same value. Note that prior to version 1.3.0 +this is the only flag to set the latency, however +this is effectively equivalent to setting peerlatency, +when side is sender and rcvlatency +when side is receiver, and the bidirectional stream +sending is not supported. +

+
+
listen_timeout=microseconds
+

Set socket listen timeout. +

+
+
maxbw=bytes/seconds
+

Maximum sending bandwidth, in bytes per seconds. +-1 infinite (CSRTCC limit is 30mbps) +0 relative to input rate (see inputbw) +>0 absolute limit value +Default value is 0 (relative) +

+
+
mode=caller|listener|rendezvous
+

Connection mode. +caller opens client connection. +listener starts server to listen for incoming connections. +rendezvous use Rendez-Vous connection mode. +Default value is caller. +

+
+
mss=bytes
+

Maximum Segment Size, in bytes. Used for buffer allocation +and rate calculation using a packet counter assuming fully +filled packets. The smallest MSS between the peers is +used. This is 1500 by default in the overall internet. +This is the maximum size of the UDP packet and can be +only decreased, unless you have some unusual dedicated +network settings. Default value is 1500. +

+
+
nakreport=1|0
+

If set to 1, Receiver will send ‘UMSG_LOSSREPORT‘ messages +periodically until a lost packet is retransmitted or +intentionally dropped. Default value is 1. +

+
+
oheadbw=percents
+

Recovery bandwidth overhead above input rate, in percents. +See inputbw. Default value is 25%. +

+
+
passphrase=string
+

HaiCrypt Encryption/Decryption Passphrase string, length +from 10 to 79 characters. The passphrase is the shared +secret between the sender and the receiver. It is used +to generate the Key Encrypting Key using PBKDF2 +(Password-Based Key Derivation Function). It is used +only if pbkeylen is non-zero. It is used on +the receiver only if the received data is encrypted. +The configured passphrase cannot be recovered (write-only). +

+
+
enforced_encryption=1|0
+

If true, both connection parties must have the same password +set (including empty, that is, with no encryption). If the +password doesn’t match or only one side is unencrypted, +the connection is rejected. Default is true. +

+
+
kmrefreshrate=packets
+

The number of packets to be transmitted after which the +encryption key is switched to a new key. Default is -1. +-1 means auto (0x1000000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
kmpreannounce=packets
+

The interval between when a new encryption key is sent and +when switchover occurs. This value also applies to the +subsequent interval between when switchover occurs and +when the old encryption key is decommissioned. Default is -1. +-1 means auto (0x1000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
snddropdelay=microseconds
+

The sender’s extra delay before dropping packets. This delay is +added to the default drop delay time interval value. +

+

Special value -1: Do not drop packets on the sender at all. +

+
+
payload_size=bytes
+

Sets the maximum declared size of a packet transferred +during the single call to the sending function in Live +mode. Use 0 if this value isn’t used (which is default in +file mode). +Default is -1 (automatic), which typically means MPEG-TS; +if you are going to use SRT +to send any different kind of payload, such as, for example, +wrapping a live stream in very small frames, then you can +use a bigger maximum frame size, though not greater than +1456 bytes. +

+
+
pkt_size=bytes
+

Alias for ‘payload_size’. +

+
+
peerlatency=microseconds
+

The latency value (as described in rcvlatency) that is +set by the sender side as a minimum value for the receiver. +

+
+
pbkeylen=bytes
+

Sender encryption key length, in bytes. +Only can be set to 0, 16, 24 and 32. +Enable sender encryption if not 0. +Not required on receiver (set to 0), +key size obtained from sender in HaiCrypt handshake. +Default value is 0. +

+
+
rcvlatency=microseconds
+

The time that should elapse since the moment when the +packet was sent and the moment when it’s delivered to +the receiver application in the receiving function. +This time should be a buffer time large enough to cover +the time spent for sending, unexpectedly extended RTT +time, and the time needed to retransmit the lost UDP +packet. The effective latency value will be the maximum +of this options’ value and the value of peerlatency +set by the peer side. Before version 1.3.0 this option +is only available as latency. +

+
+
recv_buffer_size=bytes
+

Set UDP receive buffer size, expressed in bytes. +

+
+
send_buffer_size=bytes
+

Set UDP send buffer size, expressed in bytes. +

+
+
timeout=microseconds
+

Set raise error timeouts for read, write and connect operations. Note that the +SRT library has internal timeouts which can be controlled separately, the +value set here is only a cap on those. +

+
+
tlpktdrop=1|0
+

Too-late Packet Drop. When enabled on receiver, it skips +missing packets that have not been delivered in time and +delivers the following packets to the application when +their time-to-play has come. It also sends a fake ACK to +the sender. When enabled on sender and enabled on the +receiving peer, the sender drops the older packets that +have no chance of being delivered in time. It was +automatically enabled in the sender if the receiver +supports it. +

+
+
sndbuf=bytes
+

Set send buffer size, expressed in bytes. +

+
+
rcvbuf=bytes
+

Set receive buffer size, expressed in bytes. +

+

Receive buffer must not be greater than ffs. +

+
+
lossmaxttl=packets
+

The value up to which the Reorder Tolerance may grow. When +Reorder Tolerance is > 0, then packet loss report is delayed +until that number of packets come in. Reorder Tolerance +increases every time a "belated" packet has come, but it +wasn’t due to retransmission (that is, when UDP packets tend +to come out of order), with the difference between the latest +sequence and this packet’s sequence, and not more than the +value of this option. By default it’s 0, which means that this +mechanism is turned off, and the loss report is always sent +immediately upon experiencing a "gap" in sequences. +

+
+
minversion
+

The minimum SRT version that is required from the peer. A connection +to a peer that does not satisfy the minimum version requirement +will be rejected. +

+

The version format in hex is 0xXXYYZZ for x.y.z in human readable +form. +

+
+
streamid=string
+

A string limited to 512 characters that can be set on the socket prior +to connecting. This stream ID will be able to be retrieved by the +listener side from the socket that is returned from srt_accept and +was connected by a socket with that set stream ID. SRT does not enforce +any special interpretation of the contents of this string. +This option doesn’t make sense in Rendezvous connection; the result +might be that simply one side will override the value from the other +side and it’s the matter of luck which one would win +

+
+
srt_streamid=string
+

Alias for ‘streamid’ to avoid conflict with ffmpeg command line option. +

+
+
smoother=live|file
+

The type of Smoother used for the transmission for that socket, which +is responsible for the transmission and congestion control. The Smoother +type must be exactly the same on both connecting parties, otherwise +the connection is rejected. +

+
+
messageapi=1|0
+

When set, this socket uses the Message API, otherwise it uses Buffer +API. Note that in live mode (see transtype) there’s only +message API available. In File mode you can chose to use one of two modes: +

+

Stream API (default, when this option is false). In this mode you may +send as many data as you wish with one sending instruction, or even use +dedicated functions that read directly from a file. The internal facility +will take care of any speed and congestion control. When receiving, you +can also receive as many data as desired, the data not extracted will be +waiting for the next call. There is no boundary between data portions in +the Stream mode. +

+

Message API. In this mode your single sending instruction passes exactly +one piece of data that has boundaries (a message). Contrary to Live mode, +this message may span across multiple UDP packets and the only size +limitation is that it shall fit as a whole in the sending buffer. The +receiver shall use as large buffer as necessary to receive the message, +otherwise the message will not be given up. When the message is not +complete (not all packets received or there was a packet loss) it will +not be given up. +

+
+
transtype=live|file
+

Sets the transmission type for the socket, in particular, setting this +option sets multiple other parameters to their default values as required +for a particular transmission type. +

+

live: Set options as for live transmission. In this mode, you should +send by one sending instruction only so many data that fit in one UDP packet, +and limited to the value defined first in payload_size (1316 is +default in this mode). There is no speed control in this mode, only the +bandwidth control, if configured, in order to not exceed the bandwidth with +the overhead transmission (retransmitted and control packets). +

+

file: Set options as for non-live transmission. See messageapi +for further explanations +

+
+
linger=seconds
+

The number of seconds that the socket waits for unsent data when closing. +Default is -1. -1 means auto (off with 0 seconds in live mode, on with 180 +seconds in file mode). The range for this option is integers in the +0 - INT_MAX. +

+
+
tsbpd=1|0
+

When true, use Timestamp-based Packet Delivery mode. The default behavior +depends on the transmission type: enabled in live mode, disabled in file +mode. +

+
+
+ +

For more information see: https://github.com/Haivision/srt. +

+ +

3.37 srtp

+ +

Secure Real-time Transport Protocol. +

+

The accepted options are: +

+
srtp_in_suite
+
srtp_out_suite
+

Select input and output encoding suites. +

+

Supported values: +

+
‘AES_CM_128_HMAC_SHA1_80’
+
‘SRTP_AES128_CM_HMAC_SHA1_80’
+
‘AES_CM_128_HMAC_SHA1_32’
+
‘SRTP_AES128_CM_HMAC_SHA1_32’
+
+ +
+
srtp_in_params
+
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. +

+
+ + +

3.38 subfile

+ +

Virtually extract a segment of a file or another stream. +The underlying stream must be seekable. +

+

Accepted options: +

+
start
+

Start offset of the extracted segment, in bytes. +

+
end
+

End offset of the extracted segment, in bytes. +If set to 0, extract till end of file. +

+
+ +

Examples: +

+

Extract a chapter from a DVD VOB file (start and end sectors obtained +externally and multiplied by 2048): +

+
subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
+
+ +

Play an AVI file directly from a TAR archive: +

+
subfile,,start,183241728,end,366490624,,:archive.tar
+
+ +

Play a MPEG-TS file from start offset till end: +

+
subfile,,start,32815239,end,0,,:video.ts
+
+ + +

3.39 tee

+ +

Writes the output to multiple protocols. The individual outputs are separated +by | +

+
+
tee:file://path/to/local/this.avi|file://path/to/local/that.avi
+
+ + +

3.40 tcp

+ +

Transmission Control Protocol. +

+

The required syntax for a TCP url is: +

+
tcp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen=2|1|0
+

Listen for an incoming connection. 0 disables listen, 1 enables listen in +single client mode, 2 enables listen in multi-client mode. Default value is 0. +

+
+
local_addr=addr
+

Local IP address of a network interface used for tcp socket connect. +

+
+
local_port=port
+

Local port used for tcp socket connect. +

+
+
timeout=microseconds
+

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. +

+
+
listen_timeout=milliseconds
+

Set listen timeout, expressed in milliseconds. +

+
+
recv_buffer_size=bytes
+

Set receive buffer size, expressed bytes. +

+
+
send_buffer_size=bytes
+

Set send buffer size, expressed bytes. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_mss=bytes
+

Set maximum segment size for outgoing TCP packets, expressed in bytes. +

+
+ +

The following example shows how to setup a listening TCP connection +with ffmpeg, which is then accessed with ffplay: +

+
ffmpeg -i input -f format tcp://hostname:port?listen
+ffplay tcp://hostname:port
+
+ + +

3.41 tls

+ +

Transport Layer Security (TLS) / Secure Sockets Layer (SSL) +

+

The required syntax for a TLS/SSL url is: +

+
tls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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 other backends, +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. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
http_proxy
+

The HTTP proxy to tunnel through, e.g. http://example.com:1234. +The proxy must support the CONNECT method. +

+
+
+ +

Example command lines: +

+

To create a TLS/SSL server that serves an input stream. +

+
+
ffmpeg -i input -f format tls://hostname:port?listen&cert=server.crt&key=server.key
+
+ +

To play back a stream from the TLS/SSL server using ffplay: +

+
+
ffplay tls://hostname:port
+
+ + +

3.42 dtls

+ +

Datagram Transport Layer Security (DTLS) +

+

The required syntax for a DTLS URL is: +

+
dtls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

DTLS shares most options with TLS, but operates over UDP instead of TCP. +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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. +

+

This is disabled by default since it requires a CA database to be +provided by the caller in many cases. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
cert_pem=string
+

Certificate PEM string +

+
+
key_pem=string
+

Private key PEM string +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
mtu=size
+

Set the Maximum Transmission Unit (MTU) for DTLS packets. +

+
+
use_srtp=1|0
+

Enable the use_srtp DTLS extension. +This is used in WebRTC applications to establish SRTP encryption keys +through the DTLS handshake. Default is disabled. +

+
+
external_sock=1|0
+

Use an external socket instead of creating a new one. +This option only makes sense to pass when interacting with the code via +API, enabling this from CLI will cause immediate failure. +Default is disabled. +

+
+
+ +

Example command lines: +

+

To create a DTLS server: +

+
+
ffmpeg -listen 1 -i dtls://hostname:port output
+
+ +

To create a DTLS client and send data to server: +

+
+
ffmpeg -i input -f format dtls://hostname:port
+
+ + +

3.43 udp

+ +

User Datagram Protocol. +

+

The required syntax for an UDP URL is: +

+
udp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

In case threading is enabled on the system, a circular buffer is used +to store the incoming data, which allows one to reduce loss of data due to +UDP socket buffer overruns. The fifo_size and +overrun_nonfatal options are related to this buffer. +

+

The list of supported options follows. +

+
+
buffer_size=size
+

Set the UDP maximum socket buffer size in bytes. This is used to set either +the receive or send buffer size, depending on what the socket is used for. +Default is 32 KB for output, 384 KB for input. See also fifo_size. +

+
+
bitrate=bitrate
+

If set to nonzero, the output will have the specified constant bitrate if the +input has enough packets to sustain it. +

+
+
burst_bits=bits
+

When using bitrate this specifies the maximum number of bits in +packet bursts. +

+
+
localport=port
+

Override the local UDP port to bind with. +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
pkt_size=size
+

Set the size in bytes of UDP packets. +

+
+
reuse=1|0
+

Explicitly allow or disallow reusing UDP sockets. +

+
+
ttl=ttl
+

Set the time to live value (for multicast only). +

+
+
dscp=dscp
+

Set the 6-bit DSCP field for outgoing packets. +

+
+
connect=1|0
+

Initialize the UDP socket with connect(). In this case, the +destination address can’t be changed with ff_udp_set_remote_url later. +If the destination address isn’t known at the start, this option can +be specified in ff_udp_set_remote_url, too. +This allows finding out the source address for the packets with getsockname, +and makes writes return with AVERROR(ECONNREFUSED) if "destination +unreachable" is received. +For receiving, this gives the benefit of only receiving packets from +the specified peer address/port. +

+
+
sources=address[,address]
+

Only receive packets sent from the specified addresses. In case of multicast, +also subscribe to multicast traffic coming from these addresses only. +

+
+
block=address[,address]
+

Ignore packets sent from the specified addresses. In case of multicast, also +exclude the source addresses in the multicast subscription. +

+
+
fifo_size=units
+

Set the UDP receiving circular buffer size, expressed as a number of +packets with size of 188 bytes. If not specified defaults to 7*4096. +

+
+
overrun_nonfatal=1|0
+

Survive in case of UDP receiving circular buffer overrun. Default +value is 0. +

+
+
timeout=microseconds
+

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. +

+
+
broadcast=1|0
+

Explicitly allow or disallow UDP broadcasting. +

+

Note that broadcasting may not work properly on networks having +a broadcast storm protection. +

+
+ + +

3.43.1 Examples

+ +
    +
  • Use ffmpeg to stream over UDP to a remote endpoint: +
    +
    ffmpeg -i input -f format udp://hostname:port
    +
    + +
  • Use ffmpeg to stream in mpegts format over UDP using 188 +sized UDP packets, using a large input buffer: +
    +
    ffmpeg -i input -f mpegts udp://hostname:port?pkt_size=188&buffer_size=65535
    +
    + +
  • Use ffmpeg to receive over UDP from a remote endpoint: +
    +
    ffmpeg -i udp://[multicast-address]:port ...
    +
    +
+ + +

3.44 unix

+ +

Unix local socket +

+

The required syntax for a Unix socket URL is: +

+
+
unix://filepath
+
+ +

The following parameters can be set via command line options +(or in code via AVOptions): +

+
+
timeout
+

Timeout in ms. +

+
listen
+

Create the Unix socket in listening mode. +

+
type
+

Select socket type. +

+
‘stream Corresponds to SOCK_STREAM (reliable stream-oriented)’
+
‘datagram Corresponds to SOCK_DGRAM (unreliable packet-oriented)’
+
‘seqpacket Corresponds to SOCK_SEQPACKET (reliable packet-oriented)’
+
+
+
pkt_size
+

Maximum packet size for packet-oriented sockets (SOCK_DGRAM and +SOCK_SEQPACKET). If greater than zero, this value is used as +max_packet_size. Ignored for SOCK_STREAM. Default is 0. +

+
+ + +

3.45 zmq

+ +

ZeroMQ asynchronous messaging using the libzmq library. +

+

This library supports unicast streaming to multiple clients without relying on +an external server. +

+

The required syntax for streaming or connecting to a stream is: +

+
zmq:tcp://ip-address:port
+
+ +

Example: +Create a localhost stream on port 5555: +

+
ffmpeg -re -i input -f mpegts zmq:tcp://127.0.0.1:5555
+
+ +

Multiple clients may connect to the stream using: +

+
ffplay zmq:tcp://127.0.0.1:5555
+
+ +

Streaming to multiple clients is implemented using a ZeroMQ Pub-Sub pattern. +The server side binds to a port and publishes data. Clients connect to the +server (via IP address/port) and subscribe to the stream. The order in which +the server and client start generally does not matter. +

+

ffmpeg must be compiled with the –enable-libzmq option to support +this protocol. +

+

Options can be set on the ffmpeg/ffplay command +line. The following options are supported: +

+
+
pkt_size
+

Forces the maximum packet size for sending/receiving data. The default value is +131,072 bytes. On the server side, this sets the maximum size of sent packets +via ZeroMQ. On the clients, it sets an internal buffer size for receiving +packets. Note that pkt_size on the clients should be equal to or greater than +pkt_size on the server. Otherwise the received message may be truncated causing +decoding errors. +

+
+
+ + + +

4 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavformat +

+ + +

5 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-resampler.html b/ffmpeg-n8.1/doc/ffmpeg-resampler.html new file mode 100644 index 00000000..777b4fd6 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-resampler.html @@ -0,0 +1,350 @@ + + + + + + + FFmpeg Resampler Documentation + + + + + + +
+

+ FFmpeg Resampler Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The FFmpeg resampler provides a high-level interface to the +libswresample library audio resampling utilities. In particular it +allows one to perform audio resampling, audio channel layout rematrixing, +and convert audio format and packing layout. +

+ + +

2 Resampler Options

+ +

The audio resampler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, option=value for the aresample filter, +by setting the value explicitly in the +SwrContext options or using the libavutil/opt.h API for +programmatic use. +

+
+
uchl, used_chlayout
+

Set used input channel layout. Default is unset. This option is +only used for special remapping. +

+
+
isr, in_sample_rate
+

Set the input sample rate. Default value is 0. +

+
+
osr, out_sample_rate
+

Set the output sample rate. Default value is 0. +

+
+
isf, in_sample_fmt
+

Specify the input sample format. It is set by default to none. +

+
+
osf, out_sample_fmt
+

Specify the output sample format. It is set by default to none. +

+
+
tsf, internal_sample_fmt
+

Set the internal sample format. Default value is none. +This will automatically be chosen when it is not explicitly set. +

+
+
ichl, in_chlayout
+
ochl, out_chlayout
+

Set the input/output channel layout. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
clev, center_mix_level
+

Set the center mix level. It is a value expressed in deciBel, and must be +in the interval [-32,32]. +

+
+
slev, surround_mix_level
+

Set the surround mix level. It is a value expressed in deciBel, and must +be in the interval [-32,32]. +

+
+
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]. +

+
+
rmvol, rematrix_volume
+

Set rematrix volume. Default value is 1.0. +

+
+
rematrix_maxval
+

Set maximum output value for rematrixing. +This can be used to prevent clipping vs. preventing volume reduction. +A value of 1.0 prevents clipping. +

+
+
flags, swr_flags
+

Set flags used by the converter. Default value is 0. +

+

It supports the following individual flags: +

+
res
+

force resampling, this flag forces resampling to be used even when the +input and output sample rates match. +

+
+ +
+
dither_scale
+

Set the dither scale. Default value is 1. +

+
+
dither_method
+

Set dither method. Default value is 0. +

+

Supported values: +

+
‘rectangular’
+

select rectangular dither +

+
‘triangular’
+

select triangular dither +

+
‘triangular_hp’
+

select triangular dither with high pass +

+
‘lipshitz’
+

select Lipshitz noise shaping dither. +

+
‘shibata’
+

select Shibata noise shaping dither. +

+
‘low_shibata’
+

select low Shibata noise shaping dither. +

+
‘high_shibata’
+

select high Shibata noise shaping dither. +

+
‘f_weighted’
+

select f-weighted noise shaping dither +

+
‘modified_e_weighted’
+

select modified-e-weighted noise shaping dither +

+
‘improved_e_weighted’
+

select improved-e-weighted noise shaping dither +

+
+
+ +
+
resampler
+

Set resampling engine. Default value is swr. +

+

Supported values: +

+
‘swr’
+

select the native SW Resampler; filter options precision and cheby are not +applicable in this case. +

+
‘soxr’
+

select the SoX Resampler (where available); compensation, and filter options +filter_size, phase_shift, exact_rational, filter_type & kaiser_beta, are not +applicable in this case. +

+
+ +
+
filter_size
+

For swr only, set resampling filter size, default value is 32. +

+
+
phase_shift
+

For swr only, set resampling phase shift, default value is 10, and must be in +the interval [0,30]. +

+
+
linear_interp
+

Use linear interpolation when enabled (the default). Disable it if you want +to preserve speed instead of quality when exact_rational fails. +

+
+
exact_rational
+

For swr only, when enabled, try to use exact phase_count based on input and +output sample rate. However, if it is larger than 1 << phase_shift, +the phase_count will be 1 << phase_shift as fallback. Default is enabled. +

+
+
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). +

+
+
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’. +

+
+
cheby
+

For soxr only, selects passband rolloff none (Chebyshev) & higher-precision +approximation for ’irrational’ ratios. Default value is 0. +

+
+
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. +

+
+
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. +

+
+
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 +(min_comp = FLT_MAX). +

+
+
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 min_comp. +The default is 0.1. +

+
+
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. +

+
+
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. +

+
+
matrix_encoding
+

Select matrixed stereo encoding. +

+

It accepts the following values: +

+
‘none’
+

select none +

+
‘dolby’
+

select Dolby +

+
‘dplii’
+

select Dolby Pro Logic II +

+
+ +

Default value is none. +

+
+
filter_type
+

For swr only, select resampling filter type. This only affects resampling +operations. +

+

It accepts the following values: +

+
‘cubic’
+

select cubic +

+
‘blackman_nuttall’
+

select Blackman Nuttall windowed sinc +

+
‘kaiser’
+

select Kaiser windowed sinc +

+
+ +
+
kaiser_beta
+

For swr only, set Kaiser window beta value. Must be a double float value in the +interval [2,16], default value is 9. +

+
+
output_sample_bits
+

For swr only, set number of used output sample bits for dithering. Must be an integer in the +interval [0,64], default value is 0, which means it’s not used. +

+
+
+ + + +

3 See Also

+ +

ffmpeg, ffplay, ffprobe, +libswresample +

+ + +

4 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-scaler.html b/ffmpeg-n8.1/doc/ffmpeg-scaler.html new file mode 100644 index 00000000..e86f50ad --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-scaler.html @@ -0,0 +1,263 @@ + + + + + + + FFmpeg Scaler Documentation + + + + + + +
+

+ FFmpeg Scaler Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The FFmpeg rescaler provides a high-level interface to the libswscale +library image conversion utilities. In particular it allows one to perform +image rescaling and pixel format conversion. +

+ + +

2 Scaler Options

+ +

The video scaler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, with a few API-only exceptions noted below. +For programmatic use, they can be set explicitly in the +SwsContext options or through the libavutil/opt.h API. +

+
+
+
+
sws_flags
+

Set the scaler flags. This is also used to set the scaling +algorithm. Only a single algorithm should be selected. Default +value is ‘bicubic’. +

+

It accepts the following values: +

+
‘fast_bilinear’
+

Select fast bilinear scaling algorithm. +

+
+
‘bilinear’
+

Select bilinear scaling algorithm. +

+
+
‘bicubic’
+

Select bicubic scaling algorithm. +

+
+
‘experimental’
+

Select experimental scaling algorithm. +

+
+
‘neighbor’
+

Select nearest neighbor rescaling algorithm. +

+
+
‘area’
+

Select averaging area rescaling algorithm. +

+
+
‘bicublin’
+

Select bicubic scaling algorithm for the luma component, bilinear for +chroma components. +

+
+
‘gauss’
+

Select Gaussian rescaling algorithm. +

+
+
‘sinc’
+

Select sinc rescaling algorithm. +

+
+
‘lanczos’
+

Select Lanczos rescaling algorithm. The default width (alpha) is 3 and can be +changed by setting param0. +

+
+
‘spline’
+

Select natural bicubic spline rescaling algorithm. +

+
+
‘print_info’
+

Enable printing/debug logging. +

+
+
‘accurate_rnd’
+

Enable accurate rounding. +

+
+
‘full_chroma_int’
+

Enable full chroma interpolation. +

+
+
‘full_chroma_inp’
+

Select full chroma input. +

+
+
‘bitexact’
+

Enable bitexact output. +

+
+
‘unstable’
+

Allow the use of experimental new code. May subtly affect the output or even +produce wrong results. For testing only. +

+
+ +
+
srcw (API only)
+

Set source width. +

+
+
srch (API only)
+

Set source height. +

+
+
dstw (API only)
+

Set destination width. +

+
+
dsth (API only)
+

Set destination height. +

+
+
src_format (API only)
+

Set source pixel format (must be expressed as an integer). +

+
+
dst_format (API only)
+

Set destination pixel format (must be expressed as an integer). +

+
+
src_range (boolean)
+

If value is set to 1, indicates source is full range. Default value is +0, which indicates source is limited range. +

+
+
dst_range (boolean)
+

If value is set to 1, enable full range for destination. Default value +is 0, which enables limited range. +

+
+
gamma (boolean)
+

If value is set to 1, enable gamma correct scaling. Default value is 0. +

+
+
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. +

+
+
sws_dither
+

Set the dithering algorithm. Accepts one of the following +values. Default value is ‘auto’. +

+
+
‘auto’
+

automatic choice +

+
+
‘none’
+

no dithering +

+
+
‘bayer’
+

bayer dither +

+
+
‘ed’
+

error diffusion dither +

+
+
‘a_dither’
+

arithmetic dither, based using addition +

+
+
‘x_dither’
+

arithmetic dither, based using xor (more random/less apparent patterning that +a_dither). +

+
+
+ +
+
alphablend
+

Set the alpha blending to use when the input has alpha but the output does not. +Default value is ‘none’. +

+
+
‘uniform_color’
+

Blend onto a uniform background color +

+
+
‘checkerboard’
+

Blend onto a checkerboard +

+
+
‘none’
+

No blending +

+
+
+ +
+
+ + + +

3 See Also

+ +

ffmpeg, ffplay, ffprobe, +libswscale +

+ + +

4 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg-utils.html b/ffmpeg-n8.1/doc/ffmpeg-utils.html new file mode 100644 index 00000000..511d85f8 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg-utils.html @@ -0,0 +1,1547 @@ + + + + + + + FFmpeg Utilities Documentation + + + + + + +
+

+ FFmpeg Utilities Documentation +

+ + + + + + + +

1 Description

+ +

This document describes some generic features and utilities provided +by the libavutil library. +

+ + +

2 Syntax

+ +

This section documents the syntax and formats employed by the FFmpeg +libraries and tools. +

+ +

2.1 Quoting and escaping

+ +

FFmpeg adopts the following quoting and escaping mechanism, unless +explicitly specified. The following rules are applied: +

+
    +
  • ‘'’ and ‘\’ 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. + +
  • A special character is escaped by prefixing it with a ‘\’. + +
  • All characters enclosed between ‘''’ are included literally in the +parsed string. The quote character ‘'’ itself cannot be quoted, +so you may need to close the quote and escape it. + +
  • Leading and trailing whitespaces, unless escaped or quoted, are +removed from the parsed string. +
+ +

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 av_get_token defined in +libavutil/avstring.h can be used to parse a token quoted or +escaped according to the rules defined above. +

+

The tool tools/ffescape in the FFmpeg source tree can be used +to automatically quote or escape a string in a script. +

+ +

2.1.1 Examples

+ +
    +
  • Escape the string Crime d'Amour containing the ' special +character: +
    +
    Crime d\'Amour
    +
    + +
  • The string above contains a quote, so the ' needs to be escaped +when quoting it: +
    +
    'Crime d'\''Amour'
    +
    + +
  • Include leading or trailing whitespaces using quoting: +
    +
    '  this string starts and ends with whitespaces  '
    +
    + +
  • Escaping and quoting can be mixed together: +
    +
    ' The string '\'string\'' is a string '
    +
    + +
  • To include a literal ‘\’ you can use either escaping or quoting: +
    +
    'c:\foo' can be written as c:\\foo
    +
    +
+ + +

2.2 Date

+ +

The accepted syntax is: +

+
[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
+now
+
+ +

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. +

+ +

2.3 Time duration

+ +

There are two accepted syntaxes for expressing time duration. +

+
+
[-][HH:]MM:SS[.m...]
+
+ +

HH expresses the number of hours, MM the number of minutes +for a maximum of 2 digits, and SS the number of seconds for a +maximum of 2 digits. The m at the end expresses decimal value for +SS. +

+

or +

+
+
[-]S+[.m...][s|ms|us]
+
+ +

S expresses the number of seconds, with the optional decimal part +m. The optional literal suffixes ‘s’, ‘ms’ or ‘us’ +indicate to interpret the value as seconds, milliseconds or microseconds, +respectively. +

+

In both expressions, the optional ‘-’ indicates negative duration. +

+ +

2.3.1 Examples

+ +

The following examples are all valid time duration: +

+
+
‘55’
+

55 seconds +

+
+
‘0.2’
+

0.2 seconds +

+
+
‘200ms’
+

200 milliseconds, that’s 0.2s +

+
+
‘200000us’
+

200000 microseconds, that’s 0.2s +

+
+
‘12:03:45’
+

12 hours, 03 minutes and 45 seconds +

+
+
‘23.189’
+

23.189 seconds +

+
+ + +

2.4 Video size

+

Specify the size of the sourced video, it may be a string of the form +widthxheight, or the name of a size abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

720x480 +

+
‘pal’
+

720x576 +

+
‘qntsc’
+

352x240 +

+
‘qpal’
+

352x288 +

+
‘sntsc’
+

640x480 +

+
‘spal’
+

768x576 +

+
‘film’
+

352x240 +

+
‘ntsc-film’
+

352x240 +

+
‘sqcif’
+

128x96 +

+
‘qcif’
+

176x144 +

+
‘cif’
+

352x288 +

+
‘4cif’
+

704x576 +

+
‘16cif’
+

1408x1152 +

+
‘qqvga’
+

160x120 +

+
‘qvga’
+

320x240 +

+
‘vga’
+

640x480 +

+
‘svga’
+

800x600 +

+
‘xga’
+

1024x768 +

+
‘uxga’
+

1600x1200 +

+
‘qxga’
+

2048x1536 +

+
‘sxga’
+

1280x1024 +

+
‘qsxga’
+

2560x2048 +

+
‘hsxga’
+

5120x4096 +

+
‘wvga’
+

852x480 +

+
‘wxga’
+

1366x768 +

+
‘wsxga’
+

1600x1024 +

+
‘wuxga’
+

1920x1200 +

+
‘woxga’
+

2560x1600 +

+
‘wqsxga’
+

3200x2048 +

+
‘wquxga’
+

3840x2400 +

+
‘whsxga’
+

6400x4096 +

+
‘whuxga’
+

7680x4800 +

+
‘cga’
+

320x200 +

+
‘ega’
+

640x350 +

+
‘hd480’
+

852x480 +

+
‘hd720’
+

1280x720 +

+
‘hd1080’
+

1920x1080 +

+
‘2k’
+

2048x1080 +

+
‘2kflat’
+

1998x1080 +

+
‘2kscope’
+

2048x858 +

+
‘4k’
+

4096x2160 +

+
‘4kflat’
+

3996x2160 +

+
‘4kscope’
+

4096x1716 +

+
‘nhd’
+

640x360 +

+
‘hqvga’
+

240x160 +

+
‘wqvga’
+

400x240 +

+
‘fwqvga’
+

432x240 +

+
‘hvga’
+

480x320 +

+
‘qhd’
+

960x540 +

+
‘2kdci’
+

2048x1080 +

+
‘4kdci’
+

4096x2160 +

+
‘uhd2160’
+

3840x2160 +

+
‘uhd4320’
+

7680x4320 +

+
+ + +

2.5 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 +frame_rate_num/frame_rate_den, an integer number, a float +number or a valid video frame rate abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

30000/1001 +

+
‘pal’
+

25/1 +

+
‘qntsc’
+

30000/1001 +

+
‘qpal’
+

25/1 +

+
‘sntsc’
+

30000/1001 +

+
‘spal’
+

25/1 +

+
‘film’
+

24/1 +

+
‘ntsc-film’
+

24000/1001 +

+
+ + +

2.6 Ratio

+ +

A ratio can be expressed as an expression, or in the form +numerator: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. +

+ +

2.7 Color

+ +

It can be the name of a color as defined below (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’ or ‘0.0’ means completely +transparent, ‘0xff’ or ‘1.0’ completely opaque). If the alpha +component is not specified then ‘0xff’ is assumed. +

+

The string ‘random’ will result in a random color. +

+

The following names of colors are recognized: +

+
‘AliceBlue’
+

0xF0F8FF +

+
‘AntiqueWhite’
+

0xFAEBD7 +

+
‘Aqua’
+

0x00FFFF +

+
‘Aquamarine’
+

0x7FFFD4 +

+
‘Azure’
+

0xF0FFFF +

+
‘Beige’
+

0xF5F5DC +

+
‘Bisque’
+

0xFFE4C4 +

+
‘Black’
+

0x000000 +

+
‘BlanchedAlmond’
+

0xFFEBCD +

+
‘Blue’
+

0x0000FF +

+
‘BlueViolet’
+

0x8A2BE2 +

+
‘Brown’
+

0xA52A2A +

+
‘BurlyWood’
+

0xDEB887 +

+
‘CadetBlue’
+

0x5F9EA0 +

+
‘Chartreuse’
+

0x7FFF00 +

+
‘Chocolate’
+

0xD2691E +

+
‘Coral’
+

0xFF7F50 +

+
‘CornflowerBlue’
+

0x6495ED +

+
‘Cornsilk’
+

0xFFF8DC +

+
‘Crimson’
+

0xDC143C +

+
‘Cyan’
+

0x00FFFF +

+
‘DarkBlue’
+

0x00008B +

+
‘DarkCyan’
+

0x008B8B +

+
‘DarkGoldenRod’
+

0xB8860B +

+
‘DarkGray’
+

0xA9A9A9 +

+
‘DarkGreen’
+

0x006400 +

+
‘DarkKhaki’
+

0xBDB76B +

+
‘DarkMagenta’
+

0x8B008B +

+
‘DarkOliveGreen’
+

0x556B2F +

+
‘Darkorange’
+

0xFF8C00 +

+
‘DarkOrchid’
+

0x9932CC +

+
‘DarkRed’
+

0x8B0000 +

+
‘DarkSalmon’
+

0xE9967A +

+
‘DarkSeaGreen’
+

0x8FBC8F +

+
‘DarkSlateBlue’
+

0x483D8B +

+
‘DarkSlateGray’
+

0x2F4F4F +

+
‘DarkTurquoise’
+

0x00CED1 +

+
‘DarkViolet’
+

0x9400D3 +

+
‘DeepPink’
+

0xFF1493 +

+
‘DeepSkyBlue’
+

0x00BFFF +

+
‘DimGray’
+

0x696969 +

+
‘DodgerBlue’
+

0x1E90FF +

+
‘FireBrick’
+

0xB22222 +

+
‘FloralWhite’
+

0xFFFAF0 +

+
‘ForestGreen’
+

0x228B22 +

+
‘Fuchsia’
+

0xFF00FF +

+
‘Gainsboro’
+

0xDCDCDC +

+
‘GhostWhite’
+

0xF8F8FF +

+
‘Gold’
+

0xFFD700 +

+
‘GoldenRod’
+

0xDAA520 +

+
‘Gray’
+

0x808080 +

+
‘Green’
+

0x008000 +

+
‘GreenYellow’
+

0xADFF2F +

+
‘HoneyDew’
+

0xF0FFF0 +

+
‘HotPink’
+

0xFF69B4 +

+
‘IndianRed’
+

0xCD5C5C +

+
‘Indigo’
+

0x4B0082 +

+
‘Ivory’
+

0xFFFFF0 +

+
‘Khaki’
+

0xF0E68C +

+
‘Lavender’
+

0xE6E6FA +

+
‘LavenderBlush’
+

0xFFF0F5 +

+
‘LawnGreen’
+

0x7CFC00 +

+
‘LemonChiffon’
+

0xFFFACD +

+
‘LightBlue’
+

0xADD8E6 +

+
‘LightCoral’
+

0xF08080 +

+
‘LightCyan’
+

0xE0FFFF +

+
‘LightGoldenRodYellow’
+

0xFAFAD2 +

+
‘LightGreen’
+

0x90EE90 +

+
‘LightGrey’
+

0xD3D3D3 +

+
‘LightPink’
+

0xFFB6C1 +

+
‘LightSalmon’
+

0xFFA07A +

+
‘LightSeaGreen’
+

0x20B2AA +

+
‘LightSkyBlue’
+

0x87CEFA +

+
‘LightSlateGray’
+

0x778899 +

+
‘LightSteelBlue’
+

0xB0C4DE +

+
‘LightYellow’
+

0xFFFFE0 +

+
‘Lime’
+

0x00FF00 +

+
‘LimeGreen’
+

0x32CD32 +

+
‘Linen’
+

0xFAF0E6 +

+
‘Magenta’
+

0xFF00FF +

+
‘Maroon’
+

0x800000 +

+
‘MediumAquaMarine’
+

0x66CDAA +

+
‘MediumBlue’
+

0x0000CD +

+
‘MediumOrchid’
+

0xBA55D3 +

+
‘MediumPurple’
+

0x9370D8 +

+
‘MediumSeaGreen’
+

0x3CB371 +

+
‘MediumSlateBlue’
+

0x7B68EE +

+
‘MediumSpringGreen’
+

0x00FA9A +

+
‘MediumTurquoise’
+

0x48D1CC +

+
‘MediumVioletRed’
+

0xC71585 +

+
‘MidnightBlue’
+

0x191970 +

+
‘MintCream’
+

0xF5FFFA +

+
‘MistyRose’
+

0xFFE4E1 +

+
‘Moccasin’
+

0xFFE4B5 +

+
‘NavajoWhite’
+

0xFFDEAD +

+
‘Navy’
+

0x000080 +

+
‘OldLace’
+

0xFDF5E6 +

+
‘Olive’
+

0x808000 +

+
‘OliveDrab’
+

0x6B8E23 +

+
‘Orange’
+

0xFFA500 +

+
‘OrangeRed’
+

0xFF4500 +

+
‘Orchid’
+

0xDA70D6 +

+
‘PaleGoldenRod’
+

0xEEE8AA +

+
‘PaleGreen’
+

0x98FB98 +

+
‘PaleTurquoise’
+

0xAFEEEE +

+
‘PaleVioletRed’
+

0xD87093 +

+
‘PapayaWhip’
+

0xFFEFD5 +

+
‘PeachPuff’
+

0xFFDAB9 +

+
‘Peru’
+

0xCD853F +

+
‘Pink’
+

0xFFC0CB +

+
‘Plum’
+

0xDDA0DD +

+
‘PowderBlue’
+

0xB0E0E6 +

+
‘Purple’
+

0x800080 +

+
‘Red’
+

0xFF0000 +

+
‘RosyBrown’
+

0xBC8F8F +

+
‘RoyalBlue’
+

0x4169E1 +

+
‘SaddleBrown’
+

0x8B4513 +

+
‘Salmon’
+

0xFA8072 +

+
‘SandyBrown’
+

0xF4A460 +

+
‘SeaGreen’
+

0x2E8B57 +

+
‘SeaShell’
+

0xFFF5EE +

+
‘Sienna’
+

0xA0522D +

+
‘Silver’
+

0xC0C0C0 +

+
‘SkyBlue’
+

0x87CEEB +

+
‘SlateBlue’
+

0x6A5ACD +

+
‘SlateGray’
+

0x708090 +

+
‘Snow’
+

0xFFFAFA +

+
‘SpringGreen’
+

0x00FF7F +

+
‘SteelBlue’
+

0x4682B4 +

+
‘Tan’
+

0xD2B48C +

+
‘Teal’
+

0x008080 +

+
‘Thistle’
+

0xD8BFD8 +

+
‘Tomato’
+

0xFF6347 +

+
‘Turquoise’
+

0x40E0D0 +

+
‘Violet’
+

0xEE82EE +

+
‘Wheat’
+

0xF5DEB3 +

+
‘White’
+

0xFFFFFF +

+
‘WhiteSmoke’
+

0xF5F5F5 +

+
‘Yellow’
+

0xFFFF00 +

+
‘YellowGreen’
+

0x9ACD32 +

+
+ + +

2.8 Channel Layout

+ +

A channel layout specifies the spatial disposition of the channels in +a multi-channel audio stream. To specify a channel layout, FFmpeg +makes use of a special syntax. +

+

Individual channels are identified by an id, as given by the table +below: +

+
‘FL’
+

front left +

+
‘FR’
+

front right +

+
‘FC’
+

front center +

+
‘LFE’
+

low frequency +

+
‘BL’
+

back left +

+
‘BR’
+

back right +

+
‘FLC’
+

front left-of-center +

+
‘FRC’
+

front right-of-center +

+
‘BC’
+

back center +

+
‘SL’
+

side left +

+
‘SR’
+

side right +

+
‘TC’
+

top center +

+
‘TFL’
+

top front left +

+
‘TFC’
+

top front center +

+
‘TFR’
+

top front right +

+
‘TBL’
+

top back left +

+
‘TBC’
+

top back center +

+
‘TBR’
+

top back right +

+
‘DL’
+

downmix left +

+
‘DR’
+

downmix right +

+
‘WL’
+

wide left +

+
‘WR’
+

wide right +

+
‘SDL’
+

surround direct left +

+
‘SDR’
+

surround direct right +

+
‘LFE2’
+

low frequency 2 +

+
+ +

Standard channel layout compositions can be specified by using the +following identifiers: +

+
‘mono’
+

FC +

+
‘stereo’
+

FL+FR +

+
‘2.1’
+

FL+FR+LFE +

+
‘3.0’
+

FL+FR+FC +

+
‘3.0(back)’
+

FL+FR+BC +

+
‘4.0’
+

FL+FR+FC+BC +

+
‘quad’
+

FL+FR+BL+BR +

+
‘quad(side)’
+

FL+FR+SL+SR +

+
‘3.1’
+

FL+FR+FC+LFE +

+
‘5.0’
+

FL+FR+FC+BL+BR +

+
‘5.0(side)’
+

FL+FR+FC+SL+SR +

+
‘4.1’
+

FL+FR+FC+LFE+BC +

+
‘5.1’
+

FL+FR+FC+LFE+BL+BR +

+
‘5.1(side)’
+

FL+FR+FC+LFE+SL+SR +

+
‘6.0’
+

FL+FR+FC+BC+SL+SR +

+
‘6.0(front)’
+

FL+FR+FLC+FRC+SL+SR +

+
‘3.1.2’
+

FL+FR+FC+LFE+TFL+TFR +

+
‘hexagonal’
+

FL+FR+FC+BL+BR+BC +

+
‘6.1’
+

FL+FR+FC+LFE+BC+SL+SR +

+
‘6.1’
+

FL+FR+FC+LFE+BL+BR+BC +

+
‘6.1(front)’
+

FL+FR+LFE+FLC+FRC+SL+SR +

+
‘7.0’
+

FL+FR+FC+BL+BR+SL+SR +

+
‘7.0(front)’
+

FL+FR+FC+FLC+FRC+SL+SR +

+
‘7.1’
+

FL+FR+FC+LFE+BL+BR+SL+SR +

+
‘7.1(wide)’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC +

+
‘7.1(wide-side)’
+

FL+FR+FC+LFE+FLC+FRC+SL+SR +

+
‘5.1.2’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR +

+
‘octagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR +

+
‘cube’
+

FL+FR+BL+BR+TFL+TFR+TBL+TBR +

+
‘5.1.4’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR+TBL+TBR +

+
‘7.1.2’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR +

+
‘7.1.4’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBL+TBR +

+
‘7.2.3’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBC+LFE2 +

+
‘9.1.4’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR +

+
‘9.1.6’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR+TSL+TSR +

+
‘hexadecagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR +

+
‘binaural’
+

BIL+BIR +

+
‘downmix’
+

DL+DR +

+
‘22.2’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+BC+SL+SR+TC+TFL+TFC+TFR+TBL+TBC+TBR+LFE2+TSL+TSR+BFC+BFL+BFR +

+
+ +

A custom channel layout can be specified as a sequence of terms, separated by ’+’. +Each term can be: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.), +each optionally containing a custom name after a ’@’, (e.g. ‘FL@Left’, +‘FR@Right’, ‘FC@Center’, ‘LFE@Low_Frequency’, etc.) +
+ +

A standard channel layout can be specified by the following: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.) + +
  • the name of a standard channel layout (e.g. ‘mono’, +‘stereo’, ‘4.0’, ‘quad’, ‘5.0’, etc.) + +
  • a number of channels, in decimal, followed by ’c’, yielding the default channel +layout for that number of channels (see the function +av_channel_layout_default). Note that not all channel counts have a +default layout. + +
  • a number of channels, in decimal, followed by ’C’, yielding an unknown channel +layout with the specified number of channels. Note that not all channel layout +specification strings support unknown channel layouts. + +
  • a channel layout mask, in hexadecimal starting with "0x" (see the +AV_CH_* macros in libavutil/channel_layout.h. +
+ +

Before libavutil version 53 the trailing character "c" to specify a number of +channels was optional, but now it is required, while a channel layout mask can +also be specified as a decimal number (if and only if not followed by "c" or "C"). +

+

See also the function av_channel_layout_from_string defined in +libavutil/channel_layout.h. +

+ +

3 Expression Evaluation

+ +

When evaluating an arithmetic expression, FFmpeg uses an internal +formula evaluator, implemented through the libavutil/eval.h +interface. +

+

An expression may contain unary, binary operators, constants, and +functions. +

+

Two expressions expr1 and expr2 can be combined to form +another expression "expr1;expr2". +expr1 and expr2 are evaluated in turn, and the new +expression evaluates to the value of expr2. +

+

The following binary operators are available: +, -, +*, /, ^. +

+

The following unary operators are available: +, -. +

+

Some internal variables can be used to store and load intermediary +results. They can be accessed using the ld and st +functions with an index argument varying from 0 to 9 to specify which +internal variable to access. +

+

The following functions are available: +

+
abs(x)
+

Compute absolute value of x. +

+
+
acos(x)
+

Compute arccosine of x. +

+
+
asin(x)
+

Compute arcsine of x. +

+
+
atan(x)
+

Compute arctangent of x. +

+
+
atan2(y, x)
+

Compute principal value of the arc tangent of y/x. +

+
+
between(x, min, max)
+

Return 1 if x is greater than or equal to min and lesser than or +equal to max, 0 otherwise. +

+
+
bitand(x, y)
+
bitor(x, y)
+

Compute bitwise and/or operation on x and y. +

+

The results of the evaluation of x and 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). +

+
+
ceil(expr)
+

Round the value of expression expr upwards to the nearest +integer. For example, "ceil(1.5)" is "2.0". +

+
+
clip(x, min, max)
+

Return the value of x clipped between min and max. +

+
+
cos(x)
+

Compute cosine of x. +

+
+
cosh(x)
+

Compute hyperbolic cosine of x. +

+
+
eq(x, y)
+

Return 1 if x and y are equivalent, 0 otherwise. +

+
+
exp(x)
+

Compute exponential of x (with base e, the Euler’s number). +

+
+
floor(expr)
+

Round the value of expression expr downwards to the nearest +integer. For example, "floor(-1.5)" is "-2.0". +

+
+
gauss(x)
+

Compute Gauss function of x, corresponding to +exp(-x*x/2) / sqrt(2*PI). +

+
+
gcd(x, y)
+

Return the greatest common divisor of x and y. If both x and +y are 0 or either or both are less than zero then behavior is undefined. +

+
+
gt(x, y)
+

Return 1 if x is greater than y, 0 otherwise. +

+
+
gte(x, y)
+

Return 1 if x is greater than or equal to y, 0 otherwise. +

+
+
hypot(x, y)
+

This function is similar to the C function with the same name; it returns +"sqrt(x*x + y*y)", the length of the hypotenuse of a +right triangle with sides of length x and y, or the distance of the +point (x, y) from the origin. +

+
+
if(x, y)
+

Evaluate x, and if the result is non-zero return the result of +the evaluation of y, return 0 otherwise. +

+
+
if(x, y, z)
+

Evaluate x, and if the result is non-zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
ifnot(x, y)
+

Evaluate x, and if the result is zero return the result of the +evaluation of y, return 0 otherwise. +

+
+
ifnot(x, y, z)
+

Evaluate x, and if the result is zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
isinf(x)
+

Return 1.0 if x is +/-INFINITY, 0.0 otherwise. +

+
+
isnan(x)
+

Return 1.0 if x is NAN, 0.0 otherwise. +

+
+
ld(idx)
+

Load the value of the internal variable with index idx, which was +previously stored with st(idx, expr). +The function returns the loaded value. +

+
+
lerp(x, y, z)
+

Return linear interpolation between x and y by amount of z. +

+
+
log(x)
+

Compute natural logarithm of x. +

+
+
lt(x, y)
+

Return 1 if x is lesser than y, 0 otherwise. +

+
+
lte(x, y)
+

Return 1 if x is lesser than or equal to y, 0 otherwise. +

+
+
max(x, y)
+

Return the maximum between x and y. +

+
+
min(x, y)
+

Return the minimum between x and y. +

+
+
mod(x, y)
+

Compute the remainder of division of x by y. +

+
+
not(expr)
+

Return 1.0 if expr is zero, 0.0 otherwise. +

+
+
pow(x, y)
+

Compute the power of x elevated y, it is equivalent to +"(x)^(y)". +

+
+
print(t)
+
print(t, l)
+

Print the value of expression t with loglevel l. If l is not +specified then a default log level is used. +Return the value of the expression printed. +

+
+
random(idx)
+

Return a pseudo random value between 0.0 and 1.0. idx is the +index of the internal variable used to save the seed/state, which can be +previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+

For example, to store the seed with value 42 in the internal +variable with index 0 and print a few random values: +

+
st(0,42); print(random(0)); print(random(0)); print(random(0))
+
+ +
+
randomi(idx, min, max)
+

Return a pseudo random value in the interval between min and +max. idx is the index of the internal variable which will be used to +save the seed/state, which can be previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+
+
root(expr, max)
+

Find an input value for which the function represented by expr +with argument ld(0) is 0 in the interval 0..max. +

+

The expression in expr must denote a continuous function or the +result is undefined. +

+

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 ld(0). When the expression evaluates to +0 then the corresponding input value will be returned. +

+
+
round(expr)
+

Round the value of expression expr to the nearest integer. For example, +"round(1.5)" is "2.0". +

+
+
sgn(x)
+

Compute sign of x. +

+
+
sin(x)
+

Compute sine of x. +

+
+
sinh(x)
+

Compute hyperbolic sine of x. +

+
+
sqrt(expr)
+

Compute the square root of expr. This is equivalent to +"(expr)^.5". +

+
+
squish(x)
+

Compute expression 1/(1 + exp(4*x)). +

+
+
st(idx, expr)
+

Store the value of the expression expr in an internal +variable. idx specifies the index 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. +

+

The stored value can be retrieved with ld(var). +

+

Note: variables are currently not shared between expressions. +

+
+
tan(x)
+

Compute tangent of x. +

+
+
tanh(x)
+

Compute hyperbolic tangent of x. +

+
+
taylor(expr, x)
+
taylor(expr, x, idx)
+

Evaluate a Taylor series at x, given an expression representing +the ld(idx)-th derivative of a function at 0. +

+

When the series does not converge the result is undefined. +

+

ld(idx) is used to represent the derivative order in expr, +which means that the given expression will be evaluated multiple times +with various input values that the expression can access through +ld(idx). If idx is not specified then 0 is assumed. +

+

Note, when you have the derivatives at y instead of 0, +taylor(expr, x-y) can be used. +

+
+
time(0)
+

Return the current (wallclock) time in seconds. +

+
+
trunc(expr)
+

Round the value of expression expr towards zero to the nearest +integer. For example, "trunc(-1.5)" is "-1.0". +

+
+
while(cond, expr)
+

Evaluate expression expr while the expression cond is +non-zero, and returns the value of the last expr evaluation, or +NAN if cond was always false. +

+
+ +

The following constants are available: +

+
PI
+

area of the unit disc, approximately 3.14 +

+
E
+

exp(1) (Euler’s number), approximately 2.718 +

+
PHI
+

golden ratio (1+sqrt(5))/2, approximately 1.618 +

+
+ +

Assuming that an expression is considered "true" if it has a non-zero +value, note that: +

+

* works like AND +

+

+ works like OR +

+

For example the construct: +

+
if (A AND B) then C
+
+

is equivalent to: +

+
if(A*B, C)
+
+ +

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. +

+
y
+

10^-24 / 2^-80 +

+
z
+

10^-21 / 2^-70 +

+
a
+

10^-18 / 2^-60 +

+
f
+

10^-15 / 2^-50 +

+
p
+

10^-12 / 2^-40 +

+
n
+

10^-9 / 2^-30 +

+
u
+

10^-6 / 2^-20 +

+
m
+

10^-3 / 2^-10 +

+
c
+

10^-2 +

+
d
+

10^-1 +

+
h
+

10^2 +

+
k
+

10^3 / 2^10 +

+
K
+

10^3 / 2^10 +

+
M
+

10^6 / 2^20 +

+
G
+

10^9 / 2^30 +

+
T
+

10^12 / 2^40 +

+
P
+

10^15 / 2^50 +

+
E
+

10^18 / 2^60 +

+
Z
+

10^21 / 2^70 +

+
Y
+

10^24 / 2^80 +

+
+ + + +

4 See Also

+ +

ffmpeg, ffplay, ffprobe, +libavutil +

+ + +

5 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffmpeg.html b/ffmpeg-n8.1/doc/ffmpeg.html new file mode 100644 index 00000000..eefcfd30 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffmpeg.html @@ -0,0 +1,4109 @@ + + + + + + + ffmpeg Documentation + + + + + + +
+

+ ffmpeg Documentation +

+ + + + + + + +

1 Synopsis

+ +

ffmpeg [global_options] {[input_file_options] -i input_url} ... {[output_file_options] output_url} ... +

+ +

2 Description

+ +

ffmpeg is a universal media converter. It can read a wide variety of +inputs - including live grabbing/recording devices - filter, and transcode them +into a plethora of output formats. +

+

ffmpeg reads from an arbitrary number of inputs (which can be regular +files, pipes, network streams, grabbing devices, etc.), specified by the +-i option, and writes to an arbitrary number of outputs, which are +specified by a plain output url. Anything found on the command line which cannot +be interpreted as an option is considered to be an output url. +

+

Each input or output can, in principle, contain any number of elementary streams +of different types (video/audio/subtitle/attachment/data), though the allowed +stream counts and/or types 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 -map option (see the Stream selection +chapter). +

+

To refer to inputs/outputs in options, you must use their indices (0-based). +E.g. the first input is 0, the second is 1, etc. Similarly, +streams within an input/output are referred to by their indices. E.g. 2:3 +refers to the fourth stream in the third input or output. 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 +option on the command line multiple times. Each occurrence is +then applied to the next input or output file. +Exceptions from this rule are the global options (e.g. verbosity level), +which should be specified first. +

+

Do not mix input and output files – first specify all input files, then all +output files. Also do not mix options which belong to different files. All +options apply ONLY to the next input or output file and are reset between files. +

+

Some simple examples follow. +

+
    +
  • Convert an input media file to a different format, by re-encoding media streams: +
    +
    ffmpeg -i input.avi output.mp4
    +
    + +
  • Set the video bitrate of the output file to 64 kbit/s: +
    +
    ffmpeg -i input.avi -b:v 64k -bufsize 64k output.mp4
    +
    + +
  • Force the frame rate of the output file to 24 fps: +
    +
    ffmpeg -i input.avi -r 24 output.mp4
    +
    + +
  • Force the frame rate of the input file (valid for raw formats only) to 1 fps and +the frame rate of the output file to 24 fps: +
    +
    ffmpeg -r 1 -i input.m2v -r 24 output.mp4
    +
    +
+ +

The format option may be needed for raw input files. +

+ + +

3 Detailed description

+ +

ffmpeg builds a transcoding pipeline out of the components listed +below. The program’s operation then consists of input data chunks flowing from +the sources down the pipes towards the sinks, while being transformed by the +components they encounter along the way. +

+

The following kinds of components are available: +

    +
  • Demuxers (short for "demultiplexers") read an input source in order to +extract + +
      +
    • global properties such as metadata or chapters; +
    • list of input elementary streams and their properties +
    + +

    One demuxer instance is created for each -i option, and sends encoded +packets to decoders or muxers. +

    +

    In other literature, demuxers are sometimes called splitters, because +their main function is splitting a file into elementary streams (though some +files only contain one elementary stream). +

    +

    A schematic representation of a demuxer looks like this: +

    ┌──────────┬───────────────────────┐
    +│ demuxer  │                       │ packets for stream 0
    +╞══════════╡ elementary stream 0   ├──────────────────────►
    +│          │                       │
    +│  global  ├───────────────────────┤
    +│properties│                       │ packets for stream 1
    +│   and    │ elementary stream 1   ├──────────────────────►
    +│ metadata │                       │
    +│          ├───────────────────────┤
    +│          │                       │
    +│          │     ...........       │
    +│          │                       │
    +│          ├───────────────────────┤
    +│          │                       │ packets for stream N
    +│          │ elementary stream N   ├──────────────────────►
    +│          │                       │
    +└──────────┴───────────────────────┘
    +     ▲
    +     │
    +     │ read from file, network stream,
    +     │     grabbing device, etc.
    +     │
    +
    +
  • Decoders receive encoded (compressed) packets for an audio, video, +or subtitle elementary stream, and decode them into raw frames (arrays of +pixels for video, PCM for audio). A decoder is typically associated with (and +receives its input from) an elementary stream in a demuxer, but sometimes +may also exist on its own (see Loopback decoders). + +

    A schematic representation of a decoder looks like this: +

              ┌─────────┐
    + packets  │         │ raw frames
    +─────────►│ decoder ├────────────►
    +          │         │
    +          └─────────┘
    +
    +
  • Filtergraphs process and transform raw audio or video frames. A +filtergraph consists of one or more individual filters linked into a +graph. Filtergraphs come in two flavors - simple and complex, +configured with the -filter and -filter_complex options, +respectively. + +

    A simple filtergraph is associated with an output elementary stream; it +receives the input to be filtered from a decoder and sends filtered +output to that output stream’s encoder. +

    +

    A simple video filtergraph that performs deinterlacing (using the yadif +deinterlacer) followed by resizing (using the scale filter) can look like +this: +

    +             ┌────────────────────────┐
    +             │  simple filtergraph    │
    + frames from ╞════════════════════════╡ frames for
    + a decoder   │  ┌───────┐  ┌───────┐  │ an encoder
    +────────────►├─►│ yadif ├─►│ scale ├─►│────────────►
    +             │  └───────┘  └───────┘  │
    +             └────────────────────────┘
    +
    +

    A complex filtergraph is standalone and not associated with any specific stream. +It may have multiple (or zero) inputs, potentially of different types (audio or +video), each of which receiving data either from a decoder or another complex +filtergraph’s output. It also has one or more outputs that feed either an +encoder or another complex filtergraph’s input. +

    +

    The following example diagram represents a complex filtergraph with 3 inputs and +2 outputs (all video): +

              ┌─────────────────────────────────────────────────┐
    +          │               complex filtergraph               │
    +          ╞═════════════════════════════════════════════════╡
    + frames   ├───────┐  ┌─────────┐      ┌─────────┐  ┌────────┤ frames
    +─────────►│input 0├─►│ overlay ├─────►│ overlay ├─►│output 0├────────►
    +          ├───────┘  │         │      │         │  └────────┤
    + frames   ├───────┐╭►│         │    ╭►│         │           │
    +─────────►│input 1├╯ └─────────┘    │ └─────────┘           │
    +          ├───────┘                 │                       │
    + frames   ├───────┐ ┌─────┐ ┌─────┬─╯              ┌────────┤ frames
    +─────────►│input 2├►│scale├►│split├───────────────►│output 1├────────►
    +          ├───────┘ └─────┘ └─────┘                └────────┤
    +          └─────────────────────────────────────────────────┘
    +

    Frames from second input are overlaid over those from the first. Frames from the +third input are rescaled, then the duplicated into two identical streams. One of +them is overlaid over the combined first two inputs, with the result exposed as +the filtergraph’s first output. The other duplicate ends up being the +filtergraph’s second output. +

    +
  • Encoders receive raw audio, video, or subtitle frames and encode +them into encoded packets. The encoding (compression) process is +typically lossy - it degrades stream quality to make the output smaller; +some encoders are lossless, but at the cost of much higher output size. A +video or audio encoder receives its input from some filtergraph’s output, +subtitle encoders receive input from a decoder (since subtitle filtering is not +supported yet). Every encoder is associated with some muxer’s output +elementary stream and sends its output to that muxer. + +

    A schematic representation of an encoder looks like this: +

                 ┌─────────┐
    + raw frames  │         │ packets
    +────────────►│ encoder ├─────────►
    +             │         │
    +             └─────────┘
    +
    +
  • Muxers (short for "multiplexers") receive encoded packets for +their elementary streams from encoders (the transcoding path) or directly +from demuxers (the streamcopy path), interleave them (when there is more +than one elementary stream), and write the resulting bytes into the output file +(or pipe, network stream, etc.). + +

    A schematic representation of a muxer looks like this: +

                           ┌──────────────────────┬───────────┐
    + packets for stream 0  │                      │   muxer   │
    +──────────────────────►│  elementary stream 0 ╞═══════════╡
    +                       │                      │           │
    +                       ├──────────────────────┤  global   │
    + packets for stream 1  │                      │properties │
    +──────────────────────►│  elementary stream 1 │   and     │
    +                       │                      │ metadata  │
    +                       ├──────────────────────┤           │
    +                       │                      │           │
    +                       │     ...........      │           │
    +                       │                      │           │
    +                       ├──────────────────────┤           │
    + packets for stream N  │                      │           │
    +──────────────────────►│  elementary stream N │           │
    +                       │                      │           │
    +                       └──────────────────────┴─────┬─────┘
    +                                                    │
    +                     write to file, network stream, │
    +                         grabbing device, etc.      │
    +                                                    │
    +                                                    ▼
    +
    +
+ + +

3.1 Streamcopy

+

The simplest pipeline in ffmpeg is single-stream +streamcopy, that is copying one input elementary stream’s packets +without decoding, filtering, or encoding them. As an example, consider an input +file called INPUT.mkv with 3 elementary streams, from which we take the +second and write it to file OUTPUT.mp4. A schematic representation of +such a pipeline looks like this: +

┌──────────┬─────────────────────┐
+│ demuxer  │                     │ unused
+╞══════════╡ elementary stream 0 ├────────╳
+│          │                     │
+│INPUT.mkv ├─────────────────────┤          ┌──────────────────────┬───────────┐
+│          │                     │ packets  │                      │   muxer   │
+│          │ elementary stream 1 ├─────────►│  elementary stream 0 ╞═══════════╡
+│          │                     │          │                      │OUTPUT.mp4 │
+│          ├─────────────────────┤          └──────────────────────┴───────────┘
+│          │                     │ unused
+│          │ elementary stream 2 ├────────╳
+│          │                     │
+└──────────┴─────────────────────┘
+
+

The above pipeline can be constructed with the following commandline: +

+
ffmpeg -i INPUT.mkv -map 0:1 -c copy OUTPUT.mp4
+
+ +

In this commandline +

    +
  • there is a single input INPUT.mkv; + +
  • there are no input options for this input; + +
  • there is a single output OUTPUT.mp4; + +
  • there are two output options for this output: + +
      +
    • -map 0:1 selects the input stream to be used - from input with index 0 +(i.e. the first one) the stream with index 1 (i.e. the second one); + +
    • -c copy selects the copy encoder, i.e. streamcopy with no decoding +or encoding. +
    + +
+ +

Streamcopy is useful for changing the elementary stream count, container format, +or modifying container-level metadata. 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 a variety of factors (e.g. certain information required by the +target container is not available in the source). Applying filters is obviously +also impossible, since filters work on decoded frames. +

+

More complex streamcopy scenarios can be constructed - e.g. combining streams +from two input files into a single output: +

┌──────────┬────────────────────┐         ┌────────────────────┬───────────┐
+│ demuxer 0│                    │ packets │                    │   muxer   │
+╞══════════╡elementary stream 0 ├────────►│elementary stream 0 ╞═══════════╡
+│INPUT0.mkv│                    │         │                    │OUTPUT.mp4 │
+└──────────┴────────────────────┘         ├────────────────────┤           │
+┌──────────┬────────────────────┐         │                    │           │
+│ demuxer 1│                    │ packets │elementary stream 1 │           │
+╞══════════╡elementary stream 0 ├────────►│                    │           │
+│INPUT1.aac│                    │         └────────────────────┴───────────┘
+└──────────┴────────────────────┘
+

that can be built by the commandline +

+
ffmpeg -i INPUT0.mkv -i INPUT1.aac -map 0:0 -map 1:0 -c copy OUTPUT.mp4
+
+ +

The output -map option is used twice here, creating two streams in the +output file - one fed by the first input and one by the second. The single +instance of the -c option selects streamcopy for both of those streams. +You could also use multiple instances of this option together with +Stream specifiers to apply different values to each stream, as will be +demonstrated in following sections. +

+

A converse scenario is splitting multiple streams from a single input into +multiple outputs: +

┌──────────┬─────────────────────┐          ┌───────────────────┬───────────┐
+│ demuxer  │                     │ packets  │                   │ muxer 0   │
+╞══════════╡ elementary stream 0 ├─────────►│elementary stream 0╞═══════════╡
+│          │                     │          │                   │OUTPUT0.mp4│
+│INPUT.mkv ├─────────────────────┤          └───────────────────┴───────────┘
+│          │                     │ packets  ┌───────────────────┬───────────┐
+│          │ elementary stream 1 ├─────────►│                   │ muxer 1   │
+│          │                     │          │elementary stream 0╞═══════════╡
+└──────────┴─────────────────────┘          │                   │OUTPUT1.mp4│
+                                            └───────────────────┴───────────┘
+

built with +

+
ffmpeg -i INPUT.mkv -map 0:0 -c copy OUTPUT0.mp4 -map 0:1 -c copy OUTPUT1.mp4
+
+

Note how a separate instance of the -c option is needed for every +output file even though their values are the same. This is because non-global +options (which is most of them) only apply in the context of the file before +which they are placed. +

+

These examples can of course be further generalized into arbitrary remappings +of any number of inputs into any number of outputs. +

+ +

3.2 Transcoding

+

Transcoding is the process of decoding a stream and then encoding it +again. Since encoding tends to be computationally expensive and in most cases +degrades the stream quality (i.e. it is lossy), you should only transcode +when you need to and perform streamcopy otherwise. Typical reasons to transcode +are: +

+
    +
  • applying filters - e.g. resizing, deinterlacing, or overlaying video; resampling +or mixing audio; + +
  • you want to feed the stream to something that cannot decode the original codec. +
+

Note that ffmpeg will transcode all audio, video, and subtitle streams +unless you specify -c copy for them. +

+

Consider an example pipeline that reads an input file with one audio and one +video stream, transcodes the video and copies the audio into a single output +file. This can be schematically represented as follows +

┌──────────┬─────────────────────┐
+│ demuxer  │                     │       audio packets
+╞══════════╡ stream 0 (audio)    ├─────────────────────────────────────╮
+│          │                     │                                     │
+│INPUT.mkv ├─────────────────────┤ video    ┌─────────┐     raw        │
+│          │                     │ packets  │  video  │ video frames   │
+│          │ stream 1 (video)    ├─────────►│ decoder ├──────────────╮ │
+│          │                     │          │         │              │ │
+└──────────┴─────────────────────┘          └─────────┘              │ │
+                                                                     ▼ ▼
+                                                                     │ │
+┌──────────┬─────────────────────┐ video    ┌─────────┐              │ │
+│ muxer    │                     │ packets  │  video  │              │ │
+╞══════════╡ stream 0 (video)    │◄─────────┤ encoder ├──────────────╯ │
+│          │                     │          │(libx264)│                │
+│OUTPUT.mp4├─────────────────────┤          └─────────┘                │
+│          │                     │                                     │
+│          │ stream 1 (audio)    │◄────────────────────────────────────╯
+│          │                     │
+└──────────┴─────────────────────┘
+

and implemented with the following commandline: +

+
ffmpeg -i INPUT.mkv -map 0:v -map 0:a -c:v libx264 -c:a copy OUTPUT.mp4
+
+

Note how it uses stream specifiers :v and :a to select input +streams and apply different values of the -c option to them; see the +Stream specifiers section for more details. +

+ + +

3.3 Filtering

+ +

When transcoding, audio and video streams can be filtered before encoding, with +either a simple or complex filtergraph. +

+ +

3.3.1 Simple filtergraphs

+ +

Simple filtergraphs are those that have exactly one input and output, both of +the same type (audio or video). They are configured with the per-stream +-filter option (with -vf and -af aliases for +-filter:v (video) and -filter:a (audio) respectively). Note +that simple filtergraphs are tied to their output stream, so e.g. if you have +multiple audio streams, -af will create a separate filtergraph for each +one. +

+

Taking the transcoding example from above, adding filtering (and omitting audio, +for clarity) makes it look like this: +

┌──────────┬───────────────┐
+│ demuxer  │               │          ┌─────────┐
+╞══════════╡ video stream  │ packets  │  video  │ frames
+│INPUT.mkv │               ├─────────►│ decoder ├─────►───╮
+│          │               │          └─────────┘         │
+└──────────┴───────────────┘                              │
+                                  ╭───────────◄───────────╯
+                                  │   ┌────────────────────────┐
+                                  │   │  simple filtergraph    │
+                                  │   ╞════════════════════════╡
+                                  │   │  ┌───────┐  ┌───────┐  │
+                                  ╰──►├─►│ yadif ├─►│ scale ├─►├╮
+                                      │  └───────┘  └───────┘  ││
+                                      └────────────────────────┘│
+                                                                │
+                                                                │
+┌──────────┬───────────────┐ video    ┌─────────┐               │
+│ muxer    │               │ packets  │  video  │               │
+╞══════════╡ video stream  │◄─────────┤ encoder ├───────◄───────╯
+│OUTPUT.mp4│               │          │         │
+│          │               │          └─────────┘
+└──────────┴───────────────┘
+
+ +

3.3.2 Complex filtergraphs

+ +

Complex filtergraphs are those which cannot be described as simply a linear +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. Complex filtergraphs are configured with the +-filter_complex option. Note that this option is global, since a +complex filtergraph, by its nature, cannot be unambiguously associated with a +single stream or file. Each instance of -filter_complex creates a new +complex filtergraph, and there can be any number of them. +

+

A trivial example of a complex filtergraph is the overlay filter, which +has two video inputs and one video output, containing one video overlaid on top +of the other. Its audio counterpart is the amix filter. +

+ +

3.4 Loopback decoders

+

While decoders are normally associated with demuxer streams, it is also possible +to create "loopback" decoders that decode the output from some encoder and allow +it to be fed back to complex filtergraphs. This is done with the -dec +directive, which takes as a parameter the index of the output stream that should +be decoded. Every such directive creates a new loopback decoder, indexed with +successive integers starting at zero. These indices should then be used to refer +to loopback decoders in complex filtergraph link labels, as described in the +documentation for -filter_complex. +

+

Decoding AVOptions can be passed to loopback decoders by placing them before +-dec, analogously to input/output options. +

+

E.g. the following example: +

+
+
ffmpeg -i INPUT                                        \
+  -map 0:v:0 -c:v libx264 -crf 45 -f null -            \
+  -threads 3 -dec 0:0                                  \
+  -filter_complex '[0:v][dec:0]hstack[stack]'          \
+  -map '[stack]' -c:v ffv1 OUTPUT
+
+ +

reads an input video and +

    +
  • (line 2) encodes it with libx264 at low quality; + +
  • (line 3) decodes this encoded stream using 3 threads; + +
  • (line 4) places decoded video side by side with the original input video; + +
  • (line 5) combined video is then losslessly encoded and written into +OUTPUT. + +
+ +

Such a transcoding pipeline can be represented with the following diagram: +

┌──────────┬───────────────┐
+│ demuxer  │               │   ┌─────────┐            ┌─────────┐    ┌────────────────────┐
+╞══════════╡ video stream  │   │  video  │            │  video  │    │ null muxer         │
+│   INPUT  │               ├──►│ decoder ├──┬────────►│ encoder ├─┬─►│(discards its input)│
+│          │               │   └─────────┘  │         │(libx264)│ │  └────────────────────┘
+└──────────┴───────────────┘                │         └─────────┘ │
+                                 ╭───────◄──╯   ┌─────────┐       │
+                                 │              │loopback │       │
+                                 │ ╭─────◄──────┤ decoder ├────◄──╯
+                                 │ │            └─────────┘
+                                 │ │
+                                 │ │
+                                 │ │  ┌───────────────────┐
+                                 │ │  │complex filtergraph│
+                                 │ │  ╞═══════════════════╡
+                                 │ │  │  ┌─────────────┐  │
+                                 ╰─╫─►├─►│   hstack    ├─►├╮
+                                   ╰─►├─►│             │  ││
+                                      │  └─────────────┘  ││
+                                      └───────────────────┘│
+                                                           │
+┌──────────┬───────────────┐  ┌─────────┐                  │
+│ muxer    │               │  │  video  │                  │
+╞══════════╡ video stream  │◄─┤ encoder ├───────◄──────────╯
+│  OUTPUT  │               │  │ (ffv1)  │
+│          │               │  └─────────┘
+└──────────┴───────────────┘
+
+ + + +

4 Stream selection

+ +

ffmpeg provides the -map option for manual control of stream selection in each +output file. Users can skip -map and let ffmpeg perform automatic stream selection as +described below. The -vn / -an / -sn / -dn options can be used to skip inclusion of +video, audio, subtitle and data streams respectively, whether manually mapped or automatically +selected, except for those streams which are outputs of complex filtergraphs. +

+ +

4.1 Description

+

The sub-sections that follow describe the various rules that are involved in stream selection. +The examples that follow next show how these rules are applied in practice. +

+

While every effort is made to accurately reflect the behavior of the program, FFmpeg is under +continuous development and the code may have changed since the time of this writing. +

+ +

4.1.1 Automatic stream selection

+ +

In the absence of any map options for a particular output file, ffmpeg inspects the output +format to check which type of streams can be included in it, viz. video, audio and/or +subtitles. For each acceptable stream type, ffmpeg will pick one stream, when available, +from among all the inputs. +

+

It will select that stream 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 found but there’s a caveat. +The output format’s default subtitle encoder can be either text-based or image-based, +and only a subtitle stream of the same type will be chosen. +
+ +

In the case where several streams of the same type rate equally, the stream with the lowest +index is chosen. +

+

Data or attachment streams are not automatically selected and can only be included +using -map. +

+

4.1.2 Manual stream selection

+ +

When -map is used, only user-mapped streams are included in that output file, +with one possible exception for filtergraph outputs described below. +

+ +

4.1.3 Complex filtergraphs

+ +

If there are any complex filtergraph output streams with unlabeled pads, they will be added +to the first output file. This will lead to a fatal error if the stream type is not supported +by the output format. In the absence of the map option, the inclusion of these streams leads +to the automatic stream selection of their types being skipped. If map options are present, +these filtergraph streams are included in addition to the mapped streams. +

+

Complex filtergraph output streams with labeled pads must be mapped once and exactly once. +

+ +

4.1.4 Stream handling

+ +

Stream handling is independent of stream selection, with an exception for subtitles described +below. Stream handling is set via the -codec option addressed to streams within a +specific output file. In particular, codec options are applied by ffmpeg after the +stream selection process and thus do not influence the latter. If no -codec option is +specified for a stream type, ffmpeg will select the default encoder registered by the output +file muxer. +

+

An exception exists for subtitles. If a subtitle encoder is specified for an output file, the +first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate +if the specified encoder can convert the selected stream or if the converted stream is acceptable +within the output format. This applies generally as well: when the user sets an encoder manually, +the stream selection process cannot check if the encoded stream can be muxed into the output file. +If it cannot, ffmpeg will abort and all output files will fail to be processed. +

+ +

4.2 Examples

+ +

The following examples illustrate the behavior, quirks and limitations of ffmpeg’s stream +selection methods. +

+

They assume the following three input files. +

+
+input file 'A.avi'
+      stream 0: video 640x360
+      stream 1: audio 2 channels
+
+input file 'B.mp4'
+      stream 0: video 1920x1080
+      stream 1: audio 2 channels
+      stream 2: subtitles (text)
+      stream 3: audio 5.1 channels
+      stream 4: subtitles (text)
+
+input file 'C.mkv'
+      stream 0: video 1280x720
+      stream 1: audio 2 channels
+      stream 2: subtitles (image)
+
+ +
+
ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
+
+

There are three output files specified, and for the first two, no -map options +are set, so ffmpeg will select streams for these two files automatically. +

+

out1.mkv is a Matroska container file and accepts video, audio and subtitle streams, +so ffmpeg will try to select one of each type.
+For video, it will select stream 0 from B.mp4, which has the highest +resolution among all the input video streams.
+For audio, it will select stream 3 from B.mp4, since it has the greatest +number of channels.
+For subtitles, it will select stream 2 from B.mp4, which is the first subtitle +stream from among A.avi and B.mp4. +

+

out2.wav accepts only audio streams, so only stream 3 from B.mp4 is +selected. +

+

For out3.mov, since a -map option is set, no automatic stream selection will +occur. The -map 1:a option will select all audio streams from the second input +B.mp4. No other streams will be included in this output file. +

+

For the first two outputs, all included streams will be transcoded. The encoders chosen will +be the default ones registered by each output format, which may not match the codec of the +selected input streams. +

+

For the third output, codec option for audio streams has been set +to copy, so no decoding-filtering-encoding operations will occur, or can occur. +Packets of selected streams shall be conveyed from the input file and muxed within the output +file. +

+ +
+
ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
+
+

Although out1.mkv is a Matroska container file which accepts subtitle streams, only a +video and audio stream shall be selected. The subtitle stream of C.mkv is image-based +and the default subtitle encoder of the Matroska muxer is text-based, so a transcode operation +for the subtitles is expected to fail and hence the stream isn’t selected. However, in +out2.mkv, a subtitle encoder is specified in the command and so, the subtitle stream is +selected, in addition to the video stream. The presence of -an disables audio stream +selection for out2.mkv. +

+ +
+
ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
+
+

A filtergraph is setup here using the -filter_complex option and consists of a single +video filter. The overlay filter requires exactly two video inputs, but none are +specified, so the first two available video streams are used, those of A.avi and +C.mkv. The output pad of the filter has no label and so is sent to the first output file +out1.mp4. Due to this, automatic selection of the video stream is skipped, which would +have selected the stream in B.mp4. The audio stream with most channels viz. stream 3 +in B.mp4, is chosen automatically. No subtitle stream is chosen however, since the MP4 +format has no default subtitle encoder registered, and the user hasn’t specified a subtitle encoder. +

+

The 2nd output file, out2.srt, only accepts text-based subtitle streams. So, even though +the first subtitle stream available belongs to C.mkv, it is image-based and hence skipped. +The selected stream, stream 2 in B.mp4, is the first text-based subtitle stream. +

+ +
+
ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+       -map '[outv]' -an        out1.mp4 \
+                                out2.mkv \
+       -map '[outv]' -map 1:a:0 out3.mkv
+
+ +

The above command will fail, as the output pad labelled [outv] has been mapped twice. +None of the output files shall be processed. +

+
+
ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+       -an        out1.mp4 \
+                  out2.mkv \
+       -map 1:a:0 out3.mkv
+
+ +

This command above will also fail as the hue filter output has a label, [outv], +and hasn’t been mapped anywhere. +

+

The command should be modified as follows, +

+
ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
+        -map '[outv1]' -an        out1.mp4 \
+                                  out2.mkv \
+        -map '[outv2]' -map 1:a:0 out3.mkv
+
+

The video stream from B.mp4 is sent to the hue filter, whose output is cloned once using +the split filter, and both outputs labelled. Then a copy each is mapped to the first and third +output files. +

+

The overlay filter, requiring two video inputs, uses the first two unused video streams. Those +are the streams from A.avi and C.mkv. The overlay output isn’t labelled, so it is +sent to the first output file out1.mp4, regardless of the presence of the -map option. +

+

The aresample filter is sent the first unused audio stream, that of A.avi. Since this filter +output is also unlabelled, it too is mapped to the first output file. The presence of -an +only suppresses automatic or manual stream selection of audio streams, not outputs sent from +filtergraphs. Both these mapped streams shall be ordered before the mapped stream in out1.mp4. +

+

The video, audio and subtitle streams mapped to out2.mkv are entirely determined by +automatic stream selection. +

+

out3.mkv consists of the cloned video output from the hue filter and the first audio +stream from B.mp4. +
+

+ + +

5 Options

+ +

All the numerical options, if not specified otherwise, accept a string +representing a number as input, which may be followed by one of the SI +unit prefixes, for example: ’K’, ’M’, or ’G’. +

+

If ’i’ is appended to the SI unit prefix, the complete prefix will be +interpreted as a unit prefix for binary multiples, which are based on +powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit +prefix multiplies the value by 8. This allows using, for example: +’KB’, ’MiB’, ’G’ and ’B’ as number suffixes. +

+

Options which do not take arguments are boolean options, and set the +corresponding value to true. They can be set to false by prefixing +the option name with "no". For example using "-nofoo" +will set the boolean option with name "foo" to false. +

+

Options that take arguments support a special syntax where the argument given on +the command line is interpreted as a path to the file from which the actual +argument value is loaded. To use this feature, add a forward slash ’/’ +immediately before the option name (after the leading dash). E.g. +

+
ffmpeg -i INPUT -/filter:v filter.script OUTPUT
+
+

will load a filtergraph description from the file named filter.script. +

+ +

5.1 Stream specifiers

+

Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers +are used to precisely specify which stream(s) a given option belongs to. +

+

A stream specifier is a string generally appended to the option name and +separated from it by a colon. E.g. -codec:a:1 ac3 contains the +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, so that the option is applied to all +of them. E.g. the stream specifier in -b:a 128k matches all audio +streams. +

+

An empty stream specifier matches all streams. For example, -codec copy +or -codec: copy would copy all the streams without reencoding. +

+

Possible forms of stream specifiers are: +

+
stream_index
+

Matches the stream with this index. E.g. -threads:1 4 would set the +thread count for the second stream to 4. If stream_index is used as an +additional stream specifier (see below), then it selects stream number +stream_index from the matching streams. Stream numbering is based on the +order of the streams as detected by libavformat except when a stream group +specifier or program ID is also specified. In this case it is based on the +ordering of the streams in the group or program. +

+
stream_type[:additional_stream_specifier]
+

stream_type is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’ +for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video +streams, ’V’ only matches video streams which are not attached pictures, video +thumbnails or cover arts. If additional_stream_specifier is used, then +it matches streams which both have this type and match the +additional_stream_specifier. Otherwise, it matches all streams of the +specified type. +

+
g:group_specifier[:additional_stream_specifier]
+

Matches streams which are in the group with the specifier group_specifier. +if additional_stream_specifier is used, then it matches streams which both +are part of the group and match the additional_stream_specifier. +group_specifier may be one of the following: +

+
group_index
+

Match the stream with this group index. +

+
#group_id or i:group_id
+

Match the stream with this group id. +

+
+
+
p:program_id[:additional_stream_specifier]
+

Matches streams which are in the program with the id program_id. If +additional_stream_specifier is used, then it matches streams which both +are part of the program and match the additional_stream_specifier. +

+
+
#stream_id or i:stream_id
+

Match the stream by stream id (e.g. PID in MPEG-TS container). +

+
m:key[:value]
+

Matches streams with the metadata tag key having the specified value. If +value is not given, matches streams that contain the given tag with any +value. The colon character ’:’ in key or value needs to be +backslash-escaped. +

+
disp:dispositions[:additional_stream_specifier]
+

Matches streams with the given disposition(s). dispositions is a list of +one or more dispositions (as printed by the -dispositions option) +joined with ’+’. +

+
u
+

Matches streams with usable configuration, the codec must be defined and the +essential information such as video dimension or audio sample rate must be present. +

+

Note that in ffmpeg, matching by metadata will only work properly for +input files. +

+
+ + +

5.2 Generic options

+ +

These options are shared amongst the ff* tools. +

+
+
-L, -license
+

Show license. +

+
+
-h, -?, -help, --help [arg]
+

Show help. An optional parameter may be specified to print help about a specific +item. If no argument is specified, only basic (non advanced) tool +options are shown. +

+

Possible values of arg are: +

+
long
+

Print advanced tool options in addition to the basic tool options. +

+
+
full
+

Print complete list of options, including shared and private options +for encoders, decoders, demuxers, muxers, filters, etc. +

+
+
decoder=decoder_name
+

Print detailed information about the decoder named decoder_name. Use the +-decoders option to get a list of all decoders. +

+
+
encoder=encoder_name
+

Print detailed information about the encoder named encoder_name. Use the +-encoders option to get a list of all encoders. +

+
+
demuxer=demuxer_name
+

Print detailed information about the demuxer named demuxer_name. Use the +-formats option to get a list of all demuxers and muxers. +

+
+
muxer=muxer_name
+

Print detailed information about the muxer named muxer_name. Use the +-formats option to get a list of all muxers and demuxers. +

+
+
filter=filter_name
+

Print detailed information about the filter named filter_name. Use the +-filters option to get a list of all filters. +

+
+
bsf=bitstream_filter_name
+

Print detailed information about the bitstream filter named bitstream_filter_name. +Use the -bsfs option to get a list of all bitstream filters. +

+
+
protocol=protocol_name
+

Print detailed information about the protocol named protocol_name. +Use the -protocols option to get a list of all protocols. +

+
+ +
+
-version
+

Show version. +

+
+
-buildconf
+

Show the build configuration, one option per line. +

+
+
-formats
+

Show available formats (including devices). +

+
+
-demuxers
+

Show available demuxers. +

+
+
-muxers
+

Show available muxers. +

+
+
-devices
+

Show available devices. +

+
+
-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. +

+
+
-decoders
+

Show available decoders. +

+
+
-encoders
+

Show all available encoders. +

+
+
-bsfs
+

Show available bitstream filters. +

+
+
-protocols
+

Show available protocols. +

+
+
-filters
+

Show available libavfilter filters. +

+
+
-pix_fmts
+

Show available pixel formats. +

+
+
-sample_fmts
+

Show available sample formats. +

+
+
-layouts
+

Show channel names and standard channel layouts. +

+
+
-dispositions
+

Show stream dispositions. +

+
+
-colors
+

Show recognized color names. +

+
+
-sources device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sources of the input device. +Some devices may provide system-dependent source names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sources pulse,server=192.168.0.4
+
+ +
+
-sinks device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sinks of the output device. +Some devices may provide system-dependent sink names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sinks pulse,server=192.168.0.4
+
+ +
+
-loglevel [flags+]loglevel | -v [flags+]loglevel
+

Set logging level and flags used by the library. +

+

The optional flags prefix can consist of the following values: +

+
‘repeat’
+

Indicates that repeated log output should not be compressed to the first line +and the "Last message repeated n times" line will be omitted. +

+
‘level’
+

Indicates that log output should add a [level] prefix to each message +line. This can be used as an alternative to log coloring, e.g. when dumping the +log to file. +

+
‘time’
+

Indicates that log lines should be prefixed with time information. +

+
‘datetime’
+

Indicates that log lines should be prefixed with date and time information. +

+
+

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single +flag without affecting other flags or changing loglevel. When +setting both flags and loglevel, a ’+’ separator is expected +between the last flags value and before loglevel. +

+

loglevel is a string or a number containing one of the following values: +

+
‘quiet, -8’
+

Show nothing at all; be silent. +

+
‘panic, 0’
+

Only show fatal errors which could lead the process to crash, such as +an assertion failure. This is not currently used for anything. +

+
‘fatal, 8’
+

Only show fatal errors. These are errors after which the process absolutely +cannot continue. +

+
‘error, 16’
+

Show all errors, including ones which can be recovered from. +

+
‘warning, 24’
+

Show all warnings and errors. Any message related to possibly +incorrect or unexpected events will be shown. +

+
‘info, 32’
+

Show informative messages during processing. This is in addition to +warnings and errors. This is the default value. +

+
‘verbose, 40’
+

Same as info, except more verbose. +

+
‘debug, 48’
+

Show everything, including debugging information. +

+
‘trace, 56’
+
+ +

For example to enable repeated log output, add the level prefix, and set +loglevel to verbose: +

+
ffmpeg -loglevel repeat+level+verbose -i input output
+
+

Another example that enables repeated log output without affecting current +state of level prefix flag or loglevel: +

+
ffmpeg [...] -loglevel +repeat
+
+ +

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 +AV_LOG_FORCE_NOCOLOR, or can be forced setting +the environment variable AV_LOG_FORCE_COLOR. +

+
+
-report
+

Dump full command line and log output to a file named +program-YYYYMMDD-HHMMSS.log in the current +directory. +This file can be useful for bug reports. +It also implies -loglevel debug. +

+

Setting the environment variable FFREPORT to any value has the +same effect. If the value is a ’:’-separated key=value sequence, these +options will affect the report; option 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 options are recognized: +

+
file
+

set the file name to use for the report; %p is expanded to the name +of the program, %t is expanded to a timestamp, %% is expanded +to a plain % +

+
level
+

set the log verbosity level using a numerical value (see -loglevel). +

+
+ +

For example, to output a report to a file named ffreport.log +using a log level of 32 (alias for log level info): +

+
+
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+ +

Errors in parsing the environment variable are not fatal, and will not +appear in the report. +

+
+
-hide_banner
+

Suppress printing banner. +

+

All FFmpeg tools will normally show a copyright notice, build options +and library versions. This option can be used to suppress printing +this information. +

+
+
-cpuflags flags (global)
+

Allows setting and clearing cpu flags. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpuflags -sse+mmx ...
+ffmpeg -cpuflags mmx ...
+ffmpeg -cpuflags 0 ...
+
+

Possible flags for this option are: +

+
‘x86’
+
+
‘mmx’
+
‘mmxext’
+
‘sse’
+
‘sse2’
+
‘sse2slow’
+
‘sse3’
+
‘sse3slow’
+
‘ssse3’
+
‘atom’
+
‘sse4.1’
+
‘sse4.2’
+
‘avx’
+
‘avx2’
+
‘xop’
+
‘fma3’
+
‘fma4’
+
‘3dnow’
+
‘3dnowext’
+
‘bmi1’
+
‘bmi2’
+
‘cmov’
+
+
+
‘ARM’
+
+
‘armv5te’
+
‘armv6’
+
‘armv6t2’
+
‘vfp’
+
‘vfpv3’
+
‘neon’
+
‘setend’
+
+
+
‘AArch64’
+
+
‘armv8’
+
‘vfp’
+
‘neon’
+
+
+
‘PowerPC’
+
+
‘altivec’
+
+
+
‘Specific Processors’
+
+
‘pentium2’
+
‘pentium3’
+
‘pentium4’
+
‘k6’
+
‘k62’
+
‘athlon’
+
‘athlonxp’
+
‘k8’
+
+
+
+ +
+
-cpucount count (global)
+

Override detection of CPU count. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpucount 2
+
+ +
+
-max_alloc bytes
+

Set the maximum size limit for allocating a block on the heap by ffmpeg’s +family of malloc functions. Exercise extreme caution when using +this option. Don’t use if you do not understand the full consequence of doing so. +Default is INT_MAX. +

+
+ + +

5.3 AVOptions

+ +

These options are provided directly by the libavformat, libavdevice and +libavcodec libraries. To see the list of available AVOptions, use the +-help option. They are separated into two categories: +

+
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. +

+
private
+

These options are specific to the given container, device or codec. Private +options are listed under their corresponding containers/devices/codecs. +

+
+ +

For example to write an ID3v2.3 header instead of a default ID3v2.4 to +an MP3 file, use the id3v2_version private option of the MP3 +muxer: +

+
ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+ +

All codec AVOptions are per-stream, and thus a stream specifier +should be attached to them: +

+
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+ +

In the above example, a multichannel audio stream is mapped twice for output. +The first instance is encoded with codec ac3 and bitrate 640k. +The second instance is downmixed to 2 channels and encoded with codec aac. A bitrate of 128k is specified for it using +absolute index of the output stream. +

+

Note: the -nooption syntax cannot be used for boolean +AVOptions, use -option 0/-option 1. +

+

Note: the 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. +

+ +

5.4 Main options

+ +
+
-f fmt (input/output)
+

Force input or output file format. The format is normally auto detected for input +files and guessed from the file extension for output files, so this option is not +needed in most cases. +

+
+
-i url (input)
+

input file url +

+
+
-y (global)
+

Overwrite output files without asking. +

+
+
-n (global)
+

Do not overwrite output files, and exit immediately if a specified +output file already exists. +

+
+
-stream_loop number (input)
+

Set number of times input stream shall be looped. Loop 0 means no loop, +loop -1 means infinite loop. +

+
+
-recast_media (global)
+

Allow forcing a decoder of a different media type than the one +detected or designated by the demuxer. Useful for decoding media +data muxed as data streams. +

+
+
-c[:stream_specifier] codec (input/output,per-stream)
+
-codec[:stream_specifier] codec (input/output,per-stream)
+

Select an encoder (when used before an output file) or a decoder (when used +before an input file) for one or more streams. codec is the name of a +decoder/encoder or a special value copy (output only) to indicate that +the stream is not to be re-encoded. +

+

For example +

+
ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+
+

encodes all video streams with libx264 and copies all audio streams. +

+

For each stream, the last matching c option is applied, so +

+
ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+
+

will copy all the streams except the second video, which will be encoded with +libx264, and the 138th audio, which will be encoded with libvorbis. +

+
+
-t duration (input/output)
+

When used as an input option (before -i), limit the duration of +data read from the input file. +

+

When used as an output option (before an output url), stop writing the +output after its duration reaches duration. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

-to and -t are mutually exclusive and -t has priority. +

+
+
-to position (input/output)
+

Stop writing the output or reading the input at position. +position must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

-to and -t are mutually exclusive and -t has priority. +

+
+
-fs limit_size (output)
+

Set the file size limit, expressed in bytes. No further chunk of bytes is written +after the limit is exceeded. The size of the output file is slightly more than the +requested file size. +

+
+
-ss position (input/output)
+

When used as an input option (before -i), seeks in this input file to +position. Note that in most formats it is not possible to seek exactly, +so ffmpeg will seek to the closest seek point before position. +When transcoding and -accurate_seek is enabled (the default), this +extra segment between the seek point and position will be decoded and +discarded. When doing stream copy or when -noaccurate_seek is used, it +will be preserved. +

+

When used as an output option (before an output url), decodes but discards +input until the timestamps reach position. +

+

position must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+
+
-sseof position (input)
+
+

Like the -ss option but relative to the "end of file". That is negative +values are earlier in the file, 0 is at EOF. +

+
+
-isync input_index (input)
+

Assign an input as a sync source. +

+

This will take the difference between the start times of the target and reference inputs and +offset the timestamps of the target file by that difference. The source timestamps of the two +inputs should derive from the same clock source for expected results. If copyts is set +then start_at_zero must also be set. If either of the inputs has no starting timestamp +then no sync adjustment is made. +

+

Acceptable values are those that refer to a valid ffmpeg input index. If the sync reference is +the target index itself or -1, then no adjustment is made to target timestamps. A sync +reference may not itself be synced to any other input. +

+

Default value is -1. +

+
+
-itsoffset offset (input)
+

Set the input time offset. +

+

offset must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

The offset is added to the timestamps of the input files. Specifying +a positive offset means that the corresponding streams are delayed by +the time duration specified in offset. +

+
+
-itsscale scale (input,per-stream)
+

Rescale input timestamps. scale should be a floating point number. +

+
+
-timestamp date (output)
+

Set the recording timestamp in the container. +

+

date must be a date specification, +see the Date section in the ffmpeg-utils(1) manual. +

+
+
-metadata[:metadata_specifier] key=value (output,per-metadata)
+

Set a metadata key/value pair. +

+

An optional metadata_specifier may be given to set metadata +on streams, chapters or programs. See -map_metadata +documentation for details. +

+

This option overrides metadata set with -map_metadata. It is +also possible to delete metadata by using an empty value. +

+

For example, for setting the title in the output file: +

+
ffmpeg -i in.avi -metadata title="my title" out.flv
+
+ +

To set the language of the first audio stream: +

+
ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
+
+ +
+
-disposition[:stream_specifier] value (output,per-stream)
+

Sets the disposition flags for a stream. +

+

Default value: by default, all disposition flags are copied from the input stream, +unless the output stream this option applies to is fed by a complex filtergraph +- in that case no disposition flags are set by default. +

+

value is a sequence of disposition flags separated by ’+’ or ’-’. A ’+’ +prefix adds the given disposition, ’-’ removes it. If the first flag is also +prefixed with ’+’ or ’-’, the resulting disposition is the default value +updated by value. If the first flag is not prefixed, the resulting +disposition is value. It is also possible to clear the disposition by +setting it to 0. +

+

If no -disposition options were specified for an output file, ffmpeg will +automatically set the ’default’ disposition flag on the first stream of each type, +when there are multiple streams of this type in the output file and no stream of +that type is already marked as default. +

+

The -dispositions option lists the known disposition flags. +

+

For example, to make the second audio stream the default stream: +

+
ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
+
+ +

To make the second subtitle stream the default stream and remove the default +disposition from the first subtitle stream: +

+
ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
+
+ +

To add an embedded cover/thumbnail: +

+
ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
+
+ +

To add the ’original’ and remove the ’comment’ disposition flag from the first +audio stream without removing its other disposition flags: +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 +original-comment out.mkv
+
+ +

To remove the ’original’ and add the ’comment’ disposition flag to the first +audio stream without removing its other disposition flags: +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 -original+comment out.mkv
+
+ +

To set only the ’original’ and ’comment’ disposition flags on the first audio +stream (and remove its other disposition flags): +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 original+comment out.mkv
+
+ +

To remove all disposition flags from the first audio stream: +

+
ffmpeg -i in.mkv -c copy -disposition:a:0 0 out.mkv
+
+ +

Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG. +

+
+
-program [title=title:][program_num=program_num:]st=stream[:st=stream...] (output)
+
+

Creates a program with the specified title, program_num and adds the specified +stream(s) to it. +

+
+
-stream_group [map=input_file_id=stream_group][type=type:]st=stream[:st=stream][:stg=stream_group][:id=stream_group_id...] (output)
+
+

Creates a stream group of the specified type and stream_group_id, or by +mapping an input group, adding the specified stream(s) and/or previously +defined stream_group(s) to it. +

+

type can be one of the following: +

+
iamf_audio_element
+

Groups streams that belong to the same IAMF Audio Element +

+

For this group type, the following options are available +

+
audio_element_type
+

The Audio Element type. The following values are supported: +

+
+
channel
+

Scalable channel audio representation +

+
scene
+

Ambisonics representation +

+
+ +
+
demixing
+

Demixing information used to reconstruct a scalable channel audio representation. +This option must be separated from the rest with a ’,’, and takes the following +key=value options +

+
+
parameter_id
+

An identifier parameters blocks in frames may refer to +

+
dmixp_mode
+

A pre-defined combination of demixing parameters +

+
+ +
+
recon_gain
+

Recon gain information used to reconstruct a scalable channel audio representation. +This option must be separated from the rest with a ’,’, and takes the following +key=value options +

+
+
parameter_id
+

An identifier parameters blocks in frames may refer to +

+
+ +
+
layer
+

A layer defining a Channel Layout in the Audio Element. +This option must be separated from the rest with a ’,’. Several ’,’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options +

+
+
ch_layout
+

The layer’s channel layout +

+
flags
+

The following flags are available: +

+
+
recon_gain
+

Whether to signal if recon_gain is present as metadata in parameter blocks within frames +

+
+ +
+
output_gain
+
output_gain_flags
+

Which channels output_gain applies to. The following flags are available: +

+
+
FL
+
FR
+
BL
+
BR
+
TFL
+
TFR
+
+ +
+
ambisonics_mode
+

The ambisonics mode. This has no effect if audio_element_type is set to channel. +

+

The following values are supported: +

+
+
mono
+

Each ambisonics channel is coded as an individual mono stream in the group +

+
+ +
+
+ +
+
default_w
+

Default weight value +

+
+
+ +
+
iamf_mix_presentation
+

Groups streams that belong to all IAMF Audio Element the same +IAMF Mix Presentation references +

+

For this group type, the following options are available +

+
+
submix
+

A sub-mix within the Mix Presentation. +This option must be separated from the rest with a ’,’. Several ’,’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options +

+
+
parameter_id
+

An identifier parameters blocks in frames may refer to, for post-processing the mixed +audio signal to generate the audio signal for playback +

+
parameter_rate
+

The sample rate duration fields in parameters blocks in frames that refer to this +parameter_id are expressed as +

+
default_mix_gain
+

Default mix gain value to apply when there are no parameter blocks sharing the same +parameter_id for a given frame +

+
+
element
+

References an Audio Element used in this Mix Presentation to generate the final output +audio signal for playback. +This option must be separated from the rest with a ’|’. Several ’|’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options: +

+
+
stg
+

The stream_group_id for an Audio Element which this sub-mix refers to +

+
parameter_id
+

An identifier parameters blocks in frames may refer to, for applying any processing to +the referenced and rendered Audio Element before being summed with other processed Audio +Elements +

+
parameter_rate
+

The sample rate duration fields in parameters blocks in frames that refer to this +parameter_id are expressed as +

+
default_mix_gain
+

Default mix gain value to apply when there are no parameter blocks sharing the same +parameter_id for a given frame +

+
annotations
+

A key=value string describing the sub-mix element where "key" is a string conforming to +BCP-47 that specifies the language for the "value" string. "key" must be the same as the +one in the mix’s annotations +

+
headphones_rendering_mode
+

Indicates whether the input channel-based Audio Element is rendered to stereo loudspeakers +or spatialized with a binaural renderer when played back on headphones. +This has no effect if the referenced Audio Element’s audio_element_type is set to +channel. +

+

The following values are supported: +

+
+
stereo
+
binaural
+
+ +
+
+ +
+
layout
+

Specifies the layouts for this sub-mix on which the loudness information was measured. +This option must be separated from the rest with a ’|’. Several ’|’ separated entries +can be defined, and at least one must be set. +

+

It takes the following ":"-separated key=value options: +

+
+
layout_type
+
+
+
loudspeakers
+

The layout follows the loudspeaker sound system convention of ITU-2051-3. +

+
binaural
+

The layout is binaural. +

+
+ +
+
sound_system
+

Channel layout matching one of Sound Systems A to J of ITU-2051-3, plus 7.1.2 and 3.1.2 +This has no effect if layout_type is set to binaural. +

+
integrated_loudness
+

The program integrated loudness information, as defined in ITU-1770-4. +

+
digital_peak
+

The digital (sampled) peak value of the audio signal, as defined in ITU-1770-4. +

+
true_peak
+

The true peak of the audio signal, as defined in ITU-1770-4. +

+
dialog_anchored_loudness
+

The Dialogue loudness information, as defined in ITU-1770-4. +

+
album_anchored_loudness
+

The Album loudness information, as defined in ITU-1770-4. +

+
+ +
+
+ +
+
annotations
+

A key=value string string describing the mix where "key" is a string conforming to BCP-47 +that specifies the language for the "value" string. "key" must be the same as the ones in +all sub-mix element’s annotationss +

+
+ +
+
+ +

E.g. to create an scalable 5.1 IAMF file from several WAV input files +

+
ffmpeg -i front.wav -i back.wav -i center.wav -i lfe.wav
+-map 0:0 -map 1:0 -map 2:0 -map 3:0 -c:a opus
+-stream_group type=iamf_audio_element:id=1:st=0:st=1:st=2:st=3,
+demixing=parameter_id=998,
+recon_gain=parameter_id=101,
+layer=ch_layout=stereo,
+layer=ch_layout=5.1(side),
+-stream_group type=iamf_mix_presentation:id=2:stg=0:annotations=en-us=Mix_Presentation,
+submix=parameter_id=100:parameter_rate=48000|element=stg=0:parameter_id=100:annotations=en-us=Scalable_Submix|layout=sound_system=stereo|layout=sound_system=5.1(side)
+-streamid 0:0 -streamid 1:1 -streamid 2:2 -streamid 3:3 output.iamf
+
+ +

To copy the two stream groups (Audio Element and Mix Presentation) from an input IAMF file with four +streams into an mp4 output +

+
ffmpeg -i input.iamf -c:a copy -stream_group map=0=0:st=0:st=1:st=2:st=3 -stream_group map=0=1:stg=0
+-streamid 0:0 -streamid 1:1 -streamid 2:2 -streamid 3:3 output.mp4
+
+ +
+
-target type (output)
+

Specify target file type (vcd, svcd, dvd, dv, +dv50). type may be prefixed with pal-, ntsc- or +film- to use the corresponding standard. All the format options +(bitrate, codecs, buffer sizes) are then set automatically. You can just type: +

+
+
ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
+
+ +

Nevertheless you can specify additional options as long as you know +they do not conflict with the standard, as in: +

+
+
ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+
+ +

The parameters set for each target are as follows. +

+

VCD +

+
pal:
+-f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
+-s 352x288 -r 25
+-codec:v mpeg1video -g 15 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
+-ar 44100 -ac 2
+-codec:a mp2 -b:a 224k
+
+ntsc:
+-f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
+-s 352x240 -r 30000/1001
+-codec:v mpeg1video -g 18 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
+-ar 44100 -ac 2
+-codec:a mp2 -b:a 224k
+
+film:
+-f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
+-s 352x240 -r 24000/1001
+-codec:v mpeg1video -g 18 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
+-ar 44100 -ac 2
+-codec:a mp2 -b:a 224k
+
+ +

SVCD +

+
pal:
+-f svcd -packetsize 2324
+-s 480x576 -pix_fmt yuv420p -r 25
+-codec:v mpeg2video -g 15 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
+-ar 44100
+-codec:a mp2 -b:a 224k
+
+ntsc:
+-f svcd -packetsize 2324
+-s 480x480 -pix_fmt yuv420p -r 30000/1001
+-codec:v mpeg2video -g 18 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
+-ar 44100
+-codec:a mp2 -b:a 224k
+
+film:
+-f svcd -packetsize 2324
+-s 480x480 -pix_fmt yuv420p -r 24000/1001
+-codec:v mpeg2video -g 18 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
+-ar 44100
+-codec:a mp2 -b:a 224k
+
+ +

DVD +

+
pal:
+-f dvd -muxrate 10080k -packetsize 2048
+-s 720x576 -pix_fmt yuv420p -r 25
+-codec:v mpeg2video -g 15 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
+-ar 48000
+-codec:a ac3 -b:a 448k
+
+ntsc:
+-f dvd -muxrate 10080k -packetsize 2048
+-s 720x480 -pix_fmt yuv420p -r 30000/1001
+-codec:v mpeg2video -g 18 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
+-ar 48000
+-codec:a ac3 -b:a 448k
+
+film:
+-f dvd -muxrate 10080k -packetsize 2048
+-s 720x480 -pix_fmt yuv420p -r 24000/1001
+-codec:v mpeg2video -g 18 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
+-ar 48000
+-codec:a ac3 -b:a 448k
+
+ +

DV +

+
pal:
+-f dv
+-s 720x576 -pix_fmt yuv420p -r 25
+-ar 48000 -ac 2
+
+ntsc:
+-f dv
+-s 720x480 -pix_fmt yuv411p -r 30000/1001
+-ar 48000 -ac 2
+
+film:
+-f dv
+-s 720x480 -pix_fmt yuv411p -r 24000/1001
+-ar 48000 -ac 2
+
+

The dv50 target is identical to the dv target except that the pixel format set is yuv422p for all three standards. +

+

Any user-set value for a parameter above will override the target preset value. In that case, the output may +not comply with the target standard. +

+
+
-dn (input/output)
+

As an input option, blocks all data streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables data recording i.e. automatic selection or +mapping of any data stream. For full manual control see the -map +option. +

+
+
-dframes number (output)
+

Set the number of data frames to output. This is an obsolete alias for +-frames:d, which you should use instead. +

+
+
-frames[:stream_specifier] framecount (output,per-stream)
+

Stop writing to the stream after framecount frames. +

+
+
-q[:stream_specifier] q (output,per-stream)
+
-qscale[:stream_specifier] q (output,per-stream)
+

Use fixed quality scale (VBR). The meaning of q/qscale is +codec-dependent. +If qscale is used without a 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. +

+
+
-filter[:stream_specifier] filtergraph (output,per-stream)
+

Create the filtergraph specified by filtergraph and use it to +filter the stream. +

+

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 filtergraph, the input is associated +to the label in, and the output to the label out. See +the ffmpeg-filters manual for more information about the filtergraph +syntax. +

+

See the -filter_complex option if you +want to create filtergraphs with multiple inputs and/or outputs. +

+
+
-reinit_filter[:stream_specifier] integer (input,per-stream)
+

This boolean option determines if the filtergraph(s) to which this stream is fed gets +reinitialized when input frame parameters change mid-stream. This option is enabled by +default as most video and all audio filters cannot handle deviation in input frame properties. +Upon reinitialization, existing filter state is lost, like e.g. the frame count n +reference available in some filters. Any frames buffered at time of reinitialization are lost. +The properties where a change triggers reinitialization are, +for video, frame resolution or pixel format; +for audio, sample format, sample rate, channel count or channel layout. +

+
+
-drop_changed[:stream_specifier] integer (input,per-stream)
+

This boolean option determines whether a frame with differing frame parameters mid-stream +gets dropped instead of leading to filtergraph reinitialization, as that would lead to loss +of filter state. Generally useful to avoid corrupted yet decodable packets in live streaming +inputs. Default is false. +

+
+
-filter_threads nb_threads (global)
+

Defines how many threads are used to process a filter pipeline. Each pipeline +will produce a thread pool with this many threads available for parallel processing. +The default is the number of available CPUs. +

+
+
-filter_buffered_frames nb_frames (global)
+

Defines the maximum number of buffered frames allowed in a filtergraph. Under +normal circumstances, a filtergraph should not buffer more than a few frames, +especially if frames are being fed to it and read from it in a balanced way +(which is the intended behavior in ffmpeg). That said, this option allows you +to limit the total number of frames buffered across all links in a filtergraph. +If more frames are generated, filtering is aborted and an error is returned. +The default value is 0, which means no limit. +

+
+
-pre[:stream_specifier] preset_name (output,per-stream)
+

Specify the preset for matching stream(s). +

+
+
-stats (global)
+

Log encoding progress/statistics as "info"-level log (see -loglevel). +It is on by default, to explicitly disable it you need to specify -nostats. +

+
+
-stats_period time (global)
+

Set period at which encoding progress/statistics are updated. Default is 0.5 seconds. +

+
+
-print_graphs (global)
+

Prints execution graph details to stderr in the format set via -print_graphs_format. +

+
+
-print_graphs_file filename (global)
+

Writes execution graph details to the specified file in the format set via -print_graphs_format. +

+
+
-print_graphs_format format (global)
+

Sets the output format (available formats are: default, compact, csv, flat, ini, json, xml, mermaid, mermaidhtml) +The default format is json. +

+
+
-progress url (global)
+

Send program-friendly progress information to url. +

+

Progress information is written periodically and at the end of +the encoding process. It is made of "key=value" lines. key +consists of only alphanumeric characters. The last key of a sequence of +progress information is always "progress" with the value "continue" or "end". +

+

The update period is set using -stats_period. +

+

For example, log progress information to stdout: +

+
+
ffmpeg -progress pipe:1 -i in.mkv out.mkv
+
+ +
+
-stdin
+

Enable interaction on standard input. On by default unless standard input is +used as an input. To explicitly disable interaction you need to specify +-nostdin. +

+

Disabling interaction on standard input is useful, for example, if +ffmpeg is in the background process group. Roughly the same result can +be achieved with ffmpeg ... < /dev/null but it requires a +shell. +

+
+
-debug_ts (global)
+

Print timestamp/latency information. It is off by default. This option is +mostly useful for testing and debugging purposes, and the output +format may change from one version to another, so it should not be +employed by portable scripts. +

+

See also the option -fdebug ts. +

+
+
-attach filename (output)
+

Add an attachment to the output file. This is supported by a few formats +like Matroska for e.g. fonts used in rendering subtitles. Attachments +are implemented as a specific type of stream, so this option will add +a new stream to the file. It is then possible to use per-stream options +on this stream in the usual way. Attachment streams created with this +option will be created after all the other streams (i.e. those created +with -map or automatic mappings). +

+

Note that for Matroska you also have to set the mimetype metadata tag: +

+
ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
+
+

(assuming that the attachment stream will be third in the output file). +

+
+
-dump_attachment[:stream_specifier] filename (input,per-stream)
+

Extract the matching attachment stream into a file named filename. If +filename is empty, then the value of the filename metadata tag +will be used. +

+

E.g. to extract the first attachment to a file named ’out.ttf’: +

+
ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
+
+

To extract all attachments to files determined by the filename tag: +

+
ffmpeg -dump_attachment:t "" -i INPUT
+
+ +

Technical note – attachments are implemented as codec extradata, so this +option can actually be used to extract extradata from any stream, not just +attachments. +

+
+ + +

5.5 Video Options

+ +
+
-vframes number (output)
+

Set the number of video frames to output. This is an obsolete alias for +-frames:v, which you should use instead. +

+
-r[:stream_specifier] fps (input/output,per-stream)
+

Set frame rate (Hz value, fraction or abbreviation). +

+

As an input option, ignore any timestamps stored in the file and instead +generate timestamps assuming constant frame rate fps. +This is not the same as the -framerate option used for some input formats +like image2 or v4l2 (it used to be the same in older versions of FFmpeg). +If in doubt use -framerate instead of the input option -r. +

+

As an output option: +

+
video encoding
+

Duplicate or drop frames right before encoding them to achieve constant output +frame rate fps. +

+
+
video streamcopy
+

Indicate to the muxer that fps is the stream frame rate. No data is +dropped or duplicated in this case. This may produce invalid files if fps +does not match the actual stream frame rate as determined by packet timestamps. +See also the setts bitstream filter. +

+
+
+ +
+
-fpsmax[:stream_specifier] fps (output,per-stream)
+

Set maximum frame rate (Hz value, fraction or abbreviation). +

+

Clamps output frame rate when output framerate is auto-set and is higher than this value. +Useful in batch processing or when input framerate is wrongly detected as very high. +It cannot be set together with -r. It is ignored during streamcopy. +

+
+
-s[:stream_specifier] size (input/output,per-stream)
+

Set frame size. +

+

As an input option, this is a shortcut for the video_size private +option, recognized by some demuxers for which the frame size is either not +stored in the file or is configurable – e.g. raw video or video grabbers. +

+

As an output option, this inserts the scale video filter to the +end of the corresponding filtergraph. Please use the scale filter +directly to insert it at the beginning or some other place. +

+

The format is ‘wxh’ (default - same as source). +

+
+
-aspect[:stream_specifier] aspect (output,per-stream)
+

Set the video display aspect ratio specified by aspect. +

+

aspect can be a floating point number string, or a string of the +form num:den, where num and 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 -vcodec copy, it will affect the aspect ratio +stored at container level, but not the aspect ratio stored in encoded +frames, if it exists. +

+
+
-display_rotation[:stream_specifier] rotation (input,per-stream)
+

Set video rotation metadata. +

+

rotation is a decimal number specifying the amount in degree by +which the video should be rotated counter-clockwise before being +displayed. +

+

This option overrides the rotation/display transform metadata stored in +the file, if any. When the video is being transcoded (rather than +copied) and -autorotate is enabled, the video will be rotated at +the filtering stage. Otherwise, the metadata will be written into the +output file if the muxer supports it. +

+

If the -display_hflip and/or -display_vflip options are +given, they are applied after the rotation specified by this option. +

+
+
-display_hflip[:stream_specifier] (input,per-stream)
+

Set whether on display the image should be horizontally flipped. +

+

See the -display_rotation option for more details. +

+
+
-display_vflip[:stream_specifier] (input,per-stream)
+

Set whether on display the image should be vertically flipped. +

+

See the -display_rotation option for more details. +

+
+
-vn (input/output)
+

As an input option, blocks all video streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables video recording i.e. automatic selection or +mapping of any video stream. For full manual control see the -map +option. +

+
+
-vcodec codec (output)
+

Set the video codec. This is an alias for -codec:v. +

+
+
-pass[:stream_specifier] n (output,per-stream)
+

Select the pass number (1 or 2). It is used to do two-pass +video encoding. The statistics of the video are recorded in the first +pass into a log file (see also the option -passlogfile), +and in the second pass that log file is used to generate the video +at the exact requested bitrate. +On pass 1, you may just deactivate audio and set output to null, +examples for Windows and Unix: +

+
ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
+ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
+
+ +
+
-passlogfile[:stream_specifier] prefix (output,per-stream)
+

Set two-pass log file name prefix to prefix, the default file name +prefix is “ffmpeg2pass”. The complete file name will be +PREFIX-N.log, where N is a number specific to the output +stream +

+
+
-vf filtergraph (output)
+

Create the filtergraph specified by filtergraph and use it to +filter the stream. +

+

This is an alias for -filter:v, see the -filter option. +

+
+
-autorotate
+

Automatically rotate the video according to file metadata. Enabled by +default, use -noautorotate to disable it. +

+
+
-autoscale
+

Automatically scale the video according to the resolution of first frame. +Enabled by default, use -noautoscale to disable it. When autoscale is +disabled, all output frames of filter graph might not be in the same resolution +and may be inadequate for some encoder/muxer. Therefore, it is not recommended +to disable it unless you really know what you are doing. +Disable autoscale at your own risk. +

+
+ + +

5.6 Advanced Video options

+ +
+
-pix_fmt[:stream_specifier] format (input/output,per-stream)
+

Set pixel format. Use -pix_fmts to show all the supported +pixel formats. +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 pix_fmt is prefixed by a +, ffmpeg will exit with an error +if the requested pixel format can not be selected, and automatic conversions +inside filtergraphs are disabled. +If pix_fmt is a single +, ffmpeg selects the same pixel format +as the input (or graph output) and automatic conversions are disabled. +

+
+
-sws_flags flags (input/output)
+

Set default flags for the libswscale library. These flags are used by +automatically inserted scale filters and those within simple +filtergraphs, if not overridden within the filtergraph definition. +

+

See the ffmpeg-scaler manual for a list +of scaler options. +

+
+
-rc_override[:stream_specifier] override (output,per-stream)
+

Rate control override for specific intervals, formatted as "int,int,int" +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. +

+
+
-vstats
+

Dump video coding statistics to vstats_HHMMSS.log. See the +vstats file format section for the format description. +

+
+
-vstats_file file
+

Dump video coding statistics to file. See the +vstats file format section for the format description. +

+
+
-vstats_version file
+

Specify which version of the vstats format to use. Default is 2. See the +vstats file format section for the format description. +

+
+
-vtag fourcc/tag (output)
+

Force video tag/fourcc. This is an alias for -tag:v. +

+
+
-force_key_frames[:stream_specifier] time[,time...] (output,per-stream)
+
-force_key_frames[:stream_specifier] expr:expr (output,per-stream)
+
-force_key_frames[:stream_specifier] source (output,per-stream)
+
-force_key_frames[:stream_specifier] scd_metadata (output,per-stream)
+
+

force_key_frames can take arguments of the following form: +

+
+
time[,time...]
+

If the argument consists of timestamps, ffmpeg will round the specified times to the nearest +output timestamp as per the encoder time base and force a keyframe at the first frame having +timestamp equal or greater than the computed timestamp. Note that if the encoder time base is too +coarse, then the keyframes may be forced on frames with timestamps lower than the specified time. +The default encoder time base is the inverse of the output framerate but may be set otherwise +via -enc_time_base. +

+

If one of the times is "chapters[delta]", it is expanded into +the time of the beginning of all chapters in the file, shifted by +delta, expressed as a time in seconds. +This option can be useful to ensure that a seek point is present at a +chapter mark or any other designated place in the output file. +

+

For example, to insert a key frame at 5 minutes, plus key frames 0.1 second +before the beginning of every chapter: +

+
-force_key_frames 0:05:00,chapters-0.1
+
+ +
+
expr:expr
+

If the argument is prefixed with expr:, the string expr +is interpreted like an expression and is evaluated for each frame. A +key frame is forced in case the evaluation is non-zero. +

+

The expression in expr can contain the following constants: +

+
n
+

the number of current processed frame, starting from 0 +

+
n_forced
+

the number of forced frames +

+
prev_forced_n
+

the number of the previous forced frame, it is NAN when no +keyframe was forced yet +

+
prev_forced_t
+

the time of the previous forced frame, it is NAN when no +keyframe was forced yet +

+
t
+

the time of the current processed frame +

+
+ +

For example to force a key frame every 5 seconds, you can specify: +

+
-force_key_frames expr:gte(t,n_forced*5)
+
+ +

To force a key frame 5 seconds after the time of the last forced one, +starting from second 13: +

+
-force_key_frames expr:if(isnan(prev_forced_t),gte(t,13),gte(t,prev_forced_t+5))
+
+ +
+
source
+

If the argument is source, ffmpeg will force a key frame if +the current frame being encoded is marked as a key frame in its source. +In cases where this particular source frame has to be dropped, +enforce the next available frame to become a key frame instead. +

+
+
scd_metadata
+

If the argument is scd_metadata, ffmpeg will force a key frame if +the current frame contains a metadata entry with the key lavfi.scd.time. +The metadata can be added by filters like scdet and scdet_vulkan. +Avoid inserting filters that duplicate frames after scdet, as this can +cause duplicate metadata for multiple frames and repeated insertion of key +frames. +

+
+
+ +

Note that forcing too many keyframes is very harmful for the lookahead +algorithms of certain encoders: using fixed-GOP options or similar +would be more efficient. +

+
+
-apply_cropping[:stream_specifier] source (input,per-stream)
+

Automatically crop the video after decoding according to file metadata. +Default is all. +

+
+
none (0)
+

Don’t apply any cropping metadata. +

+
all (1)
+

Apply both codec and container level croppping. This is the default mode. +

+
codec (2)
+

Apply codec level croppping. +

+
container (3)
+

Apply container level croppping. +

+
+ +
+
-copyinkf[:stream_specifier] (output,per-stream)
+

When doing stream copy, copy also non-key frames found at the +beginning. +

+
+
-init_hw_device type[=name][:device[,key=value...]]
+

Initialise a new hardware device of type type called name, using the +given device parameters. +If no name is specified it will receive a default name of the form "type%d". +

+

The meaning of device and the following arguments depends on the +device type: +

+
cuda
+

device is the number of the CUDA device. +

+

The following options are recognized: +

+
primary_ctx
+

If set to 1, uses the primary device context instead of creating a new one. +

+
+ +

Examples: +

+
-init_hw_device cuda:1
+

Choose the second device on the system. +

+
+
-init_hw_device cuda:0,primary_ctx=1
+

Choose the first device and use the primary device context. +

+
+ +
+
dxva2
+

device is the number of the Direct3D 9 display adapter. +

+
+
d3d11va
+

device is the number of the Direct3D 11 display adapter. +If not specified, it will attempt to use the default Direct3D 11 display adapter +or the first Direct3D 11 display adapter whose hardware VendorId is specified +by ‘vendor_id’. +

+

Examples: +

+
-init_hw_device d3d11va
+

Create a d3d11va device on the default Direct3D 11 display adapter. +

+
+
-init_hw_device d3d11va:1
+

Create a d3d11va device on the Direct3D 11 display adapter specified by index 1. +

+
+
-init_hw_device d3d11va:,vendor_id=0x8086
+

Create a d3d11va device on the first Direct3D 11 display adapter whose hardware VendorId is 0x8086. +

+
+ +
+
vaapi
+

device is either an X11 display name, a DRM render node or a DirectX adapter index. +If not specified, it will attempt to open the default X11 display ($DISPLAY) +and then the first DRM render node (/dev/dri/renderD128), or the default +DirectX adapter on Windows. +

+

The following options are recognized: +

+
kernel_driver
+

When device is not specified, use this option to specify the name of the kernel +driver associated with the desired device. This option is available only when +the hardware acceleration method drm and vaapi are enabled. +

+
vendor_id
+

When device and kernel_driver are not specified, use this option to specify +the vendor id associated with the desired device. This option is available only when the +hardware acceleration method drm and vaapi are enabled and kernel_driver +is not specified. +

+
+ +

Examples: +

+
-init_hw_device vaapi
+

Create a vaapi device on the default device. +

+
+
-init_hw_device vaapi:/dev/dri/renderD129
+

Create a vaapi device on DRM render node /dev/dri/renderD129. +

+
+
-init_hw_device vaapi:1
+

Create a vaapi device on DirectX adapter 1. +

+
+
-init_hw_device vaapi:,kernel_driver=i915
+

Create a vaapi device on a device associated with kernel driver ‘i915’. +

+
+
-init_hw_device vaapi:,vendor_id=0x8086
+

Create a vaapi device on a device associated with vendor id ‘0x8086’. +

+
+ +
+
vdpau
+

device is an X11 display name. +If not specified, it will attempt to open the default X11 display ($DISPLAY). +

+
+
qsv
+

device selects a value in ‘MFX_IMPL_*’. Allowed values are: +

+
auto
+
sw
+
hw
+
auto_any
+
hw_any
+
hw2
+
hw3
+
hw4
+
+

If not specified, ‘auto_any’ is used. +(Note that it may be easier to achieve the desired result for QSV by creating the +platform-appropriate subdevice (‘dxva2’ or ‘d3d11va’ or ‘vaapi’) and then deriving a +QSV device from that.) +

+

The following options are recognized: +

+
child_device
+

Specify a DRM render node on Linux or DirectX adapter on Windows. +

+
child_device_type
+

Choose platform-appropriate subdevice type. On Windows ‘d3d11va’ is used +as default subdevice type when --enable-libvpl is specified at configuration time, +‘dxva2’ is used as default subdevice type when --enable-libmfx is specified at +configuration time. On Linux user can use ‘vaapi’ only as subdevice type. +

+
+ +

Examples: +

+
-init_hw_device qsv:hw,child_device=/dev/dri/renderD129
+

Create a QSV device with ‘MFX_IMPL_HARDWARE’ on DRM render node /dev/dri/renderD129. +

+
+
-init_hw_device qsv:hw,child_device=1
+

Create a QSV device with ‘MFX_IMPL_HARDWARE’ on DirectX adapter 1. +

+
+
-init_hw_device qsv:hw,child_device_type=d3d11va
+

Choose the GPU subdevice with type ‘d3d11va’ and create QSV device with ‘MFX_IMPL_HARDWARE’. +

+
+
-init_hw_device qsv:hw,child_device_type=dxva2
+

Choose the GPU subdevice with type ‘dxva2’ and create QSV device with ‘MFX_IMPL_HARDWARE’. +

+
+
-init_hw_device qsv:hw,child_device=1,child_device_type=d3d11va
+

Create a QSV device with ‘MFX_IMPL_HARDWARE’ on DirectX adapter 1 with subdevice type ‘d3d11va’. +

+
+
-init_hw_device vaapi=va:/dev/dri/renderD129 -init_hw_device qsv=hw1@va
+

Create a VAAPI device called ‘va’ on /dev/dri/renderD129, then derive a QSV device called ‘hw1’ +from device ‘va’. +

+
+
+ +
+
opencl
+

device selects the platform and device as platform_index.device_index. +

+

The set of devices can also be filtered using the key-value pairs to find only +devices matching particular platform or device strings. +

+

The strings usable as filters are: +

+
platform_profile
+
platform_version
+
platform_name
+
platform_vendor
+
platform_extensions
+
device_name
+
device_vendor
+
driver_version
+
device_version
+
device_profile
+
device_extensions
+
device_type
+
+ +

The indices and filters must together uniquely select a device. +

+

Examples: +

+
-init_hw_device opencl:0.1
+

Choose the second device on the first platform. +

+
+
-init_hw_device opencl:,device_name=Foo9000
+

Choose the device with a name containing the string Foo9000. +

+
+
-init_hw_device opencl:1,device_type=gpu,device_extensions=cl_khr_fp16
+

Choose the GPU device on the second platform supporting the cl_khr_fp16 +extension. +

+
+ +
+
vulkan
+

If device is an integer, it selects the device by its index in a +system-dependent list of devices. If device is any other string, it +selects the first device with a name containing that string as a substring. +

+

The following options are recognized: +

+
debug
+

If set to 1, enables the validation layer, if installed. +

+
linear_images
+

If set to 1, images allocated by the hwcontext will be linear and locally mappable. +

+
instance_extensions
+

A plus separated list of additional instance extensions to enable. +

+
device_extensions
+

A plus separated list of additional device extensions to enable. +

+
+ +

Examples: +

+
-init_hw_device vulkan:1
+

Choose the second device on the system. +

+
+
-init_hw_device vulkan:RADV
+

Choose the first device with a name containing the string RADV. +

+
+
-init_hw_device vulkan:0,instance_extensions=VK_KHR_wayland_surface+VK_KHR_xcb_surface
+

Choose the first device and enable the Wayland and XCB instance extensions. +

+
+ +
+
+ +
+
-init_hw_device type[=name]@source
+

Initialise a new hardware device of type type called name, +deriving it from the existing device with the name source. +

+
+
-init_hw_device list
+

List all hardware device types supported in this build of ffmpeg. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +This can be used to set the device to upload to with the hwupload filter, +or the device to map to with the hwmap filter. Other filters may also +make use of this parameter when they require a hardware device. Note that this +is typically only required when the input is not already in hardware frames - +when it is, filters will derive the device they require from the context of the +frames they receive as input. +

+

This is a global setting, so all filters will receive the same device. +

+
+
-hwaccel[:stream_specifier] hwaccel (input,per-stream)
+

Use hardware acceleration to decode the matching stream(s). The allowed values +of hwaccel are: +

+
none
+

Do not use any hardware acceleration (the default). +

+
+
auto
+

Automatically select the hardware acceleration method. +

+
+
vdpau
+

Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration. +

+
+
dxva2
+

Use DXVA2 (DirectX Video Acceleration) hardware acceleration. +

+
+
d3d11va
+

Use D3D11VA (DirectX Video Acceleration) hardware acceleration. +

+
+
vaapi
+

Use VAAPI (Video Acceleration API) hardware acceleration. +

+
+
qsv
+

Use the Intel QuickSync Video acceleration for video transcoding. +

+

Unlike most other values, this option does not enable accelerated decoding (that +is used automatically whenever a qsv decoder is selected), but accelerated +transcoding, without copying the frames into the system memory. +

+

For it to work, both the decoder and the encoder must support QSV acceleration +and no filters must be used. +

+
+
videotoolbox
+

Use Video Toolbox hardware acceleration. +

+
+ +

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, 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. +

+
+
-hwaccel_device[:stream_specifier] hwaccel_device (input,per-stream)
+

Select a device to use for hardware acceleration. +

+

This option only makes sense when the -hwaccel option is also specified. +It can either refer to an existing device created with -init_hw_device +by name, or it can create a new device as if +‘-init_hw_device’ type:hwaccel_device +were called immediately before. +

+
+
-hwaccels
+

List all hardware acceleration components enabled in this build of ffmpeg. +Actual runtime availability depends on the hardware and its suitable driver +being installed. +

+
+
-fix_sub_duration_heartbeat[:stream_specifier]
+

Set a specific output video stream as the heartbeat stream according to which +to split and push through currently in-progress subtitle upon receipt of a +random access packet. +

+

This lowers the latency of subtitles for which the end packet or the following +subtitle has not yet been received. As a drawback, this will most likely lead +to duplication of subtitle events in order to cover the full duration, so +when dealing with use cases where latency of when the subtitle event is passed +on to output is not relevant this option should not be utilized. +

+

Requires -fix_sub_duration to be set for the relevant input subtitle +stream for this to have any effect, as well as for the input subtitle stream +having to be directly mapped to the same output in which the heartbeat stream +resides. +

+
+
+ + +

5.7 Audio Options

+ +
+
-aframes number (output)
+

Set the number of audio frames to output. This is an obsolete alias for +-frames:a, which you should use instead. +

+
-ar[:stream_specifier] freq (input/output,per-stream)
+

Set the audio sampling frequency. For output streams it is set by +default to the frequency of the corresponding input stream. For input +streams this option only makes sense for audio grabbing devices and raw +demuxers and is mapped to the corresponding demuxer options. +

+
-aq q (output)
+

Set the audio quality (codec-specific, VBR). This is an alias for -q:a. +

+
-ac[:stream_specifier] channels (input/output,per-stream)
+

Set the number of audio channels. For output streams it is set by +default to the number of input audio channels. For input streams +this option only makes sense for audio grabbing devices and raw demuxers +and is mapped to the corresponding demuxer options. +

+
-an (input/output)
+

As an input option, blocks all audio streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables audio recording i.e. automatic selection or +mapping of any audio stream. For full manual control see the -map +option. +

+
-acodec codec (input/output)
+

Set the audio codec. This is an alias for -codec:a. +

+
-sample_fmt[:stream_specifier] sample_fmt (output,per-stream)
+

Set the audio sample format. Use -sample_fmts to get a list +of supported sample formats. +

+
+
-af filtergraph (output)
+

Create the filtergraph specified by filtergraph and use it to +filter the stream. +

+

This is an alias for -filter:a, see the -filter option. +

+
+ + +

5.8 Advanced Audio options

+ +
+
-atag fourcc/tag (output)
+

Force audio tag/fourcc. This is an alias for -tag:a. +

+
-ch_layout[:stream_specifier] layout (input/output,per-stream)
+

Alias for -channel_layout. +

+
-channel_layout[:stream_specifier] layout (input/output,per-stream)
+

Set the audio channel layout. For output streams it is set by default to the +input channel layout. For input streams it overrides the channel layout of the +input. Not all decoders respect the overridden channel layout. This option +also sets the channel layout for audio grabbing devices and raw demuxers +and is mapped to the corresponding demuxer option. +

+
-guess_layout_max channels (input,per-stream)
+

If some input channel layout is not known, try to guess only if it +corresponds to at most the specified number of channels. For example, 2 +tells to ffmpeg to recognize 1 channel as mono and 2 channels as +stereo but not 6 channels as 5.1. The default is to always try to guess. Use +0 to disable all guessing. Using the -channel_layout option to +explicitly specify an input layout also disables guessing. +

+
+ + +

5.9 Subtitle options

+ +
+
-scodec codec (input/output)
+

Set the subtitle codec. This is an alias for -codec:s. +

+
-sn (input/output)
+

As an input option, blocks all subtitle streams of a file from being filtered or +being automatically selected or mapped for any output. See -discard +option to disable streams individually. +

+

As an output option, disables subtitle recording i.e. automatic selection or +mapping of any subtitle stream. For full manual control see the -map +option. +

+
+ + +

5.10 Advanced Subtitle options

+ +
+
-fix_sub_duration
+

Fix subtitles durations. For each subtitle, wait for the next packet in the +same stream and adjust the duration of the first to avoid overlap. This is +necessary with some subtitles codecs, especially DVB subtitles, because the +duration in the original packet is only a rough estimate and the end is +actually marked by an empty subtitle frame. Failing to use this option when +necessary can result in exaggerated durations or muxing failures due to +non-monotonic timestamps. +

+

Note that this option will delay the output of all data until the next +subtitle packet is decoded: it may increase memory consumption and latency a +lot. +

+
+
-canvas_size size
+

Set the size of the canvas used to render subtitles. +

+
+
+ + +

5.11 Advanced options

+ +
+
-map [-]input_file_id[:stream_specifier][:view_specifier][:?] | [linklabel] (output)
+
+

Create one or more streams in the output file. This option has two forms for +specifying the data source(s): the first selects one or more streams from some +input file (specified with -i), the second takes an output from some +complex filtergraph (specified with -filter_complex). +

+

In the first form, an output stream is created for every stream from the input +file with the index input_file_id. If stream_specifier is given, +only those streams that match the specifier are used (see the +Stream specifiers section for the stream_specifier syntax). +

+

A - character before the stream identifier creates a "negative" mapping. +It disables matching streams from already created mappings. +

+

An optional view_specifier may be given after the stream specifier, which +for multiview video specifies the view to be used. The view specifier may have +one of the following formats: +

+
view:view_id
+

select a view by its ID; view_id may be set to ’all’ to use all the views +interleaved into one stream; +

+
+
vidx:view_idx
+

select a view by its index; i.e. 0 is the base view, 1 is the first non-base +view, etc. +

+
+
vpos:position
+

select a view by its display position; position may be left or +right +

+
+

The default for transcoding is to only use the base view, i.e. the equivalent of +vidx:0. For streamcopy, view specifiers are not supported and all views +are always copied. +

+

A trailing ? after the stream index will allow the map to be +optional: if the map matches no streams the map will be ignored instead +of failing. Note the map will still fail if an invalid input file index +is used; such as if the map refers to a non-existent input. +

+

An alternative [linklabel] form will map outputs from complex filter +graphs (see the -filter_complex option) to the output file. +linklabel must correspond to a defined output link label in the graph. +

+

This option may be specified multiple times, each adding more streams to the +output file. Any given input stream may also be mapped any number of times as a +source for different output streams, e.g. in order to use different encoding +options and/or filters. The streams are created in the output in the same order +in which the -map options are given on the commandline. +

+

Using this option disables the default mappings for this output file. +

+

Examples: +

+
+
map everything
+

To map ALL streams from the first input file to output +

+
ffmpeg -i INPUT -map 0 output
+
+ +
+
select specific stream
+

If you have two audio streams in the first input file, these streams are +identified by 0:0 and 0:1. You can use -map to select which +streams to place in an output file. For example: +

+
ffmpeg -i INPUT -map 0:1 out.wav
+
+

will map the second input stream in INPUT to the (single) output stream +in out.wav. +

+
+
create multiple streams
+

To select the stream with index 2 from input file a.mov (specified by the +identifier 0:2), and stream with index 6 from input b.mov +(specified by the identifier 1:6), and copy them to the output file +out.mov: +

+
ffmpeg -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
+
+ +
+
create multiple streams 2
+

To select all video and the third audio stream from an input file: +

+
ffmpeg -i INPUT -map 0:v -map 0:a:2 OUTPUT
+
+ +
+
negative map
+

To map all the streams except the second audio, use negative mappings +

+
ffmpeg -i INPUT -map 0 -map -0:a:1 OUTPUT
+
+ +
+
optional map
+

To map the video and audio streams from the first input, and using the +trailing ?, ignore the audio mapping if no audio streams exist in +the first input: +

+
ffmpeg -i INPUT -map 0:v -map 0:a? OUTPUT
+
+ +
+
map by language
+

To pick the English audio stream: +

+
ffmpeg -i INPUT -map 0:m:language:eng OUTPUT
+
+ +
+
+ +
+
-ignore_unknown
+

Ignore input streams with unknown type instead of failing if copying +such streams is attempted. +

+
+
-copy_unknown
+

Allow input streams with unknown type to be copied instead of failing if copying +such streams is attempted. +

+
+
-map_metadata[:metadata_spec_out] infile[:metadata_spec_in] (output,per-metadata)
+

Set metadata information of the next output file from infile. Note that +those are file indices (zero-based), not filenames. +Optional metadata_spec_in/out parameters specify, which metadata to copy. +A metadata specifier can have the following forms: +

+
g
+

global metadata, i.e. metadata that applies to the whole file +

+
+
s[:stream_spec]
+

per-stream metadata. stream_spec is a stream specifier as described +in the Stream specifiers chapter. In an input metadata specifier, the first +matching stream is copied from. In an output metadata specifier, all matching +streams are copied to. +

+
+
c:chapter_index
+

per-chapter metadata. chapter_index is the zero-based chapter index. +

+
+
p:program_index
+

per-program metadata. program_index is the zero-based program index. +

+
+

If metadata specifier is omitted, it defaults to global. +

+

By default, global metadata is copied from the first input file, +per-stream and per-chapter metadata is copied along with streams/chapters. These +default mappings are disabled by creating any mapping of the relevant type. A negative +file index can be used to create a dummy mapping that just disables automatic copying. +

+

For example to copy metadata from the first stream of the input file to global metadata +of the output file: +

+
ffmpeg -i in.ogg -map_metadata 0:s:0 out.mp3
+
+ +

To do the reverse, i.e. copy global metadata to all audio streams: +

+
ffmpeg -i in.mkv -map_metadata:s:a 0:g out.mkv
+
+

Note that simple 0 would work as well in this example, since global +metadata is assumed by default. +

+
+
-map_chapters input_file_index (output)
+

Copy chapters from input file with index input_file_index to the next +output file. If no chapter mapping is specified, then chapters are copied from +the first input file with at least one chapter. Use a negative file index to +disable any chapter copying. +

+
+
-benchmark (global)
+

Show benchmarking information at the end of an encode. +Shows real, system and user time used and maximum memory consumption. +Maximum memory consumption is not supported on all systems, +it will usually display as 0 if not supported. +

+
-benchmark_all (global)
+

Show benchmarking information during the encode. +Shows real, system and user time used in various steps (audio/video encode/decode). +

+
-timelimit duration (global)
+

Exit after ffmpeg has been running for duration seconds in CPU user time. +

+
-dump (global)
+

Dump each input packet to stderr. +

+
-hex (global)
+

When dumping packets, also dump the payload. +

+
-readrate speed (input)
+

Limit input read speed. +

+

Its value is a floating-point positive number which represents the maximum duration of +media, in seconds, that should be ingested in one second of wallclock time. +Default value is zero and represents no imposed limitation on speed of ingestion. +Value 1 represents real-time speed and is equivalent to -re. +

+

Mainly used to simulate a capture device or live input stream (e.g. when reading from a file). +Should not be used with a low value when input is an actual capture device or live stream as +it may cause packet loss. +

+

It is useful for when flow speed of output packets is important, such as live streaming. +

+
-re (input)
+

Read input at native frame rate. This is equivalent to setting -readrate 1. +

+
-readrate_initial_burst seconds
+

Set an initial read burst time, in seconds, after which -re/-readrate +will be enforced. +

+
-readrate_catchup speed (input)
+

If either the input or output is blocked leading to actual read speed falling behind the +specified readrate, then this rate takes effect till the input catches up with the +specified readrate. Must not be lower than the primary readrate. +

+
+
-vsync parameter (global)
+
-fps_mode[:stream_specifier] parameter (output,per-stream)
+

Set video sync method / framerate mode. vsync is applied to all output video streams +but can be overridden for a stream by setting fps_mode. vsync is deprecated and will be +removed in the future. +

+

For compatibility reasons some of the values for vsync can be specified as numbers (shown +in parentheses in the following table). +

+
+
passthrough (0)
+

Each frame is passed with its timestamp from the demuxer to the muxer. +

+
cfr (1)
+

Frames will be duplicated and dropped to achieve exactly the requested +constant frame rate. +

+
vfr (2)
+

Frames are passed through with their timestamp or dropped so as to +prevent 2 frames from having the same timestamp. +

+
auto (-1)
+

Chooses between cfr and vfr depending on muxer capabilities. This is the +default method. +

+
+ +

Note that the timestamps may be further modified by the muxer, after this. +For example, in the case that the format option avoid_negative_ts +is enabled. +

+

With -map you can select from which stream the timestamps should be +taken. You can leave either video or audio unchanged and sync the +remaining stream(s) to the unchanged one. +

+
+
-frame_drop_threshold parameter
+

Frame drop threshold, which specifies how much behind video frames can +be before they are dropped. In frame rate units, so 1.0 is one frame. +The default is -1.1. One possible usecase is to avoid framedrops in case +of noisy timestamps or to increase frame drop precision in case of exact +timestamps. +

+
+
-apad parameters (output,per-stream)
+

Pad the output audio stream(s). This is the same as applying -af apad. +Argument is a string of filter parameters composed the same as with the apad filter. +-shortest must be set for this output for the option to take effect. +

+
+
-copyts
+

Do not process input timestamps, but keep their values without trying +to sanitize them. In particular, do not remove the initial start time +offset value. +

+

Note that, depending on the vsync option or on specific muxer +processing (e.g. in case the format option avoid_negative_ts +is enabled) the output timestamps may mismatch with the input +timestamps even when this option is selected. +

+
+
-start_at_zero
+

When used with copyts, shift input timestamps so they start at zero. +

+

This means that using e.g. -ss 50 will make output timestamps start at +50 seconds, regardless of what timestamp the input file started at. +

+
+
-copytb mode
+

Specify how to set the encoder timebase when stream copying. mode is an +integer numeric value, and can assume one of the following values: +

+
+
1
+

Use the demuxer timebase. +

+

The time base is copied to the output encoder from the corresponding input +demuxer. This is sometimes required to avoid non monotonically increasing +timestamps when copying video streams with variable frame rate. +

+
+
0
+

Use the decoder timebase. +

+

The time base is copied to the output encoder from the corresponding input +decoder. +

+
+
-1
+

Try to make the choice automatically, in order to generate a sane output. +

+
+ +

Default value is -1. +

+
+
-enc_time_base[:stream_specifier] timebase (output,per-stream)
+

Set the encoder timebase. timebase can assume one of the following values: +

+
+
0
+

Assign a default value according to the media type. +

+

For video - use 1/framerate, for audio - use 1/samplerate. +

+
+
demux
+

Use the timebase from the demuxer. +

+
+
filter
+

Use the timebase from the filtergraph. +

+
+
a positive number
+

Use the provided number as the timebase. +

+

This field can be provided as a ratio of two integers (e.g. 1:24, 1:48000) +or as a decimal number (e.g. 0.04166, 2.0833e-5) +

+
+ +

Default value is 0. +

+
+
-bitexact (input/output)
+

Enable bitexact mode for (de)muxer and (de/en)coder +

+
-shortest (output)
+

Finish encoding when the shortest output stream ends. +

+

Note that this option may require buffering frames, which introduces extra +latency. The maximum amount of this latency may be controlled with the +-shortest_buf_duration option. +

+
+
-shortest_buf_duration duration (output)
+

The -shortest option may require buffering potentially large amounts +of data when at least one of the streams is "sparse" (i.e. has large gaps +between frames – this is typically the case for subtitles). +

+

This option controls the maximum duration of buffered frames in seconds. +Larger values may allow the -shortest option to produce more accurate +results, but increase memory use and latency. +

+

The default value is 10 seconds. +

+
+
-dts_delta_threshold threshold
+

Timestamp discontinuity delta threshold, expressed as a decimal number +of seconds. +

+

The timestamp discontinuity correction enabled by this option is only +applied to input formats accepting timestamp discontinuity (for which +the AVFMT_TS_DISCONT flag is enabled), e.g. MPEG-TS and HLS, and +is automatically disabled when employing the -copyts option +(unless wrapping is detected). +

+

If a timestamp discontinuity is detected whose absolute value is +greater than threshold, ffmpeg will remove the discontinuity by +decreasing/increasing the current DTS and PTS by the corresponding +delta value. +

+

The default value is 10. +

+
+
-dts_error_threshold threshold
+

Timestamp error delta threshold, expressed as a decimal number of +seconds. +

+

The timestamp correction enabled by this option is only applied to +input formats not accepting timestamp discontinuity (for which the +AVFMT_TS_DISCONT flag is not enabled). +

+

If a timestamp discontinuity is detected whose absolute value is +greater than threshold, ffmpeg will drop the PTS/DTS timestamp +value. +

+

The default value is 3600*30 (30 hours), which is arbitrarily +picked and quite conservative. +

+
+
-muxdelay seconds (output)
+

Set the maximum demux-decode delay. +

+
-muxpreload seconds (output)
+

Set the initial demux-decode delay. +

+
-streamid output-stream-index:new-value (output)
+

Assign a new stream-id value to an output stream. This option should be +specified prior to the output filename to which it applies. +For the situation where multiple output files exist, a streamid +may be reassigned to a different value. +

+

For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for +an output mpegts file: +

+
ffmpeg -i inurl -streamid 0:33 -streamid 1:36 out.ts
+
+ +
+
-bsf[:stream_specifier] bitstream_filters (input/output,per-stream)
+

Apply bitstream filters to matching streams. The filters are applied to each +packet as it is received from the demuxer (when used as an input option) or +before it is sent to the muxer (when used as an output option). +

+

bitstream_filters is a comma-separated list of bitstream filter +specifications, each of the form +

+
filter[=optname0=optval0:optname1=optval1:...]
+
+

Any of the ’,=:’ characters that are to be a part of an option value need to be +escaped with a backslash. +

+

Use the -bsfs option to get the list of bitstream filters. +

+

E.g. +

+
ffmpeg -bsf:v h264_mp4toannexb -i h264.mp4 -c:v copy -an out.h264
+
+

applies the h264_mp4toannexb bitstream filter (which converts +MP4-encapsulated H.264 stream to Annex B) to the input video stream. +

+

On the other hand, +

+
ffmpeg -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
+
+

applies the mov2textsub bitstream filter (which extracts text from MOV +subtitles) to the output subtitle stream. Note, however, that since both +examples use -c copy, it matters little whether the filters are applied +on input or output - that would change if transcoding was happening. +

+
+
-tag[:stream_specifier] codec_tag (input/output,per-stream)
+

Force a tag/fourcc for matching streams. +

+
+
-timecode hh:mm:ssSEPff
+

Specify Timecode for writing. SEP is ’:’ for non drop timecode and ’;’ +(or ’.’) for drop. +

+
ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
+
+ +
+
-filter_complex filtergraph (global)
+

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 -filter options. filtergraph is a description of +the filtergraph, as described in the “Filtergraph syntax” section of the +ffmpeg-filters manual. This option may be specified multiple times - each use +creates a new complex filtergraph. +

+

Inputs to a complex filtergraph may come from different source types, +distinguished by the format of the corresponding link label: +

    +
  • To connect an input stream, use [file_index:stream_specifier] (i.e. the +same syntax as -map). If stream_specifier matches multiple +streams, the first one will be used. For multiview video, the stream specifier +may be followed by the view specifier, see documentation for the -map +option for its syntax. + +
  • To connect a loopback decoder use [dec:dec_idx], where dec_idx is +the index of the loopback decoder to be connected to given input. For multiview +video, the decoder index may be followed by the view specifier, see +documentation for the -map option for its syntax. + +
  • To connect an output from another complex filtergraph, use its link label. E.g +the following example: + +
    +
    ffmpeg -i input.mkv \
    +  -filter_complex '[0:v]scale=size=hd1080,split=outputs=2[for_enc][orig_scaled]' \
    +  -c:v libx264 -map '[for_enc]' output.mkv \
    +  -dec 0:0 \
    +  -filter_complex '[dec:0][orig_scaled]hstack[stacked]' \
    +  -map '[stacked]' -c:v ffv1 comparison.mkv
    +
    + +

    reads an input video and +

      +
    • (line 2) uses a complex filtergraph with one input and two outputs +to scale the video to 1920x1080 and duplicate the result to both +outputs; + +
    • (line 3) encodes one scaled output with libx264 and writes the result to +output.mkv; + +
    • (line 4) decodes this encoded stream with a loopback decoder; + +
    • (line 5) places the output of the loopback decoder (i.e. the +libx264-encoded video) side by side with the scaled original input; + +
    • (line 6) combined video is then losslessly encoded and written into +comparison.mkv. + +
    + +

    Note that the two filtergraphs cannot be combined into one, because then there +would be a cycle in the transcoding pipeline (filtergraph output goes to +encoding, from there to decoding, then back to the same graph), and such cycles +are not allowed. +

    +
+ +

An unlabeled input will be connected to the first unused input stream of the +matching type. +

+

Output link labels are referred to with -map. Unlabeled outputs are +added to the first output file. +

+

Note that with this option it is possible to use only lavfi sources without +normal input files. +

+

For example, to overlay an image over video +

+
ffmpeg -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
+'[out]' out.mkv
+
+

Here [0:v] refers to the first video stream in the first input file, +which is linked to the first (main) input of the overlay filter. Similarly the +first video stream in the second input is linked to the second (overlay) input +of overlay. +

+

Assuming there is only one video stream in each input file, we can omit input +labels, so the above is equivalent to +

+
ffmpeg -i video.mkv -i image.png -filter_complex 'overlay[out]' -map
+'[out]' out.mkv
+
+ +

Furthermore we can omit the output label and the single output from the filter +graph will be added to the output file automatically, so we can simply write +

+
ffmpeg -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
+
+ +

As a special exception, you can use a bitmap subtitle stream as input: it +will be converted into a video with the same size as the largest video in +the file, or 720x576 if no video is present. Note that this is an +experimental and temporary solution. It will be removed once libavfilter has +proper support for subtitles. +

+

For example, to hardcode subtitles on top of a DVB-T recording stored in +MPEG-TS format, delaying the subtitles by 1 second: +

+
ffmpeg -i input.ts -filter_complex \
+  '[#0x2ef] setpts=PTS+1/TB [sub] ; [#0x2d0] [sub] overlay' \
+  -sn -map '#0x2dc' output.mkv
+
+

(0x2d0, 0x2dc and 0x2ef are the MPEG-TS PIDs of respectively the video, +audio and subtitles streams; 0:0, 0:3 and 0:7 would have worked too) +

+

To generate 5 seconds of pure red video using lavfi color source: +

+
ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv
+
+ +
+
-filter_complex_threads nb_threads (global)
+

Defines how many threads are used to process a filter_complex graph. +Similar to filter_threads but used for -filter_complex graphs only. +The default is the number of available CPUs. +

+
+
-lavfi filtergraph (global)
+

Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or +outputs. Equivalent to -filter_complex. +

+
+
-accurate_seek (input)
+

This option enables or disables accurate seeking in input files with the +-ss option. It is enabled by default, so seeking is accurate when +transcoding. Use -noaccurate_seek to disable it, which may be useful +e.g. when copying some streams and transcoding the others. +

+
+
-seek_timestamp (input)
+

This option enables or disables seeking by timestamp in input files with the +-ss option. It is disabled by default. If enabled, the argument +to the -ss option is considered an actual timestamp, and is not +offset by the start time of the file. This matters only for files which do +not start from timestamp 0, such as transport streams. +

+
+
-thread_queue_size size (input/output)
+

For input, this option sets the maximum number of queued packets when reading +from the file or device. With low latency / high rate live streams, packets may +be discarded if they are not read in a timely manner; setting this value can +force ffmpeg to use a separate input thread and read packets as soon as they +arrive. By default ffmpeg only does this if multiple inputs are specified. +

+

For output, this option specified the maximum number of packets that may be +queued to each muxing thread. +

+
+
-sdp_file file (global)
+

Print sdp information for an output stream to file. +This allows dumping sdp information when at least one output isn’t an +rtp stream. (Requires at least one of the output formats to be rtp). +

+
+
-discard (input)
+

Allows discarding specific streams or frames from streams. +Any input stream can be fully discarded, using value all whereas +selective discarding of frames from a stream occurs at the demuxer +and is not supported by all demuxers. +

+
+
none
+

Discard no frame. +

+
+
default
+

Default, which discards no frames. +

+
+
noref
+

Discard all non-reference frames. +

+
+
bidir
+

Discard all bidirectional frames. +

+
+
nokey
+

Discard all frames excepts keyframes. +

+
+
all
+

Discard all frames. +

+
+ +
+
-abort_on flags (global)
+

Stop and abort on various conditions. The following flags are available: +

+
+
empty_output
+

No packets were passed to the muxer, the output is empty. +

+
empty_output_stream
+

No packets were passed to the muxer in some of the output streams. +

+
+ +
+
-max_error_rate (global)
+

Set fraction of decoding frame failures across all inputs which when crossed +ffmpeg will return exit code 69. Crossing this threshold does not terminate +processing. Range is a floating-point number between 0 to 1. Default is 2/3. +

+
+
-xerror (global)
+

Stop and exit on error +

+
+
-max_muxing_queue_size packets (output,per-stream)
+

When transcoding audio and/or video streams, ffmpeg will not begin writing into +the output until it has one packet for each such stream. While waiting for that +to happen, packets for other streams are buffered. This option sets the size of +this buffer, in packets, for the matching output stream. +

+

The default value of this option should be high enough for most uses, so only +touch this option if you are sure that you need it. +

+
+
-muxing_queue_data_threshold bytes (output,per-stream)
+

This is a minimum threshold until which the muxing queue size is not taken into +account. Defaults to 50 megabytes per stream, and is based on the overall size +of packets passed to the muxer. +

+
+
-auto_conversion_filters (global)
+

Enable automatically inserting format conversion filters in all filter +graphs, including those defined by -vf, -af, +-filter_complex and -lavfi. If filter format negotiation +requires a conversion, the initialization of the filters will fail. +Conversions can still be performed by inserting the relevant conversion +filter (scale, aresample) in the graph. +On by default, to explicitly disable it you need to specify +-noauto_conversion_filters. +

+
+
-bits_per_raw_sample[:stream_specifier] value (output,per-stream)
+

Declare the number of bits per raw sample in the given output stream to be +value. Note that this option sets the information provided to the +encoder/muxer, it does not change the stream to conform to this value. Setting +values that do not match the stream properties may result in encoding failures +or invalid output files. +

+
+
-stats_enc_pre[:stream_specifier] path (output,per-stream)
+
-stats_enc_post[:stream_specifier] path (output,per-stream)
+
-stats_mux_pre[:stream_specifier] path (output,per-stream)
+

Write per-frame encoding information about the matching streams into the file +given by path. +

+

-stats_enc_pre writes information about raw video or audio frames right +before they are sent for encoding, while -stats_enc_post writes +information about encoded packets as they are received from the encoder. +-stats_mux_pre writes information about packets just as they are about to +be sent to the muxer. Every frame or packet produces one line in the specified +file. The format of this line is controlled by -stats_enc_pre_fmt / +-stats_enc_post_fmt / -stats_mux_pre_fmt. +

+

When stats for multiple streams are written into a single file, the lines +corresponding to different streams will be interleaved. The precise order of +this interleaving is not specified and not guaranteed to remain stable between +different invocations of the program, even with the same options. +

+
+
-stats_enc_pre_fmt[:stream_specifier] format_spec (output,per-stream)
+
-stats_enc_post_fmt[:stream_specifier] format_spec (output,per-stream)
+
-stats_mux_pre_fmt[:stream_specifier] format_spec (output,per-stream)
+

Specify the format for the lines written with -stats_enc_pre / +-stats_enc_post / -stats_mux_pre. +

+

format_spec is a string that may contain directives of the form +{fmt}. format_spec is backslash-escaped — use \{, \}, and \\ +to write a literal {, }, or \, respectively, into the output. +

+

The directives given with fmt may be one of the following: +

+
fidx
+

Index of the output file. +

+
+
sidx
+

Index of the output stream in the file. +

+
+
n
+

Frame number. Pre-encoding: number of frames sent to the encoder so far. +Post-encoding: number of packets received from the encoder so far. +Muxing: number of packets submitted to the muxer for this stream so far. +

+
+
ni
+

Input frame number. Index of the input frame (i.e. output by a decoder) that +corresponds to this output frame or packet. -1 if unavailable. +

+
+
tb
+

Timebase in which this frame/packet’s timestamps are expressed, as a rational +number num/den. Note that encoder and muxer may use different timebases. +

+
+
tbi
+

Timebase for ptsi, as a rational number num/den. Available when +ptsi is available, 0/1 otherwise. +

+
+
pts
+

Presentation timestamp of the frame or packet, as an integer. Should be +multiplied by the timebase to compute presentation time. +

+
+
ptsi
+

Presentation timestamp of the input frame (see ni), as an integer. Should +be multiplied by tbi to compute presentation time. Printed as +(2^63 - 1 = 9223372036854775807) when not available. +

+
+
t
+

Presentation time of the frame or packet, as a decimal number. Equal to +pts multiplied by tb. +

+
+
ti
+

Presentation time of the input frame (see ni), as a decimal number. Equal +to ptsi multiplied by tbi. Printed as inf when not available. +

+
+
dts (packet)
+

Decoding timestamp of the packet, as an integer. Should be multiplied by the +timebase to compute presentation time. +

+
+
dt (packet)
+

Decoding time of the frame or packet, as a decimal number. Equal to +dts multiplied by tb. +

+
+
sn (frame,audio)
+

Number of audio samples sent to the encoder so far. +

+
+
samp (frame,audio)
+

Number of audio samples in the frame. +

+
+
size (packet)
+

Size of the encoded packet in bytes. +

+
+
br (packet)
+

Current bitrate in bits per second. +

+
+
abr (packet)
+

Average bitrate for the whole stream so far, in bits per second, -1 if it cannot +be determined at this point. +

+
+
key (packet)
+

Character ’K’ if the packet contains a keyframe, character ’N’ otherwise. +

+
+ +

Directives tagged with packet may only be used with +-stats_enc_post_fmt and -stats_mux_pre_fmt. +

+

Directives tagged with frame may only be used with +-stats_enc_pre_fmt. +

+

Directives tagged with audio may only be used with audio streams. +

+

The default format strings are: +

+
pre-encoding
+

{fidx} {sidx} {n} {t} +

+
post-encoding
+

{fidx} {sidx} {n} {t} +

+
+

In the future, new items may be added to the end of the default formatting +strings. Users who depend on the format staying exactly the same, should +prescribe it manually. +

+

Note that stats for different streams written into the same file may have +different formats. +

+
+
+ + +

5.12 Preset files

+

A preset file contains a sequence of option=value pairs, +one for each line, specifying a sequence of options which would be +awkward to specify on the command line. Lines starting with the hash +(’#’) character are ignored and are used to provide comments. Check +the presets directory in the FFmpeg source tree for examples. +

+

There are two types of preset files: ffpreset and avpreset files. +

+ +

5.12.1 ffpreset files

+

ffpreset files are specified with the vpre, apre, +spre, and fpre options. The fpre option takes the +filename of the preset instead of a preset name as input and can be +used for any kind of codec. For the vpre, apre, and +spre options, the options specified in a preset file are +applied to the currently selected codec of the same type as the preset +option. +

+

The argument passed to the vpre, apre, and spre +preset options identifies the preset file to use according to the +following rules: +

+

First ffmpeg searches for a file named arg.ffpreset in the +directories $FFMPEG_DATADIR (if set), and $HOME/.ffmpeg, and in +the datadir defined at configuration time (usually PREFIX/share/ffmpeg) +or in a ffpresets folder along the executable on win32, +in that order. For example, if the argument is libvpx-1080p, it will +search for the file libvpx-1080p.ffpreset. +

+

If no such file is found, then ffmpeg will search for a file named +codec_name-arg.ffpreset in the above-mentioned +directories, where codec_name is the name of the codec to which +the preset file options will be applied. For example, if you select +the video codec with -vcodec libvpx and use -vpre 1080p, +then it will search for the file libvpx-1080p.ffpreset. +

+ +

5.12.2 avpreset files

+

avpreset files are specified with the pre option. They work similar to +ffpreset files, but they only allow encoder- specific options. Therefore, an +option=value pair specifying an encoder cannot be used. +

+

When the pre option is specified, ffmpeg will look for files with the +suffix .avpreset in the directories $AVCONV_DATADIR (if set), and +$HOME/.avconv, and in the datadir defined at configuration time (usually +PREFIX/share/ffmpeg), in that order. +

+

First ffmpeg searches for a file named codec_name-arg.avpreset in +the above-mentioned directories, where codec_name is the name of the codec +to which the preset file options will be applied. For example, if you select the +video codec with -vcodec libvpx and use -pre 1080p, then it will +search for the file libvpx-1080p.avpreset. +

+

If no such file is found, then ffmpeg will search for a file named +arg.avpreset in the same directories. +

+ +

5.13 vstats file format

+

The -vstats and -vstats_file options enable generation of a file +containing statistics about the generated video outputs. +

+

The -vstats_version option controls the format version of the generated +file. +

+

With version 1 the format is: +

+
frame= FRAME q= FRAME_QUALITY PSNR= PSNR f_size= FRAME_SIZE s_size= STREAM_SIZEkB time= TIMESTAMP br= BITRATEkbits/s avg_br= AVERAGE_BITRATEkbits/s
+
+ +

With version 2 the format is: +

+
out= OUT_FILE_INDEX st= OUT_FILE_STREAM_INDEX frame= FRAME_NUMBER q= FRAME_QUALITYf PSNR= PSNR f_size= FRAME_SIZE s_size= STREAM_SIZEkB time= TIMESTAMP br= BITRATEkbits/s avg_br= AVERAGE_BITRATEkbits/s
+
+ +

The value corresponding to each key is described below: +

+
avg_br
+

average bitrate expressed in Kbits/s +

+
+
br
+

bitrate expressed in Kbits/s +

+
+
frame
+

number of encoded frame +

+
+
out
+

out file index +

+
+
PSNR
+

Peak Signal to Noise Ratio +

+
+
q
+

quality of the frame +

+
+
f_size
+

encoded packet size expressed as number of bytes +

+
+
s_size
+

stream size expressed in KiB +

+
+
st
+

out file stream index +

+
+
time
+

time of the packet +

+
+
type
+

picture type +

+
+ +

See also the -stats_enc options for an alternative way +to show encoding statistics. +

+ + +

6 Examples

+ + +

6.1 Video and Audio grabbing

+ +

If you specify the input format and device then ffmpeg can grab video +and audio directly. +

+
+
ffmpeg -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
+
+ +

Or with an ALSA audio source (mono input, card id 1) instead of OSS: +

+
ffmpeg -f alsa -ac 1 -i hw:1 -f video4linux2 -i /dev/video0 /tmp/out.mpg
+
+ +

Note that you must activate the right video source and channel before +launching ffmpeg with any TV viewer such as +xawtv by Gerd Knorr. You also +have to set the audio recording levels correctly with a +standard mixer. +

+ +

6.2 X11 grabbing

+ +

Grab the X11 display with ffmpeg via +

+
+
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0 /tmp/out.mpg
+
+ +

0.0 is display.screen number of your X11 server, same as +the DISPLAY environment variable. +

+
+
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0+10,20 /tmp/out.mpg
+
+ +

0.0 is display.screen number of your X11 server, same as the DISPLAY environment +variable. 10 is the x-offset and 20 the y-offset for the grabbing. +

+ +

6.3 Video and Audio file format conversion

+ +

Any supported file format and protocol can serve as input to ffmpeg: +

+

Examples: +

    +
  • You can use YUV files as input: + +
    +
    ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
    +
    + +

    It will use the files: +

    +
    /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
    +/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
    +
    + +

    The Y files use twice the resolution of the U and V files. They are +raw files, without header. They can be generated by all decent video +decoders. You must specify the size of the image with the -s option +if ffmpeg cannot guess it. +

    +
  • You can input from a raw YUV420P file: + +
    +
    ffmpeg -i /tmp/test.yuv /tmp/out.avi
    +
    + +

    test.yuv is a file containing raw YUV planar data. Each frame is composed +of the Y plane followed by the U and V planes at half vertical and +horizontal resolution. +

    +
  • You can output to a raw YUV420P file: + +
    +
    ffmpeg -i mydivx.avi hugefile.yuv
    +
    + +
  • You can set several input files and output files: + +
    +
    ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
    +
    + +

    Converts the audio file a.wav and the raw YUV video file a.yuv +to MPEG file a.mpg. +

    +
  • You can also do audio and video conversions at the same time: + +
    +
    ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
    +
    + +

    Converts a.wav to MPEG audio at 22050 Hz sample rate. +

    +
  • You can encode to several formats at the same time and define a +mapping from input stream to output streams: + +
    +
    ffmpeg -i /tmp/a.wav -map 0:a -b:a 64k /tmp/a.mp2 -map 0:a -b:a 128k /tmp/b.mp2
    +
    + +

    Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. ’-map +file:index’ specifies which input stream is used for each output +stream, in the order of the definition of output streams. +

    +
  • You can transcode decrypted VOBs: + +
    +
    ffmpeg -i snatch_1.vob -f avi -c:v mpeg4 -b:v 800k -g 300 -bf 2 -c:a libmp3lame -b:a 128k snatch.avi
    +
    + +

    This is a typical DVD ripping example; the input is a VOB file, the +output an AVI file with MPEG-4 video and MP3 audio. Note that in this +command we use B-frames so the MPEG-4 stream is DivX5 compatible, and +GOP size is 300 which means one intra frame every 10 seconds for 29.97fps +input video. Furthermore, the audio stream is MP3-encoded so you need +to enable LAME support by passing --enable-libmp3lame to configure. +The mapping is particularly useful for DVD transcoding +to get the desired audio language. +

    +

    NOTE: To see the supported input formats, use ffmpeg -demuxers. +

    +
  • You can extract images from a video, or create a video from many images: + +

    For extracting images from a video: +

    +
    ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
    +
    + +

    This will extract one video frame per second from the video and will +output them in files named foo-001.jpeg, foo-002.jpeg, +etc. Images will be rescaled to fit the new WxH values. +

    +

    If you want to extract just a limited number of frames, you can use the +above command in combination with the -frames:v or -t option, +or in combination with -ss to start extracting from a certain point in time. +

    +

    For creating a video from many images: +

    +
    ffmpeg -f image2 -framerate 12 -i foo-%03d.jpeg -s WxH foo.avi
    +
    + +

    The syntax foo-%03d.jpeg specifies to use a decimal number +composed of three digits padded with zeroes to express the sequence +number. It is the same syntax supported by the C printf function, but +only formats accepting a normal integer are suitable. +

    +

    When importing an image sequence, -i also supports expanding +shell-like wildcard patterns (globbing) internally, by selecting the +image2-specific -pattern_type glob option. +

    +

    For example, for creating a video from filenames matching the glob pattern +foo-*.jpeg: +

    +
    ffmpeg -f image2 -pattern_type glob -framerate 12 -i 'foo-*.jpeg' -s WxH foo.avi
    +
    + +
  • You can put many streams of the same type in the output: + +
    +
    ffmpeg -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut
    +
    + +

    The resulting output file test12.nut will contain the first four streams +from the input files in reverse order. +

    +
  • To force CBR video output: +
    +
    ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
    +
    + +
  • The four options lmin, lmax, mblmin and mblmax use ’lambda’ units, +but you may use the QP2LAMBDA constant to easily convert from ’q’ units: +
    +
    ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
    +
    + +
+ + + +

7 See Also

+ +

ffmpeg-all, +ffplay, ffprobe, +ffmpeg-utils, +ffmpeg-scaler, +ffmpeg-resampler, +ffmpeg-codecs, +ffmpeg-bitstream-filters, +ffmpeg-formats, +ffmpeg-devices, +ffmpeg-protocols, +ffmpeg-filters +

+ + +

8 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffplay-all.html b/ffmpeg-n8.1/doc/ffplay-all.html new file mode 100644 index 00000000..4ada1a0a --- /dev/null +++ b/ffmpeg-n8.1/doc/ffplay-all.html @@ -0,0 +1,54756 @@ + + + + + + + ffplay Documentation + + + + + + +
+

+ ffplay Documentation +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 Synopsis

+ +

ffplay [options] [input_url] +

+ +

2 Description

+ +

FFplay is a very simple and portable media player using the FFmpeg +libraries and the SDL library. It is mostly used as a testbed for the +various FFmpeg APIs. +

+ +

3 Options

+ +

All the numerical options, if not specified otherwise, accept a string +representing a number as input, which may be followed by one of the SI +unit prefixes, for example: ’K’, ’M’, or ’G’. +

+

If ’i’ is appended to the SI unit prefix, the complete prefix will be +interpreted as a unit prefix for binary multiples, which are based on +powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit +prefix multiplies the value by 8. This allows using, for example: +’KB’, ’MiB’, ’G’ and ’B’ as number suffixes. +

+

Options which do not take arguments are boolean options, and set the +corresponding value to true. They can be set to false by prefixing +the option name with "no". For example using "-nofoo" +will set the boolean option with name "foo" to false. +

+

Options that take arguments support a special syntax where the argument given on +the command line is interpreted as a path to the file from which the actual +argument value is loaded. To use this feature, add a forward slash ’/’ +immediately before the option name (after the leading dash). E.g. +

+
ffmpeg -i INPUT -/filter:v filter.script OUTPUT
+
+

will load a filtergraph description from the file named filter.script. +

+ +

3.1 Stream specifiers

+

Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers +are used to precisely specify which stream(s) a given option belongs to. +

+

A stream specifier is a string generally appended to the option name and +separated from it by a colon. E.g. -codec:a:1 ac3 contains the +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, so that the option is applied to all +of them. E.g. the stream specifier in -b:a 128k matches all audio +streams. +

+

An empty stream specifier matches all streams. For example, -codec copy +or -codec: copy would copy all the streams without reencoding. +

+

Possible forms of stream specifiers are: +

+
stream_index
+

Matches the stream with this index. E.g. -threads:1 4 would set the +thread count for the second stream to 4. If stream_index is used as an +additional stream specifier (see below), then it selects stream number +stream_index from the matching streams. Stream numbering is based on the +order of the streams as detected by libavformat except when a stream group +specifier or program ID is also specified. In this case it is based on the +ordering of the streams in the group or program. +

+
stream_type[:additional_stream_specifier]
+

stream_type is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’ +for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video +streams, ’V’ only matches video streams which are not attached pictures, video +thumbnails or cover arts. If additional_stream_specifier is used, then +it matches streams which both have this type and match the +additional_stream_specifier. Otherwise, it matches all streams of the +specified type. +

+
g:group_specifier[:additional_stream_specifier]
+

Matches streams which are in the group with the specifier group_specifier. +if additional_stream_specifier is used, then it matches streams which both +are part of the group and match the additional_stream_specifier. +group_specifier may be one of the following: +

+
group_index
+

Match the stream with this group index. +

+
#group_id or i:group_id
+

Match the stream with this group id. +

+
+
+
p:program_id[:additional_stream_specifier]
+

Matches streams which are in the program with the id program_id. If +additional_stream_specifier is used, then it matches streams which both +are part of the program and match the additional_stream_specifier. +

+
+
#stream_id or i:stream_id
+

Match the stream by stream id (e.g. PID in MPEG-TS container). +

+
m:key[:value]
+

Matches streams with the metadata tag key having the specified value. If +value is not given, matches streams that contain the given tag with any +value. The colon character ’:’ in key or value needs to be +backslash-escaped. +

+
disp:dispositions[:additional_stream_specifier]
+

Matches streams with the given disposition(s). dispositions is a list of +one or more dispositions (as printed by the -dispositions option) +joined with ’+’. +

+
u
+

Matches streams with usable configuration, the codec must be defined and the +essential information such as video dimension or audio sample rate must be present. +

+

Note that in ffmpeg, matching by metadata will only work properly for +input files. +

+
+ + +

3.2 Generic options

+ +

These options are shared amongst the ff* tools. +

+
+
-L, -license
+

Show license. +

+
+
-h, -?, -help, --help [arg]
+

Show help. An optional parameter may be specified to print help about a specific +item. If no argument is specified, only basic (non advanced) tool +options are shown. +

+

Possible values of arg are: +

+
long
+

Print advanced tool options in addition to the basic tool options. +

+
+
full
+

Print complete list of options, including shared and private options +for encoders, decoders, demuxers, muxers, filters, etc. +

+
+
decoder=decoder_name
+

Print detailed information about the decoder named decoder_name. Use the +-decoders option to get a list of all decoders. +

+
+
encoder=encoder_name
+

Print detailed information about the encoder named encoder_name. Use the +-encoders option to get a list of all encoders. +

+
+
demuxer=demuxer_name
+

Print detailed information about the demuxer named demuxer_name. Use the +-formats option to get a list of all demuxers and muxers. +

+
+
muxer=muxer_name
+

Print detailed information about the muxer named muxer_name. Use the +-formats option to get a list of all muxers and demuxers. +

+
+
filter=filter_name
+

Print detailed information about the filter named filter_name. Use the +-filters option to get a list of all filters. +

+
+
bsf=bitstream_filter_name
+

Print detailed information about the bitstream filter named bitstream_filter_name. +Use the -bsfs option to get a list of all bitstream filters. +

+
+
protocol=protocol_name
+

Print detailed information about the protocol named protocol_name. +Use the -protocols option to get a list of all protocols. +

+
+ +
+
-version
+

Show version. +

+
+
-buildconf
+

Show the build configuration, one option per line. +

+
+
-formats
+

Show available formats (including devices). +

+
+
-demuxers
+

Show available demuxers. +

+
+
-muxers
+

Show available muxers. +

+
+
-devices
+

Show available devices. +

+
+
-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. +

+
+
-decoders
+

Show available decoders. +

+
+
-encoders
+

Show all available encoders. +

+
+
-bsfs
+

Show available bitstream filters. +

+
+
-protocols
+

Show available protocols. +

+
+
-filters
+

Show available libavfilter filters. +

+
+
-pix_fmts
+

Show available pixel formats. +

+
+
-sample_fmts
+

Show available sample formats. +

+
+
-layouts
+

Show channel names and standard channel layouts. +

+
+
-dispositions
+

Show stream dispositions. +

+
+
-colors
+

Show recognized color names. +

+
+
-sources device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sources of the input device. +Some devices may provide system-dependent source names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sources pulse,server=192.168.0.4
+
+ +
+
-sinks device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sinks of the output device. +Some devices may provide system-dependent sink names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sinks pulse,server=192.168.0.4
+
+ +
+
-loglevel [flags+]loglevel | -v [flags+]loglevel
+

Set logging level and flags used by the library. +

+

The optional flags prefix can consist of the following values: +

+
‘repeat’
+

Indicates that repeated log output should not be compressed to the first line +and the "Last message repeated n times" line will be omitted. +

+
‘level’
+

Indicates that log output should add a [level] prefix to each message +line. This can be used as an alternative to log coloring, e.g. when dumping the +log to file. +

+
‘time’
+

Indicates that log lines should be prefixed with time information. +

+
‘datetime’
+

Indicates that log lines should be prefixed with date and time information. +

+
+

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single +flag without affecting other flags or changing loglevel. When +setting both flags and loglevel, a ’+’ separator is expected +between the last flags value and before loglevel. +

+

loglevel is a string or a number containing one of the following values: +

+
‘quiet, -8’
+

Show nothing at all; be silent. +

+
‘panic, 0’
+

Only show fatal errors which could lead the process to crash, such as +an assertion failure. This is not currently used for anything. +

+
‘fatal, 8’
+

Only show fatal errors. These are errors after which the process absolutely +cannot continue. +

+
‘error, 16’
+

Show all errors, including ones which can be recovered from. +

+
‘warning, 24’
+

Show all warnings and errors. Any message related to possibly +incorrect or unexpected events will be shown. +

+
‘info, 32’
+

Show informative messages during processing. This is in addition to +warnings and errors. This is the default value. +

+
‘verbose, 40’
+

Same as info, except more verbose. +

+
‘debug, 48’
+

Show everything, including debugging information. +

+
‘trace, 56’
+
+ +

For example to enable repeated log output, add the level prefix, and set +loglevel to verbose: +

+
ffmpeg -loglevel repeat+level+verbose -i input output
+
+

Another example that enables repeated log output without affecting current +state of level prefix flag or loglevel: +

+
ffmpeg [...] -loglevel +repeat
+
+ +

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 +AV_LOG_FORCE_NOCOLOR, or can be forced setting +the environment variable AV_LOG_FORCE_COLOR. +

+
+
-report
+

Dump full command line and log output to a file named +program-YYYYMMDD-HHMMSS.log in the current +directory. +This file can be useful for bug reports. +It also implies -loglevel debug. +

+

Setting the environment variable FFREPORT to any value has the +same effect. If the value is a ’:’-separated key=value sequence, these +options will affect the report; option 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 options are recognized: +

+
file
+

set the file name to use for the report; %p is expanded to the name +of the program, %t is expanded to a timestamp, %% is expanded +to a plain % +

+
level
+

set the log verbosity level using a numerical value (see -loglevel). +

+
+ +

For example, to output a report to a file named ffreport.log +using a log level of 32 (alias for log level info): +

+
+
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+ +

Errors in parsing the environment variable are not fatal, and will not +appear in the report. +

+
+
-hide_banner
+

Suppress printing banner. +

+

All FFmpeg tools will normally show a copyright notice, build options +and library versions. This option can be used to suppress printing +this information. +

+
+
-cpuflags flags (global)
+

Allows setting and clearing cpu flags. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpuflags -sse+mmx ...
+ffmpeg -cpuflags mmx ...
+ffmpeg -cpuflags 0 ...
+
+

Possible flags for this option are: +

+
‘x86’
+
+
‘mmx’
+
‘mmxext’
+
‘sse’
+
‘sse2’
+
‘sse2slow’
+
‘sse3’
+
‘sse3slow’
+
‘ssse3’
+
‘atom’
+
‘sse4.1’
+
‘sse4.2’
+
‘avx’
+
‘avx2’
+
‘xop’
+
‘fma3’
+
‘fma4’
+
‘3dnow’
+
‘3dnowext’
+
‘bmi1’
+
‘bmi2’
+
‘cmov’
+
+
+
‘ARM’
+
+
‘armv5te’
+
‘armv6’
+
‘armv6t2’
+
‘vfp’
+
‘vfpv3’
+
‘neon’
+
‘setend’
+
+
+
‘AArch64’
+
+
‘armv8’
+
‘vfp’
+
‘neon’
+
+
+
‘PowerPC’
+
+
‘altivec’
+
+
+
‘Specific Processors’
+
+
‘pentium2’
+
‘pentium3’
+
‘pentium4’
+
‘k6’
+
‘k62’
+
‘athlon’
+
‘athlonxp’
+
‘k8’
+
+
+
+ +
+
-cpucount count (global)
+

Override detection of CPU count. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpucount 2
+
+ +
+
-max_alloc bytes
+

Set the maximum size limit for allocating a block on the heap by ffmpeg’s +family of malloc functions. Exercise extreme caution when using +this option. Don’t use if you do not understand the full consequence of doing so. +Default is INT_MAX. +

+
+ + +

3.3 AVOptions

+ +

These options are provided directly by the libavformat, libavdevice and +libavcodec libraries. To see the list of available AVOptions, use the +-help option. They are separated into two categories: +

+
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. +

+
private
+

These options are specific to the given container, device or codec. Private +options are listed under their corresponding containers/devices/codecs. +

+
+ +

For example to write an ID3v2.3 header instead of a default ID3v2.4 to +an MP3 file, use the id3v2_version private option of the MP3 +muxer: +

+
ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+ +

All codec AVOptions are per-stream, and thus a stream specifier +should be attached to them: +

+
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+ +

In the above example, a multichannel audio stream is mapped twice for output. +The first instance is encoded with codec ac3 and bitrate 640k. +The second instance is downmixed to 2 channels and encoded with codec aac. A bitrate of 128k is specified for it using +absolute index of the output stream. +

+

Note: the -nooption syntax cannot be used for boolean +AVOptions, use -option 0/-option 1. +

+

Note: the 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. +

+ +

3.4 Main options

+ +
+
-x width
+

Force displayed width. +

+
-y height
+

Force displayed height. +

+
-fs
+

Start in fullscreen mode. +

+
-an
+

Disable audio. +

+
-vn
+

Disable video. +

+
-sn
+

Disable subtitles. +

+
-ss pos
+

Seek to pos. Note that in most formats it is not possible to seek +exactly, so ffplay will seek to the nearest seek point to +pos. +

+

pos must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+
-t duration
+

Play duration seconds of audio/video. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+
-bytes
+

Seek by bytes. +

+
-seek_interval
+

Set custom interval, in seconds, for seeking using left/right keys. Default is 10 seconds. +

+
-nodisp
+

Disable graphical display. +

+
-noborder
+

Borderless window. +

+
-alwaysontop
+

Window always on top. Available on: X11 with SDL >= 2.0.5, Windows SDL >= 2.0.6. +

+
-volume
+

Set the startup volume. 0 means silence, 100 means no volume reduction or +amplification. Negative values are treated as 0, values above 100 are treated +as 100. +

+
-f fmt
+

Force format. +

+
-window_title title
+

Set window title (default is the input filename). +

+
-left title
+

Set the x position for the left of the window (default is a centered window). +

+
-top title
+

Set the y position for the top of the window (default is a centered window). +

+
-loop number
+

Loops movie playback <number> times. 0 means forever. +

+
-showmode mode
+

Set the show mode to use. +Available values for mode are: +

+
‘0, video’
+

show video +

+
‘1, waves’
+

show audio waves +

+
‘2, rdft’
+

show audio frequency band using RDFT ((Inverse) Real Discrete Fourier Transform) +

+
+ +

Default value is "video", if video is not present or cannot be played +"rdft" is automatically selected. +

+

You can interactively cycle through the available show modes by +pressing the key w. +

+
+
-vf filtergraph
+

Create the filtergraph specified by filtergraph and use it to +filter the video stream. +

+

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 filtergraph, the input is associated to the label +in, and the output to the label out. See the +ffmpeg-filters manual for more information about the filtergraph +syntax. +

+

You can specify this parameter multiple times and cycle through the specified +filtergraphs along with the show modes by pressing the key w. +

+
+
-af filtergraph
+

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). +

+
+
-i input_url
+

Read input_url. +

+
+ + +

3.5 Advanced options

+
+
-stats
+

Print several playback statistics, in particular show the stream +duration, the codec parameters, the current position in the stream and +the audio/video synchronisation drift. It is shown by default, unless the +log level is lower than info. Its display can be forced by manually +specifying this option. To disable it, you need to specify -nostats. +

+
+
-fast
+

Non-spec-compliant optimizations. +

+
-genpts
+

Generate pts. +

+
-sync type
+

Set the master clock to audio (type=audio), video +(type=video) or external (type=ext). Default is audio. The +master clock is used to control audio-video synchronization. Most media +players use audio as master clock, but in some cases (streaming or high +quality broadcast) it is necessary to change that. This option is mainly +used for debugging purposes. +

+
-ast audio_stream_specifier
+

Select the desired audio stream using the given stream specifier. The stream +specifiers are described in the Stream specifiers chapter. If this option +is not specified, the "best" audio stream is selected in the program of the +already selected video stream. +

+
-vst video_stream_specifier
+

Select the desired video stream using the given stream specifier. The stream +specifiers are described in the Stream specifiers chapter. If this option +is not specified, the "best" video stream is selected. +

+
-sst subtitle_stream_specifier
+

Select the desired subtitle stream using the given stream specifier. The stream +specifiers are described in the Stream specifiers chapter. If this option +is not specified, the "best" subtitle stream is selected in the program of the +already selected video or audio stream. +

+
-autoexit
+

Exit when video is done playing. +

+
-exitonkeydown
+

Exit if any key is pressed. +

+
-exitonmousedown
+

Exit if any mouse button is pressed. +

+
+
-codec:media_specifier codec_name
+

Force a specific decoder implementation for the stream identified by +media_specifier, which can assume the values a (audio), +v (video), and s subtitle. +

+
+
-acodec codec_name
+

Force a specific audio decoder. +

+
+
-vcodec codec_name
+

Force a specific video decoder. +

+
+
-scodec codec_name
+

Force a specific subtitle decoder. +

+
+
-autorotate
+

Automatically rotate the video according to file metadata. Enabled by +default, use -noautorotate to disable it. +

+
+
-framedrop
+

Drop video frames if video is out of sync. Enabled by default if the master +clock is not set to video. Use this option to enable frame dropping for all +master clock sources, use -noframedrop to disable it. +

+
+
-infbuf
+

Do not limit the input buffer size, read as much data as possible from the +input as soon as possible. Enabled by default for realtime streams, where data +may be dropped if not read in time. Use this option to enable infinite buffers +for all inputs, use -noinfbuf to disable it. +

+
+
-filter_threads nb_threads
+

Defines how many threads are used to process a filter pipeline. Each pipeline +will produce a thread pool with this many threads available for parallel +processing. The default is 0 which means that the thread count will be +determined by the number of available CPUs. +

+
+
-enable_vulkan
+

Use vulkan renderer rather than SDL builtin renderer. Depends on libplacebo. +

+
+
-vulkan_params
+
+

Vulkan configuration using a list of key=value pairs separated by +":". +

+
+
-hwaccel
+

Use HW accelerated decoding. Enable this option will enable vulkan renderer +automatically. +

+
+
-video_bg pattern
+

Set the video background pattern used for transparent videos. For solid color +patterns you can use the color name or color code as specified in the +Color section in the ffmpeg-utils(1) manual. +You can also use the special tiles keyword for a checker board style +pattern. This is also the default. The none pattern does rendering +without alpha blending effectively ignoring alpha channel. +

+
+
+ + +

3.6 While playing

+ +
+
q, ESC
+

Quit. +

+
+
f
+

Toggle full screen. +

+
+
p, SPC
+

Pause. +

+
+
m
+

Toggle mute. +

+
+
9, 0
+
/, *
+

Decrease and increase volume respectively. +

+
+
a
+

Cycle audio channel in the current program. +

+
+
v
+

Cycle video channel. +

+
+
t
+

Cycle subtitle channel in the current program. +

+
+
c
+

Cycle program. +

+
+
w
+

Cycle video filters or show modes. +

+
+
s
+

Step to the next frame. +

+

Pause if the stream is not already paused, step to the next video +frame, and pause. +

+
+
left/right
+

Seek backward/forward by 10 seconds or a custom interval if -seek_interval is set. +

+
+
down/up
+

Seek backward/forward 1 minute. +

+
+
page down/page up
+

Seek to previous/next chapter or backward/forward 10 minutes if no chapters. +

+
+
right mouse click
+

Seek to percentage in file corresponding to fraction of width. +

+
+
left mouse double-click
+

Toggle full screen. +

+
+
+ + + +

4 Syntax

+ +

This section documents the syntax and formats employed by the FFmpeg +libraries and tools. +

+ +

4.1 Quoting and escaping

+ +

FFmpeg adopts the following quoting and escaping mechanism, unless +explicitly specified. The following rules are applied: +

+
    +
  • ‘'’ and ‘\’ 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. + +
  • A special character is escaped by prefixing it with a ‘\’. + +
  • All characters enclosed between ‘''’ are included literally in the +parsed string. The quote character ‘'’ itself cannot be quoted, +so you may need to close the quote and escape it. + +
  • Leading and trailing whitespaces, unless escaped or quoted, are +removed from the parsed string. +
+ +

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 av_get_token defined in +libavutil/avstring.h can be used to parse a token quoted or +escaped according to the rules defined above. +

+

The tool tools/ffescape in the FFmpeg source tree can be used +to automatically quote or escape a string in a script. +

+ +

4.1.1 Examples

+ +
    +
  • Escape the string Crime d'Amour containing the ' special +character: +
    +
    Crime d\'Amour
    +
    + +
  • The string above contains a quote, so the ' needs to be escaped +when quoting it: +
    +
    'Crime d'\''Amour'
    +
    + +
  • Include leading or trailing whitespaces using quoting: +
    +
    '  this string starts and ends with whitespaces  '
    +
    + +
  • Escaping and quoting can be mixed together: +
    +
    ' The string '\'string\'' is a string '
    +
    + +
  • To include a literal ‘\’ you can use either escaping or quoting: +
    +
    'c:\foo' can be written as c:\\foo
    +
    +
+ + +

4.2 Date

+ +

The accepted syntax is: +

+
[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
+now
+
+ +

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. +

+ +

4.3 Time duration

+ +

There are two accepted syntaxes for expressing time duration. +

+
+
[-][HH:]MM:SS[.m...]
+
+ +

HH expresses the number of hours, MM the number of minutes +for a maximum of 2 digits, and SS the number of seconds for a +maximum of 2 digits. The m at the end expresses decimal value for +SS. +

+

or +

+
+
[-]S+[.m...][s|ms|us]
+
+ +

S expresses the number of seconds, with the optional decimal part +m. The optional literal suffixes ‘s’, ‘ms’ or ‘us’ +indicate to interpret the value as seconds, milliseconds or microseconds, +respectively. +

+

In both expressions, the optional ‘-’ indicates negative duration. +

+ +

4.3.1 Examples

+ +

The following examples are all valid time duration: +

+
+
‘55’
+

55 seconds +

+
+
‘0.2’
+

0.2 seconds +

+
+
‘200ms’
+

200 milliseconds, that’s 0.2s +

+
+
‘200000us’
+

200000 microseconds, that’s 0.2s +

+
+
‘12:03:45’
+

12 hours, 03 minutes and 45 seconds +

+
+
‘23.189’
+

23.189 seconds +

+
+ + +

4.4 Video size

+

Specify the size of the sourced video, it may be a string of the form +widthxheight, or the name of a size abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

720x480 +

+
‘pal’
+

720x576 +

+
‘qntsc’
+

352x240 +

+
‘qpal’
+

352x288 +

+
‘sntsc’
+

640x480 +

+
‘spal’
+

768x576 +

+
‘film’
+

352x240 +

+
‘ntsc-film’
+

352x240 +

+
‘sqcif’
+

128x96 +

+
‘qcif’
+

176x144 +

+
‘cif’
+

352x288 +

+
‘4cif’
+

704x576 +

+
‘16cif’
+

1408x1152 +

+
‘qqvga’
+

160x120 +

+
‘qvga’
+

320x240 +

+
‘vga’
+

640x480 +

+
‘svga’
+

800x600 +

+
‘xga’
+

1024x768 +

+
‘uxga’
+

1600x1200 +

+
‘qxga’
+

2048x1536 +

+
‘sxga’
+

1280x1024 +

+
‘qsxga’
+

2560x2048 +

+
‘hsxga’
+

5120x4096 +

+
‘wvga’
+

852x480 +

+
‘wxga’
+

1366x768 +

+
‘wsxga’
+

1600x1024 +

+
‘wuxga’
+

1920x1200 +

+
‘woxga’
+

2560x1600 +

+
‘wqsxga’
+

3200x2048 +

+
‘wquxga’
+

3840x2400 +

+
‘whsxga’
+

6400x4096 +

+
‘whuxga’
+

7680x4800 +

+
‘cga’
+

320x200 +

+
‘ega’
+

640x350 +

+
‘hd480’
+

852x480 +

+
‘hd720’
+

1280x720 +

+
‘hd1080’
+

1920x1080 +

+
‘2k’
+

2048x1080 +

+
‘2kflat’
+

1998x1080 +

+
‘2kscope’
+

2048x858 +

+
‘4k’
+

4096x2160 +

+
‘4kflat’
+

3996x2160 +

+
‘4kscope’
+

4096x1716 +

+
‘nhd’
+

640x360 +

+
‘hqvga’
+

240x160 +

+
‘wqvga’
+

400x240 +

+
‘fwqvga’
+

432x240 +

+
‘hvga’
+

480x320 +

+
‘qhd’
+

960x540 +

+
‘2kdci’
+

2048x1080 +

+
‘4kdci’
+

4096x2160 +

+
‘uhd2160’
+

3840x2160 +

+
‘uhd4320’
+

7680x4320 +

+
+ + +

4.5 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 +frame_rate_num/frame_rate_den, an integer number, a float +number or a valid video frame rate abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

30000/1001 +

+
‘pal’
+

25/1 +

+
‘qntsc’
+

30000/1001 +

+
‘qpal’
+

25/1 +

+
‘sntsc’
+

30000/1001 +

+
‘spal’
+

25/1 +

+
‘film’
+

24/1 +

+
‘ntsc-film’
+

24000/1001 +

+
+ + +

4.6 Ratio

+ +

A ratio can be expressed as an expression, or in the form +numerator: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. +

+ +

4.7 Color

+ +

It can be the name of a color as defined below (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’ or ‘0.0’ means completely +transparent, ‘0xff’ or ‘1.0’ completely opaque). If the alpha +component is not specified then ‘0xff’ is assumed. +

+

The string ‘random’ will result in a random color. +

+

The following names of colors are recognized: +

+
‘AliceBlue’
+

0xF0F8FF +

+
‘AntiqueWhite’
+

0xFAEBD7 +

+
‘Aqua’
+

0x00FFFF +

+
‘Aquamarine’
+

0x7FFFD4 +

+
‘Azure’
+

0xF0FFFF +

+
‘Beige’
+

0xF5F5DC +

+
‘Bisque’
+

0xFFE4C4 +

+
‘Black’
+

0x000000 +

+
‘BlanchedAlmond’
+

0xFFEBCD +

+
‘Blue’
+

0x0000FF +

+
‘BlueViolet’
+

0x8A2BE2 +

+
‘Brown’
+

0xA52A2A +

+
‘BurlyWood’
+

0xDEB887 +

+
‘CadetBlue’
+

0x5F9EA0 +

+
‘Chartreuse’
+

0x7FFF00 +

+
‘Chocolate’
+

0xD2691E +

+
‘Coral’
+

0xFF7F50 +

+
‘CornflowerBlue’
+

0x6495ED +

+
‘Cornsilk’
+

0xFFF8DC +

+
‘Crimson’
+

0xDC143C +

+
‘Cyan’
+

0x00FFFF +

+
‘DarkBlue’
+

0x00008B +

+
‘DarkCyan’
+

0x008B8B +

+
‘DarkGoldenRod’
+

0xB8860B +

+
‘DarkGray’
+

0xA9A9A9 +

+
‘DarkGreen’
+

0x006400 +

+
‘DarkKhaki’
+

0xBDB76B +

+
‘DarkMagenta’
+

0x8B008B +

+
‘DarkOliveGreen’
+

0x556B2F +

+
‘Darkorange’
+

0xFF8C00 +

+
‘DarkOrchid’
+

0x9932CC +

+
‘DarkRed’
+

0x8B0000 +

+
‘DarkSalmon’
+

0xE9967A +

+
‘DarkSeaGreen’
+

0x8FBC8F +

+
‘DarkSlateBlue’
+

0x483D8B +

+
‘DarkSlateGray’
+

0x2F4F4F +

+
‘DarkTurquoise’
+

0x00CED1 +

+
‘DarkViolet’
+

0x9400D3 +

+
‘DeepPink’
+

0xFF1493 +

+
‘DeepSkyBlue’
+

0x00BFFF +

+
‘DimGray’
+

0x696969 +

+
‘DodgerBlue’
+

0x1E90FF +

+
‘FireBrick’
+

0xB22222 +

+
‘FloralWhite’
+

0xFFFAF0 +

+
‘ForestGreen’
+

0x228B22 +

+
‘Fuchsia’
+

0xFF00FF +

+
‘Gainsboro’
+

0xDCDCDC +

+
‘GhostWhite’
+

0xF8F8FF +

+
‘Gold’
+

0xFFD700 +

+
‘GoldenRod’
+

0xDAA520 +

+
‘Gray’
+

0x808080 +

+
‘Green’
+

0x008000 +

+
‘GreenYellow’
+

0xADFF2F +

+
‘HoneyDew’
+

0xF0FFF0 +

+
‘HotPink’
+

0xFF69B4 +

+
‘IndianRed’
+

0xCD5C5C +

+
‘Indigo’
+

0x4B0082 +

+
‘Ivory’
+

0xFFFFF0 +

+
‘Khaki’
+

0xF0E68C +

+
‘Lavender’
+

0xE6E6FA +

+
‘LavenderBlush’
+

0xFFF0F5 +

+
‘LawnGreen’
+

0x7CFC00 +

+
‘LemonChiffon’
+

0xFFFACD +

+
‘LightBlue’
+

0xADD8E6 +

+
‘LightCoral’
+

0xF08080 +

+
‘LightCyan’
+

0xE0FFFF +

+
‘LightGoldenRodYellow’
+

0xFAFAD2 +

+
‘LightGreen’
+

0x90EE90 +

+
‘LightGrey’
+

0xD3D3D3 +

+
‘LightPink’
+

0xFFB6C1 +

+
‘LightSalmon’
+

0xFFA07A +

+
‘LightSeaGreen’
+

0x20B2AA +

+
‘LightSkyBlue’
+

0x87CEFA +

+
‘LightSlateGray’
+

0x778899 +

+
‘LightSteelBlue’
+

0xB0C4DE +

+
‘LightYellow’
+

0xFFFFE0 +

+
‘Lime’
+

0x00FF00 +

+
‘LimeGreen’
+

0x32CD32 +

+
‘Linen’
+

0xFAF0E6 +

+
‘Magenta’
+

0xFF00FF +

+
‘Maroon’
+

0x800000 +

+
‘MediumAquaMarine’
+

0x66CDAA +

+
‘MediumBlue’
+

0x0000CD +

+
‘MediumOrchid’
+

0xBA55D3 +

+
‘MediumPurple’
+

0x9370D8 +

+
‘MediumSeaGreen’
+

0x3CB371 +

+
‘MediumSlateBlue’
+

0x7B68EE +

+
‘MediumSpringGreen’
+

0x00FA9A +

+
‘MediumTurquoise’
+

0x48D1CC +

+
‘MediumVioletRed’
+

0xC71585 +

+
‘MidnightBlue’
+

0x191970 +

+
‘MintCream’
+

0xF5FFFA +

+
‘MistyRose’
+

0xFFE4E1 +

+
‘Moccasin’
+

0xFFE4B5 +

+
‘NavajoWhite’
+

0xFFDEAD +

+
‘Navy’
+

0x000080 +

+
‘OldLace’
+

0xFDF5E6 +

+
‘Olive’
+

0x808000 +

+
‘OliveDrab’
+

0x6B8E23 +

+
‘Orange’
+

0xFFA500 +

+
‘OrangeRed’
+

0xFF4500 +

+
‘Orchid’
+

0xDA70D6 +

+
‘PaleGoldenRod’
+

0xEEE8AA +

+
‘PaleGreen’
+

0x98FB98 +

+
‘PaleTurquoise’
+

0xAFEEEE +

+
‘PaleVioletRed’
+

0xD87093 +

+
‘PapayaWhip’
+

0xFFEFD5 +

+
‘PeachPuff’
+

0xFFDAB9 +

+
‘Peru’
+

0xCD853F +

+
‘Pink’
+

0xFFC0CB +

+
‘Plum’
+

0xDDA0DD +

+
‘PowderBlue’
+

0xB0E0E6 +

+
‘Purple’
+

0x800080 +

+
‘Red’
+

0xFF0000 +

+
‘RosyBrown’
+

0xBC8F8F +

+
‘RoyalBlue’
+

0x4169E1 +

+
‘SaddleBrown’
+

0x8B4513 +

+
‘Salmon’
+

0xFA8072 +

+
‘SandyBrown’
+

0xF4A460 +

+
‘SeaGreen’
+

0x2E8B57 +

+
‘SeaShell’
+

0xFFF5EE +

+
‘Sienna’
+

0xA0522D +

+
‘Silver’
+

0xC0C0C0 +

+
‘SkyBlue’
+

0x87CEEB +

+
‘SlateBlue’
+

0x6A5ACD +

+
‘SlateGray’
+

0x708090 +

+
‘Snow’
+

0xFFFAFA +

+
‘SpringGreen’
+

0x00FF7F +

+
‘SteelBlue’
+

0x4682B4 +

+
‘Tan’
+

0xD2B48C +

+
‘Teal’
+

0x008080 +

+
‘Thistle’
+

0xD8BFD8 +

+
‘Tomato’
+

0xFF6347 +

+
‘Turquoise’
+

0x40E0D0 +

+
‘Violet’
+

0xEE82EE +

+
‘Wheat’
+

0xF5DEB3 +

+
‘White’
+

0xFFFFFF +

+
‘WhiteSmoke’
+

0xF5F5F5 +

+
‘Yellow’
+

0xFFFF00 +

+
‘YellowGreen’
+

0x9ACD32 +

+
+ + +

4.8 Channel Layout

+ +

A channel layout specifies the spatial disposition of the channels in +a multi-channel audio stream. To specify a channel layout, FFmpeg +makes use of a special syntax. +

+

Individual channels are identified by an id, as given by the table +below: +

+
‘FL’
+

front left +

+
‘FR’
+

front right +

+
‘FC’
+

front center +

+
‘LFE’
+

low frequency +

+
‘BL’
+

back left +

+
‘BR’
+

back right +

+
‘FLC’
+

front left-of-center +

+
‘FRC’
+

front right-of-center +

+
‘BC’
+

back center +

+
‘SL’
+

side left +

+
‘SR’
+

side right +

+
‘TC’
+

top center +

+
‘TFL’
+

top front left +

+
‘TFC’
+

top front center +

+
‘TFR’
+

top front right +

+
‘TBL’
+

top back left +

+
‘TBC’
+

top back center +

+
‘TBR’
+

top back right +

+
‘DL’
+

downmix left +

+
‘DR’
+

downmix right +

+
‘WL’
+

wide left +

+
‘WR’
+

wide right +

+
‘SDL’
+

surround direct left +

+
‘SDR’
+

surround direct right +

+
‘LFE2’
+

low frequency 2 +

+
+ +

Standard channel layout compositions can be specified by using the +following identifiers: +

+
‘mono’
+

FC +

+
‘stereo’
+

FL+FR +

+
‘2.1’
+

FL+FR+LFE +

+
‘3.0’
+

FL+FR+FC +

+
‘3.0(back)’
+

FL+FR+BC +

+
‘4.0’
+

FL+FR+FC+BC +

+
‘quad’
+

FL+FR+BL+BR +

+
‘quad(side)’
+

FL+FR+SL+SR +

+
‘3.1’
+

FL+FR+FC+LFE +

+
‘5.0’
+

FL+FR+FC+BL+BR +

+
‘5.0(side)’
+

FL+FR+FC+SL+SR +

+
‘4.1’
+

FL+FR+FC+LFE+BC +

+
‘5.1’
+

FL+FR+FC+LFE+BL+BR +

+
‘5.1(side)’
+

FL+FR+FC+LFE+SL+SR +

+
‘6.0’
+

FL+FR+FC+BC+SL+SR +

+
‘6.0(front)’
+

FL+FR+FLC+FRC+SL+SR +

+
‘3.1.2’
+

FL+FR+FC+LFE+TFL+TFR +

+
‘hexagonal’
+

FL+FR+FC+BL+BR+BC +

+
‘6.1’
+

FL+FR+FC+LFE+BC+SL+SR +

+
‘6.1’
+

FL+FR+FC+LFE+BL+BR+BC +

+
‘6.1(front)’
+

FL+FR+LFE+FLC+FRC+SL+SR +

+
‘7.0’
+

FL+FR+FC+BL+BR+SL+SR +

+
‘7.0(front)’
+

FL+FR+FC+FLC+FRC+SL+SR +

+
‘7.1’
+

FL+FR+FC+LFE+BL+BR+SL+SR +

+
‘7.1(wide)’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC +

+
‘7.1(wide-side)’
+

FL+FR+FC+LFE+FLC+FRC+SL+SR +

+
‘5.1.2’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR +

+
‘octagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR +

+
‘cube’
+

FL+FR+BL+BR+TFL+TFR+TBL+TBR +

+
‘5.1.4’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR+TBL+TBR +

+
‘7.1.2’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR +

+
‘7.1.4’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBL+TBR +

+
‘7.2.3’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBC+LFE2 +

+
‘9.1.4’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR +

+
‘9.1.6’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR+TSL+TSR +

+
‘hexadecagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR +

+
‘binaural’
+

BIL+BIR +

+
‘downmix’
+

DL+DR +

+
‘22.2’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+BC+SL+SR+TC+TFL+TFC+TFR+TBL+TBC+TBR+LFE2+TSL+TSR+BFC+BFL+BFR +

+
+ +

A custom channel layout can be specified as a sequence of terms, separated by ’+’. +Each term can be: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.), +each optionally containing a custom name after a ’@’, (e.g. ‘FL@Left’, +‘FR@Right’, ‘FC@Center’, ‘LFE@Low_Frequency’, etc.) +
+ +

A standard channel layout can be specified by the following: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.) + +
  • the name of a standard channel layout (e.g. ‘mono’, +‘stereo’, ‘4.0’, ‘quad’, ‘5.0’, etc.) + +
  • a number of channels, in decimal, followed by ’c’, yielding the default channel +layout for that number of channels (see the function +av_channel_layout_default). Note that not all channel counts have a +default layout. + +
  • a number of channels, in decimal, followed by ’C’, yielding an unknown channel +layout with the specified number of channels. Note that not all channel layout +specification strings support unknown channel layouts. + +
  • a channel layout mask, in hexadecimal starting with "0x" (see the +AV_CH_* macros in libavutil/channel_layout.h. +
+ +

Before libavutil version 53 the trailing character "c" to specify a number of +channels was optional, but now it is required, while a channel layout mask can +also be specified as a decimal number (if and only if not followed by "c" or "C"). +

+

See also the function av_channel_layout_from_string defined in +libavutil/channel_layout.h. +

+ +

5 Expression Evaluation

+ +

When evaluating an arithmetic expression, FFmpeg uses an internal +formula evaluator, implemented through the libavutil/eval.h +interface. +

+

An expression may contain unary, binary operators, constants, and +functions. +

+

Two expressions expr1 and expr2 can be combined to form +another expression "expr1;expr2". +expr1 and expr2 are evaluated in turn, and the new +expression evaluates to the value of expr2. +

+

The following binary operators are available: +, -, +*, /, ^. +

+

The following unary operators are available: +, -. +

+

Some internal variables can be used to store and load intermediary +results. They can be accessed using the ld and st +functions with an index argument varying from 0 to 9 to specify which +internal variable to access. +

+

The following functions are available: +

+
abs(x)
+

Compute absolute value of x. +

+
+
acos(x)
+

Compute arccosine of x. +

+
+
asin(x)
+

Compute arcsine of x. +

+
+
atan(x)
+

Compute arctangent of x. +

+
+
atan2(y, x)
+

Compute principal value of the arc tangent of y/x. +

+
+
between(x, min, max)
+

Return 1 if x is greater than or equal to min and lesser than or +equal to max, 0 otherwise. +

+
+
bitand(x, y)
+
bitor(x, y)
+

Compute bitwise and/or operation on x and y. +

+

The results of the evaluation of x and 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). +

+
+
ceil(expr)
+

Round the value of expression expr upwards to the nearest +integer. For example, "ceil(1.5)" is "2.0". +

+
+
clip(x, min, max)
+

Return the value of x clipped between min and max. +

+
+
cos(x)
+

Compute cosine of x. +

+
+
cosh(x)
+

Compute hyperbolic cosine of x. +

+
+
eq(x, y)
+

Return 1 if x and y are equivalent, 0 otherwise. +

+
+
exp(x)
+

Compute exponential of x (with base e, the Euler’s number). +

+
+
floor(expr)
+

Round the value of expression expr downwards to the nearest +integer. For example, "floor(-1.5)" is "-2.0". +

+
+
gauss(x)
+

Compute Gauss function of x, corresponding to +exp(-x*x/2) / sqrt(2*PI). +

+
+
gcd(x, y)
+

Return the greatest common divisor of x and y. If both x and +y are 0 or either or both are less than zero then behavior is undefined. +

+
+
gt(x, y)
+

Return 1 if x is greater than y, 0 otherwise. +

+
+
gte(x, y)
+

Return 1 if x is greater than or equal to y, 0 otherwise. +

+
+
hypot(x, y)
+

This function is similar to the C function with the same name; it returns +"sqrt(x*x + y*y)", the length of the hypotenuse of a +right triangle with sides of length x and y, or the distance of the +point (x, y) from the origin. +

+
+
if(x, y)
+

Evaluate x, and if the result is non-zero return the result of +the evaluation of y, return 0 otherwise. +

+
+
if(x, y, z)
+

Evaluate x, and if the result is non-zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
ifnot(x, y)
+

Evaluate x, and if the result is zero return the result of the +evaluation of y, return 0 otherwise. +

+
+
ifnot(x, y, z)
+

Evaluate x, and if the result is zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
isinf(x)
+

Return 1.0 if x is +/-INFINITY, 0.0 otherwise. +

+
+
isnan(x)
+

Return 1.0 if x is NAN, 0.0 otherwise. +

+
+
ld(idx)
+

Load the value of the internal variable with index idx, which was +previously stored with st(idx, expr). +The function returns the loaded value. +

+
+
lerp(x, y, z)
+

Return linear interpolation between x and y by amount of z. +

+
+
log(x)
+

Compute natural logarithm of x. +

+
+
lt(x, y)
+

Return 1 if x is lesser than y, 0 otherwise. +

+
+
lte(x, y)
+

Return 1 if x is lesser than or equal to y, 0 otherwise. +

+
+
max(x, y)
+

Return the maximum between x and y. +

+
+
min(x, y)
+

Return the minimum between x and y. +

+
+
mod(x, y)
+

Compute the remainder of division of x by y. +

+
+
not(expr)
+

Return 1.0 if expr is zero, 0.0 otherwise. +

+
+
pow(x, y)
+

Compute the power of x elevated y, it is equivalent to +"(x)^(y)". +

+
+
print(t)
+
print(t, l)
+

Print the value of expression t with loglevel l. If l is not +specified then a default log level is used. +Return the value of the expression printed. +

+
+
random(idx)
+

Return a pseudo random value between 0.0 and 1.0. idx is the +index of the internal variable used to save the seed/state, which can be +previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+

For example, to store the seed with value 42 in the internal +variable with index 0 and print a few random values: +

+
st(0,42); print(random(0)); print(random(0)); print(random(0))
+
+ +
+
randomi(idx, min, max)
+

Return a pseudo random value in the interval between min and +max. idx is the index of the internal variable which will be used to +save the seed/state, which can be previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+
+
root(expr, max)
+

Find an input value for which the function represented by expr +with argument ld(0) is 0 in the interval 0..max. +

+

The expression in expr must denote a continuous function or the +result is undefined. +

+

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 ld(0). When the expression evaluates to +0 then the corresponding input value will be returned. +

+
+
round(expr)
+

Round the value of expression expr to the nearest integer. For example, +"round(1.5)" is "2.0". +

+
+
sgn(x)
+

Compute sign of x. +

+
+
sin(x)
+

Compute sine of x. +

+
+
sinh(x)
+

Compute hyperbolic sine of x. +

+
+
sqrt(expr)
+

Compute the square root of expr. This is equivalent to +"(expr)^.5". +

+
+
squish(x)
+

Compute expression 1/(1 + exp(4*x)). +

+
+
st(idx, expr)
+

Store the value of the expression expr in an internal +variable. idx specifies the index 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. +

+

The stored value can be retrieved with ld(var). +

+

Note: variables are currently not shared between expressions. +

+
+
tan(x)
+

Compute tangent of x. +

+
+
tanh(x)
+

Compute hyperbolic tangent of x. +

+
+
taylor(expr, x)
+
taylor(expr, x, idx)
+

Evaluate a Taylor series at x, given an expression representing +the ld(idx)-th derivative of a function at 0. +

+

When the series does not converge the result is undefined. +

+

ld(idx) is used to represent the derivative order in expr, +which means that the given expression will be evaluated multiple times +with various input values that the expression can access through +ld(idx). If idx is not specified then 0 is assumed. +

+

Note, when you have the derivatives at y instead of 0, +taylor(expr, x-y) can be used. +

+
+
time(0)
+

Return the current (wallclock) time in seconds. +

+
+
trunc(expr)
+

Round the value of expression expr towards zero to the nearest +integer. For example, "trunc(-1.5)" is "-1.0". +

+
+
while(cond, expr)
+

Evaluate expression expr while the expression cond is +non-zero, and returns the value of the last expr evaluation, or +NAN if cond was always false. +

+
+ +

The following constants are available: +

+
PI
+

area of the unit disc, approximately 3.14 +

+
E
+

exp(1) (Euler’s number), approximately 2.718 +

+
PHI
+

golden ratio (1+sqrt(5))/2, approximately 1.618 +

+
+ +

Assuming that an expression is considered "true" if it has a non-zero +value, note that: +

+

* works like AND +

+

+ works like OR +

+

For example the construct: +

+
if (A AND B) then C
+
+

is equivalent to: +

+
if(A*B, C)
+
+ +

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. +

+
y
+

10^-24 / 2^-80 +

+
z
+

10^-21 / 2^-70 +

+
a
+

10^-18 / 2^-60 +

+
f
+

10^-15 / 2^-50 +

+
p
+

10^-12 / 2^-40 +

+
n
+

10^-9 / 2^-30 +

+
u
+

10^-6 / 2^-20 +

+
m
+

10^-3 / 2^-10 +

+
c
+

10^-2 +

+
d
+

10^-1 +

+
h
+

10^2 +

+
k
+

10^3 / 2^10 +

+
K
+

10^3 / 2^10 +

+
M
+

10^6 / 2^20 +

+
G
+

10^9 / 2^30 +

+
T
+

10^12 / 2^40 +

+
P
+

10^15 / 2^50 +

+
E
+

10^18 / 2^60 +

+
Z
+

10^21 / 2^70 +

+
Y
+

10^24 / 2^80 +

+
+ + +

6 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 nonsensical 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVCodecContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follow: +

+
+
b integer (encoding,audio,video)
+

Set bitrate in bits/s. Default value is 200K. +

+
+
ab integer (encoding,audio)
+

Set audio bitrate (in bits/s). Default value is 128K. +

+
+
bt integer (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. +

+
+
flags flags (decoding/encoding,audio,video,subtitles)
+

Set generic flags. +

+

Possible values: +

+
‘mv4’
+

Use four motion vector by macroblock (mpeg4). +

+
‘qpel’
+

Use 1/4 pel motion compensation. +

+
‘loop’
+

Use loop filter. +

+
‘qscale’
+

Use fixed qscale. +

+
‘pass1’
+

Use internal 2pass ratecontrol in first pass mode. +

+
‘pass2’
+

Use internal 2pass ratecontrol in second pass mode. +

+
‘gray’
+

Only decode/encode grayscale. +

+
‘psnr’
+

Set error[?] variables during encoding. +

+
‘truncated’
+

Input bitstream might be randomly truncated. +

+
‘drop_changed’
+

Don’t output frames whose parameters differ from first decoded frame in stream. +Error AVERROR_INPUT_CHANGED is returned when a frame is dropped. +

+
+
‘ildct’
+

Use interlaced DCT. +

+
‘low_delay’
+

Force low delay. +

+
‘global_header’
+

Place global headers in extradata instead of every keyframe. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. (except (I)DCT). +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘aic’
+

Apply H263 advanced intra coding / mpeg4 ac prediction. +

+
‘ilme’
+

Apply interlaced motion estimation. +

+
‘cgop’
+

Use closed gop. +

+
‘output_corrupt’
+

Output even potentially corrupted frames. +

+
+ +
+
time_base 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 / frame_rate and timestamp increments should be +identically 1. +

+
+
g integer (encoding,video)
+

Set the group of picture (GOP) size. Default value is 12. +

+
+
ar integer (decoding/encoding,audio)
+

Set audio sampling rate (in Hz). +

+
+
ac integer (decoding/encoding,audio)
+

Set number of audio channels. +

+
+
cutoff integer (encoding,audio)
+

Set cutoff bandwidth. (Supported only by selected encoders, see +their respective documentation sections.) +

+
+
frame_size integer (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. +

+
+
frame_number integer
+

Set the frame number. +

+
+
delay integer
+
qcomp float (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. +

+
+
qblur float (encoding,video)
+

Set video quantizer scale blur (VBR). +

+
+
qmin integer (encoding,video)
+

Set min video quantizer scale (VBR). Must be included between -1 and +69, default value is 2. +

+
+
qmax integer (encoding,video)
+

Set max video quantizer scale (VBR). Must be included between -1 and +1024, default value is 31. +

+
+
qdiff integer (encoding,video)
+

Set max difference between the quantizer scale (VBR). +

+
+
bf integer (encoding,video)
+

Set max number of B frames between non-B-frames. +

+

Must be an integer between -1 and 16. 0 means that B-frames are +disabled. If a value of -1 is used, it will choose an automatic value +depending on the encoder. +

+

Default value is 0. +

+
+
b_qfactor float (encoding,video)
+

Set qp factor between P and B frames. +

+
+
codec_tag integer
+
bug flags (decoding,video)
+

Workaround not auto detected encoder bugs. +

+

Possible values: +

+
‘autodetect’
+
‘xvid_ilace’
+

Xvid interlacing bug (autodetected if fourcc==XVIX) +

+
‘ump4’
+

(autodetected if fourcc==UMP4) +

+
‘no_padding’
+

padding bug (autodetected) +

+
‘amv’
+
‘qpel_chroma’
+
‘std_qpel’
+

old standard qpel (autodetected per fourcc/version) +

+
‘qpel_chroma2’
+
‘direct_blocksize’
+

direct-qpel-blocksize bug (autodetected per fourcc/version) +

+
‘edge’
+

edge padding bug (autodetected per fourcc/version) +

+
‘hpel_chroma’
+
‘dc_clip’
+
‘ms’
+

Workaround various bugs in microsoft broken decoders. +

+
‘trunc’
+

trancated frames +

+
+ +
+
strict integer (decoding/encoding,audio,video)
+

Specify how strictly to follow the standards. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
b_qoffset float (encoding,video)
+

Set QP offset between P and B frames. +

+
+
err_detect flags (decoding,audio,video)
+

Set error detection flags. +

+

Possible values: +

+
‘crccheck’
+

verify embedded CRCs +

+
‘bitstream’
+

detect bitstream specification deviations +

+
‘buffer’
+

detect improper bitstream length +

+
‘explode’
+

abort decoding on minor error detection +

+
‘ignore_err’
+

ignore decoding errors, and continue decoding. +This is useful if you want to analyze the content of a video and thus want +everything to be decoded no matter what. This option will not result in a video +that is pleasing to watch in case of errors. +

+
‘careful’
+

consider things that violate the spec and have not been seen in the wild as errors +

+
‘compliant’
+

consider all spec non compliancies as errors +

+
‘aggressive’
+

consider things that a sane encoder should not do as an error +

+
+ +
+
has_b_frames integer
+
block_align integer
+
rc_override_count integer
+
maxrate integer (encoding,audio,video)
+

Set max bitrate tolerance (in bits/s). Requires bufsize to be set. +

+
+
minrate integer (encoding,audio,video)
+

Set min bitrate tolerance (in bits/s). Most useful in setting up a CBR +encode. It is of little use elsewise. +

+
+
bufsize integer (encoding,audio,video)
+

Set ratecontrol buffer size (in bits). +

+
+
i_qfactor float (encoding,video)
+

Set QP factor between P and I frames. +

+
+
i_qoffset float (encoding,video)
+

Set QP offset between P and I frames. +

+
+
dct integer (encoding,video)
+

Set DCT algorithm. +

+

Possible values: +

+
‘auto’
+

autoselect a good one (default) +

+
‘fastint’
+

fast integer +

+
‘int’
+

accurate integer +

+
‘mmx’
+
‘altivec’
+
‘faan’
+

floating point AAN DCT +

+
+ +
+
lumi_mask float (encoding,video)
+

Compress bright areas stronger than medium ones. +

+
+
tcplx_mask float (encoding,video)
+

Set temporal complexity masking. +

+
+
scplx_mask float (encoding,video)
+

Set spatial complexity masking. +

+
+
p_mask float (encoding,video)
+

Set inter masking. +

+
+
dark_mask float (encoding,video)
+

Compress dark areas stronger than medium ones. +

+
+
idct integer (decoding/encoding,video)
+

Select IDCT implementation. +

+

Possible values: +

+
‘auto’
+
‘int’
+
‘simple’
+
‘simplemmx’
+
‘simpleauto’
+

Automatically pick a IDCT compatible with the simple one +

+
+
‘arm’
+
‘altivec’
+
‘sh4’
+
‘simplearm’
+
‘simplearmv5te’
+
‘simplearmv6’
+
‘simpleneon’
+
‘xvid’
+
‘faani’
+

floating point AAN IDCT +

+
+ +
+
slice_count integer
+
ec flags (decoding,video)
+

Set error concealment strategy. +

+

Possible values: +

+
‘guess_mvs’
+

iterative motion vector (MV) search (slow) +

+
‘deblock’
+

use strong deblock filter for damaged MBs +

+
‘favor_inter’
+

favor predicting from the previous frame instead of the current +

+
+ +
+
bits_per_coded_sample integer
+
aspect rational number (encoding,video)
+

Set sample aspect ratio. +

+
+
sar rational number (encoding,video)
+

Set sample aspect ratio. Alias to aspect. +

+
+
debug flags (decoding/encoding,audio,video,subtitles)
+

Print specific debug info. +

+

Possible values: +

+
‘pict’
+

picture info +

+
‘rc’
+

rate control +

+
‘bitstream’
+
‘mb_type’
+

macroblock (MB) type +

+
‘qp’
+

per-block quantization parameter (QP) +

+
‘dct_coeff’
+
‘green_metadata’
+

display complexity metadata for the upcoming frame, GoP or for a given duration. +

+
+
‘skip’
+
‘startcode’
+
‘er’
+

error recognition +

+
‘mmco’
+

memory management control operations (H.264) +

+
‘bugs’
+
‘buffers’
+

picture buffer allocations +

+
‘thread_ops’
+

threading operations +

+
‘nomc’
+

skip motion compensation +

+
+ +
+
cmp integer (encoding,video)
+

Set full pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
subcmp integer (encoding,video)
+

Set sub pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
mbcmp integer (encoding,video)
+

Set macroblock compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
ildctcmp integer (encoding,video)
+

Set interlaced dct compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation. +

+
‘(1024, INT_MAX)’
+

full motion estimation(slowest) +

+
‘(768, 1024]’
+

umh motion estimation +

+
‘(512, 768]’
+

hex motion estimation +

+
‘(256, 512]’
+

l2s diamond motion estimation +

+
‘[2,256]’
+

var diamond motion estimation +

+
‘(-1, 2)’
+

small diamond motion estimation +

+
‘-1’
+

funny diamond motion estimation +

+
‘(INT_MIN, -1)’
+

sab diamond motion estimation +

+
+ +
+
last_pred integer (encoding,video)
+

Set amount of motion predictors from the previous frame. +

+
+
precmp integer (encoding,video)
+

Set pre motion estimation compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
pre_dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation pre-pass. +

+
+
subq integer (encoding,video)
+

Set sub pel motion estimation quality. +

+
+
me_range integer (encoding,video)
+

Set limit motion vectors range (1023 for DivX player). +

+
+
global_quality integer (encoding,audio,video)
+
slice_flags integer
+
mbd integer (encoding,video)
+

Set macroblock decision algorithm (high quality mode). +

+

Possible values: +

+
‘simple’
+

use mbcmp (default) +

+
‘bits’
+

use fewest bits +

+
‘rd’
+

use best rate distortion +

+
+ +
+
rc_init_occupancy integer (encoding,video)
+

Set number of bits which should be loaded into the rc buffer before +decoding starts. +

+
+
flags2 flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘fast’
+

Allow non spec compliant speedup tricks. +

+
‘noout’
+

Skip bitstream encoding. +

+
‘ignorecrop’
+

Ignore cropping information from sps. +

+
‘local_header’
+

Place global headers at every keyframe instead of in extradata. +

+
‘chunks’
+

Frame data might be split into multiple chunks. +

+
‘showall’
+

Show all frames before the first keyframe. +

+
‘export_mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘skip_manual’
+

Do not skip samples and export skip information as frame side data. +

+
‘ass_ro_flush_noop’
+

Do not reset ASS ReadOrder field on flush. +

+
‘icc_profiles’
+

Generate/parse embedded ICC profiles from/to colorimetry tags. +

+
+ +
+
export_side_data flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘prft’
+

Export encoder Producer Reference Time into packet side-data (see AV_PKT_DATA_PRFT) +for codecs that support it. +

+
‘venc_params’
+

Export video encoding parameters through frame side data (see AV_FRAME_DATA_VIDEO_ENC_PARAMS) +for codecs that support it. At present, those are H.264 and VP9. +

+
‘film_grain’
+

Export film grain parameters through frame side data (see AV_FRAME_DATA_FILM_GRAIN_PARAMS). +Supported at present by AV1 decoders. +

+
‘enhancements’
+

Export picture enhancement metadata through frame side data, e.g. LCEVC (see AV_FRAME_DATA_LCEVC). +

+
+ +
+
threads integer (decoding/encoding,video)
+

Set the number of threads to be used, in case the selected codec +implementation supports multi-threading. +

+

Possible values: +

+
‘auto, 0’
+

automatically select the number of threads to set +

+
+ +

Default value is ‘auto’. +

+
+
dc integer (encoding,video)
+

Set intra_dc_precision. +

+
+
nssew integer (encoding,video)
+

Set nsse weight. +

+
+
skip_top integer (decoding,video)
+

Set number of macroblock rows at the top which are skipped. +

+
+
skip_bottom integer (decoding,video)
+

Set number of macroblock rows at the bottom which are skipped. +

+
+
profile integer (encoding,audio,video)
+
+

Set encoder codec profile. Default value is ‘unknown’. Encoder specific +profiles are documented in the relevant encoder documentation. +

+
+
level integer (encoding,audio,video)
+
+

Set the encoder level. This level depends on the specific codec, and +might correspond to the profile level. It is set by default to +‘unknown’. +

+

Possible values: +

+
‘unknown’
+
+ +
+
lowres integer (decoding,audio,video)
+

Decode at 1= 1/2, 2=1/4, 3=1/8 resolutions. +

+
+
mblmin integer (encoding,video)
+

Set min macroblock lagrange factor (VBR). +

+
+
mblmax integer (encoding,video)
+

Set max macroblock lagrange factor (VBR). +

+
+
skip_loop_filter integer (decoding,video)
+
skip_idct integer (decoding,video)
+
skip_frame integer (decoding,video)
+
+

Make decoder discard processing depending on the frame type selected +by the option value. +

+

skip_loop_filter skips frame loop filtering, skip_idct +skips frame IDCT/dequantization, skip_frame skips decoding. +

+

Possible values: +

+
‘none’
+

Discard no frame. +

+
+
‘default’
+

Discard useless frames like 0-sized frames. +

+
+
‘noref’
+

Discard all non-reference frames. +

+
+
‘bidir’
+

Discard all bidirectional frames. +

+
+
‘nokey’
+

Discard all frames excepts keyframes. +

+
+
‘nointra’
+

Discard all frames except I frames. +

+
+
‘all’
+

Discard all frames. +

+
+ +

Default value is ‘default’. +

+
+
bidir_refine integer (encoding,video)
+

Refine the two motion vectors used in bidirectional macroblocks. +

+
+
keyint_min integer (encoding,video)
+

Set minimum interval between IDR-frames. +

+
+
refs integer (encoding,video)
+

Set reference frames to consider for motion compensation. +

+
+
trellis integer (encoding,audio,video)
+

Set rate-distortion optimal quantization. +

+
+
mv0_threshold integer (encoding,video)
+
compression_level integer (encoding,audio,video)
+
bits_per_raw_sample integer
+
channel_layout integer (decoding/encoding,audio)
+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
rc_max_vbv_use float (encoding,video)
+
rc_min_vbv_use float (encoding,video)
+
color_primaries integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘bt470m’
+

BT.470 M +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘film’
+

Film +

+
‘bt2020’
+

BT.2020 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘smpte431’
+

SMPTE 431-2 +

+
‘smpte432’
+

SMPTE 432-1 +

+
‘jedec-p22’
+

JEDEC P22 +

+
+ +
+
color_trc integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘gamma22’
+

BT.470 M +

+
‘gamma28’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘linear’
+

Linear +

+
‘log’
+
‘log100’
+

Log +

+
‘log_sqrt’
+
‘log316’
+

Log square root +

+
‘iec61966_2_4’
+
‘iec61966-2-4’
+

IEC 61966-2-4 +

+
‘bt1361’
+
‘bt1361e’
+

BT.1361 +

+
‘iec61966_2_1’
+
‘iec61966-2-1’
+

IEC 61966-2-1 +

+
‘bt2020_10’
+
‘bt2020_10bit’
+

BT.2020 - 10 bit +

+
‘bt2020_12’
+
‘bt2020_12bit’
+

BT.2020 - 12 bit +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ +
+
colorspace integer (decoding/encoding,video)
+

Possible values: +

+
‘rgb’
+

RGB +

+
‘bt709’
+

BT.709 +

+
‘fcc’
+

FCC +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘ycocg’
+

YCOCG +

+
‘bt2020nc’
+
‘bt2020_ncl’
+

BT.2020 NCL +

+
‘bt2020c’
+
‘bt2020_cl’
+

BT.2020 CL +

+
‘smpte2085’
+

SMPTE 2085 +

+
‘chroma-derived-nc’
+

Chroma-derived NCL +

+
‘chroma-derived-c’
+

Chroma-derived CL +

+
‘ictcp’
+

ICtCp +

+
+ +
+
color_range integer (decoding/encoding,video)
+

If used as input parameter, it serves as a hint to the decoder, which +color_range the input has. +Possible values: +

+
‘tv’
+
‘mpeg’
+
‘limited’
+

MPEG (219*2^(n-8)) +

+
‘pc’
+
‘jpeg’
+
‘full’
+

JPEG (2^n-1) +

+
+ +
+
chroma_sample_location integer (decoding/encoding,video)
+

Possible values: +

+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode integer (decoding/encoding,video)
+

Possible values: +

+
‘premultiplied’
+
‘straight’
+
+ + +
+
log_level_offset integer
+

Set the log level offset. +

+
+
slices integer (encoding,video)
+

Number of slices, used in parallelized encoding. +

+
+
thread_type flags (decoding/encoding,video)
+

Select which multithreading methods to use. +

+

Use of ‘frame’ will increase decoding delay by one frame per +thread, so clients which cannot provide future frames should not use +it. +

+

Possible values: +

+
‘slice’
+

Decode more than one part of a single frame at once. +

+

Multithreading using slices works only when the video was encoded with +slices. +

+
+
‘frame’
+

Decode more than one frame at once. +

+
+ +

Default value is ‘slice+frame’. +

+
+
audio_service_type integer (encoding,audio)
+

Set audio service type. +

+

Possible values: +

+
‘ma’
+

Main Audio Service +

+
‘ef’
+

Effects +

+
‘vi’
+

Visually Impaired +

+
‘hi’
+

Hearing Impaired +

+
‘di’
+

Dialogue +

+
‘co’
+

Commentary +

+
‘em’
+

Emergency +

+
‘vo’
+

Voice Over +

+
‘ka’
+

Karaoke +

+
+ +
+
request_sample_fmt sample_fmt (decoding,audio)
+

Set sample format audio decoders should prefer. Default value is +none. +

+
+
pkt_timebase rational number
+
sub_charenc encoding (decoding,subtitles)
+

Set the input subtitles character encoding. +

+
+
field_order field_order (video)
+

Set/override the field order of the video. +Possible values: +

+
‘progressive’
+

Progressive video +

+
‘tt’
+

Interlaced video, top field coded and displayed first +

+
‘bb’
+

Interlaced video, bottom field coded and displayed first +

+
‘tb’
+

Interlaced video, top coded first, bottom displayed first +

+
‘bt’
+

Interlaced video, bottom coded first, top displayed first +

+
+ +
+
skip_alpha bool (decoding,video)
+

Set to 1 to disable processing alpha (transparency). This works like the +‘gray’ flag in the flags option which skips chroma information +instead of alpha. Default is 0. +

+
+
codec_whitelist list (input)
+

"," separated list of allowed decoders. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_pixels integer (decoding/encoding,video)
+

Maximum number of pixels per image. This value can be used to avoid out of +memory failures due to large images. +

+
+
apply_cropping bool (decoding,video)
+

Enable cropping if cropping parameters are multiples of the required +alignment for the left and top parameters. If the alignment is not met the +cropping will be partially applied to maintain alignment. +Default is 1 (enabled). +Note: The required alignment depends on if AV_CODEC_FLAG_UNALIGNED is set and the +CPU. AV_CODEC_FLAG_UNALIGNED cannot be changed from the command line. Also hardware +decoders will not apply left/top Cropping. +

+ +
+
+ + + +

7 Decoders

+ +

Decoders are configured elements in FFmpeg which allow the decoding of +multimedia streams. +

+

When you configure your FFmpeg build, all the supported native decoders +are enabled by default. Decoders requiring an external library must be enabled +manually via the corresponding --enable-lib option. You can list all +available decoders using the configure option --list-decoders. +

+

You can disable all the decoders with the configure option +--disable-decoders and selectively enable / disable single decoders +with the options --enable-decoder=DECODER / +--disable-decoder=DECODER. +

+

The option -decoders of the ff* tools will display the list of +enabled decoders. +

+ + +

8 Video Decoders

+ +

A description of some of the currently available video decoders +follows. +

+ +

8.1 av1

+ +

AOMedia Video 1 (AV1) decoder. +

+ +

8.1.1 Options

+ +
+
operating_point
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Default is 0. +

+
+
+ + +

8.2 hevc

+

HEVC (AKA ITU-T H.265 or ISO/IEC 23008-2) decoder. +

+

The decoder supports MV-HEVC multiview streams with at most two views. Views to +be output are selected by supplying a list of view IDs to the decoder (the +view_ids option). This option may be set either statically before +decoder init, or from the get_format() callback - useful for the case +when the view count or IDs change dynamically during decoding. +

+

Only the base layer is decoded by default. +

+

Note that if you are using the ffmpeg CLI tool, you should be using view +specifiers as documented in its manual, rather than the options documented here. +

+ +

8.2.1 Options

+ +
+
view_ids (MV-HEVC)
+

Specify a list of view IDs that should be output. This option can also be set to +a single ’-1’, which will cause all views defined in the VPS to be decoded and +output. +

+
+
view_ids_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view IDs available +in the active VPS. The array is empty for single-layer video. +

+

The value of this option is guaranteed to be accurate when read from the +get_format() callback. It may also be set at other times (e.g. after +opening the decoder), but the value is informational only and may be incorrect +(e.g. when the stream contains multiple distinct VPS NALUs). +

+
+
view_pos_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view positions +(left, right, or unspecified) available in the active VPS, as +AVStereo3DView values. When the array is available, its elements apply to +the corresponding elements of view_ids_available, i.e. +view_pos_available[i] contains the position of view with ID +view_ids_available[i]. +

+

Same validity restrictions as for view_ids_available apply to +this option. +

+
+
+ + +

8.3 rawvideo

+ +

Raw video decoder. +

+

This decoder decodes rawvideo streams. +

+ +

8.3.1 Options

+ +
+
top top_field_first
+

Specify the assumed field type of the input video. +

+
-1
+

the video is assumed to be progressive (default) +

+
0
+

bottom-field-first is assumed +

+
1
+

top-field-first is assumed +

+
+ +
+
+ + +

8.4 libdav1d

+ +

dav1d AV1 decoder. +

+

libdav1d allows libavcodec to decode the AOMedia Video 1 (AV1) codec. +Requires the presence of the libdav1d headers and library during configuration. +You need to explicitly configure the build with --enable-libdav1d. +

+ +

8.4.1 Options

+ +

The following options are supported by the libdav1d wrapper. +

+
+
max_frame_delay
+

Set max amount of frames the decoder may buffer internally. The default value is 0 +(autodetect). +

+
+
filmgrain
+

Apply film grain to the decoded video if present in the bitstream. Defaults to the +internal default of the library. +This option is deprecated and will be removed in the future. See the global option +export_side_data to export Film Grain parameters instead of applying it. +

+
+
oppoint
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Defaults to the +internal default of the library. +

+
+
alllayers
+

Output all spatial layers of a scalable AV1 bitstream. The default value is false. +

+
+
+ + +

8.5 libdavs2

+ +

AVS2-P2/IEEE1857.4 video decoder wrapper. +

+

This decoder allows libavcodec to decode AVS2 streams with davs2 library. +

+ + +

8.6 libuavs3d

+ +

AVS3-P2/IEEE1857.10 video decoder. +

+

libuavs3d allows libavcodec to decode AVS3 streams. +Requires the presence of the libuavs3d headers and library during configuration. +You need to explicitly configure the build with --enable-libuavs3d. +

+ +

8.6.1 Options

+ +

The following option is supported by the libuavs3d wrapper. +

+
+
frame_threads
+

Set amount of frame threads to use during decoding. The default value is 0 (autodetect). +

+
+
+ + +

8.7 libxevd

+ +

eXtra-fast Essential Video Decoder (XEVD) MPEG-5 EVC decoder wrapper. +

+

This decoder requires the presence of the libxevd headers and library +during configuration. You need to explicitly configure the build with +--enable-libxevd. +

+

The xevd project website is at https://github.com/mpeg5/xevd. +

+ +

8.7.1 Options

+ +

The following options are supported by the libxevd wrapper. +The xevd-equivalent options or values are listed in parentheses for easy migration. +

+

To get a more accurate and extensive documentation of the libxevd options, +invoke the command xevd_app --help or consult the libxevd documentation. +

+
+
threads (threads)
+

Force to use a specific number of threads +

+
+
+ + +

8.8 QSV Decoders

+ +

The family of Intel QuickSync Video decoders (VC1, MPEG-2, H.264, HEVC, +JPEG/MJPEG, VP8, VP9, AV1, VVC). +

+ +

8.8.1 Common Options

+ +

The following options are supported by all qsv decoders. +

+
+
async_depth
+

Internal parallelization depth, the higher the value the higher the latency. +

+
+
gpu_copy
+

A GPU-accelerated copy between video and system memory +

+
‘default’
+
‘on’
+
‘off’
+
+ +
+
+ + +

8.8.2 HEVC Options

+

Extra options for hevc_qsv. +

+
+
load_plugin
+

A user plugin to load in an internal session +

+
‘none’
+
‘hevc_sw’
+
‘hevc_hw’
+
+ +
+
load_plugins
+

A :-separate list of hexadecimal plugin UIDs to load in an internal session +

+
+
+ + +

8.9 v210

+ +

Uncompressed 4:2:2 10-bit decoder. +

+ +

8.9.1 Options

+ +
+
custom_stride
+

Set the line size of the v210 data in bytes. The default value is 0 +(autodetect). You can use the special -1 value for a strideless v210 as seen in +BOXX files. +

+
+
+ + + +

9 Audio Decoders

+ +

A description of some of the currently available audio decoders +follows. +

+ +

9.1 ac3

+ +

AC-3 audio decoder. +

+

This decoder implements part of ATSC A/52:2010 and ETSI TS 102 366, as well as +the undocumented RealAudio 3 (a.k.a. dnet). +

+ +

9.1.1 AC-3 Decoder Options

+ +
+
-drc_scale value
+

Dynamic Range Scale Factor. The factor to apply to dynamic range values +from the AC-3 stream. This factor is applied exponentially. The default value is 1. +There are 3 notable scale factor ranges: +

+
drc_scale == 0
+

DRC disabled. Produces full range audio. +

+
0 < drc_scale <= 1
+

DRC enabled. Applies a fraction of the stream DRC value. +Audio reproduction is between full range and full compression. +

+
drc_scale > 1
+

DRC enabled. Applies drc_scale asymmetrically. +Loud sounds are fully compressed. Soft sounds are enhanced. +

+
+ +
+
+ + +

9.2 flac

+ +

FLAC audio decoder. +

+

This decoder aims to implement the complete FLAC specification from Xiph. +

+ +

9.2.1 FLAC Decoder options

+ +
+
-use_buggy_lpc
+

The lavc FLAC encoder used to produce buggy streams with high lpc values +(like the default value). This option makes it possible to decode such streams +correctly by using lavc’s old buggy lpc logic for decoding. +

+
+
+ + +

9.3 ffwavesynth

+ +

Internal wave synthesizer. +

+

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. +

+ +

9.4 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 --enable-libcelt. +

+ +

9.5 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 --enable-libgsm. +

+

This decoder supports both the ordinary GSM and the Microsoft variant. +

+ +

9.6 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 +--enable-libilbc. +

+ +

9.6.1 Options

+ +

The following option is supported by the libilbc wrapper. +

+
+
enhance
+
+

Enable the enhancement of the decoded audio when set to 1. The default +value is 0 (disabled). +

+
+
+ + +

9.7 libmpeghdec

+ +

libmpeghdec decoder wrapper. +

+

libmpeghdec allows libmpeghdec to decode the MPEG-H 3D audio codec. +Requires the presence of the libmpeghdec headers and library during +configuration. You need to explicitly configure the build with +--enable-libmpeghdec --enable-nonfree. +

+ +

9.8 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 --enable-libopencore-amrnb. +

+

An FFmpeg native decoder for AMR-NB exists, so users can decode AMR-NB +without this library. +

+ +

9.9 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 --enable-libopencore-amrwb. +

+

An FFmpeg native decoder for AMR-WB exists, so users can decode AMR-WB +without this library. +

+ +

9.10 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 +--enable-libopus. +

+

An FFmpeg native decoder for Opus exists, so users can decode Opus +without this library. +

+ + +

10 Subtitles Decoders

+ + +

10.1 libaribb24

+ +

ARIB STD-B24 caption decoder. +

+

Implements profiles A and C of the ARIB STD-B24 standard. +

+ +

10.1.1 libaribb24 Decoder Options

+ +
+
-aribb24-base-path path
+

Sets the base path for the libaribb24 library. This is utilized for reading of +configuration files (for custom unicode conversions), and for dumping of +non-text symbols as images under that location. +

+

Unset by default. +

+
+
-aribb24-skip-ruby-text boolean
+

Tells the decoder wrapper to skip text blocks that contain half-height ruby +text. +

+

Enabled by default. +

+
+
+ + +

10.2 libaribcaption

+ +

Yet another ARIB STD-B24 caption decoder using external libaribcaption +library. +

+

Implements profiles A and C of the Japanese ARIB STD-B24 standard, +Brazilian ABNT NBR 15606-1, and Philippines version of ISDB-T. +

+

Requires the presence of the libaribcaption headers and library +(https://github.com/xqq/libaribcaption) during configuration. +You need to explicitly configure the build with --enable-libaribcaption. +If both libaribb24 and libaribcaption are enabled, libaribcaption +decoder precedes. +

+ +

10.2.1 libaribcaption Decoder Options

+ +
+
-sub_type subtitle_type
+

Specifies the format of the decoded subtitles. +

+
+
‘bitmap’
+

Graphical image. +

+
‘ass’
+

ASS formatted text. +

+
‘text’
+

Simple text based output without formatting. +

+
+ +

The default is ass as same as libaribb24 decoder. +Some present players (e.g., mpv) expect ASS format for ARIB caption. +

+
+
-caption_encoding encoding_scheme
+

Specifies the encoding scheme of input subtitle text. +

+
+
‘auto’
+

Automatically detect text encoding (default). +

+
‘jis’
+

8bit-char JIS encoding defined in ARIB STD B24. +This encoding used in Japan for ISDB captions. +

+
‘utf8’
+

UTF-8 encoding defined in ARIB STD B24. +This encoding is used in Philippines for ISDB-T captions. +

+
‘latin’
+

Latin character encoding defined in ABNT NBR 15606-1. +This encoding is used in South America for SBTVD / ISDB-Tb captions. +

+
+ +
+
-font font_name[,font_name2,...]
+

Specify comma-separated list of font family names to be used for bitmap +or ass type subtitle rendering. +Only first font name is used for ass type subtitle. +

+

If not specified, use internally defined default font family. +

+
+
-ass_single_rect boolean
+

ARIB STD-B24 specifies that some captions may be displayed at different +positions at a time (multi-rectangle subtitle). +Since some players (e.g., old mpv) can’t handle multiple ASS rectangles +in a single AVSubtitle, or multiple ASS rectangles of indeterminate duration +with the same start timestamp, this option can change the behavior so that +all the texts are displayed in a single ASS rectangle. +

+

The default is false. +

+

If your player cannot handle AVSubtitles with multiple ASS rectangles properly, +set this option to true or define ASS_SINGLE_RECT=1 to change +default behavior at compilation. +

+
+
-force_outline_text boolean
+

Specify whether always render outline text for all characters regardless of +the indication by character style. +

+

The default is false. +

+
+
-outline_width number (0.0 - 3.0)
+

Specify width for outline text, in dots (relative). +

+

The default is 1.5. +

+
+
-ignore_background boolean
+

Specify whether to ignore background color rendering. +

+

The default is false. +

+
+
-ignore_ruby boolean
+

Specify whether to ignore rendering for ruby-like (furigana) characters. +

+

The default is false. +

+
+
-replace_drcs boolean
+

Specify whether to render replaced DRCS characters as Unicode characters. +

+

The default is true. +

+
+
-replace_msz_ascii boolean
+

Specify whether to replace MSZ (Middle Size; half width) fullwidth +alphanumerics with halfwidth alphanumerics. +

+

The default is true. +

+
+
-replace_msz_japanese boolean
+

Specify whether to replace some MSZ (Middle Size; half width) fullwidth +japanese special characters with halfwidth ones. +

+

The default is true. +

+
+
-replace_msz_glyph boolean
+

Specify whether to replace MSZ (Middle Size; half width) characters +with halfwidth glyphs if the fonts supports it. +This option works under FreeType or DirectWrite renderer +with Adobe-Japan1 compliant fonts. +e.g., IBM Plex Sans JP, Morisawa BIZ UDGothic, Morisawa BIZ UDMincho, +Yu Gothic, Yu Mincho, and Meiryo. +

+

The default is true. +

+
+
-canvas_size image_size
+

Specify the resolution of the canvas to render subtitles to; usually, this +should be frame size of input video. +This only applies when -subtitle_type is set to bitmap. +

+

The libaribcaption decoder assumes input frame size for bitmap rendering as below: +

    +
  1. PROFILE_A : 1440 x 1080 with SAR (PAR) 4:3 +
  2. PROFILE_C : 320 x 180 with SAR (PAR) 1:1 +
+ +

If actual frame size of input video does not match above assumption, +the rendered captions may be distorted. +To make the captions undistorted, add -canvas_size option to specify +actual input video size. +

+

Note that the -canvas_size option is not required for video with +different size but same aspect ratio. +In such cases, the caption will be stretched or shrunk to actual video size +if -canvas_size option is not specified. +If -canvas_size option is specified with different size, +the caption will be stretched or shrunk as specified size with calculated SAR. +

+
+
+ + +

10.2.2 libaribcaption decoder usage examples

+ +

Display MPEG-TS file with ARIB subtitle by ffplay tool: +

+
ffplay -sub_type bitmap MPEG.TS
+
+ +

Display MPEG-TS file with input frame size 1920x1080 by ffplay tool: +

+
ffplay -sub_type bitmap -canvas_size 1920x1080 MPEG.TS
+
+ +

Embed ARIB subtitle in transcoded video: +

+
ffmpeg -sub_type bitmap -i src.m2t -filter_complex "[0:v][0:s]overlay" -vcodec h264 dest.mp4
+
+ + +

10.3 dvbsub

+ + +

10.3.1 Options

+ +
+
compute_clut
+
+
-2
+

Compute clut once if no matching CLUT is in the stream. +

+
-1
+

Compute clut if no matching CLUT is in the stream. +

+
0
+

Never compute CLUT +

+
1
+

Always compute CLUT and override the one provided in the stream. +

+
+
+
dvb_substream
+

Selects the dvb substream, or all substreams if -1 which is default. +

+
+
+ + +

10.4 dvdsub

+ +

This codec decodes the bitmap subtitles used in DVDs; the same subtitles can +also be found in VobSub file pairs and in some Matroska files. +

+ +

10.4.1 Options

+ +
+
palette
+

Specify the global palette used by the bitmaps. When stored in VobSub, the +palette is normally specified in the index file; in Matroska, the palette is +stored in the codec extra-data in the same format as in VobSub. In DVDs, the +palette is stored in the IFO file, and therefore not available when reading +from dumped VOB files. +

+

The format for this option is a string containing 16 24-bits hexadecimal +numbers (without 0x prefix) separated by commas, for example 0d00ee, +ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, +7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b. +

+
+
ifo_palette
+

Specify the IFO file from which the global palette is obtained. +(experimental) +

+
+
forced_subs_only
+

Only decode subtitle entries marked as forced. Some titles have forced +and non-forced subtitles in the same track. Setting this flag to 1 +will only keep the forced subtitles. Default value is 0. +

+
+ + +

10.5 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 +--enable-libzvbi. +

+ +

10.5.1 Options

+ +
+
txt_page
+

List of teletext page numbers to decode. Pages that do not match the specified +list are dropped. You may use the special * string to match all pages, +or subtitle to match all subtitle pages. +Default value is *. +

+
txt_default_region
+

Set default character set used for decoding, a value between 0 and 87 (see +ETS 300 706, Section 15, Table 32). Default value is -1, which does not +override the libzvbi default. This option is needed for some legacy level 1.0 +transmissions which cannot signal the proper charset. +

+
txt_chop_top
+

Discards the top teletext line. Default value is 1. +

+
txt_format
+

Specifies the format of the decoded subtitles. +

+
bitmap
+

The default format, you should use this for teletext pages, because certain +graphics and colors cannot be expressed in simple text or even ASS. +

+
text
+

Simple text based output without formatting. +

+
ass
+

Formatted ASS output, subtitle pages and teletext pages are returned in +different styles, subtitle pages are stripped down to text, but an effort is +made to keep the text alignment and the formatting. +

+
+
+
txt_left
+

X offset of generated bitmaps, default is 0. +

+
txt_top
+

Y offset of generated bitmaps, default is 0. +

+
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 characters. +Default value is 1. +

+
txt_duration
+

Sets the display duration of the decoded teletext pages or subtitles in +milliseconds. Default value is -1 which means infinity or until the next +subtitle event comes. +

+
txt_transparent
+

Force transparent background of the generated teletext bitmaps. Default value +is 0 which means an opaque background. +

+
txt_opacity
+

Sets the opacity (0-255) of the teletext background. If +txt_transparent is not set, it only affects characters between a start +box and an end box, typically subtitles. Default value is 0 if +txt_transparent is set, 255 otherwise. +

+
+
+ + +

11 Bitstream Filters

+ +

When you configure your FFmpeg build, all the supported bitstream +filters are enabled by default. You can list all available ones using +the configure option --list-bsfs. +

+

You can disable all the bitstream filters using the configure option +--disable-bsfs, and selectively enable any bitstream filter using +the option --enable-bsf=BSF, or you can disable a particular +bitstream filter using the option --disable-bsf=BSF. +

+

The option -bsfs of the ff* tools will display the list of +all the supported bitstream filters included in your build. +

+

The ff* tools have a -bsf option applied per stream, taking a +comma-separated list of filters, whose parameters follow the filter +name after a ’=’. +

+
+
ffmpeg -i INPUT -c:v copy -bsf:v filter1[=opt1=str1:opt2=str2][,filter2] OUTPUT
+
+ +

Below is a description of the currently available bitstream filters, +with their parameters, if any. +

+ +

11.1 aac_adtstoasc

+ +

Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration +bitstream. +

+

This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4 +ADTS header and removes the ADTS header. +

+

This filter is required for example when copying an AAC stream from a +raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or +to MOV/MP4 files and related formats such as 3GP or M4A. Please note +that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats. +

+ +

11.2 av1_metadata

+ +

Modify metadata embedded in an AV1 stream. +

+
+
td
+

Insert or remove temporal delimiter OBUs in all temporal units of the +stream. +

+
+
‘insert’
+

Insert a TD at the beginning of every TU which does not already have one. +

+
‘remove’
+

Remove the TD from the beginning of every TU which has one. +

+
+ +
+
color_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the color description fields in the stream (see AV1 section 6.4.2). +

+
+
color_range
+

Set the color range in the stream (see AV1 section 6.4.2; note that +this cannot be set for streams using BT.709 primaries, sRGB transfer +characteristic and identity (RGB) matrix coefficients). +

+
‘tv’
+

Limited range. +

+
‘pc’
+

Full range. +

+
+ +
+
chroma_sample_position
+

Set the chroma sample location in the stream (see AV1 section 6.4.2). +This can only be set for 4:2:0 streams. +

+
+
‘vertical’
+

Left position (matching the default in MPEG-2 and H.264). +

+
‘colocated’
+

Top-left position. +

+
+ +
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_display_tick) in +the timing info in the sequence header. +

+
num_ticks_per_picture
+

Set the number of ticks in each picture, to indicate that the stream +has a fixed framerate. Ignored if tick_rate is not also set. +

+
+
delete_padding
+

Deletes Padding OBUs. +

+
+
+ + +

11.3 chomp

+ +

Remove zero padding at the end of a packet. +

+ +

11.4 dca_core

+ +

Extract the core from a DCA/DTS stream, dropping extensions such as +DTS-HD. +

+ +

11.5 dovi_rpu

+ +

Manipulate Dolby Vision metadata in a HEVC/AV1 bitstream, optionally enabling +metadata compression. +

+
+
strip
+

If enabled, strip all Dolby Vision metadata (configuration record + RPU data +blocks) from the stream. +

+
compression
+

Which compression level to enable. +

+
‘none’
+

No metadata compression. +

+
‘limited’
+

Limited metadata compression scheme. Should be compatible with most devices. +This is the default. +

+
‘extended’
+

Extended metadata compression. Devices are not required to support this. Note +that this level currently behaves the same as ‘limited’ in libavcodec. +

+
+
+
+ + +

11.6 dump_extra

+ +

Add extradata to the beginning of the filtered packets except when +said packets already exactly begin with the extradata that is intended +to be added. +

+
+
freq
+

The additional argument specifies which packets should be filtered. +It accepts the values: +

+
‘k’
+
‘keyframe’
+

add extradata to all key packets +

+
+
‘e’
+
‘all’
+

add extradata to all packets +

+
+
+
+ +

If not specified it is assumed ‘k’. +

+

For example the following ffmpeg command forces a global +header (thus disabling individual packet headers) in the H.264 packets +generated by the libx264 encoder, but corrects them by adding +the header stored in extradata to the key packets: +

+
ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts
+
+ + +

11.7 dv_error_marker

+ +

Blocks in DV which are marked as damaged are replaced by blocks of the specified color. +

+
+
color
+

The color to replace damaged blocks by +

+
sta
+

A 16 bit mask which specifies which of the 16 possible error status values are +to be replaced by colored blocks. 0xFFFE is the default which replaces all non 0 +error status values. +

+
‘ok’
+

No error, no concealment +

+
‘err’
+

Error, No concealment +

+
‘res’
+

Reserved +

+
‘notok’
+

Error or concealment +

+
‘notres’
+

Not reserved +

+
‘Aa, Ba, Ca, Ab, Bb, Cb, A, B, C, a, b, erri, erru’
+

The specific error status code +

+
+

see page 44-46 or section 5.5 of +http://web.archive.org/web/20060927044735/http://www.smpte.org/smpte_store/standards/pdf/s314m.pdf +

+
+
+ + +

11.8 eac3_core

+ +

Extract the core from a E-AC-3 stream, dropping extra channels. +

+ +

11.9 eia608_to_smpte436m

+ +

Convert from a EIA_608 stream to a SMPTE_436M_ANC data stream, wrapping the closed captions in CTA-708 CDP VANC packets. +

+
+
line_number
+

Choose which line number the generated VANC packets should go on. You generally want either line 9 (the default) or 11. +

+
wrapping_type
+

Choose the SMPTE 436M wrapping type, defaults to ‘vanc_frame’. +It accepts the values: +

+
‘vanc_frame’
+

VANC frame (interlaced or segmented progressive frame) +

+
‘vanc_field_1’
+
‘vanc_field_2’
+
‘vanc_progressive_frame’
+
+
+
sample_coding
+

Choose the SMPTE 436M sample coding, defaults to ‘8bit_luma’. +It accepts the values: +

+
‘8bit_luma’
+

8-bit component luma samples +

+
‘8bit_color_diff’
+

8-bit component color difference samples +

+
‘8bit_luma_and_color_diff’
+

8-bit component luma and color difference samples +

+
‘10bit_luma’
+

10-bit component luma samples +

+
‘10bit_color_diff’
+

10-bit component color difference samples +

+
‘10bit_luma_and_color_diff’
+

10-bit component luma and color difference samples +

+
‘8bit_luma_parity_error’
+

8-bit component luma samples with parity error +

+
‘8bit_color_diff_parity_error’
+

8-bit component color difference samples with parity error +

+
‘8bit_luma_and_color_diff_parity_error’
+

8-bit component luma and color difference samples with parity error +

+
+
+
initial_cdp_sequence_cntr
+

The initial value of the CDP’s 16-bit unsigned integer cdp_hdr_sequence_cntr and cdp_ftr_sequence_cntr fields. Defaults to 0. +

+
cdp_frame_rate
+

Set the CDP’s cdp_frame_rate field. This doesn’t actually change the timing of the data stream, it just changes the values inserted in that field in the generated CDP packets. Defaults to ‘30000/1001’. +

+
+ + +

11.10 extract_extradata

+ +

Extract the in-band extradata. +

+

Certain codecs allow the long-term headers (e.g. MPEG-2 sequence headers, +or H.264/HEVC (VPS/)SPS/PPS) to be transmitted either "in-band" (i.e. as a part +of the bitstream containing the coded frames) or "out of band" (e.g. on the +container level). This latter form is called "extradata" in FFmpeg terminology. +

+

This bitstream filter detects the in-band headers and makes them available as +extradata. +

+
+
remove
+

When this option is enabled, the long-term headers are removed from the +bitstream after extraction. +

+
+ + +

11.11 filter_units

+ +

Remove units with types in or not in a given set from the stream. +

+
+
pass_types
+

List of unit types or ranges of unit types to pass through while removing +all others. This is specified as a ’|’-separated list of unit type values +or ranges of values with ’-’. +

+
+
remove_types
+

Identical to pass_types, except the units in the given set +removed and all others passed through. +

+
+ +

The types used by pass_types and remove_types correspond to NAL unit types +(nal_unit_type) in H.264, HEVC and H.266 (see Table 7-1 in the H.264 +and HEVC specifications or Table 5 in the H.266 specification), to +marker values for JPEG (without 0xFF prefix) and to start codes without +start code prefix (i.e. the byte following the 0x000001) for MPEG-2. +For VP8 and VP9, every unit has type zero. +

+

Extradata is unchanged by this transformation, but note that if the stream +contains inline parameter sets then the output may be unusable if they are +removed. +

+

For example, to remove all non-VCL NAL units from an H.264 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=pass_types=1-5' OUTPUT
+
+ +

To remove all AUDs, SEI and filler from an H.265 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=35|38-40' OUTPUT
+
+ +

To remove all user data from a MPEG-2 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=178' OUTPUT
+
+ +

To remove all SEI from a H264 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=6' OUTPUT
+
+ +

To remove all prefix and suffix SEI from a HEVC stream, including Closed Captions and dynamic HDR: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=39|40' OUTPUT
+
+ + +

11.12 hapqa_extract

+ +

Extract Rgb or Alpha part of an HAPQA file, without recompression, in order to create an HAPQ or an HAPAlphaOnly file. +

+
+
texture
+

Specifies the texture to keep. +

+
+
color
+
alpha
+
+ +
+
+ +

Convert HAPQA to HAPQ +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=color -tag:v HapY -metadata:s:v:0 encoder="HAPQ" hapq_file.mov
+
+ +

Convert HAPQA to HAPAlphaOnly +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=alpha -tag:v HapA -metadata:s:v:0 encoder="HAPAlpha Only" hapalphaonly_file.mov
+
+ + +

11.13 h264_metadata

+ +

Modify metadata embedded in an H.264 stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
+ +

Default is pass. +

+
+
sample_aspect_ratio
+

Set the sample aspect ratio of the stream in the VUI parameters. +See H.264 table E-1. +

+
+
overscan_appropriate_flag
+

Set whether the stream is suitable for display using overscan +or not (see H.264 section E.2.1). +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.264 section E.2.1 and +table E-2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.264 section E.2.1 +and tables E-3, E-4 and E-5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.264 section +E.2.1 and figure E-1). +

+
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_tick) in the VUI +parameters. This is the smallest time unit representable in the +stream, and in many cases represents the field rate of the stream +(double the frame rate). +

+
fixed_frame_rate_flag
+

Set whether the stream has fixed framerate - typically this indicates +that the framerate is exactly half the tick rate, but the exact +meaning is dependent on interlacing and the picture structure (see +H.264 section E.2.1 and table E-6). +

+
zero_new_constraint_set_flags
+

Zero constraint_set4_flag and constraint_set5_flag in the SPS. These +bits were reserved in a previous version of the H.264 spec, and thus +some hardware decoders require these to be zero. The result of zeroing +this is still a valid bitstream. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the frame cropping offsets in the SPS. These values will replace +the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled or the stream is interlaced +(see H.264 section 7.4.2.1.1). +

+
+
sei_user_data
+

Insert a string as SEI unregistered user data. The argument must +be of the form UUID+string, where the UUID is as hex digits +possibly separated by hyphens, and the string can be anything. +

+

For example, ‘086f3693-b7b3-4f2c-9653-21492feee5b8+hello’ will +insert the string “hello” associated with the given UUID. +

+
+
delete_filler
+

Deletes both filler NAL units and filler SEI messages. +

+
+
display_orientation
+

Insert, extract or remove Display orientation SEI messages. +See H.264 section D.1.27 and D.2.27 for syntax and semantics. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
‘extract’
+
+ +

Default is pass. +

+

Insert mode works in conjunction with rotate and flip options. +Any pre-existing Display orientation messages will be removed in insert or remove mode. +Extract mode attaches the display matrix to the packet as side data. +

+
+
rotate
+

Set rotation in display orientation SEI (anticlockwise angle in degrees). +Range is -360 to +360. Default is NaN. +

+
+
flip
+

Set flip in display orientation SEI. +

+
+
‘horizontal’
+
‘vertical’
+
+ +

Default is unset. +

+
+
level
+

Set the level in the SPS. Refer to H.264 section A.3 and tables A-1 +to A-5. +

+

The argument must be the name of a level (for example, ‘4.2’), a +level_idc value (for example, ‘42’), or the special name ‘auto’ +indicating that the filter should attempt to guess the level from the +input stream properties. +

+
+
+ + +

11.14 h264_mp4toannexb

+ +

Convert an H.264 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.264 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an H.264 stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw H.264 (muxer h264) output formats. +

+ +

11.15 h264_redundant_pps

+ +

This applies a specific fixup to some Blu-ray BDMV H264 streams +which contain redundant PPSs. The PPSs modify irrelevant parameters +of the stream, confusing other transformations which require +the correct extradata. +

+

The encoder used on these impacted streams adds extra PPSs throughout +the stream, varying the initial QP and whether weighted prediction +was enabled. This causes issues after copying the stream into +a global header container, as the starting PPS is not suitable +for the rest of the stream. One side effect, for example, +is seeking will return garbled output until a new PPS appears. +

+

This BSF removes the extra PPSs and rewrites the slice headers +such that the stream uses a single leading PPS in the global header, +which resolves the issue. +

+ +

11.16 hevc_metadata

+ +

Modify metadata embedded in an HEVC stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘insert’
+
‘remove’
+
+ +
+
sample_aspect_ratio
+

Set the sample aspect ratio in the stream in the VUI parameters. +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.265 section E.3.1 and +table E.2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.265 section E.3.1 +and tables E.3, E.4 and E.5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.265 section +E.3.1 and figure E.1). +

+
+
tick_rate
+

Set the tick rate in the VPS and VUI parameters (time_scale / +num_units_in_tick). Combined with num_ticks_poc_diff_one, this can +set a constant framerate in the stream. Note that it is likely to be +overridden by container parameters when the stream is in a container. +

+
+
num_ticks_poc_diff_one
+

Set poc_proportional_to_timing_flag in VPS and VUI and use this value +to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and +E.3.1). Ignored if tick_rate is not also set. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the conformance window cropping offsets in the SPS. These values +will replace the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled (H.265 section 7.4.3.2.1). +

+
+
width
+
height
+

Set width and height after crop. +

+
+
level
+

Set the level in the VPS and SPS. See H.265 section A.4 and tables +A.6 and A.7. +

+

The argument must be the name of a level (for example, ‘5.1’), a +general_level_idc value (for example, ‘153’ for level 5.1), +or the special name ‘auto’ indicating that the filter should +attempt to guess the level from the input stream properties. +

+
+
+ + +

11.17 hevc_mp4toannexb

+ +

Convert an HEVC/H.265 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.265 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an HEVC stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw HEVC/H.265 (muxer h265 or +hevc) output formats. +

+ +

11.18 imxdump

+ +

Modifies the bitstream to fit in MOV and to be usable by the Final Cut +Pro decoder. This filter only applies to the mpeg2video codec, and is +likely not needed for Final Cut Pro 7 and newer with the appropriate +-tag:v. +

+

For example, to remux 30 MB/sec NTSC IMX to MOV: +

+
+
ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov
+
+ + +

11.19 mjpeg2jpeg

+ +

Convert MJPEG/AVI1 packets to full JPEG/JFIF packets. +

+

MJPEG is a video codec wherein each video frame is essentially a +JPEG image. The individual frames can be extracted without loss, +e.g. by +

+
+
ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg
+
+ +

Unfortunately, these chunks are incomplete JPEG images, because +they lack the DHT segment required for decoding. Quoting from +http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml: +

+

Avery Lee, writing in the rec.video.desktop newsgroup in 2001, +commented that "MJPEG, or at least the MJPEG in AVIs having the +MJPG fourcc, is restricted JPEG with a fixed – and *omitted* – +Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2, +and it must use basic Huffman encoding, not arithmetic or +progressive. . . . You can indeed extract the MJPEG frames and +decode them with a regular JPEG decoder, but you have to prepend +the DHT segment to them, or else the decoder won’t have any idea +how to decompress the data. The exact table necessary is given in +the OpenDML spec." +

+

This bitstream filter patches the header of frames extracted from an MJPEG +stream (carrying the AVI1 header ID and lacking a DHT segment) to +produce fully qualified JPEG images. +

+
+
ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg
+exiftran -i -9 frame*.jpg
+ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
+
+ + +

11.20 mjpegadump

+ +

Add an MJPEG A header to the bitstream, to enable decoding by +Quicktime. +

+ +

11.21 mov2textsub

+ +

Extract a representable text file from MOV subtitles, stripping the +metadata header from each subtitle packet. +

+

See also the text2movsub filter. +

+ +

11.22 mpeg2_metadata

+ +

Modify metadata embedded in an MPEG-2 stream. +

+
+
display_aspect_ratio
+

Set the display aspect ratio in the stream. +

+

The following fixed values are supported: +

+
4/3
+
16/9
+
221/100
+
+

Any other value will result in square pixels being signalled instead +(see H.262 section 6.3.3 and table 6-3). +

+
+
frame_rate
+

Set the frame rate in the stream. This is constructed from a table +of known values combined with a small multiplier and divisor - if +the supplied value is not exactly representable, the nearest +representable value will be used instead (see H.262 section 6.3.3 +and table 6-4). +

+
+
video_format
+

Set the video format in the stream (see H.262 section 6.3.6 and +table 6-6). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.262 section 6.3.6 +and tables 6-7, 6-8 and 6-9). +

+
+
+ + +

11.23 mpeg4_unpack_bframes

+ +

Unpack DivX-style packed B-frames. +

+

DivX-style packed B-frames are not valid MPEG-4 and were only a +workaround for the broken Video for Windows subsystem. +They use more space, can cause minor AV sync issues, require more +CPU power to decode (unless the player has some decoded picture queue +to compensate the 2,0,2,0 frame per packet style) and cause +trouble if copied into a standard container like mp4 or mpeg-ps/ts, +because MPEG-4 decoders may not be able to decode them, since they are +not valid MPEG-4. +

+

For example to fix an AVI file containing an MPEG-4 stream with +DivX-style packed B-frames using ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi
+
+ + +

11.24 noise

+ +

Damages the contents of packets or simply drops them without damaging the +container. Can be used for fuzzing or testing error resilience/concealment. +

+

Parameters: +

+
amount
+

Accepts an expression whose evaluation per-packet determines how often bytes in that +packet will be modified. A value below 0 will result in a variable frequency. +Default is 0 which results in no modification. However, if neither amount nor drop is specified, +amount will be set to -1. See below for accepted variables. +

+
drop
+

Accepts an expression evaluated per-packet whose value determines whether that packet is dropped. +Evaluation to a positive value results in the packet being dropped. Evaluation to a negative +value results in a variable chance of it being dropped, roughly inverse in proportion to the magnitude +of the value. Default is 0 which results in no drops. See below for accepted variables. +

+
dropamount
+

Accepts a non-negative integer, which assigns a variable chance of it being dropped, roughly inverse +in proportion to the value. Default is 0 which results in no drops. This option is kept for backwards +compatibility and is equivalent to setting drop to a negative value with the same magnitude +i.e. dropamount=4 is the same as drop=-4. Ignored if drop is also specified. +

+
+ +

Both amount and drop accept expressions containing the following variables: +

+
+
‘n’
+

The index of the packet, starting from zero. +

+
‘tb’
+

The timebase for packet timestamps. +

+
‘pts’
+

Packet presentation timestamp. +

+
‘dts’
+

Packet decoding timestamp. +

+
‘nopts’
+

Constant representing AV_NOPTS_VALUE. +

+
‘startpts’
+

First non-AV_NOPTS_VALUE PTS seen in the stream. +

+
‘startdts’
+

First non-AV_NOPTS_VALUE DTS seen in the stream. +

+
‘duration’
+
‘d’
+

Packet duration, in timebase units. +

+
‘pos’
+

Packet position in input; may be -1 when unknown or not set. +

+
‘size’
+

Packet size, in bytes. +

+
‘key’
+

Whether packet is marked as a keyframe. +

+
‘state’
+

A pseudo random integer, primarily derived from the content of packet payload. +

+
+ + +

11.24.1 Examples

+

Apply modification to every byte but don’t drop any packets. +

+
ffmpeg -i INPUT -c copy -bsf noise=1 output.mkv
+
+ +

Drop every video packet not marked as a keyframe after timestamp 30s but do not +modify any of the remaining packets. +

+
ffmpeg -i INPUT -c copy -bsf:v noise=drop='gt(pts*tb\,30)*not(key)' output.mkv
+
+ +

Drop one second of audio every 10 seconds and add some random noise to the rest. +

+
ffmpeg -i INPUT -c copy -bsf:a noise=amount=-1:drop='between(mod(pts*tb\,10)\,9\,10)' output.mkv
+
+ + +

11.25 null

+

This bitstream filter passes the packets through unchanged. +

+ +

11.26 pcm_rechunk

+ +

Repacketize PCM audio to a fixed number of samples per packet or a fixed packet +rate per second. This is similar to the asetnsamples audio +filter but works on audio packets instead of audio frames. +

+
+
nb_out_samples, n
+

Set the number of samples per each output audio packet. The number is intended +as the number of samples per each channel. Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio packet with silence, so that it +will contain the same number of samples (or roughly the same number of samples, +see frame_rate) as the previous ones. Default value is 1. +

+
+
frame_rate, r
+

This option makes the filter output a fixed number of packets per second instead +of a fixed number of samples per packet. If the audio sample rate is not +divisible by the frame rate then the number of samples will not be constant but +will vary slightly so that each packet will start as close to the frame +boundary as possible. Using this option has precedence over nb_out_samples. +

+
+ +

You can generate the well known 1602-1601-1602-1601-1602 pattern of 48kHz audio +for NTSC frame rate using the frame_rate option. +

+
ffmpeg -f lavfi -i sine=r=48000:d=1 -c pcm_s16le -bsf pcm_rechunk=r=30000/1001 -f framecrc -
+
+ + +

11.27 pgs_frame_merge

+ +

Merge a sequence of PGS Subtitle segments ending with an "end of display set" +segment into a single packet. +

+

This is required by some containers that support PGS subtitles +(muxer matroska). +

+ +

11.28 prores_metadata

+ +

Modify color property metadata embedded in prores stream. +

+
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘bt470bg’
+

BT601 625 +

+
+
‘smpte170m’
+

BT601 525 +

+
+
‘bt2020’
+
‘smpte431’
+

DCI P3 +

+
+
‘smpte432’
+

P3 D65 +

+
+
+ +
+
transfer_characteristics
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same transfer characteristics property (default). +

+
+
‘unknown’
+
‘bt709’
+

BT 601, BT 709, BT 2020 +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ + +
+
matrix_coefficients
+

Set the matrix coefficient. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘smpte170m’
+

BT 601 +

+
+
‘bt2020nc’
+
+
+
+ +

Set Rec709 colorspace for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt709:color_trc=bt709:colorspace=bt709 output.mov
+
+ +

Set Hybrid Log-Gamma parameters for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt2020:color_trc=arib-std-b67:colorspace=bt2020nc output.mov
+
+ + +

11.29 remove_extra

+ +

Remove extradata from packets. +

+

It accepts the following parameter: +

+
freq
+

Set which frame types to remove extradata from. +

+
+
‘k’
+

Remove extradata from non-keyframes only. +

+
+
‘keyframe’
+

Remove extradata from keyframes only. +

+
+
‘e, all’
+

Remove extradata from all frames. +

+
+
+
+
+ + +

11.30 setts

+

Set PTS and DTS in packets. +

+

It accepts the following parameters: +

+
ts
+
pts
+
dts
+

Set expressions for PTS, DTS or both. +

+
duration
+

Set expression for duration. +

+
time_base
+

Set output time base. +

+
prescale
+

Set whether to convert time fields to user-set output time base before evaluation of expressions. Defaults to 0. +

+
+ +

The expressions are evaluated through the eval API and can contain the following +constants: +

+
+
N
+

The count of the input packet. Starting from 0. +

+
+
TS
+

The demux timestamp in input in case of ts or dts option or presentation +timestamp in case of pts option. +

+
+
POS
+

The original position in the file of the packet, or undefined if undefined +for the current packet +

+
+
DTS
+

The demux timestamp in input. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
DURATION
+

The duration in input. +

+
+
STARTDTS
+

The DTS of the first packet. +

+
+
STARTPTS
+

The PTS of the first packet. +

+
+
PREV_INDTS
+

The previous input DTS. +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INDURATION
+

The previous input duration. +

+
+
PREV_OUTDTS
+

The previous output DTS. +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTDURATION
+

The previous output duration. +

+
+
NEXT_DTS
+

The next input DTS. +

+
+
NEXT_PTS
+

The next input PTS. +

+
+
NEXT_DURATION
+

The next input duration. +

+
+
TB
+

The timebase in which time fields are denominated. The user-set output timebase if prescale is enabled, else the input timebase. +

+
+
TB_OUT
+

The output timebase. +

+
+
SR
+

The sample rate of stream packet belongs. +

+
+
NOPTS
+

The AV_NOPTS_VALUE constant. +

+
+ +

For example, to set PTS equal to DTS (not recommended if B-frames are involved): +

+
ffmpeg -i INPUT -c:a copy -bsf:a setts=pts=DTS out.mkv
+
+ + +

11.31 showinfo

+

Log basic packet information. Mainly useful for testing, debugging, +and development. +

+ +

11.32 smpte436m_to_eia608

+ +

Convert from a SMPTE_436M_ANC data stream to a EIA_608 stream, +extracting the closed captions from CTA-708 CDP VANC packets, and ignoring all other data. +

+ +

11.33 text2movsub

+ +

Convert text subtitles to MOV subtitles (as used by the mov_text +codec) with metadata headers. +

+

See also the mov2textsub filter. +

+ +

11.34 trace_headers

+ +

Log trace output containing all syntax elements in the coded stream +headers (everything above the level of individual coded blocks). +This can be useful for debugging low-level stream issues. +

+

Supports AV1, H.264, H.265, (M)JPEG, MPEG-2 and VP9, but depending +on the build only a subset of these may be available. +

+ +

11.35 truehd_core

+ +

Extract the core from a TrueHD stream, dropping ATMOS data. +

+ +

11.36 vp9_metadata

+ +

Modify metadata embedded in a VP9 stream. +

+
+
color_space
+

Set the color space value in the frame header. Note that any frame +set to RGB will be implicitly set to PC range and that RGB is +incompatible with profiles 0 and 2. +

+
‘unknown’
+
‘bt601’
+
‘bt709’
+
‘smpte170’
+
‘smpte240’
+
‘bt2020’
+
‘rgb’
+
+ +
+
color_range
+

Set the color range value in the frame header. Note that any value +imposed by the color space will take precedence over this value. +

+
‘tv’
+
‘pc’
+
+
+
+ + +

11.37 vp9_superframe

+ +

Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This +fixes merging of split/segmented VP9 streams where the alt-ref frame +was split from its visible counterpart. +

+ +

11.38 vp9_superframe_split

+ +

Split VP9 superframes into single frames. +

+ +

11.39 vp9_raw_reorder

+ +

Given a VP9 stream with correct timestamps but possibly out of order, +insert additional show-existing-frame packets to correct the ordering. +

+ +

12 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
avioflags flags (input/output)
+

Possible values: +

+
‘direct’
+

Reduce buffering. +

+
+ +
+
probesize integer (input)
+

Set probing size in bytes, i.e. the size of the data to analyze to get +stream information. A higher value will enable detecting 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. +

+
+
max_probe_packets integer (input)
+

Set the maximum number of buffered packets when probing a codec. +Default is 2500 packets. +

+
+
packetsize integer (output)
+

Set packet size. +

+
+
fflags flags
+

Set format flags. Some are implemented for a limited number of formats. +

+

Possible values for input files: +

+
‘discardcorrupt’
+

Discard corrupted packets. +

+
‘fastseek’
+

Enable fast, but inaccurate seeks for some formats. +

+
‘genpts’
+

Generate missing PTS if DTS is present. +

+
‘igndts’
+

Ignore DTS if PTS is also set. In case the PTS is set, the DTS value +is set to NOPTS. This is ignored when the nofillin flag is set. +

+
‘ignidx’
+

Ignore index. +

+
‘nobuffer’
+

Reduce the latency introduced by buffering during initial input streams analysis. +

+
‘nofillin’
+

Do not fill in missing values in packet fields that can be exactly calculated. +

+
‘noparse’
+

Disable AVParsers, this needs +nofillin too. +

+
‘sortdts’
+

Try to interleave output packets by DTS. At present, available only for AVIs with an index. +

+
+ +

Possible values for output files: +

+
‘autobsf’
+

Automatically apply bitstream filters as required by the output format. Enabled by default. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘flush_packets’
+

Write out packets immediately. +

+
‘shortest’
+

Stop muxing at the end of the shortest stream. +It may be needed to increase max_interleave_delta to avoid flushing the longer +streams before EOF. +

+
+ +
+
seek2any integer (input)
+

Allow seeking to non-keyframes on demuxer level when supported if set to 1. +Default is 0. +

+
+
analyzeduration integer (input)
+

Specify how many microseconds are analyzed to probe the input. A +higher value will enable detecting more accurate information, but will +increase latency. It defaults to 5,000,000 microseconds = 5 seconds. +

+
+
cryptokey hexadecimal string (input)
+

Set decryption key. +

+
+
indexmem integer (input)
+

Set max memory used for timestamp index (per stream). +

+
+
rtbufsize integer (input)
+

Set max memory used for buffering real-time frames. +

+
+
fdebug flags (input/output)
+

Print specific debug info. +

+

Possible values: +

+
‘ts’
+
+ +
+
max_delay integer (input/output)
+

Set maximum muxing or demuxing delay in microseconds. +

+
+
fpsprobesize integer (input)
+

Set number of frames used to probe fps. +

+
+
audio_preload integer (output)
+

Set microseconds by which audio packets should be interleaved earlier. +

+
+
chunk_duration integer (output)
+

Set microseconds for each chunk. +

+
+
chunk_size integer (output)
+

Set size in bytes for each chunk. +

+
+
err_detect, f_err_detect flags (input)
+

Set error detection flags. f_err_detect is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘crccheck’
+

Verify embedded CRCs. +

+
‘bitstream’
+

Detect bitstream specification deviations. +

+
‘buffer’
+

Detect improper bitstream length. +

+
‘explode’
+

Abort decoding on minor error detection. +

+
‘careful’
+

Consider things that violate the spec and have not been seen in the +wild as errors. +

+
‘compliant’
+

Consider all spec non compliancies as errors. +

+
‘aggressive’
+

Consider things that a sane encoder should not do as an error. +

+
+ +
+
max_interleave_delta integer (output)
+

Set maximum buffering duration for interleaving. The duration is +expressed in microseconds, and defaults to 10000000 (10 seconds). +

+

To ensure all the streams are interleaved correctly, libavformat will +wait until it has at least one packet for each stream before actually +writing any packets to the output file. When some streams are +"sparse" (i.e. there are large gaps between successive packets), this +can result in excessive buffering. +

+

This field specifies the maximum difference between the timestamps of the +first and the last packet in the muxing queue, above which libavformat +will output a packet regardless of whether it has queued a packet for all +the streams. +

+

If set to 0, libavformat will continue buffering packets until it has +a packet for each stream, regardless of the maximum timestamp +difference between the buffered packets. +

+
+
use_wallclock_as_timestamps integer (input)
+

Use wallclock as timestamps if set to 1. Default is 0. +

+
+
avoid_negative_ts integer (output)
+
+

Possible values: +

+
‘make_non_negative’
+

Shift timestamps to make them non-negative. +Also note that this affects only leading negative timestamps, and not +non-monotonic negative timestamps. +

+
‘make_zero’
+

Shift timestamps so that the first timestamp is 0. +

+
‘auto (default)’
+

Enables shifting when required by the target format. +

+
‘disabled’
+

Disables shifting of timestamp. +

+
+ +

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. +

+
+
skip_initial_bytes integer (input)
+

Set number of bytes to skip before reading header and frames if set to 1. +Default is 0. +

+
+
correct_ts_overflow integer (input)
+

Correct single timestamp overflows if set to 1. Default is 1. +

+
+
flush_packets integer (output)
+

Flush the underlying I/O stream after each packet. Default is -1 (auto), which +means that the underlying protocol will decide, 1 enables it, and has the +effect of reducing the latency, 0 disables it and may increase IO throughput in +some cases. +

+
+
output_ts_offset offset (output)
+

Set the output time offset. +

+

offset must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

The offset is added by the muxer to the output timestamps. +

+

Specifying a positive offset means that the corresponding streams are +delayed bt the time duration specified in offset. Default value +is 0 (meaning that no offset is applied). +

+
+
format_whitelist list (input)
+

"," separated list of allowed demuxers. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_streams integer (input)
+

Specifies the maximum number of streams. This can be used to reject files that +would require too many resources due to a large number of streams. +

+
+
skip_estimate_duration_from_pts bool (input)
+

Skip estimation of input duration if it requires an additional probing for PTS at end of file. +At present, applicable for MPEG-PS and MPEG-TS. +

+
+
duration_probesize integer (input)
+

Set probing size, in bytes, for input duration estimation when it actually requires +an additional probing for PTS at end of file (at present: MPEG-PS and MPEG-TS). +It is aimed at users interested in better durations probing for itself, or indirectly +because using the concat demuxer, for example. +The typical use case is an MPEG-TS CBR with a high bitrate, high video buffering and +ending cleaning with similar PTS for video and audio: in such a scenario, the large +physical gap between the last video packet and the last audio packet makes it necessary +to read many bytes in order to get the video stream duration. +Another use case is where the default probing behaviour only reaches a single video frame which is +not the last one of the stream due to frame reordering, so the duration is not accurate. +Setting this option has a performance impact even for small files because the probing +size is fixed. +Default behaviour is a general purpose trade-off, largely adaptive, but the probing size +will not be extended to get streams durations at all costs. +Must be an integer not lesser than 1, or 0 for default behaviour. +

+
+
strict, f_strict integer (input/output)
+

Specify how strictly to follow the standards. f_strict is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
+ + + +

12.1 Format stream specifiers

+ +

Format stream specifiers allow selection of one or more streams that +match specific properties. +

+

The exact semantics of stream specifiers is defined by the +avformat_match_stream_specifier() function declared in the +libavformat/avformat.h header and documented in the +Stream specifiers section in the ffmpeg(1) manual. +

+ +

13 Demuxers

+ +

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 +are enabled by default. You can list all available ones using the +configure option --list-demuxers. +

+

You can disable all the demuxers using the configure option +--disable-demuxers, and selectively enable a single demuxer with +the option --enable-demuxer=DEMUXER, or disable it +with the option --disable-demuxer=DEMUXER. +

+

The option -demuxers of the ff* tools will display the list of +enabled demuxers. Use -formats to view a combined list of +enabled demuxers and muxers. +

+

The description of some of the currently available demuxers follows. +

+ +

13.1 aa

+ +

Audible Format 2, 3, and 4 demuxer. +

+

This demuxer is used to demux Audible Format 2, 3, and 4 (.aa) files. +

+ +

13.2 aac

+ +

Raw Audio Data Transport Stream AAC demuxer. +

+

This demuxer is used to demux an ADTS input containing a single AAC stream +alongwith any ID3v1/2 or APE tags in it. +

+ +

13.3 apng

+ +

Animated Portable Network Graphics demuxer. +

+

This demuxer is used to demux APNG files. +All headers, but the PNG signature, up to (but not including) the first +fcTL chunk are transmitted as extradata. +Frames are then split as being all the chunks between two fcTL ones, or +between the last fcTL and IEND chunks. +

+
+
-ignore_loop bool
+

Ignore the loop variable in the file if set. Default is enabled. +

+
+
-max_fps int
+

Maximum framerate in frames per second. Default of 0 imposes no limit. +

+
+
-default_fps int
+

Default framerate in frames per second when none is specified in the file +(0 meaning as fast as possible). Default is 15. +

+
+
+ + +

13.4 asf

+ +

Advanced Systems Format demuxer. +

+

This demuxer is used to demux ASF files and MMS network streams. +

+
+
-no_resync_search bool
+

Do not try to resynchronize by looking for a certain optional start code. +

+
+ + +

13.5 concat

+ +

Virtual concatenation script demuxer. +

+

This demuxer reads a list of files and other directives from a text file and +demuxes them one after the other, as if all their packets had been muxed +together. +

+

The timestamps in the files are adjusted so that the first file starts at 0 +and each next file starts where the previous one finishes. Note that it is +done globally and may cause gaps if all streams do not have exactly the same +length. +

+

All files must have the same streams (same codecs, same time base, etc.). +

+

The duration of each file is used to adjust the timestamps of the next file: +if the duration is incorrect (because it was computed using the bit-rate or +because the file is truncated, for example), it can cause artifacts. The +duration directive can be used to override the duration stored in +each file. +

+ +

13.5.1 Syntax

+ +

The script is a text file in extended-ASCII, with one directive per line. +Empty lines, leading spaces and lines starting with ’#’ are ignored. The +following directive is recognized: +

+
+
file path
+

Path to a file to read; special characters and spaces must be escaped with +backslash or single quotes. +

+

All subsequent file-related directives apply to that file. +

+
+
ffconcat version 1.0
+

Identify the script type and version. +

+

To make FFmpeg recognize the format automatically, this directive must +appear exactly as is (no extra space or byte-order-mark) on the very first +line of the script. +

+
+
duration dur
+

Duration of the file. This information can be specified from the file; +specifying it here may be more efficient or help if the information from the +file is not available or accurate. +

+

If the duration is set for all files, then it is possible to seek in the +whole concatenated video. +

+
+
inpoint timestamp
+

In point of the file. When the demuxer opens the file it instantly seeks to the +specified timestamp. Seeking is done so that all streams can be presented +successfully at In point. +

+

This directive works best with intra frame codecs, because for non-intra frame +ones you will usually get extra packets before the actual In point and the +decoded content will most likely contain frames before In point too. +

+

For each file, packets before the file In point will have timestamps less than +the calculated start timestamp of the file (negative in case of the first +file), and the duration of the files (if not specified by the duration +directive) will be reduced based on their specified In point. +

+

Because of potential packets before the specified In point, packet timestamps +may overlap between two concatenated files. +

+
+
outpoint timestamp
+

Out point of the file. When the demuxer reaches the specified decoding +timestamp in any of the streams, it handles it as an end of file condition and +skips the current and all the remaining packets from all streams. +

+

Out point is exclusive, which means that the demuxer will not output packets +with a decoding timestamp greater or equal to Out point. +

+

This directive works best with intra frame codecs and formats where all streams +are tightly interleaved. For non-intra frame codecs you will usually get +additional packets with presentation timestamp after Out point therefore the +decoded content will most likely contain frames after Out point too. If your +streams are not tightly interleaved you may not get all the packets from all +streams before Out point and you may only will be able to decode the earliest +stream until Out point. +

+

The duration of the files (if not specified by the duration +directive) will be reduced based on their specified Out point. +

+
+
file_packet_metadata key=value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +This directive is deprecated, use file_packet_meta instead. +

+
+
file_packet_meta key value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +

+
+
option key value
+

Option to access, open and probe the file. +Can be present multiple times. +

+
+
stream
+

Introduce a stream in the virtual file. +All subsequent stream-related directives apply to the last introduced +stream. +Some streams properties must be set in order to allow identifying the +matching streams in the subfiles. +If no streams are defined in the script, the streams from the first file are +copied. +

+
+
exact_stream_id id
+

Set the id of the stream. +If this directive is given, the string with the corresponding id in the +subfiles will be used. +This is especially useful for MPEG-PS (VOB) files, where the order of the +streams is not reliable. +

+
+
stream_meta key value
+

Metadata for the stream. +Can be present multiple times. +

+
+
stream_codec value
+

Codec for the stream. +

+
+
stream_extradata hex_string
+

Extradata for the string, encoded in hexadecimal. +

+
+
chapter id start end
+

Add a chapter. id is an unique identifier, possibly small and +consecutive. +

+
+
+ + +

13.5.2 Options

+ +

This demuxer accepts the following option: +

+
+
safe
+

If set to 1, reject unsafe file paths and directives. +A file path is considered safe if it +does not contain a protocol specification and is relative and all components +only contain characters from the portable character set (letters, digits, +period, underscore and hyphen) and have no period at the beginning of a +component. +

+

If set to 0, any file name is accepted. +

+

The default is 1. +

+
+
auto_convert
+

If set to 1, try to perform automatic conversions on packet data to make the +streams concatenable. +The default is 1. +

+

Currently, the only conversion is adding the h264_mp4toannexb bitstream +filter to H.264 streams in MP4 format. This is necessary in particular if +there are resolution changes. +

+
+
segment_time_metadata
+

If set to 1, every packet will contain the lavf.concat.start_time and the +lavf.concat.duration packet metadata values which are the start_time and +the duration of the respective file segments in the concatenated output +expressed in microseconds. The duration metadata is only set if it is known +based on the concat file. +The default is 0. +

+
+
+ + +

13.5.3 Examples

+ +
    +
  • Use absolute filenames and include some comments: +
    +
    # my first filename
    +file /mnt/share/file-1.wav
    +# my second filename including whitespace
    +file '/mnt/share/file 2.wav'
    +# my third filename including whitespace plus single quote
    +file '/mnt/share/file 3'\''.wav'
    +
    + +
  • Allow for input format auto-probing, use safe filenames and set the duration of +the first file: +
    +
    ffconcat version 1.0
    +
    +file file-1.wav
    +duration 20.0
    +
    +file subdir/file-2.wav
    +
    +
+ + +

13.6 dash

+ +

Dynamic Adaptive Streaming over HTTP demuxer. +

+

This demuxer presents all AVStreams found in the manifest. +By setting the discard flags on AVStreams the caller can decide +which streams to actually receive. +Each stream mirrors the id and bandwidth properties from the +<Representation> as metadata keys named "id" and "variant_bitrate" respectively. +

+ +

13.6.1 Options

+ +

This demuxer accepts the following option: +

+
+
cenc_decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
cenc_decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
+ + +

13.7 dvdvideo

+ +

DVD-Video demuxer, powered by libdvdnav and libdvdread. +

+

Can directly ingest DVD titles, specifically sequential PGCs, into +a conversion pipeline. Menu assets, such as background video or audio, +can also be demuxed given the menu’s coordinates (at best effort). +

+

Block devices (DVD drives), ISO files, and directory structures are accepted. +Activate with -f dvdvideo in front of one of these inputs. +

+

This demuxer does NOT have decryption code of any kind. You are on your own +working with encrypted DVDs, and should not expect support on the matter. +

+

Underlying playback is handled by libdvdnav, and structure parsing by libdvdread. +FFmpeg must be built with GPL library support available as well as the +configure switches --enable-libdvdnav and --enable-libdvdread. +

+

You will need to provide either the desired "title number" or exact PGC/PG coordinates. +Many open-source DVD players and tools can aid in providing this information. +If not specified, the demuxer will default to title 1 which works for many discs. +However, due to the flexibility of the format, it is recommended to check manually. +There are many discs that are authored strangely or with invalid headers. +

+

If the input is a real DVD drive, please note that there are some drives which may +silently fail on reading bad sectors from the disc, returning random bits instead +which is effectively corrupt data. This is especially prominent on aging or rotting discs. +A second pass and integrity checks would be needed to detect the corruption. +This is not an FFmpeg issue. +

+ +

13.7.1 Background

+ +

DVD-Video is not a directly accessible, linear container format in the +traditional sense. Instead, it allows for complex and programmatic playback of +carefully muxed MPEG-PS streams that are stored in headerless VOB files. +To the end-user, these streams are known simply as "titles", but the actual +logical playback sequence is defined by one or more "PGCs", or Program Group Chains, +within the title. The PGC is in turn comprised of multiple "PGs", or Programs", +which are the actual video segments (and for a typical video feature, sequentially +ordered). The PGC structure, along with stream layout and metadata, are stored in +IFO files that need to be parsed. PGCs can be thought of as playlists in easier terms. +

+

An actual DVD player relies on user GUI interaction via menus and an internal VM +to drive the direction of demuxing. Generally, the user would either navigate (via menus) +or automatically be redirected to the PGC of their choice. During this process and +the subsequent playback, the DVD player’s internal VM also maintains a state and +executes instructions that can create jumps to different sectors during playback. +This is why libdvdnav is involved, as a linear read of the MPEG-PS blobs on the +disc (VOBs) is not enough to produce the right sequence in many cases. +

+

There are many other DVD structures (a long subject) that will not be discussed here. +NAV packets, in particular, are handled by this demuxer to build accurate timing +but not emitted as a stream. For a good high-level understanding, refer to: +https://code.videolan.org/videolan/libdvdnav/-/blob/master/doc/dvd_structures +

+ +

13.7.2 Options

+ +

This demuxer accepts the following options: +

+
+
title int
+

The title number to play. Must be set if pgc and pg are not set. +Not applicable to menus. +Default is 0 (auto), which currently only selects the first available title (title 1) +and notifies the user about the implications. +

+
+
chapter_start int
+

The chapter, or PTT (part-of-title), number to start at. Not applicable to menus. +Default is 1. +

+
+
chapter_end int
+

The chapter, or PTT (part-of-title), number to end at. Not applicable to menus. +Default is 0, which is a special value to signal end at the last possible chapter. +

+
+
angle int
+

The video angle number, referring to what is essentially an additional +video stream that is composed from alternate frames interleaved in the VOBs. +Not applicable to menus. +Default is 1. +

+
+
region int
+

The region code to use for playback. Some discs may use this to default playback +at a particular angle in different regions. This option will not affect the region code +of a real DVD drive, if used as an input. Not applicable to menus. +Default is 0, "world". +

+
+
menu bool
+

Demux menu assets instead of navigating a title. Requires exact coordinates +of the menu (menu_lu, menu_vts, pgc, pg). +Default is false. +

+
+
menu_lu int
+

The menu language to demux. In DVD, menus are grouped by language. +Default is 1, the first language unit. +

+
+
menu_vts int
+

The VTS where the menu lives, or 0 if it is a VMG menu (root-level). +Default is 1, menu of the first VTS. +

+
+
pgc int
+

The entry PGC to start playback, in conjunction with pg. +Alternative to setting title. +Chapter markers are not supported at this time. +Must be explicitly set for menus. +Default is 0, automatically resolve from value of title. +

+
+
pg int
+

The entry PG to start playback, in conjunction with pgc. +Alternative to setting title. +Chapter markers are not supported at this time. +Default is 1, the first PG of the PGC. +

+
+
preindex bool
+

Enable this to have accurate chapter (PTT) markers and duration measurement, +which requires a slow second pass read in order to index the chapter marker +timestamps from NAV packets. This is non-ideal extra work for real optical drives. +It is recommended and faster to use this option with a backup of the DVD structure +stored on a hard drive. Not compatible with pgc and pg. +Default is 0, false. +

+
+
trim bool
+

Skip padding cells (i.e. cells shorter than 1 second) from the beginning. +There exist many discs with filler segments at the beginning of the PGC, +often with junk data intended for controlling a real DVD player’s +buffering speed and with no other material data value. +Not applicable to menus. +Default is 1, true. +

+
+
+ + +

13.7.3 Examples

+ +
    +
  • Open title 3 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -title 3 -i <path to DVD> ...
    +
    + +
  • Open chapters 3-6 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 3 -chapter_end 6 -title 1 -i <path to DVD> ...
    +
    + +
  • Open only chapter 5 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 5 -chapter_end 5 -title 1 -i <path to DVD> ...
    +
    + +
  • Demux menu with language 1 from VTS 1, PGC 1, starting at PG 1: +
    +
    ffmpeg -f dvdvideo -menu 1 -menu_lu 1 -menu_vts 1 -pgc 1 -pg 1 -i <path to DVD> ...
    +
    +
+ + +

13.8 ea

+ +

Electronic Arts Multimedia format demuxer. +

+

This format is used by various Electronic Arts games. +

+ +

13.8.1 Options

+ +
+
merge_alpha bool
+
+

Normally the VP6 alpha channel (if exists) is returned as a secondary video +stream, by setting this option you can make the demuxer return a single video +stream which contains the alpha channel in addition to the ordinary video. +

+
+
+ + +

13.9 imf

+ +

Interoperable Master Format demuxer. +

+

This demuxer presents audio and video streams found in an IMF Composition, as +specified in SMPTE ST 2067-2. +

+
+
ffmpeg [-assetmaps <path of ASSETMAP1>,<path of ASSETMAP2>,...] -i <path of CPL> ...
+
+ +

If -assetmaps is not specified, the demuxer looks for a file called +ASSETMAP.xml in the same directory as the CPL. +

+ +

13.10 flv, live_flv, kux

+ +

Adobe Flash Video Format demuxer. +

+

This demuxer is used to demux FLV files and RTMP network streams. In case of live network streams, if you force format, you may use live_flv option instead of flv to survive timestamp discontinuities. +KUX is a flv variant used on the Youku platform. +

+
+
ffmpeg -f flv -i myfile.flv ...
+ffmpeg -f live_flv -i rtmp://<any.server>/anything/key ....
+
+ + +
+
-flv_metadata bool
+

Allocate the streams according to the onMetaData array content. +

+
+
-flv_ignore_prevtag bool
+

Ignore the size of previous tag value. +

+
+
-flv_full_metadata bool
+

Output all context of the onMetadata. +

+
+ + +

13.11 gif

+ +

Animated GIF demuxer. +

+

It accepts the following options: +

+
+
min_delay
+

Set the minimum valid delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 2. +

+
+
max_gif_delay
+

Set the maximum valid delay between frames in hundredth of seconds. +Range is 0 to 65535. Default value is 65535 (nearly eleven minutes), +the maximum value allowed by the specification. +

+
+
default_delay
+

Set the default delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 10. +

+
+
ignore_loop
+

GIF files can contain information to loop a certain number of times (or +infinitely). If ignore_loop is set to 1, then the loop setting +from the input will be ignored and looping will not occur. If set to 0, +then looping will occur and will cycle the number of times according to +the GIF. Default value is 1. +

+
+ +

For example, with the overlay filter, place an infinitely looping GIF +over another video: +

+
ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv
+
+ +

Note that in the above example the shortest option for overlay filter is +used to end the output video at the length of the shortest input file, +which in this case is input.mp4 as the GIF in this example loops +infinitely. +

+ +

13.12 hls

+ +

HLS demuxer +

+

Apple HTTP Live Streaming demuxer. +

+

This demuxer presents all AVStreams from all variant streams. +The id field is set to the bitrate variant index number. By setting +the discard flags on AVStreams (by pressing ’a’ or ’v’ in ffplay), +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". +

+

It accepts the following options: +

+
+
live_start_index
+

segment index to start live streams at (negative values are from the end). +

+
+
prefer_x_start
+

prefer to use #EXT-X-START if it’s in playlist instead of live_start_index. +

+
+
allowed_extensions
+

’,’ separated list of file extensions that hls is allowed to access. +

+
+
extension_picky
+

This blocks disallowed extensions from probing +It also requires all available segments to have matching extensions to the format +except mpegts, which is always allowed. +It is recommended to set the whitelists correctly instead of depending on extensions +Enabled by default. +

+
+
max_reload
+

Maximum number of times a insufficient list is attempted to be reloaded. +Default value is 1000. +

+
+
m3u8_hold_counters
+

The maximum number of times to load m3u8 when it refreshes without new segments. +Default value is 1000. +

+
+
http_persistent
+

Use persistent HTTP connections. Applicable only for HTTP streams. +Enabled by default. +

+
+
http_multiple
+

Use multiple HTTP connections for downloading HTTP segments. +Enabled by default for HTTP/1.1 servers. +

+
+
http_seekable
+

Use HTTP partial requests for downloading HTTP segments. +0 = disable, 1 = enable, -1 = auto, Default is auto. +

+
+
seg_format_options
+

Set options for the demuxer of media segments using a list of key=value pairs separated by :. +

+
+
seg_max_retry
+

Maximum number of times to reload a segment on error, useful when segment skip on network error is not desired. +Default value is 0. +

+
+ + +

13.13 image2

+ +

Image file demuxer. +

+

This demuxer reads from a list of image files specified by a pattern. +The syntax and meaning of the pattern is specified by the +option pattern_type. +

+

The pattern may contain a suffix which is used to automatically +determine the format of the images contained in the files. +

+

The size, the pixel format, and the format of each image must be the +same for all the files in the sequence. +

+

This demuxer accepts the following options: +

+
framerate
+

Set the frame rate for the video stream. It defaults to 25. +

+
loop
+

If set to 1, loop over the input. Default value is 0. +

+
pattern_type
+

Select the pattern type used to interpret the provided filename. +

+

pattern_type accepts one of the following values. +

+
none
+

Disable pattern matching, therefore the video will only contain the specified +image. You should use this option if you do not want to create sequences from +multiple images and your filenames may contain special pattern characters. +

+
sequence
+

Select a sequence pattern type, used to specify a sequence of files +indexed by sequential numbers. +

+

A sequence pattern may contain the string "%d" or "%0Nd", which +specifies the position of the characters representing a sequential +number in each filename matched by the pattern. If the form +"%d0Nd" is used, the string representing the number in each +filename is 0-padded and N is the total number of 0-padded +digits representing the number. The literal character ’%’ can be +specified in the pattern with the string "%%". +

+

If the sequence pattern contains "%d" or "%0Nd", the first filename of +the file list specified by the pattern must contain a number +inclusively contained between start_number and +start_number+start_number_range-1, and all the following +numbers must be sequential. +

+

For example the pattern "img-%03d.bmp" will match a sequence of +filenames of the form img-001.bmp, img-002.bmp, ..., +img-010.bmp, etc.; the pattern "i%%m%%g-%d.jpg" will match a +sequence of filenames of the form i%m%g-1.jpg, +i%m%g-2.jpg, ..., i%m%g-10.jpg, etc. +

+

Note that the pattern must not necessarily contain "%d" or +"%0Nd", for example to convert a single image file +img.jpeg you can employ the command: +

+
ffmpeg -i img.jpeg img.png
+
+ +
+
glob
+

Select a glob wildcard pattern type. +

+

The pattern is interpreted like a glob() pattern. This is only +selectable if libavformat was compiled with globbing support. +

+
+ +

Default value is sequence. +

+
pixel_format
+

Set the pixel format of the images to read. If not specified the pixel +format is guessed from the first image file in the sequence. +

+
start_number
+

Set the index of the file matched by the image file pattern to start +to read from. Default value is 0. +

+
start_number_range
+

Set the index interval range to check when looking for the first image +file in the sequence, starting from start_number. Default value +is 5. +

+
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. +If set to 2, will set frame timestamp to the modification time of the image file in +nanosecond precision. +

+
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. +

+
export_path_metadata
+

If set to 1, will add two extra fields to the metadata found in input, making them +also available for other filters (see drawtext filter for examples). Default +value is 0. The extra fields are described below: +

+
lavf.image2dec.source_path
+

Corresponds to the full path to the input file being read. +

+
lavf.image2dec.source_basename
+

Corresponds to the name of the file being read. +

+
+ +
+
+ + +

13.13.1 Examples

+ +
    +
  • Use ffmpeg for creating a video from the images in the file +sequence img-001.jpeg, img-002.jpeg, ..., assuming an +input frame rate of 10 frames per second: +
    +
    ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • As above, but start by reading from a file with index 100 in the sequence: +
    +
    ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • Read images matching the "*.png" glob pattern , that is all the files +terminating with the ".png" suffix: +
    +
    ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv
    +
    +
+ + +

13.14 libgme

+ +

The Game Music Emu library is a collection of video game music file emulators. +

+

See https://bitbucket.org/mpyne/game-music-emu/overview for more information. +

+

It accepts the following options: +

+
+
track_index
+

Set the index of which track to demux. The demuxer can only export one track. +Track indexes start at 0. Default is to pick the first track. Number of tracks +is exported as tracks metadata entry. +

+
+
sample_rate
+

Set the sampling rate of the exported track. Range is 1000 to 999999. Default is 44100. +

+
+
max_size (bytes)
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. +Default is 50 MiB. +

+
+
+ + +

13.15 libmodplug

+ +

ModPlug based module demuxer +

+

See https://github.com/Konstanty/libmodplug +

+

It will export one 2-channel 16-bit 44.1 kHz audio stream. +Optionally, a pal8 16-color video stream can be exported with or without printed metadata. +

+

It accepts the following options: +

+
+
noise_reduction
+

Apply a simple low-pass filter. Can be 1 (on) or 0 (off). Default is 0. +

+
+
reverb_depth
+

Set amount of reverb. Range 0-100. Default is 0. +

+
+
reverb_delay
+

Set delay in ms, clamped to 40-250 ms. Default is 0. +

+
+
bass_amount
+

Apply bass expansion a.k.a. XBass or megabass. Range is 0 (quiet) to 100 (loud). Default is 0. +

+
+
bass_range
+

Set cutoff i.e. upper-bound for bass frequencies. Range is 10-100 Hz. Default is 0. +

+
+
surround_depth
+

Apply a Dolby Pro-Logic surround effect. Range is 0 (quiet) to 100 (heavy). Default is 0. +

+
+
surround_delay
+

Set surround delay in ms, clamped to 5-40 ms. Default is 0. +

+
+
max_size
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. Range is 0 to 100 MiB. +0 removes buffer size limit (not recommended). Default is 5 MiB. +

+
+
video_stream_expr
+

String which is evaluated using the eval API to assign colors to the generated video stream. +Variables which can be used are x, y, w, h, t, speed, +tempo, order, pattern and row. +

+
+
video_stream
+

Generate video stream. Can be 1 (on) or 0 (off). Default is 0. +

+
+
video_stream_w
+

Set video frame width in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_h
+

Set video frame height in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_ptxt
+

Print metadata on video stream. Includes speed, tempo, order, pattern, +row and ts (time in ms). Can be 1 (on) or 0 (off). Default is 1. +

+
+
+ + +

13.16 libopenmpt

+ +

libopenmpt based module demuxer +

+

See https://lib.openmpt.org/libopenmpt/ for more information. +

+

Some files have multiple subsongs (tracks) this can be set with the subsong +option. +

+

It accepts the following options: +

+
+
subsong
+

Set the subsong index. This can be either ’all’, ’auto’, or the index of the +subsong. Subsong indexes start at 0. The default is ’auto’. +

+

The default value is to let libopenmpt choose. +

+
+
layout
+

Set the channel layout. Valid values are 1, 2, and 4 channel layouts. +The default value is STEREO. +

+
+
sample_rate
+

Set the sample rate for libopenmpt to output. +Range is from 1000 to INT_MAX. The value default is 48000. +

+
+ + +

13.17 mcc

+ +

Demuxer for MacCaption MCC files, it supports MCC versions 1.0 and 2.0. +MCC files store VANC data, which can include closed captions (EIA-608 and CEA-708), ancillary time code, pan-scan data, etc. +By default, for backward compatibility, the MCC demuxer extracts just the EIA-608 and CEA-708 closed captions and returns a EIA_608 stream, ignoring all other VANC data. +You can change it to return all VANC data in a SMPTE_436M_ANC data stream by setting -eia608_extract 0 +

+ +

13.17.1 Examples

+ +
    +
  • Convert a MCC file to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.mcc -c:s copy CC.scc
    +
    +

    Note that the SCC format only supports EIA-608, so this will discard all other data such as CEA-708 extensions. +

    +
  • Merge a MCC file into a MXF file: +
    +
    ffmpeg -i video_and_audio.mxf -eia608_extract 0 -i CC.mcc -c copy -map 0 -map 1 out.mxf
    +
    +

    This retains all VANC data and inserts it into the output MXF file as a SMPTE_436M_ANC data stream. +

+ + +

13.18 mov/mp4/3gp

+ +

Demuxer for Quicktime File Format & ISO/IEC Base Media File Format (ISO/IEC 14496-12 or MPEG-4 Part 12, ISO/IEC 15444-12 or JPEG 2000 Part 12). +

+

Registered extensions: mov, mp4, m4a, 3gp, 3g2, mj2, psp, m4b, ism, ismv, isma, f4v +

+ +

13.18.1 Options

+ +

This demuxer accepts the following options: +

+
enable_drefs
+

Enable loading of external tracks, disabled by default. +Enabling this can theoretically leak information in some use cases. +

+
+
use_absolute_path
+

Allows loading of external tracks via absolute paths, disabled by default. +Enabling this poses a security risk. It should only be enabled if the source +is known to be non-malicious. +

+
+
seek_streams_individually
+

When seeking, identify the closest point in each stream individually and demux packets in +that stream from identified point. This can lead to a different sequence of packets compared +to demuxing linearly from the beginning. Default is true. +

+
+
ignore_editlist
+

Ignore any edit list atoms. The demuxer, by default, modifies the stream index to reflect the +timeline described by the edit list. Default is false. +

+
+
advanced_editlist
+

Modify the stream index to reflect the timeline described by the edit list. ignore_editlist +must be set to false for this option to be effective. +If both ignore_editlist and this option are set to false, then only the +start of the stream index is modified to reflect initial dwell time or starting timestamp +described by the edit list. Default is true. +

+
+
ignore_chapters
+

Don’t parse chapters. This includes GoPro ’HiLight’ tags/moments. Note that chapters are +only parsed when input is seekable. Default is false. +

+
+
use_mfra_for
+

For seekable fragmented input, set fragment’s starting timestamp from media fragment random access box, if present. +

+

Following options are available: +

+
‘auto’
+

Auto-detect whether to set mfra timestamps as PTS or DTS (default) +

+
+
‘dts’
+

Set mfra timestamps as DTS +

+
+
‘pts’
+

Set mfra timestamps as PTS +

+
+
‘0’
+

Don’t use mfra box to set timestamps +

+
+ +
+
use_tfdt
+

For fragmented input, set fragment’s starting timestamp to baseMediaDecodeTime from the tfdt box. +Default is enabled, which will prefer to use the tfdt box to set DTS. Disable to use the earliest_presentation_time from the sidx box. +In either case, the timestamp from the mfra box will be used if it’s available and use_mfra_for is +set to pts or dts. +

+
+
export_all
+

Export unrecognized boxes within the udta box as metadata entries. The first four +characters of the box type are set as the key. Default is false. +

+
+
export_xmp
+

Export entire contents of XMP_ box and uuid box as a string with key xmp. Note that +if export_all is set and this option isn’t, the contents of XMP_ box are still exported +but with key XMP_. Default is false. +

+
+
activation_bytes
+

4-byte key required to decrypt Audible AAX and AAX+ files. See Audible AAX subsection below. +

+
+
audible_fixed_key
+

Fixed key used for handling Audible AAX/AAX+ files. It has been pre-set so should not be necessary to +specify. +

+
+
decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
max_stts_delta
+

Very high sample deltas written in a trak’s stts box may occasionally be intended but usually they are written in +error or used to store a negative value for dts correction when treated as signed 32-bit integers. This option lets +the user set an upper limit, beyond which the delta is clamped to 1. Values greater than the limit if negative when +cast to int32 are used to adjust onward dts. +

+

Unit is the track time scale. Range is 0 to UINT_MAX. Default is UINT_MAX - 48000*10 which allows up to +a 10 second dts correction for 48 kHz audio streams while accommodating 99.9% of uint32 range. +

+
+
interleaved_read
+

Interleave packets from multiple tracks at demuxer level. For badly interleaved files, this prevents playback issues +caused by large gaps between packets in different tracks, as MOV/MP4 do not have packet placement requirements. +However, this can cause excessive seeking on very badly interleaved files, due to seeking between tracks, so disabling +it may prevent I/O issues, at the expense of playback. +

+
+
+ + +

13.18.2 Audible AAX

+ +

Audible AAX files are encrypted M4B files, and they can be decrypted by specifying a 4 byte activation secret. +

+
ffmpeg -activation_bytes 1CEB00DA -i test.aax -vn -c:a copy output.mp4
+
+ + +

13.19 mpegts

+ +

MPEG-2 transport stream demuxer. +

+

This demuxer accepts the following options: +

+
resync_size
+

Set size limit for looking up a new synchronization. Default value is +65536. +

+
+
skip_unknown_pmt
+

Skip PMTs for programs not defined in the PAT. Default value is 0. +

+
+
fix_teletext_pts
+

Override 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. +

+
+
ts_packetsize
+

Output option carrying the raw packet size in bytes. +Show the detected raw packet size, cannot be set by the user. +

+
+
scan_all_pmts
+

Scan and combine all PMTs. The value is an integer with value from -1 +to 1 (-1 means automatic setting, 1 means enabled, 0 means +disabled). Default value is -1. +

+
+
merge_pmt_versions
+

Reuse existing streams when a PMT’s version is updated and elementary +streams move to different PIDs. Default value is 0. +

+
+
max_packet_size
+

Set maximum size, in bytes, of packet emitted by the demuxer. Payloads above this size +are split across multiple packets. Range is 1 to INT_MAX/2. Default is 204800 bytes. +

+
+ + +

13.20 mpjpeg

+ +

MJPEG encapsulated in multi-part MIME demuxer. +

+

This demuxer allows reading of MJPEG, where each frame is represented as a part of +multipart/x-mixed-replace stream. +

+
strict_mime_boundary
+

Default implementation applies a relaxed standard to multi-part MIME boundary detection, +to prevent regression with numerous existing endpoints not generating a proper MIME +MJPEG stream. Turning this option on by setting it to 1 will result in a stricter check +of the boundary value. +

+
+ + +

13.21 rawvideo

+ +

Raw video demuxer. +

+

This demuxer allows one to read raw video data. Since there is no header +specifying the assumed video parameters, the user must specify them +in order to be able to decode the data correctly. +

+

This demuxer accepts the following options: +

+
framerate
+

Set input video frame rate. Default value is 25. +

+
+
pixel_format
+

Set the input video pixel format. Default value is yuv420p. +

+
+
stride
+

Set frame line size in bytes, only required if there are extra padding. +For multiplane formats, stride is a list of line size for each +plane. +

+
+
video_size
+

Set the input video size. This value must be specified explicitly. +

+
+ +

For example to read a rawvideo file input.raw with +ffplay, assuming a pixel format of rgb24, a video +size of 320x240, and a frame rate of 10 images per second, use +the command: +

+
ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw
+
+ +

Read a rawvideo with ffplay, assuming a pixel format of yuv420p, +a video size of 1080x1920, has 8 bytes of padding in each line of Y plane, +and 4 bytes of padding with UV plane, +

+
ffplay -f rawvideo -pixel_format yuv420p -video_size 1080x1920 -stride 1088,544,544 input.raw
+
+ + +

13.22 rcwt

+ +

RCWT (Raw Captions With Time) is a format native to ccextractor, a commonly +used open source tool for processing 608/708 Closed Captions (CC) sources. +For more information on the format, see (ffmpeg-formats)rcwtenc. +

+

This demuxer implements the specification as of March 2024, which has +been stable and unchanged since April 2014. +

+ +

13.22.1 Examples

+ +
    +
  • Render CC to ASS using the built-in decoder: +
    +
    ffmpeg -i CC.rcwt.bin CC.ass
    +
    +

    Note that if your output appears to be empty, you may have to manually +set the decoder’s data_field option to pick the desired CC substream. +

    +
  • Convert an RCWT backup to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.rcwt.bin -c:s copy CC.scc
    +
    +

    Note that the SCC format does not support all of the possible CC extensions +that can be stored in RCWT (such as EIA-708). +

+ + +

13.23 sbg

+ +

SBaGen script demuxer. +

+

This demuxer reads the script language used by SBaGen +http://uazu.net/sbagen/ to generate binaural beats sessions. A SBG +script looks like that: +

+
-SE
+a: 300-2.5/3 440+4.5/0
+b: 300-2.5/0 440+4.5/3
+off: -
+NOW      == a
++0:07:00 == b
++0:14:00 == a
++0:21:00 == b
++0:30:00    off
+
+ +

A SBG script can mix absolute and relative timestamps. If the script uses +either only absolute timestamps (including the script start time) or only +relative ones, then its layout is fixed, and the conversion is +straightforward. On the other hand, if the script mixes both kind of +timestamps, then the NOW reference for relative timestamps will be +taken from the current time of day at the time the script is read, and the +script layout will be frozen according to that reference. That means that if +the script is directly played, the actual times will match the absolute +timestamps up to the sound controller’s clock accuracy, but if the user +somehow pauses the playback or seeks, all times will be shifted accordingly. +

+ +

13.24 tedcaptions

+ +

JSON captions used for TED Talks. +

+

TED does not provide links to the captions, but they can be guessed from the +page. The file tools/bookmarklets.html from the FFmpeg source tree +contains a bookmarklet to expose them. +

+

This demuxer accepts the following option: +

+
start_time
+

Set the start time of the TED talk, in milliseconds. The default is 15000 +(15s). It is used to sync the captions with the downloadable videos, because +they include a 15s intro. +

+
+ +

Example: convert the captions to a format most players understand: +

+
ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt
+
+ + +

13.25 vapoursynth

+ +

Vapoursynth wrapper. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+

This demuxer accepts the following option: +

+
max_script_size
+

The demuxer buffers the entire script into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of scripts that can be read. +Default is 1 MiB. +

+
+ + +

13.26 w64

+ +

Sony Wave64 Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

See the same option for the wav demuxer. +

+
+ + +

13.27 wav

+ +

RIFF Wave Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

Specify the maximum packet size in bytes for the demuxed packets. By default +this is set to 0, which means that a sensible value is chosen based on the +input format. +

+
+ + +

14 Metadata

+ +

FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded +INI-like text file and then load it back using the metadata muxer/demuxer. +

+

The file format is as follows: +

    +
  1. A file consists of a header and a number of metadata tags divided into sections, +each on its own line. + +
  2. The header is a ‘;FFMETADATA’ string, followed by a version number (now 1). + +
  3. Metadata tags are of the form ‘key=value’ + +
  4. Immediately after header follows global metadata + +
  5. After global metadata there may be sections with per-stream/per-chapter +metadata. + +
  6. A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in +brackets (‘[’, ‘]’) and ends with next section or end of file. + +
  7. At the beginning of a chapter section there may be an optional timebase to be +used for start/end values. It must be in form +‘TIMEBASE=num/den’, where num and den are +integers. If the timebase is missing then start/end times are assumed to +be in nanoseconds. + +

    Next a chapter section must contain chapter start and end times in form +‘START=num’, ‘END=num’, where num is a positive +integer. +

    +
  8. Empty lines and lines starting with ‘;’ or ‘#’ are ignored. + +
  9. Metadata keys or values containing special characters (‘=’, ‘;’, +‘#’, ‘\’ and a newline) must be escaped with a backslash ‘\’. + +
  10. Note that whitespace in metadata (e.g. ‘foo = bar’) is considered to be +a part of the tag (in the example above key is ‘foo ’, value is +‘ bar’). +
+ +

A ffmetadata file might look like this: +

+
;FFMETADATA1
+title=bike\\shed
+;this is a comment
+artist=FFmpeg troll team
+
+[CHAPTER]
+TIMEBASE=1/1000
+START=0
+#chapter ends at 0:01:00
+END=60000
+title=chapter \#1
+[STREAM]
+title=multi\
+line
+
+ +

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 ffmpeg goes as follows: +

+
ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
+
+ +

Reinserting edited metadata information from the FFMETADATAFILE file can +be done as: +

+
ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
+
+ + +

15 Protocol Options

+ +

The libavformat library provides some generic global options, which +can be set on all the protocols. In addition each protocol may support +so-called private options, which are specific for that component. +

+

Options may be set by specifying -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
protocol_whitelist list (input)
+

Set a ","-separated list of allowed protocols. "ALL" matches all protocols. Protocols +prefixed by "-" are disabled. +All protocols are allowed by default but protocols used by an another +protocol (nested protocols) are restricted to a per protocol subset. +

+
+ + + +

16 Protocols

+ +

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 +configure option "–list-protocols". +

+

You can disable all the protocols using the configure option +"–disable-protocols", and selectively enable a protocol using the +option "–enable-protocol=PROTOCOL", or you can disable a +particular protocol using the option +"–disable-protocol=PROTOCOL". +

+

The option "-protocols" of the ff* tools will display the list of +supported protocols. +

+

All protocols accept the following options: +

+
+
rw_timeout
+

Maximum time to wait for (network) read/write operations to complete, +in microseconds. +

+
+ +

A description of the currently available protocols follows. +

+ +

16.1 amqp

+ +

Advanced Message Queueing Protocol (AMQP) version 0-9-1 is a broker based +publish-subscribe communication protocol. +

+

FFmpeg must be compiled with –enable-librabbitmq to support AMQP. A separate +AMQP broker must also be run. An example open-source AMQP broker is RabbitMQ. +

+

After starting the broker, an FFmpeg client may stream data to the broker using +the command: +

+
+
ffmpeg -re -i input -f mpegts amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

Where hostname and port (default is 5672) is the address of the broker. The +client may also set a user/password for authentication. The default for both +fields is "guest". Name of virtual host on broker can be set with vhost. The +default value is "/". +

+

Multiple subscribers may stream from the broker using the command: +

+
ffplay amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

In RabbitMQ all data published to the broker flows through a specific exchange, +and each subscribing client has an assigned queue/buffer. When a packet arrives +at an exchange, it may be copied to a client’s queue depending on the exchange +and routing_key fields. +

+

The following options are supported: +

+
+
exchange
+

Sets the exchange to use on the broker. RabbitMQ has several predefined +exchanges: "amq.direct" is the default exchange, where the publisher and +subscriber must have a matching routing_key; "amq.fanout" is the same as a +broadcast operation (i.e. the data is forwarded to all queues on the fanout +exchange independent of the routing_key); and "amq.topic" is similar to +"amq.direct", but allows for more complex pattern matching (refer to the RabbitMQ +documentation). +

+
+
routing_key
+

Sets the routing key. The default value is "amqp". The routing key is used on +the "amq.direct" and "amq.topic" exchanges to decide whether packets are written +to the queue of a subscriber. +

+
+
pkt_size
+

Maximum size of each packet sent/received to the broker. Default is 131072. +Minimum is 4096 and max is any large value (representable by an int). When +receiving packets, this sets an internal buffer size in FFmpeg. It should be +equal to or greater than the size of the published packets to the broker. Otherwise +the received message may be truncated causing decoding errors. +

+
+
connection_timeout
+

The timeout in seconds during the initial connection to the broker. The +default value is rw_timeout, or 5 seconds if rw_timeout is not set. +

+
+
delivery_mode mode
+

Sets the delivery mode of each message sent to broker. +The following values are accepted: +

+
‘persistent’
+

Delivery mode set to "persistent" (2). This is the default value. +Messages may be written to the broker’s disk depending on its setup. +

+
+
‘non-persistent’
+

Delivery mode set to "non-persistent" (1). +Messages will stay in broker’s memory unless the broker is under memory +pressure. +

+
+
+ +
+
+ + +

16.2 async

+ +

Asynchronous data filling wrapper for input stream. +

+

Fill data in a background thread, to decouple I/O operation from demux thread. +

+
+
async:URL
+async:http://host/resource
+async:cache:http://host/resource
+
+ + +

16.3 bluray

+ +

Read BluRay playlist. +

+

The accepted options are: +

+
angle
+

BluRay angle +

+
+
chapter
+

Start chapter (1...N) +

+
+
playlist
+

Playlist to read (BDMV/PLAYLIST/?????.mpls) +

+
+
+ +

Examples: +

+

Read longest playlist from BluRay mounted to /mnt/bluray: +

+
bluray:/mnt/bluray
+
+ +

Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: +

+
-playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
+
+ + +

16.4 cache

+ +

Caching wrapper for input stream. +

+

Cache the input stream to temporary file. It brings seeking capability to live streams. +

+

The accepted options are: +

+
read_ahead_limit
+

Amount in bytes that may be read ahead when seeking isn’t supported. Range is -1 to INT_MAX. +-1 for unlimited. Default is 65536. +

+
+
+ +

URL Syntax is +

+
cache:URL
+
+ + +

16.5 concat

+ +

Physical concatenation protocol. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concat:URL1|URL2|...|URLN
+
+ +

where URL1, URL2, ..., URLN are the urls of the +resource to be concatenated, each one possibly specifying a distinct +protocol. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg with ffplay use the +command: +

+
ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+
+ +

Note that you may need to escape the character "|" which is special for +many shells. +

+ +

16.6 concatf

+ +

Physical concatenation protocol using a line break delimited list of +resources. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concatf:URL
+
+ +

where URL is the url containing a line break delimited list of +resources to be concatenated, each one possibly specifying a distinct +protocol. Special characters must be escaped with backslash or single +quotes. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg listed in separate lines within +a file split.txt with ffplay use the command: +

+
ffplay concatf:split.txt
+
+

Where split.txt contains the lines: +

+
split1.mpeg
+split2.mpeg
+split3.mpeg
+
+ + +

16.7 crypto

+ +

AES-encrypted stream reading protocol. +

+

The accepted options are: +

+
key
+

Set the AES decryption key binary block from given hexadecimal representation. +

+
+
iv
+

Set the AES decryption initialization vector binary block from given hexadecimal representation. +

+
+ +

Accepted URL formats: +

+
crypto:URL
+crypto+URL
+
+ + +

16.8 data

+ +

Data in-line in the URI. See http://en.wikipedia.org/wiki/Data_URI_scheme. +

+

For example, to convert a GIF file given inline with ffmpeg: +

+
ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
+
+ + +

16.9 fd

+ +

File descriptor access protocol. +

+

The accepted syntax is: +

+
fd: -fd file_descriptor
+
+ +

If fd is not specified, by default the stdout file descriptor will be +used for writing, stdin for reading. Unlike the pipe protocol, fd protocol has +seek support if it corresponding to a regular file. fd protocol doesn’t support +pass file descriptor via URL for security. +

+

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
fd
+

Set file descriptor. +

+
+ + +

16.10 file

+ +

File access protocol. +

+

Read from or write to a file. +

+

A file URL can have the form: +

+
file:filename
+
+ +

where filename is the path of the file to read. +

+

An URL that does not have a protocol prefix will be assumed to be a +file URL. Depending on the build, an URL that looks like a Windows +path with the drive letter at the beginning will also be assumed to be +a file URL (usually not the case in builds for unix-like systems). +

+

For example to read from a file input.mpeg with ffmpeg +use the command: +

+
ffmpeg -i file:input.mpeg output.mpeg
+
+ +

This protocol accepts the following options: +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
follow
+

If set to 1, the protocol will retry reading at the end of the file, allowing +reading files that still are being written. In order for this to terminate, +you either need to use the rw_timeout option, or use the interrupt callback +(for API users). +

+
+
seekable
+

Controls if seekability is advertised on the file. 0 means non-seekable, -1 +means auto (seekable for normal files, non-seekable for named pipes). +

+

Many demuxers handle seekable and non-seekable resources differently, +overriding this might speed up opening certain files at the cost of losing some +features (e.g. accurate seeking). +

+
+
pkt_size
+

Set the maximum packet size used for file I/O. A smaller value may reduce +memory usage. A higher value may increase throughput especially with networked +filesystems. +

+

For reading, if explicitly set, it overrides the default internal buffer size +(32 KB) and limits the maximum amount of data read per operation. +

+

For writing, this sets the size of each write operation. The default is 256 KB +for regular files, 32 KB otherwise. +

+
+ + +

16.11 ftp

+ +

FTP (File Transfer Protocol). +

+

Read from or write to remote resources using FTP protocol. +

+

Following syntax is required. +

+
ftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in microseconds 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. +

+
+
ftp-user
+

Set a user to be used for authenticating to the FTP server. This is overridden by the +user in the FTP URL. +

+
+
ftp-password
+

Set a password to be used for authenticating to the FTP server. This is overridden by +the password in the FTP URL, or by ftp-anonymous-password if no user is set. +

+
+
ftp-anonymous-password
+

Password used when login as anonymous user. Typically an e-mail address +should be used. +

+
+
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. +

+
+ +

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. +

+ +

16.12 gopher

+ +

Gopher protocol. +

+ +

16.13 gophers

+ +

Gophers protocol. +

+

The Gopher protocol with TLS encapsulation. +

+ +

16.14 http

+ +

HTTP (Hyper Text Transfer Protocol). +

+

This protocol accepts the following options: +

+
+
seekable
+

Control seekability of connection. If set to 1 the resource is +supposed to be seekable, if set to 0 it is assumed not to be seekable, +if set to -1 it will try to autodetect if it is seekable. Default +value is -1. +

+
+
chunked_post
+

If set to 1 use chunked Transfer-Encoding for posts, default is 1. +

+
+
http_proxy
+

set HTTP proxy to tunnel through e.g. http://example.com:1234 +

+
+
headers
+

Set custom HTTP headers, can override built in default headers. The +value must be a string encoding the headers. +

+
+
content_type
+

Set a specific content type for the POST messages or for listen mode. +

+
+
user_agent
+

Override the User-Agent header. If not specified the protocol will use a +string describing the libavformat build. ("Lavf/<version>") +

+
+
referer
+

Set the Referer header. Include ’Referer: URL’ header in HTTP request. +

+
+
multiple_requests
+

Use persistent connections if set to 1, default is 0. +

+
+
request_size
+

Limit the size of requests made. This is useful for some pathological servers +that throttle unbounded range requests, as well as when expecting to seek +frequently. Disabled (set to 0) by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. Doing so allows FFmpeg +to reuse a single HTTP connection wherever possible. +

+
+
initial_request_size
+

Limit the size of initial requests. Similar to request_size, but only +used during initial format parsing. Useful for formats like MXF or MOV that +require frequent seeks during header parsing. Lasts until the demuxer makes a +read request larger than this size (without a seek in between), after which +the implementation will continue using requests as usual. Disabled (set to 0) +by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. +

+
+
post_data
+

Set custom HTTP post data. +

+
+
mime_type
+

Export the MIME type. +

+
+
http_version
+

Exports the HTTP response version number. Usually "1.0" or "1.1". +

+
+
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 +delimited by a newline character. +

+
+
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 icy_metadata_headers and icy_metadata_packet options. +The default is 1. +

+
+
icy_metadata_headers
+

If the server supports ICY metadata, this contains the ICY-specific HTTP reply +headers, separated by newline characters. +

+
+
icy_metadata_packet
+

If the server supports ICY metadata, and icy was set to 1, this +contains the last non-empty metadata packet sent by the server. It should be +polled in regular intervals by applications interested in mid-stream metadata +updates. +

+
+
metadata
+

Set an exported dictionary containing Icecast metadata from the bitstream, if present. +Only useful with the C API. +

+
+
auth_type
+
+

Set HTTP authentication type. No option for Digest, since this method requires +getting nonce parameters from the server first and can’t be used straight away like +Basic. +

+
+
none
+

Choose the HTTP authentication type automatically. This is the default. +

+
basic
+
+

Choose the HTTP basic authentication. +

+

Basic authentication sends a Base64-encoded string that contains a user name and password +for the client. Base64 is not a form of encryption and should be considered the same as +sending the user name and password in clear text (Base64 is a reversible encoding). +If a resource needs to be protected, strongly consider using an authentication scheme +other than basic authentication. HTTPS/TLS should be used with basic authentication. +Without these additional security enhancements, basic authentication should not be used +to protect sensitive or valuable information. +

+
+ +
+
send_expect_100
+

Send an Expect: 100-continue header for POST. If set to 1 it will send, if set +to 0 it won’t, if set to -1 it will try to send if it is applicable. Default +value is -1. +

+
+
location
+

An exported dictionary containing the content location. Only useful with the C +API. +

+
+
offset
+

Set initial byte offset. +

+
+
end_offset
+

Try to limit the request to bytes preceding this offset. +

+
+
method
+

When used as a client option it sets the HTTP method for the request. +

+

When used as a server option it sets the HTTP method that is going to be +expected from the client(s). +If the expected and the received HTTP method do not match the client will +be given a Bad Request response. +When unset the HTTP method is not checked for now. This will be replaced by +autodetection in the future. +

+
+
reconnect
+

Reconnect automatically when disconnected before EOF is hit. +

+
+
reconnect_at_eof
+

If set then eof is treated like an error and causes reconnection, this is useful +for live / endless streams. +

+
+
reconnect_on_network_error
+

Reconnect automatically in case of TCP/TLS errors during connect. +

+
+
reconnect_on_http_error
+

A comma separated list of HTTP status codes to reconnect on. The list can +include specific status codes (e.g. ’503’) or the strings ’4xx’ / ’5xx’. +

+
+
reconnect_streamed
+

If set then even streamed/non seekable streams will be reconnected on errors. +

+
+
reconnect_delay_max
+

Set the maximum delay in seconds after which to give up reconnecting. +

+
+
reconnect_max_retries
+

Set the maximum number of times to retry a connection. Default unset. +

+
+
reconnect_delay_total_max
+

Set the maximum total delay in seconds after which to give up reconnecting. +

+
+
respect_retry_after
+

If enabled, and a Retry-After header is encountered, its requested reconnection +delay will be honored, rather than using exponential backoff. Useful for 429 and +503 errors. Default enabled. +

+
+
listen
+

If set to 1 enables experimental HTTP server. This can be used to send data when +used as an output option, or read data from a client with HTTP POST when used as +an input option. +If set to 2 enables experimental multi-client HTTP server. This is not yet implemented +in ffmpeg.c and thus must not be used as a command line option. +

+
# Server side (sending):
+ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://server:port
+
+# Client side (receiving):
+ffmpeg -i http://server:port -c copy somefile.ogg
+
+# Client can also be done with wget:
+wget http://server:port -O somefile.ogg
+
+# Server side (receiving):
+ffmpeg -listen 1 -i http://server:port -c copy somefile.ogg
+
+# Client side (sending):
+ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://server:port
+
+# Client can also be done with wget:
+wget --post-file=somefile.ogg http://server:port
+
+ +
+
resource
+

The resource requested by a client, when the experimental HTTP server is in use. +

+
+
reply_code
+

The HTTP code returned to the client, when the experimental HTTP server is in use. +

+
+
short_seek_size
+

Set the threshold, in bytes, for when a readahead should be preferred over a seek and +new HTTP request. This is useful, for example, to make sure the same connection +is used for reading large video packets with small audio packets in between. +

+
+
+ + +

16.14.1 HTTP Cookies

+ +

Some HTTP requests will be denied unless cookie values are passed in with the +request. The cookies option allows these cookies to be specified. At +the very least, each cookie must specify a value along with a path and domain. +HTTP requests that match both the domain and path will automatically include the +cookie value in the HTTP Cookie header field. Multiple cookies can be delimited +by a newline. +

+

The required syntax to play a stream specifying a cookie is: +

+
ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
+
+ + +

16.15 Icecast

+ +

Icecast protocol (stream to Icecast servers) +

+

This protocol accepts the following options: +

+
+
ice_genre
+

Set the stream genre. +

+
+
ice_name
+

Set the stream name. +

+
+
ice_description
+

Set the stream description. +

+
+
ice_url
+

Set the stream website URL. +

+
+
ice_public
+

Set if the stream should be public. +The default is 0 (not public). +

+
+
user_agent
+

Override the User-Agent header. If not specified a string of the form +"Lavf/<version>" will be used. +

+
+
password
+

Set the Icecast mountpoint password. +

+
+
content_type
+

Set the stream content type. This must be set if it is different from +audio/mpeg. +

+
+
legacy_icecast
+

This enables support for Icecast versions < 2.4.0, that do not support the +HTTP PUT method but the SOURCE method. +

+
+
tls
+

Establish a TLS (HTTPS) connection to Icecast. +

+
+
+ +
+
icecast://[username[:password]@]server:port/mountpoint
+
+ + +

16.16 ipfs

+ +

InterPlanetary File System (IPFS) protocol support. One can access files stored +on the IPFS network through so-called gateways. These are http(s) endpoints. +This protocol wraps the IPFS native protocols (ipfs:// and ipns://) to be sent +to such a gateway. Users can (and should) host their own node which means this +protocol will use one’s local gateway to access files on the IPFS network. +

+

This protocol accepts the following options: +

+
+
gateway
+

Defines the gateway to use. When not set, the protocol will first try +locating the local gateway by looking at $IPFS_GATEWAY, $IPFS_PATH +and $HOME/.ipfs/, in that order. +

+
+
+ +

One can use this protocol in 2 ways. Using IPFS: +

+
ffplay ipfs://<hash>
+
+ +

Or the IPNS protocol (IPNS is mutable IPFS): +

+
ffplay ipns://<hash>
+
+ + +

16.17 mmst

+ +

MMS (Microsoft Media Server) protocol over TCP. +

+ +

16.18 mmsh

+ +

MMS (Microsoft Media Server) protocol over HTTP. +

+

The required syntax is: +

+
mmsh://server[:port][/app][/playpath]
+
+ + +

16.19 md5

+ +

MD5 output protocol. +

+

Computes the MD5 hash of the data to be written, and on close writes +this to the designated output or stdout if none is specified. It can +be used to test muxers without writing an actual file. +

+

Some examples follow. +

+
# Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
+ffmpeg -i input.flv -f avi -y md5:output.avi.md5
+
+# Write the MD5 hash of the encoded AVI file to stdout.
+ffmpeg -i input.flv -f avi -y md5:
+
+ +

Note that some formats (typically MOV) require the output protocol to +be seekable, so they will fail with the MD5 output protocol. +

+ +

16.20 pipe

+ +

UNIX pipe access protocol. +

+

Read and write from UNIX pipes. +

+

The accepted syntax is: +

+
pipe:[number]
+
+ +

If fd isn’t specified, number is the number corresponding to the file descriptor of the +pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If number +is not specified, by default the stdout file descriptor will be used +for writing, stdin for reading. +

+

For example to read from stdin with ffmpeg: +

+
cat test.wav | ffmpeg -i pipe:0
+# ...this is the same as...
+cat test.wav | ffmpeg -i pipe:
+
+ +

For writing to stdout with ffmpeg: +

+
ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
+# ...this is the same as...
+ffmpeg -i test.wav -f avi pipe: | cat > test.avi
+
+ +

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
fd
+

Set file descriptor. +

+
+ +

Note that some formats (typically MOV), require the output protocol to +be seekable, so they will fail with the pipe output protocol. +

+ +

16.21 prompeg

+ +

Pro-MPEG Code of Practice #3 Release 2 FEC protocol. +

+

The Pro-MPEG CoP#3 FEC is a 2D parity-check forward error correction mechanism +for MPEG-2 Transport Streams sent over RTP. +

+

This protocol must be used in conjunction with the rtp_mpegts muxer and +the rtp protocol. +

+

The required syntax is: +

+
-f rtp_mpegts -fec prompeg=option=val... rtp://hostname:port
+
+ +

The destination UDP ports are port + 2 for the column FEC stream +and port + 4 for the row FEC stream. +

+

This protocol accepts the following options: +

+
l=n
+

The number of columns (4-20, LxD <= 100) +

+
+
d=n
+

The number of rows (4-20, LxD <= 100) +

+
+
+ +

Example usage: +

+
+
-f rtp_mpegts -fec prompeg=l=8:d=4 rtp://hostname:port
+
+ + +

16.22 rist

+ +

Reliable Internet Streaming Transport protocol +

+

The accepted options are: +

+
rist_profile
+

Supported values: +

+
‘simple’
+
‘main’
+

This one is default. +

+
‘advanced’
+
+ +
+
buffer_size
+

Set internal RIST buffer size in milliseconds for retransmission of data. +Default value is 0 which means the librist default (1 sec). Maximum value is 30 +seconds. +

+
+
fifo_size
+

Size of the librist receiver output fifo in number of packets. This must be a +power of 2. +Defaults to 8192 (vs the librist default of 1024). +

+
+
overrun_nonfatal=1|0
+

Survive in case of librist fifo buffer overrun. Default value is 0. +

+
+
pkt_size
+

Set maximum packet size for sending data. 1316 by default. +

+
+
log_level
+

Set loglevel for RIST logging messages. You only need to set this if you +explicitly want to enable debug level messages or packet loss simulation, +otherwise the regular loglevel is respected. +

+
+
secret
+

Set override of encryption secret, by default is unset. +

+
+
encryption
+

Set encryption type, by default is disabled. +Acceptable values are 128 and 256. +

+
+ + +

16.23 rtmp

+ +

Real-Time Messaging Protocol. +

+

The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia +content across a TCP/IP network. +

+

The required syntax is: +

+
rtmp://[username:password@]server[:port][/app][/instance][/playpath]
+
+ +

The accepted parameters are: +

+
username
+

An optional username (mostly for publishing). +

+
+
password
+

An optional password (mostly for publishing). +

+
+
server
+

The address of the RTMP server. +

+
+
port
+

The number of the TCP port to use (by default is 1935). +

+
+
app
+

It is the name of the application to access. It usually corresponds to +the path where the application is installed on the RTMP server +(e.g. /ondemand/, /flash/live/, etc.). You can override +the value parsed from the URI through the rtmp_app option, too. +

+
+
playpath
+

It is the path or name of the resource to play with reference to the +application specified in app, may be prefixed by "mp4:". You +can override the value parsed from the URI through the rtmp_playpath +option, too. +

+
+
listen
+

Act as a server, listening for an incoming connection. +

+
+
timeout
+

Maximum time to wait for the incoming connection. Implies listen. +

+
+ +

Additionally, the following parameters can be set via command line options +(or in code via AVOptions): +

+
rtmp_app
+

Name of application to connect on the RTMP server. This option +overrides the parameter specified in the URI. +

+
+
rtmp_buffer
+

Set the client buffer time in milliseconds. The default is 3000. +

+
+
rtmp_conn
+

Extra arbitrary AMF connection parameters, parsed from a string, +e.g. like B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0. +Each value is prefixed by a single character denoting the type, +B for Boolean, N for number, S for string, O for object, or Z for null, +followed by a colon. For Booleans the data must be either 0 or 1 for +FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or +1 to end or begin an object, respectively. Data items in subobjects may +be named, by prefixing the type with ’N’ and specifying the name before +the value (i.e. NB:myFlag:1). This option may be used multiple +times to construct arbitrary AMF sequences. +

+
+
rtmp_enhanced_codecs
+

Specify the list of codecs the client advertises to support in an +enhanced RTMP stream. This option should be set to a comma separated +list of fourcc values, like hvc1,av01,vp09 for multiple codecs +or hvc1 for only one codec. The specified list will be presented +in the "fourCcLive" property of the Connect Command Message. +

+
+
rtmp_flashver
+

Version of the Flash plugin used to run the SWF player. The default +is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; +<libavformat version>).) +

+
+
rtmp_flush_interval
+

Number of packets flushed in the same request (RTMPT only). The default +is 10. +

+
+
rtmp_live
+

Specify that the media is a live stream. No resuming or seeking in +live streams is possible. The default value is any, which means the +subscriber first tries to play the live stream specified in the +playpath. If a live stream of that name is not found, it plays the +recorded stream. The other possible values are live and +recorded. +

+
+
rtmp_pageurl
+

URL of the web page in which the media was embedded. By default no +value will be sent. +

+
+
rtmp_playpath
+

Stream identifier to play or to publish. This option overrides the +parameter specified in the URI. +

+
+
rtmp_subscribe
+

Name of live stream to subscribe to. By default no value will be sent. +It is only sent if the option is specified or if rtmp_live +is set to live. +

+
+
rtmp_swfhash
+

SHA256 hash of the decompressed SWF file (32 bytes). +

+
+
rtmp_swfsize
+

Size of the decompressed SWF file, required for SWFVerification. +

+
+
rtmp_swfurl
+

URL of the SWF player for the media. By default no value will be sent. +

+
+
rtmp_swfverify
+

URL to player swf file, compute hash/size automatically. +

+
+
rtmp_tcurl
+

URL of the target stream. Defaults to proto://host[:port]/app. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_keepalive=1|0
+

Enable the TCP keepalive mechanism to detect dead peers and help maintain long-lived idle connections. Default value is 0. +

+

Only the basic keepalive option (SO_KEEPALIVE) can be enabled or disabled. Platform-specific tuning parameters such as TCP_KEEPIDLE, TCP_KEEPINTVL, or TCP_KEEPCNT are not configurable and will use the operating system’s default values. +

+
+
+ +

For example to read with ffplay a multimedia resource named +"sample" from the application "vod" from an RTMP server "myserver": +

+
ffplay rtmp://myserver/vod/sample
+
+ +

To publish to a password protected server, passing the playpath and +app names separately: +

+
ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@myserver/
+
+ + +

16.24 rtmpe

+ +

Encrypted Real-Time Messaging Protocol. +

+

The Encrypted Real-Time Messaging Protocol (RTMPE) is used for +streaming multimedia content within standard cryptographic primitives, +consisting of Diffie-Hellman key exchange and HMACSHA256, generating +a pair of RC4 keys. +

+ +

16.25 rtmps

+ +

Real-Time Messaging Protocol over a secure SSL connection. +

+

The Real-Time Messaging Protocol (RTMPS) is used for streaming +multimedia content across an encrypted connection. +

+ +

16.26 rtmpt

+ +

Real-Time Messaging Protocol tunneled through HTTP. +

+

The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used +for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

16.27 rtmpte

+ +

Encrypted Real-Time Messaging Protocol tunneled through HTTP. +

+

The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) +is used for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

16.28 rtmpts

+ +

Real-Time Messaging Protocol tunneled through HTTPS. +

+

The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used +for streaming multimedia content within HTTPS requests to traverse +firewalls. +

+ +

16.29 libsmbclient

+ +

libsmbclient permits one to manipulate CIFS/SMB network resources. +

+

Following syntax is required. +

+
+
smb://[[domain:]user[:password@]]server[/share[/path[/file]]]
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in milliseconds 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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
workgroup
+

Set the workgroup used for making connections. By default workgroup is not specified. +

+
+
+ +

For more information see: http://www.samba.org/. +

+ +

16.30 libssh

+ +

Secure File Transfer Protocol via libssh +

+

Read from or write to remote resources using SFTP protocol. +

+

Following syntax is required. +

+
+
sftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
private_key
+

Specify the path of the file containing private key to use during authorization. +By default libssh searches for keys in the ~/.ssh/ directory. +

+
+
+ +

Example: Play a file stored on remote server. +

+
+
ffplay sftp://user:password@server_address:22/home/user/resource.mpeg
+
+ + +

16.31 librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte

+ +

Real-Time Messaging Protocol and its variants supported through +librtmp. +

+

Requires the presence of the librtmp headers and library during +configuration. You need to explicitly configure the build with +"–enable-librtmp". If enabled this will replace the native RTMP +protocol. +

+

This protocol provides most client functions and a few server +functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), +encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled +variants of these encrypted types (RTMPTE, RTMPTS). +

+

The required syntax is: +

+
rtmp_proto://server[:port][/app][/playpath] options
+
+ +

where rtmp_proto is one of the strings "rtmp", "rtmpt", "rtmpe", +"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and +server, port, app and playpath have the same +meaning as specified for the RTMP native protocol. +options contains a list of space-separated options of the form +key=val. +

+

See the librtmp manual page (man 3 librtmp) for more information. +

+

For example, to stream a file in real-time to an RTMP server using +ffmpeg: +

+
ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
+
+ +

To play the same stream using ffplay: +

+
ffplay "rtmp://myserver/live/mystream live=1"
+
+ + +

16.32 rtp

+ +

Real-time Transport Protocol. +

+

The required syntax for an RTP URL is: +

+
rtp://hostname[:port][?options]
+
+ +

port specifies the RTP port to use. +

+

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ttl=n
+

Set the TTL (Time-To-Live) value (for multicast only). +

+
+
rtcpport=n
+

Set the remote RTCP port to n. +

+
+
localport, local_rtpport, localrtpport=n
+

Set the local RTP port to n. +

+

Using the localport option name is deprecated and should not be used. +

+
+
local_rtcpport, localrtcpport=n'
+

Set the local RTCP port to n. +

+
+
pkt_size=n
+

Set max packet size (in bytes) to n. +

+
+
buffer_size=size
+

Set the maximum UDP socket buffer size in bytes. +

+
+
connect=0|1
+

Do a connect() on the UDP socket (if set to 1) or not (if set +to 0). +

+
+
sources=ip[,ip]
+

List allowed source IP addresses. +

+
+
block=ip[,ip]
+

List disallowed (blocked) source IP addresses. +

+
+
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). +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
timeout=n
+

Set timeout (in microseconds) of socket I/O operations to n. +

+
+ +

Important notes: +

+
    +
  1. If rtcpport is not set the RTCP port will be set to the RTP +port value plus 1. + +
  2. If localrtpport (the local RTP port) is not set any available +port will be used for the local RTP and RTCP ports. + +
  3. If localrtcpport (the local RTCP port) is not set it will be +set to the local RTP port value plus 1. +
+ + +

16.33 rtsp

+ +

Real-Time Streaming Protocol. +

+

RTSP is not technically a protocol handler in libavformat, it is a demuxer +and muxer. The demuxer supports both normal RTSP (with data transferred +over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with +data transferred over RDT). +

+

The muxer can be used to send a stream using RTSP ANNOUNCE to a server +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock’s +RTSP server). +

+

The required syntax for a RTSP url is: +

+
rtsp://hostname[:port]/path
+
+ +

Options can be set on the ffmpeg/ffplay command +line, or set in code via AVOptions or in +avformat_open_input. +

+ +

16.33.1 Muxer

+

The following options are supported. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+ +

Default value is ‘0’. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘latm’
+

Use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC. +

+
‘rfc2190’
+

Use RFC 2190 packetization instead of RFC 4629 for H.263. +

+
‘skip_rtcp’
+

Don’t send RTCP sender reports. +

+
‘h264_mode0’
+

Use mode 0 for H.264 in RTP. +

+
‘send_bye’
+

Send RTCP BYE packets when finishing. +

+
+ +

Default value is ‘0’. +

+ +
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+
pkt_size
+

Set max send packet size (in bytes). Default value is 1472. +

+
+ + +

16.33.2 Demuxer

+

The following options are supported. +

+
+
initial_pause
+

Do not start playing the stream immediately if set to 1. Default value +is 0. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+
‘udp_multicast’
+

Use UDP multicast as lower transport protocol. +

+
+
‘http’
+

Use HTTP tunneling as lower transport protocol, which is useful for +passing proxies. +

+
+
‘https’
+

Use HTTPs tunneling as lower transport protocol, which is useful for +passing proxies and widely used for security consideration. +

+
+ +

Multiple lower transport protocols may be specified, in that case they are +tried one at a time (if the setup of one fails, the next one is tried). +For the muxer, only the ‘tcp’ and ‘udp’ options are supported. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘filter_src’
+

Accept packets only from negotiated peer address and port. +

+
‘listen’
+

Act as a server, listening for an incoming connection. +

+
‘prefer_tcp’
+

Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. +

+
‘satip_raw’
+

Export raw MPEG-TS stream instead of demuxing. The flag will simply write out +the raw stream, with the original PAT/PMT/PIDs intact. +

+
+ +

Default value is ‘none’. +

+
+
allowed_media_types
+

Set media types to accept from the server. +

+

The following flags are accepted: +

+
‘video’
+
‘audio’
+
‘data’
+
‘subtitle’
+
+ +

By default it accepts all media types. +

+
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
listen_timeout
+

Set maximum timeout (in seconds) to establish an initial connection. Setting +listen_timeout > 0 sets rtsp_flags to ‘listen’. Default is -1 +which means an infinite timeout when ‘listen’ mode is set. +

+
+
reorder_queue_size
+

Set number of packets to buffer for handling of reordered packets. +

+
+
timeout
+

Set socket TCP I/O timeout in microseconds. +

+
+
user_agent
+

Override User-Agent header. If not specified, it defaults to the +libavformat identifier string. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+ +

When receiving data over UDP, the demuxer tries to reorder received packets +(since they may arrive out of order, or packets may get lost totally). This +can be disabled by setting the maximum demuxing delay to zero (via +the max_delay field of AVFormatContext). +

+

When watching multi-bitrate Real-RTSP streams with ffplay, the +streams to display can be chosen with -vst n and +-ast n for video and audio respectively, and can be switched +on the fly by pressing v and a. +

+ +

16.33.3 Examples

+ +

The following examples all make use of the ffplay and +ffmpeg tools. +

+
    +
  • Watch a stream over UDP, with a max reordering delay of 0.5 seconds: +
    +
    ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
    +
    + +
  • Watch a stream tunneled over HTTP: +
    +
    ffplay -rtsp_transport http rtsp://server/video.mp4
    +
    + +
  • Send a stream in realtime to a RTSP server, for others to watch: +
    +
    ffmpeg -re -i input -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
    +
    + +
  • Receive a stream in realtime: +
    +
    ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp output
    +
    +
+ + +

16.34 sap

+ +

Session Announcement Protocol (RFC 2974). This is not technically a +protocol handler in libavformat, it is a muxer and demuxer. +It is used for signalling of RTP streams, by announcing the SDP for the +streams regularly on a separate port. +

+ +

16.34.1 Muxer

+ +

The syntax for a SAP url given to the muxer is: +

+
sap://destination[:port][?options]
+
+ +

The RTP packets are sent to destination on port port, +or to port 5004 if no port is specified. +options is a &-separated list. The following options +are supported: +

+
+
announce_addr=address
+

Specify the destination IP address for sending the announcements to. +If omitted, the announcements are sent to the commonly used SAP +announcement multicast address 224.2.127.254 (sap.mcast.net), or +ff0e::2:7ffe if destination is an IPv6 address. +

+
+
announce_port=port
+

Specify the port to send the announcements on, defaults to +9875 if not specified. +

+
+
ttl=ttl
+

Specify the time to live value for the announcements and RTP packets, +defaults to 255. +

+
+
same_port=0|1
+

If set to 1, send all RTP streams on the same port pair. If zero (the +default), all streams are sent on unique ports, with each stream on a +port 2 numbers higher than the previous. +VLC/Live555 requires this to be set to 1, to be able to receive the stream. +The RTP stack in libavformat for receiving requires all streams to be sent +on unique ports. +

+
+ +

Example command lines follow. +

+

To broadcast a stream on the local subnet, for watching in VLC: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255?same_port=1
+
+ +

Similarly, for watching in ffplay: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255
+
+ +

And for watching in ffplay, over IPv6: +

+
+
ffmpeg -re -i input -f sap sap://[ff0e::1:2:3:4]
+
+ + +

16.34.2 Demuxer

+ +

The syntax for a SAP url given to the demuxer is: +

+
sap://[address][:port]
+
+ +

address is the multicast address to listen for announcements on, +if omitted, the default 224.2.127.254 (sap.mcast.net) is used. port +is the port that is listened on, 9875 if omitted. +

+

The demuxers listens for announcements on the given address and port. +Once an announcement is received, it tries to receive that particular stream. +

+

Example command lines follow. +

+

To play back the first stream announced on the normal SAP multicast address: +

+
+
ffplay sap://
+
+ +

To play back the first stream announced on one the default IPv6 SAP multicast address: +

+
+
ffplay sap://[ff0e::2:7ffe]
+
+ + +

16.35 sctp

+ +

Stream Control Transmission Protocol. +

+

The accepted URL syntax is: +

+
sctp://host:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen
+

If set to any value, listen for an incoming connection. Outgoing connection is done by default. +

+
+
max_streams
+

Set the maximum number of streams. By default no limit is set. +

+
+ + +

16.36 srt

+ +

Haivision Secure Reliable Transport Protocol via libsrt. +

+

The supported syntax for a SRT URL is: +

+
srt://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
connect_timeout=milliseconds
+

Connection timeout; SRT cannot connect for RTT > 1500 msec +(2 handshake exchanges) with the default connect timeout of +3 seconds. This option applies to the caller and rendezvous +connection modes. The connect timeout is 10 times the value +set for the rendezvous mode (which can be used as a +workaround for this connection problem with earlier versions). +

+
+
ffs=bytes
+

Flight Flag Size (Window Size), in bytes. FFS is actually an +internal parameter and you should set it to not less than +recv_buffer_size and mss. The default value +is relatively large, therefore unless you set a very large receiver buffer, +you do not need to change this option. Default value is 25600. +

+
+
inputbw=bytes/seconds
+

Sender nominal input rate, in bytes per seconds. Used along with +oheadbw, when maxbw is set to relative (0), to +calculate maximum sending rate when recovery packets are sent +along with the main media stream: +inputbw * (100 + oheadbw) / 100 +if inputbw is not set while maxbw is set to +relative (0), the actual input rate is evaluated inside +the library. Default value is 0. +

+
+
iptos=tos
+

IP Type of Service. Applies to sender only. Default value is 0xB8. +

+
+
ipttl=ttl
+

IP Time To Live. Applies to sender only. Default value is 64. +

+
+
latency=microseconds
+

Timestamp-based Packet Delivery Delay. +Used to absorb bursts of missed packet retransmissions. +This flag sets both rcvlatency and peerlatency +to the same value. Note that prior to version 1.3.0 +this is the only flag to set the latency, however +this is effectively equivalent to setting peerlatency, +when side is sender and rcvlatency +when side is receiver, and the bidirectional stream +sending is not supported. +

+
+
listen_timeout=microseconds
+

Set socket listen timeout. +

+
+
maxbw=bytes/seconds
+

Maximum sending bandwidth, in bytes per seconds. +-1 infinite (CSRTCC limit is 30mbps) +0 relative to input rate (see inputbw) +>0 absolute limit value +Default value is 0 (relative) +

+
+
mode=caller|listener|rendezvous
+

Connection mode. +caller opens client connection. +listener starts server to listen for incoming connections. +rendezvous use Rendez-Vous connection mode. +Default value is caller. +

+
+
mss=bytes
+

Maximum Segment Size, in bytes. Used for buffer allocation +and rate calculation using a packet counter assuming fully +filled packets. The smallest MSS between the peers is +used. This is 1500 by default in the overall internet. +This is the maximum size of the UDP packet and can be +only decreased, unless you have some unusual dedicated +network settings. Default value is 1500. +

+
+
nakreport=1|0
+

If set to 1, Receiver will send ‘UMSG_LOSSREPORT‘ messages +periodically until a lost packet is retransmitted or +intentionally dropped. Default value is 1. +

+
+
oheadbw=percents
+

Recovery bandwidth overhead above input rate, in percents. +See inputbw. Default value is 25%. +

+
+
passphrase=string
+

HaiCrypt Encryption/Decryption Passphrase string, length +from 10 to 79 characters. The passphrase is the shared +secret between the sender and the receiver. It is used +to generate the Key Encrypting Key using PBKDF2 +(Password-Based Key Derivation Function). It is used +only if pbkeylen is non-zero. It is used on +the receiver only if the received data is encrypted. +The configured passphrase cannot be recovered (write-only). +

+
+
enforced_encryption=1|0
+

If true, both connection parties must have the same password +set (including empty, that is, with no encryption). If the +password doesn’t match or only one side is unencrypted, +the connection is rejected. Default is true. +

+
+
kmrefreshrate=packets
+

The number of packets to be transmitted after which the +encryption key is switched to a new key. Default is -1. +-1 means auto (0x1000000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
kmpreannounce=packets
+

The interval between when a new encryption key is sent and +when switchover occurs. This value also applies to the +subsequent interval between when switchover occurs and +when the old encryption key is decommissioned. Default is -1. +-1 means auto (0x1000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
snddropdelay=microseconds
+

The sender’s extra delay before dropping packets. This delay is +added to the default drop delay time interval value. +

+

Special value -1: Do not drop packets on the sender at all. +

+
+
payload_size=bytes
+

Sets the maximum declared size of a packet transferred +during the single call to the sending function in Live +mode. Use 0 if this value isn’t used (which is default in +file mode). +Default is -1 (automatic), which typically means MPEG-TS; +if you are going to use SRT +to send any different kind of payload, such as, for example, +wrapping a live stream in very small frames, then you can +use a bigger maximum frame size, though not greater than +1456 bytes. +

+
+
pkt_size=bytes
+

Alias for ‘payload_size’. +

+
+
peerlatency=microseconds
+

The latency value (as described in rcvlatency) that is +set by the sender side as a minimum value for the receiver. +

+
+
pbkeylen=bytes
+

Sender encryption key length, in bytes. +Only can be set to 0, 16, 24 and 32. +Enable sender encryption if not 0. +Not required on receiver (set to 0), +key size obtained from sender in HaiCrypt handshake. +Default value is 0. +

+
+
rcvlatency=microseconds
+

The time that should elapse since the moment when the +packet was sent and the moment when it’s delivered to +the receiver application in the receiving function. +This time should be a buffer time large enough to cover +the time spent for sending, unexpectedly extended RTT +time, and the time needed to retransmit the lost UDP +packet. The effective latency value will be the maximum +of this options’ value and the value of peerlatency +set by the peer side. Before version 1.3.0 this option +is only available as latency. +

+
+
recv_buffer_size=bytes
+

Set UDP receive buffer size, expressed in bytes. +

+
+
send_buffer_size=bytes
+

Set UDP send buffer size, expressed in bytes. +

+
+
timeout=microseconds
+

Set raise error timeouts for read, write and connect operations. Note that the +SRT library has internal timeouts which can be controlled separately, the +value set here is only a cap on those. +

+
+
tlpktdrop=1|0
+

Too-late Packet Drop. When enabled on receiver, it skips +missing packets that have not been delivered in time and +delivers the following packets to the application when +their time-to-play has come. It also sends a fake ACK to +the sender. When enabled on sender and enabled on the +receiving peer, the sender drops the older packets that +have no chance of being delivered in time. It was +automatically enabled in the sender if the receiver +supports it. +

+
+
sndbuf=bytes
+

Set send buffer size, expressed in bytes. +

+
+
rcvbuf=bytes
+

Set receive buffer size, expressed in bytes. +

+

Receive buffer must not be greater than ffs. +

+
+
lossmaxttl=packets
+

The value up to which the Reorder Tolerance may grow. When +Reorder Tolerance is > 0, then packet loss report is delayed +until that number of packets come in. Reorder Tolerance +increases every time a "belated" packet has come, but it +wasn’t due to retransmission (that is, when UDP packets tend +to come out of order), with the difference between the latest +sequence and this packet’s sequence, and not more than the +value of this option. By default it’s 0, which means that this +mechanism is turned off, and the loss report is always sent +immediately upon experiencing a "gap" in sequences. +

+
+
minversion
+

The minimum SRT version that is required from the peer. A connection +to a peer that does not satisfy the minimum version requirement +will be rejected. +

+

The version format in hex is 0xXXYYZZ for x.y.z in human readable +form. +

+
+
streamid=string
+

A string limited to 512 characters that can be set on the socket prior +to connecting. This stream ID will be able to be retrieved by the +listener side from the socket that is returned from srt_accept and +was connected by a socket with that set stream ID. SRT does not enforce +any special interpretation of the contents of this string. +This option doesn’t make sense in Rendezvous connection; the result +might be that simply one side will override the value from the other +side and it’s the matter of luck which one would win +

+
+
srt_streamid=string
+

Alias for ‘streamid’ to avoid conflict with ffmpeg command line option. +

+
+
smoother=live|file
+

The type of Smoother used for the transmission for that socket, which +is responsible for the transmission and congestion control. The Smoother +type must be exactly the same on both connecting parties, otherwise +the connection is rejected. +

+
+
messageapi=1|0
+

When set, this socket uses the Message API, otherwise it uses Buffer +API. Note that in live mode (see transtype) there’s only +message API available. In File mode you can chose to use one of two modes: +

+

Stream API (default, when this option is false). In this mode you may +send as many data as you wish with one sending instruction, or even use +dedicated functions that read directly from a file. The internal facility +will take care of any speed and congestion control. When receiving, you +can also receive as many data as desired, the data not extracted will be +waiting for the next call. There is no boundary between data portions in +the Stream mode. +

+

Message API. In this mode your single sending instruction passes exactly +one piece of data that has boundaries (a message). Contrary to Live mode, +this message may span across multiple UDP packets and the only size +limitation is that it shall fit as a whole in the sending buffer. The +receiver shall use as large buffer as necessary to receive the message, +otherwise the message will not be given up. When the message is not +complete (not all packets received or there was a packet loss) it will +not be given up. +

+
+
transtype=live|file
+

Sets the transmission type for the socket, in particular, setting this +option sets multiple other parameters to their default values as required +for a particular transmission type. +

+

live: Set options as for live transmission. In this mode, you should +send by one sending instruction only so many data that fit in one UDP packet, +and limited to the value defined first in payload_size (1316 is +default in this mode). There is no speed control in this mode, only the +bandwidth control, if configured, in order to not exceed the bandwidth with +the overhead transmission (retransmitted and control packets). +

+

file: Set options as for non-live transmission. See messageapi +for further explanations +

+
+
linger=seconds
+

The number of seconds that the socket waits for unsent data when closing. +Default is -1. -1 means auto (off with 0 seconds in live mode, on with 180 +seconds in file mode). The range for this option is integers in the +0 - INT_MAX. +

+
+
tsbpd=1|0
+

When true, use Timestamp-based Packet Delivery mode. The default behavior +depends on the transmission type: enabled in live mode, disabled in file +mode. +

+
+
+ +

For more information see: https://github.com/Haivision/srt. +

+ +

16.37 srtp

+ +

Secure Real-time Transport Protocol. +

+

The accepted options are: +

+
srtp_in_suite
+
srtp_out_suite
+

Select input and output encoding suites. +

+

Supported values: +

+
‘AES_CM_128_HMAC_SHA1_80’
+
‘SRTP_AES128_CM_HMAC_SHA1_80’
+
‘AES_CM_128_HMAC_SHA1_32’
+
‘SRTP_AES128_CM_HMAC_SHA1_32’
+
+ +
+
srtp_in_params
+
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. +

+
+ + +

16.38 subfile

+ +

Virtually extract a segment of a file or another stream. +The underlying stream must be seekable. +

+

Accepted options: +

+
start
+

Start offset of the extracted segment, in bytes. +

+
end
+

End offset of the extracted segment, in bytes. +If set to 0, extract till end of file. +

+
+ +

Examples: +

+

Extract a chapter from a DVD VOB file (start and end sectors obtained +externally and multiplied by 2048): +

+
subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
+
+ +

Play an AVI file directly from a TAR archive: +

+
subfile,,start,183241728,end,366490624,,:archive.tar
+
+ +

Play a MPEG-TS file from start offset till end: +

+
subfile,,start,32815239,end,0,,:video.ts
+
+ + +

16.39 tee

+ +

Writes the output to multiple protocols. The individual outputs are separated +by | +

+
+
tee:file://path/to/local/this.avi|file://path/to/local/that.avi
+
+ + +

16.40 tcp

+ +

Transmission Control Protocol. +

+

The required syntax for a TCP url is: +

+
tcp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen=2|1|0
+

Listen for an incoming connection. 0 disables listen, 1 enables listen in +single client mode, 2 enables listen in multi-client mode. Default value is 0. +

+
+
local_addr=addr
+

Local IP address of a network interface used for tcp socket connect. +

+
+
local_port=port
+

Local port used for tcp socket connect. +

+
+
timeout=microseconds
+

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. +

+
+
listen_timeout=milliseconds
+

Set listen timeout, expressed in milliseconds. +

+
+
recv_buffer_size=bytes
+

Set receive buffer size, expressed bytes. +

+
+
send_buffer_size=bytes
+

Set send buffer size, expressed bytes. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_mss=bytes
+

Set maximum segment size for outgoing TCP packets, expressed in bytes. +

+
+ +

The following example shows how to setup a listening TCP connection +with ffmpeg, which is then accessed with ffplay: +

+
ffmpeg -i input -f format tcp://hostname:port?listen
+ffplay tcp://hostname:port
+
+ + +

16.41 tls

+ +

Transport Layer Security (TLS) / Secure Sockets Layer (SSL) +

+

The required syntax for a TLS/SSL url is: +

+
tls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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 other backends, +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. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
http_proxy
+

The HTTP proxy to tunnel through, e.g. http://example.com:1234. +The proxy must support the CONNECT method. +

+
+
+ +

Example command lines: +

+

To create a TLS/SSL server that serves an input stream. +

+
+
ffmpeg -i input -f format tls://hostname:port?listen&cert=server.crt&key=server.key
+
+ +

To play back a stream from the TLS/SSL server using ffplay: +

+
+
ffplay tls://hostname:port
+
+ + +

16.42 dtls

+ +

Datagram Transport Layer Security (DTLS) +

+

The required syntax for a DTLS URL is: +

+
dtls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

DTLS shares most options with TLS, but operates over UDP instead of TCP. +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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. +

+

This is disabled by default since it requires a CA database to be +provided by the caller in many cases. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
cert_pem=string
+

Certificate PEM string +

+
+
key_pem=string
+

Private key PEM string +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
mtu=size
+

Set the Maximum Transmission Unit (MTU) for DTLS packets. +

+
+
use_srtp=1|0
+

Enable the use_srtp DTLS extension. +This is used in WebRTC applications to establish SRTP encryption keys +through the DTLS handshake. Default is disabled. +

+
+
external_sock=1|0
+

Use an external socket instead of creating a new one. +This option only makes sense to pass when interacting with the code via +API, enabling this from CLI will cause immediate failure. +Default is disabled. +

+
+
+ +

Example command lines: +

+

To create a DTLS server: +

+
+
ffmpeg -listen 1 -i dtls://hostname:port output
+
+ +

To create a DTLS client and send data to server: +

+
+
ffmpeg -i input -f format dtls://hostname:port
+
+ + +

16.43 udp

+ +

User Datagram Protocol. +

+

The required syntax for an UDP URL is: +

+
udp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

In case threading is enabled on the system, a circular buffer is used +to store the incoming data, which allows one to reduce loss of data due to +UDP socket buffer overruns. The fifo_size and +overrun_nonfatal options are related to this buffer. +

+

The list of supported options follows. +

+
+
buffer_size=size
+

Set the UDP maximum socket buffer size in bytes. This is used to set either +the receive or send buffer size, depending on what the socket is used for. +Default is 32 KB for output, 384 KB for input. See also fifo_size. +

+
+
bitrate=bitrate
+

If set to nonzero, the output will have the specified constant bitrate if the +input has enough packets to sustain it. +

+
+
burst_bits=bits
+

When using bitrate this specifies the maximum number of bits in +packet bursts. +

+
+
localport=port
+

Override the local UDP port to bind with. +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
pkt_size=size
+

Set the size in bytes of UDP packets. +

+
+
reuse=1|0
+

Explicitly allow or disallow reusing UDP sockets. +

+
+
ttl=ttl
+

Set the time to live value (for multicast only). +

+
+
dscp=dscp
+

Set the 6-bit DSCP field for outgoing packets. +

+
+
connect=1|0
+

Initialize the UDP socket with connect(). In this case, the +destination address can’t be changed with ff_udp_set_remote_url later. +If the destination address isn’t known at the start, this option can +be specified in ff_udp_set_remote_url, too. +This allows finding out the source address for the packets with getsockname, +and makes writes return with AVERROR(ECONNREFUSED) if "destination +unreachable" is received. +For receiving, this gives the benefit of only receiving packets from +the specified peer address/port. +

+
+
sources=address[,address]
+

Only receive packets sent from the specified addresses. In case of multicast, +also subscribe to multicast traffic coming from these addresses only. +

+
+
block=address[,address]
+

Ignore packets sent from the specified addresses. In case of multicast, also +exclude the source addresses in the multicast subscription. +

+
+
fifo_size=units
+

Set the UDP receiving circular buffer size, expressed as a number of +packets with size of 188 bytes. If not specified defaults to 7*4096. +

+
+
overrun_nonfatal=1|0
+

Survive in case of UDP receiving circular buffer overrun. Default +value is 0. +

+
+
timeout=microseconds
+

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. +

+
+
broadcast=1|0
+

Explicitly allow or disallow UDP broadcasting. +

+

Note that broadcasting may not work properly on networks having +a broadcast storm protection. +

+
+ + +

16.43.1 Examples

+ +
    +
  • Use ffmpeg to stream over UDP to a remote endpoint: +
    +
    ffmpeg -i input -f format udp://hostname:port
    +
    + +
  • Use ffmpeg to stream in mpegts format over UDP using 188 +sized UDP packets, using a large input buffer: +
    +
    ffmpeg -i input -f mpegts udp://hostname:port?pkt_size=188&buffer_size=65535
    +
    + +
  • Use ffmpeg to receive over UDP from a remote endpoint: +
    +
    ffmpeg -i udp://[multicast-address]:port ...
    +
    +
+ + +

16.44 unix

+ +

Unix local socket +

+

The required syntax for a Unix socket URL is: +

+
+
unix://filepath
+
+ +

The following parameters can be set via command line options +(or in code via AVOptions): +

+
+
timeout
+

Timeout in ms. +

+
listen
+

Create the Unix socket in listening mode. +

+
type
+

Select socket type. +

+
‘stream Corresponds to SOCK_STREAM (reliable stream-oriented)’
+
‘datagram Corresponds to SOCK_DGRAM (unreliable packet-oriented)’
+
‘seqpacket Corresponds to SOCK_SEQPACKET (reliable packet-oriented)’
+
+
+
pkt_size
+

Maximum packet size for packet-oriented sockets (SOCK_DGRAM and +SOCK_SEQPACKET). If greater than zero, this value is used as +max_packet_size. Ignored for SOCK_STREAM. Default is 0. +

+
+ + +

16.45 zmq

+ +

ZeroMQ asynchronous messaging using the libzmq library. +

+

This library supports unicast streaming to multiple clients without relying on +an external server. +

+

The required syntax for streaming or connecting to a stream is: +

+
zmq:tcp://ip-address:port
+
+ +

Example: +Create a localhost stream on port 5555: +

+
ffmpeg -re -i input -f mpegts zmq:tcp://127.0.0.1:5555
+
+ +

Multiple clients may connect to the stream using: +

+
ffplay zmq:tcp://127.0.0.1:5555
+
+ +

Streaming to multiple clients is implemented using a ZeroMQ Pub-Sub pattern. +The server side binds to a port and publishes data. Clients connect to the +server (via IP address/port) and subscribe to the stream. The order in which +the server and client start generally does not matter. +

+

ffmpeg must be compiled with the –enable-libzmq option to support +this protocol. +

+

Options can be set on the ffmpeg/ffplay command +line. The following options are supported: +

+
+
pkt_size
+

Forces the maximum packet size for sending/receiving data. The default value is +131,072 bytes. On the server side, this sets the maximum size of sent packets +via ZeroMQ. On the clients, it sets an internal buffer size for receiving +packets. Note that pkt_size on the clients should be equal to or greater than +pkt_size on the server. Otherwise the received message may be truncated causing +decoding errors. +

+
+
+ + +

17 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the device +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+ + +

18 Input Devices

+ +

Input devices are configured elements in FFmpeg which enable accessing +the data coming from a multimedia device attached to your system. +

+

When you configure your FFmpeg build, all the supported input devices +are enabled by default. You can list all available ones using the +configure option "–list-indevs". +

+

You can disable all the input devices using the configure option +"–disable-indevs", and selectively enable an input device using the +option "–enable-indev=INDEV", or you can disable a particular +input device using the option "–disable-indev=INDEV". +

+

The option "-devices" of the ff* tools will display the list of +supported input devices. +

+

A description of the currently available input devices follows. +

+ +

18.1 alsa

+ +

ALSA (Advanced Linux Sound Architecture) input device. +

+

To enable this input device during configuration you need libasound +installed on your system. +

+

This device allows capturing from an ALSA device. The name of the +device to capture has to be an ALSA card identifier. +

+

An ALSA identifier has the syntax: +

+
hw:CARD[,DEV[,SUBDEV]]
+
+ +

where the DEV and SUBDEV components are optional. +

+

The three arguments (in order: CARD,DEV,SUBDEV) +specify card number or identifier, device number and subdevice number +(-1 means any). +

+

To see the list of cards currently recognized by your system check the +files /proc/asound/cards and /proc/asound/devices. +

+

For example to capture with ffmpeg from an ALSA device with +card id 0, you may run the command: +

+
ffmpeg -f alsa -i hw:0 alsaout.wav
+
+ +

For more information see: +http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html +

+ +

18.1.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

18.2 android_camera

+ +

Android camera input device. +

+

This input devices uses the Android Camera2 NDK API which is +available on devices with API level 24+. The availability of +android_camera is autodetected during configuration. +

+

This device allows capturing from all cameras on an Android device, +which are integrated into the Camera2 NDK API. +

+

The available cameras are enumerated internally and can be selected +with the camera_index parameter. The input file string is +discarded. +

+

Generally the back facing camera has index 0 while the front facing +camera has index 1. +

+ +

18.2.1 Options

+ +
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Falls back to the first available configuration reported by +Android if requested video size is not available or by default. +

+
+
framerate
+

Set the video framerate. +Falls back to the first available configuration reported by +Android if requested framerate is not available or by default (-1). +

+
+
camera_index
+

Set the index of the camera to use. Default is 0. +

+
+
input_queue_size
+

Set the maximum number of frames to buffer. Default is 5. +

+
+
+ + +

18.3 avfoundation

+ +

AVFoundation input device. +

+

AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS. +

+

The input filename has to be given in the following syntax: +

+
-i "[[VIDEO]:[AUDIO]]"
+
+

The first entry selects the video input while the latter selects the audio input. +The stream has to be specified by the device name or the device index as shown by the device list. +Alternatively, the video and/or audio input device can be chosen by index using the + + -video_device_index <INDEX> + +and/or + + -audio_device_index <INDEX> + +, overriding any +device name or index given in the input filename. +

+

All available devices can be enumerated by using -list_devices true, listing +all device names and corresponding indices. +

+

There are two device name aliases: +

+
default
+

Select the AVFoundation default device of the corresponding type. +

+
+
none
+

Do not record the corresponding media type. +This is equivalent to specifying an empty device name or index. +

+
+
+ + +

18.3.1 Options

+ +

AVFoundation supports the following options: +

+
+
-list_devices <TRUE|FALSE>
+

If set to true, a list of all available input devices is given showing all +device names and indices. +

+
+
-video_device_index <INDEX>
+

Specify the video device by its index. Overrides anything given in the input filename. +

+
+
-audio_device_index <INDEX>
+

Specify the audio device by its index. Overrides anything given in the input filename. +

+
+
-pixel_format <FORMAT>
+

Request the video device to use a specific pixel format. +If the specified format is not supported, a list of available formats is given +and the first one in this list is used instead. Available pixel formats are: +monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0, + bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10, + yuv420p, nv12, yuyv422, gray +

+
+
-framerate
+

Set the grabbing frame rate. Default is ntsc, corresponding to a +frame rate of 30000/1001. +

+
+
-video_size
+

Set the video frame size. +

+
+
-capture_cursor
+

Capture the mouse pointer. Default is 0. +

+
+
-capture_mouse_clicks
+

Capture the screen mouse clicks. Default is 0. +

+
+
-capture_raw_data
+

Capture the raw device data. Default is 0. +Using this option may result in receiving the underlying data delivered to the AVFoundation framework. E.g. for muxed devices that sends raw DV data to the framework (like tape-based camcorders), setting this option to false results in extracted video frames captured in the designated pixel format only. Setting this option to true results in receiving the raw DV stream untouched. +

+
+ + +

18.3.2 Examples

+ +
    +
  • Print the list of AVFoundation supported devices and exit: +
    +
    $ ffmpeg -f avfoundation -list_devices true -i ""
    +
    + +
  • Record video from video device 0 and audio from audio device 0 into out.avi: +
    +
    $ ffmpeg -f avfoundation -i "0:0" out.avi
    +
    + +
  • Record video from video device 2 and audio from audio device 1 into out.avi: +
    +
    $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi
    +
    + +
  • Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi: +
    +
    $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi
    +
    + +
  • Record raw DV data from a suitable input device and write the output into out.dv: +
    +
    $ ffmpeg -f avfoundation -capture_raw_data true -i "zr100:none" out.dv
    +
    + + +
+ + +

18.4 decklink

+ +

The decklink input device provides capture capabilities for Blackmagic +DeckLink devices. +

+

To enable this input device, you need the Blackmagic DeckLink SDK and you +need to configure with the appropriate --extra-cflags +and --extra-ldflags. +On Windows, you need to run the IDL files through widl. +

+

DeckLink is very picky about the formats it supports. Pixel format of the +input can be set with raw_format. +Framerate and video size must be determined for your device with +-list_formats 1. Audio sample rate is always 48 kHz and the number +of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single +audio track. +

+ +

18.4.1 Options

+ +
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. This option is deprecated, please use the +-sources option of ffmpeg to list the available input devices. +

+
+
list_formats
+

If set to true, print a list of supported formats and exit. +Defaults to false. +

+
+
format_code <FourCC>
+

This sets the input video format to the format given by the FourCC. To see +the supported values of your device(s) use list_formats. +Note that there is a FourCC 'pal ' that can also be used +as pal (3 letters). +Default behavior is autodetection of the input video format, if the hardware +supports it. +

+
+
raw_format
+

Set the pixel format of the captured video. +Available values are: +

+
‘auto’
+
+

This is the default which means 8-bit YUV 422 or 8-bit ARGB if format +autodetection is used, 8-bit YUV 422 otherwise. +

+
+
‘uyvy422’
+
+

8-bit YUV 422. +

+
+
‘yuv422p10’
+
+

10-bit YUV 422. +

+
+
‘argb’
+
+

8-bit RGB. +

+
+
‘bgra’
+
+

8-bit RGB. +

+
+
‘rgb10’
+
+

10-bit RGB. +

+
+
+ +
+
teletext_lines
+

If set to nonzero, an additional teletext stream will be captured from the +vertical ancillary data. Both SD PAL (576i) and HD (1080i or 1080p) +sources are supported. In case of HD sources, OP47 packets are decoded. +

+

This option is a bitmask of the SD PAL VBI lines captured, specifically lines 6 +to 22, and lines 318 to 335. Line 6 is the LSB in the mask. Selected lines +which do not contain teletext information will be ignored. You can use the +special all constant to select all possible lines, or +standard to skip lines 6, 318 and 319, which are not compatible with +all receivers. +

+

For SD sources, ffmpeg needs to be compiled with --enable-libzvbi. For +HD sources, on older (pre-4K) DeckLink card models you have to capture in 10 +bit mode. +

+
+
channels
+

Defines number of audio channels to capture. Must be ‘2’, ‘8’ or ‘16’. +Defaults to ‘2’. +

+
+
duplex_mode
+

Sets the decklink device duplex/profile mode. Must be ‘unset’, ‘half’, ‘full’, +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +Defaults to ‘unset’. +

+

Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property. +For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 +sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile +is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles. +

+

Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0): +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +

+

Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2: +‘half’, ‘full’ +

+
+
timecode_format
+

Timecode type to include in the frame and video stream metadata. Must be +‘none’, ‘rp188vitc’, ‘rp188vitc2’, ‘rp188ltc’, +‘rp188hfr’, ‘rp188any’, ‘vitc’, ‘vitc2’, or ‘serial’. +Defaults to ‘none’ (not included). +

+

In order to properly support 50/60 fps timecodes, the ordering of the queried +timecode types for ‘rp188any’ is HFR, VITC1, VITC2 and LTC for >30 fps +content. Note that this is slightly different to the ordering used by the +DeckLink API, which is HFR, VITC1, LTC, VITC2. +

+
+
video_input
+

Sets the video input source. Must be ‘unset’, ‘sdi’, ‘hdmi’, +‘optical_sdi’, ‘component’, ‘composite’ or ‘s_video’. +Defaults to ‘unset’. +

+
+
audio_input
+

Sets the audio input source. Must be ‘unset’, ‘embedded’, +‘aes_ebu’, ‘analog’, ‘analog_xlr’, ‘analog_rca’ or +‘microphone’. Defaults to ‘unset’. +

+
+
video_pts
+

Sets the video packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘video’. +

+
+
audio_pts
+

Sets the audio packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘audio’. +

+
+
draw_bars
+

If set to ‘true’, color bars are drawn in the event of a signal loss. +Defaults to ‘true’. +This option is deprecated, please use the signal_loss_action option. +

+
+
signal_loss_action
+

Sets the action to take in the event of a signal loss. Accepts one of the +following values: +

+
+
1, none
+

Do nothing on signal loss. This usually results in black frames. +

+
2, bars
+

Draw color bars on signal loss. Only supported for 8-bit input signals. +

+
3, repeat
+

Repeat the last video frame on signal loss. +

+
+ +

Defaults to ‘bars’. +

+
+
queue_size
+

Sets maximum input buffer size in bytes. If the buffering reaches this value, +incoming frames will be dropped. +Defaults to ‘1073741824’. +

+
+
audio_depth
+

Sets the audio sample bit depth. Must be ‘16’ or ‘32’. +Defaults to ‘16’. +

+
+
decklink_copyts
+

If set to true, timestamps are forwarded as they are without removing +the initial offset. +Defaults to false. +

+
+
timestamp_align
+

Capture start time alignment in seconds. If set to nonzero, input frames are +dropped till the system timestamp aligns with configured value. +Alignment difference of up to one frame duration is tolerated. +This is useful for maintaining input synchronization across N different +hardware devices deployed for ’N-way’ redundancy. The system time of different +hardware devices should be synchronized with protocols such as NTP or PTP, +before using this option. +Note that this method is not foolproof. In some border cases input +synchronization may not happen due to thread scheduling jitters in the OS. +Either sync could go wrong by 1 frame or in a rarer case +timestamp_align seconds. +Defaults to ‘0’. +

+
+
wait_for_tc (bool)
+

Drop frames till a frame with timecode is received. Sometimes serial timecode +isn’t received with the first input frame. If that happens, the stored stream +timecode will be inaccurate. If this option is set to true, input frames +are dropped till a frame with timecode is received. +Option timecode_format must be specified. +Defaults to false. +

+
+
enable_klv(bool)
+

If set to true, extracts KLV data from VANC and outputs KLV packets. +KLV VANC packets are joined based on MID and PSC fields and aggregated into +one KLV packet. +Defaults to false. +

+
+
+ + +

18.4.2 Examples

+ +
    +
  • List input devices: +
    +
    ffmpeg -sources decklink
    +
    + +
  • List supported formats: +
    +
    ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'
    +
    + +
  • Capture video clip at 1080i50: +
    +
    ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 10 bit: +
    +
    ffmpeg -raw_format yuv422p10 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 with 16 audio channels: +
    +
    ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
+ + +

18.5 dshow

+ +

Windows DirectShow input device. +

+

DirectShow support is enabled when FFmpeg is built with the mingw-w64 project. +Currently only audio and video devices are supported. +

+

Multiple devices may be opened as separate inputs, but they may also be +opened on the same input, which should improve synchronism between them. +

+

The input name should be in the format: +

+
+
TYPE=NAME[:TYPE=NAME]
+
+ +

where TYPE can be either audio or video, +and NAME is the device’s name or alternative name.. +

+ +

18.5.1 Options

+ +

If no options are specified, the device’s defaults are used. +If the device does not support the requested options, it will +fail to open. +

+
+
video_size
+

Set the video size in the captured video. +

+
+
framerate
+

Set the frame rate in the captured video. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. +

+
+
channels
+

Set the number of channels in the captured audio. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +

+
+
list_options
+

If set to true, print a list of selected device’s options +and exit. +

+
+
video_device_number
+

Set video device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
audio_device_number
+

Set audio device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
pixel_format
+

Select pixel format to be used by DirectShow. This may only be set when +the video codec is not set or set to rawvideo. +

+
+
audio_buffer_size
+

Set audio device buffer size in milliseconds (which can directly +impact latency, depending on the device). +Defaults to using the audio device’s +default buffer size (typically some multiple of 500ms). +Setting this value too low can degrade performance. +See also +http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx +

+
+
video_pin_name
+

Select video capture pin to use by name or alternative name. +

+
+
audio_pin_name
+

Select audio capture pin to use by name or alternative name. +

+
+
crossbar_video_input_pin_number
+

Select video input pin number for crossbar device. This will be +routed to the crossbar device’s Video Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
crossbar_audio_input_pin_number
+

Select audio input pin number for crossbar device. This will be +routed to the crossbar device’s Audio Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
show_video_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change video filter properties +and configurations manually. +Note that for crossbar devices, adjusting values in this dialog +may be needed at times to toggle between PAL (25 fps) and NTSC (29.97) +input frame rates, sizes, interlacing, etc. Changing these values can +enable different scan rates/frame rates and avoiding green bars at +the bottom, flickering scan lines, etc. +Note that with some devices, changing these properties can also affect future +invocations (sets new defaults) until system reboot occurs. +

+
+
show_audio_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change audio filter properties +and configurations manually. +

+
+
show_video_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens a video device. +

+
+
show_audio_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens an audio device. +

+
+
show_analog_tv_tuner_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV channels and frequencies. +

+
+
show_analog_tv_tuner_audio_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV audio (like mono vs. stereo, Language A,B or C). +

+
+
audio_device_load
+

Load an audio capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this an audio capture source has to be specified, but it can +be anything even fake one. +

+
+
audio_device_save
+

Save the currently used audio capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
video_device_load
+

Load a video capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this a video capture source has to be specified, but it can +be anything even fake one. +

+
+
video_device_save
+

Save the currently used video capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
use_video_device_timestamps
+

If set to false, the timestamp for video frames will be +derived from the wallclock instead of the timestamp provided by +the capture device. This allows working around devices that +provide unreliable timestamps. +

+
+
+ + +

18.5.2 Examples

+ +
    +
  • Print the list of DirectShow supported devices and exit: +
    +
    $ ffmpeg -list_devices true -f dshow -i dummy
    +
    + +
  • Open video device Camera: +
    +
    $ ffmpeg -f dshow -i video="Camera"
    +
    + +
  • Open second video device with name Camera: +
    +
    $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"
    +
    + +
  • Open video device Camera and audio device Microphone: +
    +
    $ ffmpeg -f dshow -i video="Camera":audio="Microphone"
    +
    + +
  • Print the list of supported options in selected device and exit: +
    +
    $ ffmpeg -list_options true -f dshow -i video="Camera"
    +
    + +
  • Specify pin names to capture by name or alternative name, specify alternative device name: +
    +
    $ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\{ca465100-deb0-4d59-818f-8c477184adf6}":audio="Microphone"
    +
    + +
  • Configure a crossbar device, specifying crossbar pins, allow user to adjust video capture properties at startup: +
    +
    $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0
    +     -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"
    +
    + +
+ + +

18.6 fbdev

+ +

Linux framebuffer input 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 +/dev/fb0. +

+

For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. +

+

See also http://linux-fbdev.sourceforge.net/, and fbset(1). +

+

To record from the framebuffer device /dev/fb0 with +ffmpeg: +

+
ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi
+
+ +

You can take a single screenshot image with the command: +

+
ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg
+
+ + +

18.6.1 Options

+ +
+
framerate
+

Set the frame rate. Default is 25. +

+
+
+ + +

18.7 gdigrab

+ +

Win32 GDI-based screen capture device. +

+

This device allows you to capture a region of the display on Windows. +

+

Amongst options for the input filenames are such elements as: +

+
desktop
+
+

or +

+
title=window_title
+
+

or +

+
hwnd=window_hwnd
+
+ +

The first option will capture the entire desktop, or a fixed region of the +desktop. The second and third options will instead capture the contents of a single +window, regardless of its position on the screen. +

+

For example, to grab the entire desktop using ffmpeg: +

+
ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg
+
+ +

Grab a 640x480 region at position 10,20: +

+
ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg
+
+ +

Grab the contents of the window named "Calculator" +

+
ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg
+
+ + +

18.7.1 Options

+ +
+
draw_mouse
+

Specify whether to draw the mouse pointer. Use the value 0 to +not draw the pointer. Default value is 1. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+

Note that show_region is incompatible with grabbing the contents +of a single window. +

+

For example: +

+
ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg
+
+ +
+
video_size
+

Set the video frame size. The default is to capture the full screen if desktop is selected, or the full window size if title=window_title is selected. +

+
+
offset_x
+

When capturing a region with video_size, set the distance from the left edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned to the left of your primary monitor, you will need to use a negative offset_x value to move the region to that monitor. +

+
+
offset_y
+

When capturing a region with video_size, set the distance from the top edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned above your primary monitor, you will need to use a negative offset_y value to move the region to that monitor. +

+
+
+ + +

18.8 iec61883

+ +

FireWire DV/HDV input device using libiec61883. +

+

To enable this input device, you need libiec61883, libraw1394 and +libavc1394 installed on your system. Use the configure option +--enable-libiec61883 to compile with the device enabled. +

+

The iec61883 capture device supports capturing from a video device +connected via IEEE1394 (FireWire), using libiec61883 and the new Linux +FireWire stack (juju). This is the default DV/HDV input method in Linux +Kernel 2.6.37 and later, since the old FireWire stack was removed. +

+

Specify the FireWire port to be used as input file, or "auto" +to choose the first port connected. +

+ +

18.8.1 Options

+ +
+
dvtype
+

Override autodetection of DV/HDV. This should only be used if auto +detection does not work, or if usage of a different device type +should be prohibited. Treating a DV device as HDV (or vice versa) will +not work and result in undefined behavior. +The values auto, dv and hdv are supported. +

+
+
dvbuffer
+

Set maximum size of buffer for incoming data, in frames. For DV, this +is an exact value. For HDV, it is not frame exact, since HDV does +not have a fixed frame size. +

+
+
dvguid
+

Select the capture device by specifying its GUID. Capturing will only +be performed from the specified device and fails if no device with the +given GUID is found. This is useful to select the input if multiple +devices are connected at the same time. +Look at /sys/bus/firewire/devices to find out the GUIDs. +

+
+
+ + +

18.8.2 Examples

+ +
    +
  • Grab and show the input of a FireWire DV/HDV device. +
    +
    ffplay -f iec61883 -i auto
    +
    + +
  • Grab and record the input of a FireWire DV/HDV device, +using a packet buffer of 100000 packets if the source is HDV. +
    +
    ffmpeg -f iec61883 -i auto -dvbuffer 100000 out.mpg
    +
    + +
+ + +

18.9 jack

+ +

JACK input device. +

+

To enable this input device during configuration you need libjack +installed on your system. +

+

A JACK input device creates one or more JACK writable clients, one for +each audio channel, with name client_name:input_N, where +client_name is the name provided by the application, and N +is a number which identifies the channel. +Each writable client will send the acquired data to the FFmpeg input +device. +

+

Once you have created one or more JACK readable clients, you need to +connect them to one or more JACK writable clients. +

+

To connect or disconnect JACK clients you can use the jack_connect +and jack_disconnect programs, or do it through a graphical interface, +for example with qjackctl. +

+

To list the JACK clients and their properties you can invoke the command +jack_lsp. +

+

Follows an example which shows how to capture a JACK readable client +with ffmpeg. +

+
# Create a JACK writable client with name "ffmpeg".
+$ ffmpeg -f jack -i ffmpeg -y out.wav
+
+# Start the sample jack_metro readable client.
+$ jack_metro -b 120 -d 0.2 -f 4000
+
+# List the current JACK clients.
+$ jack_lsp -c
+system:capture_1
+system:capture_2
+system:playback_1
+system:playback_2
+ffmpeg:input_1
+metro:120_bpm
+
+# Connect metro to the ffmpeg writable client.
+$ jack_connect metro:120_bpm ffmpeg:input_1
+
+ +

For more information read: +http://jackaudio.org/ +

+ +

18.9.1 Options

+ +
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

18.10 kmsgrab

+ +

KMS video input device. +

+

Captures the KMS scanout framebuffer associated with a specified CRTC or plane as a +DRM object that can be passed to other hardware functions. +

+

Requires either DRM master or CAP_SYS_ADMIN to run. +

+

If you don’t understand what all of that means, you probably don’t want this. Look at +x11grab instead. +

+ +

18.10.1 Options

+ +
+
device
+

DRM device to capture on. Defaults to /dev/dri/card0. +

+
+
format
+

Pixel format of the framebuffer. This can be autodetected if you are running Linux 5.7 +or later, but needs to be provided for earlier versions. Defaults to bgr0, +which is the most common format used by the Linux console and Xorg X server. +

+
+
format_modifier
+

Format modifier to signal on output frames. This is necessary to import correctly into +some APIs. It can be autodetected if you are running Linux 5.7 or later, but will need +to be provided explicitly when needed in earlier versions. See the libdrm documentation +for possible values. +

+
+
crtc_id
+

KMS CRTC ID to define the capture source. The first active plane on the given CRTC +will be used. +

+
+
plane_id
+

KMS plane ID to define the capture source. Defaults to the first active plane found if +neither crtc_id nor plane_id are specified. +

+
+
framerate
+

Framerate to capture at. This is not synchronised to any page flipping or framebuffer +changes - it just defines the interval at which the framebuffer is sampled. Sampling +faster than the framebuffer update rate will generate independent frames with the same +content. Defaults to 30. +

+
+
+ + +

18.10.2 Examples

+ +
    +
  • Capture from the first active plane, download the result to normal frames and encode. +This will only work if the framebuffer is both linear and mappable - if not, the result +may be scrambled or fail to download. +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwdownload,format=bgr0' output.mp4
    +
    + +
  • Capture from CRTC ID 42 at 60fps, map the result to VAAPI, convert to NV12 and encode as H.264. +
    +
    ffmpeg -crtc_id 42 -framerate 60 -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,scale_vaapi=w=1920:h=1080:format=nv12' -c:v h264_vaapi output.mp4
    +
    + +
  • To capture only part of a plane the output can be cropped - this can be used to capture +a single window, as long as it has a known absolute position and size. For example, to +capture and encode the middle quarter of a 1920x1080 plane: +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,crop=960:540:480:270,scale_vaapi=960:540:nv12' -c:v h264_vaapi output.mp4
    +
    + +
+ + +

18.11 lavfi

+ +

Libavfilter input virtual device. +

+

This input device reads data from the open output pads of a libavfilter +filtergraph. +

+

For each filtergraph open output, the input device will create a +corresponding stream which is mapped to the generated output. +The filtergraph is specified through the option graph. +

+ +

18.11.1 Options

+ +
+
graph
+

Specify the filtergraph to use as input. Each video open output must be +labelled by a unique string of the form "outN", where N is a +number starting from 0 corresponding to the mapped input stream +generated by the device. +The first unlabelled output is automatically assigned to the "out0" +label, but all the others need to be specified explicitly. +

+

The suffix "+subcc" can be appended to the output label to create an extra +stream with the closed captions packets attached to that output +(experimental; only for EIA-608 / CEA-708 for now). +The subcc streams are created after all the normal streams, in the order of +the corresponding stream. +For example, if there is "out19+subcc", "out7+subcc" and up to "out42", the +stream #43 is subcc for stream #7 and stream #44 is subcc for stream #19. +

+

If not specified defaults to the filename specified for the input +device. +

+
+
graph_file
+

Set the filename of the filtergraph to be read and sent to the other +filters. Syntax of the filtergraph is the same as the one specified by +the option graph. +

+
+
dumpgraph
+

Dump graph to stderr. +

+
+
+ + +

18.11.2 Examples

+ +
    +
  • Create a color video stream and play it back with ffplay: +
    +
    ffplay -f lavfi -graph "color=c=pink [out0]" dummy
    +
    + +
  • As the previous example, but use filename for specifying the graph +description, and omit the "out0" label: +
    +
    ffplay -f lavfi color=c=pink
    +
    + +
  • Create three different video test filtered sources and play them: +
    +
    ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3
    +
    + +
  • Read an audio stream from a file using the amovie source and play it +back with ffplay: +
    +
    ffplay -f lavfi "amovie=test.wav"
    +
    + +
  • Read an audio stream and a video stream and play it back with +ffplay: +
    +
    ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"
    +
    + +
  • Dump decoded frames to images and Closed Captions to an RCWT backup: +
    +
    ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rcwt subcc.bin
    +
    + +
+ + +

18.12 libcdio

+ +

Audio-CD input device based on libcdio. +

+

To enable this input device during configuration you need libcdio +installed on your system. It requires the configure option +--enable-libcdio. +

+

This device allows playing and grabbing from an Audio-CD. +

+

For example to copy with ffmpeg the entire Audio-CD in /dev/sr0, +you may run the command: +

+
ffmpeg -f libcdio -i /dev/sr0 cd.wav
+
+ + +

18.12.1 Options

+
+
speed
+

Set drive reading speed. Default value is 0. +

+

The speed is specified CD-ROM speed units. The speed is set through +the libcdio cdio_cddap_speed_set function. On many CD-ROM +drives, specifying a value too large will result in using the fastest +speed. +

+
+
paranoia_mode
+

Set paranoia recovery mode flags. It accepts one of the following values: +

+
+
‘disable’
+
‘verify’
+
‘overlap’
+
‘neverskip’
+
‘full’
+
+ +

Default value is ‘disable’. +

+

For more information about the available recovery modes, consult the +paranoia project documentation. +

+
+ + +

18.13 libdc1394

+ +

IIDC1394 input device, based on libdc1394 and libraw1394. +

+

Requires the configure option --enable-libdc1394. +

+ +

18.13.1 Options

+
+
framerate
+

Set the frame rate. Default is ntsc, corresponding to a frame +rate of 30000/1001. +

+
+
pixel_format
+

Select the pixel format. Default is uyvy422. +

+
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Default is qvga. +

+
+ + +

18.14 openal

+ +

The OpenAL input device provides audio capture on all systems with a +working OpenAL 1.1 implementation. +

+

To enable this input device during configuration, you need OpenAL +headers and libraries installed on your system, and need to configure +FFmpeg with --enable-openal. +

+

OpenAL headers and libraries should be provided as part of your OpenAL +implementation, or as an additional download (an SDK). Depending on your +installation you may need to specify additional flags via the +--extra-cflags and --extra-ldflags for allowing the build +system to locate the OpenAL headers and libraries. +

+

An incomplete list of OpenAL implementations follows: +

+
+
Creative
+

The official Windows implementation, providing hardware acceleration +with supported devices and software fallback. +See http://openal.org/. +

+
OpenAL Soft
+

Portable, open source (LGPL) software implementation. Includes +backends for the most common sound APIs on the Windows, Linux, +Solaris, and BSD operating systems. +See http://kcat.strangesoft.net/openal.html. +

+
Apple
+

OpenAL is part of Core Audio, the official Mac OS X Audio interface. +See http://developer.apple.com/technologies/mac/audio-and-video.html +

+
+ +

This device allows one to capture from an audio input device handled +through OpenAL. +

+

You need to specify the name of the device to capture in the provided +filename. If the empty string is provided, the device will +automatically select the default device. You can get the list of the +supported devices by using the option list_devices. +

+ +

18.14.1 Options

+ +
+
channels
+

Set the number of channels in the captured audio. Only the values +1 (monaural) and 2 (stereo) are currently supported. +Defaults to 2. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. Only the values +8 and 16 are currently supported. Defaults to +16. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +Defaults to 44.1k. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. +

+
+
+ + +

18.14.2 Examples

+ +

Print the list of OpenAL supported devices and exit: +

+
$ ffmpeg -list_devices true -f openal -i dummy out.ogg
+
+ +

Capture from the OpenAL device DR-BT101 via PulseAudio: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg
+
+ +

Capture from the default device (note the empty string ” as filename): +

+
$ ffmpeg -f openal -i '' out.ogg
+
+ +

Capture from two devices simultaneously, writing to two different files, +within the same ffmpeg command: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg
+
+

Note: not all OpenAL implementations support multiple simultaneous capture - +try the latest OpenAL Soft if the above does not work. +

+ +

18.15 oss

+ +

Open Sound System input device. +

+

The filename to provide to the input device is the device node +representing the OSS input device, and is usually set to +/dev/dsp. +

+

For example to grab from /dev/dsp using ffmpeg use the +command: +

+
ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
+
+ +

For more information about OSS see: +http://manuals.opensound.com/usersguide/dsp.html +

+ +

18.15.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

18.16 pulse

+ +

PulseAudio input device. +

+

To enable this output device you need to configure FFmpeg with --enable-libpulse. +

+

The filename to provide to the input device is a source device or the +string "default" +

+

To list the PulseAudio source devices and their properties you can invoke +the command pactl list sources. +

+

More information about PulseAudio can be found on http://www.pulseaudio.org. +

+ +

18.16.1 Options

+
+
server
+

Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. +

+
+
name
+

Specify the application name PulseAudio will use when showing active clients, +by default it is the LIBAVFORMAT_IDENT string. +

+
+
stream_name
+

Specify the stream name PulseAudio will use when showing active streams, +by default it is "record". +

+
+
sample_rate
+

Specify the samplerate in Hz, by default 48kHz is used. +

+
+
channels
+

Specify the channels in use, by default 2 (stereo) is set. +

+
+
frame_size
+

This option does nothing and is deprecated. +

+
+
fragment_size
+

Specify the size in bytes of the minimal buffering fragment in PulseAudio, it +will affect the audio latency. By default it is set to 50 ms amount of data. +

+
+
wallclock
+

Set the initial PTS using the current time. Default is 1. +

+
+
+ + +

18.16.2 Examples

+

Record a stream from default device: +

+
ffmpeg -f pulse -i default /tmp/pulse.wav
+
+ + +

18.17 sndio

+ +

sndio input device. +

+

To enable this input device during configuration you need libsndio +installed on your system. +

+

The filename to provide to the input device is the device node +representing the sndio input device, and is usually set to +/dev/audio0. +

+

For example to grab from /dev/audio0 using ffmpeg use the +command: +

+
ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
+
+ + +

18.17.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

18.18 video4linux2, v4l2

+ +

Video4Linux2 input video device. +

+

"v4l2" can be used as alias for "video4linux2". +

+

If FFmpeg is built with v4l-utils support (by using the +--enable-libv4l2 configure option), it is possible to use it with the +-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 +(e.g. an USB webcam) is plugged into the system, and has a name of the +kind /dev/videoN, where N is a number associated to +the device. +

+

Video4Linux2 devices usually support a limited set of +widthxheight sizes and frame rates. You can check which are +supported using -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 -list_standards all. +

+

The time base for the timestamps is 1 microsecond. Depending on the kernel +version and configuration, the timestamps may be derived from the real time +clock (origin at the Unix Epoch) or the monotonic clock (origin usually at +boot time, unaffected by NTP or manual changes to the clock). The +-timestamps abs or -ts abs option can be used to force +conversion into the real time clock. +

+

Some usage examples of the video4linux2 device with ffmpeg +and ffplay: +

    +
  • List supported formats for a video4linux2 device: +
    +
    ffplay -f video4linux2 -list_formats all /dev/video0
    +
    + +
  • Grab and show the input of a video4linux2 device: +
    +
    ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
    +
    + +
  • Grab and record the input of a video4linux2 device, leave the +frame rate and size as previously set: +
    +
    ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
    +
    +
+ +

For more information about Video4Linux, check http://linuxtv.org/. +

+ +

18.18.1 Options

+ +
+
standard
+

Set the standard. Must be the name of a supported standard. To get a +list of the supported standards, use the list_standards +option. +

+
+
channel
+

Set the input channel number. Default to -1, which means using the +previously selected channel. +

+
+
video_size
+

Set the video frame size. The argument must be a string in the form +WIDTHxHEIGHT or a valid size abbreviation. +

+
+
pixel_format
+

Select the pixel format (only valid for raw video input). +

+
+
input_format
+

Set the preferred pixel format (for raw video) or a codec name. +This option allows one to select the input format, when several are +available. +

+
+
framerate
+

Set the preferred video frame rate. +

+
+
list_formats
+

List available formats (supported pixel formats, codecs, and frame +sizes) and exit. +

+

Available values are: +

+
‘all’
+

Show all available (compressed and non-compressed) formats. +

+
+
‘raw’
+

Show only raw video (non-compressed) formats. +

+
+
‘compressed’
+

Show only compressed formats. +

+
+ +
+
list_standards
+

List supported standards and exit. +

+

Available values are: +

+
‘all’
+

Show all supported standards. +

+
+ +
+
timestamps, ts
+

Set type of timestamps for grabbed frames. +

+

Available values are: +

+
‘default’
+

Use timestamps from the kernel. +

+
+
‘abs’
+

Use absolute timestamps (wall clock). +

+
+
‘mono2abs’
+

Force conversion from monotonic to absolute timestamps. +

+
+ +

Default value is default. +

+
+
use_libv4l2
+

Use libv4l2 (v4l-utils) conversion functions. Default is 0. +

+
+
+ + +

18.19 vfwcap

+ +

VfW (Video for Windows) capture input device. +

+

The filename passed as input is the capture driver number, ranging from +0 to 9. You may use "list" as filename to print a list of drivers. Any +other filename will be interpreted as device number 0. +

+ +

18.19.1 Options

+ +
+
video_size
+

Set the video frame size. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
+ + +

18.20 x11grab

+ +

X11 video input device. +

+

To enable this input device during configuration you need libxcb +installed on your system. It will be automatically detected during +configuration. +

+

This device allows one to capture a region of an X11 display. +

+

The filename passed as input has the syntax: +

+
[hostname]:display_number.screen_number[+x_offset,y_offset]
+
+ +

hostname:display_number.screen_number specifies the +X11 display name of the screen to grab from. hostname can be +omitted, and defaults to "localhost". The environment variable +DISPLAY contains the default display name. +

+

x_offset and y_offset specify the offsets of the grabbed +area with respect to the top-left border of the X11 screen. They +default to 0. +

+

Check the X11 documentation (e.g. man X) for more detailed +information. +

+

Use the xdpyinfo program for getting basic information about +the properties of your X11 display (e.g. grep for "name" or +"dimensions"). +

+

For example to grab from :0.0 using ffmpeg: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

Grab at position 10,20: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ + +

18.20.1 Options

+ +
+
select_region
+

Specify whether to select the grabbing area graphically using the pointer. +A value of 1 prompts the user to select the grabbing area graphically +by clicking and dragging. A single click with no dragging will select the +whole screen. A region with zero width or height will also select the whole +screen. This option overwrites the video_size, grab_x, and +grab_y options. Default value is 0. +

+
+
draw_mouse
+

Specify whether to draw the mouse pointer. A value of 0 specifies +not to draw the pointer. Default value is 1. +

+
+
follow_mouse
+

Make the grabbed area follow the mouse. The argument can be +centered or a number of pixels PIXELS. +

+

When it is specified with "centered", the grabbing region follows the mouse +pointer and keeps the pointer at the center of region; otherwise, the region +follows only when the mouse pointer reaches within PIXELS (greater than +zero) to the edge of region. +

+

For example: +

+
ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

To follow only when the mouse pointer reaches within 100 pixels to edge: +

+
ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+
+
region_border
+

Set the region border thickness if -show_region 1 is used. +Range is 1 to 128 and default is 3 (XCB-based x11grab only). +

+

For example: +

+
ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ +

With follow_mouse: +

+
ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
window_id
+

Grab this window, instead of the whole screen. Default value is 0, which maps to +the whole screen (root window). +

+

The id of a window can be found using the xwininfo program, possibly with options -tree and +-root. +

+

If the window is later enlarged, the new area is not recorded. Video ends when +the window is closed, unmapped (i.e., iconified) or shrunk beyond the video +size (which defaults to the initial window size). +

+

This option disables options follow_mouse and select_region. +

+
+
video_size
+

Set the video frame size. Default is the full desktop or window. +

+
+
grab_x
+
grab_y
+

Set the grabbing region coordinates. They are expressed as offset from +the top left corner of the X11 window and correspond to the +x_offset and y_offset parameters in the device name. The +default value for both options is 0. +

+
+ + +

19 Resampler Options

+ +

The audio resampler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, option=value for the aresample filter, +by setting the value explicitly in the +SwrContext options or using the libavutil/opt.h API for +programmatic use. +

+
+
uchl, used_chlayout
+

Set used input channel layout. Default is unset. This option is +only used for special remapping. +

+
+
isr, in_sample_rate
+

Set the input sample rate. Default value is 0. +

+
+
osr, out_sample_rate
+

Set the output sample rate. Default value is 0. +

+
+
isf, in_sample_fmt
+

Specify the input sample format. It is set by default to none. +

+
+
osf, out_sample_fmt
+

Specify the output sample format. It is set by default to none. +

+
+
tsf, internal_sample_fmt
+

Set the internal sample format. Default value is none. +This will automatically be chosen when it is not explicitly set. +

+
+
ichl, in_chlayout
+
ochl, out_chlayout
+

Set the input/output channel layout. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
clev, center_mix_level
+

Set the center mix level. It is a value expressed in deciBel, and must be +in the interval [-32,32]. +

+
+
slev, surround_mix_level
+

Set the surround mix level. It is a value expressed in deciBel, and must +be in the interval [-32,32]. +

+
+
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]. +

+
+
rmvol, rematrix_volume
+

Set rematrix volume. Default value is 1.0. +

+
+
rematrix_maxval
+

Set maximum output value for rematrixing. +This can be used to prevent clipping vs. preventing volume reduction. +A value of 1.0 prevents clipping. +

+
+
flags, swr_flags
+

Set flags used by the converter. Default value is 0. +

+

It supports the following individual flags: +

+
res
+

force resampling, this flag forces resampling to be used even when the +input and output sample rates match. +

+
+ +
+
dither_scale
+

Set the dither scale. Default value is 1. +

+
+
dither_method
+

Set dither method. Default value is 0. +

+

Supported values: +

+
‘rectangular’
+

select rectangular dither +

+
‘triangular’
+

select triangular dither +

+
‘triangular_hp’
+

select triangular dither with high pass +

+
‘lipshitz’
+

select Lipshitz noise shaping dither. +

+
‘shibata’
+

select Shibata noise shaping dither. +

+
‘low_shibata’
+

select low Shibata noise shaping dither. +

+
‘high_shibata’
+

select high Shibata noise shaping dither. +

+
‘f_weighted’
+

select f-weighted noise shaping dither +

+
‘modified_e_weighted’
+

select modified-e-weighted noise shaping dither +

+
‘improved_e_weighted’
+

select improved-e-weighted noise shaping dither +

+
+
+ +
+
resampler
+

Set resampling engine. Default value is swr. +

+

Supported values: +

+
‘swr’
+

select the native SW Resampler; filter options precision and cheby are not +applicable in this case. +

+
‘soxr’
+

select the SoX Resampler (where available); compensation, and filter options +filter_size, phase_shift, exact_rational, filter_type & kaiser_beta, are not +applicable in this case. +

+
+ +
+
filter_size
+

For swr only, set resampling filter size, default value is 32. +

+
+
phase_shift
+

For swr only, set resampling phase shift, default value is 10, and must be in +the interval [0,30]. +

+
+
linear_interp
+

Use linear interpolation when enabled (the default). Disable it if you want +to preserve speed instead of quality when exact_rational fails. +

+
+
exact_rational
+

For swr only, when enabled, try to use exact phase_count based on input and +output sample rate. However, if it is larger than 1 << phase_shift, +the phase_count will be 1 << phase_shift as fallback. Default is enabled. +

+
+
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). +

+
+
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’. +

+
+
cheby
+

For soxr only, selects passband rolloff none (Chebyshev) & higher-precision +approximation for ’irrational’ ratios. Default value is 0. +

+
+
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. +

+
+
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. +

+
+
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 +(min_comp = FLT_MAX). +

+
+
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 min_comp. +The default is 0.1. +

+
+
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. +

+
+
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. +

+
+
matrix_encoding
+

Select matrixed stereo encoding. +

+

It accepts the following values: +

+
‘none’
+

select none +

+
‘dolby’
+

select Dolby +

+
‘dplii’
+

select Dolby Pro Logic II +

+
+ +

Default value is none. +

+
+
filter_type
+

For swr only, select resampling filter type. This only affects resampling +operations. +

+

It accepts the following values: +

+
‘cubic’
+

select cubic +

+
‘blackman_nuttall’
+

select Blackman Nuttall windowed sinc +

+
‘kaiser’
+

select Kaiser windowed sinc +

+
+ +
+
kaiser_beta
+

For swr only, set Kaiser window beta value. Must be a double float value in the +interval [2,16], default value is 9. +

+
+
output_sample_bits
+

For swr only, set number of used output sample bits for dithering. Must be an integer in the +interval [0,64], default value is 0, which means it’s not used. +

+
+
+ + +

20 Scaler Options

+ +

The video scaler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, with a few API-only exceptions noted below. +For programmatic use, they can be set explicitly in the +SwsContext options or through the libavutil/opt.h API. +

+
+
+
+
sws_flags
+

Set the scaler flags. This is also used to set the scaling +algorithm. Only a single algorithm should be selected. Default +value is ‘bicubic’. +

+

It accepts the following values: +

+
‘fast_bilinear’
+

Select fast bilinear scaling algorithm. +

+
+
‘bilinear’
+

Select bilinear scaling algorithm. +

+
+
‘bicubic’
+

Select bicubic scaling algorithm. +

+
+
‘experimental’
+

Select experimental scaling algorithm. +

+
+
‘neighbor’
+

Select nearest neighbor rescaling algorithm. +

+
+
‘area’
+

Select averaging area rescaling algorithm. +

+
+
‘bicublin’
+

Select bicubic scaling algorithm for the luma component, bilinear for +chroma components. +

+
+
‘gauss’
+

Select Gaussian rescaling algorithm. +

+
+
‘sinc’
+

Select sinc rescaling algorithm. +

+
+
‘lanczos’
+

Select Lanczos rescaling algorithm. The default width (alpha) is 3 and can be +changed by setting param0. +

+
+
‘spline’
+

Select natural bicubic spline rescaling algorithm. +

+
+
‘print_info’
+

Enable printing/debug logging. +

+
+
‘accurate_rnd’
+

Enable accurate rounding. +

+
+
‘full_chroma_int’
+

Enable full chroma interpolation. +

+
+
‘full_chroma_inp’
+

Select full chroma input. +

+
+
‘bitexact’
+

Enable bitexact output. +

+
+
‘unstable’
+

Allow the use of experimental new code. May subtly affect the output or even +produce wrong results. For testing only. +

+
+ +
+
srcw (API only)
+

Set source width. +

+
+
srch (API only)
+

Set source height. +

+
+
dstw (API only)
+

Set destination width. +

+
+
dsth (API only)
+

Set destination height. +

+
+
src_format (API only)
+

Set source pixel format (must be expressed as an integer). +

+
+
dst_format (API only)
+

Set destination pixel format (must be expressed as an integer). +

+
+
src_range (boolean)
+

If value is set to 1, indicates source is full range. Default value is +0, which indicates source is limited range. +

+
+
dst_range (boolean)
+

If value is set to 1, enable full range for destination. Default value +is 0, which enables limited range. +

+
+
gamma (boolean)
+

If value is set to 1, enable gamma correct scaling. Default value is 0. +

+
+
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. +

+
+
sws_dither
+

Set the dithering algorithm. Accepts one of the following +values. Default value is ‘auto’. +

+
+
‘auto’
+

automatic choice +

+
+
‘none’
+

no dithering +

+
+
‘bayer’
+

bayer dither +

+
+
‘ed’
+

error diffusion dither +

+
+
‘a_dither’
+

arithmetic dither, based using addition +

+
+
‘x_dither’
+

arithmetic dither, based using xor (more random/less apparent patterning that +a_dither). +

+
+
+ +
+
alphablend
+

Set the alpha blending to use when the input has alpha but the output does not. +Default value is ‘none’. +

+
+
‘uniform_color’
+

Blend onto a uniform background color +

+
+
‘checkerboard’
+

Blend onto a checkerboard +

+
+
‘none’
+

No blending +

+
+
+ +
+
+ + +

21 Filtering Introduction

+ +

Filtering in FFmpeg is enabled through the libavfilter library. +

+

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. +

+
                [main]
+input --> split ---------------------> overlay --> output
+            |                             ^
+            |[tmp]                  [flip]|
+            +-----> crop --> vflip -------+
+
+

This filtergraph splits the input stream in two streams, then 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: +

+
+
ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
+
+ +

The result will be that the top half of the video is mirrored +onto the bottom half of the output video. +

+

Filters in the same linear chain are separated by commas, and distinct +linear chains of filters are separated by semicolons. In our example, +crop,vflip are in one linear chain, split and +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 [main] and [tmp]. +

+

The stream sent to the second output of split, labelled as +[tmp], is processed through the crop filter, which crops +away the lower half part of the video, and then vertically flipped. The +overlay filter takes in input the first unchanged output of the +split filter (which was labelled as [main]), and overlay on its +lower half the output generated by the 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 +by a colon. +

+

There exist so-called source filters that do not have an +audio/video input, and sink filters that will not have audio/video +output. +

+ + +

22 graph2dot

+ +

The graph2dot program included in the FFmpeg tools +directory can be used to parse a filtergraph description and issue a +corresponding textual representation in the dot language. +

+

Invoke the command: +

+
graph2dot -h
+
+ +

to see how to use graph2dot. +

+

You can then pass the dot description to the dot program (from +the graphviz suite of programs) and obtain a graphical representation +of the filtergraph. +

+

For example the sequence of commands: +

+
echo GRAPH_DESCRIPTION | \
+tools/graph2dot -o graph.tmp && \
+dot -Tpng graph.tmp -o graph.png && \
+display graph.png
+
+ +

can be used to create and display an image representing the graph +described by the GRAPH_DESCRIPTION string. Note that this string must be +a complete self-contained graph, with its inputs and outputs explicitly defined. +For example if your command line is of the form: +

+
ffmpeg -i infile -vf scale=640:360 outfile
+
+

your GRAPH_DESCRIPTION string will need to be of the form: +

+
nullsrc,scale=640:360,nullsink
+
+

you may also need to set the nullsrc parameters and add a format +filter in order to simulate a specific input file. +

+ + +

23 Filtergraph description

+ +

A filtergraph is a directed graph of connected filters. It can contain +cycles, and there can be multiple links between a pair of +filters. Each link has one input pad on one side connecting it to one +filter from which it takes its input, and one output pad on the other +side connecting it to one filter accepting its output. +

+

Each filter in a filtergraph is an instance of a filter class +registered in the application, which defines the features and the +number of input and output pads of the filter. +

+

A filter with no input pads is called a "source", and a filter with no +output pads is called a "sink". +

+ +

23.1 Filtergraph syntax

+ +

A filtergraph has a textual representation, which is recognized by the +-filter/-vf/-af and +-filter_complex options in ffmpeg and +-vf/-af in ffplay, and by the +avfilter_graph_parse_ptr() function defined in +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 +represented by a list of ","-separated filter descriptions. +

+

A filtergraph consists of a sequence of filterchains. A sequence of +filterchains is represented by a list of ";"-separated filterchain +descriptions. +

+

A filter is represented by a string of the form: +[in_link_1]...[in_link_N]filter_name@id=arguments[out_link_1]...[out_link_M] +

+

filter_name is the name of the filter class of which the +described filter is an instance of, and has to be the name of one of +the filter classes registered in the program optionally followed by "@id". +The name of the filter class is optionally followed by a string +"=arguments". +

+

arguments is a string which contains the parameters used to +initialize the filter instance. It may have one of two forms: +

    +
  • A ’:’-separated list of key=value pairs. + +
  • A ’:’-separated list of value. In this case, the keys are assumed to be +the option names in the order they are declared. E.g. the fade filter +declares three options in this order – type, start_frame and +nb_frames. Then the parameter list in:0:30 means that the value +in is assigned to the option type, 0 to +start_frame and 30 to nb_frames. + +
  • A ’:’-separated list of mixed direct value and long key=value +pairs. The direct value must precede the key=value pairs, and +follow the same constraints order of the previous point. The following +key=value pairs can be set in any preferred order. + +
+ +

If the option value itself is a list of items (e.g. the 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 +within the quoted text; otherwise the argument string is considered +terminated when the next special character (belonging to the set +‘[]=;,’) is encountered. +

+

A special syntax implemented in the ffmpeg CLI tool allows loading +option values from files. This is done be prepending a slash ’/’ to the option +name, then the supplied value is interpreted as a path from which the actual +value is loaded. E.g. +

+
ffmpeg -i <INPUT> -vf drawtext=/text=/tmp/some_text <OUTPUT>
+
+

will load the text to be drawn from /tmp/some_text. API users wishing to +implement a similar feature should use the avfilter_graph_segment_*() +functions together with custom IO code. +

+

The name and arguments of the filter are optionally preceded and +followed by a list of link labels. +A link label allows one to name a link and associate it to a filter output +or input pad. The preceding labels in_link_1 +... in_link_N, are associated to the filter input pads, +the following labels out_link_1 ... out_link_M, are +associated to the output pads. +

+

When two link labels with the same name are found in the +filtergraph, a link between the corresponding input and output pad is +created. +

+

If an output pad is not labelled, it is linked by default to the first +unlabelled input pad of the next filter in the filterchain. +For example in the filterchain +

+
nullsrc, split[L1], [L2]overlay, nullsink
+
+

the split filter instance has two output pads, and the overlay filter +instance two input pads. The first output pad of split is labelled +"L1", the first input pad of overlay is labelled "L2", and the second +output pad of split is linked to the second input pad of overlay, +which are both unlabelled. +

+

In a filter description, if the input label of the first filter is not +specified, "in" is assumed; if the output label of the last filter is not +specified, "out" is assumed. +

+

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. +

+

Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens +in the filtergraph specification are ignored. This means that the filtergraph +can be expressed using empty lines and spaces to improve readability. +

+

For example, the filtergraph: +

+
testsrc,split[L1],hflip[L2];[L1][L2] hstack
+
+ +

can be represented as: +

+
testsrc,
+split [L1], hflip [L2];
+
+[L1][L2] hstack
+
+ +

Libavfilter will automatically insert scale filters where format +conversion is required. It is possible to specify swscale flags +for those automatically inserted scalers by prepending +sws_flags=flags; +to the filtergraph description. +

+

Here is a BNF description of the filtergraph syntax: +

+
NAME             ::= sequence of alphanumeric characters and '_'
+FILTER_NAME      ::= NAME["@"NAME]
+LINKLABEL        ::= "[" NAME "]"
+LINKLABELS       ::= LINKLABEL [LINKLABELS]
+FILTER_ARGUMENTS ::= sequence of chars (possibly quoted)
+FILTER           ::= [LINKLABELS] FILTER_NAME ["=" FILTER_ARGUMENTS] [LINKLABELS]
+FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
+FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]
+
+ + +

23.2 Notes on filtergraph escaping

+ +

Filtergraph description composition entails several levels of +escaping. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual for more +information about the employed escaping procedure. +

+

A first level escaping affects the content of each filter option +value, which may contain the special character : used to +separate values, or one of the escaping characters \'. +

+

A second level escaping affects the whole filter description, which +may contain the escaping characters \' or the special +characters [],; used by the filtergraph description. +

+

Finally, when you specify a filtergraph on a shell commandline, you +need to perform a third level escaping for the shell special +characters contained within it. +

+

For example, consider the following string to be embedded in +the drawtext filter description text value: +

+
this is a 'string': may contain one, or more, special characters
+
+ +

This string contains the ' special escaping character, and the +: special character, so it needs to be escaped in this way: +

+
text=this is a \'string\'\: may contain one, or more, special characters
+
+ +

A second level of escaping is required when embedding the filter +description in a filtergraph description, in order to escape all the +filtergraph special characters. Thus the example above becomes: +

+
drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
+
+

(note that in addition to the \' escaping special characters, +also , needs to be escaped). +

+

Finally an additional level of escaping is needed when writing the +filtergraph description in a shell command, which depends on the +escaping rules of the adopted shell. For example, assuming that +\ is special and needs to be escaped with another \, the +previous string will finally result in: +

+
-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
+
+ +

In order to avoid cumbersome escaping when using a commandline tool accepting a +filter specification as input, it is advisable to avoid direct inclusion of the +filter or options specification in the shell. +

+

For example, in case of the drawtext filter, you might prefer to +use the textfile option in place of text to specify the text +to render. +

+ +

24 Timeline editing

+ +

Some filters support a generic 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: +

+
‘t’
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
‘n’
+

sequential number of the input frame, starting from 0 +

+
+
‘pos’
+

the position in the file of the input frame, NAN if unknown; deprecated, do +not use +

+
+
‘w’
+
‘h’
+

width and height of the input frame if video +

+
+ +

Additionally, these filters support an enable command that can be used +to re-define the expression. +

+

Like any other filtering option, the enable option follows the same +rules. +

+

For example, to enable a blur filter (smartblur) from 10 seconds to 3 +minutes, and a curves filter starting at 3 seconds: +

+
smartblur = enable='between(t,10,3*60)',
+curves    = enable='gte(t,3)' : preset=cross_process
+
+ +

See ffmpeg -filters to view which filters have timeline support. +

+ + +

25 Changing options at runtime with a command

+ +

Some options can be changed during the operation of the filter using +a command. These options are marked ’T’ on the output of +ffmpeg -h filter=<name of filter>. +The name of the command is the name of the option and the argument is +the new value. +

+ +

26 Options for filters with several inputs (framesync)

+ +

Some filters with several inputs support a common set of options. +These options can only be set by name, not with the short notation. +

+
+
eof_action
+

The action to take when EOF is encountered on the secondary input; it accepts +one of the following values: +

+
+
repeat
+

Repeat the last frame (the default). +

+
endall
+

End both streams. +

+
pass
+

Pass the main input through. +

+
+ +
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
repeatlast
+

If set to 1, force the filter to extend the last frame of secondary streams +until the end of the primary stream. A value of 0 disables this behavior. +Default value is 1. +

+
+
ts_sync_mode
+

How strictly to sync streams based on secondary input timestamps; it accepts +one of the following values: +

+
+
default
+

Frame from secondary input with the nearest lower or equal timestamp to the +primary input frame. +

+
nearest
+

Frame from secondary input with the absolute nearest timestamp to the primary +input frame. +

+
+
+
+ + + +

27 Audio Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the audio filters included in your +build. +

+

Below is a description of the currently available audio filters. +

+ +

27.1 aap

+

Apply Affine Projection algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to estimate unknown audio based on multiple input audio samples. +Affine projection algorithm can make trade-offs between computation complexity with convergence speed. +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
projection
+

Set the projection order. +

+
+
mu
+

Set the filter mu. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

27.2 acompressor

+ +

A compressor is mainly used to reduce the dynamic range of a signal. +Especially modern music is mostly compressed at a high ratio to +improve the overall loudness. It’s done to get the highest attention +of a listener, "fatten" the sound and bring more "power" to the track. +If a signal is compressed too much it may sound dull or "dead" +afterwards or it may start to "pump" (which could be a powerful effect +but can also destroy a track completely). +The right compression is the key to reach a professional sound and is +the high art of mixing and mastering. Because of its complex settings +it may take a long time to get the right feeling for this kind of effect. +

+

Compression is done by detecting the volume above a chosen level +threshold and dividing it by the factor set with ratio. +So if you set the threshold to -12dB and your signal reaches -6dB a ratio +of 2:1 will result in a signal at -9dB. Because an exact manipulation of +the signal would cause distortion of the waveform the reduction can be +levelled over the time. This is done by setting "Attack" and "Release". +attack determines how long the signal has to rise above the threshold +before any reduction will occur and release sets the time the signal +has to fall below the threshold to reduce the reduction again. Shorter signals +than the chosen attack time will be left untouched. +The overall reduction of the signal can be made up afterwards with the +makeup setting. So compressing the peaks of a signal about 6dB and +raising the makeup to this level results in a signal twice as loud than the +source. To gain a softer entry in the compression the knee flattens the +hard edge at the threshold in the range of the chosen decibels. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of stream rises above this level it will affect the gain +reduction. +By default it is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. 1:2 means that if the level +rose 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of input stream +or the louder(maximum) channel of input stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mostly smoother. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

27.2.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.3 acontrast

+

Simple audio dynamic range compression/expansion filter. +

+

The filter accepts the following options: +

+
+
contrast
+

Set contrast. Default is 33. Allowed range is between 0 and 100. +

+
+ + +

27.4 acopy

+ +

Copy the input audio source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

27.5 acrossfade

+ +

Apply cross fade from one input audio stream to another input audio stream. +The cross fade is applied for specified duration near the end of first stream. +

+

The filter accepts the following options: +

+
+
inputs, n
+

Specify the number of inputs to crossfade. When crossfading multiple inputs, +each input will be concatenated and crossfaded in sequence, similar to the +concat filter. Default is 2. +

+
+
nb_samples, ns
+

Specify the number of samples for which the cross fade effect has to last. +At the end of the cross fade effect the first input audio will be completely +silent. Default is 44100. +

+
+
duration, d
+

Specify the duration of the cross fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
overlap, o
+

Should first stream end overlap with second stream start. Default is enabled. +

+
+
curve1
+

Set curve for cross fade transition for first stream. +

+
+
curve2
+

Set curve for cross fade transition for second stream. +

+

For description of available curve types see afade filter description. +

+
+ + +

27.5.1 Examples

+ +
    +
  • Cross fade from one input to another: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
    +
    + +
  • Cross fade from one input to another but without overlapping: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
    +
    + +

    Concatenate multiple inputs with cross fade between each: +

    +
    ffmpeg -i first.flac -i second.flac -i third.flac -filter_complex acrossfade=n=3 output.flac
    +
    +
+ + +

27.6 acrossover

+

Split audio stream into several bands. +

+

This filter splits audio stream into two or more frequency ranges. +Summing all streams back will give flat output. +

+

The filter accepts the following options: +

+
+
split
+

Set split frequencies. Those must be positive and increasing. +

+
+
order
+

Set filter order for each band split. This controls filter roll-off or steepness +of filter transfer function. +Available values are: +

+
+
‘2nd’
+

12 dB per octave. +

+
‘4th’
+

24 dB per octave. +

+
‘6th’
+

36 dB per octave. +

+
‘8th’
+

48 dB per octave. +

+
‘10th’
+

60 dB per octave. +

+
‘12th’
+

72 dB per octave. +

+
‘14th’
+

84 dB per octave. +

+
‘16th’
+

96 dB per octave. +

+
‘18th’
+

108 dB per octave. +

+
‘20th’
+

120 dB per octave. +

+
+ +

Default is 4th. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+
gains
+

Set output gain for each band. Default value is 1 for all bands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+ + +

27.6.1 Examples

+ +
    +
  • Split input audio stream into two bands (low and high) with split frequency of 1500 Hz, +each band will be in separate stream: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but with higher filter order: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but also with additional middle band (frequencies between 1500 and 8000): +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav
    +
    +
+ + +

27.7 acrusher

+ +

Reduce audio bit resolution. +

+

This filter is bit crusher with enhanced functionality. A bit crusher +is used to audibly reduce number of bits an audio signal is sampled +with. This doesn’t change the bit depth at all, it just produces the +effect. Material reduced in bit depth sounds more harsh and "digital". +This filter is able to even round to continuous values instead of discrete +bit depths. +Additionally it has a D/C offset which results in different crushing of +the lower and the upper half of the signal. +An Anti-Aliasing setting is able to produce "softer" crushing sounds. +

+

Another feature of this filter is the logarithmic mode. +This setting switches from linear distances between bits to logarithmic ones. +The result is a much more "natural" sounding crusher which doesn’t gate low +signals for example. The human ear has a logarithmic perception, +so this kind of crushing is much more pleasant. +Logarithmic crushing is also able to get anti-aliased. +

+

The filter accepts the following options: +

+
+
level_in
+

Set level in. +

+
+
level_out
+

Set level out. +

+
+
bits
+

Set bit reduction. +

+
+
mix
+

Set mixing amount. +

+
+
mode
+

Can be linear: lin or logarithmic: log. +

+
+
dc
+

Set DC. +

+
+
aa
+

Set anti-aliasing. +

+
+
samples
+

Set sample reduction. +

+
+
lfo
+

Enable LFO. By default disabled. +

+
+
lforange
+

Set LFO range. +

+
+
lforate
+

Set LFO rate. +

+
+ + +

27.7.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.8 acue

+ +

Delay audio filtering until a given wallclock timestamp. See the cue +filter. +

+ +

27.9 adeclick

+

Remove impulsive noise from input audio. +

+

Samples detected as impulsive noise are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to +100. Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from +50 to 95. Default value is 75 percent. +Setting this to a very high value increases impulsive noise removal but makes +whole process much slower. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 2 percent. This option also +controls quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 2. +This controls the strength of impulsive noise which is going to be removed. +The lower value, the more samples will be detected as impulsive noise. +

+
+
burst, b
+

Set burst fusion, in percentage of window size. Allowed range is 0 to +10. Default value is 2. +If any two samples detected as noise are spaced less than this value then any +sample between those two samples will be also detected as noise. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly +changed with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

27.10 adeclip

+

Remove clipped samples from input audio. +

+

Samples detected as clipped are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to 100. +Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from 50 +to 95. Default value is 75 percent. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 8 percent. This option also controls +quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 10. Higher values make clip detection less aggressive. +

+
+
hsize, n
+

Set size of histogram used to detect clips. Allowed range is from 100 to 9999. +Default value is 1000. Higher values make clip detection less aggressive. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly changed +with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

27.11 adecorrelate

+

Apply decorrelation to input audio stream. +

+

The filter accepts the following options: +

+
+
stages
+

Set decorrelation stages of filtering. Allowed +range is from 1 to 16. Default value is 6. +

+
+
seed
+

Set random seed used for setting delay in samples across channels. +

+
+ + +

27.12 adelay

+ +

Delay one or more audio channels. +

+

Samples in delayed channel are filled with silence. +

+

The filter accepts the following option: +

+
+
delays
+

Set list of delays in milliseconds for each channel separated by ’|’. +Unused delays will be silently ignored. If number of given delays is +smaller than number of channels all remaining channels will not be delayed. +If you want to delay exact number of samples, append ’S’ to number. +If you want instead to delay in seconds, append ’s’ to number. +

+
+
all
+

Use last set delay for all remaining channels. By default is disabled. +This option if enabled changes how option delays is interpreted. +

+
+ + +

27.12.1 Examples

+ +
    +
  • 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. +
    +
    adelay=1500|0|500
    +
    + +
  • Delay second channel by 500 samples, the third channel by 700 samples and leave +the first channel (and any other channels that may be present) unchanged. +
    +
    adelay=0|500S|700S
    +
    + +
  • Delay all channels by same number of samples: +
    +
    adelay=delays=64S:all=1
    +
    +
+ + +

27.13 adenorm

+

Remedy denormals in audio by adding extremely low-level noise. +

+

This filter shall be placed before any filter that can produce denormals. +

+

A description of the accepted parameters follows. +

+
+
level
+

Set level of added noise in dB. Default is -351. +Allowed range is from -451 to -90. +

+
+
type
+

Set type of added noise. +

+
+
dc
+

Add DC signal. +

+
ac
+

Add AC signal. +

+
square
+

Add square signal. +

+
pulse
+

Add pulse signal. +

+
+ +

Default is dc. +

+
+ + +

27.13.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.14 aderivative, aintegral

+ +

Compute derivative/integral of audio stream. +

+

Applying both filters one after another produces original audio. +

+ +

27.15 adrc

+ +

Apply spectral dynamic range controller filter to input audio stream. +

+

A description of the accepted options follows. +

+
+
transfer
+

Set the transfer expression. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frequency power value, in dB +

+
+
f
+

current frequency in Hz +

+
+ +

Default value is p. +

+
+
attack
+

Set the attack in milliseconds. Default is 50 milliseconds. +Allowed range is from 1 to 1000 milliseconds. +

+
release
+

Set the release in milliseconds. Default is 100 milliseconds. +Allowed range is from 5 to 2000 milliseconds. +

+
channels
+

Set which channels to filter, by default all channels in audio stream are filtered. +

+
+ + +

27.15.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.15.2 Examples

+ +
    +
  • Apply spectral compression to all frequencies with threshold of -50 dB and 1:6 ratio: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/6,p)':attack=50:release=100
    +
    + +
  • Similar to above but with 1:2 ratio and filtering only front center channel: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/2,p)':attack=50:release=100:channels=FC
    +
    + +
  • Apply spectral noise gate to all frequencies with threshold of -85 dB and with short attack time and short release time: +
    +
    adrc=transfer='if(lte(p,-85),p-800,p)':attack=1:release=5
    +
    + +
  • Apply spectral expansion to all frequencies with threshold of -10 dB and 1:2 ratio: +
    +
    adrc=transfer='if(lt(p,-10),-10+(p-(-10))*2,p)':attack=50:release=100
    +
    + +
  • Apply limiter to max -60 dB to all frequencies, with attack of 2 ms and release of 10 ms: +
    +
    adrc=transfer='min(p,-60)':attack=2:release=10
    +
    +
+ + +

27.16 adynamicequalizer

+ +

Apply dynamic equalization to input audio stream. +

+

A description of the accepted options follows. +

+
+
threshold
+

Set the detection threshold used to trigger equalization. +Threshold detection is using detection filter. +Default value is 0. Allowed range is from 0 to 100. +

+
+
dfrequency
+

Set the detection frequency in Hz used for detection filter used to trigger equalization. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
dqfactor
+

Set the detection resonance factor for detection filter used to trigger equalization. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
tfrequency
+

Set the target frequency of equalization filter. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
tqfactor
+

Set the target resonance factor for target equalization filter. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
attack
+

Set the amount of milliseconds the signal from detection has to rise above +the detection threshold before equalization starts. +Default is 20. Allowed range is between 1 and 2000. +

+
+
release
+

Set the amount of milliseconds the signal from detection has to fall below the +detection threshold before equalization ends. +Default is 200. Allowed range is between 1 and 2000. +

+
+
ratio
+

Set the ratio by which the equalization gain is raised. +Default is 1. Allowed range is between 0 and 30. +

+
+
makeup
+

Set the makeup offset by which the equalization gain is raised. +Default is 0. Allowed range is between 0 and 100. +

+
+
range
+

Set the max allowed cut/boost amount. Default is 50. +Allowed range is from 1 to 200. +

+
+
mode
+

Set the mode of filter operation, can be one of the following: +

+
+
‘listen’
+

Output only isolated detection signal. +

+
‘cutbelow’
+

Cut frequencies below detection threshold. +

+
‘cutabove’
+

Cut frequencies above detection threshold. +

+
‘boostbelow’
+

Boost frequencies below detection threshold. +

+
‘boostabove’
+

Boost frequencies above detection threshold. +

+
+

Default mode is ‘cutbelow’. +

+
+
dftype
+

Set the type of detection filter, can be one of the following: +

+
+
‘bandpass’
+
‘lowpass’
+
‘highpass’
+
‘peak’
+
+

Default type is ‘bandpass’. +

+
+
tftype
+

Set the type of target filter, can be one of the following: +

+
+
‘bell’
+
‘lowshelf’
+
‘highshelf’
+
+

Default type is ‘bell’. +

+
+
auto
+

Automatically gather threshold from detection filter. By default +is ‘disabled’. +This option is useful to detect threshold in certain time frame of +input audio stream, in such case option value is changed at runtime. +

+

Available values are: +

+
‘disabled’
+

Disable using automatically gathered threshold value. +

+
‘off’
+

Stop picking threshold value. +

+
‘on’
+

Start picking threshold value. +

+
‘adaptive’
+

Adaptively pick threshold value, by calculating sliding window entropy. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

27.16.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.17 adynamicsmooth

+ +

Apply dynamic smoothing to input audio stream. +

+

A description of the accepted options follows. +

+
+
sensitivity
+

Set an amount of sensitivity to frequency fluctations. Default is 2. +Allowed range is from 0 to 1e+06. +

+
+
basefreq
+

Set a base frequency for smoothing. Default value is 22050. +Allowed range is from 2 to 1e+06. +

+
+ + +

27.17.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.18 aecho

+ +

Apply echoing to the input audio. +

+

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 delay, and the +loudness of the reflected signal is the decay. +Multiple echoes can have different delays and decays. +

+

A description of the accepted parameters follows. +

+
+
in_gain
+

Set input gain of reflected signal. Default is 0.6. +

+
+
out_gain
+

Set output gain of reflected signal. Default is 0.3. +

+
+
delays
+

Set list of time intervals in milliseconds between original signal and reflections +separated by ’|’. Allowed range for each delay is (0 - 90000.0]. +Default is 1000. +

+
+
decays
+

Set list of loudness of reflected signals separated by ’|’. +Allowed range for each decay is (0 - 1.0]. +Default is 0.5. +

+
+ + +

27.18.1 Examples

+ +
    +
  • Make it sound as if there are twice as many instruments as are actually playing: +
    +
    aecho=0.8:0.88:60:0.4
    +
    + +
  • If delay is very short, then it sounds like a (metallic) robot playing music: +
    +
    aecho=0.8:0.88:6:0.4
    +
    + +
  • A longer delay will sound like an open air concert in the mountains: +
    +
    aecho=0.8:0.9:1000:0.3
    +
    + +
  • Same as above but with one more mountain: +
    +
    aecho=0.8:0.9:1000|1800:0.3|0.25
    +
    +
+ + +

27.19 aemphasis

+

Audio emphasis filter creates or restores material directly taken from LPs or +emphased CDs with different filter curves. E.g. to store music on vinyl the +signal has to be altered by a filter first to even out the disadvantages of +this recording medium. +Once the material is played back the inverse filter has to be applied to +restore the distortion of the frequency response. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. +

+
+
level_out
+

Set output gain. +

+
+
mode
+

Set filter mode. For restoring material use reproduction mode, otherwise +use production mode. Default is reproduction mode. +

+
+
type
+

Set filter type. Selects medium. Can be one of the following: +

+
+
col
+

select Columbia. +

+
emi
+

select EMI. +

+
bsi
+

select BSI (78RPM). +

+
riaa
+

select RIAA. +

+
cd
+

select Compact Disc (CD). +

+
50fm
+

select 50µs (FM). +

+
75fm
+

select 75µs (FM). +

+
50kf
+

select 50µs (FM-KF). +

+
75kf
+

select 75µs (FM-KF). +

+
+
+
+ + +

27.19.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.20 aeval

+ +

Modify an audio signal according to the specified expressions. +

+

This filter accepts one or more expressions (one for each channel), +which are evaluated and used to modify a corresponding audio signal. +

+

It accepts the following parameters: +

+
+
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. +

+
+
channel_layout, c
+

Set output channel layout. If not specified, the channel layout is +specified by the number of expressions. If set to ‘same’, it will +use by default the same input channel layout. +

+
+ +

Each expression in exprs can contain the following constants and functions: +

+
+
ch
+

channel number of the current expression +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
s
+

sample rate +

+
+
t
+

time of the evaluated sample expressed in seconds +

+
+
nb_in_channels
+
nb_out_channels
+

input and output number of channels +

+
+
val(CH)
+

the value of input channel with number CH +

+
+ +

Note: this filter is slow. For faster processing you should use a +dedicated filter. +

+ +

27.20.1 Examples

+ +
    +
  • Half volume: +
    +
    aeval=val(ch)/2:c=same
    +
    + +
  • Invert phase of the second channel: +
    +
    aeval=val(0)|-val(1)
    +
    +
+ + +

27.21 aexciter

+ +

An exciter is used to produce high sound that is not present in the +original signal. This is done by creating harmonic distortions of the +signal which are restricted in range and added to the original signal. +An Exciter raises the upper end of an audio signal without simply raising +the higher frequencies like an equalizer would do to create a more +"crisp" or "brilliant" sound. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level prior processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
level_out
+

Set output level after processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
amount
+

Set the amount of harmonics added to original signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
drive
+

Set the amount of newly created harmonics. +Allowed range is from 0.1 to 10. +Default value is 8.5. +

+
+
blend
+

Set the octave of newly created harmonics. +Allowed range is from -10 to 10. +Default value is 0. +

+
+
freq
+

Set the lower frequency limit of producing harmonics in Hz. +Allowed range is from 2000 to 12000 Hz. +Default is 7500 Hz. +

+
+
ceil
+

Set the upper frequency limit of producing harmonics. +Allowed range is from 9999 to 20000 Hz. +If value is lower than 10000 Hz no limit is applied. +

+
+
listen
+

Mute the original signal and output only added harmonics. +By default is disabled. +

+
+ + +

27.21.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.22 afade

+ +

Apply fade-in/out effect to input audio. +

+

A description of the accepted parameters follows. +

+
+
type, t
+

Specify the effect type, can be either in for fade-in, or +out for a fade-out effect. Default is in. +

+
+
start_sample, ss
+

Specify the number of the start sample for starting to apply the fade +effect. Default is 0. +

+
+
nb_samples, ns
+

Specify the number of samples for which the fade effect has to last. 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 44100. +

+
+
start_time, st
+

Specify the start time of the fade effect. Default is 0. +The value must be specified as a time duration; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +If set this option is used instead of start_sample. +

+
+
duration, d
+

Specify the duration of the fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
curve
+

Set curve for fade transition. +

+

It accepts the following values: +

+
tri
+

select triangular, linear slope (default) +

+
qsin
+

select quarter of sine wave +

+
hsin
+

select half of sine wave +

+
esin
+

select exponential sine wave +

+
log
+

select logarithmic +

+
ipar
+

select inverted parabola +

+
qua
+

select quadratic +

+
cub
+

select cubic +

+
squ
+

select square root +

+
cbr
+

select cubic root +

+
par
+

select parabola +

+
exp
+

select exponential +

+
iqsin
+

select inverted quarter of sine wave +

+
ihsin
+

select inverted half of sine wave +

+
dese
+

select double-exponential seat +

+
desi
+

select double-exponential sigmoid +

+
losi
+

select logistic sigmoid +

+
sinc
+

select sine cardinal function +

+
isinc
+

select inverted sine cardinal function +

+
quat
+

select quartic +

+
quatr
+

select quartic root +

+
qsin2
+

select squared quarter of sine wave +

+
hsin2
+

select squared half of sine wave +

+
nofade
+

no fade applied +

+
+ +
+
silence
+

Set the initial gain for fade-in or final gain for fade-out. +Default value is 0.0. +

+
+
unity
+

Set the initial gain for fade-out or final gain for fade-in. +Default value is 1.0. +

+
+ + +

27.22.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.22.2 Examples

+ +
    +
  • Fade in first 15 seconds of audio: +
    +
    afade=t=in:ss=0:d=15
    +
    + +
  • Fade out last 25 seconds of a 900 seconds audio: +
    +
    afade=t=out:st=875:d=25
    +
    +
+ + +

27.23 afftdn

+

Denoise audio samples with FFT. +

+

A description of the accepted parameters follows. +

+
+
noise_reduction, nr
+

Set the noise reduction in dB, allowed range is 0.01 to 97. +Default value is 12 dB. +

+
+
noise_floor, nf
+

Set the noise floor in dB, allowed range is -80 to -20. +Default value is -50 dB. +

+
+
noise_type, nt
+

Set the noise type. +

+

It accepts the following values: +

+
white, w
+

Select white noise. +

+
+
vinyl, v
+

Select vinyl noise. +

+
+
shellac, s
+

Select shellac noise. +

+
+
custom, c
+

Select custom noise, defined in bn option. +

+

Default value is white noise. +

+
+ +
+
band_noise, bn
+

Set custom band noise profile for every one of 15 bands. +Bands are separated by ’ ’ or ’|’. +

+
+
residual_floor, rf
+

Set the residual floor in dB, allowed range is -80 to -20. +Default value is -38 dB. +

+
+
track_noise, tn
+

Enable noise floor tracking. By default is disabled. +With this enabled, noise floor is automatically adjusted. +

+
+
track_residual, tr
+

Enable residual tracking. By default is disabled. +

+
+
output_mode, om
+

Set the output mode. +

+

It accepts the following values: +

+
input, i
+

Pass input unchanged. +

+
+
output, o
+

Pass noise filtered out. +

+
+
noise, n
+

Pass only noise. +

+

Default value is output. +

+
+ +
+
adaptivity, ad
+

Set the adaptivity factor, used how fast to adapt gains adjustments per +each frequency bin. Value 0 enables instant adaptation, while higher values +react much slower. +Allowed range is from 0 to 1. Default value is 0.5. +

+
+
floor_offset, fo
+

Set the noise floor offset factor. This option is used to adjust offset applied to measured +noise floor. It is only effective when noise floor tracking is enabled. +Allowed range is from -2.0 to 2.0. Default value is 1.0. +

+
+
noise_link, nl
+

Set the noise link used for multichannel audio. +

+

It accepts the following values: +

+
none
+

Use unchanged channel’s noise floor. +

+
+
min
+

Use measured min noise floor of all channels. +

+
+
max
+

Use measured max noise floor of all channels. +

+
+
average
+

Use measured average noise floor of all channels. +

+

Default value is min. +

+
+ +
+
band_multiplier, bm
+

Set the band multiplier factor, used how much to spread bands across frequency bins. +Allowed range is from 0.2 to 5. Default value is 1.25. +

+
+
sample_noise, sn
+

Toggle capturing and measurement of noise profile from input audio. +

+

It accepts the following values: +

+
start, begin
+

Start sample noise capture. +

+
+
stop, end
+

Stop sample noise capture and measure new noise band profile. +

+

Default value is none. +

+
+ +
+
gain_smooth, gs
+

Set gain smooth spatial radius, used to smooth gains applied to each frequency bin. +Useful to reduce random music noise artefacts. +Higher values increases smoothing of gains. +Allowed range is from 0 to 50. +Default value is 0. +

+
+ + +

27.23.1 Commands

+ +

This filter supports the some above mentioned options as commands. +

+ +

27.23.2 Examples

+ +
    +
  • Reduce white noise by 10dB, and use previously measured noise floor of -40dB: +
    +
    afftdn=nr=10:nf=-40
    +
    + +
  • Reduce white noise by 10dB, also set initial noise floor to -80dB and enable automatic +tracking of noise floor so noise floor will gradually change during processing: +
    +
    afftdn=nr=10:nf=-80:tn=1
    +
    + +
  • Reduce noise by 20dB, using noise floor of -40dB and using commands to take noise profile +of first 0.4 seconds of input audio: +
    +
    asendcmd=0.0 afftdn sn start,asendcmd=0.4 afftdn sn stop,afftdn=nr=20:nf=-40
    +
    +
+ + +

27.24 afftfilt

+

Apply arbitrary expressions to samples in frequency domain. +

+
+
real
+

Set frequency domain real expression for each separate channel separated +by ’|’. Default is "re". +If the number of input channels is greater than the number of +expressions, the last specified expression is used for the remaining +output channels. +

+
+
imag
+

Set frequency domain imaginary expression for each separate channel +separated by ’|’. Default is "im". +

+

Each expression in real and imag can contain the following +constants and functions: +

+
+
sr
+

sample rate +

+
+
b
+

current frequency bin number +

+
+
nb
+

number of available bins +

+
+
ch
+

channel number of the current expression +

+
+
chs
+

number of channels +

+
+
pts
+

current frame pts +

+
+
re
+

current real part of frequency bin of current channel +

+
+
im
+

current imaginary part of frequency bin of current channel +

+
+
real(b, ch)
+

Return the value of real part of frequency bin at location (bin,channel) +

+
+
imag(b, ch)
+

Return the value of imaginary part of frequency bin at location (bin,channel) +

+
+ +
+
win_size
+

Set window size. Allowed range is from 16 to 131072. +Default is 4096 +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.75. +

+
+ + +

27.24.1 Examples

+ +
    +
  • Leave almost only low frequencies in audio: +
    +
    afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
    +
    + +
  • Apply robotize effect: +
    +
    afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
    +
    + +
  • Apply whisper effect: +
    +
    afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8"
    +
    + +
  • Apply phase shift: +
    +
    afftfilt="real=re*cos(1)-im*sin(1):imag=re*sin(1)+im*cos(1)"
    +
    +
+ + +

27.25 afir

+ +

Apply an arbitrary Finite Impulse Response filter. +

+

This filter is designed for applying long FIR filters, +up to 60 seconds long. +

+

It can be used as component for digital crossover filters, +room equalization, cross talk cancellation, wavefield synthesis, +auralization, ambiophonics, ambisonics and spatialization. +

+

This filter uses the streams higher than first one as FIR coefficients. +If the non-first stream holds a single channel, it will be used +for all input channels in the first stream, otherwise +the number of channels in the non-first stream must be same as +the number of channels in the first stream. +

+

It accepts the following parameters: +

+
+
dry
+

Set dry gain. This sets input gain. +

+
+
wet
+

Set wet gain. This sets final output gain. +

+
+
length
+

Set Impulse Response filter length. Default is 1, which means whole IR is processed. +

+
+
gtype
+

This option is deprecated, and does nothing. +

+
+
irnorm
+

Set norm to be applied to IR coefficients before filtering. +Allowed range is from -1 to 2. +IR coefficients are normalized with calculated vector norm set by this option. +For negative values, no norm is calculated, and IR coefficients are not modified at all. +Default is 1. +

+
+
irlink
+

For multichannel IR if this option is set to true, all IR channels will be +normalized with maximal measured gain of all IR channels coefficients as set by irnorm option. +When disabled, all IR coefficients in each IR channel will be normalized independently. +Default is true. +

+
+
irgain
+

Set gain to be applied to IR coefficients before filtering. +Allowed range is 0 to 1. This gain is applied after any gain applied with irnorm option. +

+
+
irfmt
+

Set format of IR stream. Can be mono or input. +Default is input. +

+
+
maxir
+

Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. +Allowed range is 0.1 to 60 seconds. +

+
+
response
+

This option is deprecated, and does nothing. +

+
+
channel
+

This option is deprecated, and does nothing. +

+
+
size
+

This option is deprecated, and does nothing. +

+
+
rate
+

This option is deprecated, and does nothing. +

+
+
minp
+

Set minimal partition size used for convolution. Default is 8192. +Allowed range is from 1 to 65536. +Lower values decreases latency at cost of higher CPU usage. +

+
+
maxp
+

Set maximal partition size used for convolution. Default is 8192. +Allowed range is from 8 to 65536. +Lower values may increase CPU usage. +

+
+
nbirs
+

Set number of input impulse responses streams which will be switchable at runtime. +Allowed range is from 1 to 32. Default is 1. +

+
+
ir
+

Set IR stream which will be used for convolution, starting from 0, should always be +lower than supplied value by nbirs option. Default is 0. +This option can be changed at runtime via commands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+
irload
+

Set when to load IR stream. Can be init or access. +First one load and prepares all IRs on initialization, second one +once on first access of specific IR. +Default is init. +

+
+ + +

27.25.1 Examples

+ +
    +
  • Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: +
    +
    ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
    +
    + +
  • Apply true stereo processing given input stereo stream, and two stereo impulse responses for left and right channel, +the impulse response files are files with names l_ir.wav and r_ir.wav, and setting irnorm option value: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irnorm=1.2,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    + +
  • Similar to above example, but with irgain explicitly set to estimated value and with irnorm disabled: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irgain=-5dB:irnom=-1,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    +
+ + +

27.26 aformat

+ +

Set output format constraints for the input audio. The framework will +negotiate the most appropriate format to minimize conversions. +

+

It accepts the following parameters: +

+
sample_fmts, f
+

A ’|’-separated list of requested sample formats. +

+
+
sample_rates, r
+

A ’|’-separated list of requested sample rates. +

+
+
channel_layouts, cl
+

A ’|’-separated list of requested channel layouts. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+ +

If a parameter is omitted, all values are allowed. +

+

Force the output to either unsigned 8-bit or signed 16-bit stereo +

+
aformat=sample_fmts=u8|s16:channel_layouts=stereo
+
+ + +

27.27 afreqshift

+

Apply frequency shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify frequency shift. Allowed range is -INT_MAX to INT_MAX. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

27.27.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.28 afwtdn

+

Reduce broadband noise from input samples using Wavelets. +

+

A description of the accepted options follows. +

+
+
sigma
+

Set the noise sigma, allowed range is from 0 to 1. +Default value is 0. +This option controls strength of denoising applied to input samples. +Most useful way to set this option is via decibels, eg. -45dB. +

+
+
levels
+

Set the number of wavelet levels of decomposition. +Allowed range is from 1 to 12. +Default value is 10. +Setting this too low make denoising performance very poor. +

+
+
wavet
+

Set wavelet type for decomposition of input frame. +They are sorted by number of coefficients, from lowest to highest. +More coefficients means worse filtering speed, but overall better quality. +Available wavelets are: +

+
+
‘sym2’
+
‘sym4’
+
‘rbior68’
+
‘deb10’
+
‘sym10’
+
‘coif5’
+
‘bl3’
+
+ +
+
percent
+

Set percent of full denoising. Allowed range is from 0 to 100 percent. +Default value is 85 percent or partial denoising. +

+
+
profile
+

If enabled, first input frame will be used as noise profile. +If first frame samples contain non-noise performance will be very poor. +

+
+
adaptive
+

If enabled, input frames are analyzed for presence of noise. +If noise is detected with high possibility then input frame profile will be +used for processing following frames, until new noise frame is detected. +

+
+
samples
+

Set size of single frame in number of samples. Allowed range is from 512 to +65536. Default frame size is 8192 samples. +

+
+
softness
+

Set softness applied inside thresholding function. Allowed range is from 0 to +10. Default softness is 1. +

+
+ + +

27.28.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.29 agate

+ +

A gate is mainly used to reduce lower parts of a signal. This kind of signal +processing reduces disturbing noise between useful signals. +

+

Gating is done by detecting the volume below a chosen level threshold +and dividing it by the factor set with ratio. The bottom of the noise +floor is set via range. Because an exact manipulation of the signal +would cause distortion of the waveform the reduction can be levelled over +time. This is done by setting attack and release. +

+

attack determines how long the signal has to fall below the threshold +before any reduction will occur and release sets the time the signal +has to rise above the threshold to reduce the reduction again. +Shorter signals than the chosen attack time will be left untouched. +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+ + +

27.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.30 aiir

+ +

Apply an arbitrary Infinite Impulse Response filter. +

+

It accepts the following parameters: +

+
+
zeros, z
+

Set B/numerator/zeros/reflection coefficients. +

+
+
poles, p
+

Set A/denominator/poles/ladder coefficients. +

+
+
gains, k
+

Set channels gains. +

+
+
dry_gain
+

Set input gain. +

+
+
wet_gain
+

Set output gain. +

+
+
format, f
+

Set coefficients format. +

+
+
‘ll’
+

lattice-ladder function +

+
‘sf’
+

analog transfer function +

+
‘tf’
+

digital transfer function +

+
‘zp’
+

Z-plane zeros/poles, cartesian (default) +

+
‘pr’
+

Z-plane zeros/poles, polar radians +

+
‘pd’
+

Z-plane zeros/poles, polar degrees +

+
‘sp’
+

S-plane zeros/poles +

+
+ +
+
process, r
+

Set type of processing. +

+
+
‘d’
+

direct processing +

+
‘s’
+

serial processing +

+
‘p’
+

parallel processing +

+
+ +
+
precision, e
+

Set filtering precision. +

+
+
‘dbl’
+

double-precision floating-point (default) +

+
‘flt’
+

single-precision floating-point +

+
‘i32’
+

32-bit integers +

+
‘i16’
+

16-bit integers +

+
+ +
+
normalize, n
+

Normalize filter coefficients, by default is enabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
mix
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
response
+

Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. +By default it is disabled. +

+
+
channel
+

Set for which IR channel to display frequency response. By default is first channel +displayed. This option is used only when response is enabled. +

+
+
size
+

Set video stream size. This option is used only when response is enabled. +

+
+ +

Coefficients in tf and sf format are separated by spaces and are in ascending +order. +

+

Coefficients in zp format are separated by spaces and order of coefficients +doesn’t matter. Coefficients in zp format are complex numbers with i +imaginary unit. +

+

Different coefficients and gains can be provided for every channel, in such case +use ’|’ to separate coefficients or gains. Last provided coefficients will be +used for all remaining channels. +

+ +

27.30.1 Examples

+ +
    +
  • Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate: +
    +
    aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
    +
    + +
  • Same as above but in zp format: +
    +
    aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
    +
    + +
  • Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format: +
    +
    aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
    +
    +
+ + +

27.31 alimiter

+ +

The limiter prevents an input signal from rising over a desired threshold. +This limiter uses lookahead technology to prevent your signal from distorting. +It means that there is a small delay after the signal is processed. Keep in mind +that the delay it produces is the attack time you set. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
limit
+

Don’t let signals above this level pass the limiter. Default is 1. +

+
+
attack
+

The limiter will reach its attenuation level in this amount of time in +milliseconds. Default is 5 milliseconds. +

+
+
release
+

Come back from limiting to attenuation 1.0 in this amount of milliseconds. +Default is 50 milliseconds. +

+
+
asc
+

When gain reduction is always needed ASC takes care of releasing to an +average reduction level rather than reaching a reduction of 0 in the release +time. +

+
+
asc_level
+

Select how much the release time is affected by ASC, 0 means nearly no changes +in release time while 1 produces higher release times. +

+
+
level
+

Auto level output signal. Default is enabled. +This normalizes audio back to 0dB if enabled. +

+
+
latency
+

Compensate the delay introduced by using the lookahead buffer set with attack +parameter. Also flush the valid audio data in the lookahead buffer when the +stream hits EOF. +

+
+ +

Depending on picked setting it is recommended to upsample input 2x or 4x times +with aresample before applying this filter. +

+ +

27.32 allpass

+ +

Apply a two-pole all-pass filter with central frequency (in Hz) +frequency, and filter-width 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: +

+
+
frequency, f
+

Set frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
order, o
+

Set the filter order, can be 1 or 2. Default is 2. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+
+
+ + +

27.32.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change allpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change allpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change allpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change allpass mix. +Syntax for the command is : "mix" +

+
+ + +

27.33 aloop

+ +

Loop audio samples. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal number of samples. Default is 0. +

+
+
start
+

Set first sample of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

27.34 amerge

+ +

Merge two or more audio streams into a single multi-channel stream. +

+

All inputs must have the same sample rate, and format. +

+

If inputs do not have the same duration, the output will stop with the +shortest. +

+

The filter accepts the following options: +

+
+
inputs
+

Set the number of inputs. Default is 2. +

+
+
layout_mode
+
+

This option controls how the output channel layout is determined and if the +audio channels are reordered during merge. +

+
+
legacy
+
+

This is the mode how the filter behaved historically so it is the default. +

+

If the channel layouts of the inputs are known and disjoint, and therefore +compatible, the channel layout of the output will be set accordingly and the +channels will be reordered as necessary. If the channel layouts of the inputs +are not disjoint, some of them are unknown, or they are using special channel +layouts, such as ambisonics, the output will have all the channels of the first +input then all the channels of the second input, in that order, and the channel +layout of the output will be the default value corresponding to the total +number of channels. +

+

For example, if the first input is in 2.1 (FL+FR+LF) and the second input +is FC+BL+BR, then the output will be in 5.1, with the channels in the +following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the +first input, b1 is the first channel of the second input). +

+

On the other hand, if both input are in stereo, the output channels will be +in the default order: a1, a2, b1, b2, and the channel layout will be +arbitrarily set to 4.0, which may or may not be the expected value. +

+
+
reset
+

This mode ignores the input channel layouts and does no channel reordering. +The output will have all the channels of the first input, then all the channels +of the second input, in that order, and so on. +

+

The output channel layout will only specify the total channel count. +

+
+
normal
+

This mode keeps channel name and designation information from the input +channels and does no channel reordering. The output will have all the channels +of the first input, then all the channels of the second input, in that order, +and so on. +

+
+
+ +
+
+ + +

27.34.1 Examples

+ +
    +
  • Merge two mono files into a stereo stream: +
    +
    amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
    +
    + +
  • Multiple merges assuming 1 video stream and 6 audio streams in input.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
    +
    +
+ + +

27.35 amix

+ +

Mixes multiple audio inputs into a single output. +

+

Note that this filter only supports float samples (the amerge +and pan audio filters support many formats). If the amix +input has integer samples then aresample will be automatically +inserted to perform the conversion to float samples. +

+

It accepts the following parameters: +

+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
duration
+

How to determine the end-of-stream. +

+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+
+ +
+
dropout_transition
+

The transition time, in seconds, for volume renormalization when an input +stream ends. The default value is 2 seconds. +

+
+
weights
+

Specify weight of each input audio stream as a sequence of numbers separated +by a space. If fewer weights are specified compared to number of inputs, the +last weight is assigned to the remaining inputs. +Default weight for each input is 1. +

+
+
normalize
+

Always scale inputs instead of only doing summation of samples. +Beware of heavy clipping if inputs are not normalized prior or after filtering +by this filter if this option is disabled. By default is enabled. +

+
+ + +

27.35.1 Examples

+ +
    +
  • This will mix 3 input audio streams to a single output with the same duration as the +first input and a dropout transition time of 3 seconds: +
    +
    ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
    +
    + +
  • This will mix one vocal and one music input audio stream to a single output with the same duration as the +longest input. The music will have quarter the weight as the vocals, and the inputs are not normalized: +
    +
    ffmpeg -i VOCALS -i MUSIC -filter_complex amix=inputs=2:duration=longest:dropout_transition=0:weights="1 0.25":normalize=0 OUTPUT
    +
    + +
+ + +

27.35.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
normalize
+

Syntax is same as option with same name. +

+
+ + +

27.36 amultiply

+ +

Multiply first audio stream with second audio stream and store result +in output audio stream. Multiplication is done by multiplying each +sample from first stream with sample at same position from second stream. +

+

With this element-wise multiplication one can create amplitude fades and +amplitude modulations. +

+ +

27.37 anequalizer

+ +

High-order parametric multiband equalizer for each channel. +

+

It accepts the following parameters: +

+
params
+
+

This option string is in format: +"cchn f=cf w=w g=g t=f | ..." +Each equalizer band is separated by ’|’. +

+
+
chn
+

Set channel number to which equalization will be applied. +If input doesn’t have that channel the entry is ignored. +

+
+
f
+

Set central frequency for band. +If input doesn’t have that frequency the entry is ignored. +

+
+
w
+

Set band width in Hertz. +

+
+
g
+

Set band gain in dB. +

+
+
t
+

Set filter type for band, optional, can be: +

+
+
‘0’
+

Butterworth, this is default. +

+
+
‘1’
+

Chebyshev type 1. +

+
+
‘2’
+

Chebyshev type 2. +

+
+
+
+ +
+
curves
+

With this option activated frequency response of anequalizer is displayed +in video stream. +

+
+
size
+

Set video stream size. Only useful if curves option is activated. +

+
+
mgain
+

Set max gain that will be displayed. Only useful if curves option is activated. +Setting this to a reasonable value makes it possible to display gain which is derived from +neighbour bands which are too close to each other and thus produce higher gain +when both are activated. +

+
+
fscale
+

Set frequency scale used to draw frequency response in video output. +Can be linear or logarithmic. Default is logarithmic. +

+
+
colors
+

Set color for each channel curve which is going to be displayed in video stream. +This is list of color names separated by space or by ’|’. +Unrecognised or missing colors will be replaced by white color. +

+
+ + +

27.37.1 Examples

+ +
    +
  • Lower gain by 10 of central frequency 200Hz and width 100 Hz +for first 2 channels using Chebyshev type 1 filter: +
    +
    anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
    +
    +
+ + +

27.37.2 Commands

+ +

This filter supports the following commands: +

+
change
+

Alter existing filter parameters. +Syntax for the commands is : "fN|f=freq|w=width|g=gain" +

+

fN is existing filter number, starting from 0, if no such filter is available +error is returned. +freq set new frequency parameter. +width set new width parameter in Hertz. +gain set new gain parameter in dB. +

+

Full filter invocation with asendcmd may look like this: +asendcmd=c=’4.0 anequalizer change 0|f=200|w=50|g=1’,anequalizer=... +

+
+ + +

27.38 anlmdn

+ +

Reduce broadband noise in audio samples using Non-Local Means algorithm. +

+

Each sample is adjusted by looking for other samples with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +p. Patches are searched in an area of r around the sample. +

+

The filter accepts the following options: +

+
+
strength, s
+

Set denoising strength. Allowed range is from 0.00001 to 10000. Default value is 0.00001. +

+
+
patch, p
+

Set patch radius duration. Allowed range is from 1 to 100 milliseconds. +Default value is 2 milliseconds. +

+
+
research, r
+

Set research radius duration. Allowed range is from 2 to 300 milliseconds. +Default value is 6 milliseconds. +

+
+
output, o
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass noise filtered out. +

+
+
n
+

Pass only noise. +

+

Default value is o. +

+
+ +
+
smooth, m
+

Set smooth factor. Default value is 11. Allowed range is from 1 to 1000. +

+
+ + +

27.38.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.39 anlmf, anlms

+

Apply Normalized Least-Mean-(Squares|Fourth) algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by finding the filter coefficients that +relate to producing the least mean square of the error signal (difference between the desired, +2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set filter order. +

+
+
mu
+

Set filter mu. +

+
+
eps
+

Set the filter eps. +

+
+
leakage
+

Set the filter leakage. +

+
+
out_mode
+

It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

27.39.1 Examples

+ +
    +
  • One of many usages of this filter is noise reduction, input audio is filtered +with same samples that are delayed by fixed amount, one such example for stereo audio is: +
    +
    asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
    +
    +
+ + +

27.39.2 Commands

+ +

This filter supports the same commands as options, excluding option order. +

+ +

27.40 anull

+ +

Pass the audio source unchanged to the output. +

+ +

27.41 apad

+ +

Pad the end of an audio stream with silence. +

+

This can be used together with ffmpeg -shortest to +extend audio streams to the same length as the video stream. +

+

A description of the accepted options follows. +

+
+
packet_size
+

Set silence packet size. Default value is 4096. +

+
+
pad_len
+

Set the number of samples of silence to add to the end. After the +value is reached, the stream is terminated. This option is mutually +exclusive with whole_len. +

+
+
whole_len
+

Set the minimum total number of samples in the output audio stream. If +the value is longer than the input audio length, silence is added to +the end, until the value is reached. This option is mutually exclusive +with pad_len. +

+
+
pad_dur
+

Specify the duration of samples of silence to add. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. +

+
+
whole_dur
+

Specify the minimum total duration in the output audio stream. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. If the value is longer than +the input audio length, silence is added to the end, until the value is reached. +This option is mutually exclusive with pad_dur +

+
+ +

If neither the pad_len nor the whole_len nor pad_dur +nor whole_dur option is set, the filter will add silence to the end of +the input stream indefinitely. +

+

Note that for ffmpeg 4.4 and earlier a zero pad_dur or +whole_dur also caused the filter to add silence indefinitely. +

+ +

27.41.1 Examples

+ +
    +
  • Add 1024 samples of silence to the end of the input: +
    +
    apad=pad_len=1024
    +
    + +
  • Make sure the audio output will contain at least 10000 samples, pad +the input with silence if required: +
    +
    apad=whole_len=10000
    +
    + +
  • Use ffmpeg to pad the audio input with silence, so that the +video stream will always result the shortest and will be converted +until the end in the output file when using the shortest +option: +
    +
    ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
    +
    +
+ + +

27.42 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. +

+
+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.74 +

+
+
delay
+

Set delay in milliseconds. Default is 3.0. +

+
+
decay
+

Set decay. Default is 0.4. +

+
+
speed
+

Set modulation speed in Hz. Default is 0.5. +

+
+
type
+

Set modulation type. Default is triangular. +

+

It accepts the following values: +

+
‘triangular, t’
+
‘sinusoidal, s’
+
+
+
+ + +

27.43 aphaseshift

+

Apply phase shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify phase shift. Allowed range is from -1.0 to 1.0. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

27.43.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.44 apsnr

+

Measure Audio Peak Signal-to-Noise Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

27.45 apsyclip

+

Apply Psychoacoustic clipper to input audio stream. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
clip
+

Set the clipping start value. Default value is 0dBFS or 1. +

+
+
diff
+

Output only difference samples, useful to hear introduced distortions. +By default is disabled. +

+
+
adaptive
+

Set strength of adaptive distortion applied. Default value is 0.5. +Allowed range is from 0 to 1. +

+
+
iterations
+

Set number of iterations of psychoacoustic clipper. +Allowed range is from 1 to 20. Default value is 10. +

+
+
level
+

Auto level output signal. Default is disabled. +This normalizes audio back to 0dBFS if enabled. +

+
+ + +

27.45.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.46 apulsator

+ +

Audio pulsator is something between an autopanner and a tremolo. +But it can produce funny stereo effects as well. Pulsator changes the volume +of the left and right channel based on a LFO (low frequency oscillator) with +different waveforms and shifted phases. +This filter have the ability to define an offset between left and right +channel. An offset of 0 means that both LFO shapes match each other. +The left and right channel are altered equally - a conventional tremolo. +An offset of 50% means that the shape of the right channel is exactly shifted +in phase (or moved backwards about half of the frequency) - pulsator acts as +an autopanner. At 1 both curves match again. Every setting in between moves the +phase shift gapless between all stages and produces some "bypassing" sounds with +sine and triangle waveforms. The more you set the offset near 1 (starting from +the 0.5) the faster the signal passes from the left to the right speaker. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
mode
+

Set waveform shape the LFO will use. Can be one of: sine, triangle, square, +sawup or sawdown. Default is sine. +

+
+
amount
+

Set modulation. Define how much of original signal is affected by the LFO. +

+
+
offset_l
+

Set left channel offset. Default is 0. Allowed range is [0 - 1]. +

+
+
offset_r
+

Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. +

+
+
width
+

Set pulse width. Default is 1. Allowed range is [0 - 2]. +

+
+
timing
+

Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. +

+
+
bpm
+

Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing +is set to bpm. +

+
+
ms
+

Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing +is set to ms. +

+
+
hz
+

Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used +if timing is set to hz. +

+
+ + +

27.47 aresample

+ +

Resample the input audio to the specified parameters, using the +libswresample library. If none are specified then the filter will +automatically convert between its input and output. +

+

This filter is also able to stretch/squeeze the audio data to make it match +the timestamps or to inject silence / cut out audio to make it match the +timestamps, do a combination of both or do neither. +

+

The filter accepts the syntax +[sample_rate:]resampler_options, where sample_rate +expresses a sample rate and resampler_options is a list of +key=value pairs, separated by ":". See the +"Resampler Options" section in the +ffmpeg-resampler(1) manual +for the complete list of supported options. +

+ +

27.47.1 Examples

+ +
    +
  • Resample the input audio to 44100Hz: +
    +
    aresample=44100
    +
    + +
  • Stretch/squeeze samples to the given timestamps, with a maximum of 1000 +samples per second compensation: +
    +
    aresample=async=1000
    +
    +
+ + +

27.48 areverse

+ +

Reverse an audio clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

27.48.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    atrim=end=5,areverse
    +
    +
+ + +

27.49 arls

+

Apply Recursive Least Squares algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by recursively finding the filter coefficients that +relate to producing the minimal weighted linear least squares cost function of the error signal (difference +between the desired, 2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
lambda
+

Set the forgetting factor. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

27.50 arnndn

+ +

Reduce noise from speech using Recurrent Neural Networks. +

+

This filter accepts the following options: +

+
+
model, m
+

Set train model file to load. This option is always required. +

+
+
mix
+

Set how much to mix filtered samples into final output. +Allowed range is from -1 to 1. Default value is 1. +Negative values are special, they set how much to keep filtered noise +in the final filter output. Set this option to -1 to hear actual +noise removed from input signal. +

+
+ + +

27.50.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.51 asdr

+

Measure Audio Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

27.52 asetnsamples

+ +

Set the number of samples per each output audio frame. +

+

The last output packet may contain a different number of samples, as +the filter will flush all the remaining samples when the input audio +signals its end. +

+

The filter accepts the following options: +

+
+
nb_out_samples, n
+

Set the number of frames per each output audio frame. The number is +intended as the number of samples per each channel. +Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio frame with zeroes, so +that the last frame will contain the same number of samples as the +previous ones. Default value is 1. +

+
+ +

For example, to set the number of per-frame samples to 1234 and +disable padding for the last frame, use: +

+
asetnsamples=n=1234:p=0
+
+ + +

27.53 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: +

+
+
sample_rate, r
+

Set the output sample rate. Default is 44100 Hz. +

+
+ + +

27.54 ashowinfo

+ +

Show a line containing various information for each input audio frame. +The input audio is not modified. +

+

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The presentation timestamp of the input frame, in time base units; the time base +depends on the filter input pad, and is usually 1/sample_rate. +

+
+
pts_time
+

The presentation timestamp of the input frame in seconds. +

+
+
fmt
+

The sample format. +

+
+
chlayout
+

The channel layout. +

+
+
rate
+

The sample rate for the audio frame. +

+
+
nb_samples
+

The number of samples (per channel) in the frame. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar +audio, the data is treated as if all the planes were concatenated. +

+
+
plane_checksums
+

A list of Adler-32 checksums for each data plane. +

+
+ + +

27.55 asisdr

+

Measure Audio Scaled-Invariant Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

27.56 asoftclip

+

Apply audio soft clipping. +

+

Soft clipping is a type of distortion effect where the amplitude of a signal is saturated +along a smooth curve, rather than the abrupt shape of hard-clipping. +

+

This filter accepts the following options: +

+
+
type
+

Set type of soft-clipping. +

+

It accepts the following values: +

+
hard
+
tanh
+
atan
+
cubic
+
exp
+
alg
+
quintic
+
sin
+
erf
+
+ +
+
threshold
+

Set threshold from where to start clipping. Default value is 0dB or 1. +

+
+
output
+

Set gain applied to output. Default value is 0dB or 1. +

+
+
param
+

Set additional parameter which controls sigmoid function. +

+
+
oversample
+

Set oversampling factor. +

+
+ + +

27.56.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.57 aspectralstats

+ +

Display frequency domain statistical information about the audio channels. +Statistics are calculated and stored as metadata for each audio channel and for each audio frame. +

+

It accepts the following option: +

+
win_size
+

Set the window length in samples. Default value is 2048. +Allowed range is from 32 to 65536. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. Allowed range is from 0 +to 1. Default value is 0.5. +

+
+
measure
+

Select the parameters which are measured. The metadata keys can +be used as flags, default is all which measures everything. +none disables all measurement. +

+
+ +

A list of each metadata key follows: +

+
+
mean
+
variance
+
centroid
+
spread
+
skewness
+
kurtosis
+
entropy
+
flatness
+
crest
+
flux
+
slope
+
decrease
+
rolloff
+
+ + +

27.58 asr

+

Automatic Speech Recognition +

+

This filter uses PocketSphinx for speech recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-pocketsphinx. +

+

It accepts the following options: +

+
+
rate
+

Set sampling rate of input audio. Defaults is 16000. +This need to match speech models, otherwise one will get poor results. +

+
+
hmm
+

Set dictionary containing acoustic model files. +

+
+
dict
+

Set pronunciation dictionary. +

+
+
lm
+

Set language model file. +

+
+
lmctl
+

Set language model set. +

+
+
lmname
+

Set which language model to use. +

+
+
logfn
+

Set output for log messages. +

+
+ +

The filter exports recognized speech as the frame metadata lavfi.asr.text. +

+ +

27.59 astats

+ +

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. +

+

It accepts the following option: +

+
length
+

Short window length in seconds, used for peak and through RMS measurement. +Default is 0.05 (50 milliseconds). Allowed range is [0 - 10]. +

+
+
metadata
+
+

Set metadata injection. All the metadata keys are prefixed with lavfi.astats.X, +where X is channel number starting from 1 or string Overall. Default is +disabled. +

+

Available keys for each channel are: +Bit_depth +Crest_factor +DC_offset +Dynamic_range +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_peak +RMS_trough +Zero_crossings +Zero_crossings_rate +

+

and for Overall: +Bit_depth +DC_offset +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Number_of_samples +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_level +RMS_peak +RMS_trough +

+

For example, a full key looks like lavfi.astats.1.DC_offset or +lavfi.astats.Overall.Peak_count. +

+

Read below for the description of the keys. +

+
+
reset
+

Set the number of frames over which cumulative stats are calculated before +being reset. Default is disabled. +

+
+
measure_perchannel
+

Select the parameters which are measured per channel. The metadata keys can +be used as flags, default is all which measures everything. +none disables all per channel measurement. +

+
+
measure_overall
+

Select the parameters which are measured overall. The metadata keys can +be used as flags, default is all which measures everything. +none disables all overall measurement. +

+
+
+ +

A description of the measure keys follow: +

+
+
none
+

no measures +

+
+
all
+

all measures +

+
+
Bit_depth
+

overall bit depth of audio, i.e. number of bits used for each sample +

+
+
Crest_factor
+

standard ratio of peak to RMS level (note: not in dB) +

+
+
DC_offset
+

mean amplitude displacement from zero +

+
+
Dynamic_range
+

measured dynamic range of audio in dB +

+
+
Entropy
+

entropy measured across whole audio, entropy of value near 1.0 is typically measured for white noise +

+
+
Flat_factor
+

flatness (i.e. consecutive samples with the same value) of the signal at its peak levels +(i.e. either Min_level or Max_level) +

+
+
Max_difference
+

maximal difference between two consecutive samples +

+
+
Max_level
+

maximal sample level +

+
+
Mean_difference
+

mean difference between two consecutive samples, i.e. the average of each difference between two consecutive samples +

+
+
Min_difference
+

minimal difference between two consecutive samples +

+
+
Min_level
+

minimal sample level +

+
+
Noise_floor
+

minimum local peak measured in dBFS over a short window +

+
+
Noise_floor_count
+

number of occasions (not the number of samples) that the signal attained +Noise floor +

+
+
Number_of_Infs
+

number of samples with an infinite value +

+
+
Number_of_NaNs
+

number of samples with a NaN (not a number) value +

+
+
Number_of_denormals
+

number of samples with a subnormal value +

+
+
Number_of_samples
+

number of samples +

+
+
Peak_count
+

number of occasions (not the number of samples) that the signal attained either +Min_level or Max_level +

+
+
Abs_Peak_count
+

number of occasions that the absolute samples taken from the signal attained +max absolute value of Min_level and Max_level +

+
+
Peak_level
+

standard peak level measured in dBFS +

+
+
RMS_difference
+

Root Mean Square difference between two consecutive samples +

+
+
RMS_level
+

standard RMS level measured in dBFS +

+
+
RMS_peak
+
RMS_trough
+

peak and through values for RMS level measured over a short window, +measured in dBFS. +

+
+
Zero crossings
+

number of points where the waveform crosses the zero level axis +

+
+
Zero crossings rate
+

rate of Zero crossings and number of audio samples +

+
+ + +

27.60 asubboost

+

Boost subwoofer frequencies. +

+

The filter accepts the following options: +

+
+
dry
+

Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
wet
+

Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
boost
+

Set max boost factor. Allowed range is from 1 to 12. Default value is 2. +

+
+
decay
+

Set delay line decay gain value. Allowed range is from 0 to 1. +Default value is 0.0. +

+
+
feedback
+

Set delay line feedback gain value. Allowed range is from 0 to 1. +Default value is 0.9. +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 50 to 900. +Default value is 100. +

+
+
slope
+

Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1. +Default value is 0.5. +

+
+
delay
+

Set delay. Allowed range is from 1 to 100. +Default value is 20. +

+
+
channels
+

Set the channels to process. Default value is all available. +

+
+ + +

27.60.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.61 asubcut

+

Cut subwoofer frequencies. +

+

This filter allows to set custom, steeper +roll off than highpass filter, and thus is able to more attenuate +frequency content in stop-band. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 2 to 200. +Default value is 20. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

27.61.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.62 asupercut

+

Cut super frequencies. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 20000 to 192000. +Default value is 20000. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

27.62.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.63 asuperpass

+

Apply high order Butterworth band-pass filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

27.63.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.64 asuperstop

+

Apply high order Butterworth band-stop filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

27.64.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.65 atempo

+ +

Adjust audio tempo. +

+

The filter accepts exactly one parameter, the audio tempo. If not +specified then the filter will assume nominal 1.0 tempo. Tempo must +be in the [0.5, 100.0] range. +

+

Note that tempo greater than 2 will skip some samples rather than +blend them in. If for any reason this is a concern it is always +possible to daisy-chain several instances of atempo to achieve the +desired product tempo. +

+ +

27.65.1 Examples

+ +
    +
  • Slow down audio to 80% tempo: +
    +
    atempo=0.8
    +
    + +
  • To speed up audio to 300% tempo: +
    +
    atempo=3
    +
    + +
  • To speed up audio to 300% tempo by daisy-chaining two atempo instances: +
    +
    atempo=sqrt(3),atempo=sqrt(3)
    +
    +
+ + +

27.65.2 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+ + +

27.66 atilt

+

Apply spectral tilt filter to audio stream. +

+

This filter apply any spectral roll-off slope over any specified frequency band. +

+

The filter accepts the following options: +

+
+
freq
+

Set central frequency of tilt in Hz. Default is 10000 Hz. +

+
+
slope
+

Set slope direction of tilt. Default is 0. Allowed range is from -1 to 1. +

+
+
width
+

Set width of tilt. Default is 1000. Allowed range is from 100 to 10000. +

+
+
order
+

Set order of tilt filter. +

+
+
level
+

Set input volume level. Allowed range is from 0 to 4. +Default is 1. +

+
+ + +

27.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.67 atrim

+ +

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Timestamp (in seconds) of the start of the section to keep. I.e. the audio +sample with the timestamp start will be the first sample in the output. +

+
+
end
+

Specify time of the first audio sample that will be dropped, i.e. the +audio sample immediately preceding the one with the timestamp end will be +the last sample in the output. +

+
+
start_pts
+

Same as start, except this option sets the start timestamp in samples +instead of seconds. +

+
+
end_pts
+

Same as end, except this option sets the end timestamp in samples instead +of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_sample
+

The number of the first sample that should be output. +

+
+
end_sample
+

The number of the first sample that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual. +

+

Note that the first two sets of the start/end options and the 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 +to have 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -af atrim=60:120
    +
    + +
  • Keep only the first 1000 samples: +
    +
    ffmpeg -i INPUT -af atrim=end_sample=1000
    +
    + +
+ + +

27.68 axcorrelate

+

Calculate normalized windowed cross-correlation between two input audio streams. +

+

Resulted samples are always between -1 and 1 inclusive. +If result is 1 it means two input samples are highly correlated in that selected segment. +Result 0 means they are not correlated at all. +If result is -1 it means two input samples are out of phase, which means they cancel each +other. +

+

The filter accepts the following options: +

+
+
size
+

Set size of segment over which cross-correlation is calculated. +Default is 256. Allowed range is from 2 to 131072. +

+
+
algo
+

Set algorithm for cross-correlation. Can be slow or fast or best. +Default is best. Fast algorithm assumes mean values over any given segment +are always zero and thus need much less calculations to make. +This is generally not true, but is valid for typical audio streams. +

+
+ + +

27.68.1 Examples

+ +
    +
  • Calculate correlation between channels in stereo audio stream: +
    +
    ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
    +
    +
+ + +

27.69 bandpass

+ +

Apply a two-pole Butterworth band-pass filter with central +frequency frequency, and (3dB-point) band-width width. +The 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: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
csg
+

Constant skirt gain if set to 1. Defaults to 0. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.69.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandpass mix. +Syntax for the command is : "mix" +

+
+ + +

27.70 bandreject

+ +

Apply a two-pole Butterworth band-reject filter with central +frequency frequency, and (3dB-point) band-width width. +The filter roll off at 6dB per octave (20dB per decade). +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.70.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandreject frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandreject width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandreject width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandreject mix. +Syntax for the command is : "mix" +

+
+ + +

27.71 bass, lowshelf

+ +

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: +

+
+
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. +

+
+
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 100 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.71.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bass width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change bass gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change bass mix. +Syntax for the command is : "mix" +

+
+ + +

27.72 biquad

+ +

Apply a biquad IIR filter with the given coefficients. +Where b0, b1, b2 and a0, a1, a2 +are the numerator and denominator coefficients respectively. +and channels, c specify which channels to filter, by default all +available are filtered. +

+ +

27.72.1 Commands

+ +

This filter supports the following commands: +

+
a0
+
a1
+
a2
+
b0
+
b1
+
b2
+

Change biquad parameter. +Syntax for the command is : "value" +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.73 bs2b

+

Bauer stereo to binaural transformation, which improves headphone listening of +stereo audio records. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libbs2b. +

+

It accepts the following parameters: +

+
profile
+

Pre-defined crossfeed level. +

+
default
+

Default level (fcut=700, feed=50). +

+
+
cmoy
+

Chu Moy circuit (fcut=700, feed=60). +

+
+
jmeier
+

Jan Meier circuit (fcut=650, feed=95). +

+
+
+ +
+
fcut
+

Cut frequency (in Hz). +

+
+
feed
+

Feed level (in Hz). +

+
+
+ + +

27.74 channelmap

+ +

Remap input channels to new locations. +

+

It accepts the following parameters: +

+
map
+

Map channels from input to output. The argument is a ’|’-separated list of +mappings, each in the in_channel-out_channel or +in_channel form. 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. out_channel is the name of the output channel or its index in the +output channel layout. If out_channel is not given then it is implicitly +an index, starting with zero and increasing by one for each mapping. Mixing +different types of mappings is not allowed and will result in a parse error. +

+
+
channel_layout
+

The channel layout of the output stream. If not specified, then filter will +guess it based on the out_channel names or the number of mappings. +Guessed layouts will not necessarily contain channels in the order of the +mappings. +

+
+ +

If no mapping is present, the filter will implicitly map input channels to +output channels, preserving indices. +

+ +

27.74.1 Examples

+ +
    +
  • For example, assuming a 5.1+downmix input MOV file, +
    +
    ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
    +
    +

    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 +
    +
    ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
    +
    +
+ + +

27.75 channelsplit

+ +

Split each channel from an input audio stream into a separate output stream. +

+

It accepts the following parameters: +

+
channel_layout
+

The channel layout of the input stream. The default is "stereo". +

+
channels
+

A channel layout describing the channels to be extracted as separate output streams +or "all" to extract each input channel as a separate stream. The default is "all". +

+

Choosing channels not present in channel layout in the input will result in an error. +

+
+ + +

27.75.1 Examples

+ +
    +
  • For example, assuming a stereo input MP3 file, +
    +
    ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
    +
    +

    will create an output Matroska file with two audio streams, one containing only +the left channel and the other the right channel. +

    +
  • Split a 5.1 WAV file into per-channel files: +
    +
    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
    +
    + +
  • Extract only LFE from a 5.1 WAV file: +
    +
    ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
    +-map '[LFE]' lfe.wav
    +
    +
+ + +

27.76 chorus

+

Add a chorus effect to the audio. +

+

Can make a single vocal sound like a chorus, but can also be applied to instrumentation. +

+

Chorus resembles an echo effect with a short delay, but whereas with echo the delay is +constant, with chorus, it is varied using sinusoidal or triangular modulation. +The modulation depth defines the range the modulated delay is played before or after +the delay. Hence the delayed sound will sound slower or faster, that is the delayed +sound tuned around the original one, like in a chorus where some vocals are slightly +off key. +

+

It accepts the following parameters: +

+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.4. +

+
+
delays
+

Set delays. A typical delay is around 40ms to 60ms. +

+
+
decays
+

Set decays. +

+
+
speeds
+

Set speeds. +

+
+
depths
+

Set depths. +

+
+ + +

27.76.1 Examples

+ +
    +
  • A single delay: +
    +
    chorus=0.7:0.9:55:0.4:0.25:2
    +
    + +
  • Two delays: +
    +
    chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
    +
    + +
  • Fuller sounding chorus with three delays: +
    +
    chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3
    +
    +
+ + +

27.77 compand

+

Compress or expand the audio’s dynamic range. +

+

It accepts the following parameters: +

+
+
attacks
+
decays
+

A list of times in seconds for each channel over which the instantaneous level +of the input signal is averaged to determine its volume. attacks refers to +increase of volume and 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. A typical value for attack is 0.3 seconds and +a typical value for decay is 0.8 seconds. +If specified number of attacks & decays is lower than number of channels, the last +set attack/decay will be used for all remaining channels. +

+
+
points
+

A list of points for the transfer function, specified in dB relative to the +maximum possible signal amplitude. Each key points list must be defined using +the following syntax: x0/y0|x1/y1|x2/y2|.... or +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 0/0 is assumed but +may be overridden (by 0/out-dBn). Typical values for the transfer +function are -70/-70|-60/-20|1/0. +

+
+
soft-knee
+

Set the curve radius in dB for all joints. It defaults to 0.01. +

+
+
gain
+

Set the additional gain in dB to be applied at all points on the transfer +function. This allows for easy adjustment of the overall gain. +It defaults to 0. +

+
+
volume
+

Set an 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. It defaults to 0. +

+
+
delay
+

Set a delay, in seconds. The input audio is analyzed 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. It defaults to 0. +

+
+
+ + +

27.77.1 Examples

+ +
    +
  • Make music with both quiet and loud passages suitable for listening to in a +noisy environment: +
    +
    compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
    +
    + +

    Another example for audio with whisper and explosion parts: +

    +
    compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
    +
    + +
  • A noise gate for when the noise is at a lower level than the signal: +
    +
    compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
    +
    + +
  • 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): +
    +
    compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
    +
    + +
  • 2:1 compression starting at -6dB: +
    +
    compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
    +
    + +
  • 2:1 compression starting at -9dB: +
    +
    compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
    +
    + +
  • 2:1 compression starting at -12dB: +
    +
    compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
    +
    + +
  • 2:1 compression starting at -18dB: +
    +
    compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
    +
    + +
  • 3:1 compression starting at -15dB: +
    +
    compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
    +
    + +
  • Compressor/Gate: +
    +
    compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
    +
    + +
  • Expander: +
    +
    compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
    +
    + +
  • Hard limiter at -6dB: +
    +
    compand=attacks=0:points=-80/-80|-6/-6|20/-6
    +
    + +
  • Hard limiter at -12dB: +
    +
    compand=attacks=0:points=-80/-80|-12/-12|20/-12
    +
    + +
  • Hard noise gate at -35 dB: +
    +
    compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
    +
    + +
  • Soft limiter: +
    +
    compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
    +
    +
+ + +

27.78 compensationdelay

+ +

Compensation Delay Line is a metric based delay to compensate differing +positions of microphones or speakers. +

+

For example, you have recorded guitar with two microphones placed in +different locations. Because the front of sound wave has fixed speed in +normal conditions, the phasing of microphones can vary and depends on +their location and interposition. The best sound mix can be achieved when +these microphones are in phase (synchronized). Note that a distance of +~30 cm between microphones makes one microphone capture the signal in +antiphase to the other microphone. That makes the final mix sound moody. +This filter helps to solve phasing problems by adding different delays +to each microphone track and make them synchronized. +

+

The best result can be reached when you take one track as base and +synchronize other tracks one by one with it. +Remember that synchronization/delay tolerance depends on sample rate, too. +Higher sample rates will give more tolerance. +

+

The filter accepts the following parameters: +

+
+
mm
+

Set millimeters distance. This is compensation distance for fine tuning. +Default is 0. +

+
+
cm
+

Set cm distance. This is compensation distance for tightening distance setup. +Default is 0. +

+
+
m
+

Set meters distance. This is compensation distance for hard distance setup. +Default is 0. +

+
+
dry
+

Set dry amount. Amount of unprocessed (dry) signal. +Default is 0. +

+
+
wet
+

Set wet amount. Amount of processed (wet) signal. +Default is 1. +

+
+
temp
+

Set temperature in degrees Celsius. This is the temperature of the environment. +Default is 20. +

+
+ + +

27.78.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.79 crossfeed

+

Apply headphone crossfeed filter. +

+

Crossfeed is the process of blending the left and right channels of stereo +audio recording. +It is mainly used to reduce extreme stereo separation of low frequencies. +

+

The intent is to produce more speaker like sound to the listener. +

+

The filter accepts the following options: +

+
+
strength
+

Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. +This sets gain of low shelf filter for side part of stereo image. +Default is -6dB. Max allowed is -30db when strength is set to 1. +

+
+
range
+

Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. +This sets cut off frequency of low shelf filter. Default is cut off near +1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. +

+
+
slope
+

Set curve slope of low shelf filter. Default is 0.5. +Allowed range is from 0.01 to 1. +

+
+
level_in
+

Set input gain. Default is 0.9. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
block_size
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.79.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.80 crystalizer

+

Simple algorithm for audio noise sharpening. +

+

This filter linearly increases differences between each audio sample. +

+

The filter accepts the following options: +

+
+
i
+

Sets the intensity of effect (default: 2.0). Must be in range between -10.0 to 0 +(unchanged sound) to 10.0 (maximum effect). +To inverse filtering use negative value. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

27.80.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.81 dcshift

+

Apply a DC shift to the audio. +

+

This can be useful to remove a DC offset (caused perhaps by a hardware problem +in the recording chain) from the audio. The effect of a DC offset is reduced +headroom and hence volume. The astats filter can be used to determine if +a signal has a DC offset. +

+
+
shift
+

Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift +the audio. +

+
+
limitergain
+

Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is +used to prevent clipping. +

+
+ + +

27.82 deesser

+ +

Apply de-essing to the audio samples. +

+
+
i
+

Set intensity for triggering de-essing. Allowed range is from 0 to 1. +Default is 0. +

+
+
m
+

Set amount of ducking on treble part of sound. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
f
+

How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
s
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass ess filtered out. +

+
+
e
+

Pass only ess. +

+

Default value is o. +

+
+ +
+
+ + +

27.83 dialoguenhance

+

Enhance dialogue in stereo audio. +

+

This filter accepts stereo input and produce surround (3.0) channels output. +The newly produced front center channel have enhanced speech dialogue originally +available in both stereo channels. +This filter outputs front left and front right channels same as available in stereo input. +

+

The filter accepts the following options: +

+
+
original
+

Set the original center factor to keep in front center channel output. +Allowed range is from 0 to 1. Default value is 1. +

+
+
enhance
+

Set the dialogue enhance factor to put in front center channel output. +Allowed range is from 0 to 3. Default value is 1. +

+
+
voice
+

Set the voice detection factor. +Allowed range is from 2 to 32. Default value is 2. +

+
+ + +

27.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.84 drmeter

+

Measure audio dynamic range. +

+

DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 +is found in transition material. And anything less that 8 have very poor dynamics +and is very compressed. +

+

The filter accepts the following options: +

+
+
length
+

Set window length in seconds used to split audio into segments of equal length. +Default is 3 seconds. +

+
+ + +

27.85 dynaudnorm

+

Dynamic Audio Normalizer. +

+

This filter applies a certain amount of gain to the input audio in order +to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in +contrast to more "simple" normalization algorithms, the Dynamic Audio +Normalizer *dynamically* re-adjusts the gain factor to the input audio. +This allows for applying extra gain to the "quiet" sections of the audio +while avoiding distortions or clipping the "loud" sections. In other words: +The Dynamic Audio Normalizer will "even out" the volume of quiet and loud +sections, in the sense that the volume of each section is brought to the +same target level. Note, however, that the Dynamic Audio Normalizer achieves +this goal *without* applying "dynamic range compressing". It will retain 100% +of the dynamic range *within* each section of the audio file. +

+
+
framelen, f
+

Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. +Default is 500 milliseconds. +The Dynamic Audio Normalizer processes the input audio in small chunks, +referred to as frames. This is required, because a peak magnitude has no +meaning for just a single sample value. Instead, we need to determine the +peak magnitude for a contiguous sequence of sample values. While a "standard" +normalizer would simply use the peak magnitude of the complete file, the +Dynamic Audio Normalizer determines the peak magnitude individually for each +frame. The length of a frame is specified in milliseconds. By default, the +Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has +been found to give good results with most files. +Note that the exact frame length, in number of samples, will be determined +automatically, based on the sampling rate of the individual input audio file. +

+
+
gausssize, g
+

Set the Gaussian filter window size. In range from 3 to 301, must be odd +number. Default is 31. +Probably the most important parameter of the Dynamic Audio Normalizer is the +window size of the Gaussian smoothing filter. The filter’s window size +is specified in frames, centered around the current frame. For the sake of +simplicity, this must be an odd number. Consequently, the default value of 31 +takes into account the current frame, as well as the 15 preceding frames and +the 15 subsequent frames. Using a larger window results in a stronger +smoothing effect and thus in less gain variation, i.e. slower gain +adaptation. Conversely, using a smaller window results in a weaker smoothing +effect and thus in more gain variation, i.e. faster gain adaptation. +In other words, the more you increase this value, the more the Dynamic Audio +Normalizer will behave like a "traditional" normalization filter. On the +contrary, the more you decrease this value, the more the Dynamic Audio +Normalizer will behave like a dynamic range compressor. +

+
+
peak, p
+

Set the target peak value. This specifies the highest permissible magnitude +level for the normalized audio input. This filter will try to approach the +target peak magnitude as closely as possible, but at the same time it also +makes sure that the normalized signal will never exceed the peak magnitude. +A frame’s maximum local gain factor is imposed directly by the target peak +magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. +It is not recommended to go above this value. +

+
+
maxgain, m
+

Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. +The Dynamic Audio Normalizer determines the maximum possible (local) gain +factor for each input frame, i.e. the maximum gain factor that does not +result in clipping or distortion. The maximum gain factor is determined by +the frame’s highest magnitude sample. However, the Dynamic Audio Normalizer +additionally bounds the frame’s maximum gain factor by a predetermined +(global) maximum gain factor. This is done in order to avoid excessive gain +factors in "silent" or almost silent frames. By default, the maximum gain +factor is 10.0, For most inputs the default value should be sufficient and +it usually is not recommended to increase this value. Though, for input +with an extremely low overall volume level, it may be necessary to allow even +higher gain factors. Note, however, that the Dynamic Audio Normalizer does +not simply apply a "hard" threshold (i.e. cut off values above the threshold). +Instead, a "sigmoid" threshold function will be applied. This way, the +gain factors will smoothly approach the threshold value, but never exceed that +value. +

+
+
targetrms, r
+

Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. +By default, the Dynamic Audio Normalizer performs "peak" normalization. +This means that the maximum local gain factor for each frame is defined +(only) by the frame’s highest magnitude sample. This way, the samples can +be amplified as much as possible without exceeding the maximum signal +level, i.e. without clipping. Optionally, however, the Dynamic Audio +Normalizer can also take into account the frame’s root mean square, +abbreviated RMS. In electrical engineering, the RMS is commonly used to +determine the power of a time-varying signal. It is therefore considered +that the RMS is a better approximation of the "perceived loudness" than +just looking at the signal’s peak magnitude. Consequently, by adjusting all +frames to a constant RMS value, a uniform "perceived loudness" can be +established. If a target RMS value has been specified, a frame’s local gain +factor is defined as the factor that would result in exactly that RMS value. +Note, however, that the maximum local gain factor is still restricted by the +frame’s highest magnitude sample, in order to prevent clipping. +

+
+
coupling, n
+

Enable channels coupling. By default is enabled. +By default, the Dynamic Audio Normalizer will amplify all channels by the same +amount. This means the same gain factor will be applied to all channels, i.e. +the maximum possible gain factor is determined by the "loudest" channel. +However, in some recordings, it may happen that the volume of the different +channels is uneven, e.g. one channel may be "quieter" than the other one(s). +In this case, this option can be used to disable the channel coupling. This way, +the gain factor will be determined independently for each channel, depending +only on the individual channel’s highest magnitude sample. This allows for +harmonizing the volume of the different channels. +

+
+
correctdc, c
+

Enable DC bias correction. By default is disabled. +An audio signal (in the time domain) is a sequence of sample values. +In the Dynamic Audio Normalizer these sample values are represented in the +-1.0 to 1.0 range, regardless of the original input format. Normally, the +audio signal, or "waveform", should be centered around the zero point. +That means if we calculate the mean value of all samples in a file, or in a +single frame, then the result should be 0.0 or at least very close to that +value. If, however, there is a significant deviation of the mean value from +0.0, in either positive or negative direction, this is referred to as a +DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic +Audio Normalizer provides optional DC bias correction. +With DC bias correction enabled, the Dynamic Audio Normalizer will determine +the mean value, or "DC correction" offset, of each input frame and subtract +that value from all of the frame’s sample values which ensures those samples +are centered around 0.0 again. Also, in order to avoid "gaps" at the frame +boundaries, the DC correction offset values will be interpolated smoothly +between neighbouring frames. +

+
+
altboundary, b
+

Enable alternative boundary mode. By default is disabled. +The Dynamic Audio Normalizer takes into account a certain neighbourhood +around each frame. This includes the preceding frames as well as the +subsequent frames. However, for the "boundary" frames, located at the very +beginning and at the very end of the audio file, not all neighbouring +frames are available. In particular, for the first few frames in the audio +file, the preceding frames are not known. And, similarly, for the last few +frames in the audio file, the subsequent frames are not known. Thus, the +question arises which gain factors should be assumed for the missing frames +in the "boundary" region. The Dynamic Audio Normalizer implements two modes +to deal with this situation. The default boundary mode assumes a gain factor +of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and +"fade out" at the beginning and at the end of the input, respectively. +

+
+
compress, s
+

Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. +By default, the Dynamic Audio Normalizer does not apply "traditional" +compression. This means that signal peaks will not be pruned and thus the +full dynamic range will be retained within each local neighbourhood. However, +in some cases it may be desirable to combine the Dynamic Audio Normalizer’s +normalization algorithm with a more "traditional" compression. +For this purpose, the Dynamic Audio Normalizer provides an optional compression +(thresholding) function. If (and only if) the compression feature is enabled, +all input frames will be processed by a soft knee thresholding function prior +to the actual normalization process. Put simply, the thresholding function is +going to prune all samples whose magnitude exceeds a certain threshold value. +However, the Dynamic Audio Normalizer does not simply apply a fixed threshold +value. Instead, the threshold value will be adjusted for each individual +frame. +In general, smaller parameters result in stronger compression, and vice versa. +Values below 3.0 are not recommended, because audible distortion may appear. +

+
+
threshold, t
+

Set the target threshold value. This specifies the lowest permissible +magnitude level for the audio input which will be normalized. +If input frame volume is above this value frame will be normalized. +Otherwise frame may not be normalized at all. The default value is set +to 0, which means all input frames will be normalized. +This option is mostly useful if digital noise is not wanted to be amplified. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
overlap, o
+

Specify overlap for frames. If set to 0 (default) no frame overlapping is done. +Using >0 and <1 values will make less conservative gain adjustments, like +when framelen option is set to smaller value, if framelen option value is +compensated for non-zero overlap then gain adjustments will be smoother across time +compared to zero overlap case. +

+
+
curve, v
+

Specify the peak mapping curve expression which is going to be used when calculating +gain applied to frames. The max output frame gain will still be limited by other +options mentioned previously for this filter. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frame peak value +

+
+
+
+ + +

27.85.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.86 earwax

+ +

Make audio easier to listen to on headphones. +

+

This filter adds ‘cues’ to 44.1kHz stereo (i.e. audio CD format) audio +so that when listened to on headphones the stereo image is moved from +inside your head (standard for headphones) to outside and in front of +the listener (standard for speakers). +

+

Ported from SoX. +

+ +

27.87 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: +

+
+
frequency, f
+

Set the filter’s central frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
gain, g
+

Set the required gain or attenuation in dB. +Beware of clipping when using a positive gain. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.87.1 Examples

+
    +
  • Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: +
    +
    equalizer=f=1000:t=h:width=200:g=-10
    +
    + +
  • Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: +
    +
    equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
    +
    +
+ + +

27.87.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change equalizer frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change equalizer width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change equalizer width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change equalizer gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change equalizer mix. +Syntax for the command is : "mix" +

+
+ + +

27.88 extrastereo

+ +

Linearly increases the difference between left and right channels which +adds some sort of "live" effect to playback. +

+

The filter accepts the following options: +

+
+
m
+

Sets the difference coefficient (default: 2.5). 0.0 means mono sound +(average of both channels), with 1.0 sound will be unchanged, with +-1.0 left and right channels will be swapped. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

27.88.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.89 firequalizer

+

Apply FIR Equalization using arbitrary frequency response. +

+

The filter accepts the following option: +

+
+
gain
+

Set gain curve equation (in dB). The expression can contain variables: +

+
f
+

the evaluated frequency +

+
sr
+

sample rate +

+
ch
+

channel number, set to 0 when multichannels evaluation is disabled +

+
chid
+

channel id, see libavutil/channel_layout.h, set to the first channel id when +multichannels evaluation is disabled +

+
chs
+

number of channels +

+
chlayout
+

channel_layout, see libavutil/channel_layout.h +

+
+
+

and functions: +

+
gain_interpolate(f)
+

interpolate gain on frequency f based on gain_entry +

+
cubic_interpolate(f)
+

same as gain_interpolate, but smoother +

+
+

This option is also available as command. Default is gain_interpolate(f). +

+
+
gain_entry
+

Set gain entry for gain_interpolate function. The expression can +contain functions: +

+
entry(f, g)
+

store gain entry at frequency f with value g +

+
+

This option is also available as command. +

+
+
delay
+

Set filter delay in seconds. Higher value means more accurate. +Default is 0.01. +

+
+
accuracy
+

Set filter accuracy in Hz. Lower value means more accurate. +Default is 5. +

+
+
wfunc
+

Set window function. Acceptable values are: +

+
rectangular
+

rectangular window, useful when gain curve is already smooth +

+
hann
+

hann window (default) +

+
hamming
+

hamming window +

+
blackman
+

blackman window +

+
nuttall3
+

3-terms continuous 1st derivative nuttall window +

+
mnuttall3
+

minimum 3-terms discontinuous nuttall window +

+
nuttall
+

4-terms continuous 1st derivative nuttall window +

+
bnuttall
+

minimum 4-terms discontinuous nuttall (blackman-nuttall) window +

+
bharris
+

blackman-harris window +

+
tukey
+

tukey window +

+
+ +
+
fixed
+

If enabled, use fixed number of audio samples. This improves speed when +filtering with large delay. Default is disabled. +

+
+
multi
+

Enable multichannels evaluation on gain. Default is disabled. +

+
+
zero_phase
+

Enable zero phase mode by subtracting timestamp to compensate delay. +Default is disabled. +

+
+
scale
+

Set scale used by gain. Acceptable values are: +

+
linlin
+

linear frequency, linear gain +

+
linlog
+

linear frequency, logarithmic (in dB) gain (default) +

+
loglin
+

logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain +

+
loglog
+

logarithmic frequency, logarithmic gain +

+
+ +
+
dumpfile
+

Set file for dumping, suitable for gnuplot. +

+
+
dumpscale
+

Set scale for dumpfile. Acceptable values are same with scale option. +Default is linlog. +

+
+
fft2
+

Enable 2-channel convolution using complex FFT. This improves speed significantly. +Default is disabled. +

+
+
min_phase
+

Enable minimum phase impulse response. Default is disabled. +

+
+ + +

27.89.1 Examples

+
    +
  • lowpass at 1000 Hz: +
    +
    firequalizer=gain='if(lt(f,1000), 0, -INF)'
    +
    +
  • lowpass at 1000 Hz with gain_entry: +
    +
    firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
    +
    +
  • custom equalization: +
    +
    firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
    +
    +
  • higher delay with zero phase to compensate delay: +
    +
    firequalizer=delay=0.1:fixed=on:zero_phase=on
    +
    +
  • lowpass on left channel, highpass on right channel: +
    +
    firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
    +:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
    +
    +
+ + +

27.90 flanger

+

Apply a flanging effect to the audio. +

+

The filter accepts the following options: +

+
+
delay
+

Set base delay in milliseconds. Range from 0 to 30. Default value is 0. +

+
+
depth
+

Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. +

+
+
regen
+

Set percentage regeneration (delayed signal feedback). Range from -95 to 95. +Default value is 0. +

+
+
width
+

Set percentage of delayed signal mixed with original. Range from 0 to 100. +Default value is 71. +

+
+
speed
+

Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. +

+
+
shape
+

Set swept wave shape, can be triangular or sinusoidal. +Default value is sinusoidal. +

+
+
phase
+

Set swept wave percentage-shift for multi channel. Range from 0 to 100. +Default value is 25. +

+
+
interp
+

Set delay-line interpolation, linear or quadratic. +Default is linear. +

+
+ + +

27.91 haas

+

Apply Haas effect to audio. +

+

Note that this makes most sense to apply on mono signals. +With this filter applied to mono signals it give some directionality and +stretches its stereo image. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level. By default is 1, or 0dB +

+
+
level_out
+

Set output level. By default is 1, or 0dB. +

+
+
side_gain
+

Set gain applied to side part of signal. By default is 1. +

+
+
middle_source
+

Set kind of middle source. Can be one of the following: +

+
+
‘left’
+

Pick left channel. +

+
+
‘right’
+

Pick right channel. +

+
+
‘mid’
+

Pick middle part signal of stereo image. +

+
+
‘side’
+

Pick side part signal of stereo image. +

+
+ +
+
middle_phase
+

Change middle phase. By default is disabled. +

+
+
left_delay
+

Set left channel delay. By default is 2.05 milliseconds. +

+
+
left_balance
+

Set left channel balance. By default is -1. +

+
+
left_gain
+

Set left channel gain. By default is 1. +

+
+
left_phase
+

Change left phase. By default is disabled. +

+
+
right_delay
+

Set right channel delay. By defaults is 2.12 milliseconds. +

+
+
right_balance
+

Set right channel balance. By default is 1. +

+
+
right_gain
+

Set right channel gain. By default is 1. +

+
+
right_phase
+

Change right phase. By default is enabled. +

+
+ + +

27.92 hdcd

+ +

Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with +embedded HDCD codes is expanded into a 20-bit PCM stream. +

+

The filter supports the Peak Extend and Low-level Gain Adjustment features +of HDCD, and detects the Transient Filter flag. +

+
+
ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
+
+ +

When using the filter with wav, note the default encoding for wav is 16-bit, +so the resulting 20-bit stream will be truncated back to 16-bit. Use something +like -acodec pcm_s24le after the filter to get 24-bit PCM output. +

+
ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
+ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
+
+ +

The filter accepts the following options: +

+
+
disable_autoconvert
+

Disable any automatic format conversion or resampling in the filter graph. +

+
+
process_stereo
+

Process the stereo channels together. If target_gain does not match between +channels, consider it invalid and use the last valid target_gain. +

+
+
cdt_ms
+

Set the code detect timer period in ms. +

+
+
force_pe
+

Always extend peaks above -3dBFS even if PE isn’t signaled. +

+
+
analyze_mode
+

Replace audio with a solid tone and adjust the amplitude to signal some +specific aspect of the decoding process. The output file can be loaded in +an audio editor alongside the original to aid analysis. +

+

analyze_mode=pe:force_pe=true can be used to see all samples above the PE level. +

+

Modes are: +

+
‘0, off’
+

Disabled +

+
‘1, lle’
+

Gain adjustment level at each sample +

+
‘2, pe’
+

Samples where peak extend occurs +

+
‘3, cdt’
+

Samples where the code detect timer is active +

+
‘4, tgm’
+

Samples where the target gain does not match between channels +

+
+
+
+ + +

27.93 headphone

+ +

Apply head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones. +The HRIRs are provided via additional streams, for each channel +one stereo input stream is needed. +

+

The filter accepts the following options: +

+
+
map
+

Set mapping of input streams for convolution. +The argument is a ’|’-separated list of channel names in order as they +are given as additional stream inputs for filter. +This also specify number of input streams. Number of input streams +must be not less than number of channels in first stream plus one. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
lfe
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
size
+

Set size of frame in number of samples which will be processed at once. +Default value is 1024. Allowed range is from 1024 to 96000. +

+
+
hrir
+

Set format of hrir stream. +Default value is stereo. Alternative value is multich. +If value is set to stereo, number of additional streams should +be greater or equal to number of input channels in first input stream. +Also each additional stream should have stereo number of channels. +If value is set to multich, number of additional streams should +be exactly one. Also number of input channels of additional stream +should be equal or greater than twice number of channels of first input +stream. +

+
+ + +

27.93.1 Examples

+ +
    +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +each amovie filter use stereo file with IR coefficients as input. +The files give coefficients for each position of virtual loudspeaker: +
    +
    ffmpeg -i input.wav
    +-filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
    +output.wav
    +
    + +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +but now in multich hrir format. +
    +
    ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
    +output.wav
    +
    +
+ + +

27.94 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 3000. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.94.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change highpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change highpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change highpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change highpass mix. +Syntax for the command is : "mix" +

+
+ + +

27.95 join

+ +

Join multiple input streams into one multi-channel stream. +

+

It accepts the following parameters: +

+
inputs
+

The number of input streams. It defaults to 2. +

+
+
channel_layout
+

The desired output channel layout. It defaults to stereo. +

+
+
map
+

Map channels from inputs to output. The argument is a ’|’-separated list of +mappings, each in the input_idx.in_channel-out_channel +form. input_idx is the 0-based index of the input stream. 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. out_channel is the name of the output +channel. +

+
+ +

The filter will attempt to guess the mappings when they 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. +

+

Join 3 inputs (with properly set channel layouts): +

+
ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
+
+ +

Build a 5.1 output from 6 single-channel streams: +

+
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
+
+ + +

27.96 ladspa

+ +

Load a LADSPA (Linux Audio Developer’s Simple Plugin API) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-ladspa. +

+
+
file, f
+

Specifies the name of LADSPA plugin library to load. If the environment +variable LADSPA_PATH is defined, the LADSPA plugin is searched in +each one of the directories specified by the colon separated list in +LADSPA_PATH, otherwise in the standard LADSPA paths, which are in +this order: HOME/.ladspa/lib/, /usr/local/lib/ladspa/, +/usr/lib/ladspa/. +

+
+
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. +

+
+
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=value0|c1=value1|c2=value2|..., where +valuei is the value set on the i-th control. +Alternatively they can be also defined using the following syntax: +value0|value1|value2|..., where +valuei is the value set on the i-th control. +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
latency, l
+

Enable latency compensation, by default is disabled. +Only used if plugin have inputs. +

+
+ + +

27.96.1 Examples

+ +
    +
  • List all available plugins within amp (LADSPA example plugin) library: +
    +
    ladspa=file=amp
    +
    + +
  • List all available controls and their valid ranges for vcf_notch +plugin from VCF library: +
    +
    ladspa=f=vcf:p=vcf_notch:c=help
    +
    + +
  • Simulate low quality audio equipment using Computer Music Toolkit (CMT) +plugin library: +
    +
    ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
    +
    + +
  • Add reverberation to the audio using TAP-plugins +(Tom’s Audio Processing plugins): +
    +
    ladspa=file=tap_reverb:tap_reverb
    +
    + +
  • Generate white noise, with 0.2 amplitude: +
    +
    ladspa=file=cmt:noise_source_white:c=c0=.2
    +
    + +
  • Generate 20 bpm clicks using plugin C* Click - Metronome from the +C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=file=caps:Click:c=c1=20'
    +
    + +
  • Apply C* Eq10X2 - Stereo 10-band equaliser effect: +
    +
    ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
    +
    + +
  • Increase volume by 20dB using fast lookahead limiter from Steve Harris +SWH Plugins collection: +
    +
    ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
    +
    + +
  • Attenuate low frequencies using Multiband EQ from Steve Harris +SWH Plugins collection: +
    +
    ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
    +
    + +
  • Reduce stereo image using Narrower from the C* Audio Plugin Suite +(CAPS) library: +
    +
    ladspa=caps:Narrower
    +
    + +
  • Another white noise, now using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:White:.2
    +
    + +
  • Some fractal noise, using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:Fractal:c=c1=1
    +
    + +
  • Dynamic volume normalization using VLevel plugin: +
    +
    ladspa=vlevel-ladspa:vlevel_mono
    +
    +
+ + +

27.96.2 Commands

+ +

This filter supports the following commands: +

+
cN
+

Modify the N-th control value. +

+

If the specified value is not valid, it is ignored and prior one is kept. +

+
+ + +

27.97 loudnorm

+ +

EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. +Support for both single pass (livestreams, files) and double pass (files) modes. +This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately +detect true peaks, the audio stream will be upsampled to 192 kHz. +Use the -ar option or aresample filter to explicitly set an output sample rate. +

+

The filter accepts the following options: +

+
+
I, i
+

Set integrated loudness target. +Range is -70.0 - -5.0. Default value is -24.0. +

+
+
LRA, lra
+

Set loudness range target. +Range is 1.0 - 50.0. Default value is 7.0. +

+
+
TP, tp
+

Set maximum true peak. +Range is -9.0 - +0.0. Default value is -2.0. +

+
+
measured_I, measured_i
+

Measured IL of input file. +Range is -99.0 - +0.0. +

+
+
measured_LRA, measured_lra
+

Measured LRA of input file. +Range is 0.0 - 99.0. +

+
+
measured_TP, measured_tp
+

Measured true peak of input file. +Range is -99.0 - +99.0. +

+
+
measured_thresh
+

Measured threshold of input file. +Range is -99.0 - +0.0. +

+
+
offset
+

Set offset gain. Gain is applied before the true-peak limiter. +Range is -99.0 - +99.0. Default is +0.0. +

+
+
linear
+

Normalize by linearly scaling the source audio. +measured_I, measured_LRA, measured_TP, +and measured_thresh must all be specified. Target LRA shouldn’t +be lower than source LRA and the change in integrated loudness shouldn’t +result in a true peak which exceeds the target TP. If any of these +conditions aren’t met, normalization mode will revert to dynamic. +Options are true or false. Default is true. +

+
+
dual_mono
+

Treat mono input files as "dual-mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +Options are true or false. Default is false. +

+
+
print_format
+

Set print format for stats. Options are summary, json, or none. +Default value is none. +

+
+
stats_file
+

Write stats to specified file. Format is controlled by print_format, +which must be set. Specify - to write to standard output. +Default is unset. +

+
+ + +

27.98 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 500. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.98.1 Examples

+
    +
  • Lowpass only LFE channel, it LFE is not present it does nothing: +
    +
    lowpass=c=LFE
    +
    +
+ + +

27.98.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change lowpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change lowpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change lowpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change lowpass mix. +Syntax for the command is : "mix" +

+
+ + +

27.99 lv2

+ +

Load a LV2 (LADSPA Version 2) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-lv2. +

+
+
plugin, p
+

Specifies the plugin URI. You may need to escape ’:’. +

+
+
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). +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+ + +

27.99.1 Examples

+ +
    +
  • Apply bass enhancer plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
    +
    + +
  • Apply vinyl plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
    +
    + +
  • Apply bit crusher plugin from ArtyFX: +
    +
    lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
    +
    +
+ + +

27.99.2 Commands

+ +

This filter supports all options that are exported by plugin as commands. +

+ +

27.100 mcompand

+

Multiband Compress or expand the audio’s dynamic range. +

+

The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. +This is akin to the crossover of a loudspeaker, and results in flat frequency +response when absent compander action. +

+

It accepts the following parameters: +

+
+
args
+

This option syntax is: +attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... +For explanation of each item refer to compand filter documentation. +

+
+ + +

27.101 pan

+ +

Mix channels with specific gain levels. The filter accepts the output +channel layout followed by a set of channels definitions. +

+

This filter is also designed to efficiently remap the channels of an audio +stream. +

+

The filter accepts parameters of the form: +"l|outdef|outdef|..." +

+
+
l
+

output channel layout or number of channels +

+
+
outdef
+

output channel specification, of the form: +"out_name=[gain*]in_name[(+-)[gain*]in_name...]" +

+
+
out_name
+

output channel to define, either a channel name (FL, FR, etc.) or a channel +number (c0, c1, etc.) +

+
+
gain
+

multiplicative coefficient for the channel, 1 leaving the volume unchanged +

+
+
in_name
+

input channel to use, see out_name for details; it is not possible to mix +named and numbered input channels +

+
+ +

If the ‘=’ in a channel specification is replaced by ‘<’, then the gains for +that specification will be renormalized so that the total is 1, thus +avoiding clipping noise. +

+ +

27.101.1 Mixing examples

+ +

For example, if you want to down-mix from stereo to mono, but with a bigger +factor for the left channel: +

+
pan=1c|c0=0.9*c0+0.1*c1
+
+ +

A customized down-mix to stereo that works automatically for 3-, 4-, 5- and +7-channels surround: +

+
pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
+
+ +

Note that ffmpeg integrates a default down-mix (and up-mix) system +that should be preferred (see "-ac" option) unless you have very specific +needs. +

+ +

27.101.2 Remapping examples

+ +

The channel remapping will be effective if, and only if: +

+
    +
  • gain coefficients are zeroes or ones, +
  • only one input per channel output, +
+ +

If all these conditions are satisfied, the filter will notify the user ("Pure +channel mapping detected"), and use an optimized and lossless method to do the +remapping. +

+

For example, if you have a 5.1 source and want a stereo audio stream by +dropping the extra channels: +

+
pan="stereo| c0=FL | c1=FR"
+
+ +

Given the same source, you can also switch front left and front right channels +and keep the input channel layout: +

+
pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
+
+ +

If the input is a stereo audio stream, you can mute the front left channel (and +still keep the stereo channel layout) with: +

+
pan="stereo|c1=c1"
+
+ +

Still with a stereo audio stream input, you can copy the right channel in both +front left and right: +

+
pan="stereo| c0=FR | c1=FR"
+
+ + +

27.102 replaygain

+ +

ReplayGain scanner filter. This filter takes an audio stream as an input and +outputs it unchanged. +At end of filtering it displays track_gain and track_peak. +

+

The filter accepts the following exported read-only options: +

+
+
track_gain
+

Exported track gain in dB at end of stream. +

+
+
track_peak
+

Exported track peak at end of stream. +

+
+ + +

27.103 resample

+ +

Convert the audio sample format, sample rate and channel layout. It is +not meant to be used directly. +

+ +

27.104 rubberband

+

Apply time-stretching and pitch-shifting with librubberband. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-librubberband. +

+

The filter accepts the following options: +

+
+
tempo
+

Set tempo scale factor. +

+
+
pitch
+

Set pitch scale factor. +

+
+
transients
+

Set transients detector. +Possible values are: +

+
crisp
+
mixed
+
smooth
+
+ +
+
detector
+

Set detector. +Possible values are: +

+
compound
+
percussive
+
soft
+
+ +
+
phase
+

Set phase. +Possible values are: +

+
laminar
+
independent
+
+ +
+
window
+

Set processing window size. +Possible values are: +

+
standard
+
short
+
long
+
+ +
+
smoothing
+

Set smoothing. +Possible values are: +

+
off
+
on
+
+ +
+
formant
+

Enable formant preservation when shift pitching. +Possible values are: +

+
shifted
+
preserved
+
+ +
+
pitchq
+

Set pitch quality. +Possible values are: +

+
quality
+
speed
+
consistency
+
+ +
+
channels
+

Set channels. +Possible values are: +

+
apart
+
together
+
+
+
+ + +

27.104.1 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+
pitch
+

Change filter pitch scale factor. +Syntax for the command is : "pitch" +

+
+ + +

27.105 sidechaincompress

+ +

This filter acts like normal compressor but has the ability to compress +detected signal using second input signal. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +The filtered signal then can be filtered with other filters in later stages of +processing. See pan and amerge filter. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of second stream raises above this level it will affect the gain +reduction of first stream. +By default is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. 1:2 means that if the level +raised 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of side-chain stream +or the louder(maximum) channel of side-chain stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mainly smoother. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

27.105.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.105.2 Examples

+ +
    +
  • Full ffmpeg example taking 2 audio inputs, 1st input to be compressed +depending on the signal of 2nd input and later compressed signal to be +merged with 2nd input: +
    +
    ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
    +
    +
+ + +

27.106 sidechaingate

+ +

A sidechain gate acts like a normal (wideband) gate but has the ability to +filter the detected signal before sending it to the gain reduction stage. +Normally a gate uses the full range signal to detect a level above the +threshold. +For example: If you cut all lower frequencies from your sidechain signal +the gate will decrease the volume of your track only if not enough highs +appear. With this technique you are able to reduce the resonation of a +natural drum or remove "rumbling" of muted strokes from a heavily distorted +guitar. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is from 0.015625 to 64. +

+
+ + +

27.106.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.107 silencedetect

+ +

Detect silence in an audio stream. +

+

This filter logs a message when it detects that the input audio volume is less +or equal to a noise tolerance value for a duration greater or equal to the +minimum detected noise duration. +

+

The printed times and duration are expressed in seconds. The +lavfi.silence_start or lavfi.silence_start.X metadata key +is set on the first frame whose timestamp equals or exceeds the detection +duration and it contains the timestamp of the first frame of the silence. +

+

The lavfi.silence_duration or lavfi.silence_duration.X +and lavfi.silence_end or lavfi.silence_end.X metadata +keys are set on the first frame after the silence. If mono is +enabled, and each channel is evaluated separately, the .X +suffixed keys are used, and X corresponds to the channel number. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or amplitude ratio. Default is -60dB, or 0.001. +

+
+
duration, d
+

Set silence duration until notification (default is 2 seconds). See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+
+
mono, m
+

Process each channel separately, instead of combined. By default is disabled. +

+
+ + +

27.107.1 Examples

+ +
    +
  • Detect 5 seconds of silence with -50dB noise tolerance: +
    +
    silencedetect=n=-50dB:d=5
    +
    + +
  • Complete example with ffmpeg to detect silence with 0.0001 noise +tolerance in silence.mp3: +
    +
    ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
    +
    +
+ + +

27.108 silenceremove

+ +

Remove silence from the beginning, middle or end of the audio. +

+

The filter accepts the following options: +

+
+
start_periods
+

This value is used to indicate if audio should be trimmed at beginning of +the audio. A value of zero indicates no silence should be trimmed from the +beginning. When specifying a non-zero value, it trims audio up until it +finds non-silence. Normally, when trimming silence from beginning of audio +the start_periods will be 1 but it can be increased to higher +values to trim all audio up to specific count of non-silence periods. +Default value is 0. +

+
+
start_duration
+

Specify the amount of time that non-silence must be detected before it stops +trimming audio. By increasing the duration, bursts of noises can be treated +as silence and trimmed off. Default value is 0. +

+
+
start_threshold
+

This indicates what sample value should be treated as silence. For digital +audio, a value of 0 may be fine but for audio recorded from analog, +you may wish to increase the value to account for background noise. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
start_silence
+

Specify max duration of silence at beginning that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
start_mode
+

Specify mode of detection of silence end at start of multi-channel audio. +Can be any or all. Default is any. +With any, any sample from any channel that is detected as non-silence +will trigger end of silence trimming at start of audio stream. +With all, only if every sample from every channel is detected as non-silence +will trigger end of silence trimming at start of audio stream, limited usage. +

+
+
stop_periods
+

Set the count for trimming silence from the end of audio. When specifying a +positive value, it trims audio after it finds specified silence period. +To remove silence from the middle of a file, specify a stop_periods +that is negative. This value is then treated as a positive value and is +used to indicate the effect should restart processing as specified by +stop_periods, making it suitable for removing periods of silence +in the middle of the audio. +Default value is 0. +

+
+
stop_duration
+

Specify a duration of silence that must exist before audio is not copied any +more. By specifying a higher duration, silence that is wanted can be left in +the audio. +Default value is 0. +

+
+
stop_threshold
+

This is the same as start_threshold but for trimming silence from +the end of audio. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
stop_silence
+

Specify max duration of silence at end that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
stop_mode
+

Specify mode of detection of silence start after start of multi-channel audio. +Can be any or all. Default is all. +With any, any sample from any channel that is detected as silence +will trigger start of silence trimming after start of audio stream, limited usage. +With all, only if every sample from every channel is detected as silence +will trigger start of silence trimming after start of audio stream. +

+
+
detection
+

Set how is silence detected. +

+
avg
+

Mean of absolute values of samples in moving window. +

+
rms
+

Root squared mean of absolute values of samples in moving window. +

+
peak
+

Maximum of absolute values of samples in moving window. +

+
median
+

Median of absolute values of samples in moving window. +

+
ptp
+

Absolute of max peak to min peak difference of samples in moving window. +

+
dev
+

Standard deviation of values of samples in moving window. +

+
+

Default value is rms. +

+
+
window
+

Set duration in number of seconds used to calculate size of window in number +of samples for detecting silence. Using 0 will effectively disable +any windowing and use only single sample per channel for silence detection. +In that case it may be needed to also set start_silence and/or +stop_silence to nonzero values with also start_duration and/or +stop_duration to nonzero values. +Default value is 0.02. Allowed range is from 0 to 10. +

+
+
timestamp
+

Set processing mode of every audio frame output timestamp. +

+
write
+

Full timestamps rewrite, keep only the start time for the first output frame. +

+
copy
+

Non-dropped frames are left with same timestamp as input audio frame. +

+
+

Defaults value is write. +

+
+ + +

27.108.1 Examples

+ +
    +
  • The following example shows how this filter can be used to start a recording +that does not contain the delay at the start which usually occurs between +pressing the record button and the start of the performance: +
    +
    silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
    +
    + +
  • Trim all silence encountered from beginning to end where there is more than 1 +second of silence in audio: +
    +
    silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Trim all digital silence samples, using peak detection, from beginning to end +where there is more than 0 samples of digital silence in audio and digital +silence is detected in all channels at same positions in stream: +
    +
    silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
    +
    + +
  • Trim every 2nd encountered silence period from beginning to end where there is +more than 1 second of silence per silence period in audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Similar as above, but keep maximum of 0.5 seconds of silence from each trimmed period: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5
    +
    + +
  • Similar as above, but keep maximum of 1.5 seconds of silence from start of audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5:start_periods=1:start_duration=1:start_silence=1.5:stop_threshold=-90dB
    +
    +
+ + +

27.108.2 Commands

+ +

This filter supports some above options as commands. +

+ +

27.109 sofalizer

+ +

SOFAlizer uses head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones (audio +formats up to 9 channels supported). +The HRTFs are stored in SOFA files (see http://www.sofacoustics.org/ for a database). +SOFAlizer is developed at the Acoustics Research Institute (ARI) of the +Austrian Academy of Sciences. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libmysofa. +

+

The filter accepts the following options: +

+
+
sofa
+

Set the SOFA file used for rendering. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
rotation
+

Set rotation of virtual loudspeakers in deg. Default is 0. +

+
+
elevation
+

Set elevation of virtual speakers in deg. Default is 0. +

+
+
radius
+

Set distance in meters between loudspeakers and the listener with near-field +HRTFs. Default is 1. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
speakers
+

Set custom positions of virtual loudspeakers. Syntax for this option is: +<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. +Each virtual loudspeaker is described with short channel name following with +azimuth and elevation in degrees. +Each virtual loudspeaker description is separated by ’|’. +For example to override front left and front right channel positions use: +’speakers=FL 45 15|FR 345 15’. +Descriptions with unrecognised channel names are ignored. +

+
+
lfegain
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
framesize
+

Set custom frame size in number of samples. Default is 1024. +Allowed range is from 1024 to 96000. Only used if option ‘type’ +is set to freq. +

+
+
normalize
+

Should all IRs be normalized upon importing SOFA file. +By default is enabled. +

+
+
interpolate
+

Should nearest IRs be interpolated with neighbor IRs if exact position +does not match. By default is disabled. +

+
+
minphase
+

Minphase all IRs upon loading of SOFA file. By default is disabled. +

+
+
anglestep
+

Set neighbor search angle step. Only used if option interpolate is enabled. +

+
+
radstep
+

Set neighbor search radius step. Only used if option interpolate is enabled. +

+
+ + +

27.109.1 Examples

+ +
    +
  • Using ClubFritz6 sofa file: +
    +
    sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
    +
    + +
  • Using ClubFritz12 sofa file and bigger radius with small rotation: +
    +
    sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
    +
    + +
  • Similar as above but with custom speaker positions for front left, front right, back left and back right +and also with custom gain: +
    +
    "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
    +
    +
+ + +

27.110 speechnorm

+

Speech Normalizer. +

+

This filter expands or compresses each half-cycle of audio samples +(local set of samples all above or all below zero and between two nearest zero crossings) depending +on threshold value, so audio reaches target peak value under conditions controlled by below options. +

+

The filter accepts the following options: +

+
+
peak, p
+

Set the expansion target peak value. This specifies the highest allowed absolute amplitude +level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0. +

+
+
expansion, e
+

Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples expansion. The maximum expansion +would be such that local peak value reaches target peak value but never to surpass it and that +ratio between new and previous peak value does not surpass this option value. +

+
+
compression, c
+

Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples compression. This option is used +only if threshold option is set to value greater than 0.0, then in such cases +when local peak is lower or same as value set by threshold all samples belonging to +that peak’s half-cycle will be compressed by current compression factor. +

+
+
threshold, t
+

Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0. +This option specifies which half-cycles of samples will be compressed and which will be expanded. +Any half-cycle samples with their local peak value below or same as this option value will be +compressed by current compression factor, otherwise, if greater than threshold value they will be +expanded with expansion factor so that it could reach peak target value but never surpass it. +

+
+
raise, r
+

Set the expansion raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per +each new half-cycle until it reaches expansion value. +Setting this options too high may lead to distortions. +

+
+
fall, f
+

Set the compression raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per +each new half-cycle until it reaches compression value. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
invert, i
+

Enable inverted filtering, by default is disabled. This inverts interpretation of threshold +option. When enabled any half-cycle of samples with their local peak value below or same as +threshold option will be expanded otherwise it will be compressed. +

+
+
link, l
+

Link channels when calculating gain applied to each filtered channel sample, by default is disabled. +When disabled each filtered channel gain calculation is independent, otherwise when this option +is enabled the minimum of all possible gains for each filtered channel is used. +

+
+
rms, m
+

Set the expansion target RMS value. This specifies the highest allowed RMS level for the normalized +audio input. Default value is 0.0, thus disabled. Allowed range is from 0.0 to 1.0. +

+
+ + +

27.110.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.110.2 Examples

+ +
    +
  • Weak and slow amplification: +
    +
    speechnorm=e=3:r=0.00001:l=1
    +
    + +
  • Moderate and slow amplification: +
    +
    speechnorm=e=6.25:r=0.00001:l=1
    +
    + +
  • Strong and fast amplification: +
    +
    speechnorm=e=12.5:r=0.0001:l=1
    +
    + +
  • Very strong and fast amplification: +
    +
    speechnorm=e=25:r=0.0001:l=1
    +
    + +
  • Extreme and fast amplification: +
    +
    speechnorm=e=50:r=0.0001:l=1
    +
    +
+ + +

27.111 stereotools

+ +

This filter has some handy utilities to manage stereo signals, for converting +M/S stereo recordings to L/R signal while having control over the parameters +or spreading the stereo image of master track. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
level_out
+

Set output level after filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
balance_in
+

Set input balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
balance_out
+

Set output balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
softclip
+

Enable softclipping. Results in analog distortion instead of harsh digital 0dB +clipping. Disabled by default. +

+
+
mutel
+

Mute the left channel. Disabled by default. +

+
+
muter
+

Mute the right channel. Disabled by default. +

+
+
phasel
+

Change the phase of the left channel. Disabled by default. +

+
+
phaser
+

Change the phase of the right channel. Disabled by default. +

+
+
mode
+

Set stereo mode. Available values are: +

+
+
‘lr>lr’
+

Left/Right to Left/Right, this is default. +

+
+
‘lr>ms’
+

Left/Right to Mid/Side. +

+
+
‘ms>lr’
+

Mid/Side to Left/Right. +

+
+
‘lr>ll’
+

Left/Right to Left/Left. +

+
+
‘lr>rr’
+

Left/Right to Right/Right. +

+
+
‘lr>l+r’
+

Left/Right to Left + Right. +

+
+
‘lr>rl’
+

Left/Right to Right/Left. +

+
+
‘ms>ll’
+

Mid/Side to Left/Left. +

+
+
‘ms>rr’
+

Mid/Side to Right/Right. +

+
+
‘ms>rl’
+

Mid/Side to Right/Left. +

+
+
‘lr>l-r’
+

Left/Right to Left - Right. +

+
+ +
+
slev
+

Set level of side signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
sbal
+

Set balance of side signal. Default is 0. +Allowed range is from -1 to 1. +

+
+
mlev
+

Set level of the middle signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
mpan
+

Set middle signal pan. Default is 0. Allowed range is from -1 to 1. +

+
+
base
+

Set stereo base between mono and inversed channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
delay
+

Set delay in milliseconds how much to delay left from right channel and +vice versa. Default is 0. Allowed range is from -20 to 20. +

+
+
sclevel
+

Set S/C level. Default is 1. Allowed range is from 1 to 100. +

+
+
phase
+

Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. +

+
+
bmode_in, bmode_out
+

Set balance mode for balance_in/balance_out option. +

+

Can be one of the following: +

+
+
‘balance’
+

Classic balance mode. Attenuate one channel at time. +Gain is raised up to 1. +

+
+
‘amplitude’
+

Similar as classic mode above but gain is raised up to 2. +

+
+
‘power’
+

Equal power distribution, from -6dB to +6dB range. +

+
+
+
+ + +

27.111.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

27.111.2 Examples

+ +
    +
  • Apply karaoke like effect: +
    +
    stereotools=mlev=0.015625
    +
    + +
  • Convert M/S signal to L/R: +
    +
    "stereotools=mode=ms>lr"
    +
    +
+ + +

27.112 stereowiden

+ +

This filter enhance the stereo effect by suppressing signal common to both +channels and by delaying the signal of left into right and vice versa, +thereby widening the stereo effect. +

+

The filter accepts the following options: +

+
+
delay
+

Time in milliseconds of the delay of left signal into right and vice versa. +Default is 20 milliseconds. +

+
+
feedback
+

Amount of gain in delayed signal into right and vice versa. Gives a delay +effect of left signal in right output and vice versa which gives widening +effect. Default is 0.3. +

+
+
crossfeed
+

Cross feed of left into right with inverted phase. This helps in suppressing +the mono. If the value is 1 it will cancel all the signal common to both +channels. Default is 0.3. +

+
+
drymix
+

Set level of input signal of original channel. Default is 0.8. +

+
+ + +

27.112.1 Commands

+ +

This filter supports the all above options except delay as commands. +

+ +

27.113 superequalizer

+

Apply 18 band equalizer. +

+

The filter accepts the following options: +

+
1b
+

Set 65Hz band gain. +

+
2b
+

Set 92Hz band gain. +

+
3b
+

Set 131Hz band gain. +

+
4b
+

Set 185Hz band gain. +

+
5b
+

Set 262Hz band gain. +

+
6b
+

Set 370Hz band gain. +

+
7b
+

Set 523Hz band gain. +

+
8b
+

Set 740Hz band gain. +

+
9b
+

Set 1047Hz band gain. +

+
10b
+

Set 1480Hz band gain. +

+
11b
+

Set 2093Hz band gain. +

+
12b
+

Set 2960Hz band gain. +

+
13b
+

Set 4186Hz band gain. +

+
14b
+

Set 5920Hz band gain. +

+
15b
+

Set 8372Hz band gain. +

+
16b
+

Set 11840Hz band gain. +

+
17b
+

Set 16744Hz band gain. +

+
18b
+

Set 20000Hz band gain. +

+
+ + +

27.114 surround

+

Apply audio surround upmix filter. +

+

This filter allows to produce multichannel output from audio stream. +

+

The filter accepts the following options: +

+
+
chl_out
+

Set output channel layout. By default, this is 5.1. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
chl_in
+

Set input channel layout. By default, this is stereo. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
level_in
+

Set input volume level. By default, this is 1. +

+
+
level_out
+

Set output volume level. By default, this is 1. +

+
+
lfe
+

Enable LFE channel output if output channel layout has it. By default, this is enabled. +

+
+
lfe_low
+

Set LFE low cut off frequency. By default, this is 128 Hz. +

+
+
lfe_high
+

Set LFE high cut off frequency. By default, this is 256 Hz. +

+
+
lfe_mode
+

Set LFE mode, can be add or sub. Default is add. +In add mode, LFE channel is created from input audio and added to output. +In sub mode, LFE channel is created from input audio and added to output but +also all non-LFE output channels are subtracted with output LFE channel. +

+
+
smooth
+

Set temporal smoothness strength, used to gradually change factors when transforming +stereo sound in time. Allowed range is from 0.0 to 1.0. +Useful to improve output quality with focus option values greater than 0.0. +Default is 0.0. Only values inside this range and without edges are effective. +

+
+
angle
+

Set angle of stereo surround transform, Allowed range is from 0 to 360. +Default is 90. +

+
+
focus
+

Set focus of stereo surround transform, Allowed range is from -1 to 1. +Default is 0. +

+
+
fc_in
+

Set front center input volume. By default, this is 1. +

+
+
fc_out
+

Set front center output volume. By default, this is 1. +

+
+
fl_in
+

Set front left input volume. By default, this is 1. +

+
+
fl_out
+

Set front left output volume. By default, this is 1. +

+
+
fr_in
+

Set front right input volume. By default, this is 1. +

+
+
fr_out
+

Set front right output volume. By default, this is 1. +

+
+
sl_in
+

Set side left input volume. By default, this is 1. +

+
+
sl_out
+

Set side left output volume. By default, this is 1. +

+
+
sr_in
+

Set side right input volume. By default, this is 1. +

+
+
sr_out
+

Set side right output volume. By default, this is 1. +

+
+
bl_in
+

Set back left input volume. By default, this is 1. +

+
+
bl_out
+

Set back left output volume. By default, this is 1. +

+
+
br_in
+

Set back right input volume. By default, this is 1. +

+
+
br_out
+

Set back right output volume. By default, this is 1. +

+
+
bc_in
+

Set back center input volume. By default, this is 1. +

+
+
bc_out
+

Set back center output volume. By default, this is 1. +

+
+
lfe_in
+

Set LFE input volume. By default, this is 1. +

+
+
lfe_out
+

Set LFE output volume. By default, this is 1. +

+
+
allx
+

Set spread usage of stereo image across X axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
ally
+

Set spread usage of stereo image across Y axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
fcx, flx, frx, blx, brx, slx, srx, bcx
+

Set spread usage of stereo image across X axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
fcy, fly, fry, bly, bry, sly, sry, bcy
+

Set spread usage of stereo image across Y axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.5. +

+
+ + +

27.115 tiltshelf

+ +

Boost or cut the lower frequencies and cut or boost higher 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: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.115.1 Commands

+ +

This filter supports some options as commands. +

+ +

27.116 treble, highshelf

+ +

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). +

+

The filter accepts the following options: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

27.116.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change treble frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change treble width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change treble width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change treble gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change treble mix. +Syntax for the command is : "mix" +

+
+ + +

27.117 tremolo

+ +

Sinusoidal amplitude modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. Modulation frequencies in the subharmonic range +(20 Hz or lower) will result in a tremolo effect. +This filter may also be used as a ring modulator by specifying +a modulation frequency higher than 20 Hz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

27.118 vibrato

+ +

Sinusoidal phase modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

27.119 virtualbass

+ +

Apply audio Virtual Bass filter. +

+

This filter accepts stereo input and produce stereo with LFE (2.1) channels output. +The newly produced LFE channel have enhanced virtual bass originally obtained from both stereo channels. +This filter outputs front left and front right channels unchanged as available in stereo input. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set the virtual bass cutoff frequency. Default value is 250 Hz. +Allowed range is from 100 to 500 Hz. +

+
+
strength
+

Set the virtual bass strength. Allowed range is from 0.5 to 3. +Default value is 3. +

+
+ + +

27.120 volume

+ +

Adjust the input audio volume. +

+

It accepts the following parameters: +

+
volume
+

Set audio volume expression. +

+

Output values are clipped to the maximum value. +

+

The output audio volume is given by the relation: +

+
output_volume = volume * input_volume
+
+ +

The default value for volume is "1.0". +

+
+
precision
+

This parameter represents the mathematical precision. +

+

It determines which input sample formats will be allowed, which affects the +precision of the volume scaling. +

+
+
fixed
+

8-bit fixed-point; this limits input sample format to U8, S16, and S32. +

+
float
+

32-bit floating-point; this limits input sample format to FLT. (default) +

+
double
+

64-bit floating-point; this limits input sample format to DBL. +

+
+ +
+
replaygain
+

Choose the behaviour on encountering ReplayGain side data in input frames. +

+
+
drop
+

Remove ReplayGain side data, ignoring its contents (the default). +

+
+
ignore
+

Ignore ReplayGain side data, but leave it in the frame. +

+
+
track
+

Prefer the track gain, if present. +

+
+
album
+

Prefer the album gain, if present. +

+
+ +
+
replaygain_preamp
+

Pre-amplification gain in dB to apply to the selected replaygain gain. +

+

Default value for replaygain_preamp is 0.0. +

+
+
replaygain_noclip
+

Prevent clipping by limiting the gain applied. +

+

Default value for replaygain_noclip is 1. +

+
+
eval
+

Set when the volume expression is evaluated. +

+

It accepts the following values: +

+
‘once’
+

only evaluate expression once during the filter initialization, or +when the ‘volume’ command is sent +

+
+
‘frame’
+

evaluate expression for each incoming frame +

+
+ +

Default value is ‘once’. +

+
+ +

The volume expression can contain the following parameters. +

+
+
n
+

frame number (starting at zero) +

+
nb_channels
+

number of channels +

+
nb_consumed_samples
+

number of samples consumed by the filter +

+
nb_samples
+

number of samples in the current frame +

+
pos
+

original frame position in the file; deprecated, do not use +

+
pts
+

frame PTS +

+
sample_rate
+

sample rate +

+
startpts
+

PTS at start of stream +

+
startt
+

time at start of stream +

+
t
+

frame time +

+
tb
+

timestamp timebase +

+
volume
+

last set volume value +

+
+ +

Note that when eval is set to ‘once’ only the +sample_rate and tb variables are available, all other +variables will evaluate to NAN. +

+ +

27.120.1 Commands

+ +

This filter supports the following commands: +

+
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. +

+
+ + +

27.120.2 Examples

+ +
    +
  • Halve the input audio volume: +
    +
    volume=volume=0.5
    +volume=volume=1/2
    +volume=volume=-6.0206dB
    +
    + +

    In all the above example the named key for volume can be +omitted, for example like in: +

    +
    volume=0.5
    +
    + +
  • Increase input audio power by 6 decibels using fixed-point precision: +
    +
    volume=volume=6dB:precision=fixed
    +
    + +
  • Fade volume after time 10 with an annihilation period of 5 seconds: +
    +
    volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
    +
    +
+ + +

27.121 volumedetect

+ +

Detect the volume of the input video. +

+

The filter has no parameters. It supports only 16-bit signed integer samples, +so the input will be converted when needed. 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 a histogram of the +registered volume values (from the maximum value to a cumulated 1/1000 of +the samples). +

+

All volumes are in decibels relative to the maximum PCM value. +

+ +

27.121.1 Examples

+ +

Here is an excerpt of the output: +

+
[Parsed_volumedetect_0  0xa23120] mean_volume: -27 dB
+[Parsed_volumedetect_0  0xa23120] max_volume: -4 dB
+[Parsed_volumedetect_0  0xa23120] histogram_4db: 6
+[Parsed_volumedetect_0  0xa23120] histogram_5db: 62
+[Parsed_volumedetect_0  0xa23120] histogram_6db: 286
+[Parsed_volumedetect_0  0xa23120] histogram_7db: 1042
+[Parsed_volumedetect_0  0xa23120] histogram_8db: 2551
+[Parsed_volumedetect_0  0xa23120] histogram_9db: 4609
+[Parsed_volumedetect_0  0xa23120] histogram_10db: 8409
+
+ +

It means that: +

    +
  • The mean square energy is approximately -27 dB, or 10^-2.7. +
  • The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. +
  • There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. +
+ +

In other words, raising the volume by +4 dB does not cause any clipping, +raising it by +5 dB causes clipping for 6 samples, etc. +

+ +

27.122 whisper

+ +

It runs automatic speech recognition using the OpenAI’s Whisper model. +

+

It requires the whisper.cpp library (https://github.com/ggml-org/whisper.cpp) +as a prerequisite. After installing the library it can be enabled using: +./configure --enable-whisper. +

+

The filter has following options: +

+
+
model
+

The file path of the downloaded whisper.cpp model (mandatory). +

+
+
language
+

The language to use for transcription (’auto’ for auto-detect). +Default value: "auto" +

+
+
queue
+

The maximum size that will be queued into the filter before processing the audio +with whisper. Using a small value the audio stream will be processed more often, +but the transcription quality will be lower and the required processing power +will be higher. Using a large value (e.g. 10-20s) will produce more accurate +results using less CPU (as using the whisper-cli tool), but the transcription +latency will be higher, thus not useful to process real-time streams. +Consider using the vad_model option associated with a large queue value. +Default value: "3" +

+
+
use_gpu
+

If the GPU support should be enabled. +Default value: "true" +

+
+
gpu_device
+

The GPU device index to use. +Default value: "0" +

+
+
destination
+

If set, the transcription output will be sent to the specified file or URL +(use one of the FFmpeg AVIO protocols); otherwise, the output will be logged as +info messages. +The output will also be set in the "lavfi.whisper.text" frame metadata. +If the destination is a file and it already exists, it will be overwritten. +

+
+
format
+

The destination format string; it could be "text" (only the transcribed text +will be sent to the destination), "srt" (subtitle format) or "json". +Default value: "text" +

+
+
max_len
+

Maximum segment length in characters. When set to a value greater than 0, +transcription segments will be split to not exceed this length. This is useful +for generating subtitles with shorter lines. +Default value: "0" +

+
+
vad_model
+

Path to the VAD model file. If set, the filter will load an additional voice +activity detection module (https://github.com/snakers4/silero-vad) that will be +used to fragment the audio queue; use this option setting a valid path obtained +from the whisper.cpp repository (e.g. "../whisper.cpp/models/ggml-silero-v5.1.2.bin") +and increase the queue parameter to a higher value (e.g. 20). +

+
+
vad_threshold
+

The VAD threshold to use. +Default value: "0.5" +

+
+
vad_min_speech_duration
+

The minimum VAD speaking duration. +Default value: "0.1" +

+
+
vad_min_silence_duration
+

The minimum VAD silence duration. +Default value: "0.5" +

+
+
+ + +

27.122.1 Examples

+
    +
  • Run a transcription with srt file generation: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=output.srt\
    +:format=srt" -f null -
    +
    + +
  • Run a transcription and send the output in JSON format to an HTTP service: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=http\\://localhost\\:3000\
    +:format=json' -f null -
    +
    + +
  • Transcribe the microphone input using the VAD option: +
    +
    ffmpeg -loglevel warning -f pulse -i default \
    +-af 'highpass=f=200,lowpass=f=3000,whisper=model=../whisper.cpp/models/ggml-medium.bin\
    +:language=en\
    +:queue=10\
    +:destination=-\
    +:format=json\
    +:vad_model=../whisper.cpp/models/ggml-silero-v5.1.2.bin' -f null -
    +
    + +
+ + + +

28 Audio Sources

+ +

Below is a description of the currently available audio sources. +

+ +

28.1 abuffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
time_base
+

The timebase which will be used for timestamps of submitted frames. It must be +either a floating-point number or in numerator/denominator form. +

+
+
sample_rate
+

The sample rate of the incoming audio buffers. +

+
+
sample_fmt
+

The sample format of the incoming audio buffers. +Either a sample format name or its corresponding integer representation from +the enum AVSampleFormat in libavutil/samplefmt.h +

+
+
channel_layout
+

The channel layout of the incoming audio buffers. +Either a channel layout name from channel_layout_map in +libavutil/channel_layout.c or its corresponding integer representation +from the AV_CH_LAYOUT_* macros in libavutil/channel_layout.h +

+
+
channels
+

The number of channels of the incoming audio buffers. +If both channels and channel_layout are specified, then they +must be consistent. +

+
+
+ + +

28.1.1 Examples

+ +
+
abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
+
+ +

will instruct the source to accept planar 16bit signed stereo at 44100Hz. +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: +

+
abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
+
+ + +

28.2 aevalsrc

+ +

Generate an audio signal specified by an expression. +

+

This source accepts in input one or more expressions (one for each +channel), which are evaluated and used to generate a corresponding +audio signal. +

+

This source accepts the following options: +

+
+
exprs
+

Set the ’|’-separated expressions list for each separate channel. In case the +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. +

+
+
channel_layout, c
+

Set the channel layout. The number of channels in the specified layout +must be equal to the number of specified expressions. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, +default to 1024. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. +

+
+ +

Each expression in exprs can contain the following constants: +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
t
+

time of the evaluated sample expressed in seconds, starting from 0 +

+
+
s
+

sample rate +

+
+
+ + +

28.2.1 Examples

+ +
    +
  • Generate silence: +
    +
    aevalsrc=0
    +
    + +
  • Generate a sin signal with frequency of 440 Hz, set sample rate to +8000 Hz: +
    +
    aevalsrc="sin(440*2*PI*t):s=8000"
    +
    + +
  • Generate a two channels signal, specify the channel layout (Front +Center + Back Center) explicitly: +
    +
    aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
    +
    + +
  • Generate white noise: +
    +
    aevalsrc="-2+random(0)"
    +
    + +
  • Generate an amplitude modulated signal: +
    +
    aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
    +
    + +
  • Generate 2.5 Hz binaural beats on a 360 Hz carrier: +
    +
    aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
    +
    + +
+ + +

28.3 afdelaysrc

+ +

Generate a fractional delay FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
delay, d
+

Set the fractional delay. Default is 0. +

+
+
sample_rate, r
+

Set the sample rate, default is 44100. +

+
+
nb_samples, n
+

Set the number of samples per each frame. Default is 1024. +

+
+
taps, t
+

Set the number of filter coefficients in output audio stream. +Default value is 0. +

+
+
channel_layout, c
+

Specifies the channel layout, and can be a string representing a channel layout. +The default value of channel_layout is "stereo". +

+
+ + +

28.4 afireqsrc

+ +

Generate a FIR equalizer coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
preset, p
+

Set equalizer preset. +Default preset is flat. +

+

Available presets are: +

+
‘custom’
+
‘flat’
+
‘acoustic’
+
‘bass’
+
‘beats’
+
‘classic’
+
‘clear’
+
‘deep bass’
+
‘dubstep’
+
‘electronic’
+
‘hard-style’
+
‘hip-hop’
+
‘jazz’
+
‘metal’
+
‘movie’
+
‘pop’
+
‘r&b’
+
‘rock’
+
‘vocal booster’
+
+ +
+
gains, g
+

Set custom gains for each band. Only used if the preset option is set to custom. +Gains are separated by white spaces and each gain is set in dBFS. +Default is 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0. +

+
+
bands, b
+

Set the custom bands from where custom equalizer gains are set. +This must be in strictly increasing order. Only used if the preset option is set to custom. +Bands are separated by white spaces and each band represent frequency in Hz. +Default is 25 40 63 100 160 250 400 630 1000 1600 2500 4000 6300 10000 16000 24000. +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 4096. +

+
+
sample_rate, r
+

Set sample rate of output audio stream, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame in output audio stream. Default is 1024. +

+
+
interp, i
+

Set interpolation method for FIR equalizer coefficients. Can be linear or cubic. +

+
+
phase, h
+

Set phase type of FIR filter. Can be linear or min: minimum-phase. +Default is minimum-phase filter. +

+
+ + +

28.5 afirsrc

+ +

Generate a FIR coefficients using frequency sampling method. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 1025. +

+
+
frequency, f
+

Set frequency points from where magnitude and phase are set. +This must be in non decreasing order, and first element must be 0, while last element +must be 1. Elements are separated by white spaces. +

+
+
magnitude, m
+

Set magnitude value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
phase, p
+

Set phase value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
win_func, w
+

Set window function. Default is blackman. +

+
+ + +

28.6 anullsrc

+ +

The null audio source, return unprocessed audio frames. It is mainly useful +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). +

+

This source accepts the following options: +

+
+
channel_layout, cl
+
+

Specifies the channel layout, and can be either an integer or a string +representing a channel layout. The default value of channel_layout +is "stereo". +

+

Check the channel_layout_map definition in +libavutil/channel_layout.c for the mapping between strings and +channel layout values. +

+
+
sample_rate, r
+

Specifies the sample rate, and defaults to 44100. +

+
+
nb_samples, n
+

Set the number of samples per requested frames. +

+
+
duration, d
+

Set the duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. +

+
+ + +

28.6.1 Examples

+ +
    +
  • Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. +
    +
    anullsrc=r=48000:cl=4
    +
    + +
  • Do the same operation with a more obvious syntax: +
    +
    anullsrc=r=48000:cl=mono
    +
    +
+ +

All the parameters need to be explicitly defined. +

+ +

28.7 flite

+ +

Synthesize a voice utterance using the libflite library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libflite. +

+

Note that versions of the flite library prior to 2.0 are not thread-safe. +

+

The filter accepts the following options: +

+
+
list_voices
+

If set to 1, list the names of the available voices and exit +immediately. Default value is 0. +

+
+
nb_samples, n
+

Set the maximum number of samples per frame. Default value is 512. +

+
+
textfile
+

Set the filename containing the text to speak. +

+
+
text
+

Set the text to speak. +

+
+
voice, v
+

Set the voice to use for the speech synthesis. Default value is +kal. See also the list_voices option. +

+
+ + +

28.7.1 Examples

+ +
    +
  • Read from file speech.txt, and synthesize the text using the +standard flite voice: +
    +
    flite=textfile=speech.txt
    +
    + +
  • Read the specified text selecting the slt voice: +
    +
    flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Input text to ffmpeg: +
    +
    ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Make ffplay speak the specified text, using flite and +the lavfi device: +
    +
    ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
    +
    +
+ +

For more information about libflite, check: +http://www.festvox.org/flite/ +

+ +

28.8 anoisesrc

+ +

Generate a noise audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Specify the sample rate. Default value is 48000 Hz. +

+
+
amplitude, a
+

Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value +is 1.0. +

+
+
duration, d
+

Specify the duration of the generated audio stream. Not specifying this option +results in noise with an infinite length. +

+
+
color, colour, c
+

Specify the color of noise. Available noise colors are white, pink, brown, +blue, violet and velvet. Default color is white. +

+
+
seed, s
+

Specify a value used to seed the PRNG. +

+
+
nb_samples, n
+

Set the number of samples per each output frame, default is 1024. +

+
+
density
+

Set the density (0.0 - 1.0) for the velvet noise generator, default is 0.05. +

+
+ + +

28.8.1 Examples

+ +
    +
  • Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: +
    +
    anoisesrc=d=60:c=pink:r=44100:a=0.5
    +
    +
+ + +

28.9 hilbert

+ +

Generate odd-tap Hilbert transform FIR coefficients. +

+

The resulting stream can be used with afir filter for phase-shifting +the signal by 90 degrees. +

+

This is used in many matrix coding schemes and for analytic signal generation. +The process is often written as a multiplication by i (or j), the imaginary unit. +

+

The filter accepts the following options: +

+
+
sample_rate, s
+

Set sample rate, default is 44100. +

+
+
taps, t
+

Set length of FIR filter, default is 22051. +

+
+
nb_samples, n
+

Set number of samples per each frame. +

+
+
win_func, w
+

Set window function to be used when generating FIR coefficients. +

+
+ + +

28.10 sinc

+ +

Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
hp
+

Set high-pass frequency. Default is 0. +

+
+
lp
+

Set low-pass frequency. Default is 0. +If high-pass frequency is lower than low-pass frequency and low-pass frequency +is higher than 0 then filter will create band-pass filter coefficients, +otherwise band-reject filter coefficients. +

+
+
phase
+

Set filter phase response. Default is 50. Allowed range is from 0 to 100. +

+
+
beta
+

Set Kaiser window beta. +

+
+
att
+

Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. +

+
+
round
+

Enable rounding, by default is disabled. +

+
+
hptaps
+

Set number of taps for high-pass filter. +

+
+
lptaps
+

Set number of taps for low-pass filter. +

+
+ + +

28.11 sine

+ +

Generate an audio signal made of a sine wave with amplitude 1/8. +

+

The audio signal is bit-exact. +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the carrier frequency. Default is 440 Hz. +

+
+
beep_factor, b
+

Enable a periodic beep every second with frequency beep_factor times +the carrier frequency. Default is 0, meaning the beep is disabled. +

+
+
sample_rate, r
+

Specify the sample rate, default is 44100. +

+
+
duration, d
+

Specify the duration of the generated audio stream. +

+
+
samples_per_frame
+

Set the number of samples per output frame. +

+

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the output audio frame, starting from 0. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the output audio frame, +expressed in TB units. +

+
+
t
+

The PTS of the output audio frame, expressed in seconds. +

+
+
TB
+

The timebase of the output audio frames. +

+
+ +

Default is 1024. +

+
+ + +

28.11.1 Examples

+ +
    +
  • Generate a simple 440 Hz sine wave: +
    +
    sine
    +
    + +
  • Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: +
    +
    sine=220:4:d=5
    +sine=f=220:b=4:d=5
    +sine=frequency=220:beep_factor=4:duration=5
    +
    + +
  • Generate a 1 kHz sine wave following 1602,1601,1602,1601,1602 NTSC +pattern: +
    +
    sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
    +
    +
+ + + +

29 Audio Sinks

+ +

Below is a description of the currently available audio sinks. +

+ +

29.1 abuffersink

+ +

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 libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVABufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+

29.2 anullsink

+ +

Null audio sink; do absolutely nothing with the input audio. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

30 Video Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the video filters included in your +build. +

+

Below is a description of the currently available video filters. +

+ +

30.1 addroi

+ +

Mark a region of interest in a video frame. +

+

The frame data is passed through unchanged, but metadata is attached +to the frame indicating regions of interest which can affect the +behaviour of later encoding. Multiple regions can be marked by +applying the filter multiple times. +

+
+
x
+

Region distance in pixels from the left edge of the frame. +

+
y
+

Region distance in pixels from the top edge of the frame. +

+
w
+

Region width in pixels. +

+
h
+

Region height in pixels. +

+

The parameters x, y, w and h are expressions, +and may contain the following variables: +

+
iw
+

Width of the input frame. +

+
ih
+

Height of the input frame. +

+
+ +
+
qoffset
+

Quantisation offset to apply within the region. +

+

This must be a real value in the range -1 to +1. A value of zero +indicates no quality change. A negative value asks for better quality +(less quantisation), while a positive value asks for worse quality +(greater quantisation). +

+

The range is calibrated so that the extreme values indicate the +largest possible offset - if the rest of the frame is encoded with the +worst possible quality, an offset of -1 indicates that this region +should be encoded with the best possible quality anyway. Intermediate +values are then interpolated in some codec-dependent way. +

+

For example, in 10-bit H.264 the quantisation parameter varies between +-12 and 51. A typical qoffset value of -1/10 therefore indicates that +this region should be encoded with a QP around one-tenth of the full +range better than the rest of the frame. So, if most of the frame +were to be encoded with a QP of around 30, this region would get a QP +of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). +An extreme value of -1 would indicate that this region should be +encoded with the best possible quality regardless of the treatment of +the rest of the frame - that is, should be encoded at a QP of -12. +

+
clear
+

If set to true, remove any existing regions of interest marked on the +frame before adding the new one. +

+
+ + +

30.1.1 Examples

+ +
    +
  • Mark the centre quarter of the frame as interesting. +
    +
    addroi=iw/4:ih/4:iw/2:ih/2:-1/10
    +
    +
  • Mark the 100-pixel-wide region on the left edge of the frame as very +uninteresting (to be encoded at much lower quality than the rest of +the frame). +
    +
    addroi=0:0:100:ih:+1/5
    +
    +
+ + +

30.2 alphaextract

+ +

Extract the alpha component from the input as a grayscale video. This +is especially useful with the alphamerge filter. +

+ +

30.3 alphamerge

+ +

Add or replace the alpha component of the primary input with the +grayscale value of a second input. This is intended for use with +alphaextract to allow the transmission or storage of frame +sequences that have alpha in a format that doesn’t support an alpha +channel. +

+

For example, to reconstruct full frames from a normal YUV-encoded video +and a separate video created with alphaextract, you might use: +

+
movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
+
+ + +

30.4 amplify

+ +

Amplify differences between current pixel and pixels of adjacent frames in +same pixel location. +

+

This filter accepts the following options: +

+
+
radius
+

Set frame radius. Default is 2. Allowed range is from 1 to 63. +For example radius of 3 will instruct filter to calculate average of 7 frames. +

+
+
factor
+

Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. +

+
+
threshold
+

Set threshold for difference amplification. Any difference greater or equal to +this value will not alter source pixel. Default is 10. +Allowed range is from 0 to 65535. +

+
+
tolerance
+

Set tolerance for difference amplification. Any difference lower to +this value will not alter source pixel. Default is 0. +Allowed range is from 0 to 65535. +

+
+
low
+

Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will decrease source pixel value. +

+
+
high
+

Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will increase source pixel value. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

30.4.1 Commands

+ +

This filter supports the following commands that corresponds to option of same name: +

+
factor
+
threshold
+
tolerance
+
low
+
high
+
planes
+
+ + +

30.5 ass

+ +

Same as the subtitles filter, except that it doesn’t require libavcodec +and libavformat to work. On the other hand, it is limited to ASS (Advanced +Substation Alpha) subtitles files. +

+

This filter accepts the following option in addition to the common options from +the subtitles filter: +

+
+
shaping
+

Set the shaping engine +

+

Available values are: +

+
‘auto’
+

The default libass shaping engine, which is the best available. +

+
‘simple’
+

Fast, font-agnostic shaper that can do only substitutions +

+
‘complex’
+

Slower shaper using OpenType for substitutions and positioning +

+
+ +

The default is auto. +

+
+ + +

30.6 atadenoise

+

Apply an Adaptive Temporal Averaging Denoiser to the video input. +

+

The filter accepts the following options: +

+
+
0a
+

Set threshold A for 1st plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
0b
+

Set threshold B for 1st plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
1a
+

Set threshold A for 2nd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
1b
+

Set threshold B for 2nd plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
2a
+

Set threshold A for 3rd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
2b
+

Set threshold B for 3rd plane. Default is 0.04. +Valid range is 0 to 5. +

+

Threshold A is designed to react on abrupt changes in the input signal and +threshold B is designed to react on continuous changes in the input signal. +

+
+
s
+

Set number of frames filter will use for averaging. Default is 9. Must be odd +number in range [5, 129]. +

+
+
p
+

Set what planes of frame filter will use for averaging. Default is all. +

+
+
a
+

Set what variant of algorithm filter will use for averaging. Default is p parallel. +Alternatively can be set to s serial. +

+

Parallel can be faster then serial, while other way around is never true. +Parallel will abort early on first change being greater then thresholds, while serial +will continue processing other side of frames if they are equal or below thresholds. +

+
+
0s
+
1s
+
2s
+

Set sigma for 1st plane, 2nd plane or 3rd plane. Default is 32767. +Valid range is from 0 to 32767. +This options controls weight for each pixel in radius defined by size. +Default value means every pixel have same weight. +Setting this option to 0 effectively disables filtering. +

+
+ + +

30.6.1 Commands

+

This filter supports same commands as options except option s. +The command accepts the same syntax of the corresponding option. +

+ +

30.7 avgblur

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sizeY
+

Set vertical radius size, if zero it will be same as sizeX. +Default is 0. +

+
+ + +

30.7.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.8 backgroundkey

+ +

Turns a static background into transparency. +

+

The filter accepts the following option: +

+
+
threshold
+

Threshold for scene change detection. +

+
similarity
+

Similarity percentage with the background. +

+
blend
+

Set the blend amount for pixels that are not similar. +

+
+ + +

30.8.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.9 bbox

+ +

Compute the bounding box for the non-black pixels in the input frame +luma plane. +

+

This filter computes the bounding box containing all the pixels with a +luma 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: +

+
+
min_val
+

Set the minimal luma value. Default is 16. +

+
+ + +

30.9.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.10 bilateral

+

Apply bilateral filter, spatial smoothing while preserving edges. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight. +Allowed range is 0 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate range weight. +Allowed range is 0 to 1. Default is 0.1. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

30.10.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.11 bitplanenoise

+ +

Show and measure bit plane noise. +

+

The filter accepts the following options: +

+
+
bitplane
+

Set which plane to analyze. Default is 1. +

+
+
filter
+

Filter out noisy pixels from bitplane set above. +Default is disabled. +

+
+ + +

30.12 blackdetect, blackdetect_vulkan

+ +

Detect video intervals that are (almost) completely black. Can be +useful to detect chapter transitions, commercials, or invalid +recordings. +

+

The filter outputs its detection analysis to both the log as well as +frame metadata. If a black segment of at least the specified minimum +duration is found, a line with the start and end timestamps as well +as duration is printed to the log with level info. In addition, +a log line with level debug is printed per frame showing the +black amount detected for that frame. +

+

The filter also attaches metadata to the first frame of a black +segment with key lavfi.black_start and to the first frame +after the black segment ends with key lavfi.black_end. The +value is the frame’s timestamp. This metadata is added regardless +of the minimum duration specified. +

+

The filter accepts the following options: +

+
+
black_min_duration, d
+

Set the minimum detected black duration expressed in seconds. It must +be a non-negative floating point number. +

+

Default value is 2.0. +

+
+
picture_black_ratio_th, pic_th
+

Set the threshold for considering a picture "black". +Express the minimum value for the ratio: +

+
nb_black_pixels / nb_pixels
+
+ +

for which a picture is considered black. +Default value is 0.98. +

+
+
pixel_black_th, pix_th
+

Set the threshold for considering a pixel "black". +

+

The threshold expresses the maximum pixel luma value for which a +pixel is considered "black". The provided value is scaled according to +the following equation: +

+
absolute_threshold = luma_minimum_value + pixel_black_th * luma_range_size
+
+ +

luma_range_size and luma_minimum_value depend on +the input video format, the range is [0-255] for YUV full-range +formats and [16-235] for YUV non full-range formats. +

+

Default value is 0.10. +

+
+
alpha
+

If true, check the alpha channel instead of the luma channel. Detects frames +which are (almost) transparent, instead of frames which are almost black. +

+

Default value is disabled. +

+
+ +

The following example sets the maximum pixel threshold to the minimum +value, and detects only black intervals of 2 or more seconds: +

+
blackdetect=d=2:pix_th=0.00
+
+ + +

30.13 blackframe

+ +

Detect frames that are (almost) completely black. Can be useful to +detect chapter transitions or commercials. Output lines consist of +the frame number of the detected frame, the percentage of blackness, +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. +

+

This filter exports frame metadata lavfi.blackframe.pblack. +The value represents the percentage of pixels in the picture that +are below the threshold value. +

+

It accepts the following parameters: +

+
+
amount
+

The percentage of the pixels that have to be below the threshold; it defaults to +98. +

+
+
threshold, thresh
+

The threshold below which a pixel value is considered black; it defaults to +32. +

+
+
+ + +

30.14 blend

+ +

Blend two video frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

The tblend (time blend) filter takes two consecutive frames +from one single stream, and outputs the result obtained by blending +the new frame on top of the old frame. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘addition’
+
‘and’
+
‘average’
+
‘bleach’
+
‘burn’
+
‘darken’
+
‘difference’
+
‘divide’
+
‘dodge’
+
‘exclusion’
+
‘extremity’
+
‘freeze’
+
‘geometric’
+
‘glow’
+
‘grainextract’
+
‘grainmerge’
+
‘hardlight’
+
‘hardmix’
+
‘hardoverlay’
+
‘harmonic’
+
‘heat’
+
‘interpolate’
+
‘lighten’
+
‘linearlight’
+
‘multiply’
+
‘multiply128’
+
‘negation’
+
‘normal’
+
‘or’
+
‘overlay’
+
‘phoenix’
+
‘pinlight’
+
‘reflect’
+
‘screen’
+
‘softdifference’
+
‘softlight’
+
‘stain’
+
‘subtract’
+
‘vividlight’
+
‘xor’
+
+ +
+
c0_opacity
+
c1_opacity
+
c2_opacity
+
c3_opacity
+
all_opacity
+

Set blend opacity for specific pixel component or all pixel components in case +of all_opacity. Only used in combination with pixel component blend modes. +

+
+
c0_expr
+
c1_expr
+
c2_expr
+
c3_expr
+
all_expr
+

Set blend expression for specific pixel component or all pixel components in case +of all_expr. Note that related mode options will be ignored if those are set. +

+

The expressions can use the following variables: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

the coordinates of the current sample +

+
+
W
+
H
+

the width and height of currently filtered plane +

+
+
SW
+
SH
+

Width and height scale for the plane being filtered. It is the +ratio between the dimensions of the current plane to the luma plane, +e.g. for a yuv420p frame, the values are 1,1 for +the luma plane and 0.5,0.5 for the chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
TOP, A
+

Value of pixel component at current location for first video frame (top layer). +

+
+
BOTTOM, B
+

Value of pixel component at current location for second video frame (bottom layer). +

+
+
+
+ +

The blend filter also supports the framesync options. +

+ +

30.14.1 Examples

+ +
    +
  • Apply transition from bottom layer to top layer in first 10 seconds: +
    +
    blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
    +
    + +
  • Apply linear horizontal transition from top layer to bottom layer: +
    +
    blend=all_expr='A*(X/W)+B*(1-X/W)'
    +
    + +
  • Apply 1x1 checkerboard effect: +
    +
    blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
    +
    + +
  • Apply uncover left effect: +
    +
    blend=all_expr='if(gte(N*SW+X,W),A,B)'
    +
    + +
  • Apply uncover down effect: +
    +
    blend=all_expr='if(gte(Y-N*SH,0),A,B)'
    +
    + +
  • Apply uncover up-left effect: +
    +
    blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
    +
    + +
  • Split diagonally video and shows top and bottom layer on each side: +
    +
    blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
    +
    + +
  • Display differences between the current and the previous frame: +
    +
    tblend=all_mode=grainextract
    +
    +
+ + +

30.14.2 Commands

+

This filter supports same commands as options. +

+ +

30.15 blockdetect

+ +

Determines blockiness of frames without altering the input frames. +

+

Based on Remco Muijs and Ihor Kirenko: "A no-reference blocking artifact measure for adaptive video processing." 2005 13th European signal processing conference. +

+

The filter accepts the following options: +

+
+
period_min
+
period_max
+

Set minimum and maximum values for determining pixel grids (periods). +Default values are [3,24]. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

30.15.1 Examples

+ +
    +
  • Determine blockiness for the first plane and search for periods within [8,32]: +
    +
    blockdetect=period_min=8:period_max=32:planes=1
    +
    +
+ + +

30.16 blurdetect

+ +

Determines blurriness of frames without altering the input frames. +

+

Based on Marziliano, Pina, et al. "A no-reference perceptual blur metric." +Allows for a block-based abbreviation. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
radius
+

Define the radius to search around an edge pixel for local maxima. +

+
+
block_pct
+

Determine blurriness only for the most significant blocks, given in percentage. +

+
+
block_width
+

Determine blurriness for blocks of width block_width. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_height. +

+
+
block_height
+

Determine blurriness for blocks of height block_height. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_width. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

30.16.1 Examples

+ +
    +
  • Determine blur for 80% of most significant 32x32 blocks: +
    +
    blurdetect=block_width=32:block_height=32:block_pct=80
    +
    +
+ + +

30.17 bm3d

+ +

Denoise frames using Block-Matching 3D algorithm. +

+

The filter accepts the following options. +

+
+
sigma
+

Set denoising strength. Default value is 1. +Allowed range is from 0 to 999.9. +The denoising algorithm is very sensitive to sigma, so adjust it +according to the source. +

+
+
block
+

Set local patch size. This sets dimensions in 2D. +

+
+
bstep
+

Set sliding step for processing blocks. Default value is 4. +Allowed range is from 1 to 64. +Smaller values allows processing more reference blocks and is slower. +

+
+
group
+

Set maximal number of similar blocks for 3rd dimension. Default value is 1. +When set to 1, no block matching is done. Larger values allows more blocks +in single group. +Allowed range is from 1 to 256. +

+
+
range
+

Set radius for search block matching. Default is 9. +Allowed range is from 1 to INT32_MAX. +

+
+
mstep
+

Set step between two search locations for block matching. Default is 1. +Allowed range is from 1 to 64. Smaller is slower. +

+
+
thmse
+

Set threshold of mean square error for block matching. Valid range is 0 to +INT32_MAX. +

+
+
hdthr
+

Set thresholding parameter for hard thresholding in 3D transformed domain. +Larger values results in stronger hard-thresholding filtering in frequency +domain. +

+
+
estim
+

Set filtering estimation mode. Can be basic or final. +Default is basic. +

+
+
ref
+

If enabled, filter will use 2nd stream for block matching. +Default is disabled for basic value of estim option, +and always enabled if value of estim is final. +

+
+
planes
+

Set planes to filter. Default is all available except alpha. +

+
+ + +

30.17.1 Examples

+ +
    +
  • Basic filtering with bm3d: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
    +
    + +
  • Same as above, but filtering only luma: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
    +
    + +
  • Same as above, but with both estimation modes: +
    +
    split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    + +
  • Same as above, but prefilter with nlmeans filter instead: +
    +
    split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    +
+ + +

30.18 boxblur

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

30.18.1 Examples

+ +
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radii +set to 2: +
    +
    boxblur=luma_radius=2:luma_power=1
    +boxblur=2:1
    +
    + +
  • Set the luma radius to 2, and alpha and chroma radius to 0: +
    +
    boxblur=2:1:cr=0:ar=0
    +
    + +
  • Set the luma and chroma radii to a fraction of the video dimension: +
    +
    boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
    +
    +
+ + +

30.19 bwdif

+ +

Deinterlace the input video ("bwdif" stands for "Bob Weaver +Deinterlacing Filter"). +

+

Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic +interpolation algorithms. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

30.20 ccrepack

+ +

Repack CEA-708 closed captioning side data +

+

This filter fixes various issues seen with commercial encoders +related to upstream malformed CEA-708 payloads, specifically +incorrect number of tuples (wrong cc_count for the target FPS), +and incorrect ordering of tuples (i.e. the CEA-608 tuples are not at +the first entries in the payload). +

+ +

30.21 cas

+ +

Apply Contrast Adaptive Sharpen filter to video stream. +

+

The filter accepts the following options: +

+
+
strength
+

Set the sharpening strength. Default value is 0. +

+
+
planes
+

Set planes to filter. Default value is to filter all +planes except alpha plane. +

+
+ + +

30.21.1 Commands

+

This filter supports same commands as options. +

+ +

30.22 chromahold

+

Remove all color information for all colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral chroma. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +0.0 makes pixels either fully gray, or not gray at all. +Higher values result in more preserved color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

30.22.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.23 chromakey

+

YUV colorspace color/chroma keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

30.23.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.23.2 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf chromakey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static black background. +
    +
    ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
    +
    +
+ + +

30.24 chromanr

+

Reduce chrominance noise. +

+

The filter accepts the following options: +

+
+
thres
+

Set threshold for averaging chrominance values. +Sum of absolute difference of Y, U and V pixel components of current +pixel and neighbour pixels lower than this threshold will be used in +averaging. Luma component is left unchanged and is copied to output. +Default value is 30. Allowed range is from 1 to 200. +

+
+
sizew
+

Set horizontal radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
sizeh
+

Set vertical radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
stepw
+

Set horizontal step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
steph
+

Set vertical step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
threy
+

Set Y threshold for averaging chrominance values. +Set finer control for max allowed difference between Y components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threu
+

Set U threshold for averaging chrominance values. +Set finer control for max allowed difference between U components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threv
+

Set V threshold for averaging chrominance values. +Set finer control for max allowed difference between V components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
distance
+

Set distance type used in calculations. +

+
+
‘manhattan’
+

Absolute difference. +

+
‘euclidean’
+

Difference squared. +

+
+ +

Default distance type is manhattan. +

+
+ + +

30.24.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+ +

30.25 chromashift

+

Shift chroma pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
cbh
+

Set amount to shift chroma-blue horizontally. +

+
cbv
+

Set amount to shift chroma-blue vertically. +

+
crh
+

Set amount to shift chroma-red horizontally. +

+
crv
+

Set amount to shift chroma-red vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

30.25.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.26 ciescope

+ +

Display CIE color diagram with pixels overlaid onto it. +

+

The filter accepts the following options: +

+
+
system
+

Set color system. +

+
+
‘ntsc, 470m’
+
‘ebu, 470bg’
+
‘smpte’
+
‘240m’
+
‘apple’
+
‘widergb’
+
‘cie1931’
+
‘rec709, hdtv’
+
‘uhdtv, rec2020’
+
‘dcip3’
+
+ +
+
cie
+

Set CIE system. +

+
+
‘xyy’
+
‘ucs’
+
‘luv’
+
+ +
+
gamuts
+

Set what gamuts to draw. +

+

See system option for available values. +

+
+
size, s
+

Set ciescope size, by default set to 512. +

+
+
intensity, i
+

Set intensity used to map input pixel values to CIE diagram. +

+
+
contrast
+

Set contrast used to draw tongue colors that are out of active color system gamut. +

+
+
corrgamma
+

Correct gamma displayed on scope, by default enabled. +

+
+
showwhite
+

Show white point on CIE diagram, by default disabled. +

+
+
gamma
+

Set input gamma. Used only with XYZ input color space. +

+
+
fill
+

Fill with CIE colors. By default is enabled. +

+
+ + +

30.27 codecview

+ +

Visualize information exported by some codecs. +

+

Some codecs can export information through frames using side-data or other +means. For example, some MPEG based codecs export motion vectors through the +export_mvs flag in the codec flags2 option. +

+

The filter accepts the following option: +

+
+
block
+

Display block partition structure using the luma plane. +

+
+
mv
+

Set motion vectors to visualize. +

+

Available flags for mv are: +

+
+
‘pf’
+

forward predicted MVs of P-frames +

+
‘bf’
+

forward predicted MVs of B-frames +

+
‘bb’
+

backward predicted MVs of B-frames +

+
+ +
+
qp
+

Display quantization parameters using the chroma planes. +

+
+
mv_type, mvt
+

Set motion vectors type to visualize. Includes MVs from all frames unless specified by frame_type option. +

+

Available flags for mv_type are: +

+
+
‘fp’
+

forward predicted MVs +

+
‘bp’
+

backward predicted MVs +

+
+ +
+
frame_type, ft
+

Set frame type to visualize motion vectors of. +

+

Available flags for frame_type are: +

+
+
‘if’
+

intra-coded frames (I-frames) +

+
‘pf’
+

predicted frames (P-frames) +

+
‘bf’
+

bi-directionally predicted frames (B-frames) +

+
+
+
+ + +

30.27.1 Examples

+ +
    +
  • Visualize forward predicted MVs of all frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
    +
    + +
  • Visualize multi-directionals MVs of P and B-Frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
    +
    +
+ + +

30.28 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: +

+
+
rs
+
gs
+
bs
+

Adjust red, green and blue shadows (darkest pixels). +

+
+
rm
+
gm
+
bm
+

Adjust red, green and blue midtones (medium pixels). +

+
+
rh
+
gh
+
bh
+

Adjust red, green and blue highlights (brightest pixels). +

+

Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
pl
+

Preserve lightness when changing color balance. Default is disabled. +

+
+ + +

30.28.1 Examples

+ +
    +
  • Add red color cast to shadows: +
    +
    colorbalance=rs=.3
    +
    +
+ + +

30.28.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.29 colorcontrast

+ +

Adjust color contrast between RGB components. +

+

The filter accepts the following options: +

+
+
rc
+

Set the red-cyan contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
gm
+

Set the green-magenta contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
by
+

Set the blue-yellow contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
rcw
+
gmw
+
byw
+

Set the weight of each rc, gm, by option value. Default value is 0.0. +Allowed range is from 0.0 to 1.0. If all weights are 0.0 filtering is disabled. +

+
+
pl
+

Set the amount of preserving lightness. Default value is 0.0. Allowed range is from 0.0 to 1.0. +

+
+ + +

30.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.30 colorcorrect

+ +

Adjust color white balance selectively for blacks and whites. +This filter operates in YUV colorspace. +

+

The filter accepts the following options: +

+
+
rl
+

Set the red shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bl
+

Set the blue shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
rh
+

Set the red highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bh
+

Set the blue highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
saturation
+

Set the amount of saturation. Allowed range is from -3.0 to 3.0. +Default value is 1. +

+
+
analyze
+

If set to anything other than manual it will analyze every frame and use derived +parameters for filtering output frame. +

+

Possible values are: +

+
‘manual’
+
‘average’
+
‘minmax’
+
‘median’
+
+

Default value is manual. +

+
+ + +

30.30.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.31 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: +

+
red=red*rr + blue*rb + green*rg + alpha*ra
+
+ +

The filter accepts the following options: +

+
+
rr
+
rg
+
rb
+
ra
+

Adjust contribution of input red, green, blue and alpha channels for output red channel. +Default is 1 for rr, and 0 for rg, rb and ra. +

+
+
gr
+
gg
+
gb
+
ga
+

Adjust contribution of input red, green, blue and alpha channels for output green channel. +Default is 1 for gg, and 0 for gr, gb and ga. +

+
+
br
+
bg
+
bb
+
ba
+

Adjust contribution of input red, green, blue and alpha channels for output blue channel. +Default is 1 for bb, and 0 for br, bg and ba. +

+
+
ar
+
ag
+
ab
+
aa
+

Adjust contribution of input red, green, blue and alpha channels for output alpha channel. +Default is 1 for aa, and 0 for ar, ag and ab. +

+

Allowed ranges for options are [-2.0, 2.0]. +

+
+
pc
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+ +
+
pa
+

Set the preserve color amount when changing colors. Allowed range is from [0.0, 1.0]. +Default is 0.0, thus disabled. +

+
+ + +

30.31.1 Examples

+ +
    +
  • Convert source to grayscale: +
    +
    colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
    +
    +
  • Simulate sepia tones: +
    +
    colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
    +
    +
+ + +

30.31.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.32 colordetect

+

Analyze the video frames to determine the effective value range and alpha +mode. +

+

The filter accepts the following options: +

+
+
mode
+

Set of properties to detect. Unavailable properties, such as alpha mode for +an input image without an alpha channel, will be ignored automatically. +

+

Accepts a combination of the following flags: +

+
+
‘color_range’
+

Detect if the source contains luma pixels outside the limited (MPEG) range, +which indicates that this is a full range YUV source. +

+
‘alpha_mode’
+

Detect if the source contains color values above the alpha channel, which +indicates that the alpha channel is independent (straight), rather than +premultiplied. Also detects if the alpha plane is fully opaque or not. +

+
‘all’
+

Enable detection of all of the above properties. This is the default. +

+
+ +
+
+ + +

30.33 colorize

+

Overlay a solid color on the video stream. +

+

The filter accepts the following options: +

+
+
hue
+

Set the color hue. Allowed range is from 0 to 360. +Default value is 0. +

+
+
saturation
+

Set the color saturation. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
lightness
+

Set the color lightness. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
mix
+

Set the mix of source lightness. By default is set to 1.0. +Allowed range is from 0.0 to 1.0. +

+
+ + +

30.33.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.34 colorkey

+

RGB colorspace color keying. +This filter operates on 8-bit RGB format frames by setting the alpha component of each pixel +which falls within the similarity radius of the key color to 0. The alpha value for pixels outside +the similarity radius depends on the value of the blend option. +

+

The filter accepts the following options: +

+
+
color
+

Set the color for which alpha will be set to 0 (full transparency). +See "Color" section in the ffmpeg-utils manual. +Default is black. +

+
+
similarity
+

Set the radius from the key color within which other colors also have full transparency. +The computed distance is related to the unit fractional distance in 3D space between the RGB values +of the key color and the pixel’s color. Range is 0.01 to 1.0. 0.01 matches within a very small radius +around the exact key color, while 1.0 matches everything. +Default is 0.01. +

+
+
blend
+

Set how the alpha value for pixels that fall outside the similarity radius is computed. +0.0 makes pixels either fully transparent or fully opaque. +Higher values result in semi-transparent pixels, with greater transparency +the more similar the pixel color is to the key color. +Range is 0.0 to 1.0. Default is 0.0. +

+
+ + +

30.34.1 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf colorkey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static background image. +
    +
    ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv
    +
    +
+ + +

30.34.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.35 colorhold

+

Remove all color information for all RGB colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral gray. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. 0.0 makes pixels fully gray. +Higher values result in more preserved color. +

+
+ + +

30.35.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.36 colorlevels

+ +

Adjust video input frames using levels. +

+

The filter accepts the following options: +

+
+
rimin
+
gimin
+
bimin
+
aimin
+

Adjust red, green, blue and alpha input black point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
rimax
+
gimax
+
bimax
+
aimax
+

Adjust red, green, blue and alpha input white point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 1. +

+

Input levels are used to lighten highlights (bright tones), darken shadows +(dark tones), change the balance of bright and dark tones. +

+
+
romin
+
gomin
+
bomin
+
aomin
+

Adjust red, green, blue and alpha output black point. +Allowed ranges for options are [0, 1.0]. Defaults are 0. +

+
+
romax
+
gomax
+
bomax
+
aomax
+

Adjust red, green, blue and alpha output white point. +Allowed ranges for options are [0, 1.0]. Defaults are 1. +

+

Output levels allows manual selection of a constrained output level range. +

+
+
preserve
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+
+
+ + +

30.36.1 Examples

+ +
    +
  • Make video output darker: +
    +
    colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
    +
    + +
  • Increase contrast: +
    +
    colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
    +
    + +
  • Make video output lighter: +
    +
    colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
    +
    + +
  • Increase brightness: +
    +
    colorlevels=romin=0.5:gomin=0.5:bomin=0.5
    +
    +
+ + +

30.36.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.37 colormap

+

Apply custom color maps to video stream. +

+

This filter needs three input video streams. +First stream is video stream that is going to be filtered out. +Second and third video stream specify color patches for source +color to target color mapping. +

+

The filter accepts the following options: +

+
+
patch_size
+

Set the source and target video stream patch size in pixels. +

+
+
nb_patches
+

Set the max number of used patches from source and target video stream. +Default value is number of patches available in additional video streams. +Max allowed number of patches is 64. +

+
+
type
+

Set the adjustments used for target colors. Can be relative or absolute. +Defaults is absolute. +

+
+
kernel
+

Set the kernel used to measure color differences between mapped colors. +

+

The accepted values are: +

+
‘euclidean’
+
‘weuclidean’
+
+ +

Default is euclidean. +

+
+ + +

30.38 colormatrix

+ +

Convert color matrix. +

+

The filter accepts the following options: +

+
+
src
+
dst
+

Specify the source and destination color matrix. Both values must be +specified. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt601’
+

BT.601 +

+
+
‘bt470’
+

BT.470 +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+
+ +

For example to convert from BT.601 to SMPTE-240M, use the command: +

+
colormatrix=bt601:smpte240m
+
+ + +

30.39 colorspace

+ +

Convert colorspace, transfer characteristics or color primaries. +Input video needs to have an even size. +

+

The filter accepts the following options: +

+
+
+
all
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘bt601-6-525’
+

BT.601-6 525 +

+
+
‘bt601-6-625’
+

BT.601-6 625 +

+
+
‘bt709’
+

BT.709 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
space
+

Specify output colorspace. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘ycgco’
+

YCgCo +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M, BT.601-6 625 or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘srgb’
+

SRGB +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘xvycc’
+

xvycc +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+ +
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
format
+

Specify output color format. +

+

The accepted values are: +

+
‘yuv420p’
+

YUV 4:2:0 planar 8-bits +

+
+
‘yuv420p10’
+

YUV 4:2:0 planar 10-bits +

+
+
‘yuv420p12’
+

YUV 4:2:0 planar 12-bits +

+
+
‘yuv422p’
+

YUV 4:2:2 planar 8-bits +

+
+
‘yuv422p10’
+

YUV 4:2:2 planar 10-bits +

+
+
‘yuv422p12’
+

YUV 4:2:2 planar 12-bits +

+
+
‘yuv444p’
+

YUV 4:4:4 planar 8-bits +

+
+
‘yuv444p10’
+

YUV 4:4:4 planar 10-bits +

+
+
‘yuv444p12’
+

YUV 4:4:4 planar 12-bits +

+
+
+ +
+
fast
+

Do a fast conversion, which skips gamma/primary correction. This will take +significantly less CPU, but will be mathematically incorrect. To get output +compatible with that produced by the colormatrix filter, use fast=1. +

+
+
dither
+

Specify dithering mode. +

+

The accepted values are: +

+
‘none’
+

No dithering +

+
+
‘fsb’
+

Floyd-Steinberg dithering +

+
+ +
+
wpadapt
+

Whitepoint adaptation mode. +

+

The accepted values are: +

+
‘bradford’
+

Bradford whitepoint adaptation +

+
+
‘vonkries’
+

von Kries whitepoint adaptation +

+
+
‘identity’
+

identity whitepoint adaptation (i.e. no whitepoint adaptation) +

+
+ +
+
clipgamut
+

Controls how to clip out-of-gamut colors that arise as a result of colorspace conversion. +

+

The accepted values are: +

+
‘none’
+

No clipping of out of gamut colors. +

+
+
‘rgb’
+

Clips the RGB values to the [0, 1] range when building the gamma transfer LUTs. +

+
+ +
+
iall
+

Override all input properties at once. Same accepted values as all. +

+
+
ispace
+

Override input colorspace. Same accepted values as space. +

+
+
iprimaries
+

Override input color primaries. Same accepted values as primaries. +

+
+
itrc
+

Override input transfer characteristics. Same accepted values as trc. +

+
+
irange
+

Override input color range. Same accepted values as range. +

+
+
+ +

The filter converts the transfer characteristics, color space and color +primaries to the specified user values. The output value, if not specified, +is set to a default value based on the "all" property. If that property is +also not specified, the filter will log an error. The output color range and +format default to the same value as the input color range and format. The +input transfer characteristics, color space, color primaries and color range +should be set on the input data. If any of these are missing, the filter will +log an error and no conversion will take place. +

+

For example to convert the input to SMPTE-240M, use the command: +

+
colorspace=smpte240m
+
+ + +

30.40 colortemperature

+

Adjust color temperature in video to simulate variations in ambient color temperature. +

+

The filter accepts the following options: +

+
+
temperature
+

Set the temperature in Kelvin. Allowed range is from 1000 to 40000. +Default value is 6500 K. +

+
+
mix
+

Set mixing with filtered output. Allowed range is from 0 to 1. +Default value is 1. +

+
+
pl
+

Set the amount of preserving lightness. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

30.40.1 Commands

+

This filter supports same commands as options. +

+ +

30.41 convolution

+ +

Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed integers in square mode, +and from 1 to 49 odd number of signed integers in row mode. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be 1/sum of all matrix elements. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. Default is 0.0. +

+
+
0mode
+
1mode
+
2mode
+
3mode
+

Set matrix mode for each plane. Can be square, row or column. +Default is square. +

+
+ + +

30.41.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.41.2 Examples

+ +
    +
  • Apply sharpen: +
    +
    convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
    +
    + +
  • Apply blur: +
    +
    convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
    +
    + +
  • Apply edge enhance: +
    +
    convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
    +
    + +
  • Apply edge detect: +
    +
    convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"
    +
    + +
  • Apply emboss: +
    +
    convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
    +
    +
+ + +

30.42 convolve

+ +

Apply 2D convolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+ +

The convolve filter also supports the framesync options. +

+ +

30.43 copy

+ +

Copy the input video source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

30.44 coreimage

+

Video filtering on GPU using Apple’s CoreImage API on OSX. +

+

Hardware acceleration is based on an OpenGL context. Usually, this means it is +processed by video hardware. However, software-based OpenGL implementations +exist which means there is no guarantee for hardware processing. It depends on +the respective OSX. +

+

There are many filters and image generators provided by Apple that come with a +large variety of options. The filter has to be referenced by its name along +with its options. +

+

The coreimage filter accepts the following options: +

+
list_filters
+

List all available filters and generators along with all their respective +options as well as possible minimum and maximum values along with the default +values. +

+
list_filters=true
+
+ +
+
filter
+

Specify all filters by their respective name and options. +Use list_filters to determine all valid filter names and options. +Numerical options are specified by a float value and are automatically clamped +to their respective value range. Vector and color options have to be specified +by a list of space separated float values. Character escaping has to be done. +A special option name default is available to use default options for a +filter. +

+

It is required to specify either default or at least one of the filter options. +All omitted options are used with their default values. +The syntax of the filter string is as follows: +

+
filter=<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...][#<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...]][#...]
+
+ +
+
output_rect
+

Specify a rectangle where the output of the filter chain is copied into the +input image. It is given by a list of space separated float values: +

+
output_rect=x\ y\ width\ height
+
+

If not given, the output rectangle equals the dimensions of the input image. +The output rectangle is automatically cropped at the borders of the input +image. Negative values are valid for each component. +

+
output_rect=25\ 25\ 100\ 100
+
+
+
+ +

Several filters can be chained for successive processing without GPU-HOST +transfers allowing for fast processing of complex filter chains. +Currently, only filters with zero (generators) or exactly one (filters) input +image and one output image are supported. Also, transition filters are not yet +usable as intended. +

+

Some filters generate output images with additional padding depending on the +respective filter kernel. The padding is automatically removed to ensure the +filter output has the same size as the input image. +

+

For image generators, the size of the output image is determined by the +previous output image of the filter chain or the input image of the whole +filterchain, respectively. The generators do not use the pixel information of +this image to generate their output. However, the generated output is +blended onto this image, resulting in partial or complete coverage of the +output image. +

+

The coreimagesrc video source can be used for generating input images +which are directly fed into the filter chain. By using it, providing input +images by another video source or an input video is not required. +

+ +

30.44.1 Examples

+ +
    +
  • List all filters available: +
    +
    coreimage=list_filters=true
    +
    + +
  • Use the CIBoxBlur filter with default options to blur an image: +
    +
    coreimage=filter=CIBoxBlur@default
    +
    + +
  • Use a filter chain with CISepiaTone at default values and CIVignetteEffect with +its center at 100x100 and a radius of 50 pixels: +
    +
    coreimage=filter=CIBoxBlur@default#CIVignetteEffect@inputCenter=100\ 100@inputRadius=50
    +
    + +
  • Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +
+ + +

30.45 corr

+ +

Obtain the correlation between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max correlation is printed through +the logging system. +

+

The filter stores the calculated correlation of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi corr -f null -
+
+ + +

30.46 cover_rect

+ +

Cover a rectangular object +

+

It accepts the following options: +

+
+
cover
+

Filepath of the optional cover image, needs to be in yuv420. +

+
+
mode
+

Set covering mode. +

+

It accepts the following values: +

+
‘cover’
+

cover it by the supplied image +

+
‘blur’
+

cover it by interpolating the surrounding pixels +

+
+ +

Default value is blur. +

+
+ + +

30.46.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    +
+ + +

30.47 crop

+ +

Crop the input video to given dimensions. +

+

It accepts the following parameters: +

+
+
w, out_w
+

The width of the output video. It defaults to iw. +This expression is evaluated only once during the filter +configuration, or when the ‘w’ or ‘out_w’ command is sent. +

+
+
h, out_h
+

The height of the output video. It defaults to ih. +This expression is evaluated only once during the filter +configuration, or when the ‘h’ or ‘out_h’ command is sent. +

+
+
x
+

The horizontal position, in the input video, of the left edge of the output +video. It defaults to (in_w-out_w)/2. +This expression is evaluated per-frame. +

+
+
y
+

The vertical position, in the input video, of the top edge of the output video. +It defaults to (in_h-out_h)/2. +This expression is evaluated per-frame. +

+
+
keep_aspect
+

If set to 1 will force the output display aspect ratio +to be the same of the input, by changing the output sample aspect +ratio. It defaults to 0. +

+
+
exact
+

Enable exact cropping. If enabled, subsampled videos will be cropped at exact +width/height/x/y as specified and will not be rounded to nearest smaller value. +It defaults to 0. +

+
+ +

The out_w, out_h, x, y parameters are +expressions containing the following constants: +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
in_w
+
in_h
+

The input width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (cropped) width and height. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

The expression for out_w may depend on the value of out_h, +and the expression for out_h may depend on out_w, but they +cannot depend on x and y, as x and y are +evaluated after out_w and out_h. +

+

The x and y parameters specify the expressions for the +position of the top-left corner of the output (non-cropped) area. They +are evaluated for each frame. If the evaluated value is not valid, it +is approximated to the nearest valid value. +

+

The expression for x may depend on y, and the expression +for y may depend on x. +

+ +

30.47.1 Examples

+ +
    +
  • Crop area with size 100x100 at position (12,34). +
    +
    crop=100:100:12:34
    +
    + +

    Using named options, the example above becomes: +

    +
    crop=w=100:h=100:x=12:y=34
    +
    + +
  • Crop the central input area with size 100x100: +
    +
    crop=100:100
    +
    + +
  • Crop the central input area with size 2/3 of the input video: +
    +
    crop=2/3*in_w:2/3*in_h
    +
    + +
  • Crop the input video central square: +
    +
    crop=out_w=in_h
    +crop=in_h
    +
    + +
  • Delimit the rectangle with the top-left corner placed at position +100:100 and the right-bottom corner corresponding to the right-bottom +corner of the input image. +
    +
    crop=in_w-100:in_h-100:100:100
    +
    + +
  • Crop 10 pixels from the left and right borders, and 20 pixels from +the top and bottom borders +
    +
    crop=in_w-2*10:in_h-2*20
    +
    + +
  • Keep only the bottom right quarter of the input image: +
    +
    crop=in_w/2:in_h/2:in_w/2:in_h/2
    +
    + +
  • Crop height for getting Greek harmony: +
    +
    crop=in_w:1/PHI*in_w
    +
    + +
  • Apply trembling effect: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)
    +
    + +
  • Apply erratic camera effect depending on timestamp: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)
    +
    + +
  • Set x depending on the value of y: +
    +
    crop=in_w/2:in_h/2:y:10+10*sin(n/10)
    +
    +
+ + +

30.47.2 Commands

+ +

This filter supports the following commands: +

+
w, out_w
+
h, out_h
+
x
+
y
+

Set width/height of the output video and the horizontal/vertical position +in the input video. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+
+ + +

30.48 cropdetect

+ +

Auto-detect the crop size. +

+

It calculates the necessary cropping parameters and prints the +recommended parameters via the logging system. The detected dimensions +correspond to the non-black or video area of the input video according to mode. +

+

It accepts the following parameters: +

+
+
mode
+

Depending on mode crop detection is based on either the mere black value of surrounding pixels or a combination of motion vectors and edge pixels. +

+
+
‘black’
+

Detect black pixels surrounding the playing video. For fine control use option limit. +

+
+
‘mvedges’
+

Detect the playing video by the motion vectors inside the video and scanning for edge pixels typically forming the border of a playing video. +

+
+ +
+
limit
+

Set higher black value threshold, which can be optionally specified +from nothing (0) to everything (255 for 8-bit based formats). An intensity +value greater to the set value is considered non-black. It defaults to 24. +You can also specify a value between 0.0 and 1.0 which will be scaled depending +on the bitdepth of the pixel format. +

+
+
round
+

The value which the width/height should be divisible by. It defaults to +16. The 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. +

+
+
skip
+

Set the number of initial frames for which evaluation is skipped. +Default is 2. Range is 0 to INT_MAX. +

+
+
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. +

+

This can be useful when channel logos distort the video area. 0 +indicates ’never reset’, and returns the largest area encountered during +playback. +

+
+
mv_threshold
+

Set motion in pixel units as threshold for motion detection. It defaults to 8. +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 5/255, and default value for high +is 15/255. +

+
+ + +

30.48.1 Examples

+ +
    +
  • Find video area surrounded by black borders: +
    +
    ffmpeg -i file.mp4 -vf cropdetect,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, generate motion vectors beforehand: +
    +
    ffmpeg -i file.mp4 -vf mestimate,cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, use motion vectors from decoder: +
    +
    ffmpeg -flags2 +export_mvs -i file.mp4 -vf cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    +
+ + +

30.48.2 Commands

+ +

This filter supports the following commands: +

+
+
limit
+

The command accepts the same syntax of the corresponding option. +If the specified expression is not valid, it is kept at its current value. +

+
+ + +

30.49 cue

+ +

Delay video filtering until a given wallclock timestamp. The filter first +passes on preroll amount of frames, then it buffers at most +buffer amount of frames and waits for the cue. After reaching the cue +it forwards the buffered frames and also any subsequent frames coming in its +input. +

+

The filter can be used synchronize the output of multiple ffmpeg processes for +realtime output devices like decklink. By putting the delay in the filtering +chain and pre-buffering frames the process can pass on data to output almost +immediately after the target wallclock timestamp is reached. +

+

Perfect frame accuracy cannot be guaranteed, but the result is good enough for +some use cases. +

+
+
cue
+

The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. +

+
+
preroll
+

The duration of content to pass on as preroll expressed in seconds. Default is 0. +

+
+
buffer
+

The maximum duration of content to buffer before waiting for the cue expressed +in seconds. Default is 0. +

+
+
+ + +

30.50 curves

+ +

Apply color adjustments using curves. +

+

This filter is similar to the Adobe Photoshop and GIMP curves tools. Each +component (red, green and blue) has its values defined by N key points +tied from each other using a smooth curve. The x-axis represents the pixel +values from the input frame, and the y-axis the new pixel values to be set for +the output frame. +

+

By default, a component curve is defined by the two points (0;0) and +(1;1). This creates a straight line where each original pixel value is +"adjusted" to its own value, which means no change to the image. +

+

The filter allows you to redefine these two points and add some more. A new +curve will be defined to pass smoothly through all these new coordinates. The +new defined points need to be strictly increasing over the x-axis, and their +x and y values must be in the [0;1] interval. The curve is +formed by using a natural or monotonic cubic spline interpolation, depending +on the interp option (default: natural). The natural +spline produces a smoother curve in general while the monotonic (pchip) +spline guarantees the transitions between the specified points to be +monotonic. If the computed curves happened to go outside the vector spaces, +the values will be clipped accordingly. +

+

The filter accepts the following options: +

+
+
preset
+

Select one of the available color presets. This option can be used in addition +to the r, g, b parameters; in this case, the later +options takes priority on the preset values. +Available presets are: +

+
‘none’
+
‘color_negative’
+
‘cross_process’
+
‘darker’
+
‘increase_contrast’
+
‘lighter’
+
‘linear_contrast’
+
‘medium_contrast’
+
‘negative’
+
‘strong_contrast’
+
‘vintage’
+
+

Default is none. +

+
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 +r, g, b or all since it acts like a +post-processing LUT. +

+
red, r
+

Set the key points for the red component. +

+
green, g
+

Set the key points for the green component. +

+
blue, b
+

Set the key points for the blue component. +

+
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 +all setting. +

+
psfile
+

Specify a Photoshop curves file (.acv) to import the settings from. +

+
plot
+

Save Gnuplot script of the curves in specified file. +

+
interp
+

Specify the kind of interpolation. Available algorithms are: +

+
‘natural’
+

Natural cubic spline using a piece-wise cubic polynomial that is twice continuously differentiable. +

+
‘pchip’
+

Monotonic cubic spline using a piecewise cubic Hermite interpolating polynomial (PCHIP). +

+
+ +
+
+ +

To avoid some filtergraph syntax conflicts, each key points list need to be +defined using the following syntax: x0/y0 x1/y1 x2/y2 .... +

+ +

30.50.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.50.2 Examples

+ +
    +
  • Increase slightly the middle level of blue: +
    +
    curves=blue='0/0 0.5/0.58 1/1'
    +
    + +
  • Vintage effect: +
    +
    curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'
    +
    +

    Here we obtain the following coordinates for each components: +

    +
    red
    +

    (0;0.11) (0.42;0.51) (1;0.95) +

    +
    green
    +

    (0;0) (0.50;0.48) (1;1) +

    +
    blue
    +

    (0;0.22) (0.49;0.44) (1;0.80) +

    +
    + +
  • The previous example can also be achieved with the associated built-in preset: +
    +
    curves=preset=vintage
    +
    + +
  • Or simply: +
    +
    curves=vintage
    +
    + +
  • Use a Photoshop preset and redefine the points of the green component: +
    +
    curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
    +
    + +
  • Check out the curves of the cross_process profile using ffmpeg +and gnuplot: +
    +
    ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
    +gnuplot -p /tmp/curves.plt
    +
    +
+ + +

30.51 datascope

+ +

Video data analysis filter. +

+

This filter shows hexadecimal pixel values of part of video. +

+

The filter accepts the following options: +

+
+
size, s
+

Set output video size. +

+
+
x
+

Set x offset from where to pick pixels. +

+
+
y
+

Set y offset from where to pick pixels. +

+
+
mode
+

Set scope mode, can be one of the following: +

+
‘mono’
+

Draw hexadecimal pixel values with white color on black background. +

+
+
‘color’
+

Draw hexadecimal pixel values with input video pixel color on black +background. +

+
+
‘color2’
+

Draw hexadecimal pixel values on color background picked from input video, +the text color is picked in such way so its always visible. +

+
+ +
+
axis
+

Draw rows and columns numbers on left and top of video. +

+
+
opacity
+

Set background opacity. +

+
+
format
+

Set display number format. Can be hex, or dec. Default is hex. +

+
+
components
+

Set pixel components to display. By default all pixel components are displayed. +

+
+ + +

30.51.1 Commands

+ +

This filter supports same commands as options excluding size option. +

+ +

30.52 dblur

+

Apply Directional blur filter. +

+

The filter accepts the following options: +

+
+
angle
+

Set angle of directional blur. Default is 45. +

+
+
radius
+

Set radius of directional blur. Default is 5. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+ + +

30.52.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.53 dctdnoiz

+ +

Denoise frames using 2D DCT (frequency domain filtering). +

+

This filter is not designed for real time. +

+

The filter accepts the following options: +

+
+
sigma, s
+

Set the noise sigma constant. +

+

This sigma defines a hard threshold of 3 * sigma; every DCT +coefficient (absolute value) below this threshold with be dropped. +

+

If you need a more advanced filtering, see expr. +

+

Default is 0. +

+
+
overlap
+

Set number overlapping pixels for each block. 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 permit processing the whole input width or +height, a warning will be displayed and according borders won’t be denoised. +

+

Default value is blocksize-1, which is the best possible setting. +

+
+
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 sigma option will be ignored. +

+

The absolute value of the coefficient can be accessed through the c +variable. +

+
+
n
+

Set the blocksize using the number of bits. 1<<n defines the +blocksize, which is the width and height of the processed blocks. +

+

The default value is 3 (8x8) and can be raised to 4 for a +blocksize of 16x16. Note that changing this setting has huge consequences +on the speed processing. Also, a larger block size does not necessarily means a +better de-noising. +

+
+ + +

30.53.1 Examples

+ +

Apply a denoise with a sigma of 4.5: +

+
dctdnoiz=4.5
+
+ +

The same operation can be achieved using the expression system: +

+
dctdnoiz=e='gte(c, 4.5*3)'
+
+ +

Violent denoise using a block size of 16x16: +

+
dctdnoiz=15:n=4
+
+ + +

30.54 deband

+ +

Remove banding artifacts from input video. +It works by replacing banded pixels with average value of referenced pixels. +

+

The filter accepts the following options: +

+
+
1thr
+
2thr
+
3thr
+
4thr
+

Set banding detection threshold for each plane. Default is 0.02. +Valid range is 0.00003 to 0.5. +If difference between current pixel and reference pixel is less than threshold, +it will be considered as banded. +

+
+
range, r
+

Banding detection range in pixels. Default is 16. If positive, random number +in range 0 to set value will be used. If negative, exact absolute value +will be used. +The range defines square of four pixels around current pixel. +

+
+
direction, d
+

Set direction in radians from which four pixel will be compared. If positive, +random direction from 0 to set direction will be picked. If negative, exact of +absolute value will be picked. For example direction 0, -PI or -2*PI radians +will pick only pixels on same row and -PI/2 will pick only pixels on same +column. +

+
+
blur, b
+

If enabled, current pixel is compared with average value of all four +surrounding pixels. The default is enabled. If disabled current pixel is +compared with all four surrounding pixels. The pixel is considered banded +if only all four differences with surrounding pixels are less than threshold. +

+
+
coupling, c
+

If enabled, current pixel is changed if and only if all pixel components are banded, +e.g. banding detection threshold is triggered for all color components. +The default is disabled. +

+
+ + +

30.54.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.55 deblock

+ +

Remove blocking artifacts from input video. +

+

The filter accepts the following options: +

+
+
filter
+

Set filter type, can be weak or strong. Default is strong. +This controls what kind of deblocking is applied. +

+
+
block
+

Set size of block, allowed range is from 4 to 512. Default is 8. +

+
+
alpha
+
beta
+
gamma
+
delta
+

Set blocking detection thresholds. Allowed range is 0 to 1. +Defaults are: 0.098 for alpha and 0.05 for the rest. +Using higher threshold gives more deblocking strength. +Setting alpha controls threshold detection at exact edge of block. +Remaining options controls threshold detection near the edge. Each one for +below/above or left/right. Setting any of those to 0 disables +deblocking. +

+
+
planes
+

Set planes to filter. Default is to filter all available planes. +

+
+ + +

30.55.1 Examples

+ +
    +
  • Deblock using weak filter and block size of 4 pixels. +
    +
    deblock=filter=weak:block=4
    +
    + +
  • Deblock using strong filter, block size of 4 pixels and custom thresholds for +deblocking more edges. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
    +
    + +
  • Similar as above, but filter only first plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
    +
    + +
  • Similar as above, but filter only second and third plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
    +
    +
+ + +

30.55.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.56 decimate

+ +

Drop duplicated frames at regular intervals. +

+

The filter accepts the following options: +

+
+
cycle
+

Set the number of frames from which one will be dropped. Setting this to +N means one frame in every batch of N frames will be dropped. +Default is 5. +

+
+
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 1.1 +

+
+
scthresh
+

Set scene change threshold. Default is 15. +

+
+
blockx
+
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 32. +

+
+
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 +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 +0. +

+
+
chroma
+

Set whether or not chroma is considered in the metric calculations. Default is +1. +

+
+
mixed
+

Set whether or not the input only partially contains content to be decimated. +Default is false. +If enabled video output stream will be in variable frame rate. +

+
+ + +

30.57 deconvolve

+ +

Apply 2D deconvolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+
noise
+

Set noise when doing divisions. Default is 0.0000001. Useful when width +and height are not same and not power of 2 or if stream prior to convolving +had noise. +

+
+ +

The deconvolve filter also supports the framesync options. +

+ +

30.58 dedot

+ +

Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video. +

+

It accepts the following options: +

+
+
m
+

Set mode of operation. Can be combination of dotcrawl for cross-luminance reduction and/or +rainbows for cross-color reduction. +

+
+
lt
+

Set spatial luma threshold. Lower values increases reduction of cross-luminance. +

+
+
tl
+

Set tolerance for temporal luma. Higher values increases reduction of cross-luminance. +

+
+
tc
+

Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color. +

+
+
ct
+

Set temporal chroma threshold. Lower values increases reduction of cross-color. +

+
+ + +

30.59 deflate

+ +

Apply deflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values lower than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

30.59.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.60 deflicker

+ +

Remove temporal frame luminance variations. +

+

It accepts the following options: +

+
+
size, s
+

Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. +

+
+
mode, m
+

Set averaging mode to smooth temporal luminance variations. +

+

Available values are: +

+
‘am’
+

Arithmetic mean +

+
+
‘gm’
+

Geometric mean +

+
+
‘hm’
+

Harmonic mean +

+
+
‘qm’
+

Quadratic mean +

+
+
‘cm’
+

Cubic mean +

+
+
‘pm’
+

Power mean +

+
+
‘median’
+

Median +

+
+ +
+
bypass
+

Do not actually modify frame. Useful when one only wants metadata. +

+
+ + +

30.61 deinterlace_d3d12

+ +

Deinterlace the input video using D3D12 hardware-accelerated video processing. +

+

This filter uses the DirectX 12 Video Processor to perform deinterlacing on +GPU, supporting both simple bob and driver-defined advanced (motion-adaptive) +algorithms. It requires the input to be in d3d12 hardware pixel format. +

+

The filter automatically queries the hardware for the required number of +temporal reference frames (if needed) and manages a frame queue to supply them. +

+

It accepts the following options: +

+
+
method
+

The deinterlacing method. It accepts one of the following values: +

+
+
‘default’
+

Select the best deinterlacing method available on the hardware. +If the driver supports custom, that method is used; otherwise +falls back to bob. This is the default. +

+
+
‘bob’
+

Bob deinterlacing. Each field is independently scaled to full +frame height. Simple and fast, but may produce visible bob artifacts +on moving content. +

+
+
‘custom’
+

Driver-defined advanced deinterlacing. The exact algorithm is +hardware-specific and typically employs motion-adaptive techniques +with temporal reference frames for higher quality. +

+
+ +

The default value is default. +

+
+
mode
+

Specify the interlacing mode. It accepts one of the following values: +

+
+
‘frame’
+

Send one frame for each frame. The output frame rate equals the input +frame rate. This is the default. +

+
+
‘field’
+

Send one frame for each field. The output frame rate is double the +input frame rate. +

+
+ +

The default value is frame. +

+
+
deint
+

Specify which frames to deinterlace. It accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames. This is the default. +

+
+
‘interlaced’
+

Only deinterlace frames marked as interlaced; progressive frames are +passed through unchanged. +

+
+ +

The default value is all. +

+
+ + +

30.61.1 Examples

+ +
    +
  • Deinterlace an interlaced video using software decoding and the best +available hardware deinterlacing method: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=method=default,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
  • Deinterlace at field rate (double the frame rate) using bob method with +hardware decoding (full d3d12 pipeline): +
    +
    ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.ts \
    +       -vf "deinterlace_d3d12=method=bob:mode=field" \
    +       -c:v h264_d3d12va output.mp4
    +
    + +
  • Deinterlace only interlaced frames, passing progressive frames through: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=deint=interlaced,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
+ + +

30.62 dejudder

+ +

Remove judder produced by partially interlaced telecined content. +

+

Judder can be introduced, for instance, by pullup filter. If the original +source was partially telecined content then the output of pullup,dejudder +will have a variable frame rate. May change the recorded frame rate of the +container. Aside from that change, this filter will not affect constant frame +rate video. +

+

The option available in this filter is: +

+
cycle
+

Specify the length of the window over which the judder repeats. +

+

Accepts any integer greater than 1. Useful values are: +

+
‘4’
+

If the original was telecined from 24 to 30 fps (Film to NTSC). +

+
+
‘5’
+

If the original was telecined from 25 to 30 fps (PAL to NTSC). +

+
+
‘20’
+

If a mixture of the two. +

+
+ +

The default is ‘4’. +

+
+ + +

30.63 delogo

+ +

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). +

+

It accepts the following parameters: +

+
x
+
y
+

Specify the top left corner coordinates of the logo. They must be +specified. +

+
+
w
+
h
+

Specify the width and height of the logo to clear. They must be +specified. +

+
+
show
+

When set to 1, a green rectangle is drawn on the screen to simplify +finding the right x, y, w, and 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. +

+
+
+ + +

30.63.1 Examples

+ +
    +
  • Set a rectangle covering the area with top left corner coordinates 0,0 +and size 100x77: +
    +
    delogo=x=0:y=0:w=100:h=77
    +
    + +
+ + +

30.64 derain

+ +

Remove the rain in the input image/video by applying the derain methods based on +convolutional neural networks. Supported models: +

+ + +

Training as well as model generation scripts are provided in +the repository at https://github.com/XueweiMeng/derain_filter.git. +

+

The filter accepts the following options: +

+
+
filter_type
+

Specify which filter to use. This option accepts the following values: +

+
+
‘derain’
+

Derain filter. To conduct derain filter, you need to use a derain model. +

+
+
‘dehaze’
+

Dehaze filter. To conduct dehaze filter, you need to use a dehaze model. +

+
+

Default value is ‘derain’. +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow can load files for only its format. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

30.65 deshake

+ +

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 the following options: +

+
+
x
+
y
+
w
+
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 +rectangular area of the frame defined by its top left corner, width +and height. These parameters have the same meaning as the drawbox +filter which can be used to visualise the position of the bounding +box. +

+

This is useful when simultaneous movement of subjects within the frame +might be confused for camera motion by the motion vector search. +

+

If any or all of x, y, w and h are set to -1 +then the full frame is used. This allows later options to be set +without specifying the bounding box for the motion vector search. +

+

Default - search the whole frame. +

+
+
rx
+
ry
+

Specify the maximum extent of movement in x and y directions in the +range 0-64 pixels. Default 16. +

+
+
edge
+

Specify how to generate pixels to fill blanks at the edge of the +frame. Available values are: +

+
‘blank, 0’
+

Fill zeroes at blank locations +

+
‘original, 1’
+

Original image at blank locations +

+
‘clamp, 2’
+

Extruded edge value at blank locations +

+
‘mirror, 3’
+

Mirrored edge at blank locations +

+
+

Default value is ‘mirror’. +

+
+
blocksize
+

Specify the blocksize to use for motion search. Range 4-128 pixels, +default 8. +

+
+
contrast
+

Specify the contrast threshold for blocks. Only blocks with more than +the specified contrast (difference between darkest and lightest +pixels) will be considered. Range 1-255, default 125. +

+
+
search
+

Specify the search strategy. Available values are: +

+
‘exhaustive, 0’
+

Set exhaustive search +

+
‘less, 1’
+

Set less exhaustive search. +

+
+

Default value is ‘exhaustive’. +

+
+
filename
+

If set then a detailed log of the motion search is written to the +specified file. +

+
+
+ + +

30.66 despill

+ +

Remove unwanted contamination of foreground colors, caused by reflected color of +greenscreen or bluescreen. +

+

This filter accepts the following options: +

+
+
type
+

Set what type of despill to use. +

+
+
mix
+

Set how spillmap will be generated. +

+
+
expand
+

Set how much to get rid of still remaining spill. +

+
+
red
+

Controls amount of red in spill area. +

+
+
green
+

Controls amount of green in spill area. +Should be -1 for greenscreen. +

+
+
blue
+

Controls amount of blue in spill area. +Should be -1 for bluescreen. +

+
+
brightness
+

Controls brightness of spill area, preserving colors. +

+
+
alpha
+

Modify alpha from generated spillmap. +

+
+ + +

30.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.67 detelecine

+ +

Apply an exact inverse of the telecine operation. It requires a predefined +pattern specified using the pattern option which must be the same as that passed +to the telecine filter. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+
start_frame
+

A number representing position of the first frame with respect to the telecine +pattern. This is to be used if the stream is cut. The default value is 0. +

+
+ + +

30.68 dilation

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

30.68.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.69 displace

+ +

Displace pixels as indicated by second and third input stream. +

+

It takes three input streams and outputs one stream, the first input is the +source, and second and third input are displacement maps. +

+

The second input specifies how much to displace pixels along the +x-axis, while the third input specifies how much to displace pixels +along the y-axis. +If one of displacement map streams terminates, last frame from that +displacement map will be used. +

+

Note that once generated, displacements maps can be reused over and over again. +

+

A description of the accepted options follows. +

+
+
edge
+

Set displace behavior for pixels that are out of range. +

+

Available values are: +

+
‘blank’
+

Missing pixels are replaced by black pixels. +

+
+
‘smear’
+

Adjacent pixels will spread out to replace missing pixels. +

+
+
‘wrap’
+

Out of range pixels are wrapped so they point to pixels of other side. +

+
+
‘mirror’
+

Out of range pixels will be replaced with mirrored pixels. +

+
+

Default is ‘smear’. +

+
+
+ + +

30.69.1 Examples

+ +
    +
  • Add ripple effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT
    +
    + +
  • Add wave effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT
    +
    +
+ + +

30.70 dnn_classify

+ +

Do classification with deep neural networks based on bounding boxes. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0, +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs for your system. +

+
+
+ + +

30.71 dnn_detect

+ +

Do object detection with deep neural networks. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0 (usually it is ’background’), +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+
+
+ + +

30.72 dnn_processing

+ +

Do image processing with deep neural networks. It works together with another filter +which converts the pixel format of the Frame to what the dnn network requires. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+
‘openvino’
+

OpenVINO backend. To enable this backend you +need to build and install the OpenVINO for C library (see +https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md) and configure FFmpeg with +--enable-libopenvino (–extra-cflags=-I... –extra-ldflags=-L... might +be needed if the header files and libraries are not installed into system path) +

+
+
‘torch’
+

Libtorch backend. To enable this backend you need to build and install Libtroch +for C++ library. Please download cxx11 ABI version (see +https://pytorch.org/get-started/locally) +and configure FFmpeg with --enable-libtorch +--extra-cflags=-I/libtorch_root/libtorch/include +--extra-cflags=-I/libtorch_root/libtorch/include/torch/csrc/api/include +--extra-ldflags=-L/libtorch_root/libtorch/lib/ +

+
+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO +and Libtorch backend can load files for only its format. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +

+
+
+ + +

30.72.1 Examples

+ +
    +
  • Remove rain in rgb24 frame with can.pb (see derain filter): +
    +
    ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
    +
    + +
  • Handle the Y channel with srcnn.pb (see sr filter) for frame with yuv420p (planar YUV formats supported): +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
    +
    + +
  • Handle the Y channel with espcn.pb (see sr filter), which changes frame size, for format yuv420p (planar YUV formats supported), +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y:backend_configs=sess_config=0x10022805320e09cdccccccccccec3f20012a01303801 -y tmp.espcn.jpg
    +
    + +
+ + +

30.73 drawbox

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

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 invert is used, the box edge color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With value 1, the pixels of the painted box +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
box_source
+

Box source can be set as side_data_detection_bboxes if you want to use box data in +detection bboxes of side data. +

+

If box_source is set, the x, y, width and height will be ignored and +still use box data in detection bboxes of side data. So please do not use this parameter if you were +not sure about the box source. +

+
+
t
+

The thickness of the drawn box. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

30.73.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + +

30.73.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.74 drawgraph

+

Draw a graph using input video metadata. +

+

It accepts the following parameters: +

+
+
m1
+

Set 1st frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg1
+

Set 1st foreground color expression. +

+
+
m2
+

Set 2nd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg2
+

Set 2nd foreground color expression. +

+
+
m3
+

Set 3rd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg3
+

Set 3rd foreground color expression. +

+
+
m4
+

Set 4th frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg4
+

Set 4th foreground color expression. +

+
+
min
+

Set minimal value of metadata value. +

+
+
max
+

Set maximal value of metadata value. +

+
+
bg
+

Set graph background color. Default is white. +

+
+
mode
+

Set graph mode. +

+

Available values for mode is: +

+
‘bar’
+
‘dot’
+
‘line’
+
+ +

Default is line. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is frame. +

+
+
size
+

Set size of graph video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +The default value is 900x256. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+

The foreground color expressions can use the following variables: +

+
MIN
+

Minimal value of metadata value. +

+
+
MAX
+

Maximal value of metadata value. +

+
+
VAL
+

Current metadata key value. +

+
+ +

The color is defined as 0xAABBGGRR. +

+
+ +

Example using metadata from signalstats filter: +

+
signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
+
+ +

Example using metadata from ebur128 filter: +

+
ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
+
+ + +

30.75 drawgrid

+ +

Draw a grid on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. +

+
+
width, w
+
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 thickness, so image gets +framed. Default to 0. +

+
+
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 invert is used, the grid color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the grid line. Default value is 1. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With 1 the pixels of the painted grid +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the grid onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input grid cell width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y coordinates of some point of grid intersection (meant to configure offset). +

+
+
w
+
h
+

The width and height of the drawn cell. +

+
+
t
+

The thickness of the drawn cell. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

30.75.1 Examples

+ +
    +
  • Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: +
    +
    drawgrid=width=100:height=100:thickness=2:color=red@0.5
    +
    + +
  • Draw a white 3x3 grid with an opacity of 50%: +
    +
    drawgrid=w=iw/3:h=ih/3:t=2:c=white@0.5
    +
    +
+ + +

30.75.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.76 drawtext

+ +

Draw a text string or text from a specified file on top of a video, using the +libfreetype library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-libfreetype and --enable-libharfbuzz. +To enable default font fallback and the font option you need to +configure FFmpeg with --enable-libfontconfig. +To enable the text_shaping option, you need to configure FFmpeg with +--enable-libfribidi. +

+ +

30.76.1 Syntax

+ +

It accepts the following parameters: +

+
+
box
+

Used to draw a box around text using the background color. +The value must be either 1 (enable) or 0 (disable). +The default value of box is 0. +

+
+
boxborderw
+

Set the width of the border to be drawn around the box using boxcolor. +The value must be specified using one of the following formats: +

    +
  • boxborderw=10 set the width of all the borders to 10 +
  • boxborderw=10|20 set the width of the top and bottom borders to 10 + and the width of the left and right borders to 20 +
  • boxborderw=10|20|30 set the width of the top border to 10, the width + of the bottom border to 30 and the width of the left and right borders to 20 +
  • boxborderw=10|20|30|40 set the borders width to 10 (top), 20 (right), + 30 (bottom), 40 (left) +
+

The default value of boxborderw is "0". +

+
+
boxcolor
+

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. +

+

The default value of boxcolor is "white". +

+
+
line_spacing
+

Set the line spacing in pixels. The default value of line_spacing is 0. +

+
+
text_align
+

Set the vertical and horizontal alignment of the text with respect to the box boundaries. +The value is combination of flags, one for the vertical alignment (T=top, +M=middle, B=bottom) and one for the horizontal alignment (L=left, C=center, R=right). +Please note that tab characters are only supported with the left horizontal alignment. +

+
+
y_align
+

Specify what the y value is referred to. Possible values are: +

    +
  • text the top of the highest glyph of the first text line is placed at y +
  • baseline the baseline of the first text line is placed at y +
  • font the baseline of the first text line is placed at y plus the + ascent (in pixels) defined in the font metrics +
+

The default value of y_align is "text" for backward compatibility. +

+
+
borderw
+

Set the width of the border to be drawn around the text using bordercolor. +The default value of borderw is 0. +

+
+
bordercolor
+

Set the color to be used for drawing border around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. +

+

The default value of bordercolor is "black". +

+
+
expansion
+

Select how the text is expanded. Can be either none, +strftime (deprecated) or normal (default). See the +Text expansion section below for details. +

+
+
basetime
+

Set a start time for the count. Value is in microseconds. Only applied +in the deprecated strftime expansion mode. To emulate in normal expansion +mode use the pts function, supplying the start time (in seconds) +as the second argument. +

+
+
fix_bounds
+

If true, check and fix text coords to avoid clipping. +

+
+
fontcolor
+

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 fontcolor is "black". +

+
+
fontcolor_expr
+

String which is expanded the same way as text to obtain dynamic +fontcolor value. By default this option has empty value and is not +processed. When this option is set, it overrides fontcolor option. +

+
+
font
+

The font family to be used for drawing text. By default Sans. +

+
+
fontfile
+

The font file to be used for drawing text. The path must be included. +This parameter is mandatory if the fontconfig support is disabled. +

+
+
alpha
+

Draw the text applying alpha blending. The value can +be a number between 0.0 and 1.0. +The expression accepts the same variables x, y as well. +The default value is 1. +Please see fontcolor_expr. +

+
+
fontsize
+

The font size to be used for drawing text. +The default value of fontsize is 16. +

+
+
text_shaping
+

If set to 1, attempt to shape the text (for example, reverse the order of +right-to-left text and join Arabic characters) before drawing it. +Otherwise, just draw the text exactly as given. +By default 1 (if supported). +

+
+
ft_load_flags
+

The flags to be used for loading the fonts. +

+

The flags map the corresponding flags supported by libfreetype, and are +a combination of the following values: +

+
default
+
no_scale
+
no_hinting
+
render
+
no_bitmap
+
vertical_layout
+
force_autohint
+
crop_bitmap
+
pedantic
+
ignore_global_advance_width
+
no_recurse
+
ignore_transform
+
monochrome
+
linear_design
+
no_autohint
+
+ +

Default value is "default". +

+

For more information consult the documentation for the FT_LOAD_* +libfreetype flags. +

+
+
shadowcolor
+

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 shadowcolor is "black". +

+
+
boxw
+

Set the width of the box to be drawn around text. +The default value of boxw is computed automatically to match the text width +

+
+
boxh
+

Set the height of the box to be drawn around text. +The default value of boxh is computed automatically to match the text height +

+
+
shadowx
+
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. The default value for both is "0". +

+
+
start_number
+

The starting frame number for the n/frame_num variable. The default value +is "0". +

+
+
tabsize
+

The size in number of spaces to use for rendering the tab. +Default value is 4. +

+
+
timecode
+

Set the initial timecode representation in "hh:mm:ss[:;.]ff" +format. It can be used with or without text parameter. timecode_rate +option must be specified. +

+
+
timecode_rate, rate, r
+

Set the timecode frame rate (timecode only). Value will be rounded to nearest +integer. Minimum value is "1". +Drop-frame timecode is supported for frame rates 30 & 60. +

+
+
tc24hmax
+

If set to 1, the output of the timecode option will wrap around at 24 hours. +Default is 0 (disabled). +

+
+
text
+

The text string to be drawn. The text must be a sequence of UTF-8 +encoded characters. +This parameter is mandatory if no file is specified with the parameter +textfile. +

+
+
textfile
+

A text file containing text to be drawn. The text must be a sequence +of UTF-8 encoded characters. +

+

This parameter is mandatory if no text string is specified with the +parameter text. +

+

If both text and textfile are specified, an error is thrown. +

+
+
text_source
+

Text source should be set as side_data_detection_bboxes if you want to use text data in +detection bboxes of side data. +

+

If text source is set, text and textfile will be ignored and still use +text data in detection bboxes of side data. So please do not use this parameter +if you are not sure about the text source. +

+
+
reload
+

The textfile will be reloaded at specified frame interval. +Be sure to update textfile atomically, or it may be read partially, +or even fail. +Range is 0 to INT_MAX. Default is 0. +

+
+
x
+
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. +

+

The default value of x and y is "0". +

+

See below for the list of accepted constants and functions. +

+
+ +

The parameters for x and y are expressions containing the +following constants and functions: +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
line_h, lh
+

the height of each text line +

+
+
main_h, h, H
+

the input height +

+
+
main_w, w, W
+

the input width +

+
+
max_glyph_a, ascent
+

the maximum distance from the baseline to the highest/upper grid +coordinate used to place a glyph outline point, for all the rendered +glyphs. +It is a positive value, due to the grid’s orientation with the Y axis +upwards. +

+
+
max_glyph_d, descent
+

the maximum distance from the baseline to the lowest grid coordinate +used to place a glyph outline point, for all the rendered glyphs. +This is a negative value, due to the grid’s orientation, with the Y axis +upwards. +

+
+
max_glyph_h
+

maximum glyph height, that is the maximum height for all the glyphs +contained in the rendered text, it is equivalent to ascent - +descent. +

+
+
max_glyph_w
+

maximum glyph width, that is the maximum width for all the glyphs +contained in the rendered text +

+
+
font_a
+

the ascent size defined in the font metrics +

+
+
font_d
+

the descent size defined in the font metrics +

+
+
top_a
+

the maximum ascender of the glyphs of the first text line +

+
+
bottom_d
+

the maximum descender of the glyphs of the last text line +

+
+
n
+

the number of input frame, starting from 0 +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

The input sample aspect ratio. +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
text_h, th
+

the height of the rendered text +

+
+
text_w, tw
+

the width of the rendered text +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer +to each other, so you can for example specify y=x/dar. +

+
+
pict_type
+

A one character description of the current frame’s picture type. +

+
+
pkt_pos
+

The current packet’s position in the input file or stream +(in bytes, from the start of the input). A value of -1 indicates +this info is not available. +

+
+
duration
+

The current packet’s duration, in seconds. +

+
+
pkt_size
+

The current packet’s size (in bytes). +

+
+ + +

30.76.2 Text expansion

+ +

If expansion is set to strftime, the filter recognizes +sequences accepted by the strftime C function in the provided +text and expands them accordingly. Check the documentation of +strftime. This feature is deprecated in favor of normal +expansion with the gmtime or localtime expansion +functions. +

+

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
expr, e
+

The expression evaluation result. +

+

It must take one argument specifying the expression to be evaluated, +which accepts the same constants and functions as the x and +y values. Note that not all constants should be used, for +example the text size is not known when evaluating the expression, so +the constants text_w and text_h will have an undefined +value. +

+
+
expr_int_format, eif
+

Evaluate the expression’s value and output as formatted integer. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries +starting with TAG included within each frame section +printed by running ffprobe -show_frames. +

+

String metadata generated in filters leading to +the drawtext filter are also available. +

+
+
n, frame_num
+

The frame number, starting from 0. +

+
+
pict_type
+

A one character description of the current picture type. +

+
+
pts
+

The timestamp of the current frame. +It can take up to three arguments. +

+

The first argument is the format of the timestamp; it defaults to flt +for seconds as a decimal number with microsecond accuracy; hms stands +for a formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as +local time zone time. +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to hms, a third argument 24HH may be +supplied to present the hour part of the formatted timestamp in 24h format +(00-23). +

+

If the format is set to localtime or gmtime, a third +argument may be supplied: a strftime C function format string. +By default, YYYY-MM-DD HH:MM:SS format will be used. +

+
+ + +

30.76.3 Commands

+ +

This filter supports altering parameters via commands: +

+
reinit
+

Alter existing filter parameters. +

+

Syntax for the argument is the same as for filter invocation, e.g. +

+
+
fontsize=56:fontcolor=green:text='Hello World'
+
+ +

Full filter invocation with sendcmd would look like this: +

+
+
sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
+
+ +

If the entire argument can’t be parsed or applied as valid values then the filter will +continue with its existing parameters. +

+
+
+ +

The following options are also supported as commands: +

+
    +
  • x +
  • y +
  • alpha +
  • fontsize +
  • fontcolor +
  • boxcolor +
  • bordercolor +
  • shadowcolor +
  • box +
  • boxw +
  • boxh +
  • boxborderw +
  • line_spacing +
  • text_align +
  • shadowx +
  • shadowy +
  • borderw +
+ + +

30.76.4 Examples

+ +
    +
  • Draw "Test Text" with font FreeSerif, using the default values for the +optional parameters. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
    +
    + +
  • Draw ’Test Text’ with font FreeSerif of size 24 at position x=100 +and y=50 (counting from the top-left corner of the screen), text is +yellow with a red box around it. Both the text and the box have an +opacity of 20%. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
    +          x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"
    +
    + +

    Note that the double quotes are not necessary if spaces are not used +within the parameter list. +

    +
  • Show the text at the center of the video frame: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
    +
    + +
  • Show the text at a random position, switching to a new position every 30 seconds: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"
    +
    + +
  • Show a text line sliding from right to left in the last row of the video +frame. The file LONG_LINE is assumed to contain a single line +with no newlines. +
    +
    drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
    +
    + +
  • Show the content of file CREDITS off the bottom of the frame and scroll up. +
    +
    drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
    +
    + +
  • Draw a single green letter "g", at the center of the input video. +The glyph baseline is placed at half screen height. +
    +
    drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
    +
    + +
  • Show text for 1 second every 3 seconds: +
    +
    drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
    +
    + +
  • Use fontconfig to set the font. Note that the colons need to be escaped. +
    +
    drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg'
    +
    + +
  • Draw "Test Text" with font size dependent on height of the video. +
    +
    drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
    +
    + +
  • Print the date of a real-time encoding (see documentation for the +strftime C function): +
    +
    drawtext='fontfile=FreeSans.ttf:text=%{localtime\:%a %b %d %Y}'
    +
    + +
  • Show text fading in and out (appearing/disappearing): +
    +
    #!/bin/sh
    +DS=1.0 # display start
    +DE=10.0 # display end
    +FID=1.5 # fade in duration
    +FOD=5 # fade out duration
    +ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 }"
    +
    + +
  • Horizontally align multiple separate texts. Note that max_glyph_a +and the fontsize value are included in the y offset. +
    +
    drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
    +drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
    +
    + +
  • Plot special lavf.image2dec.source_basename metadata onto each frame if +such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer +must have option -export_path_metadata 1 for the special metadata fields +to be available for filters. +
    +
    drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%{metadata\:lavf.image2dec.source_basename\:NA}':x=10:y=10"
    +
    + +
+ +

For more information about libfreetype, check: +http://www.freetype.org/. +

+

For more information about fontconfig, check: +http://freedesktop.org/software/fontconfig/fontconfig-user.html. +

+

For more information about libfribidi, check: +http://fribidi.org/. +

+

For more information about libharfbuzz, check: +https://github.com/harfbuzz/harfbuzz. +

+ +

30.77 drawvg

+ +

Draw vector graphics on top of video frames, by executing a script written in +a custom language called VGS (Vector Graphics Script). +

+

The documentation for the language can be found in +drawvg - Language Reference. A version of this reference +with rendered examples can be found at the +author’s site. +

+

Graphics are rendered using the cario 2D +graphics library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-cairo. +

+ +

30.77.1 Parameters

+ +

Either script or file must be set. +

+
+
s, script
+

Script source to draw the graphics. +

+
+
file
+

Path of the file to load the script source. +

+
+
+ + +

30.77.2 Pixel Formats

+ +

Since Cairo only supports RGB images, if the input video is something else (like +YUV 4:2:0), before executing the script the video is converted to a format +compatible with Cairo. Then, you have to use either the format filter, +or the -pix_fmt option, to convert it to the expected format in the +output. +

+ +

30.77.3 Examples

+ +
    +
  • Draw the outline of an ellipse. + +
    +
    ffmpeg -i input.webm \
    +    -vf 'drawvg=ellipse (w/2) (h/2) (w/3) (h/3) stroke' \
    +    -pix_fmt yuv420p \
    +    output.webm
    +
    + +
  • +Draw a square rotating in the middle of the frame. + +

    The script for drawvg is in a file draw.vgs: +

    +
    +
    translate (w/2) (h/2)
    +rotate t
    +rect -100 -100 200 200
    +setcolor red@0.5
    +fill
    +
    + +

    Then: +

    +
    +
    ffmpeg -i input.webm -vf 'drawvg=file=draw.vgs,format=yuv420p' output.webm
    +
    + +
+ + +

30.78 edgedetect

+ +

Detect and draw edges. The filter uses the Canny Edge Detection algorithm. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
mode
+

Define the drawing mode. +

+
+
‘wires’
+

Draw white/gray wires on black background. +

+
+
‘colormix’
+

Mix the colors to create a paint/cartoon effect. +

+
+
‘canny’
+

Apply Canny edge detector on all selected planes. +

+
+

Default value is wires. +

+
+
planes
+

Select planes for filtering. By default all available planes are filtered. +

+
+ + +

30.78.1 Examples

+ +
    +
  • Standard edge detection with custom values for the hysteresis thresholding: +
    +
    edgedetect=low=0.1:high=0.4
    +
    + +
  • Painting effect without thresholding: +
    +
    edgedetect=mode=colormix:high=0
    +
    +
+ + +

30.79 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. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
pal8
+

Set pal8 output pixel format. This option does not work with codebook +length greater than 256. Default is disabled. +

+
+
use_alpha
+

Include alpha values in the quantization calculation. Allows creating +palettized output images (e.g. PNG8) with multiple alpha smooth blending. +

+
+ + +

30.80 entropy

+ +

Measure graylevel entropy in histogram of color channels of video frames. +

+

It accepts the following parameters: +

+
+
mode
+

Can be either normal or diff. Default is normal. +

+

diff mode measures entropy of histogram delta values, absolute differences +between neighbour histogram values. +

+
+ + +

30.81 epx

+

Apply the EPX magnification filter which is designed for pixel art. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xEPX, 3 for +3xEPX. +Default is 3. +

+
+ + +

30.82 eq

+

Set brightness, contrast, saturation and approximate gamma adjustment. +

+

The filter accepts the following options: +

+
+
contrast
+

Set the contrast expression. The value must be a float value in range +-1000.0 to 1000.0. The default value is "1". +

+
+
brightness
+

Set the brightness expression. The value must be a float value in +range -1.0 to 1.0. The default value is "0". +

+
+
saturation
+

Set the saturation expression. The value must be a float in +range 0.0 to 3.0. The default value is "1". +

+
+
gamma
+

Set the gamma expression. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_r
+

Set the gamma expression for red. The value must be a float in +range 0.1 to 10.0. The default value is "1". +

+
+
gamma_g
+

Set the gamma expression for green. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_b
+

Set the gamma expression for blue. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_weight
+

Set the gamma weight expression. It can be used to reduce the effect +of a high gamma value on bright image areas, e.g. keep them from +getting overamplified and just plain white. The value must be a float +in range 0.0 to 1.0. A value of 0.0 turns the +gamma correction all the way down while 1.0 leaves it at its +full strength. Default is "1". +

+
+
eval
+

Set when the expressions for brightness, contrast, saturation and +gamma expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ +

The expressions accept the following parameters: +

+
n
+

frame count of the input frame starting from 0 +

+
+
pos
+

byte position of the corresponding packet in the input file, NAN if +unspecified; deprecated, do not use +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+ + +

30.82.1 Commands

+

The filter supports the following commands: +

+
+
contrast
+

Set the contrast expression. +

+
+
brightness
+

Set the brightness expression. +

+
+
saturation
+

Set the saturation expression. +

+
+
gamma
+

Set the gamma expression. +

+
+
gamma_r
+

Set the gamma_r expression. +

+
+
gamma_g
+

Set gamma_g expression. +

+
+
gamma_b
+

Set gamma_b expression. +

+
+
gamma_weight
+

Set gamma_weight 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. +

+
+
+ + +

30.83 erosion

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

30.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.84 estdif

+ +

Deinterlace the input video ("estdif" stands for "Edge Slope +Tracing Deinterlacing Filter"). +

+

Spatial only filter that uses edge slope tracing algorithm +to interpolate missing lines. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
all
+

Deinterlace all frames. +

+
interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+
rslope
+

Specify the search radius for edge slope tracing. Default value is 1. +Allowed range is from 1 to 15. +

+
+
redge
+

Specify the search radius for best edge matching. Default value is 2. +Allowed range is from 0 to 15. +

+
+
ecost
+

Specify the edge cost for edge matching. Default value is 2. +Allowed range is from 0 to 50. +

+
+
mcost
+

Specify the middle cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
dcost
+

Specify the distance cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
interp
+

Specify the interpolation used. Default is 4-point interpolation. It accepts one +of the following values: +

+
+
2p
+

Two-point interpolation. +

+
4p
+

Four-point interpolation. +

+
6p
+

Six-point interpolation. +

+
+
+
+ + +

30.84.1 Commands

+

This filter supports same commands as options. +

+ +

30.85 exposure

+

Adjust exposure of the video stream. +

+

The filter accepts the following options: +

+
+
exposure
+

Set the exposure correction in EV. Allowed range is from -3.0 to 3.0 EV +Default value is 0 EV. +

+
+
black
+

Set the black level correction. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+ + +

30.85.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.86 extractplanes

+ +

Extract color channel components from input video stream into +separate grayscale video streams. +

+

The filter accepts the following option: +

+
+
planes
+

Set plane(s) to extract. +

+

Available values for planes are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +

Choosing planes not available in the input will result in an error. +That means you cannot select r, g, b planes +with y, u, v planes at same time. +

+
+ + +

30.86.1 Examples

+ +
    +
  • Extract luma, u and v color channel component from input video frame +into 3 grayscale outputs: +
    +
    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
    +
    +
+ + +

30.87 fade

+ +

Apply a fade-in/out effect to the input video. +

+

It accepts the following parameters: +

+
+
type, t
+

The effect type can be either "in" for a fade-in, or "out" for a fade-out +effect. +Default is in. +

+
+
start_frame, s
+

Specify the number of the frame to start applying the fade +effect at. Default is 0. +

+
+
nb_frames, n
+

The number of frames that the fade effect lasts. 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 color. +Default is 25. +

+
+
alpha
+

If set to 1, fade only alpha channel, if one exists on the input. +Default value is 0. +

+
+
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. +

+
+
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 color. +If both duration and nb_frames are specified, duration is used. Default is 0 +(nb_frames is used by default). +

+
+
color, c
+

Specify the color of the fade. Default is "black". +

+
+ + +

30.87.1 Examples

+ +
    +
  • Fade in the first 30 frames of video: +
    +
    fade=in:0:30
    +
    + +

    The command above is equivalent to: +

    +
    fade=t=in:s=0:n=30
    +
    + +
  • Fade out the last 45 frames of a 200-frame video: +
    +
    fade=out:155:45
    +fade=type=out:start_frame=155:nb_frames=45
    +
    + +
  • Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: +
    +
    fade=in:0:25, fade=out:975:25
    +
    + +
  • Make the first 5 frames yellow, then fade in from frame 5-24: +
    +
    fade=in:5:20:color=yellow
    +
    + +
  • Fade in alpha over first 25 frames of video: +
    +
    fade=in:0:25:alpha=1
    +
    + +
  • Make the first 5.5 seconds black, then fade in for 0.5 seconds: +
    +
    fade=t=in:st=5.5:d=0.5
    +
    + +
+ + +

30.88 feedback

+

Apply feedback video filter. +

+

This filter pass cropped input frames to 2nd output. +From there it can be filtered with other video filters. +After filter receives frame from 2nd input, that frame +is combined on top of original frame from 1st input and passed +to 1st output. +

+

The typical usage is filter only part of frame. +

+

The filter accepts the following options: +

+
x
+
y
+

Set the top left crop position. +

+
+
w
+
h
+

Set the crop size. +

+
+ + +

30.88.1 Examples

+ +
    +
  • Blur only top left rectangular part of video frame size 100x100 with gblur filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]gblur=8[blurin]
    +
    + +
  • Draw black box on top left part of video frame of size 100x100 with drawbox filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]drawbox=x=0:y=0:w=100:h=100:t=100[blurin]
    +
    + +
  • Pixelize rectangular part of video frame of size 100x100 with pixelize filter. +
    +
    [in][blurin]feedback=x=320:y=240:w=100:h=100[out][blurout];[blurout]pixelize[blurin]
    +
    +
+ + +

30.89 fftdnoiz

+

Denoise frames using 3D FFT (frequency domain filtering). +

+

The filter accepts the following options: +

+
+
sigma
+

Set the noise sigma constant. This sets denoising strength. +Default value is 1. Allowed range is from 0 to 30. +Using very high sigma with low overlap may give blocking artifacts. +

+
+
amount
+

Set amount of denoising. By default all detected noise is reduced. +Default value is 1. Allowed range is from 0 to 1. +

+
+
block
+

Set size of block in pixels, Default is 32, can be 8 to 256. +

+
+
overlap
+

Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. +

+
+
method
+

Set denoising method. Default is wiener, can also be hard. +

+
+
prev
+

Set number of previous frames to use for denoising. By default is set to 0. +

+
+
next
+

Set number of next frames to to use for denoising. By default is set to 0. +

+
+
planes
+

Set planes which will be filtered, by default are all available filtered +except alpha. +

+
+ + +

30.90 fftfilt

+

Apply arbitrary expressions to samples in frequency domain +

+
+
dc_Y
+

Adjust the dc value (gain) of the luma plane of the image. The filter +accepts an integer value in range 0 to 1000. The default +value is set to 0. +

+
+
dc_U
+

Adjust the dc value (gain) of the 1st chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
dc_V
+

Adjust the dc value (gain) of the 2nd chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
weight_Y
+

Set the frequency domain weight expression for the luma plane. +

+
+
weight_U
+

Set the frequency domain weight expression for the 1st chroma plane. +

+
+
weight_V
+

Set the frequency domain weight expression for the 2nd chroma plane. +

+
+
eval
+

Set when the expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

Only evaluate expressions once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+ +

Default value is ‘init’. +

+

The filter accepts the following variables: +

+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
N
+

The number of input frame, starting from 0. +

+
+
WS
+
HS
+

The size of FFT array for horizontal and vertical processing. +

+
+ + +

30.90.1 Examples

+ +
    +
  • High-pass: +
    +
    fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
    +
    + +
  • Low-pass: +
    +
    fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
    +
    + +
  • Sharpen: +
    +
    fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
    +
    + +
  • Blur: +
    +
    fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
    +
    + +
+ + +

30.91 field

+ +

Extract a single field from an interlaced image using stride +arithmetic to avoid wasting CPU time. The output frames are marked as +non-interlaced. +

+

The filter accepts the following options: +

+
+
type
+

Specify whether to extract the top (if the value is 0 or +top) or the bottom field (if the value is 1 or +bottom). +

+
+ + +

30.92 fieldhint

+ +

Create new frames by copying the top and bottom fields from surrounding frames +supplied as numbers by the hint file. +

+
+
hint
+

Set file containing hints: absolute/relative frame numbers. +

+

There must be one line for each frame in a clip. Each line must contain two +numbers separated by the comma, optionally followed by - or +. +Numbers supplied on each line of file can not be out of [N-1,N+1] where N +is current frame number for absolute mode or out of [-1, 1] range +for relative mode. First number tells from which frame to pick up top +field and second number tells from which frame to pick up bottom field. +

+

If optionally followed by + output frame will be marked as interlaced, +else if followed by - output frame will be marked as progressive, else +it will be marked same as input frame. +If optionally followed by t output frame will use only top field, or in +case of b it will use only bottom field. +If line starts with # or ; that line is skipped. +

+
+
mode
+

Can be item absolute or relative or pattern. Default is absolute. +The pattern mode is same as relative mode, except at last entry of file if there +are more frames to process than hint file is seek back to start. +

+
+ +

Example of first several lines of hint file for relative mode: +

+
0,0 - # first frame
+1,0 - # second frame, use third's frame top field and second's frame bottom field
+1,0 - # third frame, use fourth's frame top field and third's frame bottom field
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+
+ + +

30.93 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 fieldmatch needs to be +followed by a decimation filter such as 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, +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 yadif before decimation. +

+

In addition to the various configuration options, fieldmatch can take an +optional second stream, activated through the 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 fieldmatch is based on. While the semantic and usage are very +close, some behaviour and options names can differ. +

+

The decimate filter currently only works for constant frame rate input. +If your input has mixed telecined (30fps) and progressive content with a lower +framerate like 24fps use the following filterchain to produce the necessary cfr +stream: dejudder,fps=30000/1001,fieldmatch,decimate. +

+

The filter accepts the following options: +

+
+
order
+

Specify the assumed field order of the input stream. Available values are: +

+
+
‘auto’
+

Auto detect parity (use FFmpeg’s internal parity value). +

+
‘bff’
+

Assume bottom field first. +

+
‘tff’
+

Assume top field first. +

+
+ +

Note that it is sometimes recommended not to trust the parity announced by the +stream. +

+

Default value is auto. +

+
+
mode
+

Set the matching mode or strategy to use. 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, 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 pc and 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 p/c/n/u/b meaning section. +

+

Available values are: +

+
+
‘pc’
+

2-way matching (p/c) +

+
‘pc_n’
+

2-way matching, and trying 3rd match if still combed (p/c + n) +

+
‘pc_u’
+

2-way matching, and trying 3rd match (same order) if still combed (p/c + u) +

+
‘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) +

+
‘pcn’
+

3-way matching (p/c/n) +

+
‘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) +

+
+ +

The parenthesis at the end indicate the matches that would be used for that +mode assuming order=tff (and field on auto or +top). +

+

In terms of speed pc mode is by far the fastest and pcn_ub is +the slowest. +

+

Default value is pc_n. +

+
+
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 clip2 feature from +VFM/TFM. +

+

Default value is 0 (disabled). +

+
+
field
+

Set the field to match from. It is recommended to set this to the same value as +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: +

+
+
‘auto’
+

Automatic (same value as order). +

+
‘bottom’
+

Match from the bottom field. +

+
‘top’
+

Match from the top field. +

+
+ +

Default value is auto. +

+
+
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 0 +only if your clip has bad chroma problems such as heavy rainbowing or other +artifacts. Setting this to 0 could also be used to speed things up at +the cost of some accuracy. +

+

Default value is 1. +

+
+
y0
+
y1
+

These define an exclusion band which excludes the lines between y0 and +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. y0 sets the starting scan line and +y1 sets the ending line; all lines in between y0 and +y1 (including y0 and y1) will be ignored. Setting +y0 and y1 to the same value will disable the feature. +y0 and y1 defaults to 0. +

+
+
scthresh
+

Set the scene change detection threshold as a percentage of maximum change on +the luma plane. Good values are in the [8.0, 14.0] range. Scene change +detection is only relevant in case combmatch=sc. The range for +scthresh is [0.0, 100.0]. +

+

Default value is 12.0. +

+
+
combmatch
+

When combatch is not none, fieldmatch will take into +account the combed scores of matches when deciding what match to use as the +final match. Available values are: +

+
+
‘none’
+

No final matching based on combed scores. +

+
‘sc’
+

Combed scores are only used when a scene change is detected. +

+
‘full’
+

Use combed scores all the time. +

+
+ +

Default is sc. +

+
+
combdbg
+

Force fieldmatch to calculate the combed metrics for certain matches and +print them. This setting is known as micout in TFM/VFM vocabulary. +Available values are: +

+
+
‘none’
+

No forced calculation. +

+
‘pcn’
+

Force p/c/n calculations. +

+
‘pcnub’
+

Force p/c/n/u/b calculations. +

+
+ +

Default value is none. +

+
+
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 +-1 (every pixel will be detected as combed) to 255 (no pixel will +be detected as combed). This is basically a pixel difference value. A good +range is [8, 12]. +

+

Default value is 9. +

+
+
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 chroma=0 is usually more reliable, except for the case +where there is chroma only combing in the source. +

+

Default value is 0. +

+
+
blockx
+
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 +combpel pixels are required to be detected as combed for a frame to be +declared combed. See the 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 16. +

+
+
combpel
+

The number of combed pixels inside any of the blocky by +blockx size blocks on the frame for the frame to be detected as +combed. While 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 blockx and blocky settings) on the +frame. Minimum value is 0 and maximum is blocky x blockx (at +which point no frames will ever be detected as combed). This setting is known +as MI in TFM/VFM vocabulary. +

+

Default value is 80. +

+
+ + +

30.93.1 p/c/n/u/b meaning

+ + +

30.93.1.1 p/c/n

+ +

We assume the following telecined stream: +

+
+
Top fields:     1 2 2 3 4
+Bottom fields:  1 2 3 4 4
+
+ +

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 fieldmatch is configured to run a matching from bottom +(field=bottom) this is how this input stream get transformed: +

+
+
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
+
+ +

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 decimate filter. +

+

The same operation now matching from top fields (field=top) +looks like this: +

+
+
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
+
+ +

In these examples, we can see what p, c and n mean; +basically, they refer to the frame and field of the opposite parity: +

+
    +
  • p matches the field of the opposite parity in the previous frame +
  • c matches the field of the opposite parity in the current frame +
  • n matches the field of the opposite parity in the next frame +
+ + +

30.93.1.2 u/b

+ +

The u and 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 (field=bottom): +

+
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
+
+ +

With top matching (field=top): +

+
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
+
+ + +

30.93.2 Examples

+ +

Simple IVTC of a top field first telecined stream: +

+
fieldmatch=order=tff:combmatch=none, decimate
+
+ +

Advanced IVTC, with fallback on yadif for still combed frames: +

+
fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
+
+ + +

30.94 fieldorder

+ +

Transform the field order of the input video. +

+

It accepts the following parameters: +

+
+
order
+

The output field order. Valid values are tff for top field first or bff +for bottom field first. +

+
+ +

The default value is ‘tff’. +

+

The transformation is done by shifting the picture content up or down +by one line, and filling the remaining line with appropriate picture content. +This method is consistent with most broadcast field order converters. +

+

If the input video is not flagged as being interlaced, or it is already +flagged as being of the required output field order, then this filter does +not alter the incoming video. +

+

It is very useful when converting to or from PAL DV material, +which is bottom field first. +

+

For example: +

+
ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
+
+ + +

30.95 fillborders

+ +

Fill borders of the input video, without changing video stream dimensions. +Sometimes video can have garbage at the four edges and you may not want to +crop video input to keep size multiple of some number. +

+

This filter accepts the following options: +

+
+
left
+

Number of pixels to fill from left border. +

+
+
right
+

Number of pixels to fill from right border. +

+
+
top
+

Number of pixels to fill from top border. +

+
+
bottom
+

Number of pixels to fill from bottom border. +

+
+
mode
+

Set fill mode. +

+

It accepts the following values: +

+
‘smear’
+

fill pixels using outermost pixels +

+
+
‘mirror’
+

fill pixels using mirroring (half sample symmetric) +

+
+
‘fixed’
+

fill pixels with constant value +

+
+
‘reflect’
+

fill pixels using reflecting (whole sample symmetric) +

+
+
‘wrap’
+

fill pixels using wrapping +

+
+
‘fade’
+

fade pixels to constant value +

+
+
‘margins’
+

fill pixels at top and bottom with weighted averages pixels near borders +

+
+ +

Default is smear. +

+
+
color
+

Set color for pixels in fixed or fade mode. Default is black. +

+
+ + +

30.95.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.96 find_rect

+ +

Find a rectangular object in the input video. +

+

The object to search for must be specified as a gray8 image specified with the +object option. +

+

For each possible match, a score is computed. If the score reaches the specified +threshold, the object is considered found. +

+

If the input video contains multiple instances of the object, the filter will +find only one of them. +

+

When an object is found, the following metadata entries are set in the matching +frame: +

+
lavfi.rect.w
+

width of object +

+
+
lavfi.rect.h
+

height of object +

+
+
lavfi.rect.x
+

x position of object +

+
+
lavfi.rect.y
+

y position of object +

+
+
lavfi.rect.score
+

match score of the found object +

+
+ +

It accepts the following options: +

+
+
object
+

Filepath of the object image, needs to be in gray8. +

+
+
threshold
+

Detection threshold, expressed as a decimal number in the range 0-1. +

+

A threshold value of 0.01 means only exact matches, a threshold of 0.99 means +almost everything matches. +

+

Default value is 0.5. +

+
+
mipmaps
+

Number of mipmaps, default is 3. +

+
+
xmin, ymin, xmax, ymax
+

Specifies the rectangle in which to search. +

+
+
discard
+

Discard frames where object is not detected. Default is disabled. +

+
+ + +

30.96.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    + +
  • Find the position of an object in each frame using ffprobe and write +it to a log file: +
    +
    ffprobe -f lavfi movie=test.mp4,find_rect=object=object.pgm:threshold=0.3 \
    +  -show_entries frame=pkt_pts_time:frame_tags=lavfi.rect.x,lavfi.rect.y \
    +  -of csv -o find_rect.csv
    +
    + +
+ + +

30.97 floodfill

+ +

Flood area with values of same pixel components with another values. +

+

It accepts the following options: +

+
x
+

Set pixel x coordinate. +

+
+
y
+

Set pixel y coordinate. +

+
+
s0
+

Set source #0 component value. +

+
+
s1
+

Set source #1 component value. +

+
+
s2
+

Set source #2 component value. +

+
+
s3
+

Set source #3 component value. +

+
+
d0
+

Set destination #0 component value. +

+
+
d1
+

Set destination #1 component value. +

+
+
d2
+

Set destination #2 component value. +

+
+
d3
+

Set destination #3 component value. +

+
+ + +

30.98 format

+ +

Convert the input video to one of the specified pixel formats. +Libavfilter will try to pick one that is suitable as input to +the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +"pix_fmts=yuv420p|monow|rgb24". +

+
+
color_spaces
+

A ’|’-separated list of color space names, such as +"color_spaces=bt709|bt470bg|bt2020nc". +

+
+
color_ranges
+

A ’|’-separated list of color range names, such as +"color_ranges=tv|pc". +

+
+
alpha_modes
+

A ’|’-separated list of color range names, such as +"alpha_modes=straight|premultiplied". +

+
+
+ + +

30.98.1 Examples

+ +
    +
  • Convert the input video to the yuv420p format +
    +
    format=pix_fmts=yuv420p
    +
    + +

    Convert the input video to any of the formats in the list +

    +
    format=pix_fmts=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

30.99 fps

+ +

Convert the video to specified constant frame rate by duplicating or dropping +frames as necessary. +

+

It accepts the following parameters: +

+
fps
+

The desired output frame rate. It accepts expressions containing the following +constants: +

+
+
‘source_fps’
+

The input’s frame rate +

+
+
‘ntsc’
+

NTSC frame rate of 30000/1001 +

+
+
‘pal’
+

PAL frame rate of 25.0 +

+
+
‘film’
+

Film frame rate of 24.0 +

+
+
‘ntsc_film’
+

NTSC-film frame rate of 24000/1001 +

+
+ +

The default is 25. +

+
+
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. +

+
+
round
+

Timestamp (PTS) rounding method. +

+

Possible values are: +

+
zero
+

round towards 0 +

+
inf
+

round away from 0 +

+
down
+

round towards -infinity +

+
up
+

round towards +infinity +

+
near
+

round to nearest +

+
+

The default is near. +

+
+
eof_action
+

Action performed when reading the last frame. +

+

Possible values are: +

+
round
+

Use same timestamp rounding method as used for other frames. +

+
pass
+

Pass through last frame if input duration has not been reached yet. +

+
+

The default is round. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +fps[:start_time[:round]]. +

+

See also the setpts filter. +

+ +

30.99.1 Examples

+ +
    +
  • A typical usage in order to set the fps to 25: +
    +
    fps=fps=25
    +
    + +
  • Sets the fps to 24, using abbreviation and rounding method to round to nearest: +
    +
    fps=fps=film:round=near
    +
    +
+ + +

30.100 framepack

+ +

Pack two different video streams into a stereoscopic video, setting proper +metadata on supported codecs. The two views should have the same size and +framerate and processing will stop when the shorter video ends. Please note +that you may conveniently adjust view properties with the scale and +fps filters. +

+

It accepts the following parameters: +

+
format
+

The desired packing format. Supported values are: +

+
+
sbs
+

The views are next to each other (default). +

+
+
tab
+

The views are on top of each other. +

+
+
lines
+

The views are packed by line. +

+
+
columns
+

The views are packed by column. +

+
+
frameseq
+

The views are temporally interleaved. +

+
+
+ +
+
+ +

Some examples: +

+
+
# Convert left and right views into a frame-sequential video
+ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
+
+# Convert views into a side-by-side video with the same output resolution as the input
+ffmpeg -i LEFT -i RIGHT -filter_complex [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/2[right],[left][right]framepack=sbs OUTPUT
+
+ + +

30.101 framerate

+ +

Change the frame rate by interpolating new video output frames from the source +frames. +

+

This filter is not designed to function correctly with interlaced media. If +you wish to change the frame rate of interlaced media then you are required +to deinterlace before this filter and re-interlace after this filter. +

+

A description of the accepted options follows. +

+
+
fps
+

Specify the output frames per second. This option can also be specified +as a value alone. The default is 50. +

+
+
interp_start
+

Specify the start of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 15. +

+
+
interp_end
+

Specify the end of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 240. +

+
+
scene
+

Specify the level at which a scene change is detected as a value between +0 and 100 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one. +The default is 8.2. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
scene_change_detect, scd
+

Enable scene change detection using the value of the option scene. +This flag is enabled by default. +

+
+
+
+ + +

30.102 framestep

+ +

Select one frame every N-th frame. +

+

This filter accepts the following option: +

+
step
+

Select frame after every step frames. +Allowed values are positive integers higher than 0. Default value is 1. +

+
+ + +

30.103 freezedetect

+ +

Detect frozen video. +

+

This filter logs a message and sets frame metadata when it detects that the +input video has no significant change in content during a specified duration. +Video freeze detection calculates the mean average absolute difference of all +the components of video frames and compares it to a noise floor. +

+

The printed times and duration are expressed in seconds. The +lavfi.freezedetect.freeze_start metadata key is set on the first frame +whose timestamp equals or exceeds the detection duration and it contains the +timestamp of the first frame of the freeze. The +lavfi.freezedetect.freeze_duration and +lavfi.freezedetect.freeze_end metadata keys are set on the first frame +after the freeze. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or as a difference ratio between 0 and 1. Default is -60dB, or +0.001. +

+
+
duration, d
+

Set freeze duration until notification (default is 2 seconds). +

+
+ + +

30.104 freezeframes

+ +

Freeze video frames. +

+

This filter freezes video frames using frame from 2nd input. +

+

The filter accepts the following options: +

+
+
first
+

Set number of first frame from which to start freeze. +

+
+
last
+

Set number of last frame from which to end freeze. +

+
+
replace
+

Set number of frame from 2nd input which will be used instead of replaced frames. +

+
+ + +

30.105 frei0r

+ +

Apply a frei0r effect to the input video. +

+

To enable the compilation of this filter, you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the frei0r effect to load. If the environment variable +FREI0R_PATH is defined, the frei0r effect is searched for in each of the +directories specified by the colon-separated list in FREI0R_PATH. +Otherwise, the standard frei0r paths are searched, in this order: +HOME/.frei0r-1/lib/, /usr/local/lib/frei0r-1/, +/usr/lib/frei0r-1/. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r effect. +

+
+
+ +

A frei0r effect parameter can be a boolean (its value is either +"y" or "n"), a double, a color (specified as +R/G/B, where R, G, and B are floating point +numbers between 0.0 and 1.0, inclusive) or a color description as specified in the +"Color" section in the ffmpeg-utils manual, +a position (specified as X/Y, where +X and Y are floating point numbers) and/or a string. +

+

The number and types of parameters depend on the loaded effect. If an +effect parameter is not specified, the default value is set. +

+ +

30.105.1 Examples

+ +
    +
  • Apply the distort0r effect, setting the first two double parameters: +
    +
    frei0r=filter_name=distort0r:filter_params=0.5|0.01
    +
    + +
  • Apply the colordistance effect, taking a color as the first parameter: +
    +
    frei0r=colordistance:0.2/0.3/0.4
    +frei0r=colordistance:violet
    +frei0r=colordistance:0x112233
    +
    + +
  • Apply the perspective effect, specifying the top left and top right image +positions: +
    +
    frei0r=perspective:0.2/0.2|0.8/0.2
    +
    +
+ +

For more information, see +http://frei0r.dyne.org +

+ +

30.105.2 Commands

+ +

This filter supports the filter_params option as commands. +

+ +

30.106 fspp

+ +

Apply fast and simple postprocessing. It is a faster version of spp. +

+

It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- +processing filter, one of them is performed once per block, not per pixel. +This allows for much higher speed. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 4-5. Default value is 4. +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range 0-63. +If not set, the filter will use the QP from the video stream (if available). +

+
+
strength
+

Set filter strength. It accepts an integer in range -15 to 32. Lower values mean +more details but also more artifacts, while higher values make the image smoother +but also blurrier. Default value is 0 − PSNR optimal. +

+
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+
+ + +

30.107 fsync

+ +

Synchronize video frames with an external mapping from a file. +

+

For each input PTS given in the map file it either drops or creates as many +frames as necessary to recreate the sequence of output frames given in the +map file. +

+

This filter is useful to recreate the output frames of a framerate conversion +by the fps filter, recorded into a map file using the ffmpeg option +-stats_mux_pre, and do further processing to the corresponding frames +e.g. quality comparison. +

+

Each line of the map file must contain three items per input frame, the input +PTS (decimal), the output PTS (decimal) and the +output TIMEBASE (decimal/decimal), separated by a space. +This file format corresponds to the output +of -stats_mux_pre_fmt="{ptsi} {pts} {tb}". +

+

The filter assumes the map file is sorted by increasing input PTS. +

+

The filter accepts the following options: +

+
file, f
+

The filename of the map file to be used. +

+
+ +

Example: +

+
# Convert a video to 25 fps and record a MAP_FILE file with the default format of this filter
+ffmpeg -i INPUT -vf fps=fps=25 -stats_mux_pre MAP_FILE -stats_mux_pre_fmt "{ptsi} {pts} {tb}" OUTPUT
+
+# Sort MAP_FILE by increasing input PTS
+sort -n MAP_FILE
+
+# Use INPUT, OUTPUT and the MAP_FILE from above to compare the corresponding frames in INPUT and OUTPUT via SSIM
+ffmpeg -i INPUT -i OUTPUT -filter_complex '[0:v]fsync=file=MAP_FILE[ref];[1:v][ref]ssim' -f null -
+
+ + +

30.108 gblur

+ +

Apply Gaussian blur filter. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
steps
+

Set number of steps for Gaussian approximation. Default is 1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+ + +

30.108.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.109 geq

+ +

Apply generic equation to each pixel. +

+

The filter accepts the following options: +

+
+
lum_expr, lum
+

Set the luma expression. +

+
cb_expr, cb
+

Set the chrominance blue expression. +

+
cr_expr, cr
+

Set the chrominance red expression. +

+
alpha_expr, a
+

Set the alpha expression. +

+
red_expr, r
+

Set the red expression. +

+
green_expr, g
+

Set the green expression. +

+
blue_expr, b
+

Set the blue expression. +

+
+ +

The colorspace is selected according to the specified options. If one +of the lum_expr, cb_expr, or cr_expr +options is specified, the filter will automatically select a YCbCr +colorspace. If one of the red_expr, green_expr, or +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 +to the luma expression. +

+

The expressions can use the following variables and functions: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
SW
+
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 1,1 for the luma plane, and +0.5,0.5 for chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
p(x, y)
+

Return the value of the pixel at location (x,y) of the current +plane. +

+
+
lum(x, y)
+

Return the value of the pixel at location (x,y) of the luma +plane. +

+
+
cb(x, y)
+

Return the value of the pixel at location (x,y) of the +blue-difference chroma plane. Return 0 if there is no such plane. +

+
+
cr(x, y)
+

Return the value of the pixel at location (x,y) of the +red-difference chroma plane. Return 0 if there is no such plane. +

+
+
r(x, y)
+
g(x, y)
+
b(x, y)
+

Return the value of the pixel at location (x,y) of the +red/green/blue component. Return 0 if there is no such component. +

+
+
alpha(x, y)
+

Return the value of the pixel at location (x,y) of the alpha +plane. Return 0 if there is no such plane. +

+
+
psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
+

Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining +sums of samples within a rectangle. See the functions without the sum postfix. +

+
+
interpolation
+

Set one of interpolation methods: +

+
nearest, n
+
bilinear, b
+
+

Default is bilinear. +

+
+ +

For functions, if x and y are outside the area, the value will be +automatically clipped to the closer edge. +

+

Please note that this filter can use multiple threads in which case each slice +will have its own expression state. If you want to use only a single expression +state because your expressions depend on previous state then you should limit +the number of filter threads to 1. +

+ +

30.109.1 Examples

+ +
    +
  • Flip the image horizontally: +
    +
    geq=p(W-X\,Y)
    +
    + +
  • Generate a bidimensional sine wave, with angle PI/3 and a +wavelength of 100 pixels: +
    +
    geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
    +
    + +
  • Generate a fancy enigmatic moving light: +
    +
    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
    +
    + +
  • Generate a quick emboss effect: +
    +
    format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
    +
    + +
  • Modify RGB components depending on pixel position: +
    +
    geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
    +
    + +
  • Create a radial gradient that is the same size as the input (also see +the vignette filter): +
    +
    geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
    +
    +
+ + +

30.110 gradfun

+ +

Fix the banding artifacts that are sometimes introduced into nearly flat +regions by truncation to 8-bit color depth. +Interpolate the gradients that should go where the bands are, and +dither them. +

+

It 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. +

+

It accepts the following parameters: +

+
+
strength
+

The maximum amount by which the filter will change any one pixel. This is also +the threshold for detecting nearly flat regions. Acceptable values range from +.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the +valid range. +

+
+
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 8-32; the default value is 16. Out-of-range +values will be clipped to the valid range. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +strength[:radius] +

+ +

30.110.1 Examples

+ +
    +
  • Apply the filter with a 3.5 strength and radius of 8: +
    +
    gradfun=3.5:8
    +
    + +
  • Specify radius, omitting the strength (which will fall-back to the default +value): +
    +
    gradfun=radius=8
    +
    + +
+ + +

30.111 graphmonitor

+

Show various filtergraph stats. +

+

With this filter one can debug complete filtergraph. +Especially issues with links filling with queued frames. +

+

The filter accepts the following options: +

+
+
size, s
+

Set video output size. Default is hd720. +

+
+
opacity, o
+

Set video opacity. Default is 0.9. Allowed range is from 0 to 1. +

+
+
mode, m
+

Set output mode flags. +

+

Available values for flags are: +

+
‘full’
+

No any filtering. Default. +

+
‘compact’
+

Show only filters with queued frames. +

+
‘nozero’
+

Show only filters with non-zero stats. +

+
‘noeof’
+

Show only filters with non-eof stat. +

+
‘nodisabled’
+

Show only filters that are enabled in timeline. +

+
+ +
+
flags, f
+

Set flags which enable which stats are shown in video. +

+

Available values for flags are: +

+
‘none’
+

All flags turned off. +

+
+
‘all’
+

All flags turned on. +

+
+
‘queue’
+

Display number of queued frames in each link. +

+
+
‘frame_count_in’
+

Display number of frames taken from filter. +

+
+
‘frame_count_out’
+

Display number of frames given out from filter. +

+
+
‘frame_count_delta’
+

Display delta number of frames between above two values. +

+
+
‘pts’
+

Display current filtered frame pts. +

+
+
‘pts_delta’
+

Display pts delta between current and previous frame. +

+
+
‘time’
+

Display current filtered frame time. +

+
+
‘time_delta’
+

Display time delta between current and previous frame. +

+
+
‘timebase’
+

Display time base for filter link. +

+
+
‘format’
+

Display used format for filter link. +

+
+
‘size’
+

Display video size or number of audio channels in case of audio used by filter link. +

+
+
‘rate’
+

Display video frame rate or sample rate in case of audio used by filter link. +

+
+
‘eof’
+

Display link output status. +

+
+
‘sample_count_in’
+

Display number of samples taken from filter. +

+
+
‘sample_count_out’
+

Display number of samples given out from filter. +

+
+
‘sample_count_delta’
+

Display delta number of samples between above two values. +

+
+
‘disabled’
+

Show the timeline filter status. +

+
+ +
+
rate, r
+

Set upper limit for video rate of output stream, Default value is 25. +This guarantee that output video frame rate will not be higher than this value. +

+
+ + +

30.112 grayworld

+

A color constancy filter that applies color correction based on the grayworld assumption +

+

See: https://www.researchgate.net/publication/275213614_A_New_Color_Correction_Method_for_Underwater_Imaging +

+

The algorithm uses linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,grayworld,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

30.113 greyedge

+

A color constancy variation filter which estimates scene illumination via grey edge algorithm +and corrects the scene colors accordingly. +

+

See: https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf +

+

The filter accepts the following options: +

+
+
difford
+

The order of differentiation to be applied on the scene. Must be chosen in the range +[0,2] and default value is 1. +

+
+
minknorm
+

The Minkowski parameter to be used for calculating the Minkowski distance. Must +be chosen in the range [0,20] and default value is 1. Set to 0 for getting +max value instead of calculating Minkowski distance. +

+
+
sigma
+

The standard deviation of Gaussian blur to be applied on the scene. Must be +chosen in the range [0,1024.0] and default value = 1. floor( sigma * break_off_sigma(3) ) +can’t be equal to 0 if difford is greater than 0. +

+
+ + +

30.113.1 Examples

+
    +
  • Grey Edge: +
    +
    greyedge=difford=1:minknorm=5:sigma=2
    +
    + +
  • Max Edge: +
    +
    greyedge=difford=1:minknorm=0:sigma=2
    +
    + +
+ + +

30.114 guided

+

Apply guided filter for edge-preserving smoothing, dehazing and so on. +

+

The filter accepts the following options: +

+
radius
+

Set the box radius in pixels. +Allowed range is 1 to 20. Default is 3. +

+
+
eps
+

Set regularization parameter (with square). +Allowed range is 0 to 1. Default is 0.01. +

+
+
mode
+

Set filter mode. Can be basic or fast. +Default is basic. +

+
+
sub
+

Set subsampling ratio for fast mode. +Range is 2 to 64. Default is 4. +No subsampling occurs in basic mode. +

+
+
guidance
+

Set guidance mode. Can be off or on. Default is off. +If off, single input is required. +If on, two inputs of the same resolution and pixel format are required. +The second input serves as the guidance. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

30.114.1 Commands

+

This filter supports the all above options as commands. +

+ +

30.114.2 Examples

+
    +
  • Edge-preserving smoothing with guided filter: +
    +
    ffmpeg -i in.png -vf guided out.png
    +
    + +
  • Dehazing, structure-transferring filtering, detail enhancement with guided filter. +For the generation of guidance image, refer to paper "Guided Image Filtering". +See: http://kaiminghe.com/publications/pami12guidedfilter.pdf. +
    +
    ffmpeg -i in.png -i guidance.png -filter_complex guided=guidance=on out.png
    +
    + +
+ + +

30.115 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: +

+
+
clut
+

Set which CLUT video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+
shortest
+

Force termination when the shortest input terminates. Default is 0. +

+
repeatlast
+

Continue applying the last CLUT after the end of the stream. A value of +0 disable the filter after the last frame of the CLUT is reached. +Default is 1. +

+
+ +

haldclut also has the same interpolation options as lut3d (both +filters share the same internals). +

+

This filter also supports the framesync options. +

+

More information about the Hald CLUT can be found on Eskil Steenberg’s website +(Hald CLUT author) at http://www.quelsolaar.com/technology/clut.html. +

+ +

30.115.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

30.115.2 Workflow examples

+ + +

30.115.2.1 Hald CLUT video stream

+ +

Generate an identity Hald CLUT stream altered with various effects: +

+
ffmpeg -f lavfi -i haldclutsrc=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut
+
+ +

Note: make sure you use a lossless codec. +

+

Then use it with haldclut to apply it on some random stream: +

+
ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
+
+ +

The Hald CLUT will be applied to the 10 first seconds (duration of +clut.nut), then the latest picture of that CLUT stream will be applied +to the remaining frames of the mandelbrot stream. +

+ +

30.115.2.2 Hald CLUT with preview

+ +

A Hald CLUT is supposed to be a squared image of Level*Level*Level by +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 +haldclut filter: +

+
+
ffmpeg -f lavfi -i 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
+
+ +

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: +

+
ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
+
+ + +

30.116 hflip

+ +

Flip the input video horizontally. +

+

For example, to horizontally flip the input video with ffmpeg: +

+
ffmpeg -i in.avi -vf "hflip" out.avi
+
+ + +

30.117 histeq

+

This filter applies a global color histogram equalization on a +per-frame basis. +

+

It can be used to correct video that has a compressed range of pixel +intensities. The filter redistributes the pixel intensities to +equalize their distribution across the intensity range. It may be +viewed as an "automatically adjusting contrast filter". This filter is +useful only for correcting degraded or poorly captured source +video. +

+

The filter accepts the following options: +

+
+
strength
+

Determine the amount of equalization to be applied. As the strength +is reduced, the distribution of pixel intensities more-and-more +approaches that of the input frame. The value must be a float number +in the range [0,1] and defaults to 0.200. +

+
+
intensity
+

Set the maximum intensity that can generated and scale the output +values appropriately. The strength should be set as desired and then +the intensity can be limited if needed to avoid washing-out. The value +must be a float number in the range [0,1] and defaults to 0.210. +

+
+
antibanding
+

Set the antibanding level. If enabled the filter will randomly vary +the luminance of output pixels by a small amount to avoid banding of +the histogram. Possible values are none, weak or +strong. It defaults to none. +

+
+ + +

30.118 histogram

+ +

Compute and draw a color distribution histogram for the input video. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

Standard histogram displays the color components distribution in an image. +Displays color graph for each color component. Shows distribution of +the Y, U, V, A or R, G, B components, depending on input format, in the +current frame. Below each graph a color component scale meter is shown. +

+

The filter accepts the following options: +

+
+
level_height
+

Set height of level. Default value is 200. +Allowed range is [50, 2048]. +

+
+
scale_height
+

Set height of color scale. Default value is 12. +Allowed range is [0, 40]. +

+
+
display_mode
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components
+

Set what color components to display. +Default is 7. +

+
+
fgopacity
+

Set foreground opacity. Default is 0.7. +

+
+
bgopacity
+

Set background opacity. Default is 0.5. +

+
+
colors_mode
+

Set colors mode. +It accepts the following values: +

+
‘whiteonblack’
+
‘blackonwhite’
+
‘whiteongray’
+
‘blackongray’
+
‘coloronblack’
+
‘coloronwhite’
+
‘colorongray’
+
‘blackoncolor’
+
‘whiteoncolor’
+
‘grayoncolor’
+
+

Default is whiteonblack. +

+
+ + +

30.118.1 Examples

+ +
    +
  • Calculate and draw histogram: +
    +
    ffplay -i input -vf histogram
    +
    + +
+ + +

30.119 hqdn3d

+ +

This is a high precision/quality 3d denoise filter. It aims to reduce +image noise, producing smooth images and making still images really +still. It should enhance compressibility. +

+

It accepts the following optional parameters: +

+
+
luma_spatial
+

A non-negative floating point number which specifies spatial luma strength. +It defaults to 4.0. +

+
+
chroma_spatial
+

A non-negative floating point number which specifies spatial chroma strength. +It defaults to 3.0*luma_spatial/4.0. +

+
+
luma_tmp
+

A floating point number which specifies luma temporal strength. It defaults to +6.0*luma_spatial/4.0. +

+
+
chroma_tmp
+

A floating point number which specifies chroma temporal strength. It defaults to +luma_tmp*chroma_spatial/luma_spatial. +

+
+ + +

30.119.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.120 hwdownload

+ +

Download hardware frames to system memory. +

+

The input must be in hardware frames, and the output a non-hardware format. +Not all formats will be supported on the output - it may be necessary to insert +an additional format filter immediately following in the graph to get +the output in a supported format. +

+ +

30.121 hwmap

+ +

Map hardware frames to system memory or to another device. +

+

This filter has several different modes of operation; which one is used depends +on the input and output formats: +

    +
  • Hardware frame input, normal frame output + +

    Map the input frames to system memory and pass them to the output. If the +original hardware frame is later required (for example, after overlaying +something else on part of it), the hwmap filter can be used again +in the next mode to retrieve it. +

  • Normal frame input, hardware frame output + +

    If the input is actually a software-mapped hardware frame, then unmap it - +that is, return the original hardware frame. +

    +

    Otherwise, a device must be provided. Create new hardware surfaces on that +device for the output, then map them back to the software format at the input +and give those frames to the preceding filter. This will then act like the +hwupload filter, but may be able to avoid an additional copy when +the input is already in a compatible format. +

  • Hardware frame input and output + +

    A device must be supplied for the output, either directly or with the +derive_device option. The input and output devices must be of +different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

    +

    If the input frames were originally created on the output device, then unmap +to retrieve the original frames. +

    +

    Otherwise, map the frames to the output device - create new hardware frames +on the output corresponding to the frames on the input. +

+ +

The following additional parameters are accepted: +

+
+
mode
+

Set the frame mapping mode. Some combination of: +

+
read
+

The mapped frame should be readable. +

+
write
+

The mapped frame should be writeable. +

+
overwrite
+

The mapping will always overwrite the entire frame. +

+

This may improve performance in some cases, as the original contents of the +frame need not be loaded. +

+
direct
+

The mapping must not involve any copying. +

+

Indirect mappings to copies of frames are created in some cases where either +direct mapping is not possible or it would have unexpected properties. +Setting this flag ensures that the mapping is direct and will fail if that is +not possible. +

+
+

Defaults to read+write if not specified. +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+
reverse
+

In a hardware to hardware mapping, map in reverse - create frames in the sink +and map them back to the source. This may be necessary in some cases where +a mapping in one direction is required but only the opposite direction is +supported by the devices being used. +

+

This option is dangerous - it may break the preceding filter in undefined +ways if there are any additional constraints on that filter’s output. +Do not use it without fully understanding the implications of its use. +

+
+ + +

30.122 hwupload

+ +

Upload system memory frames to hardware surfaces. +

+

The device to upload to must be supplied when the filter is initialised. If +using ffmpeg, select the appropriate device with the -filter_hw_device +option or with the derive_device option. The input and output devices +must be of different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

+

The following additional parameters are accepted: +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+ + +

30.123 hwupload_cuda

+ +

Upload system memory frames to a CUDA device. +

+

It accepts the following optional parameters: +

+
+
device
+

The number of the CUDA device to use +

+
+ + +

30.124 hqx

+ +

Apply a high-quality magnification filter designed for pixel art. This filter +was originally created by Maxim Stepin. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for hq2x, 3 for +hq3x and 4 for hq4x. +Default is 3. +

+
+ + +

30.125 hstack

+

Stack input videos horizontally. +

+

All streams must be of same pixel format and of same height. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following option: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

30.126 hsvhold

+

Turns a certain HSV range into gray values. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to be gray or not. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully gray, or not gray at all. +

+

Higher values result in more gray pixels, with a higher gray pixel +the more similar the pixels color is to the key color. +

+
+ + +

30.127 hsvkey

+

Turns a certain HSV range into transparency. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to transparent by adding alpha channel. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

30.128 hue

+ +

Modify the hue and/or the saturation of the input. +

+

It accepts the following parameters: +

+
+
h
+

Specify the hue angle as a number of degrees. It accepts an expression, +and defaults to "0". +

+
+
s
+

Specify the saturation in the [-10,10] range. It accepts an expression and +defaults to "1". +

+
+
H
+

Specify the hue angle as a number of radians. It accepts an +expression, and defaults to "0". +

+
+
b
+

Specify the brightness in the [-10,10] range. It accepts an expression and +defaults to "0". +

+
+ +

h and H are mutually exclusive, and can’t be +specified at the same time. +

+

The b, h, H and s option values are +expressions containing the following constants: +

+
+
n
+

frame count of the input frame starting from 0 +

+
+
pts
+

presentation timestamp of the input frame expressed in time base units +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
tb
+

time base of the input video +

+
+ + +

30.128.1 Examples

+ +
    +
  • Set the hue to 90 degrees and the saturation to 1.0: +
    +
    hue=h=90:s=1
    +
    + +
  • Same command but expressing the hue in radians: +
    +
    hue=H=PI/2:s=1
    +
    + +
  • Rotate hue and make the saturation swing between 0 +and 2 over a period of 1 second: +
    +
    hue="H=2*PI*t: s=sin(2*PI*t)+1"
    +
    + +
  • Apply a 3 seconds saturation fade-in effect starting at 0: +
    +
    hue="s=min(t/3\,1)"
    +
    + +

    The general fade-in expression can be written as: +

    +
    hue="s=min(0\, max((t-START)/DURATION\, 1))"
    +
    + +
  • Apply a 3 seconds saturation fade-out effect starting at 5 seconds: +
    +
    hue="s=max(0\, min(1\, (8-t)/3))"
    +
    + +

    The general fade-out expression can be written as: +

    +
    hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
    +
    + +
+ + +

30.128.2 Commands

+ +

This filter supports the following commands: +

+
b
+
s
+
h
+
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 the specified expression is not valid, it is kept at its current +value. +

+
+ + +

30.129 huesaturation

+

Apply hue-saturation-intensity adjustments to input video stream. +

+

This filter operates in RGB colorspace. +

+

This filter accepts the following options: +

+
+
hue
+

Set the hue shift in degrees to apply. Default is 0. +Allowed range is from -180 to 180. +

+
+
saturation
+

Set the saturation shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
intensity
+

Set the intensity shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
colors
+

Set which primary and complementary colors are going to be adjusted. +This options is set by providing one or multiple values. +This can select multiple colors at once. By default all colors are selected. +

+
‘r’
+

Adjust reds. +

+
‘y’
+

Adjust yellows. +

+
‘g’
+

Adjust greens. +

+
‘c’
+

Adjust cyans. +

+
‘b’
+

Adjust blues. +

+
‘m’
+

Adjust magentas. +

+
‘a’
+

Adjust all colors. +

+
+ +
+
strength
+

Set strength of filtering. Allowed range is from 0 to 100. +Default value is 1. +

+
+
rw, gw, bw
+

Set weight for each RGB component. Allowed range is from 0 to 1. +By default is set to 0.333, 0.334, 0.333. +Those options are used in saturation and lightess processing. +

+
+
lightness
+

Set preserving lightness, by default is disabled. +Adjusting hues can change lightness from original RGB triplet, +with this option enabled lightness is kept at same value. +

+
+ + +

30.130 hysteresis

+ +

Grow first stream into second stream by connecting components. +This makes it possible to build more robust edge masks. +

+

This filter accepts the following options: +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+
threshold
+

Set threshold which is used in filtering. If pixel component value is higher than +this value filter algorithm for connecting components is activated. +By default value is 0. +

+
+ +

The hysteresis filter also supports the framesync options. +

+ +

30.131 iccdetect

+ +

Detect the colorspace from an embedded ICC profile (if present), and update +the frame’s tags accordingly. +

+

This filter accepts the following options: +

+
+
force
+

If true, the frame’s existing colorspace tags will always be overridden by +values detected from an ICC profile. Otherwise, they will only be assigned if +they contain unknown. Enabled by default. +

+
+ + +

30.132 iccgen

+ +

Generate ICC profiles and attach them to frames. +

+

This filter accepts the following options: +

+
+
color_primaries
+
color_trc
+

Configure the colorspace that the ICC profile will be generated for. The +default value of auto infers the value from the input frame’s metadata, +defaulting to BT.709/sRGB as appropriate. +

+

See the setparams filter for a list of possible values, but note that +unknown are not valid values for this filter. +

+
+
force
+

If true, an ICC profile will be generated even if it would overwrite an +already existing ICC profile. Disabled by default. +

+
+ + +

30.133 identity

+ +

Obtain the identity score between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max identity score is printed through +the logging system. +

+

The filter stores the calculated identity scores of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi identity -f null -
+
+ + +

30.134 idet

+ +

Detect video interlacing type. +

+

This filter tries to detect if the input frames are interlaced, progressive, +top or bottom field first. It will also try to detect fields that are +repeated between adjacent frames (a sign of telecine). +

+

Single frame detection considers only immediately adjacent frames when classifying each frame. +Multiple frame detection incorporates the classification history of previous frames. +

+

The filter will log these metadata values: +

+
+
single.current_frame
+

Detected type of current frame using single-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
single.tff
+

Cumulative number of frames detected as top field first using single-frame detection. +

+
+
multiple.tff
+

Cumulative number of frames detected as top field first using multiple-frame detection. +

+
+
single.bff
+

Cumulative number of frames detected as bottom field first using single-frame detection. +

+
+
multiple.current_frame
+

Detected type of current frame using multiple-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
multiple.bff
+

Cumulative number of frames detected as bottom field first using multiple-frame detection. +

+
+
single.progressive
+

Cumulative number of frames detected as progressive using single-frame detection. +

+
+
multiple.progressive
+

Cumulative number of frames detected as progressive using multiple-frame detection. +

+
+
single.undetermined
+

Cumulative number of frames that could not be classified using single-frame detection. +

+
+
multiple.undetermined
+

Cumulative number of frames that could not be classified using multiple-frame detection. +

+
+
repeated.current_frame
+

Which field in the current frame is repeated from the last. One of “neither”, “top”, or “bottom”. +

+
+
repeated.neither
+

Cumulative number of frames with no repeated field. +

+
+
repeated.top
+

Cumulative number of frames with the top field repeated from the previous frame’s top field. +

+
+
repeated.bottom
+

Cumulative number of frames with the bottom field repeated from the previous frame’s bottom field. +

+
+ +

The filter accepts the following options: +

+
+
intl_thres
+

Set interlacing threshold. +

+
prog_thres
+

Set progressive threshold. +

+
rep_thres
+

Threshold for repeated field detection. +

+
half_life
+

Number of frames after which a given frame’s contribution to the +statistics is halved (i.e., it contributes only 0.5 to its +classification). The default of 0 means that all frames seen are given +full weight of 1.0 forever. +

+
analyze_interlaced_flag
+

When this is not 0 then idet will use the specified number of frames to determine +if the interlaced flag is accurate, it will not count undetermined frames. +If the flag is found to be accurate it will be used without any further +computations, if it is found to be inaccurate it will be cleared without any +further computations. This allows inserting the idet filter as a low computational +method to clean up the interlaced flag +

+
+ + +

30.134.1 Examples

+ +

Inspect the field order of the first 360 frames in a video, in verbose detail: +

+
ffmpeg -i INPUT -filter:v idet,metadata=mode=print -frames:v 360 -an -f null -
+
+

The idet filter will add analysis metadata to each frame, which will then be +discarded. At the end, the filter will also print a final report with statistics. +

+ +

30.135 il

+ +

Deinterleave or interleave fields. +

+

This filter allows one to process interlaced images fields without +deinterlacing them. Deinterleaving splits the input frame into 2 +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. +

+

The filter accepts the following options: +

+
+
luma_mode, l
+
chroma_mode, c
+
alpha_mode, a
+

Available values for luma_mode, chroma_mode and +alpha_mode are: +

+
+
‘none’
+

Do nothing. +

+
+
‘deinterleave, d’
+

Deinterleave fields, placing one above the other. +

+
+
‘interleave, i’
+

Interleave fields. Reverse the effect of deinterleaving. +

+
+

Default value is none. +

+
+
luma_swap, ls
+
chroma_swap, cs
+
alpha_swap, as
+

Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is 0. +

+
+ + +

30.135.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.136 inflate

+ +

Apply inflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values higher than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

30.136.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.137 interlace, interlace_vulkan

+ +

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. +

+
+
   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
+
+ +

It accepts the following optional parameters: +

+
+
scan
+

This determines whether the interlaced frame is taken from the even +(tff - default) or odd (bff) lines of the progressive frame. +

+
+
lowpass
+

Vertical lowpass filter to avoid twitter interlacing and +reduce moire patterns. +

+
+
‘0, off’
+

Disable vertical lowpass filter +

+
+
‘1, linear’
+

Enable linear filter (default) +

+
+
‘2, complex’
+

Enable complex filter. This will slightly less reduce twitter and moire +but better retain detail and subjective sharpness impression. +

+
+
+
+
+ + +

30.138 kerndeint

+ +

Deinterlace input video by applying Donald Graft’s adaptive kernel +deinterling. Work on interlaced parts of a video to produce +progressive frames. +

+

The description of the accepted parameters follows. +

+
+
thresh
+

Set the threshold which affects the filter’s tolerance when +determining if a pixel line must be processed. It must be an integer +in the range [0,255] and defaults to 10. A value of 0 will result in +applying the process on every pixels. +

+
+
map
+

Paint pixels exceeding the threshold value to white if set to 1. +Default is 0. +

+
+
order
+

Set the fields order. Swap fields if set to 1, leave fields alone if +0. Default is 0. +

+
+
sharp
+

Enable additional sharpening if set to 1. Default is 0. +

+
+
twoway
+

Enable twoway sharpening if set to 1. Default is 0. +

+
+ + +

30.138.1 Examples

+ +
    +
  • Apply default values: +
    +
    kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
    +
    + +
  • Enable additional sharpening: +
    +
    kerndeint=sharp=1
    +
    + +
  • Paint processed pixels in white: +
    +
    kerndeint=map=1
    +
    +
+ + +

30.139 kirsch

+

Apply kirsch operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

30.139.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.140 lagfun

+ +

Slowly update darker pixels. +

+

This filter makes short flashes of light appear longer. +This filter accepts the following options: +

+
+
decay
+

Set factor for decaying. Default is .95. Allowed range is from 0 to 1. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

30.140.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.141 lenscorrection

+ +

Correct radial lens distortion +

+

This filter can be used to correct for radial distortion as can result from the use +of wide angle lenses, and thereby re-rectify the image. To find the right parameters +one can use tools available for example as part of opencv or simply trial-and-error. +To use opencv use the calibration sample (under samples/cpp) from the opencv sources +and extract the k1 and k2 coefficients from the resulting matrix. +

+

Note that effectively the same filter is available in the open-source tools Krita and +Digikam from the KDE project. +

+

In contrast to the vignette filter, which can also be used to compensate lens errors, +this filter corrects the distortion of the image, whereas vignette corrects the +brightness distribution, so you may want to use both filters together in certain +cases, though you will have to take care of ordering, i.e. whether vignetting should +be applied before or after lens correction. +

+ +

30.141.1 Options

+ +

The filter accepts the following options: +

+
+
cx
+

Relative x-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +width. Default is 0.5. +

+
cy
+

Relative y-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +height. Default is 0.5. +

+
k1
+

Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means +no correction. Default is 0. +

+
k2
+

Coefficient of the double quadratic correction term. This value has a range [-1,1]. +0 means no correction. Default is 0. +

+
i
+

Set interpolation type. Can be nearest or bilinear. +Default is nearest. +

+
fc
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black@0. +

+
+ +

The formula that generates the correction is: +

+

r_src = r_tgt * (1 + k1 * (r_tgt / r_0)^2 + k2 * (r_tgt / r_0)^4) +

+

where r_0 is halve of the image diagonal and r_src and r_tgt are the +distances from the focal point in the source and target images, respectively. +

+ +

30.141.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.142 lensfun

+ +

Apply lens correction via the lensfun library (http://lensfun.sourceforge.net/). +

+

The lensfun filter requires the camera make, camera model, and lens model +to apply the lens correction. The filter will load the lensfun database and +query it to find the corresponding camera and lens entries in the database. As +long as these entries can be found with the given options, the filter can +perform corrections on frames. Note that incomplete strings will result in the +filter choosing the best match with the given options, and the filter will +output the chosen camera and lens models (logged with level "info"). You must +provide the make, camera model, and lens model as they are required. +

+

To obtain a list of available makes and models, leave out one or both of make and +model options. The filter will send the full list to the log with level INFO. +The first column is the make and the second column is the model. +To obtain a list of available lenses, set any values for make and model and leave out the +lens_model option. The filter will send the full list of lenses in the log with level +INFO. The ffmpeg tool will exit after the list is printed. +

+

The filter accepts the following options: +

+
+
make
+

The make of the camera (for example, "Canon"). This option is required. +

+
+
model
+

The model of the camera (for example, "Canon EOS 100D"). This option is +required. +

+
+
lens_model
+

The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This +option is required. +

+
+
db_path
+

The full path to the lens database folder. If not set, the filter will attempt to +load the database from the install path when the library was built. Default is unset. +

+
+
mode
+

The type of correction to apply. The following values are valid options: +

+
+
‘vignetting’
+

Enables fixing lens vignetting. +

+
+
‘geometry’
+

Enables fixing lens geometry. This is the default. +

+
+
‘subpixel’
+

Enables fixing chromatic aberrations. +

+
+
‘vig_geo’
+

Enables fixing lens vignetting and lens geometry. +

+
+
‘vig_subpixel’
+

Enables fixing lens vignetting and chromatic aberrations. +

+
+
‘distortion’
+

Enables fixing both lens geometry and chromatic aberrations. +

+
+
‘all’
+

Enables all possible corrections. +

+
+
+
+
focal_length
+

The focal length of the image/video (zoom; expected constant for video). For +example, a 18–55mm lens has focal length range of [18–55], so a value in that +range should be chosen when using that lens. Default 18. +

+
+
aperture
+

The aperture of the image/video (expected constant for video). Note that +aperture is only used for vignetting correction. Default 3.5. +

+
+
focus_distance
+

The focus distance of the image/video (expected constant for video). Note that +focus distance is only used for vignetting and only slightly affects the +vignetting correction process. If unknown, leave it at the default value (which +is 1000). +

+
+
scale
+

The scale factor which is applied after transformation. After correction the +video is no longer necessarily rectangular. This parameter controls how much of +the resulting image is visible. The value 0 means that a value will be chosen +automatically such that there is little or no unmapped area in the output +image. 1.0 means that no additional scaling is done. Lower values may result +in more of the corrected image being visible, while higher values may avoid +unmapped areas in the output. +

+
+
target_geometry
+

The target geometry of the output image/video. The following values are valid +options: +

+
+
‘rectilinear (default)’
+
‘fisheye’
+
‘panoramic’
+
‘equirectangular’
+
‘fisheye_orthographic’
+
‘fisheye_stereographic’
+
‘fisheye_equisolid’
+
‘fisheye_thoby’
+
+
+
reverse
+

Apply the reverse of image correction (instead of correcting distortion, apply +it). +

+
+
interpolation
+

The type of interpolation used when correcting distortion. The following values +are valid options: +

+
+
‘nearest’
+
‘linear (default)’
+
‘lanczos’
+
+
+
+ + +

30.142.1 Examples

+ +
    +
  • Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens +model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and +aperture of "8.0". + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
    +
    + +
  • Apply the same as before, but only for the first 5 seconds of video. + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov
    +
    + +
+ + +

30.143 lcevc

+ +

Low Complexity Enhancement Video Codec filter based on liblcevc_dec +(https://github.com/v-novaltd/LCEVCdec). +

+ +

30.144 libplacebo

+ +

Flexible GPU-accelerated processing filter based on libplacebo +(https://code.videolan.org/videolan/libplacebo). +

+ +

30.144.1 Options

+ +

The options for this filter are divided into the following sections: +

+ +

30.144.1.1 Output mode

+

These options control the overall output mode. By default, libplacebo will try +to preserve the source colorimetry and size as best as it can, but it will +apply any embedded film grain, dolby vision metadata or anamorphic SAR present +in source frames. +

+
inputs
+

Set the number of inputs. This can be used, alongside the idx variable, +to allow placing/blending multiple inputs inside the output frame. This +effectively enables functionality similar to hstack, overlay, etc. +

+
+
w
+
h
+

Set the output video dimension expression. Default values are iw and +ih. +

+

Allows for the same expressions as the scale filter. +

+
+
crop_x
+
crop_y
+

Set the input crop x/y expressions, default values are (iw-cw)/2 and +(ih-ch)/2. +

+
+
crop_w
+
crop_h
+

Set the input crop width/height expressions, default values are iw and +ih. +

+
+
pos_x
+
pos_y
+

Set the output placement x/y expressions, default values are (ow-pw)/2 +and (oh-ph)/2. +

+
+
pos_w
+
pos_h
+

Set the output placement width/height expressions, default values are ow +and oh. +

+
+
rotate
+

Rotate the input frame clockwise by the specified angle. +

+
+
‘0, 360’
+
‘90’
+
‘180’
+
‘270’
+
+ +
+
fps
+

Set the output frame rate. This can be rational, e.g. 60000/1001. If +set to the special string none (the default), input timestamps will +instead be passed through to the output unmodified. Otherwise, the input video +frames will be interpolated as necessary to rescale the video to the specified +target framerate, in a manner as determined by the frame_mixer option. +

+
+
format
+

Set the output format override. If unset (the default), frames will be output +in the same format as the respective input frames. Otherwise, format conversion +will be performed. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. Note that +force_divisible_by also works with fit_sense=constraint. +

+
+
reset_sar
+

If enabled, output frames will always have a pixel aspect ratio of 1:1. If +disabled (the default), any aspect ratio mismatches, including those from +e.g. anamorphic video sources, are forwarded to the output pixel aspect ratio. +

+
+
normalize_sar
+

Like reset_sar, but instead of stretching the video content to fill +the new output aspect ratio, the content is instead padded or cropped as +necessary. Mutually exclusive with fit_mode. Disabled by default. +

+
+
pad_crop_ratio
+

Specifies a ratio (between 0.0 and 1.0) between padding and +cropping when the input aspect ratio does not match the output aspect ratio and +normalize_sar is in effect. The default of 0.0 always pads the +content with black borders, while a value of 1.0 always crops off parts +of the content. Intermediate values are possible, leading to a mix of the two +approaches. +

+
+
fit_mode
+

Specify the content fit strategy according to a list of predefined modes. +Determines how the input image is to be placed inside the destination crop +rectangle (as defined by pos_x/y and pos_w/h). The names and +their implementations are taken from the CSS ’object-fit’ property. Note that +this option is mutually exclusive with normalize_sar. Defaults to +fill. Valid values are: +

+
+
‘fill’
+

Stretch the input to the output rectangle, ignoring aspect ratio mismatches. +Note that unless reset_sar is also enabled, the output will still +have the correct pixel aspect ratio tagged. +

+
+
‘contain’
+

Scale the input to fit inside the output, preserving aspect ratio by padding. +Equivalent to normalize_sar with pad_crop_ratio set to +0.0. +

+
+
‘cover’
+

Scale the input to fill the output, preserving aspect ratio by cropping. +Equivalent to normalize_sar with pad_crop_ratio set to +1.0. +

+
+
‘none, place’
+

Don’t scale the input. The input will be placed inside the output rectangle at +its natural size; which may result in additional padding or cropping. +

+
+
‘scale_down’
+

Scale the input down as much as needed to fit inside the output. Equivalent +to either contain or none, depending on whether the input is +larger than the output or not. +

+
+ +
+
fit_sense
+

When fit_mode is in use, this option controls how the fit strategy +is applied against the specified output resolution. Mutually exclusive with +force_original_aspect_ratio. Valid values are: +

+
+
‘target’
+

The computed output resolution is taken as the exact size of the output frame. +This is the default behavior. +

+
+
‘constraint’
+

The computed output resolution is a size reference against which the fit mode +is applied, enlarging or decreasing the true frame size as needed to fit the +content. +

+
+ +
+
fillcolor
+

Set the color used to fill the output area not covered by the output image, for +example as a result of normalize_sar. For the general syntax of this +option, check the "Color" section in the ffmpeg-utils +manual. Defaults to black@0. +

+
+
corner_rounding
+

Render frames with rounded corners. The value, given as a float ranging from +0.0 to 1.0, indicates the relative degree of rounding, from fully +square to fully circular. In other words, it gives the radius divided by half +the smaller side length. Defaults to 0.0. +

+
+
lut
+

Specifies a custom LUT (in Adobe .cube format) to apply to the colors +as part of color conversion. The exact interpretation depends on the value +of lut_type. +

+
+
lut_type
+

Controls the interpretation of color values fed to and from the LUT +specified as lut. Valid values are: +

+
+
‘auto’
+

Chooses the interpretation of the LUT automatically from tagged +metadata, and otherwise falls back to ‘native’. (Default) +

+
+
‘native’
+

Applied to raw image contents in its native RGB colorspace (non-linear +light), before conversion to the output color space. +

+
+
‘normalized’
+

Applied to the normalized RGB image contents, in linear light, before +conversion to the output color space. +

+
+
‘conversion’
+

Fully replaces the conversion from the image color space to the output +color space. If such a LUT is present, it has the highest priority, and +overrides any ICC profiles, as well as options related to tone mapping +and output colorimetry (color_primaries, color_trc). +

+
+
+ +
+
extra_opts
+

Pass extra libplacebo internal configuration options. These can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to configure a custom filter kernel ("EWA LanczosSharp") and use it +to double the input image resolution: +

+
+
-vf "libplacebo=w=iw*2:h=ih*2:extra_opts='upscaler=custom\:upscaler_preset=ewa_lanczos\:upscaler_blur=0.9812505644269356'"
+
+ + +
+
shader_cache
+

File path of a cache directory that libplacebo will use to store and load +cached shader objects. This cache is not cleaned up automatically. If the +path does not end in a directory separator, the generated filenames will be +effectively prefixed by the last path component. All directories must already +exist. +

+
+
-vf "libplacebo=shader_cache=/tmp/pl-shader-"
+
+ +
+
colorspace
+
color_primaries
+
color_trc
+
range
+
chroma_location
+

Configure the colorspace that output frames will be delivered in. The default +value of auto outputs frames in the same format as the input frames, +leading to no change. For any other value, conversion will be performed. +

+

See the setparams filter for a list of possible values. +

+
+
alpha_mode
+

Choose the desired output alpha mode, when the output format has an alpha +channel. See the setparams filter for a list of possible values. +

+
+
apply_filmgrain
+

Apply film grain (e.g. AV1 or H.274) if present in source frames, and strip +it from the output. Enabled by default. +

+
+
apply_dolbyvision
+

Apply Dolby Vision RPU metadata if present in source frames, and strip it from +the output. Enabled by default. Note that Dolby Vision will always output +BT.2020+PQ, overriding the usual input frame metadata. These will also be +picked as the values of auto for the respective frame output options. +

+
+ +

In addition to the expression constants documented for the scale filter, +the crop_w, crop_h, crop_x, crop_y, +pos_w, pos_h, pos_x and pos_y options can +also contain the following constants: +

+
+
in_idx, idx
+

The (0-based) numeric index of the currently active input stream. +

+
crop_w, cw
+
crop_h, ch
+

The computed values of crop_w and crop_h. +

+
+
pos_w, pw
+
pos_h, ph
+

The computed values of pos_w and pos_h. +

+
+
in_t, t
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
out_t, ot
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
n
+

The input frame number, starting with 0. +

+
+ + +

30.144.1.2 Scaling

+

The options in this section control how libplacebo performs upscaling and (if +necessary) downscaling. Note that libplacebo will always internally operate on +4:4:4 content, so any sub-sampled chroma formats such as yuv420p will +necessarily be upsampled and downsampled as part of the rendering process. That +means scaling might be in effect even if the source and destination resolution +are the same. +

+
upscaler
+
downscaler
+

Configure the filter kernel used for upscaling and downscaling. The respective +defaults are spline36 and mitchell. For a full list of possible +values, pass help to these options. The most important values are: +

+
‘none’
+

Forces the use of built-in GPU texture sampling (typically bilinear). Extremely +fast but poor quality, especially when downscaling. +

+
+
‘bilinear’
+

Bilinear interpolation. Can generally be done for free on GPUs, except when +doing so would lead to aliasing. Fast and low quality. +

+
+
‘nearest’
+

Nearest-neighbour interpolation. Sharp but highly aliasing. +

+
+
‘oversample’
+

Algorithm that looks visually similar to nearest-neighbour interpolation but +tries to preserve pixel aspect ratio. Good for pixel art, since it results in +minimal distortion of the artistic appearance. +

+
+
‘lanczos’
+

Standard sinc-sinc interpolation kernel. +

+
+
‘spline36’
+

Cubic spline approximation of lanczos. No difference in performance, but has +very slightly less ringing. +

+
+
‘ewa_lanczos’
+

Elliptically weighted average version of lanczos, based on a jinc-jinc kernel. +This is also popularly referred to as just "Jinc scaling". Slow but very high +quality. +

+
+
‘gaussian’
+

Gaussian kernel. Has certain ideal mathematical properties, but subjectively +very blurry. +

+
+
‘mitchell’
+

Cubic BC spline with parameters recommended by Mitchell and Netravali. Very +little ringing. +

+
+ +
+
frame_mixer
+

Controls the kernel used for mixing frames temporally. The default value is +none, which disables frame mixing. For a full list of possible values, +pass help to this option. The most important values are: +

+
‘none’
+

Disables frame mixing, giving a result equivalent to "nearest neighbour" +semantics. +

+
+
‘oversample’
+

Oversamples the input video to create a "Smooth Motion"-type effect: if an +output frame would exactly fall on the transition between two video frames, it +is blended according to the relative overlap. This is the recommended option +whenever preserving the original subjective appearance is desired. +

+
+
‘mitchell_clamp’
+

Larger filter kernel that smoothly interpolates multiple frames in a manner +designed to eliminate ringing and other artefacts as much as possible. This is +the recommended option wherever maximum visual smoothness is desired. +

+
+
‘linear’
+

Linear blend/fade between frames. Especially useful for constructing e.g. +slideshows. +

+
+ +
+
antiringing
+

Enables anti-ringing (for non-EWA filters). The value (between 0.0 and +1.0) configures the strength of the anti-ringing algorithm. May increase +aliasing if set too high. Disabled by default. +

+
+
sigmoid
+

Enable sigmoidal compression during upscaling. Reduces ringing slightly. +Enabled by default. +

+
+ + +

30.144.1.3 Deinterlacing

+

Deinterlacing is automatically supported when frames are tagged as interlaced, +however frames are not deinterlaced unless a deinterlacing algorithm is chosen. +

+
deinterlace
+

The the deinterlacing algorithm to use. +

+
‘weave’
+

No deinterlacing, weave fields together into a single frame. This is the default. +

+
‘bob’
+

Naive bob deinterlacing, simply repeat each field line twice. +

+
‘yadif’
+

Yet another deinterlacing filter. See the yadif filter for more details. +

+
‘bwdif’
+

Bob weaver deinterlacing filter. See the bwdif filter for more details. +

+
+ +
+
skip_spatial_check
+

Skip the spatial deinterlacing check when using yadif deinterlacing. +

+
+
send_fields
+

Output a frame for each field, rather than for each frame. Note that this will +always double the tagged output frame rate, even if the input does not contain +any interlaced frames. Disabled by default. +

+
+ + +

30.144.1.4 Debanding

+

Libplacebo comes with a built-in debanding filter that is good at counteracting +many common sources of banding and blocking. Turning this on is highly +recommended whenever quality is desired. +

+
deband
+

Enable (fast) debanding algorithm. Disabled by default. +

+
+
deband_iterations
+

Number of deband iterations of the debanding algorithm. Each iteration is +performed with progressively increased radius (and diminished threshold). +Recommended values are in the range 1 to 4. Defaults to 1. +

+
+
deband_threshold
+

Debanding filter strength. Higher numbers lead to more aggressive debanding. +Defaults to 4.0. +

+
+
deband_radius
+

Debanding filter radius. A higher radius is better for slow gradients, while +a lower radius is better for steep gradients. Defaults to 16.0. +

+
+
deband_grain
+

Amount of extra output grain to add. Helps hide imperfections. Defaults to +6.0. +

+
+ + +

30.144.1.5 Color adjustment

+

A collection of subjective color controls. Not very rigorous, so the exact +effect will vary somewhat depending on the input primaries and colorspace. +

+
brightness
+

Brightness boost, between -1.0 and 1.0. Defaults to 0.0. +

+
+
contrast
+

Contrast gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
saturation
+

Saturation gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
hue
+

Hue shift in radians, between -3.14 and 3.14. Defaults to +0.0. This will rotate the UV subvector, defaulting to BT.709 +coefficients for RGB inputs. +

+
+
gamma
+

Gamma adjustment, between 0.0 and 16.0. Defaults to 1.0. +

+
+
temperature
+

Color temperature adjustment. Lower values make the output warmer/redder, +down to 1667, while higher values make the output cooler/bluer, up to +25000. Defaults to 6500 (neutral white). +

+
+
cones
+

Cone model to use for color blindness simulation. Accepts any combination of +l, m and s. Here are some examples: +

+
‘m’
+

Deuteranomaly / deuteranopia (affecting 3%-4% of the population) +

+
‘l’
+

Protanomaly / protanopia (affecting 1%-2% of the population) +

+
‘l+m’
+

Monochromacy (very rare) +

+
‘l+m+s’
+

Achromatopsy (complete loss of daytime vision, extremely rare) +

+
+ +
+
cone-strength
+

Gain factor for the cones specified by cones, between 0.0 and +10.0. A value of 1.0 results in no change to color vision. A +value of 0.0 (the default) simulates complete loss of those cones. Values +above 1.0 result in exaggerating the differences between cones, which +may help compensate for reduced color vision. +

+
+ + +

30.144.1.6 Peak detection

+

To help deal with sources that only have static HDR10 metadata (or no tagging +whatsoever), libplacebo uses its own internal frame analysis compute shader to +analyze source frames and adapt the tone mapping function in realtime. If this +is too slow, or if exactly reproducible frame-perfect results are needed, it’s +recommended to turn this feature off. +

+
peak_detect
+

Enable HDR peak detection. Ignores static MaxCLL/MaxFALL values in favor of +dynamic detection from the input. Note that the detected values do not get +written back to the output frames, they merely guide the internal tone mapping +process. Enabled by default. +

+
+
smoothing_period
+

Peak detection smoothing period, between 0.0 and 1000.0. Higher +values result in peak detection becoming less responsive to changes in the +input. Defaults to 20.0. +

+
+
scene_threshold_low
+
scene_threshold_high
+

Lower and upper thresholds for scene change detection. Expressed in a +logarithmic scale between 0.0 and 100.0. Default to 1.0 +and 3.0, respectively. Setting either to a negative value disables +this functionality. +

+
+
percentile
+

Which percentile of the frame brightness histogram to use as the source peak +for tone-mapping. Defaults to 99.995, a fairly conservative value. +Setting this to 100.0 disables frame histogram measurement and instead +uses the true peak brightness for tone-mapping. +

+
+ + +

30.144.1.7 Tone mapping

+

The options in this section control how libplacebo performs tone-mapping and +gamut-mapping when dealing with mismatches between wide-gamut or HDR content. +In general, libplacebo relies on accurate source tagging and mastering display +gamut information to produce the best results. +

+
gamut_mode
+

How to handle out-of-gamut colors that can occur as a result of colorimetric +gamut mapping. +

+
‘clip’
+

Do nothing, simply clip out-of-range colors to the RGB volume. Low quality but +extremely fast. +

+
‘perceptual’
+

Perceptually soft-clip colors to the gamut volume. This is the default. +

+
‘relative’
+

Relative colorimetric hard-clip. Similar to perceptual but without +the soft knee. +

+
‘saturation’
+

Saturation mapping, maps primaries directly to primaries in RGB space. +Not recommended except for artificial computer graphics for which a bright, +saturated display is desired. +

+
‘absolute’
+

Absolute colorimetric hard-clip. Performs no adjustment of the white point. +

+
‘desaturate’
+

Hard-desaturates out-of-gamut colors towards white, while preserving the +luminance. Has a tendency to distort the visual appearance of bright objects. +

+
‘darken’
+

Linearly reduces content brightness to preserves saturated details, followed by +clipping the remaining out-of-gamut colors. +

+
‘warn’
+

Highlight out-of-gamut pixels (by inverting/marking them). +

+
‘linear’
+

Linearly reduces chromaticity of the entire image to make it fit within the +target color volume. Be careful when using this on BT.2020 sources without +proper mastering metadata, as doing so will lead to excessive desaturation. +

+
+ +
+
tonemapping
+

Tone-mapping algorithm to use. Available values are: +

+
‘auto’
+

Automatic selection based on internal heuristics. This is the default. +

+
‘clip’
+

Performs no tone-mapping, just clips out-of-range colors. Retains perfect color +accuracy for in-range colors but completely destroys out-of-range information. +Does not perform any black point adaptation. Not configurable. +

+
‘st2094-40’
+

EETF from SMPTE ST 2094-40 Annex B, which applies the Bezier curves from HDR10+ +dynamic metadata based on Bezier curves to perform tone-mapping. The OOTF used +is adjusted based on the ratio between the targeted and actual display peak +luminances. +

+
‘st2094-10’
+

EETF from SMPTE ST 2094-10 Annex B.2, which takes into account the input signal +average luminance in addition to the maximum/minimum. The configurable contrast +parameter influences the slope of the linear output segment, defaulting to +1.0 for no increase/decrease in contrast. Note that this does not +currently include the subjective gain/offset/gamma controls defined in Annex +B.3. +

+
‘bt.2390’
+

EETF from the ITU-R Report BT.2390, a hermite spline roll-off with linear +segment. The knee point offset is configurable. Note that this parameter +defaults to 1.0, rather than the value of 0.5 from the ITU-R +spec. +

+
‘bt.2446a’
+

EETF from ITU-R Report BT.2446, method A. Designed for well-mastered HDR +sources. Can be used for both forward and inverse tone mapping. Not +configurable. +

+
‘spline’
+

Simple spline consisting of two polynomials, joined by a single pivot point. +The parameter gives the pivot point (in PQ space), defaulting to 0.30. +Can be used for both forward and inverse tone mapping. +

+
‘reinhard’
+

Simple non-linear, global tone mapping algorithm. The parameter specifies the +local contrast coefficient at the display peak. Essentially, a parameter of +0.5 implies that the reference white will be about half as bright as +when clipping. Defaults to 0.5, which results in the simplest +formulation of this function. +

+
‘mobius’
+

Generalization of the reinhard tone mapping algorithm to support an additional +linear slope near black. The tone mapping parameter indicates the trade-off +between the linear section and the non-linear section. Essentially, for a given +parameter x, every color value below x will be mapped linearly, +while higher values get non-linearly tone-mapped. Values near 1.0 make +this curve behave like clip, while values near 0.0 make this +curve behave like reinhard. The default value is 0.3, which +provides a good balance between colorimetric accuracy and preserving +out-of-gamut details. +

+
‘hable’
+

Piece-wise, filmic tone-mapping algorithm developed by John Hable for use in +Uncharted 2, inspired by a similar tone-mapping algorithm used by Kodak. +Popularized by its use in video games with HDR rendering. Preserves both dark +and bright details very well, but comes with the drawback of changing the +average brightness quite significantly. This is sort of similar to +reinhard with parameter 0.24. +

+
‘gamma’
+

Fits a gamma (power) function to transfer between the source and target color +spaces, effectively resulting in a perceptual hard-knee joining two roughly +linear sections. This preserves details at all scales fairly accurately, but +can result in an image with a muted or dull appearance. The parameter is used +as the cutoff point, defaulting to 0.5. +

+
‘linear’
+

Linearly stretches the input range to the output range, in PQ space. This will +preserve all details accurately, but results in a significantly different +average brightness. Can be used for inverse tone-mapping in addition to regular +tone-mapping. The parameter can be used as an additional linear gain +coefficient (defaulting to 1.0). +

+
+ +
+
tonemapping_param
+

For tunable tone mapping functions, this parameter can be used to fine-tune the +curve behavior. Refer to the documentation of tonemapping. The default +value of 0.0 is replaced by the curve’s preferred default setting. +

+
+
inverse_tonemapping
+

If enabled, this filter will also attempt stretching SDR signals to fill HDR +output color volumes. Disabled by default. +

+
+
tonemapping_lut_size
+

Size of the tone-mapping LUT, between 2 and 1024. Defaults to +256. Note that this figure is squared when combined with +peak_detect. +

+
+
contrast_recovery
+

Contrast recovery strength. If set to a value above 0.0, the source +image will be divided into high-frequency and low-frequency components, and a +portion of the high-frequency image is added back onto the tone-mapped output. +May cause excessive ringing artifacts for some HDR sources, but can improve the +subjective sharpness and detail left over in the image after tone-mapping. +Defaults to 0.30. +

+
+
contrast_smoothness
+

Contrast recovery lowpass kernel size. Defaults to 3.5. Increasing or +decreasing this will affect the visual appearance substantially. Has no effect +when contrast_recovery is disabled. +

+
+ + +

30.144.1.8 Dithering

+

By default, libplacebo will dither whenever necessary, which includes rendering +to any integer format below 16-bit precision. It’s recommended to always leave +this on, since not doing so may result in visible banding in the output, even +if the debanding filter is enabled. If maximum performance is needed, +use ordered_fixed instead of disabling dithering. +

+
dithering
+

Dithering method to use. Accepts the following values: +

+
‘none’
+

Disables dithering completely. May result in visible banding. +

+
‘blue’
+

Dither with pseudo-blue noise. This is the default. +

+
‘ordered’
+

Tunable ordered dither pattern. +

+
‘ordered_fixed’
+

Faster ordered dither with a fixed size of 6. Texture-less. +

+
‘white’
+

Dither with white noise. Texture-less. +

+
+ +
+
dither_lut_size
+

Dither LUT size, as log base2 between 1 and 8. Defaults to +6, corresponding to a LUT size of 64x64. +

+
+
dither_temporal
+

Enables temporal dithering. Disabled by default. +

+
+ + +

30.144.1.9 Custom shaders

+

libplacebo supports a number of custom shaders based on the mpv .hook GLSL +syntax. A collection of such shaders can be found here: +https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders +

+

A full description of the mpv shader format is beyond the scope of this +section, but a summary can be found here: +https://mpv.io/manual/master/#options-glsl-shader +

+
custom_shader_path
+

Specifies a path to a custom shader file to load at runtime. +

+
+
custom_shader_bin
+

Specifies a complete custom shader as a raw string. +

+
+ + +

30.144.1.10 Debugging / performance

+

All of the options in this section default off. They may be of assistance when +attempting to squeeze the maximum performance at the cost of quality. +

+
skip_aa
+

Disable anti-aliasing when downscaling. +

+
+
disable_linear
+

Disable linear light scaling. +

+
+
disable_builtin
+

Disable built-in GPU sampling (forces LUT). +

+
+
disable_fbos
+

Forcibly disable FBOs, resulting in loss of almost all functionality, but +offering the maximum possible speed. +

+
+ + +

30.144.2 Commands

+

This filter supports almost all of the above options as commands. +

+ +

30.144.3 Examples

+
    +
  • Tone-map input to standard gamut BT.709 output: +
    +
    libplacebo=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv
    +
    + +
  • Rescale input to fit into standard 1080p, with high quality scaling: +
    +
    libplacebo=w=1920:h=1080:force_original_aspect_ratio=decrease:normalize_sar=true:upscaler=ewa_lanczos:downscaler=ewa_lanczos
    +
    + +
  • Interpolate low FPS / VFR input to smoothed constant 60 fps output: +
    +
    libplacebo=fps=60:frame_mixer=mitchell_clamp
    +
    + +
  • Convert input to standard sRGB JPEG: +
    +
    libplacebo=format=yuv420p:colorspace=bt470bg:color_primaries=bt709:color_trc=iec61966-2-1:range=pc
    +
    + +
  • Use higher quality debanding settings: +
    +
    libplacebo=deband=true:deband_iterations=3:deband_radius=8:deband_threshold=6
    +
    + +
  • Run this filter on the CPU, on systems with Mesa installed (and with the most +expensive options disabled): +
    +
    ffmpeg ... -init_hw_device vulkan:llvmpipe ... -vf libplacebo=upscaler=none:downscaler=none:peak_detect=false
    +
    + +
  • Suppress CPU-based AV1/H.274 film grain application in the decoder, in favor of +doing it with this filter. Note that this is only a gain if the frames are +either already on the GPU, or if you’re using libplacebo for other purposes, +since otherwise the VRAM roundtrip will more than offset any expected speedup. +
    +
    ffmpeg -export_side_data +film_grain ... -vf libplacebo=apply_filmgrain=true
    +
    + +
  • Interop with VAAPI hwdec to avoid round-tripping through RAM: +
    +
    ffmpeg -init_hw_device vulkan -hwaccel vaapi -hwaccel_output_format vaapi ... -vf libplacebo
    +
    +
+ + +

30.145 libvmaf

+ +

Calculate the VMAF (Video Multi-Method Assessment Fusion) score for a +reference/distorted pair of input videos. +

+

The first input is the distorted video, and the second input is the reference video. +

+

The obtained VMAF score is printed through the logging system. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-libvmaf. +

+

The filter has following options: +

+
+
model
+

A ‘|‘ delimited list of vmaf models. Each model can be configured with a number of parameters. +Default value: "version=vmaf_v0.6.1" +

+
+
feature
+

A ‘|‘ delimited list of features. Each feature can be configured with a number of parameters. +

+
+
log_path
+

Set the file path to be used to store log files. +

+
+
log_fmt
+

Set the format of the log file (xml, json, csv, or sub). +

+
+
pool
+

Set the pool method to be used for computing vmaf. +Options are min, harmonic_mean or mean (default). +

+
+
n_threads
+

Set number of threads to be used when initializing libvmaf. +Default value: 0, no threads. +

+
+
n_subsample
+

Set frame subsampling interval to be used. +

+
+ +

This filter also supports the framesync options. +

+ +

30.145.1 Examples

+
    +
  • In the examples below, a distorted video distorted.mpg is +compared with a reference file reference.mpg. + +
  • Basic usage: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf=log_path=output.xml -f null -
    +
    + +
  • Example with multiple models: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='model=version=vmaf_v0.6.1\\:name=vmaf|version=vmaf_v0.6.1neg\\:name=vmaf_neg' -f null -
    +
    + +
  • Example with multiple additional features: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr|name=ciede' -f null -
    +
    + +
  • Example with options and different containers: +
    +
    ffmpeg -i distorted.mpg -i reference.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=log_fmt=json:log_path=output.json" -f null -
    +
    +
+ + +

30.146 libvmaf_cuda

+ +

This is the CUDA variant of the libvmaf filter. It only accepts CUDA frames. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-nonfree --enable-ffnvcodec --enable-libvmaf. +

+ +

30.146.1 Examples

+
    +
  • Basic usage showing CUVID hardware decoding and CUDA scaling with scale_cuda: +
    +
    ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i dis.obu \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i ref.obu \
    +    -filter_complex "
    +        [0:v]scale_cuda=format=yuv420p[dis]; \
    +        [1:v]scale_cuda=format=yuv420p[ref]; \
    +        [dis][ref]libvmaf_cuda=log_fmt=json:log_path=output.json
    +    " \
    +    -f null -
    +
    +
+ + +

30.147 limitdiff

+

Apply limited difference filter using second and optionally third video stream. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the threshold to use when allowing certain differences between video streams. +Any absolute difference value lower or exact than this threshold will pick pixel components from +first video stream. +

+
+
elasticity
+

Set the elasticity of soft thresholding when processing video streams. +This value multiplied with first one sets second threshold. +Any absolute difference value greater or exact than second threshold will pick pixel components +from second video stream. For values between those two threshold +linear interpolation between first and second video stream will be used. +

+
+
reference
+

Enable the reference (third) video stream processing. By default is disabled. +If set, this video stream will be used for calculating absolute difference with first video +stream. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

30.147.1 Commands

+ +

This filter supports the all above options as commands except option ‘reference’. +

+ +

30.148 limiter

+ +

Limits the pixel components values to the specified range [min, max]. +

+

The filter accepts the following options: +

+
+
min
+

Lower bound. Defaults to the lowest allowed value for the input. +

+
+
max
+

Upper bound. Defaults to the highest allowed value for the input. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

30.148.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.149 loop

+ +

Loop video frames. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal size in number of frames. Default is 0. +

+
+
start
+

Set first frame of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

30.149.1 Examples

+ +
    +
  • Loop single first frame infinitely: +
    +
    loop=loop=-1:size=1:start=0
    +
    + +
  • Loop single first frame 10 times: +
    +
    loop=loop=10:size=1:start=0
    +
    + +
  • Loop 10 first frames 5 times: +
    +
    loop=loop=5:size=10:start=0
    +
    +
+ + +

30.150 lut1d

+ +

Apply a 1D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 1D LUT file name. +

+

Currently supported formats: +

+
‘cube’
+

Iridas +

+
‘csp’
+

cineSpace +

+
+ +
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘linear’
+

Interpolate values using the linear interpolation. +

+
‘cosine’
+

Interpolate values using the cosine interpolation. +

+
‘cubic’
+

Interpolate values using the cubic interpolation. +

+
‘spline’
+

Interpolate values using the spline interpolation. +

+
+
+
+ + +

30.150.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.151 lut3d

+ +

Apply a 3D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 3D LUT file name. +

+

Currently supported formats: +

+
‘3dl’
+

AfterEffects +

+
‘cube’
+

Iridas +

+
‘dat’
+

DaVinci +

+
‘m3d’
+

Pandora +

+
‘csp’
+

cineSpace +

+
+
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘trilinear’
+

Interpolate values using the 8 points defining a cube. +

+
‘tetrahedral’
+

Interpolate values using a tetrahedron. +

+
‘pyramid’
+

Interpolate values using a pyramid. +

+
‘prism’
+

Interpolate values using a prism. +

+
+
+
+ + +

30.151.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

30.152 lumakey

+ +

Turn certain luma values into transparency. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the luma which will be used as base for transparency. +Default value is 0. +

+
+
tolerance
+

Set the range of luma values to be keyed out. +Default value is 0.01. +

+
+
softness
+

Set the range of softness. Default value is 0. +Use this to control gradual transition from zero to full transparency. +

+
+ + +

30.152.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.153 lut, lutrgb, lutyuv

+ +

Compute a look-up table for binding each pixel component input value +to an output value, and apply it to the input video. +

+

lutyuv applies a lookup table to a YUV input video, lutrgb +to an RGB input video. +

+

These filters accept the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
r
+

set red component expression +

+
g
+

set green component expression +

+
b
+

set blue component expression +

+
a
+

alpha component expression +

+
+
y
+

set Y/luma component expression +

+
u
+

set U/Cb component expression +

+
v
+

set V/Cr component expression +

+
+ +

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 c* options depends on the +format in input. +

+

The lut filter requires either YUV or RGB pixel formats in input, +lutrgb requires RGB pixel formats in input, and lutyuv requires YUV. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
clipval
+

The input value, clipped to the minval-maxval range. +

+
+
maxval
+

The maximum value for the pixel component. +

+
+
minval
+

The minimum value for the pixel component. +

+
+
negval
+

The negated value for the pixel component value, clipped to the +minval-maxval range; it corresponds to the expression +"maxval-clipval+minval". +

+
+
clip(val)
+

The computed value in val, clipped to the +minval-maxval range. +

+
+
gammaval(gamma)
+

The computed gamma correction value of the pixel component value, +clipped to the minval-maxval range. It corresponds to the +expression +"pow((clipval-minval)/(maxval-minval)\,gamma)*(maxval-minval)+minval" +

+
+
+ +

All expressions default to "clipval". +

+ +

30.153.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.153.2 Examples

+ +
    +
  • Negate input video: +
    +
    lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
    +lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
    +
    + +

    The above is the same as: +

    +
    lutrgb="r=negval:g=negval:b=negval"
    +lutyuv="y=negval:u=negval:v=negval"
    +
    + +
  • Negate luma: +
    +
    lutyuv=y=negval
    +
    + +
  • Remove chroma components, turning the video into a graytone image: +
    +
    lutyuv="u=128:v=128"
    +
    + +
  • Apply a luma burning effect: +
    +
    lutyuv="y=2*val"
    +
    + +
  • Remove green and blue components: +
    +
    lutrgb="g=0:b=0"
    +
    + +
  • Set a constant alpha channel value on input: +
    +
    format=rgba,lutrgb=a="maxval-minval/2"
    +
    + +
  • Correct luma gamma by a factor of 0.5: +
    +
    lutyuv=y=gammaval(0.5)
    +
    + +
  • Discard least significant bits of luma: +
    +
    lutyuv=y='bitand(val, 128+64+32)'
    +
    + +
  • Technicolor like effect: +
    +
    lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
    +
    +
+ + +

30.154 lut2, tlut2

+ +

The lut2 filter takes two input streams and outputs one +stream. +

+

The tlut2 (time lut2) filter takes two consecutive frames +from one single stream. +

+

This filter accepts the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
d
+

set output bit depth, only available for lut2 filter. By default is 0, +which means bit depth is automatically picked from first input format. +

+
+ +

The lut2 filter also supports the framesync options. +

+

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 c* options depends on the +format in inputs. +

+

The expressions can contain the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
x
+

The first input value for the pixel component. +

+
+
y
+

The second input value for the pixel component. +

+
+
bdx
+

The first input video bit depth. +

+
+
bdy
+

The second input video bit depth. +

+
+ +

All expressions default to "x". +

+ +

30.154.1 Commands

+ +

This filter supports the all above options as commands except option d. +

+ +

30.154.2 Examples

+ +
    +
  • Highlight differences between two RGB video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'
    +
    + +
  • Highlight differences between two YUV video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'
    +
    + +
  • Show max difference between two video streams: +
    +
    lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'
    +
    +
+ + +

30.155 maskedclamp

+ +

Clamp the first input stream with the second input and third input stream. +

+

Returns the value of first stream to be between second input +stream - undershoot and third input stream + overshoot. +

+

This filter accepts the following options: +

+
undershoot
+

Default value is 0. +

+
+
overshoot
+

Default value is 0. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

30.155.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.156 maskedmax

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is greater than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

30.156.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.157 maskedmerge

+ +

Merge the first input stream with the second input stream using per pixel +weights in the third input stream. +

+

A value of 0 in the third stream pixel component means that pixel component +from first stream is returned unchanged, while maximum value (eg. 255 for +8-bit videos) means that pixel component from second stream is returned +unchanged. Intermediate values define the amount of merging between both +input stream’s pixel components. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

30.157.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.158 maskedmin

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is less than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

30.158.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.159 maskedthreshold

+

Pick pixels comparing absolute difference of two video streams with fixed +threshold. +

+

If absolute difference between pixel component of first and second video +stream is equal or lower than user supplied threshold than pixel component +from first video stream is picked, otherwise pixel component from second +video stream is picked. +

+

This filter accepts the following options: +

+
threshold
+

Set threshold used when picking pixels from absolute difference from two input +video streams. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from second stream. +By default value 0xf, all planes will be processed. +

+
+
mode
+

Set mode of filter operation. Can be abs or diff. +Default is abs. +

+
+ + +

30.159.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.160 maskfun

+

Create mask from input video. +

+

For example it is useful to create motion masks after tblend filter. +

+

This filter accepts the following options: +

+
+
low
+

Set low threshold. Any pixel component lower or exact than this value will be set to 0. +

+
+
high
+

Set high threshold. Any pixel component higher than this value will be set to max value +allowed for current pixel format. +

+
+
planes
+

Set planes to filter, by default all available planes are filtered. +

+
+
fill
+

Fill all frame pixels with this value. +

+
+
sum
+

Set max average pixel value for frame. If sum of all pixel components is higher that this +average, output frame will be completely filled with value set by fill option. +Typically useful for scene changes when used in combination with tblend filter. +

+
+ + +

30.160.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.161 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: +

+
mode
+

Set the deinterlacing mode. +

+

It accepts one of the following values: +

+
‘fast’
+
‘medium’
+
‘slow’
+

use iterative motion estimation +

+
‘extra_slow’
+

like ‘slow’, but use multiple reference frames. +

+
+

Default value is ‘fast’. +

+
+
parity
+

Set the picture field parity assumed for the input video. It must be +one of the following values: +

+
+
‘0, tff’
+

assume top field first +

+
‘1, bff’
+

assume bottom field first +

+
+ +

Default value is ‘bff’. +

+
+
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. +

+
+ + +

30.162 median

+ +

Pick median pixel from certain rectangle defined by radius. +

+

This filter accepts the following options: +

+
+
radius
+

Set horizontal radius size. Default value is 1. +Allowed range is integer from 1 to 127. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+
radiusV
+

Set vertical radius size. Default value is 0. +Allowed range is integer from 0 to 127. +If it is 0, value will be picked from horizontal radius option. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

30.162.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.163 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: +

+
mapping
+

Set input to output plane mapping. Default is 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. +

+
+
format
+

Set output pixel format. Default is yuva444p. +

+
+
map0s
+
map1s
+
map2s
+
map3s
+

Set input to output stream mapping for output Nth plane. Default is 0. +

+
+
map0p
+
map1p
+
map2p
+
map3p
+

Set input to output plane mapping for output Nth plane. Default is 0. +

+
+ + +

30.163.1 Examples

+ +
    +
  • Merge three gray video streams of same width and height into single video stream: +
    +
    [a0][a1][a2]mergeplanes=0x001020:yuv444p
    +
    + +
  • Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: +
    +
    [a0][a1]mergeplanes=0x00010210:yuva444p
    +
    + +
  • Swap Y and A plane in yuva444p stream: +
    +
    format=yuva444p,mergeplanes=0x03010200:yuva444p
    +
    + +
  • Swap U and V plane in yuv420p stream: +
    +
    format=yuv420p,mergeplanes=0x000201:yuv420p
    +
    + +
  • Cast a rgb24 clip to yuv444p: +
    +
    format=rgb24,mergeplanes=0x000102:yuv444p
    +
    +
+ + +

30.164 mestimate

+ +

Estimate and export motion vectors using block matching algorithms. +Motion vectors are stored in frame side data to be used by other filters. +

+

This filter accepts the following options: +

+
method
+

Specify the motion estimation method. Accepts one of the following values: +

+
+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default value is ‘esa’. +

+
+
mb_size
+

Macroblock size. Default 16. +

+
+
search_param
+

Search parameter. Default 7. +

+
+ + +

30.165 mestimate_d3d12

+ +

Estimate and export motion vectors using D3D12 hardware-accelerated motion estimation. +This filter uses GPU hardware motion estimation capabilities available in +DirectX 12 Video APIs to achieve significant performance improvements +over the software-based mestimate filter. +

+

Motion vectors are stored in frame side data to be used by other filters. +

+

This filter requires the input to be in d3d12 hardware pixel format. +The filter uses quarter-pixel precision for motion vector estimation. +

+

This filter accepts the following options: +

+
mb_size
+

Macroblock size. Only 8 and 16 are supported. +Default 16. +

+
+ + +

30.165.1 Examples

+ +

Estimate motion vectors using D3D12 hardware acceleration with 16x16 blocks, +and visualize them: +

+
ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.mp4 \
+        -vf mestimate_d3d12=mb_size=16,hwdownload,format=nv12,codecview=mv=pf \
+        -c:v libx264 -preset fast -b:v 5M output.mp4
+
+ + +

30.166 midequalizer

+ +

Apply Midway Image Equalization effect using two video streams. +

+

Midway Image Equalization adjusts a pair of images to have the same +histogram, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a pair of stereo cameras. +

+

This filter has two inputs and one output, which must be of same pixel format, but +may be of different sizes. The output of filter is first input adjusted with +midway histogram of both inputs. +

+

This filter accepts the following option: +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

30.167 minterpolate

+ +

Convert the video to specified frame rate using motion interpolation. +

+

This filter accepts the following options: +

+
fps
+

Specify the output frame rate. This can be rational e.g. 60000/1001. Frames are dropped if fps is lower than source fps. Default 60. +

+
+
mi_mode
+

Motion interpolation mode. Following values are accepted: +

+
‘dup’
+

Duplicate previous or next frame for interpolating new ones. +

+
‘blend’
+

Blend source frames. Interpolated frame is mean of previous and next frames. +

+
‘mci’
+

Motion compensated interpolation. Following options are effective when this mode is selected: +

+
+
‘mc_mode’
+

Motion compensation mode. Following values are accepted: +

+
‘obmc’
+

Overlapped block motion compensation. +

+
‘aobmc’
+

Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. +

+
+

Default mode is ‘obmc’. +

+
+
‘me_mode’
+

Motion estimation mode. Following values are accepted: +

+
‘bidir’
+

Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. +

+
‘bilat’
+

Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. +

+
+

Default mode is ‘bilat’. +

+
+
‘me’
+

The algorithm to be used for motion estimation. Following values are accepted: +

+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default algorithm is ‘epzs’. +

+
+
‘mb_size’
+

Macroblock size. Default 16. +

+
+
‘search_param’
+

Motion estimation search parameter. Default 32. +

+
+
‘vsbmc’
+

Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make them less blurry. Default is 0 (disabled). +

+
+
+
+ +
+
scd
+

Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted: +

+
‘none’
+

Disable scene change detection. +

+
‘fdiff’
+

Frame difference. Corresponding pixel values are compared and if it satisfies scd_threshold scene change is detected. +

+
+

Default method is ‘fdiff’. +

+
+
scd_threshold
+

Scene change detection threshold. Default is 10.. +

+
+ + +

30.168 mix

+ +

Mix several video input streams into one video stream. +

+

A description of the accepted options follows. +

+
+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
weights
+

Specify weight of each input video stream as sequence. +Each weight is separated by space. If number of weights +is smaller than number of frames last specified +weight will be used for all remaining unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+
duration
+

Specify how end of stream is determined. +

+
‘longest’
+

The duration of the longest input. (default) +

+
+
‘shortest’
+

The duration of the shortest input. +

+
+
‘first’
+

The duration of the first input. +

+
+
+
+ + +

30.168.1 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

30.169 monochrome

+

Convert video to gray using custom color filter. +

+

A description of the accepted options follows. +

+
+
cb
+

Set the chroma blue spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
cr
+

Set the chroma red spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
size
+

Set the color filter size. Allowed range is from .1 to 10. +Default value is 1. +

+
+
high
+

Set the highlights strength. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

30.169.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.170 morpho

+ +

This filter allows to apply main morphological grayscale transforms, +erode and dilate with arbitrary structures set in second input stream. +

+

Unlike naive implementation and much slower performance in erosion +and dilation filters, when speed is critical morpho filter +should be used instead. +

+

A description of accepted options follows, +

+
+
mode
+

Set morphological transform to apply, can be: +

+
+
‘erode’
+
‘dilate’
+
‘open’
+
‘close’
+
‘gradient’
+
‘tophat’
+
‘blackhat’
+
+

Default is erode. +

+
+
planes
+

Set planes to filter, by default all planes except alpha are filtered. +

+
+
structure
+

Set which structure video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+ +

The morpho filter also supports the framesync options. +

+ +

30.170.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.171 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. +

+
+
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 disregarding the +number of previous sequentially dropped frames. +

+

Default value is 0. +

+
+
keep
+

Set the maximum number of consecutive similar frames to ignore before to start dropping them. +If the value is 0, the frame is dropped disregarding the +number of previous sequentially similar frames. +

+

Default value is 0. +

+
+
hi
+
lo
+
frac
+

Set the dropping threshold values. +

+

Values for hi and 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 hi, and if no more than frac blocks (1 +meaning the whole image) differ by more than a threshold of lo. +

+

Default value for hi is 64*12, default value for lo is +64*5, and default value for frac is 0.33. +

+
+ + +

30.172 msad

+ +

Obtain the MSAD (Mean Sum of Absolute Differences) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max MSAD is printed through +the logging system. +

+

The filter stores the calculated MSAD of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi msad -f null -
+
+ + +

30.173 multiply

+

Multiply first video stream pixels values with second video stream pixels values. +

+

The filter accepts the following options: +

+
+
scale
+

Set the scale applied to second video stream. By default is 1. +Allowed range is from 0 to 9. +

+
+
offset
+

Set the offset applied to second video stream. By default is 0.5. +Allowed range is from -1 to 1. +

+
+
planes
+

Specify planes from input video stream that will be processed. +By default all planes are processed. +

+
+ + +

30.173.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.174 negate

+ +

Negate (invert) the input video. +

+

It accepts the following option: +

+
+
components
+

Set components to negate. +

+

Available values for components are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +
+
negate_alpha
+

With value 1, it negates the alpha component, if present. Default value is 0. +

+
+ + +

30.174.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.175 nlmeans

+ +

Denoise frames using Non-Local Means algorithm. +

+

Each pixel is adjusted by looking for other pixels with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +pxp. Patches are searched in an area of rxr +around the pixel. +

+

Note that the research area defines centers for patches, which means some +patches will be made of pixels outside that research area. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0]. +

+
+
p
+

Set patch size. Default is 7. Must be odd number in range [0, 99]. +

+
+
pc
+

Same as p but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
rc
+

Same as r but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+ + +

30.176 nnedi

+ +

Deinterlace video using neural network edge directed interpolation. +

+

This filter accepts the following options: +

+
+
weights
+

Mandatory option, without binary file filter can not work. +Currently file can be found here: +https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin +

+
+
deint
+

Set which frames to deinterlace, by default it is all. +Can be all or interlaced. +

+
+
field
+

Set mode of operation. +

+

Can be one of the following: +

+
+
‘af’
+

Use frame flags, both fields. +

+
‘a’
+

Use frame flags, single field. +

+
‘t’
+

Use top field only. +

+
‘b’
+

Use bottom field only. +

+
‘tf’
+

Use both fields, top first. +

+
‘bf’
+

Use both fields, bottom first. +

+
+ +
+
planes
+

Set which planes to process, by default filter process all frames. +

+
+
nsize
+

Set size of local neighborhood around each pixel, used by the predictor neural +network. +

+

Can be one of the following: +

+
+
‘s8x6’
+
‘s16x6’
+
‘s32x6’
+
‘s48x6’
+
‘s8x4’
+
‘s16x4’
+
‘s32x4’
+
+ +
+
nns
+

Set the number of neurons in predictor neural network. +Can be one of the following: +

+
+
‘n16’
+
‘n32’
+
‘n64’
+
‘n128’
+
‘n256’
+
+ +
+
qual
+

Controls the number of different neural network predictions that are blended +together to compute the final output value. Can be fast, default or +slow. +

+
+
etype
+

Set which set of weights to use in the predictor. +Can be one of the following: +

+
+
‘a, abs’
+

weights trained to minimize absolute error +

+
‘s, mse’
+

weights trained to minimize squared error +

+
+ +
+
pscrn
+

Controls whether or not the prescreener neural network is used to decide +which pixels should be processed by the predictor neural network and which +can be handled by simple cubic interpolation. +The prescreener is trained to know whether cubic interpolation will be +sufficient for a pixel or whether it should be predicted by the predictor nn. +The computational complexity of the prescreener nn is much less than that of +the predictor nn. Since most pixels can be handled by cubic interpolation, +using the prescreener generally results in much faster processing. +The prescreener is pretty accurate, so the difference between using it and not +using it is almost always unnoticeable. +

+

Can be one of the following: +

+
+
‘none’
+
‘original’
+
‘new’
+
‘new2’
+
‘new3’
+
+ +

Default is new. +

+
+ + +

30.176.1 Commands

+

This filter supports same commands as options, excluding weights option. +

+ +

30.177 noformat

+ +

Force libavfilter not to use any of the specified pixel formats for the +input to the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +pix_fmts=yuv420p|monow|rgb24". +

+
+
+ + +

30.177.1 Examples

+ +
    +
  • Force libavfilter to use a format different from yuv420p for the +input to the vflip filter: +
    +
    noformat=pix_fmts=yuv420p,vflip
    +
    + +
  • Convert the input video to any of the formats not contained in the list: +
    +
    noformat=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

30.178 noise

+ +

Add noise on video input frame. +

+

The filter accepts the following options: +

+
+
all_seed
+
c0_seed
+
c1_seed
+
c2_seed
+
c3_seed
+

Set noise seed for specific pixel component or all pixel components in case +of all_seed. Default value is 123457. +

+
+
all_strength, alls
+
c0_strength, c0s
+
c1_strength, c1s
+
c2_strength, c2s
+
c3_strength, c3s
+

Set noise strength for specific pixel component or all pixel components in case +all_strength. Default value is 0. Allowed range is [0, 100]. +

+
+
all_flags, allf
+
c0_flags, c0f
+
c1_flags, c1f
+
c2_flags, c2f
+
c3_flags, c3f
+

Set pixel component flags or set flags for all components if all_flags. +Available values for component flags are: +

+
‘a’
+

averaged temporal noise (smoother) +

+
‘p’
+

mix random noise with a (semi)regular pattern +

+
‘t’
+

temporal noise (noise pattern changes between frames) +

+
‘u’
+

uniform noise (gaussian otherwise) +

+
+
+
+ + +

30.178.1 Examples

+ +

Add temporal and uniform noise to input video: +

+
noise=alls=20:allf=t+u
+
+ + +

30.179 normalize

+ +

Normalize RGB video (aka histogram stretching, contrast stretching). +See: https://en.wikipedia.org/wiki/Normalization_(image_processing) +

+

For each channel of each frame, the filter computes the input range and maps +it linearly to the user-specified output range. The output range defaults +to the full dynamic range from pure black to pure white. +

+

Temporal smoothing can be used on the input range to reduce flickering (rapid +changes in brightness) caused when small dark or bright objects enter or leave +the scene. This is similar to the auto-exposure (automatic gain control) on a +video camera, and, like a video camera, it may cause a period of over- or +under-exposure of the video. +

+

The R,G,B channels can be normalized independently, which may cause some +color shifting, or linked together as a single channel, which prevents +color shifting. Linked normalization preserves hue. Independent normalization +does not, so it can be used to remove some color casts. Independent and linked +normalization can be combined in any ratio. +

+

The normalize filter accepts the following options: +

+
+
blackpt
+
whitept
+

Colors which define the output range. The minimum input value is mapped to +the blackpt. The maximum input value is mapped to the whitept. +The defaults are black and white respectively. Specifying white for +blackpt and black for whitept will give color-inverted, +normalized video. Shades of grey can be used to reduce the dynamic range +(contrast). Specifying saturated colors here can create some interesting +effects. +

+
+
smoothing
+

The number of previous frames to use for temporal smoothing. The input range +of each channel is smoothed using a rolling average over the current frame +and the smoothing previous frames. The default is 0 (no temporal +smoothing). +

+
+
independence
+

Controls the ratio of independent (color shifting) channel normalization to +linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully +independent. Defaults to 1.0 (fully independent). +

+
+
strength
+

Overall strength of the filter. 1.0 is full strength. 0.0 is a rather +expensive no-op. Defaults to 1.0 (full strength). +

+
+
+ + +

30.179.1 Commands

+

This filter supports same commands as options, excluding smoothing option. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.179.2 Examples

+ +

Stretch video contrast to use the full dynamic range, with no temporal +smoothing; may flicker depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=0
+
+ +

As above, but with 50 frames of temporal smoothing; flicker should be +reduced, depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=50
+
+ +

As above, but with hue-preserving linked channel normalization: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0
+
+ +

As above, but with half strength: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
+
+ +

Map the darkest input color to red, the brightest input color to cyan: +

+
normalize=blackpt=red:whitept=cyan
+
+ + +

30.180 null

+ +

Pass the video source unchanged to the output. +

+ +

30.181 ocio

+

OpenColorIO library filter +

+

This filter allows you to do color management using the OpenColorIO library. +See https://opencolorio.org/ for more details. To Enable +compilation of this filter, you need to configure FFmpeg with --enable-libopencolorio. +

+

It accepts the following options: +

+
+
config
+

By default the filter will use the OCIO config defined by the OCIO environment variable, but this parameter allows you to explicitly specify its location. +If you are getting started, you can use config=ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1 which specifies one of the built in defaults. +

+
+
input
+

Set the input colorspace. +

+
+
output
+

Set the output colorspace. +

+
+
display
+

Set the display colorspace, used in combination with view. +

+
+
view
+

Set the view colorspace, used in combination with display. +

+
+
inverse
+

When used in combination with display and view, this inverts the transform, so going from a display/view to the "input colorspace". +

+
+
filetransform
+

Allows you to specify an external file-transform to use instead of the OCIO config file. This is useful for applying a single transform without needing a full OCIO config file. +

+
+
format
+

Allow you to specify the output pix_fmt of the OCIO filter. This *has* to be a RGB colorspace, so you really are limited to rgb24, rgba, rgb48, rgba48, gbrp10, gbrp12, gbrpf32le, gbrapf32le, for most encoding we would recommend rgb48 +

+
+
context_params
+

Allow you to specify additional context parameters for the OCIO filter. This is a list of key=value pairs, separated by colons. +

+
+
+ + +

30.181.1 Examples

+ +

Map from ACEScg to ACEScct, this assumes the OCIO file is defined with the OCIO environment variable. +

+
input=ACEScg:output=ACEScct:format=rgb48
+
+ +

Map from ACEScg to a sRGB display using the "ACES 1.0 - SDR Video" view transform, this assumes the OCIO file is defined with the OCIO environment variable. Note you will need to wrap the argument in quotes to ensure that the spaces are interpreted correctly. +

+
input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ + +

As above but using the OCIO file studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio rather than the OCIO environment variable. +

+
config=studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio:input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ +

If you are converting to YCrCb you still will want to set the color matrix for the conversion. This is a good example of combining the two. +

+
ffmpeg -y -i SOURCEFRAMES.%05d.exr -c:v libx265 -vf "ocio=input=ACEScg:output=ACEScct:format=rgb48,scale=in_color_matrix=bt709:out_color_matrix=bt709,format=yuv444p10"  OUTPUTFILE.mov
+
+ + +

30.182 ocr

+

Optical Character Recognition +

+

This filter uses Tesseract for optical character recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-libtesseract. +

+

It accepts the following options: +

+
+
datapath
+

Set datapath to tesseract data. Default is to use whatever was +set at installation. +

+
+
language
+

Set language, default is "eng". +

+
+
whitelist
+

Set character whitelist. +

+
+
blacklist
+

Set character blacklist. +

+
+ +

The filter exports recognized text as the frame metadata lavfi.ocr.text. +The filter exports confidence of recognized words as the frame metadata lavfi.ocr.confidence. +

+ +

30.183 ocv

+ +

Apply a video transform using libopencv. +

+

To enable this filter, install the libopencv library and headers and +configure FFmpeg with --enable-libopencv. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the libopencv filter to apply. +

+
+
filter_params
+

The parameters to pass to the libopencv filter. If not specified, the default +values are assumed. +

+
+
+ +

Refer to the official libopencv documentation for more precise +information: +http://docs.opencv.org/master/modules/imgproc/doc/filtering.html +

+

Several libopencv filters are supported; see the following subsections. +

+ +

30.183.1 dilate

+ +

Dilate an image by using a specific structuring element. +It corresponds to the libopencv function cvDilate. +

+

It accepts the parameters: struct_el|nb_iterations. +

+

struct_el represents a structuring element, and has the syntax: +colsxrows+anchor_xxanchor_y/shape +

+

cols and rows represent the number of columns and rows of +the structuring element, anchor_x and anchor_y the anchor +point, and shape the shape for the structuring element. shape +must be "rect", "cross", "ellipse", or "custom". +

+

If the value for shape is "custom", it must be followed by a +string of the form "=filename". The file with name +filename is assumed to represent a binary image, with each +printable character corresponding to a bright pixel. When a custom +shape is used, cols and rows are ignored, the number +or columns and rows of the read file are assumed instead. +

+

The default value for struct_el is "3x3+0x0/rect". +

+

nb_iterations specifies the number of times the transform is +applied to the image, and defaults to 1. +

+

Some examples: +

+
# Use the default values
+ocv=dilate
+
+# Dilate using a structuring element with a 5x5 cross, iterating two times
+ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
+
+# Read the shape from the file diamond.shape, iterating two times.
+# The file diamond.shape may contain a pattern of characters like this
+#   *
+#  ***
+# *****
+#  ***
+#   *
+# The specified columns and rows are ignored
+# but the anchor point coordinates are not
+ocv=dilate:0x0+2x2/custom=diamond.shape|2
+
+ + +

30.183.2 erode

+ +

Erode an image by using a specific structuring element. +It corresponds to the libopencv function cvErode. +

+

It accepts the parameters: struct_el:nb_iterations, +with the same syntax and semantics as the dilate filter. +

+ +

30.183.3 smooth

+ +

Smooth the input video. +

+

The filter takes the following parameters: +type|param1|param2|param3|param4. +

+

type is the type of smooth filter to apply, and must be one of +the following values: "blur", "blur_no_scale", "median", "gaussian", +or "bilateral". The default value is "gaussian". +

+

The meaning of param1, param2, param3, and param4 +depends on the smooth type. param1 and +param2 accept integer positive values or 0. param3 and +param4 accept floating point values. +

+

The default value for param1 is 3. The default value for the +other parameters is 0. +

+

These parameters correspond to the parameters assigned to the +libopencv function cvSmooth. +

+ +

30.184 oscilloscope

+ +

2D Video Oscilloscope. +

+

Useful to measure spatial impulse, step responses, chroma delays, etc. +

+

It accepts the following parameters: +

+
+
x
+

Set scope center x position. +

+
+
y
+

Set scope center y position. +

+
+
s
+

Set scope size, relative to frame diagonal. +

+
+
t
+

Set scope tilt/rotation. +

+
+
o
+

Set trace opacity. +

+
+
tx
+

Set trace center x position. +

+
+
ty
+

Set trace center y position. +

+
+
tw
+

Set trace width, relative to width of frame. +

+
+
th
+

Set trace height, relative to height of frame. +

+
+
c
+

Set which components to trace. By default it traces first three components. +

+
+
g
+

Draw trace grid. By default is enabled. +

+
+
st
+

Draw some statistics. By default is enabled. +

+
+
sc
+

Draw scope. By default is enabled. +

+
+ + +

30.184.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

30.184.2 Examples

+ +
    +
  • Inspect full first row of video frame. +
    +
    oscilloscope=x=0.5:y=0:s=1
    +
    + +
  • Inspect full last row of video frame. +
    +
    oscilloscope=x=0.5:y=1:s=1
    +
    + +
  • Inspect full 5th line of video frame of height 1080. +
    +
    oscilloscope=x=0.5:y=5/1080:s=1
    +
    + +
  • Inspect full last column of video frame. +
    +
    oscilloscope=x=1:y=0.5:s=1:t=1
    +
    + +
+ + +

30.185 overlay

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+

A description of the accepted options follows. +

+
+
x
+
y
+

Set the expression for the x and y coordinates of the overlaid video +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). +

+
+
eof_action
+

See framesync. +

+
+
eval
+

Set when the expressions for x, and y are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘frame’. +

+
+
shortest
+

See framesync. +

+
+
format
+

Set the format for the output video. +

+

It accepts the following values: +

+
‘yuv420’
+

force YUV 4:2:0 8-bit planar output +

+
+
‘yuv420p10’
+

force YUV 4:2:0 10-bit planar output +

+
+
‘yuv422’
+

force YUV 4:2:2 8-bit planar output +

+
+
‘yuv422p10’
+

force YUV 4:2:2 10-bit planar output +

+
+
‘yuv444’
+

force YUV 4:4:4 8-bit planar output +

+
+
‘yuv444p10’
+

force YUV 4:4:4 10-bit planar output +

+
+
‘rgb’
+

force RGB 8-bit packed output +

+
+
‘gbrp’
+

force RGB 8-bit planar output +

+
+
‘auto’
+

automatically pick format +

+
+ +

Default value is ‘yuv420’. +

+
+
repeatlast
+

See framesync. +

+
+
alpha
+

Set format of alpha of the overlaid video, it can be straight or +premultiplied, or auto to choose the alpha mode automatically. +Default is auto. +

+
+ +

The x, and y expressions can contain the following +parameters. +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values of the output +format. For example for the pixel format "yuv422p" hsub is 2 and +vsub is 1. +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp, expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

This filter also supports the framesync options. +

+

Note that the n, t variables are available only +when evaluation is done per frame, and will evaluate to NAN +when eval is set to ‘init’. +

+

Be aware that frames are taken from each input video in timestamp +order, hence, if their initial timestamps differ, it is a good idea +to pass the two inputs through a setpts=PTS-STARTPTS filter to +have them begin in the same zero timestamp, as the example for +the movie filter does. +

+

You can chain together more overlays but you should test the +efficiency of such approach. +

+ +

30.185.1 Commands

+ +

This filter supports the following commands: +

+
x
+
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. +

+
+ + +

30.185.2 Examples

+ +
    +
  • Draw the overlay at 10 pixels from the bottom right corner of the main +video: +
    +
    overlay=main_w-overlay_w-10:main_h-overlay_h-10
    +
    + +

    Using named options the example above becomes: +

    +
    overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
    +
    + +
  • Insert a transparent PNG logo in the bottom left corner of the input, +using the ffmpeg tool with the -filter_complex option: +
    +
    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 ffmpeg tool: +
    +
    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
    +
    + +
  • Add a transparent color layer on top of the main video; WxH +must specify the size of the main input to the overlay filter: +
    +
    color=color=red@.3:size=WxH [over]; [in][over] overlay [out]
    +
    + +
  • Play an original video and a filtered version (here with the deshake +filter) side by side using the ffplay tool: +
    +
    ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
    +
    + +

    The above command is the same as: +

    +
    ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
    +
    + +
  • Make a sliding overlay appearing from the left to the right top part of the +screen starting since time 2: +
    +
    overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
    +
    + +
  • Compose output by putting two input videos side to side: +
    +
    ffmpeg -i left.avi -i right.avi -filter_complex "
    +nullsrc=size=200x100 [background];
    +[0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
    +[1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
    +[background][left]       overlay=shortest=1       [background+left];
    +[background+left][right] overlay=shortest=1:x=100 [left+right]
    +"
    +
    + +
  • Mask 10-20 seconds of a video by applying the delogo filter to a section +
    +
    ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
    +-vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
    +masked.avi
    +
    + +
  • Chain several overlays in cascade: +
    +
    nullsrc=s=200x200 [bg];
    +testsrc=s=100x100, split=4 [in0][in1][in2][in3];
    +[in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
    +[in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
    +[in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
    +[in3] null,       [mid2] overlay=100:100 [out0]
    +
    + +
+ + +

30.186 owdenoise

+ +

Apply Overcomplete Wavelet denoiser. +

+

The filter accepts the following options: +

+
+
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 8. +

+
+
luma_strength, ls
+

Set luma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+
chroma_strength, cs
+

Set chroma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+ + +

30.187 pad

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following parameters: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

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 color is "black". +

+
+
eval
+

Specify when to evaluate width, height, x and y expression. +

+

It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when +a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+
+
aspect
+

Pad to aspect instead to a resolution. +

+
+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

30.187.1 Examples

+ +
    +
  • Add paddings with the color "violet" to the input video. The output video +size is 640x480, and the top-left corner of the input video is placed at +column 0, row 40 +
    +
    pad=640:480:0:40:violet
    +
    + +

    The example above is equivalent to the following command: +

    +
    pad=width=640:height=480:x=0:y=40:color=violet
    +
    + +
  • Pad the input to get an output with dimensions increased by 3/2, +and put the input video at the center of the padded area: +
    +
    pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a squared output with size equal to the maximum +value between the input width and height, and put the input video at +the center of the padded area: +
    +
    pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a final w/h ratio of 16:9: +
    +
    pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • In case of anamorphic video, in order to set the output display aspect +correctly, it is necessary to use sar in the expression, +according to the relation: +
    +
    (ih * X / ih) * sar = output_dar
    +X = output_dar / sar
    +
    + +

    Thus the previous example needs to be modified to: +

    +
    pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Double the output size and put the input video in the bottom-right +corner of the output padded area: +
    +
    pad="2*iw:2*ih:ow-iw:oh-ih"
    +
    +
+ + +

30.188 palettegen

+ +

Generate one palette for a whole video stream. +

+

It accepts the following options: +

+
+
max_colors
+

Set the maximum number of colors to quantize in the palette. +Note: the palette will still contain 256 colors; the unused palette entries +will be black. +

+
+
reserve_transparent
+

Create a palette of 255 colors maximum and reserve the last one for +transparency. Reserving the transparency color is useful for GIF optimization. +If not set, the maximum of colors in the palette will be 256. You probably want +to disable this option for a standalone image. +Set by default. +

+
+
transparency_color
+

Set the color that will be used as background for transparency. +

+
+
stats_mode
+

Set statistics mode. +

+

It accepts the following values: +

+
‘full’
+

Compute full frame histograms. +

+
‘diff’
+

Compute histograms only for the part that differs from previous frame. This +might be relevant to give more importance to the moving part of your input if +the background is static. +

+
‘single’
+

Compute new histogram for each frame. +

+
+ +

Default value is full. +

+
+ +

The filter also exports the frame metadata lavfi.color_quant_ratio +(nb_color_in / nb_color_out) which you can use to evaluate the degree of +color quantization of the palette. This information is also visible at +info logging level. +

+ +

30.188.1 Examples

+ +
    +
  • Generate a representative palette of a given video using ffmpeg: +
    +
    ffmpeg -i input.mkv -vf palettegen palette.png
    +
    +
+ + +

30.189 paletteuse

+ +

Use a palette to downsample an input video stream. +

+

The filter takes two inputs: one video stream and a palette. The palette must +be a 256 pixels image. +

+

It accepts the following options: +

+
+
dither
+

Select dithering mode. Available algorithms are: +

+
‘bayer’
+

Ordered 8x8 bayer dithering (deterministic) +

+
‘heckbert’
+

Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). +Note: this dithering is sometimes considered "wrong" and is included as a +reference. +

+
‘floyd_steinberg’
+

Floyd and Steingberg dithering (error diffusion) +

+
‘sierra2’
+

Frankie Sierra dithering v2 (error diffusion) +

+
‘sierra2_4a’
+

Frankie Sierra dithering v2 "Lite" (error diffusion) +

+
‘sierra3’
+

Frankie Sierra dithering v3 (error diffusion) +

+
‘burkes’
+

Burkes dithering (error diffusion) +

+
‘atkinson’
+

Atkinson dithering by Bill Atkinson at Apple Computer (error diffusion) +

+
‘none’
+

Disable dithering. +

+
+ +

Default is sierra2_4a. +

+
+
bayer_scale
+

When bayer dithering is selected, this option defines the scale of the +pattern (how much the crosshatch pattern is visible). A low value means more +visible pattern for less banding, and higher value means less visible pattern +at the cost of more banding. +

+

The option must be an integer value in the range [0,5]. Default is 2. +

+
+
diff_mode
+

If set, define the zone to process +

+
+
‘rectangle’
+

Only the changing rectangle will be reprocessed. This is similar to GIF +cropping/offsetting compression mechanism. This option can be useful for speed +if only a part of the image is changing, and has use cases such as limiting the +scope of the error diffusal dither to the rectangle that bounds the +moving scene (it leads to more deterministic output if the scene doesn’t change +much, and as a result less moving noise and better GIF compression). +

+
+ +

Default is none. +

+
+
new
+

Take new palette for each output frame. +

+
+
alpha_threshold
+

Sets the alpha threshold for transparency. Alpha values above this threshold +will be treated as completely opaque, and values below this threshold will be +treated as completely transparent. +

+

The option must be an integer value in the range [0,255]. Default is 128. +

+
+ + +

30.189.1 Examples

+ +
    +
  • Use a palette (generated for example with palettegen) to encode a GIF +using ffmpeg: +
    +
    ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
    +
    +
+ + +

30.190 perspective

+ +

Correct perspective of video not recorded perpendicular to the screen. +

+

A description of the accepted parameters follows. +

+
+
x0
+
y0
+
x1
+
y1
+
x2
+
y2
+
x3
+
y3
+

Set coordinates expression for top left, top right, bottom left and bottom right corners. +Default values are 0:0:W:0:0:H:W:H with which perspective will remain unchanged. +If the sense option is set to source, then the specified points will be sent +to the corners of the destination. If the sense option is set to destination, +then the corners of the source will be sent to the specified coordinates. +

+

The expressions can use the following variables: +

+
+
W
+
H
+

the width and height of video frame. +

+
in
+

Input frame count. +

+
on
+

Output frame count. +

+
+ +
+
interpolation
+

Set interpolation for perspective correction. +

+

It accepts the following values: +

+
‘linear’
+
‘cubic’
+
+ +

Default value is ‘linear’. +

+
+
sense
+

Set interpretation of coordinate options. +

+

It accepts the following values: +

+
‘0, source’
+
+

Send point in the source specified by the given coordinates to +the corners of the destination. +

+
+
‘1, destination’
+
+

Send the corners of the source to the point in the destination specified +by the given coordinates. +

+

Default value is ‘source’. +

+
+ +
+
eval
+

Set when the expressions for coordinates x0,y0,...x3,y3 are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ + +

30.191 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. +

+
+
mode
+

Set phase mode. +

+

It accepts the following values: +

+
‘t’
+

Capture field order top-first, transfer bottom-first. +Filter will delay the bottom field. +

+
+
‘b’
+

Capture field order bottom-first, transfer top-first. +Filter will delay the top field. +

+
+
‘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. +

+
+
‘a’
+

Capture field order determined automatically by field flags, transfer +opposite. +Filter selects among ‘t’ and ‘b’ modes on a frame by frame +basis using field flags. If no field information is available, +then this works just like ‘u’. +

+
+
‘u’
+

Capture unknown or varying, transfer opposite. +Filter selects among ‘t’ and ‘b’ on a frame by frame basis by +analyzing the images and selecting the alternative that produces best +match between the fields. +

+
+
‘T’
+

Capture top-first, transfer unknown or varying. +Filter selects among ‘t’ and ‘p’ using image analysis. +

+
+
‘B’
+

Capture bottom-first, transfer unknown or varying. +Filter selects among ‘b’ and ‘p’ using image analysis. +

+
+
‘A’
+

Capture determined by field flags, transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using field flags and +image analysis. If no field information is available, then this works just +like ‘U’. This is the default mode. +

+
+
‘U’
+

Both capture and transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using image analysis only. +

+
+
+
+ + +

30.191.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.192 photosensitivity

+

Reduce various flashes in video, so to help users with epilepsy. +

+

It accepts the following options: +

+
frames, f
+

Set how many frames to use when filtering. Default is 30. +

+
+
threshold, t
+

Set detection threshold factor. Default is 1. +Lower is stricter. +

+
+
skip
+

Set how many pixels to skip when sampling frames. Default is 1. +Allowed range is from 1 to 1024. +

+
+
bypass
+

Leave frames unchanged. Default is disabled. +

+
+ + +

30.193 pixdesctest

+ +

Pixel format descriptor test filter, mainly useful for internal +testing. The output video should be equal to the input video. +

+

For example: +

+
format=monow, pixdesctest
+
+ +

can be used to test the monowhite pixel format descriptor definition. +

+ +

30.194 pixelize

+

Apply pixelization to video stream. +

+

The filter accepts the following options: +

+
width, w
+
height, h
+

Set block dimensions that will be used for pixelization. +Default value is 16. +

+
+
mode, m
+

Set the mode of pixelization used. +

+

Possible values are: +

+
‘avg’
+
‘min’
+
‘max’
+
+

Default value is avg. +

+
+
planes, p
+

Set what planes to filter. Default is to filter all planes. +

+
+ + +

30.194.1 Commands

+ +

This filter supports all options as commands. +

+ +

30.195 pixscope

+ +

Display sample values of color channels. Mainly useful for checking color +and levels. Minimum supported resolution is 640x480. +

+

The filters accept the following options: +

+
+
x
+

Set scope X position, relative offset on X axis. +

+
+
y
+

Set scope Y position, relative offset on Y axis. +

+
+
w
+

Set scope width. +

+
+
h
+

Set scope height. +

+
+
o
+

Set window opacity. This window also holds statistics about pixel area. +

+
+
wx
+

Set window X position, relative offset on X axis. +

+
+
wy
+

Set window Y position, relative offset on Y axis. +

+
+ + +

30.195.1 Commands

+ +

This filter supports same commands as options. +

+ +

30.196 pp7

+

Apply Postprocessing filter 7. It is variant of the spp filter, +similar to spp = 6 with 7 point DCT, where only the center sample is +used after IDCT. +

+

The filter accepts the following options: +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range +0 to 63. If not set, the filter will use the QP from the video stream +(if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding. +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
‘medium’
+

Set medium thresholding (good results, default). +

+
+
+
+ + +

30.197 premultiply

+

Apply alpha premultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

30.198 premultiply_dynamic

+

Dynamically premultiply or unpremultiply the input video stream as needed, +to match the requirements of the downstream filter graph. This is roughly +equivalent to either premultiply:inplace=yes or +unpremultiply:inplace=yes, or otherwise a noop. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ + +

30.199 prewitt

+

Apply prewitt operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

30.199.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.200 pseudocolor

+ +

Alter frame colors in video with pseudocolors. +

+

This filter accepts the following options: +

+
+
c0
+

set pixel first component expression +

+
+
c1
+

set pixel second component expression +

+
+
c2
+

set pixel third component expression +

+
+
c3
+

set pixel fourth component expression, corresponds to the alpha component +

+
+
index, i
+

set component to use as base for altering colors +

+
+
preset, p
+

Pick one of built-in LUTs. By default is set to none. +

+

Available LUTs: +

+
‘magma’
+
‘inferno’
+
‘plasma’
+
‘viridis’
+
‘turbo’
+
‘cividis’
+
‘range1’
+
‘range2’
+
‘shadows’
+
‘highlights’
+
‘solar’
+
‘nominal’
+
‘preferred’
+
‘total’
+
‘spectral’
+
‘cool’
+
‘heat’
+
‘fiery’
+
‘blues’
+
‘green’
+
‘helix’
+
+ +
+
opacity
+

Set opacity of output colors. Allowed range is from 0 to 1. +Default value is set to 1. +

+
+ +

Each of the expression options specifies the expression to use for computing +the lookup table for the corresponding pixel component values. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
ymin, umin, vmin, amin
+

The minimum allowed component value. +

+
+
ymax, umax, vmax, amax
+

The maximum allowed component value. +

+
+ +

All expressions default to "val". +

+ +

30.200.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.200.2 Examples

+ +
    +
  • Change too high luma values to gradient: +
    +
    pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
    +
    +
+ + +

30.201 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: +

+
+
PSNR = 10*log10(MAX^2/MSE)
+
+ +

Where MAX is the average of the maximum values of each component of the +image. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the PSNR of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+
stats_version
+

Specifies which version of the stats file format to use. Details of +each format are written below. +Default value is 1. +

+
+
output_max
+

Determines whether the max value is output to the stats log. +Default value is 0. +Requires stats_version >= 2. If this is set and stats_version < 2, +the filter will return an error. +

+
+ +

This filter also supports the framesync options. +

+

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

If a stats_version greater than 1 is specified, a header line precedes +the list of per-frame-pair stats, with key value pairs following the frame +format with the following parameters: +

+
+
psnr_log_version
+

The version of the log file format. Will match stats_version. +

+
+
fields
+

A comma separated list of the per-frame-pair parameters included in +the log. +

+
+ +

A description of each shown per-frame-pair parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
mse_avg
+

Mean Square Error pixel-by-pixel average difference of the compared +frames, averaged over all the image components. +

+
+
mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
+

Mean Square Error pixel-by-pixel average difference of the compared +frames for the component specified by the suffix. +

+
+
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. +

+
+
max_avg, max_y, max_u, max_v
+

Maximum allowed value for each channel, and average over all +channels. +

+
+ + +

30.201.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] psnr="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The PSNR of each individual frame +is stored in stats.log. +

    +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -
    +
    +
+ + +

30.202 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 fps=24000/1001 if the input frame rate is 29.97fps, +fps=24 for 30fps and the (rare) telecined 25fps input. +

+

The filter accepts the following options: +

+
+
jl
+
jr
+
jt
+
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. +

+
+
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 0. +

+
+
mp
+

Set the metric plane to use. It accepts the following values: +

+
‘l’
+

Use luma plane. +

+
+
‘u’
+

Use chroma blue plane. +

+
+
‘v’
+

Use chroma red plane. +

+
+ +

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 mp to a chroma plane is to reduce CPU +load and make pullup usable in realtime on slow machines. +

+
+ +

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: +

+
ffmpeg -i input -vf pullup -r 24000/1001 ...
+
+ + +

30.203 qp

+ +

Change video quantization parameters (QP). +

+

The filter accepts the following option: +

+
+
qp
+

Set expression for quantization parameter. +

+
+ +

The expression is evaluated through the eval API and can contain, among others, +the following constants: +

+
+
known
+

1 if index is not 129, 0 otherwise. +

+
+
qp
+

Sequential index starting from -129 to 128. +

+
+ + +

30.203.1 Examples

+ +
    +
  • Some equation like: +
    +
    qp=2+2*sin(PI*qp)
    +
    +
+ + +

30.204 qrencode

+

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/), and overlay it on top of the current +frame. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and overlaid into the video output according to +the specified options. +

+

In case no text is specified, no QR code is overlaied. +

+

This filter accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
x
+
y
+

Specify an expression for positioning the padded QR code top-left corner. The +x expression can reference the value set by the y expression, and +vice. +

+

By default x and y are set set to 0, meaning that the QR code +is placed in the top left corner of the input. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section below for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section below for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

30.204.1 qrencode Expressions

+ +

The expressions set by the options contain the following constants and functions. +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
duration
+

the current frame’s duration, in seconds +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
main_h, H
+

the input height +

+
+
main_w, W
+

the input width +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pict_type
+

a number representing the picture type +

+
+
qr_w, w
+

the width of the encoded QR code +

+
+
rendered_qr_w, q
+
rendered_padded_qr_w, Q
+

the width of the rendered QR code, without and without padding. +

+

These parameters allow the q and Q expressions to refer to each +other, so you can for example specify q=3/4*Q. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

the input sample aspect ratio +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer to each +other, so you can for example specify y=x/dar. +

+
+ + +

30.204.2 qrencode Text expansion

+ +

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
n, frame_num
+

return the frame number +

+
+
pts
+

Return the presentation timestamp of the current frame. +

+

It can take up to two arguments. +

+

The first argument is the format of the timestamp; it defaults to flt for +seconds as a decimal number with microsecond accuracy; hms stands for a +formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as local time +zone time. If the format is set to hms24hh, the time is formatted in 24h +format (00-23). +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to localtime or gmtime, a third argument may +be supplied: a strftime C function format string. By default, +YYYY-MM-DD HH:MM:SS format will be used. +

+
+
expr, e
+

Evaluate the expression’s value and output as a double. +

+

It must take one argument specifying the expression to be evaluated, accepting +the constants and functions defined in qrencode_expressions. +

+
+
expr_formatted, ef
+

Evaluate the expression’s value and output as a formatted string. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries starting with TAG +included within each frame section printed by running ffprobe +-show_frames. +

+

String metadata generated in filters leading to the qrencode filter are also +available. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+ + +

30.204.3 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size, overalaid +in the top left corner of the input video, with the default size: +
    +
    qrencode=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencode=text=www.ffmpeg.org:bc=pink@0.5:fc=blue
    +
    + +
  • Place the QR code in the bottom right corner of the input video: +
    +
    qrencode=text=www.ffmpeg.org:x=W-Q:y=H-Q
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencode=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencode=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Make the QR code a fraction of the input video width: +
    +
    qrencode=text=www.ffmpeg.org:q=W/5
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencode=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencode=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencode=text=%{pts}
    +
    + +
+ + +

30.205 quirc

+ +

Identify and decode a QR code using the libquirc library (see +https://github.com/dlbeer/quirc/), and print the identified QR codes +positions and payload as metadata. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libquirc. +

+

For each found QR code in the input video, some metadata entries are added with +the prefix lavfi.quirc.N, where N is the index, starting from 0, +associated to the QR code. +

+

A description of each metadata value follows: +

+
+
lavfi.quirc.count
+

the number of found QR codes, it is not set in case none was found +

+
+
lavfi.quirc.N.corner.M.x
+
lavfi.quirc.N.coreer.M.y
+

the x/y positions of the four corners of the square containing the QR code, +where M is the index of the corner starting from 0 +

+
+
lavfi.quirc.N.payload
+

the payload of the QR code +

+
+ + +

30.206 random

+ +

Flush video frames from internal cache of frames into a random order. +No frame is discarded. +Inspired by frei0r nervous filter. +

+
+
frames
+

Set size in number of frames of internal cache, in range from 2 to +512. Default is 30. +

+
+
seed
+

Set seed for random number generator, must be an integer included between +0 and UINT32_MAX. If not specified, or if explicitly set to +less than 0, the filter will try to use a good random seed on a +best effort basis. +

+
+ + +

30.207 readeia608

+ +

Read closed captioning (EIA-608) information from the top lines of a video frame. +

+

This filter adds frame metadata for lavfi.readeia608.X.cc and +lavfi.readeia608.X.line, where X is the number of the identified line +with EIA-608 data (starting from 0). A description of each metadata value follows: +

+
+
lavfi.readeia608.X.cc
+

The two bytes stored as EIA-608 data (printed in hexadecimal). +

+
+
lavfi.readeia608.X.line
+

The number of the line on which the EIA-608 data was identified and read. +

+
+ +

This filter accepts the following options: +

+
+
scan_min
+

Set the line to start scanning for EIA-608 data. Default is 0. +

+
+
scan_max
+

Set the line to end scanning for EIA-608 data. Default is 29. +

+
+
spw
+

Set the ratio of width reserved for sync code detection. +Default is 0.27. Allowed range is [0.1 - 0.7]. +

+
+
chp
+

Enable checking the parity bit. In the event of a parity error, the filter will output +0x00 for that character. Default is false. +

+
+
lp
+

Lowpass lines prior to further processing. Default is enabled. +

+
+ + +

30.207.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.207.2 Examples

+ +
    +
  • Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. +
    +
    ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv
    +
    +
+ + +

30.208 readvitc

+ +

Read vertical interval timecode (VITC) information from the top lines of a +video frame. +

+

The filter adds frame metadata key lavfi.readvitc.tc_str with the +timecode value, if a valid timecode has been detected. Further metadata key +lavfi.readvitc.found is set to 0/1 depending on whether +timecode data has been found or not. +

+

This filter accepts the following options: +

+
+
scan_max
+

Set the maximum number of lines to scan for VITC data. If the value is set to +-1 the full video frame is scanned. Default is 45. +

+
+
thr_b
+

Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], +default value is 0.2. The value must be equal or less than thr_w. +

+
+
thr_w
+

Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], +default value is 0.6. The value must be equal or greater than thr_b. +

+
+ + +

30.208.1 Examples

+ +
    +
  • Detect and draw VITC data onto the video frame; if no valid VITC is detected, +draw --:--:--:-- as a placeholder: +
    +
    ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--}:x=(w-tw)/2:y=400-ascent'
    +
    +
+ + +

30.209 remap

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 16bit depth, single channel. +

+
+
format
+

Specify pixel format of output from this filter. Can be color or gray. +Default is color. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

30.210 removegrain

+ +

The removegrain filter is a spatial denoiser for progressive video. +

+
+
m0
+

Set mode for the first plane. +

+
+
m1
+

Set mode for the second plane. +

+
+
m2
+

Set mode for the third plane. +

+
+
m3
+

Set mode for the fourth plane. +

+
+ +

Range of mode is from 0 to 24. Description of each mode follows: +

+
+
0
+

Leave input plane unchanged. Default. +

+
+
1
+

Clips the pixel with the minimum and maximum of the 8 neighbour pixels. +

+
+
2
+

Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. +

+
+
3
+

Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. +

+
+
4
+

Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. +This is equivalent to a median filter. +

+
+
5
+

Line-sensitive clipping giving the minimal change. +

+
+
6
+

Line-sensitive clipping, intermediate. +

+
+
7
+

Line-sensitive clipping, intermediate. +

+
+
8
+

Line-sensitive clipping, intermediate. +

+
+
9
+

Line-sensitive clipping on a line where the neighbours pixels are the closest. +

+
+
10
+

Replaces the target pixel with the closest neighbour. +

+
+
11
+

[1 2 1] horizontal and vertical kernel blur. +

+
+
12
+

Same as mode 11. +

+
+
13
+

Bob mode, interpolates top field from the line where the neighbours +pixels are the closest. +

+
+
14
+

Bob mode, interpolates bottom field from the line where the neighbours +pixels are the closest. +

+
+
15
+

Bob mode, interpolates top field. Same as 13 but with a more complicated +interpolation formula. +

+
+
16
+

Bob mode, interpolates bottom field. Same as 14 but with a more complicated +interpolation formula. +

+
+
17
+

Clips the pixel with the minimum and maximum of respectively the maximum and +minimum of each pair of opposite neighbour pixels. +

+
+
18
+

Line-sensitive clipping using opposite neighbours whose greatest distance from +the current pixel is minimal. +

+
+
19
+

Replaces the pixel with the average of its 8 neighbours. +

+
+
20
+

Averages the 9 pixels ([1 1 1] horizontal and vertical blur). +

+
+
21
+

Clips pixels using the averages of opposite neighbour. +

+
+
22
+

Same as mode 21 but simpler and faster. +

+
+
23
+

Small edge and halo removal, but reputed useless. +

+
+
24
+

Similar as 23. +

+
+ + +

30.211 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. +

+

The filter accepts the following options: +

+
+
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. +

+
+ +

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 +the logo. If you use white (255) for the logo and black (0) for the +rest, you will be safe. For making the filter bitmap, it is +recommended to take a screen capture of a black frame with the logo +visible, and then using a threshold filter followed by the erode +filter once or twice. +

+

If needed, little splotches can be fixed manually. Remember that if +logo pixels are not covered, the filter quality will be much +reduced. Marking too many pixels as part of the logo does not hurt as +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. +

+ +

30.212 repeatfields

+ +

This filter uses the repeat_field flag from the Video ES headers and hard repeats +fields based on its value. +

+ +

30.213 reverse

+ +

Reverse a video clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

30.213.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    trim=end=5,reverse
    +
    +
+ + +

30.214 rgbashift

+

Shift R/G/B/A pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
rh
+

Set amount to shift red horizontally. +

+
rv
+

Set amount to shift red vertically. +

+
gh
+

Set amount to shift green horizontally. +

+
gv
+

Set amount to shift green vertically. +

+
bh
+

Set amount to shift blue horizontally. +

+
bv
+

Set amount to shift blue vertically. +

+
ah
+

Set amount to shift alpha horizontally. +

+
av
+

Set amount to shift alpha vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

30.214.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.215 roberts

+

Apply roberts cross operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

30.215.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.216 rotate

+ +

Rotate video by an arbitrary angle expressed in radians. +

+

The filter accepts the following options: +

+

A description of the optional parameters follows. +

+
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. +

+
+
out_w, ow
+

Set the output width expression, default value is "iw". +This expression is evaluated just once during configuration. +

+
+
out_h, oh
+

Set the output height expression, default value is "ih". +This expression is evaluated just once during configuration. +

+
+
bilinear
+

Enable bilinear interpolation if set to 1, a value of 0 disables +it. Default value is 1. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the rotated +image. For the general syntax 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". +

+
+ +

The expressions for the angle and the output size can contain the +following constants and functions: +

+
+
n
+

sequential number of the input frame, starting from 0. It is always NAN +before the first frame is filtered. +

+
+
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. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_w, iw
+
in_h, ih
+

the input video width and height +

+
+
out_w, ow
+
out_h, oh
+

the output width and height, that is the size of the padded area as +specified by the width and height expressions +

+
+
rotw(a)
+
roth(a)
+

the minimal width/height required for completely containing the input +video rotated by a radians. +

+

These are only available when computing the out_w and +out_h expressions. +

+
+ + +

30.216.1 Examples

+ +
    +
  • Rotate the input by PI/6 radians clockwise: +
    +
    rotate=PI/6
    +
    + +
  • Rotate the input by PI/6 radians counter-clockwise: +
    +
    rotate=-PI/6
    +
    + +
  • Rotate the input by 45 degrees clockwise: +
    +
    rotate=45*PI/180
    +
    + +
  • Apply a constant rotation with period T, starting from an angle of PI/3: +
    +
    rotate=PI/3+2*PI*t/T
    +
    + +
  • Make the input video rotation oscillating with a period of T +seconds and an amplitude of A radians: +
    +
    rotate=A*sin(2*PI/T*t)
    +
    + +
  • Rotate the video, output size is chosen so that the whole rotating +input video is always completely contained in the output: +
    +
    rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
    +
    + +
  • Rotate the video, reduce the output size so that no background is ever +shown: +
    +
    rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
    +
    +
+ + +

30.216.2 Commands

+ +

The filter supports the following commands: +

+
+
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. +

+
+ + +

30.217 sab

+ +

Apply Shape Adaptive Blur. +

+

The filter accepts the following options: +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
chroma_radius, cr
+

Set chroma blur filter strength, must be a value in range -0.9-4.0. A +greater value will result in a more blurred image, and in slower +processing. +

+
+
chroma_pre_filter_radius, cpfr
+

Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. +

+
+
chroma_strength, cs
+

Set chroma maximum difference between pixels to still be considered, +must be a value in the -0.9-100.0 range. +

+
+ +

Each chroma option value, if not explicitly specified, is set to the +corresponding luma option value. +

+ +

30.218 scale

+ +

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. +

+

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. +

+ +

30.218.1 Options

+

The filter accepts the following options, any of the options supported +by the libswscale scaler, as well as any of the framesync options. +

+

See the ffmpeg-scaler manual for +the complete list of scaler options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the scale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+ +
+
interl
+

Set the interlacing mode. It accepts the following values: +

+
+
‘1’
+

Force interlaced aware scaling. +

+
+
‘0’
+

Do not apply interlaced scaling. +

+
+
‘-1’
+

Select interlaced aware scaling depending on whether the source frames +are flagged as interlaced or not. +

+
+ +

Default value is ‘0’. +

+
+
flags
+

Set libswscale scaling flags. See +the ffmpeg-scaler manual for the +complete list of values. If not explicitly specified the filter applies +the default flags. +

+ +
+
param0, param1
+

Set libswscale input parameters for scaling algorithms that need them. See +the ffmpeg-scaler manual for the +complete documentation. If not explicitly specified the filter applies +empty parameters. +

+
+
intent
+

Set the ICC rendering intent to use when transforming between different color +spaces. It accepts the following values: +

+
+
‘perceptual’
+

Use a perceptually guided tone and gamut mapping curve. The exact details of +the mapping used may change at any time and should not be relied on as stable. +This intent is recommended for final viewing of image/video content in typical +viewing settings. +

+
+
‘relative_colorimetric’
+

Statically clip out-of-gamut colors using a colorimetric clipping curve which +attempts to find the colorimetrically least dissimilar in-gamut color. This +intent performs white point adaptation and black point adaptation. This is +the default. This intent is recommended wherever faithful color reproduction +is of the utmost importance, even at the cost of clipping. +

+
+
‘absolute_colorimetric’
+

Hard clip out-of-gamut colors with no attempt at white or black point +reproduction. This intent will reproduce in-gamut colors 1:1 on the output +display as they would appear on the reference display, assuming the output +display is appropriately calibrated. +

+
+
‘saturation’
+

Performs saturation mapping - that is, stretches the input color volume +directly onto the output color volume, in non-linear fashion that preserves the +original signal appearance as much as possible. This intent is recommended for +signal content evaluation, as it will not lead to any clipping. It is roughly +analogous to not performing any color mapping, although it still takes into +account the mastering display primaries and any differences in encoding TRC. +

+
+ +
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
in_color_matrix
+
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: +

+
+
‘auto’
+

Choose automatically. +

+
+
‘bt709’
+

Format conforming to International Telecommunication Union (ITU) +Recommendation BT.709. +

+
+
‘fcc’
+

Set color space conforming to the United States Federal Communications +Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). +

+
+
‘bt601’
+
‘bt470’
+
‘smpte170m’
+

Set color space conforming to: +

+
    +
  • ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 + +
  • ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G + +
  • Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 + +
+ +
+
‘smpte240m’
+

Set color space conforming to SMPTE ST 240:1999. +

+
+
‘bt2020’
+

Set color space conforming to ITU-R BT.2020 non-constant luminance system. +

+
+ +
+
in_range
+
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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
in_chroma_loc
+
out_chroma_loc
+

Set in/output chroma sample location. If not specified, center-sited chroma +is used by default. Possible values: +

+
+
‘auto, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
in_primaries
+
out_primaries
+

Set in/output RGB primaries. +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
‘ebu3213’
+
+ +
+
in_transfer
+
out_transfer
+

Set in/output transfer response curve (TRC). +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘gamma22’
+
‘bt470bg’
+
‘gamma28’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘iec61966-2-1’
+
‘srgb’
+
‘iec61966-2-4’
+
‘xvycc’
+
‘bt1361e’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Enabling this option leads to the output SAR being reset to 1. +Additionally, if the user requests proportional scaling either +through the width or height expressions, e.g. w=-4:h=360 or w=iw/2:h=-1 +or by enabling force_original_aspect_ratio, then the input DAR is taken into +account and the output is scaled to produce square pixels. +Default is false. +

+
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+
ref_w, rw
+
ref_h, rh
+
ref_a
+
ref_dar, rdar
+
ref_n
+
ref_t
+
ref_pos
+

Eqvuialent to the above, but for a second reference input. If any of these +variables are present, this filter accepts two inputs. +

+
+ + +

30.218.2 Examples

+ +
    +
  • Scale the input video to a size of 200x100 +
    +
    scale=w=200:h=100
    +
    + +

    This is equivalent to: +

    +
    scale=200:100
    +
    + +

    or: +

    +
    scale=200x100
    +
    + +
  • Specify a size abbreviation for the output size: +
    +
    scale=qcif
    +
    + +

    which can also be written as: +

    +
    scale=size=qcif
    +
    + +
  • Scale the input to 2x: +
    +
    scale=w=2*iw:h=2*ih
    +
    + +
  • The above is the same as: +
    +
    scale=2*in_w:2*in_h
    +
    + +
  • Scale the input to 2x with forced interlaced scaling: +
    +
    scale=2*iw:2*ih:interl=1
    +
    + +
  • Scale the input to half size: +
    +
    scale=w=iw/2:h=ih/2
    +
    + +
  • Increase the width, and set the height to the same size: +
    +
    scale=3/2*iw:ow
    +
    + +
  • Seek Greek harmony: +
    +
    scale=iw:1/PHI*iw
    +scale=ih*PHI:ih
    +
    + +
  • Increase the height, and set the width to 3/2 of the height: +
    +
    scale=w=3/2*oh:h=3/5*ih
    +
    + +
  • Increase the size, making the size a multiple of the chroma +subsample values: +
    +
    scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
    +
    + +
  • Increase the width to a maximum of 500 pixels, +keeping the same aspect ratio as the input: +
    +
    scale=w='min(500\, iw*3/2):h=-1'
    +
    + +
  • Make pixels square by combining scale and setsar: +
    +
    scale='trunc(ih*dar):ih',setsar=1/1
    +
    + +
  • Make pixels square using reset_sar, +making sure the resulting resolution is even (required by some codecs): +
    +
    scale='-2:ih-mod(ih,2):reset_sar=1'
    +
    + +
  • Scale to target exactly, however reset SAR to 1: +
    +
    scale='400:300:reset_sar=1'
    +
    + +
  • Scale to even dimensions that fit within 400x300, preserving input SAR: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2'
    +
    + +
  • Scale to produce square pixels with even dimensions that fit within 400x300: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2:reset_sar=1'
    +
    + +
  • Scale a subtitle stream (sub) to match the main video (main) in size before +overlaying. ("scale2ref") +
    +
    '[main]split[a][b]; [ref][a]scale=rw:rh[c]; [b][c]overlay'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display +aspect ratio. +
    +
    [logo-in][video-in]scale=w=oh*dar:h=rh/10[logo-out]
    +
    +
+ + +

30.218.3 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + +

30.219 scharr

+

Apply scharr operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

30.219.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.220 scroll

+

Scroll input video horizontally and/or vertically by constant speed. +

+

The filter accepts the following options: +

+
horizontal, h
+

Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
vertical, v
+

Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
hpos
+

Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+
vpos
+

Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+ + +

30.220.1 Commands

+ +

This filter supports the following commands: +

+
horizontal, h
+

Set the horizontal scrolling speed. +

+
vertical, v
+

Set the vertical scrolling speed. +

+
+ + +

30.221 scdet

+ +

Detect video scene change. +

+

This filter sets frame metadata with mafd between frame, the scene score, and +forward the frame to the next filter, so they can use these metadata to detect +scene change or others. +

+

In addition, this filter logs a message and sets frame metadata when it detects +a scene change by threshold. +

+

lavfi.scd.mafd metadata keys are set with mafd for every frame. +

+

lavfi.scd.score metadata keys are set with scene change score for every frame +to detect scene change. +

+

lavfi.scd.time metadata keys are set with current filtered frame time which +detect scene change with threshold. +

+

The filter accepts the following options: +

+
+
threshold, t
+

Set the scene change detection threshold as a percentage of maximum change. Good +values are in the [8.0, 14.0] range. The range for threshold is +[0., 100.]. +

+

Default value is 10.. +

+
+
sc_pass, s
+

Set the flag to pass scene change frames to the next filter. Default value is 0 +You can enable it if you want to get snapshot of scene change frames only. +

+
+ + +

30.222 selectivecolor

+ +

Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such +as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined +by the "purity" of the color (that is, how saturated it already is). +

+

This filter is similar to the Adobe Photoshop Selective Color tool. +

+

The filter accepts the following options: +

+
+
correction_method
+

Select color correction method. +

+

Available values are: +

+
‘absolute’
+

Specified adjustments are applied "as-is" (added/subtracted to original pixel +component value). +

+
‘relative’
+

Specified adjustments are relative to the original component value. +

+
+

Default is absolute. +

+
reds
+

Adjustments for red pixels (pixels where the red component is the maximum) +

+
yellows
+

Adjustments for yellow pixels (pixels where the blue component is the minimum) +

+
greens
+

Adjustments for green pixels (pixels where the green component is the maximum) +

+
cyans
+

Adjustments for cyan pixels (pixels where the red component is the minimum) +

+
blues
+

Adjustments for blue pixels (pixels where the blue component is the maximum) +

+
magentas
+

Adjustments for magenta pixels (pixels where the green component is the minimum) +

+
whites
+

Adjustments for white pixels (pixels where all components are greater than 128) +

+
neutrals
+

Adjustments for all pixels except pure black and pure white +

+
blacks
+

Adjustments for black pixels (pixels where all components are lesser than 128) +

+
psfile
+

Specify a Photoshop selective color file (.asv) to import the settings from. +

+
+ +

All the adjustment settings (reds, yellows, ...) accept up to +4 space separated floating point adjustment values in the [-1,1] range, +respectively to adjust the amount of cyan, magenta, yellow and black for the +pixels of its range. +

+ +

30.222.1 Examples

+ +
    +
  • Increase cyan by 50% and reduce yellow by 33% in every green areas, and +increase magenta by 27% in blue areas: +
    +
    selectivecolor=greens=.5 0 -.33 0:blues=0 .27
    +
    + +
  • Use a Photoshop selective color preset: +
    +
    selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
    +
    +
+ + +

30.223 separatefields

+ +

The 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 setfield filter before separatefields filter. +

+ +

30.224 setdar, setsar

+ +

The setdar filter sets the Display Aspect Ratio for the filter +output video. +

+

This is done by changing the specified Sample (aka Pixel) Aspect +Ratio, according to the following equation: +

+
DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR
+
+ +

Keep in mind that the setdar filter does not modify the pixel +dimensions of the video frame. Also, the display aspect ratio set by +this filter may be changed by later filters in the filterchain, +e.g. in case of scaling or if another "setdar" or a "setsar" filter is +applied. +

+

The setsar filter sets the Sample (aka Pixel) Aspect Ratio for +the filter output video. +

+

Note that as a consequence of the application of this filter, the +output display aspect ratio will change according to the equation +above. +

+

Keep in mind that the sample aspect ratio set by the setsar +filter may be changed by later filters in the filterchain, e.g. if +another "setsar" or a "setdar" filter is applied. +

+

It accepts the following parameters: +

+
+
r, ratio, dar (setdar only), sar (setsar only)
+

Set the aspect ratio used by the filter. +

+

The parameter can be a floating point number string, or an expression. If the +parameter is not specified, the value "0" is assumed, meaning that the same +input value is used. +

+
+
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 100. +

+
+
+ +

The parameter sar is an expression containing the following constants: +

+
+
w, h
+

The input width and height. +

+
+
a
+

Same as w / h. +

+
+
sar
+

The input sample aspect ratio. +

+
+
dar
+

The input display aspect ratio. It is the same as +(w / h) * sar. +

+
+
hsub, vsub
+

Horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

30.224.1 Examples

+ +
    +
  • To change the display aspect ratio to 16:9, specify one of the following: +
    +
    setdar=dar=1.77777
    +setdar=dar=16/9
    +
    + +
  • To change the sample aspect ratio to 10:11, specify: +
    +
    setsar=sar=10/11
    +
    + +
  • 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: +
    +
    setdar=ratio=16/9:max=1000
    +
    + +
+ + +

30.225 setfield

+ +

Force field for the output video frame. +

+

The setfield filter marks the interlace type field for the +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. fieldorder or yadif). +

+

The filter accepts the following options: +

+
+
mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property. +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+
+
+ + +

30.226 setparams

+ +

Force frame parameter for the output video frame. +

+

The setparams filter marks interlace and color range for the +output frames. It does not change the input frame, but only sets the +corresponding property, which affects how the frame is treated by +filters/encoders. +

+
+
field_mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property (default). +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+ +
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property (default). +

+
+
‘unspecified, unknown’
+

Mark the frame as unspecified color range. +

+
+
‘limited, tv, mpeg’
+

Mark the frame as limited range. +

+
+
‘full, pc, jpeg’
+

Mark the frame as full range. +

+
+ +
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
+ +
+
color_trc
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same color trc property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘log100’
+
‘log316’
+
‘iec61966-2-4’
+
‘bt1361e’
+
‘iec61966-2-1’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
colorspace
+

Set the colorspace. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘gbr’
+
‘bt709’
+
‘unknown’
+
‘fcc’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘ycgco’
+
‘bt2020nc’
+
‘bt2020c’
+
‘smpte2085’
+
‘chroma-derived-nc’
+
‘chroma-derived-c’
+
‘ictcp’
+
+ +
+
chroma_location
+

Set the chroma sample location. +Available values are: +

+
+
‘auto’
+

Keep the same chroma location (default). +

+
+
‘unspecified, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode
+

Set the alpha moda. +Available values are: +

+
+
‘auto’
+

Keep the same alpha mode (default). +

+
+
‘unspecified, unknown’
+
‘premultiplied’
+
‘straight’
+
+
+
+ + +

30.227 shear

+

Apply shear transform to input video. +

+

This filter supports the following options: +

+
+
shx
+

Shear factor in X-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
shy
+

Shear factor in Y-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the transformed +video. For the general syntax 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". +

+
+
interp
+

Set interpolation type. Can be bilinear or nearest. Default is bilinear. +

+
+ + +

30.227.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.228 showinfo

+ +

Show a line containing various information for each input video frame. +The input video is not modified. +

+

This filter supports the following options: +

+
+
checksum
+

Calculate checksums of each plane. By default enabled. +

+
+
udu_sei_as_ascii
+

Try to print user data unregistered SEI as ascii character when possible, +in hex format otherwise. +

+
+ +

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The Presentation TimeStamp of the input frame, expressed as a number of +time base units. The time base unit depends on the filter input pad. +

+
+
pts_time
+

The Presentation TimeStamp of the input frame, expressed as a number of +seconds. +

+
+
fmt
+

The pixel format name. +

+
+
sar
+

The sample aspect ratio of the input frame, expressed in the form +num/den. +

+
+
s
+

The size of the input frame. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
i
+

The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" +for bottom field first). +

+
+
iskey
+

This is 1 if the frame is a key frame, 0 otherwise. +

+
+
type
+

The picture type of the input frame ("I" for an I-frame, "P" for a +P-frame, "B" for a B-frame, or "?" for an unknown type). +Also refer to the documentation of the AVPictureType enum and of +the av_get_picture_type_char function defined in +libavutil/avutil.h. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. +

+
+
plane_checksum
+

The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, +expressed in the form "[c0 c1 c2 c3]". +

+
+
mean
+

The mean value of pixels in each plane of the input frame, expressed in the form +"[mean0 mean1 mean2 mean3]". +

+
+
stdev
+

The standard deviation of pixel values in each plane of the input frame, expressed +in the form "[stdev0 stdev1 stdev2 stdev3]". +

+
+
+ + +

30.229 showpalette

+ +

Displays the 256 colors palette of each frame. This filter is only relevant for +pal8 pixel format frames. +

+

It accepts the following option: +

+
+
s
+

Set the size of the box used to represent one palette color entry. Default is +30 (for a 30x30 pixel box). +

+
+ + +

30.230 shuffleframes

+ +

Reorder and/or duplicate and/or drop video frames. +

+

It accepts the following parameters: +

+
+
mapping
+

Set the destination indexes of input frames. +This is space or ’|’ separated list of indexes that maps input frames to output +frames. Number of indexes also sets maximal value that each index may have. +’-1’ index have special meaning and that is to drop frame. +

+
+ +

The first frame has the index 0. The default is to keep the input unchanged. +

+ +

30.230.1 Examples

+ +
    +
  • Swap second and third frame of every three frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
    +
    + +
  • Swap 10th and 1st frame of every ten frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
    +
    +
+ + +

30.231 shufflepixels

+ +

Reorder pixels in video frames. +

+

This filter accepts the following options: +

+
+
direction, d
+

Set shuffle direction. Can be forward or inverse direction. +Default direction is forward. +

+
+
mode, m
+

Set shuffle mode. Can be horizontal, vertical or block mode. +

+
+
width, w
+
height, h
+

Set shuffle block_size. In case of horizontal shuffle mode only width +part of size is used, and in case of vertical shuffle mode only height +part of size is used. +

+
+
seed, s
+

Set random seed used with shuffling pixels. Mainly useful to set to be able +to reverse filtering process to get original input. +For example, to reverse forward shuffle you need to use same parameters +and exact same seed and to set direction to inverse. +

+
+ + +

30.232 shuffleplanes

+ +

Reorder and/or duplicate video planes. +

+

It accepts the following parameters: +

+
+
map0
+

The index of the input plane to be used as the first output plane. +

+
+
map1
+

The index of the input plane to be used as the second output plane. +

+
+
map2
+

The index of the input plane to be used as the third output plane. +

+
+
map3
+

The index of the input plane to be used as the fourth output plane. +

+
+
+ +

The first plane has the index 0. The default is to keep the input unchanged. +

+ +

30.232.1 Examples

+ +
    +
  • Swap the second and third planes of the input: +
    +
    ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
    +
    +
+ + +

30.233 signalstats

+

Evaluate various visual metrics that assist in determining issues associated +with the digitization of analog video media. +

+

By default the filter will log these metadata values: +

+
+
YMIN
+

Display the minimal Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
YLOW
+

Display the Y value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YAVG
+

Display the average Y value within the input frame. Expressed in range of +[0-255]. +

+
+
YHIGH
+

Display the Y value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YMAX
+

Display the maximum Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
UMIN
+

Display the minimal U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
ULOW
+

Display the U value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UAVG
+

Display the average U value within the input frame. Expressed in range of +[0-255]. +

+
+
UHIGH
+

Display the U value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UMAX
+

Display the maximum U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VMIN
+

Display the minimal V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VLOW
+

Display the V value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VAVG
+

Display the average V value within the input frame. Expressed in range of +[0-255]. +

+
+
VHIGH
+

Display the V value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VMAX
+

Display the maximum V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
SATMIN
+

Display the minimal saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATLOW
+

Display the saturation value at the 10% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATAVG
+

Display the average saturation value within the input frame. Expressed in range +of [0-~181.02]. +

+
+
SATHIGH
+

Display the saturation value at the 90% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATMAX
+

Display the maximum saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
HUEMED
+

Display the median value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
HUEAVG
+

Display the average value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
YDIF
+

Display the average of sample value difference between all values of the Y +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
UDIF
+

Display the average of sample value difference between all values of the U +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
VDIF
+

Display the average of sample value difference between all values of the V +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
YBITDEPTH
+

Display bit depth of Y plane in current frame. +Expressed in range of [0-16]. +

+
+
UBITDEPTH
+

Display bit depth of U plane in current frame. +Expressed in range of [0-16]. +

+
+
VBITDEPTH
+

Display bit depth of V plane in current frame. +Expressed in range of [0-16]. +

+
+ +

The filter accepts the following options: +

+
+
stat
+
out
+
+

stat specify an additional form of image analysis. +out output video with the specified type of pixel highlighted. +

+

Both options accept the following values: +

+
+
‘tout’
+

Identify temporal outliers pixels. A temporal outlier is a pixel +unlike the neighboring pixels of the same field. Examples of temporal outliers +include the results of video dropouts, head clogs, or tape tracking issues. +

+
+
‘vrep’
+

Identify vertical line repetition. Vertical line repetition includes +similar rows of pixels within a frame. In born-digital video vertical line +repetition is common, but this pattern is uncommon in video digitized from an +analog source. When it occurs in video that results from the digitization of an +analog source it can indicate concealment from a dropout compensator. +

+
+
‘brng’
+

Identify pixels that fall outside of legal broadcast range. +

+
+ +
+
color, c
+

Set the highlight color for the out option. The default color is +yellow. +

+
+ + +

30.233.1 Examples

+ +
    +
  • Output data of various video metrics: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
    +
    + +
  • Output specific data about the minimum and maximum values of the Y plane per frame: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
    +
    + +
  • Playback video while highlighting pixels that are outside of broadcast range in red. +
    +
    ffplay example.mov -vf signalstats="out=brng:color=red"
    +
    + +
  • Playback video with signalstats metadata drawn over the frame. +
    +
    ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
    +
    + +

    The contents of signalstat_drawtext.txt used in the command are: +

    +
    time %{pts:hms}
    +Y (%{metadata:lavfi.signalstats.YMIN}-%{metadata:lavfi.signalstats.YMAX})
    +U (%{metadata:lavfi.signalstats.UMIN}-%{metadata:lavfi.signalstats.UMAX})
    +V (%{metadata:lavfi.signalstats.VMIN}-%{metadata:lavfi.signalstats.VMAX})
    +saturation maximum: %{metadata:lavfi.signalstats.SATMAX}
    +
    +
    +
+ + +

30.234 signature

+ +

Calculates the MPEG-7 Video Signature. The filter can handle more than one +input. In this case the matching between the inputs can be calculated additionally. +The filter always passes through the first input. The signature of each stream can +be written into a file. +

+

It accepts the following options: +

+
+
detectmode
+

Enable or disable the matching process. +

+

Available values are: +

+
+
‘off’
+

Disable the calculation of a matching (default). +

+
‘full’
+

Calculate the matching for the whole video and output whether the whole video +matches or only parts. +

+
‘fast’
+

Calculate only until a matching is found or the video ends. Should be faster in +some cases. +

+
+ +
+
nb_inputs
+

Set the number of inputs. The option value must be a non negative integer. +Default value is 1. +

+
+
filename
+

Set the path to which the output is written. If there is more than one input, +the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive +integer), that will be replaced with the input number. If no filename is +specified, no output will be written. This is the default. +

+
+
format
+

Choose the output format. +

+

Available values are: +

+
+
‘binary’
+

Use the specified binary representation (default). +

+
‘xml’
+

Use the specified xml representation. +

+
+ +
+
th_d
+

Set threshold to detect one word as similar. The option value must be an integer +greater than zero. The default value is 9000. +

+
+
th_dc
+

Set threshold to detect all words as similar. The option value must be an integer +greater than zero. The default value is 60000. +

+
+
th_xh
+

Set threshold to detect frames as similar. The option value must be an integer +greater than zero. The default value is 116. +

+
+
th_di
+

Set the minimum length of a sequence in frames to recognize it as matching +sequence. The option value must be a non negative integer value. +The default value is 0. +

+
+
th_it
+

Set the minimum relation, that matching frames to all frames must have. +The option value must be a double value between 0 and 1. The default value is 0.5. +

+
+ + +

30.234.1 Examples

+ +
    +
  • To calculate the signature of an input video and store it in signature.bin: +
    +
    ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
    +
    + +
  • To detect whether two videos match and store the signatures in XML format in +signature0.xml and signature1.xml: +
    +
    ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -
    +
    + +
+ + +

30.235 siti

+ +

Calculate Spatial Information (SI) and Temporal Information (TI) scores for a video, +as defined in ITU-T Rec. P.910 (11/21): Subjective video quality assessment methods +for multimedia applications. Available PDF at https://www.itu.int/rec/T-REC-P.910-202111-S/en. +Note that this is a legacy implementation that corresponds to a superseded recommendation. +Refer to ITU-T Rec. P.910 (07/22) for the latest version: https://www.itu.int/rec/T-REC-P.910-202207-I/en +

+

It accepts the following option: +

+
+
print_summary
+

If set to 1, Summary statistics will be printed to the console. Default 0. +

+
+ + +

30.235.1 Examples

+
    +
  • To calculate SI/TI metrics and print summary: +
    +
    ffmpeg -i input.mp4 -vf siti=print_summary=1 -f null -
    +
    +
+ + +

30.236 smartblur

+ +

Blur the input video without impacting the outlines. +

+

It accepts the following options: +

+
+
luma_radius, lr
+

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. +

+
+
luma_strength, ls
+

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. +

+
+
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. +

+
+
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 luma_radius. +

+
+
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 luma_strength. +

+
+
chroma_threshold, ct
+

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 +in [-30,0] will filter edges. Default value is luma_threshold. +

+
+
alpha_radius, ar
+

Set the alpha 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 luma_radius. +

+
+
alpha_strength, as
+

Set the alpha 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 luma_strength. +

+
+
alpha_threshold, at
+

Set the alpha 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 luma_threshold. +

+
+ +

If a chroma or alpha option is not explicitly set, the corresponding luma value +is set. +

+ +

30.237 sobel

+

Apply sobel operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

30.237.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.238 spp

+ +

Apply a simple postprocessing filter that compresses and decompresses the image +at several (or - in the case of quality level 6 - all) shifts +and average the results. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-6. If set to 0, the filter will have no +effect. A value of 6 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding (default). +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
+ +
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+ + +

30.238.1 Commands

+ +

This filter supports the following commands: +

+
quality, level
+

Set quality level. The value max can be used to set the maximum level, +currently 6. +

+
+ + +

30.239 sr

+ +

Scale the input by applying one of the super-resolution methods based on +convolutional neural networks. Supported models: +

+ + +

Training scripts as well as scripts for model file (.pb) saving can be found at +https://github.com/XueweiMeng/sr/tree/sr_dnn_native. Original repository +is at https://github.com/HighVoltageRocknRoll/sr.git. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO backend +can load files for only its format. +

+
+
scale_factor
+

Set scale factor for SRCNN model. Allowed values are 2, 3 and 4. +Default value is 2. Scale factor is necessary for SRCNN model, because it accepts +input upscaled using bicubic upscaling with proper scale factor. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

30.240 sr_amf

+ +

Upscale (size increasing) for the input video using AMD Advanced Media Framework library for hardware acceleration. +Use advanced algorithms for upscaling with higher output quality. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
algorithm
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+
+
sr1-0
+

Video SR1.0 +This is a default value +

+
+
point
+

Point +

+
+
sr1-1
+

Video SR1.1 +

+
+
+ +
+
sharpness
+

Control hq scaler sharpening. The value is a float in the range of [0.0, 2.0] +

+
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+
+
keep-ratio
+

Force the scaler to keep the aspect ratio of the input image when the output size has a different aspect ratio. +Default value is false. +

+
+
fill
+

Specifies whether the output image outside the region of interest, +which does not fill the entire output surface should be filled with a solid color. +

+
+
+ + +

30.240.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    sr_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K with algorithm video SR1.1. +
    +
    sr_amf=4096:2160:algorithm=sr1-1
    +
    +
+ + +

30.241 ssim

+ +

Obtain the SSIM (Structural SImilarity Metric) 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 SSIM. +

+

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 filter stores the calculated SSIM of each frame. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the SSIM of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+ +

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

A description of each shown parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
Y, U, V, R, G, B
+

SSIM of the compared frames for the component specified by the suffix. +

+
+
All
+

SSIM of the compared frames for the whole frame. +

+
+
dB
+

Same as above but in dB representation. +

+
+ +

This filter also supports the framesync options. +

+ +

30.241.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] ssim="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The SSIM of each individual frame +is stored in stats.log. +

    +
  • Another example with both psnr and ssim at same time: +
    +
    ffmpeg -i main.mpg -i ref.mpg -lavfi  "ssim;[0:v][1:v]psnr" -f null -
    +
    + +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -
    +
    +
+ + +

30.242 stereo3d

+ +

Convert between different stereoscopic image formats. +

+

The filters accept the following options: +

+
+
in
+

Set stereoscopic image format of input. +

+

Available values for input image formats are: +

+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+

Default value is ‘sbsl’. +

+
+ +
+
out
+

Set stereoscopic image format of output. +

+
+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘arbg’
+

anaglyph red/blue gray +(red filter on left eye, blue filter on right eye) +

+
+
‘argg’
+

anaglyph red/green gray +(red filter on left eye, green filter on right eye) +

+
+
‘arcg’
+

anaglyph red/cyan gray +(red filter on left eye, cyan filter on right eye) +

+
+
‘arch’
+

anaglyph red/cyan half colored +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcc’
+

anaglyph red/cyan color +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcd’
+

anaglyph red/cyan color optimized with the least squares projection of dubois +(red filter on left eye, cyan filter on right eye) +

+
+
‘agmg’
+

anaglyph green/magenta gray +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmh’
+

anaglyph green/magenta half colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmc’
+

anaglyph green/magenta colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmd’
+

anaglyph green/magenta color optimized with the least squares projection of dubois +(green filter on left eye, magenta filter on right eye) +

+
+
‘aybg’
+

anaglyph yellow/blue gray +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybh’
+

anaglyph yellow/blue half colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybc’
+

anaglyph yellow/blue colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybd’
+

anaglyph yellow/blue color optimized with the least squares projection of dubois +(yellow filter on left eye, blue filter on right eye) +

+
+
‘ml’
+

mono output (left eye only) +

+
+
‘mr’
+

mono output (right eye only) +

+
+
‘chl’
+

checkerboard, left eye first +

+
+
‘chr’
+

checkerboard, right eye first +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+
+
‘hdmi’
+

HDMI frame pack +

+
+ +

Default value is ‘arcd’. +

+
+ + +

30.242.1 Examples

+ +
    +
  • Convert input video from side by side parallel to anaglyph yellow/blue dubois: +
    +
    stereo3d=sbsl:aybd
    +
    + +
  • Convert input video from above below (left eye above, right eye below) to side by side crosseye. +
    +
    stereo3d=abl:sbsr
    +
    +
+ + +

30.243 streamselect, astreamselect

+

Select video or audio streams. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. Default is 2. +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

30.243.1 Commands

+ +

The streamselect and astreamselect filter supports the following +commands: +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

30.243.2 Examples

+ +
    +
  • Select first 5 seconds 1st stream and rest of time 2nd stream: +
    +
    sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
    +
    + +
  • Same as above, but for audio: +
    +
    asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
    +
    +
+ + +

30.244 subtitles

+ +

Draw subtitles on top of input video using the libass library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libass. This filter also requires a build with libavcodec and +libavformat to convert the passed subtitles file to ASS (Advanced Substation +Alpha) subtitles format. +

+

The filter accepts the following options: +

+
+
filename, f
+

Set the filename of the subtitle file to read. It must be specified. +

+
+
original_size
+

Specify the size of the original video, the video for which the ASS file +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. +

+
+
fontsdir
+

Set a directory path containing fonts that can be used by the filter. +These fonts will be used in addition to whatever the font provider uses. +

+
+
alpha
+

Process alpha channel, by default alpha channel is untouched. +

+
+
charenc
+

Set subtitles input character encoding. subtitles filter only. Only +useful if not UTF-8. +

+
+
stream_index, si
+

Set subtitles stream index. subtitles filter only. +

+
+
force_style
+

Override default style or script info parameters of the subtitles. It accepts a +string containing ASS style format KEY=VALUE couples separated by ",". +

+
+
wrap_unicode
+

Break lines according to the Unicode Line Breaking Algorithm. Availability requires +at least libass release 0.17.0 (or LIBASS_VERSION 0x01600010), and libass must +have been built with libunibreak. +

+

The option is enabled by default except for native ASS. +

+
+ +

If the first key is not specified, it is assumed that the first value +specifies the filename. +

+

For example, to render the file sub.srt on top of the input +video, use the command: +

+
subtitles=sub.srt
+
+ +

which is equivalent to: +

+
subtitles=filename=sub.srt
+
+ +

To render the default subtitles stream from file video.mkv, use: +

+
subtitles=video.mkv
+
+ +

To render the second subtitles stream from that file, use: +

+
subtitles=video.mkv:si=1
+
+ +

To make the subtitles stream from sub.srt appear in 80% transparent blue +DejaVu Serif, use: +

+
subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
+
+ + +

30.245 super2xsai

+ +

Scale the input by 2x and smooth using the Super2xSaI (Scale and +Interpolate) pixel art scaling algorithm. +

+

Useful for enlarging pixel art images without reducing sharpness. +

+ +

30.246 swaprect

+ +

Swap two rectangular objects in video. +

+

This filter accepts the following options: +

+
+
w
+

Set object width. +

+
+
h
+

Set object height. +

+
+
x1
+

Set 1st rect x coordinate. +

+
+
y1
+

Set 1st rect y coordinate. +

+
+
x2
+

Set 2nd rect x coordinate. +

+
+
y2
+

Set 2nd rect y coordinate. +

+

All expressions are evaluated once for each frame. +

+
+ +

The all options are expressions containing the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
a
+

same as w / h +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+ + +

30.246.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.247 swapuv

+

Swap U & V plane. +

+ +

30.248 tblend

+

Blend successive video frames. +

+

See blend +

+ +

30.249 telecine

+ +

Apply telecine process to the video. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+ +
+
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
+
+ + +

30.250 thistogram

+ +

Compute and draw a color distribution histogram for the input video across time. +

+

Unlike histogram video filter which only shows histogram of single input frame +at certain time, this filter shows also past histograms of number of frames defined +by width option. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

The filter accepts the following options: +

+
+
width, w
+

Set width of single color component output. Default value is 0. +Value of 0 means width will be picked from input video. +This also set number of passed histograms to keep. +Allowed range is [0, 8192]. +

+
+
display_mode, d
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode, m
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components, c
+

Set what color components to display. +Default is 7. +

+
+
bgopacity, b
+

Set background opacity. Default is 0.9. +

+
+
envelope, e
+

Show envelope. Default is disabled. +

+
+
ecolor, ec
+

Set envelope color. Default is gold. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is replace. +

+
+ + +

30.251 threshold

+ +

Apply threshold effect to video stream. +

+

This filter needs four video streams to perform thresholding. +First stream is stream we are filtering. +Second stream is holding threshold values, third stream is holding min values, +and last, fourth stream is holding max values. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ +

For example if first stream pixel’s component value is less then threshold value +of pixel component from 2nd threshold stream, third stream value will picked, +otherwise fourth stream pixel component value will be picked. +

+

Using color source filter one can perform various types of thresholding: +

+ +

30.251.1 Commands

+ +

This filter supports the all options as commands. +

+ +

30.251.2 Examples

+ +
    +
  • Binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
    +
    + +
  • Inverted binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
    +
    + +
  • Truncate binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
    +
    + +
  • Threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
    +
    + +
  • Inverted threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
    +
    +
+ + +

30.252 thumbnail

+

Select the most representative frame in a given sequence of consecutive frames. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+
log
+

Set the log level to display picked frame stats. +Default is info. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

30.252.1 Examples

+ +
    +
  • Extract one picture each 50 frames: +
    +
    thumbnail=50
    +
    + +
  • Complete example of a thumbnail creation with ffmpeg: +
    +
    ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
    +
    +
+ + +

30.253 tile

+ +

Tile several successive frames together. +

+

The untile filter can do the reverse. +

+

The filter accepts the following options: +

+
+
layout
+

Set the grid size in the form COLUMNSxROWS. Range is up to UINT_MAX cells. +Default is 6x5. +

+
+
nb_frames
+

Set the maximum number of frames to render in the given area. It must be less +than or equal to wxh. The default value is 0, meaning all +the area will be used. +

+
+
margin
+

Set the outer border margin in pixels. Range is 0 to 1024. Default is 0. +

+
+
padding
+

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. Range is 0 to 1024. Default is 0. +

+
+
color
+

Specify the color of the unused area. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +The default value of color is "black". +

+
+
overlap
+

Set the number of frames to overlap when tiling several successive frames together. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+
init_padding
+

Set the number of frames to initially be empty before displaying first output frame. +This controls how soon will one get first output frame. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+ + +

30.253.1 Examples

+ +
    +
  • Produce 8x8 PNG tiles of all keyframes (-skip_frame nokey) in a movie: +
    +
    ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
    +
    +

    The -vsync 0 is necessary to prevent ffmpeg from +duplicating each output frame to accommodate the originally detected frame +rate. +

    +
  • Display 5 pictures in an area of 3x2 frames, +with 7 pixels between them, and 2 pixels of initial margin, using +mixed flat and named options: +
    +
    tile=3x2:nb_frames=5:padding=7:margin=2
    +
    +
+ + +

30.254 tiltandshift

+

Apply tilt-and-shift effect. +

+

What happens when you invert time and space? +

+

Normally a video is composed of several frames that represent a different +instant of time and shows a scene that evolves in the space captured by the +frame. This filter is the antipode of that concept, taking inspiration from +tilt and shift photography. +

+

A filtered frame contains the whole timeline of events composing the sequence, +and this is obtained by placing a slice of pixels from each frame into a single +one. However, since there are no infinite-width frames, this is done up the +width of the input frame, and a video is recomposed by shifting away one +column for each subsequent frame. In order to map space to time, the filter +tilts each input frame as well, so that motion is preserved. This is accomplished +by progressively selecting a different column from each input frame. +

+

The end result is a sort of inverted parallax, so that far away objects move +much faster that the ones in the front. The ideal conditions for this video +effect are when there is either very little motion and the background is static, +or when there is a lot of motion and a very wide depth of field (e.g. wide +panorama, while moving on a train). +

+

The filter accepts the following parameters: +

+
+
tilt
+

Tilt video while shifting (default). When unset, video will be sliding a +static image, composed of the first column of each frame. +

+
+
start
+

What to do at the start of filtering (see below). +

+
+
end
+

What to do at the end of filtering (see below). +

+
+
hold
+

How many columns should pass through before start of filtering. +

+
+
pad
+

How many columns should be inserted before end of filtering. +

+
+
+ +

Normally the filter shifts and tilts from the very first frame, and stops when +the last one is received. However, before filtering starts, normal video may +be preserved, so that the effect is slowly shifted in its place. Similarly, +the last video frame may be reconstructed at the end. Alternatively it is +possible to just start and end with black. +

+
+
‘none’
+

Filtering starts immediately and ends when the last frame is received. +

+
+
‘frame’
+

The first frames or the very last frame are kept intact during processing. +

+
+
‘black’
+

Black is padded at the beginning or at the end of filtering. +

+
+
+ + +

30.255 tinterlace

+ +

Perform various types of temporal field interlacing. +

+

Frames are counted starting from 1, so the first input frame is +considered odd. +

+

The filter accepts the following options: +

+
+
mode
+

Specify the mode of the interlacing. This option can also be specified +as a value alone. See below for a list of values for this option. +

+

Available values are: +

+
+
‘merge, 0’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at half frame rate. +

+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ +
+
‘drop_even, 1’
+

Only output odd frames, even frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+11111                           33333
+11111                           33333
+11111                           33333
+
+ +
+
‘drop_odd, 2’
+

Only output even frames, odd frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+                22222                           44444
+                22222                           44444
+                22222                           44444
+                22222                           44444
+
+ +
+
‘pad, 3’
+

Expand each frame to full height, but pad alternate lines with black, +generating a frame with double height at the same input frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+
+Output:
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+
+ + +
+
‘interlacex2, 6’
+

Double frame rate with unchanged height. Frames are inserted each +containing the second temporal field from the previous input frame and +the first temporal field from the next input frame. This mode relies on +the top_field_first flag. Useful for interlaced video displays with no +field synchronisation. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+
+Output:
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+
+ + +
+
‘mergex2, 7’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at same frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+
+ +
+
+ +

Numeric values are deprecated but are accepted for backward +compatibility reasons. +

+

Default mode is merge. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
low_pass_filter, vlpf
+

Enable linear vertical low-pass filtering in the filter. +Vertical low-pass filtering is required when creating an interlaced +destination from a progressive source which contains high-frequency +vertical detail. Filtering will reduce interlace ’twitter’ and Moire +patterning. +

+
+
complex_filter, cvlpf
+

Enable complex vertical low-pass filtering. +This will slightly less reduce interlace ’twitter’ and Moire +patterning but better retain detail and subjective sharpness impression. +

+
+
bypass_il
+

Bypass already interlaced frames, only adjust the frame rate. +

+
+ +

Vertical low-pass filtering and bypassing already interlaced frames can only be +enabled for mode interleave_top and interleave_bottom. +

+
+
+ + +

30.256 tmedian

+

Pick median pixels from several successive input video frames. +

+

The filter accepts the following options: +

+
+
radius
+

Set radius of median filter. +Default is 1. Allowed range is from 1 to 127. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

30.256.1 Commands

+ +

This filter supports all above options as commands, excluding option radius. +

+ +

30.257 tmidequalizer

+ +

Apply Temporal Midway Video Equalization effect. +

+

Midway Video Equalization adjusts a sequence of video frames to have the same +histograms, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a video frames sequence. +

+

This filter accepts the following option: +

+
+
radius
+

Set filtering radius. Default is 5. Allowed range is from 1 to 127. +

+
+
sigma
+

Set filtering sigma. Default is 0.5. This controls strength of filtering. +Setting this option to 0 effectively does nothing. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

30.258 tmix

+ +

Mix successive video frames. +

+

A description of the accepted options follows. +

+
+
frames
+

The number of successive frames to mix. If unspecified, it defaults to 3. +

+
+
weights
+

Specify weight of each input video frame. +Each weight is separated by space. If number of weights is smaller than +number of frames last specified weight will be used for all remaining +unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

30.258.1 Examples

+ +
    +
  • Average 7 successive frames: +
    +
    tmix=frames=7:weights="1 1 1 1 1 1 1"
    +
    + +
  • Apply simple temporal convolution: +
    +
    tmix=frames=3:weights="-1 3 -1"
    +
    + +
  • Similar as above but only showing temporal differences: +
    +
    tmix=frames=3:weights="-1 2 -1":scale=1
    +
    +
+ + +

30.258.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

30.259 tonemap

+

Tone map colors from different dynamic ranges. +

+

This filter expects data in single precision floating point, as it needs to +operate on (and can output) out-of-range values. Another filter, such as +zscale, is needed to convert the resulting frame to a usable format. +

+

The tonemapping algorithms implemented only work on linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

30.259.1 Options

+

The filter accepts the following options. +

+
+
tonemap
+

Set the tone map algorithm to use. +

+

Possible values are: +

+
none
+

Do not apply any tone map, only desaturate overbright pixels. +

+
+
clip
+

Hard-clip any out-of-range values. Use it for perfect color accuracy for +in-range values, while distorting out-of-range values. +

+
+
linear
+

Stretch the entire reference gamut to a linear multiple of the display. +

+
+
gamma
+

Fit a logarithmic transfer between the tone curves. +

+
+
reinhard
+

Preserve overall image brightness with a simple curve, using nonlinear +contrast, which results in flattening details and degrading color accuracy. +

+
+
hable
+

Preserve both dark and bright details better than reinhard, at the cost +of slightly darkening everything. Use it when detail preservation is more +important than color and brightness accuracy. +

+
+
mobius
+

Smoothly map out-of-range values, while retaining contrast and colors for +in-range material as much as possible. Use it when color accuracy is more +important than detail preservation. +

+
+ +

Default is none. +

+
+
param
+

Tune the tone mapping algorithm. +

+

This affects the following algorithms: +

+
none
+

Ignored. +

+
+
linear
+

Specifies the scale factor to use while stretching. +Default to 1.0. +

+
+
gamma
+

Specifies the exponent of the function. +Default to 1.8. +

+
+
clip
+

Specify an extra linear coefficient to multiply into the signal before clipping. +Default to 1.0. +

+
+
reinhard
+

Specify the local contrast coefficient at the display peak. +Default to 0.5, which means that in-gamut values will be about half as bright +as when clipping. +

+
+
hable
+

Ignored. +

+
+
mobius
+

Specify the transition point from linear to mobius transform. Every value +below this point is guaranteed to be mapped 1:1. The higher the value, the +more accurate the result will be, at the cost of losing bright details. +Default to 0.3, which due to the steep initial slope still preserves in-range +colors fairly accurately. +

+
+ +
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default of 2.0 is somewhat conservative and will mostly just apply to +skies or directly sunlit surfaces. A setting of 0.0 disables this option. +

+

This option works only if the input frame has a supported color tag. +

+
+
peak
+

Override signal/nominal/reference peak with this value. Useful when the +embedded peak information in display metadata is not reliable or when tone +mapping from a lower range to a higher range. +

+
+ + +

30.260 tpad

+ +

Temporarily pad video frames. +

+

The filter accepts the following options: +

+
+
start
+

Specify number of delay frames before input video stream. Default is 0. +

+
+
stop
+

Specify number of padding frames after input video stream. +Set to -1 to pad indefinitely. Default is 0. +

+
+
start_mode
+

Set kind of frames added to beginning of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of first frame. +Default is add. +

+
+
stop_mode
+

Set kind of frames added to end of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of last frame. +Default is add. +

+
+
start_duration, stop_duration
+

Specify the duration of the start/stop delay. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +These options override start and stop. Default is 0. +

+
+
color
+

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 color is "black". +

+
+ + +

30.261 transpose

+ +

Transpose rows with columns in the input video and optionally flip it. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘0, 4, cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip (default), that is: +

+
L.R     L.l
+. . ->  . .
+l.r     R.r
+
+ +
+
‘1, 5, clock’
+

Rotate by 90 degrees clockwise, that is: +

+
L.R     l.L
+. . ->  . .
+l.r     r.R
+
+ +
+
‘2, 6, cclock’
+

Rotate by 90 degrees counterclockwise, that is: +

+
L.R     R.r
+. . ->  . .
+l.r     L.l
+
+ +
+
‘3, 7, clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip, that is: +

+
L.R     r.R
+. . ->  . .
+l.r     l.L
+
+
+
+ +

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 passthrough option should be used instead. +

+

Numerical values are deprecated, and should be dropped in favor of +symbolic constants. +

+
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +

Default value is none. +

+
+ +

For example to rotate by 90 degrees clockwise and preserve portrait +layout: +

+
transpose=dir=1:passthrough=portrait
+
+ +

The command above can also be specified as: +

+
transpose=1:portrait
+
+ + +

30.262 trim

+

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Specify the time of the start of the kept section, i.e. the frame with the +timestamp start will be the first frame in the output. +

+
+
end
+

Specify the time of the first frame that will be dropped, i.e. the frame +immediately preceding the one with the timestamp end will be the last +frame in the output. +

+
+
start_pts
+

This is the same as start, except this option sets the start timestamp +in timebase units instead of seconds. +

+
+
end_pts
+

This is the same as end, except this option sets the end timestamp +in timebase units instead of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_frame
+

The number of the first frame that should be passed to the output. +

+
+
end_frame
+

The number of the first frame that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

Note that the first two sets of the start/end options and the 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 for the output timestamps to 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -vf trim=60:120
    +
    + +
  • Keep only the first second: +
    +
    ffmpeg -i INPUT -vf trim=duration=1
    +
    + +
+ + +

30.263 unpremultiply

+

Apply alpha unpremultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+

If the format has 1 or 2 components, then luma is bit 0. +If the format has 3 or 4 components: +for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; +for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. +If present, the alpha channel is always the last bit. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

30.264 unsharp

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. It must be an odd integer between +3 and 23. The default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. It must be an odd integer between 3 +and 23. The default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. It must be a floating point 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. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. It must be a floating point 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 0.0. +

+
+
alpha_msize_x, ax
+

Set the alpha matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_msize_y, ay
+

Set the alpha matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_amount, aa
+

Set the alpha effect strength. It must be a floating point 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 0.0. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

30.264.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    unsharp=7:7:-2:7:7:-2
    +
    +
+ + +

30.265 untile

+ +

Decompose a video made of tiled images into the individual images. +

+

The frame rate of the output video is the frame rate of the input video +multiplied by the number of tiles. +

+

This filter does the reverse of tile. +

+

The filter accepts the following options: +

+
+
layout
+

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. +

+
+ + +

30.265.1 Examples

+ +
    +
  • Produce a 1-second video from a still image file made of 25 frames stacked +vertically, like an analogic film reel: +
    +
    ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
    +
    +
+ + +

30.266 uspp

+ +

Apply ultra slow/simple postprocessing filter that compresses and decompresses +the image at several (or - in the case of quality level 8 - all) +shifts and average the results. +

+

The way this differs from the behavior of spp is that uspp actually encodes & +decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 +DCT similar to MJPEG. +

+

This filter is not available in ffmpeg versions between 5.0 and 6.0. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-8. If set to 0, the filter will have no +effect. A value of 8 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
codec
+

Use specified codec instead of snow. +

+
+ + +

30.267 v360

+ +

Convert 360 videos between various formats. +

+

The filter accepts the following options: +

+
+
input
+
output
+

Set format of the input/output video. +

+

Available formats: +

+
+
‘e’
+
‘equirect’
+

Equirectangular projection. +

+
+
‘c3x2’
+
‘c6x1’
+
‘c1x6’
+

Cubemap with 3x2/6x1/1x6 layout. +

+

Format specific options: +

+
+
in_pad
+
out_pad
+

Set padding proportion for the input/output cubemap. Values in decimals. +

+

Example values: +

+
‘0’
+

No padding. +

+
‘0.01’
+

1% of face is padding. For example, with 1920x1280 resolution face size would be 640x640 and padding would be 3 pixels from each side. (640 * 0.01 = 6 pixels) +

+
+ +

Default value is ‘0’. +Maximum value is ‘0.1’. +

+
+
fin_pad
+
fout_pad
+

Set fixed padding for the input/output cubemap. Values in pixels. +

+

Default value is ‘0’. If greater than zero it overrides other padding options. +

+
+
in_forder
+
out_forder
+

Set order of faces for the input/output cubemap. Choose one direction for each position. +

+

Designation of directions: +

+
‘r’
+

right +

+
‘l’
+

left +

+
‘u’
+

up +

+
‘d’
+

down +

+
‘f’
+

forward +

+
‘b’
+

back +

+
+ +

Default value is ‘rludfb’. +

+
+
in_frot
+
out_frot
+

Set rotation of faces for the input/output cubemap. Choose one angle for each position. +

+

Designation of angles: +

+
‘0’
+

0 degrees clockwise +

+
‘1’
+

90 degrees clockwise +

+
‘2’
+

180 degrees clockwise +

+
‘3’
+

270 degrees clockwise +

+
+ +

Default value is ‘000000’. +

+
+ +
+
‘eac’
+

Equi-Angular Cubemap. +

+
+
‘flat’
+
‘gnomonic’
+
‘rectilinear’
+

Regular video. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘dfisheye’
+

Dual fisheye. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘barrel’
+
‘fb’
+
‘barrelsplit’
+

Facebook’s 360 formats. +

+
+
‘sg’
+

Stereographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘mercator’
+

Mercator format. +

+
+
‘ball’
+

Ball format, gives significant distortion toward the back. +

+
+
‘hammer’
+

Hammer-Aitoff map projection format. +

+
+
‘sinusoidal’
+

Sinusoidal map projection format. +

+
+
‘fisheye’
+

Fisheye projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘pannini’
+

Pannini projection. +

+

Format specific options: +

+
h_fov
+

Set output pannini parameter. +

+
+
ih_fov
+

Set input pannini parameter. +

+
+ +
+
‘cylindrical’
+

Cylindrical projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘perspective’
+

Perspective projection. (output only) +

+

Format specific options: +

+
v_fov
+

Set perspective parameter. +

+
+ +
+
‘tetrahedron’
+

Tetrahedron projection. +

+
+
‘tsp’
+

Truncated square pyramid projection. +

+
+
‘he’
+
‘hequirect’
+

Half equirectangular projection. +

+
+
‘equisolid’
+

Equisolid format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘og’
+

Orthographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘octahedron’
+

Octahedron projection. +

+
+
‘cylindricalea’
+

Cylindrical Equal Area projection. +

+
+ +
+
interp
+

Set interpolation method.
+Note: more complex interpolation methods require much more memory to run. +

+

Available methods: +

+
+
‘near’
+
‘nearest’
+

Nearest neighbour. +

+
‘line’
+
‘linear’
+

Bilinear interpolation. +

+
‘lagrange9’
+

Lagrange9 interpolation. +

+
‘cube’
+
‘cubic’
+

Bicubic interpolation. +

+
‘lanc’
+
‘lanczos’
+

Lanczos interpolation. +

+
‘sp16’
+
‘spline16’
+

Spline16 interpolation. +

+
‘gauss’
+
‘gaussian’
+

Gaussian interpolation. +

+
‘mitchell’
+

Mitchell interpolation. +

+
+ +

Default value is ‘line’. +

+
+
w
+
h
+

Set the output video resolution. +

+

Default resolution depends on formats. +

+
+
in_stereo
+
out_stereo
+

Set the input/output stereo format. +

+
+
‘2d’
+

2D mono +

+
‘sbs’
+

Side by side +

+
‘tb’
+

Top bottom +

+
+ +

Default value is ‘2d’ for input and output format. +

+
+
yaw
+
pitch
+
roll
+

Set rotation for the output video. Values in degrees. +

+
+
rorder
+

Set rotation order for the output video. Choose one item for each position. +

+
+
‘y, Y’
+

yaw +

+
‘p, P’
+

pitch +

+
‘r, R’
+

roll +

+
+ +

Default value is ‘ypr’. +

+
+
h_flip
+
v_flip
+
d_flip
+

Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values. +

+
+
ih_flip
+
iv_flip
+

Set if input video is flipped horizontally/vertically. Boolean values. +

+
+
in_trans
+

Set if input video is transposed. Boolean value, by default disabled. +

+
+
out_trans
+

Set if output video needs to be transposed. Boolean value, by default disabled. +

+
+
h_offset
+
v_offset
+

Set output horizontal/vertical off-axis offset. Default is set to 0. +Allowed range is from -1 to 1. +

+
+
alpha_mask
+

Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled. +

+
+
reset_rot
+

Reset rotation of output video. Boolean value, by default disabled. +

+
+ + +

30.267.1 Examples

+ +
    +
  • Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation: +
    +
    ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
    +
    +
  • Extract back view of Equi-Angular Cubemap: +
    +
    ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
    +
    +
  • Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format: +
    +
    v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
    +
    +
+ + +

30.267.2 Commands

+ +

This filter supports subset of above options as commands. +

+ +

30.268 vaguedenoiser

+ +

Apply a wavelet based denoiser. +

+

It transforms each frame from the video input into the wavelet domain, +using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to +the obtained coefficients. It does an inverse wavelet transform after. +Due to wavelet properties, it should give a nice smoothed result, and +reduced noise, without blurring picture features. +

+

This filter accepts the following options: +

+
+
threshold
+

The filtering strength. The higher, the more filtered the video will be. +Hard thresholding can use a higher threshold than soft thresholding +before the video looks overfiltered. Default value is 2. +

+
+
method
+

The filtering method the filter will use. +

+

It accepts the following values: +

+
‘hard’
+

All values under the threshold will be zeroed. +

+
+
‘soft’
+

All values under the threshold will be zeroed. All values above will be +reduced by the threshold. +

+
+
‘garrote’
+

Scales or nullifies coefficients - intermediary between (more) soft and +(less) hard thresholding. +

+
+ +

Default is garrote. +

+
+
nsteps
+

Number of times, the wavelet will decompose the picture. Picture can’t +be decomposed beyond a particular point (typically, 8 for a 640x480 +frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. +

+
+
percent
+

Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. +

+
+
planes
+

A list of the planes to process. By default all planes are processed. +

+
+
type
+

The threshold type the filter will use. +

+

It accepts the following values: +

+
‘universal’
+

Threshold used is same for all decompositions. +

+
+
‘bayes’
+

Threshold used depends also on each decomposition coefficients. +

+
+ +

Default is universal. +

+
+ + +

30.269 varblur

+

Apply variable blur filter by using 2nd video stream to set blur radius. +The 2nd stream must have the same dimensions. +

+

This filter accepts the following options: +

+
+
min_r
+

Set min allowed radius. Allowed range is from 0 to 254. Default is 0. +

+
max_r
+

Set max allowed radius. Allowed range is from 1 to 255. Default is 8. +

+
planes
+

Set which planes to process. By default, all are used. +

+
+ +

The varblur filter also supports the framesync options. +

+ +

30.269.1 Commands

+ +

This filter supports all the above options as commands. +

+ +

30.270 vectorscope

+ +

Display 2 color component values in the two dimensional graph (which is called +a vectorscope). +

+

This filter accepts the following options: +

+
+
mode, m
+

Set vectorscope mode. +

+

It accepts the following values: +

+
‘gray’
+
‘tint’
+

Gray values are displayed on graph, higher brightness means more pixels have +same component color value on location in graph. This is the default mode. +

+
+
‘color’
+

Gray values are displayed on graph. Surrounding pixels values which are not +present in video frame are drawn in gradient of 2 color components which are +set by option x and y. The 3rd color component is static. +

+
+
‘color2’
+

Actual color components values present in video frame are displayed on graph. +

+
+
‘color3’
+

Similar as color2 but higher frequency of same values x and y +on graph increases value of another color component, which is luminance by +default values of x and y. +

+
+
‘color4’
+

Actual colors present in video frame are displayed on graph. If two different +colors map to same position on graph then color with higher value of component +not present in graph is picked. +

+
+
‘color5’
+

Gray values are displayed on graph. Similar to color but with 3rd color +component picked from radial gradient. +

+
+ +
+
x
+

Set which color component will be represented on X-axis. Default is 1. +

+
+
y
+

Set which color component will be represented on Y-axis. Default is 2. +

+
+
intensity, i
+

Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness +of color component which represents frequency of (X, Y) location in graph. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, even darkest single pixel will be clearly highlighted. +

+
+
‘peak’
+

Hold maximum and minimum values presented in graph over time. This way you +can still spot out of range values without constantly looking at vectorscope. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
graticule, g
+

Set what kind of graticule to draw. +

+
‘none’
+
‘green’
+
‘color’
+
‘invert’
+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, f
+

Set graticule flags. +

+
+
‘white’
+

Draw graticule for white point. +

+
+
‘black’
+

Draw graticule for black point. +

+
+
‘name’
+

Draw color points short names. +

+
+ +
+
bgopacity, b
+

Set background opacity. +

+
+
lthreshold, l
+

Set low threshold for color component not represented on X or Y axis. +Values lower than this value will be ignored. Default is 0. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and low threshold value of 0.1 actual threshold +is 0.1 * 255 = 25. +

+
+
hthreshold, h
+

Set high threshold for color component not represented on X or Y axis. +Values higher than this value will be ignored. Default is 1. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and high threshold value of 0.9 actual threshold +is 0.9 * 255 = 230. +

+
+
colorspace, c
+

Set what kind of colorspace to use when drawing graticule. +

+
‘auto’
+
‘601’
+
‘709’
+
+

Default is auto. +

+
+
tint0, t0
+
tint1, t1
+

Set color tint for gray/tint vectorscope mode. By default both options are zero. +This means no tint, and output will remain gray. +

+
+ + +

30.271 vidstabdetect

+ +

Analyze video stabilization/deshaking. Perform pass 1 of 2, see +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 vidstabtransform filter. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libvidstab. +

+

This filter accepts the following options: +

+
+
result
+

Set the path to the file used to write the transforms information. +Default value is transforms.trf. +

+
+
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. +

+
+
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 15. +

+
+
stepsize
+

Set stepsize of the search process. The region around minimum is +scanned with 1 pixel resolution. Default value is 6. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
fileformat
+

Format for the transforms data file to be written. +Acceptable values are +

+
+
‘ascii’
+

Human-readable plain text +

+
+
‘binary’
+

Binary format, roughly 40% smaller than ascii. (default) +

+
+ +
+
+ + +

30.271.1 Examples

+ +
    +
  • Use default values: +
    +
    vidstabdetect
    +
    + +
  • Analyze strongly shaky movie and put the results in file +mytransforms.trf: +
    +
    vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
    +
    + +
  • Visualize the result of internal transformations in the resulting +video: +
    +
    vidstabdetect=show=1
    +
    + +
  • Analyze a video with medium shakiness using ffmpeg: +
    +
    ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
    +
    +
+ + +

30.272 vidstabtransform

+ +

Video stabilization/deshaking: pass 2 of 2, +see vidstabdetect for pass 1. +

+

Read a file with transform information for each frame and +apply/compensate them. Together with the vidstabdetect +filter this can be used to deshake videos. See also +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 +--enable-libvidstab. +

+ +

30.272.1 Options

+ +
+
input
+

Set path to the file used to read the transforms. Default value is +transforms.trf. +

+
+
smoothing
+

Set the number of frames (value*2 + 1) used for lowpass filtering the +camera movements. Default value is 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 value leads to a smoother video, but limits the acceleration of +the camera (pan/tilt movements). 0 is a special case where a static +camera is simulated. +

+
+
optalgo
+

Set the camera path optimization algorithm. +

+

Accepted values are: +

+
‘gauss’
+

gaussian kernel low-pass filter on camera motion (default) +

+
‘avg’
+

averaging on transformations +

+
+ +
+
maxshift
+

Set maximal number of pixels to translate frames. Default value is -1, +meaning no limit. +

+
+
maxangle
+

Set maximal angle in radians (degree*PI/180) to rotate frames. Default +value is -1, meaning no limit. +

+
+
crop
+

Specify how to deal with borders that may be visible due to movement +compensation. +

+

Available values are: +

+
‘keep’
+

keep image information from previous frame (default) +

+
‘black’
+

fill the border black +

+
+ +
+
invert
+

Invert transforms if set to 1. Default value is 0. +

+
+
relative
+

Consider transforms as relative to previous frame if set to 1, +absolute if set to 0. Default value is 0. +

+
+
zoom
+

Set percentage to zoom. A positive value will result in a zoom-in +effect, a negative value in a zoom-out effect. Default value is 0 (no +zoom). +

+
+
optzoom
+

Set optimal zooming to avoid borders. +

+

Accepted values are: +

+
‘0’
+

disabled +

+
‘1’
+

optimal static zoom value is determined (only very strong movements +will lead to visible borders) (default) +

+
‘2’
+

optimal adaptive zoom value is determined (no borders will be +visible), see zoomspeed +

+
+ +

Note that the value given at zoom is added to the one calculated here. +

+
+
zoomspeed
+

Set percent to zoom maximally each frame (enabled when +optzoom is set to 2). Range is from 0 to 5, default value is +0.25. +

+
+
interpol
+

Specify type of interpolation. +

+

Available values are: +

+
‘no’
+

no interpolation +

+
‘linear’
+

linear only horizontal +

+
‘bilinear’
+

linear in both directions (default) +

+
‘bicubic’
+

cubic in both directions (slow) +

+
+ +
+
tripod
+

Enable virtual tripod mode if set to 1, which is equivalent to +relative=0:smoothing=0. Default value is 0. +

+

Use also tripod option of vidstabdetect. +

+
+
debug
+

Increase log verbosity if set to 1. Also the detected global motions +are written to the temporary file global_motions.trf. Default +value is 0. +

+
+ + +

30.272.2 Examples

+ +
    +
  • Use ffmpeg for a typical stabilization with default values: +
    +
    ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
    +
    + +

    Note the use of the unsharp filter which is always recommended. +

    +
  • Zoom in a bit more and load transform data from a given file: +
    +
    vidstabtransform=zoom=5:input="mytransforms.trf"
    +
    + +
  • Smoothen the video even more: +
    +
    vidstabtransform=smoothing=30
    +
    +
+ + +

30.273 vflip

+ +

Flip the input video vertically. +

+

For example, to vertically flip a video with ffmpeg: +

+
ffmpeg -i in.avi -vf "vflip" out.avi
+
+ + +

30.274 vfrdet

+ +

Detect variable frame rate video. +

+

This filter tries to detect if the input is variable or constant frame rate. +

+

At end it will output number of frames detected as having variable delta pts, +and ones with constant delta pts. +If there was frames with variable delta, than it will also show min, max and +average delta encountered. +

+ +

30.275 vibrance

+ +

Boost or alter saturation. +

+

The filter accepts the following options: +

+
intensity
+

Set strength of boost if positive value or strength of alter if negative value. +Default is 0. Allowed range is from -2 to 2. +

+
+
rbal
+

Set the red balance. Default is 1. Allowed range is from -10 to 10. +

+
+
gbal
+

Set the green balance. Default is 1. Allowed range is from -10 to 10. +

+
+
bbal
+

Set the blue balance. Default is 1. Allowed range is from -10 to 10. +

+
+
rlum
+

Set the red luma coefficient. +

+
+
glum
+

Set the green luma coefficient. +

+
+
blum
+

Set the blue luma coefficient. +

+
+
alternate
+

If intensity is negative and this is set to 1, colors will change, +otherwise colors will be less saturated, more towards gray. +

+
+ + +

30.275.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

30.276 vif

+ +

Obtain the average VIF (Visual Information Fidelity) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 VIF score is printed through the logging system. +

+

The filter stores the calculated VIF score of each frame. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi vif -f null -
+
+ + +

30.277 vignette

+ +

Make or reverse a natural vignetting effect. +

+

The filter accepts the following options: +

+
+
angle, a
+

Set lens angle expression as a number of radians. +

+

The value is clipped in the [0,PI/2] range. +

+

Default value: "PI/5" +

+
+
x0
+
y0
+

Set center coordinates expressions. Respectively "w/2" and "h/2" +by default. +

+
+
mode
+

Set forward/backward mode. +

+

Available modes are: +

+
‘forward’
+

The larger the distance from the central point, the darker the image becomes. +

+
+
‘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 angle and other settings (yet). It can +also be used to create a burning effect. +

+
+ +

Default value is ‘forward’. +

+
+
eval
+

Set evaluation mode for the expressions (angle, x0, y0). +

+

It accepts the following values: +

+
‘init’
+

Evaluate expressions only once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. This is way slower than the +‘init’ mode since it requires all the scalers to be re-computed, but it +allows advanced dynamic expressions. +

+
+ +

Default value is ‘init’. +

+
+
dither
+

Set dithering to reduce the circular banding effects. Default is 1 +(enabled). +

+
+
aspect
+

Set vignette aspect. This setting allows one 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 1/1. +

+
+ + +

30.277.1 Expressions

+ +

The alpha, x0 and y0 expressions can contain the +following parameters. +

+
+
w
+
h
+

input width and height +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pts
+

the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in +TB units, NAN if undefined +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined +

+
+
tb
+

time base of the input video +

+
+ + + +

30.277.2 Examples

+ +
    +
  • Apply simple strong vignetting effect: +
    +
    vignette=PI/4
    +
    + +
  • Make a flickering vignetting: +
    +
    vignette='PI/4+random(1)*PI/50':eval=frame
    +
    + +
+ + +

30.278 vmafmotion

+ +

Obtain the average VMAF motion score of a video. +It is one of the component metrics of VMAF. +

+

The obtained average motion score is printed through the logging system. +

+

The filter accepts the following options: +

+
+
stats_file
+

If specified, the filter will use the named file to save the motion score of +each frame with respect to the previous frame. +When filename equals "-" the data is sent to standard output. +

+
+ +

Example: +

+
ffmpeg -i ref.mpg -vf vmafmotion -f null -
+
+ + +

30.279 vpp_amf

+ +

Scale (resize) and convert colorspace, transfer characteristics or color primaries for the input video, using AMD Advanced Media Framework library for hardware acceleration. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
scale_type
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+

This is the default. +

+
+
bicubic
+

Bicubic +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+ +
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
color_profile
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt601’
+

BT.601 +

+
+
‘bt709’
+

BT.709 +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘linear’
+

Linear +

+
+
‘log’
+

LOG +

+
+
‘log-sqrt’
+

LOG_SQRT +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘bt1361-ecg’
+

BT1361_ECG +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
‘smpte2084’
+

SMPTE2084 +

+
+
‘smpte428’
+

SMPTE428 +

+
+
‘arib-std-b67’
+

ARIB_STD_B67 +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘smpte428’
+

SMPTE-428 +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+
+
+ + +

30.279.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    vpp_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K and change color profile to bt2020. +
    +
    vpp_amf=4096:2160:color_profile=bt2020
    +
    +
+ + +

30.280 vstack

+

Stack input videos vertically. +

+

All streams must be of same pixel format and of same width. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

30.281 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. +

+

This filter uses 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 setfield filter before w3fdif filter. +

+

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: +

+
+
filter
+

Set the interlacing filter coefficients. Accepts one of the following values: +

+
+
‘simple’
+

Simple filter coefficient set. +

+
‘complex’
+

More-complex filter coefficient set. +

+
+

Default value is ‘complex’. +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames, +

+
‘interlaced’
+

Only deinterlace frames marked as interlaced. +

+
+ +

Default value is ‘all’. +

+
+ + +

30.281.1 Commands

+

This filter supports same commands as options. +

+ +

30.282 waveform

+

Video waveform monitor. +

+

The waveform monitor plots color component intensity. By default luma +only. Each column of the waveform corresponds to a column of pixels in the +source video. +

+

It accepts the following options: +

+
+
mode, m
+

Can be either row, or column. Default is column. +In row mode, the graph on the left side represents color component value 0 and +the right side represents value = 255. In column mode, the top side represents +color component value = 0 and bottom side represents value = 255. +

+
+
intensity, i
+

Set intensity. Smaller values are useful to find out how many values of the same +luminance are distributed across input rows/columns. +Default value is 0.04. Allowed range is [0, 1]. +

+
+
mirror, r
+

Set mirroring mode. 0 means unmirrored, 1 means mirrored. +In mirrored mode, higher values will be represented on the left +side for row mode and at the top for column mode. Default is +1 (mirrored). +

+
+
display, d
+

Set display mode. +It accepts the following values: +

+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+

This display mode makes it easier to spot relative differences or similarities +in overlapping areas of the color components that are supposed to be identical, +such as neutral whites, grays, or blacks. +

+
+
‘stack’
+

Display separate graph for the color components side by side in +row mode or one below the other in column mode. +

+
+
‘parade’
+

Display separate graph for the color components side by side in +column mode or one below the other in row mode. +

+

Using this display mode makes it easy to spot color casts in the highlights +and shadows of an image, by comparing the contours of the top and the bottom +graphs of each waveform. Since whites, grays, and blacks are characterized +by exactly equal amounts of red, green, and blue, neutral areas of the picture +should display three waveforms of roughly equal width/height. If not, the +correction is easy to perform by making level adjustments the three waveforms. +

+
+

Default is stack. +

+
+
components, c
+

Set which color components to display. Default is 1, which means only luma +or red color component if input is in RGB colorspace. If is set for example to +7 it will display all 3 (if) available color components. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, minimum and maximum values presented in graph will be easily +visible even with small step value. +

+
+
‘peak’
+

Hold minimum and maximum values presented in graph across time. This way you +can still spot out of range values without constantly looking at waveforms. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
filter, f
+
+
‘lowpass’
+

No filtering, this is default. +

+
+
‘flat’
+

Luma and chroma combined together. +

+
+
‘aflat’
+

Similar as above, but shows difference between blue and red chroma. +

+
+
‘xflat’
+

Similar as above, but use different colors. +

+
+
‘yflat’
+

Similar as above, but again with different colors. +

+
+
‘chroma’
+

Displays only chroma. +

+
+
‘color’
+

Displays actual color value on waveform. +

+
+
‘acolor’
+

Similar as above, but with luma showing frequency of chroma values. +

+
+ +
+
graticule, g
+

Set which graticule to display. +

+
+
‘none’
+

Do not display graticule. +

+
+
‘green’
+

Display green graticule showing legal broadcast ranges. +

+
+
‘orange’
+

Display orange graticule showing legal broadcast ranges. +

+
+
‘invert’
+

Display invert graticule showing legal broadcast ranges. +

+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, fl
+

Set graticule flags. +

+
+
‘numbers’
+

Draw numbers above lines. By default enabled. +

+
+
‘dots’
+

Draw dots instead of lines. +

+
+ +
+
scale, s
+

Set scale used for displaying graticule. +

+
+
‘digital’
+
‘millivolts’
+
‘ire’
+
+

Default is digital. +

+
+
bgopacity, b
+

Set background opacity. +

+
+
tint0, t0
+
tint1, t1
+

Set tint for output. +Only used with lowpass filter and when display is not overlay and input +pixel formats are not RGB. +

+
+
fitmode, fm
+

Set sample aspect ratio of video output frames. +Can be used to configure waveform so it is not +stretched too much in one of directions. +

+
+
‘none’
+

Set sample aspect ration to 1/1. +

+
‘size’
+

Set sample aspect ratio to match input size of video +

+
+

Default is ‘none’. +

+
+
input
+

Set input formats for filter to pick from. +Can be ‘all’, for selecting from all available formats, +or ‘first’, for selecting first available format. +Default is ‘first’. +

+
+ + +

30.283 weave, doubleweave

+ +

The weave takes a field-based video input and join +each two sequential fields into single frame, producing a new double +height clip with half the frame rate and half the frame count. +

+

The doubleweave works same as weave but without +halving frame rate and frame count. +

+

It accepts the following option: +

+
+
first_field
+

Set first field. Available values are: +

+
+
‘top, t’
+

Set the frame as top-field-first. +

+
+
‘bottom, b’
+

Set the frame as bottom-field-first. +

+
+
+
+ + +

30.283.1 Examples

+ +
    +
  • Interlace video using select and separatefields filter: +
    +
    separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
    +
    +
+ + +

30.284 xbr

+

Apply the xBR high-quality magnification filter which is designed for pixel +art. It follows a set of edge-detection rules, see +https://forums.libretro.com/t/xbr-algorithm-tutorial/123. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xBR, 3 for +3xBR and 4 for 4xBR. +Default is 3. +

+
+ + +

30.285 xcorrelate

+

Apply normalized cross-correlation between first and second input video stream. +

+

Second input video stream dimensions must be lower than first input video stream. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
secondary
+

Set which secondary video frames will be processed from second input video stream, +can be first or all. Default is all. +

+
+ +

The xcorrelate filter also supports the framesync options. +

+ +

30.286 xfade

+ +

Apply cross fade from one input video stream to another input video stream. +The cross fade is applied for specified duration. +

+

Both inputs must be constant frame-rate and have the same resolution, pixel format, +frame rate and timebase. +

+

The filter accepts the following options: +

+
+
transition
+

Set one of available transition effects: +

+
+
‘custom’
+
‘fade’
+
‘wipeleft’
+
‘wiperight’
+
‘wipeup’
+
‘wipedown’
+
‘slideleft’
+
‘slideright’
+
‘slideup’
+
‘slidedown’
+
‘circlecrop’
+
‘rectcrop’
+
‘distance’
+
‘fadeblack’
+
‘fadewhite’
+
‘radial’
+
‘smoothleft’
+
‘smoothright’
+
‘smoothup’
+
‘smoothdown’
+
‘circleopen’
+
‘circleclose’
+
‘vertopen’
+
‘vertclose’
+
‘horzopen’
+
‘horzclose’
+
‘dissolve’
+
‘pixelize’
+
‘diagtl’
+
‘diagtr’
+
‘diagbl’
+
‘diagbr’
+
‘hlslice’
+
‘hrslice’
+
‘vuslice’
+
‘vdslice’
+
‘hblur’
+
‘fadegrays’
+
‘wipetl’
+
‘wipetr’
+
‘wipebl’
+
‘wipebr’
+
‘squeezeh’
+
‘squeezev’
+
‘zoomin’
+
‘fadefast’
+
‘fadeslow’
+
‘hlwind’
+
‘hrwind’
+
‘vuwind’
+
‘vdwind’
+
‘coverleft’
+
‘coverright’
+
‘coverup’
+
‘coverdown’
+
‘revealleft’
+
‘revealright’
+
‘revealup’
+
‘revealdown’
+
+

Default transition effect is fade. +

+
+
duration
+

Set cross fade duration in seconds. +Range is 0 to 60 seconds. +Default duration is 1 second. +

+
+
offset
+

Set cross fade start relative to first input stream in seconds. +Default offset is 0. +

+
+
expr
+

Set expression for custom transition effect. +

+

The expressions can use the following variables and functions: +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
P
+

Progress of transition effect. +

+
+
PLANE
+

Currently processed plane. +

+
+
A
+

Return value of first input at current location and plane. +

+
+
B
+

Return value of second input at current location and plane. +

+
+
a0(x, y)
+
a1(x, y)
+
a2(x, y)
+
a3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of first input. +

+
+
b0(x, y)
+
b1(x, y)
+
b2(x, y)
+
b3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of second input. +

+
+
+
+ + +

30.286.1 Examples

+ +
    +
  • Cross fade from one input video to another input video, with fade transition and duration of transition +of 2 seconds starting at offset of 5 seconds: +
    +
    ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
    +
    +
+ + +

30.287 xmedian

+

Pick median pixels from several input videos. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. +Default is 3. Allowed range is from 3 to 255. +If number of inputs is even number, than result will be mean value between two median values. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

30.287.1 Commands

+ +

This filter supports all above options as commands, excluding option inputs. +

+ +

30.288 xpsnr

+ +

Obtain the average (across all input frames) and minimum (across all color plane averages) +eXtended Perceptually weighted peak Signal-to-Noise Ratio (XPSNR) between two input videos. +

+

The XPSNR is a low-complexity psychovisually motivated distortion measurement algorithm for +assessing the difference between two video streams or images. This is especially useful for +objectively quantifying the distortions caused by video and image codecs, as an alternative +to a formal subjective test. The logarithmic XPSNR output values are in a similar range as +those of traditional psnr assessments but better reflect human impressions of visual +coding quality. More details on the XPSNR measure, which essentially represents a blockwise +weighted variant of the PSNR measure, can be found in the following freely available papers: +

+
    +
  • C. R. Helmrich, M. Siekmann, S. Becker, S. Bosse, D. Marpe, and T. Wiegand, "XPSNR: A +Low-Complexity Extension of the Perceptually Weighted Peak Signal-to-Noise Ratio for +High-Resolution Video Quality Assessment," in Proc. IEEE Int. Conf. Acoustics, Speech, +Sig. Process. (ICASSP), virt./online, May 2020. www.ecodis.de/xpsnr.htm + +
  • C. R. Helmrich, S. Bosse, H. Schwarz, D. Marpe, and T. Wiegand, "A Study of the +Extended Perceptually Weighted Peak Signal-to-Noise Ratio (XPSNR) for Video Compression +with Different Resolutions and Bit Depths," ITU Journal: ICT Discoveries, vol. 3, no. +1, pp. 65 - 72, May 2020. http://handle.itu.int/11.1002/pub/8153d78b-en +
+ +

When publishing the results of XPSNR assessments obtained using, e.g., this FFmpeg filter, a +reference to the above papers as a means of documentation is strongly encouraged. The filter +requires two input videos. The first input is considered a (usually not distorted) reference +source and is passed unchanged to the output, whereas the second input is a (distorted) test +signal. Except for the bit depth, these two video inputs must have the same pixel format. In +addition, for best performance, both compared input videos should be in YCbCr color format. +

+

The obtained overall XPSNR values mentioned above are printed through the logging system. In +case of input with multiple color planes, we suggest reporting of the minimum XPSNR average. +

+

The following parameter, which behaves like the one for the psnr filter, is accepted: +

+
+
stats_file, f
+

If specified, the filter will use the named file to save the XPSNR value of each individual +frame and color plane. When the file name equals "-", that data is sent to standard output. +

+
+ +

This filter also supports the framesync options. +

+ +

30.288.1 Examples

+
    +
  • XPSNR analysis of two 1080p HD videos, ref_source.yuv and test_video.yuv, both at 24 frames +per second, with color format 4:2:0, bit depth 8, and output of a logfile named "xpsnr.log": +
    +
    ffmpeg -s 1920x1080 -framerate 24 -pix_fmt yuv420p -i ref_source.yuv -s 1920x1080 -framerate
    +24 -pix_fmt yuv420p -i test_video.yuv -lavfi xpsnr="stats_file=xpsnr.log" -f null -
    +
    + +
  • XPSNR analysis of two 2160p UHD videos, ref_source.yuv with bit depth 8 and test_video.yuv +with bit depth 10, both at 60 frames per second with color format 4:2:0, no logfile output: +
    +
    ffmpeg -s 3840x2160 -framerate 60 -pix_fmt yuv420p -i ref_source.yuv -s 3840x2160 -framerate
    +60 -pix_fmt yuv420p10le -i test_video.yuv -lavfi xpsnr="stats_file=-" -f null -
    +
    +
+ + +

30.289 xstack

+

Stack video inputs into custom layout. +

+

All streams must be of same pixel format. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
layout
+

Specify layout of inputs. +This option requires the desired layout configuration to be explicitly set by the user. +This sets position of each video input in output. Each input +is separated by ’|’. +The first number represents the column, and the second number represents the row. +Numbers start at 0 and are separated by ’_’. Optionally one can use wX and hX, +where X is video input from which to take width or height. +Multiple values can be used when separated by ’+’. In such +case values are summed together. +

+

Note that if inputs are of different sizes gaps may appear, as not all of +the output video frame will be filled. Similarly, videos can overlap each +other if their position doesn’t leave enough space for the full frame of +adjoining videos. +

+

For 2 inputs, a default layout of 0_0|w0_0 (equivalent to +grid=2x1) is set. In all other cases, a layout or a grid must be set by +the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
grid
+

Specify a fixed size grid of inputs. +This option is used to create a fixed size grid of the input streams. Set the +grid size in the form COLUMNSxROWS. There must be ROWS * COLUMNS +input streams and they will be arranged as a grid with ROWS rows and +COLUMNS columns. When using this option, each input stream within a row +must have the same height and all the rows must have the same width. +

+

If grid is set, then inputs option is ignored and is implicitly +set to ROWS * COLUMNS. +

+

For 2 inputs, a default grid of 2x1 (equivalent to +layout=0_0|w0_0) is set. In all other cases, a layout or a grid must be +set by the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
fill
+

If set to valid color, all unused pixels will be filled with that color. +By default fill is set to none, so it is disabled. +

+
+ + +

30.289.1 Examples

+ +
    +
  • Display 4 inputs into 2x2 grid. + +

    Layout: +

    +
    input1(0, 0)  | input3(w0, 0)
    +input2(0, h0) | input4(w0, h0)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 4 inputs into 1x4 grid. + +

    Layout: +

    +
    input1(0, 0)
    +input2(0, h0)
    +input3(0, h0+h1)
    +input4(0, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
    +
    + +

    Note that if inputs are of different widths, unused space will appear. +

    +
  • Display 9 inputs into 3x3 grid. + +

    Layout: +

    +
    input1(0, 0)       | input4(w0, 0)      | input7(w0+w3, 0)
    +input2(0, h0)      | input5(w0, h0)     | input8(w0+w3, h0)
    +input3(0, h0+h1)   | input6(w0, h0+h1)  | input9(w0+w3, h0+h1)
    +
    + +
    +
    xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 16 inputs into 4x4 grid. + +

    Layout: +

    +
    input1(0, 0)       | input5(w0, 0)       | input9 (w0+w4, 0)       | input13(w0+w4+w8, 0)
    +input2(0, h0)      | input6(w0, h0)      | input10(w0+w4, h0)      | input14(w0+w4+w8, h0)
    +input3(0, h0+h1)   | input7(w0, h0+h1)   | input11(w0+w4, h0+h1)   | input15(w0+w4+w8, h0+h1)
    +input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0|
    +w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
+ + +

30.290 yadif

+ +

Deinterlace the input video ("yadif" means "yet another deinterlacing +filter"). +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

30.291 yaepblur

+ +

Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter"). +The algorithm is described in +"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980." +

+

It accepts the following parameters: +

+
+
radius, r
+

Set the window radius. Default value is 3. +

+
+
planes, p
+

Set which planes to filter. Default is only the first plane. +

+
+
sigma, s
+

Set blur strength. Default value is 128. +

+
+ + +

30.291.1 Commands

+

This filter supports same commands as options. +

+ +

30.292 zoompan

+ +

Apply Zoom & Pan effect. +

+

This filter accepts the following options: +

+
+
zoom, z
+

Set the zoom expression. Range is 1-10. Default is 1. +

+
+
x
+
y
+

Set the x and y expression. Default is 0. +

+
+
d
+

Set the duration expression in number of frames. +This sets for how many number of frames effect will last for +single input image. Default is 90. +

+
+
s
+

Set the output image size, default is ’hd720’. +

+
+
fps
+

Set the output frame rate, default is ’25’. +

+
+ +

Each expression can contain the following constants: +

+
+
in_w, iw
+

Input width. +

+
+
in_h, ih
+

Input height. +

+
+
out_w, ow
+

Output width. +

+
+
out_h, oh
+

Output height. +

+
+
in
+

Input frame count. +

+
+
on
+

Output frame count. +

+
+
in_time, it
+

The input timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
out_time, time, ot
+

The output timestamp expressed in seconds. +

+
+
x
+
y
+

Last calculated ’x’ and ’y’ position from ’x’ and ’y’ expression +for current input frame. +

+
+
px
+
py
+

’x’ and ’y’ of last output frame of previous input frame or 0 when there was +not yet such frame (first input frame). +

+
+
zoom
+

Last calculated zoom from ’z’ expression for current input frame. +

+
+
pzoom
+

Last calculated zoom of last output frame of previous input frame. +

+
+
duration
+

Number of output frames for current input frame. Calculated from ’d’ expression +for each input frame. +

+
+
pduration
+

number of output frames created for previous input frame +

+
+
a
+

Rational number: input width / input height +

+
+
sar
+

sample aspect ratio +

+
+
dar
+

display aspect ratio +

+
+
+ + +

30.292.1 Examples

+ +
    +
  • Zoom in up to 1.5x and pan at same time to some spot near center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360
    +
    + +
  • Zoom in up to 1.5x and pan always at center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Same as above but without pausing: +
    +
    zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Zoom in 2x into center of picture only for the first second of the input video: +
    +
    zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
+ + +

30.293 zscale

+

Scale (resize) the input video, using the z.lib library: +https://github.com/sekrit-twc/zimg. To enable compilation of this +filter, you need to configure FFmpeg with --enable-libzimg. +

+

The zscale filter forces the output display aspect ratio to be the same +as the input, by changing the output sample aspect ratio. +

+

If the input image format is different from the format requested by +the next filter, the zscale filter will convert the input to the +requested format. +

+ +

30.293.1 Options

+

The filter accepts the following options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the zscale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
dither, d
+

Set the dither type. +

+

Possible values are: +

+
none
+
ordered
+
random
+
error_diffusion
+
+ +

Default is none. +

+
+
filter, f
+

Set the resize filter type. +

+

Possible values are: +

+
point
+
bilinear
+
bicubic
+
spline16
+
spline36
+
spline64
+
lanczos
+
+ +

Default is bilinear. +

+
+
range, r
+

Set the color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
smpte2084
+
iec61966-2-1
+
arib-std-b67
+
+ +

Default is same as input. +

+
+
matrix, m
+

Set the colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +

Default is same as input. +

+
+
rangein, rin
+

Set the input color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primariesin, pin
+

Set the input color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transferin, tin
+

Set the input transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
+ +

Default is same as input. +

+
+
matrixin, min
+

Set the input colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +
+
chromal, c
+

Set the output chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
chromalin, cin
+

Set the input chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
npl
+

Set the nominal peak luminance. +

+
+
param_a
+

Parameter A for scaling filters. Parameter "b" for bicubic, and the number of +filter taps for lanczos. +

+
+
param_b
+

Parameter B for scaling filters. Parameter "c" for bicubic. +

+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

30.293.2 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + + +

31 CUDA Video Filters

+ +

To enable CUDA and/or NPP filters please refer to configuration guidelines for CUDA and for CUDA NPP filters. +

+

Running CUDA filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device cuda[=name][:device[,key=value...]]
+

Initialise a new hardware device of type cuda called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of initializing second CUDA device on the system and running scale_cuda and bilateral_cuda filters. +
    +
    ./ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -init_hw_device cuda:1 -filter_complex \
    +"[0:v]scale_cuda=format=yuv444p[scaled_video];[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    +
+ +

Since CUDA filters operate exclusively on GPU memory, frame data must sometimes be uploaded (hwupload) to hardware surfaces associated with the appropriate CUDA device before processing, and downloaded (hwdownload) back to normal memory afterward, if required. Whether hwupload or hwdownload is necessary depends on the specific workflow: +

+
    +
  • If the input frames are already in GPU memory (e.g., when using -hwaccel cuda or -hwaccel_output_format cuda), explicit use of hwupload is not needed, as the data is already in the appropriate memory space. +
  • If the input frames are in CPU memory (e.g., software-decoded frames or frames processed by CPU-based filters), it is necessary to use hwupload to transfer the data to GPU memory for CUDA processing. +
  • If the output of the CUDA filters needs to be further processed by software-based filters or saved in a format not supported by GPU-based encoders, hwdownload is required to transfer the data back to CPU memory. +
+

Note that hwupload uploads data to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before hwupload to ensure the input is in the correct format. Similarly, hwdownload may not support all output formats, so an additional format filter may need to be inserted immediately after hwdownload in the filter graph to ensure compatibility. +

+ +

31.1 CUDA

+

Below is a description of the currently available Nvidia CUDA video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
+ +

Note: If FFmpeg detects the Nvidia CUDA Toolkit during configuration, it will enable CUDA filters automatically without requiring any additional flags. If you want to explicitly enable them, use the following options: +

+
    +
  • Configure FFmpeg with --enable-cuda-nvcc --enable-nonfree. +
  • Configure FFmpeg with --enable-cuda-llvm. Additional requirement: llvm lib must be installed. +
+ + +

31.1.1 bilateral_cuda

+

CUDA accelerated bilateral filter, an edge preserving filter. +This filter is mathematically accurate thanks to the use of GPU acceleration. +For best output quality, use one to one chroma subsampling, i.e. yuv444p format. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight, also called sigma space. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate color range weight, also called sigma color. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
window_size
+

Set window size of the bilateral function to determine the number of neighbours to loop on. +If the number entered is even, one will be added automatically. +Allowed range is 1 to 255. Default is 1. +

+
+ +

31.1.1.1 Examples

+ +
    +
  • Apply the bilateral filter on a video. + +
    +
    ./ffmpeg -v verbose \
    +-hwaccel cuda -hwaccel_output_format cuda -i input.mp4  \
    +-init_hw_device cuda \
    +-filter_complex \
    +" \
    +[0:v]scale_cuda=format=yuv444p[scaled_video];
    +[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    + +
+ + +

31.1.2 bwdif_cuda

+ +

Deinterlace the input video using the bwdif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

31.1.3 chromakey_cuda

+

CUDA accelerated YUV colorspace color/chroma keying. +

+

This filter works like normal chromakey filter but operates on CUDA frames. +for more details and parameters see chromakey. +

+ +

31.1.3.1 Examples

+ +
    +
  • Make all the green pixels in the input video transparent and use it as an overlay for another video: + +
    +
    ./ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -i input_green.mp4  \
    +    -hwaccel cuda -hwaccel_output_format cuda -i base_video.mp4 \
    +    -init_hw_device cuda \
    +    -filter_complex \
    +    " \
    +        [0:v]chromakey_cuda=0x25302D:0.1:0.12:1[overlay_video]; \
    +        [1:v]scale_cuda=format=yuv420p[base]; \
    +        [base][overlay_video]overlay_cuda" \
    +    -an -sn -c:v h264_nvenc -cq 20 output.mp4
    +
    + +
  • Process two software sources, explicitly uploading the frames: + +
    +
    ./ffmpeg -init_hw_device cuda=cuda -filter_hw_device cuda \
    +    -f lavfi -i color=size=800x600:color=white,format=yuv420p \
    +    -f lavfi -i yuvtestsrc=size=200x200,format=yuv420p \
    +    -filter_complex \
    +    " \
    +        [0]hwupload[under]; \
    +        [1]hwupload,chromakey_cuda=green:0.1:0.12[over]; \
    +        [under][over]overlay_cuda" \
    +    -c:v hevc_nvenc -cq 18 -preset slow output.mp4
    +
    + +
+ + +

31.1.4 colorspace_cuda

+ +

CUDA accelerated implementation of the colorspace filter. +

+

It is by no means feature complete compared to the software colorspace filter, +and at the current time only supports color range conversion between jpeg/full +and mpeg/limited range. +

+

The filter accepts the following options: +

+
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
+ + +

31.1.5 overlay_cuda

+ +

Overlay one video on top of another. +

+

This is the CUDA variant of the overlay filter. +It only accepts CUDA frames. The underlying input pixel formats have to match. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

They can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
n
+

The ordinal index of the main input frame, starting from 0. +

+
+
pos
+

The byte offset position in the file of the main input frame, NAN if unknown. +Deprecated, do not use. +

+
+
t
+

The timestamp of the main input frame, expressed in seconds, NAN if unknown. +

+
+
+ +

Default value is "0" for both expressions. +

+
+
eval
+

Set when the expressions for x and y are evaluated. +

+

It accepts the following values: +

+
init
+

Evaluate expressions once during filter initialization or +when a command is processed. +

+
+
frame
+

Evaluate expressions for each incoming frame +

+
+ +

Default value is frame. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+ + +

31.1.6 pad_cuda

+

Add paddings to an input video stream using CUDA. +

+

This filter is the CUDA-accelerated version of the pad filter. It accepts the same options and expressions and provides the same core functionality. +For a detailed description of available options, please see the documentation for the pad filter. +

+ +

31.1.6.1 Examples

+ +
    +
  • Add a 200-pixel black border to all sides of a video frame: +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=iw+400:h=ih+400:x=200:y=200" -c:v h264_nvenc out.mp4
    +
    + +
  • Pad the input video to a 16:9 aspect ratio, filling with the color "blue": +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=ih*16/9/sar:h=ih:x=(ow-iw)/2:y=(oh-ih)/2:color=blue" -c:v h264_nvenc out.mp4
    +
    +
+ + +

31.1.7 scale_cuda

+ +

Scale (resize) and convert (pixel format) the input video, using accelerated CUDA kernels. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
interp_algo
+

Sets the algorithm used for scaling: +

+
+
nearest
+

Nearest neighbour +

+

Used by default if input parameters match the desired output. +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+

This is the default. +

+
+
lanczos
+

Lanczos +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+

The filter does not support converting between YUV and RGB pixel formats. +

+
+
passthrough
+

If set to 0, every frame is processed, even if no conversion is necessary. +This mode can be useful to use the filter as a buffer for a downstream +frame-consumer that exhausts the limited decoder frame pool. +

+

If set to 1, frames are passed through as-is if they match the desired output +parameters. This is the default behaviour. +

+
+
param
+

Algorithm-Specific parameter. +

+

Affects the curves of the bicubic algorithm. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
+ + +

31.1.7.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    scale_cuda=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K using nearest neighbour algorithm. +
    +
    scale_cuda=4096:2160:interp_algo=nearest
    +
    + +
  • Don’t do any conversion or scaling, but copy all input frames into newly allocated ones. +This can be useful to deal with a filter and encode chain that otherwise exhausts the +decoders frame pool. +
    +
    scale_cuda=passthrough=0
    +
    +
+ + +

31.1.8 thumbnail_cuda

+ +

Select the most representative frame in a given sequence of consecutive frames using CUDA. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

31.1.8.1 Example

+ +
    +
  • Thumbnails are extracted from every n=150-frame batch, selecting one per batch. Chosen frames are then scaled with scale_cuda. +
    +
    ./ffmpeg  -hwaccel cuda -hwaccel_output_format cuda  -i ./input.mp4 -vf "thumbnail_cuda=150,scale_cuda=1920:1080,hwdownload,format=nv12" ./output/out%03d.png
    +
    + +
+ + +

31.1.9 yadif_cuda

+ +

Deinterlace the input video using the yadif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

31.2 CUDA NPP

+

Below is a description of the currently available NVIDIA Performance Primitives (libnpp) video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
  • Install libnpp +
+ +

To enable CUDA NPP filters: +

+
    +
  • Configure FFmpeg with --enable-nonfree --enable-libnpp. +
+ + + +

31.2.1 scale_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel +format conversion on CUDA video frames. Setting the output width and height +works in the same way as for the scale filter. +

+

The following additional options are accepted: +

+
format
+

The pixel format of the output CUDA frames. If set to the string "same" (the +default), the input format will be kept. Note that automatic format negotiation +and conversion is not yet supported for hardware frames +

+
+
interp_algo
+

The interpolation algorithm used for resizing. One of the following: +

+
nn
+

Nearest neighbour. +

+
+
linear
+
cubic
+
cubic2p_bspline
+

2-parameter cubic (B=1, C=0) +

+
+
cubic2p_catmullrom
+

2-parameter cubic (B=0, C=1/2) +

+
+
cubic2p_b05c03
+

2-parameter cubic (B=1/2, C=3/10) +

+
+
super
+

Supersampling +

+
+
lanczos
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+ + +

31.2.2 scale2ref_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to scale (resize) the input +video, based on a reference video. +

+

See the scale_npp filter for available options, scale2ref_npp supports the same +but uses the reference video instead of the main input as basis. scale2ref_npp +also supports the following additional constants for the w and +h options: +

+
+
main_w
+
main_h
+

The main input video’s width and height +

+
+
main_a
+

The same as main_w / main_h +

+
+
main_sar
+

The main input video’s sample aspect ratio +

+
+
main_dar, mdar
+

The main input video’s display aspect ratio. Calculated from +(main_w / main_h) * main_sar. +

+
+
main_n
+

The (sequential) number of the main input frame, starting from 0. +Only available with eval=frame. +

+
+
main_t
+

The presentation timestamp of the main input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
main_pos
+

The position (byte offset) of the frame in the main input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +

+
+ + +

31.2.2.1 Examples

+ +
    +
  • Scale a subtitle stream (b) to match the main video (a) in size before overlaying +
    +
    'scale2ref_npp[b][a];[a][b]overlay_cuda'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio. +
    +
    [logo-in][video-in]scale2ref_npp=w=oh*mdar:h=ih/10[logo-out][video-out]
    +
    +
+ + +

31.2.3 sharpen_npp

+

Use the NVIDIA Performance Primitives (libnpp) to perform image sharpening with +border control. +

+

The following additional options are accepted: +

+
border_type
+

Type of sampling to be used ad frame borders. One of the following: +

+
replicate
+

Replicate pixel values. +

+
+
+
+
+ + +

31.2.4 transpose_npp

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

32 OpenCL Video Filters

+ +

Below is a description of the currently available OpenCL video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-opencl. +

+

Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device opencl[=name][:device[,key=value...]]
+

Initialise a new hardware device of type opencl called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it. +
    +
    -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
    +
    +
+ +

Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded(hwdownload) back to normal memory. Note that hwupload will upload to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it may be necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

32.1 avgblur_opencl

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 1024] and default value is 1. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 1024] and default value is 0. If zero, sizeX value will be used. +

+
+ + +

32.1.1 Example

+ +
    +
  • Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +
    +
    -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
    +
    +
+ + +

32.2 boxblur_opencl

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

32.2.1 Examples

+ +

Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses luma_radius, chroma_radius, alpha_radius for each plane respectively. The filter will apply luma_power, chroma_power, alpha_power times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +

+
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radius +set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image. +
    +
    -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
    +-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
    +
    + +
  • Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7. + +

    For the luma plane, a 2x2 box radius will be run once. +

    +

    For the chroma plane, a 4x4 box radius will be run 5 times. +

    +

    For the alpha plane, a 3x3 box radius will be run 7 times. +

    +
    -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
    +
    +
+ + +

32.3 colorkey_opencl

+

RGB colorspace color keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

32.3.1 Examples

+ +
    +
  • Make every semi-green pixel in the input transparent with some slight blending: +
    +
    -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
    +
    +
+ + +

32.4 convolution_opencl

+ +

Apply convolution of 3x3, 5x5, 7x7 matrix. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed numbers. +Default value for each plane is 0 0 0 0 1 0 0 0 0. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be sum of all matrix elements. +The option value must be a float number greater or equal to 0.0. Default value is 1.0. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. +The option value must be a float number greater or equal to 0.0. Default value is 0.0. +

+
+
+ + +

32.4.1 Examples

+ +
    +
  • Apply sharpen: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0, hwdownload" OUTPUT
    +
    + +
  • Apply blur: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9, hwdownload" OUTPUT
    +
    + +
  • Apply edge enhance: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply edge detect: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT
    +
    + +
  • Apply emboss: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2, hwdownload" OUTPUT
    +
    +
+ + +

32.5 erosion_opencl

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

32.5.1 Example

+ +
    +
  • Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

32.6 deshake_opencl

+

Feature-point based video stabilization filter. +

+

The filter accepts the following options: +

+
+
tripod
+

Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to 0. +

+
+
debug
+

Whether or not additional debug info should be displayed, both in the processed output and in the console. +

+

Note that in order to see console debug output you will also need to pass -v verbose to ffmpeg. +

+

Viewing point matches in the output video is only supported for RGB input. +

+

Defaults to 0. +

+
+
adaptive_crop
+

Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels. +

+

Defaults to 1. +

+
+
refine_features
+

Whether or not feature points should be refined at a sub-pixel level. +

+

This can be turned off for a slight performance gain at the cost of precision. +

+

Defaults to 1. +

+
+
smooth_strength
+

The strength of the smoothing applied to the camera path from 0.0 to 1.0. +

+

1.0 is the maximum smoothing strength while values less than that result in less smoothing. +

+

0.0 causes the filter to adaptively choose a smoothing strength on a per-frame basis. +

+

Defaults to 0.0. +

+
+
smooth_window_multiplier
+

Controls the size of the smoothing window (the number of frames buffered to determine motion information from). +

+

The size of the smoothing window is determined by multiplying the framerate of the video by this number. +

+

Acceptable values range from 0.1 to 10.0. +

+

Larger values increase the amount of motion data available for determining how to smooth the camera path, +potentially improving smoothness, but also increase latency and memory usage. +

+

Defaults to 2.0. +

+
+
+ + +

32.6.1 Examples

+ +
    +
  • Stabilize a video with a fixed, medium smoothing strength: +
    +
    -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
    +
    + +
  • Stabilize a video with debugging (both in console and in rendered video): +
    +
    -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
    +
    +
+ + +

32.7 dilation_opencl

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

32.7.1 Example

+ +
    +
  • Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

32.8 nlmeans_opencl

+ +

Non-local Means denoise filter through OpenCL, this filter accepts same options as nlmeans. +

+ +

32.9 overlay_opencl

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires same memory layout for all the inputs. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

32.9.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    +
  • The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    + +
+ + +

32.10 pad_opencl

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

32.11 prewitt_opencl

+ +

Apply the Prewitt operator (https://en.wikipedia.org/wiki/Prewitt_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

32.11.1 Example

+ +
    +
  • Apply the Prewitt operator with scale set to 2 and delta set to 10. +
    +
    -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

32.12 program_opencl

+ +

Filter video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
inputs
+

Number of inputs to the filter. Defaults to 1. +

+
+
size, s
+

Size of output frames. Defaults to the same as the first input. +

+
+
+ +

The program_opencl filter also supports the framesync options. +

+

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

  • Frame index, unsigned int. + +

    This is a counter starting from zero and increasing by one for each frame. +

  • Source images, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

+ +

Example programs: +

+
    +
  • Copy the input to the output (output must be the same size as the input). +
    __kernel void copy(__write_only image2d_t destination,
    +                   unsigned int index,
    +                   __read_only  image2d_t source)
    +{
    +    const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
    +
    +    int2 location = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = read_imagef(source, sampler, location);
    +
    +    write_imagef(destination, location, value);
    +}
    +
    +
  • Apply a simple transformation, rotating the input by an amount increasing +with the index counter. Pixel values are linearly interpolated by the +sampler, and the output need not have the same dimensions as the input. +
    __kernel void rotate_image(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float angle = (float)index / 100.0f;
    +
    +    float2 dst_dim = convert_float2(get_image_dim(dst));
    +    float2 src_dim = convert_float2(get_image_dim(src));
    +
    +    float2 dst_cen = dst_dim / 2.0f;
    +    float2 src_cen = src_dim / 2.0f;
    +
    +    int2   dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float2 dst_pos = convert_float2(dst_loc) - dst_cen;
    +    float2 src_pos = {
    +        cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
    +        sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
    +    };
    +    src_pos = src_pos * src_dim / dst_dim;
    +
    +    float2 src_loc = src_pos + src_cen;
    +
    +    if (src_loc.x < 0.0f      || src_loc.y < 0.0f ||
    +        src_loc.x > src_dim.x || src_loc.y > src_dim.y)
    +        write_imagef(dst, dst_loc, 0.5f);
    +    else
    +        write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
    +}
    +
    +
  • Blend two inputs together, with the amount of each input used varying +with the index counter. +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
    +
    +    int2  dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +    int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
    +    int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
    +
    +    float4 val1 = read_imagef(src1, sampler, src1_loc);
    +    float4 val2 = read_imagef(src2, sampler, src2_loc);
    +
    +    write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
    +}
    +
    +
+ + +

32.13 remap_opencl

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 32bit float pixel format, single channel. +

+
+
interp
+

Specify interpolation used for remapping of pixels. +Allowed values are near and linear. +Default value is linear. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

32.14 roberts_opencl

+

Apply the Roberts cross operator (https://en.wikipedia.org/wiki/Roberts_cross) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

32.14.1 Example

+ +
    +
  • Apply the Roberts cross operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

32.15 sobel_opencl

+ +

Apply the Sobel operator (https://en.wikipedia.org/wiki/Sobel_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

32.15.1 Example

+ +
    +
  • Apply sobel operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

32.16 tonemap_opencl

+ +

Perform HDR(PQ/HLG) to SDR conversion with tone-mapping. +

+

It accepts the following parameters: +

+
+
tonemap
+

Specify the tone-mapping operator to be used. Same as tonemap option in tonemap. +

+
+
param
+

Tune the tone mapping algorithm. same as param option in tonemap. +

+
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default value is 0.5, and the algorithm here is a little different from +the cpu version tonemap currently. A setting of 0.0 disables this option. +

+
+
threshold
+

The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold +is used to detect whether the scene has changed or not. If the distance between +the current frame average brightness and the current running average exceeds +a threshold value, we would re-calculate scene average and peak brightness. +The default value is 0.2. +

+
+
format
+

Specify the output pixel format. +

+

Currently supported formats are: +

+
p010
+
nv12
+
+ +
+
range, r
+

Set the output color range. +

+

Possible values are: +

+
tv/mpeg
+
pc/jpeg
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the output color primaries. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is bt709. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Possible value are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
+ + +

32.16.1 Example

+ +
    +
  • Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator. +
    +
    -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
    +
    +
+ + +

32.17 unsharp_opencl

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. +Range is [-10, 10] and default value is 1.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. +Range is [-10, 10] and default value is 0.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

32.17.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
    +
    +
+ + +

32.18 xfade_opencl

+ +

Cross fade two videos with custom transition effect by using OpenCL. +

+

It accepts the following options: +

+
+
transition
+

Set one of possible transition effects. +

+
+
custom
+

Select custom transition effect, the actual transition description +will be picked from source and kernel options. +

+
+
fade
+
wipeleft
+
wiperight
+
wipeup
+
wipedown
+
slideleft
+
slideright
+
slideup
+
slidedown
+
+

Default transition is fade. +

+
+ +
+
source
+

OpenCL program source file for custom transition. +

+
+
kernel
+

Set name of kernel to use for custom transition from program source file. +

+
+
duration
+

Set duration of video transition. +

+
+
offset
+

Set time of start of transition relative to first video. +

+
+ +

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

    +
  • First Source image, __read_only image2d_t. +Second Source image, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

    +
  • Transition progress, float. This value is always between 0 and 1 inclusive. +
+ +

Example programs: +

+
    +
  • Apply dots curtain transition effect: +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2,
    +                           float progress)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +    int2  p = (int2)(get_global_id(0), get_global_id(1));
    +    float2 rp = (float2)(get_global_id(0), get_global_id(1));
    +    float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
    +    rp = rp / dim;
    +
    +    float2 dots = (float2)(20.0, 20.0);
    +    float2 center = (float2)(0,0);
    +    float2 unused;
    +
    +    float4 val1 = read_imagef(src1, sampler, p);
    +    float4 val2 = read_imagef(src2, sampler, p);
    +    bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
    +
    +    write_imagef(dst, p, next ? val1 : val2);
    +}
    +
    +
+ + + +

33 VAAPI Video Filters

+ +

VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vaapi. +

+

To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/VAAPI +

+ +

33.1 overlay_vaapi

+ +

Overlay one video on the top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +

+

The filter accepts the following options: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

Default value is "0" for both expressions. +

+
+
w
+
h
+

Set expressions for the width and height the overlaid video +on the main video. +

+

Default values are ’overlay_iw’ for ’w’ and ’overlay_ih*w/overlay_iw’ for ’h’. +

+

The expressions can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_iw
+
overlay_ih
+

The overlay input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay output width and height. +

+
+
overlay_x, x
+
overlay_y, y
+

Position of the overlay layer inside of main +

+
+
+ +
+
alpha
+

Set transparency of overlaid video. Allowed range is 0.0 to 1.0. +Higher value means lower transparency. +Default value is 1.0. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+

33.1.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs for this filter are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_vaapi" OUTPUT
    +
    +
  • Overlay an image LOGO at the offset (200, 100) from the top-left corner of the INPUT video. +The inputs have same memory layout for color channels, the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_vaapi=x=200:y=100:w=400:h=300:alpha=1.0, hwdownload, format=nv12" OUTPUT
    +
    + +
+ + +

33.2 tonemap_vaapi

+ +

Perform HDR-to-SDR or HDR-to-HDR tone-mapping. +It currently only accepts HDR10 as input. +

+

It accepts the following parameters: +

+
+
format
+

Specify the output pixel format. +

+

Default is nv12 for HDR-to-SDR tone-mapping and p010 for HDR-to-HDR +tone-mapping. +

+
+
primaries, p
+

Set the output color primaries. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
display
+

Set the output mastering display colour volume. It is given by a ’|’-separated +list of two values, two values are space separated. It set display primaries +x & y in G, B, R order, then white point x & y, the nominal minimum & maximum +display luminances. +

+

HDR-to-HDR tone-mapping will be performed when this option is set. +

+
+
light
+

Set the output content light level information. It accepts 2 space-separated +values, the first input is the maximum light level and the second input is +the maximum average light level. +

+

It is ignored for HDR-to-SDR tone-mapping, and optional for HDR-to-HDR +tone-mapping. +

+
+
+ + +

33.2.1 Example

+ +
    +
  • Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format +
    +
    tonemap_vaapi=format=p010:t=bt2020-10
    +
    +
  • Convert HDR video to HDR video +
    +
    tonemap_vaapi=display=7500\ 3000|34000\ 16000|13250\ 34500|15635\ 16450|500\ 10000000
    +
    +
+ + +

33.3 hstack_vaapi

+

Stack input videos horizontally. +

+

This is the VA-API variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

33.4 vstack_vaapi

+

Stack input videos vertically. +

+

This is the VA-API variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

33.5 xstack_vaapi

+

Stack video inputs into custom layout. +

+

This is the VA-API variant of the xstack filter, each input stream may +have different size, this filter will scale down/up each input stream to the +given output size, or the size of the first input stream. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_vaapi=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + +

33.6 pad_vaapi

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

33.7 drawbox_vaapi

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

Specify the color of the box to write. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

With value 1, the pixels of the painted box will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input video. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
t
+

The thickness of the drawn box. +

+
+
+ + +

33.7.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + + +

34 VideoToolbox Video Filters

+ +

Below is a description of the currently available VideoToolbox video filters. +

+

VideoToolbox filter depends on VideoToolbox framework, and is auto detected +when building ffmpeg for an Apple platform such as macOS. Add +--enable-videotoolbox to configure if autodetect is disabled. +

+ +

34.1 scale_vt

+ +

Scale and convert the color parameters using VTPixelTransferSession. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+
+
color_matrix
+

Set the output colorspace matrix. +

+
+
color_primaries
+

Set the output color primaries. +

+
+
color_transfer
+

Set the output transfer characteristics. +

+
+
+ + +

34.1.1 Examples

+ +
    +
  • Perform HDR to SDR conversion, and scale to half size of input +
    +
    ffmpeg -hwaccel videotoolbox \
    +        -hwaccel_output_format videotoolbox_vld \
    +        -i hdr.mov \
    +        -c:v hevc_videotoolbox \
    +        -profile:v main \
    +        -b:v 3M \
    +        -vf scale_vt=w=iw/2:h=ih/2:color_matrix=bt709:color_primaries=bt709:color_transfer=bt709 \
    +        -c:a copy \
    +        -tag:v hvc1 \
    +        sdr.mp4
    +
    + +
+ + +

34.2 transpose_vt

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+
‘hflip’
+

Flip the input video horizontally. +

+
+
‘vflip’
+

Flip the input video vertically. +

+
+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

35 Vulkan Video Filters

+ +

Below is a description of the currently available Vulkan video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vulkan and either --enable-libglslang or --enable-libshaderc. +

+

Running Vulkan filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device vulkan[=name][:device[,key=value...]]
+

Initialise a new hardware device of type vulkan called name, using the +given device parameters and options in key=value. The following options +are supported: +

+
+
debug
+

Switches validation layers on if set to 1. +

+
+
linear_images
+

Allocates linear images. Does not apply to decoding. +

+
+
disable_multiplane
+

Disables multiplane images. Does not apply to decoding. +

+
+
avoid_host_import
+

Avoids the use of dynamic host memory imports, in favor of a regular memcpy() +into a previously mapped buffer. +

+
+ +
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device and running nlmeans_vulkan filter with default parameters on it. +
    +
    -init_hw_device vulkan=vk:0 -filter_hw_device vk -i INPUT -vf "hwupload,nlmeans_vulkan,hwdownload" OUTPUT
    +
    +
+ +

As Vulkan filters are not able to access frame data in normal memory, all frame data needs to be uploaded (hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded (hwdownload) back to normal memory. Note that hwupload will upload to a frame with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it is usually necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

35.1 avgblur_vulkan

+ +

Apply an average blur filter, implemented on the GPU using Vulkan. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 32] and default value is 3. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 32] and default value is 3. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+ + +

35.2 blend_vulkan

+ +

Blend two Vulkan frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘normal’
+
‘multiply’
+
+ +
+
+ + +

35.3 bwdif_vulkan

+ +

Deinterlacer using bwdif, the "Bob Weaver Deinterlacing Filter" algorithm, implemented +on the GPU using Vulkan. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

35.4 chromaber_vulkan

+ +

Apply an effect that emulates chromatic aberration. Works best with RGB inputs, +but provides a similar effect with YCbCr inputs too. +

+
+
dist_x
+

Horizontal displacement multiplier. Each chroma pixel’s position will be multiplied +by this amount, starting from the center of the image. Default is 0. +

+
+
dist_y
+

Similarly, this sets the vertical displacement multiplier. Default is 0. +

+
+
+ + +

35.5 color_vulkan

+ +

Video source that creates a Vulkan frame of a solid color. +Useful for benchmarking, or overlaying. +

+

It accepts the following parameters: +

+
+
color
+

The color to use. Either a name, or a hexadecimal value. +The default value is black. +

+
+
size
+

The size of the output frame. Default value is 1920x1080. +

+
+
rate
+

The framerate to output at. Default value is 60 frames per second. +

+
+
duration
+

The video duration. Default value is -0.000001. +

+
+
sar
+

The video signal aspect ratio. Default value is 1/1. +

+
+
format
+

The pixel format of the output Vulkan frames. Default value is yuv444p. +

+
+
out_range
+

Set the 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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
+ + +

35.6 vflip_vulkan

+ +

Flips an image vertically. +

+ +

35.7 hflip_vulkan

+ +

Flips an image horizontally. +

+ +

35.8 flip_vulkan

+ +

Flips an image along both the vertical and horizontal axis. +

+ +

35.9 gblur_vulkan

+ +

Apply Gaussian blur filter on Vulkan frames. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
size
+

Set the kernel size along the horizontal axis. Default is 19. +

+
+
sizeV
+

Set the kernel size along the vertical axis. Default is 0, +which sets to use the same value as size. +

+
+
+ + +

35.10 nlmeans_vulkan

+ +

Denoise frames using Non-Local Means algorithm, implemented on the GPU using +Vulkan. +Supports more pixel formats than nlmeans or nlmeans_opencl, including +alpha channel support. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength for all components. Default is 1.0. Must be in range [0.0, 100.0]. +

+
+
p
+

Set patch size for all planes. Default is 7. Must be odd number in range [0, 99]. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
t
+

Set parallelism. Default is 8. Must be a number in the range [1, 64]. +Larger values will use more VRAM but may not result in greater speed. +The optimal value is hardware and input dependent. +

+
+
s0
+
s1
+
s2
+
s3
+

Set denoising strength for a specific component. Default is 1.0, equal to s. +Must be in range [0.0, 100.0]. 0.0 disables denoising in that component. +

+
+
p0
+
p1
+
p2
+
p3
+

Set patch size for a specific component. Default is 7, equal to p. +Must be odd number in range [0, 99]. +

+
+
+ + +

35.11 overlay_vulkan

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires all inputs to use the same pixel format. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

35.12 transpose_vulkan

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

36 QSV Video Filters

+ +

Below is a description of the currently available QSV video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-libmfx or --enable-libvpl. +

+

To use QSV filters, you need to setup the QSV device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/QuickSync +

+ +

36.1 hstack_qsv

+

Stack input videos horizontally. +

+

This is the QSV variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

36.2 vstack_qsv

+

Stack input videos vertically. +

+

This is the QSV variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

36.3 xstack_qsv

+

Stack video inputs into custom layout. +

+

This is the QSV variant of the xstack filter. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_qsv=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + + +

37 Video Sources

+ +

Below is a description of the currently available video sources. +

+ +

37.1 buffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
+
video_size
+

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. +

+
+
width
+

The input video width. +

+
+
height
+

The input video height. +

+
+
pix_fmt
+

A string representing the pixel format of the buffered video frames. +It may be a number corresponding to a pixel format, or a pixel format +name. +

+
+
time_base
+

Specify the timebase assumed by the timestamps of the buffered frames. +

+
+
frame_rate
+

Specify the frame rate expected for the video stream. +

+
+
colorspace
+

A string representing the color space of the buffered video frames. +It may be a number corresponding to a color space, or a color space +name. +

+
+
range
+

A string representing the color range of the buffered video frames. +It may be a number corresponding to a color range, or a color range +name. +

+
+
alpha_mode
+

A string representing the alpha mode of the buffered video frames. +It may be a number corresponding to an alpha mode, or an alpha mode +name. +

+
+
pixel_aspect, sar
+

The sample (pixel) aspect ratio of the input video. +

+
+
hw_frames_ctx
+

When using a hardware pixel format, this should be a reference to an +AVHWFramesContext describing input frames. +

+
+ +

For example: +

+
buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
+
+ +

will instruct the source to accept video frames with size 320x240 and +with format "yuv410p", assuming 1/24 as the timestamps timebase and +square pixels (1:1 sample aspect ratio). +Since the pixel format with name "yuv410p" corresponds to the number 6 +(check the enum AVPixelFormat definition in libavutil/pixfmt.h), +this example corresponds to: +

+
buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
+
+ +

Alternatively, the options can be specified as a flat string, but this +syntax is deprecated: +

+

width:height:pix_fmt:time_base.num:time_base.den:pixel_aspect.num:pixel_aspect.den +

+ +

37.2 cellauto

+ +

Create a pattern generated by an elementary cellular automaton. +

+

The initial state of the cellular automaton can be defined through the +filename and pattern options. If such options are +not specified an initial state is created randomly. +

+

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 scroll option. +

+

This source accepts the following options: +

+
+
filename, f
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified file. +In the file, each non-whitespace character is considered an alive +cell, a newline will terminate the row, and further characters in the +file will be ignored. +

+
+
pattern, p
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified string. +

+

Each non-whitespace character in the string is considered an alive +cell, a newline will terminate the row, and further characters in the +string will be ignored. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial cellular automaton row. It +is a floating point number value ranging from 0 to 1, defaults to +1/PHI. +

+

This option is ignored when a file or a pattern is specified. +

+
+
random_seed, seed
+

Set the seed for filling randomly the initial row, 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. +

+
+
rule
+

Set the cellular automaton rule, it is a number ranging from 0 to 255. +Default value is 110. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename or pattern is specified, the size is set +by default to the width of the specified initial state row, and the +height is set to width * PHI. +

+

If size is set, it must contain the width of the specified +pattern string, and the specified pattern will be centered in the +larger row. +

+

If a filename or a pattern string is not specified, the size value +defaults to "320x518" (used for a randomly generated initial state). +

+
+
scroll
+

If set to 1, scroll the output upward when all the rows in the output +have been already filled. If set to 0, the new generated row will be +written over the top row just after the bottom row is filled. +Defaults to 1. +

+
+
start_full, full
+

If set to 1, completely fill the output with generated rows before +outputting the first frame. +This is the default behavior, for disabling set the value to 0. +

+
+
stitch
+

If set to 1, stitch the left and right row edges together. +This is the default behavior, for disabling set the value to 0. +

+
+ + +

37.2.1 Examples

+ +
    +
  • Read the initial state from pattern, and specify an output of +size 200x400. +
    +
    cellauto=f=pattern:s=200x400
    +
    + +
  • Generate a random initial row with a width of 200 cells, with a fill +ratio of 2/3: +
    +
    cellauto=ratio=2/3:s=200x200
    +
    + +
  • Create a pattern generated by rule 18 starting by a single alive cell +centered on an initial row with width 100: +
    +
    cellauto=p=@:s=100x400:full=0:rule=18
    +
    + +
  • Specify a more elaborated initial pattern: +
    +
    cellauto=p='@@ @ @@':s=100x400:full=0:rule=18
    +
    + +
+ + +

37.3 coreimagesrc

+

Video source generated on GPU using Apple’s CoreImage API on OSX. +

+

This video source is a specialized version of the coreimage video filter. +Use a core image generator at the beginning of the applied filterchain to +generate the content. +

+

The coreimagesrc video source accepts the following options: +

+
list_generators
+

List all available generators along with all their respective options as well as +possible minimum and maximum values along with the default values. +

+
list_generators=true
+
+ +
+
size, s
+

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. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+ +

Additionally, all options of the coreimage video filter are accepted. +A complete filterchain can be used for further processing of the +generated input without CPU-HOST transfer. See coreimage documentation +and examples for details. +

+ +

37.3.1 Examples

+ +
    +
  • Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +

    This example is equivalent to the QRCode example of coreimage without the +need for a nullsrc video source. +

+ + + +

37.4 ddagrab

+ +

Captures the Windows Desktop via Desktop Duplication API. +

+

The filter exclusively returns D3D11 Hardware Frames, for on-gpu encoding +or processing. So an explicit hwdownload is needed for any kind of +software processing. +

+

It accepts the following options: +

+
+
output_idx
+

DXGI Output Index to capture. +

+

Usually corresponds to the index Windows has given the screen minus one, +so it’s starting at 0. +

+

Defaults to output 0. +

+
+
draw_mouse
+

Whether to draw the mouse cursor. +

+

Defaults to true. +

+

Only affects hardware cursors. If a game or application renders its own cursor, +it’ll always be captured. +

+
+
framerate
+

Maximum framerate at which the desktop will be captured - the interval between +successive frames will not be smaller than the inverse of the framerate. When +dup_frames is true (the default) and the desktop is not being updated +often enough, the filter will duplicate a previous frame. Note that there is no +background buffering going on, so when the filter is not polled often enough +then the actual inter-frame interval may be significantly larger. +

+

Defaults to 30 FPS. +

+
+
video_size
+

Specify the size of the captured video. +

+

Defaults to the full size of the screen. +

+

Cropped from the bottom/right if smaller than screen size. +

+
+
offset_x
+

Horizontal offset of the captured video. +

+
+
offset_y
+

Vertical offset of the captured video. +

+
+
output_fmt
+

Desired filter output format. +Defaults to 8 Bit BGRA. +

+

It accepts the following values: +

+
‘auto’
+

Passes all supported output formats to DDA and returns what DDA decides to use. +

+
‘8bit’
+
‘bgra’
+

8 Bit formats always work, and DDA will convert to them if necessary. +

+
‘10bit’
+
‘x2bgr10’
+

Filter initialization will fail if 10 bit format is requested but unavailable. +

+
+ +
+
dup_frames
+

When this option is set to true (the default), the filter will duplicate frames +when the desktop has not been updated in order to maintain approximately +constant target framerate. When this option is set to false, the filter will +wait for the desktop to be updated (inter-frame intervals may vary significantly +in this case). +

+
+
+ + +

37.4.1 Examples

+ +

Capture primary screen and encode using nvenc: +

+
ffmpeg -f lavfi -i ddagrab -c:v h264_nvenc -cq 18 output.mp4
+
+ +

You can also skip the lavfi device and directly use the filter. +Also demonstrates downloading the frame and encoding with libx264. +Explicit output format specification is required in this case: +

+
ffmpeg -filter_complex ddagrab=output_idx=1:framerate=60,hwdownload,format=bgra -c:v libx264 -crf 18 output.mp4
+
+ +

If you want to capture only a subsection of the desktop, this can be achieved +by specifying a smaller size and its offsets into the screen: +

+
ddagrab=video_size=800x600:offset_x=100:offset_y=100
+
+ + + +

37.5 gfxcapture

+ +

Capture windows or monitors using Windows.Graphics.Capture API. +

+

This source provides low overhead capture of application windows or entire monitors. +The filter outputs hardware frames in d3d11 format; use hwdownload,format= +if system memory frames are required. +

+

The window to be captured can be selected via regular expressions on its title, +class name or backing executable name, by explicit native handles, or by monitor +index or explicit native handle. A window must match all provided expressions to be +selected. The first matching window will be picked, in whatever order Windows +returns them. +

+

Explicit handles (hwnd, hmonitor) override pattern or index +based selection. If neither handles nor a monitor index are given, the first +window matching the provided regular expressions is captured. +

+

This source does NOT hold a stable FPS. It returns frames at whatever rate the compositor +provides them, only capped by the max_framerate. +If you need a stable rate, you need to add an fps filter to drop/duplicate frames as needed. +

+

If the capture source disappears mid-capture (window closed, monitor disconnected), the filter will return EOF. +

+

This source accepts the following options: +

+
window_title
+

ECMAScript regular expression matched against the window title. Supports a +PCRE style (?i) prefix for case-insensitive matching. +

+
+
window_class
+

As window_title, but matched against the window class name. +

+
+
window_exe
+

As window_title, but matched against the executable file name of the +window’s process. +

+
+
monitor_idx
+

Zero-based index of the monitor to capture. +

+

Can also be set to window to capture the monitor the selected window +is displayed on at filter initialization time. +

+
+
hwnd
+

Explicit native window handle (HWND). +

+
+
hmonitor
+

Explicit native monitor handle (HMONITOR). +

+
+
capture_cursor
+

Capture the mouse cursor. Enabled by default. +

+
+
capture_border
+

Capture the full area of the window, including its window decorarions/border. +Disabled by default. +

+
+
display_border
+

Draw a yellow highlight border around the captured window. Disabled by default. +

+
+
max_framerate
+

Maximum capture frame rate. Accepts a video rate (e.g. 30, 60/1, +24000/1001). The default is 60 FPS. +The actual rate is the rate at which the compositor renders the window/monitor, +capped by this option. +

+
+
width
+

Force the output canvas width. If zero (default) the initial captured source +width is used. If a negative number is provided, the width will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
height
+

Force the output canvas height. If zero (default) the initial captured source +height is used. If a negative number is provided, the height will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
crop_left
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_top
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_right
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_bottom
+

Crop this many pixels from the left side of the captured frames. +

+
+
premultiplied
+

If set to 1, return frames with premultiplied alpha. Default is 0 (straight +alpha). +

+
+
resize_mode
+

Defines how the captured content is fitted into the output canvas size. +Possible values: +

+
‘crop’
+

Crop (or pad with black) to the canvas size. (default) +

+
‘scale’
+

Scale the source to fill the canvas, potentially altering aspect ratio. +

+
‘scale_aspect’
+

Scale the source to fit inside the canvas while preserving aspect ratio. +Remaining area is filled with black. +

+
+ +
+
scale_mode
+

Scaling algorithm used when resizing is required. +

+

Possible values: +

+
‘point’
+

Nearest neighbour (pixelated) scaling. +

+
‘bilinear’
+

Bilinear filtering. (default) +

+
‘bicubic’
+

Bicubic filtering. Potentially more blurry, but fewer scaling artifacts depending on contents. +

+
+ +
+
output_fmt
+

Desired output pixel format inside the D3D11 hardware frames. +

+

Possible values: +

+
‘bgra’
+
‘8bit’
+

8 bit BGRA output (default) +

+
‘x2bgr10’
+
‘10bit’
+

10 bit BGR output +

+
‘rgbaf16’
+
‘16bit’
+

16bit float RGBA output +

+
+ +
+
+ + +

37.5.1 Examples

+
    +
  • Capture a window by title (case-insensitive) at a maximum of 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_title='(?i)My Application':max_framerate=60,hwdownload,format=bgra,format=yuv420p -c:v libx264 -crf 15 capture.mp4
    +
    + +
  • Capture monitor 1 at native refresh, 10bit color depth, scale to 1920x1080 preserving aspect: +
    +
    ffmpeg -filter_complex gfxcapture=monitor_idx=1:width=1920:height=1080:resize_mode=scale_aspect:output_fmt=10bit -c:v hevc_nvenc -cq 15 capture.mp4
    +
    + +
  • Capture a window by executable name, draw border, force point scaling, fixed 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_exe='^firefox.exe$':display_border=1:scale_mode=point,fps=60 -rc qvbr -qvbr_quality_level 15 -c:v h264_amf capture.mp4
    +
    + +
+ + + +

37.6 gradients

+

Generate several gradients. +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
c0, c1, c2, c3, c4, c5, c6, c7
+

Set 8 colors. Default values for colors is to pick random one. +

+
+
x0, y0, y0, y1
+

Set gradient line source and destination points. If negative or out of range, random ones +are picked. +

+
+
nb_colors, n
+

Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2. +

+
+
seed
+

Set seed for picking gradient line points. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
speed
+

Set speed of gradients rotation. +

+
+
type, t
+

Set type of gradients. +Available values are: +

+
‘linear’
+
‘radial’
+
‘circular’
+
‘spiral’
+
‘square’
+
+ +

Default type is linear. +

+
+ + +

37.6.1 Commands

+ +

This source supports the some above options as commands. +

+ +

37.7 mandelbrot

+ +

Generate a Mandelbrot set fractal, and progressively zoom towards the +point specified with start_x and start_y. +

+

This source accepts the following options: +

+
+
end_pts
+

Set the terminal pts value. Default value is 400. +

+
+
end_scale
+

Set the terminal scale value. +Must be a floating point value. Default value is 0.3. +

+
+
inner
+

Set the inner coloring mode, that is the algorithm used to draw the +Mandelbrot fractal internal region. +

+

It shall assume one of the following values: +

+
black
+

Set black mode. +

+
convergence
+

Show time until convergence. +

+
mincol
+

Set color based on point closest to the origin of the iterations. +

+
period
+

Set period mode. +

+
+ +

Default value is mincol. +

+
+
bailout
+

Set the bailout value. Default value is 10.0. +

+
+
maxiter
+

Set the maximum of iterations performed by the rendering +algorithm. Default value is 7189. +

+
+
outer
+

Set outer coloring mode. +It shall assume one of following values: +

+
iteration_count
+

Set iteration count mode. +

+
normalized_iteration_count
+

set normalized iteration count mode. +

+
+

Default value is normalized_iteration_count. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
start_scale
+

Set the initial scale value. Default value is 3.0. +

+
+
start_x
+

Set the initial x position. Must be a floating point value between +-100 and 100. Default value is -0.743643887037158704752191506114774. +

+
+
start_y
+

Set the initial y position. Must be a floating point value between +-100 and 100. Default value is -0.131825904205311970493132056385139. +

+
+ + +

37.8 mptestsrc

+ +

Generate various test patterns, as generated by the MPlayer test filter. +

+

The size of the generated video is fixed, and is 512x512. +This source is useful in particular for testing encoding features. +

+

This source accepts the following options: +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
test, t
+
+

Set the number or the name of the test to perform. Supported tests are: +

+
dc_luma
+
dc_chroma
+
freq_luma
+
freq_chroma
+
amp_luma
+
amp_chroma
+
cbp
+
mv
+
ring1
+
ring2
+
all
+
max_frames, m
+

Set the maximum number of frames generated for each test, default value is 30. +

+
+
+ +

Default value is "all", which will cycle through the list of all tests. +

+
+ +

Some examples: +

+
mptestsrc=t=dc_luma
+
+ +

will generate a "dc_luma" test pattern. +

+ +

37.9 frei0r_src

+ +

Provide a frei0r source. +

+

To enable compilation of this filter you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

This source accepts the following parameters: +

+
+
size
+

The size of the video to generate. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
framerate
+

The framerate of the generated video. It may be a string of the form +num/den or a frame rate abbreviation. +

+
+
filter_name
+

The name to the frei0r source to load. For more information regarding frei0r and +how to set the parameters, read the frei0r section in the video filters +documentation. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r source. +

+
+
+ +

For example, to generate a frei0r partik0l source with size 200x200 +and frame rate 10 which is overlaid on the overlay filter main input: +

+
frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
+
+ + +

37.10 life

+ +

Generate a life pattern. +

+

This source is based on a generalization of John Conway’s life game. +

+

The sourced input represents a life grid, each pixel represents a cell +which can be in one of two possible states, alive or dead. Every cell +interacts with its eight neighbours, which are the cells that are +horizontally, vertically, or diagonally adjacent. +

+

At each interaction the grid evolves according to the adopted rule, +which specifies the number of neighbor alive cells which will make a +cell stay alive or born. The rule option allows one to specify +the rule to adopt. +

+

This source accepts the following options: +

+
+
filename, f
+

Set the file from which to read the initial grid state. In the file, +each non-whitespace character is considered an alive cell, and newline +is used to delimit the end of each row. +

+

If this option is not specified, the initial grid is generated +randomly. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial random grid. It is a +floating point number value ranging from 0 to 1, defaults to 1/PHI. +It is ignored when a file is specified. +

+
+
random_seed, seed
+

Set the seed for filling the initial random grid, 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. +

+
+
rule
+

Set the life rule. +

+

A rule can be specified with a code of the kind "SNS/BNB", +where NS and NB are sequences of numbers in the range 0-8, +NS specifies the number of alive neighbor cells which make a +live cell stay alive, and NB the number of alive neighbor cells +which make a dead cell to become alive (i.e. to "born"). +"s" and "b" can be used in place of "S" and "B", respectively. +

+

Alternatively a rule can be specified by an 18-bits integer. The 9 +high order bits are used to encode the next cell state if it is alive +for each number of neighbor alive cells, the low order bits specify +the rule for "borning" new cells. Higher order bits encode for an +higher number of neighbor cells. +For example the number 6153 = (12<<9)+9 specifies a stay alive +rule of 12 and a born rule of 9, which corresponds to "S23/B03". +

+

Default value is "S23/B3", which is the original Conway’s game of life +rule, and will keep a cell alive if it has 2 or 3 neighbor alive +cells, and will born a new cell if there are three alive cells around +a dead cell. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename is specified, the size is set by default to the +same size of the input file. If size is set, it must contain +the size specified in the input file, and the initial grid defined in +that file is centered in the larger resulting area. +

+

If a filename is not specified, the size value defaults to "320x240" +(used for a randomly generated initial grid). +

+
+
stitch
+

If set to 1, stitch the left and right grid edges together, and the +top and bottom edges also. Defaults to 1. +

+
+
mold
+

Set cell mold speed. If set, a dead cell will go from death_color to +mold_color with a step of mold. mold can have a +value from 0 to 255. +

+
+
life_color
+

Set the color of living (or new born) cells. +

+
+
death_color
+

Set the color of dead cells. If mold is set, this is the first color +used to represent a dead cell. +

+
+
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. +

+
+ + +

37.10.1 Examples

+ +
    +
  • Read a grid from pattern, and center it on a grid of size +300x300 pixels: +
    +
    life=f=pattern:s=300x300
    +
    + +
  • Generate a random grid of size 200x200, with a fill ratio of 2/3: +
    +
    life=ratio=2/3:s=200x200
    +
    + +
  • Specify a custom rule for evolving a randomly generated grid: +
    +
    life=rule=S14/B34
    +
    + +
  • Full example with slow death effect (mold) using ffplay: +
    +
    ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
    +
    +
+ + +

37.11 perlin

+

Generate Perlin noise. +

+

Perlin noise is a kind of noise with local continuity in space. This +can be used to generate patterns with continuity in space and time, +e.g. to simulate smoke, fluids, or terrain. +

+

In case more than one octave is specified through the octaves +option, Perlin noise is generated as a sum of components, each one +with doubled frequency. In this case the persistence option +specify the ratio of the amplitude with respect to the previous +component. More octave components enable to specify more high +frequency details in the generated noise (e.g. small size variations +due to boulders in a generated terrain). +

+ +

37.11.1 Options

+
+
size, s
+

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. +Default value is 320x240. +

+
+
rate, r
+

Specify the frame rate expected for the video stream, expressed as a +number of frames per second. Default value is 25. +

+
+
octaves
+

Specify the total number of components making up the noise, each one +with doubled frequency. Default value is 1. +

+
+
persistence
+

Set the ratio used to compute the amplitude of the next octave +component with respect to the previous component amplitude. Default +value is 1. +

+
+
xscale
+
yscale
+

Define a scale factor used to multiple the x, y coordinates. This can +be useful to define an effect with a pattern stretched along the x or +y axis. Default value is 1. +

+
+
tscale
+

Define a scale factor used to multiple the time coordinate. This can +be useful to change the time variation speed. Default value is 1. +

+
+
random_mode
+

Set random mode used to compute initial pattern. +

+

Supported values are: +

+
random
+

Compute and use random seed. +

+
+
ken
+

Use the predefined initial pattern defined by Ken Perlin in the +original article, can be useful to compare the output with other +sources. +

+
+
seed
+

Use the value specified by random_seed option. +

+
+ +

Default value is random. +

+
+
random_seed, seed
+

When random_mode is set to random_seed, use this value +to compute the initial pattern. Default value is 0. +

+
+ + +

37.11.2 Examples

+
    +
  • Generate single component: +
    +
    perlin
    +
    + +
  • Use Perlin noise with 7 components, each one with a halved contribution +to total amplitude: +
    +
    perlin=octaves=7:persistence=0.5
    +
    + +
  • Chain Perlin noise with the lutyuv to generate a black&white +effect: +
    +
    perlin=octaves=3:tscale=0.3,lutyuv=y='if(lt(val\,128)\,255\,0)'
    +
    + +
  • Stretch noise along the y axis, and convert gray level to red-only +signal: +
    +
    perlin=octaves=7:tscale=0.4:yscale=0.3,lutrgb=r=val:b=0:g=0
    +
    +
+ + +

37.12 qrencodesrc

+ +

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/). +

+

To enable the compilation of this source, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and put in the video output according to the +specified output size options. +

+

In case no text is specified, the QR code is not generated, but an empty colored +output is returned instead. +

+

This source accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated only once, when initializing the source. +See the qrencode Expressions section for details. +

+

Note that some of the constants are missing for the source (for example the +x or t or ¸n), since they only makes sense when evaluating the +expression for each frame rather than at initialization time. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

37.12.1 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size: +
    +
    qrencodesrc=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencodesrc=text=www.ffmpeg.org:bc=pink:fc=blue
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencodesrc=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencodesrc=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencodesrc=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencodesrc=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencodesrc=text=%{pts}
    +
    + +
+ + +

37.13 allrgb, allyuv, color, colorchart, colorspectrum, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc

+ +

The allrgb source returns frames of size 4096x4096 of all rgb colors. +

+

The allyuv source returns frames of size 4096x4096 of all yuv colors. +

+

The color source provides an uniformly colored input. +

+

The colorchart source provides a colors checker chart. +

+

The colorspectrum source provides a color spectrum input. +

+

The haldclutsrc source provides an identity Hald CLUT. See also +haldclut filter. +

+

The 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. +

+

The pal75bars source generates a color bars pattern, based on +EBU PAL recommendations with 75% color levels. +

+

The pal100bars source generates a color bars pattern, based on +EBU PAL recommendations with 100% color levels. +

+

The rgbtestsrc source generates an RGB test pattern useful for +detecting RGB vs BGR issues. You should see a red, green and blue +stripe from top to bottom. +

+

The smptebars source generates a color bars pattern, based on +the SMPTE Engineering Guideline EG 1-1990. +

+

The smptehdbars source generates a color bars pattern, based on +the SMPTE RP 219-2002. +

+

The testsrc source generates a test video pattern, showing a +color pattern, a scrolling gradient and a timestamp. This is mainly +intended for testing purposes. +

+

The testsrc2 source is similar to testsrc, but supports more +pixel formats instead of just rgb24. This allows using it as an +input for other tests without requiring a format conversion. +

+

The yuvtestsrc source generates an YUV test pattern. You should +see a y, cb and cr stripe from top to bottom. +

+

The sources accept the following parameters: +

+
+
level
+

Specify the level of the Hald CLUT, only available in the haldclutsrc +source. A level of N generates a picture of N*N*N by N*N*N +pixels to be used as identity matrix for 3D lookup tables. Each component is +coded on a 1/(N*N) scale. +

+
+
color, c
+

Specify the color of the source, only available in the color +source. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +

+
+
size, s
+

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 allrgb, allyuv, and +haldclutsrc filters. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+

Since the frame rate is used as time base, all frames including the last one +will have their full duration. If the specified duration is not a multiple +of the frame duration, it will be rounded up. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
alpha
+

Specify the alpha (opacity) of the background, only available in the +testsrc2 source. The value must be between 0 (fully transparent) and +255 (fully opaque, the default). +

+
+
decimals, n
+

Set the number of decimals to show in the timestamp, only available in the +testsrc source. +

+

The displayed timestamp value will correspond to the original +timestamp value multiplied by the power of 10 of the specified +value. Default value is 0. +

+
+
type
+

Set the type of the color spectrum, only available in the +colorspectrum source. Can be one of the following: +

+
+
‘black’
+
‘white’
+
‘all’
+
+ +
+
patch_size
+

Set patch size of single color patch, only available in the +colorchart source. Default is 64x64. +

+
+
preset
+

Set colorchecker colors preset, only available in the +colorchart source. +

+

Available values are: +

+
‘reference’
+
‘skintones’
+
+ +

Default value is reference. +

+
+ + +

37.13.1 Examples

+ +
    +
  • Generate a video with a duration of 5.3 seconds, with size +176x144 and a frame rate of 10 frames per second: +
    +
    testsrc=duration=5.3:size=qcif:rate=10
    +
    + +
  • The following graph description will generate a red source +with an opacity of 0.2, with size "qcif" and a frame rate of 10 +frames per second: +
    +
    color=c=red@0.2:s=qcif:r=10
    +
    + +
  • If the input content is to be ignored, nullsrc can be used. The +following command generates noise in the luma plane by employing +the geq filter: +
    +
    nullsrc=s=256x256, geq=random(1)*255:128:128
    +
    +
+ + +

37.13.2 Commands

+ +

The color source supports the following commands: +

+
+
c, color
+

Set the color of the created image. Accepts the same syntax of the +corresponding color option. +

+
+ + +

37.14 openclsrc

+ +

Generate video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
size, s
+

Size of frames to generate. This must be set. +

+
+
format
+

Pixel format to use for the generated frames. This must be set. +

+
+
rate, r
+

Number of frames generated every second. Default value is ’25’. +

+
+
+ +

For details of how the program loading works, see the program_opencl +filter. +

+

Example programs: +

+
    +
  • Generate a colour ramp by setting pixel values from the position of the pixel +in the output image. (Note that this will work with all pixel formats, but +the generated output will not be the same.) +
    __kernel void ramp(__write_only image2d_t dst,
    +                   unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 val;
    +    val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
    +
    +    write_imagef(dst, loc, val);
    +}
    +
    +
  • Generate a Sierpinski carpet pattern, panning by a single pixel each frame. +
    __kernel void sierpinski_carpet(__write_only image2d_t dst,
    +                                unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = 0.0f;
    +    int x = loc.x + index;
    +    int y = loc.y + index;
    +    while (x > 0 || y > 0) {
    +        if (x % 3 == 1 && y % 3 == 1) {
    +            value = 1.0f;
    +            break;
    +        }
    +        x /= 3;
    +        y /= 3;
    +    }
    +
    +    write_imagef(dst, loc, value);
    +}
    +
    +
+ + +

37.15 sierpinski

+ +

Generate a Sierpinski carpet/triangle fractal, and randomly pan around. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
seed
+

Set seed which is used for random panning. +

+
+
jump
+

Set max jump for single pan destination. Allowed range is from 1 to 10000. +

+
+
type
+

Set fractal type, can be default carpet or triangle. +

+
+ + +

37.16 zoneplate

+

Generate a zoneplate test video pattern. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "320x240". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
precision
+

Set precision in bits for look-up table for sine calculations. Default value is 10. +Allowed range is from 4 to 16. +

+
+
xo
+

Set horizontal axis offset for output signal. Default value is 0. +

+
+
yo
+

Set vertical axis offset for output signal. Default value is 0. +

+
+
to
+

Set time axis offset for output signal. Default value is 0. +

+
+
k0
+

Set 0-order, constant added to signal phase. Default value is 0. +

+
+
kx
+

Set 1-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky
+

Set 1-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt
+

Set 1-order, phase factor multiplier for time axis. Default value is 0. +

+
+
kxt, kyt, kxy
+

Set phase factor multipliers for combination of spatial and temporal axis. +Default value is 0. +

+
+
kx2
+

Set 2-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky2
+

Set 2-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt2
+

Set 2-order, phase factor multiplier for time axis. Default value is 0. +

+
+
ku
+

Set the constant added to final phase to produce chroma-blue component of signal. +Default value is 0. +

+
+
kv
+

Set the constant added to final phase to produce chroma-red component of signal. +Default value is 0. +

+
+ + +

37.16.1 Commands

+ +

This source supports the some above options as commands. +

+ +

37.16.2 Examples

+ +
    +
  • Generate horizontal color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:kx2=256:s=wvga:xo=-426:kt=11
    +
    + +
  • Generate vertical color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:ky2=156:s=wvga:yo=-240:kt=11
    +
    + +
  • Generate circular zone-plate: +
    +
    zoneplate=ku=512:kv=100:kt2=0:ky2=256:kx2=556:s=wvga:yo=0:kt=11
    +
    +
+ + + +

38 Video Sinks

+ +

Below is a description of the currently available video sinks. +

+ +

38.1 buffersink

+ +

Buffer video frames, and make them available to the end of the filter +graph. +

+

This sink is mainly intended for programmatic use, in particular +through the interface defined in libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVBufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+ +

38.2 nullsink

+ +

Null video sink: do absolutely nothing with the input video. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

39 Multimedia Filters

+ +

Below is a description of the currently available multimedia filters. +

+ +

39.1 a3dscope

+ +

Convert input audio to 3d scope video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
fov
+

Set the camera field of view. Default is 90 degrees. +Allowed range is from 40 to 150. +

+
+
roll
+

Set the camera roll. +

+
+
pitch
+

Set the camera pitch. +

+
+
yaw
+

Set the camera yaw. +

+
+
xzoom
+

Set the camera zoom on X-axis. +

+
+
yzoom
+

Set the camera zoom on Y-axis. +

+
+
zzoom
+

Set the camera zoom on Z-axis. +

+
+
xpos
+

Set the camera position on X-axis. +

+
+
ypos
+

Set the camera position on Y-axis. +

+
+
zpos
+

Set the camera position on Z-axis. +

+
+
length
+

Set the length of displayed audio waves in number of frames. +

+
+ + +

39.1.1 Commands

+ +

Filter supports the some above options as commands. +

+ +

39.2 abitscope

+ +

Convert input audio to a video output, displaying the audio bit scope. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 1024x256. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channels. Unrecognized or missing colors will be replaced +by white color. +

+
+
mode, m
+

Set output mode. Can be bars or trace. Default is bars. +

+
+ + +

39.3 adrawgraph

+

Draw a graph using input audio metadata. +

+

See drawgraph +

+ +

39.4 agraphmonitor

+ +

See graphmonitor. +

+ +

39.5 ahistogram

+ +

Convert input audio to a video output, displaying the volume histogram. +

+

The filter accepts the following options: +

+
+
dmode
+

Specify how histogram is calculated. +

+

It accepts the following values: +

+
‘single’
+

Use single histogram for all channels. +

+
‘separate’
+

Use separate histogram for each channel. +

+
+

Default is single. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
scale
+

Set display scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘sqrt’
+

square root +

+
‘cbrt’
+

cubic root +

+
‘lin’
+

linear +

+
‘rlog’
+

reverse logarithmic +

+
+

Default is log. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘lin’
+

linear +

+
+

Default is log. +

+
+
acount
+

Set how much frames to accumulate in histogram. +Default is 1. Setting this to -1 accumulates all frames. +

+
+
rheight
+

Set histogram ratio of window height. +

+
+
slide
+

Set sonogram sliding. +

+

It accepts the following values: +

+
‘replace’
+

replace old rows with new ones. +

+
‘scroll’
+

scroll from top to bottom. +

+
+

Default is replace. +

+
+
hmode
+

Set histogram mode. +

+

It accepts the following values: +

+
‘abs’
+

Use absolute values of samples. +

+
‘sign’
+

Use untouched values of samples. +

+
+

Default is abs. +

+
+ + +

39.6 aphasemeter

+ +

Measures phase of input audio, which is exported as metadata lavfi.aphasemeter.phase, +representing mean phase of current audio frame. A video output can also be produced and is +enabled by default. The audio is passed through as first output. +

+

Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in +range [-1, 1] where -1 means left and right channels are completely out of phase +and 1 means channels are in phase. +

+

The filter accepts the following options, all related to its video output: +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
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 800x400. +

+
+
rc
+
gc
+
bc
+

Specify the red, green, blue contrast. Default values are 2, +7 and 1. +Allowed range is [0, 255]. +

+
+
mpc
+

Set color which will be used for drawing median phase. If color is +none which is default, no median phase value will be drawn. +

+
+
video
+

Enable video output. Default is enabled. +

+
+ + +

39.6.1 phasing detection

+ +

The filter also detects out of phase and mono sequences in stereo streams. +It logs the sequence start, end and duration when it lasts longer or as long as the minimum set. +

+

The filter accepts the following options for this detection: +

+
+
phasing
+

Enable mono and out of phase detection. Default is disabled. +

+
+
tolerance, t
+

Set phase tolerance for mono detection, in amplitude ratio. Default is 0. +Allowed range is [0, 1]. +

+
+
angle, a
+

Set angle threshold for out of phase detection, in degree. Default is 170. +Allowed range is [90, 180]. +

+
+
duration, d
+

Set mono or out of phase duration until notification, expressed in seconds. Default is 2. +

+
+ + +

39.6.2 Examples

+ +
    +
  • Complete example with ffmpeg to detect 1 second of mono with 0.001 phase tolerance: +
    +
    ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
    +
    +
+ + +

39.7 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 monaural 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: +

+
+
mode, m
+

Set the vectorscope mode. +

+

Available values are: +

+
‘lissajous’
+

Lissajous rotated by 45 degrees. +

+
+
‘lissajous_xy’
+

Same as above but not rotated. +

+
+
‘polar’
+

Shape resembling half of circle. +

+
+ +

Default value is ‘lissajous’. +

+
+
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 400x400. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
rc
+
gc
+
bc
+
ac
+

Specify the red, green, blue and alpha contrast. Default values are 40, +160, 80 and 255. +Allowed range is [0, 255]. +

+
+
rf
+
gf
+
bf
+
af
+

Specify the red, green, blue and alpha fade. Default values are 15, +10, 5 and 5. +Allowed range is [0, 255]. +

+
+
zoom
+

Set the zoom factor. Default value is 1. Allowed range is [0, 10]. +Values lower than 1 will auto adjust zoom factor to maximal possible value. +

+
+
draw
+

Set the vectorscope drawing mode. +

+

Available values are: +

+
‘dot’
+

Draw dot for each sample. +

+
+
‘line’
+

Draw line between previous and current sample. +

+
+
‘aaline’
+

Draw anti-aliased line between previous and current sample. +

+
+ +

Default value is ‘dot’. +

+
+
scale
+

Specify amplitude scale of audio samples. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+
‘log’
+

Logarithmic. +

+
+ +
+
swap
+

Swap left channel axis with right channel axis. +

+
+
mirror
+

Mirror axis. +

+
+
‘none’
+

No mirror. +

+
+
‘x’
+

Mirror only x axis. +

+
+
‘y’
+

Mirror only y axis. +

+
+
‘xy’
+

Mirror both axis. +

+
+ +
+
+ + +

39.7.1 Examples

+ +
    +
  • Complete example using ffplay: +
    +
    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]'
    +
    +
+ + +

39.7.2 Commands

+ +

This filter supports the all above options as commands except options size and rate. +

+ +

39.8 bench, abench

+ +

Benchmark part of a filtergraph. +

+

The filter accepts the following options: +

+
+
action
+

Start or stop a timer. +

+

Available values are: +

+
‘start’
+

Get the current time, set it as frame metadata (using the key +lavfi.bench.start_time), and forward the frame to the next filter. +

+
+
‘stop’
+

Get the current time and fetch the lavfi.bench.start_time metadata from +the input frame metadata to get the time difference. Time difference, average, +maximum and minimum time (respectively t, avg, max and +min) are then printed. The timestamps are expressed in seconds. +

+
+
+
+ + +

39.8.1 Examples

+ +
    +
  • Benchmark selectivecolor filter: +
    +
    bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
    +
    +
+ + +

39.9 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: +

+
+
n
+

Set the number of segments. Default is 2. +

+
+
v
+

Set the number of output video streams, that is also the number of video +streams in each segment. Default is 1. +

+
+
a
+

Set the number of output audio streams, that is also the number of audio +streams in each segment. Default is 0. +

+
+
unsafe
+

Activate unsafe mode: do not fail if segments have a different format. +

+
+
+ +

The filter has v+a outputs: first v video outputs, then +a audio outputs. +

+

There are nx(v+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. +

+ +

39.9.1 Examples

+ +
    +
  • Concatenate an opening, an episode and an ending, all in bilingual version +(video in stream 0, audio in streams 1 and 2): +
    +
    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
    +
    + +
  • Concatenate two parts, handling audio and video separately, using the +(a)movie sources, and adjusting the resolution: +
    +
    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]
    +
    +

    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. +

    +
+ + +

39.9.2 Commands

+ +

This filter supports the following commands: +

+
next
+

Close the current segment and step to the next one +

+
+ + +

39.10 ebur128

+ +

EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness +level. By default, it logs a message at a frequency of 10Hz with the +Momentary loudness (identified by M), Short-term loudness (S), +Integrated loudness (I) and Loudness Range (LRA). +

+

The filter can only analyze streams which have +sample format is double-precision floating point. The input stream will be converted to +this specification, if needed. Users may need to insert aformat and/or aresample filters +after this filter to obtain the original parameters. +

+

The filter also has a video output (see the 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), but can optionally be configured +to instead display short-term loudness (see gauge). +

+

The green area marks a +/- 1LU target range around the target loudness +(-23LUFS by default, unless modified through target). +

+

More information about the Loudness Recommendation EBU R128 on +http://tech.ebu.ch/loudness. +

+

The filter accepts the following options: +

+
+
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 0. +

+
+
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 640x480. +

+
+
meter
+

Set the EBU scale meter. Default is 9. Common values are 9 and +18, respectively for EBU scale meter +9 and EBU scale meter +18. Any +other integer value between this range is allowed. +

+
+
metadata
+

Set metadata injection. If set to 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 lavfi.r128.. +

+

Default is 0. +

+
+
framelog
+

Force the frame logging level. +

+

Available values are: +

+
‘quiet’
+

logging disabled +

+
‘info’
+

information logging level +

+
‘verbose’
+

verbose logging level +

+
+ +

By default, the logging level is set to info. If the video or +the metadata options are set, it switches to verbose. +

+
+
peak
+

Set peak mode(s). +

+

Available modes can be cumulated (the option is a flag type). Possible +values are: +

+
‘none’
+

Disable any peak mode (default). +

+
‘sample’
+

Enable sample-peak mode. +

+

Simple peak mode looking for the higher sample value. It logs a message +for sample-peak (identified by SPK). +

+
‘true’
+

Enable true-peak mode. +

+

If enabled, the peak lookup is done on an over-sampled version of the input +stream for better peak accuracy. It logs a message for true-peak. +(identified by TPK) and true-peak per frame (identified by FTPK). +This mode requires a build with libswresample. +

+
+ +
+
dualmono
+

Treat mono input files as "dual mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +

+
+
panlaw
+

Set a specific pan law to be used for the measurement of dual mono files. +This parameter is optional, and has a default value of -3.01dB. +

+
+
target
+

Set a specific target level (in LUFS) used as relative zero in the visualization. +This parameter is optional and has a default value of -23LUFS as specified +by EBU R128. However, material published online may prefer a level of -16LUFS +(e.g. for use with podcasts or video platforms). +

+
+
gauge
+

Set the value displayed by the gauge. Valid values are momentary and s +shortterm. By default the momentary value will be used, but in certain +scenarios it may be more useful to observe the short term value instead (e.g. +live mixing). +

+
+
scale
+

Sets the display scale for the loudness. Valid parameters are absolute +(in LUFS) or relative (LU) relative to the target. This only affects the +video output, not the summary or continuous log output. +

+
+
integrated
+

Read-only exported value for measured integrated loudness, in LUFS. +

+
+
range
+

Read-only exported value for measured loudness range, in LU. +

+
+
lra_low
+

Read-only exported value for measured LRA low, in LUFS. +

+
+
lra_high
+

Read-only exported value for measured LRA high, in LUFS. +

+
+
sample_peak
+

Read-only exported value for measured sample peak, in dBFS. +

+
+
true_peak
+

Read-only exported value for measured true peak, in dBFS. +

+
+ + +

39.10.1 Examples

+ +
    +
  • Real-time graph using ffplay, with a EBU scale meter +18: +
    +
    ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
    +
    + +
  • Run an analysis with ffmpeg: +
    +
    ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
    +
    +
+ + +

39.11 interleave, ainterleave

+ +

Temporally interleave frames from several inputs. +

+

interleave works with video inputs, ainterleave with audio. +

+

These filters read frames from several inputs and send the oldest +queued frame to the output. +

+

Input streams must have 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 select filter +which always drops input frames. The interleave filter will keep +reading from that input, but it will never be able to send new frames +to output until the input sends 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: +

+
+
nb_inputs, n
+

Set the number of different inputs, it is 2 by default. +

+
+
duration
+

How to determine the end-of-stream. +

+
+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+ +
+
+ + +

39.11.1 Examples

+ +
    +
  • Interleave frames belonging to different streams using ffmpeg: +
    +
    ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
    +
    + +
  • Add flickering blur effect: +
    +
    select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
    +
    +
+ + +

39.12 latency, alatency

+

Measure filtering latency. +

+

Report previous filter filtering latency, delay in number of audio samples for audio filters +or number of video frames for video filters. +

+

On end of input stream, filter will report min and max measured latency for previous running filter +in filtergraph. +

+ +

39.13 metadata, ametadata

+ +

Manipulate frame metadata. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

If both value and key is set, select frames +which have such metadata. If only key is set, select +every frame that has such key in metadata. +

+
+
‘add’
+

Add new metadata key and value. If key is already available +do nothing. +

+
+
‘modify’
+

Modify value of already present key. +

+
+
‘delete’
+

If value is set, delete only keys that have such value. +Otherwise, delete key. If key is not set, delete all metadata values in +the frame. +

+
+
‘print’
+

Print key and its value if metadata was found. If key is not set print all +metadata values available in frame. +

+
+ +
+
key
+

Set key used with all modes. Must be set for all modes except print and delete. +

+
+
value
+

Set metadata value which will be used. This option is mandatory for +modify and add mode. +

+
+
function
+

Which function to use when comparing metadata value and value. +

+

Can be one of following: +

+
+
‘same_str’
+

Values are interpreted as strings, returns true if metadata value is same as value. +

+
+
‘starts_with’
+

Values are interpreted as strings, returns true if metadata value starts with +the value option string. +

+
+
‘less’
+

Values are interpreted as floats, returns true if metadata value is less than value. +

+
+
‘equal’
+

Values are interpreted as floats, returns true if value is equal with metadata value. +

+
+
‘greater’
+

Values are interpreted as floats, returns true if metadata value is greater than value. +

+
+
‘expr’
+

Values are interpreted as floats, returns true if expression from option expr +evaluates to true. +

+
+
‘ends_with’
+

Values are interpreted as strings, returns true if metadata value ends with +the value option string. +

+
+ +
+
expr
+

Set expression which is used when function is set to expr. +The expression is evaluated through the eval API and can contain the following +constants: +

+
+
VALUE1, FRAMEVAL
+

Float representation of value from metadata key. +

+
+
VALUE2, USERVAL
+

Float representation of value as supplied by user in value option. +

+
+ +
+
file
+

If specified in print mode, output is written to the named file. Instead of +plain filename any writable url can be specified. Filename “-” is a shorthand +for standard output. If file option is not set, output is written to the log +with AV_LOG_INFO loglevel. +

+
+
direct
+

Reduces buffering in print mode when output is written to a URL set using file. +

+
+
+ + +

39.13.1 Examples

+ +
    +
  • Print all metadata values for frames with key lavfi.signalstats.YDIF with values +between 0 and 1. +
    +
    signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
    +
    +
  • Print silencedetect output to file metadata.txt. +
    +
    silencedetect,ametadata=mode=print:file=metadata.txt
    +
    +
  • Direct all metadata to a pipe with file descriptor 4. +
    +
    metadata=mode=print:file='pipe\:4'
    +
    +
+ + +

39.14 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 the following options: +

+
+
mode
+

Select the permissions mode. +

+

It accepts the following values: +

+
‘none’
+

Do nothing. This is the default. +

+
‘ro’
+

Set all the output frames read-only. +

+
‘rw’
+

Set all the output frames directly writable. +

+
‘toggle’
+

Make the frame read-only if writable, and writable if read-only. +

+
‘random’
+

Set each output frame read-only or writable randomly. +

+
+ +
+
seed
+

Set the seed for the random mode, 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. +

+
+ +

Note: in case of auto-inserted filter between the permission filter and the +following one, the permission might not be received as expected in that +following filter. Inserting a format or aformat filter before the +perms/aperms filter can avoid this problem. +

+ +

39.15 realtime, arealtime

+ +

Slow down filtering to match real time approximately. +

+

These filters will pause the filtering for a variable amount of time to +match the output rate with the input timestamps. +They are similar to the re option to ffmpeg. +

+

They accept the following options: +

+
+
limit
+

Time limit for the pauses. Any pause longer than that will be considered +a timestamp discontinuity and reset the timer. Default is 2 seconds. +

+
speed
+

Speed factor for processing. The value must be a float larger than zero. +Values larger than 1.0 will result in faster than realtime processing, +smaller will slow processing down. The limit is automatically adapted +accordingly. Default is 1.0. +

+

A processing speed faster than what is possible without these filters cannot +be achieved. +

+
+ + +

39.15.1 Commands

+ +

Both filters supports the all above options as commands. +

+ +

39.16 segment, asegment

+ +

Split single input stream into multiple streams. +

+

This filter does opposite of concat filters. +

+

segment works on video frames, asegment on audio samples. +

+

This filter accepts the following options: +

+
+
timestamps
+

Timestamps of output segments separated by ’|’. The first segment will run +from the beginning of the input stream. The last segment will run until +the end of the input stream +

+
+
frames, samples
+

Exact frame/sample count to split the segments. +

+
+ +

In all cases, prefixing an each segment with ’+’ will make it relative to the +previous segment. +

+ +

39.16.1 Examples

+ +
    +
  • Split input audio stream into three output audio streams, starting at start of input audio stream +and storing that in 1st output audio stream, then following at 60th second and storing than in 2nd +output audio stream, and last after 150th second of input audio stream store in 3rd output audio stream: +
    +
    asegment=timestamps="60|150"
    +
    + +
+ + +

39.17 select, aselect

+ +

Select frames to pass in output. +

+

This filter accepts the following options: +

+
+
expr, e
+

Set expression, which is evaluated for each input frame. +

+

If the expression is evaluated to zero, the frame 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 +ceil(val)-1, assuming that the input index starts from 0. +

+

For example a value of 1.2 corresponds to the output with index +ceil(1.2)-1 = 2-1 = 1, that is the second output. +

+
+
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. +

+
+ +

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the filtered frame, starting from 0. +

+
+
selected_n
+

The (sequential) number of the selected frame, starting from 0. +

+
+
prev_selected_n
+

The sequential number of the last selected frame. It’s NAN if undefined. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the filtered frame, +expressed in TB units. It’s NAN if undefined. +

+
+
t
+

The PTS of the filtered frame, +expressed in seconds. It’s NAN if undefined. +

+
+
prev_pts
+

The PTS of the previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_pts
+

The PTS of the last previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_t
+

The PTS of the last previously selected frame, expressed in seconds. It’s NAN if undefined. +

+
+
start_pts
+

The first PTS in the stream which is not NAN. It remains NAN if not found. +

+
+
start_t
+

The first PTS, in seconds, in the stream which is not NAN. It remains NAN if not found. +

+
+
pict_type (video only)
+

The type of the filtered frame. It can assume one of the following +values: +

+
I
+
P
+
B
+
S
+
SI
+
SP
+
BI
+
+ +
+
interlace_type (video only)
+

The frame interlace type. It can assume one of the following values: +

+
PROGRESSIVE
+

The frame is progressive (not interlaced). +

+
TOPFIRST
+

The frame is top-field-first. +

+
BOTTOMFIRST
+

The frame is bottom-field-first. +

+
+ +
+
consumed_sample_n (audio only)
+

the number of selected samples before the current frame +

+
+
samples_n (audio only)
+

the number of samples in the current frame +

+
+
sample_rate (audio only)
+

the input sample rate +

+
+
key
+

This is 1 if the filtered frame is a key-frame, 0 otherwise. +

+
+
pos
+

the position in the file of the filtered frame, -1 if the information +is not available (e.g. for synthetic video); deprecated, do not use +

+
+
scene (video only)
+

value between 0 and 1 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one (see the example below) +

+
+
concatdec_select
+

The concat demuxer can select only part of a concat input file by setting an +inpoint and an outpoint, but the output packets may not be entirely contained +in the selected interval. By using this variable, it is possible to skip frames +generated by the concat demuxer which are not exactly contained in the selected +interval. +

+

This works by comparing the frame pts against the lavf.concat.start_time +and the lavf.concat.duration packet metadata values which are also +present in the decoded frames. +

+

The concatdec_select variable is -1 if the frame pts is at least +start_time and either the duration metadata is missing or the frame pts is less +than start_time + duration, 0 otherwise, and NaN if the start_time metadata is +missing. +

+

That basically means that an input frame is selected if its pts is within the +interval set by the concat demuxer. +

+
+
iw (video only)
+

Represents the width of the input video frame. +

+
+
ih (video only)
+

Represents the height of the input video frame. +

+
+
view (video only)
+

View ID for multi-view video. +

+
+
+ +

The default value of the select expression is "1". +

+ +

39.17.1 Examples

+ +
    +
  • Select all frames in input: +
    +
    select
    +
    + +

    The example above is the same as: +

    +
    select=1
    +
    + +
  • Skip all frames: +
    +
    select=0
    +
    + +
  • Select only I-frames: +
    +
    select='eq(pict_type\,I)'
    +
    + +
  • Select one frame every 100: +
    +
    select='not(mod(n\,100))'
    +
    + +
  • Select only frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)
    +
    + +
  • Select only I-frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)*eq(pict_type\,I)
    +
    + +
  • Select frames with a minimum distance of 10 seconds: +
    +
    select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
    +
    + +
  • Use aselect to select only audio frames with samples number > 100: +
    +
    aselect='gt(samples_n\,100)'
    +
    + +
  • Create a mosaic of the first scenes: +
    +
    ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
    +
    + +

    Comparing scene against a value between 0.3 and 0.5 is generally a sane +choice. +

    +
  • Send even and odd frames to separate outputs, and compose them: +
    +
    select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
    +
    + +
  • Select useful frames from an ffconcat file which is using inpoints and +outpoints but where the source files are not intra frame only. +
    +
    ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
    +
    +
+ + +

39.18 sendcmd, asendcmd

+ +

Send commands to filters in the filtergraph. +

+

These filters read commands to be sent to other filters in the +filtergraph. +

+

sendcmd must be inserted between two video filters, +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 +with the commands option, or in a file specified by the +filename option. +

+

These filters accept the following options: +

+
commands, c
+

Set the commands to be read and sent to the other filters. +

+
filename, f
+

Set the filename of the commands to be read and sent to the other +filters. +

+
+ + +

39.18.1 Commands syntax

+ +

A commands description consists of a sequence of interval +specifications, comprising a list of commands to be executed when a +particular event related to that interval occurs. The occurring event +is typically the current frame time entering or leaving a given time +interval. +

+

An interval is specified by the following syntax: +

+
START[-END] COMMANDS;
+
+ +

The time interval is specified by the START and END times. +END is optional and defaults to the maximum time. +

+

The current frame time is considered within the specified interval if +it is included in the interval [START, END), that is when +the time is greater or equal to START and is lesser than +END. +

+

COMMANDS consists of a sequence of one or more command +specifications, separated by ",", relating to that interval. The +syntax of a command specification is given by: +

+
[FLAGS] TARGET COMMAND ARG
+
+ +

FLAGS is optional and specifies the type of events relating to +the time interval which enable sending the specified command, and must +be a non-null sequence of identifier flags separated by "+" or "|" and +enclosed between "[" and "]". +

+

The following flags are recognized: +

+
enter
+

The command is sent when the current frame timestamp enters the +specified interval. In other words, the command is sent when the +previous frame timestamp was not in the given interval, and the +current is. +

+
+
leave
+

The command is sent when the current frame timestamp leaves the +specified interval. In other words, the command is sent when the +previous frame timestamp was in the given interval, and the +current is not. +

+
+
expr
+

The command ARG is interpreted as expression and result of +expression is passed as ARG. +

+

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
POS
+

Original position in the file of the frame, or undefined if undefined +for the current frame. Deprecated, do not use. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
N
+

The count of the input frame for video or audio, starting from 0. +

+
+
T
+

The time in seconds of the current frame. +

+
+
TS
+

The start time in seconds of the current command interval. +

+
+
TE
+

The end time in seconds of the current command interval. +

+
+
TI
+

The interpolated time of the current command interval, TI = (T - TS) / (TE - TS). +

+
+
W
+

The video frame width. +

+
+
H
+

The video frame height. +

+
+ +
+
+ +

If FLAGS is not specified, a default value of [enter] is +assumed. +

+

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional list of argument for +the given COMMAND. +

+

Between one interval specification and another, whitespaces, or +sequences of characters starting with # until the end of line, +are ignored and can be used to annotate comments. +

+

A simplified BNF description of the commands specification syntax +follows: +

+
COMMAND_FLAG  ::= "enter" | "leave"
+COMMAND_FLAGS ::= COMMAND_FLAG [(+|"|")COMMAND_FLAG]
+COMMAND       ::= ["[" COMMAND_FLAGS "]"] TARGET COMMAND [ARG]
+COMMANDS      ::= COMMAND [,COMMANDS]
+INTERVAL      ::= START[-END] COMMANDS
+INTERVALS     ::= INTERVAL[;INTERVALS]
+
+ + +

39.18.2 Examples

+ +
    +
  • Specify audio tempo change at second 4: +
    +
    asendcmd=c='4.0 atempo tempo 1.5',atempo
    +
    + +
  • Target a specific filter instance: +
    +
    asendcmd=c='4.0 atempo@my tempo 1.5',atempo@my
    +
    + +
  • Specify a list of drawtext and hue commands in a file. +
    +
    # show text in the interval 5-10
    +5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
    +         [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
    +
    +# desaturate the image in the interval 15-20
    +15.0-20.0 [enter] hue s 0,
    +          [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
    +          [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(25-t)
    +
    + +

    A filtergraph allowing to read and process the above command list +stored in a file test.cmd, can be specified with: +

    +
    sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
    +
    +
+ + +

39.19 setpts, asetpts

+ +

Change the PTS (presentation timestamp) of the input frames. +

+

setpts works on video frames, asetpts on audio frames. +

+

This filter accepts the following options: +

+
+
expr
+

The expression which is evaluated for each frame to construct its timestamp. +

+
+
strip_fps (video only)
+

Boolean option which determines if the original framerate and frame duration +metadata is unset. If set to true, be advised that a sane frame rate should be +explicitly specified if output is sent to a constant frame rate muxer. +Default is false. +

+
+
+ +

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
FRAME_RATE, FR
+

frame rate, only defined for constant frame-rate video +

+
+
PTS
+

The presentation timestamp in input +

+
+
N
+

The count of the input frame for video or the number of consumed samples, +not including the current frame for audio, starting from 0. +

+
+
NB_CONSUMED_SAMPLES
+

The number of consumed samples, not including the current frame (only +audio) +

+
+
NB_SAMPLES, S
+

The number of samples in the current frame (only audio) +

+
+
SAMPLE_RATE, SR
+

The audio sample rate. +

+
+
STARTPTS
+

The PTS of the first frame. +

+
+
STARTT
+

the time in seconds of the first frame +

+
+
INTERLACED
+

State whether the current frame is interlaced. +

+
+
T
+

the time in seconds of the current frame +

+
+
POS
+

original position in the file of the frame, or undefined if undefined +for the current frame; deprecated, do not use +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INT
+

previous input time in seconds +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTT
+

previous output time in seconds +

+
+
RTCTIME
+

The wallclock (RTC) time in microseconds. This is deprecated, use time(0) +instead. +

+
+
RTCSTART
+

The wallclock (RTC) time at the start of the movie in microseconds. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
T_CHANGE
+

Time of the first frame after command was applied or time of the first frame if no commands. +

+
+
+ + +

39.19.1 Examples

+ +
    +
  • Start counting PTS from zero +
    +
    setpts=PTS-STARTPTS
    +
    + +
  • Apply fast motion effect: +
    +
    setpts=0.5*PTS
    +
    + +
  • Apply slow motion effect: +
    +
    setpts=2.0*PTS
    +
    + +
  • Set fixed rate of 25 frames per second: +
    +
    setpts=N/(25*TB)
    +
    + +
  • Apply a random jitter effect of +/-100 TB units: +
    +
    setpts=PTS+randomi(0, -100\,100)
    +
    + +
  • Set fixed rate 25 fps with some jitter: +
    +
    setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
    +
    + +
  • Apply an offset of 10 seconds to the input PTS: +
    +
    setpts=PTS+10/TB
    +
    + +
  • Generate timestamps from a "live source" and rebase onto the current timebase: +
    +
    setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
    +
    + +
  • Generate timestamps by counting samples: +
    +
    asetpts=N/SR/TB
    +
    + +
+ + +

39.19.2 Commands

+ +

Both filters support all above options as commands. +

+ +

39.20 setrange

+ +

Force color range for the output video frame. +

+

The setrange filter marks the color range property for the +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. +

+

The filter accepts the following options: +

+
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property. +

+
+
‘unspecified, unknown’
+

Set the color range as unspecified. +

+
+
‘limited, tv, mpeg’
+

Set the color range as limited. +

+
+
‘full, pc, jpeg’
+

Set the color range as full. +

+
+
+
+ + +

39.21 settb, asettb

+ +

Set the timebase to use for the output frames timestamps. +It is mainly useful for testing timebase configuration. +

+

It accepts the following parameters: +

+
+
expr, tb
+

The expression which is evaluated into the output timebase. +

+
+
+ +

The value for tb is an arithmetic expression representing a +rational. The expression can contain the constants "AVTB" (the default +timebase), "intb" (the input timebase) and "sr" (the sample rate, +audio only). Default value is "intb". +

+ +

39.21.1 Examples

+ +
    +
  • Set the timebase to 1/25: +
    +
    settb=expr=1/25
    +
    + +
  • Set the timebase to 1/10: +
    +
    settb=expr=0.1
    +
    + +
  • Set the timebase to 1001/1000: +
    +
    settb=1+0.001
    +
    + +
  • Set the timebase to 2*intb: +
    +
    settb=2*intb
    +
    + +
  • Set the default timebase value: +
    +
    settb=AVTB
    +
    +
+ + +

39.22 showcqt

+

Convert input audio to a video output representing frequency spectrum +logarithmically using Brown-Puckette constant Q transform algorithm with +direct frequency domain coefficient calculation (but the transform itself +is not really constant Q, instead the Q factor is actually variable/clamped), +with musical tone scale, from E0 to D#10. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify the video size for the output. It must be even. For the syntax of this option, +check the "Video size" section in the ffmpeg-utils manual. +Default value is 1920x1080. +

+
+
fps, rate, r
+

Set the output frame rate. Default value is 25. +

+
+
bar_h
+

Set the bargraph height. It must be even. Default value is -1 which +computes the bargraph height automatically. +

+
+
axis_h
+

Set the axis height. It must be even. Default value is -1 which computes +the axis height automatically. +

+
+
sono_h
+

Set the sonogram height. It must be even. Default value is -1 which +computes the sonogram height automatically. +

+
+
fullhd
+

Set the fullhd resolution. This option is deprecated, use size, s +instead. Default value is 1. +

+
+
sono_v, volume
+

Specify the sonogram volume expression. It can contain variables: +

+
bar_v
+

the bar_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is 16. +

+
+
bar_v, volume2
+

Specify the bargraph volume expression. It can contain variables: +

+
sono_v
+

the sono_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is sono_v. +

+
+
sono_g, gamma
+

Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, +higher gamma makes the spectrum having more range. Default value is 3. +Acceptable range is [1, 7]. +

+
+
bar_g, gamma2
+

Specify the bargraph gamma. Default value is 1. Acceptable range is +[1, 7]. +

+
+
bar_t
+

Specify the bargraph transparency level. Lower value makes the bargraph sharper. +Default value is 1. Acceptable range is [0, 1]. +

+
+
timeclamp, tc
+

Specify the transform timeclamp. At low frequency, there is trade-off between +accuracy in time domain and frequency domain. If timeclamp is lower, +event in time domain is represented more accurately (such as fast bass drum), +otherwise event in frequency domain is represented more accurately +(such as bass guitar). Acceptable range is [0.002, 1]. Default value is 0.17. +

+
+
attack
+

Set attack time in seconds. The default is 0 (disabled). Otherwise, it +limits future samples by applying asymmetric windowing in time domain, useful +when low latency is required. Accepted range is [0, 1]. +

+
+
basefreq
+

Specify the transform base frequency. Default value is 20.01523126408007475, +which is frequency 50 cents below E0. Acceptable range is [10, 100000]. +

+
+
endfreq
+

Specify the transform end frequency. Default value is 20495.59681441799654, +which is frequency 50 cents above D#10. Acceptable range is [10, 100000]. +

+
+
coeffclamp
+

This option is deprecated and ignored. +

+
+
tlength
+

Specify the transform length in time domain. Use this option to control accuracy +trade-off between time domain and frequency domain at every frequency sample. +It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option. +

+
+

Default value is 384*tc/(384+tc*f). +

+
+
count
+

Specify the transform count for every video frame. Default value is 6. +Acceptable range is [1, 30]. +

+
+
fcount
+

Specify the transform count for every single pixel. Default value is 0, +which makes it computed automatically. Acceptable range is [0, 10]. +

+
+
fontfile
+

Specify font file for use with freetype to draw the axis. If not specified, +use embedded font. Note that drawing with font file or embedded font is not +implemented with custom basefreq and endfreq, use axisfile +option instead. +

+
+
font
+

Specify fontconfig pattern. This has lower priority than fontfile. The +: in the pattern may be replaced by | to avoid unnecessary +escaping. +

+
+
fontcolor
+

Specify font color expression. This is arithmetic expression that should return +integer value 0xRRGGBB. It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
midi(f)
+

midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) +

+
r(x), g(x), b(x)
+

red, green, and blue value of intensity x. +

+
+

Default value is st(0, (midi(f)-59.5)/12); +st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); +r(1-ld(1)) + b(ld(1)). +

+
+
axisfile
+

Specify image file to draw the axis. This option override fontfile and +fontcolor option. +

+
+
axis, text
+

Enable/disable drawing text to the axis. If it is set to 0, drawing to +the axis is disabled, ignoring fontfile and axisfile option. +Default value is 1. +

+
+
csp
+

Set colorspace. The accepted values are: +

+
‘unspecified’
+

Unspecified (default) +

+
+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
cscheme
+

Set spectrogram color scheme. This is list of floating point values with format +left_r|left_g|left_b|right_r|right_g|right_b. +The default is 1|0.5|0|0|0.5|1. +

+
+
+ + +

39.22.1 Examples

+ +
    +
  • Playing audio while showing the spectrum: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with frame rate 30 fps: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
    +
    + +
  • Playing at 1280x720: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
    +
    + +
  • Disable sonogram display: +
    +
    sono_h=0
    +
    + +
  • A1 and its harmonics: A1, A2, (near)E3, A3: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with more accuracy in frequency domain: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
    +
    + +
  • Custom volume: +
    +
    bar_v=10:sono_v=bar_v*a_weighting(f)
    +
    + +
  • Custom gamma, now spectrum is linear to the amplitude. +
    +
    bar_g=2:sono_g=2
    +
    + +
  • Custom tlength equation: +
    +
    tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'
    +
    + +
  • Custom fontcolor and fontfile, C-note is colored green, others are colored blue: +
    +
    fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
    +
    + +
  • Custom font using fontconfig: +
    +
    font='Courier New,Monospace,mono|bold'
    +
    + +
  • Custom frequency range with custom axis using image file: +
    +
    axisfile=myaxis.png:basefreq=40:endfreq=10000
    +
    +
+ + +

39.23 showcwt

+ +

Convert input audio to video output representing frequency spectrum +using Continuous Wavelet Transform and Morlet wavelet. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
scale
+

Set the frequency scale used. Allowed values are: +

+
+
linear
+
log
+
bark
+
mel
+
erbs
+
sqrt
+
cbrt
+
qdrt
+
fm
+
+

Default value is linear. +

+
+
iscale
+

Set the intensity scale used. Allowed values are: +

+
+
linear
+
log
+
sqrt
+
cbrt
+
qdrt
+
+

Default value is log. +

+
+
min
+

Set the minimum frequency that will be used in output. +Default is 20 Hz. +

+
+
max
+

Set the maximum frequency that will be used in output. +Default is 20000 Hz. The real frequency upper limit +depends on input audio’s sample rate and such will be enforced +on this value when it is set to value greater than Nyquist frequency. +

+
+
imin
+

Set the minimum intensity that will be used in output. +

+
+
imax
+

Set the maximum intensity that will be used in output. +

+
+
logb
+

Set the logarithmic basis for brightness strength when +mapping calculated magnitude values to pixel values. +Allowed range is from 0 to 1. +Default value is 0.0001. +

+
+
deviation
+

Set the frequency deviation. +Lower values than 1 are more frequency oriented, +while higher values than 1 are more time oriented. +Allowed range is from 0 to 10. +Default value is 1. +

+
+
pps
+

Set the number of pixel output per each second in one row. +Allowed range is from 1 to 1024. +Default value is 64. +

+
+
mode
+

Set the output visual mode. Allowed values are: +

+
+
magnitude
+

Show magnitude. +

+
phase
+

Show only phase. +

+
magphase
+

Show combination of magnitude and phase. +Magnitude is mapped to brightness and phase to color. +

+
channel
+

Show unique color per channel magnitude. +

+
stereo
+

Show unique color per stereo difference. +

+
+ +

Default value is magnitude. +

+
+
slide
+

Set the output slide method. Allowed values are: +

+
+
replace
+
scroll
+
frame
+
+ +
+
direction
+

Set the direction method for output slide method. Allowed values are: +

+
+
lr
+

Direction from left to right. +

+
rl
+

Direction from right to left. +

+
ud
+

Direction from up to down. +

+
du
+

Direction from down to up. +

+
+ +
+
bar
+

Set the ratio of bargraph display to display size. Default is 0. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+ + +

39.24 showfreqs

+ +

Convert input audio to video output representing the audio power spectrum. +Audio amplitude is on Y-axis while frequency is on X-axis. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify size of video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +Default is 1024x512. +

+
+
rate, r
+

Set video rate. Default is 25. +

+
+
mode
+

Set display mode. +This set how each frequency bin will be represented. +

+

It accepts the following values: +

+
‘line’
+
‘bar’
+
‘dot’
+
+

Default is bar. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘sqrt’
+

Square root scale. +

+
+
‘cbrt’
+

Cubic root scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+

Default is log. +

+
+
fscale
+

Set frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+
‘rlog’
+

Reverse logarithmic scale. +

+
+

Default is lin. +

+
+
win_size
+

Set window size. Allowed range is from 16 to 65536. +

+

Default is 2048 +

+
+
win_func
+

Set windowing function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hanning. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
averaging
+

Set time averaging. Setting this to 0 will display current maximal peaks. +Default is 1, which means time averaging is disabled. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channel frequencies. Unrecognized or missing colors will be replaced +by white color. +

+
+
cmode
+

Set channel display mode. +

+

It accepts the following values: +

+
‘combined’
+
‘separate’
+
+

Default is combined. +

+
+
minamp
+

Set minimum amplitude used in log amplitude scaler. +

+
+
data
+

Set data display mode. +

+

It accepts the following values: +

+
‘magnitude’
+
‘phase’
+
‘delay’
+
+

Default is magnitude. +

+
+
channels
+

Set channels to use when processing audio. By default all are processed. +

+
+ + +

39.25 showspatial

+ +

Convert stereo input audio to a video output, representing the spatial relationship +between two channels. +

+

The filter accepts the following options: +

+
+
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 512x512. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
rate, r
+

Set output framerate. +

+
+ + +

39.26 showspectrum

+ +

Convert input audio to a video output, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
slide
+

Specify how the spectrum should slide along the window. +

+

It accepts the following values: +

+
‘replace’
+

the samples start again on the left when they reach the right +

+
‘scroll’
+

the samples scroll from right to left +

+
‘fullframe’
+

frames are only produced when the samples reach the right +

+
‘rscroll’
+

the samples scroll from left to right +

+
‘lreplace’
+

the samples start again on the right when they reach the left +

+
+ +

Default value is replace. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+ +

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+ +

Default value is ‘channel’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+ +

Default value is ‘sqrt’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
overlap
+

Set ratio of overlap window. Default value is 0. +When value is 1 overlap is set to recommended size for specific +window function currently used. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
data
+

Set which data to display. Can be magnitude, default or phase, +or unwrapped phase: uphase. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
fps
+

Set upper frame rate limit. Default is auto, unlimited. +

+
+
legend
+

Draw time and frequency axes and legends. Default is disabled. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ +

The usage is very similar to the showwaves filter; see the examples in that +section. +

+ +

39.26.1 Examples

+ +
    +
  • Large window with logarithmic color scaling: +
    +
    showspectrum=s=1280x480:scale=log
    +
    + +
  • Complete example for a colored and sliding spectrum per channel using ffplay: +
    +
    ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
    +             [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
    +
    +
+ + +

39.27 showspectrumpic

+ +

Convert input audio to a single video frame, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 4096x2048. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+

Default value is ‘intensity’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+

Default value is ‘log’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
legend
+

Draw time and frequency axes and legends. Default is enabled. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ + +

39.27.1 Examples

+ +
    +
  • Extract an audio spectrogram of a whole audio track +in a 1024x1024 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
    +
    +
+ + +

39.28 showvolume

+ +

Convert input audio volume to a video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set video rate. +

+
+
b
+

Set border width, allowed range is [0, 5]. Default is 1. +

+
+
w
+

Set channel width, allowed range is [80, 8192]. Default is 400. +

+
+
h
+

Set channel height, allowed range is [1, 900]. Default is 20. +

+
+
f
+

Set fade, allowed range is [0, 1]. Default is 0.95. +

+
+
c
+

Set volume color expression. +

+

The expression can use the following variables: +

+
+
VOLUME
+

Current max volume of channel in dB. +

+
+
PEAK
+

Current peak. +

+
+
CHANNEL
+

Current channel number, starting from 0. +

+
+ +
+
t
+

If set, displays channel names. Default is enabled. +

+
+
v
+

If set, displays volume values. Default is enabled. +

+
+
o
+

Set orientation, can be horizontal: h or vertical: v, +default is h. +

+
+
s
+

Set step size, allowed range is [0, 5]. Default is 0, which means +step is disabled. +

+
+
p
+

Set background opacity, allowed range is [0, 1]. Default is 0. +

+
+
m
+

Set metering mode, can be peak: p or rms: r, +default is p. +

+
+
ds
+

Set display scale, can be linear: lin or log: log, +default is lin. +

+
+
dm
+

In second. +If set to > 0., display a line for the max level +in the previous seconds. +default is disabled: 0. +

+
+
dmc
+

The color of the max line. Use when dm option is set to > 0. +default is: orange +

+
+ + +

39.29 showwaves

+ +

Convert input audio to a video output, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
mode
+

Set display mode. +

+

Available values are: +

+
‘point’
+

Draw a point for each sample. +

+
+
‘line’
+

Draw a vertical line for each sample. +

+
+
‘p2p’
+

Draw a point for each sample and a line between them. +

+
+
‘cline’
+

Draw a centered vertical line for each sample. +

+
+ +

Default value is point. +

+
+
n
+

Set the number of samples which are printed on the same column. A +larger value will decrease the frame rate. Must be a positive +integer. This option can be set only if the value for rate +is not explicitly specified. +

+
+
rate, r
+

Set the (approximate) output frame rate. This is done by setting the +option n. Default value is "25". +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. This is mostly useful to set for high n. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+ + +

39.29.1 Examples

+ +
    +
  • Output the input file audio and the corresponding video representation +at the same time: +
    +
    amovie=a.mp3,asplit[out0],showwaves[out1]
    +
    + +
  • Create a synthetic signal and show it with showwaves, forcing a +frame rate of 30 frames per second: +
    +
    aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
    +
    +
+ + +

39.30 showwavespic

+ +

Convert input audio to a single video frame, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+
filter
+

Set the filter mode. +

+

Available values are: +

+
‘average’
+

Use average samples values for each drawn sample. +

+
+
‘peak’
+

Use peak samples values for each drawn sample. +

+
+ +

Default value is average. +

+
+ + +

39.30.1 Examples

+ +
    +
  • Extract a channel split representation of the wave form of a whole audio track +in a 1024x800 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
    +
    +
+ + +

39.31 sidedata, asidedata

+ +

Delete frame side data, or select frames based on it. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

Select every frame with side data of type. +

+
+
‘delete’
+

Delete side data of type. If type is not set, delete all side +data in the frame. +

+
+
+ +
+
type
+

Set side data type used with all modes. Must be set for select mode. +

+

Possible values are: +

+
+
‘PANSCAN’
+
‘A53_CC’
+
‘STEREO3D’
+
‘MATRIXENCODING’
+
‘DOWNMIX_INFO’
+
‘REPLAYGAIN’
+
‘DISPLAYMATRIX’
+
‘AFD’
+
‘MOTION_VECTORS’
+
‘SKIP_SAMPLES’
+
‘AUDIO_SERVICE_TYPE’
+
‘MASTERING_DISPLAY_METADATA’
+
‘GOP_TIMECODE’
+
‘SPHERICAL’
+
‘CONTENT_LIGHT_LEVEL’
+
‘ICC_PROFILE’
+
‘S12M_TIMECODE’
+
‘DYNAMIC_HDR_PLUS’
+
‘REGIONS_OF_INTEREST’
+
‘VIDEO_ENC_PARAMS’
+
‘SEI_UNREGISTERED’
+
‘FILM_GRAIN_PARAMS’
+
‘DETECTION_BOUNDING_BOXES’
+
‘DETECTION_BBOXES’
+
‘DOVI_RPU_BUFFER’
+
‘DOVI_METADATA’
+
‘DYNAMIC_HDR_VIVID’
+
‘AMBIENT_VIEWING_ENVIRONMENT’
+
‘VIDEO_HINT’
+
+ +
+
+ + +

39.32 spectrumsynth

+ +

Synthesize audio from 2 input video spectrums, first input stream represents +magnitude across time and second represents phase across time. +The filter will transform from frequency domain as displayed in videos back +to time domain as presented in audio output. +

+

This filter is primarily created for reversing processed showspectrum +filter outputs, but can synthesize sound from other spectrograms too. +But in such case results are going to be poor if the phase data is not +available, because in such cases phase data need to be recreated, usually +it’s just recreated from random noise. +For best results use gray only output (channel color mode in +showspectrum filter) and log scale for magnitude video and +lin scale for phase video. To produce phase, for 2nd video, use +data option. Inputs videos should generally use fullframe +slide mode as that saves resources needed for decoding video. +

+

The filter accepts the following options: +

+
+
sample_rate
+

Specify sample rate of output audio, the sample rate of audio from which +spectrum was generated may differ. +

+
+
channels
+

Set number of channels represented in input video spectrums. +

+
+
scale
+

Set scale which was used when generating magnitude input spectrum. +Can be lin or log. Default is log. +

+
+
slide
+

Set slide which was used when generating inputs spectrums. +Can be replace, scroll, fullframe or rscroll. +Default is fullframe. +

+
+
win_func
+

Set window function used for resynthesis. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
orientation
+

Set orientation of input videos. Can be vertical or horizontal. +Default is vertical. +

+
+ + +

39.32.1 Examples

+ +
    +
  • First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, +then resynthesize videos back to audio with spectrumsynth: +
    +
    ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
    +ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
    +ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
    +
    +
+ + +

39.33 split, asplit

+ +

Split input into several identical outputs. +

+

asplit works with audio input, split with video. +

+

The filter accepts a single parameter which specifies the number of outputs. If +unspecified, it defaults to 2. +

+ +

39.33.1 Examples

+ +
    +
  • Create two separate outputs from the same input: +
    +
    [in] split [out0][out1]
    +
    + +
  • To create 3 or more outputs, you need to specify the number of +outputs, like in: +
    +
    [in] asplit=3 [out0][out1][out2]
    +
    + +
  • Create two separate outputs from the same input, one cropped and +one padded: +
    +
    [in] split [splitout1][splitout2];
    +[splitout1] crop=100:100:0:0    [cropout];
    +[splitout2] pad=200:200:100:100 [padout];
    +
    + +
  • Create 5 copies of the input audio with ffmpeg: +
    +
    ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
    +
    +
+ + +

39.34 zmq, azmq

+ +

Receive commands sent through a libzmq client, and forward them to +filters in the filtergraph. +

+

zmq and azmq work as a pass-through filters. zmq +must be inserted between two video filters, azmq between two +audio filters. Both are capable to send messages to any filter type. +

+

To enable these filters you need to install the libzmq library and +headers and configure FFmpeg with --enable-libzmq. +

+

For more information about libzmq see: +http://www.zeromq.org/ +

+

The zmq and azmq filters work as a libzmq server, which +receives messages sent through a network interface defined by the +bind_address (or the abbreviation "b") option. +Default value of this option is tcp://localhost:5555. You may +want to alter this value to your needs, but do not forget to escape any +’:’ signs (see filtergraph escaping). +

+

The received message must be in the form: +

+
TARGET COMMAND [ARG]
+
+ +

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. The default +filter instance name uses the pattern ‘Parsed_<filter_name>_<index>’, +but you can override this by using the ‘filter_name@id’ syntax +(see Filtergraph syntax). +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional argument list for the +given 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: +

+
ERROR_CODE ERROR_REASON
+MESSAGE
+
+ +

MESSAGE is optional. +

+ +

39.34.1 Examples

+ +

Look at 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 ffplay. +In this example the last overlay filter has an instance name. All other +filters will have default instance names. +

+
+
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@my=x=100 "
+
+ +

To change the color of the left side of the video, the following +command can be used: +

+
echo Parsed_color_0 c yellow | tools/zmqsend
+
+ +

To change the right side: +

+
echo Parsed_color_1 c pink | tools/zmqsend
+
+ +

To change the position of the right side: +

+
echo overlay@my x 150 | tools/zmqsend
+
+ + + + +

40 Multimedia Sources

+ +

Below is a description of the currently available multimedia sources. +

+ +

40.1 amovie

+ +

This is the same as movie source, except it selects an audio +stream by default. +

+ +

40.2 avsynctest

+

Generate an Audio/Video Sync Test. +

+

Generated stream periodically shows flash video frame and emits beep in audio. +Useful to inspect A/V sync issues. +

+

It accepts the following options: +

+
+
size, s
+

Set output video size. Default value is hd720. +

+
+
framerate, fr
+

Set output video frame rate. Default value is 30. +

+
+
samplerate, sr
+

Set output audio sample rate. Default value is 44100. +

+
+
amplitude, a
+

Set output audio beep amplitude. Default value is 0.7. +

+
+
period, p
+

Set output audio beep period in seconds. Default value is 3. +

+
+
delay, dl
+

Set output video flash delay in number of frames. Default value is 0. +

+
+
cycle, c
+

Enable cycling of video delays, by default is disabled. +

+
+
duration, d
+

Set stream output duration. By default duration is unlimited. +

+
+
fg, bg, ag
+

Set foreground/background/additional color. +

+
+ + +

40.2.1 Commands

+ +

This source supports the some above options as commands. +

+ +

40.3 movie

+ +

Read audio and/or video stream(s) from a movie container. +

+

It accepts the following parameters: +

+
+
filename
+

The name of the resource to read (not necessarily a file; it can also be a +device or a stream accessed through some protocol). +

+
+
format_name, f
+

Specifies the format assumed for the movie to read, and can be either +the name of a container or an input device. If not specified, the +format is guessed from movie_name or by probing. +

+
+
seek_point, sp
+

Specifies the seek point in seconds. The frames will be output +starting from this seek point. The parameter is evaluated with +av_strtod, so the numerical value may be suffixed by an IS +postfix. The default value is "0". +

+
+
streams, s
+

Specifies the streams to read. Several streams can be specified, +separated by "+". The source will then have as many outputs, in the +same order. The syntax is explained in the "Stream specifiers" +section in the ffmpeg manual. Two special names, "dv" and "da" specify +respectively the default (best suited) video and audio stream. Default +is "dv", or "da" if the filter is called as "amovie". +

+
+
stream_index, si
+

Specifies the index of the video stream to read. If the value is -1, +the most suitable video stream will be automatically selected. The default +value is "-1". Deprecated. If the filter is called "amovie", it will select +audio instead of video. +

+
+
loop
+

Specifies how many times to read the stream in sequence. +If the value is 0, the stream will be looped infinitely. +Default value is "1". +

+

Note that when the movie is looped the source timestamps are not +changed, so it will generate non monotonically increasing timestamps. +

+
+
discontinuity
+

Specifies the time difference between frames above which the point is +considered a timestamp discontinuity which is removed by adjusting the later +timestamps. +

+
+
dec_threads
+

Specifies the number of threads for decoding +

+
+
format_opts
+

Specify format options for the opened file. Format options can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to add protocol_whitelist and protocol_blacklist options: +

+
ffplay -f lavfi
+"movie=filename='1.sdp':format_opts='protocol_whitelist=file,rtp,udp\:protocol_blacklist=http'"
+
+
+
+ +

It allows overlaying a second video on top of the main input of +a filtergraph, as shown in this graph: +

+
input -----------> deltapts0 --> overlay --> output
+                                    ^
+                                    |
+movie --> scale--> deltapts1 -------+
+
+ +

40.3.1 Examples

+ +
    +
  • Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it +on top of the input labelled "in": +
    +
    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]
    +
    + +
  • Read from a video4linux2 device, and overlay it on top of the input +labelled "in": +
    +
    movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
    +[in] setpts=PTS-STARTPTS [main];
    +[main][over] overlay=16:16 [out]
    +
    + +
  • Read the first video stream and the audio stream with id 0x81 from +dvd.vob; the video is connected to the pad named "video" and the audio is +connected to the pad named "audio": +
    +
    movie=dvd.vob:s=v:0+#0x81 [video] [audio]
    +
    +
+ + +

40.3.2 Commands

+ +

Both movie and amovie support the following commands: +

+
seek
+

Perform seek using "av_seek_frame". +The syntax is: seek stream_index|timestamp|flags +

    +
  • stream_index: If stream_index is -1, a default +stream is selected, and timestamp is automatically converted +from AV_TIME_BASE units to the stream specific time_base. +
  • timestamp: Timestamp in AVStream.time_base units +or, if no stream is specified, in AV_TIME_BASE units. +
  • flags: Flags which select direction and seeking mode. +
+ +
+
get_duration
+

Get movie duration in AV_TIME_BASE units. +

+
+
+ + +

41 External libraries

+ +

FFmpeg can be hooked up with a number of external libraries to add support +for more formats. None of them are used by default, their use has to be +explicitly requested by passing the appropriate flags to +./configure. +

+ +

41.1 Alliance for Open Media (AOM)

+ +

FFmpeg can make use of the AOM library for AV1 decoding and encoding. +

+

Go to http://aomedia.org/ and follow the instructions for +installing the library. Then pass --enable-libaom to configure to +enable it. +

+ +

41.2 AMD AMF/VCE

+ +

FFmpeg can use the AMD Advanced Media Framework library +for accelerated H.264 and HEVC(only windows) encoding on hardware with Video Coding Engine (VCE). +

+

To enable support you must obtain the AMF framework header files(version 1.4.9+) from +https://github.com/GPUOpen-LibrariesAndSDKs/AMF.git. +

+

Create an AMF/ directory in the system include path. +Copy the contents of AMF/amf/public/include/ into that directory. +Then configure FFmpeg with --enable-amf. +

+

Initialization of amf encoder occurs in this order: +1) trying to initialize through dx11(only windows) +2) trying to initialize through dx9(only windows) +3) trying to initialize through vulkan +

+

To use h.264(AMD VCE) encoder on linux amdgru-pro version 19.20+ and amf-amdgpu-pro +package(amdgru-pro contains, but does not install automatically) are required. +

+

This driver can be installed using amdgpu-pro-install script in official amd driver archive. +

+ +

41.3 AviSynth

+ +

FFmpeg can read AviSynth scripts as input. To enable support, pass +--enable-avisynth to configure after installing the headers +provided by AviSynth+. +AviSynth+ can be configured to install only the headers by either +passing -DHEADERS_ONLY:bool=on to the normal CMake-based build +system, or by using the supplied GNUmakefile. +

+

For Windows, supported AviSynth variants are +AviSynth 2.6 RC1 or higher for 32-bit builds and +AviSynth+ r1718 or higher for 32-bit and 64-bit builds. +

+

For Linux, macOS, and BSD, the only supported AviSynth variant is +AviSynth+, starting with version 3.5. +

+
+

In 2016, AviSynth+ added support for building with GCC. However, due to +the eccentricities of Windows’ calling conventions, 32-bit GCC builds +of AviSynth+ are not compatible with typical 32-bit builds of FFmpeg. +

+

By default, FFmpeg assumes compatibility with 32-bit MSVC builds of +AviSynth+ since that is the most widely-used and entrenched build +configuration. Users can override this and enable support for 32-bit +GCC builds of AviSynth+ by passing -DAVSC_WIN32_GCC32 to +--extra-cflags when configuring FFmpeg. +

+

64-bit builds of FFmpeg are not affected, and can use either MSVC or +GCC builds of AviSynth+ without any special flags. +

+
+

AviSynth(+) is loaded dynamically. Distributors can build FFmpeg +with --enable-avisynth, and the binaries will work regardless +of the end user having AviSynth installed. If/when an end user +would like to use AviSynth scripts, then they can install AviSynth(+) +and FFmpeg will be able to find and use it to open scripts. +

+ +

41.4 Chromaprint

+ +

FFmpeg can make use of the Chromaprint library for generating audio fingerprints. +Pass --enable-chromaprint to configure to +enable it. See https://acoustid.org/chromaprint. +

+ +

41.5 codec2

+ +

FFmpeg can make use of the codec2 library for codec2 decoding and encoding. +There is currently no native decoder, so libcodec2 must be used for decoding. +

+

Go to http://freedv.org/, download "Codec 2 source archive". +Build and install using CMake. Debian users can install the libcodec2-dev package instead. +Once libcodec2 is installed you can pass --enable-libcodec2 to configure to enable it. +

+

The easiest way to use codec2 is with .c2 files, since they contain the mode information required for decoding. +To encode such a file, use a .c2 file extension and give the libcodec2 encoder the -mode option: +ffmpeg -i input.wav -mode 700C output.c2. +Playback is as simple as ffplay output.c2. +For a list of supported modes, run ffmpeg -h encoder=libcodec2. +Raw codec2 files are also supported. +To make sense of them the mode in use needs to be specified as a format option: +ffmpeg -f codec2raw -mode 1300 -i input.raw output.wav. +

+ +

41.6 dav1d

+ +

FFmpeg can make use of the dav1d library for AV1 video decoding. +

+

Go to https://code.videolan.org/videolan/dav1d and follow the instructions for +installing the library. Then pass --enable-libdav1d to configure to enable it. +

+ +

41.7 davs2

+ +

FFmpeg can make use of the davs2 library for AVS2-P2/IEEE1857.4 video decoding. +

+

Go to https://github.com/pkuvcl/davs2 and follow the instructions for +installing the library. Then pass --enable-libdavs2 to configure to +enable it. +

+
+

libdavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

41.8 uavs3d

+ +

FFmpeg can make use of the uavs3d library for AVS3-P2/IEEE1857.10 video decoding. +

+

Go to https://github.com/uavs3/uavs3d and follow the instructions for +installing the library. Then pass --enable-libuavs3d to configure to +enable it. +

+ +

41.9 Game Music Emu

+ +

FFmpeg can make use of the Game Music Emu library to read audio from supported video game +music file formats. Pass --enable-libgme to configure to +enable it. See https://bitbucket.org/mpyne/game-music-emu/overview. +

+ +

41.10 Intel QuickSync Video

+ +

FFmpeg can use Intel QuickSync Video (QSV) for accelerated decoding and encoding +of multiple codecs. To use QSV, FFmpeg must be linked against the libmfx +dispatcher, which loads the actual decoding libraries. +

+

The dispatcher is open source and can be downloaded from +https://github.com/lu-zero/mfx_dispatch.git. FFmpeg needs to be configured +with the --enable-libmfx option and pkg-config needs to be able to +locate the dispatcher’s .pc files. +

+ +

41.11 Kvazaar

+ +

FFmpeg can make use of the Kvazaar library for HEVC encoding. +

+

Go to https://github.com/ultravideo/kvazaar and follow the +instructions for installing the library. Then pass +--enable-libkvazaar to configure to enable it. +

+ +

41.12 LAME

+ +

FFmpeg can make use of the LAME library for MP3 encoding. +

+

Go to http://lame.sourceforge.net/ and follow the +instructions for installing the library. +Then pass --enable-libmp3lame to configure to enable it. +

+ +

41.13 LCEVCdec

+ +

FFmpeg can make use of the liblcevc_dec library for LCEVC enhancement layer +decoding on supported bitstreams. +

+

Go to https://github.com/v-novaltd/LCEVCdec and follow the instructions +for installing the library. Then pass --enable-liblcevc-dec to configure to +enable it. +

+
+

LCEVCdec is under the BSD-3-Clause-Clear License. +

+ +

41.14 libilbc

+ +

iLBC is a narrowband speech codec that has been made freely available +by Google as part of the WebRTC project. libilbc is a packaging friendly +copy of the iLBC codec. FFmpeg can make use of the libilbc library for +iLBC decoding and encoding. +

+

Go to https://github.com/TimothyGu/libilbc and follow the instructions for +installing the library. Then pass --enable-libilbc to configure to +enable it. +

+ +

41.15 libjxl

+ +

JPEG XL is an image format intended to fully replace legacy JPEG for an extended +period of life. See https://jpegxl.info/ for more information, and see +https://github.com/libjxl/libjxl for the library source. You can pass +--enable-libjxl to configure in order enable the libjxl wrapper. +

+ +

41.16 libvpx

+ +

FFmpeg can make use of the libvpx library for VP8/VP9 decoding and encoding. +

+

Go to http://www.webmproject.org/ and follow the instructions for +installing the library. Then pass --enable-libvpx to configure to +enable it. +

+ +

41.17 ModPlug

+ +

FFmpeg can make use of this library, originating in Modplug-XMMS, to read from MOD-like music files. +See https://github.com/Konstanty/libmodplug. Pass --enable-libmodplug to configure to +enable it. +

+ +

41.18 OpenCORE, VisualOn, and Fraunhofer libraries

+ +

Spun off Google Android sources, OpenCore, VisualOn and Fraunhofer +libraries provide encoders for a number of audio codecs. +

+
+

OpenCORE and VisualOn libraries are under the Apache License 2.0 +(see http://www.apache.org/licenses/LICENSE-2.0 for details), which is +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) by passing --enable-version3 to configure in +order to use it. +

+

The license of the Fraunhofer AAC library is incompatible with the GPL. +Therefore, for GPL builds, you have to pass --enable-nonfree to +configure in order to use it. To the best of our knowledge, it is +compatible with the LGPL. +

+ +

41.18.1 OpenCORE AMR

+ +

FFmpeg can make use of the OpenCORE libraries for AMR-NB +decoding/encoding and AMR-WB decoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the libraries. +Then pass --enable-libopencore-amrnb and/or +--enable-libopencore-amrwb to configure to enable them. +

+ +

41.18.2 VisualOn AMR-WB encoder library

+ +

FFmpeg can make use of the VisualOn AMR-WBenc library for AMR-WB encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libvo-amrwbenc to configure to enable it. +

+ +

41.18.3 Fraunhofer AAC library

+ +

FFmpeg can make use of the Fraunhofer AAC library for AAC decoding & encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libfdk-aac to configure to enable it. +

+ +

41.18.4 Fraunhofer MPEG-H 3D Audio decoder library

+ +

FFmpeg can make use of the Fraunhofer MPEG-H decoder library for MPEG-H 3DA decoding. +

+

Go to https://github.com/Fraunhofer-IIS/mpeghdec and follow the +instructions for installing the library. +Then pass --enable-libmpeghdec --enable-nonfree to configure to enable it. +

+ +

41.18.5 LC3 library

+ +

FFmpeg can make use of the Google LC3 library for LC3 decoding & encoding. +

+

Go to https://github.com/google/liblc3/ and follow the instructions for +installing the library. +Then pass --enable-liblc3 to configure to enable it. +

+ +

41.19 OpenH264

+ +

FFmpeg can make use of the OpenH264 library for H.264 decoding and encoding. +

+

Go to http://www.openh264.org/ and follow the instructions for +installing the library. Then pass --enable-libopenh264 to configure to +enable it. +

+

For decoding, this library is much more limited than the built-in decoder +in libavcodec; currently, this library lacks support for decoding B-frames +and some other main/high profile features. (It currently only supports +constrained baseline profile and CABAC.) Using it is mostly useful for +testing and for taking advantage of Cisco’s patent portfolio license +(http://www.openh264.org/BINARY_LICENSE.txt). +

+ +

41.20 OpenJPEG

+ +

FFmpeg can use the OpenJPEG libraries for decoding/encoding J2K videos. Go to +http://www.openjpeg.org/ to get the libraries and follow the installation +instructions. To enable using OpenJPEG in FFmpeg, pass --enable-libopenjpeg to +./configure. +

+ +

41.21 rav1e

+ +

FFmpeg can make use of rav1e (Rust AV1 Encoder) via its C bindings to encode videos. +Go to https://github.com/xiph/rav1e/ and follow the instructions to build +the C library. To enable using rav1e in FFmpeg, pass --enable-librav1e +to ./configure. +

+ +

41.22 SVT-AV1

+ +

FFmpeg can make use of the Scalable Video Technology for AV1 library for AV1 encoding. +

+

Go to https://gitlab.com/AOMediaCodec/SVT-AV1/ and follow the instructions +for installing the library. Then pass --enable-libsvtav1 to configure to +enable it. +

+ +

41.23 SVT-JPEG-XS

+ +

FFmpeg can make use of the Scalable Video Technology for JPEG-XS library for JPEG-XS +decoding and encoding. +

+

Go to https://github.com/OpenVisualCloud/SVT-JPEG-XS and follow the instructions +for installing the library. Then pass --enable-libsvtjpegxs to configure to +enable it. +

+ +

41.24 TwoLAME

+ +

FFmpeg can make use of the TwoLAME library for MP2 encoding. +

+

Go to http://www.twolame.org/ and follow the +instructions for installing the library. +Then pass --enable-libtwolame to configure to enable it. +

+ +

41.25 VapourSynth

+ +

FFmpeg can read VapourSynth scripts as input. To enable support, pass +--enable-vapoursynth to configure. Vapoursynth is detected via +pkg-config. Versions 42 or greater supported. +See http://www.vapoursynth.com/. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+ +

41.26 x264

+ +

FFmpeg can make use of the x264 library for H.264 encoding. +

+

Go to http://www.videolan.org/developers/x264.html and follow the +instructions for installing the library. Then pass --enable-libx264 to +configure to enable it. +

+
+

x264 is under the GNU Public License Version 2 or later +(see 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. +

+ +

41.27 x265

+ +

FFmpeg can make use of the x265 library for HEVC encoding. +

+

Go to http://x265.org/developers.html and follow the instructions +for installing the library. Then pass --enable-libx265 to configure +to enable it. +

+
+

x265 is under the GNU Public License Version 2 or later +(see 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. +

+ +

41.28 xavs

+ +

FFmpeg can make use of the xavs library for AVS encoding. +

+

Go to http://xavs.sf.net/ and follow the instructions for +installing the library. Then pass --enable-libxavs to configure to +enable it. +

+ +

41.29 xavs2

+ +

FFmpeg can make use of the xavs2 library for AVS2-P2/IEEE1857.4 video encoding. +

+

Go to https://github.com/pkuvcl/xavs2 and follow the instructions for +installing the library. Then pass --enable-libxavs2 to configure to +enable it. +

+
+

libxavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

41.30 eXtra-fast Essential Video Encoder (XEVE)

+ +

FFmpeg can make use of the XEVE library for EVC video encoding. +

+

Go to https://github.com/mpeg5/xeve and follow the instructions for +installing the XEVE library. Then pass --enable-libxeve to configure to +enable it. +

+ +

41.31 eXtra-fast Essential Video Decoder (XEVD)

+ +

FFmpeg can make use of the XEVD library for EVC video decoding. +

+

Go to https://github.com/mpeg5/xevd and follow the instructions for +installing the XEVD library. Then pass --enable-libxevd to configure to +enable it. +

+ +

41.32 ZVBI

+ +

ZVBI is a VBI decoding library which can be used by FFmpeg to decode DVB +teletext pages and DVB teletext subtitles. +

+

Go to http://sourceforge.net/projects/zapping/ and follow the instructions for +installing the library. Then pass --enable-libzvbi to configure to +enable it. +

+ +

42 Supported File Formats, Codecs or Features

+ +

You can use the -formats and -codecs options to have an exhaustive list. +

+ +

42.1 File Formats

+ +

FFmpeg supports the following file formats through the libavformat +library: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
3dostrX
4xmX4X Technologies format, used in some games.
8088flex TMVX
AAXXAudible Enhanced Audio format, used in audiobooks.
AAXAudible Format 2, 3, and 4, used in audiobooks.
ACT VoiceXcontains G.729 audio
Adobe FilmstripXX
Audio IFF (AIFF)XX
American Laser Games MMXMultimedia format used in games like Mad Dog McCree.
3GPP AMRXX
Amazing Studio Packed Animation FileXMultimedia format used in game Heart Of Darkness.
Apple HTTP Live StreamingX
Artworx Data FormatX
Interplay ACMXAudio only format used in some Interplay games.
ADPXAudio format used on the Nintendo Gamecube.
AFCXAudio format used on the Nintendo Gamecube.
ADS/SS2XAudio format used on the PS2.
APNGXX
ASFXXAdvanced / Active Streaming Format.
ASTXXAudio format used on the Nintendo Wii.
AVIXX
AviSynthX
AVRXAudio format used on Mac.
AVSXMultimedia format used by the Creature Shock game.
Beam Software SIFFXAudio and video format used in some games by Beam Software.
Bethesda Softworks VIDXUsed in some games from Bethesda Softworks.
Binary textX
BinkXMultimedia format used by many games.
Bink AudioXAudio only multimedia format used by some games.
Bitmap Brothers JVXUsed in Z and Z95 games.
BRPXArgonaut Games format.
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
BFSTMXAudio format used on the Nintendo WiiU (based on BRSTM).
BRSTMXAudio format used on the Nintendo Wii.
BW64XBroadcast Wave 64bit.
BWFXX
codec2 (raw)XXMust be given -mode format option to decode correctly.
codec2 (.c2 files)XXContains header with version and mode info, simplifying playback.
CRI ADXXXAudio-only format used in console video games.
CRI AIXX
CRI HCAXAudio-only format used in console video games.
Discworld II BMVX
Interplay C93XUsed in the game Cyberia from Interplay.
Delphine Software International CINXMultimedia format used by Delphine Software games.
Digital Speech Standard (DSS)X
CD+GXVideo format used by CD+G karaoke disks
Phantom CineX
Commodore CDXLXAmiga CD video format
Core Audio FormatXXApple Core Audio Format
CRC testing formatX
Creative VoiceXXCreated for the Sound Blaster Pro.
CRYO APCXAudio format used in some games by CRYO Interactive Entertainment.
D-Cinema audioXX
Deluxe Paint AnimationX
DCSTRX
DFAXThis format is used in Chronomaster game
DirectDraw SurfaceX
DSD Stream File (DSF)X
DV videoXX
DXAXThis format is used in the non-Windows version of the Feeble Files + game and different game cutscenes repacked for use with ScummVM.
Electronic Arts cdataX
Electronic Arts MultimediaXUsed in various EA games; files have extensions like WVE and UV2.
Ensoniq Paris Audio FileX
FFM (FFserver live feed)XX
Flash (SWF)XX
Flash 9 (AVM2)XXOnly embedded audio is decoded.
FLI/FLC/FLX animationX.fli/.flc files
Flash Video (FLV)XXMacromedia Flash video files
framecrc testing formatX
FunCom ISSXAudio format used in various games from FunCom like The Longest Journey.
G.723.1XX
G.726XBoth left- and right-justified.
G.729 BITXX
G.729 rawX
GENHXAudio format for various games.
GIF AnimationXX
GXFXXGeneral eXchange Format SMPTE 360M, used by Thomson Grass Valley + playout servers.
HNMXOnly version 4 supported, used in some games from Cryo Interactive
iCEDraw FileX
ICOXXMicrosoft Windows ICO
id Quake II CIN videoX
id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
IEC61937 encapsulationXX
IFFXInterchange File Format
IFVXA format used by some old CCTV DVRs.
iLBCXX
Interplay MVEXFormat used in various Interplay computer games.
Iterated Systems ClearVideoXI-frames only
IV8XA format generated by IndigoVision 8000 video server.
IVF (On2)XXA format used by libvpx
Internet Video RecordingX
IRCAMXX
LAFXLimitless Audio Format
LATMXX
LMLM4XUsed by Linux Media Labs MPEG-4 PCI boards
LOASXcontains LATM multiplexed AAC audio
LRCXX
LVFX
LXFXVR native stream format, used by Leitch/Harris’ video servers.
Magic Lantern Video (MLV)X
MatroskaXX
Matroska audioX
FFmpeg metadataXXMetadata in text format.
MAXIS XAXUsed in Sim City 3000; file extension .xa.
MCAXUsed in some games from Capcom; file extension .mca.
MD StudioX
Metal Gear Solid: The Twin SnakesX
Megalux FrameXUsed by Megalux Ultimate Paint
MobiClip MODSX
MobiClip MOFLEXX
Mobotix .mxgX
Monkey’s AudioX
Motion Pixels MVIX
MOV/QuickTime/MP4XX3GP, 3GP2, PSP, iPod variants supported
MP2XX
MP3XX
MPEG-1 SystemXXmuxed audio and video, VCD format supported
MPEG-PS (program stream)XXalso known as VOB file, SVCD and DVD format supported
MPEG-TS (transport stream)XXalso known as DVB Transport Stream
MPEG-4XXMPEG-4 is a variant of QuickTime.
MSFXAudio format used on the PS3.
Mirillis FIC videoXNo cursor rendering.
MIDI Sample Dump StandardX
MIME multipart JPEGX
MSN TCP webcamXUsed by MSN Messenger webcam streams.
MTVX
MusepackX
Musepack SV8X
Material eXchange Format (MXF)XXSMPTE 377M, used by D-Cinema, broadcast industry.
Material eXchange Format (MXF), D-10 MappingXXSMPTE 386M, D-10/IMX Mapping.
NC camera feedXNC (AVIP NC4600) camera streams
NIST SPeech HEader REsourcesX
Computerized Speech Lab NSPX
NTT TwinVQ (VQF)XNippon Telegraph and Telephone Corporation TwinVQ.
Nullsoft Streaming VideoX
NuppelVideoX
NUTXXNUT Open Container Format
OggXX
Playstation Portable PMPX
Portable Voice FormatX
RK Audio (RKA)X
TechnoTrend PVAXUsed by TechnoTrend DVB PCI boards.
QCPX
raw ADTS (AAC)XX
raw AC-3XX
raw AMR-NBX
raw AMR-WBX
raw APACX
raw APVXX
raw aptXXX
raw aptX HDXX
raw BonkX
raw Chinese AVS videoXX
raw DFPWMXX
raw DiracXX
raw DNxHDXX
raw DTSXX
raw DTS-HDX
raw E-AC-3XX
raw EVCXX
raw FLACXX
raw G.728X
raw GSMX
raw H.261XX
raw H.263XX
raw H.264XX
raw HEVCXX
raw Ingenient MJPEGX
raw MJPEGXX
raw MLPX
raw MPEGX
raw MPEG-1X
raw MPEG-2X
raw MPEG-4XX
raw NULLX
raw videoXX
raw id RoQX
raw OBUXX
raw OSQX
raw SBCXX
raw ShortenX
raw TAKX
raw TrueHDXX
raw VC-1XX
raw PCM A-lawXX
raw PCM mu-lawXX
raw PCM Archimedes VIDCXX
raw PCM signed 8 bitXX
raw PCM signed 16 bit big-endianXX
raw PCM signed 16 bit little-endianXX
raw PCM signed 24 bit big-endianXX
raw PCM signed 24 bit little-endianXX
raw PCM signed 32 bit big-endianXX
raw PCM signed 32 bit little-endianXX
raw PCM signed 64 bit big-endianXX
raw PCM signed 64 bit little-endianXX
raw PCM unsigned 8 bitXX
raw PCM unsigned 16 bit big-endianXX
raw PCM unsigned 16 bit little-endianXX
raw PCM unsigned 24 bit big-endianXX
raw PCM unsigned 24 bit little-endianXX
raw PCM unsigned 32 bit big-endianXX
raw PCM unsigned 32 bit little-endianXX
raw PCM 16.8 floating point little-endianX
raw PCM 24.0 floating point little-endianX
raw PCM floating-point 32 bit big-endianXX
raw PCM floating-point 32 bit little-endianXX
raw PCM floating-point 64 bit big-endianXX
raw PCM floating-point 64 bit little-endianXX
RDTX
REDCODE R3DXFile format used by RED Digital cameras, contains JPEG 2000 frames and PCM audio.
RealMediaXX
RedirectorX
RedSparkX
Renderware TeXture DictionaryX
Resolume DXVXXEncoding is only supported for the DXT1 (Normal Quality, No Alpha) texture format.
RF64X
RL2XAudio and video format used in some games by Entertainment Software Partners.
RPL/ARMovieX
Lego Mindstorms RSOXX
RSDX
RTMPXXOutput is performed by publishing stream to RTMP server
RTPXX
RTSPXX
Sample Dump eXchangeX
SAPXX
SBGX
SDNSX
SDPX
SERX
Digital Pictures SGAX
Sega FILM/CPKXXUsed in many Sega Saturn console games.
Silicon Graphics MovieX
Sierra SOLX.sol files used in Sierra Online games.
Sierra VMDXUsed in Sierra CD-ROM games.
SmackerXMultimedia format used by many games.
SMJPEGXXUsed in certain Loki game ports.
SMPTE 337M encapsulationX
SmushXMultimedia format used in some LucasArts games.
Sony OpenMG (OMA)XXAudio format used in Sony Sonic Stage and Sony Vegas.
Sony PlayStation STRX
Sony Wave64 (W64)XX
SoX native formatXX
SUN AU formatXX
SUP raw PGS subtitlesXX
SVAGXAudio format used in Konami PS2 games.
TDSCX
Text filesX
THPXUsed on the Nintendo GameCube.
Tiertex Limited SEQXTiertex .seq files used in the DOS CD-ROM version of the game Flashback.
True AudioXX
VAGXAudio format used in many Sony PS2 games.
VC-1 test bitstreamXX
Vidvox HapXX
VivoX
VPKXAudio format used in Sony PS games.
Marble WADYX
WAVXX
Waveform ArchiverX
WavPackXX
WebMXX
Windows Televison (WTV)XX
Wing Commander III movieXMultimedia format used in Origin’s Wing Commander III computer game.
Westwood Studios audioXXMultimedia format used in Westwood Studios games.
Westwood Studios VQAXMultimedia format used in Westwood Studios games.
Wideband Single-bit Data (WSD)X
WVEX
Konami XMDX
XMVXMicrosoft video container used in Xbox games.
XVAGXAudio format used on the PS3.
xWMAXMicrosoft audio container used by XAudio 2.
eXtended BINary text (XBIN)X
YUV4MPEG pipeXX
Psygnosis YOPX
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+ +

42.2 Image Formats

+ +

FFmpeg can read and write images for each frame of a video sequence. The +following image formats are supported: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
.Y.U.VXXone raw file per component
Alias PIXXXAlias/Wavefront PIX image format
animated GIFXX
APNGXXAnimated Portable Network Graphics
BMPXXMicrosoft BMP image
BRender PIXXArgonaut BRender 3D engine image format.
CRIXCintel RAW
DPXXXDigital Picture Exchange
EXRXOpenEXR
FITSXXFlexible Image Transport System
HDRXXRadiance HDR RGBE Image format
IMGXGEM Raster image
JPEGXXProgressive JPEG is not supported.
JPEG 2000XX
JPEG-LSXX
JPEG-XSEESupported through external library libsvtjpegxs
LJPEGXLossless JPEG
Media 100X
MSPXMicrosoft Paint image
PAMXXPAM is a PNM extension with alpha support.
PBMXXPortable BitMap image
PCDXPhotoCD
PCXXXPC Paintbrush
PFMXXPortable FloatMap image
PGMXXPortable GrayMap image
PGMYUVXXPGM with U and V components in YUV 4:2:0
PGXXPGX file decoder
PHMXXPortable HalfFloatMap image
PICXPictor/PC Paint
PNGXXPortable Network Graphics image
PPMXXPortable PixelMap image
PSDXPhotoshop
PTXXV.Flash PTX format
QOIXXQuite OK Image format
SGIXXSGI RGB image format
Sun RasterfileXXSun RAS image format
TIFFXXYUV, JPEG and some extension is not supported yet.
Truevision TargaXXTarga (.TGA) image format
VBNXXVizrt Binary Image format
WBMPXXWireless Application Protocol Bitmap image format
WebPEXWebP image format, encoding supported through external library libwebp
XBMXXX BitMap image format
XFaceXXX-Face image format
XPMXX PixMap image format
XWDXXX Window Dump image format
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

42.3 Video Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
4X MovieXUsed in certain computer games.
8088flex TMVX
A64 multicolorXCreates video suitable to be played on a commodore 64 (multicolor mode).
Amazing Studio PAF VideoX
American Laser Games MMXUsed in games like Mad Dog McCree.
Amuse Graphics MovieX
AMV VideoXXUsed in Chinese MP3 players.
ANSI/ASCII artX
Apple Intermediate CodecX
Apple MJPEG-BX
Apple PixletX
Apple ProResXXfourcc: apch,apcn,apcs,apco,ap4h,ap4x
Apple QuickDrawXfourcc: qdrw
APVX
Argonaut VideoXUsed in some Argonaut games.
Asus v1XXfourcc: ASV1
Asus v2XXfourcc: ASV2
ATI VCR1Xfourcc: VCR1
ATI VCR2Xfourcc: VCR2
Auravision AuraX
Auravision Aura 2X
Autodesk Animator Flic videoX
Autodesk RLEXfourcc: AASC
AV1EESupported through external libraries libaom, libdav1d, librav1e and libsvtav1
Avid 1:1 10-bit RGB PackerXXfourcc: AVrp
AVS (Audio Video Standard) videoXVideo encoding used by the Creature Shock game.
AVS2-P2/IEEE1857.4EESupported through external libraries libxavs2 and libdavs2
AVS3-P2/IEEE1857.10ESupported through external library libuavs3d
AYUVXXMicrosoft uncompressed packed 4:4:4:4
Beam Software VBX
Bethesda VID videoXUsed in some games from Bethesda Softworks.
Bink VideoX
BitJazz SheerVideoX
Bitmap Brothers JV videoX
y41p Brooktree uncompressed 4:1:1 12-bitXX
Brooktree ProSumer VideoXfourcc: BT20
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
C93 videoXCodec used in Cyberia game.
CamStudioXfourcc: CSCD
CD+GXVideo codec for CD+G karaoke disks
CDXLXAmiga CD video codec
Chinese AVS videoEXAVS1-P2, JiZhun profile, encoding through external library libxavs
Delphine Software International CIN videoXCodec used in Delphine Software International games.
Discworld II BMV VideoX
CineForm HDXX
Canopus HQX
Canopus HQAX
Canopus HQXX
Canopus Lossless CodecX
CDToonsXCodec used in various Broderbund games.
CinepakX
Cirrus Logic AccuPakXXfourcc: CLJR
CPiA Video FormatX
Creative YUV (CYUV)X
DFAXCodec used in Chronomaster game.
DiracEXsupported though the native vc2 (Dirac Pro) encoder
Deluxe Paint AnimationX
DNxHDXXaka SMPTE VC3
Duck TrueMotion 1.0Xfourcc: DUCK
Duck TrueMotion 2.0Xfourcc: TM20
Duck TrueMotion 2.0 RTXfourcc: TR20
DV (Digital Video)XX
Dxtory capture formatX
Feeble Files/ScummVM DXAXCodec originally used in Feeble Files game.
Electronic Arts CMV videoXUsed in NHL 95 game.
Electronic Arts Madcow videoX
Electronic Arts TGV videoX
Electronic Arts TGQ videoX
Electronic Arts TQI videoX
Escape 124X
Escape 130X
EVC / MPEG-5 Part 1EEencoding and decoding supported through external libraries libxeve and libxevd
FFmpeg video codec #1XXlossless codec (fourcc: FFV1)
Flash Screen Video v1XXfourcc: FSV1
Flash Screen Video v2XX
Flash Video (FLV)XXSorenson H.263 used in Flash
FM Screen Capture CodecX
Forward UncompressedX
FrapsX
Go2MeetingXfourcc: G2M2, G2M3
Go2WebinarXfourcc: G2M4
Gremlin Digital VideoX
H.261XX
H.263 / H.263-1996XX
H.263+ / H.263-1998 / H.263 version 2XX
H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10EXencoding supported through external library libx264 and OpenH264
HEVCXXencoding supported through external library libx265 and libkvazaar
HNM version 4X
HuffYUVXX
HuffYUV FFmpeg variantXX
IBM UltimotionXfourcc: ULTI
id Cinematic videoXUsed in Quake II.
id RoQ videoXXUsed in Quake III, Jedi Knight 2, other computer games.
IFF ILBMXIFF interleaved bitmap
IFF ByteRun1XIFF run length encoded bitmap
Infinity IMM4X
Intel H.263X
Intel Indeo 2X
Intel Indeo 3X
Intel Indeo 4X
Intel Indeo 5X
Interplay C93XUsed in the game Cyberia from Interplay.
Interplay MVE videoXUsed in Interplay .MVE files.
J2KXX
Karl Morton’s video codecXCodec used in Worms games.
Kega Game Video (KGV1)XKega emulator screen capture codec.
LagarithX
LCEVC / MPEG-5 LCEVC / MPEG-5 Part 2Edecoding supported through external library liblcevc-dec
LCL (LossLess Codec Library) MSZHX
LCL (LossLess Codec Library) ZLIBEE
LEAD MCMPX
LOCOX
LucasArts SANM/SmushXUsed in LucasArts games / SMUSH animations.
lossless MJPEGXX
MagicYUV VideoXX
Mandsoft Screen Capture CodecX
Microsoft ATC ScreenXAlso known as Microsoft Screen 3.
Microsoft Expression Encoder ScreenXAlso known as Microsoft Titanium Screen 2.
Microsoft RLEXX
Microsoft Screen 1XAlso known as Windows Media Video V7 Screen.
Microsoft Screen 2XAlso known as Windows Media Video V9 Screen.
Microsoft Video 1X
MimicXUsed in MSN Messenger Webcam streams.
Miro VideoXLXfourcc: VIXL
MJPEG (Motion JPEG)XX
Mobotix MxPEG videoX
Motion Pixels videoX
MPEG-1 videoXX
MPEG-2 videoXX
MPEG-4 part 2XXlibxvidcore can be used alternatively for encoding.
MPEG-4 part 2 Microsoft variant version 1X
MPEG-4 part 2 Microsoft variant version 2XX
MPEG-4 part 2 Microsoft variant version 3XX
Newtek SpeedHQXX
Nintendo Gamecube THP videoX
NotchLCX
NuppelVideo/RTjpegXVideo encoding used in NuppelVideo files.
On2 VP3Xstill experimental
On2 VP4Xfourcc: VP40
On2 VP5Xfourcc: VP50
On2 VP6Xfourcc: VP60,VP61,VP62
On2 VP7Xfourcc: VP70,VP71
VP8EXfourcc: VP80, encoding supported through external library libvpx
VP9EXencoding supported through external library libvpx
Pinnacle TARGA CineWave YUV16Xfourcc: Y216
Q-team QPEGXfourccs: QPEG, Q1.0, Q1.1
QuickTime 8BPS videoX
QuickTime Animation (RLE) videoXXfourcc: ’rle ’
QuickTime Graphics (SMC)XXfourcc: ’smc ’
QuickTime video (RPZA)XXfourcc: rpza
R10K AJA Kona 10-bit RGB CodecXX
R210 Quicktime Uncompressed RGB 10-bitXX
Raw VideoXX
RealVideo 1.0XX
RealVideo 2.0XX
RealVideo 3.0Xstill far from ideal
RealVideo 4.0X
RealVideo 6.0X
Renderware TXD (TeXture Dictionary)XTexture dictionaries used by the Renderware Engine.
RivaTuner VideoXfourcc: ’RTV1’
RL2 videoXused in some games by Entertainment Software Partners
ScreenPressorX
ScreenpressoX
Screen Recorder Gold CodecX
Sierra VMD videoXUsed in Sierra VMD files.
Silicon Graphics Motion Video Compressor 1 (MVC1)X
Silicon Graphics Motion Video Compressor 2 (MVC2)X
Silicon Graphics RLE 8-bit videoX
Smacker videoXVideo encoding used in Smacker.
SMPTE VC-1X
SnowXXexperimental wavelet codec (fourcc: SNOW)
Sony PlayStation MDEC (Motion DECoder)X
Sorenson Vector Quantizer 1XXfourcc: SVQ1
Sorenson Vector Quantizer 3Xfourcc: SVQ3
Sunplus JPEG (SP5X)Xfourcc: SP5X
TechSmith Screen Capture CodecXfourcc: TSCC
TechSmith Screen Capture Codec 2Xfourcc: TSC2
TheoraEXencoding supported through external library libtheora
Tiertex Limited SEQ videoXCodec used in DOS CD-ROM FlashBack game.
Ut VideoXX
v210 QuickTime uncompressed 4:2:2 10-bitXX
v308 QuickTime uncompressed 4:4:4XX
v408 QuickTime uncompressed 4:4:4:4XX
v410 QuickTime uncompressed 4:4:4 10-bitXX
VBLE Lossless CodecX
vMix VideoXfourcc: ’VMX1’
VMware Screen Codec / VMware VideoXCodec used in videos captured by VMware.
Westwood Studios VQA (Vector Quantized Animation) videoX
Windows Media ImageX
Windows Media Video 7XX
Windows Media Video 8XX
Windows Media Video 9Xnot completely working
Wing Commander III / XanXUsed in Wing Commander III .MVE files.
Wing Commander IV / XanXUsed in Wing Commander IV.
Winnov WNV1X
WMV7XX
YAMAHA SMAFXX
Psygnosis YOP VideoX
yuv4XXlibquicktime uncompressed packed 4:2:0
ZeroCodec Lossless VideoX
ZLIBXXpart of LCL, encoder experimental
Zip Motion Blocks VideoXXEncoder works only in PAL8.
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

42.4 Audio Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
8SVX exponentialX
8SVX fibonacciX
AACEXXencoding supported through internal encoder and external library libfdk-aac
AAC+EIXencoding supported through external library libfdk-aac
AC-3IXIX
ACELP.KELVINX
ADPCM 4X MovieX
ADPCM Yamaha AICAX
ADPCM AmuseGraphics MovieX
ADPCM Argonaut GamesXX
ADPCM CDROM XAX
ADPCM Creative TechnologyX16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
ADPCM Electronic ArtsXUsed in various EA titles.
ADPCM Electronic Arts Maxis CDROM XSXUsed in Sim City 3000.
ADPCM Electronic Arts R1X
ADPCM Electronic Arts R2X
ADPCM Electronic Arts R3X
ADPCM Electronic Arts XASX
ADPCM G.722XX
ADPCM G.726XX
ADPCM IMA Acorn ReplayX
ADPCM IMA AMVXXUsed in AMV files
ADPCM IMA Cunning DevelopmentsX
ADPCM IMA Electronic Arts EACSX
ADPCM IMA Electronic Arts SEADX
ADPCM IMA FuncomX
ADPCM IMA High Voltage Software ALPXX
ADPCM IMA Mobiclip MOFLEXX
ADPCM IMA QuickTimeXX
ADPCM IMA Simon & Schuster InteractiveXX
ADPCM IMA Ubisoft APMXX
ADPCM IMA Loki SDL MJPEGX
ADPCM IMA WAVXX
ADPCM IMA WestwoodX
ADPCM ISS IMAXUsed in FunCom games.
ADPCM IMA DialogicX
ADPCM IMA Duck DK3XUsed in some Sega Saturn console games.
ADPCM IMA Duck DK4XUsed in some Sega Saturn console games.
ADPCM IMA RadicalX
ADPCM IMA XboxX
ADPCM MicrosoftXX
ADPCM MS IMAXX
ADPCM Nintendo Gamecube AFCX
ADPCM Nintendo Gamecube DTKX
ADPCM Nintendo THPX
ADPCM PlaystationX
ADPCM QT IMAXX
ADPCM SanyoX
ADPCM SEGA CRI ADXXXUsed in Sega Dreamcast games.
ADPCM Shockwave FlashXX
ADPCM Sound Blaster Pro 2-bitX
ADPCM Sound Blaster Pro 2.6-bitX
ADPCM Sound Blaster Pro 4-bitX
ADPCM VIMAXUsed in LucasArts SMUSH animations.
ADPCM Konami XMDX
ADPCM Westwood Studios IMAXXUsed in Westwood Studios games like Command and Conquer.
ADPCM YamahaXX
ADPCM ZorkX
AMR-NBEXencoding supported through external library libopencore-amrnb
AMR-WBEXencoding supported through external library libvo-amrwbenc
Amazing Studio PAF AudioX
Apple lossless audioXXQuickTime fourcc ’alac’
aptXXXUsed in Bluetooth A2DP
aptX HDXXUsed in Bluetooth A2DP
ATRAC1X
ATRAC3X
ATRAC3+X
ATRAC9X
Bink AudioXUsed in Bink and Smacker files in many games.
Bonk audioX
CELTEdecoding supported through external library libcelt
codec2EEen/decoding supported through external library libcodec2
CRI HCAX
Delphine Software International CIN audioXCodec used in Delphine Software International games.
DFPWMXX
Digital Speech Standard - Standard Play mode (DSS SP)X
Discworld II BMV AudioX
COOKXAll versions except 5.1 are supported.
DCA (DTS Coherent Acoustics)XXsupported extensions: XCh, XXCH, X96, XBR, XLL, LBR (partially)
Dolby EX
DPCM Cuberoot-Delta-ExactXUsed in few games.
DPCM GremlinX
DPCM id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
DPCM Marble WADYX
DPCM InterplayXUsed in various Interplay computer games.
DPCM Squareroot-Delta-ExactXUsed in various games.
DPCM Sierra OnlineXUsed in Sierra Online game audio files.
DPCM SolX
DPCM XanXUsed in Origin’s Wing Commander IV AVI files.
DPCM Xilam DERFX
DSD (Direct Stream Digital), least significant bit firstX
DSD (Direct Stream Digital), most significant bit firstX
DSD (Direct Stream Digital), least significant bit first, planarX
DSD (Direct Stream Digital), most significant bit first, planarX
DSP Group TrueSpeechX
DST (Direct Stream Transfer)X
DV audioX
Enhanced AC-3XX
EVRC (Enhanced Variable Rate Codec)X
FLAC (Free Lossless Audio Codec)XIX
FTR VoiceX
G.723.1XX
G.728X
G.729X
GSMEXencoding supported through external library libgsm
GSM Microsoft variantEXencoding supported through external library libgsm
IAC (Indeo Audio Coder)X
iLBC (Internet Low Bitrate Codec)EEXencoding and decoding supported through external library libilbc
IMC (Intel Music Coder)X
Interplay ACMX
LC3EEsupported through external library liblc3
MACE (Macintosh Audio Compression/Expansion) 6:1X
Marian’s A-pac audioX
MI-SC4 (Micronas SC-4 Audio)X
MLP (Meridian Lossless Packing)XXUsed in DVD-Audio discs.
Monkey’s AudioX
MP1 (MPEG audio layer 1)IX
MP2 (MPEG audio layer 2)IXIXencoding supported also through external library TwoLAME
MP3 (MPEG audio layer 3)EIXencoding supported through external library LAME, ADU MP3 and MP3onMP4 also supported
MPEG-4 Audio Lossless Coding (ALS)X
MPEG-H 3D AudioEdecoding supported through external library libmpeghdec
MobiClip FastAudioX
Musepack SV7X
Musepack SV8X
Nellymoser AsaoXX
On2 AVC (Audio for Video Codec)X
OpusEXencoding supported through external library libopus
OSQ (Original Sound Quality)X
PCM A-lawXX
PCM mu-lawXX
PCM Archimedes VIDCXX
PCM signed 8-bit planarXX
PCM signed 16-bit big-endian planarXX
PCM signed 16-bit little-endian planarXX
PCM signed 24-bit little-endian planarXX
PCM signed 32-bit little-endian planarXX
PCM 32-bit floating point big-endianXX
PCM 32-bit floating point little-endianXX
PCM 64-bit floating point big-endianXX
PCM 64-bit floating point little-endianXX
PCM D-Cinema audio signed 24-bitXX
PCM signed 8-bitXX
PCM signed 16-bit big-endianXX
PCM signed 16-bit little-endianXX
PCM signed 24-bit big-endianXX
PCM signed 24-bit little-endianXX
PCM signed 32-bit big-endianXX
PCM signed 32-bit little-endianXX
PCM signed 16/20/24-bit big-endian in MPEG-TSX
PCM unsigned 8-bitXX
PCM unsigned 16-bit big-endianXX
PCM unsigned 16-bit little-endianXX
PCM unsigned 24-bit big-endianXX
PCM unsigned 24-bit little-endianXX
PCM unsigned 32-bit big-endianXX
PCM unsigned 32-bit little-endianXX
PCM SGAX
QCELP / PureVoiceX
QDesign Music Codec 1X
QDesign Music Codec 2XThere are still some distortions.
RealAudio 1.0 (14.4K)XXReal 14400 bit/s codec
RealAudio 2.0 (28.8K)XReal 28800 bit/s codec
RealAudio 3.0 (dnet)IXXReal low bitrate AC-3 codec
RealAudio LosslessX
RealAudio SIPR / ACELP.NETX
RK Audio (RKA)X
SBC (low-complexity subband codec)XXUsed in Bluetooth A2DP
ShortenX
Sierra VMD audioXUsed in Sierra VMD files.
Smacker audioX
SMPTE 302M AES3 audioXX
SonicXXexperimental codec
Sonic losslessXXexperimental codec
SpeexEEXsupported through external library libspeex
TAK (Tom’s lossless Audio Kompressor)X
True Audio (TTA)XX
TrueHDXXUsed in HD-DVD and Blu-Ray discs.
TwinVQ (VQF flavor)X
VIMAXUsed in LucasArts SMUSH animations.
ViewQuest VQCX
VorbisEXA native but very primitive encoder exists.
Voxware MetaSoundX
Waveform ArchiverX
WavPackXX
Westwood Audio (SND1)X
Windows Media Audio 1XX
Windows Media Audio 2XX
Windows Media Audio LosslessX
Windows Media Audio ProX
Windows Media Audio VoiceX
Xbox Media Audio 1X
Xbox Media Audio 2X
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+

I means that an integer-only version is available, too (ensures high +performance on systems without hardware floating point support). +

+ +

42.5 Subtitle Formats

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameMuxingDemuxingEncodingDecoding
3GPP Timed TextXX
AQTitleXX
DVBXXXX
DVB teletextXE
DVDXXXX
JACOsubXXX
MicroDVDXXX
MPL2XX
MPsub (MPlayer)XX
PGSX
PJS (Phoenix)XX
RealTextXX
SAMIXX
Spruce format (STL)XX
SSA/ASSXXXX
SubRip (SRT)XXXX
SubViewer v1XX
SubViewerXX
TED Talks captionsXX
TTMLXX
VobSub (IDX+SUB)XX
VPlayerXX
WebVTTXXXX
XSUBXX
+ +

X means that the feature is supported. +

+

E means that support is provided through an external library. +

+ +

42.6 Network Protocols

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSupport
AMQPE
fileX
FTPX
GopherX
GophersX
HLSX
HTTPX
HTTPSX
IcecastX
MMSHX
MMSTX
pipeX
Pro-MPEG FECX
RTMPX
RTMPEX
RTMPSX
RTMPTX
RTMPTEX
RTMPTSX
RTPX
SAMBAE
SCTPX
SFTPE
TCPX
TLSX
UDPX
ZMQE
+ +

X means that the protocol is supported. +

+

E means that support is provided through an external library. +

+ + +

42.7 Input/Output Devices

+ + + + + + + + + + + + + + + + + + + + + + +
NameInputOutput
ALSAXX
BKTRX
cacaX
DV1394X
Lavfi virtual deviceX
Linux framebufferXX
JACKX
LIBCDIOX
LIBDC1394X
OpenALX
OpenGLX
OSSXX
PulseAudioXX
SDLX
Video4Linux2XX
VfW captureX
X11 grabbingX
Win32 grabbingX
+ +

X means that input/output is supported. +

+ +

42.8 Timecode

+ + + + + + + + + + +
Codec/formatReadWrite
AVIXX
DVXX
GXFXX
MOVXX
MPEG1/2XX
MXFXX
+ + +

43 See Also

+ +

ffplay, +ffmpeg, ffprobe, +ffmpeg-utils, +ffmpeg-scaler, +ffmpeg-resampler, +ffmpeg-codecs, +ffmpeg-bitstream-filters, +ffmpeg-formats, +ffmpeg-devices, +ffmpeg-protocols, +ffmpeg-filters +

+ + +

44 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffplay.html b/ffmpeg-n8.1/doc/ffplay.html new file mode 100644 index 00000000..900f447a --- /dev/null +++ b/ffmpeg-n8.1/doc/ffplay.html @@ -0,0 +1,921 @@ + + + + + + + ffplay Documentation + + + + + + +
+

+ ffplay Documentation +

+ + + + + + + +

1 Synopsis

+ +

ffplay [options] [input_url] +

+ +

2 Description

+ +

FFplay is a very simple and portable media player using the FFmpeg +libraries and the SDL library. It is mostly used as a testbed for the +various FFmpeg APIs. +

+ +

3 Options

+ +

All the numerical options, if not specified otherwise, accept a string +representing a number as input, which may be followed by one of the SI +unit prefixes, for example: ’K’, ’M’, or ’G’. +

+

If ’i’ is appended to the SI unit prefix, the complete prefix will be +interpreted as a unit prefix for binary multiples, which are based on +powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit +prefix multiplies the value by 8. This allows using, for example: +’KB’, ’MiB’, ’G’ and ’B’ as number suffixes. +

+

Options which do not take arguments are boolean options, and set the +corresponding value to true. They can be set to false by prefixing +the option name with "no". For example using "-nofoo" +will set the boolean option with name "foo" to false. +

+

Options that take arguments support a special syntax where the argument given on +the command line is interpreted as a path to the file from which the actual +argument value is loaded. To use this feature, add a forward slash ’/’ +immediately before the option name (after the leading dash). E.g. +

+
ffmpeg -i INPUT -/filter:v filter.script OUTPUT
+
+

will load a filtergraph description from the file named filter.script. +

+ +

3.1 Stream specifiers

+

Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers +are used to precisely specify which stream(s) a given option belongs to. +

+

A stream specifier is a string generally appended to the option name and +separated from it by a colon. E.g. -codec:a:1 ac3 contains the +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, so that the option is applied to all +of them. E.g. the stream specifier in -b:a 128k matches all audio +streams. +

+

An empty stream specifier matches all streams. For example, -codec copy +or -codec: copy would copy all the streams without reencoding. +

+

Possible forms of stream specifiers are: +

+
stream_index
+

Matches the stream with this index. E.g. -threads:1 4 would set the +thread count for the second stream to 4. If stream_index is used as an +additional stream specifier (see below), then it selects stream number +stream_index from the matching streams. Stream numbering is based on the +order of the streams as detected by libavformat except when a stream group +specifier or program ID is also specified. In this case it is based on the +ordering of the streams in the group or program. +

+
stream_type[:additional_stream_specifier]
+

stream_type is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’ +for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video +streams, ’V’ only matches video streams which are not attached pictures, video +thumbnails or cover arts. If additional_stream_specifier is used, then +it matches streams which both have this type and match the +additional_stream_specifier. Otherwise, it matches all streams of the +specified type. +

+
g:group_specifier[:additional_stream_specifier]
+

Matches streams which are in the group with the specifier group_specifier. +if additional_stream_specifier is used, then it matches streams which both +are part of the group and match the additional_stream_specifier. +group_specifier may be one of the following: +

+
group_index
+

Match the stream with this group index. +

+
#group_id or i:group_id
+

Match the stream with this group id. +

+
+
+
p:program_id[:additional_stream_specifier]
+

Matches streams which are in the program with the id program_id. If +additional_stream_specifier is used, then it matches streams which both +are part of the program and match the additional_stream_specifier. +

+
+
#stream_id or i:stream_id
+

Match the stream by stream id (e.g. PID in MPEG-TS container). +

+
m:key[:value]
+

Matches streams with the metadata tag key having the specified value. If +value is not given, matches streams that contain the given tag with any +value. The colon character ’:’ in key or value needs to be +backslash-escaped. +

+
disp:dispositions[:additional_stream_specifier]
+

Matches streams with the given disposition(s). dispositions is a list of +one or more dispositions (as printed by the -dispositions option) +joined with ’+’. +

+
u
+

Matches streams with usable configuration, the codec must be defined and the +essential information such as video dimension or audio sample rate must be present. +

+

Note that in ffmpeg, matching by metadata will only work properly for +input files. +

+
+ + +

3.2 Generic options

+ +

These options are shared amongst the ff* tools. +

+
+
-L, -license
+

Show license. +

+
+
-h, -?, -help, --help [arg]
+

Show help. An optional parameter may be specified to print help about a specific +item. If no argument is specified, only basic (non advanced) tool +options are shown. +

+

Possible values of arg are: +

+
long
+

Print advanced tool options in addition to the basic tool options. +

+
+
full
+

Print complete list of options, including shared and private options +for encoders, decoders, demuxers, muxers, filters, etc. +

+
+
decoder=decoder_name
+

Print detailed information about the decoder named decoder_name. Use the +-decoders option to get a list of all decoders. +

+
+
encoder=encoder_name
+

Print detailed information about the encoder named encoder_name. Use the +-encoders option to get a list of all encoders. +

+
+
demuxer=demuxer_name
+

Print detailed information about the demuxer named demuxer_name. Use the +-formats option to get a list of all demuxers and muxers. +

+
+
muxer=muxer_name
+

Print detailed information about the muxer named muxer_name. Use the +-formats option to get a list of all muxers and demuxers. +

+
+
filter=filter_name
+

Print detailed information about the filter named filter_name. Use the +-filters option to get a list of all filters. +

+
+
bsf=bitstream_filter_name
+

Print detailed information about the bitstream filter named bitstream_filter_name. +Use the -bsfs option to get a list of all bitstream filters. +

+
+
protocol=protocol_name
+

Print detailed information about the protocol named protocol_name. +Use the -protocols option to get a list of all protocols. +

+
+ +
+
-version
+

Show version. +

+
+
-buildconf
+

Show the build configuration, one option per line. +

+
+
-formats
+

Show available formats (including devices). +

+
+
-demuxers
+

Show available demuxers. +

+
+
-muxers
+

Show available muxers. +

+
+
-devices
+

Show available devices. +

+
+
-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. +

+
+
-decoders
+

Show available decoders. +

+
+
-encoders
+

Show all available encoders. +

+
+
-bsfs
+

Show available bitstream filters. +

+
+
-protocols
+

Show available protocols. +

+
+
-filters
+

Show available libavfilter filters. +

+
+
-pix_fmts
+

Show available pixel formats. +

+
+
-sample_fmts
+

Show available sample formats. +

+
+
-layouts
+

Show channel names and standard channel layouts. +

+
+
-dispositions
+

Show stream dispositions. +

+
+
-colors
+

Show recognized color names. +

+
+
-sources device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sources of the input device. +Some devices may provide system-dependent source names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sources pulse,server=192.168.0.4
+
+ +
+
-sinks device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sinks of the output device. +Some devices may provide system-dependent sink names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sinks pulse,server=192.168.0.4
+
+ +
+
-loglevel [flags+]loglevel | -v [flags+]loglevel
+

Set logging level and flags used by the library. +

+

The optional flags prefix can consist of the following values: +

+
‘repeat’
+

Indicates that repeated log output should not be compressed to the first line +and the "Last message repeated n times" line will be omitted. +

+
‘level’
+

Indicates that log output should add a [level] prefix to each message +line. This can be used as an alternative to log coloring, e.g. when dumping the +log to file. +

+
‘time’
+

Indicates that log lines should be prefixed with time information. +

+
‘datetime’
+

Indicates that log lines should be prefixed with date and time information. +

+
+

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single +flag without affecting other flags or changing loglevel. When +setting both flags and loglevel, a ’+’ separator is expected +between the last flags value and before loglevel. +

+

loglevel is a string or a number containing one of the following values: +

+
‘quiet, -8’
+

Show nothing at all; be silent. +

+
‘panic, 0’
+

Only show fatal errors which could lead the process to crash, such as +an assertion failure. This is not currently used for anything. +

+
‘fatal, 8’
+

Only show fatal errors. These are errors after which the process absolutely +cannot continue. +

+
‘error, 16’
+

Show all errors, including ones which can be recovered from. +

+
‘warning, 24’
+

Show all warnings and errors. Any message related to possibly +incorrect or unexpected events will be shown. +

+
‘info, 32’
+

Show informative messages during processing. This is in addition to +warnings and errors. This is the default value. +

+
‘verbose, 40’
+

Same as info, except more verbose. +

+
‘debug, 48’
+

Show everything, including debugging information. +

+
‘trace, 56’
+
+ +

For example to enable repeated log output, add the level prefix, and set +loglevel to verbose: +

+
ffmpeg -loglevel repeat+level+verbose -i input output
+
+

Another example that enables repeated log output without affecting current +state of level prefix flag or loglevel: +

+
ffmpeg [...] -loglevel +repeat
+
+ +

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 +AV_LOG_FORCE_NOCOLOR, or can be forced setting +the environment variable AV_LOG_FORCE_COLOR. +

+
+
-report
+

Dump full command line and log output to a file named +program-YYYYMMDD-HHMMSS.log in the current +directory. +This file can be useful for bug reports. +It also implies -loglevel debug. +

+

Setting the environment variable FFREPORT to any value has the +same effect. If the value is a ’:’-separated key=value sequence, these +options will affect the report; option 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 options are recognized: +

+
file
+

set the file name to use for the report; %p is expanded to the name +of the program, %t is expanded to a timestamp, %% is expanded +to a plain % +

+
level
+

set the log verbosity level using a numerical value (see -loglevel). +

+
+ +

For example, to output a report to a file named ffreport.log +using a log level of 32 (alias for log level info): +

+
+
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+ +

Errors in parsing the environment variable are not fatal, and will not +appear in the report. +

+
+
-hide_banner
+

Suppress printing banner. +

+

All FFmpeg tools will normally show a copyright notice, build options +and library versions. This option can be used to suppress printing +this information. +

+
+
-cpuflags flags (global)
+

Allows setting and clearing cpu flags. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpuflags -sse+mmx ...
+ffmpeg -cpuflags mmx ...
+ffmpeg -cpuflags 0 ...
+
+

Possible flags for this option are: +

+
‘x86’
+
+
‘mmx’
+
‘mmxext’
+
‘sse’
+
‘sse2’
+
‘sse2slow’
+
‘sse3’
+
‘sse3slow’
+
‘ssse3’
+
‘atom’
+
‘sse4.1’
+
‘sse4.2’
+
‘avx’
+
‘avx2’
+
‘xop’
+
‘fma3’
+
‘fma4’
+
‘3dnow’
+
‘3dnowext’
+
‘bmi1’
+
‘bmi2’
+
‘cmov’
+
+
+
‘ARM’
+
+
‘armv5te’
+
‘armv6’
+
‘armv6t2’
+
‘vfp’
+
‘vfpv3’
+
‘neon’
+
‘setend’
+
+
+
‘AArch64’
+
+
‘armv8’
+
‘vfp’
+
‘neon’
+
+
+
‘PowerPC’
+
+
‘altivec’
+
+
+
‘Specific Processors’
+
+
‘pentium2’
+
‘pentium3’
+
‘pentium4’
+
‘k6’
+
‘k62’
+
‘athlon’
+
‘athlonxp’
+
‘k8’
+
+
+
+ +
+
-cpucount count (global)
+

Override detection of CPU count. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpucount 2
+
+ +
+
-max_alloc bytes
+

Set the maximum size limit for allocating a block on the heap by ffmpeg’s +family of malloc functions. Exercise extreme caution when using +this option. Don’t use if you do not understand the full consequence of doing so. +Default is INT_MAX. +

+
+ + +

3.3 AVOptions

+ +

These options are provided directly by the libavformat, libavdevice and +libavcodec libraries. To see the list of available AVOptions, use the +-help option. They are separated into two categories: +

+
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. +

+
private
+

These options are specific to the given container, device or codec. Private +options are listed under their corresponding containers/devices/codecs. +

+
+ +

For example to write an ID3v2.3 header instead of a default ID3v2.4 to +an MP3 file, use the id3v2_version private option of the MP3 +muxer: +

+
ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+ +

All codec AVOptions are per-stream, and thus a stream specifier +should be attached to them: +

+
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+ +

In the above example, a multichannel audio stream is mapped twice for output. +The first instance is encoded with codec ac3 and bitrate 640k. +The second instance is downmixed to 2 channels and encoded with codec aac. A bitrate of 128k is specified for it using +absolute index of the output stream. +

+

Note: the -nooption syntax cannot be used for boolean +AVOptions, use -option 0/-option 1. +

+

Note: the 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. +

+ +

3.4 Main options

+ +
+
-x width
+

Force displayed width. +

+
-y height
+

Force displayed height. +

+
-fs
+

Start in fullscreen mode. +

+
-an
+

Disable audio. +

+
-vn
+

Disable video. +

+
-sn
+

Disable subtitles. +

+
-ss pos
+

Seek to pos. Note that in most formats it is not possible to seek +exactly, so ffplay will seek to the nearest seek point to +pos. +

+

pos must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+
-t duration
+

Play duration seconds of audio/video. +

+

duration must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+
-bytes
+

Seek by bytes. +

+
-seek_interval
+

Set custom interval, in seconds, for seeking using left/right keys. Default is 10 seconds. +

+
-nodisp
+

Disable graphical display. +

+
-noborder
+

Borderless window. +

+
-alwaysontop
+

Window always on top. Available on: X11 with SDL >= 2.0.5, Windows SDL >= 2.0.6. +

+
-volume
+

Set the startup volume. 0 means silence, 100 means no volume reduction or +amplification. Negative values are treated as 0, values above 100 are treated +as 100. +

+
-f fmt
+

Force format. +

+
-window_title title
+

Set window title (default is the input filename). +

+
-left title
+

Set the x position for the left of the window (default is a centered window). +

+
-top title
+

Set the y position for the top of the window (default is a centered window). +

+
-loop number
+

Loops movie playback <number> times. 0 means forever. +

+
-showmode mode
+

Set the show mode to use. +Available values for mode are: +

+
‘0, video’
+

show video +

+
‘1, waves’
+

show audio waves +

+
‘2, rdft’
+

show audio frequency band using RDFT ((Inverse) Real Discrete Fourier Transform) +

+
+ +

Default value is "video", if video is not present or cannot be played +"rdft" is automatically selected. +

+

You can interactively cycle through the available show modes by +pressing the key w. +

+
+
-vf filtergraph
+

Create the filtergraph specified by filtergraph and use it to +filter the video stream. +

+

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 filtergraph, the input is associated to the label +in, and the output to the label out. See the +ffmpeg-filters manual for more information about the filtergraph +syntax. +

+

You can specify this parameter multiple times and cycle through the specified +filtergraphs along with the show modes by pressing the key w. +

+
+
-af filtergraph
+

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). +

+
+
-i input_url
+

Read input_url. +

+
+ + +

3.5 Advanced options

+
+
-stats
+

Print several playback statistics, in particular show the stream +duration, the codec parameters, the current position in the stream and +the audio/video synchronisation drift. It is shown by default, unless the +log level is lower than info. Its display can be forced by manually +specifying this option. To disable it, you need to specify -nostats. +

+
+
-fast
+

Non-spec-compliant optimizations. +

+
-genpts
+

Generate pts. +

+
-sync type
+

Set the master clock to audio (type=audio), video +(type=video) or external (type=ext). Default is audio. The +master clock is used to control audio-video synchronization. Most media +players use audio as master clock, but in some cases (streaming or high +quality broadcast) it is necessary to change that. This option is mainly +used for debugging purposes. +

+
-ast audio_stream_specifier
+

Select the desired audio stream using the given stream specifier. The stream +specifiers are described in the Stream specifiers chapter. If this option +is not specified, the "best" audio stream is selected in the program of the +already selected video stream. +

+
-vst video_stream_specifier
+

Select the desired video stream using the given stream specifier. The stream +specifiers are described in the Stream specifiers chapter. If this option +is not specified, the "best" video stream is selected. +

+
-sst subtitle_stream_specifier
+

Select the desired subtitle stream using the given stream specifier. The stream +specifiers are described in the Stream specifiers chapter. If this option +is not specified, the "best" subtitle stream is selected in the program of the +already selected video or audio stream. +

+
-autoexit
+

Exit when video is done playing. +

+
-exitonkeydown
+

Exit if any key is pressed. +

+
-exitonmousedown
+

Exit if any mouse button is pressed. +

+
+
-codec:media_specifier codec_name
+

Force a specific decoder implementation for the stream identified by +media_specifier, which can assume the values a (audio), +v (video), and s subtitle. +

+
+
-acodec codec_name
+

Force a specific audio decoder. +

+
+
-vcodec codec_name
+

Force a specific video decoder. +

+
+
-scodec codec_name
+

Force a specific subtitle decoder. +

+
+
-autorotate
+

Automatically rotate the video according to file metadata. Enabled by +default, use -noautorotate to disable it. +

+
+
-framedrop
+

Drop video frames if video is out of sync. Enabled by default if the master +clock is not set to video. Use this option to enable frame dropping for all +master clock sources, use -noframedrop to disable it. +

+
+
-infbuf
+

Do not limit the input buffer size, read as much data as possible from the +input as soon as possible. Enabled by default for realtime streams, where data +may be dropped if not read in time. Use this option to enable infinite buffers +for all inputs, use -noinfbuf to disable it. +

+
+
-filter_threads nb_threads
+

Defines how many threads are used to process a filter pipeline. Each pipeline +will produce a thread pool with this many threads available for parallel +processing. The default is 0 which means that the thread count will be +determined by the number of available CPUs. +

+
+
-enable_vulkan
+

Use vulkan renderer rather than SDL builtin renderer. Depends on libplacebo. +

+
+
-vulkan_params
+
+

Vulkan configuration using a list of key=value pairs separated by +":". +

+
+
-hwaccel
+

Use HW accelerated decoding. Enable this option will enable vulkan renderer +automatically. +

+
+
-video_bg pattern
+

Set the video background pattern used for transparent videos. For solid color +patterns you can use the color name or color code as specified in the +Color section in the ffmpeg-utils(1) manual. +You can also use the special tiles keyword for a checker board style +pattern. This is also the default. The none pattern does rendering +without alpha blending effectively ignoring alpha channel. +

+
+
+ + +

3.6 While playing

+ +
+
q, ESC
+

Quit. +

+
+
f
+

Toggle full screen. +

+
+
p, SPC
+

Pause. +

+
+
m
+

Toggle mute. +

+
+
9, 0
+
/, *
+

Decrease and increase volume respectively. +

+
+
a
+

Cycle audio channel in the current program. +

+
+
v
+

Cycle video channel. +

+
+
t
+

Cycle subtitle channel in the current program. +

+
+
c
+

Cycle program. +

+
+
w
+

Cycle video filters or show modes. +

+
+
s
+

Step to the next frame. +

+

Pause if the stream is not already paused, step to the next video +frame, and pause. +

+
+
left/right
+

Seek backward/forward by 10 seconds or a custom interval if -seek_interval is set. +

+
+
down/up
+

Seek backward/forward 1 minute. +

+
+
page down/page up
+

Seek to previous/next chapter or backward/forward 10 minutes if no chapters. +

+
+
right mouse click
+

Seek to percentage in file corresponding to fraction of width. +

+
+
left mouse double-click
+

Toggle full screen. +

+
+
+ + + + +

4 See Also

+ +

ffmpeg-all, +ffmpeg, ffprobe, +ffmpeg-utils, +ffmpeg-scaler, +ffmpeg-resampler, +ffmpeg-codecs, +ffmpeg-bitstream-filters, +ffmpeg-formats, +ffmpeg-devices, +ffmpeg-protocols, +ffmpeg-filters +

+ + +

5 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffprobe-all.html b/ffmpeg-n8.1/doc/ffprobe-all.html new file mode 100644 index 00000000..38655a01 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffprobe-all.html @@ -0,0 +1,55116 @@ + + + + + + + ffprobe Documentation + + + + + + +
+

+ ffprobe Documentation +

+ + + + +
+

Table of Contents

+ +
+ + +
+
+ + +

1 Synopsis

+ +

ffprobe [options] input_url +

+ +

2 Description

+ +

ffprobe gathers information from multimedia streams and prints it in +human- and machine-readable fashion. +

+

For example it can be used to check the format of the container used +by a multimedia stream and the format and type of each media stream +contained in it. +

+

If a url is specified in input, ffprobe will try to open and +probe the url content. If the url cannot be opened or recognized as +a multimedia file, a positive exit code is returned. +

+

If no output is specified as output with o ffprobe will write +to stdout. +

+

ffprobe may be employed both as a standalone application or in +combination with a textual filter, which may perform more +sophisticated processing, e.g. statistical processing or plotting. +

+

Options are used to list some of the formats supported by ffprobe or +for specifying which information to display, and for setting how +ffprobe will show it. +

+

ffprobe output is designed to be easily parsable by a textual filter, +and consists of one or more sections of a form defined by the selected +writer, which is specified by the output_format option. +

+

Sections may contain other nested sections, and are identified by a +name (which may be shared by other sections), and an unique +name. See the output of sections. +

+

Metadata tags stored in the container or in the streams are recognized +and printed in the corresponding "FORMAT", "STREAM", "STREAM_GROUP_STREAM" +or "PROGRAM_STREAM" section. +

+ + +

3 Options

+ +

All the numerical options, if not specified otherwise, accept a string +representing a number as input, which may be followed by one of the SI +unit prefixes, for example: ’K’, ’M’, or ’G’. +

+

If ’i’ is appended to the SI unit prefix, the complete prefix will be +interpreted as a unit prefix for binary multiples, which are based on +powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit +prefix multiplies the value by 8. This allows using, for example: +’KB’, ’MiB’, ’G’ and ’B’ as number suffixes. +

+

Options which do not take arguments are boolean options, and set the +corresponding value to true. They can be set to false by prefixing +the option name with "no". For example using "-nofoo" +will set the boolean option with name "foo" to false. +

+

Options that take arguments support a special syntax where the argument given on +the command line is interpreted as a path to the file from which the actual +argument value is loaded. To use this feature, add a forward slash ’/’ +immediately before the option name (after the leading dash). E.g. +

+
ffmpeg -i INPUT -/filter:v filter.script OUTPUT
+
+

will load a filtergraph description from the file named filter.script. +

+ +

3.1 Stream specifiers

+

Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers +are used to precisely specify which stream(s) a given option belongs to. +

+

A stream specifier is a string generally appended to the option name and +separated from it by a colon. E.g. -codec:a:1 ac3 contains the +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, so that the option is applied to all +of them. E.g. the stream specifier in -b:a 128k matches all audio +streams. +

+

An empty stream specifier matches all streams. For example, -codec copy +or -codec: copy would copy all the streams without reencoding. +

+

Possible forms of stream specifiers are: +

+
stream_index
+

Matches the stream with this index. E.g. -threads:1 4 would set the +thread count for the second stream to 4. If stream_index is used as an +additional stream specifier (see below), then it selects stream number +stream_index from the matching streams. Stream numbering is based on the +order of the streams as detected by libavformat except when a stream group +specifier or program ID is also specified. In this case it is based on the +ordering of the streams in the group or program. +

+
stream_type[:additional_stream_specifier]
+

stream_type is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’ +for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video +streams, ’V’ only matches video streams which are not attached pictures, video +thumbnails or cover arts. If additional_stream_specifier is used, then +it matches streams which both have this type and match the +additional_stream_specifier. Otherwise, it matches all streams of the +specified type. +

+
g:group_specifier[:additional_stream_specifier]
+

Matches streams which are in the group with the specifier group_specifier. +if additional_stream_specifier is used, then it matches streams which both +are part of the group and match the additional_stream_specifier. +group_specifier may be one of the following: +

+
group_index
+

Match the stream with this group index. +

+
#group_id or i:group_id
+

Match the stream with this group id. +

+
+
+
p:program_id[:additional_stream_specifier]
+

Matches streams which are in the program with the id program_id. If +additional_stream_specifier is used, then it matches streams which both +are part of the program and match the additional_stream_specifier. +

+
+
#stream_id or i:stream_id
+

Match the stream by stream id (e.g. PID in MPEG-TS container). +

+
m:key[:value]
+

Matches streams with the metadata tag key having the specified value. If +value is not given, matches streams that contain the given tag with any +value. The colon character ’:’ in key or value needs to be +backslash-escaped. +

+
disp:dispositions[:additional_stream_specifier]
+

Matches streams with the given disposition(s). dispositions is a list of +one or more dispositions (as printed by the -dispositions option) +joined with ’+’. +

+
u
+

Matches streams with usable configuration, the codec must be defined and the +essential information such as video dimension or audio sample rate must be present. +

+

Note that in ffmpeg, matching by metadata will only work properly for +input files. +

+
+ + +

3.2 Generic options

+ +

These options are shared amongst the ff* tools. +

+
+
-L, -license
+

Show license. +

+
+
-h, -?, -help, --help [arg]
+

Show help. An optional parameter may be specified to print help about a specific +item. If no argument is specified, only basic (non advanced) tool +options are shown. +

+

Possible values of arg are: +

+
long
+

Print advanced tool options in addition to the basic tool options. +

+
+
full
+

Print complete list of options, including shared and private options +for encoders, decoders, demuxers, muxers, filters, etc. +

+
+
decoder=decoder_name
+

Print detailed information about the decoder named decoder_name. Use the +-decoders option to get a list of all decoders. +

+
+
encoder=encoder_name
+

Print detailed information about the encoder named encoder_name. Use the +-encoders option to get a list of all encoders. +

+
+
demuxer=demuxer_name
+

Print detailed information about the demuxer named demuxer_name. Use the +-formats option to get a list of all demuxers and muxers. +

+
+
muxer=muxer_name
+

Print detailed information about the muxer named muxer_name. Use the +-formats option to get a list of all muxers and demuxers. +

+
+
filter=filter_name
+

Print detailed information about the filter named filter_name. Use the +-filters option to get a list of all filters. +

+
+
bsf=bitstream_filter_name
+

Print detailed information about the bitstream filter named bitstream_filter_name. +Use the -bsfs option to get a list of all bitstream filters. +

+
+
protocol=protocol_name
+

Print detailed information about the protocol named protocol_name. +Use the -protocols option to get a list of all protocols. +

+
+ +
+
-version
+

Show version. +

+
+
-buildconf
+

Show the build configuration, one option per line. +

+
+
-formats
+

Show available formats (including devices). +

+
+
-demuxers
+

Show available demuxers. +

+
+
-muxers
+

Show available muxers. +

+
+
-devices
+

Show available devices. +

+
+
-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. +

+
+
-decoders
+

Show available decoders. +

+
+
-encoders
+

Show all available encoders. +

+
+
-bsfs
+

Show available bitstream filters. +

+
+
-protocols
+

Show available protocols. +

+
+
-filters
+

Show available libavfilter filters. +

+
+
-pix_fmts
+

Show available pixel formats. +

+
+
-sample_fmts
+

Show available sample formats. +

+
+
-layouts
+

Show channel names and standard channel layouts. +

+
+
-dispositions
+

Show stream dispositions. +

+
+
-colors
+

Show recognized color names. +

+
+
-sources device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sources of the input device. +Some devices may provide system-dependent source names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sources pulse,server=192.168.0.4
+
+ +
+
-sinks device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sinks of the output device. +Some devices may provide system-dependent sink names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sinks pulse,server=192.168.0.4
+
+ +
+
-loglevel [flags+]loglevel | -v [flags+]loglevel
+

Set logging level and flags used by the library. +

+

The optional flags prefix can consist of the following values: +

+
‘repeat’
+

Indicates that repeated log output should not be compressed to the first line +and the "Last message repeated n times" line will be omitted. +

+
‘level’
+

Indicates that log output should add a [level] prefix to each message +line. This can be used as an alternative to log coloring, e.g. when dumping the +log to file. +

+
‘time’
+

Indicates that log lines should be prefixed with time information. +

+
‘datetime’
+

Indicates that log lines should be prefixed with date and time information. +

+
+

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single +flag without affecting other flags or changing loglevel. When +setting both flags and loglevel, a ’+’ separator is expected +between the last flags value and before loglevel. +

+

loglevel is a string or a number containing one of the following values: +

+
‘quiet, -8’
+

Show nothing at all; be silent. +

+
‘panic, 0’
+

Only show fatal errors which could lead the process to crash, such as +an assertion failure. This is not currently used for anything. +

+
‘fatal, 8’
+

Only show fatal errors. These are errors after which the process absolutely +cannot continue. +

+
‘error, 16’
+

Show all errors, including ones which can be recovered from. +

+
‘warning, 24’
+

Show all warnings and errors. Any message related to possibly +incorrect or unexpected events will be shown. +

+
‘info, 32’
+

Show informative messages during processing. This is in addition to +warnings and errors. This is the default value. +

+
‘verbose, 40’
+

Same as info, except more verbose. +

+
‘debug, 48’
+

Show everything, including debugging information. +

+
‘trace, 56’
+
+ +

For example to enable repeated log output, add the level prefix, and set +loglevel to verbose: +

+
ffmpeg -loglevel repeat+level+verbose -i input output
+
+

Another example that enables repeated log output without affecting current +state of level prefix flag or loglevel: +

+
ffmpeg [...] -loglevel +repeat
+
+ +

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 +AV_LOG_FORCE_NOCOLOR, or can be forced setting +the environment variable AV_LOG_FORCE_COLOR. +

+
+
-report
+

Dump full command line and log output to a file named +program-YYYYMMDD-HHMMSS.log in the current +directory. +This file can be useful for bug reports. +It also implies -loglevel debug. +

+

Setting the environment variable FFREPORT to any value has the +same effect. If the value is a ’:’-separated key=value sequence, these +options will affect the report; option 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 options are recognized: +

+
file
+

set the file name to use for the report; %p is expanded to the name +of the program, %t is expanded to a timestamp, %% is expanded +to a plain % +

+
level
+

set the log verbosity level using a numerical value (see -loglevel). +

+
+ +

For example, to output a report to a file named ffreport.log +using a log level of 32 (alias for log level info): +

+
+
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+ +

Errors in parsing the environment variable are not fatal, and will not +appear in the report. +

+
+
-hide_banner
+

Suppress printing banner. +

+

All FFmpeg tools will normally show a copyright notice, build options +and library versions. This option can be used to suppress printing +this information. +

+
+
-cpuflags flags (global)
+

Allows setting and clearing cpu flags. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpuflags -sse+mmx ...
+ffmpeg -cpuflags mmx ...
+ffmpeg -cpuflags 0 ...
+
+

Possible flags for this option are: +

+
‘x86’
+
+
‘mmx’
+
‘mmxext’
+
‘sse’
+
‘sse2’
+
‘sse2slow’
+
‘sse3’
+
‘sse3slow’
+
‘ssse3’
+
‘atom’
+
‘sse4.1’
+
‘sse4.2’
+
‘avx’
+
‘avx2’
+
‘xop’
+
‘fma3’
+
‘fma4’
+
‘3dnow’
+
‘3dnowext’
+
‘bmi1’
+
‘bmi2’
+
‘cmov’
+
+
+
‘ARM’
+
+
‘armv5te’
+
‘armv6’
+
‘armv6t2’
+
‘vfp’
+
‘vfpv3’
+
‘neon’
+
‘setend’
+
+
+
‘AArch64’
+
+
‘armv8’
+
‘vfp’
+
‘neon’
+
+
+
‘PowerPC’
+
+
‘altivec’
+
+
+
‘Specific Processors’
+
+
‘pentium2’
+
‘pentium3’
+
‘pentium4’
+
‘k6’
+
‘k62’
+
‘athlon’
+
‘athlonxp’
+
‘k8’
+
+
+
+ +
+
-cpucount count (global)
+

Override detection of CPU count. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpucount 2
+
+ +
+
-max_alloc bytes
+

Set the maximum size limit for allocating a block on the heap by ffmpeg’s +family of malloc functions. Exercise extreme caution when using +this option. Don’t use if you do not understand the full consequence of doing so. +Default is INT_MAX. +

+
+ + +

3.3 AVOptions

+ +

These options are provided directly by the libavformat, libavdevice and +libavcodec libraries. To see the list of available AVOptions, use the +-help option. They are separated into two categories: +

+
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. +

+
private
+

These options are specific to the given container, device or codec. Private +options are listed under their corresponding containers/devices/codecs. +

+
+ +

For example to write an ID3v2.3 header instead of a default ID3v2.4 to +an MP3 file, use the id3v2_version private option of the MP3 +muxer: +

+
ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+ +

All codec AVOptions are per-stream, and thus a stream specifier +should be attached to them: +

+
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+ +

In the above example, a multichannel audio stream is mapped twice for output. +The first instance is encoded with codec ac3 and bitrate 640k. +The second instance is downmixed to 2 channels and encoded with codec aac. A bitrate of 128k is specified for it using +absolute index of the output stream. +

+

Note: the -nooption syntax cannot be used for boolean +AVOptions, use -option 0/-option 1. +

+

Note: the 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. +

+ +

3.4 Main options

+ +
+
-f format
+

Force format to use. +

+
+
-unit
+

Show the unit of the displayed values. +

+
+
-prefix
+

Use SI prefixes for the displayed values. +Unless the "-byte_binary_prefix" option is used all the prefixes +are decimal. +

+
+
-byte_binary_prefix
+

Force the use of binary prefixes for byte values. +

+
+
-sexagesimal
+

Use sexagesimal format HH:MM:SS.MICROSECONDS for time values. +

+
+
-pretty
+

Prettify the format of the displayed values, it corresponds to the +options "-unit -prefix -byte_binary_prefix -sexagesimal". +

+
+
-output_format, -of, -print_format writer_name[=writer_options]
+

Set the output printing format. +

+

writer_name specifies the name of the writer, and +writer_options specifies the options to be passed to the writer. +

+

For example for printing the output in JSON format, specify: +

+
-output_format json
+
+ +

For more details on the available output printing formats, see the +Writers section below. +

+
+
-sections
+

Print sections structure and section information, and exit. The output +is not meant to be parsed by a machine. +

+
+
-select_streams stream_specifier
+

Select only the streams specified by stream_specifier. This +option affects only the options related to streams +(e.g. show_streams, show_packets, etc.). +

+

For example to show only audio streams, you can use the command: +

+
ffprobe -show_streams -select_streams a INPUT
+
+ +

To show only video packets belonging to the video stream with index 1: +

+
ffprobe -show_packets -select_streams v:1 INPUT
+
+ +
+
-show_data
+

Show payload data, as a hexadecimal and ASCII dump (other formats can be +selected using -data_dump_format). Coupled with +-show_packets, it will dump the packets’ data. Coupled with +-show_streams, it will dump the codec extradata. +

+

The dump is printed as the "data" field. It may contain newlines. +

+
+
-show_data_hash algorithm
+

Show a hash of payload data, for packets with -show_packets and for +codec extradata with -show_streams. +

+
+
-data_dump_format format
+

Select a format used for the data dumps enabled with the -show_data +option. The default is xxd which is a hexdump format compatible with the +well-known xxd program. base64 is also supported. +

+
+
-show_error
+

Show information about the error found when trying to probe the input. +

+

The error information is printed within a section with name "ERROR". +

+
+
-show_format
+

Show information about the container format of the input multimedia +stream. +

+

All the container format information is printed within a section with +name "FORMAT". +

+
+
-show_entries section_entries
+

Set list of entries to show. +

+

Entries are specified according to the following +syntax. section_entries contains a list of section entries +separated by :. Each section entry is composed by a section +name (or unique name), optionally followed by a list of entries local +to that section, separated by ,. +

+

If section name is specified but is followed by no =, all +entries are printed to output, together with all the contained +sections. Otherwise only the entries specified in the local section +entries list are printed. In particular, if = is specified but +the list of local entries is empty, then no entries will be shown for +that section. +

+

Note that the order of specification of the local section entries is +not honored in the output, and the usual display order will be +retained. +

+

The formal syntax is given by: +

+
LOCAL_SECTION_ENTRIES ::= SECTION_ENTRY_NAME[,LOCAL_SECTION_ENTRIES]
+SECTION_ENTRY         ::= SECTION_NAME[=[LOCAL_SECTION_ENTRIES]]
+SECTION_ENTRIES       ::= SECTION_ENTRY[:SECTION_ENTRIES]
+
+ +

For example, to show only the index and type of each stream, and the PTS +time, duration time, and stream index of the packets, you can specify +the argument: +

+
packet=pts_time,duration_time,stream_index : stream=index,codec_type
+
+ +

To show all the entries in the section "format", but only the codec +type in the section "stream", specify the argument: +

+
format : stream=codec_type
+
+ +

To show all the tags in the stream and format sections: +

+
stream_tags : format_tags
+
+ +

To show only the title tag (if available) in the stream +sections: +

+
stream_tags=title
+
+ +
+
-show_packets
+

Show information about each packet contained in the input multimedia +stream. +

+

The information for each single packet is printed within a dedicated +section with name "PACKET". +

+
+
-show_frames
+

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" or "SUBTITLE". +

+
+
-show_log loglevel
+

Show logging information from the decoder about each frame according to +the value set in loglevel, (see -loglevel). This option requires -show_frames. +

+

The information for each log message is printed within a dedicated +section with name "LOG". +

+
+
-show_streams
+

Show information about each media stream contained in the input +multimedia stream. +

+

Each media stream information is printed within a dedicated section +with name "STREAM". +

+
+
-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". +

+
+
-show_stream_groups
+

Show information about stream groups and their streams contained in the +input multimedia stream. +

+

Each media stream information is printed within a dedicated section +with name "STREAM_GROUP_STREAM". +

+
+
-show_chapters
+

Show information about chapters stored in the format. +

+

Each chapter is printed within a dedicated section with name "CHAPTER". +

+
+
-count_frames
+

Count the number of frames per stream and report it in the +corresponding stream section. +

+
+
-count_packets
+

Count the number of packets per stream and report it in the +corresponding stream section. +

+
+
-read_intervals read_intervals
+
+

Read only the specified intervals. read_intervals must be a +sequence of interval specifications separated by ",". +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 absolute 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: +

+
INTERVAL  ::= [START|+START_OFFSET][%[END|+END_OFFSET]]
+INTERVALS ::= INTERVAL[,INTERVALS]
+
+ +

A few examples follow. +

    +
  • Seek to time 10, read packets until 20 seconds after the found seek +point, then seek to position 01:30 (1 minute and thirty +seconds) and read packets until position 01:45. +
    +
    10%+20,01:30%01:45
    +
    + +
  • Read only 42 packets after seeking to position 01:23: +
    +
    01:23%+#42
    +
    + +
  • Read only the first 20 seconds from the start: +
    +
    %+20
    +
    + +
  • Read from the start until position 02:30: +
    +
    %02:30
    +
    +
+ +
+
-show_private_data, -private
+

Show private data, that is data depending on the format of the +particular shown element. +This option is enabled by default, but you may need to disable it +for specific uses, for example when creating XSD-compliant XML output. +

+
+
-show_program_version
+

Show information related to program version. +

+

Version information is printed within a section with name +"PROGRAM_VERSION". +

+
+
-show_library_versions
+

Show information related to library versions. +

+

Version information for each library is printed within a section with +name "LIBRARY_VERSION". +

+
+
-show_versions
+

Show information related to program and library versions. This is the +equivalent of setting both -show_program_version and +-show_library_versions options. +

+
+
-show_pixel_formats
+

Show information about all pixel formats supported by FFmpeg. +

+

Pixel format information for each format is printed within a section +with name "PIXEL_FORMAT". +

+
+
-show_optional_fields value
+

Some writers viz. JSON and XML, omit the printing of fields with invalid or non-applicable values, +while other writers always print them. This option enables one to control this behaviour. +Valid values are always/1, never/0 and auto/-1. +Default is auto. +

+
+
-analyze_frames
+

Analyze frames and/or their side data up to the provided read interval, +providing additional information that may be useful at a stream level. +Must be paired with the -show_streams option or it will have no effect. +

+

Currently, the additional fields provided by this option when enabled are the +closed_captions and film_grain fields. +

+

For example, to analyze the first 20 seconds and populate these fields: +

+
ffprobe -show_streams -analyze_frames -read_intervals "%+20" INPUT
+
+ +
+
-bitexact
+

Force bitexact output, useful to produce output which is not dependent +on the specific build. +

+
+
-i input_url
+

Read input_url. +

+
+
-o output_url
+

Write output to output_url. If not specified, the output is sent +to stdout. +

+
+
-c:media_specifier codec_name
+
-codec:media_specifier codec_name
+

Force a specific decoder implementation for the stream identified by +media_specifier, which can assume the values a (audio), +v (video), s (subtitle), and d (data). +

+
+
+ + +

4 Writers

+ +

A writer defines the output format adopted by ffprobe, and will be +used for printing all the parts of the output. +

+

A writer may accept one or more arguments, which specify the options +to adopt. The options are specified as a list of key=value +pairs, separated by ":". +

+

All writers support the following options: +

+
+
string_validation, sv
+

Set string validation mode. +

+

The following values are accepted. +

+
‘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. +

+
+
‘ignore’
+

Any validation error will be ignored. This will result in possibly +broken output, especially with the json or xml writer. +

+
+
‘replace’
+

The writer will substitute invalid UTF-8 sequences or code points with +the string specified with the string_validation_replacement. +

+
+ +

Default value is ‘replace’. +

+
+
string_validation_replacement, svr
+

Set replacement string to use in case string_validation is +set to ‘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. +

+
+ +

A description of the currently available writers follows. +

+ +

4.1 default

+

Default format. +

+

Print each section in the form: +

+
[SECTION]
+key1=val1
+...
+keyN=valN
+[/SECTION]
+
+ +

Metadata tags are printed as a line in the corresponding FORMAT, STREAM, +STREAM_GROUP_STREAM or PROGRAM_STREAM section, and are prefixed by the +string "TAG:". +

+

A description of the accepted options follows. +

+
+
nokey, nk
+

If set to 1 specify not to print the key of each field. Default value +is 0. +

+
+
noprint_wrappers, nw
+

If set to 1 specify not to print the section header and footer. +Default value is 0. +

+
+ + +

4.2 compact, csv

+

Compact and CSV format. +

+

The csv writer is equivalent to compact, but supports +different defaults. +

+

Each section is printed on a single line. +If no option is specified, the output has the form: +

+
section|key1=val1| ... |keyN=valN
+
+ +

Metadata tags are printed in the corresponding "format" or "stream" +section. A metadata tag key, if printed, is prefixed by the string +"tag:". +

+

The description of the accepted options follows. +

+
+
item_sep, s
+

Specify the character to use for separating fields in the output line. +It must be a single printable character, it is "|" by default ("," for +the csv writer). +

+
+
nokey, nk
+

If set to 1 specify not to print the key of each field. Its default +value is 0 (1 for the csv writer). +

+
+
escape, e
+

Set the escape mode to use, default to "c" ("csv" for the csv +writer). +

+

It can assume one of the following values: +

+
c
+

Perform C-like escaping. Strings containing a newline (‘\n’), carriage +return (‘\r’), a tab (‘\t’), a form feed (‘\f’), the escaping +character (‘\’) or the item separator character SEP are escaped +using C-like fashioned escaping, so that a newline is converted to the +sequence ‘\n’, a carriage return to ‘\r’, ‘\’ to ‘\\’ and +the separator SEP is converted to ‘\SEP’. +

+
+
csv
+

Perform CSV-like escaping, as described in RFC4180. Strings +containing a newline (‘\n’), a carriage return (‘\r’), a double quote +(‘"’), or SEP are enclosed in double-quotes. +

+
+
none
+

Perform no escaping. +

+
+ +
+
print_section, p
+

Print the section name at the beginning of each line if the value is +1, disable it with value set to 0. Default value is +1. +

+
+
+ + +

4.3 flat

+

Flat format. +

+

A free-form output where each line contains an explicit key=value, such as +"streams.stream.3.tags.foo=bar". The output is shell escaped, so it can be +directly embedded in sh scripts as long as the separator character is an +alphanumeric character or an underscore (see sep_char option). +

+

The description of the accepted options follows. +

+
+
sep_char, s
+

Separator character used to separate the chapter, the section name, IDs and +potential tags in the printed field key. +

+

Default value is ‘.’. +

+
+
hierarchical, h
+

Specify if the section name specification should be hierarchical. If +set to 1, and if there is more than one section in the current +chapter, the section name will be prefixed by the name of the +chapter. A value of 0 will disable this behavior. +

+

Default value is 1. +

+
+ + +

4.4 ini

+

INI format output. +

+

Print output in an INI based format. +

+

The following conventions are adopted: +

+
    +
  • all key and values are UTF-8 +
  • ‘.’ is the subgroup separator +
  • newline, ‘\t’, ‘\f’, ‘\b’ and the following characters are +escaped +
  • ‘\’ is the escape character +
  • ‘#’ is the comment indicator +
  • ‘=’ is the key/value separator +
  • ‘:’ is not used but usually parsed as key/value separator +
+ +

This writer accepts options as a list of key=value pairs, +separated by ‘:’. +

+

The description of the accepted options follows. +

+
+
hierarchical, h
+

Specify if the section name specification should be hierarchical. If +set to 1, and if there is more than one section in the current +chapter, the section name will be prefixed by the name of the +chapter. A value of 0 will disable this behavior. +

+

Default value is 1. +

+
+ + +

4.5 json

+

JSON based format. +

+

Each section is printed using JSON notation. +

+

The description of the accepted options follows. +

+
+
compact, c
+

If set to 1 enable compact output, that is each section will be +printed on a single line. Default value is 0. +

+
+ +

For more information about JSON, see http://www.json.org/. +

+ +

4.6 xml

+

XML based format. +

+

The XML output is described in the XML schema description file +ffprobe.xsd installed in the FFmpeg datadir. +

+

An updated version of the schema can be retrieved at the url +http://www.ffmpeg.org/schema/ffprobe.xsd, which redirects to the +latest schema committed into the FFmpeg development source code tree. +

+

Note that the output issued will be compliant to the +ffprobe.xsd schema only when no special global output options +(unit, prefix, byte_binary_prefix, +sexagesimal etc.) are specified. +

+

The description of the accepted options follows. +

+
+
fully_qualified, q
+

If set to 1 specify if the output should be fully qualified. Default +value is 0. +This is required for generating an XML file which can be validated +through an XSD file. +

+
+
xsd_strict, x
+

If set to 1 perform more checks for ensuring that the output is XSD +compliant. Default value is 0. +This option automatically sets fully_qualified to 1. +

+
+ +

For more information about the XML format, see +https://www.w3.org/XML/. +

+ +

5 Timecode

+ +

ffprobe supports Timecode extraction: +

+
    +
  • MPEG1/2 timecode is extracted from the GOP, and is available in the video +stream details (-show_streams, see timecode). + +
  • MOV timecode is extracted from tmcd track, so is available in the tmcd +stream metadata (-show_streams, see TAG:timecode). + +
  • DV, GXF and AVI timecodes are available in format metadata +(-show_format, see TAG:timecode). + +
+ + +

6 Syntax

+ +

This section documents the syntax and formats employed by the FFmpeg +libraries and tools. +

+ +

6.1 Quoting and escaping

+ +

FFmpeg adopts the following quoting and escaping mechanism, unless +explicitly specified. The following rules are applied: +

+
    +
  • ‘'’ and ‘\’ 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. + +
  • A special character is escaped by prefixing it with a ‘\’. + +
  • All characters enclosed between ‘''’ are included literally in the +parsed string. The quote character ‘'’ itself cannot be quoted, +so you may need to close the quote and escape it. + +
  • Leading and trailing whitespaces, unless escaped or quoted, are +removed from the parsed string. +
+ +

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 av_get_token defined in +libavutil/avstring.h can be used to parse a token quoted or +escaped according to the rules defined above. +

+

The tool tools/ffescape in the FFmpeg source tree can be used +to automatically quote or escape a string in a script. +

+ +

6.1.1 Examples

+ +
    +
  • Escape the string Crime d'Amour containing the ' special +character: +
    +
    Crime d\'Amour
    +
    + +
  • The string above contains a quote, so the ' needs to be escaped +when quoting it: +
    +
    'Crime d'\''Amour'
    +
    + +
  • Include leading or trailing whitespaces using quoting: +
    +
    '  this string starts and ends with whitespaces  '
    +
    + +
  • Escaping and quoting can be mixed together: +
    +
    ' The string '\'string\'' is a string '
    +
    + +
  • To include a literal ‘\’ you can use either escaping or quoting: +
    +
    'c:\foo' can be written as c:\\foo
    +
    +
+ + +

6.2 Date

+ +

The accepted syntax is: +

+
[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
+now
+
+ +

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. +

+ +

6.3 Time duration

+ +

There are two accepted syntaxes for expressing time duration. +

+
+
[-][HH:]MM:SS[.m...]
+
+ +

HH expresses the number of hours, MM the number of minutes +for a maximum of 2 digits, and SS the number of seconds for a +maximum of 2 digits. The m at the end expresses decimal value for +SS. +

+

or +

+
+
[-]S+[.m...][s|ms|us]
+
+ +

S expresses the number of seconds, with the optional decimal part +m. The optional literal suffixes ‘s’, ‘ms’ or ‘us’ +indicate to interpret the value as seconds, milliseconds or microseconds, +respectively. +

+

In both expressions, the optional ‘-’ indicates negative duration. +

+ +

6.3.1 Examples

+ +

The following examples are all valid time duration: +

+
+
‘55’
+

55 seconds +

+
+
‘0.2’
+

0.2 seconds +

+
+
‘200ms’
+

200 milliseconds, that’s 0.2s +

+
+
‘200000us’
+

200000 microseconds, that’s 0.2s +

+
+
‘12:03:45’
+

12 hours, 03 minutes and 45 seconds +

+
+
‘23.189’
+

23.189 seconds +

+
+ + +

6.4 Video size

+

Specify the size of the sourced video, it may be a string of the form +widthxheight, or the name of a size abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

720x480 +

+
‘pal’
+

720x576 +

+
‘qntsc’
+

352x240 +

+
‘qpal’
+

352x288 +

+
‘sntsc’
+

640x480 +

+
‘spal’
+

768x576 +

+
‘film’
+

352x240 +

+
‘ntsc-film’
+

352x240 +

+
‘sqcif’
+

128x96 +

+
‘qcif’
+

176x144 +

+
‘cif’
+

352x288 +

+
‘4cif’
+

704x576 +

+
‘16cif’
+

1408x1152 +

+
‘qqvga’
+

160x120 +

+
‘qvga’
+

320x240 +

+
‘vga’
+

640x480 +

+
‘svga’
+

800x600 +

+
‘xga’
+

1024x768 +

+
‘uxga’
+

1600x1200 +

+
‘qxga’
+

2048x1536 +

+
‘sxga’
+

1280x1024 +

+
‘qsxga’
+

2560x2048 +

+
‘hsxga’
+

5120x4096 +

+
‘wvga’
+

852x480 +

+
‘wxga’
+

1366x768 +

+
‘wsxga’
+

1600x1024 +

+
‘wuxga’
+

1920x1200 +

+
‘woxga’
+

2560x1600 +

+
‘wqsxga’
+

3200x2048 +

+
‘wquxga’
+

3840x2400 +

+
‘whsxga’
+

6400x4096 +

+
‘whuxga’
+

7680x4800 +

+
‘cga’
+

320x200 +

+
‘ega’
+

640x350 +

+
‘hd480’
+

852x480 +

+
‘hd720’
+

1280x720 +

+
‘hd1080’
+

1920x1080 +

+
‘2k’
+

2048x1080 +

+
‘2kflat’
+

1998x1080 +

+
‘2kscope’
+

2048x858 +

+
‘4k’
+

4096x2160 +

+
‘4kflat’
+

3996x2160 +

+
‘4kscope’
+

4096x1716 +

+
‘nhd’
+

640x360 +

+
‘hqvga’
+

240x160 +

+
‘wqvga’
+

400x240 +

+
‘fwqvga’
+

432x240 +

+
‘hvga’
+

480x320 +

+
‘qhd’
+

960x540 +

+
‘2kdci’
+

2048x1080 +

+
‘4kdci’
+

4096x2160 +

+
‘uhd2160’
+

3840x2160 +

+
‘uhd4320’
+

7680x4320 +

+
+ + +

6.5 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 +frame_rate_num/frame_rate_den, an integer number, a float +number or a valid video frame rate abbreviation. +

+

The following abbreviations are recognized: +

+
‘ntsc’
+

30000/1001 +

+
‘pal’
+

25/1 +

+
‘qntsc’
+

30000/1001 +

+
‘qpal’
+

25/1 +

+
‘sntsc’
+

30000/1001 +

+
‘spal’
+

25/1 +

+
‘film’
+

24/1 +

+
‘ntsc-film’
+

24000/1001 +

+
+ + +

6.6 Ratio

+ +

A ratio can be expressed as an expression, or in the form +numerator: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. +

+ +

6.7 Color

+ +

It can be the name of a color as defined below (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’ or ‘0.0’ means completely +transparent, ‘0xff’ or ‘1.0’ completely opaque). If the alpha +component is not specified then ‘0xff’ is assumed. +

+

The string ‘random’ will result in a random color. +

+

The following names of colors are recognized: +

+
‘AliceBlue’
+

0xF0F8FF +

+
‘AntiqueWhite’
+

0xFAEBD7 +

+
‘Aqua’
+

0x00FFFF +

+
‘Aquamarine’
+

0x7FFFD4 +

+
‘Azure’
+

0xF0FFFF +

+
‘Beige’
+

0xF5F5DC +

+
‘Bisque’
+

0xFFE4C4 +

+
‘Black’
+

0x000000 +

+
‘BlanchedAlmond’
+

0xFFEBCD +

+
‘Blue’
+

0x0000FF +

+
‘BlueViolet’
+

0x8A2BE2 +

+
‘Brown’
+

0xA52A2A +

+
‘BurlyWood’
+

0xDEB887 +

+
‘CadetBlue’
+

0x5F9EA0 +

+
‘Chartreuse’
+

0x7FFF00 +

+
‘Chocolate’
+

0xD2691E +

+
‘Coral’
+

0xFF7F50 +

+
‘CornflowerBlue’
+

0x6495ED +

+
‘Cornsilk’
+

0xFFF8DC +

+
‘Crimson’
+

0xDC143C +

+
‘Cyan’
+

0x00FFFF +

+
‘DarkBlue’
+

0x00008B +

+
‘DarkCyan’
+

0x008B8B +

+
‘DarkGoldenRod’
+

0xB8860B +

+
‘DarkGray’
+

0xA9A9A9 +

+
‘DarkGreen’
+

0x006400 +

+
‘DarkKhaki’
+

0xBDB76B +

+
‘DarkMagenta’
+

0x8B008B +

+
‘DarkOliveGreen’
+

0x556B2F +

+
‘Darkorange’
+

0xFF8C00 +

+
‘DarkOrchid’
+

0x9932CC +

+
‘DarkRed’
+

0x8B0000 +

+
‘DarkSalmon’
+

0xE9967A +

+
‘DarkSeaGreen’
+

0x8FBC8F +

+
‘DarkSlateBlue’
+

0x483D8B +

+
‘DarkSlateGray’
+

0x2F4F4F +

+
‘DarkTurquoise’
+

0x00CED1 +

+
‘DarkViolet’
+

0x9400D3 +

+
‘DeepPink’
+

0xFF1493 +

+
‘DeepSkyBlue’
+

0x00BFFF +

+
‘DimGray’
+

0x696969 +

+
‘DodgerBlue’
+

0x1E90FF +

+
‘FireBrick’
+

0xB22222 +

+
‘FloralWhite’
+

0xFFFAF0 +

+
‘ForestGreen’
+

0x228B22 +

+
‘Fuchsia’
+

0xFF00FF +

+
‘Gainsboro’
+

0xDCDCDC +

+
‘GhostWhite’
+

0xF8F8FF +

+
‘Gold’
+

0xFFD700 +

+
‘GoldenRod’
+

0xDAA520 +

+
‘Gray’
+

0x808080 +

+
‘Green’
+

0x008000 +

+
‘GreenYellow’
+

0xADFF2F +

+
‘HoneyDew’
+

0xF0FFF0 +

+
‘HotPink’
+

0xFF69B4 +

+
‘IndianRed’
+

0xCD5C5C +

+
‘Indigo’
+

0x4B0082 +

+
‘Ivory’
+

0xFFFFF0 +

+
‘Khaki’
+

0xF0E68C +

+
‘Lavender’
+

0xE6E6FA +

+
‘LavenderBlush’
+

0xFFF0F5 +

+
‘LawnGreen’
+

0x7CFC00 +

+
‘LemonChiffon’
+

0xFFFACD +

+
‘LightBlue’
+

0xADD8E6 +

+
‘LightCoral’
+

0xF08080 +

+
‘LightCyan’
+

0xE0FFFF +

+
‘LightGoldenRodYellow’
+

0xFAFAD2 +

+
‘LightGreen’
+

0x90EE90 +

+
‘LightGrey’
+

0xD3D3D3 +

+
‘LightPink’
+

0xFFB6C1 +

+
‘LightSalmon’
+

0xFFA07A +

+
‘LightSeaGreen’
+

0x20B2AA +

+
‘LightSkyBlue’
+

0x87CEFA +

+
‘LightSlateGray’
+

0x778899 +

+
‘LightSteelBlue’
+

0xB0C4DE +

+
‘LightYellow’
+

0xFFFFE0 +

+
‘Lime’
+

0x00FF00 +

+
‘LimeGreen’
+

0x32CD32 +

+
‘Linen’
+

0xFAF0E6 +

+
‘Magenta’
+

0xFF00FF +

+
‘Maroon’
+

0x800000 +

+
‘MediumAquaMarine’
+

0x66CDAA +

+
‘MediumBlue’
+

0x0000CD +

+
‘MediumOrchid’
+

0xBA55D3 +

+
‘MediumPurple’
+

0x9370D8 +

+
‘MediumSeaGreen’
+

0x3CB371 +

+
‘MediumSlateBlue’
+

0x7B68EE +

+
‘MediumSpringGreen’
+

0x00FA9A +

+
‘MediumTurquoise’
+

0x48D1CC +

+
‘MediumVioletRed’
+

0xC71585 +

+
‘MidnightBlue’
+

0x191970 +

+
‘MintCream’
+

0xF5FFFA +

+
‘MistyRose’
+

0xFFE4E1 +

+
‘Moccasin’
+

0xFFE4B5 +

+
‘NavajoWhite’
+

0xFFDEAD +

+
‘Navy’
+

0x000080 +

+
‘OldLace’
+

0xFDF5E6 +

+
‘Olive’
+

0x808000 +

+
‘OliveDrab’
+

0x6B8E23 +

+
‘Orange’
+

0xFFA500 +

+
‘OrangeRed’
+

0xFF4500 +

+
‘Orchid’
+

0xDA70D6 +

+
‘PaleGoldenRod’
+

0xEEE8AA +

+
‘PaleGreen’
+

0x98FB98 +

+
‘PaleTurquoise’
+

0xAFEEEE +

+
‘PaleVioletRed’
+

0xD87093 +

+
‘PapayaWhip’
+

0xFFEFD5 +

+
‘PeachPuff’
+

0xFFDAB9 +

+
‘Peru’
+

0xCD853F +

+
‘Pink’
+

0xFFC0CB +

+
‘Plum’
+

0xDDA0DD +

+
‘PowderBlue’
+

0xB0E0E6 +

+
‘Purple’
+

0x800080 +

+
‘Red’
+

0xFF0000 +

+
‘RosyBrown’
+

0xBC8F8F +

+
‘RoyalBlue’
+

0x4169E1 +

+
‘SaddleBrown’
+

0x8B4513 +

+
‘Salmon’
+

0xFA8072 +

+
‘SandyBrown’
+

0xF4A460 +

+
‘SeaGreen’
+

0x2E8B57 +

+
‘SeaShell’
+

0xFFF5EE +

+
‘Sienna’
+

0xA0522D +

+
‘Silver’
+

0xC0C0C0 +

+
‘SkyBlue’
+

0x87CEEB +

+
‘SlateBlue’
+

0x6A5ACD +

+
‘SlateGray’
+

0x708090 +

+
‘Snow’
+

0xFFFAFA +

+
‘SpringGreen’
+

0x00FF7F +

+
‘SteelBlue’
+

0x4682B4 +

+
‘Tan’
+

0xD2B48C +

+
‘Teal’
+

0x008080 +

+
‘Thistle’
+

0xD8BFD8 +

+
‘Tomato’
+

0xFF6347 +

+
‘Turquoise’
+

0x40E0D0 +

+
‘Violet’
+

0xEE82EE +

+
‘Wheat’
+

0xF5DEB3 +

+
‘White’
+

0xFFFFFF +

+
‘WhiteSmoke’
+

0xF5F5F5 +

+
‘Yellow’
+

0xFFFF00 +

+
‘YellowGreen’
+

0x9ACD32 +

+
+ + +

6.8 Channel Layout

+ +

A channel layout specifies the spatial disposition of the channels in +a multi-channel audio stream. To specify a channel layout, FFmpeg +makes use of a special syntax. +

+

Individual channels are identified by an id, as given by the table +below: +

+
‘FL’
+

front left +

+
‘FR’
+

front right +

+
‘FC’
+

front center +

+
‘LFE’
+

low frequency +

+
‘BL’
+

back left +

+
‘BR’
+

back right +

+
‘FLC’
+

front left-of-center +

+
‘FRC’
+

front right-of-center +

+
‘BC’
+

back center +

+
‘SL’
+

side left +

+
‘SR’
+

side right +

+
‘TC’
+

top center +

+
‘TFL’
+

top front left +

+
‘TFC’
+

top front center +

+
‘TFR’
+

top front right +

+
‘TBL’
+

top back left +

+
‘TBC’
+

top back center +

+
‘TBR’
+

top back right +

+
‘DL’
+

downmix left +

+
‘DR’
+

downmix right +

+
‘WL’
+

wide left +

+
‘WR’
+

wide right +

+
‘SDL’
+

surround direct left +

+
‘SDR’
+

surround direct right +

+
‘LFE2’
+

low frequency 2 +

+
+ +

Standard channel layout compositions can be specified by using the +following identifiers: +

+
‘mono’
+

FC +

+
‘stereo’
+

FL+FR +

+
‘2.1’
+

FL+FR+LFE +

+
‘3.0’
+

FL+FR+FC +

+
‘3.0(back)’
+

FL+FR+BC +

+
‘4.0’
+

FL+FR+FC+BC +

+
‘quad’
+

FL+FR+BL+BR +

+
‘quad(side)’
+

FL+FR+SL+SR +

+
‘3.1’
+

FL+FR+FC+LFE +

+
‘5.0’
+

FL+FR+FC+BL+BR +

+
‘5.0(side)’
+

FL+FR+FC+SL+SR +

+
‘4.1’
+

FL+FR+FC+LFE+BC +

+
‘5.1’
+

FL+FR+FC+LFE+BL+BR +

+
‘5.1(side)’
+

FL+FR+FC+LFE+SL+SR +

+
‘6.0’
+

FL+FR+FC+BC+SL+SR +

+
‘6.0(front)’
+

FL+FR+FLC+FRC+SL+SR +

+
‘3.1.2’
+

FL+FR+FC+LFE+TFL+TFR +

+
‘hexagonal’
+

FL+FR+FC+BL+BR+BC +

+
‘6.1’
+

FL+FR+FC+LFE+BC+SL+SR +

+
‘6.1’
+

FL+FR+FC+LFE+BL+BR+BC +

+
‘6.1(front)’
+

FL+FR+LFE+FLC+FRC+SL+SR +

+
‘7.0’
+

FL+FR+FC+BL+BR+SL+SR +

+
‘7.0(front)’
+

FL+FR+FC+FLC+FRC+SL+SR +

+
‘7.1’
+

FL+FR+FC+LFE+BL+BR+SL+SR +

+
‘7.1(wide)’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC +

+
‘7.1(wide-side)’
+

FL+FR+FC+LFE+FLC+FRC+SL+SR +

+
‘5.1.2’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR +

+
‘octagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR +

+
‘cube’
+

FL+FR+BL+BR+TFL+TFR+TBL+TBR +

+
‘5.1.4’
+

FL+FR+FC+LFE+BL+BR+TFL+TFR+TBL+TBR +

+
‘7.1.2’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR +

+
‘7.1.4’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBL+TBR +

+
‘7.2.3’
+

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBC+LFE2 +

+
‘9.1.4’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR +

+
‘9.1.6’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR+TSL+TSR +

+
‘hexadecagonal’
+

FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR +

+
‘binaural’
+

BIL+BIR +

+
‘downmix’
+

DL+DR +

+
‘22.2’
+

FL+FR+FC+LFE+BL+BR+FLC+FRC+BC+SL+SR+TC+TFL+TFC+TFR+TBL+TBC+TBR+LFE2+TSL+TSR+BFC+BFL+BFR +

+
+ +

A custom channel layout can be specified as a sequence of terms, separated by ’+’. +Each term can be: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.), +each optionally containing a custom name after a ’@’, (e.g. ‘FL@Left’, +‘FR@Right’, ‘FC@Center’, ‘LFE@Low_Frequency’, etc.) +
+ +

A standard channel layout can be specified by the following: +

    +
  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.) + +
  • the name of a standard channel layout (e.g. ‘mono’, +‘stereo’, ‘4.0’, ‘quad’, ‘5.0’, etc.) + +
  • a number of channels, in decimal, followed by ’c’, yielding the default channel +layout for that number of channels (see the function +av_channel_layout_default). Note that not all channel counts have a +default layout. + +
  • a number of channels, in decimal, followed by ’C’, yielding an unknown channel +layout with the specified number of channels. Note that not all channel layout +specification strings support unknown channel layouts. + +
  • a channel layout mask, in hexadecimal starting with "0x" (see the +AV_CH_* macros in libavutil/channel_layout.h. +
+ +

Before libavutil version 53 the trailing character "c" to specify a number of +channels was optional, but now it is required, while a channel layout mask can +also be specified as a decimal number (if and only if not followed by "c" or "C"). +

+

See also the function av_channel_layout_from_string defined in +libavutil/channel_layout.h. +

+ +

7 Expression Evaluation

+ +

When evaluating an arithmetic expression, FFmpeg uses an internal +formula evaluator, implemented through the libavutil/eval.h +interface. +

+

An expression may contain unary, binary operators, constants, and +functions. +

+

Two expressions expr1 and expr2 can be combined to form +another expression "expr1;expr2". +expr1 and expr2 are evaluated in turn, and the new +expression evaluates to the value of expr2. +

+

The following binary operators are available: +, -, +*, /, ^. +

+

The following unary operators are available: +, -. +

+

Some internal variables can be used to store and load intermediary +results. They can be accessed using the ld and st +functions with an index argument varying from 0 to 9 to specify which +internal variable to access. +

+

The following functions are available: +

+
abs(x)
+

Compute absolute value of x. +

+
+
acos(x)
+

Compute arccosine of x. +

+
+
asin(x)
+

Compute arcsine of x. +

+
+
atan(x)
+

Compute arctangent of x. +

+
+
atan2(y, x)
+

Compute principal value of the arc tangent of y/x. +

+
+
between(x, min, max)
+

Return 1 if x is greater than or equal to min and lesser than or +equal to max, 0 otherwise. +

+
+
bitand(x, y)
+
bitor(x, y)
+

Compute bitwise and/or operation on x and y. +

+

The results of the evaluation of x and 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). +

+
+
ceil(expr)
+

Round the value of expression expr upwards to the nearest +integer. For example, "ceil(1.5)" is "2.0". +

+
+
clip(x, min, max)
+

Return the value of x clipped between min and max. +

+
+
cos(x)
+

Compute cosine of x. +

+
+
cosh(x)
+

Compute hyperbolic cosine of x. +

+
+
eq(x, y)
+

Return 1 if x and y are equivalent, 0 otherwise. +

+
+
exp(x)
+

Compute exponential of x (with base e, the Euler’s number). +

+
+
floor(expr)
+

Round the value of expression expr downwards to the nearest +integer. For example, "floor(-1.5)" is "-2.0". +

+
+
gauss(x)
+

Compute Gauss function of x, corresponding to +exp(-x*x/2) / sqrt(2*PI). +

+
+
gcd(x, y)
+

Return the greatest common divisor of x and y. If both x and +y are 0 or either or both are less than zero then behavior is undefined. +

+
+
gt(x, y)
+

Return 1 if x is greater than y, 0 otherwise. +

+
+
gte(x, y)
+

Return 1 if x is greater than or equal to y, 0 otherwise. +

+
+
hypot(x, y)
+

This function is similar to the C function with the same name; it returns +"sqrt(x*x + y*y)", the length of the hypotenuse of a +right triangle with sides of length x and y, or the distance of the +point (x, y) from the origin. +

+
+
if(x, y)
+

Evaluate x, and if the result is non-zero return the result of +the evaluation of y, return 0 otherwise. +

+
+
if(x, y, z)
+

Evaluate x, and if the result is non-zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
ifnot(x, y)
+

Evaluate x, and if the result is zero return the result of the +evaluation of y, return 0 otherwise. +

+
+
ifnot(x, y, z)
+

Evaluate x, and if the result is zero return the evaluation +result of y, otherwise the evaluation result of z. +

+
+
isinf(x)
+

Return 1.0 if x is +/-INFINITY, 0.0 otherwise. +

+
+
isnan(x)
+

Return 1.0 if x is NAN, 0.0 otherwise. +

+
+
ld(idx)
+

Load the value of the internal variable with index idx, which was +previously stored with st(idx, expr). +The function returns the loaded value. +

+
+
lerp(x, y, z)
+

Return linear interpolation between x and y by amount of z. +

+
+
log(x)
+

Compute natural logarithm of x. +

+
+
lt(x, y)
+

Return 1 if x is lesser than y, 0 otherwise. +

+
+
lte(x, y)
+

Return 1 if x is lesser than or equal to y, 0 otherwise. +

+
+
max(x, y)
+

Return the maximum between x and y. +

+
+
min(x, y)
+

Return the minimum between x and y. +

+
+
mod(x, y)
+

Compute the remainder of division of x by y. +

+
+
not(expr)
+

Return 1.0 if expr is zero, 0.0 otherwise. +

+
+
pow(x, y)
+

Compute the power of x elevated y, it is equivalent to +"(x)^(y)". +

+
+
print(t)
+
print(t, l)
+

Print the value of expression t with loglevel l. If l is not +specified then a default log level is used. +Return the value of the expression printed. +

+
+
random(idx)
+

Return a pseudo random value between 0.0 and 1.0. idx is the +index of the internal variable used to save the seed/state, which can be +previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+

For example, to store the seed with value 42 in the internal +variable with index 0 and print a few random values: +

+
st(0,42); print(random(0)); print(random(0)); print(random(0))
+
+ +
+
randomi(idx, min, max)
+

Return a pseudo random value in the interval between min and +max. idx is the index of the internal variable which will be used to +save the seed/state, which can be previously stored with st(idx). +

+

To initialize the seed, you need to store the seed value as a 64-bit +unsigned integer in the internal variable with index idx. +

+
+
root(expr, max)
+

Find an input value for which the function represented by expr +with argument ld(0) is 0 in the interval 0..max. +

+

The expression in expr must denote a continuous function or the +result is undefined. +

+

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 ld(0). When the expression evaluates to +0 then the corresponding input value will be returned. +

+
+
round(expr)
+

Round the value of expression expr to the nearest integer. For example, +"round(1.5)" is "2.0". +

+
+
sgn(x)
+

Compute sign of x. +

+
+
sin(x)
+

Compute sine of x. +

+
+
sinh(x)
+

Compute hyperbolic sine of x. +

+
+
sqrt(expr)
+

Compute the square root of expr. This is equivalent to +"(expr)^.5". +

+
+
squish(x)
+

Compute expression 1/(1 + exp(4*x)). +

+
+
st(idx, expr)
+

Store the value of the expression expr in an internal +variable. idx specifies the index 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. +

+

The stored value can be retrieved with ld(var). +

+

Note: variables are currently not shared between expressions. +

+
+
tan(x)
+

Compute tangent of x. +

+
+
tanh(x)
+

Compute hyperbolic tangent of x. +

+
+
taylor(expr, x)
+
taylor(expr, x, idx)
+

Evaluate a Taylor series at x, given an expression representing +the ld(idx)-th derivative of a function at 0. +

+

When the series does not converge the result is undefined. +

+

ld(idx) is used to represent the derivative order in expr, +which means that the given expression will be evaluated multiple times +with various input values that the expression can access through +ld(idx). If idx is not specified then 0 is assumed. +

+

Note, when you have the derivatives at y instead of 0, +taylor(expr, x-y) can be used. +

+
+
time(0)
+

Return the current (wallclock) time in seconds. +

+
+
trunc(expr)
+

Round the value of expression expr towards zero to the nearest +integer. For example, "trunc(-1.5)" is "-1.0". +

+
+
while(cond, expr)
+

Evaluate expression expr while the expression cond is +non-zero, and returns the value of the last expr evaluation, or +NAN if cond was always false. +

+
+ +

The following constants are available: +

+
PI
+

area of the unit disc, approximately 3.14 +

+
E
+

exp(1) (Euler’s number), approximately 2.718 +

+
PHI
+

golden ratio (1+sqrt(5))/2, approximately 1.618 +

+
+ +

Assuming that an expression is considered "true" if it has a non-zero +value, note that: +

+

* works like AND +

+

+ works like OR +

+

For example the construct: +

+
if (A AND B) then C
+
+

is equivalent to: +

+
if(A*B, C)
+
+ +

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. +

+
y
+

10^-24 / 2^-80 +

+
z
+

10^-21 / 2^-70 +

+
a
+

10^-18 / 2^-60 +

+
f
+

10^-15 / 2^-50 +

+
p
+

10^-12 / 2^-40 +

+
n
+

10^-9 / 2^-30 +

+
u
+

10^-6 / 2^-20 +

+
m
+

10^-3 / 2^-10 +

+
c
+

10^-2 +

+
d
+

10^-1 +

+
h
+

10^2 +

+
k
+

10^3 / 2^10 +

+
K
+

10^3 / 2^10 +

+
M
+

10^6 / 2^20 +

+
G
+

10^9 / 2^30 +

+
T
+

10^12 / 2^40 +

+
P
+

10^15 / 2^50 +

+
E
+

10^18 / 2^60 +

+
Z
+

10^21 / 2^70 +

+
Y
+

10^24 / 2^80 +

+
+ + +

8 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 nonsensical 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVCodecContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follow: +

+
+
b integer (encoding,audio,video)
+

Set bitrate in bits/s. Default value is 200K. +

+
+
ab integer (encoding,audio)
+

Set audio bitrate (in bits/s). Default value is 128K. +

+
+
bt integer (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. +

+
+
flags flags (decoding/encoding,audio,video,subtitles)
+

Set generic flags. +

+

Possible values: +

+
‘mv4’
+

Use four motion vector by macroblock (mpeg4). +

+
‘qpel’
+

Use 1/4 pel motion compensation. +

+
‘loop’
+

Use loop filter. +

+
‘qscale’
+

Use fixed qscale. +

+
‘pass1’
+

Use internal 2pass ratecontrol in first pass mode. +

+
‘pass2’
+

Use internal 2pass ratecontrol in second pass mode. +

+
‘gray’
+

Only decode/encode grayscale. +

+
‘psnr’
+

Set error[?] variables during encoding. +

+
‘truncated’
+

Input bitstream might be randomly truncated. +

+
‘drop_changed’
+

Don’t output frames whose parameters differ from first decoded frame in stream. +Error AVERROR_INPUT_CHANGED is returned when a frame is dropped. +

+
+
‘ildct’
+

Use interlaced DCT. +

+
‘low_delay’
+

Force low delay. +

+
‘global_header’
+

Place global headers in extradata instead of every keyframe. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. (except (I)DCT). +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘aic’
+

Apply H263 advanced intra coding / mpeg4 ac prediction. +

+
‘ilme’
+

Apply interlaced motion estimation. +

+
‘cgop’
+

Use closed gop. +

+
‘output_corrupt’
+

Output even potentially corrupted frames. +

+
+ +
+
time_base 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 / frame_rate and timestamp increments should be +identically 1. +

+
+
g integer (encoding,video)
+

Set the group of picture (GOP) size. Default value is 12. +

+
+
ar integer (decoding/encoding,audio)
+

Set audio sampling rate (in Hz). +

+
+
ac integer (decoding/encoding,audio)
+

Set number of audio channels. +

+
+
cutoff integer (encoding,audio)
+

Set cutoff bandwidth. (Supported only by selected encoders, see +their respective documentation sections.) +

+
+
frame_size integer (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. +

+
+
frame_number integer
+

Set the frame number. +

+
+
delay integer
+
qcomp float (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. +

+
+
qblur float (encoding,video)
+

Set video quantizer scale blur (VBR). +

+
+
qmin integer (encoding,video)
+

Set min video quantizer scale (VBR). Must be included between -1 and +69, default value is 2. +

+
+
qmax integer (encoding,video)
+

Set max video quantizer scale (VBR). Must be included between -1 and +1024, default value is 31. +

+
+
qdiff integer (encoding,video)
+

Set max difference between the quantizer scale (VBR). +

+
+
bf integer (encoding,video)
+

Set max number of B frames between non-B-frames. +

+

Must be an integer between -1 and 16. 0 means that B-frames are +disabled. If a value of -1 is used, it will choose an automatic value +depending on the encoder. +

+

Default value is 0. +

+
+
b_qfactor float (encoding,video)
+

Set qp factor between P and B frames. +

+
+
codec_tag integer
+
bug flags (decoding,video)
+

Workaround not auto detected encoder bugs. +

+

Possible values: +

+
‘autodetect’
+
‘xvid_ilace’
+

Xvid interlacing bug (autodetected if fourcc==XVIX) +

+
‘ump4’
+

(autodetected if fourcc==UMP4) +

+
‘no_padding’
+

padding bug (autodetected) +

+
‘amv’
+
‘qpel_chroma’
+
‘std_qpel’
+

old standard qpel (autodetected per fourcc/version) +

+
‘qpel_chroma2’
+
‘direct_blocksize’
+

direct-qpel-blocksize bug (autodetected per fourcc/version) +

+
‘edge’
+

edge padding bug (autodetected per fourcc/version) +

+
‘hpel_chroma’
+
‘dc_clip’
+
‘ms’
+

Workaround various bugs in microsoft broken decoders. +

+
‘trunc’
+

trancated frames +

+
+ +
+
strict integer (decoding/encoding,audio,video)
+

Specify how strictly to follow the standards. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
b_qoffset float (encoding,video)
+

Set QP offset between P and B frames. +

+
+
err_detect flags (decoding,audio,video)
+

Set error detection flags. +

+

Possible values: +

+
‘crccheck’
+

verify embedded CRCs +

+
‘bitstream’
+

detect bitstream specification deviations +

+
‘buffer’
+

detect improper bitstream length +

+
‘explode’
+

abort decoding on minor error detection +

+
‘ignore_err’
+

ignore decoding errors, and continue decoding. +This is useful if you want to analyze the content of a video and thus want +everything to be decoded no matter what. This option will not result in a video +that is pleasing to watch in case of errors. +

+
‘careful’
+

consider things that violate the spec and have not been seen in the wild as errors +

+
‘compliant’
+

consider all spec non compliancies as errors +

+
‘aggressive’
+

consider things that a sane encoder should not do as an error +

+
+ +
+
has_b_frames integer
+
block_align integer
+
rc_override_count integer
+
maxrate integer (encoding,audio,video)
+

Set max bitrate tolerance (in bits/s). Requires bufsize to be set. +

+
+
minrate integer (encoding,audio,video)
+

Set min bitrate tolerance (in bits/s). Most useful in setting up a CBR +encode. It is of little use elsewise. +

+
+
bufsize integer (encoding,audio,video)
+

Set ratecontrol buffer size (in bits). +

+
+
i_qfactor float (encoding,video)
+

Set QP factor between P and I frames. +

+
+
i_qoffset float (encoding,video)
+

Set QP offset between P and I frames. +

+
+
dct integer (encoding,video)
+

Set DCT algorithm. +

+

Possible values: +

+
‘auto’
+

autoselect a good one (default) +

+
‘fastint’
+

fast integer +

+
‘int’
+

accurate integer +

+
‘mmx’
+
‘altivec’
+
‘faan’
+

floating point AAN DCT +

+
+ +
+
lumi_mask float (encoding,video)
+

Compress bright areas stronger than medium ones. +

+
+
tcplx_mask float (encoding,video)
+

Set temporal complexity masking. +

+
+
scplx_mask float (encoding,video)
+

Set spatial complexity masking. +

+
+
p_mask float (encoding,video)
+

Set inter masking. +

+
+
dark_mask float (encoding,video)
+

Compress dark areas stronger than medium ones. +

+
+
idct integer (decoding/encoding,video)
+

Select IDCT implementation. +

+

Possible values: +

+
‘auto’
+
‘int’
+
‘simple’
+
‘simplemmx’
+
‘simpleauto’
+

Automatically pick a IDCT compatible with the simple one +

+
+
‘arm’
+
‘altivec’
+
‘sh4’
+
‘simplearm’
+
‘simplearmv5te’
+
‘simplearmv6’
+
‘simpleneon’
+
‘xvid’
+
‘faani’
+

floating point AAN IDCT +

+
+ +
+
slice_count integer
+
ec flags (decoding,video)
+

Set error concealment strategy. +

+

Possible values: +

+
‘guess_mvs’
+

iterative motion vector (MV) search (slow) +

+
‘deblock’
+

use strong deblock filter for damaged MBs +

+
‘favor_inter’
+

favor predicting from the previous frame instead of the current +

+
+ +
+
bits_per_coded_sample integer
+
aspect rational number (encoding,video)
+

Set sample aspect ratio. +

+
+
sar rational number (encoding,video)
+

Set sample aspect ratio. Alias to aspect. +

+
+
debug flags (decoding/encoding,audio,video,subtitles)
+

Print specific debug info. +

+

Possible values: +

+
‘pict’
+

picture info +

+
‘rc’
+

rate control +

+
‘bitstream’
+
‘mb_type’
+

macroblock (MB) type +

+
‘qp’
+

per-block quantization parameter (QP) +

+
‘dct_coeff’
+
‘green_metadata’
+

display complexity metadata for the upcoming frame, GoP or for a given duration. +

+
+
‘skip’
+
‘startcode’
+
‘er’
+

error recognition +

+
‘mmco’
+

memory management control operations (H.264) +

+
‘bugs’
+
‘buffers’
+

picture buffer allocations +

+
‘thread_ops’
+

threading operations +

+
‘nomc’
+

skip motion compensation +

+
+ +
+
cmp integer (encoding,video)
+

Set full pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
subcmp integer (encoding,video)
+

Set sub pel me compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
mbcmp integer (encoding,video)
+

Set macroblock compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
ildctcmp integer (encoding,video)
+

Set interlaced dct compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation. +

+
‘(1024, INT_MAX)’
+

full motion estimation(slowest) +

+
‘(768, 1024]’
+

umh motion estimation +

+
‘(512, 768]’
+

hex motion estimation +

+
‘(256, 512]’
+

l2s diamond motion estimation +

+
‘[2,256]’
+

var diamond motion estimation +

+
‘(-1, 2)’
+

small diamond motion estimation +

+
‘-1’
+

funny diamond motion estimation +

+
‘(INT_MIN, -1)’
+

sab diamond motion estimation +

+
+ +
+
last_pred integer (encoding,video)
+

Set amount of motion predictors from the previous frame. +

+
+
precmp integer (encoding,video)
+

Set pre motion estimation compare function. +

+

Possible values: +

+
‘sad’
+

sum of absolute differences, fast (default) +

+
‘sse’
+

sum of squared errors +

+
‘satd’
+

sum of absolute Hadamard transformed differences +

+
‘dct’
+

sum of absolute DCT transformed differences +

+
‘psnr’
+

sum of squared quantization errors (avoid, low quality) +

+
‘bit’
+

number of bits needed for the block +

+
‘rd’
+

rate distortion optimal, slow +

+
‘zero’
+

0 +

+
‘vsad’
+

sum of absolute vertical differences +

+
‘vsse’
+

sum of squared vertical differences +

+
‘nsse’
+

noise preserving sum of squared differences +

+
‘w53’
+

5/3 wavelet, only used in snow +

+
‘w97’
+

9/7 wavelet, only used in snow +

+
‘dctmax’
+
‘chroma’
+
+ +
+
pre_dia_size integer (encoding,video)
+

Set diamond type & size for motion estimation pre-pass. +

+
+
subq integer (encoding,video)
+

Set sub pel motion estimation quality. +

+
+
me_range integer (encoding,video)
+

Set limit motion vectors range (1023 for DivX player). +

+
+
global_quality integer (encoding,audio,video)
+
slice_flags integer
+
mbd integer (encoding,video)
+

Set macroblock decision algorithm (high quality mode). +

+

Possible values: +

+
‘simple’
+

use mbcmp (default) +

+
‘bits’
+

use fewest bits +

+
‘rd’
+

use best rate distortion +

+
+ +
+
rc_init_occupancy integer (encoding,video)
+

Set number of bits which should be loaded into the rc buffer before +decoding starts. +

+
+
flags2 flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘fast’
+

Allow non spec compliant speedup tricks. +

+
‘noout’
+

Skip bitstream encoding. +

+
‘ignorecrop’
+

Ignore cropping information from sps. +

+
‘local_header’
+

Place global headers at every keyframe instead of in extradata. +

+
‘chunks’
+

Frame data might be split into multiple chunks. +

+
‘showall’
+

Show all frames before the first keyframe. +

+
‘export_mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘skip_manual’
+

Do not skip samples and export skip information as frame side data. +

+
‘ass_ro_flush_noop’
+

Do not reset ASS ReadOrder field on flush. +

+
‘icc_profiles’
+

Generate/parse embedded ICC profiles from/to colorimetry tags. +

+
+ +
+
export_side_data flags (decoding/encoding,audio,video,subtitles)
+
+

Possible values: +

+
‘mvs’
+

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) +for codecs that support it. See also doc/examples/export_mvs.c. +

+
‘prft’
+

Export encoder Producer Reference Time into packet side-data (see AV_PKT_DATA_PRFT) +for codecs that support it. +

+
‘venc_params’
+

Export video encoding parameters through frame side data (see AV_FRAME_DATA_VIDEO_ENC_PARAMS) +for codecs that support it. At present, those are H.264 and VP9. +

+
‘film_grain’
+

Export film grain parameters through frame side data (see AV_FRAME_DATA_FILM_GRAIN_PARAMS). +Supported at present by AV1 decoders. +

+
‘enhancements’
+

Export picture enhancement metadata through frame side data, e.g. LCEVC (see AV_FRAME_DATA_LCEVC). +

+
+ +
+
threads integer (decoding/encoding,video)
+

Set the number of threads to be used, in case the selected codec +implementation supports multi-threading. +

+

Possible values: +

+
‘auto, 0’
+

automatically select the number of threads to set +

+
+ +

Default value is ‘auto’. +

+
+
dc integer (encoding,video)
+

Set intra_dc_precision. +

+
+
nssew integer (encoding,video)
+

Set nsse weight. +

+
+
skip_top integer (decoding,video)
+

Set number of macroblock rows at the top which are skipped. +

+
+
skip_bottom integer (decoding,video)
+

Set number of macroblock rows at the bottom which are skipped. +

+
+
profile integer (encoding,audio,video)
+
+

Set encoder codec profile. Default value is ‘unknown’. Encoder specific +profiles are documented in the relevant encoder documentation. +

+
+
level integer (encoding,audio,video)
+
+

Set the encoder level. This level depends on the specific codec, and +might correspond to the profile level. It is set by default to +‘unknown’. +

+

Possible values: +

+
‘unknown’
+
+ +
+
lowres integer (decoding,audio,video)
+

Decode at 1= 1/2, 2=1/4, 3=1/8 resolutions. +

+
+
mblmin integer (encoding,video)
+

Set min macroblock lagrange factor (VBR). +

+
+
mblmax integer (encoding,video)
+

Set max macroblock lagrange factor (VBR). +

+
+
skip_loop_filter integer (decoding,video)
+
skip_idct integer (decoding,video)
+
skip_frame integer (decoding,video)
+
+

Make decoder discard processing depending on the frame type selected +by the option value. +

+

skip_loop_filter skips frame loop filtering, skip_idct +skips frame IDCT/dequantization, skip_frame skips decoding. +

+

Possible values: +

+
‘none’
+

Discard no frame. +

+
+
‘default’
+

Discard useless frames like 0-sized frames. +

+
+
‘noref’
+

Discard all non-reference frames. +

+
+
‘bidir’
+

Discard all bidirectional frames. +

+
+
‘nokey’
+

Discard all frames excepts keyframes. +

+
+
‘nointra’
+

Discard all frames except I frames. +

+
+
‘all’
+

Discard all frames. +

+
+ +

Default value is ‘default’. +

+
+
bidir_refine integer (encoding,video)
+

Refine the two motion vectors used in bidirectional macroblocks. +

+
+
keyint_min integer (encoding,video)
+

Set minimum interval between IDR-frames. +

+
+
refs integer (encoding,video)
+

Set reference frames to consider for motion compensation. +

+
+
trellis integer (encoding,audio,video)
+

Set rate-distortion optimal quantization. +

+
+
mv0_threshold integer (encoding,video)
+
compression_level integer (encoding,audio,video)
+
bits_per_raw_sample integer
+
channel_layout integer (decoding/encoding,audio)
+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
rc_max_vbv_use float (encoding,video)
+
rc_min_vbv_use float (encoding,video)
+
color_primaries integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘bt470m’
+

BT.470 M +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘film’
+

Film +

+
‘bt2020’
+

BT.2020 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘smpte431’
+

SMPTE 431-2 +

+
‘smpte432’
+

SMPTE 432-1 +

+
‘jedec-p22’
+

JEDEC P22 +

+
+ +
+
color_trc integer (decoding/encoding,video)
+

Possible values: +

+
‘bt709’
+

BT.709 +

+
‘gamma22’
+

BT.470 M +

+
‘gamma28’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘linear’
+

Linear +

+
‘log’
+
‘log100’
+

Log +

+
‘log_sqrt’
+
‘log316’
+

Log square root +

+
‘iec61966_2_4’
+
‘iec61966-2-4’
+

IEC 61966-2-4 +

+
‘bt1361’
+
‘bt1361e’
+

BT.1361 +

+
‘iec61966_2_1’
+
‘iec61966-2-1’
+

IEC 61966-2-1 +

+
‘bt2020_10’
+
‘bt2020_10bit’
+

BT.2020 - 10 bit +

+
‘bt2020_12’
+
‘bt2020_12bit’
+

BT.2020 - 12 bit +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘smpte428’
+
‘smpte428_1’
+

SMPTE ST 428-1 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ +
+
colorspace integer (decoding/encoding,video)
+

Possible values: +

+
‘rgb’
+

RGB +

+
‘bt709’
+

BT.709 +

+
‘fcc’
+

FCC +

+
‘bt470bg’
+

BT.470 BG +

+
‘smpte170m’
+

SMPTE 170 M +

+
‘smpte240m’
+

SMPTE 240 M +

+
‘ycocg’
+

YCOCG +

+
‘bt2020nc’
+
‘bt2020_ncl’
+

BT.2020 NCL +

+
‘bt2020c’
+
‘bt2020_cl’
+

BT.2020 CL +

+
‘smpte2085’
+

SMPTE 2085 +

+
‘chroma-derived-nc’
+

Chroma-derived NCL +

+
‘chroma-derived-c’
+

Chroma-derived CL +

+
‘ictcp’
+

ICtCp +

+
+ +
+
color_range integer (decoding/encoding,video)
+

If used as input parameter, it serves as a hint to the decoder, which +color_range the input has. +Possible values: +

+
‘tv’
+
‘mpeg’
+
‘limited’
+

MPEG (219*2^(n-8)) +

+
‘pc’
+
‘jpeg’
+
‘full’
+

JPEG (2^n-1) +

+
+ +
+
chroma_sample_location integer (decoding/encoding,video)
+

Possible values: +

+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode integer (decoding/encoding,video)
+

Possible values: +

+
‘premultiplied’
+
‘straight’
+
+ + +
+
log_level_offset integer
+

Set the log level offset. +

+
+
slices integer (encoding,video)
+

Number of slices, used in parallelized encoding. +

+
+
thread_type flags (decoding/encoding,video)
+

Select which multithreading methods to use. +

+

Use of ‘frame’ will increase decoding delay by one frame per +thread, so clients which cannot provide future frames should not use +it. +

+

Possible values: +

+
‘slice’
+

Decode more than one part of a single frame at once. +

+

Multithreading using slices works only when the video was encoded with +slices. +

+
+
‘frame’
+

Decode more than one frame at once. +

+
+ +

Default value is ‘slice+frame’. +

+
+
audio_service_type integer (encoding,audio)
+

Set audio service type. +

+

Possible values: +

+
‘ma’
+

Main Audio Service +

+
‘ef’
+

Effects +

+
‘vi’
+

Visually Impaired +

+
‘hi’
+

Hearing Impaired +

+
‘di’
+

Dialogue +

+
‘co’
+

Commentary +

+
‘em’
+

Emergency +

+
‘vo’
+

Voice Over +

+
‘ka’
+

Karaoke +

+
+ +
+
request_sample_fmt sample_fmt (decoding,audio)
+

Set sample format audio decoders should prefer. Default value is +none. +

+
+
pkt_timebase rational number
+
sub_charenc encoding (decoding,subtitles)
+

Set the input subtitles character encoding. +

+
+
field_order field_order (video)
+

Set/override the field order of the video. +Possible values: +

+
‘progressive’
+

Progressive video +

+
‘tt’
+

Interlaced video, top field coded and displayed first +

+
‘bb’
+

Interlaced video, bottom field coded and displayed first +

+
‘tb’
+

Interlaced video, top coded first, bottom displayed first +

+
‘bt’
+

Interlaced video, bottom coded first, top displayed first +

+
+ +
+
skip_alpha bool (decoding,video)
+

Set to 1 to disable processing alpha (transparency). This works like the +‘gray’ flag in the flags option which skips chroma information +instead of alpha. Default is 0. +

+
+
codec_whitelist list (input)
+

"," separated list of allowed decoders. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_pixels integer (decoding/encoding,video)
+

Maximum number of pixels per image. This value can be used to avoid out of +memory failures due to large images. +

+
+
apply_cropping bool (decoding,video)
+

Enable cropping if cropping parameters are multiples of the required +alignment for the left and top parameters. If the alignment is not met the +cropping will be partially applied to maintain alignment. +Default is 1 (enabled). +Note: The required alignment depends on if AV_CODEC_FLAG_UNALIGNED is set and the +CPU. AV_CODEC_FLAG_UNALIGNED cannot be changed from the command line. Also hardware +decoders will not apply left/top Cropping. +

+ +
+
+ + + +

9 Decoders

+ +

Decoders are configured elements in FFmpeg which allow the decoding of +multimedia streams. +

+

When you configure your FFmpeg build, all the supported native decoders +are enabled by default. Decoders requiring an external library must be enabled +manually via the corresponding --enable-lib option. You can list all +available decoders using the configure option --list-decoders. +

+

You can disable all the decoders with the configure option +--disable-decoders and selectively enable / disable single decoders +with the options --enable-decoder=DECODER / +--disable-decoder=DECODER. +

+

The option -decoders of the ff* tools will display the list of +enabled decoders. +

+ + +

10 Video Decoders

+ +

A description of some of the currently available video decoders +follows. +

+ +

10.1 av1

+ +

AOMedia Video 1 (AV1) decoder. +

+ +

10.1.1 Options

+ +
+
operating_point
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Default is 0. +

+
+
+ + +

10.2 hevc

+

HEVC (AKA ITU-T H.265 or ISO/IEC 23008-2) decoder. +

+

The decoder supports MV-HEVC multiview streams with at most two views. Views to +be output are selected by supplying a list of view IDs to the decoder (the +view_ids option). This option may be set either statically before +decoder init, or from the get_format() callback - useful for the case +when the view count or IDs change dynamically during decoding. +

+

Only the base layer is decoded by default. +

+

Note that if you are using the ffmpeg CLI tool, you should be using view +specifiers as documented in its manual, rather than the options documented here. +

+ +

10.2.1 Options

+ +
+
view_ids (MV-HEVC)
+

Specify a list of view IDs that should be output. This option can also be set to +a single ’-1’, which will cause all views defined in the VPS to be decoded and +output. +

+
+
view_ids_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view IDs available +in the active VPS. The array is empty for single-layer video. +

+

The value of this option is guaranteed to be accurate when read from the +get_format() callback. It may also be set at other times (e.g. after +opening the decoder), but the value is informational only and may be incorrect +(e.g. when the stream contains multiple distinct VPS NALUs). +

+
+
view_pos_available (MV-HEVC)
+

This option may be read by the caller to retrieve an array of view positions +(left, right, or unspecified) available in the active VPS, as +AVStereo3DView values. When the array is available, its elements apply to +the corresponding elements of view_ids_available, i.e. +view_pos_available[i] contains the position of view with ID +view_ids_available[i]. +

+

Same validity restrictions as for view_ids_available apply to +this option. +

+
+
+ + +

10.3 rawvideo

+ +

Raw video decoder. +

+

This decoder decodes rawvideo streams. +

+ +

10.3.1 Options

+ +
+
top top_field_first
+

Specify the assumed field type of the input video. +

+
-1
+

the video is assumed to be progressive (default) +

+
0
+

bottom-field-first is assumed +

+
1
+

top-field-first is assumed +

+
+ +
+
+ + +

10.4 libdav1d

+ +

dav1d AV1 decoder. +

+

libdav1d allows libavcodec to decode the AOMedia Video 1 (AV1) codec. +Requires the presence of the libdav1d headers and library during configuration. +You need to explicitly configure the build with --enable-libdav1d. +

+ +

10.4.1 Options

+ +

The following options are supported by the libdav1d wrapper. +

+
+
max_frame_delay
+

Set max amount of frames the decoder may buffer internally. The default value is 0 +(autodetect). +

+
+
filmgrain
+

Apply film grain to the decoded video if present in the bitstream. Defaults to the +internal default of the library. +This option is deprecated and will be removed in the future. See the global option +export_side_data to export Film Grain parameters instead of applying it. +

+
+
oppoint
+

Select an operating point of a scalable AV1 bitstream (0 - 31). Defaults to the +internal default of the library. +

+
+
alllayers
+

Output all spatial layers of a scalable AV1 bitstream. The default value is false. +

+
+
+ + +

10.5 libdavs2

+ +

AVS2-P2/IEEE1857.4 video decoder wrapper. +

+

This decoder allows libavcodec to decode AVS2 streams with davs2 library. +

+ + +

10.6 libuavs3d

+ +

AVS3-P2/IEEE1857.10 video decoder. +

+

libuavs3d allows libavcodec to decode AVS3 streams. +Requires the presence of the libuavs3d headers and library during configuration. +You need to explicitly configure the build with --enable-libuavs3d. +

+ +

10.6.1 Options

+ +

The following option is supported by the libuavs3d wrapper. +

+
+
frame_threads
+

Set amount of frame threads to use during decoding. The default value is 0 (autodetect). +

+
+
+ + +

10.7 libxevd

+ +

eXtra-fast Essential Video Decoder (XEVD) MPEG-5 EVC decoder wrapper. +

+

This decoder requires the presence of the libxevd headers and library +during configuration. You need to explicitly configure the build with +--enable-libxevd. +

+

The xevd project website is at https://github.com/mpeg5/xevd. +

+ +

10.7.1 Options

+ +

The following options are supported by the libxevd wrapper. +The xevd-equivalent options or values are listed in parentheses for easy migration. +

+

To get a more accurate and extensive documentation of the libxevd options, +invoke the command xevd_app --help or consult the libxevd documentation. +

+
+
threads (threads)
+

Force to use a specific number of threads +

+
+
+ + +

10.8 QSV Decoders

+ +

The family of Intel QuickSync Video decoders (VC1, MPEG-2, H.264, HEVC, +JPEG/MJPEG, VP8, VP9, AV1, VVC). +

+ +

10.8.1 Common Options

+ +

The following options are supported by all qsv decoders. +

+
+
async_depth
+

Internal parallelization depth, the higher the value the higher the latency. +

+
+
gpu_copy
+

A GPU-accelerated copy between video and system memory +

+
‘default’
+
‘on’
+
‘off’
+
+ +
+
+ + +

10.8.2 HEVC Options

+

Extra options for hevc_qsv. +

+
+
load_plugin
+

A user plugin to load in an internal session +

+
‘none’
+
‘hevc_sw’
+
‘hevc_hw’
+
+ +
+
load_plugins
+

A :-separate list of hexadecimal plugin UIDs to load in an internal session +

+
+
+ + +

10.9 v210

+ +

Uncompressed 4:2:2 10-bit decoder. +

+ +

10.9.1 Options

+ +
+
custom_stride
+

Set the line size of the v210 data in bytes. The default value is 0 +(autodetect). You can use the special -1 value for a strideless v210 as seen in +BOXX files. +

+
+
+ + + +

11 Audio Decoders

+ +

A description of some of the currently available audio decoders +follows. +

+ +

11.1 ac3

+ +

AC-3 audio decoder. +

+

This decoder implements part of ATSC A/52:2010 and ETSI TS 102 366, as well as +the undocumented RealAudio 3 (a.k.a. dnet). +

+ +

11.1.1 AC-3 Decoder Options

+ +
+
-drc_scale value
+

Dynamic Range Scale Factor. The factor to apply to dynamic range values +from the AC-3 stream. This factor is applied exponentially. The default value is 1. +There are 3 notable scale factor ranges: +

+
drc_scale == 0
+

DRC disabled. Produces full range audio. +

+
0 < drc_scale <= 1
+

DRC enabled. Applies a fraction of the stream DRC value. +Audio reproduction is between full range and full compression. +

+
drc_scale > 1
+

DRC enabled. Applies drc_scale asymmetrically. +Loud sounds are fully compressed. Soft sounds are enhanced. +

+
+ +
+
+ + +

11.2 flac

+ +

FLAC audio decoder. +

+

This decoder aims to implement the complete FLAC specification from Xiph. +

+ +

11.2.1 FLAC Decoder options

+ +
+
-use_buggy_lpc
+

The lavc FLAC encoder used to produce buggy streams with high lpc values +(like the default value). This option makes it possible to decode such streams +correctly by using lavc’s old buggy lpc logic for decoding. +

+
+
+ + +

11.3 ffwavesynth

+ +

Internal wave synthesizer. +

+

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. +

+ +

11.4 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 --enable-libcelt. +

+ +

11.5 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 --enable-libgsm. +

+

This decoder supports both the ordinary GSM and the Microsoft variant. +

+ +

11.6 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 +--enable-libilbc. +

+ +

11.6.1 Options

+ +

The following option is supported by the libilbc wrapper. +

+
+
enhance
+
+

Enable the enhancement of the decoded audio when set to 1. The default +value is 0 (disabled). +

+
+
+ + +

11.7 libmpeghdec

+ +

libmpeghdec decoder wrapper. +

+

libmpeghdec allows libmpeghdec to decode the MPEG-H 3D audio codec. +Requires the presence of the libmpeghdec headers and library during +configuration. You need to explicitly configure the build with +--enable-libmpeghdec --enable-nonfree. +

+ +

11.8 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 --enable-libopencore-amrnb. +

+

An FFmpeg native decoder for AMR-NB exists, so users can decode AMR-NB +without this library. +

+ +

11.9 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 --enable-libopencore-amrwb. +

+

An FFmpeg native decoder for AMR-WB exists, so users can decode AMR-WB +without this library. +

+ +

11.10 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 +--enable-libopus. +

+

An FFmpeg native decoder for Opus exists, so users can decode Opus +without this library. +

+ + +

12 Subtitles Decoders

+ + +

12.1 libaribb24

+ +

ARIB STD-B24 caption decoder. +

+

Implements profiles A and C of the ARIB STD-B24 standard. +

+ +

12.1.1 libaribb24 Decoder Options

+ +
+
-aribb24-base-path path
+

Sets the base path for the libaribb24 library. This is utilized for reading of +configuration files (for custom unicode conversions), and for dumping of +non-text symbols as images under that location. +

+

Unset by default. +

+
+
-aribb24-skip-ruby-text boolean
+

Tells the decoder wrapper to skip text blocks that contain half-height ruby +text. +

+

Enabled by default. +

+
+
+ + +

12.2 libaribcaption

+ +

Yet another ARIB STD-B24 caption decoder using external libaribcaption +library. +

+

Implements profiles A and C of the Japanese ARIB STD-B24 standard, +Brazilian ABNT NBR 15606-1, and Philippines version of ISDB-T. +

+

Requires the presence of the libaribcaption headers and library +(https://github.com/xqq/libaribcaption) during configuration. +You need to explicitly configure the build with --enable-libaribcaption. +If both libaribb24 and libaribcaption are enabled, libaribcaption +decoder precedes. +

+ +

12.2.1 libaribcaption Decoder Options

+ +
+
-sub_type subtitle_type
+

Specifies the format of the decoded subtitles. +

+
+
‘bitmap’
+

Graphical image. +

+
‘ass’
+

ASS formatted text. +

+
‘text’
+

Simple text based output without formatting. +

+
+ +

The default is ass as same as libaribb24 decoder. +Some present players (e.g., mpv) expect ASS format for ARIB caption. +

+
+
-caption_encoding encoding_scheme
+

Specifies the encoding scheme of input subtitle text. +

+
+
‘auto’
+

Automatically detect text encoding (default). +

+
‘jis’
+

8bit-char JIS encoding defined in ARIB STD B24. +This encoding used in Japan for ISDB captions. +

+
‘utf8’
+

UTF-8 encoding defined in ARIB STD B24. +This encoding is used in Philippines for ISDB-T captions. +

+
‘latin’
+

Latin character encoding defined in ABNT NBR 15606-1. +This encoding is used in South America for SBTVD / ISDB-Tb captions. +

+
+ +
+
-font font_name[,font_name2,...]
+

Specify comma-separated list of font family names to be used for bitmap +or ass type subtitle rendering. +Only first font name is used for ass type subtitle. +

+

If not specified, use internally defined default font family. +

+
+
-ass_single_rect boolean
+

ARIB STD-B24 specifies that some captions may be displayed at different +positions at a time (multi-rectangle subtitle). +Since some players (e.g., old mpv) can’t handle multiple ASS rectangles +in a single AVSubtitle, or multiple ASS rectangles of indeterminate duration +with the same start timestamp, this option can change the behavior so that +all the texts are displayed in a single ASS rectangle. +

+

The default is false. +

+

If your player cannot handle AVSubtitles with multiple ASS rectangles properly, +set this option to true or define ASS_SINGLE_RECT=1 to change +default behavior at compilation. +

+
+
-force_outline_text boolean
+

Specify whether always render outline text for all characters regardless of +the indication by character style. +

+

The default is false. +

+
+
-outline_width number (0.0 - 3.0)
+

Specify width for outline text, in dots (relative). +

+

The default is 1.5. +

+
+
-ignore_background boolean
+

Specify whether to ignore background color rendering. +

+

The default is false. +

+
+
-ignore_ruby boolean
+

Specify whether to ignore rendering for ruby-like (furigana) characters. +

+

The default is false. +

+
+
-replace_drcs boolean
+

Specify whether to render replaced DRCS characters as Unicode characters. +

+

The default is true. +

+
+
-replace_msz_ascii boolean
+

Specify whether to replace MSZ (Middle Size; half width) fullwidth +alphanumerics with halfwidth alphanumerics. +

+

The default is true. +

+
+
-replace_msz_japanese boolean
+

Specify whether to replace some MSZ (Middle Size; half width) fullwidth +japanese special characters with halfwidth ones. +

+

The default is true. +

+
+
-replace_msz_glyph boolean
+

Specify whether to replace MSZ (Middle Size; half width) characters +with halfwidth glyphs if the fonts supports it. +This option works under FreeType or DirectWrite renderer +with Adobe-Japan1 compliant fonts. +e.g., IBM Plex Sans JP, Morisawa BIZ UDGothic, Morisawa BIZ UDMincho, +Yu Gothic, Yu Mincho, and Meiryo. +

+

The default is true. +

+
+
-canvas_size image_size
+

Specify the resolution of the canvas to render subtitles to; usually, this +should be frame size of input video. +This only applies when -subtitle_type is set to bitmap. +

+

The libaribcaption decoder assumes input frame size for bitmap rendering as below: +

    +
  1. PROFILE_A : 1440 x 1080 with SAR (PAR) 4:3 +
  2. PROFILE_C : 320 x 180 with SAR (PAR) 1:1 +
+ +

If actual frame size of input video does not match above assumption, +the rendered captions may be distorted. +To make the captions undistorted, add -canvas_size option to specify +actual input video size. +

+

Note that the -canvas_size option is not required for video with +different size but same aspect ratio. +In such cases, the caption will be stretched or shrunk to actual video size +if -canvas_size option is not specified. +If -canvas_size option is specified with different size, +the caption will be stretched or shrunk as specified size with calculated SAR. +

+
+
+ + +

12.2.2 libaribcaption decoder usage examples

+ +

Display MPEG-TS file with ARIB subtitle by ffplay tool: +

+
ffplay -sub_type bitmap MPEG.TS
+
+ +

Display MPEG-TS file with input frame size 1920x1080 by ffplay tool: +

+
ffplay -sub_type bitmap -canvas_size 1920x1080 MPEG.TS
+
+ +

Embed ARIB subtitle in transcoded video: +

+
ffmpeg -sub_type bitmap -i src.m2t -filter_complex "[0:v][0:s]overlay" -vcodec h264 dest.mp4
+
+ + +

12.3 dvbsub

+ + +

12.3.1 Options

+ +
+
compute_clut
+
+
-2
+

Compute clut once if no matching CLUT is in the stream. +

+
-1
+

Compute clut if no matching CLUT is in the stream. +

+
0
+

Never compute CLUT +

+
1
+

Always compute CLUT and override the one provided in the stream. +

+
+
+
dvb_substream
+

Selects the dvb substream, or all substreams if -1 which is default. +

+
+
+ + +

12.4 dvdsub

+ +

This codec decodes the bitmap subtitles used in DVDs; the same subtitles can +also be found in VobSub file pairs and in some Matroska files. +

+ +

12.4.1 Options

+ +
+
palette
+

Specify the global palette used by the bitmaps. When stored in VobSub, the +palette is normally specified in the index file; in Matroska, the palette is +stored in the codec extra-data in the same format as in VobSub. In DVDs, the +palette is stored in the IFO file, and therefore not available when reading +from dumped VOB files. +

+

The format for this option is a string containing 16 24-bits hexadecimal +numbers (without 0x prefix) separated by commas, for example 0d00ee, +ee450d, 101010, eaeaea, 0ce60b, ec14ed, ebff0b, 0d617a, 7b7b7b, d1d1d1, +7b2a0e, 0d950c, 0f007b, cf0dec, cfa80c, 7c127b. +

+
+
ifo_palette
+

Specify the IFO file from which the global palette is obtained. +(experimental) +

+
+
forced_subs_only
+

Only decode subtitle entries marked as forced. Some titles have forced +and non-forced subtitles in the same track. Setting this flag to 1 +will only keep the forced subtitles. Default value is 0. +

+
+ + +

12.5 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 +--enable-libzvbi. +

+ +

12.5.1 Options

+ +
+
txt_page
+

List of teletext page numbers to decode. Pages that do not match the specified +list are dropped. You may use the special * string to match all pages, +or subtitle to match all subtitle pages. +Default value is *. +

+
txt_default_region
+

Set default character set used for decoding, a value between 0 and 87 (see +ETS 300 706, Section 15, Table 32). Default value is -1, which does not +override the libzvbi default. This option is needed for some legacy level 1.0 +transmissions which cannot signal the proper charset. +

+
txt_chop_top
+

Discards the top teletext line. Default value is 1. +

+
txt_format
+

Specifies the format of the decoded subtitles. +

+
bitmap
+

The default format, you should use this for teletext pages, because certain +graphics and colors cannot be expressed in simple text or even ASS. +

+
text
+

Simple text based output without formatting. +

+
ass
+

Formatted ASS output, subtitle pages and teletext pages are returned in +different styles, subtitle pages are stripped down to text, but an effort is +made to keep the text alignment and the formatting. +

+
+
+
txt_left
+

X offset of generated bitmaps, default is 0. +

+
txt_top
+

Y offset of generated bitmaps, default is 0. +

+
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 characters. +Default value is 1. +

+
txt_duration
+

Sets the display duration of the decoded teletext pages or subtitles in +milliseconds. Default value is -1 which means infinity or until the next +subtitle event comes. +

+
txt_transparent
+

Force transparent background of the generated teletext bitmaps. Default value +is 0 which means an opaque background. +

+
txt_opacity
+

Sets the opacity (0-255) of the teletext background. If +txt_transparent is not set, it only affects characters between a start +box and an end box, typically subtitles. Default value is 0 if +txt_transparent is set, 255 otherwise. +

+
+
+ + +

13 Bitstream Filters

+ +

When you configure your FFmpeg build, all the supported bitstream +filters are enabled by default. You can list all available ones using +the configure option --list-bsfs. +

+

You can disable all the bitstream filters using the configure option +--disable-bsfs, and selectively enable any bitstream filter using +the option --enable-bsf=BSF, or you can disable a particular +bitstream filter using the option --disable-bsf=BSF. +

+

The option -bsfs of the ff* tools will display the list of +all the supported bitstream filters included in your build. +

+

The ff* tools have a -bsf option applied per stream, taking a +comma-separated list of filters, whose parameters follow the filter +name after a ’=’. +

+
+
ffmpeg -i INPUT -c:v copy -bsf:v filter1[=opt1=str1:opt2=str2][,filter2] OUTPUT
+
+ +

Below is a description of the currently available bitstream filters, +with their parameters, if any. +

+ +

13.1 aac_adtstoasc

+ +

Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration +bitstream. +

+

This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4 +ADTS header and removes the ADTS header. +

+

This filter is required for example when copying an AAC stream from a +raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or +to MOV/MP4 files and related formats such as 3GP or M4A. Please note +that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats. +

+ +

13.2 av1_metadata

+ +

Modify metadata embedded in an AV1 stream. +

+
+
td
+

Insert or remove temporal delimiter OBUs in all temporal units of the +stream. +

+
+
‘insert’
+

Insert a TD at the beginning of every TU which does not already have one. +

+
‘remove’
+

Remove the TD from the beginning of every TU which has one. +

+
+ +
+
color_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the color description fields in the stream (see AV1 section 6.4.2). +

+
+
color_range
+

Set the color range in the stream (see AV1 section 6.4.2; note that +this cannot be set for streams using BT.709 primaries, sRGB transfer +characteristic and identity (RGB) matrix coefficients). +

+
‘tv’
+

Limited range. +

+
‘pc’
+

Full range. +

+
+ +
+
chroma_sample_position
+

Set the chroma sample location in the stream (see AV1 section 6.4.2). +This can only be set for 4:2:0 streams. +

+
+
‘vertical’
+

Left position (matching the default in MPEG-2 and H.264). +

+
‘colocated’
+

Top-left position. +

+
+ +
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_display_tick) in +the timing info in the sequence header. +

+
num_ticks_per_picture
+

Set the number of ticks in each picture, to indicate that the stream +has a fixed framerate. Ignored if tick_rate is not also set. +

+
+
delete_padding
+

Deletes Padding OBUs. +

+
+
+ + +

13.3 chomp

+ +

Remove zero padding at the end of a packet. +

+ +

13.4 dca_core

+ +

Extract the core from a DCA/DTS stream, dropping extensions such as +DTS-HD. +

+ +

13.5 dovi_rpu

+ +

Manipulate Dolby Vision metadata in a HEVC/AV1 bitstream, optionally enabling +metadata compression. +

+
+
strip
+

If enabled, strip all Dolby Vision metadata (configuration record + RPU data +blocks) from the stream. +

+
compression
+

Which compression level to enable. +

+
‘none’
+

No metadata compression. +

+
‘limited’
+

Limited metadata compression scheme. Should be compatible with most devices. +This is the default. +

+
‘extended’
+

Extended metadata compression. Devices are not required to support this. Note +that this level currently behaves the same as ‘limited’ in libavcodec. +

+
+
+
+ + +

13.6 dump_extra

+ +

Add extradata to the beginning of the filtered packets except when +said packets already exactly begin with the extradata that is intended +to be added. +

+
+
freq
+

The additional argument specifies which packets should be filtered. +It accepts the values: +

+
‘k’
+
‘keyframe’
+

add extradata to all key packets +

+
+
‘e’
+
‘all’
+

add extradata to all packets +

+
+
+
+ +

If not specified it is assumed ‘k’. +

+

For example the following ffmpeg command forces a global +header (thus disabling individual packet headers) in the H.264 packets +generated by the libx264 encoder, but corrects them by adding +the header stored in extradata to the key packets: +

+
ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts
+
+ + +

13.7 dv_error_marker

+ +

Blocks in DV which are marked as damaged are replaced by blocks of the specified color. +

+
+
color
+

The color to replace damaged blocks by +

+
sta
+

A 16 bit mask which specifies which of the 16 possible error status values are +to be replaced by colored blocks. 0xFFFE is the default which replaces all non 0 +error status values. +

+
‘ok’
+

No error, no concealment +

+
‘err’
+

Error, No concealment +

+
‘res’
+

Reserved +

+
‘notok’
+

Error or concealment +

+
‘notres’
+

Not reserved +

+
‘Aa, Ba, Ca, Ab, Bb, Cb, A, B, C, a, b, erri, erru’
+

The specific error status code +

+
+

see page 44-46 or section 5.5 of +http://web.archive.org/web/20060927044735/http://www.smpte.org/smpte_store/standards/pdf/s314m.pdf +

+
+
+ + +

13.8 eac3_core

+ +

Extract the core from a E-AC-3 stream, dropping extra channels. +

+ +

13.9 eia608_to_smpte436m

+ +

Convert from a EIA_608 stream to a SMPTE_436M_ANC data stream, wrapping the closed captions in CTA-708 CDP VANC packets. +

+
+
line_number
+

Choose which line number the generated VANC packets should go on. You generally want either line 9 (the default) or 11. +

+
wrapping_type
+

Choose the SMPTE 436M wrapping type, defaults to ‘vanc_frame’. +It accepts the values: +

+
‘vanc_frame’
+

VANC frame (interlaced or segmented progressive frame) +

+
‘vanc_field_1’
+
‘vanc_field_2’
+
‘vanc_progressive_frame’
+
+
+
sample_coding
+

Choose the SMPTE 436M sample coding, defaults to ‘8bit_luma’. +It accepts the values: +

+
‘8bit_luma’
+

8-bit component luma samples +

+
‘8bit_color_diff’
+

8-bit component color difference samples +

+
‘8bit_luma_and_color_diff’
+

8-bit component luma and color difference samples +

+
‘10bit_luma’
+

10-bit component luma samples +

+
‘10bit_color_diff’
+

10-bit component color difference samples +

+
‘10bit_luma_and_color_diff’
+

10-bit component luma and color difference samples +

+
‘8bit_luma_parity_error’
+

8-bit component luma samples with parity error +

+
‘8bit_color_diff_parity_error’
+

8-bit component color difference samples with parity error +

+
‘8bit_luma_and_color_diff_parity_error’
+

8-bit component luma and color difference samples with parity error +

+
+
+
initial_cdp_sequence_cntr
+

The initial value of the CDP’s 16-bit unsigned integer cdp_hdr_sequence_cntr and cdp_ftr_sequence_cntr fields. Defaults to 0. +

+
cdp_frame_rate
+

Set the CDP’s cdp_frame_rate field. This doesn’t actually change the timing of the data stream, it just changes the values inserted in that field in the generated CDP packets. Defaults to ‘30000/1001’. +

+
+ + +

13.10 extract_extradata

+ +

Extract the in-band extradata. +

+

Certain codecs allow the long-term headers (e.g. MPEG-2 sequence headers, +or H.264/HEVC (VPS/)SPS/PPS) to be transmitted either "in-band" (i.e. as a part +of the bitstream containing the coded frames) or "out of band" (e.g. on the +container level). This latter form is called "extradata" in FFmpeg terminology. +

+

This bitstream filter detects the in-band headers and makes them available as +extradata. +

+
+
remove
+

When this option is enabled, the long-term headers are removed from the +bitstream after extraction. +

+
+ + +

13.11 filter_units

+ +

Remove units with types in or not in a given set from the stream. +

+
+
pass_types
+

List of unit types or ranges of unit types to pass through while removing +all others. This is specified as a ’|’-separated list of unit type values +or ranges of values with ’-’. +

+
+
remove_types
+

Identical to pass_types, except the units in the given set +removed and all others passed through. +

+
+ +

The types used by pass_types and remove_types correspond to NAL unit types +(nal_unit_type) in H.264, HEVC and H.266 (see Table 7-1 in the H.264 +and HEVC specifications or Table 5 in the H.266 specification), to +marker values for JPEG (without 0xFF prefix) and to start codes without +start code prefix (i.e. the byte following the 0x000001) for MPEG-2. +For VP8 and VP9, every unit has type zero. +

+

Extradata is unchanged by this transformation, but note that if the stream +contains inline parameter sets then the output may be unusable if they are +removed. +

+

For example, to remove all non-VCL NAL units from an H.264 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=pass_types=1-5' OUTPUT
+
+ +

To remove all AUDs, SEI and filler from an H.265 stream: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=35|38-40' OUTPUT
+
+ +

To remove all user data from a MPEG-2 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=178' OUTPUT
+
+ +

To remove all SEI from a H264 stream, including Closed Captions: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=6' OUTPUT
+
+ +

To remove all prefix and suffix SEI from a HEVC stream, including Closed Captions and dynamic HDR: +

+
ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=39|40' OUTPUT
+
+ + +

13.12 hapqa_extract

+ +

Extract Rgb or Alpha part of an HAPQA file, without recompression, in order to create an HAPQ or an HAPAlphaOnly file. +

+
+
texture
+

Specifies the texture to keep. +

+
+
color
+
alpha
+
+ +
+
+ +

Convert HAPQA to HAPQ +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=color -tag:v HapY -metadata:s:v:0 encoder="HAPQ" hapq_file.mov
+
+ +

Convert HAPQA to HAPAlphaOnly +

+
ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=alpha -tag:v HapA -metadata:s:v:0 encoder="HAPAlpha Only" hapalphaonly_file.mov
+
+ + +

13.13 h264_metadata

+ +

Modify metadata embedded in an H.264 stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
+ +

Default is pass. +

+
+
sample_aspect_ratio
+

Set the sample aspect ratio of the stream in the VUI parameters. +See H.264 table E-1. +

+
+
overscan_appropriate_flag
+

Set whether the stream is suitable for display using overscan +or not (see H.264 section E.2.1). +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.264 section E.2.1 and +table E-2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.264 section E.2.1 +and tables E-3, E-4 and E-5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.264 section +E.2.1 and figure E-1). +

+
+
tick_rate
+

Set the tick rate (time_scale / num_units_in_tick) in the VUI +parameters. This is the smallest time unit representable in the +stream, and in many cases represents the field rate of the stream +(double the frame rate). +

+
fixed_frame_rate_flag
+

Set whether the stream has fixed framerate - typically this indicates +that the framerate is exactly half the tick rate, but the exact +meaning is dependent on interlacing and the picture structure (see +H.264 section E.2.1 and table E-6). +

+
zero_new_constraint_set_flags
+

Zero constraint_set4_flag and constraint_set5_flag in the SPS. These +bits were reserved in a previous version of the H.264 spec, and thus +some hardware decoders require these to be zero. The result of zeroing +this is still a valid bitstream. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the frame cropping offsets in the SPS. These values will replace +the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled or the stream is interlaced +(see H.264 section 7.4.2.1.1). +

+
+
sei_user_data
+

Insert a string as SEI unregistered user data. The argument must +be of the form UUID+string, where the UUID is as hex digits +possibly separated by hyphens, and the string can be anything. +

+

For example, ‘086f3693-b7b3-4f2c-9653-21492feee5b8+hello’ will +insert the string “hello” associated with the given UUID. +

+
+
delete_filler
+

Deletes both filler NAL units and filler SEI messages. +

+
+
display_orientation
+

Insert, extract or remove Display orientation SEI messages. +See H.264 section D.1.27 and D.2.27 for syntax and semantics. +

+
+
‘pass’
+
‘insert’
+
‘remove’
+
‘extract’
+
+ +

Default is pass. +

+

Insert mode works in conjunction with rotate and flip options. +Any pre-existing Display orientation messages will be removed in insert or remove mode. +Extract mode attaches the display matrix to the packet as side data. +

+
+
rotate
+

Set rotation in display orientation SEI (anticlockwise angle in degrees). +Range is -360 to +360. Default is NaN. +

+
+
flip
+

Set flip in display orientation SEI. +

+
+
‘horizontal’
+
‘vertical’
+
+ +

Default is unset. +

+
+
level
+

Set the level in the SPS. Refer to H.264 section A.3 and tables A-1 +to A-5. +

+

The argument must be the name of a level (for example, ‘4.2’), a +level_idc value (for example, ‘42’), or the special name ‘auto’ +indicating that the filter should attempt to guess the level from the +input stream properties. +

+
+
+ + +

13.14 h264_mp4toannexb

+ +

Convert an H.264 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.264 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an H.264 stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw H.264 (muxer h264) output formats. +

+ +

13.15 h264_redundant_pps

+ +

This applies a specific fixup to some Blu-ray BDMV H264 streams +which contain redundant PPSs. The PPSs modify irrelevant parameters +of the stream, confusing other transformations which require +the correct extradata. +

+

The encoder used on these impacted streams adds extra PPSs throughout +the stream, varying the initial QP and whether weighted prediction +was enabled. This causes issues after copying the stream into +a global header container, as the starting PPS is not suitable +for the rest of the stream. One side effect, for example, +is seeking will return garbled output until a new PPS appears. +

+

This BSF removes the extra PPSs and rewrites the slice headers +such that the stream uses a single leading PPS in the global header, +which resolves the issue. +

+ +

13.16 hevc_metadata

+ +

Modify metadata embedded in an HEVC stream. +

+
+
aud
+

Insert or remove AUD NAL units in all access units of the stream. +

+
+
‘insert’
+
‘remove’
+
+ +
+
sample_aspect_ratio
+

Set the sample aspect ratio in the stream in the VUI parameters. +

+
+
video_format
+
video_full_range_flag
+

Set the video format in the stream (see H.265 section E.3.1 and +table E.2). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.265 section E.3.1 +and tables E.3, E.4 and E.5). +

+
+
chroma_sample_loc_type
+

Set the chroma sample location in the stream (see H.265 section +E.3.1 and figure E.1). +

+
+
tick_rate
+

Set the tick rate in the VPS and VUI parameters (time_scale / +num_units_in_tick). Combined with num_ticks_poc_diff_one, this can +set a constant framerate in the stream. Note that it is likely to be +overridden by container parameters when the stream is in a container. +

+
+
num_ticks_poc_diff_one
+

Set poc_proportional_to_timing_flag in VPS and VUI and use this value +to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and +E.3.1). Ignored if tick_rate is not also set. +

+
+
crop_left
+
crop_right
+
crop_top
+
crop_bottom
+

Set the conformance window cropping offsets in the SPS. These values +will replace the current ones if the stream is already cropped. +

+

These fields are set in pixels. Note that some sizes may not be +representable if the chroma is subsampled (H.265 section 7.4.3.2.1). +

+
+
width
+
height
+

Set width and height after crop. +

+
+
level
+

Set the level in the VPS and SPS. See H.265 section A.4 and tables +A.6 and A.7. +

+

The argument must be the name of a level (for example, ‘5.1’), a +general_level_idc value (for example, ‘153’ for level 5.1), +or the special name ‘auto’ indicating that the filter should +attempt to guess the level from the input stream properties. +

+
+
+ + +

13.17 hevc_mp4toannexb

+ +

Convert an HEVC/H.265 bitstream from length prefixed mode to start code +prefixed mode (as defined in the Annex B of the ITU-T H.265 +specification). +

+

This is required by some streaming formats, typically the MPEG-2 +transport stream format (muxer mpegts). +

+

For example to remux an MP4 file containing an HEVC stream to mpegts +format with ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
+
+ +

Please note that this filter is auto-inserted for MPEG-TS (muxer +mpegts) and raw HEVC/H.265 (muxer h265 or +hevc) output formats. +

+ +

13.18 imxdump

+ +

Modifies the bitstream to fit in MOV and to be usable by the Final Cut +Pro decoder. This filter only applies to the mpeg2video codec, and is +likely not needed for Final Cut Pro 7 and newer with the appropriate +-tag:v. +

+

For example, to remux 30 MB/sec NTSC IMX to MOV: +

+
+
ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov
+
+ + +

13.19 mjpeg2jpeg

+ +

Convert MJPEG/AVI1 packets to full JPEG/JFIF packets. +

+

MJPEG is a video codec wherein each video frame is essentially a +JPEG image. The individual frames can be extracted without loss, +e.g. by +

+
+
ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg
+
+ +

Unfortunately, these chunks are incomplete JPEG images, because +they lack the DHT segment required for decoding. Quoting from +http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml: +

+

Avery Lee, writing in the rec.video.desktop newsgroup in 2001, +commented that "MJPEG, or at least the MJPEG in AVIs having the +MJPG fourcc, is restricted JPEG with a fixed – and *omitted* – +Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2, +and it must use basic Huffman encoding, not arithmetic or +progressive. . . . You can indeed extract the MJPEG frames and +decode them with a regular JPEG decoder, but you have to prepend +the DHT segment to them, or else the decoder won’t have any idea +how to decompress the data. The exact table necessary is given in +the OpenDML spec." +

+

This bitstream filter patches the header of frames extracted from an MJPEG +stream (carrying the AVI1 header ID and lacking a DHT segment) to +produce fully qualified JPEG images. +

+
+
ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg
+exiftran -i -9 frame*.jpg
+ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
+
+ + +

13.20 mjpegadump

+ +

Add an MJPEG A header to the bitstream, to enable decoding by +Quicktime. +

+ +

13.21 mov2textsub

+ +

Extract a representable text file from MOV subtitles, stripping the +metadata header from each subtitle packet. +

+

See also the text2movsub filter. +

+ +

13.22 mpeg2_metadata

+ +

Modify metadata embedded in an MPEG-2 stream. +

+
+
display_aspect_ratio
+

Set the display aspect ratio in the stream. +

+

The following fixed values are supported: +

+
4/3
+
16/9
+
221/100
+
+

Any other value will result in square pixels being signalled instead +(see H.262 section 6.3.3 and table 6-3). +

+
+
frame_rate
+

Set the frame rate in the stream. This is constructed from a table +of known values combined with a small multiplier and divisor - if +the supplied value is not exactly representable, the nearest +representable value will be used instead (see H.262 section 6.3.3 +and table 6-4). +

+
+
video_format
+

Set the video format in the stream (see H.262 section 6.3.6 and +table 6-6). +

+
+
colour_primaries
+
transfer_characteristics
+
matrix_coefficients
+

Set the colour description in the stream (see H.262 section 6.3.6 +and tables 6-7, 6-8 and 6-9). +

+
+
+ + +

13.23 mpeg4_unpack_bframes

+ +

Unpack DivX-style packed B-frames. +

+

DivX-style packed B-frames are not valid MPEG-4 and were only a +workaround for the broken Video for Windows subsystem. +They use more space, can cause minor AV sync issues, require more +CPU power to decode (unless the player has some decoded picture queue +to compensate the 2,0,2,0 frame per packet style) and cause +trouble if copied into a standard container like mp4 or mpeg-ps/ts, +because MPEG-4 decoders may not be able to decode them, since they are +not valid MPEG-4. +

+

For example to fix an AVI file containing an MPEG-4 stream with +DivX-style packed B-frames using ffmpeg, you can use the command: +

+
+
ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi
+
+ + +

13.24 noise

+ +

Damages the contents of packets or simply drops them without damaging the +container. Can be used for fuzzing or testing error resilience/concealment. +

+

Parameters: +

+
amount
+

Accepts an expression whose evaluation per-packet determines how often bytes in that +packet will be modified. A value below 0 will result in a variable frequency. +Default is 0 which results in no modification. However, if neither amount nor drop is specified, +amount will be set to -1. See below for accepted variables. +

+
drop
+

Accepts an expression evaluated per-packet whose value determines whether that packet is dropped. +Evaluation to a positive value results in the packet being dropped. Evaluation to a negative +value results in a variable chance of it being dropped, roughly inverse in proportion to the magnitude +of the value. Default is 0 which results in no drops. See below for accepted variables. +

+
dropamount
+

Accepts a non-negative integer, which assigns a variable chance of it being dropped, roughly inverse +in proportion to the value. Default is 0 which results in no drops. This option is kept for backwards +compatibility and is equivalent to setting drop to a negative value with the same magnitude +i.e. dropamount=4 is the same as drop=-4. Ignored if drop is also specified. +

+
+ +

Both amount and drop accept expressions containing the following variables: +

+
+
‘n’
+

The index of the packet, starting from zero. +

+
‘tb’
+

The timebase for packet timestamps. +

+
‘pts’
+

Packet presentation timestamp. +

+
‘dts’
+

Packet decoding timestamp. +

+
‘nopts’
+

Constant representing AV_NOPTS_VALUE. +

+
‘startpts’
+

First non-AV_NOPTS_VALUE PTS seen in the stream. +

+
‘startdts’
+

First non-AV_NOPTS_VALUE DTS seen in the stream. +

+
‘duration’
+
‘d’
+

Packet duration, in timebase units. +

+
‘pos’
+

Packet position in input; may be -1 when unknown or not set. +

+
‘size’
+

Packet size, in bytes. +

+
‘key’
+

Whether packet is marked as a keyframe. +

+
‘state’
+

A pseudo random integer, primarily derived from the content of packet payload. +

+
+ + +

13.24.1 Examples

+

Apply modification to every byte but don’t drop any packets. +

+
ffmpeg -i INPUT -c copy -bsf noise=1 output.mkv
+
+ +

Drop every video packet not marked as a keyframe after timestamp 30s but do not +modify any of the remaining packets. +

+
ffmpeg -i INPUT -c copy -bsf:v noise=drop='gt(pts*tb\,30)*not(key)' output.mkv
+
+ +

Drop one second of audio every 10 seconds and add some random noise to the rest. +

+
ffmpeg -i INPUT -c copy -bsf:a noise=amount=-1:drop='between(mod(pts*tb\,10)\,9\,10)' output.mkv
+
+ + +

13.25 null

+

This bitstream filter passes the packets through unchanged. +

+ +

13.26 pcm_rechunk

+ +

Repacketize PCM audio to a fixed number of samples per packet or a fixed packet +rate per second. This is similar to the asetnsamples audio +filter but works on audio packets instead of audio frames. +

+
+
nb_out_samples, n
+

Set the number of samples per each output audio packet. The number is intended +as the number of samples per each channel. Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio packet with silence, so that it +will contain the same number of samples (or roughly the same number of samples, +see frame_rate) as the previous ones. Default value is 1. +

+
+
frame_rate, r
+

This option makes the filter output a fixed number of packets per second instead +of a fixed number of samples per packet. If the audio sample rate is not +divisible by the frame rate then the number of samples will not be constant but +will vary slightly so that each packet will start as close to the frame +boundary as possible. Using this option has precedence over nb_out_samples. +

+
+ +

You can generate the well known 1602-1601-1602-1601-1602 pattern of 48kHz audio +for NTSC frame rate using the frame_rate option. +

+
ffmpeg -f lavfi -i sine=r=48000:d=1 -c pcm_s16le -bsf pcm_rechunk=r=30000/1001 -f framecrc -
+
+ + +

13.27 pgs_frame_merge

+ +

Merge a sequence of PGS Subtitle segments ending with an "end of display set" +segment into a single packet. +

+

This is required by some containers that support PGS subtitles +(muxer matroska). +

+ +

13.28 prores_metadata

+ +

Modify color property metadata embedded in prores stream. +

+
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘bt470bg’
+

BT601 625 +

+
+
‘smpte170m’
+

BT601 525 +

+
+
‘bt2020’
+
‘smpte431’
+

DCI P3 +

+
+
‘smpte432’
+

P3 D65 +

+
+
+ +
+
transfer_characteristics
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same transfer characteristics property (default). +

+
+
‘unknown’
+
‘bt709’
+

BT 601, BT 709, BT 2020 +

+
‘smpte2084’
+

SMPTE ST 2084 +

+
‘arib-std-b67’
+

ARIB STD-B67 +

+
+ + +
+
matrix_coefficients
+

Set the matrix coefficient. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘unknown’
+
‘bt709’
+
‘smpte170m’
+

BT 601 +

+
+
‘bt2020nc’
+
+
+
+ +

Set Rec709 colorspace for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt709:color_trc=bt709:colorspace=bt709 output.mov
+
+ +

Set Hybrid Log-Gamma parameters for each frame of the file +

+
ffmpeg -i INPUT -c copy -bsf:v prores_metadata=color_primaries=bt2020:color_trc=arib-std-b67:colorspace=bt2020nc output.mov
+
+ + +

13.29 remove_extra

+ +

Remove extradata from packets. +

+

It accepts the following parameter: +

+
freq
+

Set which frame types to remove extradata from. +

+
+
‘k’
+

Remove extradata from non-keyframes only. +

+
+
‘keyframe’
+

Remove extradata from keyframes only. +

+
+
‘e, all’
+

Remove extradata from all frames. +

+
+
+
+
+ + +

13.30 setts

+

Set PTS and DTS in packets. +

+

It accepts the following parameters: +

+
ts
+
pts
+
dts
+

Set expressions for PTS, DTS or both. +

+
duration
+

Set expression for duration. +

+
time_base
+

Set output time base. +

+
prescale
+

Set whether to convert time fields to user-set output time base before evaluation of expressions. Defaults to 0. +

+
+ +

The expressions are evaluated through the eval API and can contain the following +constants: +

+
+
N
+

The count of the input packet. Starting from 0. +

+
+
TS
+

The demux timestamp in input in case of ts or dts option or presentation +timestamp in case of pts option. +

+
+
POS
+

The original position in the file of the packet, or undefined if undefined +for the current packet +

+
+
DTS
+

The demux timestamp in input. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
DURATION
+

The duration in input. +

+
+
STARTDTS
+

The DTS of the first packet. +

+
+
STARTPTS
+

The PTS of the first packet. +

+
+
PREV_INDTS
+

The previous input DTS. +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INDURATION
+

The previous input duration. +

+
+
PREV_OUTDTS
+

The previous output DTS. +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTDURATION
+

The previous output duration. +

+
+
NEXT_DTS
+

The next input DTS. +

+
+
NEXT_PTS
+

The next input PTS. +

+
+
NEXT_DURATION
+

The next input duration. +

+
+
TB
+

The timebase in which time fields are denominated. The user-set output timebase if prescale is enabled, else the input timebase. +

+
+
TB_OUT
+

The output timebase. +

+
+
SR
+

The sample rate of stream packet belongs. +

+
+
NOPTS
+

The AV_NOPTS_VALUE constant. +

+
+ +

For example, to set PTS equal to DTS (not recommended if B-frames are involved): +

+
ffmpeg -i INPUT -c:a copy -bsf:a setts=pts=DTS out.mkv
+
+ + +

13.31 showinfo

+

Log basic packet information. Mainly useful for testing, debugging, +and development. +

+ +

13.32 smpte436m_to_eia608

+ +

Convert from a SMPTE_436M_ANC data stream to a EIA_608 stream, +extracting the closed captions from CTA-708 CDP VANC packets, and ignoring all other data. +

+ +

13.33 text2movsub

+ +

Convert text subtitles to MOV subtitles (as used by the mov_text +codec) with metadata headers. +

+

See also the mov2textsub filter. +

+ +

13.34 trace_headers

+ +

Log trace output containing all syntax elements in the coded stream +headers (everything above the level of individual coded blocks). +This can be useful for debugging low-level stream issues. +

+

Supports AV1, H.264, H.265, (M)JPEG, MPEG-2 and VP9, but depending +on the build only a subset of these may be available. +

+ +

13.35 truehd_core

+ +

Extract the core from a TrueHD stream, dropping ATMOS data. +

+ +

13.36 vp9_metadata

+ +

Modify metadata embedded in a VP9 stream. +

+
+
color_space
+

Set the color space value in the frame header. Note that any frame +set to RGB will be implicitly set to PC range and that RGB is +incompatible with profiles 0 and 2. +

+
‘unknown’
+
‘bt601’
+
‘bt709’
+
‘smpte170’
+
‘smpte240’
+
‘bt2020’
+
‘rgb’
+
+ +
+
color_range
+

Set the color range value in the frame header. Note that any value +imposed by the color space will take precedence over this value. +

+
‘tv’
+
‘pc’
+
+
+
+ + +

13.37 vp9_superframe

+ +

Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This +fixes merging of split/segmented VP9 streams where the alt-ref frame +was split from its visible counterpart. +

+ +

13.38 vp9_superframe_split

+ +

Split VP9 superframes into single frames. +

+ +

13.39 vp9_raw_reorder

+ +

Given a VP9 stream with correct timestamps but possibly out of order, +insert additional show-existing-frame packets to correct the ordering. +

+ +

14 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
avioflags flags (input/output)
+

Possible values: +

+
‘direct’
+

Reduce buffering. +

+
+ +
+
probesize integer (input)
+

Set probing size in bytes, i.e. the size of the data to analyze to get +stream information. A higher value will enable detecting 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. +

+
+
max_probe_packets integer (input)
+

Set the maximum number of buffered packets when probing a codec. +Default is 2500 packets. +

+
+
packetsize integer (output)
+

Set packet size. +

+
+
fflags flags
+

Set format flags. Some are implemented for a limited number of formats. +

+

Possible values for input files: +

+
‘discardcorrupt’
+

Discard corrupted packets. +

+
‘fastseek’
+

Enable fast, but inaccurate seeks for some formats. +

+
‘genpts’
+

Generate missing PTS if DTS is present. +

+
‘igndts’
+

Ignore DTS if PTS is also set. In case the PTS is set, the DTS value +is set to NOPTS. This is ignored when the nofillin flag is set. +

+
‘ignidx’
+

Ignore index. +

+
‘nobuffer’
+

Reduce the latency introduced by buffering during initial input streams analysis. +

+
‘nofillin’
+

Do not fill in missing values in packet fields that can be exactly calculated. +

+
‘noparse’
+

Disable AVParsers, this needs +nofillin too. +

+
‘sortdts’
+

Try to interleave output packets by DTS. At present, available only for AVIs with an index. +

+
+ +

Possible values for output files: +

+
‘autobsf’
+

Automatically apply bitstream filters as required by the output format. Enabled by default. +

+
‘bitexact’
+

Only write platform-, build- and time-independent data. +This ensures that file and data checksums are reproducible and match between +platforms. Its primary use is for regression testing. +

+
‘flush_packets’
+

Write out packets immediately. +

+
‘shortest’
+

Stop muxing at the end of the shortest stream. +It may be needed to increase max_interleave_delta to avoid flushing the longer +streams before EOF. +

+
+ +
+
seek2any integer (input)
+

Allow seeking to non-keyframes on demuxer level when supported if set to 1. +Default is 0. +

+
+
analyzeduration integer (input)
+

Specify how many microseconds are analyzed to probe the input. A +higher value will enable detecting more accurate information, but will +increase latency. It defaults to 5,000,000 microseconds = 5 seconds. +

+
+
cryptokey hexadecimal string (input)
+

Set decryption key. +

+
+
indexmem integer (input)
+

Set max memory used for timestamp index (per stream). +

+
+
rtbufsize integer (input)
+

Set max memory used for buffering real-time frames. +

+
+
fdebug flags (input/output)
+

Print specific debug info. +

+

Possible values: +

+
‘ts’
+
+ +
+
max_delay integer (input/output)
+

Set maximum muxing or demuxing delay in microseconds. +

+
+
fpsprobesize integer (input)
+

Set number of frames used to probe fps. +

+
+
audio_preload integer (output)
+

Set microseconds by which audio packets should be interleaved earlier. +

+
+
chunk_duration integer (output)
+

Set microseconds for each chunk. +

+
+
chunk_size integer (output)
+

Set size in bytes for each chunk. +

+
+
err_detect, f_err_detect flags (input)
+

Set error detection flags. f_err_detect is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘crccheck’
+

Verify embedded CRCs. +

+
‘bitstream’
+

Detect bitstream specification deviations. +

+
‘buffer’
+

Detect improper bitstream length. +

+
‘explode’
+

Abort decoding on minor error detection. +

+
‘careful’
+

Consider things that violate the spec and have not been seen in the +wild as errors. +

+
‘compliant’
+

Consider all spec non compliancies as errors. +

+
‘aggressive’
+

Consider things that a sane encoder should not do as an error. +

+
+ +
+
max_interleave_delta integer (output)
+

Set maximum buffering duration for interleaving. The duration is +expressed in microseconds, and defaults to 10000000 (10 seconds). +

+

To ensure all the streams are interleaved correctly, libavformat will +wait until it has at least one packet for each stream before actually +writing any packets to the output file. When some streams are +"sparse" (i.e. there are large gaps between successive packets), this +can result in excessive buffering. +

+

This field specifies the maximum difference between the timestamps of the +first and the last packet in the muxing queue, above which libavformat +will output a packet regardless of whether it has queued a packet for all +the streams. +

+

If set to 0, libavformat will continue buffering packets until it has +a packet for each stream, regardless of the maximum timestamp +difference between the buffered packets. +

+
+
use_wallclock_as_timestamps integer (input)
+

Use wallclock as timestamps if set to 1. Default is 0. +

+
+
avoid_negative_ts integer (output)
+
+

Possible values: +

+
‘make_non_negative’
+

Shift timestamps to make them non-negative. +Also note that this affects only leading negative timestamps, and not +non-monotonic negative timestamps. +

+
‘make_zero’
+

Shift timestamps so that the first timestamp is 0. +

+
‘auto (default)’
+

Enables shifting when required by the target format. +

+
‘disabled’
+

Disables shifting of timestamp. +

+
+ +

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. +

+
+
skip_initial_bytes integer (input)
+

Set number of bytes to skip before reading header and frames if set to 1. +Default is 0. +

+
+
correct_ts_overflow integer (input)
+

Correct single timestamp overflows if set to 1. Default is 1. +

+
+
flush_packets integer (output)
+

Flush the underlying I/O stream after each packet. Default is -1 (auto), which +means that the underlying protocol will decide, 1 enables it, and has the +effect of reducing the latency, 0 disables it and may increase IO throughput in +some cases. +

+
+
output_ts_offset offset (output)
+

Set the output time offset. +

+

offset must be a time duration specification, +see the Time duration section in the ffmpeg-utils(1) manual. +

+

The offset is added by the muxer to the output timestamps. +

+

Specifying a positive offset means that the corresponding streams are +delayed bt the time duration specified in offset. Default value +is 0 (meaning that no offset is applied). +

+
+
format_whitelist list (input)
+

"," separated list of allowed demuxers. By default all are allowed. +

+
+
dump_separator string (input)
+

Separator used to separate the fields printed on the command line about the +Stream parameters. +For example, to separate the fields with newlines and indentation: +

+
ffprobe -dump_separator "
+                          "  -i ~/videos/matrixbench_mpeg2.mpg
+
+ +
+
max_streams integer (input)
+

Specifies the maximum number of streams. This can be used to reject files that +would require too many resources due to a large number of streams. +

+
+
skip_estimate_duration_from_pts bool (input)
+

Skip estimation of input duration if it requires an additional probing for PTS at end of file. +At present, applicable for MPEG-PS and MPEG-TS. +

+
+
duration_probesize integer (input)
+

Set probing size, in bytes, for input duration estimation when it actually requires +an additional probing for PTS at end of file (at present: MPEG-PS and MPEG-TS). +It is aimed at users interested in better durations probing for itself, or indirectly +because using the concat demuxer, for example. +The typical use case is an MPEG-TS CBR with a high bitrate, high video buffering and +ending cleaning with similar PTS for video and audio: in such a scenario, the large +physical gap between the last video packet and the last audio packet makes it necessary +to read many bytes in order to get the video stream duration. +Another use case is where the default probing behaviour only reaches a single video frame which is +not the last one of the stream due to frame reordering, so the duration is not accurate. +Setting this option has a performance impact even for small files because the probing +size is fixed. +Default behaviour is a general purpose trade-off, largely adaptive, but the probing size +will not be extended to get streams durations at all costs. +Must be an integer not lesser than 1, or 0 for default behaviour. +

+
+
strict, f_strict integer (input/output)
+

Specify how strictly to follow the standards. f_strict is deprecated and +should be used only via the ffmpeg tool. +

+

Possible values: +

+
‘very’
+

strictly conform to an older more strict version of the spec or reference software +

+
‘strict’
+

strictly conform to all the things in the spec no matter what consequences +

+
‘normal’
+
‘unofficial’
+

allow unofficial extensions +

+
‘experimental’
+

allow non standardized experimental things, experimental +(unfinished/work in progress/not well tested) decoders and encoders. +Note: experimental decoders can pose a security risk, do not use this for +decoding untrusted input. +

+
+ +
+
+ + + +

14.1 Format stream specifiers

+ +

Format stream specifiers allow selection of one or more streams that +match specific properties. +

+

The exact semantics of stream specifiers is defined by the +avformat_match_stream_specifier() function declared in the +libavformat/avformat.h header and documented in the +Stream specifiers section in the ffmpeg(1) manual. +

+ +

15 Demuxers

+ +

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 +are enabled by default. You can list all available ones using the +configure option --list-demuxers. +

+

You can disable all the demuxers using the configure option +--disable-demuxers, and selectively enable a single demuxer with +the option --enable-demuxer=DEMUXER, or disable it +with the option --disable-demuxer=DEMUXER. +

+

The option -demuxers of the ff* tools will display the list of +enabled demuxers. Use -formats to view a combined list of +enabled demuxers and muxers. +

+

The description of some of the currently available demuxers follows. +

+ +

15.1 aa

+ +

Audible Format 2, 3, and 4 demuxer. +

+

This demuxer is used to demux Audible Format 2, 3, and 4 (.aa) files. +

+ +

15.2 aac

+ +

Raw Audio Data Transport Stream AAC demuxer. +

+

This demuxer is used to demux an ADTS input containing a single AAC stream +alongwith any ID3v1/2 or APE tags in it. +

+ +

15.3 apng

+ +

Animated Portable Network Graphics demuxer. +

+

This demuxer is used to demux APNG files. +All headers, but the PNG signature, up to (but not including) the first +fcTL chunk are transmitted as extradata. +Frames are then split as being all the chunks between two fcTL ones, or +between the last fcTL and IEND chunks. +

+
+
-ignore_loop bool
+

Ignore the loop variable in the file if set. Default is enabled. +

+
+
-max_fps int
+

Maximum framerate in frames per second. Default of 0 imposes no limit. +

+
+
-default_fps int
+

Default framerate in frames per second when none is specified in the file +(0 meaning as fast as possible). Default is 15. +

+
+
+ + +

15.4 asf

+ +

Advanced Systems Format demuxer. +

+

This demuxer is used to demux ASF files and MMS network streams. +

+
+
-no_resync_search bool
+

Do not try to resynchronize by looking for a certain optional start code. +

+
+ + +

15.5 concat

+ +

Virtual concatenation script demuxer. +

+

This demuxer reads a list of files and other directives from a text file and +demuxes them one after the other, as if all their packets had been muxed +together. +

+

The timestamps in the files are adjusted so that the first file starts at 0 +and each next file starts where the previous one finishes. Note that it is +done globally and may cause gaps if all streams do not have exactly the same +length. +

+

All files must have the same streams (same codecs, same time base, etc.). +

+

The duration of each file is used to adjust the timestamps of the next file: +if the duration is incorrect (because it was computed using the bit-rate or +because the file is truncated, for example), it can cause artifacts. The +duration directive can be used to override the duration stored in +each file. +

+ +

15.5.1 Syntax

+ +

The script is a text file in extended-ASCII, with one directive per line. +Empty lines, leading spaces and lines starting with ’#’ are ignored. The +following directive is recognized: +

+
+
file path
+

Path to a file to read; special characters and spaces must be escaped with +backslash or single quotes. +

+

All subsequent file-related directives apply to that file. +

+
+
ffconcat version 1.0
+

Identify the script type and version. +

+

To make FFmpeg recognize the format automatically, this directive must +appear exactly as is (no extra space or byte-order-mark) on the very first +line of the script. +

+
+
duration dur
+

Duration of the file. This information can be specified from the file; +specifying it here may be more efficient or help if the information from the +file is not available or accurate. +

+

If the duration is set for all files, then it is possible to seek in the +whole concatenated video. +

+
+
inpoint timestamp
+

In point of the file. When the demuxer opens the file it instantly seeks to the +specified timestamp. Seeking is done so that all streams can be presented +successfully at In point. +

+

This directive works best with intra frame codecs, because for non-intra frame +ones you will usually get extra packets before the actual In point and the +decoded content will most likely contain frames before In point too. +

+

For each file, packets before the file In point will have timestamps less than +the calculated start timestamp of the file (negative in case of the first +file), and the duration of the files (if not specified by the duration +directive) will be reduced based on their specified In point. +

+

Because of potential packets before the specified In point, packet timestamps +may overlap between two concatenated files. +

+
+
outpoint timestamp
+

Out point of the file. When the demuxer reaches the specified decoding +timestamp in any of the streams, it handles it as an end of file condition and +skips the current and all the remaining packets from all streams. +

+

Out point is exclusive, which means that the demuxer will not output packets +with a decoding timestamp greater or equal to Out point. +

+

This directive works best with intra frame codecs and formats where all streams +are tightly interleaved. For non-intra frame codecs you will usually get +additional packets with presentation timestamp after Out point therefore the +decoded content will most likely contain frames after Out point too. If your +streams are not tightly interleaved you may not get all the packets from all +streams before Out point and you may only will be able to decode the earliest +stream until Out point. +

+

The duration of the files (if not specified by the duration +directive) will be reduced based on their specified Out point. +

+
+
file_packet_metadata key=value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +This directive is deprecated, use file_packet_meta instead. +

+
+
file_packet_meta key value
+

Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. +

+
+
option key value
+

Option to access, open and probe the file. +Can be present multiple times. +

+
+
stream
+

Introduce a stream in the virtual file. +All subsequent stream-related directives apply to the last introduced +stream. +Some streams properties must be set in order to allow identifying the +matching streams in the subfiles. +If no streams are defined in the script, the streams from the first file are +copied. +

+
+
exact_stream_id id
+

Set the id of the stream. +If this directive is given, the string with the corresponding id in the +subfiles will be used. +This is especially useful for MPEG-PS (VOB) files, where the order of the +streams is not reliable. +

+
+
stream_meta key value
+

Metadata for the stream. +Can be present multiple times. +

+
+
stream_codec value
+

Codec for the stream. +

+
+
stream_extradata hex_string
+

Extradata for the string, encoded in hexadecimal. +

+
+
chapter id start end
+

Add a chapter. id is an unique identifier, possibly small and +consecutive. +

+
+
+ + +

15.5.2 Options

+ +

This demuxer accepts the following option: +

+
+
safe
+

If set to 1, reject unsafe file paths and directives. +A file path is considered safe if it +does not contain a protocol specification and is relative and all components +only contain characters from the portable character set (letters, digits, +period, underscore and hyphen) and have no period at the beginning of a +component. +

+

If set to 0, any file name is accepted. +

+

The default is 1. +

+
+
auto_convert
+

If set to 1, try to perform automatic conversions on packet data to make the +streams concatenable. +The default is 1. +

+

Currently, the only conversion is adding the h264_mp4toannexb bitstream +filter to H.264 streams in MP4 format. This is necessary in particular if +there are resolution changes. +

+
+
segment_time_metadata
+

If set to 1, every packet will contain the lavf.concat.start_time and the +lavf.concat.duration packet metadata values which are the start_time and +the duration of the respective file segments in the concatenated output +expressed in microseconds. The duration metadata is only set if it is known +based on the concat file. +The default is 0. +

+
+
+ + +

15.5.3 Examples

+ +
    +
  • Use absolute filenames and include some comments: +
    +
    # my first filename
    +file /mnt/share/file-1.wav
    +# my second filename including whitespace
    +file '/mnt/share/file 2.wav'
    +# my third filename including whitespace plus single quote
    +file '/mnt/share/file 3'\''.wav'
    +
    + +
  • Allow for input format auto-probing, use safe filenames and set the duration of +the first file: +
    +
    ffconcat version 1.0
    +
    +file file-1.wav
    +duration 20.0
    +
    +file subdir/file-2.wav
    +
    +
+ + +

15.6 dash

+ +

Dynamic Adaptive Streaming over HTTP demuxer. +

+

This demuxer presents all AVStreams found in the manifest. +By setting the discard flags on AVStreams the caller can decide +which streams to actually receive. +Each stream mirrors the id and bandwidth properties from the +<Representation> as metadata keys named "id" and "variant_bitrate" respectively. +

+ +

15.6.1 Options

+ +

This demuxer accepts the following option: +

+
+
cenc_decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
cenc_decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
+ + +

15.7 dvdvideo

+ +

DVD-Video demuxer, powered by libdvdnav and libdvdread. +

+

Can directly ingest DVD titles, specifically sequential PGCs, into +a conversion pipeline. Menu assets, such as background video or audio, +can also be demuxed given the menu’s coordinates (at best effort). +

+

Block devices (DVD drives), ISO files, and directory structures are accepted. +Activate with -f dvdvideo in front of one of these inputs. +

+

This demuxer does NOT have decryption code of any kind. You are on your own +working with encrypted DVDs, and should not expect support on the matter. +

+

Underlying playback is handled by libdvdnav, and structure parsing by libdvdread. +FFmpeg must be built with GPL library support available as well as the +configure switches --enable-libdvdnav and --enable-libdvdread. +

+

You will need to provide either the desired "title number" or exact PGC/PG coordinates. +Many open-source DVD players and tools can aid in providing this information. +If not specified, the demuxer will default to title 1 which works for many discs. +However, due to the flexibility of the format, it is recommended to check manually. +There are many discs that are authored strangely or with invalid headers. +

+

If the input is a real DVD drive, please note that there are some drives which may +silently fail on reading bad sectors from the disc, returning random bits instead +which is effectively corrupt data. This is especially prominent on aging or rotting discs. +A second pass and integrity checks would be needed to detect the corruption. +This is not an FFmpeg issue. +

+ +

15.7.1 Background

+ +

DVD-Video is not a directly accessible, linear container format in the +traditional sense. Instead, it allows for complex and programmatic playback of +carefully muxed MPEG-PS streams that are stored in headerless VOB files. +To the end-user, these streams are known simply as "titles", but the actual +logical playback sequence is defined by one or more "PGCs", or Program Group Chains, +within the title. The PGC is in turn comprised of multiple "PGs", or Programs", +which are the actual video segments (and for a typical video feature, sequentially +ordered). The PGC structure, along with stream layout and metadata, are stored in +IFO files that need to be parsed. PGCs can be thought of as playlists in easier terms. +

+

An actual DVD player relies on user GUI interaction via menus and an internal VM +to drive the direction of demuxing. Generally, the user would either navigate (via menus) +or automatically be redirected to the PGC of their choice. During this process and +the subsequent playback, the DVD player’s internal VM also maintains a state and +executes instructions that can create jumps to different sectors during playback. +This is why libdvdnav is involved, as a linear read of the MPEG-PS blobs on the +disc (VOBs) is not enough to produce the right sequence in many cases. +

+

There are many other DVD structures (a long subject) that will not be discussed here. +NAV packets, in particular, are handled by this demuxer to build accurate timing +but not emitted as a stream. For a good high-level understanding, refer to: +https://code.videolan.org/videolan/libdvdnav/-/blob/master/doc/dvd_structures +

+ +

15.7.2 Options

+ +

This demuxer accepts the following options: +

+
+
title int
+

The title number to play. Must be set if pgc and pg are not set. +Not applicable to menus. +Default is 0 (auto), which currently only selects the first available title (title 1) +and notifies the user about the implications. +

+
+
chapter_start int
+

The chapter, or PTT (part-of-title), number to start at. Not applicable to menus. +Default is 1. +

+
+
chapter_end int
+

The chapter, or PTT (part-of-title), number to end at. Not applicable to menus. +Default is 0, which is a special value to signal end at the last possible chapter. +

+
+
angle int
+

The video angle number, referring to what is essentially an additional +video stream that is composed from alternate frames interleaved in the VOBs. +Not applicable to menus. +Default is 1. +

+
+
region int
+

The region code to use for playback. Some discs may use this to default playback +at a particular angle in different regions. This option will not affect the region code +of a real DVD drive, if used as an input. Not applicable to menus. +Default is 0, "world". +

+
+
menu bool
+

Demux menu assets instead of navigating a title. Requires exact coordinates +of the menu (menu_lu, menu_vts, pgc, pg). +Default is false. +

+
+
menu_lu int
+

The menu language to demux. In DVD, menus are grouped by language. +Default is 1, the first language unit. +

+
+
menu_vts int
+

The VTS where the menu lives, or 0 if it is a VMG menu (root-level). +Default is 1, menu of the first VTS. +

+
+
pgc int
+

The entry PGC to start playback, in conjunction with pg. +Alternative to setting title. +Chapter markers are not supported at this time. +Must be explicitly set for menus. +Default is 0, automatically resolve from value of title. +

+
+
pg int
+

The entry PG to start playback, in conjunction with pgc. +Alternative to setting title. +Chapter markers are not supported at this time. +Default is 1, the first PG of the PGC. +

+
+
preindex bool
+

Enable this to have accurate chapter (PTT) markers and duration measurement, +which requires a slow second pass read in order to index the chapter marker +timestamps from NAV packets. This is non-ideal extra work for real optical drives. +It is recommended and faster to use this option with a backup of the DVD structure +stored on a hard drive. Not compatible with pgc and pg. +Default is 0, false. +

+
+
trim bool
+

Skip padding cells (i.e. cells shorter than 1 second) from the beginning. +There exist many discs with filler segments at the beginning of the PGC, +often with junk data intended for controlling a real DVD player’s +buffering speed and with no other material data value. +Not applicable to menus. +Default is 1, true. +

+
+
+ + +

15.7.3 Examples

+ +
    +
  • Open title 3 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -title 3 -i <path to DVD> ...
    +
    + +
  • Open chapters 3-6 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 3 -chapter_end 6 -title 1 -i <path to DVD> ...
    +
    + +
  • Open only chapter 5 from title 1 from a given DVD structure: +
    +
    ffmpeg -f dvdvideo -chapter_start 5 -chapter_end 5 -title 1 -i <path to DVD> ...
    +
    + +
  • Demux menu with language 1 from VTS 1, PGC 1, starting at PG 1: +
    +
    ffmpeg -f dvdvideo -menu 1 -menu_lu 1 -menu_vts 1 -pgc 1 -pg 1 -i <path to DVD> ...
    +
    +
+ + +

15.8 ea

+ +

Electronic Arts Multimedia format demuxer. +

+

This format is used by various Electronic Arts games. +

+ +

15.8.1 Options

+ +
+
merge_alpha bool
+
+

Normally the VP6 alpha channel (if exists) is returned as a secondary video +stream, by setting this option you can make the demuxer return a single video +stream which contains the alpha channel in addition to the ordinary video. +

+
+
+ + +

15.9 imf

+ +

Interoperable Master Format demuxer. +

+

This demuxer presents audio and video streams found in an IMF Composition, as +specified in SMPTE ST 2067-2. +

+
+
ffmpeg [-assetmaps <path of ASSETMAP1>,<path of ASSETMAP2>,...] -i <path of CPL> ...
+
+ +

If -assetmaps is not specified, the demuxer looks for a file called +ASSETMAP.xml in the same directory as the CPL. +

+ +

15.10 flv, live_flv, kux

+ +

Adobe Flash Video Format demuxer. +

+

This demuxer is used to demux FLV files and RTMP network streams. In case of live network streams, if you force format, you may use live_flv option instead of flv to survive timestamp discontinuities. +KUX is a flv variant used on the Youku platform. +

+
+
ffmpeg -f flv -i myfile.flv ...
+ffmpeg -f live_flv -i rtmp://<any.server>/anything/key ....
+
+ + +
+
-flv_metadata bool
+

Allocate the streams according to the onMetaData array content. +

+
+
-flv_ignore_prevtag bool
+

Ignore the size of previous tag value. +

+
+
-flv_full_metadata bool
+

Output all context of the onMetadata. +

+
+ + +

15.11 gif

+ +

Animated GIF demuxer. +

+

It accepts the following options: +

+
+
min_delay
+

Set the minimum valid delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 2. +

+
+
max_gif_delay
+

Set the maximum valid delay between frames in hundredth of seconds. +Range is 0 to 65535. Default value is 65535 (nearly eleven minutes), +the maximum value allowed by the specification. +

+
+
default_delay
+

Set the default delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 10. +

+
+
ignore_loop
+

GIF files can contain information to loop a certain number of times (or +infinitely). If ignore_loop is set to 1, then the loop setting +from the input will be ignored and looping will not occur. If set to 0, +then looping will occur and will cycle the number of times according to +the GIF. Default value is 1. +

+
+ +

For example, with the overlay filter, place an infinitely looping GIF +over another video: +

+
ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv
+
+ +

Note that in the above example the shortest option for overlay filter is +used to end the output video at the length of the shortest input file, +which in this case is input.mp4 as the GIF in this example loops +infinitely. +

+ +

15.12 hls

+ +

HLS demuxer +

+

Apple HTTP Live Streaming demuxer. +

+

This demuxer presents all AVStreams from all variant streams. +The id field is set to the bitrate variant index number. By setting +the discard flags on AVStreams (by pressing ’a’ or ’v’ in ffplay), +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". +

+

It accepts the following options: +

+
+
live_start_index
+

segment index to start live streams at (negative values are from the end). +

+
+
prefer_x_start
+

prefer to use #EXT-X-START if it’s in playlist instead of live_start_index. +

+
+
allowed_extensions
+

’,’ separated list of file extensions that hls is allowed to access. +

+
+
extension_picky
+

This blocks disallowed extensions from probing +It also requires all available segments to have matching extensions to the format +except mpegts, which is always allowed. +It is recommended to set the whitelists correctly instead of depending on extensions +Enabled by default. +

+
+
max_reload
+

Maximum number of times a insufficient list is attempted to be reloaded. +Default value is 1000. +

+
+
m3u8_hold_counters
+

The maximum number of times to load m3u8 when it refreshes without new segments. +Default value is 1000. +

+
+
http_persistent
+

Use persistent HTTP connections. Applicable only for HTTP streams. +Enabled by default. +

+
+
http_multiple
+

Use multiple HTTP connections for downloading HTTP segments. +Enabled by default for HTTP/1.1 servers. +

+
+
http_seekable
+

Use HTTP partial requests for downloading HTTP segments. +0 = disable, 1 = enable, -1 = auto, Default is auto. +

+
+
seg_format_options
+

Set options for the demuxer of media segments using a list of key=value pairs separated by :. +

+
+
seg_max_retry
+

Maximum number of times to reload a segment on error, useful when segment skip on network error is not desired. +Default value is 0. +

+
+ + +

15.13 image2

+ +

Image file demuxer. +

+

This demuxer reads from a list of image files specified by a pattern. +The syntax and meaning of the pattern is specified by the +option pattern_type. +

+

The pattern may contain a suffix which is used to automatically +determine the format of the images contained in the files. +

+

The size, the pixel format, and the format of each image must be the +same for all the files in the sequence. +

+

This demuxer accepts the following options: +

+
framerate
+

Set the frame rate for the video stream. It defaults to 25. +

+
loop
+

If set to 1, loop over the input. Default value is 0. +

+
pattern_type
+

Select the pattern type used to interpret the provided filename. +

+

pattern_type accepts one of the following values. +

+
none
+

Disable pattern matching, therefore the video will only contain the specified +image. You should use this option if you do not want to create sequences from +multiple images and your filenames may contain special pattern characters. +

+
sequence
+

Select a sequence pattern type, used to specify a sequence of files +indexed by sequential numbers. +

+

A sequence pattern may contain the string "%d" or "%0Nd", which +specifies the position of the characters representing a sequential +number in each filename matched by the pattern. If the form +"%d0Nd" is used, the string representing the number in each +filename is 0-padded and N is the total number of 0-padded +digits representing the number. The literal character ’%’ can be +specified in the pattern with the string "%%". +

+

If the sequence pattern contains "%d" or "%0Nd", the first filename of +the file list specified by the pattern must contain a number +inclusively contained between start_number and +start_number+start_number_range-1, and all the following +numbers must be sequential. +

+

For example the pattern "img-%03d.bmp" will match a sequence of +filenames of the form img-001.bmp, img-002.bmp, ..., +img-010.bmp, etc.; the pattern "i%%m%%g-%d.jpg" will match a +sequence of filenames of the form i%m%g-1.jpg, +i%m%g-2.jpg, ..., i%m%g-10.jpg, etc. +

+

Note that the pattern must not necessarily contain "%d" or +"%0Nd", for example to convert a single image file +img.jpeg you can employ the command: +

+
ffmpeg -i img.jpeg img.png
+
+ +
+
glob
+

Select a glob wildcard pattern type. +

+

The pattern is interpreted like a glob() pattern. This is only +selectable if libavformat was compiled with globbing support. +

+
+ +

Default value is sequence. +

+
pixel_format
+

Set the pixel format of the images to read. If not specified the pixel +format is guessed from the first image file in the sequence. +

+
start_number
+

Set the index of the file matched by the image file pattern to start +to read from. Default value is 0. +

+
start_number_range
+

Set the index interval range to check when looking for the first image +file in the sequence, starting from start_number. Default value +is 5. +

+
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. +If set to 2, will set frame timestamp to the modification time of the image file in +nanosecond precision. +

+
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. +

+
export_path_metadata
+

If set to 1, will add two extra fields to the metadata found in input, making them +also available for other filters (see drawtext filter for examples). Default +value is 0. The extra fields are described below: +

+
lavf.image2dec.source_path
+

Corresponds to the full path to the input file being read. +

+
lavf.image2dec.source_basename
+

Corresponds to the name of the file being read. +

+
+ +
+
+ + +

15.13.1 Examples

+ +
    +
  • Use ffmpeg for creating a video from the images in the file +sequence img-001.jpeg, img-002.jpeg, ..., assuming an +input frame rate of 10 frames per second: +
    +
    ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • As above, but start by reading from a file with index 100 in the sequence: +
    +
    ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv
    +
    + +
  • Read images matching the "*.png" glob pattern , that is all the files +terminating with the ".png" suffix: +
    +
    ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv
    +
    +
+ + +

15.14 libgme

+ +

The Game Music Emu library is a collection of video game music file emulators. +

+

See https://bitbucket.org/mpyne/game-music-emu/overview for more information. +

+

It accepts the following options: +

+
+
track_index
+

Set the index of which track to demux. The demuxer can only export one track. +Track indexes start at 0. Default is to pick the first track. Number of tracks +is exported as tracks metadata entry. +

+
+
sample_rate
+

Set the sampling rate of the exported track. Range is 1000 to 999999. Default is 44100. +

+
+
max_size (bytes)
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. +Default is 50 MiB. +

+
+
+ + +

15.15 libmodplug

+ +

ModPlug based module demuxer +

+

See https://github.com/Konstanty/libmodplug +

+

It will export one 2-channel 16-bit 44.1 kHz audio stream. +Optionally, a pal8 16-color video stream can be exported with or without printed metadata. +

+

It accepts the following options: +

+
+
noise_reduction
+

Apply a simple low-pass filter. Can be 1 (on) or 0 (off). Default is 0. +

+
+
reverb_depth
+

Set amount of reverb. Range 0-100. Default is 0. +

+
+
reverb_delay
+

Set delay in ms, clamped to 40-250 ms. Default is 0. +

+
+
bass_amount
+

Apply bass expansion a.k.a. XBass or megabass. Range is 0 (quiet) to 100 (loud). Default is 0. +

+
+
bass_range
+

Set cutoff i.e. upper-bound for bass frequencies. Range is 10-100 Hz. Default is 0. +

+
+
surround_depth
+

Apply a Dolby Pro-Logic surround effect. Range is 0 (quiet) to 100 (heavy). Default is 0. +

+
+
surround_delay
+

Set surround delay in ms, clamped to 5-40 ms. Default is 0. +

+
+
max_size
+

The demuxer buffers the entire file into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of files that can be read. Range is 0 to 100 MiB. +0 removes buffer size limit (not recommended). Default is 5 MiB. +

+
+
video_stream_expr
+

String which is evaluated using the eval API to assign colors to the generated video stream. +Variables which can be used are x, y, w, h, t, speed, +tempo, order, pattern and row. +

+
+
video_stream
+

Generate video stream. Can be 1 (on) or 0 (off). Default is 0. +

+
+
video_stream_w
+

Set video frame width in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_h
+

Set video frame height in ’chars’ where one char indicates 8 pixels. Range is 20-512. Default is 30. +

+
+
video_stream_ptxt
+

Print metadata on video stream. Includes speed, tempo, order, pattern, +row and ts (time in ms). Can be 1 (on) or 0 (off). Default is 1. +

+
+
+ + +

15.16 libopenmpt

+ +

libopenmpt based module demuxer +

+

See https://lib.openmpt.org/libopenmpt/ for more information. +

+

Some files have multiple subsongs (tracks) this can be set with the subsong +option. +

+

It accepts the following options: +

+
+
subsong
+

Set the subsong index. This can be either ’all’, ’auto’, or the index of the +subsong. Subsong indexes start at 0. The default is ’auto’. +

+

The default value is to let libopenmpt choose. +

+
+
layout
+

Set the channel layout. Valid values are 1, 2, and 4 channel layouts. +The default value is STEREO. +

+
+
sample_rate
+

Set the sample rate for libopenmpt to output. +Range is from 1000 to INT_MAX. The value default is 48000. +

+
+ + +

15.17 mcc

+ +

Demuxer for MacCaption MCC files, it supports MCC versions 1.0 and 2.0. +MCC files store VANC data, which can include closed captions (EIA-608 and CEA-708), ancillary time code, pan-scan data, etc. +By default, for backward compatibility, the MCC demuxer extracts just the EIA-608 and CEA-708 closed captions and returns a EIA_608 stream, ignoring all other VANC data. +You can change it to return all VANC data in a SMPTE_436M_ANC data stream by setting -eia608_extract 0 +

+ +

15.17.1 Examples

+ +
    +
  • Convert a MCC file to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.mcc -c:s copy CC.scc
    +
    +

    Note that the SCC format only supports EIA-608, so this will discard all other data such as CEA-708 extensions. +

    +
  • Merge a MCC file into a MXF file: +
    +
    ffmpeg -i video_and_audio.mxf -eia608_extract 0 -i CC.mcc -c copy -map 0 -map 1 out.mxf
    +
    +

    This retains all VANC data and inserts it into the output MXF file as a SMPTE_436M_ANC data stream. +

+ + +

15.18 mov/mp4/3gp

+ +

Demuxer for Quicktime File Format & ISO/IEC Base Media File Format (ISO/IEC 14496-12 or MPEG-4 Part 12, ISO/IEC 15444-12 or JPEG 2000 Part 12). +

+

Registered extensions: mov, mp4, m4a, 3gp, 3g2, mj2, psp, m4b, ism, ismv, isma, f4v +

+ +

15.18.1 Options

+ +

This demuxer accepts the following options: +

+
enable_drefs
+

Enable loading of external tracks, disabled by default. +Enabling this can theoretically leak information in some use cases. +

+
+
use_absolute_path
+

Allows loading of external tracks via absolute paths, disabled by default. +Enabling this poses a security risk. It should only be enabled if the source +is known to be non-malicious. +

+
+
seek_streams_individually
+

When seeking, identify the closest point in each stream individually and demux packets in +that stream from identified point. This can lead to a different sequence of packets compared +to demuxing linearly from the beginning. Default is true. +

+
+
ignore_editlist
+

Ignore any edit list atoms. The demuxer, by default, modifies the stream index to reflect the +timeline described by the edit list. Default is false. +

+
+
advanced_editlist
+

Modify the stream index to reflect the timeline described by the edit list. ignore_editlist +must be set to false for this option to be effective. +If both ignore_editlist and this option are set to false, then only the +start of the stream index is modified to reflect initial dwell time or starting timestamp +described by the edit list. Default is true. +

+
+
ignore_chapters
+

Don’t parse chapters. This includes GoPro ’HiLight’ tags/moments. Note that chapters are +only parsed when input is seekable. Default is false. +

+
+
use_mfra_for
+

For seekable fragmented input, set fragment’s starting timestamp from media fragment random access box, if present. +

+

Following options are available: +

+
‘auto’
+

Auto-detect whether to set mfra timestamps as PTS or DTS (default) +

+
+
‘dts’
+

Set mfra timestamps as DTS +

+
+
‘pts’
+

Set mfra timestamps as PTS +

+
+
‘0’
+

Don’t use mfra box to set timestamps +

+
+ +
+
use_tfdt
+

For fragmented input, set fragment’s starting timestamp to baseMediaDecodeTime from the tfdt box. +Default is enabled, which will prefer to use the tfdt box to set DTS. Disable to use the earliest_presentation_time from the sidx box. +In either case, the timestamp from the mfra box will be used if it’s available and use_mfra_for is +set to pts or dts. +

+
+
export_all
+

Export unrecognized boxes within the udta box as metadata entries. The first four +characters of the box type are set as the key. Default is false. +

+
+
export_xmp
+

Export entire contents of XMP_ box and uuid box as a string with key xmp. Note that +if export_all is set and this option isn’t, the contents of XMP_ box are still exported +but with key XMP_. Default is false. +

+
+
activation_bytes
+

4-byte key required to decrypt Audible AAX and AAX+ files. See Audible AAX subsection below. +

+
+
audible_fixed_key
+

Fixed key used for handling Audible AAX/AAX+ files. It has been pre-set so should not be necessary to +specify. +

+
+
decryption_key
+

Default 16-byte key, in hex, to decrypt files encrypted using ISO Common Encryption (CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
decryption_keys
+

Dictionary of 16-byte key ID => 16-byte key, both in hex, to decrypt files encrypted using ISO Common Encryption +(CENC/AES-128 CTR; ISO/IEC 23001-7). +

+
+
max_stts_delta
+

Very high sample deltas written in a trak’s stts box may occasionally be intended but usually they are written in +error or used to store a negative value for dts correction when treated as signed 32-bit integers. This option lets +the user set an upper limit, beyond which the delta is clamped to 1. Values greater than the limit if negative when +cast to int32 are used to adjust onward dts. +

+

Unit is the track time scale. Range is 0 to UINT_MAX. Default is UINT_MAX - 48000*10 which allows up to +a 10 second dts correction for 48 kHz audio streams while accommodating 99.9% of uint32 range. +

+
+
interleaved_read
+

Interleave packets from multiple tracks at demuxer level. For badly interleaved files, this prevents playback issues +caused by large gaps between packets in different tracks, as MOV/MP4 do not have packet placement requirements. +However, this can cause excessive seeking on very badly interleaved files, due to seeking between tracks, so disabling +it may prevent I/O issues, at the expense of playback. +

+
+
+ + +

15.18.2 Audible AAX

+ +

Audible AAX files are encrypted M4B files, and they can be decrypted by specifying a 4 byte activation secret. +

+
ffmpeg -activation_bytes 1CEB00DA -i test.aax -vn -c:a copy output.mp4
+
+ + +

15.19 mpegts

+ +

MPEG-2 transport stream demuxer. +

+

This demuxer accepts the following options: +

+
resync_size
+

Set size limit for looking up a new synchronization. Default value is +65536. +

+
+
skip_unknown_pmt
+

Skip PMTs for programs not defined in the PAT. Default value is 0. +

+
+
fix_teletext_pts
+

Override 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. +

+
+
ts_packetsize
+

Output option carrying the raw packet size in bytes. +Show the detected raw packet size, cannot be set by the user. +

+
+
scan_all_pmts
+

Scan and combine all PMTs. The value is an integer with value from -1 +to 1 (-1 means automatic setting, 1 means enabled, 0 means +disabled). Default value is -1. +

+
+
merge_pmt_versions
+

Reuse existing streams when a PMT’s version is updated and elementary +streams move to different PIDs. Default value is 0. +

+
+
max_packet_size
+

Set maximum size, in bytes, of packet emitted by the demuxer. Payloads above this size +are split across multiple packets. Range is 1 to INT_MAX/2. Default is 204800 bytes. +

+
+ + +

15.20 mpjpeg

+ +

MJPEG encapsulated in multi-part MIME demuxer. +

+

This demuxer allows reading of MJPEG, where each frame is represented as a part of +multipart/x-mixed-replace stream. +

+
strict_mime_boundary
+

Default implementation applies a relaxed standard to multi-part MIME boundary detection, +to prevent regression with numerous existing endpoints not generating a proper MIME +MJPEG stream. Turning this option on by setting it to 1 will result in a stricter check +of the boundary value. +

+
+ + +

15.21 rawvideo

+ +

Raw video demuxer. +

+

This demuxer allows one to read raw video data. Since there is no header +specifying the assumed video parameters, the user must specify them +in order to be able to decode the data correctly. +

+

This demuxer accepts the following options: +

+
framerate
+

Set input video frame rate. Default value is 25. +

+
+
pixel_format
+

Set the input video pixel format. Default value is yuv420p. +

+
+
stride
+

Set frame line size in bytes, only required if there are extra padding. +For multiplane formats, stride is a list of line size for each +plane. +

+
+
video_size
+

Set the input video size. This value must be specified explicitly. +

+
+ +

For example to read a rawvideo file input.raw with +ffplay, assuming a pixel format of rgb24, a video +size of 320x240, and a frame rate of 10 images per second, use +the command: +

+
ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw
+
+ +

Read a rawvideo with ffplay, assuming a pixel format of yuv420p, +a video size of 1080x1920, has 8 bytes of padding in each line of Y plane, +and 4 bytes of padding with UV plane, +

+
ffplay -f rawvideo -pixel_format yuv420p -video_size 1080x1920 -stride 1088,544,544 input.raw
+
+ + +

15.22 rcwt

+ +

RCWT (Raw Captions With Time) is a format native to ccextractor, a commonly +used open source tool for processing 608/708 Closed Captions (CC) sources. +For more information on the format, see (ffmpeg-formats)rcwtenc. +

+

This demuxer implements the specification as of March 2024, which has +been stable and unchanged since April 2014. +

+ +

15.22.1 Examples

+ +
    +
  • Render CC to ASS using the built-in decoder: +
    +
    ffmpeg -i CC.rcwt.bin CC.ass
    +
    +

    Note that if your output appears to be empty, you may have to manually +set the decoder’s data_field option to pick the desired CC substream. +

    +
  • Convert an RCWT backup to Scenarist (SCC) format: +
    +
    ffmpeg -i CC.rcwt.bin -c:s copy CC.scc
    +
    +

    Note that the SCC format does not support all of the possible CC extensions +that can be stored in RCWT (such as EIA-708). +

+ + +

15.23 sbg

+ +

SBaGen script demuxer. +

+

This demuxer reads the script language used by SBaGen +http://uazu.net/sbagen/ to generate binaural beats sessions. A SBG +script looks like that: +

+
-SE
+a: 300-2.5/3 440+4.5/0
+b: 300-2.5/0 440+4.5/3
+off: -
+NOW      == a
++0:07:00 == b
++0:14:00 == a
++0:21:00 == b
++0:30:00    off
+
+ +

A SBG script can mix absolute and relative timestamps. If the script uses +either only absolute timestamps (including the script start time) or only +relative ones, then its layout is fixed, and the conversion is +straightforward. On the other hand, if the script mixes both kind of +timestamps, then the NOW reference for relative timestamps will be +taken from the current time of day at the time the script is read, and the +script layout will be frozen according to that reference. That means that if +the script is directly played, the actual times will match the absolute +timestamps up to the sound controller’s clock accuracy, but if the user +somehow pauses the playback or seeks, all times will be shifted accordingly. +

+ +

15.24 tedcaptions

+ +

JSON captions used for TED Talks. +

+

TED does not provide links to the captions, but they can be guessed from the +page. The file tools/bookmarklets.html from the FFmpeg source tree +contains a bookmarklet to expose them. +

+

This demuxer accepts the following option: +

+
start_time
+

Set the start time of the TED talk, in milliseconds. The default is 15000 +(15s). It is used to sync the captions with the downloadable videos, because +they include a 15s intro. +

+
+ +

Example: convert the captions to a format most players understand: +

+
ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt
+
+ + +

15.25 vapoursynth

+ +

Vapoursynth wrapper. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+

This demuxer accepts the following option: +

+
max_script_size
+

The demuxer buffers the entire script into memory. Adjust this value to set the maximum buffer size, +which in turn, acts as a ceiling for the size of scripts that can be read. +Default is 1 MiB. +

+
+ + +

15.26 w64

+ +

Sony Wave64 Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

See the same option for the wav demuxer. +

+
+ + +

15.27 wav

+ +

RIFF Wave Audio demuxer. +

+

This demuxer accepts the following options: +

+
max_size
+

Specify the maximum packet size in bytes for the demuxed packets. By default +this is set to 0, which means that a sensible value is chosen based on the +input format. +

+
+ + +

16 Metadata

+ +

FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded +INI-like text file and then load it back using the metadata muxer/demuxer. +

+

The file format is as follows: +

    +
  1. A file consists of a header and a number of metadata tags divided into sections, +each on its own line. + +
  2. The header is a ‘;FFMETADATA’ string, followed by a version number (now 1). + +
  3. Metadata tags are of the form ‘key=value’ + +
  4. Immediately after header follows global metadata + +
  5. After global metadata there may be sections with per-stream/per-chapter +metadata. + +
  6. A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in +brackets (‘[’, ‘]’) and ends with next section or end of file. + +
  7. At the beginning of a chapter section there may be an optional timebase to be +used for start/end values. It must be in form +‘TIMEBASE=num/den’, where num and den are +integers. If the timebase is missing then start/end times are assumed to +be in nanoseconds. + +

    Next a chapter section must contain chapter start and end times in form +‘START=num’, ‘END=num’, where num is a positive +integer. +

    +
  8. Empty lines and lines starting with ‘;’ or ‘#’ are ignored. + +
  9. Metadata keys or values containing special characters (‘=’, ‘;’, +‘#’, ‘\’ and a newline) must be escaped with a backslash ‘\’. + +
  10. Note that whitespace in metadata (e.g. ‘foo = bar’) is considered to be +a part of the tag (in the example above key is ‘foo ’, value is +‘ bar’). +
+ +

A ffmetadata file might look like this: +

+
;FFMETADATA1
+title=bike\\shed
+;this is a comment
+artist=FFmpeg troll team
+
+[CHAPTER]
+TIMEBASE=1/1000
+START=0
+#chapter ends at 0:01:00
+END=60000
+title=chapter \#1
+[STREAM]
+title=multi\
+line
+
+ +

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 ffmpeg goes as follows: +

+
ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
+
+ +

Reinserting edited metadata information from the FFMETADATAFILE file can +be done as: +

+
ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
+
+ + +

17 Protocol Options

+ +

The libavformat library provides some generic global options, which +can be set on all the protocols. In addition each protocol may support +so-called private options, which are specific for that component. +

+

Options may be set by specifying -option value in the +FFmpeg tools, or by setting the value explicitly in the +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+

The list of supported options follows: +

+
+
protocol_whitelist list (input)
+

Set a ","-separated list of allowed protocols. "ALL" matches all protocols. Protocols +prefixed by "-" are disabled. +All protocols are allowed by default but protocols used by an another +protocol (nested protocols) are restricted to a per protocol subset. +

+
+ + + +

18 Protocols

+ +

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 +configure option "–list-protocols". +

+

You can disable all the protocols using the configure option +"–disable-protocols", and selectively enable a protocol using the +option "–enable-protocol=PROTOCOL", or you can disable a +particular protocol using the option +"–disable-protocol=PROTOCOL". +

+

The option "-protocols" of the ff* tools will display the list of +supported protocols. +

+

All protocols accept the following options: +

+
+
rw_timeout
+

Maximum time to wait for (network) read/write operations to complete, +in microseconds. +

+
+ +

A description of the currently available protocols follows. +

+ +

18.1 amqp

+ +

Advanced Message Queueing Protocol (AMQP) version 0-9-1 is a broker based +publish-subscribe communication protocol. +

+

FFmpeg must be compiled with –enable-librabbitmq to support AMQP. A separate +AMQP broker must also be run. An example open-source AMQP broker is RabbitMQ. +

+

After starting the broker, an FFmpeg client may stream data to the broker using +the command: +

+
+
ffmpeg -re -i input -f mpegts amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

Where hostname and port (default is 5672) is the address of the broker. The +client may also set a user/password for authentication. The default for both +fields is "guest". Name of virtual host on broker can be set with vhost. The +default value is "/". +

+

Multiple subscribers may stream from the broker using the command: +

+
ffplay amqp://[[user]:[password]@]hostname[:port][/vhost]
+
+ +

In RabbitMQ all data published to the broker flows through a specific exchange, +and each subscribing client has an assigned queue/buffer. When a packet arrives +at an exchange, it may be copied to a client’s queue depending on the exchange +and routing_key fields. +

+

The following options are supported: +

+
+
exchange
+

Sets the exchange to use on the broker. RabbitMQ has several predefined +exchanges: "amq.direct" is the default exchange, where the publisher and +subscriber must have a matching routing_key; "amq.fanout" is the same as a +broadcast operation (i.e. the data is forwarded to all queues on the fanout +exchange independent of the routing_key); and "amq.topic" is similar to +"amq.direct", but allows for more complex pattern matching (refer to the RabbitMQ +documentation). +

+
+
routing_key
+

Sets the routing key. The default value is "amqp". The routing key is used on +the "amq.direct" and "amq.topic" exchanges to decide whether packets are written +to the queue of a subscriber. +

+
+
pkt_size
+

Maximum size of each packet sent/received to the broker. Default is 131072. +Minimum is 4096 and max is any large value (representable by an int). When +receiving packets, this sets an internal buffer size in FFmpeg. It should be +equal to or greater than the size of the published packets to the broker. Otherwise +the received message may be truncated causing decoding errors. +

+
+
connection_timeout
+

The timeout in seconds during the initial connection to the broker. The +default value is rw_timeout, or 5 seconds if rw_timeout is not set. +

+
+
delivery_mode mode
+

Sets the delivery mode of each message sent to broker. +The following values are accepted: +

+
‘persistent’
+

Delivery mode set to "persistent" (2). This is the default value. +Messages may be written to the broker’s disk depending on its setup. +

+
+
‘non-persistent’
+

Delivery mode set to "non-persistent" (1). +Messages will stay in broker’s memory unless the broker is under memory +pressure. +

+
+
+ +
+
+ + +

18.2 async

+ +

Asynchronous data filling wrapper for input stream. +

+

Fill data in a background thread, to decouple I/O operation from demux thread. +

+
+
async:URL
+async:http://host/resource
+async:cache:http://host/resource
+
+ + +

18.3 bluray

+ +

Read BluRay playlist. +

+

The accepted options are: +

+
angle
+

BluRay angle +

+
+
chapter
+

Start chapter (1...N) +

+
+
playlist
+

Playlist to read (BDMV/PLAYLIST/?????.mpls) +

+
+
+ +

Examples: +

+

Read longest playlist from BluRay mounted to /mnt/bluray: +

+
bluray:/mnt/bluray
+
+ +

Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: +

+
-playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
+
+ + +

18.4 cache

+ +

Caching wrapper for input stream. +

+

Cache the input stream to temporary file. It brings seeking capability to live streams. +

+

The accepted options are: +

+
read_ahead_limit
+

Amount in bytes that may be read ahead when seeking isn’t supported. Range is -1 to INT_MAX. +-1 for unlimited. Default is 65536. +

+
+
+ +

URL Syntax is +

+
cache:URL
+
+ + +

18.5 concat

+ +

Physical concatenation protocol. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concat:URL1|URL2|...|URLN
+
+ +

where URL1, URL2, ..., URLN are the urls of the +resource to be concatenated, each one possibly specifying a distinct +protocol. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg with ffplay use the +command: +

+
ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+
+ +

Note that you may need to escape the character "|" which is special for +many shells. +

+ +

18.6 concatf

+ +

Physical concatenation protocol using a line break delimited list of +resources. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concatf:URL
+
+ +

where URL is the url containing a line break delimited list of +resources to be concatenated, each one possibly specifying a distinct +protocol. Special characters must be escaped with backslash or single +quotes. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg listed in separate lines within +a file split.txt with ffplay use the command: +

+
ffplay concatf:split.txt
+
+

Where split.txt contains the lines: +

+
split1.mpeg
+split2.mpeg
+split3.mpeg
+
+ + +

18.7 crypto

+ +

AES-encrypted stream reading protocol. +

+

The accepted options are: +

+
key
+

Set the AES decryption key binary block from given hexadecimal representation. +

+
+
iv
+

Set the AES decryption initialization vector binary block from given hexadecimal representation. +

+
+ +

Accepted URL formats: +

+
crypto:URL
+crypto+URL
+
+ + +

18.8 data

+ +

Data in-line in the URI. See http://en.wikipedia.org/wiki/Data_URI_scheme. +

+

For example, to convert a GIF file given inline with ffmpeg: +

+
ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
+
+ + +

18.9 fd

+ +

File descriptor access protocol. +

+

The accepted syntax is: +

+
fd: -fd file_descriptor
+
+ +

If fd is not specified, by default the stdout file descriptor will be +used for writing, stdin for reading. Unlike the pipe protocol, fd protocol has +seek support if it corresponding to a regular file. fd protocol doesn’t support +pass file descriptor via URL for security. +

+

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
fd
+

Set file descriptor. +

+
+ + +

18.10 file

+ +

File access protocol. +

+

Read from or write to a file. +

+

A file URL can have the form: +

+
file:filename
+
+ +

where filename is the path of the file to read. +

+

An URL that does not have a protocol prefix will be assumed to be a +file URL. Depending on the build, an URL that looks like a Windows +path with the drive letter at the beginning will also be assumed to be +a file URL (usually not the case in builds for unix-like systems). +

+

For example to read from a file input.mpeg with ffmpeg +use the command: +

+
ffmpeg -i file:input.mpeg output.mpeg
+
+ +

This protocol accepts the following options: +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
+
follow
+

If set to 1, the protocol will retry reading at the end of the file, allowing +reading files that still are being written. In order for this to terminate, +you either need to use the rw_timeout option, or use the interrupt callback +(for API users). +

+
+
seekable
+

Controls if seekability is advertised on the file. 0 means non-seekable, -1 +means auto (seekable for normal files, non-seekable for named pipes). +

+

Many demuxers handle seekable and non-seekable resources differently, +overriding this might speed up opening certain files at the cost of losing some +features (e.g. accurate seeking). +

+
+
pkt_size
+

Set the maximum packet size used for file I/O. A smaller value may reduce +memory usage. A higher value may increase throughput especially with networked +filesystems. +

+

For reading, if explicitly set, it overrides the default internal buffer size +(32 KB) and limits the maximum amount of data read per operation. +

+

For writing, this sets the size of each write operation. The default is 256 KB +for regular files, 32 KB otherwise. +

+
+ + +

18.11 ftp

+ +

FTP (File Transfer Protocol). +

+

Read from or write to remote resources using FTP protocol. +

+

Following syntax is required. +

+
ftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in microseconds 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. +

+
+
ftp-user
+

Set a user to be used for authenticating to the FTP server. This is overridden by the +user in the FTP URL. +

+
+
ftp-password
+

Set a password to be used for authenticating to the FTP server. This is overridden by +the password in the FTP URL, or by ftp-anonymous-password if no user is set. +

+
+
ftp-anonymous-password
+

Password used when login as anonymous user. Typically an e-mail address +should be used. +

+
+
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. +

+
+ +

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. +

+ +

18.12 gopher

+ +

Gopher protocol. +

+ +

18.13 gophers

+ +

Gophers protocol. +

+

The Gopher protocol with TLS encapsulation. +

+ +

18.14 http

+ +

HTTP (Hyper Text Transfer Protocol). +

+

This protocol accepts the following options: +

+
+
seekable
+

Control seekability of connection. If set to 1 the resource is +supposed to be seekable, if set to 0 it is assumed not to be seekable, +if set to -1 it will try to autodetect if it is seekable. Default +value is -1. +

+
+
chunked_post
+

If set to 1 use chunked Transfer-Encoding for posts, default is 1. +

+
+
http_proxy
+

set HTTP proxy to tunnel through e.g. http://example.com:1234 +

+
+
headers
+

Set custom HTTP headers, can override built in default headers. The +value must be a string encoding the headers. +

+
+
content_type
+

Set a specific content type for the POST messages or for listen mode. +

+
+
user_agent
+

Override the User-Agent header. If not specified the protocol will use a +string describing the libavformat build. ("Lavf/<version>") +

+
+
referer
+

Set the Referer header. Include ’Referer: URL’ header in HTTP request. +

+
+
multiple_requests
+

Use persistent connections if set to 1, default is 0. +

+
+
request_size
+

Limit the size of requests made. This is useful for some pathological servers +that throttle unbounded range requests, as well as when expecting to seek +frequently. Disabled (set to 0) by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. Doing so allows FFmpeg +to reuse a single HTTP connection wherever possible. +

+
+
initial_request_size
+

Limit the size of initial requests. Similar to request_size, but only +used during initial format parsing. Useful for formats like MXF or MOV that +require frequent seeks during header parsing. Lasts until the demuxer makes a +read request larger than this size (without a seek in between), after which +the implementation will continue using requests as usual. Disabled (set to 0) +by default. +

+

Note that if enabling this option, it’s strongly recommended to also enable +the multiple_requests option, as well as setting +short_seek_size to the same value or higher. +

+
+
post_data
+

Set custom HTTP post data. +

+
+
mime_type
+

Export the MIME type. +

+
+
http_version
+

Exports the HTTP response version number. Usually "1.0" or "1.1". +

+
+
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 +delimited by a newline character. +

+
+
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 icy_metadata_headers and icy_metadata_packet options. +The default is 1. +

+
+
icy_metadata_headers
+

If the server supports ICY metadata, this contains the ICY-specific HTTP reply +headers, separated by newline characters. +

+
+
icy_metadata_packet
+

If the server supports ICY metadata, and icy was set to 1, this +contains the last non-empty metadata packet sent by the server. It should be +polled in regular intervals by applications interested in mid-stream metadata +updates. +

+
+
metadata
+

Set an exported dictionary containing Icecast metadata from the bitstream, if present. +Only useful with the C API. +

+
+
auth_type
+
+

Set HTTP authentication type. No option for Digest, since this method requires +getting nonce parameters from the server first and can’t be used straight away like +Basic. +

+
+
none
+

Choose the HTTP authentication type automatically. This is the default. +

+
basic
+
+

Choose the HTTP basic authentication. +

+

Basic authentication sends a Base64-encoded string that contains a user name and password +for the client. Base64 is not a form of encryption and should be considered the same as +sending the user name and password in clear text (Base64 is a reversible encoding). +If a resource needs to be protected, strongly consider using an authentication scheme +other than basic authentication. HTTPS/TLS should be used with basic authentication. +Without these additional security enhancements, basic authentication should not be used +to protect sensitive or valuable information. +

+
+ +
+
send_expect_100
+

Send an Expect: 100-continue header for POST. If set to 1 it will send, if set +to 0 it won’t, if set to -1 it will try to send if it is applicable. Default +value is -1. +

+
+
location
+

An exported dictionary containing the content location. Only useful with the C +API. +

+
+
offset
+

Set initial byte offset. +

+
+
end_offset
+

Try to limit the request to bytes preceding this offset. +

+
+
method
+

When used as a client option it sets the HTTP method for the request. +

+

When used as a server option it sets the HTTP method that is going to be +expected from the client(s). +If the expected and the received HTTP method do not match the client will +be given a Bad Request response. +When unset the HTTP method is not checked for now. This will be replaced by +autodetection in the future. +

+
+
reconnect
+

Reconnect automatically when disconnected before EOF is hit. +

+
+
reconnect_at_eof
+

If set then eof is treated like an error and causes reconnection, this is useful +for live / endless streams. +

+
+
reconnect_on_network_error
+

Reconnect automatically in case of TCP/TLS errors during connect. +

+
+
reconnect_on_http_error
+

A comma separated list of HTTP status codes to reconnect on. The list can +include specific status codes (e.g. ’503’) or the strings ’4xx’ / ’5xx’. +

+
+
reconnect_streamed
+

If set then even streamed/non seekable streams will be reconnected on errors. +

+
+
reconnect_delay_max
+

Set the maximum delay in seconds after which to give up reconnecting. +

+
+
reconnect_max_retries
+

Set the maximum number of times to retry a connection. Default unset. +

+
+
reconnect_delay_total_max
+

Set the maximum total delay in seconds after which to give up reconnecting. +

+
+
respect_retry_after
+

If enabled, and a Retry-After header is encountered, its requested reconnection +delay will be honored, rather than using exponential backoff. Useful for 429 and +503 errors. Default enabled. +

+
+
listen
+

If set to 1 enables experimental HTTP server. This can be used to send data when +used as an output option, or read data from a client with HTTP POST when used as +an input option. +If set to 2 enables experimental multi-client HTTP server. This is not yet implemented +in ffmpeg.c and thus must not be used as a command line option. +

+
# Server side (sending):
+ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://server:port
+
+# Client side (receiving):
+ffmpeg -i http://server:port -c copy somefile.ogg
+
+# Client can also be done with wget:
+wget http://server:port -O somefile.ogg
+
+# Server side (receiving):
+ffmpeg -listen 1 -i http://server:port -c copy somefile.ogg
+
+# Client side (sending):
+ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://server:port
+
+# Client can also be done with wget:
+wget --post-file=somefile.ogg http://server:port
+
+ +
+
resource
+

The resource requested by a client, when the experimental HTTP server is in use. +

+
+
reply_code
+

The HTTP code returned to the client, when the experimental HTTP server is in use. +

+
+
short_seek_size
+

Set the threshold, in bytes, for when a readahead should be preferred over a seek and +new HTTP request. This is useful, for example, to make sure the same connection +is used for reading large video packets with small audio packets in between. +

+
+
+ + +

18.14.1 HTTP Cookies

+ +

Some HTTP requests will be denied unless cookie values are passed in with the +request. The cookies option allows these cookies to be specified. At +the very least, each cookie must specify a value along with a path and domain. +HTTP requests that match both the domain and path will automatically include the +cookie value in the HTTP Cookie header field. Multiple cookies can be delimited +by a newline. +

+

The required syntax to play a stream specifying a cookie is: +

+
ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
+
+ + +

18.15 Icecast

+ +

Icecast protocol (stream to Icecast servers) +

+

This protocol accepts the following options: +

+
+
ice_genre
+

Set the stream genre. +

+
+
ice_name
+

Set the stream name. +

+
+
ice_description
+

Set the stream description. +

+
+
ice_url
+

Set the stream website URL. +

+
+
ice_public
+

Set if the stream should be public. +The default is 0 (not public). +

+
+
user_agent
+

Override the User-Agent header. If not specified a string of the form +"Lavf/<version>" will be used. +

+
+
password
+

Set the Icecast mountpoint password. +

+
+
content_type
+

Set the stream content type. This must be set if it is different from +audio/mpeg. +

+
+
legacy_icecast
+

This enables support for Icecast versions < 2.4.0, that do not support the +HTTP PUT method but the SOURCE method. +

+
+
tls
+

Establish a TLS (HTTPS) connection to Icecast. +

+
+
+ +
+
icecast://[username[:password]@]server:port/mountpoint
+
+ + +

18.16 ipfs

+ +

InterPlanetary File System (IPFS) protocol support. One can access files stored +on the IPFS network through so-called gateways. These are http(s) endpoints. +This protocol wraps the IPFS native protocols (ipfs:// and ipns://) to be sent +to such a gateway. Users can (and should) host their own node which means this +protocol will use one’s local gateway to access files on the IPFS network. +

+

This protocol accepts the following options: +

+
+
gateway
+

Defines the gateway to use. When not set, the protocol will first try +locating the local gateway by looking at $IPFS_GATEWAY, $IPFS_PATH +and $HOME/.ipfs/, in that order. +

+
+
+ +

One can use this protocol in 2 ways. Using IPFS: +

+
ffplay ipfs://<hash>
+
+ +

Or the IPNS protocol (IPNS is mutable IPFS): +

+
ffplay ipns://<hash>
+
+ + +

18.17 mmst

+ +

MMS (Microsoft Media Server) protocol over TCP. +

+ +

18.18 mmsh

+ +

MMS (Microsoft Media Server) protocol over HTTP. +

+

The required syntax is: +

+
mmsh://server[:port][/app][/playpath]
+
+ + +

18.19 md5

+ +

MD5 output protocol. +

+

Computes the MD5 hash of the data to be written, and on close writes +this to the designated output or stdout if none is specified. It can +be used to test muxers without writing an actual file. +

+

Some examples follow. +

+
# Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
+ffmpeg -i input.flv -f avi -y md5:output.avi.md5
+
+# Write the MD5 hash of the encoded AVI file to stdout.
+ffmpeg -i input.flv -f avi -y md5:
+
+ +

Note that some formats (typically MOV) require the output protocol to +be seekable, so they will fail with the MD5 output protocol. +

+ +

18.20 pipe

+ +

UNIX pipe access protocol. +

+

Read and write from UNIX pipes. +

+

The accepted syntax is: +

+
pipe:[number]
+
+ +

If fd isn’t specified, number is the number corresponding to the file descriptor of the +pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If number +is not specified, by default the stdout file descriptor will be used +for writing, stdin for reading. +

+

For example to read from stdin with ffmpeg: +

+
cat test.wav | ffmpeg -i pipe:0
+# ...this is the same as...
+cat test.wav | ffmpeg -i pipe:
+
+ +

For writing to stdout with ffmpeg: +

+
ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
+# ...this is the same as...
+ffmpeg -i test.wav -f avi pipe: | cat > test.avi
+
+ +

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +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. +

+
fd
+

Set file descriptor. +

+
+ +

Note that some formats (typically MOV), require the output protocol to +be seekable, so they will fail with the pipe output protocol. +

+ +

18.21 prompeg

+ +

Pro-MPEG Code of Practice #3 Release 2 FEC protocol. +

+

The Pro-MPEG CoP#3 FEC is a 2D parity-check forward error correction mechanism +for MPEG-2 Transport Streams sent over RTP. +

+

This protocol must be used in conjunction with the rtp_mpegts muxer and +the rtp protocol. +

+

The required syntax is: +

+
-f rtp_mpegts -fec prompeg=option=val... rtp://hostname:port
+
+ +

The destination UDP ports are port + 2 for the column FEC stream +and port + 4 for the row FEC stream. +

+

This protocol accepts the following options: +

+
l=n
+

The number of columns (4-20, LxD <= 100) +

+
+
d=n
+

The number of rows (4-20, LxD <= 100) +

+
+
+ +

Example usage: +

+
+
-f rtp_mpegts -fec prompeg=l=8:d=4 rtp://hostname:port
+
+ + +

18.22 rist

+ +

Reliable Internet Streaming Transport protocol +

+

The accepted options are: +

+
rist_profile
+

Supported values: +

+
‘simple’
+
‘main’
+

This one is default. +

+
‘advanced’
+
+ +
+
buffer_size
+

Set internal RIST buffer size in milliseconds for retransmission of data. +Default value is 0 which means the librist default (1 sec). Maximum value is 30 +seconds. +

+
+
fifo_size
+

Size of the librist receiver output fifo in number of packets. This must be a +power of 2. +Defaults to 8192 (vs the librist default of 1024). +

+
+
overrun_nonfatal=1|0
+

Survive in case of librist fifo buffer overrun. Default value is 0. +

+
+
pkt_size
+

Set maximum packet size for sending data. 1316 by default. +

+
+
log_level
+

Set loglevel for RIST logging messages. You only need to set this if you +explicitly want to enable debug level messages or packet loss simulation, +otherwise the regular loglevel is respected. +

+
+
secret
+

Set override of encryption secret, by default is unset. +

+
+
encryption
+

Set encryption type, by default is disabled. +Acceptable values are 128 and 256. +

+
+ + +

18.23 rtmp

+ +

Real-Time Messaging Protocol. +

+

The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia +content across a TCP/IP network. +

+

The required syntax is: +

+
rtmp://[username:password@]server[:port][/app][/instance][/playpath]
+
+ +

The accepted parameters are: +

+
username
+

An optional username (mostly for publishing). +

+
+
password
+

An optional password (mostly for publishing). +

+
+
server
+

The address of the RTMP server. +

+
+
port
+

The number of the TCP port to use (by default is 1935). +

+
+
app
+

It is the name of the application to access. It usually corresponds to +the path where the application is installed on the RTMP server +(e.g. /ondemand/, /flash/live/, etc.). You can override +the value parsed from the URI through the rtmp_app option, too. +

+
+
playpath
+

It is the path or name of the resource to play with reference to the +application specified in app, may be prefixed by "mp4:". You +can override the value parsed from the URI through the rtmp_playpath +option, too. +

+
+
listen
+

Act as a server, listening for an incoming connection. +

+
+
timeout
+

Maximum time to wait for the incoming connection. Implies listen. +

+
+ +

Additionally, the following parameters can be set via command line options +(or in code via AVOptions): +

+
rtmp_app
+

Name of application to connect on the RTMP server. This option +overrides the parameter specified in the URI. +

+
+
rtmp_buffer
+

Set the client buffer time in milliseconds. The default is 3000. +

+
+
rtmp_conn
+

Extra arbitrary AMF connection parameters, parsed from a string, +e.g. like B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0. +Each value is prefixed by a single character denoting the type, +B for Boolean, N for number, S for string, O for object, or Z for null, +followed by a colon. For Booleans the data must be either 0 or 1 for +FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or +1 to end or begin an object, respectively. Data items in subobjects may +be named, by prefixing the type with ’N’ and specifying the name before +the value (i.e. NB:myFlag:1). This option may be used multiple +times to construct arbitrary AMF sequences. +

+
+
rtmp_enhanced_codecs
+

Specify the list of codecs the client advertises to support in an +enhanced RTMP stream. This option should be set to a comma separated +list of fourcc values, like hvc1,av01,vp09 for multiple codecs +or hvc1 for only one codec. The specified list will be presented +in the "fourCcLive" property of the Connect Command Message. +

+
+
rtmp_flashver
+

Version of the Flash plugin used to run the SWF player. The default +is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; +<libavformat version>).) +

+
+
rtmp_flush_interval
+

Number of packets flushed in the same request (RTMPT only). The default +is 10. +

+
+
rtmp_live
+

Specify that the media is a live stream. No resuming or seeking in +live streams is possible. The default value is any, which means the +subscriber first tries to play the live stream specified in the +playpath. If a live stream of that name is not found, it plays the +recorded stream. The other possible values are live and +recorded. +

+
+
rtmp_pageurl
+

URL of the web page in which the media was embedded. By default no +value will be sent. +

+
+
rtmp_playpath
+

Stream identifier to play or to publish. This option overrides the +parameter specified in the URI. +

+
+
rtmp_subscribe
+

Name of live stream to subscribe to. By default no value will be sent. +It is only sent if the option is specified or if rtmp_live +is set to live. +

+
+
rtmp_swfhash
+

SHA256 hash of the decompressed SWF file (32 bytes). +

+
+
rtmp_swfsize
+

Size of the decompressed SWF file, required for SWFVerification. +

+
+
rtmp_swfurl
+

URL of the SWF player for the media. By default no value will be sent. +

+
+
rtmp_swfverify
+

URL to player swf file, compute hash/size automatically. +

+
+
rtmp_tcurl
+

URL of the target stream. Defaults to proto://host[:port]/app. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_keepalive=1|0
+

Enable the TCP keepalive mechanism to detect dead peers and help maintain long-lived idle connections. Default value is 0. +

+

Only the basic keepalive option (SO_KEEPALIVE) can be enabled or disabled. Platform-specific tuning parameters such as TCP_KEEPIDLE, TCP_KEEPINTVL, or TCP_KEEPCNT are not configurable and will use the operating system’s default values. +

+
+
+ +

For example to read with ffplay a multimedia resource named +"sample" from the application "vod" from an RTMP server "myserver": +

+
ffplay rtmp://myserver/vod/sample
+
+ +

To publish to a password protected server, passing the playpath and +app names separately: +

+
ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@myserver/
+
+ + +

18.24 rtmpe

+ +

Encrypted Real-Time Messaging Protocol. +

+

The Encrypted Real-Time Messaging Protocol (RTMPE) is used for +streaming multimedia content within standard cryptographic primitives, +consisting of Diffie-Hellman key exchange and HMACSHA256, generating +a pair of RC4 keys. +

+ +

18.25 rtmps

+ +

Real-Time Messaging Protocol over a secure SSL connection. +

+

The Real-Time Messaging Protocol (RTMPS) is used for streaming +multimedia content across an encrypted connection. +

+ +

18.26 rtmpt

+ +

Real-Time Messaging Protocol tunneled through HTTP. +

+

The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used +for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

18.27 rtmpte

+ +

Encrypted Real-Time Messaging Protocol tunneled through HTTP. +

+

The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) +is used for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

18.28 rtmpts

+ +

Real-Time Messaging Protocol tunneled through HTTPS. +

+

The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used +for streaming multimedia content within HTTPS requests to traverse +firewalls. +

+ +

18.29 libsmbclient

+ +

libsmbclient permits one to manipulate CIFS/SMB network resources. +

+

Following syntax is required. +

+
+
smb://[[domain:]user[:password@]]server[/share[/path[/file]]]
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in milliseconds 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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
workgroup
+

Set the workgroup used for making connections. By default workgroup is not specified. +

+
+
+ +

For more information see: http://www.samba.org/. +

+ +

18.30 libssh

+ +

Secure File Transfer Protocol via libssh +

+

Read from or write to remote resources using SFTP protocol. +

+

Following syntax is required. +

+
+
sftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
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. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
private_key
+

Specify the path of the file containing private key to use during authorization. +By default libssh searches for keys in the ~/.ssh/ directory. +

+
+
+ +

Example: Play a file stored on remote server. +

+
+
ffplay sftp://user:password@server_address:22/home/user/resource.mpeg
+
+ + +

18.31 librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte

+ +

Real-Time Messaging Protocol and its variants supported through +librtmp. +

+

Requires the presence of the librtmp headers and library during +configuration. You need to explicitly configure the build with +"–enable-librtmp". If enabled this will replace the native RTMP +protocol. +

+

This protocol provides most client functions and a few server +functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), +encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled +variants of these encrypted types (RTMPTE, RTMPTS). +

+

The required syntax is: +

+
rtmp_proto://server[:port][/app][/playpath] options
+
+ +

where rtmp_proto is one of the strings "rtmp", "rtmpt", "rtmpe", +"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and +server, port, app and playpath have the same +meaning as specified for the RTMP native protocol. +options contains a list of space-separated options of the form +key=val. +

+

See the librtmp manual page (man 3 librtmp) for more information. +

+

For example, to stream a file in real-time to an RTMP server using +ffmpeg: +

+
ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
+
+ +

To play the same stream using ffplay: +

+
ffplay "rtmp://myserver/live/mystream live=1"
+
+ + +

18.32 rtp

+ +

Real-time Transport Protocol. +

+

The required syntax for an RTP URL is: +

+
rtp://hostname[:port][?options]
+
+ +

port specifies the RTP port to use. +

+

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ttl=n
+

Set the TTL (Time-To-Live) value (for multicast only). +

+
+
rtcpport=n
+

Set the remote RTCP port to n. +

+
+
localport, local_rtpport, localrtpport=n
+

Set the local RTP port to n. +

+

Using the localport option name is deprecated and should not be used. +

+
+
local_rtcpport, localrtcpport=n'
+

Set the local RTCP port to n. +

+
+
pkt_size=n
+

Set max packet size (in bytes) to n. +

+
+
buffer_size=size
+

Set the maximum UDP socket buffer size in bytes. +

+
+
connect=0|1
+

Do a connect() on the UDP socket (if set to 1) or not (if set +to 0). +

+
+
sources=ip[,ip]
+

List allowed source IP addresses. +

+
+
block=ip[,ip]
+

List disallowed (blocked) source IP addresses. +

+
+
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). +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
timeout=n
+

Set timeout (in microseconds) of socket I/O operations to n. +

+
+ +

Important notes: +

+
    +
  1. If rtcpport is not set the RTCP port will be set to the RTP +port value plus 1. + +
  2. If localrtpport (the local RTP port) is not set any available +port will be used for the local RTP and RTCP ports. + +
  3. If localrtcpport (the local RTCP port) is not set it will be +set to the local RTP port value plus 1. +
+ + +

18.33 rtsp

+ +

Real-Time Streaming Protocol. +

+

RTSP is not technically a protocol handler in libavformat, it is a demuxer +and muxer. The demuxer supports both normal RTSP (with data transferred +over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with +data transferred over RDT). +

+

The muxer can be used to send a stream using RTSP ANNOUNCE to a server +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock’s +RTSP server). +

+

The required syntax for a RTSP url is: +

+
rtsp://hostname[:port]/path
+
+ +

Options can be set on the ffmpeg/ffplay command +line, or set in code via AVOptions or in +avformat_open_input. +

+ +

18.33.1 Muxer

+

The following options are supported. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+ +

Default value is ‘0’. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘latm’
+

Use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC. +

+
‘rfc2190’
+

Use RFC 2190 packetization instead of RFC 4629 for H.263. +

+
‘skip_rtcp’
+

Don’t send RTCP sender reports. +

+
‘h264_mode0’
+

Use mode 0 for H.264 in RTP. +

+
‘send_bye’
+

Send RTCP BYE packets when finishing. +

+
+ +

Default value is ‘0’. +

+ +
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+
pkt_size
+

Set max send packet size (in bytes). Default value is 1472. +

+
+ + +

18.33.2 Demuxer

+

The following options are supported. +

+
+
initial_pause
+

Do not start playing the stream immediately if set to 1. Default value +is 0. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+
‘udp_multicast’
+

Use UDP multicast as lower transport protocol. +

+
+
‘http’
+

Use HTTP tunneling as lower transport protocol, which is useful for +passing proxies. +

+
+
‘https’
+

Use HTTPs tunneling as lower transport protocol, which is useful for +passing proxies and widely used for security consideration. +

+
+ +

Multiple lower transport protocols may be specified, in that case they are +tried one at a time (if the setup of one fails, the next one is tried). +For the muxer, only the ‘tcp’ and ‘udp’ options are supported. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘filter_src’
+

Accept packets only from negotiated peer address and port. +

+
‘listen’
+

Act as a server, listening for an incoming connection. +

+
‘prefer_tcp’
+

Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. +

+
‘satip_raw’
+

Export raw MPEG-TS stream instead of demuxing. The flag will simply write out +the raw stream, with the original PAT/PMT/PIDs intact. +

+
+ +

Default value is ‘none’. +

+
+
allowed_media_types
+

Set media types to accept from the server. +

+

The following flags are accepted: +

+
‘video’
+
‘audio’
+
‘data’
+
‘subtitle’
+
+ +

By default it accepts all media types. +

+
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
listen_timeout
+

Set maximum timeout (in seconds) to establish an initial connection. Setting +listen_timeout > 0 sets rtsp_flags to ‘listen’. Default is -1 +which means an infinite timeout when ‘listen’ mode is set. +

+
+
reorder_queue_size
+

Set number of packets to buffer for handling of reordered packets. +

+
+
timeout
+

Set socket TCP I/O timeout in microseconds. +

+
+
user_agent
+

Override User-Agent header. If not specified, it defaults to the +libavformat identifier string. +

+
+
buffer_size
+

Set the maximum socket buffer size in bytes. +

+
+ +

When receiving data over UDP, the demuxer tries to reorder received packets +(since they may arrive out of order, or packets may get lost totally). This +can be disabled by setting the maximum demuxing delay to zero (via +the max_delay field of AVFormatContext). +

+

When watching multi-bitrate Real-RTSP streams with ffplay, the +streams to display can be chosen with -vst n and +-ast n for video and audio respectively, and can be switched +on the fly by pressing v and a. +

+ +

18.33.3 Examples

+ +

The following examples all make use of the ffplay and +ffmpeg tools. +

+
    +
  • Watch a stream over UDP, with a max reordering delay of 0.5 seconds: +
    +
    ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
    +
    + +
  • Watch a stream tunneled over HTTP: +
    +
    ffplay -rtsp_transport http rtsp://server/video.mp4
    +
    + +
  • Send a stream in realtime to a RTSP server, for others to watch: +
    +
    ffmpeg -re -i input -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
    +
    + +
  • Receive a stream in realtime: +
    +
    ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp output
    +
    +
+ + +

18.34 sap

+ +

Session Announcement Protocol (RFC 2974). This is not technically a +protocol handler in libavformat, it is a muxer and demuxer. +It is used for signalling of RTP streams, by announcing the SDP for the +streams regularly on a separate port. +

+ +

18.34.1 Muxer

+ +

The syntax for a SAP url given to the muxer is: +

+
sap://destination[:port][?options]
+
+ +

The RTP packets are sent to destination on port port, +or to port 5004 if no port is specified. +options is a &-separated list. The following options +are supported: +

+
+
announce_addr=address
+

Specify the destination IP address for sending the announcements to. +If omitted, the announcements are sent to the commonly used SAP +announcement multicast address 224.2.127.254 (sap.mcast.net), or +ff0e::2:7ffe if destination is an IPv6 address. +

+
+
announce_port=port
+

Specify the port to send the announcements on, defaults to +9875 if not specified. +

+
+
ttl=ttl
+

Specify the time to live value for the announcements and RTP packets, +defaults to 255. +

+
+
same_port=0|1
+

If set to 1, send all RTP streams on the same port pair. If zero (the +default), all streams are sent on unique ports, with each stream on a +port 2 numbers higher than the previous. +VLC/Live555 requires this to be set to 1, to be able to receive the stream. +The RTP stack in libavformat for receiving requires all streams to be sent +on unique ports. +

+
+ +

Example command lines follow. +

+

To broadcast a stream on the local subnet, for watching in VLC: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255?same_port=1
+
+ +

Similarly, for watching in ffplay: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255
+
+ +

And for watching in ffplay, over IPv6: +

+
+
ffmpeg -re -i input -f sap sap://[ff0e::1:2:3:4]
+
+ + +

18.34.2 Demuxer

+ +

The syntax for a SAP url given to the demuxer is: +

+
sap://[address][:port]
+
+ +

address is the multicast address to listen for announcements on, +if omitted, the default 224.2.127.254 (sap.mcast.net) is used. port +is the port that is listened on, 9875 if omitted. +

+

The demuxers listens for announcements on the given address and port. +Once an announcement is received, it tries to receive that particular stream. +

+

Example command lines follow. +

+

To play back the first stream announced on the normal SAP multicast address: +

+
+
ffplay sap://
+
+ +

To play back the first stream announced on one the default IPv6 SAP multicast address: +

+
+
ffplay sap://[ff0e::2:7ffe]
+
+ + +

18.35 sctp

+ +

Stream Control Transmission Protocol. +

+

The accepted URL syntax is: +

+
sctp://host:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen
+

If set to any value, listen for an incoming connection. Outgoing connection is done by default. +

+
+
max_streams
+

Set the maximum number of streams. By default no limit is set. +

+
+ + +

18.36 srt

+ +

Haivision Secure Reliable Transport Protocol via libsrt. +

+

The supported syntax for a SRT URL is: +

+
srt://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
connect_timeout=milliseconds
+

Connection timeout; SRT cannot connect for RTT > 1500 msec +(2 handshake exchanges) with the default connect timeout of +3 seconds. This option applies to the caller and rendezvous +connection modes. The connect timeout is 10 times the value +set for the rendezvous mode (which can be used as a +workaround for this connection problem with earlier versions). +

+
+
ffs=bytes
+

Flight Flag Size (Window Size), in bytes. FFS is actually an +internal parameter and you should set it to not less than +recv_buffer_size and mss. The default value +is relatively large, therefore unless you set a very large receiver buffer, +you do not need to change this option. Default value is 25600. +

+
+
inputbw=bytes/seconds
+

Sender nominal input rate, in bytes per seconds. Used along with +oheadbw, when maxbw is set to relative (0), to +calculate maximum sending rate when recovery packets are sent +along with the main media stream: +inputbw * (100 + oheadbw) / 100 +if inputbw is not set while maxbw is set to +relative (0), the actual input rate is evaluated inside +the library. Default value is 0. +

+
+
iptos=tos
+

IP Type of Service. Applies to sender only. Default value is 0xB8. +

+
+
ipttl=ttl
+

IP Time To Live. Applies to sender only. Default value is 64. +

+
+
latency=microseconds
+

Timestamp-based Packet Delivery Delay. +Used to absorb bursts of missed packet retransmissions. +This flag sets both rcvlatency and peerlatency +to the same value. Note that prior to version 1.3.0 +this is the only flag to set the latency, however +this is effectively equivalent to setting peerlatency, +when side is sender and rcvlatency +when side is receiver, and the bidirectional stream +sending is not supported. +

+
+
listen_timeout=microseconds
+

Set socket listen timeout. +

+
+
maxbw=bytes/seconds
+

Maximum sending bandwidth, in bytes per seconds. +-1 infinite (CSRTCC limit is 30mbps) +0 relative to input rate (see inputbw) +>0 absolute limit value +Default value is 0 (relative) +

+
+
mode=caller|listener|rendezvous
+

Connection mode. +caller opens client connection. +listener starts server to listen for incoming connections. +rendezvous use Rendez-Vous connection mode. +Default value is caller. +

+
+
mss=bytes
+

Maximum Segment Size, in bytes. Used for buffer allocation +and rate calculation using a packet counter assuming fully +filled packets. The smallest MSS between the peers is +used. This is 1500 by default in the overall internet. +This is the maximum size of the UDP packet and can be +only decreased, unless you have some unusual dedicated +network settings. Default value is 1500. +

+
+
nakreport=1|0
+

If set to 1, Receiver will send ‘UMSG_LOSSREPORT‘ messages +periodically until a lost packet is retransmitted or +intentionally dropped. Default value is 1. +

+
+
oheadbw=percents
+

Recovery bandwidth overhead above input rate, in percents. +See inputbw. Default value is 25%. +

+
+
passphrase=string
+

HaiCrypt Encryption/Decryption Passphrase string, length +from 10 to 79 characters. The passphrase is the shared +secret between the sender and the receiver. It is used +to generate the Key Encrypting Key using PBKDF2 +(Password-Based Key Derivation Function). It is used +only if pbkeylen is non-zero. It is used on +the receiver only if the received data is encrypted. +The configured passphrase cannot be recovered (write-only). +

+
+
enforced_encryption=1|0
+

If true, both connection parties must have the same password +set (including empty, that is, with no encryption). If the +password doesn’t match or only one side is unencrypted, +the connection is rejected. Default is true. +

+
+
kmrefreshrate=packets
+

The number of packets to be transmitted after which the +encryption key is switched to a new key. Default is -1. +-1 means auto (0x1000000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
kmpreannounce=packets
+

The interval between when a new encryption key is sent and +when switchover occurs. This value also applies to the +subsequent interval between when switchover occurs and +when the old encryption key is decommissioned. Default is -1. +-1 means auto (0x1000 in srt library). The range for +this option is integers in the 0 - INT_MAX. +

+
+
snddropdelay=microseconds
+

The sender’s extra delay before dropping packets. This delay is +added to the default drop delay time interval value. +

+

Special value -1: Do not drop packets on the sender at all. +

+
+
payload_size=bytes
+

Sets the maximum declared size of a packet transferred +during the single call to the sending function in Live +mode. Use 0 if this value isn’t used (which is default in +file mode). +Default is -1 (automatic), which typically means MPEG-TS; +if you are going to use SRT +to send any different kind of payload, such as, for example, +wrapping a live stream in very small frames, then you can +use a bigger maximum frame size, though not greater than +1456 bytes. +

+
+
pkt_size=bytes
+

Alias for ‘payload_size’. +

+
+
peerlatency=microseconds
+

The latency value (as described in rcvlatency) that is +set by the sender side as a minimum value for the receiver. +

+
+
pbkeylen=bytes
+

Sender encryption key length, in bytes. +Only can be set to 0, 16, 24 and 32. +Enable sender encryption if not 0. +Not required on receiver (set to 0), +key size obtained from sender in HaiCrypt handshake. +Default value is 0. +

+
+
rcvlatency=microseconds
+

The time that should elapse since the moment when the +packet was sent and the moment when it’s delivered to +the receiver application in the receiving function. +This time should be a buffer time large enough to cover +the time spent for sending, unexpectedly extended RTT +time, and the time needed to retransmit the lost UDP +packet. The effective latency value will be the maximum +of this options’ value and the value of peerlatency +set by the peer side. Before version 1.3.0 this option +is only available as latency. +

+
+
recv_buffer_size=bytes
+

Set UDP receive buffer size, expressed in bytes. +

+
+
send_buffer_size=bytes
+

Set UDP send buffer size, expressed in bytes. +

+
+
timeout=microseconds
+

Set raise error timeouts for read, write and connect operations. Note that the +SRT library has internal timeouts which can be controlled separately, the +value set here is only a cap on those. +

+
+
tlpktdrop=1|0
+

Too-late Packet Drop. When enabled on receiver, it skips +missing packets that have not been delivered in time and +delivers the following packets to the application when +their time-to-play has come. It also sends a fake ACK to +the sender. When enabled on sender and enabled on the +receiving peer, the sender drops the older packets that +have no chance of being delivered in time. It was +automatically enabled in the sender if the receiver +supports it. +

+
+
sndbuf=bytes
+

Set send buffer size, expressed in bytes. +

+
+
rcvbuf=bytes
+

Set receive buffer size, expressed in bytes. +

+

Receive buffer must not be greater than ffs. +

+
+
lossmaxttl=packets
+

The value up to which the Reorder Tolerance may grow. When +Reorder Tolerance is > 0, then packet loss report is delayed +until that number of packets come in. Reorder Tolerance +increases every time a "belated" packet has come, but it +wasn’t due to retransmission (that is, when UDP packets tend +to come out of order), with the difference between the latest +sequence and this packet’s sequence, and not more than the +value of this option. By default it’s 0, which means that this +mechanism is turned off, and the loss report is always sent +immediately upon experiencing a "gap" in sequences. +

+
+
minversion
+

The minimum SRT version that is required from the peer. A connection +to a peer that does not satisfy the minimum version requirement +will be rejected. +

+

The version format in hex is 0xXXYYZZ for x.y.z in human readable +form. +

+
+
streamid=string
+

A string limited to 512 characters that can be set on the socket prior +to connecting. This stream ID will be able to be retrieved by the +listener side from the socket that is returned from srt_accept and +was connected by a socket with that set stream ID. SRT does not enforce +any special interpretation of the contents of this string. +This option doesn’t make sense in Rendezvous connection; the result +might be that simply one side will override the value from the other +side and it’s the matter of luck which one would win +

+
+
srt_streamid=string
+

Alias for ‘streamid’ to avoid conflict with ffmpeg command line option. +

+
+
smoother=live|file
+

The type of Smoother used for the transmission for that socket, which +is responsible for the transmission and congestion control. The Smoother +type must be exactly the same on both connecting parties, otherwise +the connection is rejected. +

+
+
messageapi=1|0
+

When set, this socket uses the Message API, otherwise it uses Buffer +API. Note that in live mode (see transtype) there’s only +message API available. In File mode you can chose to use one of two modes: +

+

Stream API (default, when this option is false). In this mode you may +send as many data as you wish with one sending instruction, or even use +dedicated functions that read directly from a file. The internal facility +will take care of any speed and congestion control. When receiving, you +can also receive as many data as desired, the data not extracted will be +waiting for the next call. There is no boundary between data portions in +the Stream mode. +

+

Message API. In this mode your single sending instruction passes exactly +one piece of data that has boundaries (a message). Contrary to Live mode, +this message may span across multiple UDP packets and the only size +limitation is that it shall fit as a whole in the sending buffer. The +receiver shall use as large buffer as necessary to receive the message, +otherwise the message will not be given up. When the message is not +complete (not all packets received or there was a packet loss) it will +not be given up. +

+
+
transtype=live|file
+

Sets the transmission type for the socket, in particular, setting this +option sets multiple other parameters to their default values as required +for a particular transmission type. +

+

live: Set options as for live transmission. In this mode, you should +send by one sending instruction only so many data that fit in one UDP packet, +and limited to the value defined first in payload_size (1316 is +default in this mode). There is no speed control in this mode, only the +bandwidth control, if configured, in order to not exceed the bandwidth with +the overhead transmission (retransmitted and control packets). +

+

file: Set options as for non-live transmission. See messageapi +for further explanations +

+
+
linger=seconds
+

The number of seconds that the socket waits for unsent data when closing. +Default is -1. -1 means auto (off with 0 seconds in live mode, on with 180 +seconds in file mode). The range for this option is integers in the +0 - INT_MAX. +

+
+
tsbpd=1|0
+

When true, use Timestamp-based Packet Delivery mode. The default behavior +depends on the transmission type: enabled in live mode, disabled in file +mode. +

+
+
+ +

For more information see: https://github.com/Haivision/srt. +

+ +

18.37 srtp

+ +

Secure Real-time Transport Protocol. +

+

The accepted options are: +

+
srtp_in_suite
+
srtp_out_suite
+

Select input and output encoding suites. +

+

Supported values: +

+
‘AES_CM_128_HMAC_SHA1_80’
+
‘SRTP_AES128_CM_HMAC_SHA1_80’
+
‘AES_CM_128_HMAC_SHA1_32’
+
‘SRTP_AES128_CM_HMAC_SHA1_32’
+
+ +
+
srtp_in_params
+
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. +

+
+ + +

18.38 subfile

+ +

Virtually extract a segment of a file or another stream. +The underlying stream must be seekable. +

+

Accepted options: +

+
start
+

Start offset of the extracted segment, in bytes. +

+
end
+

End offset of the extracted segment, in bytes. +If set to 0, extract till end of file. +

+
+ +

Examples: +

+

Extract a chapter from a DVD VOB file (start and end sectors obtained +externally and multiplied by 2048): +

+
subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
+
+ +

Play an AVI file directly from a TAR archive: +

+
subfile,,start,183241728,end,366490624,,:archive.tar
+
+ +

Play a MPEG-TS file from start offset till end: +

+
subfile,,start,32815239,end,0,,:video.ts
+
+ + +

18.39 tee

+ +

Writes the output to multiple protocols. The individual outputs are separated +by | +

+
+
tee:file://path/to/local/this.avi|file://path/to/local/that.avi
+
+ + +

18.40 tcp

+ +

Transmission Control Protocol. +

+

The required syntax for a TCP url is: +

+
tcp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
listen=2|1|0
+

Listen for an incoming connection. 0 disables listen, 1 enables listen in +single client mode, 2 enables listen in multi-client mode. Default value is 0. +

+
+
local_addr=addr
+

Local IP address of a network interface used for tcp socket connect. +

+
+
local_port=port
+

Local port used for tcp socket connect. +

+
+
timeout=microseconds
+

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. +

+
+
listen_timeout=milliseconds
+

Set listen timeout, expressed in milliseconds. +

+
+
recv_buffer_size=bytes
+

Set receive buffer size, expressed bytes. +

+
+
send_buffer_size=bytes
+

Set send buffer size, expressed bytes. +

+
+
tcp_nodelay=1|0
+

Set TCP_NODELAY to disable Nagle’s algorithm. Default value is 0. +

+

Remark: Writing to the socket is currently not optimized to minimize system calls and reduces the efficiency / effect of TCP_NODELAY. +

+
+
tcp_mss=bytes
+

Set maximum segment size for outgoing TCP packets, expressed in bytes. +

+
+ +

The following example shows how to setup a listening TCP connection +with ffmpeg, which is then accessed with ffplay: +

+
ffmpeg -i input -f format tcp://hostname:port?listen
+ffplay tcp://hostname:port
+
+ + +

18.41 tls

+ +

Transport Layer Security (TLS) / Secure Sockets Layer (SSL) +

+

The required syntax for a TLS/SSL url is: +

+
tls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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 other backends, +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. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
http_proxy
+

The HTTP proxy to tunnel through, e.g. http://example.com:1234. +The proxy must support the CONNECT method. +

+
+
+ +

Example command lines: +

+

To create a TLS/SSL server that serves an input stream. +

+
+
ffmpeg -i input -f format tls://hostname:port?listen&cert=server.crt&key=server.key
+
+ +

To play back a stream from the TLS/SSL server using ffplay: +

+
+
ffplay tls://hostname:port
+
+ + +

18.42 dtls

+ +

Datagram Transport Layer Security (DTLS) +

+

The required syntax for a DTLS URL is: +

+
dtls://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

DTLS shares most options with TLS, but operates over UDP instead of TCP. +

+

The list of supported options follows. +

+
+
ca_file, cafile=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. +

+
+
tls_verify, verify=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. +

+

This is disabled by default since it requires a CA database to be +provided by the caller in many cases. +

+
+
cert_file, cert=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.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
cert_pem=string
+

Certificate PEM string +

+
+
key_pem=string
+

Private key PEM string +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
mtu=size
+

Set the Maximum Transmission Unit (MTU) for DTLS packets. +

+
+
use_srtp=1|0
+

Enable the use_srtp DTLS extension. +This is used in WebRTC applications to establish SRTP encryption keys +through the DTLS handshake. Default is disabled. +

+
+
external_sock=1|0
+

Use an external socket instead of creating a new one. +This option only makes sense to pass when interacting with the code via +API, enabling this from CLI will cause immediate failure. +Default is disabled. +

+
+
+ +

Example command lines: +

+

To create a DTLS server: +

+
+
ffmpeg -listen 1 -i dtls://hostname:port output
+
+ +

To create a DTLS client and send data to server: +

+
+
ffmpeg -i input -f format dtls://hostname:port
+
+ + +

18.43 udp

+ +

User Datagram Protocol. +

+

The required syntax for an UDP URL is: +

+
udp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. Standard percent-encoding (and using the plus sign for +space) can be used to escape keys and values. +

+

Options can also can be specified via command line options (or in code via +AVOptions). +

+

In case threading is enabled on the system, a circular buffer is used +to store the incoming data, which allows one to reduce loss of data due to +UDP socket buffer overruns. The fifo_size and +overrun_nonfatal options are related to this buffer. +

+

The list of supported options follows. +

+
+
buffer_size=size
+

Set the UDP maximum socket buffer size in bytes. This is used to set either +the receive or send buffer size, depending on what the socket is used for. +Default is 32 KB for output, 384 KB for input. See also fifo_size. +

+
+
bitrate=bitrate
+

If set to nonzero, the output will have the specified constant bitrate if the +input has enough packets to sustain it. +

+
+
burst_bits=bits
+

When using bitrate this specifies the maximum number of bits in +packet bursts. +

+
+
localport=port
+

Override the local UDP port to bind with. +

+
+
localaddr=addr
+

Local IP address of a network interface used for sending packets or joining +multicast groups. +

+
+
pkt_size=size
+

Set the size in bytes of UDP packets. +

+
+
reuse=1|0
+

Explicitly allow or disallow reusing UDP sockets. +

+
+
ttl=ttl
+

Set the time to live value (for multicast only). +

+
+
dscp=dscp
+

Set the 6-bit DSCP field for outgoing packets. +

+
+
connect=1|0
+

Initialize the UDP socket with connect(). In this case, the +destination address can’t be changed with ff_udp_set_remote_url later. +If the destination address isn’t known at the start, this option can +be specified in ff_udp_set_remote_url, too. +This allows finding out the source address for the packets with getsockname, +and makes writes return with AVERROR(ECONNREFUSED) if "destination +unreachable" is received. +For receiving, this gives the benefit of only receiving packets from +the specified peer address/port. +

+
+
sources=address[,address]
+

Only receive packets sent from the specified addresses. In case of multicast, +also subscribe to multicast traffic coming from these addresses only. +

+
+
block=address[,address]
+

Ignore packets sent from the specified addresses. In case of multicast, also +exclude the source addresses in the multicast subscription. +

+
+
fifo_size=units
+

Set the UDP receiving circular buffer size, expressed as a number of +packets with size of 188 bytes. If not specified defaults to 7*4096. +

+
+
overrun_nonfatal=1|0
+

Survive in case of UDP receiving circular buffer overrun. Default +value is 0. +

+
+
timeout=microseconds
+

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. +

+
+
broadcast=1|0
+

Explicitly allow or disallow UDP broadcasting. +

+

Note that broadcasting may not work properly on networks having +a broadcast storm protection. +

+
+ + +

18.43.1 Examples

+ +
    +
  • Use ffmpeg to stream over UDP to a remote endpoint: +
    +
    ffmpeg -i input -f format udp://hostname:port
    +
    + +
  • Use ffmpeg to stream in mpegts format over UDP using 188 +sized UDP packets, using a large input buffer: +
    +
    ffmpeg -i input -f mpegts udp://hostname:port?pkt_size=188&buffer_size=65535
    +
    + +
  • Use ffmpeg to receive over UDP from a remote endpoint: +
    +
    ffmpeg -i udp://[multicast-address]:port ...
    +
    +
+ + +

18.44 unix

+ +

Unix local socket +

+

The required syntax for a Unix socket URL is: +

+
+
unix://filepath
+
+ +

The following parameters can be set via command line options +(or in code via AVOptions): +

+
+
timeout
+

Timeout in ms. +

+
listen
+

Create the Unix socket in listening mode. +

+
type
+

Select socket type. +

+
‘stream Corresponds to SOCK_STREAM (reliable stream-oriented)’
+
‘datagram Corresponds to SOCK_DGRAM (unreliable packet-oriented)’
+
‘seqpacket Corresponds to SOCK_SEQPACKET (reliable packet-oriented)’
+
+
+
pkt_size
+

Maximum packet size for packet-oriented sockets (SOCK_DGRAM and +SOCK_SEQPACKET). If greater than zero, this value is used as +max_packet_size. Ignored for SOCK_STREAM. Default is 0. +

+
+ + +

18.45 zmq

+ +

ZeroMQ asynchronous messaging using the libzmq library. +

+

This library supports unicast streaming to multiple clients without relying on +an external server. +

+

The required syntax for streaming or connecting to a stream is: +

+
zmq:tcp://ip-address:port
+
+ +

Example: +Create a localhost stream on port 5555: +

+
ffmpeg -re -i input -f mpegts zmq:tcp://127.0.0.1:5555
+
+ +

Multiple clients may connect to the stream using: +

+
ffplay zmq:tcp://127.0.0.1:5555
+
+ +

Streaming to multiple clients is implemented using a ZeroMQ Pub-Sub pattern. +The server side binds to a port and publishes data. Clients connect to the +server (via IP address/port) and subscribe to the stream. The order in which +the server and client start generally does not matter. +

+

ffmpeg must be compiled with the –enable-libzmq option to support +this protocol. +

+

Options can be set on the ffmpeg/ffplay command +line. The following options are supported: +

+
+
pkt_size
+

Forces the maximum packet size for sending/receiving data. The default value is +131,072 bytes. On the server side, this sets the maximum size of sent packets +via ZeroMQ. On the clients, it sets an internal buffer size for receiving +packets. Note that pkt_size on the clients should be equal to or greater than +pkt_size on the server. Otherwise the received message may be truncated causing +decoding errors. +

+
+
+ + +

19 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 -option value in the +FFmpeg tools, or by setting the value explicitly in the device +AVFormatContext options or using the libavutil/opt.h API +for programmatic use. +

+ + +

20 Input Devices

+ +

Input devices are configured elements in FFmpeg which enable accessing +the data coming from a multimedia device attached to your system. +

+

When you configure your FFmpeg build, all the supported input devices +are enabled by default. You can list all available ones using the +configure option "–list-indevs". +

+

You can disable all the input devices using the configure option +"–disable-indevs", and selectively enable an input device using the +option "–enable-indev=INDEV", or you can disable a particular +input device using the option "–disable-indev=INDEV". +

+

The option "-devices" of the ff* tools will display the list of +supported input devices. +

+

A description of the currently available input devices follows. +

+ +

20.1 alsa

+ +

ALSA (Advanced Linux Sound Architecture) input device. +

+

To enable this input device during configuration you need libasound +installed on your system. +

+

This device allows capturing from an ALSA device. The name of the +device to capture has to be an ALSA card identifier. +

+

An ALSA identifier has the syntax: +

+
hw:CARD[,DEV[,SUBDEV]]
+
+ +

where the DEV and SUBDEV components are optional. +

+

The three arguments (in order: CARD,DEV,SUBDEV) +specify card number or identifier, device number and subdevice number +(-1 means any). +

+

To see the list of cards currently recognized by your system check the +files /proc/asound/cards and /proc/asound/devices. +

+

For example to capture with ffmpeg from an ALSA device with +card id 0, you may run the command: +

+
ffmpeg -f alsa -i hw:0 alsaout.wav
+
+ +

For more information see: +http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html +

+ +

20.1.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

20.2 android_camera

+ +

Android camera input device. +

+

This input devices uses the Android Camera2 NDK API which is +available on devices with API level 24+. The availability of +android_camera is autodetected during configuration. +

+

This device allows capturing from all cameras on an Android device, +which are integrated into the Camera2 NDK API. +

+

The available cameras are enumerated internally and can be selected +with the camera_index parameter. The input file string is +discarded. +

+

Generally the back facing camera has index 0 while the front facing +camera has index 1. +

+ +

20.2.1 Options

+ +
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Falls back to the first available configuration reported by +Android if requested video size is not available or by default. +

+
+
framerate
+

Set the video framerate. +Falls back to the first available configuration reported by +Android if requested framerate is not available or by default (-1). +

+
+
camera_index
+

Set the index of the camera to use. Default is 0. +

+
+
input_queue_size
+

Set the maximum number of frames to buffer. Default is 5. +

+
+
+ + +

20.3 avfoundation

+ +

AVFoundation input device. +

+

AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS. +

+

The input filename has to be given in the following syntax: +

+
-i "[[VIDEO]:[AUDIO]]"
+
+

The first entry selects the video input while the latter selects the audio input. +The stream has to be specified by the device name or the device index as shown by the device list. +Alternatively, the video and/or audio input device can be chosen by index using the + + -video_device_index <INDEX> + +and/or + + -audio_device_index <INDEX> + +, overriding any +device name or index given in the input filename. +

+

All available devices can be enumerated by using -list_devices true, listing +all device names and corresponding indices. +

+

There are two device name aliases: +

+
default
+

Select the AVFoundation default device of the corresponding type. +

+
+
none
+

Do not record the corresponding media type. +This is equivalent to specifying an empty device name or index. +

+
+
+ + +

20.3.1 Options

+ +

AVFoundation supports the following options: +

+
+
-list_devices <TRUE|FALSE>
+

If set to true, a list of all available input devices is given showing all +device names and indices. +

+
+
-video_device_index <INDEX>
+

Specify the video device by its index. Overrides anything given in the input filename. +

+
+
-audio_device_index <INDEX>
+

Specify the audio device by its index. Overrides anything given in the input filename. +

+
+
-pixel_format <FORMAT>
+

Request the video device to use a specific pixel format. +If the specified format is not supported, a list of available formats is given +and the first one in this list is used instead. Available pixel formats are: +monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0, + bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10, + yuv420p, nv12, yuyv422, gray +

+
+
-framerate
+

Set the grabbing frame rate. Default is ntsc, corresponding to a +frame rate of 30000/1001. +

+
+
-video_size
+

Set the video frame size. +

+
+
-capture_cursor
+

Capture the mouse pointer. Default is 0. +

+
+
-capture_mouse_clicks
+

Capture the screen mouse clicks. Default is 0. +

+
+
-capture_raw_data
+

Capture the raw device data. Default is 0. +Using this option may result in receiving the underlying data delivered to the AVFoundation framework. E.g. for muxed devices that sends raw DV data to the framework (like tape-based camcorders), setting this option to false results in extracted video frames captured in the designated pixel format only. Setting this option to true results in receiving the raw DV stream untouched. +

+
+ + +

20.3.2 Examples

+ +
    +
  • Print the list of AVFoundation supported devices and exit: +
    +
    $ ffmpeg -f avfoundation -list_devices true -i ""
    +
    + +
  • Record video from video device 0 and audio from audio device 0 into out.avi: +
    +
    $ ffmpeg -f avfoundation -i "0:0" out.avi
    +
    + +
  • Record video from video device 2 and audio from audio device 1 into out.avi: +
    +
    $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi
    +
    + +
  • Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi: +
    +
    $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi
    +
    + +
  • Record raw DV data from a suitable input device and write the output into out.dv: +
    +
    $ ffmpeg -f avfoundation -capture_raw_data true -i "zr100:none" out.dv
    +
    + + +
+ + +

20.4 decklink

+ +

The decklink input device provides capture capabilities for Blackmagic +DeckLink devices. +

+

To enable this input device, you need the Blackmagic DeckLink SDK and you +need to configure with the appropriate --extra-cflags +and --extra-ldflags. +On Windows, you need to run the IDL files through widl. +

+

DeckLink is very picky about the formats it supports. Pixel format of the +input can be set with raw_format. +Framerate and video size must be determined for your device with +-list_formats 1. Audio sample rate is always 48 kHz and the number +of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single +audio track. +

+ +

20.4.1 Options

+ +
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. This option is deprecated, please use the +-sources option of ffmpeg to list the available input devices. +

+
+
list_formats
+

If set to true, print a list of supported formats and exit. +Defaults to false. +

+
+
format_code <FourCC>
+

This sets the input video format to the format given by the FourCC. To see +the supported values of your device(s) use list_formats. +Note that there is a FourCC 'pal ' that can also be used +as pal (3 letters). +Default behavior is autodetection of the input video format, if the hardware +supports it. +

+
+
raw_format
+

Set the pixel format of the captured video. +Available values are: +

+
‘auto’
+
+

This is the default which means 8-bit YUV 422 or 8-bit ARGB if format +autodetection is used, 8-bit YUV 422 otherwise. +

+
+
‘uyvy422’
+
+

8-bit YUV 422. +

+
+
‘yuv422p10’
+
+

10-bit YUV 422. +

+
+
‘argb’
+
+

8-bit RGB. +

+
+
‘bgra’
+
+

8-bit RGB. +

+
+
‘rgb10’
+
+

10-bit RGB. +

+
+
+ +
+
teletext_lines
+

If set to nonzero, an additional teletext stream will be captured from the +vertical ancillary data. Both SD PAL (576i) and HD (1080i or 1080p) +sources are supported. In case of HD sources, OP47 packets are decoded. +

+

This option is a bitmask of the SD PAL VBI lines captured, specifically lines 6 +to 22, and lines 318 to 335. Line 6 is the LSB in the mask. Selected lines +which do not contain teletext information will be ignored. You can use the +special all constant to select all possible lines, or +standard to skip lines 6, 318 and 319, which are not compatible with +all receivers. +

+

For SD sources, ffmpeg needs to be compiled with --enable-libzvbi. For +HD sources, on older (pre-4K) DeckLink card models you have to capture in 10 +bit mode. +

+
+
channels
+

Defines number of audio channels to capture. Must be ‘2’, ‘8’ or ‘16’. +Defaults to ‘2’. +

+
+
duplex_mode
+

Sets the decklink device duplex/profile mode. Must be ‘unset’, ‘half’, ‘full’, +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +Defaults to ‘unset’. +

+

Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property. +For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 +sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile +is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles. +

+

Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0): +‘one_sub_device_full’, ‘one_sub_device_half’, ‘two_sub_device_full’, +‘four_sub_device_half’ +

+

Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2: +‘half’, ‘full’ +

+
+
timecode_format
+

Timecode type to include in the frame and video stream metadata. Must be +‘none’, ‘rp188vitc’, ‘rp188vitc2’, ‘rp188ltc’, +‘rp188hfr’, ‘rp188any’, ‘vitc’, ‘vitc2’, or ‘serial’. +Defaults to ‘none’ (not included). +

+

In order to properly support 50/60 fps timecodes, the ordering of the queried +timecode types for ‘rp188any’ is HFR, VITC1, VITC2 and LTC for >30 fps +content. Note that this is slightly different to the ordering used by the +DeckLink API, which is HFR, VITC1, LTC, VITC2. +

+
+
video_input
+

Sets the video input source. Must be ‘unset’, ‘sdi’, ‘hdmi’, +‘optical_sdi’, ‘component’, ‘composite’ or ‘s_video’. +Defaults to ‘unset’. +

+
+
audio_input
+

Sets the audio input source. Must be ‘unset’, ‘embedded’, +‘aes_ebu’, ‘analog’, ‘analog_xlr’, ‘analog_rca’ or +‘microphone’. Defaults to ‘unset’. +

+
+
video_pts
+

Sets the video packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘video’. +

+
+
audio_pts
+

Sets the audio packet timestamp source. Must be ‘video’, ‘audio’, +‘reference’, ‘wallclock’ or ‘abs_wallclock’. +Defaults to ‘audio’. +

+
+
draw_bars
+

If set to ‘true’, color bars are drawn in the event of a signal loss. +Defaults to ‘true’. +This option is deprecated, please use the signal_loss_action option. +

+
+
signal_loss_action
+

Sets the action to take in the event of a signal loss. Accepts one of the +following values: +

+
+
1, none
+

Do nothing on signal loss. This usually results in black frames. +

+
2, bars
+

Draw color bars on signal loss. Only supported for 8-bit input signals. +

+
3, repeat
+

Repeat the last video frame on signal loss. +

+
+ +

Defaults to ‘bars’. +

+
+
queue_size
+

Sets maximum input buffer size in bytes. If the buffering reaches this value, +incoming frames will be dropped. +Defaults to ‘1073741824’. +

+
+
audio_depth
+

Sets the audio sample bit depth. Must be ‘16’ or ‘32’. +Defaults to ‘16’. +

+
+
decklink_copyts
+

If set to true, timestamps are forwarded as they are without removing +the initial offset. +Defaults to false. +

+
+
timestamp_align
+

Capture start time alignment in seconds. If set to nonzero, input frames are +dropped till the system timestamp aligns with configured value. +Alignment difference of up to one frame duration is tolerated. +This is useful for maintaining input synchronization across N different +hardware devices deployed for ’N-way’ redundancy. The system time of different +hardware devices should be synchronized with protocols such as NTP or PTP, +before using this option. +Note that this method is not foolproof. In some border cases input +synchronization may not happen due to thread scheduling jitters in the OS. +Either sync could go wrong by 1 frame or in a rarer case +timestamp_align seconds. +Defaults to ‘0’. +

+
+
wait_for_tc (bool)
+

Drop frames till a frame with timecode is received. Sometimes serial timecode +isn’t received with the first input frame. If that happens, the stored stream +timecode will be inaccurate. If this option is set to true, input frames +are dropped till a frame with timecode is received. +Option timecode_format must be specified. +Defaults to false. +

+
+
enable_klv(bool)
+

If set to true, extracts KLV data from VANC and outputs KLV packets. +KLV VANC packets are joined based on MID and PSC fields and aggregated into +one KLV packet. +Defaults to false. +

+
+
+ + +

20.4.2 Examples

+ +
    +
  • List input devices: +
    +
    ffmpeg -sources decklink
    +
    + +
  • List supported formats: +
    +
    ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'
    +
    + +
  • Capture video clip at 1080i50: +
    +
    ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 10 bit: +
    +
    ffmpeg -raw_format yuv422p10 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
  • Capture video clip at 1080i50 with 16 audio channels: +
    +
    ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
    +
    + +
+ + +

20.5 dshow

+ +

Windows DirectShow input device. +

+

DirectShow support is enabled when FFmpeg is built with the mingw-w64 project. +Currently only audio and video devices are supported. +

+

Multiple devices may be opened as separate inputs, but they may also be +opened on the same input, which should improve synchronism between them. +

+

The input name should be in the format: +

+
+
TYPE=NAME[:TYPE=NAME]
+
+ +

where TYPE can be either audio or video, +and NAME is the device’s name or alternative name.. +

+ +

20.5.1 Options

+ +

If no options are specified, the device’s defaults are used. +If the device does not support the requested options, it will +fail to open. +

+
+
video_size
+

Set the video size in the captured video. +

+
+
framerate
+

Set the frame rate in the captured video. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. +

+
+
channels
+

Set the number of channels in the captured audio. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +

+
+
list_options
+

If set to true, print a list of selected device’s options +and exit. +

+
+
video_device_number
+

Set video device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
audio_device_number
+

Set audio device number for devices with the same name (starts at 0, +defaults to 0). +

+
+
pixel_format
+

Select pixel format to be used by DirectShow. This may only be set when +the video codec is not set or set to rawvideo. +

+
+
audio_buffer_size
+

Set audio device buffer size in milliseconds (which can directly +impact latency, depending on the device). +Defaults to using the audio device’s +default buffer size (typically some multiple of 500ms). +Setting this value too low can degrade performance. +See also +http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx +

+
+
video_pin_name
+

Select video capture pin to use by name or alternative name. +

+
+
audio_pin_name
+

Select audio capture pin to use by name or alternative name. +

+
+
crossbar_video_input_pin_number
+

Select video input pin number for crossbar device. This will be +routed to the crossbar device’s Video Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
crossbar_audio_input_pin_number
+

Select audio input pin number for crossbar device. This will be +routed to the crossbar device’s Audio Decoder output pin. +Note that changing this value can affect future invocations +(sets a new default) until system reboot occurs. +

+
+
show_video_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change video filter properties +and configurations manually. +Note that for crossbar devices, adjusting values in this dialog +may be needed at times to toggle between PAL (25 fps) and NTSC (29.97) +input frame rates, sizes, interlacing, etc. Changing these values can +enable different scan rates/frame rates and avoiding green bars at +the bottom, flickering scan lines, etc. +Note that with some devices, changing these properties can also affect future +invocations (sets new defaults) until system reboot occurs. +

+
+
show_audio_device_dialog
+

If set to true, before capture starts, popup a display dialog +to the end user, allowing them to change audio filter properties +and configurations manually. +

+
+
show_video_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens a video device. +

+
+
show_audio_crossbar_connection_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify crossbar pin routings, when it opens an audio device. +

+
+
show_analog_tv_tuner_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV channels and frequencies. +

+
+
show_analog_tv_tuner_audio_dialog
+

If set to true, before capture starts, popup a display +dialog to the end user, allowing them to manually +modify TV audio (like mono vs. stereo, Language A,B or C). +

+
+
audio_device_load
+

Load an audio capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this an audio capture source has to be specified, but it can +be anything even fake one. +

+
+
audio_device_save
+

Save the currently used audio capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
video_device_load
+

Load a video capture filter device from file instead of searching +it by name. It may load additional parameters too, if the filter +supports the serialization of its properties to. +To use this a video capture source has to be specified, but it can +be anything even fake one. +

+
+
video_device_save
+

Save the currently used video capture filter device and its +parameters (if the filter supports it) to a file. +If a file with the same name exists it will be overwritten. +

+
+
use_video_device_timestamps
+

If set to false, the timestamp for video frames will be +derived from the wallclock instead of the timestamp provided by +the capture device. This allows working around devices that +provide unreliable timestamps. +

+
+
+ + +

20.5.2 Examples

+ +
    +
  • Print the list of DirectShow supported devices and exit: +
    +
    $ ffmpeg -list_devices true -f dshow -i dummy
    +
    + +
  • Open video device Camera: +
    +
    $ ffmpeg -f dshow -i video="Camera"
    +
    + +
  • Open second video device with name Camera: +
    +
    $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"
    +
    + +
  • Open video device Camera and audio device Microphone: +
    +
    $ ffmpeg -f dshow -i video="Camera":audio="Microphone"
    +
    + +
  • Print the list of supported options in selected device and exit: +
    +
    $ ffmpeg -list_options true -f dshow -i video="Camera"
    +
    + +
  • Specify pin names to capture by name or alternative name, specify alternative device name: +
    +
    $ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\{ca465100-deb0-4d59-818f-8c477184adf6}":audio="Microphone"
    +
    + +
  • Configure a crossbar device, specifying crossbar pins, allow user to adjust video capture properties at startup: +
    +
    $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0
    +     -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"
    +
    + +
+ + +

20.6 fbdev

+ +

Linux framebuffer input 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 +/dev/fb0. +

+

For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. +

+

See also http://linux-fbdev.sourceforge.net/, and fbset(1). +

+

To record from the framebuffer device /dev/fb0 with +ffmpeg: +

+
ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi
+
+ +

You can take a single screenshot image with the command: +

+
ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg
+
+ + +

20.6.1 Options

+ +
+
framerate
+

Set the frame rate. Default is 25. +

+
+
+ + +

20.7 gdigrab

+ +

Win32 GDI-based screen capture device. +

+

This device allows you to capture a region of the display on Windows. +

+

Amongst options for the input filenames are such elements as: +

+
desktop
+
+

or +

+
title=window_title
+
+

or +

+
hwnd=window_hwnd
+
+ +

The first option will capture the entire desktop, or a fixed region of the +desktop. The second and third options will instead capture the contents of a single +window, regardless of its position on the screen. +

+

For example, to grab the entire desktop using ffmpeg: +

+
ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg
+
+ +

Grab a 640x480 region at position 10,20: +

+
ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg
+
+ +

Grab the contents of the window named "Calculator" +

+
ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg
+
+ + +

20.7.1 Options

+ +
+
draw_mouse
+

Specify whether to draw the mouse pointer. Use the value 0 to +not draw the pointer. Default value is 1. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+

Note that show_region is incompatible with grabbing the contents +of a single window. +

+

For example: +

+
ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg
+
+ +
+
video_size
+

Set the video frame size. The default is to capture the full screen if desktop is selected, or the full window size if title=window_title is selected. +

+
+
offset_x
+

When capturing a region with video_size, set the distance from the left edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned to the left of your primary monitor, you will need to use a negative offset_x value to move the region to that monitor. +

+
+
offset_y
+

When capturing a region with video_size, set the distance from the top edge of the screen or desktop. +

+

Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned above your primary monitor, you will need to use a negative offset_y value to move the region to that monitor. +

+
+
+ + +

20.8 iec61883

+ +

FireWire DV/HDV input device using libiec61883. +

+

To enable this input device, you need libiec61883, libraw1394 and +libavc1394 installed on your system. Use the configure option +--enable-libiec61883 to compile with the device enabled. +

+

The iec61883 capture device supports capturing from a video device +connected via IEEE1394 (FireWire), using libiec61883 and the new Linux +FireWire stack (juju). This is the default DV/HDV input method in Linux +Kernel 2.6.37 and later, since the old FireWire stack was removed. +

+

Specify the FireWire port to be used as input file, or "auto" +to choose the first port connected. +

+ +

20.8.1 Options

+ +
+
dvtype
+

Override autodetection of DV/HDV. This should only be used if auto +detection does not work, or if usage of a different device type +should be prohibited. Treating a DV device as HDV (or vice versa) will +not work and result in undefined behavior. +The values auto, dv and hdv are supported. +

+
+
dvbuffer
+

Set maximum size of buffer for incoming data, in frames. For DV, this +is an exact value. For HDV, it is not frame exact, since HDV does +not have a fixed frame size. +

+
+
dvguid
+

Select the capture device by specifying its GUID. Capturing will only +be performed from the specified device and fails if no device with the +given GUID is found. This is useful to select the input if multiple +devices are connected at the same time. +Look at /sys/bus/firewire/devices to find out the GUIDs. +

+
+
+ + +

20.8.2 Examples

+ +
    +
  • Grab and show the input of a FireWire DV/HDV device. +
    +
    ffplay -f iec61883 -i auto
    +
    + +
  • Grab and record the input of a FireWire DV/HDV device, +using a packet buffer of 100000 packets if the source is HDV. +
    +
    ffmpeg -f iec61883 -i auto -dvbuffer 100000 out.mpg
    +
    + +
+ + +

20.9 jack

+ +

JACK input device. +

+

To enable this input device during configuration you need libjack +installed on your system. +

+

A JACK input device creates one or more JACK writable clients, one for +each audio channel, with name client_name:input_N, where +client_name is the name provided by the application, and N +is a number which identifies the channel. +Each writable client will send the acquired data to the FFmpeg input +device. +

+

Once you have created one or more JACK readable clients, you need to +connect them to one or more JACK writable clients. +

+

To connect or disconnect JACK clients you can use the jack_connect +and jack_disconnect programs, or do it through a graphical interface, +for example with qjackctl. +

+

To list the JACK clients and their properties you can invoke the command +jack_lsp. +

+

Follows an example which shows how to capture a JACK readable client +with ffmpeg. +

+
# Create a JACK writable client with name "ffmpeg".
+$ ffmpeg -f jack -i ffmpeg -y out.wav
+
+# Start the sample jack_metro readable client.
+$ jack_metro -b 120 -d 0.2 -f 4000
+
+# List the current JACK clients.
+$ jack_lsp -c
+system:capture_1
+system:capture_2
+system:playback_1
+system:playback_2
+ffmpeg:input_1
+metro:120_bpm
+
+# Connect metro to the ffmpeg writable client.
+$ jack_connect metro:120_bpm ffmpeg:input_1
+
+ +

For more information read: +http://jackaudio.org/ +

+ +

20.9.1 Options

+ +
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

20.10 kmsgrab

+ +

KMS video input device. +

+

Captures the KMS scanout framebuffer associated with a specified CRTC or plane as a +DRM object that can be passed to other hardware functions. +

+

Requires either DRM master or CAP_SYS_ADMIN to run. +

+

If you don’t understand what all of that means, you probably don’t want this. Look at +x11grab instead. +

+ +

20.10.1 Options

+ +
+
device
+

DRM device to capture on. Defaults to /dev/dri/card0. +

+
+
format
+

Pixel format of the framebuffer. This can be autodetected if you are running Linux 5.7 +or later, but needs to be provided for earlier versions. Defaults to bgr0, +which is the most common format used by the Linux console and Xorg X server. +

+
+
format_modifier
+

Format modifier to signal on output frames. This is necessary to import correctly into +some APIs. It can be autodetected if you are running Linux 5.7 or later, but will need +to be provided explicitly when needed in earlier versions. See the libdrm documentation +for possible values. +

+
+
crtc_id
+

KMS CRTC ID to define the capture source. The first active plane on the given CRTC +will be used. +

+
+
plane_id
+

KMS plane ID to define the capture source. Defaults to the first active plane found if +neither crtc_id nor plane_id are specified. +

+
+
framerate
+

Framerate to capture at. This is not synchronised to any page flipping or framebuffer +changes - it just defines the interval at which the framebuffer is sampled. Sampling +faster than the framebuffer update rate will generate independent frames with the same +content. Defaults to 30. +

+
+
+ + +

20.10.2 Examples

+ +
    +
  • Capture from the first active plane, download the result to normal frames and encode. +This will only work if the framebuffer is both linear and mappable - if not, the result +may be scrambled or fail to download. +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwdownload,format=bgr0' output.mp4
    +
    + +
  • Capture from CRTC ID 42 at 60fps, map the result to VAAPI, convert to NV12 and encode as H.264. +
    +
    ffmpeg -crtc_id 42 -framerate 60 -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,scale_vaapi=w=1920:h=1080:format=nv12' -c:v h264_vaapi output.mp4
    +
    + +
  • To capture only part of a plane the output can be cropped - this can be used to capture +a single window, as long as it has a known absolute position and size. For example, to +capture and encode the middle quarter of a 1920x1080 plane: +
    +
    ffmpeg -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,crop=960:540:480:270,scale_vaapi=960:540:nv12' -c:v h264_vaapi output.mp4
    +
    + +
+ + +

20.11 lavfi

+ +

Libavfilter input virtual device. +

+

This input device reads data from the open output pads of a libavfilter +filtergraph. +

+

For each filtergraph open output, the input device will create a +corresponding stream which is mapped to the generated output. +The filtergraph is specified through the option graph. +

+ +

20.11.1 Options

+ +
+
graph
+

Specify the filtergraph to use as input. Each video open output must be +labelled by a unique string of the form "outN", where N is a +number starting from 0 corresponding to the mapped input stream +generated by the device. +The first unlabelled output is automatically assigned to the "out0" +label, but all the others need to be specified explicitly. +

+

The suffix "+subcc" can be appended to the output label to create an extra +stream with the closed captions packets attached to that output +(experimental; only for EIA-608 / CEA-708 for now). +The subcc streams are created after all the normal streams, in the order of +the corresponding stream. +For example, if there is "out19+subcc", "out7+subcc" and up to "out42", the +stream #43 is subcc for stream #7 and stream #44 is subcc for stream #19. +

+

If not specified defaults to the filename specified for the input +device. +

+
+
graph_file
+

Set the filename of the filtergraph to be read and sent to the other +filters. Syntax of the filtergraph is the same as the one specified by +the option graph. +

+
+
dumpgraph
+

Dump graph to stderr. +

+
+
+ + +

20.11.2 Examples

+ +
    +
  • Create a color video stream and play it back with ffplay: +
    +
    ffplay -f lavfi -graph "color=c=pink [out0]" dummy
    +
    + +
  • As the previous example, but use filename for specifying the graph +description, and omit the "out0" label: +
    +
    ffplay -f lavfi color=c=pink
    +
    + +
  • Create three different video test filtered sources and play them: +
    +
    ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3
    +
    + +
  • Read an audio stream from a file using the amovie source and play it +back with ffplay: +
    +
    ffplay -f lavfi "amovie=test.wav"
    +
    + +
  • Read an audio stream and a video stream and play it back with +ffplay: +
    +
    ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"
    +
    + +
  • Dump decoded frames to images and Closed Captions to an RCWT backup: +
    +
    ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rcwt subcc.bin
    +
    + +
+ + +

20.12 libcdio

+ +

Audio-CD input device based on libcdio. +

+

To enable this input device during configuration you need libcdio +installed on your system. It requires the configure option +--enable-libcdio. +

+

This device allows playing and grabbing from an Audio-CD. +

+

For example to copy with ffmpeg the entire Audio-CD in /dev/sr0, +you may run the command: +

+
ffmpeg -f libcdio -i /dev/sr0 cd.wav
+
+ + +

20.12.1 Options

+
+
speed
+

Set drive reading speed. Default value is 0. +

+

The speed is specified CD-ROM speed units. The speed is set through +the libcdio cdio_cddap_speed_set function. On many CD-ROM +drives, specifying a value too large will result in using the fastest +speed. +

+
+
paranoia_mode
+

Set paranoia recovery mode flags. It accepts one of the following values: +

+
+
‘disable’
+
‘verify’
+
‘overlap’
+
‘neverskip’
+
‘full’
+
+ +

Default value is ‘disable’. +

+

For more information about the available recovery modes, consult the +paranoia project documentation. +

+
+ + +

20.13 libdc1394

+ +

IIDC1394 input device, based on libdc1394 and libraw1394. +

+

Requires the configure option --enable-libdc1394. +

+ +

20.13.1 Options

+
+
framerate
+

Set the frame rate. Default is ntsc, corresponding to a frame +rate of 30000/1001. +

+
+
pixel_format
+

Select the pixel format. Default is uyvy422. +

+
+
video_size
+

Set the video size given as a string such as 640x480 or hd720. +Default is qvga. +

+
+ + +

20.14 openal

+ +

The OpenAL input device provides audio capture on all systems with a +working OpenAL 1.1 implementation. +

+

To enable this input device during configuration, you need OpenAL +headers and libraries installed on your system, and need to configure +FFmpeg with --enable-openal. +

+

OpenAL headers and libraries should be provided as part of your OpenAL +implementation, or as an additional download (an SDK). Depending on your +installation you may need to specify additional flags via the +--extra-cflags and --extra-ldflags for allowing the build +system to locate the OpenAL headers and libraries. +

+

An incomplete list of OpenAL implementations follows: +

+
+
Creative
+

The official Windows implementation, providing hardware acceleration +with supported devices and software fallback. +See http://openal.org/. +

+
OpenAL Soft
+

Portable, open source (LGPL) software implementation. Includes +backends for the most common sound APIs on the Windows, Linux, +Solaris, and BSD operating systems. +See http://kcat.strangesoft.net/openal.html. +

+
Apple
+

OpenAL is part of Core Audio, the official Mac OS X Audio interface. +See http://developer.apple.com/technologies/mac/audio-and-video.html +

+
+ +

This device allows one to capture from an audio input device handled +through OpenAL. +

+

You need to specify the name of the device to capture in the provided +filename. If the empty string is provided, the device will +automatically select the default device. You can get the list of the +supported devices by using the option list_devices. +

+ +

20.14.1 Options

+ +
+
channels
+

Set the number of channels in the captured audio. Only the values +1 (monaural) and 2 (stereo) are currently supported. +Defaults to 2. +

+
+
sample_size
+

Set the sample size (in bits) of the captured audio. Only the values +8 and 16 are currently supported. Defaults to +16. +

+
+
sample_rate
+

Set the sample rate (in Hz) of the captured audio. +Defaults to 44.1k. +

+
+
list_devices
+

If set to true, print a list of devices and exit. +Defaults to false. +

+
+
+ + +

20.14.2 Examples

+ +

Print the list of OpenAL supported devices and exit: +

+
$ ffmpeg -list_devices true -f openal -i dummy out.ogg
+
+ +

Capture from the OpenAL device DR-BT101 via PulseAudio: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg
+
+ +

Capture from the default device (note the empty string ” as filename): +

+
$ ffmpeg -f openal -i '' out.ogg
+
+ +

Capture from two devices simultaneously, writing to two different files, +within the same ffmpeg command: +

+
$ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg
+
+

Note: not all OpenAL implementations support multiple simultaneous capture - +try the latest OpenAL Soft if the above does not work. +

+ +

20.15 oss

+ +

Open Sound System input device. +

+

The filename to provide to the input device is the device node +representing the OSS input device, and is usually set to +/dev/dsp. +

+

For example to grab from /dev/dsp using ffmpeg use the +command: +

+
ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
+
+ +

For more information about OSS see: +http://manuals.opensound.com/usersguide/dsp.html +

+ +

20.15.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

20.16 pulse

+ +

PulseAudio input device. +

+

To enable this output device you need to configure FFmpeg with --enable-libpulse. +

+

The filename to provide to the input device is a source device or the +string "default" +

+

To list the PulseAudio source devices and their properties you can invoke +the command pactl list sources. +

+

More information about PulseAudio can be found on http://www.pulseaudio.org. +

+ +

20.16.1 Options

+
+
server
+

Connect to a specific PulseAudio server, specified by an IP address. +Default server is used when not provided. +

+
+
name
+

Specify the application name PulseAudio will use when showing active clients, +by default it is the LIBAVFORMAT_IDENT string. +

+
+
stream_name
+

Specify the stream name PulseAudio will use when showing active streams, +by default it is "record". +

+
+
sample_rate
+

Specify the samplerate in Hz, by default 48kHz is used. +

+
+
channels
+

Specify the channels in use, by default 2 (stereo) is set. +

+
+
frame_size
+

This option does nothing and is deprecated. +

+
+
fragment_size
+

Specify the size in bytes of the minimal buffering fragment in PulseAudio, it +will affect the audio latency. By default it is set to 50 ms amount of data. +

+
+
wallclock
+

Set the initial PTS using the current time. Default is 1. +

+
+
+ + +

20.16.2 Examples

+

Record a stream from default device: +

+
ffmpeg -f pulse -i default /tmp/pulse.wav
+
+ + +

20.17 sndio

+ +

sndio input device. +

+

To enable this input device during configuration you need libsndio +installed on your system. +

+

The filename to provide to the input device is the device node +representing the sndio input device, and is usually set to +/dev/audio0. +

+

For example to grab from /dev/audio0 using ffmpeg use the +command: +

+
ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
+
+ + +

20.17.1 Options

+ +
+
sample_rate
+

Set the sample rate in Hz. Default is 48000. +

+
+
channels
+

Set the number of channels. Default is 2. +

+
+
+ + +

20.18 video4linux2, v4l2

+ +

Video4Linux2 input video device. +

+

"v4l2" can be used as alias for "video4linux2". +

+

If FFmpeg is built with v4l-utils support (by using the +--enable-libv4l2 configure option), it is possible to use it with the +-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 +(e.g. an USB webcam) is plugged into the system, and has a name of the +kind /dev/videoN, where N is a number associated to +the device. +

+

Video4Linux2 devices usually support a limited set of +widthxheight sizes and frame rates. You can check which are +supported using -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 -list_standards all. +

+

The time base for the timestamps is 1 microsecond. Depending on the kernel +version and configuration, the timestamps may be derived from the real time +clock (origin at the Unix Epoch) or the monotonic clock (origin usually at +boot time, unaffected by NTP or manual changes to the clock). The +-timestamps abs or -ts abs option can be used to force +conversion into the real time clock. +

+

Some usage examples of the video4linux2 device with ffmpeg +and ffplay: +

    +
  • List supported formats for a video4linux2 device: +
    +
    ffplay -f video4linux2 -list_formats all /dev/video0
    +
    + +
  • Grab and show the input of a video4linux2 device: +
    +
    ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
    +
    + +
  • Grab and record the input of a video4linux2 device, leave the +frame rate and size as previously set: +
    +
    ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
    +
    +
+ +

For more information about Video4Linux, check http://linuxtv.org/. +

+ +

20.18.1 Options

+ +
+
standard
+

Set the standard. Must be the name of a supported standard. To get a +list of the supported standards, use the list_standards +option. +

+
+
channel
+

Set the input channel number. Default to -1, which means using the +previously selected channel. +

+
+
video_size
+

Set the video frame size. The argument must be a string in the form +WIDTHxHEIGHT or a valid size abbreviation. +

+
+
pixel_format
+

Select the pixel format (only valid for raw video input). +

+
+
input_format
+

Set the preferred pixel format (for raw video) or a codec name. +This option allows one to select the input format, when several are +available. +

+
+
framerate
+

Set the preferred video frame rate. +

+
+
list_formats
+

List available formats (supported pixel formats, codecs, and frame +sizes) and exit. +

+

Available values are: +

+
‘all’
+

Show all available (compressed and non-compressed) formats. +

+
+
‘raw’
+

Show only raw video (non-compressed) formats. +

+
+
‘compressed’
+

Show only compressed formats. +

+
+ +
+
list_standards
+

List supported standards and exit. +

+

Available values are: +

+
‘all’
+

Show all supported standards. +

+
+ +
+
timestamps, ts
+

Set type of timestamps for grabbed frames. +

+

Available values are: +

+
‘default’
+

Use timestamps from the kernel. +

+
+
‘abs’
+

Use absolute timestamps (wall clock). +

+
+
‘mono2abs’
+

Force conversion from monotonic to absolute timestamps. +

+
+ +

Default value is default. +

+
+
use_libv4l2
+

Use libv4l2 (v4l-utils) conversion functions. Default is 0. +

+
+
+ + +

20.19 vfwcap

+ +

VfW (Video for Windows) capture input device. +

+

The filename passed as input is the capture driver number, ranging from +0 to 9. You may use "list" as filename to print a list of drivers. Any +other filename will be interpreted as device number 0. +

+ +

20.19.1 Options

+ +
+
video_size
+

Set the video frame size. +

+
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
+ + +

20.20 x11grab

+ +

X11 video input device. +

+

To enable this input device during configuration you need libxcb +installed on your system. It will be automatically detected during +configuration. +

+

This device allows one to capture a region of an X11 display. +

+

The filename passed as input has the syntax: +

+
[hostname]:display_number.screen_number[+x_offset,y_offset]
+
+ +

hostname:display_number.screen_number specifies the +X11 display name of the screen to grab from. hostname can be +omitted, and defaults to "localhost". The environment variable +DISPLAY contains the default display name. +

+

x_offset and y_offset specify the offsets of the grabbed +area with respect to the top-left border of the X11 screen. They +default to 0. +

+

Check the X11 documentation (e.g. man X) for more detailed +information. +

+

Use the xdpyinfo program for getting basic information about +the properties of your X11 display (e.g. grep for "name" or +"dimensions"). +

+

For example to grab from :0.0 using ffmpeg: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

Grab at position 10,20: +

+
ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ + +

20.20.1 Options

+ +
+
select_region
+

Specify whether to select the grabbing area graphically using the pointer. +A value of 1 prompts the user to select the grabbing area graphically +by clicking and dragging. A single click with no dragging will select the +whole screen. A region with zero width or height will also select the whole +screen. This option overwrites the video_size, grab_x, and +grab_y options. Default value is 0. +

+
+
draw_mouse
+

Specify whether to draw the mouse pointer. A value of 0 specifies +not to draw the pointer. Default value is 1. +

+
+
follow_mouse
+

Make the grabbed area follow the mouse. The argument can be +centered or a number of pixels PIXELS. +

+

When it is specified with "centered", the grabbing region follows the mouse +pointer and keeps the pointer at the center of region; otherwise, the region +follows only when the mouse pointer reaches within PIXELS (greater than +zero) to the edge of region. +

+

For example: +

+
ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +

To follow only when the mouse pointer reaches within 100 pixels to edge: +

+
ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
framerate
+

Set the grabbing frame rate. Default value is ntsc, +corresponding to a frame rate of 30000/1001. +

+
+
show_region
+

Show grabbed region on screen. +

+

If show_region is specified with 1, then the grabbing +region will be indicated on screen. With this option, it is easy to +know what is being grabbed if only a portion of the screen is grabbed. +

+
+
region_border
+

Set the region border thickness if -show_region 1 is used. +Range is 1 to 128 and default is 3 (XCB-based x11grab only). +

+

For example: +

+
ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
+
+ +

With follow_mouse: +

+
ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg
+
+ +
+
window_id
+

Grab this window, instead of the whole screen. Default value is 0, which maps to +the whole screen (root window). +

+

The id of a window can be found using the xwininfo program, possibly with options -tree and +-root. +

+

If the window is later enlarged, the new area is not recorded. Video ends when +the window is closed, unmapped (i.e., iconified) or shrunk beyond the video +size (which defaults to the initial window size). +

+

This option disables options follow_mouse and select_region. +

+
+
video_size
+

Set the video frame size. Default is the full desktop or window. +

+
+
grab_x
+
grab_y
+

Set the grabbing region coordinates. They are expressed as offset from +the top left corner of the X11 window and correspond to the +x_offset and y_offset parameters in the device name. The +default value for both options is 0. +

+
+ + +

21 Resampler Options

+ +

The audio resampler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, option=value for the aresample filter, +by setting the value explicitly in the +SwrContext options or using the libavutil/opt.h API for +programmatic use. +

+
+
uchl, used_chlayout
+

Set used input channel layout. Default is unset. This option is +only used for special remapping. +

+
+
isr, in_sample_rate
+

Set the input sample rate. Default value is 0. +

+
+
osr, out_sample_rate
+

Set the output sample rate. Default value is 0. +

+
+
isf, in_sample_fmt
+

Specify the input sample format. It is set by default to none. +

+
+
osf, out_sample_fmt
+

Specify the output sample format. It is set by default to none. +

+
+
tsf, internal_sample_fmt
+

Set the internal sample format. Default value is none. +This will automatically be chosen when it is not explicitly set. +

+
+
ichl, in_chlayout
+
ochl, out_chlayout
+

Set the input/output channel layout. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
clev, center_mix_level
+

Set the center mix level. It is a value expressed in deciBel, and must be +in the interval [-32,32]. +

+
+
slev, surround_mix_level
+

Set the surround mix level. It is a value expressed in deciBel, and must +be in the interval [-32,32]. +

+
+
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]. +

+
+
rmvol, rematrix_volume
+

Set rematrix volume. Default value is 1.0. +

+
+
rematrix_maxval
+

Set maximum output value for rematrixing. +This can be used to prevent clipping vs. preventing volume reduction. +A value of 1.0 prevents clipping. +

+
+
flags, swr_flags
+

Set flags used by the converter. Default value is 0. +

+

It supports the following individual flags: +

+
res
+

force resampling, this flag forces resampling to be used even when the +input and output sample rates match. +

+
+ +
+
dither_scale
+

Set the dither scale. Default value is 1. +

+
+
dither_method
+

Set dither method. Default value is 0. +

+

Supported values: +

+
‘rectangular’
+

select rectangular dither +

+
‘triangular’
+

select triangular dither +

+
‘triangular_hp’
+

select triangular dither with high pass +

+
‘lipshitz’
+

select Lipshitz noise shaping dither. +

+
‘shibata’
+

select Shibata noise shaping dither. +

+
‘low_shibata’
+

select low Shibata noise shaping dither. +

+
‘high_shibata’
+

select high Shibata noise shaping dither. +

+
‘f_weighted’
+

select f-weighted noise shaping dither +

+
‘modified_e_weighted’
+

select modified-e-weighted noise shaping dither +

+
‘improved_e_weighted’
+

select improved-e-weighted noise shaping dither +

+
+
+ +
+
resampler
+

Set resampling engine. Default value is swr. +

+

Supported values: +

+
‘swr’
+

select the native SW Resampler; filter options precision and cheby are not +applicable in this case. +

+
‘soxr’
+

select the SoX Resampler (where available); compensation, and filter options +filter_size, phase_shift, exact_rational, filter_type & kaiser_beta, are not +applicable in this case. +

+
+ +
+
filter_size
+

For swr only, set resampling filter size, default value is 32. +

+
+
phase_shift
+

For swr only, set resampling phase shift, default value is 10, and must be in +the interval [0,30]. +

+
+
linear_interp
+

Use linear interpolation when enabled (the default). Disable it if you want +to preserve speed instead of quality when exact_rational fails. +

+
+
exact_rational
+

For swr only, when enabled, try to use exact phase_count based on input and +output sample rate. However, if it is larger than 1 << phase_shift, +the phase_count will be 1 << phase_shift as fallback. Default is enabled. +

+
+
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). +

+
+
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’. +

+
+
cheby
+

For soxr only, selects passband rolloff none (Chebyshev) & higher-precision +approximation for ’irrational’ ratios. Default value is 0. +

+
+
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. +

+
+
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. +

+
+
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 +(min_comp = FLT_MAX). +

+
+
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 min_comp. +The default is 0.1. +

+
+
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. +

+
+
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. +

+
+
matrix_encoding
+

Select matrixed stereo encoding. +

+

It accepts the following values: +

+
‘none’
+

select none +

+
‘dolby’
+

select Dolby +

+
‘dplii’
+

select Dolby Pro Logic II +

+
+ +

Default value is none. +

+
+
filter_type
+

For swr only, select resampling filter type. This only affects resampling +operations. +

+

It accepts the following values: +

+
‘cubic’
+

select cubic +

+
‘blackman_nuttall’
+

select Blackman Nuttall windowed sinc +

+
‘kaiser’
+

select Kaiser windowed sinc +

+
+ +
+
kaiser_beta
+

For swr only, set Kaiser window beta value. Must be a double float value in the +interval [2,16], default value is 9. +

+
+
output_sample_bits
+

For swr only, set number of used output sample bits for dithering. Must be an integer in the +interval [0,64], default value is 0, which means it’s not used. +

+
+
+ + +

22 Scaler Options

+ +

The video scaler supports the following named options. +

+

Options may be set by specifying -option value in the +FFmpeg tools, with a few API-only exceptions noted below. +For programmatic use, they can be set explicitly in the +SwsContext options or through the libavutil/opt.h API. +

+
+
+
+
sws_flags
+

Set the scaler flags. This is also used to set the scaling +algorithm. Only a single algorithm should be selected. Default +value is ‘bicubic’. +

+

It accepts the following values: +

+
‘fast_bilinear’
+

Select fast bilinear scaling algorithm. +

+
+
‘bilinear’
+

Select bilinear scaling algorithm. +

+
+
‘bicubic’
+

Select bicubic scaling algorithm. +

+
+
‘experimental’
+

Select experimental scaling algorithm. +

+
+
‘neighbor’
+

Select nearest neighbor rescaling algorithm. +

+
+
‘area’
+

Select averaging area rescaling algorithm. +

+
+
‘bicublin’
+

Select bicubic scaling algorithm for the luma component, bilinear for +chroma components. +

+
+
‘gauss’
+

Select Gaussian rescaling algorithm. +

+
+
‘sinc’
+

Select sinc rescaling algorithm. +

+
+
‘lanczos’
+

Select Lanczos rescaling algorithm. The default width (alpha) is 3 and can be +changed by setting param0. +

+
+
‘spline’
+

Select natural bicubic spline rescaling algorithm. +

+
+
‘print_info’
+

Enable printing/debug logging. +

+
+
‘accurate_rnd’
+

Enable accurate rounding. +

+
+
‘full_chroma_int’
+

Enable full chroma interpolation. +

+
+
‘full_chroma_inp’
+

Select full chroma input. +

+
+
‘bitexact’
+

Enable bitexact output. +

+
+
‘unstable’
+

Allow the use of experimental new code. May subtly affect the output or even +produce wrong results. For testing only. +

+
+ +
+
srcw (API only)
+

Set source width. +

+
+
srch (API only)
+

Set source height. +

+
+
dstw (API only)
+

Set destination width. +

+
+
dsth (API only)
+

Set destination height. +

+
+
src_format (API only)
+

Set source pixel format (must be expressed as an integer). +

+
+
dst_format (API only)
+

Set destination pixel format (must be expressed as an integer). +

+
+
src_range (boolean)
+

If value is set to 1, indicates source is full range. Default value is +0, which indicates source is limited range. +

+
+
dst_range (boolean)
+

If value is set to 1, enable full range for destination. Default value +is 0, which enables limited range. +

+
+
gamma (boolean)
+

If value is set to 1, enable gamma correct scaling. Default value is 0. +

+
+
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. +

+
+
sws_dither
+

Set the dithering algorithm. Accepts one of the following +values. Default value is ‘auto’. +

+
+
‘auto’
+

automatic choice +

+
+
‘none’
+

no dithering +

+
+
‘bayer’
+

bayer dither +

+
+
‘ed’
+

error diffusion dither +

+
+
‘a_dither’
+

arithmetic dither, based using addition +

+
+
‘x_dither’
+

arithmetic dither, based using xor (more random/less apparent patterning that +a_dither). +

+
+
+ +
+
alphablend
+

Set the alpha blending to use when the input has alpha but the output does not. +Default value is ‘none’. +

+
+
‘uniform_color’
+

Blend onto a uniform background color +

+
+
‘checkerboard’
+

Blend onto a checkerboard +

+
+
‘none’
+

No blending +

+
+
+ +
+
+ + +

23 Filtering Introduction

+ +

Filtering in FFmpeg is enabled through the libavfilter library. +

+

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. +

+
                [main]
+input --> split ---------------------> overlay --> output
+            |                             ^
+            |[tmp]                  [flip]|
+            +-----> crop --> vflip -------+
+
+

This filtergraph splits the input stream in two streams, then 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: +

+
+
ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
+
+ +

The result will be that the top half of the video is mirrored +onto the bottom half of the output video. +

+

Filters in the same linear chain are separated by commas, and distinct +linear chains of filters are separated by semicolons. In our example, +crop,vflip are in one linear chain, split and +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 [main] and [tmp]. +

+

The stream sent to the second output of split, labelled as +[tmp], is processed through the crop filter, which crops +away the lower half part of the video, and then vertically flipped. The +overlay filter takes in input the first unchanged output of the +split filter (which was labelled as [main]), and overlay on its +lower half the output generated by the 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 +by a colon. +

+

There exist so-called source filters that do not have an +audio/video input, and sink filters that will not have audio/video +output. +

+ + +

24 graph2dot

+ +

The graph2dot program included in the FFmpeg tools +directory can be used to parse a filtergraph description and issue a +corresponding textual representation in the dot language. +

+

Invoke the command: +

+
graph2dot -h
+
+ +

to see how to use graph2dot. +

+

You can then pass the dot description to the dot program (from +the graphviz suite of programs) and obtain a graphical representation +of the filtergraph. +

+

For example the sequence of commands: +

+
echo GRAPH_DESCRIPTION | \
+tools/graph2dot -o graph.tmp && \
+dot -Tpng graph.tmp -o graph.png && \
+display graph.png
+
+ +

can be used to create and display an image representing the graph +described by the GRAPH_DESCRIPTION string. Note that this string must be +a complete self-contained graph, with its inputs and outputs explicitly defined. +For example if your command line is of the form: +

+
ffmpeg -i infile -vf scale=640:360 outfile
+
+

your GRAPH_DESCRIPTION string will need to be of the form: +

+
nullsrc,scale=640:360,nullsink
+
+

you may also need to set the nullsrc parameters and add a format +filter in order to simulate a specific input file. +

+ + +

25 Filtergraph description

+ +

A filtergraph is a directed graph of connected filters. It can contain +cycles, and there can be multiple links between a pair of +filters. Each link has one input pad on one side connecting it to one +filter from which it takes its input, and one output pad on the other +side connecting it to one filter accepting its output. +

+

Each filter in a filtergraph is an instance of a filter class +registered in the application, which defines the features and the +number of input and output pads of the filter. +

+

A filter with no input pads is called a "source", and a filter with no +output pads is called a "sink". +

+ +

25.1 Filtergraph syntax

+ +

A filtergraph has a textual representation, which is recognized by the +-filter/-vf/-af and +-filter_complex options in ffmpeg and +-vf/-af in ffplay, and by the +avfilter_graph_parse_ptr() function defined in +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 +represented by a list of ","-separated filter descriptions. +

+

A filtergraph consists of a sequence of filterchains. A sequence of +filterchains is represented by a list of ";"-separated filterchain +descriptions. +

+

A filter is represented by a string of the form: +[in_link_1]...[in_link_N]filter_name@id=arguments[out_link_1]...[out_link_M] +

+

filter_name is the name of the filter class of which the +described filter is an instance of, and has to be the name of one of +the filter classes registered in the program optionally followed by "@id". +The name of the filter class is optionally followed by a string +"=arguments". +

+

arguments is a string which contains the parameters used to +initialize the filter instance. It may have one of two forms: +

    +
  • A ’:’-separated list of key=value pairs. + +
  • A ’:’-separated list of value. In this case, the keys are assumed to be +the option names in the order they are declared. E.g. the fade filter +declares three options in this order – type, start_frame and +nb_frames. Then the parameter list in:0:30 means that the value +in is assigned to the option type, 0 to +start_frame and 30 to nb_frames. + +
  • A ’:’-separated list of mixed direct value and long key=value +pairs. The direct value must precede the key=value pairs, and +follow the same constraints order of the previous point. The following +key=value pairs can be set in any preferred order. + +
+ +

If the option value itself is a list of items (e.g. the 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 +within the quoted text; otherwise the argument string is considered +terminated when the next special character (belonging to the set +‘[]=;,’) is encountered. +

+

A special syntax implemented in the ffmpeg CLI tool allows loading +option values from files. This is done be prepending a slash ’/’ to the option +name, then the supplied value is interpreted as a path from which the actual +value is loaded. E.g. +

+
ffmpeg -i <INPUT> -vf drawtext=/text=/tmp/some_text <OUTPUT>
+
+

will load the text to be drawn from /tmp/some_text. API users wishing to +implement a similar feature should use the avfilter_graph_segment_*() +functions together with custom IO code. +

+

The name and arguments of the filter are optionally preceded and +followed by a list of link labels. +A link label allows one to name a link and associate it to a filter output +or input pad. The preceding labels in_link_1 +... in_link_N, are associated to the filter input pads, +the following labels out_link_1 ... out_link_M, are +associated to the output pads. +

+

When two link labels with the same name are found in the +filtergraph, a link between the corresponding input and output pad is +created. +

+

If an output pad is not labelled, it is linked by default to the first +unlabelled input pad of the next filter in the filterchain. +For example in the filterchain +

+
nullsrc, split[L1], [L2]overlay, nullsink
+
+

the split filter instance has two output pads, and the overlay filter +instance two input pads. The first output pad of split is labelled +"L1", the first input pad of overlay is labelled "L2", and the second +output pad of split is linked to the second input pad of overlay, +which are both unlabelled. +

+

In a filter description, if the input label of the first filter is not +specified, "in" is assumed; if the output label of the last filter is not +specified, "out" is assumed. +

+

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. +

+

Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens +in the filtergraph specification are ignored. This means that the filtergraph +can be expressed using empty lines and spaces to improve readability. +

+

For example, the filtergraph: +

+
testsrc,split[L1],hflip[L2];[L1][L2] hstack
+
+ +

can be represented as: +

+
testsrc,
+split [L1], hflip [L2];
+
+[L1][L2] hstack
+
+ +

Libavfilter will automatically insert scale filters where format +conversion is required. It is possible to specify swscale flags +for those automatically inserted scalers by prepending +sws_flags=flags; +to the filtergraph description. +

+

Here is a BNF description of the filtergraph syntax: +

+
NAME             ::= sequence of alphanumeric characters and '_'
+FILTER_NAME      ::= NAME["@"NAME]
+LINKLABEL        ::= "[" NAME "]"
+LINKLABELS       ::= LINKLABEL [LINKLABELS]
+FILTER_ARGUMENTS ::= sequence of chars (possibly quoted)
+FILTER           ::= [LINKLABELS] FILTER_NAME ["=" FILTER_ARGUMENTS] [LINKLABELS]
+FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
+FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]
+
+ + +

25.2 Notes on filtergraph escaping

+ +

Filtergraph description composition entails several levels of +escaping. See the "Quoting and escaping" +section in the ffmpeg-utils(1) manual for more +information about the employed escaping procedure. +

+

A first level escaping affects the content of each filter option +value, which may contain the special character : used to +separate values, or one of the escaping characters \'. +

+

A second level escaping affects the whole filter description, which +may contain the escaping characters \' or the special +characters [],; used by the filtergraph description. +

+

Finally, when you specify a filtergraph on a shell commandline, you +need to perform a third level escaping for the shell special +characters contained within it. +

+

For example, consider the following string to be embedded in +the drawtext filter description text value: +

+
this is a 'string': may contain one, or more, special characters
+
+ +

This string contains the ' special escaping character, and the +: special character, so it needs to be escaped in this way: +

+
text=this is a \'string\'\: may contain one, or more, special characters
+
+ +

A second level of escaping is required when embedding the filter +description in a filtergraph description, in order to escape all the +filtergraph special characters. Thus the example above becomes: +

+
drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
+
+

(note that in addition to the \' escaping special characters, +also , needs to be escaped). +

+

Finally an additional level of escaping is needed when writing the +filtergraph description in a shell command, which depends on the +escaping rules of the adopted shell. For example, assuming that +\ is special and needs to be escaped with another \, the +previous string will finally result in: +

+
-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
+
+ +

In order to avoid cumbersome escaping when using a commandline tool accepting a +filter specification as input, it is advisable to avoid direct inclusion of the +filter or options specification in the shell. +

+

For example, in case of the drawtext filter, you might prefer to +use the textfile option in place of text to specify the text +to render. +

+ +

26 Timeline editing

+ +

Some filters support a generic 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: +

+
‘t’
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
‘n’
+

sequential number of the input frame, starting from 0 +

+
+
‘pos’
+

the position in the file of the input frame, NAN if unknown; deprecated, do +not use +

+
+
‘w’
+
‘h’
+

width and height of the input frame if video +

+
+ +

Additionally, these filters support an enable command that can be used +to re-define the expression. +

+

Like any other filtering option, the enable option follows the same +rules. +

+

For example, to enable a blur filter (smartblur) from 10 seconds to 3 +minutes, and a curves filter starting at 3 seconds: +

+
smartblur = enable='between(t,10,3*60)',
+curves    = enable='gte(t,3)' : preset=cross_process
+
+ +

See ffmpeg -filters to view which filters have timeline support. +

+ + +

27 Changing options at runtime with a command

+ +

Some options can be changed during the operation of the filter using +a command. These options are marked ’T’ on the output of +ffmpeg -h filter=<name of filter>. +The name of the command is the name of the option and the argument is +the new value. +

+ +

28 Options for filters with several inputs (framesync)

+ +

Some filters with several inputs support a common set of options. +These options can only be set by name, not with the short notation. +

+
+
eof_action
+

The action to take when EOF is encountered on the secondary input; it accepts +one of the following values: +

+
+
repeat
+

Repeat the last frame (the default). +

+
endall
+

End both streams. +

+
pass
+

Pass the main input through. +

+
+ +
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
repeatlast
+

If set to 1, force the filter to extend the last frame of secondary streams +until the end of the primary stream. A value of 0 disables this behavior. +Default value is 1. +

+
+
ts_sync_mode
+

How strictly to sync streams based on secondary input timestamps; it accepts +one of the following values: +

+
+
default
+

Frame from secondary input with the nearest lower or equal timestamp to the +primary input frame. +

+
nearest
+

Frame from secondary input with the absolute nearest timestamp to the primary +input frame. +

+
+
+
+ + + +

29 Audio Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the audio filters included in your +build. +

+

Below is a description of the currently available audio filters. +

+ +

29.1 aap

+

Apply Affine Projection algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to estimate unknown audio based on multiple input audio samples. +Affine projection algorithm can make trade-offs between computation complexity with convergence speed. +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
projection
+

Set the projection order. +

+
+
mu
+

Set the filter mu. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

29.2 acompressor

+ +

A compressor is mainly used to reduce the dynamic range of a signal. +Especially modern music is mostly compressed at a high ratio to +improve the overall loudness. It’s done to get the highest attention +of a listener, "fatten" the sound and bring more "power" to the track. +If a signal is compressed too much it may sound dull or "dead" +afterwards or it may start to "pump" (which could be a powerful effect +but can also destroy a track completely). +The right compression is the key to reach a professional sound and is +the high art of mixing and mastering. Because of its complex settings +it may take a long time to get the right feeling for this kind of effect. +

+

Compression is done by detecting the volume above a chosen level +threshold and dividing it by the factor set with ratio. +So if you set the threshold to -12dB and your signal reaches -6dB a ratio +of 2:1 will result in a signal at -9dB. Because an exact manipulation of +the signal would cause distortion of the waveform the reduction can be +levelled over the time. This is done by setting "Attack" and "Release". +attack determines how long the signal has to rise above the threshold +before any reduction will occur and release sets the time the signal +has to fall below the threshold to reduce the reduction again. Shorter signals +than the chosen attack time will be left untouched. +The overall reduction of the signal can be made up afterwards with the +makeup setting. So compressing the peaks of a signal about 6dB and +raising the makeup to this level results in a signal twice as loud than the +source. To gain a softer entry in the compression the knee flattens the +hard edge at the threshold in the range of the chosen decibels. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of stream rises above this level it will affect the gain +reduction. +By default it is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. 1:2 means that if the level +rose 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of input stream +or the louder(maximum) channel of input stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mostly smoother. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

29.2.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.3 acontrast

+

Simple audio dynamic range compression/expansion filter. +

+

The filter accepts the following options: +

+
+
contrast
+

Set contrast. Default is 33. Allowed range is between 0 and 100. +

+
+ + +

29.4 acopy

+ +

Copy the input audio source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

29.5 acrossfade

+ +

Apply cross fade from one input audio stream to another input audio stream. +The cross fade is applied for specified duration near the end of first stream. +

+

The filter accepts the following options: +

+
+
inputs, n
+

Specify the number of inputs to crossfade. When crossfading multiple inputs, +each input will be concatenated and crossfaded in sequence, similar to the +concat filter. Default is 2. +

+
+
nb_samples, ns
+

Specify the number of samples for which the cross fade effect has to last. +At the end of the cross fade effect the first input audio will be completely +silent. Default is 44100. +

+
+
duration, d
+

Specify the duration of the cross fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
overlap, o
+

Should first stream end overlap with second stream start. Default is enabled. +

+
+
curve1
+

Set curve for cross fade transition for first stream. +

+
+
curve2
+

Set curve for cross fade transition for second stream. +

+

For description of available curve types see afade filter description. +

+
+ + +

29.5.1 Examples

+ +
    +
  • Cross fade from one input to another: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
    +
    + +
  • Cross fade from one input to another but without overlapping: +
    +
    ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
    +
    + +

    Concatenate multiple inputs with cross fade between each: +

    +
    ffmpeg -i first.flac -i second.flac -i third.flac -filter_complex acrossfade=n=3 output.flac
    +
    +
+ + +

29.6 acrossover

+

Split audio stream into several bands. +

+

This filter splits audio stream into two or more frequency ranges. +Summing all streams back will give flat output. +

+

The filter accepts the following options: +

+
+
split
+

Set split frequencies. Those must be positive and increasing. +

+
+
order
+

Set filter order for each band split. This controls filter roll-off or steepness +of filter transfer function. +Available values are: +

+
+
‘2nd’
+

12 dB per octave. +

+
‘4th’
+

24 dB per octave. +

+
‘6th’
+

36 dB per octave. +

+
‘8th’
+

48 dB per octave. +

+
‘10th’
+

60 dB per octave. +

+
‘12th’
+

72 dB per octave. +

+
‘14th’
+

84 dB per octave. +

+
‘16th’
+

96 dB per octave. +

+
‘18th’
+

108 dB per octave. +

+
‘20th’
+

120 dB per octave. +

+
+ +

Default is 4th. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+
gains
+

Set output gain for each band. Default value is 1 for all bands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+ + +

29.6.1 Examples

+ +
    +
  • Split input audio stream into two bands (low and high) with split frequency of 1500 Hz, +each band will be in separate stream: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but with higher filter order: +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
    +
    + +
  • Same as above, but also with additional middle band (frequencies between 1500 and 8000): +
    +
    ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav
    +
    +
+ + +

29.7 acrusher

+ +

Reduce audio bit resolution. +

+

This filter is bit crusher with enhanced functionality. A bit crusher +is used to audibly reduce number of bits an audio signal is sampled +with. This doesn’t change the bit depth at all, it just produces the +effect. Material reduced in bit depth sounds more harsh and "digital". +This filter is able to even round to continuous values instead of discrete +bit depths. +Additionally it has a D/C offset which results in different crushing of +the lower and the upper half of the signal. +An Anti-Aliasing setting is able to produce "softer" crushing sounds. +

+

Another feature of this filter is the logarithmic mode. +This setting switches from linear distances between bits to logarithmic ones. +The result is a much more "natural" sounding crusher which doesn’t gate low +signals for example. The human ear has a logarithmic perception, +so this kind of crushing is much more pleasant. +Logarithmic crushing is also able to get anti-aliased. +

+

The filter accepts the following options: +

+
+
level_in
+

Set level in. +

+
+
level_out
+

Set level out. +

+
+
bits
+

Set bit reduction. +

+
+
mix
+

Set mixing amount. +

+
+
mode
+

Can be linear: lin or logarithmic: log. +

+
+
dc
+

Set DC. +

+
+
aa
+

Set anti-aliasing. +

+
+
samples
+

Set sample reduction. +

+
+
lfo
+

Enable LFO. By default disabled. +

+
+
lforange
+

Set LFO range. +

+
+
lforate
+

Set LFO rate. +

+
+ + +

29.7.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.8 acue

+ +

Delay audio filtering until a given wallclock timestamp. See the cue +filter. +

+ +

29.9 adeclick

+

Remove impulsive noise from input audio. +

+

Samples detected as impulsive noise are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to +100. Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from +50 to 95. Default value is 75 percent. +Setting this to a very high value increases impulsive noise removal but makes +whole process much slower. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 2 percent. This option also +controls quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 2. +This controls the strength of impulsive noise which is going to be removed. +The lower value, the more samples will be detected as impulsive noise. +

+
+
burst, b
+

Set burst fusion, in percentage of window size. Allowed range is 0 to +10. Default value is 2. +If any two samples detected as noise are spaced less than this value then any +sample between those two samples will be also detected as noise. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly +changed with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

29.10 adeclip

+

Remove clipped samples from input audio. +

+

Samples detected as clipped are replaced by interpolated samples using +autoregressive modelling. +

+
+
window, w
+

Set window size, in milliseconds. Allowed range is from 10 to 100. +Default value is 55 milliseconds. +This sets size of window which will be processed at once. +

+
+
overlap, o
+

Set window overlap, in percentage of window size. Allowed range is from 50 +to 95. Default value is 75 percent. +

+
+
arorder, a
+

Set autoregression order, in percentage of window size. Allowed range is from +0 to 25. Default value is 8 percent. This option also controls +quality of interpolated samples using neighbour good samples. +

+
+
threshold, t
+

Set threshold value. Allowed range is from 1 to 100. +Default value is 10. Higher values make clip detection less aggressive. +

+
+
hsize, n
+

Set size of histogram used to detect clips. Allowed range is from 100 to 9999. +Default value is 1000. Higher values make clip detection less aggressive. +

+
+
method, m
+

Set overlap method. +

+

It accepts the following values: +

+
add, a
+

Select overlap-add method. Even not interpolated samples are slightly changed +with this method. +

+
+
save, s
+

Select overlap-save method. Not interpolated samples remain unchanged. +

+
+ +

Default value is a. +

+
+ + +

29.11 adecorrelate

+

Apply decorrelation to input audio stream. +

+

The filter accepts the following options: +

+
+
stages
+

Set decorrelation stages of filtering. Allowed +range is from 1 to 16. Default value is 6. +

+
+
seed
+

Set random seed used for setting delay in samples across channels. +

+
+ + +

29.12 adelay

+ +

Delay one or more audio channels. +

+

Samples in delayed channel are filled with silence. +

+

The filter accepts the following option: +

+
+
delays
+

Set list of delays in milliseconds for each channel separated by ’|’. +Unused delays will be silently ignored. If number of given delays is +smaller than number of channels all remaining channels will not be delayed. +If you want to delay exact number of samples, append ’S’ to number. +If you want instead to delay in seconds, append ’s’ to number. +

+
+
all
+

Use last set delay for all remaining channels. By default is disabled. +This option if enabled changes how option delays is interpreted. +

+
+ + +

29.12.1 Examples

+ +
    +
  • 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. +
    +
    adelay=1500|0|500
    +
    + +
  • Delay second channel by 500 samples, the third channel by 700 samples and leave +the first channel (and any other channels that may be present) unchanged. +
    +
    adelay=0|500S|700S
    +
    + +
  • Delay all channels by same number of samples: +
    +
    adelay=delays=64S:all=1
    +
    +
+ + +

29.13 adenorm

+

Remedy denormals in audio by adding extremely low-level noise. +

+

This filter shall be placed before any filter that can produce denormals. +

+

A description of the accepted parameters follows. +

+
+
level
+

Set level of added noise in dB. Default is -351. +Allowed range is from -451 to -90. +

+
+
type
+

Set type of added noise. +

+
+
dc
+

Add DC signal. +

+
ac
+

Add AC signal. +

+
square
+

Add square signal. +

+
pulse
+

Add pulse signal. +

+
+ +

Default is dc. +

+
+ + +

29.13.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.14 aderivative, aintegral

+ +

Compute derivative/integral of audio stream. +

+

Applying both filters one after another produces original audio. +

+ +

29.15 adrc

+ +

Apply spectral dynamic range controller filter to input audio stream. +

+

A description of the accepted options follows. +

+
+
transfer
+

Set the transfer expression. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frequency power value, in dB +

+
+
f
+

current frequency in Hz +

+
+ +

Default value is p. +

+
+
attack
+

Set the attack in milliseconds. Default is 50 milliseconds. +Allowed range is from 1 to 1000 milliseconds. +

+
release
+

Set the release in milliseconds. Default is 100 milliseconds. +Allowed range is from 5 to 2000 milliseconds. +

+
channels
+

Set which channels to filter, by default all channels in audio stream are filtered. +

+
+ + +

29.15.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.15.2 Examples

+ +
    +
  • Apply spectral compression to all frequencies with threshold of -50 dB and 1:6 ratio: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/6,p)':attack=50:release=100
    +
    + +
  • Similar to above but with 1:2 ratio and filtering only front center channel: +
    +
    adrc=transfer='if(gt(p,-50),-50+(p-(-50))/2,p)':attack=50:release=100:channels=FC
    +
    + +
  • Apply spectral noise gate to all frequencies with threshold of -85 dB and with short attack time and short release time: +
    +
    adrc=transfer='if(lte(p,-85),p-800,p)':attack=1:release=5
    +
    + +
  • Apply spectral expansion to all frequencies with threshold of -10 dB and 1:2 ratio: +
    +
    adrc=transfer='if(lt(p,-10),-10+(p-(-10))*2,p)':attack=50:release=100
    +
    + +
  • Apply limiter to max -60 dB to all frequencies, with attack of 2 ms and release of 10 ms: +
    +
    adrc=transfer='min(p,-60)':attack=2:release=10
    +
    +
+ + +

29.16 adynamicequalizer

+ +

Apply dynamic equalization to input audio stream. +

+

A description of the accepted options follows. +

+
+
threshold
+

Set the detection threshold used to trigger equalization. +Threshold detection is using detection filter. +Default value is 0. Allowed range is from 0 to 100. +

+
+
dfrequency
+

Set the detection frequency in Hz used for detection filter used to trigger equalization. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
dqfactor
+

Set the detection resonance factor for detection filter used to trigger equalization. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
tfrequency
+

Set the target frequency of equalization filter. +Default value is 1000 Hz. Allowed range is between 2 and 1000000 Hz. +

+
+
tqfactor
+

Set the target resonance factor for target equalization filter. +Default value is 1. Allowed range is from 0.001 to 1000. +

+
+
attack
+

Set the amount of milliseconds the signal from detection has to rise above +the detection threshold before equalization starts. +Default is 20. Allowed range is between 1 and 2000. +

+
+
release
+

Set the amount of milliseconds the signal from detection has to fall below the +detection threshold before equalization ends. +Default is 200. Allowed range is between 1 and 2000. +

+
+
ratio
+

Set the ratio by which the equalization gain is raised. +Default is 1. Allowed range is between 0 and 30. +

+
+
makeup
+

Set the makeup offset by which the equalization gain is raised. +Default is 0. Allowed range is between 0 and 100. +

+
+
range
+

Set the max allowed cut/boost amount. Default is 50. +Allowed range is from 1 to 200. +

+
+
mode
+

Set the mode of filter operation, can be one of the following: +

+
+
‘listen’
+

Output only isolated detection signal. +

+
‘cutbelow’
+

Cut frequencies below detection threshold. +

+
‘cutabove’
+

Cut frequencies above detection threshold. +

+
‘boostbelow’
+

Boost frequencies below detection threshold. +

+
‘boostabove’
+

Boost frequencies above detection threshold. +

+
+

Default mode is ‘cutbelow’. +

+
+
dftype
+

Set the type of detection filter, can be one of the following: +

+
+
‘bandpass’
+
‘lowpass’
+
‘highpass’
+
‘peak’
+
+

Default type is ‘bandpass’. +

+
+
tftype
+

Set the type of target filter, can be one of the following: +

+
+
‘bell’
+
‘lowshelf’
+
‘highshelf’
+
+

Default type is ‘bell’. +

+
+
auto
+

Automatically gather threshold from detection filter. By default +is ‘disabled’. +This option is useful to detect threshold in certain time frame of +input audio stream, in such case option value is changed at runtime. +

+

Available values are: +

+
‘disabled’
+

Disable using automatically gathered threshold value. +

+
‘off’
+

Stop picking threshold value. +

+
‘on’
+

Start picking threshold value. +

+
‘adaptive’
+

Adaptively pick threshold value, by calculating sliding window entropy. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

29.16.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.17 adynamicsmooth

+ +

Apply dynamic smoothing to input audio stream. +

+

A description of the accepted options follows. +

+
+
sensitivity
+

Set an amount of sensitivity to frequency fluctations. Default is 2. +Allowed range is from 0 to 1e+06. +

+
+
basefreq
+

Set a base frequency for smoothing. Default value is 22050. +Allowed range is from 2 to 1e+06. +

+
+ + +

29.17.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.18 aecho

+ +

Apply echoing to the input audio. +

+

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 delay, and the +loudness of the reflected signal is the decay. +Multiple echoes can have different delays and decays. +

+

A description of the accepted parameters follows. +

+
+
in_gain
+

Set input gain of reflected signal. Default is 0.6. +

+
+
out_gain
+

Set output gain of reflected signal. Default is 0.3. +

+
+
delays
+

Set list of time intervals in milliseconds between original signal and reflections +separated by ’|’. Allowed range for each delay is (0 - 90000.0]. +Default is 1000. +

+
+
decays
+

Set list of loudness of reflected signals separated by ’|’. +Allowed range for each decay is (0 - 1.0]. +Default is 0.5. +

+
+ + +

29.18.1 Examples

+ +
    +
  • Make it sound as if there are twice as many instruments as are actually playing: +
    +
    aecho=0.8:0.88:60:0.4
    +
    + +
  • If delay is very short, then it sounds like a (metallic) robot playing music: +
    +
    aecho=0.8:0.88:6:0.4
    +
    + +
  • A longer delay will sound like an open air concert in the mountains: +
    +
    aecho=0.8:0.9:1000:0.3
    +
    + +
  • Same as above but with one more mountain: +
    +
    aecho=0.8:0.9:1000|1800:0.3|0.25
    +
    +
+ + +

29.19 aemphasis

+

Audio emphasis filter creates or restores material directly taken from LPs or +emphased CDs with different filter curves. E.g. to store music on vinyl the +signal has to be altered by a filter first to even out the disadvantages of +this recording medium. +Once the material is played back the inverse filter has to be applied to +restore the distortion of the frequency response. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. +

+
+
level_out
+

Set output gain. +

+
+
mode
+

Set filter mode. For restoring material use reproduction mode, otherwise +use production mode. Default is reproduction mode. +

+
+
type
+

Set filter type. Selects medium. Can be one of the following: +

+
+
col
+

select Columbia. +

+
emi
+

select EMI. +

+
bsi
+

select BSI (78RPM). +

+
riaa
+

select RIAA. +

+
cd
+

select Compact Disc (CD). +

+
50fm
+

select 50µs (FM). +

+
75fm
+

select 75µs (FM). +

+
50kf
+

select 50µs (FM-KF). +

+
75kf
+

select 75µs (FM-KF). +

+
+
+
+ + +

29.19.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.20 aeval

+ +

Modify an audio signal according to the specified expressions. +

+

This filter accepts one or more expressions (one for each channel), +which are evaluated and used to modify a corresponding audio signal. +

+

It accepts the following parameters: +

+
+
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. +

+
+
channel_layout, c
+

Set output channel layout. If not specified, the channel layout is +specified by the number of expressions. If set to ‘same’, it will +use by default the same input channel layout. +

+
+ +

Each expression in exprs can contain the following constants and functions: +

+
+
ch
+

channel number of the current expression +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
s
+

sample rate +

+
+
t
+

time of the evaluated sample expressed in seconds +

+
+
nb_in_channels
+
nb_out_channels
+

input and output number of channels +

+
+
val(CH)
+

the value of input channel with number CH +

+
+ +

Note: this filter is slow. For faster processing you should use a +dedicated filter. +

+ +

29.20.1 Examples

+ +
    +
  • Half volume: +
    +
    aeval=val(ch)/2:c=same
    +
    + +
  • Invert phase of the second channel: +
    +
    aeval=val(0)|-val(1)
    +
    +
+ + +

29.21 aexciter

+ +

An exciter is used to produce high sound that is not present in the +original signal. This is done by creating harmonic distortions of the +signal which are restricted in range and added to the original signal. +An Exciter raises the upper end of an audio signal without simply raising +the higher frequencies like an equalizer would do to create a more +"crisp" or "brilliant" sound. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level prior processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
level_out
+

Set output level after processing of signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
amount
+

Set the amount of harmonics added to original signal. +Allowed range is from 0 to 64. +Default value is 1. +

+
+
drive
+

Set the amount of newly created harmonics. +Allowed range is from 0.1 to 10. +Default value is 8.5. +

+
+
blend
+

Set the octave of newly created harmonics. +Allowed range is from -10 to 10. +Default value is 0. +

+
+
freq
+

Set the lower frequency limit of producing harmonics in Hz. +Allowed range is from 2000 to 12000 Hz. +Default is 7500 Hz. +

+
+
ceil
+

Set the upper frequency limit of producing harmonics. +Allowed range is from 9999 to 20000 Hz. +If value is lower than 10000 Hz no limit is applied. +

+
+
listen
+

Mute the original signal and output only added harmonics. +By default is disabled. +

+
+ + +

29.21.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.22 afade

+ +

Apply fade-in/out effect to input audio. +

+

A description of the accepted parameters follows. +

+
+
type, t
+

Specify the effect type, can be either in for fade-in, or +out for a fade-out effect. Default is in. +

+
+
start_sample, ss
+

Specify the number of the start sample for starting to apply the fade +effect. Default is 0. +

+
+
nb_samples, ns
+

Specify the number of samples for which the fade effect has to last. 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 44100. +

+
+
start_time, st
+

Specify the start time of the fade effect. Default is 0. +The value must be specified as a time duration; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +If set this option is used instead of start_sample. +

+
+
duration, d
+

Specify the duration of the fade effect. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +By default the duration is determined by nb_samples. +If set this option is used instead of nb_samples. +

+
+
curve
+

Set curve for fade transition. +

+

It accepts the following values: +

+
tri
+

select triangular, linear slope (default) +

+
qsin
+

select quarter of sine wave +

+
hsin
+

select half of sine wave +

+
esin
+

select exponential sine wave +

+
log
+

select logarithmic +

+
ipar
+

select inverted parabola +

+
qua
+

select quadratic +

+
cub
+

select cubic +

+
squ
+

select square root +

+
cbr
+

select cubic root +

+
par
+

select parabola +

+
exp
+

select exponential +

+
iqsin
+

select inverted quarter of sine wave +

+
ihsin
+

select inverted half of sine wave +

+
dese
+

select double-exponential seat +

+
desi
+

select double-exponential sigmoid +

+
losi
+

select logistic sigmoid +

+
sinc
+

select sine cardinal function +

+
isinc
+

select inverted sine cardinal function +

+
quat
+

select quartic +

+
quatr
+

select quartic root +

+
qsin2
+

select squared quarter of sine wave +

+
hsin2
+

select squared half of sine wave +

+
nofade
+

no fade applied +

+
+ +
+
silence
+

Set the initial gain for fade-in or final gain for fade-out. +Default value is 0.0. +

+
+
unity
+

Set the initial gain for fade-out or final gain for fade-in. +Default value is 1.0. +

+
+ + +

29.22.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.22.2 Examples

+ +
    +
  • Fade in first 15 seconds of audio: +
    +
    afade=t=in:ss=0:d=15
    +
    + +
  • Fade out last 25 seconds of a 900 seconds audio: +
    +
    afade=t=out:st=875:d=25
    +
    +
+ + +

29.23 afftdn

+

Denoise audio samples with FFT. +

+

A description of the accepted parameters follows. +

+
+
noise_reduction, nr
+

Set the noise reduction in dB, allowed range is 0.01 to 97. +Default value is 12 dB. +

+
+
noise_floor, nf
+

Set the noise floor in dB, allowed range is -80 to -20. +Default value is -50 dB. +

+
+
noise_type, nt
+

Set the noise type. +

+

It accepts the following values: +

+
white, w
+

Select white noise. +

+
+
vinyl, v
+

Select vinyl noise. +

+
+
shellac, s
+

Select shellac noise. +

+
+
custom, c
+

Select custom noise, defined in bn option. +

+

Default value is white noise. +

+
+ +
+
band_noise, bn
+

Set custom band noise profile for every one of 15 bands. +Bands are separated by ’ ’ or ’|’. +

+
+
residual_floor, rf
+

Set the residual floor in dB, allowed range is -80 to -20. +Default value is -38 dB. +

+
+
track_noise, tn
+

Enable noise floor tracking. By default is disabled. +With this enabled, noise floor is automatically adjusted. +

+
+
track_residual, tr
+

Enable residual tracking. By default is disabled. +

+
+
output_mode, om
+

Set the output mode. +

+

It accepts the following values: +

+
input, i
+

Pass input unchanged. +

+
+
output, o
+

Pass noise filtered out. +

+
+
noise, n
+

Pass only noise. +

+

Default value is output. +

+
+ +
+
adaptivity, ad
+

Set the adaptivity factor, used how fast to adapt gains adjustments per +each frequency bin. Value 0 enables instant adaptation, while higher values +react much slower. +Allowed range is from 0 to 1. Default value is 0.5. +

+
+
floor_offset, fo
+

Set the noise floor offset factor. This option is used to adjust offset applied to measured +noise floor. It is only effective when noise floor tracking is enabled. +Allowed range is from -2.0 to 2.0. Default value is 1.0. +

+
+
noise_link, nl
+

Set the noise link used for multichannel audio. +

+

It accepts the following values: +

+
none
+

Use unchanged channel’s noise floor. +

+
+
min
+

Use measured min noise floor of all channels. +

+
+
max
+

Use measured max noise floor of all channels. +

+
+
average
+

Use measured average noise floor of all channels. +

+

Default value is min. +

+
+ +
+
band_multiplier, bm
+

Set the band multiplier factor, used how much to spread bands across frequency bins. +Allowed range is from 0.2 to 5. Default value is 1.25. +

+
+
sample_noise, sn
+

Toggle capturing and measurement of noise profile from input audio. +

+

It accepts the following values: +

+
start, begin
+

Start sample noise capture. +

+
+
stop, end
+

Stop sample noise capture and measure new noise band profile. +

+

Default value is none. +

+
+ +
+
gain_smooth, gs
+

Set gain smooth spatial radius, used to smooth gains applied to each frequency bin. +Useful to reduce random music noise artefacts. +Higher values increases smoothing of gains. +Allowed range is from 0 to 50. +Default value is 0. +

+
+ + +

29.23.1 Commands

+ +

This filter supports the some above mentioned options as commands. +

+ +

29.23.2 Examples

+ +
    +
  • Reduce white noise by 10dB, and use previously measured noise floor of -40dB: +
    +
    afftdn=nr=10:nf=-40
    +
    + +
  • Reduce white noise by 10dB, also set initial noise floor to -80dB and enable automatic +tracking of noise floor so noise floor will gradually change during processing: +
    +
    afftdn=nr=10:nf=-80:tn=1
    +
    + +
  • Reduce noise by 20dB, using noise floor of -40dB and using commands to take noise profile +of first 0.4 seconds of input audio: +
    +
    asendcmd=0.0 afftdn sn start,asendcmd=0.4 afftdn sn stop,afftdn=nr=20:nf=-40
    +
    +
+ + +

29.24 afftfilt

+

Apply arbitrary expressions to samples in frequency domain. +

+
+
real
+

Set frequency domain real expression for each separate channel separated +by ’|’. Default is "re". +If the number of input channels is greater than the number of +expressions, the last specified expression is used for the remaining +output channels. +

+
+
imag
+

Set frequency domain imaginary expression for each separate channel +separated by ’|’. Default is "im". +

+

Each expression in real and imag can contain the following +constants and functions: +

+
+
sr
+

sample rate +

+
+
b
+

current frequency bin number +

+
+
nb
+

number of available bins +

+
+
ch
+

channel number of the current expression +

+
+
chs
+

number of channels +

+
+
pts
+

current frame pts +

+
+
re
+

current real part of frequency bin of current channel +

+
+
im
+

current imaginary part of frequency bin of current channel +

+
+
real(b, ch)
+

Return the value of real part of frequency bin at location (bin,channel) +

+
+
imag(b, ch)
+

Return the value of imaginary part of frequency bin at location (bin,channel) +

+
+ +
+
win_size
+

Set window size. Allowed range is from 16 to 131072. +Default is 4096 +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.75. +

+
+ + +

29.24.1 Examples

+ +
    +
  • Leave almost only low frequencies in audio: +
    +
    afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
    +
    + +
  • Apply robotize effect: +
    +
    afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
    +
    + +
  • Apply whisper effect: +
    +
    afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8"
    +
    + +
  • Apply phase shift: +
    +
    afftfilt="real=re*cos(1)-im*sin(1):imag=re*sin(1)+im*cos(1)"
    +
    +
+ + +

29.25 afir

+ +

Apply an arbitrary Finite Impulse Response filter. +

+

This filter is designed for applying long FIR filters, +up to 60 seconds long. +

+

It can be used as component for digital crossover filters, +room equalization, cross talk cancellation, wavefield synthesis, +auralization, ambiophonics, ambisonics and spatialization. +

+

This filter uses the streams higher than first one as FIR coefficients. +If the non-first stream holds a single channel, it will be used +for all input channels in the first stream, otherwise +the number of channels in the non-first stream must be same as +the number of channels in the first stream. +

+

It accepts the following parameters: +

+
+
dry
+

Set dry gain. This sets input gain. +

+
+
wet
+

Set wet gain. This sets final output gain. +

+
+
length
+

Set Impulse Response filter length. Default is 1, which means whole IR is processed. +

+
+
gtype
+

This option is deprecated, and does nothing. +

+
+
irnorm
+

Set norm to be applied to IR coefficients before filtering. +Allowed range is from -1 to 2. +IR coefficients are normalized with calculated vector norm set by this option. +For negative values, no norm is calculated, and IR coefficients are not modified at all. +Default is 1. +

+
+
irlink
+

For multichannel IR if this option is set to true, all IR channels will be +normalized with maximal measured gain of all IR channels coefficients as set by irnorm option. +When disabled, all IR coefficients in each IR channel will be normalized independently. +Default is true. +

+
+
irgain
+

Set gain to be applied to IR coefficients before filtering. +Allowed range is 0 to 1. This gain is applied after any gain applied with irnorm option. +

+
+
irfmt
+

Set format of IR stream. Can be mono or input. +Default is input. +

+
+
maxir
+

Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. +Allowed range is 0.1 to 60 seconds. +

+
+
response
+

This option is deprecated, and does nothing. +

+
+
channel
+

This option is deprecated, and does nothing. +

+
+
size
+

This option is deprecated, and does nothing. +

+
+
rate
+

This option is deprecated, and does nothing. +

+
+
minp
+

Set minimal partition size used for convolution. Default is 8192. +Allowed range is from 1 to 65536. +Lower values decreases latency at cost of higher CPU usage. +

+
+
maxp
+

Set maximal partition size used for convolution. Default is 8192. +Allowed range is from 8 to 65536. +Lower values may increase CPU usage. +

+
+
nbirs
+

Set number of input impulse responses streams which will be switchable at runtime. +Allowed range is from 1 to 32. Default is 1. +

+
+
ir
+

Set IR stream which will be used for convolution, starting from 0, should always be +lower than supplied value by nbirs option. Default is 0. +This option can be changed at runtime via commands. +

+
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+ +

Default value is auto. +

+
+
irload
+

Set when to load IR stream. Can be init or access. +First one load and prepares all IRs on initialization, second one +once on first access of specific IR. +Default is init. +

+
+ + +

29.25.1 Examples

+ +
    +
  • Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: +
    +
    ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
    +
    + +
  • Apply true stereo processing given input stereo stream, and two stereo impulse responses for left and right channel, +the impulse response files are files with names l_ir.wav and r_ir.wav, and setting irnorm option value: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irnorm=1.2,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    + +
  • Similar to above example, but with irgain explicitly set to estimated value and with irnorm disabled: +
    +
    "pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irgain=-5dB:irnom=-1,pan=stereo|FL<c0+c2|FR<c1+c3"
    +
    +
+ + +

29.26 aformat

+ +

Set output format constraints for the input audio. The framework will +negotiate the most appropriate format to minimize conversions. +

+

It accepts the following parameters: +

+
sample_fmts, f
+

A ’|’-separated list of requested sample formats. +

+
+
sample_rates, r
+

A ’|’-separated list of requested sample rates. +

+
+
channel_layouts, cl
+

A ’|’-separated list of requested channel layouts. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+ +

If a parameter is omitted, all values are allowed. +

+

Force the output to either unsigned 8-bit or signed 16-bit stereo +

+
aformat=sample_fmts=u8|s16:channel_layouts=stereo
+
+ + +

29.27 afreqshift

+

Apply frequency shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify frequency shift. Allowed range is -INT_MAX to INT_MAX. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

29.27.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.28 afwtdn

+

Reduce broadband noise from input samples using Wavelets. +

+

A description of the accepted options follows. +

+
+
sigma
+

Set the noise sigma, allowed range is from 0 to 1. +Default value is 0. +This option controls strength of denoising applied to input samples. +Most useful way to set this option is via decibels, eg. -45dB. +

+
+
levels
+

Set the number of wavelet levels of decomposition. +Allowed range is from 1 to 12. +Default value is 10. +Setting this too low make denoising performance very poor. +

+
+
wavet
+

Set wavelet type for decomposition of input frame. +They are sorted by number of coefficients, from lowest to highest. +More coefficients means worse filtering speed, but overall better quality. +Available wavelets are: +

+
+
‘sym2’
+
‘sym4’
+
‘rbior68’
+
‘deb10’
+
‘sym10’
+
‘coif5’
+
‘bl3’
+
+ +
+
percent
+

Set percent of full denoising. Allowed range is from 0 to 100 percent. +Default value is 85 percent or partial denoising. +

+
+
profile
+

If enabled, first input frame will be used as noise profile. +If first frame samples contain non-noise performance will be very poor. +

+
+
adaptive
+

If enabled, input frames are analyzed for presence of noise. +If noise is detected with high possibility then input frame profile will be +used for processing following frames, until new noise frame is detected. +

+
+
samples
+

Set size of single frame in number of samples. Allowed range is from 512 to +65536. Default frame size is 8192 samples. +

+
+
softness
+

Set softness applied inside thresholding function. Allowed range is from 0 to +10. Default softness is 1. +

+
+ + +

29.28.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.29 agate

+ +

A gate is mainly used to reduce lower parts of a signal. This kind of signal +processing reduces disturbing noise between useful signals. +

+

Gating is done by detecting the volume below a chosen level threshold +and dividing it by the factor set with ratio. The bottom of the noise +floor is set via range. Because an exact manipulation of the signal +would cause distortion of the waveform the reduction can be levelled over +time. This is done by setting attack and release. +

+

attack determines how long the signal has to fall below the threshold +before any reduction will occur and release sets the time the signal +has to rise above the threshold to reduce the reduction again. +Shorter signals than the chosen attack time will be left untouched. +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio by which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+ + +

29.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.30 aiir

+ +

Apply an arbitrary Infinite Impulse Response filter. +

+

It accepts the following parameters: +

+
+
zeros, z
+

Set B/numerator/zeros/reflection coefficients. +

+
+
poles, p
+

Set A/denominator/poles/ladder coefficients. +

+
+
gains, k
+

Set channels gains. +

+
+
dry_gain
+

Set input gain. +

+
+
wet_gain
+

Set output gain. +

+
+
format, f
+

Set coefficients format. +

+
+
‘ll’
+

lattice-ladder function +

+
‘sf’
+

analog transfer function +

+
‘tf’
+

digital transfer function +

+
‘zp’
+

Z-plane zeros/poles, cartesian (default) +

+
‘pr’
+

Z-plane zeros/poles, polar radians +

+
‘pd’
+

Z-plane zeros/poles, polar degrees +

+
‘sp’
+

S-plane zeros/poles +

+
+ +
+
process, r
+

Set type of processing. +

+
+
‘d’
+

direct processing +

+
‘s’
+

serial processing +

+
‘p’
+

parallel processing +

+
+ +
+
precision, e
+

Set filtering precision. +

+
+
‘dbl’
+

double-precision floating-point (default) +

+
‘flt’
+

single-precision floating-point +

+
‘i32’
+

32-bit integers +

+
‘i16’
+

16-bit integers +

+
+ +
+
normalize, n
+

Normalize filter coefficients, by default is enabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
mix
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
response
+

Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. +By default it is disabled. +

+
+
channel
+

Set for which IR channel to display frequency response. By default is first channel +displayed. This option is used only when response is enabled. +

+
+
size
+

Set video stream size. This option is used only when response is enabled. +

+
+ +

Coefficients in tf and sf format are separated by spaces and are in ascending +order. +

+

Coefficients in zp format are separated by spaces and order of coefficients +doesn’t matter. Coefficients in zp format are complex numbers with i +imaginary unit. +

+

Different coefficients and gains can be provided for every channel, in such case +use ’|’ to separate coefficients or gains. Last provided coefficients will be +used for all remaining channels. +

+ +

29.30.1 Examples

+ +
    +
  • Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate: +
    +
    aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
    +
    + +
  • Same as above but in zp format: +
    +
    aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
    +
    + +
  • Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format: +
    +
    aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
    +
    +
+ + +

29.31 alimiter

+ +

The limiter prevents an input signal from rising over a desired threshold. +This limiter uses lookahead technology to prevent your signal from distorting. +It means that there is a small delay after the signal is processed. Keep in mind +that the delay it produces is the attack time you set. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
limit
+

Don’t let signals above this level pass the limiter. Default is 1. +

+
+
attack
+

The limiter will reach its attenuation level in this amount of time in +milliseconds. Default is 5 milliseconds. +

+
+
release
+

Come back from limiting to attenuation 1.0 in this amount of milliseconds. +Default is 50 milliseconds. +

+
+
asc
+

When gain reduction is always needed ASC takes care of releasing to an +average reduction level rather than reaching a reduction of 0 in the release +time. +

+
+
asc_level
+

Select how much the release time is affected by ASC, 0 means nearly no changes +in release time while 1 produces higher release times. +

+
+
level
+

Auto level output signal. Default is enabled. +This normalizes audio back to 0dB if enabled. +

+
+
latency
+

Compensate the delay introduced by using the lookahead buffer set with attack +parameter. Also flush the valid audio data in the lookahead buffer when the +stream hits EOF. +

+
+ +

Depending on picked setting it is recommended to upsample input 2x or 4x times +with aresample before applying this filter. +

+ +

29.32 allpass

+ +

Apply a two-pole all-pass filter with central frequency (in Hz) +frequency, and filter-width 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: +

+
+
frequency, f
+

Set frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
order, o
+

Set the filter order, can be 1 or 2. Default is 2. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+
+
+ + +

29.32.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change allpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change allpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change allpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change allpass mix. +Syntax for the command is : "mix" +

+
+ + +

29.33 aloop

+ +

Loop audio samples. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal number of samples. Default is 0. +

+
+
start
+

Set first sample of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

29.34 amerge

+ +

Merge two or more audio streams into a single multi-channel stream. +

+

All inputs must have the same sample rate, and format. +

+

If inputs do not have the same duration, the output will stop with the +shortest. +

+

The filter accepts the following options: +

+
+
inputs
+

Set the number of inputs. Default is 2. +

+
+
layout_mode
+
+

This option controls how the output channel layout is determined and if the +audio channels are reordered during merge. +

+
+
legacy
+
+

This is the mode how the filter behaved historically so it is the default. +

+

If the channel layouts of the inputs are known and disjoint, and therefore +compatible, the channel layout of the output will be set accordingly and the +channels will be reordered as necessary. If the channel layouts of the inputs +are not disjoint, some of them are unknown, or they are using special channel +layouts, such as ambisonics, the output will have all the channels of the first +input then all the channels of the second input, in that order, and the channel +layout of the output will be the default value corresponding to the total +number of channels. +

+

For example, if the first input is in 2.1 (FL+FR+LF) and the second input +is FC+BL+BR, then the output will be in 5.1, with the channels in the +following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the +first input, b1 is the first channel of the second input). +

+

On the other hand, if both input are in stereo, the output channels will be +in the default order: a1, a2, b1, b2, and the channel layout will be +arbitrarily set to 4.0, which may or may not be the expected value. +

+
+
reset
+

This mode ignores the input channel layouts and does no channel reordering. +The output will have all the channels of the first input, then all the channels +of the second input, in that order, and so on. +

+

The output channel layout will only specify the total channel count. +

+
+
normal
+

This mode keeps channel name and designation information from the input +channels and does no channel reordering. The output will have all the channels +of the first input, then all the channels of the second input, in that order, +and so on. +

+
+
+ +
+
+ + +

29.34.1 Examples

+ +
    +
  • Merge two mono files into a stereo stream: +
    +
    amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
    +
    + +
  • Multiple merges assuming 1 video stream and 6 audio streams in input.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
    +
    +
+ + +

29.35 amix

+ +

Mixes multiple audio inputs into a single output. +

+

Note that this filter only supports float samples (the amerge +and pan audio filters support many formats). If the amix +input has integer samples then aresample will be automatically +inserted to perform the conversion to float samples. +

+

It accepts the following parameters: +

+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
duration
+

How to determine the end-of-stream. +

+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+
+ +
+
dropout_transition
+

The transition time, in seconds, for volume renormalization when an input +stream ends. The default value is 2 seconds. +

+
+
weights
+

Specify weight of each input audio stream as a sequence of numbers separated +by a space. If fewer weights are specified compared to number of inputs, the +last weight is assigned to the remaining inputs. +Default weight for each input is 1. +

+
+
normalize
+

Always scale inputs instead of only doing summation of samples. +Beware of heavy clipping if inputs are not normalized prior or after filtering +by this filter if this option is disabled. By default is enabled. +

+
+ + +

29.35.1 Examples

+ +
    +
  • This will mix 3 input audio streams to a single output with the same duration as the +first input and a dropout transition time of 3 seconds: +
    +
    ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
    +
    + +
  • This will mix one vocal and one music input audio stream to a single output with the same duration as the +longest input. The music will have quarter the weight as the vocals, and the inputs are not normalized: +
    +
    ffmpeg -i VOCALS -i MUSIC -filter_complex amix=inputs=2:duration=longest:dropout_transition=0:weights="1 0.25":normalize=0 OUTPUT
    +
    + +
+ + +

29.35.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
normalize
+

Syntax is same as option with same name. +

+
+ + +

29.36 amultiply

+ +

Multiply first audio stream with second audio stream and store result +in output audio stream. Multiplication is done by multiplying each +sample from first stream with sample at same position from second stream. +

+

With this element-wise multiplication one can create amplitude fades and +amplitude modulations. +

+ +

29.37 anequalizer

+ +

High-order parametric multiband equalizer for each channel. +

+

It accepts the following parameters: +

+
params
+
+

This option string is in format: +"cchn f=cf w=w g=g t=f | ..." +Each equalizer band is separated by ’|’. +

+
+
chn
+

Set channel number to which equalization will be applied. +If input doesn’t have that channel the entry is ignored. +

+
+
f
+

Set central frequency for band. +If input doesn’t have that frequency the entry is ignored. +

+
+
w
+

Set band width in Hertz. +

+
+
g
+

Set band gain in dB. +

+
+
t
+

Set filter type for band, optional, can be: +

+
+
‘0’
+

Butterworth, this is default. +

+
+
‘1’
+

Chebyshev type 1. +

+
+
‘2’
+

Chebyshev type 2. +

+
+
+
+ +
+
curves
+

With this option activated frequency response of anequalizer is displayed +in video stream. +

+
+
size
+

Set video stream size. Only useful if curves option is activated. +

+
+
mgain
+

Set max gain that will be displayed. Only useful if curves option is activated. +Setting this to a reasonable value makes it possible to display gain which is derived from +neighbour bands which are too close to each other and thus produce higher gain +when both are activated. +

+
+
fscale
+

Set frequency scale used to draw frequency response in video output. +Can be linear or logarithmic. Default is logarithmic. +

+
+
colors
+

Set color for each channel curve which is going to be displayed in video stream. +This is list of color names separated by space or by ’|’. +Unrecognised or missing colors will be replaced by white color. +

+
+ + +

29.37.1 Examples

+ +
    +
  • Lower gain by 10 of central frequency 200Hz and width 100 Hz +for first 2 channels using Chebyshev type 1 filter: +
    +
    anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
    +
    +
+ + +

29.37.2 Commands

+ +

This filter supports the following commands: +

+
change
+

Alter existing filter parameters. +Syntax for the commands is : "fN|f=freq|w=width|g=gain" +

+

fN is existing filter number, starting from 0, if no such filter is available +error is returned. +freq set new frequency parameter. +width set new width parameter in Hertz. +gain set new gain parameter in dB. +

+

Full filter invocation with asendcmd may look like this: +asendcmd=c=’4.0 anequalizer change 0|f=200|w=50|g=1’,anequalizer=... +

+
+ + +

29.38 anlmdn

+ +

Reduce broadband noise in audio samples using Non-Local Means algorithm. +

+

Each sample is adjusted by looking for other samples with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +p. Patches are searched in an area of r around the sample. +

+

The filter accepts the following options: +

+
+
strength, s
+

Set denoising strength. Allowed range is from 0.00001 to 10000. Default value is 0.00001. +

+
+
patch, p
+

Set patch radius duration. Allowed range is from 1 to 100 milliseconds. +Default value is 2 milliseconds. +

+
+
research, r
+

Set research radius duration. Allowed range is from 2 to 300 milliseconds. +Default value is 6 milliseconds. +

+
+
output, o
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass noise filtered out. +

+
+
n
+

Pass only noise. +

+

Default value is o. +

+
+ +
+
smooth, m
+

Set smooth factor. Default value is 11. Allowed range is from 1 to 1000. +

+
+ + +

29.38.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.39 anlmf, anlms

+

Apply Normalized Least-Mean-(Squares|Fourth) algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by finding the filter coefficients that +relate to producing the least mean square of the error signal (difference between the desired, +2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set filter order. +

+
+
mu
+

Set filter mu. +

+
+
eps
+

Set the filter eps. +

+
+
leakage
+

Set the filter leakage. +

+
+
out_mode
+

It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

29.39.1 Examples

+ +
    +
  • One of many usages of this filter is noise reduction, input audio is filtered +with same samples that are delayed by fixed amount, one such example for stereo audio is: +
    +
    asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
    +
    +
+ + +

29.39.2 Commands

+ +

This filter supports the same commands as options, excluding option order. +

+ +

29.40 anull

+ +

Pass the audio source unchanged to the output. +

+ +

29.41 apad

+ +

Pad the end of an audio stream with silence. +

+

This can be used together with ffmpeg -shortest to +extend audio streams to the same length as the video stream. +

+

A description of the accepted options follows. +

+
+
packet_size
+

Set silence packet size. Default value is 4096. +

+
+
pad_len
+

Set the number of samples of silence to add to the end. After the +value is reached, the stream is terminated. This option is mutually +exclusive with whole_len. +

+
+
whole_len
+

Set the minimum total number of samples in the output audio stream. If +the value is longer than the input audio length, silence is added to +the end, until the value is reached. This option is mutually exclusive +with pad_len. +

+
+
pad_dur
+

Specify the duration of samples of silence to add. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. +

+
+
whole_dur
+

Specify the minimum total duration in the output audio stream. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. Used only if set to non-negative value. If the value is longer than +the input audio length, silence is added to the end, until the value is reached. +This option is mutually exclusive with pad_dur +

+
+ +

If neither the pad_len nor the whole_len nor pad_dur +nor whole_dur option is set, the filter will add silence to the end of +the input stream indefinitely. +

+

Note that for ffmpeg 4.4 and earlier a zero pad_dur or +whole_dur also caused the filter to add silence indefinitely. +

+ +

29.41.1 Examples

+ +
    +
  • Add 1024 samples of silence to the end of the input: +
    +
    apad=pad_len=1024
    +
    + +
  • Make sure the audio output will contain at least 10000 samples, pad +the input with silence if required: +
    +
    apad=whole_len=10000
    +
    + +
  • Use ffmpeg to pad the audio input with silence, so that the +video stream will always result the shortest and will be converted +until the end in the output file when using the shortest +option: +
    +
    ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
    +
    +
+ + +

29.42 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. +

+
+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.74 +

+
+
delay
+

Set delay in milliseconds. Default is 3.0. +

+
+
decay
+

Set decay. Default is 0.4. +

+
+
speed
+

Set modulation speed in Hz. Default is 0.5. +

+
+
type
+

Set modulation type. Default is triangular. +

+

It accepts the following values: +

+
‘triangular, t’
+
‘sinusoidal, s’
+
+
+
+ + +

29.43 aphaseshift

+

Apply phase shift to input audio samples. +

+

The filter accepts the following options: +

+
+
shift
+

Specify phase shift. Allowed range is from -1.0 to 1.0. +Default value is 0.0. +

+
+
level
+

Set output gain applied to final output. Allowed range is from 0.0 to 1.0. +Default value is 1.0. +

+
+
order
+

Set filter order used for filtering. Allowed range is from 1 to 16. +Default value is 8. +

+
+ + +

29.43.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.44 apsnr

+

Measure Audio Peak Signal-to-Noise Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

29.45 apsyclip

+

Apply Psychoacoustic clipper to input audio stream. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
clip
+

Set the clipping start value. Default value is 0dBFS or 1. +

+
+
diff
+

Output only difference samples, useful to hear introduced distortions. +By default is disabled. +

+
+
adaptive
+

Set strength of adaptive distortion applied. Default value is 0.5. +Allowed range is from 0 to 1. +

+
+
iterations
+

Set number of iterations of psychoacoustic clipper. +Allowed range is from 1 to 20. Default value is 10. +

+
+
level
+

Auto level output signal. Default is disabled. +This normalizes audio back to 0dBFS if enabled. +

+
+ + +

29.45.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.46 apulsator

+ +

Audio pulsator is something between an autopanner and a tremolo. +But it can produce funny stereo effects as well. Pulsator changes the volume +of the left and right channel based on a LFO (low frequency oscillator) with +different waveforms and shifted phases. +This filter have the ability to define an offset between left and right +channel. An offset of 0 means that both LFO shapes match each other. +The left and right channel are altered equally - a conventional tremolo. +An offset of 50% means that the shape of the right channel is exactly shifted +in phase (or moved backwards about half of the frequency) - pulsator acts as +an autopanner. At 1 both curves match again. Every setting in between moves the +phase shift gapless between all stages and produces some "bypassing" sounds with +sine and triangle waveforms. The more you set the offset near 1 (starting from +the 0.5) the faster the signal passes from the left to the right speaker. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
level_out
+

Set output gain. By default it is 1. Range is [0.015625 - 64]. +

+
+
mode
+

Set waveform shape the LFO will use. Can be one of: sine, triangle, square, +sawup or sawdown. Default is sine. +

+
+
amount
+

Set modulation. Define how much of original signal is affected by the LFO. +

+
+
offset_l
+

Set left channel offset. Default is 0. Allowed range is [0 - 1]. +

+
+
offset_r
+

Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. +

+
+
width
+

Set pulse width. Default is 1. Allowed range is [0 - 2]. +

+
+
timing
+

Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. +

+
+
bpm
+

Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing +is set to bpm. +

+
+
ms
+

Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing +is set to ms. +

+
+
hz
+

Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used +if timing is set to hz. +

+
+ + +

29.47 aresample

+ +

Resample the input audio to the specified parameters, using the +libswresample library. If none are specified then the filter will +automatically convert between its input and output. +

+

This filter is also able to stretch/squeeze the audio data to make it match +the timestamps or to inject silence / cut out audio to make it match the +timestamps, do a combination of both or do neither. +

+

The filter accepts the syntax +[sample_rate:]resampler_options, where sample_rate +expresses a sample rate and resampler_options is a list of +key=value pairs, separated by ":". See the +"Resampler Options" section in the +ffmpeg-resampler(1) manual +for the complete list of supported options. +

+ +

29.47.1 Examples

+ +
    +
  • Resample the input audio to 44100Hz: +
    +
    aresample=44100
    +
    + +
  • Stretch/squeeze samples to the given timestamps, with a maximum of 1000 +samples per second compensation: +
    +
    aresample=async=1000
    +
    +
+ + +

29.48 areverse

+ +

Reverse an audio clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

29.48.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    atrim=end=5,areverse
    +
    +
+ + +

29.49 arls

+

Apply Recursive Least Squares algorithm to the first audio stream using the second audio stream. +

+

This adaptive filter is used to mimic a desired filter by recursively finding the filter coefficients that +relate to producing the minimal weighted linear least squares cost function of the error signal (difference +between the desired, 2nd input audio stream and the actual signal, the 1st input audio stream). +

+

A description of the accepted options follows. +

+
+
order
+

Set the filter order. +

+
+
lambda
+

Set the forgetting factor. +

+
+
delta
+

Set the coefficient to initialize internal covariance matrix. +

+
+
out_mode
+

Set the filter output samples. It accepts the following values: +

+
i
+

Pass the 1st input. +

+
+
d
+

Pass the 2nd input. +

+
+
o
+

Pass difference between desired, 2nd input and error signal estimate. +

+
+
n
+

Pass difference between input, 1st input and error signal estimate. +

+
+
e
+

Pass error signal estimated samples. +

+

Default value is o. +

+
+ +
+
precision
+

Set which precision to use when processing samples. +

+
+
auto
+

Auto pick internal sample format depending on other filters. +

+
+
float
+

Always use single-floating point precision sample format. +

+
+
double
+

Always use double-floating point precision sample format. +

+
+
+
+ + +

29.50 arnndn

+ +

Reduce noise from speech using Recurrent Neural Networks. +

+

This filter accepts the following options: +

+
+
model, m
+

Set train model file to load. This option is always required. +

+
+
mix
+

Set how much to mix filtered samples into final output. +Allowed range is from -1 to 1. Default value is 1. +Negative values are special, they set how much to keep filtered noise +in the final filter output. Set this option to -1 to hear actual +noise removed from input signal. +

+
+ + +

29.50.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.51 asdr

+

Measure Audio Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

29.52 asetnsamples

+ +

Set the number of samples per each output audio frame. +

+

The last output packet may contain a different number of samples, as +the filter will flush all the remaining samples when the input audio +signals its end. +

+

The filter accepts the following options: +

+
+
nb_out_samples, n
+

Set the number of frames per each output audio frame. The number is +intended as the number of samples per each channel. +Default value is 1024. +

+
+
pad, p
+

If set to 1, the filter will pad the last audio frame with zeroes, so +that the last frame will contain the same number of samples as the +previous ones. Default value is 1. +

+
+ +

For example, to set the number of per-frame samples to 1234 and +disable padding for the last frame, use: +

+
asetnsamples=n=1234:p=0
+
+ + +

29.53 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: +

+
+
sample_rate, r
+

Set the output sample rate. Default is 44100 Hz. +

+
+ + +

29.54 ashowinfo

+ +

Show a line containing various information for each input audio frame. +The input audio is not modified. +

+

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The presentation timestamp of the input frame, in time base units; the time base +depends on the filter input pad, and is usually 1/sample_rate. +

+
+
pts_time
+

The presentation timestamp of the input frame in seconds. +

+
+
fmt
+

The sample format. +

+
+
chlayout
+

The channel layout. +

+
+
rate
+

The sample rate for the audio frame. +

+
+
nb_samples
+

The number of samples (per channel) in the frame. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar +audio, the data is treated as if all the planes were concatenated. +

+
+
plane_checksums
+

A list of Adler-32 checksums for each data plane. +

+
+ + +

29.55 asisdr

+

Measure Audio Scaled-Invariant Signal-to-Distortion Ratio. +

+

This filter takes two audio streams for input, and outputs first +audio stream. +Results are in dB per channel at end of either input. +

+ +

29.56 asoftclip

+

Apply audio soft clipping. +

+

Soft clipping is a type of distortion effect where the amplitude of a signal is saturated +along a smooth curve, rather than the abrupt shape of hard-clipping. +

+

This filter accepts the following options: +

+
+
type
+

Set type of soft-clipping. +

+

It accepts the following values: +

+
hard
+
tanh
+
atan
+
cubic
+
exp
+
alg
+
quintic
+
sin
+
erf
+
+ +
+
threshold
+

Set threshold from where to start clipping. Default value is 0dB or 1. +

+
+
output
+

Set gain applied to output. Default value is 0dB or 1. +

+
+
param
+

Set additional parameter which controls sigmoid function. +

+
+
oversample
+

Set oversampling factor. +

+
+ + +

29.56.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.57 aspectralstats

+ +

Display frequency domain statistical information about the audio channels. +Statistics are calculated and stored as metadata for each audio channel and for each audio frame. +

+

It accepts the following option: +

+
win_size
+

Set the window length in samples. Default value is 2048. +Allowed range is from 32 to 65536. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. Allowed range is from 0 +to 1. Default value is 0.5. +

+
+
measure
+

Select the parameters which are measured. The metadata keys can +be used as flags, default is all which measures everything. +none disables all measurement. +

+
+ +

A list of each metadata key follows: +

+
+
mean
+
variance
+
centroid
+
spread
+
skewness
+
kurtosis
+
entropy
+
flatness
+
crest
+
flux
+
slope
+
decrease
+
rolloff
+
+ + +

29.58 asr

+

Automatic Speech Recognition +

+

This filter uses PocketSphinx for speech recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-pocketsphinx. +

+

It accepts the following options: +

+
+
rate
+

Set sampling rate of input audio. Defaults is 16000. +This need to match speech models, otherwise one will get poor results. +

+
+
hmm
+

Set dictionary containing acoustic model files. +

+
+
dict
+

Set pronunciation dictionary. +

+
+
lm
+

Set language model file. +

+
+
lmctl
+

Set language model set. +

+
+
lmname
+

Set which language model to use. +

+
+
logfn
+

Set output for log messages. +

+
+ +

The filter exports recognized speech as the frame metadata lavfi.asr.text. +

+ +

29.59 astats

+ +

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. +

+

It accepts the following option: +

+
length
+

Short window length in seconds, used for peak and through RMS measurement. +Default is 0.05 (50 milliseconds). Allowed range is [0 - 10]. +

+
+
metadata
+
+

Set metadata injection. All the metadata keys are prefixed with lavfi.astats.X, +where X is channel number starting from 1 or string Overall. Default is +disabled. +

+

Available keys for each channel are: +Bit_depth +Crest_factor +DC_offset +Dynamic_range +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_peak +RMS_trough +Zero_crossings +Zero_crossings_rate +

+

and for Overall: +Bit_depth +DC_offset +Entropy +Flat_factor +Max_difference +Max_level +Mean_difference +Min_difference +Min_level +Noise_floor +Noise_floor_count +Number_of_Infs +Number_of_NaNs +Number_of_denormals +Number_of_samples +Peak_count +Abs_Peak_count +Peak_level +RMS_difference +RMS_level +RMS_peak +RMS_trough +

+

For example, a full key looks like lavfi.astats.1.DC_offset or +lavfi.astats.Overall.Peak_count. +

+

Read below for the description of the keys. +

+
+
reset
+

Set the number of frames over which cumulative stats are calculated before +being reset. Default is disabled. +

+
+
measure_perchannel
+

Select the parameters which are measured per channel. The metadata keys can +be used as flags, default is all which measures everything. +none disables all per channel measurement. +

+
+
measure_overall
+

Select the parameters which are measured overall. The metadata keys can +be used as flags, default is all which measures everything. +none disables all overall measurement. +

+
+
+ +

A description of the measure keys follow: +

+
+
none
+

no measures +

+
+
all
+

all measures +

+
+
Bit_depth
+

overall bit depth of audio, i.e. number of bits used for each sample +

+
+
Crest_factor
+

standard ratio of peak to RMS level (note: not in dB) +

+
+
DC_offset
+

mean amplitude displacement from zero +

+
+
Dynamic_range
+

measured dynamic range of audio in dB +

+
+
Entropy
+

entropy measured across whole audio, entropy of value near 1.0 is typically measured for white noise +

+
+
Flat_factor
+

flatness (i.e. consecutive samples with the same value) of the signal at its peak levels +(i.e. either Min_level or Max_level) +

+
+
Max_difference
+

maximal difference between two consecutive samples +

+
+
Max_level
+

maximal sample level +

+
+
Mean_difference
+

mean difference between two consecutive samples, i.e. the average of each difference between two consecutive samples +

+
+
Min_difference
+

minimal difference between two consecutive samples +

+
+
Min_level
+

minimal sample level +

+
+
Noise_floor
+

minimum local peak measured in dBFS over a short window +

+
+
Noise_floor_count
+

number of occasions (not the number of samples) that the signal attained +Noise floor +

+
+
Number_of_Infs
+

number of samples with an infinite value +

+
+
Number_of_NaNs
+

number of samples with a NaN (not a number) value +

+
+
Number_of_denormals
+

number of samples with a subnormal value +

+
+
Number_of_samples
+

number of samples +

+
+
Peak_count
+

number of occasions (not the number of samples) that the signal attained either +Min_level or Max_level +

+
+
Abs_Peak_count
+

number of occasions that the absolute samples taken from the signal attained +max absolute value of Min_level and Max_level +

+
+
Peak_level
+

standard peak level measured in dBFS +

+
+
RMS_difference
+

Root Mean Square difference between two consecutive samples +

+
+
RMS_level
+

standard RMS level measured in dBFS +

+
+
RMS_peak
+
RMS_trough
+

peak and through values for RMS level measured over a short window, +measured in dBFS. +

+
+
Zero crossings
+

number of points where the waveform crosses the zero level axis +

+
+
Zero crossings rate
+

rate of Zero crossings and number of audio samples +

+
+ + +

29.60 asubboost

+

Boost subwoofer frequencies. +

+

The filter accepts the following options: +

+
+
dry
+

Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
wet
+

Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1. +Default value is 1.0. +

+
+
boost
+

Set max boost factor. Allowed range is from 1 to 12. Default value is 2. +

+
+
decay
+

Set delay line decay gain value. Allowed range is from 0 to 1. +Default value is 0.0. +

+
+
feedback
+

Set delay line feedback gain value. Allowed range is from 0 to 1. +Default value is 0.9. +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 50 to 900. +Default value is 100. +

+
+
slope
+

Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1. +Default value is 0.5. +

+
+
delay
+

Set delay. Allowed range is from 1 to 100. +Default value is 20. +

+
+
channels
+

Set the channels to process. Default value is all available. +

+
+ + +

29.60.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.61 asubcut

+

Cut subwoofer frequencies. +

+

This filter allows to set custom, steeper +roll off than highpass filter, and thus is able to more attenuate +frequency content in stop-band. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 2 to 200. +Default value is 20. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

29.61.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.62 asupercut

+

Cut super frequencies. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set cutoff frequency in Hertz. Allowed range is 20000 to 192000. +Default value is 20000. +

+
+
order
+

Set filter order. Available values are from 3 to 20. +Default value is 10. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 1. Default value is 1. +

+
+ + +

29.62.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.63 asuperpass

+

Apply high order Butterworth band-pass filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

29.63.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.64 asuperstop

+

Apply high order Butterworth band-stop filter. +

+

The filter accepts the following options: +

+
+
centerf
+

Set center frequency in Hertz. Allowed range is 2 to 999999. +Default value is 1000. +

+
+
order
+

Set filter order. Available values are from 4 to 20. +Default value is 4. +

+
+
qfactor
+

Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. +

+
+
level
+

Set input gain level. Allowed range is from 0 to 2. Default value is 1. +

+
+ + +

29.64.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.65 atempo

+ +

Adjust audio tempo. +

+

The filter accepts exactly one parameter, the audio tempo. If not +specified then the filter will assume nominal 1.0 tempo. Tempo must +be in the [0.5, 100.0] range. +

+

Note that tempo greater than 2 will skip some samples rather than +blend them in. If for any reason this is a concern it is always +possible to daisy-chain several instances of atempo to achieve the +desired product tempo. +

+ +

29.65.1 Examples

+ +
    +
  • Slow down audio to 80% tempo: +
    +
    atempo=0.8
    +
    + +
  • To speed up audio to 300% tempo: +
    +
    atempo=3
    +
    + +
  • To speed up audio to 300% tempo by daisy-chaining two atempo instances: +
    +
    atempo=sqrt(3),atempo=sqrt(3)
    +
    +
+ + +

29.65.2 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+ + +

29.66 atilt

+

Apply spectral tilt filter to audio stream. +

+

This filter apply any spectral roll-off slope over any specified frequency band. +

+

The filter accepts the following options: +

+
+
freq
+

Set central frequency of tilt in Hz. Default is 10000 Hz. +

+
+
slope
+

Set slope direction of tilt. Default is 0. Allowed range is from -1 to 1. +

+
+
width
+

Set width of tilt. Default is 1000. Allowed range is from 100 to 10000. +

+
+
order
+

Set order of tilt filter. +

+
+
level
+

Set input volume level. Allowed range is from 0 to 4. +Default is 1. +

+
+ + +

29.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.67 atrim

+ +

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Timestamp (in seconds) of the start of the section to keep. I.e. the audio +sample with the timestamp start will be the first sample in the output. +

+
+
end
+

Specify time of the first audio sample that will be dropped, i.e. the +audio sample immediately preceding the one with the timestamp end will be +the last sample in the output. +

+
+
start_pts
+

Same as start, except this option sets the start timestamp in samples +instead of seconds. +

+
+
end_pts
+

Same as end, except this option sets the end timestamp in samples instead +of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_sample
+

The number of the first sample that should be output. +

+
+
end_sample
+

The number of the first sample that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual. +

+

Note that the first two sets of the start/end options and the 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 +to have 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -af atrim=60:120
    +
    + +
  • Keep only the first 1000 samples: +
    +
    ffmpeg -i INPUT -af atrim=end_sample=1000
    +
    + +
+ + +

29.68 axcorrelate

+

Calculate normalized windowed cross-correlation between two input audio streams. +

+

Resulted samples are always between -1 and 1 inclusive. +If result is 1 it means two input samples are highly correlated in that selected segment. +Result 0 means they are not correlated at all. +If result is -1 it means two input samples are out of phase, which means they cancel each +other. +

+

The filter accepts the following options: +

+
+
size
+

Set size of segment over which cross-correlation is calculated. +Default is 256. Allowed range is from 2 to 131072. +

+
+
algo
+

Set algorithm for cross-correlation. Can be slow or fast or best. +Default is best. Fast algorithm assumes mean values over any given segment +are always zero and thus need much less calculations to make. +This is generally not true, but is valid for typical audio streams. +

+
+ + +

29.68.1 Examples

+ +
    +
  • Calculate correlation between channels in stereo audio stream: +
    +
    ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
    +
    +
+ + +

29.69 bandpass

+ +

Apply a two-pole Butterworth band-pass filter with central +frequency frequency, and (3dB-point) band-width width. +The 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: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
csg
+

Constant skirt gain if set to 1. Defaults to 0. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.69.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandpass mix. +Syntax for the command is : "mix" +

+
+ + +

29.70 bandreject

+ +

Apply a two-pole Butterworth band-reject filter with central +frequency frequency, and (3dB-point) band-width width. +The filter roll off at 6dB per octave (20dB per decade). +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the filter’s central frequency. Default is 3000. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.70.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bandreject frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bandreject width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bandreject width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change bandreject mix. +Syntax for the command is : "mix" +

+
+ + +

29.71 bass, lowshelf

+ +

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: +

+
+
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. +

+
+
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 100 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.71.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change bass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change bass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change bass width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change bass gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change bass mix. +Syntax for the command is : "mix" +

+
+ + +

29.72 biquad

+ +

Apply a biquad IIR filter with the given coefficients. +Where b0, b1, b2 and a0, a1, a2 +are the numerator and denominator coefficients respectively. +and channels, c specify which channels to filter, by default all +available are filtered. +

+ +

29.72.1 Commands

+ +

This filter supports the following commands: +

+
a0
+
a1
+
a2
+
b0
+
b1
+
b2
+

Change biquad parameter. +Syntax for the command is : "value" +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.73 bs2b

+

Bauer stereo to binaural transformation, which improves headphone listening of +stereo audio records. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libbs2b. +

+

It accepts the following parameters: +

+
profile
+

Pre-defined crossfeed level. +

+
default
+

Default level (fcut=700, feed=50). +

+
+
cmoy
+

Chu Moy circuit (fcut=700, feed=60). +

+
+
jmeier
+

Jan Meier circuit (fcut=650, feed=95). +

+
+
+ +
+
fcut
+

Cut frequency (in Hz). +

+
+
feed
+

Feed level (in Hz). +

+
+
+ + +

29.74 channelmap

+ +

Remap input channels to new locations. +

+

It accepts the following parameters: +

+
map
+

Map channels from input to output. The argument is a ’|’-separated list of +mappings, each in the in_channel-out_channel or +in_channel form. 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. out_channel is the name of the output channel or its index in the +output channel layout. If out_channel is not given then it is implicitly +an index, starting with zero and increasing by one for each mapping. Mixing +different types of mappings is not allowed and will result in a parse error. +

+
+
channel_layout
+

The channel layout of the output stream. If not specified, then filter will +guess it based on the out_channel names or the number of mappings. +Guessed layouts will not necessarily contain channels in the order of the +mappings. +

+
+ +

If no mapping is present, the filter will implicitly map input channels to +output channels, preserving indices. +

+ +

29.74.1 Examples

+ +
    +
  • For example, assuming a 5.1+downmix input MOV file, +
    +
    ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
    +
    +

    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 +
    +
    ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
    +
    +
+ + +

29.75 channelsplit

+ +

Split each channel from an input audio stream into a separate output stream. +

+

It accepts the following parameters: +

+
channel_layout
+

The channel layout of the input stream. The default is "stereo". +

+
channels
+

A channel layout describing the channels to be extracted as separate output streams +or "all" to extract each input channel as a separate stream. The default is "all". +

+

Choosing channels not present in channel layout in the input will result in an error. +

+
+ + +

29.75.1 Examples

+ +
    +
  • For example, assuming a stereo input MP3 file, +
    +
    ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
    +
    +

    will create an output Matroska file with two audio streams, one containing only +the left channel and the other the right channel. +

    +
  • Split a 5.1 WAV file into per-channel files: +
    +
    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
    +
    + +
  • Extract only LFE from a 5.1 WAV file: +
    +
    ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
    +-map '[LFE]' lfe.wav
    +
    +
+ + +

29.76 chorus

+

Add a chorus effect to the audio. +

+

Can make a single vocal sound like a chorus, but can also be applied to instrumentation. +

+

Chorus resembles an echo effect with a short delay, but whereas with echo the delay is +constant, with chorus, it is varied using sinusoidal or triangular modulation. +The modulation depth defines the range the modulated delay is played before or after +the delay. Hence the delayed sound will sound slower or faster, that is the delayed +sound tuned around the original one, like in a chorus where some vocals are slightly +off key. +

+

It accepts the following parameters: +

+
in_gain
+

Set input gain. Default is 0.4. +

+
+
out_gain
+

Set output gain. Default is 0.4. +

+
+
delays
+

Set delays. A typical delay is around 40ms to 60ms. +

+
+
decays
+

Set decays. +

+
+
speeds
+

Set speeds. +

+
+
depths
+

Set depths. +

+
+ + +

29.76.1 Examples

+ +
    +
  • A single delay: +
    +
    chorus=0.7:0.9:55:0.4:0.25:2
    +
    + +
  • Two delays: +
    +
    chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
    +
    + +
  • Fuller sounding chorus with three delays: +
    +
    chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3
    +
    +
+ + +

29.77 compand

+

Compress or expand the audio’s dynamic range. +

+

It accepts the following parameters: +

+
+
attacks
+
decays
+

A list of times in seconds for each channel over which the instantaneous level +of the input signal is averaged to determine its volume. attacks refers to +increase of volume and 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. A typical value for attack is 0.3 seconds and +a typical value for decay is 0.8 seconds. +If specified number of attacks & decays is lower than number of channels, the last +set attack/decay will be used for all remaining channels. +

+
+
points
+

A list of points for the transfer function, specified in dB relative to the +maximum possible signal amplitude. Each key points list must be defined using +the following syntax: x0/y0|x1/y1|x2/y2|.... or +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 0/0 is assumed but +may be overridden (by 0/out-dBn). Typical values for the transfer +function are -70/-70|-60/-20|1/0. +

+
+
soft-knee
+

Set the curve radius in dB for all joints. It defaults to 0.01. +

+
+
gain
+

Set the additional gain in dB to be applied at all points on the transfer +function. This allows for easy adjustment of the overall gain. +It defaults to 0. +

+
+
volume
+

Set an 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. It defaults to 0. +

+
+
delay
+

Set a delay, in seconds. The input audio is analyzed 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. It defaults to 0. +

+
+
+ + +

29.77.1 Examples

+ +
    +
  • Make music with both quiet and loud passages suitable for listening to in a +noisy environment: +
    +
    compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
    +
    + +

    Another example for audio with whisper and explosion parts: +

    +
    compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
    +
    + +
  • A noise gate for when the noise is at a lower level than the signal: +
    +
    compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
    +
    + +
  • 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): +
    +
    compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
    +
    + +
  • 2:1 compression starting at -6dB: +
    +
    compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
    +
    + +
  • 2:1 compression starting at -9dB: +
    +
    compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
    +
    + +
  • 2:1 compression starting at -12dB: +
    +
    compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
    +
    + +
  • 2:1 compression starting at -18dB: +
    +
    compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
    +
    + +
  • 3:1 compression starting at -15dB: +
    +
    compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
    +
    + +
  • Compressor/Gate: +
    +
    compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
    +
    + +
  • Expander: +
    +
    compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
    +
    + +
  • Hard limiter at -6dB: +
    +
    compand=attacks=0:points=-80/-80|-6/-6|20/-6
    +
    + +
  • Hard limiter at -12dB: +
    +
    compand=attacks=0:points=-80/-80|-12/-12|20/-12
    +
    + +
  • Hard noise gate at -35 dB: +
    +
    compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
    +
    + +
  • Soft limiter: +
    +
    compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
    +
    +
+ + +

29.78 compensationdelay

+ +

Compensation Delay Line is a metric based delay to compensate differing +positions of microphones or speakers. +

+

For example, you have recorded guitar with two microphones placed in +different locations. Because the front of sound wave has fixed speed in +normal conditions, the phasing of microphones can vary and depends on +their location and interposition. The best sound mix can be achieved when +these microphones are in phase (synchronized). Note that a distance of +~30 cm between microphones makes one microphone capture the signal in +antiphase to the other microphone. That makes the final mix sound moody. +This filter helps to solve phasing problems by adding different delays +to each microphone track and make them synchronized. +

+

The best result can be reached when you take one track as base and +synchronize other tracks one by one with it. +Remember that synchronization/delay tolerance depends on sample rate, too. +Higher sample rates will give more tolerance. +

+

The filter accepts the following parameters: +

+
+
mm
+

Set millimeters distance. This is compensation distance for fine tuning. +Default is 0. +

+
+
cm
+

Set cm distance. This is compensation distance for tightening distance setup. +Default is 0. +

+
+
m
+

Set meters distance. This is compensation distance for hard distance setup. +Default is 0. +

+
+
dry
+

Set dry amount. Amount of unprocessed (dry) signal. +Default is 0. +

+
+
wet
+

Set wet amount. Amount of processed (wet) signal. +Default is 1. +

+
+
temp
+

Set temperature in degrees Celsius. This is the temperature of the environment. +Default is 20. +

+
+ + +

29.78.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.79 crossfeed

+

Apply headphone crossfeed filter. +

+

Crossfeed is the process of blending the left and right channels of stereo +audio recording. +It is mainly used to reduce extreme stereo separation of low frequencies. +

+

The intent is to produce more speaker like sound to the listener. +

+

The filter accepts the following options: +

+
+
strength
+

Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. +This sets gain of low shelf filter for side part of stereo image. +Default is -6dB. Max allowed is -30db when strength is set to 1. +

+
+
range
+

Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. +This sets cut off frequency of low shelf filter. Default is cut off near +1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. +

+
+
slope
+

Set curve slope of low shelf filter. Default is 0.5. +Allowed range is from 0.01 to 1. +

+
+
level_in
+

Set input gain. Default is 0.9. +

+
+
level_out
+

Set output gain. Default is 1. +

+
+
block_size
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.79.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.80 crystalizer

+

Simple algorithm for audio noise sharpening. +

+

This filter linearly increases differences between each audio sample. +

+

The filter accepts the following options: +

+
+
i
+

Sets the intensity of effect (default: 2.0). Must be in range between -10.0 to 0 +(unchanged sound) to 10.0 (maximum effect). +To inverse filtering use negative value. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

29.80.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.81 dcshift

+

Apply a DC shift to the audio. +

+

This can be useful to remove a DC offset (caused perhaps by a hardware problem +in the recording chain) from the audio. The effect of a DC offset is reduced +headroom and hence volume. The astats filter can be used to determine if +a signal has a DC offset. +

+
+
shift
+

Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift +the audio. +

+
+
limitergain
+

Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is +used to prevent clipping. +

+
+ + +

29.82 deesser

+ +

Apply de-essing to the audio samples. +

+
+
i
+

Set intensity for triggering de-essing. Allowed range is from 0 to 1. +Default is 0. +

+
+
m
+

Set amount of ducking on treble part of sound. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
f
+

How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1. +Default is 0.5. +

+
+
s
+

Set the output mode. +

+

It accepts the following values: +

+
i
+

Pass input unchanged. +

+
+
o
+

Pass ess filtered out. +

+
+
e
+

Pass only ess. +

+

Default value is o. +

+
+ +
+
+ + +

29.83 dialoguenhance

+

Enhance dialogue in stereo audio. +

+

This filter accepts stereo input and produce surround (3.0) channels output. +The newly produced front center channel have enhanced speech dialogue originally +available in both stereo channels. +This filter outputs front left and front right channels same as available in stereo input. +

+

The filter accepts the following options: +

+
+
original
+

Set the original center factor to keep in front center channel output. +Allowed range is from 0 to 1. Default value is 1. +

+
+
enhance
+

Set the dialogue enhance factor to put in front center channel output. +Allowed range is from 0 to 3. Default value is 1. +

+
+
voice
+

Set the voice detection factor. +Allowed range is from 2 to 32. Default value is 2. +

+
+ + +

29.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.84 drmeter

+

Measure audio dynamic range. +

+

DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 +is found in transition material. And anything less that 8 have very poor dynamics +and is very compressed. +

+

The filter accepts the following options: +

+
+
length
+

Set window length in seconds used to split audio into segments of equal length. +Default is 3 seconds. +

+
+ + +

29.85 dynaudnorm

+

Dynamic Audio Normalizer. +

+

This filter applies a certain amount of gain to the input audio in order +to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in +contrast to more "simple" normalization algorithms, the Dynamic Audio +Normalizer *dynamically* re-adjusts the gain factor to the input audio. +This allows for applying extra gain to the "quiet" sections of the audio +while avoiding distortions or clipping the "loud" sections. In other words: +The Dynamic Audio Normalizer will "even out" the volume of quiet and loud +sections, in the sense that the volume of each section is brought to the +same target level. Note, however, that the Dynamic Audio Normalizer achieves +this goal *without* applying "dynamic range compressing". It will retain 100% +of the dynamic range *within* each section of the audio file. +

+
+
framelen, f
+

Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. +Default is 500 milliseconds. +The Dynamic Audio Normalizer processes the input audio in small chunks, +referred to as frames. This is required, because a peak magnitude has no +meaning for just a single sample value. Instead, we need to determine the +peak magnitude for a contiguous sequence of sample values. While a "standard" +normalizer would simply use the peak magnitude of the complete file, the +Dynamic Audio Normalizer determines the peak magnitude individually for each +frame. The length of a frame is specified in milliseconds. By default, the +Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has +been found to give good results with most files. +Note that the exact frame length, in number of samples, will be determined +automatically, based on the sampling rate of the individual input audio file. +

+
+
gausssize, g
+

Set the Gaussian filter window size. In range from 3 to 301, must be odd +number. Default is 31. +Probably the most important parameter of the Dynamic Audio Normalizer is the +window size of the Gaussian smoothing filter. The filter’s window size +is specified in frames, centered around the current frame. For the sake of +simplicity, this must be an odd number. Consequently, the default value of 31 +takes into account the current frame, as well as the 15 preceding frames and +the 15 subsequent frames. Using a larger window results in a stronger +smoothing effect and thus in less gain variation, i.e. slower gain +adaptation. Conversely, using a smaller window results in a weaker smoothing +effect and thus in more gain variation, i.e. faster gain adaptation. +In other words, the more you increase this value, the more the Dynamic Audio +Normalizer will behave like a "traditional" normalization filter. On the +contrary, the more you decrease this value, the more the Dynamic Audio +Normalizer will behave like a dynamic range compressor. +

+
+
peak, p
+

Set the target peak value. This specifies the highest permissible magnitude +level for the normalized audio input. This filter will try to approach the +target peak magnitude as closely as possible, but at the same time it also +makes sure that the normalized signal will never exceed the peak magnitude. +A frame’s maximum local gain factor is imposed directly by the target peak +magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. +It is not recommended to go above this value. +

+
+
maxgain, m
+

Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. +The Dynamic Audio Normalizer determines the maximum possible (local) gain +factor for each input frame, i.e. the maximum gain factor that does not +result in clipping or distortion. The maximum gain factor is determined by +the frame’s highest magnitude sample. However, the Dynamic Audio Normalizer +additionally bounds the frame’s maximum gain factor by a predetermined +(global) maximum gain factor. This is done in order to avoid excessive gain +factors in "silent" or almost silent frames. By default, the maximum gain +factor is 10.0, For most inputs the default value should be sufficient and +it usually is not recommended to increase this value. Though, for input +with an extremely low overall volume level, it may be necessary to allow even +higher gain factors. Note, however, that the Dynamic Audio Normalizer does +not simply apply a "hard" threshold (i.e. cut off values above the threshold). +Instead, a "sigmoid" threshold function will be applied. This way, the +gain factors will smoothly approach the threshold value, but never exceed that +value. +

+
+
targetrms, r
+

Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. +By default, the Dynamic Audio Normalizer performs "peak" normalization. +This means that the maximum local gain factor for each frame is defined +(only) by the frame’s highest magnitude sample. This way, the samples can +be amplified as much as possible without exceeding the maximum signal +level, i.e. without clipping. Optionally, however, the Dynamic Audio +Normalizer can also take into account the frame’s root mean square, +abbreviated RMS. In electrical engineering, the RMS is commonly used to +determine the power of a time-varying signal. It is therefore considered +that the RMS is a better approximation of the "perceived loudness" than +just looking at the signal’s peak magnitude. Consequently, by adjusting all +frames to a constant RMS value, a uniform "perceived loudness" can be +established. If a target RMS value has been specified, a frame’s local gain +factor is defined as the factor that would result in exactly that RMS value. +Note, however, that the maximum local gain factor is still restricted by the +frame’s highest magnitude sample, in order to prevent clipping. +

+
+
coupling, n
+

Enable channels coupling. By default is enabled. +By default, the Dynamic Audio Normalizer will amplify all channels by the same +amount. This means the same gain factor will be applied to all channels, i.e. +the maximum possible gain factor is determined by the "loudest" channel. +However, in some recordings, it may happen that the volume of the different +channels is uneven, e.g. one channel may be "quieter" than the other one(s). +In this case, this option can be used to disable the channel coupling. This way, +the gain factor will be determined independently for each channel, depending +only on the individual channel’s highest magnitude sample. This allows for +harmonizing the volume of the different channels. +

+
+
correctdc, c
+

Enable DC bias correction. By default is disabled. +An audio signal (in the time domain) is a sequence of sample values. +In the Dynamic Audio Normalizer these sample values are represented in the +-1.0 to 1.0 range, regardless of the original input format. Normally, the +audio signal, or "waveform", should be centered around the zero point. +That means if we calculate the mean value of all samples in a file, or in a +single frame, then the result should be 0.0 or at least very close to that +value. If, however, there is a significant deviation of the mean value from +0.0, in either positive or negative direction, this is referred to as a +DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic +Audio Normalizer provides optional DC bias correction. +With DC bias correction enabled, the Dynamic Audio Normalizer will determine +the mean value, or "DC correction" offset, of each input frame and subtract +that value from all of the frame’s sample values which ensures those samples +are centered around 0.0 again. Also, in order to avoid "gaps" at the frame +boundaries, the DC correction offset values will be interpolated smoothly +between neighbouring frames. +

+
+
altboundary, b
+

Enable alternative boundary mode. By default is disabled. +The Dynamic Audio Normalizer takes into account a certain neighbourhood +around each frame. This includes the preceding frames as well as the +subsequent frames. However, for the "boundary" frames, located at the very +beginning and at the very end of the audio file, not all neighbouring +frames are available. In particular, for the first few frames in the audio +file, the preceding frames are not known. And, similarly, for the last few +frames in the audio file, the subsequent frames are not known. Thus, the +question arises which gain factors should be assumed for the missing frames +in the "boundary" region. The Dynamic Audio Normalizer implements two modes +to deal with this situation. The default boundary mode assumes a gain factor +of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and +"fade out" at the beginning and at the end of the input, respectively. +

+
+
compress, s
+

Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. +By default, the Dynamic Audio Normalizer does not apply "traditional" +compression. This means that signal peaks will not be pruned and thus the +full dynamic range will be retained within each local neighbourhood. However, +in some cases it may be desirable to combine the Dynamic Audio Normalizer’s +normalization algorithm with a more "traditional" compression. +For this purpose, the Dynamic Audio Normalizer provides an optional compression +(thresholding) function. If (and only if) the compression feature is enabled, +all input frames will be processed by a soft knee thresholding function prior +to the actual normalization process. Put simply, the thresholding function is +going to prune all samples whose magnitude exceeds a certain threshold value. +However, the Dynamic Audio Normalizer does not simply apply a fixed threshold +value. Instead, the threshold value will be adjusted for each individual +frame. +In general, smaller parameters result in stronger compression, and vice versa. +Values below 3.0 are not recommended, because audible distortion may appear. +

+
+
threshold, t
+

Set the target threshold value. This specifies the lowest permissible +magnitude level for the audio input which will be normalized. +If input frame volume is above this value frame will be normalized. +Otherwise frame may not be normalized at all. The default value is set +to 0, which means all input frames will be normalized. +This option is mostly useful if digital noise is not wanted to be amplified. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
overlap, o
+

Specify overlap for frames. If set to 0 (default) no frame overlapping is done. +Using >0 and <1 values will make less conservative gain adjustments, like +when framelen option is set to smaller value, if framelen option value is +compensated for non-zero overlap then gain adjustments will be smoother across time +compared to zero overlap case. +

+
+
curve, v
+

Specify the peak mapping curve expression which is going to be used when calculating +gain applied to frames. The max output frame gain will still be limited by other +options mentioned previously for this filter. +

+

The expression can contain the following constants: +

+
+
ch
+

current channel number +

+
+
sn
+

current sample number +

+
+
nb_channels
+

number of channels +

+
+
t
+

timestamp expressed in seconds +

+
+
sr
+

sample rate +

+
+
p
+

current frame peak value +

+
+
+
+ + +

29.85.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.86 earwax

+ +

Make audio easier to listen to on headphones. +

+

This filter adds ‘cues’ to 44.1kHz stereo (i.e. audio CD format) audio +so that when listened to on headphones the stereo image is moved from +inside your head (standard for headphones) to outside and in front of +the listener (standard for speakers). +

+

Ported from SoX. +

+ +

29.87 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: +

+
+
frequency, f
+

Set the filter’s central frequency in Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Specify the band-width of a filter in width_type units. +

+
+
gain, g
+

Set the required gain or attenuation in dB. +Beware of clipping when using a positive gain. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.87.1 Examples

+
    +
  • Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: +
    +
    equalizer=f=1000:t=h:width=200:g=-10
    +
    + +
  • Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: +
    +
    equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
    +
    +
+ + +

29.87.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change equalizer frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change equalizer width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change equalizer width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change equalizer gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change equalizer mix. +Syntax for the command is : "mix" +

+
+ + +

29.88 extrastereo

+ +

Linearly increases the difference between left and right channels which +adds some sort of "live" effect to playback. +

+

The filter accepts the following options: +

+
+
m
+

Sets the difference coefficient (default: 2.5). 0.0 means mono sound +(average of both channels), with 1.0 sound will be unchanged, with +-1.0 left and right channels will be swapped. +

+
+
c
+

Enable clipping. By default is enabled. +

+
+ + +

29.88.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.89 firequalizer

+

Apply FIR Equalization using arbitrary frequency response. +

+

The filter accepts the following option: +

+
+
gain
+

Set gain curve equation (in dB). The expression can contain variables: +

+
f
+

the evaluated frequency +

+
sr
+

sample rate +

+
ch
+

channel number, set to 0 when multichannels evaluation is disabled +

+
chid
+

channel id, see libavutil/channel_layout.h, set to the first channel id when +multichannels evaluation is disabled +

+
chs
+

number of channels +

+
chlayout
+

channel_layout, see libavutil/channel_layout.h +

+
+
+

and functions: +

+
gain_interpolate(f)
+

interpolate gain on frequency f based on gain_entry +

+
cubic_interpolate(f)
+

same as gain_interpolate, but smoother +

+
+

This option is also available as command. Default is gain_interpolate(f). +

+
+
gain_entry
+

Set gain entry for gain_interpolate function. The expression can +contain functions: +

+
entry(f, g)
+

store gain entry at frequency f with value g +

+
+

This option is also available as command. +

+
+
delay
+

Set filter delay in seconds. Higher value means more accurate. +Default is 0.01. +

+
+
accuracy
+

Set filter accuracy in Hz. Lower value means more accurate. +Default is 5. +

+
+
wfunc
+

Set window function. Acceptable values are: +

+
rectangular
+

rectangular window, useful when gain curve is already smooth +

+
hann
+

hann window (default) +

+
hamming
+

hamming window +

+
blackman
+

blackman window +

+
nuttall3
+

3-terms continuous 1st derivative nuttall window +

+
mnuttall3
+

minimum 3-terms discontinuous nuttall window +

+
nuttall
+

4-terms continuous 1st derivative nuttall window +

+
bnuttall
+

minimum 4-terms discontinuous nuttall (blackman-nuttall) window +

+
bharris
+

blackman-harris window +

+
tukey
+

tukey window +

+
+ +
+
fixed
+

If enabled, use fixed number of audio samples. This improves speed when +filtering with large delay. Default is disabled. +

+
+
multi
+

Enable multichannels evaluation on gain. Default is disabled. +

+
+
zero_phase
+

Enable zero phase mode by subtracting timestamp to compensate delay. +Default is disabled. +

+
+
scale
+

Set scale used by gain. Acceptable values are: +

+
linlin
+

linear frequency, linear gain +

+
linlog
+

linear frequency, logarithmic (in dB) gain (default) +

+
loglin
+

logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain +

+
loglog
+

logarithmic frequency, logarithmic gain +

+
+ +
+
dumpfile
+

Set file for dumping, suitable for gnuplot. +

+
+
dumpscale
+

Set scale for dumpfile. Acceptable values are same with scale option. +Default is linlog. +

+
+
fft2
+

Enable 2-channel convolution using complex FFT. This improves speed significantly. +Default is disabled. +

+
+
min_phase
+

Enable minimum phase impulse response. Default is disabled. +

+
+ + +

29.89.1 Examples

+
    +
  • lowpass at 1000 Hz: +
    +
    firequalizer=gain='if(lt(f,1000), 0, -INF)'
    +
    +
  • lowpass at 1000 Hz with gain_entry: +
    +
    firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
    +
    +
  • custom equalization: +
    +
    firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
    +
    +
  • higher delay with zero phase to compensate delay: +
    +
    firequalizer=delay=0.1:fixed=on:zero_phase=on
    +
    +
  • lowpass on left channel, highpass on right channel: +
    +
    firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
    +:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
    +
    +
+ + +

29.90 flanger

+

Apply a flanging effect to the audio. +

+

The filter accepts the following options: +

+
+
delay
+

Set base delay in milliseconds. Range from 0 to 30. Default value is 0. +

+
+
depth
+

Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. +

+
+
regen
+

Set percentage regeneration (delayed signal feedback). Range from -95 to 95. +Default value is 0. +

+
+
width
+

Set percentage of delayed signal mixed with original. Range from 0 to 100. +Default value is 71. +

+
+
speed
+

Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. +

+
+
shape
+

Set swept wave shape, can be triangular or sinusoidal. +Default value is sinusoidal. +

+
+
phase
+

Set swept wave percentage-shift for multi channel. Range from 0 to 100. +Default value is 25. +

+
+
interp
+

Set delay-line interpolation, linear or quadratic. +Default is linear. +

+
+ + +

29.91 haas

+

Apply Haas effect to audio. +

+

Note that this makes most sense to apply on mono signals. +With this filter applied to mono signals it give some directionality and +stretches its stereo image. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level. By default is 1, or 0dB +

+
+
level_out
+

Set output level. By default is 1, or 0dB. +

+
+
side_gain
+

Set gain applied to side part of signal. By default is 1. +

+
+
middle_source
+

Set kind of middle source. Can be one of the following: +

+
+
‘left’
+

Pick left channel. +

+
+
‘right’
+

Pick right channel. +

+
+
‘mid’
+

Pick middle part signal of stereo image. +

+
+
‘side’
+

Pick side part signal of stereo image. +

+
+ +
+
middle_phase
+

Change middle phase. By default is disabled. +

+
+
left_delay
+

Set left channel delay. By default is 2.05 milliseconds. +

+
+
left_balance
+

Set left channel balance. By default is -1. +

+
+
left_gain
+

Set left channel gain. By default is 1. +

+
+
left_phase
+

Change left phase. By default is disabled. +

+
+
right_delay
+

Set right channel delay. By defaults is 2.12 milliseconds. +

+
+
right_balance
+

Set right channel balance. By default is 1. +

+
+
right_gain
+

Set right channel gain. By default is 1. +

+
+
right_phase
+

Change right phase. By default is enabled. +

+
+ + +

29.92 hdcd

+ +

Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with +embedded HDCD codes is expanded into a 20-bit PCM stream. +

+

The filter supports the Peak Extend and Low-level Gain Adjustment features +of HDCD, and detects the Transient Filter flag. +

+
+
ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
+
+ +

When using the filter with wav, note the default encoding for wav is 16-bit, +so the resulting 20-bit stream will be truncated back to 16-bit. Use something +like -acodec pcm_s24le after the filter to get 24-bit PCM output. +

+
ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
+ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
+
+ +

The filter accepts the following options: +

+
+
disable_autoconvert
+

Disable any automatic format conversion or resampling in the filter graph. +

+
+
process_stereo
+

Process the stereo channels together. If target_gain does not match between +channels, consider it invalid and use the last valid target_gain. +

+
+
cdt_ms
+

Set the code detect timer period in ms. +

+
+
force_pe
+

Always extend peaks above -3dBFS even if PE isn’t signaled. +

+
+
analyze_mode
+

Replace audio with a solid tone and adjust the amplitude to signal some +specific aspect of the decoding process. The output file can be loaded in +an audio editor alongside the original to aid analysis. +

+

analyze_mode=pe:force_pe=true can be used to see all samples above the PE level. +

+

Modes are: +

+
‘0, off’
+

Disabled +

+
‘1, lle’
+

Gain adjustment level at each sample +

+
‘2, pe’
+

Samples where peak extend occurs +

+
‘3, cdt’
+

Samples where the code detect timer is active +

+
‘4, tgm’
+

Samples where the target gain does not match between channels +

+
+
+
+ + +

29.93 headphone

+ +

Apply head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones. +The HRIRs are provided via additional streams, for each channel +one stereo input stream is needed. +

+

The filter accepts the following options: +

+
+
map
+

Set mapping of input streams for convolution. +The argument is a ’|’-separated list of channel names in order as they +are given as additional stream inputs for filter. +This also specify number of input streams. Number of input streams +must be not less than number of channels in first stream plus one. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
lfe
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
size
+

Set size of frame in number of samples which will be processed at once. +Default value is 1024. Allowed range is from 1024 to 96000. +

+
+
hrir
+

Set format of hrir stream. +Default value is stereo. Alternative value is multich. +If value is set to stereo, number of additional streams should +be greater or equal to number of input channels in first input stream. +Also each additional stream should have stereo number of channels. +If value is set to multich, number of additional streams should +be exactly one. Also number of input channels of additional stream +should be equal or greater than twice number of channels of first input +stream. +

+
+ + +

29.93.1 Examples

+ +
    +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +each amovie filter use stereo file with IR coefficients as input. +The files give coefficients for each position of virtual loudspeaker: +
    +
    ffmpeg -i input.wav
    +-filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
    +output.wav
    +
    + +
  • Full example using wav files as coefficients with amovie filters for 7.1 downmix, +but now in multich hrir format. +
    +
    ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
    +output.wav
    +
    +
+ + +

29.94 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 3000. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.94.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change highpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change highpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change highpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change highpass mix. +Syntax for the command is : "mix" +

+
+ + +

29.95 join

+ +

Join multiple input streams into one multi-channel stream. +

+

It accepts the following parameters: +

+
inputs
+

The number of input streams. It defaults to 2. +

+
+
channel_layout
+

The desired output channel layout. It defaults to stereo. +

+
+
map
+

Map channels from inputs to output. The argument is a ’|’-separated list of +mappings, each in the input_idx.in_channel-out_channel +form. input_idx is the 0-based index of the input stream. 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. out_channel is the name of the output +channel. +

+
+ +

The filter will attempt to guess the mappings when they 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. +

+

Join 3 inputs (with properly set channel layouts): +

+
ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
+
+ +

Build a 5.1 output from 6 single-channel streams: +

+
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
+
+ + +

29.96 ladspa

+ +

Load a LADSPA (Linux Audio Developer’s Simple Plugin API) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-ladspa. +

+
+
file, f
+

Specifies the name of LADSPA plugin library to load. If the environment +variable LADSPA_PATH is defined, the LADSPA plugin is searched in +each one of the directories specified by the colon separated list in +LADSPA_PATH, otherwise in the standard LADSPA paths, which are in +this order: HOME/.ladspa/lib/, /usr/local/lib/ladspa/, +/usr/lib/ladspa/. +

+
+
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. +

+
+
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=value0|c1=value1|c2=value2|..., where +valuei is the value set on the i-th control. +Alternatively they can be also defined using the following syntax: +value0|value1|value2|..., where +valuei is the value set on the i-th control. +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
latency, l
+

Enable latency compensation, by default is disabled. +Only used if plugin have inputs. +

+
+ + +

29.96.1 Examples

+ +
    +
  • List all available plugins within amp (LADSPA example plugin) library: +
    +
    ladspa=file=amp
    +
    + +
  • List all available controls and their valid ranges for vcf_notch +plugin from VCF library: +
    +
    ladspa=f=vcf:p=vcf_notch:c=help
    +
    + +
  • Simulate low quality audio equipment using Computer Music Toolkit (CMT) +plugin library: +
    +
    ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
    +
    + +
  • Add reverberation to the audio using TAP-plugins +(Tom’s Audio Processing plugins): +
    +
    ladspa=file=tap_reverb:tap_reverb
    +
    + +
  • Generate white noise, with 0.2 amplitude: +
    +
    ladspa=file=cmt:noise_source_white:c=c0=.2
    +
    + +
  • Generate 20 bpm clicks using plugin C* Click - Metronome from the +C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=file=caps:Click:c=c1=20'
    +
    + +
  • Apply C* Eq10X2 - Stereo 10-band equaliser effect: +
    +
    ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
    +
    + +
  • Increase volume by 20dB using fast lookahead limiter from Steve Harris +SWH Plugins collection: +
    +
    ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
    +
    + +
  • Attenuate low frequencies using Multiband EQ from Steve Harris +SWH Plugins collection: +
    +
    ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
    +
    + +
  • Reduce stereo image using Narrower from the C* Audio Plugin Suite +(CAPS) library: +
    +
    ladspa=caps:Narrower
    +
    + +
  • Another white noise, now using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:White:.2
    +
    + +
  • Some fractal noise, using C* Audio Plugin Suite (CAPS) library: +
    +
    ladspa=caps:Fractal:c=c1=1
    +
    + +
  • Dynamic volume normalization using VLevel plugin: +
    +
    ladspa=vlevel-ladspa:vlevel_mono
    +
    +
+ + +

29.96.2 Commands

+ +

This filter supports the following commands: +

+
cN
+

Modify the N-th control value. +

+

If the specified value is not valid, it is ignored and prior one is kept. +

+
+ + +

29.97 loudnorm

+ +

EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. +Support for both single pass (livestreams, files) and double pass (files) modes. +This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately +detect true peaks, the audio stream will be upsampled to 192 kHz. +Use the -ar option or aresample filter to explicitly set an output sample rate. +

+

The filter accepts the following options: +

+
+
I, i
+

Set integrated loudness target. +Range is -70.0 - -5.0. Default value is -24.0. +

+
+
LRA, lra
+

Set loudness range target. +Range is 1.0 - 50.0. Default value is 7.0. +

+
+
TP, tp
+

Set maximum true peak. +Range is -9.0 - +0.0. Default value is -2.0. +

+
+
measured_I, measured_i
+

Measured IL of input file. +Range is -99.0 - +0.0. +

+
+
measured_LRA, measured_lra
+

Measured LRA of input file. +Range is 0.0 - 99.0. +

+
+
measured_TP, measured_tp
+

Measured true peak of input file. +Range is -99.0 - +99.0. +

+
+
measured_thresh
+

Measured threshold of input file. +Range is -99.0 - +0.0. +

+
+
offset
+

Set offset gain. Gain is applied before the true-peak limiter. +Range is -99.0 - +99.0. Default is +0.0. +

+
+
linear
+

Normalize by linearly scaling the source audio. +measured_I, measured_LRA, measured_TP, +and measured_thresh must all be specified. Target LRA shouldn’t +be lower than source LRA and the change in integrated loudness shouldn’t +result in a true peak which exceeds the target TP. If any of these +conditions aren’t met, normalization mode will revert to dynamic. +Options are true or false. Default is true. +

+
+
dual_mono
+

Treat mono input files as "dual-mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +Options are true or false. Default is false. +

+
+
print_format
+

Set print format for stats. Options are summary, json, or none. +Default value is none. +

+
+
stats_file
+

Write stats to specified file. Format is controlled by print_format, +which must be set. Specify - to write to standard output. +Default is unset. +

+
+ + +

29.98 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: +

+
+
frequency, f
+

Set frequency in Hz. Default is 500. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
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. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.98.1 Examples

+
    +
  • Lowpass only LFE channel, it LFE is not present it does nothing: +
    +
    lowpass=c=LFE
    +
    +
+ + +

29.98.2 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change lowpass frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change lowpass width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change lowpass width. +Syntax for the command is : "width" +

+
+
mix, m
+

Change lowpass mix. +Syntax for the command is : "mix" +

+
+ + +

29.99 lv2

+ +

Load a LV2 (LADSPA Version 2) plugin. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-lv2. +

+
+
plugin, p
+

Specifies the plugin URI. You may need to escape ’:’. +

+
+
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). +If controls is set to help, all available controls and +their valid ranges are printed. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+ + +

29.99.1 Examples

+ +
    +
  • Apply bass enhancer plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
    +
    + +
  • Apply vinyl plugin from Calf: +
    +
    lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
    +
    + +
  • Apply bit crusher plugin from ArtyFX: +
    +
    lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
    +
    +
+ + +

29.99.2 Commands

+ +

This filter supports all options that are exported by plugin as commands. +

+ +

29.100 mcompand

+

Multiband Compress or expand the audio’s dynamic range. +

+

The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. +This is akin to the crossover of a loudspeaker, and results in flat frequency +response when absent compander action. +

+

It accepts the following parameters: +

+
+
args
+

This option syntax is: +attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... +For explanation of each item refer to compand filter documentation. +

+
+ + +

29.101 pan

+ +

Mix channels with specific gain levels. The filter accepts the output +channel layout followed by a set of channels definitions. +

+

This filter is also designed to efficiently remap the channels of an audio +stream. +

+

The filter accepts parameters of the form: +"l|outdef|outdef|..." +

+
+
l
+

output channel layout or number of channels +

+
+
outdef
+

output channel specification, of the form: +"out_name=[gain*]in_name[(+-)[gain*]in_name...]" +

+
+
out_name
+

output channel to define, either a channel name (FL, FR, etc.) or a channel +number (c0, c1, etc.) +

+
+
gain
+

multiplicative coefficient for the channel, 1 leaving the volume unchanged +

+
+
in_name
+

input channel to use, see out_name for details; it is not possible to mix +named and numbered input channels +

+
+ +

If the ‘=’ in a channel specification is replaced by ‘<’, then the gains for +that specification will be renormalized so that the total is 1, thus +avoiding clipping noise. +

+ +

29.101.1 Mixing examples

+ +

For example, if you want to down-mix from stereo to mono, but with a bigger +factor for the left channel: +

+
pan=1c|c0=0.9*c0+0.1*c1
+
+ +

A customized down-mix to stereo that works automatically for 3-, 4-, 5- and +7-channels surround: +

+
pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
+
+ +

Note that ffmpeg integrates a default down-mix (and up-mix) system +that should be preferred (see "-ac" option) unless you have very specific +needs. +

+ +

29.101.2 Remapping examples

+ +

The channel remapping will be effective if, and only if: +

+
    +
  • gain coefficients are zeroes or ones, +
  • only one input per channel output, +
+ +

If all these conditions are satisfied, the filter will notify the user ("Pure +channel mapping detected"), and use an optimized and lossless method to do the +remapping. +

+

For example, if you have a 5.1 source and want a stereo audio stream by +dropping the extra channels: +

+
pan="stereo| c0=FL | c1=FR"
+
+ +

Given the same source, you can also switch front left and front right channels +and keep the input channel layout: +

+
pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
+
+ +

If the input is a stereo audio stream, you can mute the front left channel (and +still keep the stereo channel layout) with: +

+
pan="stereo|c1=c1"
+
+ +

Still with a stereo audio stream input, you can copy the right channel in both +front left and right: +

+
pan="stereo| c0=FR | c1=FR"
+
+ + +

29.102 replaygain

+ +

ReplayGain scanner filter. This filter takes an audio stream as an input and +outputs it unchanged. +At end of filtering it displays track_gain and track_peak. +

+

The filter accepts the following exported read-only options: +

+
+
track_gain
+

Exported track gain in dB at end of stream. +

+
+
track_peak
+

Exported track peak at end of stream. +

+
+ + +

29.103 resample

+ +

Convert the audio sample format, sample rate and channel layout. It is +not meant to be used directly. +

+ +

29.104 rubberband

+

Apply time-stretching and pitch-shifting with librubberband. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-librubberband. +

+

The filter accepts the following options: +

+
+
tempo
+

Set tempo scale factor. +

+
+
pitch
+

Set pitch scale factor. +

+
+
transients
+

Set transients detector. +Possible values are: +

+
crisp
+
mixed
+
smooth
+
+ +
+
detector
+

Set detector. +Possible values are: +

+
compound
+
percussive
+
soft
+
+ +
+
phase
+

Set phase. +Possible values are: +

+
laminar
+
independent
+
+ +
+
window
+

Set processing window size. +Possible values are: +

+
standard
+
short
+
long
+
+ +
+
smoothing
+

Set smoothing. +Possible values are: +

+
off
+
on
+
+ +
+
formant
+

Enable formant preservation when shift pitching. +Possible values are: +

+
shifted
+
preserved
+
+ +
+
pitchq
+

Set pitch quality. +Possible values are: +

+
quality
+
speed
+
consistency
+
+ +
+
channels
+

Set channels. +Possible values are: +

+
apart
+
together
+
+
+
+ + +

29.104.1 Commands

+ +

This filter supports the following commands: +

+
tempo
+

Change filter tempo scale factor. +Syntax for the command is : "tempo" +

+
+
pitch
+

Change filter pitch scale factor. +Syntax for the command is : "pitch" +

+
+ + +

29.105 sidechaincompress

+ +

This filter acts like normal compressor but has the ability to compress +detected signal using second input signal. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +The filtered signal then can be filtered with other filters in later stages of +processing. See pan and amerge filter. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mode
+

Set mode of compressor operation. Can be upward or downward. +Default is downward. +

+
+
threshold
+

If a signal of second stream raises above this level it will affect the gain +reduction of first stream. +By default is 0.125. Range is between 0.00097563 and 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. 1:2 means that if the level +raised 4dB above the threshold, it will be only 2dB above after the reduction. +Default is 2. Range is between 1 and 20. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction starts. Default is 20. Range is between 0.01 and 2000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before +reduction is decreased again. Default is 250. Range is between 0.01 and 9000. +

+
+
makeup
+

Set the amount by how much signal will be amplified after processing. +Default is 1. Range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.82843. Range is between 1 and 8. +

+
+
link
+

Choose if the average level between all channels of side-chain stream +or the louder(maximum) channel of side-chain stream affects the +reduction. Default is average. +

+
+
detection
+

Should the exact signal be taken in case of peak or an RMS one in case +of rms. Default is rms which is mainly smoother. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is between 0.015625 and 64. +

+
+
mix
+

How much to use compressed signal in output. Default is 1. +Range is between 0 and 1. +

+
+ + +

29.105.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.105.2 Examples

+ +
    +
  • Full ffmpeg example taking 2 audio inputs, 1st input to be compressed +depending on the signal of 2nd input and later compressed signal to be +merged with 2nd input: +
    +
    ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
    +
    +
+ + +

29.106 sidechaingate

+ +

A sidechain gate acts like a normal (wideband) gate but has the ability to +filter the detected signal before sending it to the gain reduction stage. +Normally a gate uses the full range signal to detect a level above the +threshold. +For example: If you cut all lower frequencies from your sidechain signal +the gate will decrease the volume of your track only if not enough highs +appear. With this technique you are able to reduce the resonation of a +natural drum or remove "rumbling" of muted strokes from a heavily distorted +guitar. +It needs two input streams and returns one output stream. +First input stream will be processed depending on second stream signal. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering. +Default is 1. Allowed range is from 0.015625 to 64. +

+
+
mode
+

Set the mode of operation. Can be upward or downward. +Default is downward. If set to upward mode, higher parts of signal +will be amplified, expanding dynamic range in upward direction. +Otherwise, in case of downward lower parts of signal will be reduced. +

+
+
range
+

Set the level of gain reduction when the signal is below the threshold. +Default is 0.06125. Allowed range is from 0 to 1. +Setting this to 0 disables reduction and then filter behaves like expander. +

+
+
threshold
+

If a signal rises above this level the gain reduction is released. +Default is 0.125. Allowed range is from 0 to 1. +

+
+
ratio
+

Set a ratio about which the signal is reduced. +Default is 2. Allowed range is from 1 to 9000. +

+
+
attack
+

Amount of milliseconds the signal has to rise above the threshold before gain +reduction stops. +Default is 20 milliseconds. Allowed range is from 0.01 to 9000. +

+
+
release
+

Amount of milliseconds the signal has to fall below the threshold before the +reduction is increased again. Default is 250 milliseconds. +Allowed range is from 0.01 to 9000. +

+
+
makeup
+

Set amount of amplification of signal after processing. +Default is 1. Allowed range is from 1 to 64. +

+
+
knee
+

Curve the sharp knee around the threshold to enter gain reduction more softly. +Default is 2.828427125. Allowed range is from 1 to 8. +

+
+
detection
+

Choose if exact signal should be taken for detection or an RMS like one. +Default is rms. Can be peak or rms. +

+
+
link
+

Choose if the average level between all channels or the louder channel affects +the reduction. +Default is average. Can be average or maximum. +

+
+
level_sc
+

Set sidechain gain. Default is 1. Range is from 0.015625 to 64. +

+
+ + +

29.106.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.107 silencedetect

+ +

Detect silence in an audio stream. +

+

This filter logs a message when it detects that the input audio volume is less +or equal to a noise tolerance value for a duration greater or equal to the +minimum detected noise duration. +

+

The printed times and duration are expressed in seconds. The +lavfi.silence_start or lavfi.silence_start.X metadata key +is set on the first frame whose timestamp equals or exceeds the detection +duration and it contains the timestamp of the first frame of the silence. +

+

The lavfi.silence_duration or lavfi.silence_duration.X +and lavfi.silence_end or lavfi.silence_end.X metadata +keys are set on the first frame after the silence. If mono is +enabled, and each channel is evaluated separately, the .X +suffixed keys are used, and X corresponds to the channel number. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or amplitude ratio. Default is -60dB, or 0.001. +

+
+
duration, d
+

Set silence duration until notification (default is 2 seconds). See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+
+
mono, m
+

Process each channel separately, instead of combined. By default is disabled. +

+
+ + +

29.107.1 Examples

+ +
    +
  • Detect 5 seconds of silence with -50dB noise tolerance: +
    +
    silencedetect=n=-50dB:d=5
    +
    + +
  • Complete example with ffmpeg to detect silence with 0.0001 noise +tolerance in silence.mp3: +
    +
    ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
    +
    +
+ + +

29.108 silenceremove

+ +

Remove silence from the beginning, middle or end of the audio. +

+

The filter accepts the following options: +

+
+
start_periods
+

This value is used to indicate if audio should be trimmed at beginning of +the audio. A value of zero indicates no silence should be trimmed from the +beginning. When specifying a non-zero value, it trims audio up until it +finds non-silence. Normally, when trimming silence from beginning of audio +the start_periods will be 1 but it can be increased to higher +values to trim all audio up to specific count of non-silence periods. +Default value is 0. +

+
+
start_duration
+

Specify the amount of time that non-silence must be detected before it stops +trimming audio. By increasing the duration, bursts of noises can be treated +as silence and trimmed off. Default value is 0. +

+
+
start_threshold
+

This indicates what sample value should be treated as silence. For digital +audio, a value of 0 may be fine but for audio recorded from analog, +you may wish to increase the value to account for background noise. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
start_silence
+

Specify max duration of silence at beginning that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
start_mode
+

Specify mode of detection of silence end at start of multi-channel audio. +Can be any or all. Default is any. +With any, any sample from any channel that is detected as non-silence +will trigger end of silence trimming at start of audio stream. +With all, only if every sample from every channel is detected as non-silence +will trigger end of silence trimming at start of audio stream, limited usage. +

+
+
stop_periods
+

Set the count for trimming silence from the end of audio. When specifying a +positive value, it trims audio after it finds specified silence period. +To remove silence from the middle of a file, specify a stop_periods +that is negative. This value is then treated as a positive value and is +used to indicate the effect should restart processing as specified by +stop_periods, making it suitable for removing periods of silence +in the middle of the audio. +Default value is 0. +

+
+
stop_duration
+

Specify a duration of silence that must exist before audio is not copied any +more. By specifying a higher duration, silence that is wanted can be left in +the audio. +Default value is 0. +

+
+
stop_threshold
+

This is the same as start_threshold but for trimming silence from +the end of audio. +Can be specified in dB (in case "dB" is appended to the specified value) +or amplitude ratio. Default value is 0. +

+
+
stop_silence
+

Specify max duration of silence at end that will be kept after +trimming. Default is 0, which is equal to trimming all samples detected +as silence. +

+
+
stop_mode
+

Specify mode of detection of silence start after start of multi-channel audio. +Can be any or all. Default is all. +With any, any sample from any channel that is detected as silence +will trigger start of silence trimming after start of audio stream, limited usage. +With all, only if every sample from every channel is detected as silence +will trigger start of silence trimming after start of audio stream. +

+
+
detection
+

Set how is silence detected. +

+
avg
+

Mean of absolute values of samples in moving window. +

+
rms
+

Root squared mean of absolute values of samples in moving window. +

+
peak
+

Maximum of absolute values of samples in moving window. +

+
median
+

Median of absolute values of samples in moving window. +

+
ptp
+

Absolute of max peak to min peak difference of samples in moving window. +

+
dev
+

Standard deviation of values of samples in moving window. +

+
+

Default value is rms. +

+
+
window
+

Set duration in number of seconds used to calculate size of window in number +of samples for detecting silence. Using 0 will effectively disable +any windowing and use only single sample per channel for silence detection. +In that case it may be needed to also set start_silence and/or +stop_silence to nonzero values with also start_duration and/or +stop_duration to nonzero values. +Default value is 0.02. Allowed range is from 0 to 10. +

+
+
timestamp
+

Set processing mode of every audio frame output timestamp. +

+
write
+

Full timestamps rewrite, keep only the start time for the first output frame. +

+
copy
+

Non-dropped frames are left with same timestamp as input audio frame. +

+
+

Defaults value is write. +

+
+ + +

29.108.1 Examples

+ +
    +
  • The following example shows how this filter can be used to start a recording +that does not contain the delay at the start which usually occurs between +pressing the record button and the start of the performance: +
    +
    silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
    +
    + +
  • Trim all silence encountered from beginning to end where there is more than 1 +second of silence in audio: +
    +
    silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Trim all digital silence samples, using peak detection, from beginning to end +where there is more than 0 samples of digital silence in audio and digital +silence is detected in all channels at same positions in stream: +
    +
    silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
    +
    + +
  • Trim every 2nd encountered silence period from beginning to end where there is +more than 1 second of silence per silence period in audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB
    +
    + +
  • Similar as above, but keep maximum of 0.5 seconds of silence from each trimmed period: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5
    +
    + +
  • Similar as above, but keep maximum of 1.5 seconds of silence from start of audio: +
    +
    silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5:start_periods=1:start_duration=1:start_silence=1.5:stop_threshold=-90dB
    +
    +
+ + +

29.108.2 Commands

+ +

This filter supports some above options as commands. +

+ +

29.109 sofalizer

+ +

SOFAlizer uses head-related transfer functions (HRTFs) to create virtual +loudspeakers around the user for binaural listening via headphones (audio +formats up to 9 channels supported). +The HRTFs are stored in SOFA files (see http://www.sofacoustics.org/ for a database). +SOFAlizer is developed at the Acoustics Research Institute (ARI) of the +Austrian Academy of Sciences. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libmysofa. +

+

The filter accepts the following options: +

+
+
sofa
+

Set the SOFA file used for rendering. +

+
+
gain
+

Set gain applied to audio. Value is in dB. Default is 0. +

+
+
rotation
+

Set rotation of virtual loudspeakers in deg. Default is 0. +

+
+
elevation
+

Set elevation of virtual speakers in deg. Default is 0. +

+
+
radius
+

Set distance in meters between loudspeakers and the listener with near-field +HRTFs. Default is 1. +

+
+
type
+

Set processing type. Can be time or freq. time is +processing audio in time domain which is slow. +freq is processing audio in frequency domain which is fast. +Default is freq. +

+
+
speakers
+

Set custom positions of virtual loudspeakers. Syntax for this option is: +<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. +Each virtual loudspeaker is described with short channel name following with +azimuth and elevation in degrees. +Each virtual loudspeaker description is separated by ’|’. +For example to override front left and front right channel positions use: +’speakers=FL 45 15|FR 345 15’. +Descriptions with unrecognised channel names are ignored. +

+
+
lfegain
+

Set custom gain for LFE channels. Value is in dB. Default is 0. +

+
+
framesize
+

Set custom frame size in number of samples. Default is 1024. +Allowed range is from 1024 to 96000. Only used if option ‘type’ +is set to freq. +

+
+
normalize
+

Should all IRs be normalized upon importing SOFA file. +By default is enabled. +

+
+
interpolate
+

Should nearest IRs be interpolated with neighbor IRs if exact position +does not match. By default is disabled. +

+
+
minphase
+

Minphase all IRs upon loading of SOFA file. By default is disabled. +

+
+
anglestep
+

Set neighbor search angle step. Only used if option interpolate is enabled. +

+
+
radstep
+

Set neighbor search radius step. Only used if option interpolate is enabled. +

+
+ + +

29.109.1 Examples

+ +
    +
  • Using ClubFritz6 sofa file: +
    +
    sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
    +
    + +
  • Using ClubFritz12 sofa file and bigger radius with small rotation: +
    +
    sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
    +
    + +
  • Similar as above but with custom speaker positions for front left, front right, back left and back right +and also with custom gain: +
    +
    "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
    +
    +
+ + +

29.110 speechnorm

+

Speech Normalizer. +

+

This filter expands or compresses each half-cycle of audio samples +(local set of samples all above or all below zero and between two nearest zero crossings) depending +on threshold value, so audio reaches target peak value under conditions controlled by below options. +

+

The filter accepts the following options: +

+
+
peak, p
+

Set the expansion target peak value. This specifies the highest allowed absolute amplitude +level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0. +

+
+
expansion, e
+

Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples expansion. The maximum expansion +would be such that local peak value reaches target peak value but never to surpass it and that +ratio between new and previous peak value does not surpass this option value. +

+
+
compression, c
+

Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. +This option controls maximum local half-cycle of samples compression. This option is used +only if threshold option is set to value greater than 0.0, then in such cases +when local peak is lower or same as value set by threshold all samples belonging to +that peak’s half-cycle will be compressed by current compression factor. +

+
+
threshold, t
+

Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0. +This option specifies which half-cycles of samples will be compressed and which will be expanded. +Any half-cycle samples with their local peak value below or same as this option value will be +compressed by current compression factor, otherwise, if greater than threshold value they will be +expanded with expansion factor so that it could reach peak target value but never surpass it. +

+
+
raise, r
+

Set the expansion raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per +each new half-cycle until it reaches expansion value. +Setting this options too high may lead to distortions. +

+
+
fall, f
+

Set the compression raising amount per each half-cycle of samples. Default value is 0.001. +Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per +each new half-cycle until it reaches compression value. +

+
+
channels, h
+

Specify which channels to filter, by default all available channels are filtered. +

+
+
invert, i
+

Enable inverted filtering, by default is disabled. This inverts interpretation of threshold +option. When enabled any half-cycle of samples with their local peak value below or same as +threshold option will be expanded otherwise it will be compressed. +

+
+
link, l
+

Link channels when calculating gain applied to each filtered channel sample, by default is disabled. +When disabled each filtered channel gain calculation is independent, otherwise when this option +is enabled the minimum of all possible gains for each filtered channel is used. +

+
+
rms, m
+

Set the expansion target RMS value. This specifies the highest allowed RMS level for the normalized +audio input. Default value is 0.0, thus disabled. Allowed range is from 0.0 to 1.0. +

+
+ + +

29.110.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.110.2 Examples

+ +
    +
  • Weak and slow amplification: +
    +
    speechnorm=e=3:r=0.00001:l=1
    +
    + +
  • Moderate and slow amplification: +
    +
    speechnorm=e=6.25:r=0.00001:l=1
    +
    + +
  • Strong and fast amplification: +
    +
    speechnorm=e=12.5:r=0.0001:l=1
    +
    + +
  • Very strong and fast amplification: +
    +
    speechnorm=e=25:r=0.0001:l=1
    +
    + +
  • Extreme and fast amplification: +
    +
    speechnorm=e=50:r=0.0001:l=1
    +
    +
+ + +

29.111 stereotools

+ +

This filter has some handy utilities to manage stereo signals, for converting +M/S stereo recordings to L/R signal while having control over the parameters +or spreading the stereo image of master track. +

+

The filter accepts the following options: +

+
+
level_in
+

Set input level before filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
level_out
+

Set output level after filtering for both channels. Defaults is 1. +Allowed range is from 0.015625 to 64. +

+
+
balance_in
+

Set input balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
balance_out
+

Set output balance between both channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
softclip
+

Enable softclipping. Results in analog distortion instead of harsh digital 0dB +clipping. Disabled by default. +

+
+
mutel
+

Mute the left channel. Disabled by default. +

+
+
muter
+

Mute the right channel. Disabled by default. +

+
+
phasel
+

Change the phase of the left channel. Disabled by default. +

+
+
phaser
+

Change the phase of the right channel. Disabled by default. +

+
+
mode
+

Set stereo mode. Available values are: +

+
+
‘lr>lr’
+

Left/Right to Left/Right, this is default. +

+
+
‘lr>ms’
+

Left/Right to Mid/Side. +

+
+
‘ms>lr’
+

Mid/Side to Left/Right. +

+
+
‘lr>ll’
+

Left/Right to Left/Left. +

+
+
‘lr>rr’
+

Left/Right to Right/Right. +

+
+
‘lr>l+r’
+

Left/Right to Left + Right. +

+
+
‘lr>rl’
+

Left/Right to Right/Left. +

+
+
‘ms>ll’
+

Mid/Side to Left/Left. +

+
+
‘ms>rr’
+

Mid/Side to Right/Right. +

+
+
‘ms>rl’
+

Mid/Side to Right/Left. +

+
+
‘lr>l-r’
+

Left/Right to Left - Right. +

+
+ +
+
slev
+

Set level of side signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
sbal
+

Set balance of side signal. Default is 0. +Allowed range is from -1 to 1. +

+
+
mlev
+

Set level of the middle signal. Default is 1. +Allowed range is from 0.015625 to 64. +

+
+
mpan
+

Set middle signal pan. Default is 0. Allowed range is from -1 to 1. +

+
+
base
+

Set stereo base between mono and inversed channels. Default is 0. +Allowed range is from -1 to 1. +

+
+
delay
+

Set delay in milliseconds how much to delay left from right channel and +vice versa. Default is 0. Allowed range is from -20 to 20. +

+
+
sclevel
+

Set S/C level. Default is 1. Allowed range is from 1 to 100. +

+
+
phase
+

Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. +

+
+
bmode_in, bmode_out
+

Set balance mode for balance_in/balance_out option. +

+

Can be one of the following: +

+
+
‘balance’
+

Classic balance mode. Attenuate one channel at time. +Gain is raised up to 1. +

+
+
‘amplitude’
+

Similar as classic mode above but gain is raised up to 2. +

+
+
‘power’
+

Equal power distribution, from -6dB to +6dB range. +

+
+
+
+ + +

29.111.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

29.111.2 Examples

+ +
    +
  • Apply karaoke like effect: +
    +
    stereotools=mlev=0.015625
    +
    + +
  • Convert M/S signal to L/R: +
    +
    "stereotools=mode=ms>lr"
    +
    +
+ + +

29.112 stereowiden

+ +

This filter enhance the stereo effect by suppressing signal common to both +channels and by delaying the signal of left into right and vice versa, +thereby widening the stereo effect. +

+

The filter accepts the following options: +

+
+
delay
+

Time in milliseconds of the delay of left signal into right and vice versa. +Default is 20 milliseconds. +

+
+
feedback
+

Amount of gain in delayed signal into right and vice versa. Gives a delay +effect of left signal in right output and vice versa which gives widening +effect. Default is 0.3. +

+
+
crossfeed
+

Cross feed of left into right with inverted phase. This helps in suppressing +the mono. If the value is 1 it will cancel all the signal common to both +channels. Default is 0.3. +

+
+
drymix
+

Set level of input signal of original channel. Default is 0.8. +

+
+ + +

29.112.1 Commands

+ +

This filter supports the all above options except delay as commands. +

+ +

29.113 superequalizer

+

Apply 18 band equalizer. +

+

The filter accepts the following options: +

+
1b
+

Set 65Hz band gain. +

+
2b
+

Set 92Hz band gain. +

+
3b
+

Set 131Hz band gain. +

+
4b
+

Set 185Hz band gain. +

+
5b
+

Set 262Hz band gain. +

+
6b
+

Set 370Hz band gain. +

+
7b
+

Set 523Hz band gain. +

+
8b
+

Set 740Hz band gain. +

+
9b
+

Set 1047Hz band gain. +

+
10b
+

Set 1480Hz band gain. +

+
11b
+

Set 2093Hz band gain. +

+
12b
+

Set 2960Hz band gain. +

+
13b
+

Set 4186Hz band gain. +

+
14b
+

Set 5920Hz band gain. +

+
15b
+

Set 8372Hz band gain. +

+
16b
+

Set 11840Hz band gain. +

+
17b
+

Set 16744Hz band gain. +

+
18b
+

Set 20000Hz band gain. +

+
+ + +

29.114 surround

+

Apply audio surround upmix filter. +

+

This filter allows to produce multichannel output from audio stream. +

+

The filter accepts the following options: +

+
+
chl_out
+

Set output channel layout. By default, this is 5.1. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
chl_in
+

Set input channel layout. By default, this is stereo. +

+

See the Channel Layout section in the ffmpeg-utils(1) manual +for the required syntax. +

+
+
level_in
+

Set input volume level. By default, this is 1. +

+
+
level_out
+

Set output volume level. By default, this is 1. +

+
+
lfe
+

Enable LFE channel output if output channel layout has it. By default, this is enabled. +

+
+
lfe_low
+

Set LFE low cut off frequency. By default, this is 128 Hz. +

+
+
lfe_high
+

Set LFE high cut off frequency. By default, this is 256 Hz. +

+
+
lfe_mode
+

Set LFE mode, can be add or sub. Default is add. +In add mode, LFE channel is created from input audio and added to output. +In sub mode, LFE channel is created from input audio and added to output but +also all non-LFE output channels are subtracted with output LFE channel. +

+
+
smooth
+

Set temporal smoothness strength, used to gradually change factors when transforming +stereo sound in time. Allowed range is from 0.0 to 1.0. +Useful to improve output quality with focus option values greater than 0.0. +Default is 0.0. Only values inside this range and without edges are effective. +

+
+
angle
+

Set angle of stereo surround transform, Allowed range is from 0 to 360. +Default is 90. +

+
+
focus
+

Set focus of stereo surround transform, Allowed range is from -1 to 1. +Default is 0. +

+
+
fc_in
+

Set front center input volume. By default, this is 1. +

+
+
fc_out
+

Set front center output volume. By default, this is 1. +

+
+
fl_in
+

Set front left input volume. By default, this is 1. +

+
+
fl_out
+

Set front left output volume. By default, this is 1. +

+
+
fr_in
+

Set front right input volume. By default, this is 1. +

+
+
fr_out
+

Set front right output volume. By default, this is 1. +

+
+
sl_in
+

Set side left input volume. By default, this is 1. +

+
+
sl_out
+

Set side left output volume. By default, this is 1. +

+
+
sr_in
+

Set side right input volume. By default, this is 1. +

+
+
sr_out
+

Set side right output volume. By default, this is 1. +

+
+
bl_in
+

Set back left input volume. By default, this is 1. +

+
+
bl_out
+

Set back left output volume. By default, this is 1. +

+
+
br_in
+

Set back right input volume. By default, this is 1. +

+
+
br_out
+

Set back right output volume. By default, this is 1. +

+
+
bc_in
+

Set back center input volume. By default, this is 1. +

+
+
bc_out
+

Set back center output volume. By default, this is 1. +

+
+
lfe_in
+

Set LFE input volume. By default, this is 1. +

+
+
lfe_out
+

Set LFE output volume. By default, this is 1. +

+
+
allx
+

Set spread usage of stereo image across X axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
ally
+

Set spread usage of stereo image across Y axis for all channels. +Allowed range is from -1 to 15. +By default this value is negative -1, and thus unused. +

+
+
fcx, flx, frx, blx, brx, slx, srx, bcx
+

Set spread usage of stereo image across X axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
fcy, fly, fry, bly, bry, sly, sry, bcy
+

Set spread usage of stereo image across Y axis for each channel. +Allowed range is from 0.06 to 15. +By default this value is 0.5. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann, hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hann. +

+
+
overlap
+

Set window overlap. If set to 1, the recommended overlap for selected +window function will be picked. Default is 0.5. +

+
+ + +

29.115 tiltshelf

+ +

Boost or cut the lower frequencies and cut or boost higher 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: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.115.1 Commands

+ +

This filter supports some options as commands. +

+ +

29.116 treble, highshelf

+ +

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). +

+

The filter accepts the following options: +

+
+
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. +

+
+
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 3000 Hz. +

+
+
width_type, t
+

Set method to specify band-width of filter. +

+
h
+

Hz +

+
q
+

Q-Factor +

+
o
+

octave +

+
s
+

slope +

+
k
+

kHz +

+
+ +
+
width, w
+

Determine how steep is the filter’s shelf transition. +

+
+
poles, p
+

Set number of poles. Default is 2. +

+
+
mix, m
+

How much to use filtered signal in output. Default is 1. +Range is between 0 and 1. +

+
+
channels, c
+

Specify which channels to filter, by default all available are filtered. +

+
+
normalize, n
+

Normalize biquad coefficients, by default is disabled. +Enabling it will normalize magnitude response at DC to 0dB. +

+
+
transform, a
+

Set transform type of IIR filter. +

+
di
+
dii
+
tdi
+
tdii
+
latt
+
svf
+
zdf
+
+ +
+
precision, r
+

Set precision of filtering. +

+
auto
+

Pick automatic sample format depending on surround filters. +

+
s16
+

Always use signed 16-bit. +

+
s32
+

Always use signed 32-bit. +

+
f32
+

Always use float 32-bit. +

+
f64
+

Always use float 64-bit. +

+
+ +
+
block_size, b
+

Set block size used for reverse IIR processing. If this value is set to high enough +value (higher than impulse response length truncated when reaches near zero values) filtering +will become linear phase otherwise if not big enough it will just produce nasty artifacts. +

+

Note that filter delay will be exactly this many samples when set to non-zero value. +

+
+ + +

29.116.1 Commands

+ +

This filter supports the following commands: +

+
frequency, f
+

Change treble frequency. +Syntax for the command is : "frequency" +

+
+
width_type, t
+

Change treble width_type. +Syntax for the command is : "width_type" +

+
+
width, w
+

Change treble width. +Syntax for the command is : "width" +

+
+
gain, g
+

Change treble gain. +Syntax for the command is : "gain" +

+
+
mix, m
+

Change treble mix. +Syntax for the command is : "mix" +

+
+ + +

29.117 tremolo

+ +

Sinusoidal amplitude modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. Modulation frequencies in the subharmonic range +(20 Hz or lower) will result in a tremolo effect. +This filter may also be used as a ring modulator by specifying +a modulation frequency higher than 20 Hz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

29.118 vibrato

+ +

Sinusoidal phase modulation. +

+

The filter accepts the following options: +

+
+
f
+

Modulation frequency in Hertz. +Range is 0.1 - 20000.0. Default value is 5.0 Hz. +

+
+
d
+

Depth of modulation as a percentage. Range is 0.0 - 1.0. +Default value is 0.5. +

+
+ + +

29.119 virtualbass

+ +

Apply audio Virtual Bass filter. +

+

This filter accepts stereo input and produce stereo with LFE (2.1) channels output. +The newly produced LFE channel have enhanced virtual bass originally obtained from both stereo channels. +This filter outputs front left and front right channels unchanged as available in stereo input. +

+

The filter accepts the following options: +

+
+
cutoff
+

Set the virtual bass cutoff frequency. Default value is 250 Hz. +Allowed range is from 100 to 500 Hz. +

+
+
strength
+

Set the virtual bass strength. Allowed range is from 0.5 to 3. +Default value is 3. +

+
+ + +

29.120 volume

+ +

Adjust the input audio volume. +

+

It accepts the following parameters: +

+
volume
+

Set audio volume expression. +

+

Output values are clipped to the maximum value. +

+

The output audio volume is given by the relation: +

+
output_volume = volume * input_volume
+
+ +

The default value for volume is "1.0". +

+
+
precision
+

This parameter represents the mathematical precision. +

+

It determines which input sample formats will be allowed, which affects the +precision of the volume scaling. +

+
+
fixed
+

8-bit fixed-point; this limits input sample format to U8, S16, and S32. +

+
float
+

32-bit floating-point; this limits input sample format to FLT. (default) +

+
double
+

64-bit floating-point; this limits input sample format to DBL. +

+
+ +
+
replaygain
+

Choose the behaviour on encountering ReplayGain side data in input frames. +

+
+
drop
+

Remove ReplayGain side data, ignoring its contents (the default). +

+
+
ignore
+

Ignore ReplayGain side data, but leave it in the frame. +

+
+
track
+

Prefer the track gain, if present. +

+
+
album
+

Prefer the album gain, if present. +

+
+ +
+
replaygain_preamp
+

Pre-amplification gain in dB to apply to the selected replaygain gain. +

+

Default value for replaygain_preamp is 0.0. +

+
+
replaygain_noclip
+

Prevent clipping by limiting the gain applied. +

+

Default value for replaygain_noclip is 1. +

+
+
eval
+

Set when the volume expression is evaluated. +

+

It accepts the following values: +

+
‘once’
+

only evaluate expression once during the filter initialization, or +when the ‘volume’ command is sent +

+
+
‘frame’
+

evaluate expression for each incoming frame +

+
+ +

Default value is ‘once’. +

+
+ +

The volume expression can contain the following parameters. +

+
+
n
+

frame number (starting at zero) +

+
nb_channels
+

number of channels +

+
nb_consumed_samples
+

number of samples consumed by the filter +

+
nb_samples
+

number of samples in the current frame +

+
pos
+

original frame position in the file; deprecated, do not use +

+
pts
+

frame PTS +

+
sample_rate
+

sample rate +

+
startpts
+

PTS at start of stream +

+
startt
+

time at start of stream +

+
t
+

frame time +

+
tb
+

timestamp timebase +

+
volume
+

last set volume value +

+
+ +

Note that when eval is set to ‘once’ only the +sample_rate and tb variables are available, all other +variables will evaluate to NAN. +

+ +

29.120.1 Commands

+ +

This filter supports the following commands: +

+
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. +

+
+ + +

29.120.2 Examples

+ +
    +
  • Halve the input audio volume: +
    +
    volume=volume=0.5
    +volume=volume=1/2
    +volume=volume=-6.0206dB
    +
    + +

    In all the above example the named key for volume can be +omitted, for example like in: +

    +
    volume=0.5
    +
    + +
  • Increase input audio power by 6 decibels using fixed-point precision: +
    +
    volume=volume=6dB:precision=fixed
    +
    + +
  • Fade volume after time 10 with an annihilation period of 5 seconds: +
    +
    volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
    +
    +
+ + +

29.121 volumedetect

+ +

Detect the volume of the input video. +

+

The filter has no parameters. It supports only 16-bit signed integer samples, +so the input will be converted when needed. 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 a histogram of the +registered volume values (from the maximum value to a cumulated 1/1000 of +the samples). +

+

All volumes are in decibels relative to the maximum PCM value. +

+ +

29.121.1 Examples

+ +

Here is an excerpt of the output: +

+
[Parsed_volumedetect_0  0xa23120] mean_volume: -27 dB
+[Parsed_volumedetect_0  0xa23120] max_volume: -4 dB
+[Parsed_volumedetect_0  0xa23120] histogram_4db: 6
+[Parsed_volumedetect_0  0xa23120] histogram_5db: 62
+[Parsed_volumedetect_0  0xa23120] histogram_6db: 286
+[Parsed_volumedetect_0  0xa23120] histogram_7db: 1042
+[Parsed_volumedetect_0  0xa23120] histogram_8db: 2551
+[Parsed_volumedetect_0  0xa23120] histogram_9db: 4609
+[Parsed_volumedetect_0  0xa23120] histogram_10db: 8409
+
+ +

It means that: +

    +
  • The mean square energy is approximately -27 dB, or 10^-2.7. +
  • The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. +
  • There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. +
+ +

In other words, raising the volume by +4 dB does not cause any clipping, +raising it by +5 dB causes clipping for 6 samples, etc. +

+ +

29.122 whisper

+ +

It runs automatic speech recognition using the OpenAI’s Whisper model. +

+

It requires the whisper.cpp library (https://github.com/ggml-org/whisper.cpp) +as a prerequisite. After installing the library it can be enabled using: +./configure --enable-whisper. +

+

The filter has following options: +

+
+
model
+

The file path of the downloaded whisper.cpp model (mandatory). +

+
+
language
+

The language to use for transcription (’auto’ for auto-detect). +Default value: "auto" +

+
+
queue
+

The maximum size that will be queued into the filter before processing the audio +with whisper. Using a small value the audio stream will be processed more often, +but the transcription quality will be lower and the required processing power +will be higher. Using a large value (e.g. 10-20s) will produce more accurate +results using less CPU (as using the whisper-cli tool), but the transcription +latency will be higher, thus not useful to process real-time streams. +Consider using the vad_model option associated with a large queue value. +Default value: "3" +

+
+
use_gpu
+

If the GPU support should be enabled. +Default value: "true" +

+
+
gpu_device
+

The GPU device index to use. +Default value: "0" +

+
+
destination
+

If set, the transcription output will be sent to the specified file or URL +(use one of the FFmpeg AVIO protocols); otherwise, the output will be logged as +info messages. +The output will also be set in the "lavfi.whisper.text" frame metadata. +If the destination is a file and it already exists, it will be overwritten. +

+
+
format
+

The destination format string; it could be "text" (only the transcribed text +will be sent to the destination), "srt" (subtitle format) or "json". +Default value: "text" +

+
+
max_len
+

Maximum segment length in characters. When set to a value greater than 0, +transcription segments will be split to not exceed this length. This is useful +for generating subtitles with shorter lines. +Default value: "0" +

+
+
vad_model
+

Path to the VAD model file. If set, the filter will load an additional voice +activity detection module (https://github.com/snakers4/silero-vad) that will be +used to fragment the audio queue; use this option setting a valid path obtained +from the whisper.cpp repository (e.g. "../whisper.cpp/models/ggml-silero-v5.1.2.bin") +and increase the queue parameter to a higher value (e.g. 20). +

+
+
vad_threshold
+

The VAD threshold to use. +Default value: "0.5" +

+
+
vad_min_speech_duration
+

The minimum VAD speaking duration. +Default value: "0.1" +

+
+
vad_min_silence_duration
+

The minimum VAD silence duration. +Default value: "0.5" +

+
+
+ + +

29.122.1 Examples

+
    +
  • Run a transcription with srt file generation: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=output.srt\
    +:format=srt" -f null -
    +
    + +
  • Run a transcription and send the output in JSON format to an HTTP service: +
    +
    ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
    +:language=en\
    +:queue=3\
    +:destination=http\\://localhost\\:3000\
    +:format=json' -f null -
    +
    + +
  • Transcribe the microphone input using the VAD option: +
    +
    ffmpeg -loglevel warning -f pulse -i default \
    +-af 'highpass=f=200,lowpass=f=3000,whisper=model=../whisper.cpp/models/ggml-medium.bin\
    +:language=en\
    +:queue=10\
    +:destination=-\
    +:format=json\
    +:vad_model=../whisper.cpp/models/ggml-silero-v5.1.2.bin' -f null -
    +
    + +
+ + + +

30 Audio Sources

+ +

Below is a description of the currently available audio sources. +

+ +

30.1 abuffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
time_base
+

The timebase which will be used for timestamps of submitted frames. It must be +either a floating-point number or in numerator/denominator form. +

+
+
sample_rate
+

The sample rate of the incoming audio buffers. +

+
+
sample_fmt
+

The sample format of the incoming audio buffers. +Either a sample format name or its corresponding integer representation from +the enum AVSampleFormat in libavutil/samplefmt.h +

+
+
channel_layout
+

The channel layout of the incoming audio buffers. +Either a channel layout name from channel_layout_map in +libavutil/channel_layout.c or its corresponding integer representation +from the AV_CH_LAYOUT_* macros in libavutil/channel_layout.h +

+
+
channels
+

The number of channels of the incoming audio buffers. +If both channels and channel_layout are specified, then they +must be consistent. +

+
+
+ + +

30.1.1 Examples

+ +
+
abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
+
+ +

will instruct the source to accept planar 16bit signed stereo at 44100Hz. +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: +

+
abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
+
+ + +

30.2 aevalsrc

+ +

Generate an audio signal specified by an expression. +

+

This source accepts in input one or more expressions (one for each +channel), which are evaluated and used to generate a corresponding +audio signal. +

+

This source accepts the following options: +

+
+
exprs
+

Set the ’|’-separated expressions list for each separate channel. In case the +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. +

+
+
channel_layout, c
+

Set the channel layout. The number of channels in the specified layout +must be equal to the number of specified expressions. +

+
+
duration, d
+

Set the minimum duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +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. +

+
+
nb_samples, n
+

Set the number of samples per channel per each output frame, +default to 1024. +

+
+
sample_rate, s
+

Specify the sample rate, default to 44100. +

+
+ +

Each expression in exprs can contain the following constants: +

+
+
n
+

number of the evaluated sample, starting from 0 +

+
+
t
+

time of the evaluated sample expressed in seconds, starting from 0 +

+
+
s
+

sample rate +

+
+
+ + +

30.2.1 Examples

+ +
    +
  • Generate silence: +
    +
    aevalsrc=0
    +
    + +
  • Generate a sin signal with frequency of 440 Hz, set sample rate to +8000 Hz: +
    +
    aevalsrc="sin(440*2*PI*t):s=8000"
    +
    + +
  • Generate a two channels signal, specify the channel layout (Front +Center + Back Center) explicitly: +
    +
    aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
    +
    + +
  • Generate white noise: +
    +
    aevalsrc="-2+random(0)"
    +
    + +
  • Generate an amplitude modulated signal: +
    +
    aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
    +
    + +
  • Generate 2.5 Hz binaural beats on a 360 Hz carrier: +
    +
    aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
    +
    + +
+ + +

30.3 afdelaysrc

+ +

Generate a fractional delay FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
delay, d
+

Set the fractional delay. Default is 0. +

+
+
sample_rate, r
+

Set the sample rate, default is 44100. +

+
+
nb_samples, n
+

Set the number of samples per each frame. Default is 1024. +

+
+
taps, t
+

Set the number of filter coefficients in output audio stream. +Default value is 0. +

+
+
channel_layout, c
+

Specifies the channel layout, and can be a string representing a channel layout. +The default value of channel_layout is "stereo". +

+
+ + +

30.4 afireqsrc

+ +

Generate a FIR equalizer coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
preset, p
+

Set equalizer preset. +Default preset is flat. +

+

Available presets are: +

+
‘custom’
+
‘flat’
+
‘acoustic’
+
‘bass’
+
‘beats’
+
‘classic’
+
‘clear’
+
‘deep bass’
+
‘dubstep’
+
‘electronic’
+
‘hard-style’
+
‘hip-hop’
+
‘jazz’
+
‘metal’
+
‘movie’
+
‘pop’
+
‘r&b’
+
‘rock’
+
‘vocal booster’
+
+ +
+
gains, g
+

Set custom gains for each band. Only used if the preset option is set to custom. +Gains are separated by white spaces and each gain is set in dBFS. +Default is 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0. +

+
+
bands, b
+

Set the custom bands from where custom equalizer gains are set. +This must be in strictly increasing order. Only used if the preset option is set to custom. +Bands are separated by white spaces and each band represent frequency in Hz. +Default is 25 40 63 100 160 250 400 630 1000 1600 2500 4000 6300 10000 16000 24000. +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 4096. +

+
+
sample_rate, r
+

Set sample rate of output audio stream, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame in output audio stream. Default is 1024. +

+
+
interp, i
+

Set interpolation method for FIR equalizer coefficients. Can be linear or cubic. +

+
+
phase, h
+

Set phase type of FIR filter. Can be linear or min: minimum-phase. +Default is minimum-phase filter. +

+
+ + +

30.5 afirsrc

+ +

Generate a FIR coefficients using frequency sampling method. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
taps, t
+

Set number of filter coefficients in output audio stream. +Default value is 1025. +

+
+
frequency, f
+

Set frequency points from where magnitude and phase are set. +This must be in non decreasing order, and first element must be 0, while last element +must be 1. Elements are separated by white spaces. +

+
+
magnitude, m
+

Set magnitude value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
phase, p
+

Set phase value for every frequency point set by frequency. +Number of values must be same as number of frequency points. +Values are separated by white spaces. +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
win_func, w
+

Set window function. Default is blackman. +

+
+ + +

30.6 anullsrc

+ +

The null audio source, return unprocessed audio frames. It is mainly useful +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). +

+

This source accepts the following options: +

+
+
channel_layout, cl
+
+

Specifies the channel layout, and can be either an integer or a string +representing a channel layout. The default value of channel_layout +is "stereo". +

+

Check the channel_layout_map definition in +libavutil/channel_layout.c for the mapping between strings and +channel layout values. +

+
+
sample_rate, r
+

Specifies the sample rate, and defaults to 44100. +

+
+
nb_samples, n
+

Set the number of samples per requested frames. +

+
+
duration, d
+

Set the duration of the sourced audio. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. +

+
+ + +

30.6.1 Examples

+ +
    +
  • Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. +
    +
    anullsrc=r=48000:cl=4
    +
    + +
  • Do the same operation with a more obvious syntax: +
    +
    anullsrc=r=48000:cl=mono
    +
    +
+ +

All the parameters need to be explicitly defined. +

+ +

30.7 flite

+ +

Synthesize a voice utterance using the libflite library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libflite. +

+

Note that versions of the flite library prior to 2.0 are not thread-safe. +

+

The filter accepts the following options: +

+
+
list_voices
+

If set to 1, list the names of the available voices and exit +immediately. Default value is 0. +

+
+
nb_samples, n
+

Set the maximum number of samples per frame. Default value is 512. +

+
+
textfile
+

Set the filename containing the text to speak. +

+
+
text
+

Set the text to speak. +

+
+
voice, v
+

Set the voice to use for the speech synthesis. Default value is +kal. See also the list_voices option. +

+
+ + +

30.7.1 Examples

+ +
    +
  • Read from file speech.txt, and synthesize the text using the +standard flite voice: +
    +
    flite=textfile=speech.txt
    +
    + +
  • Read the specified text selecting the slt voice: +
    +
    flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Input text to ffmpeg: +
    +
    ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
    +
    + +
  • Make ffplay speak the specified text, using flite and +the lavfi device: +
    +
    ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
    +
    +
+ +

For more information about libflite, check: +http://www.festvox.org/flite/ +

+ +

30.8 anoisesrc

+ +

Generate a noise audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Specify the sample rate. Default value is 48000 Hz. +

+
+
amplitude, a
+

Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value +is 1.0. +

+
+
duration, d
+

Specify the duration of the generated audio stream. Not specifying this option +results in noise with an infinite length. +

+
+
color, colour, c
+

Specify the color of noise. Available noise colors are white, pink, brown, +blue, violet and velvet. Default color is white. +

+
+
seed, s
+

Specify a value used to seed the PRNG. +

+
+
nb_samples, n
+

Set the number of samples per each output frame, default is 1024. +

+
+
density
+

Set the density (0.0 - 1.0) for the velvet noise generator, default is 0.05. +

+
+ + +

30.8.1 Examples

+ +
    +
  • Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: +
    +
    anoisesrc=d=60:c=pink:r=44100:a=0.5
    +
    +
+ + +

30.9 hilbert

+ +

Generate odd-tap Hilbert transform FIR coefficients. +

+

The resulting stream can be used with afir filter for phase-shifting +the signal by 90 degrees. +

+

This is used in many matrix coding schemes and for analytic signal generation. +The process is often written as a multiplication by i (or j), the imaginary unit. +

+

The filter accepts the following options: +

+
+
sample_rate, s
+

Set sample rate, default is 44100. +

+
+
taps, t
+

Set length of FIR filter, default is 22051. +

+
+
nb_samples, n
+

Set number of samples per each frame. +

+
+
win_func, w
+

Set window function to be used when generating FIR coefficients. +

+
+ + +

30.10 sinc

+ +

Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. +

+

The resulting stream can be used with afir filter for filtering the audio signal. +

+

The filter accepts the following options: +

+
+
sample_rate, r
+

Set sample rate, default is 44100. +

+
+
nb_samples, n
+

Set number of samples per each frame. Default is 1024. +

+
+
hp
+

Set high-pass frequency. Default is 0. +

+
+
lp
+

Set low-pass frequency. Default is 0. +If high-pass frequency is lower than low-pass frequency and low-pass frequency +is higher than 0 then filter will create band-pass filter coefficients, +otherwise band-reject filter coefficients. +

+
+
phase
+

Set filter phase response. Default is 50. Allowed range is from 0 to 100. +

+
+
beta
+

Set Kaiser window beta. +

+
+
att
+

Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. +

+
+
round
+

Enable rounding, by default is disabled. +

+
+
hptaps
+

Set number of taps for high-pass filter. +

+
+
lptaps
+

Set number of taps for low-pass filter. +

+
+ + +

30.11 sine

+ +

Generate an audio signal made of a sine wave with amplitude 1/8. +

+

The audio signal is bit-exact. +

+

The filter accepts the following options: +

+
+
frequency, f
+

Set the carrier frequency. Default is 440 Hz. +

+
+
beep_factor, b
+

Enable a periodic beep every second with frequency beep_factor times +the carrier frequency. Default is 0, meaning the beep is disabled. +

+
+
sample_rate, r
+

Specify the sample rate, default is 44100. +

+
+
duration, d
+

Specify the duration of the generated audio stream. +

+
+
samples_per_frame
+

Set the number of samples per output frame. +

+

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the output audio frame, starting from 0. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the output audio frame, +expressed in TB units. +

+
+
t
+

The PTS of the output audio frame, expressed in seconds. +

+
+
TB
+

The timebase of the output audio frames. +

+
+ +

Default is 1024. +

+
+ + +

30.11.1 Examples

+ +
    +
  • Generate a simple 440 Hz sine wave: +
    +
    sine
    +
    + +
  • Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: +
    +
    sine=220:4:d=5
    +sine=f=220:b=4:d=5
    +sine=frequency=220:beep_factor=4:duration=5
    +
    + +
  • Generate a 1 kHz sine wave following 1602,1601,1602,1601,1602 NTSC +pattern: +
    +
    sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
    +
    +
+ + + +

31 Audio Sinks

+ +

Below is a description of the currently available audio sinks. +

+ +

31.1 abuffersink

+ +

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 libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVABufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+

31.2 anullsink

+ +

Null audio sink; do absolutely nothing with the input audio. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

32 Video Filters

+ +

When you configure your FFmpeg build, you can disable any of the +existing filters using --disable-filters. +The configure output will show the video filters included in your +build. +

+

Below is a description of the currently available video filters. +

+ +

32.1 addroi

+ +

Mark a region of interest in a video frame. +

+

The frame data is passed through unchanged, but metadata is attached +to the frame indicating regions of interest which can affect the +behaviour of later encoding. Multiple regions can be marked by +applying the filter multiple times. +

+
+
x
+

Region distance in pixels from the left edge of the frame. +

+
y
+

Region distance in pixels from the top edge of the frame. +

+
w
+

Region width in pixels. +

+
h
+

Region height in pixels. +

+

The parameters x, y, w and h are expressions, +and may contain the following variables: +

+
iw
+

Width of the input frame. +

+
ih
+

Height of the input frame. +

+
+ +
+
qoffset
+

Quantisation offset to apply within the region. +

+

This must be a real value in the range -1 to +1. A value of zero +indicates no quality change. A negative value asks for better quality +(less quantisation), while a positive value asks for worse quality +(greater quantisation). +

+

The range is calibrated so that the extreme values indicate the +largest possible offset - if the rest of the frame is encoded with the +worst possible quality, an offset of -1 indicates that this region +should be encoded with the best possible quality anyway. Intermediate +values are then interpolated in some codec-dependent way. +

+

For example, in 10-bit H.264 the quantisation parameter varies between +-12 and 51. A typical qoffset value of -1/10 therefore indicates that +this region should be encoded with a QP around one-tenth of the full +range better than the rest of the frame. So, if most of the frame +were to be encoded with a QP of around 30, this region would get a QP +of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). +An extreme value of -1 would indicate that this region should be +encoded with the best possible quality regardless of the treatment of +the rest of the frame - that is, should be encoded at a QP of -12. +

+
clear
+

If set to true, remove any existing regions of interest marked on the +frame before adding the new one. +

+
+ + +

32.1.1 Examples

+ +
    +
  • Mark the centre quarter of the frame as interesting. +
    +
    addroi=iw/4:ih/4:iw/2:ih/2:-1/10
    +
    +
  • Mark the 100-pixel-wide region on the left edge of the frame as very +uninteresting (to be encoded at much lower quality than the rest of +the frame). +
    +
    addroi=0:0:100:ih:+1/5
    +
    +
+ + +

32.2 alphaextract

+ +

Extract the alpha component from the input as a grayscale video. This +is especially useful with the alphamerge filter. +

+ +

32.3 alphamerge

+ +

Add or replace the alpha component of the primary input with the +grayscale value of a second input. This is intended for use with +alphaextract to allow the transmission or storage of frame +sequences that have alpha in a format that doesn’t support an alpha +channel. +

+

For example, to reconstruct full frames from a normal YUV-encoded video +and a separate video created with alphaextract, you might use: +

+
movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
+
+ + +

32.4 amplify

+ +

Amplify differences between current pixel and pixels of adjacent frames in +same pixel location. +

+

This filter accepts the following options: +

+
+
radius
+

Set frame radius. Default is 2. Allowed range is from 1 to 63. +For example radius of 3 will instruct filter to calculate average of 7 frames. +

+
+
factor
+

Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. +

+
+
threshold
+

Set threshold for difference amplification. Any difference greater or equal to +this value will not alter source pixel. Default is 10. +Allowed range is from 0 to 65535. +

+
+
tolerance
+

Set tolerance for difference amplification. Any difference lower to +this value will not alter source pixel. Default is 0. +Allowed range is from 0 to 65535. +

+
+
low
+

Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will decrease source pixel value. +

+
+
high
+

Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. +This option controls maximum possible value that will increase source pixel value. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

32.4.1 Commands

+ +

This filter supports the following commands that corresponds to option of same name: +

+
factor
+
threshold
+
tolerance
+
low
+
high
+
planes
+
+ + +

32.5 ass

+ +

Same as the subtitles filter, except that it doesn’t require libavcodec +and libavformat to work. On the other hand, it is limited to ASS (Advanced +Substation Alpha) subtitles files. +

+

This filter accepts the following option in addition to the common options from +the subtitles filter: +

+
+
shaping
+

Set the shaping engine +

+

Available values are: +

+
‘auto’
+

The default libass shaping engine, which is the best available. +

+
‘simple’
+

Fast, font-agnostic shaper that can do only substitutions +

+
‘complex’
+

Slower shaper using OpenType for substitutions and positioning +

+
+ +

The default is auto. +

+
+ + +

32.6 atadenoise

+

Apply an Adaptive Temporal Averaging Denoiser to the video input. +

+

The filter accepts the following options: +

+
+
0a
+

Set threshold A for 1st plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
0b
+

Set threshold B for 1st plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
1a
+

Set threshold A for 2nd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
1b
+

Set threshold B for 2nd plane. Default is 0.04. +Valid range is 0 to 5. +

+
+
2a
+

Set threshold A for 3rd plane. Default is 0.02. +Valid range is 0 to 0.3. +

+
+
2b
+

Set threshold B for 3rd plane. Default is 0.04. +Valid range is 0 to 5. +

+

Threshold A is designed to react on abrupt changes in the input signal and +threshold B is designed to react on continuous changes in the input signal. +

+
+
s
+

Set number of frames filter will use for averaging. Default is 9. Must be odd +number in range [5, 129]. +

+
+
p
+

Set what planes of frame filter will use for averaging. Default is all. +

+
+
a
+

Set what variant of algorithm filter will use for averaging. Default is p parallel. +Alternatively can be set to s serial. +

+

Parallel can be faster then serial, while other way around is never true. +Parallel will abort early on first change being greater then thresholds, while serial +will continue processing other side of frames if they are equal or below thresholds. +

+
+
0s
+
1s
+
2s
+

Set sigma for 1st plane, 2nd plane or 3rd plane. Default is 32767. +Valid range is from 0 to 32767. +This options controls weight for each pixel in radius defined by size. +Default value means every pixel have same weight. +Setting this option to 0 effectively disables filtering. +

+
+ + +

32.6.1 Commands

+

This filter supports same commands as options except option s. +The command accepts the same syntax of the corresponding option. +

+ +

32.7 avgblur

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sizeY
+

Set vertical radius size, if zero it will be same as sizeX. +Default is 0. +

+
+ + +

32.7.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.8 backgroundkey

+ +

Turns a static background into transparency. +

+

The filter accepts the following option: +

+
+
threshold
+

Threshold for scene change detection. +

+
similarity
+

Similarity percentage with the background. +

+
blend
+

Set the blend amount for pixels that are not similar. +

+
+ + +

32.8.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.9 bbox

+ +

Compute the bounding box for the non-black pixels in the input frame +luma plane. +

+

This filter computes the bounding box containing all the pixels with a +luma 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: +

+
+
min_val
+

Set the minimal luma value. Default is 16. +

+
+ + +

32.9.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.10 bilateral

+

Apply bilateral filter, spatial smoothing while preserving edges. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight. +Allowed range is 0 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate range weight. +Allowed range is 0 to 1. Default is 0.1. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

32.10.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.11 bitplanenoise

+ +

Show and measure bit plane noise. +

+

The filter accepts the following options: +

+
+
bitplane
+

Set which plane to analyze. Default is 1. +

+
+
filter
+

Filter out noisy pixels from bitplane set above. +Default is disabled. +

+
+ + +

32.12 blackdetect, blackdetect_vulkan

+ +

Detect video intervals that are (almost) completely black. Can be +useful to detect chapter transitions, commercials, or invalid +recordings. +

+

The filter outputs its detection analysis to both the log as well as +frame metadata. If a black segment of at least the specified minimum +duration is found, a line with the start and end timestamps as well +as duration is printed to the log with level info. In addition, +a log line with level debug is printed per frame showing the +black amount detected for that frame. +

+

The filter also attaches metadata to the first frame of a black +segment with key lavfi.black_start and to the first frame +after the black segment ends with key lavfi.black_end. The +value is the frame’s timestamp. This metadata is added regardless +of the minimum duration specified. +

+

The filter accepts the following options: +

+
+
black_min_duration, d
+

Set the minimum detected black duration expressed in seconds. It must +be a non-negative floating point number. +

+

Default value is 2.0. +

+
+
picture_black_ratio_th, pic_th
+

Set the threshold for considering a picture "black". +Express the minimum value for the ratio: +

+
nb_black_pixels / nb_pixels
+
+ +

for which a picture is considered black. +Default value is 0.98. +

+
+
pixel_black_th, pix_th
+

Set the threshold for considering a pixel "black". +

+

The threshold expresses the maximum pixel luma value for which a +pixel is considered "black". The provided value is scaled according to +the following equation: +

+
absolute_threshold = luma_minimum_value + pixel_black_th * luma_range_size
+
+ +

luma_range_size and luma_minimum_value depend on +the input video format, the range is [0-255] for YUV full-range +formats and [16-235] for YUV non full-range formats. +

+

Default value is 0.10. +

+
+
alpha
+

If true, check the alpha channel instead of the luma channel. Detects frames +which are (almost) transparent, instead of frames which are almost black. +

+

Default value is disabled. +

+
+ +

The following example sets the maximum pixel threshold to the minimum +value, and detects only black intervals of 2 or more seconds: +

+
blackdetect=d=2:pix_th=0.00
+
+ + +

32.13 blackframe

+ +

Detect frames that are (almost) completely black. Can be useful to +detect chapter transitions or commercials. Output lines consist of +the frame number of the detected frame, the percentage of blackness, +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. +

+

This filter exports frame metadata lavfi.blackframe.pblack. +The value represents the percentage of pixels in the picture that +are below the threshold value. +

+

It accepts the following parameters: +

+
+
amount
+

The percentage of the pixels that have to be below the threshold; it defaults to +98. +

+
+
threshold, thresh
+

The threshold below which a pixel value is considered black; it defaults to +32. +

+
+
+ + +

32.14 blend

+ +

Blend two video frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

The tblend (time blend) filter takes two consecutive frames +from one single stream, and outputs the result obtained by blending +the new frame on top of the old frame. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘addition’
+
‘and’
+
‘average’
+
‘bleach’
+
‘burn’
+
‘darken’
+
‘difference’
+
‘divide’
+
‘dodge’
+
‘exclusion’
+
‘extremity’
+
‘freeze’
+
‘geometric’
+
‘glow’
+
‘grainextract’
+
‘grainmerge’
+
‘hardlight’
+
‘hardmix’
+
‘hardoverlay’
+
‘harmonic’
+
‘heat’
+
‘interpolate’
+
‘lighten’
+
‘linearlight’
+
‘multiply’
+
‘multiply128’
+
‘negation’
+
‘normal’
+
‘or’
+
‘overlay’
+
‘phoenix’
+
‘pinlight’
+
‘reflect’
+
‘screen’
+
‘softdifference’
+
‘softlight’
+
‘stain’
+
‘subtract’
+
‘vividlight’
+
‘xor’
+
+ +
+
c0_opacity
+
c1_opacity
+
c2_opacity
+
c3_opacity
+
all_opacity
+

Set blend opacity for specific pixel component or all pixel components in case +of all_opacity. Only used in combination with pixel component blend modes. +

+
+
c0_expr
+
c1_expr
+
c2_expr
+
c3_expr
+
all_expr
+

Set blend expression for specific pixel component or all pixel components in case +of all_expr. Note that related mode options will be ignored if those are set. +

+

The expressions can use the following variables: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

the coordinates of the current sample +

+
+
W
+
H
+

the width and height of currently filtered plane +

+
+
SW
+
SH
+

Width and height scale for the plane being filtered. It is the +ratio between the dimensions of the current plane to the luma plane, +e.g. for a yuv420p frame, the values are 1,1 for +the luma plane and 0.5,0.5 for the chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
TOP, A
+

Value of pixel component at current location for first video frame (top layer). +

+
+
BOTTOM, B
+

Value of pixel component at current location for second video frame (bottom layer). +

+
+
+
+ +

The blend filter also supports the framesync options. +

+ +

32.14.1 Examples

+ +
    +
  • Apply transition from bottom layer to top layer in first 10 seconds: +
    +
    blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
    +
    + +
  • Apply linear horizontal transition from top layer to bottom layer: +
    +
    blend=all_expr='A*(X/W)+B*(1-X/W)'
    +
    + +
  • Apply 1x1 checkerboard effect: +
    +
    blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
    +
    + +
  • Apply uncover left effect: +
    +
    blend=all_expr='if(gte(N*SW+X,W),A,B)'
    +
    + +
  • Apply uncover down effect: +
    +
    blend=all_expr='if(gte(Y-N*SH,0),A,B)'
    +
    + +
  • Apply uncover up-left effect: +
    +
    blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
    +
    + +
  • Split diagonally video and shows top and bottom layer on each side: +
    +
    blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
    +
    + +
  • Display differences between the current and the previous frame: +
    +
    tblend=all_mode=grainextract
    +
    +
+ + +

32.14.2 Commands

+

This filter supports same commands as options. +

+ +

32.15 blockdetect

+ +

Determines blockiness of frames without altering the input frames. +

+

Based on Remco Muijs and Ihor Kirenko: "A no-reference blocking artifact measure for adaptive video processing." 2005 13th European signal processing conference. +

+

The filter accepts the following options: +

+
+
period_min
+
period_max
+

Set minimum and maximum values for determining pixel grids (periods). +Default values are [3,24]. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

32.15.1 Examples

+ +
    +
  • Determine blockiness for the first plane and search for periods within [8,32]: +
    +
    blockdetect=period_min=8:period_max=32:planes=1
    +
    +
+ + +

32.16 blurdetect

+ +

Determines blurriness of frames without altering the input frames. +

+

Based on Marziliano, Pina, et al. "A no-reference perceptual blur metric." +Allows for a block-based abbreviation. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
radius
+

Define the radius to search around an edge pixel for local maxima. +

+
+
block_pct
+

Determine blurriness only for the most significant blocks, given in percentage. +

+
+
block_width
+

Determine blurriness for blocks of width block_width. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_height. +

+
+
block_height
+

Determine blurriness for blocks of height block_height. If set to any value smaller 1, no blocks are used and the whole image is processed as one no matter of block_width. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

32.16.1 Examples

+ +
    +
  • Determine blur for 80% of most significant 32x32 blocks: +
    +
    blurdetect=block_width=32:block_height=32:block_pct=80
    +
    +
+ + +

32.17 bm3d

+ +

Denoise frames using Block-Matching 3D algorithm. +

+

The filter accepts the following options. +

+
+
sigma
+

Set denoising strength. Default value is 1. +Allowed range is from 0 to 999.9. +The denoising algorithm is very sensitive to sigma, so adjust it +according to the source. +

+
+
block
+

Set local patch size. This sets dimensions in 2D. +

+
+
bstep
+

Set sliding step for processing blocks. Default value is 4. +Allowed range is from 1 to 64. +Smaller values allows processing more reference blocks and is slower. +

+
+
group
+

Set maximal number of similar blocks for 3rd dimension. Default value is 1. +When set to 1, no block matching is done. Larger values allows more blocks +in single group. +Allowed range is from 1 to 256. +

+
+
range
+

Set radius for search block matching. Default is 9. +Allowed range is from 1 to INT32_MAX. +

+
+
mstep
+

Set step between two search locations for block matching. Default is 1. +Allowed range is from 1 to 64. Smaller is slower. +

+
+
thmse
+

Set threshold of mean square error for block matching. Valid range is 0 to +INT32_MAX. +

+
+
hdthr
+

Set thresholding parameter for hard thresholding in 3D transformed domain. +Larger values results in stronger hard-thresholding filtering in frequency +domain. +

+
+
estim
+

Set filtering estimation mode. Can be basic or final. +Default is basic. +

+
+
ref
+

If enabled, filter will use 2nd stream for block matching. +Default is disabled for basic value of estim option, +and always enabled if value of estim is final. +

+
+
planes
+

Set planes to filter. Default is all available except alpha. +

+
+ + +

32.17.1 Examples

+ +
    +
  • Basic filtering with bm3d: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
    +
    + +
  • Same as above, but filtering only luma: +
    +
    bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
    +
    + +
  • Same as above, but with both estimation modes: +
    +
    split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    + +
  • Same as above, but prefilter with nlmeans filter instead: +
    +
    split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
    +
    +
+ + +

32.18 boxblur

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

32.18.1 Examples

+ +
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radii +set to 2: +
    +
    boxblur=luma_radius=2:luma_power=1
    +boxblur=2:1
    +
    + +
  • Set the luma radius to 2, and alpha and chroma radius to 0: +
    +
    boxblur=2:1:cr=0:ar=0
    +
    + +
  • Set the luma and chroma radii to a fraction of the video dimension: +
    +
    boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
    +
    +
+ + +

32.19 bwdif

+ +

Deinterlace the input video ("bwdif" stands for "Bob Weaver +Deinterlacing Filter"). +

+

Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic +interpolation algorithms. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

32.20 ccrepack

+ +

Repack CEA-708 closed captioning side data +

+

This filter fixes various issues seen with commercial encoders +related to upstream malformed CEA-708 payloads, specifically +incorrect number of tuples (wrong cc_count for the target FPS), +and incorrect ordering of tuples (i.e. the CEA-608 tuples are not at +the first entries in the payload). +

+ +

32.21 cas

+ +

Apply Contrast Adaptive Sharpen filter to video stream. +

+

The filter accepts the following options: +

+
+
strength
+

Set the sharpening strength. Default value is 0. +

+
+
planes
+

Set planes to filter. Default value is to filter all +planes except alpha plane. +

+
+ + +

32.21.1 Commands

+

This filter supports same commands as options. +

+ +

32.22 chromahold

+

Remove all color information for all colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral chroma. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +0.0 makes pixels either fully gray, or not gray at all. +Higher values result in more preserved color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

32.22.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.23 chromakey

+

YUV colorspace color/chroma keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+
yuv
+

Signals that the color passed is already in YUV instead of RGB. +

+

Literal colors like "green" or "red" don’t make sense with this enabled anymore. +This can be used to pass exact YUV values as hexadecimal numbers. +

+
+ + +

32.23.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.23.2 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf chromakey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static black background. +
    +
    ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
    +
    +
+ + +

32.24 chromanr

+

Reduce chrominance noise. +

+

The filter accepts the following options: +

+
+
thres
+

Set threshold for averaging chrominance values. +Sum of absolute difference of Y, U and V pixel components of current +pixel and neighbour pixels lower than this threshold will be used in +averaging. Luma component is left unchanged and is copied to output. +Default value is 30. Allowed range is from 1 to 200. +

+
+
sizew
+

Set horizontal radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
sizeh
+

Set vertical radius of rectangle used for averaging. +Allowed range is from 1 to 100. Default value is 5. +

+
+
stepw
+

Set horizontal step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
steph
+

Set vertical step when averaging. Default value is 1. +Allowed range is from 1 to 50. +Mostly useful to speed-up filtering. +

+
+
threy
+

Set Y threshold for averaging chrominance values. +Set finer control for max allowed difference between Y components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threu
+

Set U threshold for averaging chrominance values. +Set finer control for max allowed difference between U components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
threv
+

Set V threshold for averaging chrominance values. +Set finer control for max allowed difference between V components +of current pixel and neighbour pixels. +Default value is 200. Allowed range is from 1 to 200. +

+
+
distance
+

Set distance type used in calculations. +

+
+
‘manhattan’
+

Absolute difference. +

+
‘euclidean’
+

Difference squared. +

+
+ +

Default distance type is manhattan. +

+
+ + +

32.24.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+ +

32.25 chromashift

+

Shift chroma pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
cbh
+

Set amount to shift chroma-blue horizontally. +

+
cbv
+

Set amount to shift chroma-blue vertically. +

+
crh
+

Set amount to shift chroma-red horizontally. +

+
crv
+

Set amount to shift chroma-red vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

32.25.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.26 ciescope

+ +

Display CIE color diagram with pixels overlaid onto it. +

+

The filter accepts the following options: +

+
+
system
+

Set color system. +

+
+
‘ntsc, 470m’
+
‘ebu, 470bg’
+
‘smpte’
+
‘240m’
+
‘apple’
+
‘widergb’
+
‘cie1931’
+
‘rec709, hdtv’
+
‘uhdtv, rec2020’
+
‘dcip3’
+
+ +
+
cie
+

Set CIE system. +

+
+
‘xyy’
+
‘ucs’
+
‘luv’
+
+ +
+
gamuts
+

Set what gamuts to draw. +

+

See system option for available values. +

+
+
size, s
+

Set ciescope size, by default set to 512. +

+
+
intensity, i
+

Set intensity used to map input pixel values to CIE diagram. +

+
+
contrast
+

Set contrast used to draw tongue colors that are out of active color system gamut. +

+
+
corrgamma
+

Correct gamma displayed on scope, by default enabled. +

+
+
showwhite
+

Show white point on CIE diagram, by default disabled. +

+
+
gamma
+

Set input gamma. Used only with XYZ input color space. +

+
+
fill
+

Fill with CIE colors. By default is enabled. +

+
+ + +

32.27 codecview

+ +

Visualize information exported by some codecs. +

+

Some codecs can export information through frames using side-data or other +means. For example, some MPEG based codecs export motion vectors through the +export_mvs flag in the codec flags2 option. +

+

The filter accepts the following option: +

+
+
block
+

Display block partition structure using the luma plane. +

+
+
mv
+

Set motion vectors to visualize. +

+

Available flags for mv are: +

+
+
‘pf’
+

forward predicted MVs of P-frames +

+
‘bf’
+

forward predicted MVs of B-frames +

+
‘bb’
+

backward predicted MVs of B-frames +

+
+ +
+
qp
+

Display quantization parameters using the chroma planes. +

+
+
mv_type, mvt
+

Set motion vectors type to visualize. Includes MVs from all frames unless specified by frame_type option. +

+

Available flags for mv_type are: +

+
+
‘fp’
+

forward predicted MVs +

+
‘bp’
+

backward predicted MVs +

+
+ +
+
frame_type, ft
+

Set frame type to visualize motion vectors of. +

+

Available flags for frame_type are: +

+
+
‘if’
+

intra-coded frames (I-frames) +

+
‘pf’
+

predicted frames (P-frames) +

+
‘bf’
+

bi-directionally predicted frames (B-frames) +

+
+
+
+ + +

32.27.1 Examples

+ +
    +
  • Visualize forward predicted MVs of all frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
    +
    + +
  • Visualize multi-directionals MVs of P and B-Frames using ffplay: +
    +
    ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
    +
    +
+ + +

32.28 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: +

+
+
rs
+
gs
+
bs
+

Adjust red, green and blue shadows (darkest pixels). +

+
+
rm
+
gm
+
bm
+

Adjust red, green and blue midtones (medium pixels). +

+
+
rh
+
gh
+
bh
+

Adjust red, green and blue highlights (brightest pixels). +

+

Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
pl
+

Preserve lightness when changing color balance. Default is disabled. +

+
+ + +

32.28.1 Examples

+ +
    +
  • Add red color cast to shadows: +
    +
    colorbalance=rs=.3
    +
    +
+ + +

32.28.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.29 colorcontrast

+ +

Adjust color contrast between RGB components. +

+

The filter accepts the following options: +

+
+
rc
+

Set the red-cyan contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
gm
+

Set the green-magenta contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
by
+

Set the blue-yellow contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. +

+
+
rcw
+
gmw
+
byw
+

Set the weight of each rc, gm, by option value. Default value is 0.0. +Allowed range is from 0.0 to 1.0. If all weights are 0.0 filtering is disabled. +

+
+
pl
+

Set the amount of preserving lightness. Default value is 0.0. Allowed range is from 0.0 to 1.0. +

+
+ + +

32.29.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.30 colorcorrect

+ +

Adjust color white balance selectively for blacks and whites. +This filter operates in YUV colorspace. +

+

The filter accepts the following options: +

+
+
rl
+

Set the red shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bl
+

Set the blue shadow spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
rh
+

Set the red highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
bh
+

Set the blue highlight spot. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+
saturation
+

Set the amount of saturation. Allowed range is from -3.0 to 3.0. +Default value is 1. +

+
+
analyze
+

If set to anything other than manual it will analyze every frame and use derived +parameters for filtering output frame. +

+

Possible values are: +

+
‘manual’
+
‘average’
+
‘minmax’
+
‘median’
+
+

Default value is manual. +

+
+ + +

32.30.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.31 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: +

+
red=red*rr + blue*rb + green*rg + alpha*ra
+
+ +

The filter accepts the following options: +

+
+
rr
+
rg
+
rb
+
ra
+

Adjust contribution of input red, green, blue and alpha channels for output red channel. +Default is 1 for rr, and 0 for rg, rb and ra. +

+
+
gr
+
gg
+
gb
+
ga
+

Adjust contribution of input red, green, blue and alpha channels for output green channel. +Default is 1 for gg, and 0 for gr, gb and ga. +

+
+
br
+
bg
+
bb
+
ba
+

Adjust contribution of input red, green, blue and alpha channels for output blue channel. +Default is 1 for bb, and 0 for br, bg and ba. +

+
+
ar
+
ag
+
ab
+
aa
+

Adjust contribution of input red, green, blue and alpha channels for output alpha channel. +Default is 1 for aa, and 0 for ar, ag and ab. +

+

Allowed ranges for options are [-2.0, 2.0]. +

+
+
pc
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+ +
+
pa
+

Set the preserve color amount when changing colors. Allowed range is from [0.0, 1.0]. +Default is 0.0, thus disabled. +

+
+ + +

32.31.1 Examples

+ +
    +
  • Convert source to grayscale: +
    +
    colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
    +
    +
  • Simulate sepia tones: +
    +
    colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
    +
    +
+ + +

32.31.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.32 colordetect

+

Analyze the video frames to determine the effective value range and alpha +mode. +

+

The filter accepts the following options: +

+
+
mode
+

Set of properties to detect. Unavailable properties, such as alpha mode for +an input image without an alpha channel, will be ignored automatically. +

+

Accepts a combination of the following flags: +

+
+
‘color_range’
+

Detect if the source contains luma pixels outside the limited (MPEG) range, +which indicates that this is a full range YUV source. +

+
‘alpha_mode’
+

Detect if the source contains color values above the alpha channel, which +indicates that the alpha channel is independent (straight), rather than +premultiplied. Also detects if the alpha plane is fully opaque or not. +

+
‘all’
+

Enable detection of all of the above properties. This is the default. +

+
+ +
+
+ + +

32.33 colorize

+

Overlay a solid color on the video stream. +

+

The filter accepts the following options: +

+
+
hue
+

Set the color hue. Allowed range is from 0 to 360. +Default value is 0. +

+
+
saturation
+

Set the color saturation. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
lightness
+

Set the color lightness. Allowed range is from 0 to 1. +Default value is 0.5. +

+
+
mix
+

Set the mix of source lightness. By default is set to 1.0. +Allowed range is from 0.0 to 1.0. +

+
+ + +

32.33.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.34 colorkey

+

RGB colorspace color keying. +This filter operates on 8-bit RGB format frames by setting the alpha component of each pixel +which falls within the similarity radius of the key color to 0. The alpha value for pixels outside +the similarity radius depends on the value of the blend option. +

+

The filter accepts the following options: +

+
+
color
+

Set the color for which alpha will be set to 0 (full transparency). +See "Color" section in the ffmpeg-utils manual. +Default is black. +

+
+
similarity
+

Set the radius from the key color within which other colors also have full transparency. +The computed distance is related to the unit fractional distance in 3D space between the RGB values +of the key color and the pixel’s color. Range is 0.01 to 1.0. 0.01 matches within a very small radius +around the exact key color, while 1.0 matches everything. +Default is 0.01. +

+
+
blend
+

Set how the alpha value for pixels that fall outside the similarity radius is computed. +0.0 makes pixels either fully transparent or fully opaque. +Higher values result in semi-transparent pixels, with greater transparency +the more similar the pixel color is to the key color. +Range is 0.0 to 1.0. Default is 0.0. +

+
+ + +

32.34.1 Examples

+ +
    +
  • Make every green pixel in the input image transparent: +
    +
    ffmpeg -i input.png -vf colorkey=green out.png
    +
    + +
  • Overlay a greenscreen-video on top of a static background image. +
    +
    ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv
    +
    +
+ + +

32.34.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.35 colorhold

+

Remove all color information for all RGB colors except for certain one. +

+

The filter accepts the following options: +

+
+
color
+

The color which will not be replaced with neutral gray. +

+
+
similarity
+

Similarity percentage with the above color. +0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. 0.0 makes pixels fully gray. +Higher values result in more preserved color. +

+
+ + +

32.35.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.36 colorlevels

+ +

Adjust video input frames using levels. +

+

The filter accepts the following options: +

+
+
rimin
+
gimin
+
bimin
+
aimin
+

Adjust red, green, blue and alpha input black point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 0. +

+
+
rimax
+
gimax
+
bimax
+
aimax
+

Adjust red, green, blue and alpha input white point. +Allowed ranges for options are [-1.0, 1.0]. Defaults are 1. +

+

Input levels are used to lighten highlights (bright tones), darken shadows +(dark tones), change the balance of bright and dark tones. +

+
+
romin
+
gomin
+
bomin
+
aomin
+

Adjust red, green, blue and alpha output black point. +Allowed ranges for options are [0, 1.0]. Defaults are 0. +

+
+
romax
+
gomax
+
bomax
+
aomax
+

Adjust red, green, blue and alpha output white point. +Allowed ranges for options are [0, 1.0]. Defaults are 1. +

+

Output levels allows manual selection of a constrained output level range. +

+
+
preserve
+

Set preserve color mode. The accepted values are: +

+
‘none’
+

Disable color preserving, this is default. +

+
‘lum’
+

Preserve luminance. +

+
‘max’
+

Preserve max value of RGB triplet. +

+
‘avg’
+

Preserve average value of RGB triplet. +

+
‘sum’
+

Preserve sum value of RGB triplet. +

+
‘nrm’
+

Preserve normalized value of RGB triplet. +

+
‘pwr’
+

Preserve power value of RGB triplet. +

+
+
+
+ + +

32.36.1 Examples

+ +
    +
  • Make video output darker: +
    +
    colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
    +
    + +
  • Increase contrast: +
    +
    colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
    +
    + +
  • Make video output lighter: +
    +
    colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
    +
    + +
  • Increase brightness: +
    +
    colorlevels=romin=0.5:gomin=0.5:bomin=0.5
    +
    +
+ + +

32.36.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.37 colormap

+

Apply custom color maps to video stream. +

+

This filter needs three input video streams. +First stream is video stream that is going to be filtered out. +Second and third video stream specify color patches for source +color to target color mapping. +

+

The filter accepts the following options: +

+
+
patch_size
+

Set the source and target video stream patch size in pixels. +

+
+
nb_patches
+

Set the max number of used patches from source and target video stream. +Default value is number of patches available in additional video streams. +Max allowed number of patches is 64. +

+
+
type
+

Set the adjustments used for target colors. Can be relative or absolute. +Defaults is absolute. +

+
+
kernel
+

Set the kernel used to measure color differences between mapped colors. +

+

The accepted values are: +

+
‘euclidean’
+
‘weuclidean’
+
+ +

Default is euclidean. +

+
+ + +

32.38 colormatrix

+ +

Convert color matrix. +

+

The filter accepts the following options: +

+
+
src
+
dst
+

Specify the source and destination color matrix. Both values must be +specified. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt601’
+

BT.601 +

+
+
‘bt470’
+

BT.470 +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+
+ +

For example to convert from BT.601 to SMPTE-240M, use the command: +

+
colormatrix=bt601:smpte240m
+
+ + +

32.39 colorspace

+ +

Convert colorspace, transfer characteristics or color primaries. +Input video needs to have an even size. +

+

The filter accepts the following options: +

+
+
+
all
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘bt601-6-525’
+

BT.601-6 525 +

+
+
‘bt601-6-625’
+

BT.601-6 625 +

+
+
‘bt709’
+

BT.709 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
space
+

Specify output colorspace. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘ycgco’
+

YCgCo +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M, BT.601-6 625 or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘srgb’
+

SRGB +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘xvycc’
+

xvycc +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+ +
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
format
+

Specify output color format. +

+

The accepted values are: +

+
‘yuv420p’
+

YUV 4:2:0 planar 8-bits +

+
+
‘yuv420p10’
+

YUV 4:2:0 planar 10-bits +

+
+
‘yuv420p12’
+

YUV 4:2:0 planar 12-bits +

+
+
‘yuv422p’
+

YUV 4:2:2 planar 8-bits +

+
+
‘yuv422p10’
+

YUV 4:2:2 planar 10-bits +

+
+
‘yuv422p12’
+

YUV 4:2:2 planar 12-bits +

+
+
‘yuv444p’
+

YUV 4:4:4 planar 8-bits +

+
+
‘yuv444p10’
+

YUV 4:4:4 planar 10-bits +

+
+
‘yuv444p12’
+

YUV 4:4:4 planar 12-bits +

+
+
+ +
+
fast
+

Do a fast conversion, which skips gamma/primary correction. This will take +significantly less CPU, but will be mathematically incorrect. To get output +compatible with that produced by the colormatrix filter, use fast=1. +

+
+
dither
+

Specify dithering mode. +

+

The accepted values are: +

+
‘none’
+

No dithering +

+
+
‘fsb’
+

Floyd-Steinberg dithering +

+
+ +
+
wpadapt
+

Whitepoint adaptation mode. +

+

The accepted values are: +

+
‘bradford’
+

Bradford whitepoint adaptation +

+
+
‘vonkries’
+

von Kries whitepoint adaptation +

+
+
‘identity’
+

identity whitepoint adaptation (i.e. no whitepoint adaptation) +

+
+ +
+
clipgamut
+

Controls how to clip out-of-gamut colors that arise as a result of colorspace conversion. +

+

The accepted values are: +

+
‘none’
+

No clipping of out of gamut colors. +

+
+
‘rgb’
+

Clips the RGB values to the [0, 1] range when building the gamma transfer LUTs. +

+
+ +
+
iall
+

Override all input properties at once. Same accepted values as all. +

+
+
ispace
+

Override input colorspace. Same accepted values as space. +

+
+
iprimaries
+

Override input color primaries. Same accepted values as primaries. +

+
+
itrc
+

Override input transfer characteristics. Same accepted values as trc. +

+
+
irange
+

Override input color range. Same accepted values as range. +

+
+
+ +

The filter converts the transfer characteristics, color space and color +primaries to the specified user values. The output value, if not specified, +is set to a default value based on the "all" property. If that property is +also not specified, the filter will log an error. The output color range and +format default to the same value as the input color range and format. The +input transfer characteristics, color space, color primaries and color range +should be set on the input data. If any of these are missing, the filter will +log an error and no conversion will take place. +

+

For example to convert the input to SMPTE-240M, use the command: +

+
colorspace=smpte240m
+
+ + +

32.40 colortemperature

+

Adjust color temperature in video to simulate variations in ambient color temperature. +

+

The filter accepts the following options: +

+
+
temperature
+

Set the temperature in Kelvin. Allowed range is from 1000 to 40000. +Default value is 6500 K. +

+
+
mix
+

Set mixing with filtered output. Allowed range is from 0 to 1. +Default value is 1. +

+
+
pl
+

Set the amount of preserving lightness. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

32.40.1 Commands

+

This filter supports same commands as options. +

+ +

32.41 convolution

+ +

Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed integers in square mode, +and from 1 to 49 odd number of signed integers in row mode. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be 1/sum of all matrix elements. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. Default is 0.0. +

+
+
0mode
+
1mode
+
2mode
+
3mode
+

Set matrix mode for each plane. Can be square, row or column. +Default is square. +

+
+ + +

32.41.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.41.2 Examples

+ +
    +
  • Apply sharpen: +
    +
    convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
    +
    + +
  • Apply blur: +
    +
    convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
    +
    + +
  • Apply edge enhance: +
    +
    convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
    +
    + +
  • Apply edge detect: +
    +
    convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"
    +
    + +
  • Apply emboss: +
    +
    convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
    +
    +
+ + +

32.42 convolve

+ +

Apply 2D convolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+ +

The convolve filter also supports the framesync options. +

+ +

32.43 copy

+ +

Copy the input video source unchanged to the output. This is mainly useful for +testing purposes. +

+ +

32.44 coreimage

+

Video filtering on GPU using Apple’s CoreImage API on OSX. +

+

Hardware acceleration is based on an OpenGL context. Usually, this means it is +processed by video hardware. However, software-based OpenGL implementations +exist which means there is no guarantee for hardware processing. It depends on +the respective OSX. +

+

There are many filters and image generators provided by Apple that come with a +large variety of options. The filter has to be referenced by its name along +with its options. +

+

The coreimage filter accepts the following options: +

+
list_filters
+

List all available filters and generators along with all their respective +options as well as possible minimum and maximum values along with the default +values. +

+
list_filters=true
+
+ +
+
filter
+

Specify all filters by their respective name and options. +Use list_filters to determine all valid filter names and options. +Numerical options are specified by a float value and are automatically clamped +to their respective value range. Vector and color options have to be specified +by a list of space separated float values. Character escaping has to be done. +A special option name default is available to use default options for a +filter. +

+

It is required to specify either default or at least one of the filter options. +All omitted options are used with their default values. +The syntax of the filter string is as follows: +

+
filter=<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...][#<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...]][#...]
+
+ +
+
output_rect
+

Specify a rectangle where the output of the filter chain is copied into the +input image. It is given by a list of space separated float values: +

+
output_rect=x\ y\ width\ height
+
+

If not given, the output rectangle equals the dimensions of the input image. +The output rectangle is automatically cropped at the borders of the input +image. Negative values are valid for each component. +

+
output_rect=25\ 25\ 100\ 100
+
+
+
+ +

Several filters can be chained for successive processing without GPU-HOST +transfers allowing for fast processing of complex filter chains. +Currently, only filters with zero (generators) or exactly one (filters) input +image and one output image are supported. Also, transition filters are not yet +usable as intended. +

+

Some filters generate output images with additional padding depending on the +respective filter kernel. The padding is automatically removed to ensure the +filter output has the same size as the input image. +

+

For image generators, the size of the output image is determined by the +previous output image of the filter chain or the input image of the whole +filterchain, respectively. The generators do not use the pixel information of +this image to generate their output. However, the generated output is +blended onto this image, resulting in partial or complete coverage of the +output image. +

+

The coreimagesrc video source can be used for generating input images +which are directly fed into the filter chain. By using it, providing input +images by another video source or an input video is not required. +

+ +

32.44.1 Examples

+ +
    +
  • List all filters available: +
    +
    coreimage=list_filters=true
    +
    + +
  • Use the CIBoxBlur filter with default options to blur an image: +
    +
    coreimage=filter=CIBoxBlur@default
    +
    + +
  • Use a filter chain with CISepiaTone at default values and CIVignetteEffect with +its center at 100x100 and a radius of 50 pixels: +
    +
    coreimage=filter=CIBoxBlur@default#CIVignetteEffect@inputCenter=100\ 100@inputRadius=50
    +
    + +
  • Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +
+ + +

32.45 corr

+ +

Obtain the correlation between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max correlation is printed through +the logging system. +

+

The filter stores the calculated correlation of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi corr -f null -
+
+ + +

32.46 cover_rect

+ +

Cover a rectangular object +

+

It accepts the following options: +

+
+
cover
+

Filepath of the optional cover image, needs to be in yuv420. +

+
+
mode
+

Set covering mode. +

+

It accepts the following values: +

+
‘cover’
+

cover it by the supplied image +

+
‘blur’
+

cover it by interpolating the surrounding pixels +

+
+ +

Default value is blur. +

+
+ + +

32.46.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    +
+ + +

32.47 crop

+ +

Crop the input video to given dimensions. +

+

It accepts the following parameters: +

+
+
w, out_w
+

The width of the output video. It defaults to iw. +This expression is evaluated only once during the filter +configuration, or when the ‘w’ or ‘out_w’ command is sent. +

+
+
h, out_h
+

The height of the output video. It defaults to ih. +This expression is evaluated only once during the filter +configuration, or when the ‘h’ or ‘out_h’ command is sent. +

+
+
x
+

The horizontal position, in the input video, of the left edge of the output +video. It defaults to (in_w-out_w)/2. +This expression is evaluated per-frame. +

+
+
y
+

The vertical position, in the input video, of the top edge of the output video. +It defaults to (in_h-out_h)/2. +This expression is evaluated per-frame. +

+
+
keep_aspect
+

If set to 1 will force the output display aspect ratio +to be the same of the input, by changing the output sample aspect +ratio. It defaults to 0. +

+
+
exact
+

Enable exact cropping. If enabled, subsampled videos will be cropped at exact +width/height/x/y as specified and will not be rounded to nearest smaller value. +It defaults to 0. +

+
+ +

The out_w, out_h, x, y parameters are +expressions containing the following constants: +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
in_w
+
in_h
+

The input width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (cropped) width and height. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

The expression for out_w may depend on the value of out_h, +and the expression for out_h may depend on out_w, but they +cannot depend on x and y, as x and y are +evaluated after out_w and out_h. +

+

The x and y parameters specify the expressions for the +position of the top-left corner of the output (non-cropped) area. They +are evaluated for each frame. If the evaluated value is not valid, it +is approximated to the nearest valid value. +

+

The expression for x may depend on y, and the expression +for y may depend on x. +

+ +

32.47.1 Examples

+ +
    +
  • Crop area with size 100x100 at position (12,34). +
    +
    crop=100:100:12:34
    +
    + +

    Using named options, the example above becomes: +

    +
    crop=w=100:h=100:x=12:y=34
    +
    + +
  • Crop the central input area with size 100x100: +
    +
    crop=100:100
    +
    + +
  • Crop the central input area with size 2/3 of the input video: +
    +
    crop=2/3*in_w:2/3*in_h
    +
    + +
  • Crop the input video central square: +
    +
    crop=out_w=in_h
    +crop=in_h
    +
    + +
  • Delimit the rectangle with the top-left corner placed at position +100:100 and the right-bottom corner corresponding to the right-bottom +corner of the input image. +
    +
    crop=in_w-100:in_h-100:100:100
    +
    + +
  • Crop 10 pixels from the left and right borders, and 20 pixels from +the top and bottom borders +
    +
    crop=in_w-2*10:in_h-2*20
    +
    + +
  • Keep only the bottom right quarter of the input image: +
    +
    crop=in_w/2:in_h/2:in_w/2:in_h/2
    +
    + +
  • Crop height for getting Greek harmony: +
    +
    crop=in_w:1/PHI*in_w
    +
    + +
  • Apply trembling effect: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)
    +
    + +
  • Apply erratic camera effect depending on timestamp: +
    +
    crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)
    +
    + +
  • Set x depending on the value of y: +
    +
    crop=in_w/2:in_h/2:y:10+10*sin(n/10)
    +
    +
+ + +

32.47.2 Commands

+ +

This filter supports the following commands: +

+
w, out_w
+
h, out_h
+
x
+
y
+

Set width/height of the output video and the horizontal/vertical position +in the input video. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+
+ + +

32.48 cropdetect

+ +

Auto-detect the crop size. +

+

It calculates the necessary cropping parameters and prints the +recommended parameters via the logging system. The detected dimensions +correspond to the non-black or video area of the input video according to mode. +

+

It accepts the following parameters: +

+
+
mode
+

Depending on mode crop detection is based on either the mere black value of surrounding pixels or a combination of motion vectors and edge pixels. +

+
+
‘black’
+

Detect black pixels surrounding the playing video. For fine control use option limit. +

+
+
‘mvedges’
+

Detect the playing video by the motion vectors inside the video and scanning for edge pixels typically forming the border of a playing video. +

+
+ +
+
limit
+

Set higher black value threshold, which can be optionally specified +from nothing (0) to everything (255 for 8-bit based formats). An intensity +value greater to the set value is considered non-black. It defaults to 24. +You can also specify a value between 0.0 and 1.0 which will be scaled depending +on the bitdepth of the pixel format. +

+
+
round
+

The value which the width/height should be divisible by. It defaults to +16. The 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. +

+
+
skip
+

Set the number of initial frames for which evaluation is skipped. +Default is 2. Range is 0 to INT_MAX. +

+
+
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. +

+

This can be useful when channel logos distort the video area. 0 +indicates ’never reset’, and returns the largest area encountered during +playback. +

+
+
mv_threshold
+

Set motion in pixel units as threshold for motion detection. It defaults to 8. +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 5/255, and default value for high +is 15/255. +

+
+ + +

32.48.1 Examples

+ +
    +
  • Find video area surrounded by black borders: +
    +
    ffmpeg -i file.mp4 -vf cropdetect,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, generate motion vectors beforehand: +
    +
    ffmpeg -i file.mp4 -vf mestimate,cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    + +
  • Find an embedded video area, use motion vectors from decoder: +
    +
    ffmpeg -flags2 +export_mvs -i file.mp4 -vf cropdetect=mode=mvedges,metadata=mode=print -f null -
    +
    +
+ + +

32.48.2 Commands

+ +

This filter supports the following commands: +

+
+
limit
+

The command accepts the same syntax of the corresponding option. +If the specified expression is not valid, it is kept at its current value. +

+
+ + +

32.49 cue

+ +

Delay video filtering until a given wallclock timestamp. The filter first +passes on preroll amount of frames, then it buffers at most +buffer amount of frames and waits for the cue. After reaching the cue +it forwards the buffered frames and also any subsequent frames coming in its +input. +

+

The filter can be used synchronize the output of multiple ffmpeg processes for +realtime output devices like decklink. By putting the delay in the filtering +chain and pre-buffering frames the process can pass on data to output almost +immediately after the target wallclock timestamp is reached. +

+

Perfect frame accuracy cannot be guaranteed, but the result is good enough for +some use cases. +

+
+
cue
+

The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. +

+
+
preroll
+

The duration of content to pass on as preroll expressed in seconds. Default is 0. +

+
+
buffer
+

The maximum duration of content to buffer before waiting for the cue expressed +in seconds. Default is 0. +

+
+
+ + +

32.50 curves

+ +

Apply color adjustments using curves. +

+

This filter is similar to the Adobe Photoshop and GIMP curves tools. Each +component (red, green and blue) has its values defined by N key points +tied from each other using a smooth curve. The x-axis represents the pixel +values from the input frame, and the y-axis the new pixel values to be set for +the output frame. +

+

By default, a component curve is defined by the two points (0;0) and +(1;1). This creates a straight line where each original pixel value is +"adjusted" to its own value, which means no change to the image. +

+

The filter allows you to redefine these two points and add some more. A new +curve will be defined to pass smoothly through all these new coordinates. The +new defined points need to be strictly increasing over the x-axis, and their +x and y values must be in the [0;1] interval. The curve is +formed by using a natural or monotonic cubic spline interpolation, depending +on the interp option (default: natural). The natural +spline produces a smoother curve in general while the monotonic (pchip) +spline guarantees the transitions between the specified points to be +monotonic. If the computed curves happened to go outside the vector spaces, +the values will be clipped accordingly. +

+

The filter accepts the following options: +

+
+
preset
+

Select one of the available color presets. This option can be used in addition +to the r, g, b parameters; in this case, the later +options takes priority on the preset values. +Available presets are: +

+
‘none’
+
‘color_negative’
+
‘cross_process’
+
‘darker’
+
‘increase_contrast’
+
‘lighter’
+
‘linear_contrast’
+
‘medium_contrast’
+
‘negative’
+
‘strong_contrast’
+
‘vintage’
+
+

Default is none. +

+
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 +r, g, b or all since it acts like a +post-processing LUT. +

+
red, r
+

Set the key points for the red component. +

+
green, g
+

Set the key points for the green component. +

+
blue, b
+

Set the key points for the blue component. +

+
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 +all setting. +

+
psfile
+

Specify a Photoshop curves file (.acv) to import the settings from. +

+
plot
+

Save Gnuplot script of the curves in specified file. +

+
interp
+

Specify the kind of interpolation. Available algorithms are: +

+
‘natural’
+

Natural cubic spline using a piece-wise cubic polynomial that is twice continuously differentiable. +

+
‘pchip’
+

Monotonic cubic spline using a piecewise cubic Hermite interpolating polynomial (PCHIP). +

+
+ +
+
+ +

To avoid some filtergraph syntax conflicts, each key points list need to be +defined using the following syntax: x0/y0 x1/y1 x2/y2 .... +

+ +

32.50.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.50.2 Examples

+ +
    +
  • Increase slightly the middle level of blue: +
    +
    curves=blue='0/0 0.5/0.58 1/1'
    +
    + +
  • Vintage effect: +
    +
    curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'
    +
    +

    Here we obtain the following coordinates for each components: +

    +
    red
    +

    (0;0.11) (0.42;0.51) (1;0.95) +

    +
    green
    +

    (0;0) (0.50;0.48) (1;1) +

    +
    blue
    +

    (0;0.22) (0.49;0.44) (1;0.80) +

    +
    + +
  • The previous example can also be achieved with the associated built-in preset: +
    +
    curves=preset=vintage
    +
    + +
  • Or simply: +
    +
    curves=vintage
    +
    + +
  • Use a Photoshop preset and redefine the points of the green component: +
    +
    curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
    +
    + +
  • Check out the curves of the cross_process profile using ffmpeg +and gnuplot: +
    +
    ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
    +gnuplot -p /tmp/curves.plt
    +
    +
+ + +

32.51 datascope

+ +

Video data analysis filter. +

+

This filter shows hexadecimal pixel values of part of video. +

+

The filter accepts the following options: +

+
+
size, s
+

Set output video size. +

+
+
x
+

Set x offset from where to pick pixels. +

+
+
y
+

Set y offset from where to pick pixels. +

+
+
mode
+

Set scope mode, can be one of the following: +

+
‘mono’
+

Draw hexadecimal pixel values with white color on black background. +

+
+
‘color’
+

Draw hexadecimal pixel values with input video pixel color on black +background. +

+
+
‘color2’
+

Draw hexadecimal pixel values on color background picked from input video, +the text color is picked in such way so its always visible. +

+
+ +
+
axis
+

Draw rows and columns numbers on left and top of video. +

+
+
opacity
+

Set background opacity. +

+
+
format
+

Set display number format. Can be hex, or dec. Default is hex. +

+
+
components
+

Set pixel components to display. By default all pixel components are displayed. +

+
+ + +

32.51.1 Commands

+ +

This filter supports same commands as options excluding size option. +

+ +

32.52 dblur

+

Apply Directional blur filter. +

+

The filter accepts the following options: +

+
+
angle
+

Set angle of directional blur. Default is 45. +

+
+
radius
+

Set radius of directional blur. Default is 5. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+ + +

32.52.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.53 dctdnoiz

+ +

Denoise frames using 2D DCT (frequency domain filtering). +

+

This filter is not designed for real time. +

+

The filter accepts the following options: +

+
+
sigma, s
+

Set the noise sigma constant. +

+

This sigma defines a hard threshold of 3 * sigma; every DCT +coefficient (absolute value) below this threshold with be dropped. +

+

If you need a more advanced filtering, see expr. +

+

Default is 0. +

+
+
overlap
+

Set number overlapping pixels for each block. 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 permit processing the whole input width or +height, a warning will be displayed and according borders won’t be denoised. +

+

Default value is blocksize-1, which is the best possible setting. +

+
+
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 sigma option will be ignored. +

+

The absolute value of the coefficient can be accessed through the c +variable. +

+
+
n
+

Set the blocksize using the number of bits. 1<<n defines the +blocksize, which is the width and height of the processed blocks. +

+

The default value is 3 (8x8) and can be raised to 4 for a +blocksize of 16x16. Note that changing this setting has huge consequences +on the speed processing. Also, a larger block size does not necessarily means a +better de-noising. +

+
+ + +

32.53.1 Examples

+ +

Apply a denoise with a sigma of 4.5: +

+
dctdnoiz=4.5
+
+ +

The same operation can be achieved using the expression system: +

+
dctdnoiz=e='gte(c, 4.5*3)'
+
+ +

Violent denoise using a block size of 16x16: +

+
dctdnoiz=15:n=4
+
+ + +

32.54 deband

+ +

Remove banding artifacts from input video. +It works by replacing banded pixels with average value of referenced pixels. +

+

The filter accepts the following options: +

+
+
1thr
+
2thr
+
3thr
+
4thr
+

Set banding detection threshold for each plane. Default is 0.02. +Valid range is 0.00003 to 0.5. +If difference between current pixel and reference pixel is less than threshold, +it will be considered as banded. +

+
+
range, r
+

Banding detection range in pixels. Default is 16. If positive, random number +in range 0 to set value will be used. If negative, exact absolute value +will be used. +The range defines square of four pixels around current pixel. +

+
+
direction, d
+

Set direction in radians from which four pixel will be compared. If positive, +random direction from 0 to set direction will be picked. If negative, exact of +absolute value will be picked. For example direction 0, -PI or -2*PI radians +will pick only pixels on same row and -PI/2 will pick only pixels on same +column. +

+
+
blur, b
+

If enabled, current pixel is compared with average value of all four +surrounding pixels. The default is enabled. If disabled current pixel is +compared with all four surrounding pixels. The pixel is considered banded +if only all four differences with surrounding pixels are less than threshold. +

+
+
coupling, c
+

If enabled, current pixel is changed if and only if all pixel components are banded, +e.g. banding detection threshold is triggered for all color components. +The default is disabled. +

+
+ + +

32.54.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.55 deblock

+ +

Remove blocking artifacts from input video. +

+

The filter accepts the following options: +

+
+
filter
+

Set filter type, can be weak or strong. Default is strong. +This controls what kind of deblocking is applied. +

+
+
block
+

Set size of block, allowed range is from 4 to 512. Default is 8. +

+
+
alpha
+
beta
+
gamma
+
delta
+

Set blocking detection thresholds. Allowed range is 0 to 1. +Defaults are: 0.098 for alpha and 0.05 for the rest. +Using higher threshold gives more deblocking strength. +Setting alpha controls threshold detection at exact edge of block. +Remaining options controls threshold detection near the edge. Each one for +below/above or left/right. Setting any of those to 0 disables +deblocking. +

+
+
planes
+

Set planes to filter. Default is to filter all available planes. +

+
+ + +

32.55.1 Examples

+ +
    +
  • Deblock using weak filter and block size of 4 pixels. +
    +
    deblock=filter=weak:block=4
    +
    + +
  • Deblock using strong filter, block size of 4 pixels and custom thresholds for +deblocking more edges. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
    +
    + +
  • Similar as above, but filter only first plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
    +
    + +
  • Similar as above, but filter only second and third plane. +
    +
    deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
    +
    +
+ + +

32.55.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.56 decimate

+ +

Drop duplicated frames at regular intervals. +

+

The filter accepts the following options: +

+
+
cycle
+

Set the number of frames from which one will be dropped. Setting this to +N means one frame in every batch of N frames will be dropped. +Default is 5. +

+
+
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 1.1 +

+
+
scthresh
+

Set scene change threshold. Default is 15. +

+
+
blockx
+
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 32. +

+
+
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 +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 +0. +

+
+
chroma
+

Set whether or not chroma is considered in the metric calculations. Default is +1. +

+
+
mixed
+

Set whether or not the input only partially contains content to be decimated. +Default is false. +If enabled video output stream will be in variable frame rate. +

+
+ + +

32.57 deconvolve

+ +

Apply 2D deconvolution of video stream in frequency domain using second stream +as impulse. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
impulse
+

Set which impulse video frames will be processed, can be first +or all. Default is all. +

+
+
noise
+

Set noise when doing divisions. Default is 0.0000001. Useful when width +and height are not same and not power of 2 or if stream prior to convolving +had noise. +

+
+ +

The deconvolve filter also supports the framesync options. +

+ +

32.58 dedot

+ +

Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video. +

+

It accepts the following options: +

+
+
m
+

Set mode of operation. Can be combination of dotcrawl for cross-luminance reduction and/or +rainbows for cross-color reduction. +

+
+
lt
+

Set spatial luma threshold. Lower values increases reduction of cross-luminance. +

+
+
tl
+

Set tolerance for temporal luma. Higher values increases reduction of cross-luminance. +

+
+
tc
+

Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color. +

+
+
ct
+

Set temporal chroma threshold. Lower values increases reduction of cross-color. +

+
+ + +

32.59 deflate

+ +

Apply deflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values lower than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

32.59.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.60 deflicker

+ +

Remove temporal frame luminance variations. +

+

It accepts the following options: +

+
+
size, s
+

Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. +

+
+
mode, m
+

Set averaging mode to smooth temporal luminance variations. +

+

Available values are: +

+
‘am’
+

Arithmetic mean +

+
+
‘gm’
+

Geometric mean +

+
+
‘hm’
+

Harmonic mean +

+
+
‘qm’
+

Quadratic mean +

+
+
‘cm’
+

Cubic mean +

+
+
‘pm’
+

Power mean +

+
+
‘median’
+

Median +

+
+ +
+
bypass
+

Do not actually modify frame. Useful when one only wants metadata. +

+
+ + +

32.61 deinterlace_d3d12

+ +

Deinterlace the input video using D3D12 hardware-accelerated video processing. +

+

This filter uses the DirectX 12 Video Processor to perform deinterlacing on +GPU, supporting both simple bob and driver-defined advanced (motion-adaptive) +algorithms. It requires the input to be in d3d12 hardware pixel format. +

+

The filter automatically queries the hardware for the required number of +temporal reference frames (if needed) and manages a frame queue to supply them. +

+

It accepts the following options: +

+
+
method
+

The deinterlacing method. It accepts one of the following values: +

+
+
‘default’
+

Select the best deinterlacing method available on the hardware. +If the driver supports custom, that method is used; otherwise +falls back to bob. This is the default. +

+
+
‘bob’
+

Bob deinterlacing. Each field is independently scaled to full +frame height. Simple and fast, but may produce visible bob artifacts +on moving content. +

+
+
‘custom’
+

Driver-defined advanced deinterlacing. The exact algorithm is +hardware-specific and typically employs motion-adaptive techniques +with temporal reference frames for higher quality. +

+
+ +

The default value is default. +

+
+
mode
+

Specify the interlacing mode. It accepts one of the following values: +

+
+
‘frame’
+

Send one frame for each frame. The output frame rate equals the input +frame rate. This is the default. +

+
+
‘field’
+

Send one frame for each field. The output frame rate is double the +input frame rate. +

+
+ +

The default value is frame. +

+
+
deint
+

Specify which frames to deinterlace. It accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames. This is the default. +

+
+
‘interlaced’
+

Only deinterlace frames marked as interlaced; progressive frames are +passed through unchanged. +

+
+ +

The default value is all. +

+
+ + +

32.61.1 Examples

+ +
    +
  • Deinterlace an interlaced video using software decoding and the best +available hardware deinterlacing method: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=method=default,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
  • Deinterlace at field rate (double the frame rate) using bob method with +hardware decoding (full d3d12 pipeline): +
    +
    ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.ts \
    +       -vf "deinterlace_d3d12=method=bob:mode=field" \
    +       -c:v h264_d3d12va output.mp4
    +
    + +
  • Deinterlace only interlaced frames, passing progressive frames through: +
    +
    ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
    +       -vf "format=nv12,hwupload,deinterlace_d3d12=deint=interlaced,hwdownload,format=nv12" \
    +       -c:v libx264 -crf 18 output.mp4
    +
    + +
+ + +

32.62 dejudder

+ +

Remove judder produced by partially interlaced telecined content. +

+

Judder can be introduced, for instance, by pullup filter. If the original +source was partially telecined content then the output of pullup,dejudder +will have a variable frame rate. May change the recorded frame rate of the +container. Aside from that change, this filter will not affect constant frame +rate video. +

+

The option available in this filter is: +

+
cycle
+

Specify the length of the window over which the judder repeats. +

+

Accepts any integer greater than 1. Useful values are: +

+
‘4’
+

If the original was telecined from 24 to 30 fps (Film to NTSC). +

+
+
‘5’
+

If the original was telecined from 25 to 30 fps (PAL to NTSC). +

+
+
‘20’
+

If a mixture of the two. +

+
+ +

The default is ‘4’. +

+
+ + +

32.63 delogo

+ +

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). +

+

It accepts the following parameters: +

+
x
+
y
+

Specify the top left corner coordinates of the logo. They must be +specified. +

+
+
w
+
h
+

Specify the width and height of the logo to clear. They must be +specified. +

+
+
show
+

When set to 1, a green rectangle is drawn on the screen to simplify +finding the right x, y, w, and 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. +

+
+
+ + +

32.63.1 Examples

+ +
    +
  • Set a rectangle covering the area with top left corner coordinates 0,0 +and size 100x77: +
    +
    delogo=x=0:y=0:w=100:h=77
    +
    + +
+ + +

32.64 derain

+ +

Remove the rain in the input image/video by applying the derain methods based on +convolutional neural networks. Supported models: +

+ + +

Training as well as model generation scripts are provided in +the repository at https://github.com/XueweiMeng/derain_filter.git. +

+

The filter accepts the following options: +

+
+
filter_type
+

Specify which filter to use. This option accepts the following values: +

+
+
‘derain’
+

Derain filter. To conduct derain filter, you need to use a derain model. +

+
+
‘dehaze’
+

Dehaze filter. To conduct dehaze filter, you need to use a dehaze model. +

+
+

Default value is ‘derain’. +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow can load files for only its format. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

32.65 deshake

+ +

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 the following options: +

+
+
x
+
y
+
w
+
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 +rectangular area of the frame defined by its top left corner, width +and height. These parameters have the same meaning as the drawbox +filter which can be used to visualise the position of the bounding +box. +

+

This is useful when simultaneous movement of subjects within the frame +might be confused for camera motion by the motion vector search. +

+

If any or all of x, y, w and h are set to -1 +then the full frame is used. This allows later options to be set +without specifying the bounding box for the motion vector search. +

+

Default - search the whole frame. +

+
+
rx
+
ry
+

Specify the maximum extent of movement in x and y directions in the +range 0-64 pixels. Default 16. +

+
+
edge
+

Specify how to generate pixels to fill blanks at the edge of the +frame. Available values are: +

+
‘blank, 0’
+

Fill zeroes at blank locations +

+
‘original, 1’
+

Original image at blank locations +

+
‘clamp, 2’
+

Extruded edge value at blank locations +

+
‘mirror, 3’
+

Mirrored edge at blank locations +

+
+

Default value is ‘mirror’. +

+
+
blocksize
+

Specify the blocksize to use for motion search. Range 4-128 pixels, +default 8. +

+
+
contrast
+

Specify the contrast threshold for blocks. Only blocks with more than +the specified contrast (difference between darkest and lightest +pixels) will be considered. Range 1-255, default 125. +

+
+
search
+

Specify the search strategy. Available values are: +

+
‘exhaustive, 0’
+

Set exhaustive search +

+
‘less, 1’
+

Set less exhaustive search. +

+
+

Default value is ‘exhaustive’. +

+
+
filename
+

If set then a detailed log of the motion search is written to the +specified file. +

+
+
+ + +

32.66 despill

+ +

Remove unwanted contamination of foreground colors, caused by reflected color of +greenscreen or bluescreen. +

+

This filter accepts the following options: +

+
+
type
+

Set what type of despill to use. +

+
+
mix
+

Set how spillmap will be generated. +

+
+
expand
+

Set how much to get rid of still remaining spill. +

+
+
red
+

Controls amount of red in spill area. +

+
+
green
+

Controls amount of green in spill area. +Should be -1 for greenscreen. +

+
+
blue
+

Controls amount of blue in spill area. +Should be -1 for bluescreen. +

+
+
brightness
+

Controls brightness of spill area, preserving colors. +

+
+
alpha
+

Modify alpha from generated spillmap. +

+
+ + +

32.66.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.67 detelecine

+ +

Apply an exact inverse of the telecine operation. It requires a predefined +pattern specified using the pattern option which must be the same as that passed +to the telecine filter. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+
start_frame
+

A number representing position of the first frame with respect to the telecine +pattern. This is to be used if the stream is cut. The default value is 0. +

+
+ + +

32.68 dilation

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

32.68.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.69 displace

+ +

Displace pixels as indicated by second and third input stream. +

+

It takes three input streams and outputs one stream, the first input is the +source, and second and third input are displacement maps. +

+

The second input specifies how much to displace pixels along the +x-axis, while the third input specifies how much to displace pixels +along the y-axis. +If one of displacement map streams terminates, last frame from that +displacement map will be used. +

+

Note that once generated, displacements maps can be reused over and over again. +

+

A description of the accepted options follows. +

+
+
edge
+

Set displace behavior for pixels that are out of range. +

+

Available values are: +

+
‘blank’
+

Missing pixels are replaced by black pixels. +

+
+
‘smear’
+

Adjacent pixels will spread out to replace missing pixels. +

+
+
‘wrap’
+

Out of range pixels are wrapped so they point to pixels of other side. +

+
+
‘mirror’
+

Out of range pixels will be replaced with mirrored pixels. +

+
+

Default is ‘smear’. +

+
+
+ + +

32.69.1 Examples

+ +
    +
  • Add ripple effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT
    +
    + +
  • Add wave effect to rgb input of video size hd720: +
    +
    ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT
    +
    +
+ + +

32.70 dnn_classify

+ +

Do classification with deep neural networks based on bounding boxes. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0, +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs for your system. +

+
+
+ + +

32.71 dnn_detect

+ +

Do object detection with deep neural networks. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +only openvino now, tensorflow backends will be added. +

+
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
confidence
+

Set the confidence threshold (default: 0.5). +

+
+
labels
+

Set path to label file specifying the mapping between label id and name. +Each label name is written in one line, tailing spaces and empty lines are skipped. +The first line is the name of label id 0 (usually it is ’background’), +and the second line is the name of label id 1, etc. +The label id is considered as name if the label file is not provided. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+
+
+ + +

32.72 dnn_processing

+ +

Do image processing with deep neural networks. It works together with another filter +which converts the pixel format of the Frame to what the dnn network requires. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+
‘openvino’
+

OpenVINO backend. To enable this backend you +need to build and install the OpenVINO for C library (see +https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md) and configure FFmpeg with +--enable-libopenvino (–extra-cflags=-I... –extra-ldflags=-L... might +be needed if the header files and libraries are not installed into system path) +

+
+
‘torch’
+

Libtorch backend. To enable this backend you need to build and install Libtroch +for C++ library. Please download cxx11 ABI version (see +https://pytorch.org/get-started/locally) +and configure FFmpeg with --enable-libtorch +--extra-cflags=-I/libtorch_root/libtorch/include +--extra-cflags=-I/libtorch_root/libtorch/include/torch/csrc/api/include +--extra-ldflags=-L/libtorch_root/libtorch/lib/ +

+
+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO +and Libtorch backend can load files for only its format. +

+
+
input
+

Set the input name of the dnn network. +

+
+
output
+

Set the output name of the dnn network. +

+
+
backend_configs
+

Set the configs to be passed into backend. To use async execution, set async (default: set). +Roll back to sync execution if the backend does not support async. +

+

For tensorflow backend, you can set its configs with sess_config options, +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +

+
+
+ + +

32.72.1 Examples

+ +
    +
  • Remove rain in rgb24 frame with can.pb (see derain filter): +
    +
    ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
    +
    + +
  • Handle the Y channel with srcnn.pb (see sr filter) for frame with yuv420p (planar YUV formats supported): +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
    +
    + +
  • Handle the Y channel with espcn.pb (see sr filter), which changes frame size, for format yuv420p (planar YUV formats supported), +please use tools/python/tf_sess_config.py to get the configs of TensorFlow backend for your system. +
    +
    ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y:backend_configs=sess_config=0x10022805320e09cdccccccccccec3f20012a01303801 -y tmp.espcn.jpg
    +
    + +
+ + +

32.73 drawbox

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

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 invert is used, the box edge color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With value 1, the pixels of the painted box +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
box_source
+

Box source can be set as side_data_detection_bboxes if you want to use box data in +detection bboxes of side data. +

+

If box_source is set, the x, y, width and height will be ignored and +still use box data in detection bboxes of side data. So please do not use this parameter if you were +not sure about the box source. +

+
+
t
+

The thickness of the drawn box. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

32.73.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + +

32.73.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.74 drawgraph

+

Draw a graph using input video metadata. +

+

It accepts the following parameters: +

+
+
m1
+

Set 1st frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg1
+

Set 1st foreground color expression. +

+
+
m2
+

Set 2nd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg2
+

Set 2nd foreground color expression. +

+
+
m3
+

Set 3rd frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg3
+

Set 3rd foreground color expression. +

+
+
m4
+

Set 4th frame metadata key from which metadata values will be used to draw a graph. +

+
+
fg4
+

Set 4th foreground color expression. +

+
+
min
+

Set minimal value of metadata value. +

+
+
max
+

Set maximal value of metadata value. +

+
+
bg
+

Set graph background color. Default is white. +

+
+
mode
+

Set graph mode. +

+

Available values for mode is: +

+
‘bar’
+
‘dot’
+
‘line’
+
+ +

Default is line. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is frame. +

+
+
size
+

Set size of graph video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +The default value is 900x256. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+

The foreground color expressions can use the following variables: +

+
MIN
+

Minimal value of metadata value. +

+
+
MAX
+

Maximal value of metadata value. +

+
+
VAL
+

Current metadata key value. +

+
+ +

The color is defined as 0xAABBGGRR. +

+
+ +

Example using metadata from signalstats filter: +

+
signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
+
+ +

Example using metadata from ebur128 filter: +

+
ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
+
+ + +

32.75 drawgrid

+ +

Draw a grid on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. +

+
+
width, w
+
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 thickness, so image gets +framed. Default to 0. +

+
+
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 invert is used, the grid color is the same as the +video with inverted luma. +

+
+
thickness, t
+

The expression which sets the thickness of the grid line. Default value is 1. +

+

See below for the list of accepted constants. +

+
+
replace
+

Applicable if the input has alpha. With 1 the pixels of the painted grid +will overwrite the video’s color and alpha pixels. +Default is 0, which composites the grid onto the input, leaving the video’s alpha intact. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
dar
+

The input display aspect ratio, it is the same as (w / h) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_h, ih
+
in_w, iw
+

The input grid cell width and height. +

+
+
sar
+

The input sample aspect ratio. +

+
+
x
+
y
+

The x and y coordinates of some point of grid intersection (meant to configure offset). +

+
+
w
+
h
+

The width and height of the drawn cell. +

+
+
t
+

The thickness of the drawn cell. +

+

These constants allow the x, y, w, h and t expressions to refer to +each other, so you may for example specify y=x/dar or h=w/dar. +

+
+
+ + +

32.75.1 Examples

+ +
    +
  • Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: +
    +
    drawgrid=width=100:height=100:thickness=2:color=red@0.5
    +
    + +
  • Draw a white 3x3 grid with an opacity of 50%: +
    +
    drawgrid=w=iw/3:h=ih/3:t=2:c=white@0.5
    +
    +
+ + +

32.75.2 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.76 drawtext

+ +

Draw a text string or text from a specified file on top of a video, using the +libfreetype library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-libfreetype and --enable-libharfbuzz. +To enable default font fallback and the font option you need to +configure FFmpeg with --enable-libfontconfig. +To enable the text_shaping option, you need to configure FFmpeg with +--enable-libfribidi. +

+ +

32.76.1 Syntax

+ +

It accepts the following parameters: +

+
+
box
+

Used to draw a box around text using the background color. +The value must be either 1 (enable) or 0 (disable). +The default value of box is 0. +

+
+
boxborderw
+

Set the width of the border to be drawn around the box using boxcolor. +The value must be specified using one of the following formats: +

    +
  • boxborderw=10 set the width of all the borders to 10 +
  • boxborderw=10|20 set the width of the top and bottom borders to 10 + and the width of the left and right borders to 20 +
  • boxborderw=10|20|30 set the width of the top border to 10, the width + of the bottom border to 30 and the width of the left and right borders to 20 +
  • boxborderw=10|20|30|40 set the borders width to 10 (top), 20 (right), + 30 (bottom), 40 (left) +
+

The default value of boxborderw is "0". +

+
+
boxcolor
+

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. +

+

The default value of boxcolor is "white". +

+
+
line_spacing
+

Set the line spacing in pixels. The default value of line_spacing is 0. +

+
+
text_align
+

Set the vertical and horizontal alignment of the text with respect to the box boundaries. +The value is combination of flags, one for the vertical alignment (T=top, +M=middle, B=bottom) and one for the horizontal alignment (L=left, C=center, R=right). +Please note that tab characters are only supported with the left horizontal alignment. +

+
+
y_align
+

Specify what the y value is referred to. Possible values are: +

    +
  • text the top of the highest glyph of the first text line is placed at y +
  • baseline the baseline of the first text line is placed at y +
  • font the baseline of the first text line is placed at y plus the + ascent (in pixels) defined in the font metrics +
+

The default value of y_align is "text" for backward compatibility. +

+
+
borderw
+

Set the width of the border to be drawn around the text using bordercolor. +The default value of borderw is 0. +

+
+
bordercolor
+

Set the color to be used for drawing border around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. +

+

The default value of bordercolor is "black". +

+
+
expansion
+

Select how the text is expanded. Can be either none, +strftime (deprecated) or normal (default). See the +Text expansion section below for details. +

+
+
basetime
+

Set a start time for the count. Value is in microseconds. Only applied +in the deprecated strftime expansion mode. To emulate in normal expansion +mode use the pts function, supplying the start time (in seconds) +as the second argument. +

+
+
fix_bounds
+

If true, check and fix text coords to avoid clipping. +

+
+
fontcolor
+

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 fontcolor is "black". +

+
+
fontcolor_expr
+

String which is expanded the same way as text to obtain dynamic +fontcolor value. By default this option has empty value and is not +processed. When this option is set, it overrides fontcolor option. +

+
+
font
+

The font family to be used for drawing text. By default Sans. +

+
+
fontfile
+

The font file to be used for drawing text. The path must be included. +This parameter is mandatory if the fontconfig support is disabled. +

+
+
alpha
+

Draw the text applying alpha blending. The value can +be a number between 0.0 and 1.0. +The expression accepts the same variables x, y as well. +The default value is 1. +Please see fontcolor_expr. +

+
+
fontsize
+

The font size to be used for drawing text. +The default value of fontsize is 16. +

+
+
text_shaping
+

If set to 1, attempt to shape the text (for example, reverse the order of +right-to-left text and join Arabic characters) before drawing it. +Otherwise, just draw the text exactly as given. +By default 1 (if supported). +

+
+
ft_load_flags
+

The flags to be used for loading the fonts. +

+

The flags map the corresponding flags supported by libfreetype, and are +a combination of the following values: +

+
default
+
no_scale
+
no_hinting
+
render
+
no_bitmap
+
vertical_layout
+
force_autohint
+
crop_bitmap
+
pedantic
+
ignore_global_advance_width
+
no_recurse
+
ignore_transform
+
monochrome
+
linear_design
+
no_autohint
+
+ +

Default value is "default". +

+

For more information consult the documentation for the FT_LOAD_* +libfreetype flags. +

+
+
shadowcolor
+

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 shadowcolor is "black". +

+
+
boxw
+

Set the width of the box to be drawn around text. +The default value of boxw is computed automatically to match the text width +

+
+
boxh
+

Set the height of the box to be drawn around text. +The default value of boxh is computed automatically to match the text height +

+
+
shadowx
+
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. The default value for both is "0". +

+
+
start_number
+

The starting frame number for the n/frame_num variable. The default value +is "0". +

+
+
tabsize
+

The size in number of spaces to use for rendering the tab. +Default value is 4. +

+
+
timecode
+

Set the initial timecode representation in "hh:mm:ss[:;.]ff" +format. It can be used with or without text parameter. timecode_rate +option must be specified. +

+
+
timecode_rate, rate, r
+

Set the timecode frame rate (timecode only). Value will be rounded to nearest +integer. Minimum value is "1". +Drop-frame timecode is supported for frame rates 30 & 60. +

+
+
tc24hmax
+

If set to 1, the output of the timecode option will wrap around at 24 hours. +Default is 0 (disabled). +

+
+
text
+

The text string to be drawn. The text must be a sequence of UTF-8 +encoded characters. +This parameter is mandatory if no file is specified with the parameter +textfile. +

+
+
textfile
+

A text file containing text to be drawn. The text must be a sequence +of UTF-8 encoded characters. +

+

This parameter is mandatory if no text string is specified with the +parameter text. +

+

If both text and textfile are specified, an error is thrown. +

+
+
text_source
+

Text source should be set as side_data_detection_bboxes if you want to use text data in +detection bboxes of side data. +

+

If text source is set, text and textfile will be ignored and still use +text data in detection bboxes of side data. So please do not use this parameter +if you are not sure about the text source. +

+
+
reload
+

The textfile will be reloaded at specified frame interval. +Be sure to update textfile atomically, or it may be read partially, +or even fail. +Range is 0 to INT_MAX. Default is 0. +

+
+
x
+
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. +

+

The default value of x and y is "0". +

+

See below for the list of accepted constants and functions. +

+
+ +

The parameters for x and y are expressions containing the +following constants and functions: +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
line_h, lh
+

the height of each text line +

+
+
main_h, h, H
+

the input height +

+
+
main_w, w, W
+

the input width +

+
+
max_glyph_a, ascent
+

the maximum distance from the baseline to the highest/upper grid +coordinate used to place a glyph outline point, for all the rendered +glyphs. +It is a positive value, due to the grid’s orientation with the Y axis +upwards. +

+
+
max_glyph_d, descent
+

the maximum distance from the baseline to the lowest grid coordinate +used to place a glyph outline point, for all the rendered glyphs. +This is a negative value, due to the grid’s orientation, with the Y axis +upwards. +

+
+
max_glyph_h
+

maximum glyph height, that is the maximum height for all the glyphs +contained in the rendered text, it is equivalent to ascent - +descent. +

+
+
max_glyph_w
+

maximum glyph width, that is the maximum width for all the glyphs +contained in the rendered text +

+
+
font_a
+

the ascent size defined in the font metrics +

+
+
font_d
+

the descent size defined in the font metrics +

+
+
top_a
+

the maximum ascender of the glyphs of the first text line +

+
+
bottom_d
+

the maximum descender of the glyphs of the last text line +

+
+
n
+

the number of input frame, starting from 0 +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

The input sample aspect ratio. +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
text_h, th
+

the height of the rendered text +

+
+
text_w, tw
+

the width of the rendered text +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer +to each other, so you can for example specify y=x/dar. +

+
+
pict_type
+

A one character description of the current frame’s picture type. +

+
+
pkt_pos
+

The current packet’s position in the input file or stream +(in bytes, from the start of the input). A value of -1 indicates +this info is not available. +

+
+
duration
+

The current packet’s duration, in seconds. +

+
+
pkt_size
+

The current packet’s size (in bytes). +

+
+ + +

32.76.2 Text expansion

+ +

If expansion is set to strftime, the filter recognizes +sequences accepted by the strftime C function in the provided +text and expands them accordingly. Check the documentation of +strftime. This feature is deprecated in favor of normal +expansion with the gmtime or localtime expansion +functions. +

+

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
expr, e
+

The expression evaluation result. +

+

It must take one argument specifying the expression to be evaluated, +which accepts the same constants and functions as the x and +y values. Note that not all constants should be used, for +example the text size is not known when evaluating the expression, so +the constants text_w and text_h will have an undefined +value. +

+
+
expr_int_format, eif
+

Evaluate the expression’s value and output as formatted integer. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries +starting with TAG included within each frame section +printed by running ffprobe -show_frames. +

+

String metadata generated in filters leading to +the drawtext filter are also available. +

+
+
n, frame_num
+

The frame number, starting from 0. +

+
+
pict_type
+

A one character description of the current picture type. +

+
+
pts
+

The timestamp of the current frame. +It can take up to three arguments. +

+

The first argument is the format of the timestamp; it defaults to flt +for seconds as a decimal number with microsecond accuracy; hms stands +for a formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as +local time zone time. +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to hms, a third argument 24HH may be +supplied to present the hour part of the formatted timestamp in 24h format +(00-23). +

+

If the format is set to localtime or gmtime, a third +argument may be supplied: a strftime C function format string. +By default, YYYY-MM-DD HH:MM:SS format will be used. +

+
+ + +

32.76.3 Commands

+ +

This filter supports altering parameters via commands: +

+
reinit
+

Alter existing filter parameters. +

+

Syntax for the argument is the same as for filter invocation, e.g. +

+
+
fontsize=56:fontcolor=green:text='Hello World'
+
+ +

Full filter invocation with sendcmd would look like this: +

+
+
sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
+
+ +

If the entire argument can’t be parsed or applied as valid values then the filter will +continue with its existing parameters. +

+
+
+ +

The following options are also supported as commands: +

+
    +
  • x +
  • y +
  • alpha +
  • fontsize +
  • fontcolor +
  • boxcolor +
  • bordercolor +
  • shadowcolor +
  • box +
  • boxw +
  • boxh +
  • boxborderw +
  • line_spacing +
  • text_align +
  • shadowx +
  • shadowy +
  • borderw +
+ + +

32.76.4 Examples

+ +
    +
  • Draw "Test Text" with font FreeSerif, using the default values for the +optional parameters. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
    +
    + +
  • Draw ’Test Text’ with font FreeSerif of size 24 at position x=100 +and y=50 (counting from the top-left corner of the screen), text is +yellow with a red box around it. Both the text and the box have an +opacity of 20%. + +
    +
    drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
    +          x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"
    +
    + +

    Note that the double quotes are not necessary if spaces are not used +within the parameter list. +

    +
  • Show the text at the center of the video frame: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
    +
    + +
  • Show the text at a random position, switching to a new position every 30 seconds: +
    +
    drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"
    +
    + +
  • Show a text line sliding from right to left in the last row of the video +frame. The file LONG_LINE is assumed to contain a single line +with no newlines. +
    +
    drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
    +
    + +
  • Show the content of file CREDITS off the bottom of the frame and scroll up. +
    +
    drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
    +
    + +
  • Draw a single green letter "g", at the center of the input video. +The glyph baseline is placed at half screen height. +
    +
    drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
    +
    + +
  • Show text for 1 second every 3 seconds: +
    +
    drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
    +
    + +
  • Use fontconfig to set the font. Note that the colons need to be escaped. +
    +
    drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg'
    +
    + +
  • Draw "Test Text" with font size dependent on height of the video. +
    +
    drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
    +
    + +
  • Print the date of a real-time encoding (see documentation for the +strftime C function): +
    +
    drawtext='fontfile=FreeSans.ttf:text=%{localtime\:%a %b %d %Y}'
    +
    + +
  • Show text fading in and out (appearing/disappearing): +
    +
    #!/bin/sh
    +DS=1.0 # display start
    +DE=10.0 # display end
    +FID=1.5 # fade in duration
    +FOD=5 # fade out duration
    +ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 }"
    +
    + +
  • Horizontally align multiple separate texts. Note that max_glyph_a +and the fontsize value are included in the y offset. +
    +
    drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
    +drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
    +
    + +
  • Plot special lavf.image2dec.source_basename metadata onto each frame if +such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer +must have option -export_path_metadata 1 for the special metadata fields +to be available for filters. +
    +
    drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%{metadata\:lavf.image2dec.source_basename\:NA}':x=10:y=10"
    +
    + +
+ +

For more information about libfreetype, check: +http://www.freetype.org/. +

+

For more information about fontconfig, check: +http://freedesktop.org/software/fontconfig/fontconfig-user.html. +

+

For more information about libfribidi, check: +http://fribidi.org/. +

+

For more information about libharfbuzz, check: +https://github.com/harfbuzz/harfbuzz. +

+ +

32.77 drawvg

+ +

Draw vector graphics on top of video frames, by executing a script written in +a custom language called VGS (Vector Graphics Script). +

+

The documentation for the language can be found in +drawvg - Language Reference. A version of this reference +with rendered examples can be found at the +author’s site. +

+

Graphics are rendered using the cario 2D +graphics library. +

+

To enable compilation of this filter, you need to configure FFmpeg with +--enable-cairo. +

+ +

32.77.1 Parameters

+ +

Either script or file must be set. +

+
+
s, script
+

Script source to draw the graphics. +

+
+
file
+

Path of the file to load the script source. +

+
+
+ + +

32.77.2 Pixel Formats

+ +

Since Cairo only supports RGB images, if the input video is something else (like +YUV 4:2:0), before executing the script the video is converted to a format +compatible with Cairo. Then, you have to use either the format filter, +or the -pix_fmt option, to convert it to the expected format in the +output. +

+ +

32.77.3 Examples

+ +
    +
  • Draw the outline of an ellipse. + +
    +
    ffmpeg -i input.webm \
    +    -vf 'drawvg=ellipse (w/2) (h/2) (w/3) (h/3) stroke' \
    +    -pix_fmt yuv420p \
    +    output.webm
    +
    + +
  • +Draw a square rotating in the middle of the frame. + +

    The script for drawvg is in a file draw.vgs: +

    +
    +
    translate (w/2) (h/2)
    +rotate t
    +rect -100 -100 200 200
    +setcolor red@0.5
    +fill
    +
    + +

    Then: +

    +
    +
    ffmpeg -i input.webm -vf 'drawvg=file=draw.vgs,format=yuv420p' output.webm
    +
    + +
+ + +

32.78 edgedetect

+ +

Detect and draw edges. The filter uses the Canny Edge Detection algorithm. +

+

The filter accepts the following options: +

+
+
low
+
high
+

Set low and high threshold values used by the Canny thresholding +algorithm. +

+

The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. +

+

low and high threshold values must be chosen in the range +[0,1], and low should be lesser or equal to high. +

+

Default value for low is 20/255, and default value for high +is 50/255. +

+
+
mode
+

Define the drawing mode. +

+
+
‘wires’
+

Draw white/gray wires on black background. +

+
+
‘colormix’
+

Mix the colors to create a paint/cartoon effect. +

+
+
‘canny’
+

Apply Canny edge detector on all selected planes. +

+
+

Default value is wires. +

+
+
planes
+

Select planes for filtering. By default all available planes are filtered. +

+
+ + +

32.78.1 Examples

+ +
    +
  • Standard edge detection with custom values for the hysteresis thresholding: +
    +
    edgedetect=low=0.1:high=0.4
    +
    + +
  • Painting effect without thresholding: +
    +
    edgedetect=mode=colormix:high=0
    +
    +
+ + +

32.79 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. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
pal8
+

Set pal8 output pixel format. This option does not work with codebook +length greater than 256. Default is disabled. +

+
+
use_alpha
+

Include alpha values in the quantization calculation. Allows creating +palettized output images (e.g. PNG8) with multiple alpha smooth blending. +

+
+ + +

32.80 entropy

+ +

Measure graylevel entropy in histogram of color channels of video frames. +

+

It accepts the following parameters: +

+
+
mode
+

Can be either normal or diff. Default is normal. +

+

diff mode measures entropy of histogram delta values, absolute differences +between neighbour histogram values. +

+
+ + +

32.81 epx

+

Apply the EPX magnification filter which is designed for pixel art. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xEPX, 3 for +3xEPX. +Default is 3. +

+
+ + +

32.82 eq

+

Set brightness, contrast, saturation and approximate gamma adjustment. +

+

The filter accepts the following options: +

+
+
contrast
+

Set the contrast expression. The value must be a float value in range +-1000.0 to 1000.0. The default value is "1". +

+
+
brightness
+

Set the brightness expression. The value must be a float value in +range -1.0 to 1.0. The default value is "0". +

+
+
saturation
+

Set the saturation expression. The value must be a float in +range 0.0 to 3.0. The default value is "1". +

+
+
gamma
+

Set the gamma expression. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_r
+

Set the gamma expression for red. The value must be a float in +range 0.1 to 10.0. The default value is "1". +

+
+
gamma_g
+

Set the gamma expression for green. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_b
+

Set the gamma expression for blue. The value must be a float in range +0.1 to 10.0. The default value is "1". +

+
+
gamma_weight
+

Set the gamma weight expression. It can be used to reduce the effect +of a high gamma value on bright image areas, e.g. keep them from +getting overamplified and just plain white. The value must be a float +in range 0.0 to 1.0. A value of 0.0 turns the +gamma correction all the way down while 1.0 leaves it at its +full strength. Default is "1". +

+
+
eval
+

Set when the expressions for brightness, contrast, saturation and +gamma expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ +

The expressions accept the following parameters: +

+
n
+

frame count of the input frame starting from 0 +

+
+
pos
+

byte position of the corresponding packet in the input file, NAN if +unspecified; deprecated, do not use +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+ + +

32.82.1 Commands

+

The filter supports the following commands: +

+
+
contrast
+

Set the contrast expression. +

+
+
brightness
+

Set the brightness expression. +

+
+
saturation
+

Set the saturation expression. +

+
+
gamma
+

Set the gamma expression. +

+
+
gamma_r
+

Set the gamma_r expression. +

+
+
gamma_g
+

Set gamma_g expression. +

+
+
gamma_b
+

Set gamma_b expression. +

+
+
gamma_weight
+

Set gamma_weight 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. +

+
+
+ + +

32.83 erosion

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. Default is 255 i.e. all eight +pixels are used. +

+

Flags to local 3x3 coordinates maps like this: +

+

1 2 3 + 4 5 + 6 7 8 +

+
+ + +

32.83.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.84 estdif

+ +

Deinterlace the input video ("estdif" stands for "Edge Slope +Tracing Deinterlacing Filter"). +

+

Spatial only filter that uses edge slope tracing algorithm +to interpolate missing lines. +It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
all
+

Deinterlace all frames. +

+
interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+
rslope
+

Specify the search radius for edge slope tracing. Default value is 1. +Allowed range is from 1 to 15. +

+
+
redge
+

Specify the search radius for best edge matching. Default value is 2. +Allowed range is from 0 to 15. +

+
+
ecost
+

Specify the edge cost for edge matching. Default value is 2. +Allowed range is from 0 to 50. +

+
+
mcost
+

Specify the middle cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
dcost
+

Specify the distance cost for edge matching. Default value is 1. +Allowed range is from 0 to 50. +

+
+
interp
+

Specify the interpolation used. Default is 4-point interpolation. It accepts one +of the following values: +

+
+
2p
+

Two-point interpolation. +

+
4p
+

Four-point interpolation. +

+
6p
+

Six-point interpolation. +

+
+
+
+ + +

32.84.1 Commands

+

This filter supports same commands as options. +

+ +

32.85 exposure

+

Adjust exposure of the video stream. +

+

The filter accepts the following options: +

+
+
exposure
+

Set the exposure correction in EV. Allowed range is from -3.0 to 3.0 EV +Default value is 0 EV. +

+
+
black
+

Set the black level correction. Allowed range is from -1.0 to 1.0. +Default value is 0. +

+
+ + +

32.85.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.86 extractplanes

+ +

Extract color channel components from input video stream into +separate grayscale video streams. +

+

The filter accepts the following option: +

+
+
planes
+

Set plane(s) to extract. +

+

Available values for planes are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +

Choosing planes not available in the input will result in an error. +That means you cannot select r, g, b planes +with y, u, v planes at same time. +

+
+ + +

32.86.1 Examples

+ +
    +
  • Extract luma, u and v color channel component from input video frame +into 3 grayscale outputs: +
    +
    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
    +
    +
+ + +

32.87 fade

+ +

Apply a fade-in/out effect to the input video. +

+

It accepts the following parameters: +

+
+
type, t
+

The effect type can be either "in" for a fade-in, or "out" for a fade-out +effect. +Default is in. +

+
+
start_frame, s
+

Specify the number of the frame to start applying the fade +effect at. Default is 0. +

+
+
nb_frames, n
+

The number of frames that the fade effect lasts. 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 color. +Default is 25. +

+
+
alpha
+

If set to 1, fade only alpha channel, if one exists on the input. +Default value is 0. +

+
+
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. +

+
+
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 color. +If both duration and nb_frames are specified, duration is used. Default is 0 +(nb_frames is used by default). +

+
+
color, c
+

Specify the color of the fade. Default is "black". +

+
+ + +

32.87.1 Examples

+ +
    +
  • Fade in the first 30 frames of video: +
    +
    fade=in:0:30
    +
    + +

    The command above is equivalent to: +

    +
    fade=t=in:s=0:n=30
    +
    + +
  • Fade out the last 45 frames of a 200-frame video: +
    +
    fade=out:155:45
    +fade=type=out:start_frame=155:nb_frames=45
    +
    + +
  • Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: +
    +
    fade=in:0:25, fade=out:975:25
    +
    + +
  • Make the first 5 frames yellow, then fade in from frame 5-24: +
    +
    fade=in:5:20:color=yellow
    +
    + +
  • Fade in alpha over first 25 frames of video: +
    +
    fade=in:0:25:alpha=1
    +
    + +
  • Make the first 5.5 seconds black, then fade in for 0.5 seconds: +
    +
    fade=t=in:st=5.5:d=0.5
    +
    + +
+ + +

32.88 feedback

+

Apply feedback video filter. +

+

This filter pass cropped input frames to 2nd output. +From there it can be filtered with other video filters. +After filter receives frame from 2nd input, that frame +is combined on top of original frame from 1st input and passed +to 1st output. +

+

The typical usage is filter only part of frame. +

+

The filter accepts the following options: +

+
x
+
y
+

Set the top left crop position. +

+
+
w
+
h
+

Set the crop size. +

+
+ + +

32.88.1 Examples

+ +
    +
  • Blur only top left rectangular part of video frame size 100x100 with gblur filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]gblur=8[blurin]
    +
    + +
  • Draw black box on top left part of video frame of size 100x100 with drawbox filter. +
    +
    [in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]drawbox=x=0:y=0:w=100:h=100:t=100[blurin]
    +
    + +
  • Pixelize rectangular part of video frame of size 100x100 with pixelize filter. +
    +
    [in][blurin]feedback=x=320:y=240:w=100:h=100[out][blurout];[blurout]pixelize[blurin]
    +
    +
+ + +

32.89 fftdnoiz

+

Denoise frames using 3D FFT (frequency domain filtering). +

+

The filter accepts the following options: +

+
+
sigma
+

Set the noise sigma constant. This sets denoising strength. +Default value is 1. Allowed range is from 0 to 30. +Using very high sigma with low overlap may give blocking artifacts. +

+
+
amount
+

Set amount of denoising. By default all detected noise is reduced. +Default value is 1. Allowed range is from 0 to 1. +

+
+
block
+

Set size of block in pixels, Default is 32, can be 8 to 256. +

+
+
overlap
+

Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. +

+
+
method
+

Set denoising method. Default is wiener, can also be hard. +

+
+
prev
+

Set number of previous frames to use for denoising. By default is set to 0. +

+
+
next
+

Set number of next frames to to use for denoising. By default is set to 0. +

+
+
planes
+

Set planes which will be filtered, by default are all available filtered +except alpha. +

+
+ + +

32.90 fftfilt

+

Apply arbitrary expressions to samples in frequency domain +

+
+
dc_Y
+

Adjust the dc value (gain) of the luma plane of the image. The filter +accepts an integer value in range 0 to 1000. The default +value is set to 0. +

+
+
dc_U
+

Adjust the dc value (gain) of the 1st chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
dc_V
+

Adjust the dc value (gain) of the 2nd chroma plane of the image. The +filter accepts an integer value in range 0 to 1000. The +default value is set to 0. +

+
+
weight_Y
+

Set the frequency domain weight expression for the luma plane. +

+
+
weight_U
+

Set the frequency domain weight expression for the 1st chroma plane. +

+
+
weight_V
+

Set the frequency domain weight expression for the 2nd chroma plane. +

+
+
eval
+

Set when the expressions are evaluated. +

+

It accepts the following values: +

+
‘init’
+

Only evaluate expressions once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+ +

Default value is ‘init’. +

+

The filter accepts the following variables: +

+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
N
+

The number of input frame, starting from 0. +

+
+
WS
+
HS
+

The size of FFT array for horizontal and vertical processing. +

+
+ + +

32.90.1 Examples

+ +
    +
  • High-pass: +
    +
    fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
    +
    + +
  • Low-pass: +
    +
    fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
    +
    + +
  • Sharpen: +
    +
    fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
    +
    + +
  • Blur: +
    +
    fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
    +
    + +
+ + +

32.91 field

+ +

Extract a single field from an interlaced image using stride +arithmetic to avoid wasting CPU time. The output frames are marked as +non-interlaced. +

+

The filter accepts the following options: +

+
+
type
+

Specify whether to extract the top (if the value is 0 or +top) or the bottom field (if the value is 1 or +bottom). +

+
+ + +

32.92 fieldhint

+ +

Create new frames by copying the top and bottom fields from surrounding frames +supplied as numbers by the hint file. +

+
+
hint
+

Set file containing hints: absolute/relative frame numbers. +

+

There must be one line for each frame in a clip. Each line must contain two +numbers separated by the comma, optionally followed by - or +. +Numbers supplied on each line of file can not be out of [N-1,N+1] where N +is current frame number for absolute mode or out of [-1, 1] range +for relative mode. First number tells from which frame to pick up top +field and second number tells from which frame to pick up bottom field. +

+

If optionally followed by + output frame will be marked as interlaced, +else if followed by - output frame will be marked as progressive, else +it will be marked same as input frame. +If optionally followed by t output frame will use only top field, or in +case of b it will use only bottom field. +If line starts with # or ; that line is skipped. +

+
+
mode
+

Can be item absolute or relative or pattern. Default is absolute. +The pattern mode is same as relative mode, except at last entry of file if there +are more frames to process than hint file is seek back to start. +

+
+ +

Example of first several lines of hint file for relative mode: +

+
0,0 - # first frame
+1,0 - # second frame, use third's frame top field and second's frame bottom field
+1,0 - # third frame, use fourth's frame top field and third's frame bottom field
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+0,0 -
+1,0 -
+1,0 -
+1,0 -
+0,0 -
+
+ + +

32.93 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 fieldmatch needs to be +followed by a decimation filter such as 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, +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 yadif before decimation. +

+

In addition to the various configuration options, fieldmatch can take an +optional second stream, activated through the 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 fieldmatch is based on. While the semantic and usage are very +close, some behaviour and options names can differ. +

+

The decimate filter currently only works for constant frame rate input. +If your input has mixed telecined (30fps) and progressive content with a lower +framerate like 24fps use the following filterchain to produce the necessary cfr +stream: dejudder,fps=30000/1001,fieldmatch,decimate. +

+

The filter accepts the following options: +

+
+
order
+

Specify the assumed field order of the input stream. Available values are: +

+
+
‘auto’
+

Auto detect parity (use FFmpeg’s internal parity value). +

+
‘bff’
+

Assume bottom field first. +

+
‘tff’
+

Assume top field first. +

+
+ +

Note that it is sometimes recommended not to trust the parity announced by the +stream. +

+

Default value is auto. +

+
+
mode
+

Set the matching mode or strategy to use. 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, 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 pc and 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 p/c/n/u/b meaning section. +

+

Available values are: +

+
+
‘pc’
+

2-way matching (p/c) +

+
‘pc_n’
+

2-way matching, and trying 3rd match if still combed (p/c + n) +

+
‘pc_u’
+

2-way matching, and trying 3rd match (same order) if still combed (p/c + u) +

+
‘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) +

+
‘pcn’
+

3-way matching (p/c/n) +

+
‘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) +

+
+ +

The parenthesis at the end indicate the matches that would be used for that +mode assuming order=tff (and field on auto or +top). +

+

In terms of speed pc mode is by far the fastest and pcn_ub is +the slowest. +

+

Default value is pc_n. +

+
+
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 clip2 feature from +VFM/TFM. +

+

Default value is 0 (disabled). +

+
+
field
+

Set the field to match from. It is recommended to set this to the same value as +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: +

+
+
‘auto’
+

Automatic (same value as order). +

+
‘bottom’
+

Match from the bottom field. +

+
‘top’
+

Match from the top field. +

+
+ +

Default value is auto. +

+
+
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 0 +only if your clip has bad chroma problems such as heavy rainbowing or other +artifacts. Setting this to 0 could also be used to speed things up at +the cost of some accuracy. +

+

Default value is 1. +

+
+
y0
+
y1
+

These define an exclusion band which excludes the lines between y0 and +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. y0 sets the starting scan line and +y1 sets the ending line; all lines in between y0 and +y1 (including y0 and y1) will be ignored. Setting +y0 and y1 to the same value will disable the feature. +y0 and y1 defaults to 0. +

+
+
scthresh
+

Set the scene change detection threshold as a percentage of maximum change on +the luma plane. Good values are in the [8.0, 14.0] range. Scene change +detection is only relevant in case combmatch=sc. The range for +scthresh is [0.0, 100.0]. +

+

Default value is 12.0. +

+
+
combmatch
+

When combatch is not none, fieldmatch will take into +account the combed scores of matches when deciding what match to use as the +final match. Available values are: +

+
+
‘none’
+

No final matching based on combed scores. +

+
‘sc’
+

Combed scores are only used when a scene change is detected. +

+
‘full’
+

Use combed scores all the time. +

+
+ +

Default is sc. +

+
+
combdbg
+

Force fieldmatch to calculate the combed metrics for certain matches and +print them. This setting is known as micout in TFM/VFM vocabulary. +Available values are: +

+
+
‘none’
+

No forced calculation. +

+
‘pcn’
+

Force p/c/n calculations. +

+
‘pcnub’
+

Force p/c/n/u/b calculations. +

+
+ +

Default value is none. +

+
+
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 +-1 (every pixel will be detected as combed) to 255 (no pixel will +be detected as combed). This is basically a pixel difference value. A good +range is [8, 12]. +

+

Default value is 9. +

+
+
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 chroma=0 is usually more reliable, except for the case +where there is chroma only combing in the source. +

+

Default value is 0. +

+
+
blockx
+
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 +combpel pixels are required to be detected as combed for a frame to be +declared combed. See the 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 16. +

+
+
combpel
+

The number of combed pixels inside any of the blocky by +blockx size blocks on the frame for the frame to be detected as +combed. While 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 blockx and blocky settings) on the +frame. Minimum value is 0 and maximum is blocky x blockx (at +which point no frames will ever be detected as combed). This setting is known +as MI in TFM/VFM vocabulary. +

+

Default value is 80. +

+
+ + +

32.93.1 p/c/n/u/b meaning

+ + +

32.93.1.1 p/c/n

+ +

We assume the following telecined stream: +

+
+
Top fields:     1 2 2 3 4
+Bottom fields:  1 2 3 4 4
+
+ +

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 fieldmatch is configured to run a matching from bottom +(field=bottom) this is how this input stream get transformed: +

+
+
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
+
+ +

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 decimate filter. +

+

The same operation now matching from top fields (field=top) +looks like this: +

+
+
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
+
+ +

In these examples, we can see what p, c and n mean; +basically, they refer to the frame and field of the opposite parity: +

+
    +
  • p matches the field of the opposite parity in the previous frame +
  • c matches the field of the opposite parity in the current frame +
  • n matches the field of the opposite parity in the next frame +
+ + +

32.93.1.2 u/b

+ +

The u and 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 (field=bottom): +

+
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
+
+ +

With top matching (field=top): +

+
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
+
+ + +

32.93.2 Examples

+ +

Simple IVTC of a top field first telecined stream: +

+
fieldmatch=order=tff:combmatch=none, decimate
+
+ +

Advanced IVTC, with fallback on yadif for still combed frames: +

+
fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
+
+ + +

32.94 fieldorder

+ +

Transform the field order of the input video. +

+

It accepts the following parameters: +

+
+
order
+

The output field order. Valid values are tff for top field first or bff +for bottom field first. +

+
+ +

The default value is ‘tff’. +

+

The transformation is done by shifting the picture content up or down +by one line, and filling the remaining line with appropriate picture content. +This method is consistent with most broadcast field order converters. +

+

If the input video is not flagged as being interlaced, or it is already +flagged as being of the required output field order, then this filter does +not alter the incoming video. +

+

It is very useful when converting to or from PAL DV material, +which is bottom field first. +

+

For example: +

+
ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
+
+ + +

32.95 fillborders

+ +

Fill borders of the input video, without changing video stream dimensions. +Sometimes video can have garbage at the four edges and you may not want to +crop video input to keep size multiple of some number. +

+

This filter accepts the following options: +

+
+
left
+

Number of pixels to fill from left border. +

+
+
right
+

Number of pixels to fill from right border. +

+
+
top
+

Number of pixels to fill from top border. +

+
+
bottom
+

Number of pixels to fill from bottom border. +

+
+
mode
+

Set fill mode. +

+

It accepts the following values: +

+
‘smear’
+

fill pixels using outermost pixels +

+
+
‘mirror’
+

fill pixels using mirroring (half sample symmetric) +

+
+
‘fixed’
+

fill pixels with constant value +

+
+
‘reflect’
+

fill pixels using reflecting (whole sample symmetric) +

+
+
‘wrap’
+

fill pixels using wrapping +

+
+
‘fade’
+

fade pixels to constant value +

+
+
‘margins’
+

fill pixels at top and bottom with weighted averages pixels near borders +

+
+ +

Default is smear. +

+
+
color
+

Set color for pixels in fixed or fade mode. Default is black. +

+
+ + +

32.95.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.96 find_rect

+ +

Find a rectangular object in the input video. +

+

The object to search for must be specified as a gray8 image specified with the +object option. +

+

For each possible match, a score is computed. If the score reaches the specified +threshold, the object is considered found. +

+

If the input video contains multiple instances of the object, the filter will +find only one of them. +

+

When an object is found, the following metadata entries are set in the matching +frame: +

+
lavfi.rect.w
+

width of object +

+
+
lavfi.rect.h
+

height of object +

+
+
lavfi.rect.x
+

x position of object +

+
+
lavfi.rect.y
+

y position of object +

+
+
lavfi.rect.score
+

match score of the found object +

+
+ +

It accepts the following options: +

+
+
object
+

Filepath of the object image, needs to be in gray8. +

+
+
threshold
+

Detection threshold, expressed as a decimal number in the range 0-1. +

+

A threshold value of 0.01 means only exact matches, a threshold of 0.99 means +almost everything matches. +

+

Default value is 0.5. +

+
+
mipmaps
+

Number of mipmaps, default is 3. +

+
+
xmin, ymin, xmax, ymax
+

Specifies the rectangle in which to search. +

+
+
discard
+

Discard frames where object is not detected. Default is disabled. +

+
+ + +

32.96.1 Examples

+ +
    +
  • Cover a rectangular object by the supplied image of a given video using ffmpeg: +
    +
    ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
    +
    + +
  • Find the position of an object in each frame using ffprobe and write +it to a log file: +
    +
    ffprobe -f lavfi movie=test.mp4,find_rect=object=object.pgm:threshold=0.3 \
    +  -show_entries frame=pkt_pts_time:frame_tags=lavfi.rect.x,lavfi.rect.y \
    +  -of csv -o find_rect.csv
    +
    + +
+ + +

32.97 floodfill

+ +

Flood area with values of same pixel components with another values. +

+

It accepts the following options: +

+
x
+

Set pixel x coordinate. +

+
+
y
+

Set pixel y coordinate. +

+
+
s0
+

Set source #0 component value. +

+
+
s1
+

Set source #1 component value. +

+
+
s2
+

Set source #2 component value. +

+
+
s3
+

Set source #3 component value. +

+
+
d0
+

Set destination #0 component value. +

+
+
d1
+

Set destination #1 component value. +

+
+
d2
+

Set destination #2 component value. +

+
+
d3
+

Set destination #3 component value. +

+
+ + +

32.98 format

+ +

Convert the input video to one of the specified pixel formats. +Libavfilter will try to pick one that is suitable as input to +the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +"pix_fmts=yuv420p|monow|rgb24". +

+
+
color_spaces
+

A ’|’-separated list of color space names, such as +"color_spaces=bt709|bt470bg|bt2020nc". +

+
+
color_ranges
+

A ’|’-separated list of color range names, such as +"color_ranges=tv|pc". +

+
+
alpha_modes
+

A ’|’-separated list of color range names, such as +"alpha_modes=straight|premultiplied". +

+
+
+ + +

32.98.1 Examples

+ +
    +
  • Convert the input video to the yuv420p format +
    +
    format=pix_fmts=yuv420p
    +
    + +

    Convert the input video to any of the formats in the list +

    +
    format=pix_fmts=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

32.99 fps

+ +

Convert the video to specified constant frame rate by duplicating or dropping +frames as necessary. +

+

It accepts the following parameters: +

+
fps
+

The desired output frame rate. It accepts expressions containing the following +constants: +

+
+
‘source_fps’
+

The input’s frame rate +

+
+
‘ntsc’
+

NTSC frame rate of 30000/1001 +

+
+
‘pal’
+

PAL frame rate of 25.0 +

+
+
‘film’
+

Film frame rate of 24.0 +

+
+
‘ntsc_film’
+

NTSC-film frame rate of 24000/1001 +

+
+ +

The default is 25. +

+
+
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. +

+
+
round
+

Timestamp (PTS) rounding method. +

+

Possible values are: +

+
zero
+

round towards 0 +

+
inf
+

round away from 0 +

+
down
+

round towards -infinity +

+
up
+

round towards +infinity +

+
near
+

round to nearest +

+
+

The default is near. +

+
+
eof_action
+

Action performed when reading the last frame. +

+

Possible values are: +

+
round
+

Use same timestamp rounding method as used for other frames. +

+
pass
+

Pass through last frame if input duration has not been reached yet. +

+
+

The default is round. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +fps[:start_time[:round]]. +

+

See also the setpts filter. +

+ +

32.99.1 Examples

+ +
    +
  • A typical usage in order to set the fps to 25: +
    +
    fps=fps=25
    +
    + +
  • Sets the fps to 24, using abbreviation and rounding method to round to nearest: +
    +
    fps=fps=film:round=near
    +
    +
+ + +

32.100 framepack

+ +

Pack two different video streams into a stereoscopic video, setting proper +metadata on supported codecs. The two views should have the same size and +framerate and processing will stop when the shorter video ends. Please note +that you may conveniently adjust view properties with the scale and +fps filters. +

+

It accepts the following parameters: +

+
format
+

The desired packing format. Supported values are: +

+
+
sbs
+

The views are next to each other (default). +

+
+
tab
+

The views are on top of each other. +

+
+
lines
+

The views are packed by line. +

+
+
columns
+

The views are packed by column. +

+
+
frameseq
+

The views are temporally interleaved. +

+
+
+ +
+
+ +

Some examples: +

+
+
# Convert left and right views into a frame-sequential video
+ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
+
+# Convert views into a side-by-side video with the same output resolution as the input
+ffmpeg -i LEFT -i RIGHT -filter_complex [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/2[right],[left][right]framepack=sbs OUTPUT
+
+ + +

32.101 framerate

+ +

Change the frame rate by interpolating new video output frames from the source +frames. +

+

This filter is not designed to function correctly with interlaced media. If +you wish to change the frame rate of interlaced media then you are required +to deinterlace before this filter and re-interlace after this filter. +

+

A description of the accepted options follows. +

+
+
fps
+

Specify the output frames per second. This option can also be specified +as a value alone. The default is 50. +

+
+
interp_start
+

Specify the start of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 15. +

+
+
interp_end
+

Specify the end of a range where the output frame will be created as a +linear interpolation of two frames. The range is [0-255], +the default is 240. +

+
+
scene
+

Specify the level at which a scene change is detected as a value between +0 and 100 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one. +The default is 8.2. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
scene_change_detect, scd
+

Enable scene change detection using the value of the option scene. +This flag is enabled by default. +

+
+
+
+ + +

32.102 framestep

+ +

Select one frame every N-th frame. +

+

This filter accepts the following option: +

+
step
+

Select frame after every step frames. +Allowed values are positive integers higher than 0. Default value is 1. +

+
+ + +

32.103 freezedetect

+ +

Detect frozen video. +

+

This filter logs a message and sets frame metadata when it detects that the +input video has no significant change in content during a specified duration. +Video freeze detection calculates the mean average absolute difference of all +the components of video frames and compares it to a noise floor. +

+

The printed times and duration are expressed in seconds. The +lavfi.freezedetect.freeze_start metadata key is set on the first frame +whose timestamp equals or exceeds the detection duration and it contains the +timestamp of the first frame of the freeze. The +lavfi.freezedetect.freeze_duration and +lavfi.freezedetect.freeze_end metadata keys are set on the first frame +after the freeze. +

+

The filter accepts the following options: +

+
+
noise, n
+

Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or as a difference ratio between 0 and 1. Default is -60dB, or +0.001. +

+
+
duration, d
+

Set freeze duration until notification (default is 2 seconds). +

+
+ + +

32.104 freezeframes

+ +

Freeze video frames. +

+

This filter freezes video frames using frame from 2nd input. +

+

The filter accepts the following options: +

+
+
first
+

Set number of first frame from which to start freeze. +

+
+
last
+

Set number of last frame from which to end freeze. +

+
+
replace
+

Set number of frame from 2nd input which will be used instead of replaced frames. +

+
+ + +

32.105 frei0r

+ +

Apply a frei0r effect to the input video. +

+

To enable the compilation of this filter, you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the frei0r effect to load. If the environment variable +FREI0R_PATH is defined, the frei0r effect is searched for in each of the +directories specified by the colon-separated list in FREI0R_PATH. +Otherwise, the standard frei0r paths are searched, in this order: +HOME/.frei0r-1/lib/, /usr/local/lib/frei0r-1/, +/usr/lib/frei0r-1/. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r effect. +

+
+
+ +

A frei0r effect parameter can be a boolean (its value is either +"y" or "n"), a double, a color (specified as +R/G/B, where R, G, and B are floating point +numbers between 0.0 and 1.0, inclusive) or a color description as specified in the +"Color" section in the ffmpeg-utils manual, +a position (specified as X/Y, where +X and Y are floating point numbers) and/or a string. +

+

The number and types of parameters depend on the loaded effect. If an +effect parameter is not specified, the default value is set. +

+ +

32.105.1 Examples

+ +
    +
  • Apply the distort0r effect, setting the first two double parameters: +
    +
    frei0r=filter_name=distort0r:filter_params=0.5|0.01
    +
    + +
  • Apply the colordistance effect, taking a color as the first parameter: +
    +
    frei0r=colordistance:0.2/0.3/0.4
    +frei0r=colordistance:violet
    +frei0r=colordistance:0x112233
    +
    + +
  • Apply the perspective effect, specifying the top left and top right image +positions: +
    +
    frei0r=perspective:0.2/0.2|0.8/0.2
    +
    +
+ +

For more information, see +http://frei0r.dyne.org +

+ +

32.105.2 Commands

+ +

This filter supports the filter_params option as commands. +

+ +

32.106 fspp

+ +

Apply fast and simple postprocessing. It is a faster version of spp. +

+

It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- +processing filter, one of them is performed once per block, not per pixel. +This allows for much higher speed. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 4-5. Default value is 4. +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range 0-63. +If not set, the filter will use the QP from the video stream (if available). +

+
+
strength
+

Set filter strength. It accepts an integer in range -15 to 32. Lower values mean +more details but also more artifacts, while higher values make the image smoother +but also blurrier. Default value is 0 − PSNR optimal. +

+
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+
+ + +

32.107 fsync

+ +

Synchronize video frames with an external mapping from a file. +

+

For each input PTS given in the map file it either drops or creates as many +frames as necessary to recreate the sequence of output frames given in the +map file. +

+

This filter is useful to recreate the output frames of a framerate conversion +by the fps filter, recorded into a map file using the ffmpeg option +-stats_mux_pre, and do further processing to the corresponding frames +e.g. quality comparison. +

+

Each line of the map file must contain three items per input frame, the input +PTS (decimal), the output PTS (decimal) and the +output TIMEBASE (decimal/decimal), separated by a space. +This file format corresponds to the output +of -stats_mux_pre_fmt="{ptsi} {pts} {tb}". +

+

The filter assumes the map file is sorted by increasing input PTS. +

+

The filter accepts the following options: +

+
file, f
+

The filename of the map file to be used. +

+
+ +

Example: +

+
# Convert a video to 25 fps and record a MAP_FILE file with the default format of this filter
+ffmpeg -i INPUT -vf fps=fps=25 -stats_mux_pre MAP_FILE -stats_mux_pre_fmt "{ptsi} {pts} {tb}" OUTPUT
+
+# Sort MAP_FILE by increasing input PTS
+sort -n MAP_FILE
+
+# Use INPUT, OUTPUT and the MAP_FILE from above to compare the corresponding frames in INPUT and OUTPUT via SSIM
+ffmpeg -i INPUT -i OUTPUT -filter_complex '[0:v]fsync=file=MAP_FILE[ref];[1:v][ref]ssim' -f null -
+
+ + +

32.108 gblur

+ +

Apply Gaussian blur filter. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
steps
+

Set number of steps for Gaussian approximation. Default is 1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+ + +

32.108.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.109 geq

+ +

Apply generic equation to each pixel. +

+

The filter accepts the following options: +

+
+
lum_expr, lum
+

Set the luma expression. +

+
cb_expr, cb
+

Set the chrominance blue expression. +

+
cr_expr, cr
+

Set the chrominance red expression. +

+
alpha_expr, a
+

Set the alpha expression. +

+
red_expr, r
+

Set the red expression. +

+
green_expr, g
+

Set the green expression. +

+
blue_expr, b
+

Set the blue expression. +

+
+ +

The colorspace is selected according to the specified options. If one +of the lum_expr, cb_expr, or cr_expr +options is specified, the filter will automatically select a YCbCr +colorspace. If one of the red_expr, green_expr, or +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 +to the luma expression. +

+

The expressions can use the following variables and functions: +

+
+
N
+

The sequential number of the filtered frame, starting from 0. +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
SW
+
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 1,1 for the luma plane, and +0.5,0.5 for chroma planes. +

+
+
T
+

Time of the current frame, expressed in seconds. +

+
+
p(x, y)
+

Return the value of the pixel at location (x,y) of the current +plane. +

+
+
lum(x, y)
+

Return the value of the pixel at location (x,y) of the luma +plane. +

+
+
cb(x, y)
+

Return the value of the pixel at location (x,y) of the +blue-difference chroma plane. Return 0 if there is no such plane. +

+
+
cr(x, y)
+

Return the value of the pixel at location (x,y) of the +red-difference chroma plane. Return 0 if there is no such plane. +

+
+
r(x, y)
+
g(x, y)
+
b(x, y)
+

Return the value of the pixel at location (x,y) of the +red/green/blue component. Return 0 if there is no such component. +

+
+
alpha(x, y)
+

Return the value of the pixel at location (x,y) of the alpha +plane. Return 0 if there is no such plane. +

+
+
psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
+

Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining +sums of samples within a rectangle. See the functions without the sum postfix. +

+
+
interpolation
+

Set one of interpolation methods: +

+
nearest, n
+
bilinear, b
+
+

Default is bilinear. +

+
+ +

For functions, if x and y are outside the area, the value will be +automatically clipped to the closer edge. +

+

Please note that this filter can use multiple threads in which case each slice +will have its own expression state. If you want to use only a single expression +state because your expressions depend on previous state then you should limit +the number of filter threads to 1. +

+ +

32.109.1 Examples

+ +
    +
  • Flip the image horizontally: +
    +
    geq=p(W-X\,Y)
    +
    + +
  • Generate a bidimensional sine wave, with angle PI/3 and a +wavelength of 100 pixels: +
    +
    geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
    +
    + +
  • Generate a fancy enigmatic moving light: +
    +
    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
    +
    + +
  • Generate a quick emboss effect: +
    +
    format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
    +
    + +
  • Modify RGB components depending on pixel position: +
    +
    geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
    +
    + +
  • Create a radial gradient that is the same size as the input (also see +the vignette filter): +
    +
    geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
    +
    +
+ + +

32.110 gradfun

+ +

Fix the banding artifacts that are sometimes introduced into nearly flat +regions by truncation to 8-bit color depth. +Interpolate the gradients that should go where the bands are, and +dither them. +

+

It 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. +

+

It accepts the following parameters: +

+
+
strength
+

The maximum amount by which the filter will change any one pixel. This is also +the threshold for detecting nearly flat regions. Acceptable values range from +.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the +valid range. +

+
+
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 8-32; the default value is 16. Out-of-range +values will be clipped to the valid range. +

+
+
+ +

Alternatively, the options can be specified as a flat string: +strength[:radius] +

+ +

32.110.1 Examples

+ +
    +
  • Apply the filter with a 3.5 strength and radius of 8: +
    +
    gradfun=3.5:8
    +
    + +
  • Specify radius, omitting the strength (which will fall-back to the default +value): +
    +
    gradfun=radius=8
    +
    + +
+ + +

32.111 graphmonitor

+

Show various filtergraph stats. +

+

With this filter one can debug complete filtergraph. +Especially issues with links filling with queued frames. +

+

The filter accepts the following options: +

+
+
size, s
+

Set video output size. Default is hd720. +

+
+
opacity, o
+

Set video opacity. Default is 0.9. Allowed range is from 0 to 1. +

+
+
mode, m
+

Set output mode flags. +

+

Available values for flags are: +

+
‘full’
+

No any filtering. Default. +

+
‘compact’
+

Show only filters with queued frames. +

+
‘nozero’
+

Show only filters with non-zero stats. +

+
‘noeof’
+

Show only filters with non-eof stat. +

+
‘nodisabled’
+

Show only filters that are enabled in timeline. +

+
+ +
+
flags, f
+

Set flags which enable which stats are shown in video. +

+

Available values for flags are: +

+
‘none’
+

All flags turned off. +

+
+
‘all’
+

All flags turned on. +

+
+
‘queue’
+

Display number of queued frames in each link. +

+
+
‘frame_count_in’
+

Display number of frames taken from filter. +

+
+
‘frame_count_out’
+

Display number of frames given out from filter. +

+
+
‘frame_count_delta’
+

Display delta number of frames between above two values. +

+
+
‘pts’
+

Display current filtered frame pts. +

+
+
‘pts_delta’
+

Display pts delta between current and previous frame. +

+
+
‘time’
+

Display current filtered frame time. +

+
+
‘time_delta’
+

Display time delta between current and previous frame. +

+
+
‘timebase’
+

Display time base for filter link. +

+
+
‘format’
+

Display used format for filter link. +

+
+
‘size’
+

Display video size or number of audio channels in case of audio used by filter link. +

+
+
‘rate’
+

Display video frame rate or sample rate in case of audio used by filter link. +

+
+
‘eof’
+

Display link output status. +

+
+
‘sample_count_in’
+

Display number of samples taken from filter. +

+
+
‘sample_count_out’
+

Display number of samples given out from filter. +

+
+
‘sample_count_delta’
+

Display delta number of samples between above two values. +

+
+
‘disabled’
+

Show the timeline filter status. +

+
+ +
+
rate, r
+

Set upper limit for video rate of output stream, Default value is 25. +This guarantee that output video frame rate will not be higher than this value. +

+
+ + +

32.112 grayworld

+

A color constancy filter that applies color correction based on the grayworld assumption +

+

See: https://www.researchgate.net/publication/275213614_A_New_Color_Correction_Method_for_Underwater_Imaging +

+

The algorithm uses linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,grayworld,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

32.113 greyedge

+

A color constancy variation filter which estimates scene illumination via grey edge algorithm +and corrects the scene colors accordingly. +

+

See: https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf +

+

The filter accepts the following options: +

+
+
difford
+

The order of differentiation to be applied on the scene. Must be chosen in the range +[0,2] and default value is 1. +

+
+
minknorm
+

The Minkowski parameter to be used for calculating the Minkowski distance. Must +be chosen in the range [0,20] and default value is 1. Set to 0 for getting +max value instead of calculating Minkowski distance. +

+
+
sigma
+

The standard deviation of Gaussian blur to be applied on the scene. Must be +chosen in the range [0,1024.0] and default value = 1. floor( sigma * break_off_sigma(3) ) +can’t be equal to 0 if difford is greater than 0. +

+
+ + +

32.113.1 Examples

+
    +
  • Grey Edge: +
    +
    greyedge=difford=1:minknorm=5:sigma=2
    +
    + +
  • Max Edge: +
    +
    greyedge=difford=1:minknorm=0:sigma=2
    +
    + +
+ + +

32.114 guided

+

Apply guided filter for edge-preserving smoothing, dehazing and so on. +

+

The filter accepts the following options: +

+
radius
+

Set the box radius in pixels. +Allowed range is 1 to 20. Default is 3. +

+
+
eps
+

Set regularization parameter (with square). +Allowed range is 0 to 1. Default is 0.01. +

+
+
mode
+

Set filter mode. Can be basic or fast. +Default is basic. +

+
+
sub
+

Set subsampling ratio for fast mode. +Range is 2 to 64. Default is 4. +No subsampling occurs in basic mode. +

+
+
guidance
+

Set guidance mode. Can be off or on. Default is off. +If off, single input is required. +If on, two inputs of the same resolution and pixel format are required. +The second input serves as the guidance. +

+
+
planes
+

Set planes to filter. Default is first only. +

+
+ + +

32.114.1 Commands

+

This filter supports the all above options as commands. +

+ +

32.114.2 Examples

+
    +
  • Edge-preserving smoothing with guided filter: +
    +
    ffmpeg -i in.png -vf guided out.png
    +
    + +
  • Dehazing, structure-transferring filtering, detail enhancement with guided filter. +For the generation of guidance image, refer to paper "Guided Image Filtering". +See: http://kaiminghe.com/publications/pami12guidedfilter.pdf. +
    +
    ffmpeg -i in.png -i guidance.png -filter_complex guided=guidance=on out.png
    +
    + +
+ + +

32.115 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: +

+
+
clut
+

Set which CLUT video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+
shortest
+

Force termination when the shortest input terminates. Default is 0. +

+
repeatlast
+

Continue applying the last CLUT after the end of the stream. A value of +0 disable the filter after the last frame of the CLUT is reached. +Default is 1. +

+
+ +

haldclut also has the same interpolation options as lut3d (both +filters share the same internals). +

+

This filter also supports the framesync options. +

+

More information about the Hald CLUT can be found on Eskil Steenberg’s website +(Hald CLUT author) at http://www.quelsolaar.com/technology/clut.html. +

+ +

32.115.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

32.115.2 Workflow examples

+ + +

32.115.2.1 Hald CLUT video stream

+ +

Generate an identity Hald CLUT stream altered with various effects: +

+
ffmpeg -f lavfi -i haldclutsrc=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut
+
+ +

Note: make sure you use a lossless codec. +

+

Then use it with haldclut to apply it on some random stream: +

+
ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
+
+ +

The Hald CLUT will be applied to the 10 first seconds (duration of +clut.nut), then the latest picture of that CLUT stream will be applied +to the remaining frames of the mandelbrot stream. +

+ +

32.115.2.2 Hald CLUT with preview

+ +

A Hald CLUT is supposed to be a squared image of Level*Level*Level by +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 +haldclut filter: +

+
+
ffmpeg -f lavfi -i 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
+
+ +

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: +

+
ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
+
+ + +

32.116 hflip

+ +

Flip the input video horizontally. +

+

For example, to horizontally flip the input video with ffmpeg: +

+
ffmpeg -i in.avi -vf "hflip" out.avi
+
+ + +

32.117 histeq

+

This filter applies a global color histogram equalization on a +per-frame basis. +

+

It can be used to correct video that has a compressed range of pixel +intensities. The filter redistributes the pixel intensities to +equalize their distribution across the intensity range. It may be +viewed as an "automatically adjusting contrast filter". This filter is +useful only for correcting degraded or poorly captured source +video. +

+

The filter accepts the following options: +

+
+
strength
+

Determine the amount of equalization to be applied. As the strength +is reduced, the distribution of pixel intensities more-and-more +approaches that of the input frame. The value must be a float number +in the range [0,1] and defaults to 0.200. +

+
+
intensity
+

Set the maximum intensity that can generated and scale the output +values appropriately. The strength should be set as desired and then +the intensity can be limited if needed to avoid washing-out. The value +must be a float number in the range [0,1] and defaults to 0.210. +

+
+
antibanding
+

Set the antibanding level. If enabled the filter will randomly vary +the luminance of output pixels by a small amount to avoid banding of +the histogram. Possible values are none, weak or +strong. It defaults to none. +

+
+ + +

32.118 histogram

+ +

Compute and draw a color distribution histogram for the input video. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

Standard histogram displays the color components distribution in an image. +Displays color graph for each color component. Shows distribution of +the Y, U, V, A or R, G, B components, depending on input format, in the +current frame. Below each graph a color component scale meter is shown. +

+

The filter accepts the following options: +

+
+
level_height
+

Set height of level. Default value is 200. +Allowed range is [50, 2048]. +

+
+
scale_height
+

Set height of color scale. Default value is 12. +Allowed range is [0, 40]. +

+
+
display_mode
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components
+

Set what color components to display. +Default is 7. +

+
+
fgopacity
+

Set foreground opacity. Default is 0.7. +

+
+
bgopacity
+

Set background opacity. Default is 0.5. +

+
+
colors_mode
+

Set colors mode. +It accepts the following values: +

+
‘whiteonblack’
+
‘blackonwhite’
+
‘whiteongray’
+
‘blackongray’
+
‘coloronblack’
+
‘coloronwhite’
+
‘colorongray’
+
‘blackoncolor’
+
‘whiteoncolor’
+
‘grayoncolor’
+
+

Default is whiteonblack. +

+
+ + +

32.118.1 Examples

+ +
    +
  • Calculate and draw histogram: +
    +
    ffplay -i input -vf histogram
    +
    + +
+ + +

32.119 hqdn3d

+ +

This is a high precision/quality 3d denoise filter. It aims to reduce +image noise, producing smooth images and making still images really +still. It should enhance compressibility. +

+

It accepts the following optional parameters: +

+
+
luma_spatial
+

A non-negative floating point number which specifies spatial luma strength. +It defaults to 4.0. +

+
+
chroma_spatial
+

A non-negative floating point number which specifies spatial chroma strength. +It defaults to 3.0*luma_spatial/4.0. +

+
+
luma_tmp
+

A floating point number which specifies luma temporal strength. It defaults to +6.0*luma_spatial/4.0. +

+
+
chroma_tmp
+

A floating point number which specifies chroma temporal strength. It defaults to +luma_tmp*chroma_spatial/luma_spatial. +

+
+ + +

32.119.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.120 hwdownload

+ +

Download hardware frames to system memory. +

+

The input must be in hardware frames, and the output a non-hardware format. +Not all formats will be supported on the output - it may be necessary to insert +an additional format filter immediately following in the graph to get +the output in a supported format. +

+ +

32.121 hwmap

+ +

Map hardware frames to system memory or to another device. +

+

This filter has several different modes of operation; which one is used depends +on the input and output formats: +

    +
  • Hardware frame input, normal frame output + +

    Map the input frames to system memory and pass them to the output. If the +original hardware frame is later required (for example, after overlaying +something else on part of it), the hwmap filter can be used again +in the next mode to retrieve it. +

  • Normal frame input, hardware frame output + +

    If the input is actually a software-mapped hardware frame, then unmap it - +that is, return the original hardware frame. +

    +

    Otherwise, a device must be provided. Create new hardware surfaces on that +device for the output, then map them back to the software format at the input +and give those frames to the preceding filter. This will then act like the +hwupload filter, but may be able to avoid an additional copy when +the input is already in a compatible format. +

  • Hardware frame input and output + +

    A device must be supplied for the output, either directly or with the +derive_device option. The input and output devices must be of +different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

    +

    If the input frames were originally created on the output device, then unmap +to retrieve the original frames. +

    +

    Otherwise, map the frames to the output device - create new hardware frames +on the output corresponding to the frames on the input. +

+ +

The following additional parameters are accepted: +

+
+
mode
+

Set the frame mapping mode. Some combination of: +

+
read
+

The mapped frame should be readable. +

+
write
+

The mapped frame should be writeable. +

+
overwrite
+

The mapping will always overwrite the entire frame. +

+

This may improve performance in some cases, as the original contents of the +frame need not be loaded. +

+
direct
+

The mapping must not involve any copying. +

+

Indirect mappings to copies of frames are created in some cases where either +direct mapping is not possible or it would have unexpected properties. +Setting this flag ensures that the mapping is direct and will fail if that is +not possible. +

+
+

Defaults to read+write if not specified. +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+
reverse
+

In a hardware to hardware mapping, map in reverse - create frames in the sink +and map them back to the source. This may be necessary in some cases where +a mapping in one direction is required but only the opposite direction is +supported by the devices being used. +

+

This option is dangerous - it may break the preceding filter in undefined +ways if there are any additional constraints on that filter’s output. +Do not use it without fully understanding the implications of its use. +

+
+ + +

32.122 hwupload

+ +

Upload system memory frames to hardware surfaces. +

+

The device to upload to must be supplied when the filter is initialised. If +using ffmpeg, select the appropriate device with the -filter_hw_device +option or with the derive_device option. The input and output devices +must be of different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). +

+

The following additional parameters are accepted: +

+
+
derive_device type
+

Rather than using the device supplied at initialisation, instead derive a new +device of type type from the device the input frames exist on. +

+
+ + +

32.123 hwupload_cuda

+ +

Upload system memory frames to a CUDA device. +

+

It accepts the following optional parameters: +

+
+
device
+

The number of the CUDA device to use +

+
+ + +

32.124 hqx

+ +

Apply a high-quality magnification filter designed for pixel art. This filter +was originally created by Maxim Stepin. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for hq2x, 3 for +hq3x and 4 for hq4x. +Default is 3. +

+
+ + +

32.125 hstack

+

Stack input videos horizontally. +

+

All streams must be of same pixel format and of same height. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following option: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

32.126 hsvhold

+

Turns a certain HSV range into gray values. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to be gray or not. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully gray, or not gray at all. +

+

Higher values result in more gray pixels, with a higher gray pixel +the more similar the pixels color is to the key color. +

+
+ + +

32.127 hsvkey

+

Turns a certain HSV range into transparency. +

+

This filter measures color difference between set HSV color in options +and ones measured in video stream. Depending on options, output +colors can be changed to transparent by adding alpha channel. +

+

The filter accepts the following options: +

+
+
hue
+

Set the hue value which will be used in color difference calculation. +Allowed range is from -360 to 360. Default value is 0. +

+
+
sat
+

Set the saturation value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
val
+

Set the value which will be used in color difference calculation. +Allowed range is from -1 to 1. Default value is 0. +

+
+
similarity
+

Set similarity percentage with the key color. +Allowed range is from 0 to 1. Default value is 0.01. +

+

0.00001 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +Allowed range is from 0 to 1. Default value is 0. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

32.128 hue

+ +

Modify the hue and/or the saturation of the input. +

+

It accepts the following parameters: +

+
+
h
+

Specify the hue angle as a number of degrees. It accepts an expression, +and defaults to "0". +

+
+
s
+

Specify the saturation in the [-10,10] range. It accepts an expression and +defaults to "1". +

+
+
H
+

Specify the hue angle as a number of radians. It accepts an +expression, and defaults to "0". +

+
+
b
+

Specify the brightness in the [-10,10] range. It accepts an expression and +defaults to "0". +

+
+ +

h and H are mutually exclusive, and can’t be +specified at the same time. +

+

The b, h, H and s option values are +expressions containing the following constants: +

+
+
n
+

frame count of the input frame starting from 0 +

+
+
pts
+

presentation timestamp of the input frame expressed in time base units +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
tb
+

time base of the input video +

+
+ + +

32.128.1 Examples

+ +
    +
  • Set the hue to 90 degrees and the saturation to 1.0: +
    +
    hue=h=90:s=1
    +
    + +
  • Same command but expressing the hue in radians: +
    +
    hue=H=PI/2:s=1
    +
    + +
  • Rotate hue and make the saturation swing between 0 +and 2 over a period of 1 second: +
    +
    hue="H=2*PI*t: s=sin(2*PI*t)+1"
    +
    + +
  • Apply a 3 seconds saturation fade-in effect starting at 0: +
    +
    hue="s=min(t/3\,1)"
    +
    + +

    The general fade-in expression can be written as: +

    +
    hue="s=min(0\, max((t-START)/DURATION\, 1))"
    +
    + +
  • Apply a 3 seconds saturation fade-out effect starting at 5 seconds: +
    +
    hue="s=max(0\, min(1\, (8-t)/3))"
    +
    + +

    The general fade-out expression can be written as: +

    +
    hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
    +
    + +
+ + +

32.128.2 Commands

+ +

This filter supports the following commands: +

+
b
+
s
+
h
+
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 the specified expression is not valid, it is kept at its current +value. +

+
+ + +

32.129 huesaturation

+

Apply hue-saturation-intensity adjustments to input video stream. +

+

This filter operates in RGB colorspace. +

+

This filter accepts the following options: +

+
+
hue
+

Set the hue shift in degrees to apply. Default is 0. +Allowed range is from -180 to 180. +

+
+
saturation
+

Set the saturation shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
intensity
+

Set the intensity shift. Default is 0. +Allowed range is from -1 to 1. +

+
+
colors
+

Set which primary and complementary colors are going to be adjusted. +This options is set by providing one or multiple values. +This can select multiple colors at once. By default all colors are selected. +

+
‘r’
+

Adjust reds. +

+
‘y’
+

Adjust yellows. +

+
‘g’
+

Adjust greens. +

+
‘c’
+

Adjust cyans. +

+
‘b’
+

Adjust blues. +

+
‘m’
+

Adjust magentas. +

+
‘a’
+

Adjust all colors. +

+
+ +
+
strength
+

Set strength of filtering. Allowed range is from 0 to 100. +Default value is 1. +

+
+
rw, gw, bw
+

Set weight for each RGB component. Allowed range is from 0 to 1. +By default is set to 0.333, 0.334, 0.333. +Those options are used in saturation and lightess processing. +

+
+
lightness
+

Set preserving lightness, by default is disabled. +Adjusting hues can change lightness from original RGB triplet, +with this option enabled lightness is kept at same value. +

+
+ + +

32.130 hysteresis

+ +

Grow first stream into second stream by connecting components. +This makes it possible to build more robust edge masks. +

+

This filter accepts the following options: +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+
threshold
+

Set threshold which is used in filtering. If pixel component value is higher than +this value filter algorithm for connecting components is activated. +By default value is 0. +

+
+ +

The hysteresis filter also supports the framesync options. +

+ +

32.131 iccdetect

+ +

Detect the colorspace from an embedded ICC profile (if present), and update +the frame’s tags accordingly. +

+

This filter accepts the following options: +

+
+
force
+

If true, the frame’s existing colorspace tags will always be overridden by +values detected from an ICC profile. Otherwise, they will only be assigned if +they contain unknown. Enabled by default. +

+
+ + +

32.132 iccgen

+ +

Generate ICC profiles and attach them to frames. +

+

This filter accepts the following options: +

+
+
color_primaries
+
color_trc
+

Configure the colorspace that the ICC profile will be generated for. The +default value of auto infers the value from the input frame’s metadata, +defaulting to BT.709/sRGB as appropriate. +

+

See the setparams filter for a list of possible values, but note that +unknown are not valid values for this filter. +

+
+
force
+

If true, an ICC profile will be generated even if it would overwrite an +already existing ICC profile. Disabled by default. +

+
+ + +

32.133 identity

+ +

Obtain the identity score between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max identity score is printed through +the logging system. +

+

The filter stores the calculated identity scores of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi identity -f null -
+
+ + +

32.134 idet

+ +

Detect video interlacing type. +

+

This filter tries to detect if the input frames are interlaced, progressive, +top or bottom field first. It will also try to detect fields that are +repeated between adjacent frames (a sign of telecine). +

+

Single frame detection considers only immediately adjacent frames when classifying each frame. +Multiple frame detection incorporates the classification history of previous frames. +

+

The filter will log these metadata values: +

+
+
single.current_frame
+

Detected type of current frame using single-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
single.tff
+

Cumulative number of frames detected as top field first using single-frame detection. +

+
+
multiple.tff
+

Cumulative number of frames detected as top field first using multiple-frame detection. +

+
+
single.bff
+

Cumulative number of frames detected as bottom field first using single-frame detection. +

+
+
multiple.current_frame
+

Detected type of current frame using multiple-frame detection. One of: +“tff” (top field first), “bff” (bottom field first), +“progressive”, or “undetermined” +

+
+
multiple.bff
+

Cumulative number of frames detected as bottom field first using multiple-frame detection. +

+
+
single.progressive
+

Cumulative number of frames detected as progressive using single-frame detection. +

+
+
multiple.progressive
+

Cumulative number of frames detected as progressive using multiple-frame detection. +

+
+
single.undetermined
+

Cumulative number of frames that could not be classified using single-frame detection. +

+
+
multiple.undetermined
+

Cumulative number of frames that could not be classified using multiple-frame detection. +

+
+
repeated.current_frame
+

Which field in the current frame is repeated from the last. One of “neither”, “top”, or “bottom”. +

+
+
repeated.neither
+

Cumulative number of frames with no repeated field. +

+
+
repeated.top
+

Cumulative number of frames with the top field repeated from the previous frame’s top field. +

+
+
repeated.bottom
+

Cumulative number of frames with the bottom field repeated from the previous frame’s bottom field. +

+
+ +

The filter accepts the following options: +

+
+
intl_thres
+

Set interlacing threshold. +

+
prog_thres
+

Set progressive threshold. +

+
rep_thres
+

Threshold for repeated field detection. +

+
half_life
+

Number of frames after which a given frame’s contribution to the +statistics is halved (i.e., it contributes only 0.5 to its +classification). The default of 0 means that all frames seen are given +full weight of 1.0 forever. +

+
analyze_interlaced_flag
+

When this is not 0 then idet will use the specified number of frames to determine +if the interlaced flag is accurate, it will not count undetermined frames. +If the flag is found to be accurate it will be used without any further +computations, if it is found to be inaccurate it will be cleared without any +further computations. This allows inserting the idet filter as a low computational +method to clean up the interlaced flag +

+
+ + +

32.134.1 Examples

+ +

Inspect the field order of the first 360 frames in a video, in verbose detail: +

+
ffmpeg -i INPUT -filter:v idet,metadata=mode=print -frames:v 360 -an -f null -
+
+

The idet filter will add analysis metadata to each frame, which will then be +discarded. At the end, the filter will also print a final report with statistics. +

+ +

32.135 il

+ +

Deinterleave or interleave fields. +

+

This filter allows one to process interlaced images fields without +deinterlacing them. Deinterleaving splits the input frame into 2 +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. +

+

The filter accepts the following options: +

+
+
luma_mode, l
+
chroma_mode, c
+
alpha_mode, a
+

Available values for luma_mode, chroma_mode and +alpha_mode are: +

+
+
‘none’
+

Do nothing. +

+
+
‘deinterleave, d’
+

Deinterleave fields, placing one above the other. +

+
+
‘interleave, i’
+

Interleave fields. Reverse the effect of deinterleaving. +

+
+

Default value is none. +

+
+
luma_swap, ls
+
chroma_swap, cs
+
alpha_swap, as
+

Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is 0. +

+
+ + +

32.135.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.136 inflate

+ +

Apply inflate effect to the video. +

+

This filter replaces the pixel by the local(3x3) average by taking into account +only values higher than the pixel. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane, default is 65535. +If 0, plane will remain unchanged. +

+
+ + +

32.136.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.137 interlace, interlace_vulkan

+ +

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. +

+
+
   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
+
+ +

It accepts the following optional parameters: +

+
+
scan
+

This determines whether the interlaced frame is taken from the even +(tff - default) or odd (bff) lines of the progressive frame. +

+
+
lowpass
+

Vertical lowpass filter to avoid twitter interlacing and +reduce moire patterns. +

+
+
‘0, off’
+

Disable vertical lowpass filter +

+
+
‘1, linear’
+

Enable linear filter (default) +

+
+
‘2, complex’
+

Enable complex filter. This will slightly less reduce twitter and moire +but better retain detail and subjective sharpness impression. +

+
+
+
+
+ + +

32.138 kerndeint

+ +

Deinterlace input video by applying Donald Graft’s adaptive kernel +deinterling. Work on interlaced parts of a video to produce +progressive frames. +

+

The description of the accepted parameters follows. +

+
+
thresh
+

Set the threshold which affects the filter’s tolerance when +determining if a pixel line must be processed. It must be an integer +in the range [0,255] and defaults to 10. A value of 0 will result in +applying the process on every pixels. +

+
+
map
+

Paint pixels exceeding the threshold value to white if set to 1. +Default is 0. +

+
+
order
+

Set the fields order. Swap fields if set to 1, leave fields alone if +0. Default is 0. +

+
+
sharp
+

Enable additional sharpening if set to 1. Default is 0. +

+
+
twoway
+

Enable twoway sharpening if set to 1. Default is 0. +

+
+ + +

32.138.1 Examples

+ +
    +
  • Apply default values: +
    +
    kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
    +
    + +
  • Enable additional sharpening: +
    +
    kerndeint=sharp=1
    +
    + +
  • Paint processed pixels in white: +
    +
    kerndeint=map=1
    +
    +
+ + +

32.139 kirsch

+

Apply kirsch operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

32.139.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.140 lagfun

+ +

Slowly update darker pixels. +

+

This filter makes short flashes of light appear longer. +This filter accepts the following options: +

+
+
decay
+

Set factor for decaying. Default is .95. Allowed range is from 0 to 1. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

32.140.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.141 lenscorrection

+ +

Correct radial lens distortion +

+

This filter can be used to correct for radial distortion as can result from the use +of wide angle lenses, and thereby re-rectify the image. To find the right parameters +one can use tools available for example as part of opencv or simply trial-and-error. +To use opencv use the calibration sample (under samples/cpp) from the opencv sources +and extract the k1 and k2 coefficients from the resulting matrix. +

+

Note that effectively the same filter is available in the open-source tools Krita and +Digikam from the KDE project. +

+

In contrast to the vignette filter, which can also be used to compensate lens errors, +this filter corrects the distortion of the image, whereas vignette corrects the +brightness distribution, so you may want to use both filters together in certain +cases, though you will have to take care of ordering, i.e. whether vignetting should +be applied before or after lens correction. +

+ +

32.141.1 Options

+ +

The filter accepts the following options: +

+
+
cx
+

Relative x-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +width. Default is 0.5. +

+
cy
+

Relative y-coordinate of the focal point of the image, and thereby the center of the +distortion. This value has a range [0,1] and is expressed as fractions of the image +height. Default is 0.5. +

+
k1
+

Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means +no correction. Default is 0. +

+
k2
+

Coefficient of the double quadratic correction term. This value has a range [-1,1]. +0 means no correction. Default is 0. +

+
i
+

Set interpolation type. Can be nearest or bilinear. +Default is nearest. +

+
fc
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black@0. +

+
+ +

The formula that generates the correction is: +

+

r_src = r_tgt * (1 + k1 * (r_tgt / r_0)^2 + k2 * (r_tgt / r_0)^4) +

+

where r_0 is halve of the image diagonal and r_src and r_tgt are the +distances from the focal point in the source and target images, respectively. +

+ +

32.141.2 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.142 lensfun

+ +

Apply lens correction via the lensfun library (http://lensfun.sourceforge.net/). +

+

The lensfun filter requires the camera make, camera model, and lens model +to apply the lens correction. The filter will load the lensfun database and +query it to find the corresponding camera and lens entries in the database. As +long as these entries can be found with the given options, the filter can +perform corrections on frames. Note that incomplete strings will result in the +filter choosing the best match with the given options, and the filter will +output the chosen camera and lens models (logged with level "info"). You must +provide the make, camera model, and lens model as they are required. +

+

To obtain a list of available makes and models, leave out one or both of make and +model options. The filter will send the full list to the log with level INFO. +The first column is the make and the second column is the model. +To obtain a list of available lenses, set any values for make and model and leave out the +lens_model option. The filter will send the full list of lenses in the log with level +INFO. The ffmpeg tool will exit after the list is printed. +

+

The filter accepts the following options: +

+
+
make
+

The make of the camera (for example, "Canon"). This option is required. +

+
+
model
+

The model of the camera (for example, "Canon EOS 100D"). This option is +required. +

+
+
lens_model
+

The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This +option is required. +

+
+
db_path
+

The full path to the lens database folder. If not set, the filter will attempt to +load the database from the install path when the library was built. Default is unset. +

+
+
mode
+

The type of correction to apply. The following values are valid options: +

+
+
‘vignetting’
+

Enables fixing lens vignetting. +

+
+
‘geometry’
+

Enables fixing lens geometry. This is the default. +

+
+
‘subpixel’
+

Enables fixing chromatic aberrations. +

+
+
‘vig_geo’
+

Enables fixing lens vignetting and lens geometry. +

+
+
‘vig_subpixel’
+

Enables fixing lens vignetting and chromatic aberrations. +

+
+
‘distortion’
+

Enables fixing both lens geometry and chromatic aberrations. +

+
+
‘all’
+

Enables all possible corrections. +

+
+
+
+
focal_length
+

The focal length of the image/video (zoom; expected constant for video). For +example, a 18–55mm lens has focal length range of [18–55], so a value in that +range should be chosen when using that lens. Default 18. +

+
+
aperture
+

The aperture of the image/video (expected constant for video). Note that +aperture is only used for vignetting correction. Default 3.5. +

+
+
focus_distance
+

The focus distance of the image/video (expected constant for video). Note that +focus distance is only used for vignetting and only slightly affects the +vignetting correction process. If unknown, leave it at the default value (which +is 1000). +

+
+
scale
+

The scale factor which is applied after transformation. After correction the +video is no longer necessarily rectangular. This parameter controls how much of +the resulting image is visible. The value 0 means that a value will be chosen +automatically such that there is little or no unmapped area in the output +image. 1.0 means that no additional scaling is done. Lower values may result +in more of the corrected image being visible, while higher values may avoid +unmapped areas in the output. +

+
+
target_geometry
+

The target geometry of the output image/video. The following values are valid +options: +

+
+
‘rectilinear (default)’
+
‘fisheye’
+
‘panoramic’
+
‘equirectangular’
+
‘fisheye_orthographic’
+
‘fisheye_stereographic’
+
‘fisheye_equisolid’
+
‘fisheye_thoby’
+
+
+
reverse
+

Apply the reverse of image correction (instead of correcting distortion, apply +it). +

+
+
interpolation
+

The type of interpolation used when correcting distortion. The following values +are valid options: +

+
+
‘nearest’
+
‘linear (default)’
+
‘lanczos’
+
+
+
+ + +

32.142.1 Examples

+ +
    +
  • Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens +model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and +aperture of "8.0". + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
    +
    + +
  • Apply the same as before, but only for the first 5 seconds of video. + +
    +
    ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov
    +
    + +
+ + +

32.143 lcevc

+ +

Low Complexity Enhancement Video Codec filter based on liblcevc_dec +(https://github.com/v-novaltd/LCEVCdec). +

+ +

32.144 libplacebo

+ +

Flexible GPU-accelerated processing filter based on libplacebo +(https://code.videolan.org/videolan/libplacebo). +

+ +

32.144.1 Options

+ +

The options for this filter are divided into the following sections: +

+ +

32.144.1.1 Output mode

+

These options control the overall output mode. By default, libplacebo will try +to preserve the source colorimetry and size as best as it can, but it will +apply any embedded film grain, dolby vision metadata or anamorphic SAR present +in source frames. +

+
inputs
+

Set the number of inputs. This can be used, alongside the idx variable, +to allow placing/blending multiple inputs inside the output frame. This +effectively enables functionality similar to hstack, overlay, etc. +

+
+
w
+
h
+

Set the output video dimension expression. Default values are iw and +ih. +

+

Allows for the same expressions as the scale filter. +

+
+
crop_x
+
crop_y
+

Set the input crop x/y expressions, default values are (iw-cw)/2 and +(ih-ch)/2. +

+
+
crop_w
+
crop_h
+

Set the input crop width/height expressions, default values are iw and +ih. +

+
+
pos_x
+
pos_y
+

Set the output placement x/y expressions, default values are (ow-pw)/2 +and (oh-ph)/2. +

+
+
pos_w
+
pos_h
+

Set the output placement width/height expressions, default values are ow +and oh. +

+
+
rotate
+

Rotate the input frame clockwise by the specified angle. +

+
+
‘0, 360’
+
‘90’
+
‘180’
+
‘270’
+
+ +
+
fps
+

Set the output frame rate. This can be rational, e.g. 60000/1001. If +set to the special string none (the default), input timestamps will +instead be passed through to the output unmodified. Otherwise, the input video +frames will be interpolated as necessary to rescale the video to the specified +target framerate, in a manner as determined by the frame_mixer option. +

+
+
format
+

Set the output format override. If unset (the default), frames will be output +in the same format as the respective input frames. Otherwise, format conversion +will be performed. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. Note that +force_divisible_by also works with fit_sense=constraint. +

+
+
reset_sar
+

If enabled, output frames will always have a pixel aspect ratio of 1:1. If +disabled (the default), any aspect ratio mismatches, including those from +e.g. anamorphic video sources, are forwarded to the output pixel aspect ratio. +

+
+
normalize_sar
+

Like reset_sar, but instead of stretching the video content to fill +the new output aspect ratio, the content is instead padded or cropped as +necessary. Mutually exclusive with fit_mode. Disabled by default. +

+
+
pad_crop_ratio
+

Specifies a ratio (between 0.0 and 1.0) between padding and +cropping when the input aspect ratio does not match the output aspect ratio and +normalize_sar is in effect. The default of 0.0 always pads the +content with black borders, while a value of 1.0 always crops off parts +of the content. Intermediate values are possible, leading to a mix of the two +approaches. +

+
+
fit_mode
+

Specify the content fit strategy according to a list of predefined modes. +Determines how the input image is to be placed inside the destination crop +rectangle (as defined by pos_x/y and pos_w/h). The names and +their implementations are taken from the CSS ’object-fit’ property. Note that +this option is mutually exclusive with normalize_sar. Defaults to +fill. Valid values are: +

+
+
‘fill’
+

Stretch the input to the output rectangle, ignoring aspect ratio mismatches. +Note that unless reset_sar is also enabled, the output will still +have the correct pixel aspect ratio tagged. +

+
+
‘contain’
+

Scale the input to fit inside the output, preserving aspect ratio by padding. +Equivalent to normalize_sar with pad_crop_ratio set to +0.0. +

+
+
‘cover’
+

Scale the input to fill the output, preserving aspect ratio by cropping. +Equivalent to normalize_sar with pad_crop_ratio set to +1.0. +

+
+
‘none, place’
+

Don’t scale the input. The input will be placed inside the output rectangle at +its natural size; which may result in additional padding or cropping. +

+
+
‘scale_down’
+

Scale the input down as much as needed to fit inside the output. Equivalent +to either contain or none, depending on whether the input is +larger than the output or not. +

+
+ +
+
fit_sense
+

When fit_mode is in use, this option controls how the fit strategy +is applied against the specified output resolution. Mutually exclusive with +force_original_aspect_ratio. Valid values are: +

+
+
‘target’
+

The computed output resolution is taken as the exact size of the output frame. +This is the default behavior. +

+
+
‘constraint’
+

The computed output resolution is a size reference against which the fit mode +is applied, enlarging or decreasing the true frame size as needed to fit the +content. +

+
+ +
+
fillcolor
+

Set the color used to fill the output area not covered by the output image, for +example as a result of normalize_sar. For the general syntax of this +option, check the "Color" section in the ffmpeg-utils +manual. Defaults to black@0. +

+
+
corner_rounding
+

Render frames with rounded corners. The value, given as a float ranging from +0.0 to 1.0, indicates the relative degree of rounding, from fully +square to fully circular. In other words, it gives the radius divided by half +the smaller side length. Defaults to 0.0. +

+
+
lut
+

Specifies a custom LUT (in Adobe .cube format) to apply to the colors +as part of color conversion. The exact interpretation depends on the value +of lut_type. +

+
+
lut_type
+

Controls the interpretation of color values fed to and from the LUT +specified as lut. Valid values are: +

+
+
‘auto’
+

Chooses the interpretation of the LUT automatically from tagged +metadata, and otherwise falls back to ‘native’. (Default) +

+
+
‘native’
+

Applied to raw image contents in its native RGB colorspace (non-linear +light), before conversion to the output color space. +

+
+
‘normalized’
+

Applied to the normalized RGB image contents, in linear light, before +conversion to the output color space. +

+
+
‘conversion’
+

Fully replaces the conversion from the image color space to the output +color space. If such a LUT is present, it has the highest priority, and +overrides any ICC profiles, as well as options related to tone mapping +and output colorimetry (color_primaries, color_trc). +

+
+
+ +
+
extra_opts
+

Pass extra libplacebo internal configuration options. These can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to configure a custom filter kernel ("EWA LanczosSharp") and use it +to double the input image resolution: +

+
+
-vf "libplacebo=w=iw*2:h=ih*2:extra_opts='upscaler=custom\:upscaler_preset=ewa_lanczos\:upscaler_blur=0.9812505644269356'"
+
+ + +
+
shader_cache
+

File path of a cache directory that libplacebo will use to store and load +cached shader objects. This cache is not cleaned up automatically. If the +path does not end in a directory separator, the generated filenames will be +effectively prefixed by the last path component. All directories must already +exist. +

+
+
-vf "libplacebo=shader_cache=/tmp/pl-shader-"
+
+ +
+
colorspace
+
color_primaries
+
color_trc
+
range
+
chroma_location
+

Configure the colorspace that output frames will be delivered in. The default +value of auto outputs frames in the same format as the input frames, +leading to no change. For any other value, conversion will be performed. +

+

See the setparams filter for a list of possible values. +

+
+
alpha_mode
+

Choose the desired output alpha mode, when the output format has an alpha +channel. See the setparams filter for a list of possible values. +

+
+
apply_filmgrain
+

Apply film grain (e.g. AV1 or H.274) if present in source frames, and strip +it from the output. Enabled by default. +

+
+
apply_dolbyvision
+

Apply Dolby Vision RPU metadata if present in source frames, and strip it from +the output. Enabled by default. Note that Dolby Vision will always output +BT.2020+PQ, overriding the usual input frame metadata. These will also be +picked as the values of auto for the respective frame output options. +

+
+ +

In addition to the expression constants documented for the scale filter, +the crop_w, crop_h, crop_x, crop_y, +pos_w, pos_h, pos_x and pos_y options can +also contain the following constants: +

+
+
in_idx, idx
+

The (0-based) numeric index of the currently active input stream. +

+
crop_w, cw
+
crop_h, ch
+

The computed values of crop_w and crop_h. +

+
+
pos_w, pw
+
pos_h, ph
+

The computed values of pos_w and pos_h. +

+
+
in_t, t
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
out_t, ot
+

The input frame timestamp, in seconds. NAN if input timestamp is unknown. +

+
+
n
+

The input frame number, starting with 0. +

+
+ + +

32.144.1.2 Scaling

+

The options in this section control how libplacebo performs upscaling and (if +necessary) downscaling. Note that libplacebo will always internally operate on +4:4:4 content, so any sub-sampled chroma formats such as yuv420p will +necessarily be upsampled and downsampled as part of the rendering process. That +means scaling might be in effect even if the source and destination resolution +are the same. +

+
upscaler
+
downscaler
+

Configure the filter kernel used for upscaling and downscaling. The respective +defaults are spline36 and mitchell. For a full list of possible +values, pass help to these options. The most important values are: +

+
‘none’
+

Forces the use of built-in GPU texture sampling (typically bilinear). Extremely +fast but poor quality, especially when downscaling. +

+
+
‘bilinear’
+

Bilinear interpolation. Can generally be done for free on GPUs, except when +doing so would lead to aliasing. Fast and low quality. +

+
+
‘nearest’
+

Nearest-neighbour interpolation. Sharp but highly aliasing. +

+
+
‘oversample’
+

Algorithm that looks visually similar to nearest-neighbour interpolation but +tries to preserve pixel aspect ratio. Good for pixel art, since it results in +minimal distortion of the artistic appearance. +

+
+
‘lanczos’
+

Standard sinc-sinc interpolation kernel. +

+
+
‘spline36’
+

Cubic spline approximation of lanczos. No difference in performance, but has +very slightly less ringing. +

+
+
‘ewa_lanczos’
+

Elliptically weighted average version of lanczos, based on a jinc-jinc kernel. +This is also popularly referred to as just "Jinc scaling". Slow but very high +quality. +

+
+
‘gaussian’
+

Gaussian kernel. Has certain ideal mathematical properties, but subjectively +very blurry. +

+
+
‘mitchell’
+

Cubic BC spline with parameters recommended by Mitchell and Netravali. Very +little ringing. +

+
+ +
+
frame_mixer
+

Controls the kernel used for mixing frames temporally. The default value is +none, which disables frame mixing. For a full list of possible values, +pass help to this option. The most important values are: +

+
‘none’
+

Disables frame mixing, giving a result equivalent to "nearest neighbour" +semantics. +

+
+
‘oversample’
+

Oversamples the input video to create a "Smooth Motion"-type effect: if an +output frame would exactly fall on the transition between two video frames, it +is blended according to the relative overlap. This is the recommended option +whenever preserving the original subjective appearance is desired. +

+
+
‘mitchell_clamp’
+

Larger filter kernel that smoothly interpolates multiple frames in a manner +designed to eliminate ringing and other artefacts as much as possible. This is +the recommended option wherever maximum visual smoothness is desired. +

+
+
‘linear’
+

Linear blend/fade between frames. Especially useful for constructing e.g. +slideshows. +

+
+ +
+
antiringing
+

Enables anti-ringing (for non-EWA filters). The value (between 0.0 and +1.0) configures the strength of the anti-ringing algorithm. May increase +aliasing if set too high. Disabled by default. +

+
+
sigmoid
+

Enable sigmoidal compression during upscaling. Reduces ringing slightly. +Enabled by default. +

+
+ + +

32.144.1.3 Deinterlacing

+

Deinterlacing is automatically supported when frames are tagged as interlaced, +however frames are not deinterlaced unless a deinterlacing algorithm is chosen. +

+
deinterlace
+

The the deinterlacing algorithm to use. +

+
‘weave’
+

No deinterlacing, weave fields together into a single frame. This is the default. +

+
‘bob’
+

Naive bob deinterlacing, simply repeat each field line twice. +

+
‘yadif’
+

Yet another deinterlacing filter. See the yadif filter for more details. +

+
‘bwdif’
+

Bob weaver deinterlacing filter. See the bwdif filter for more details. +

+
+ +
+
skip_spatial_check
+

Skip the spatial deinterlacing check when using yadif deinterlacing. +

+
+
send_fields
+

Output a frame for each field, rather than for each frame. Note that this will +always double the tagged output frame rate, even if the input does not contain +any interlaced frames. Disabled by default. +

+
+ + +

32.144.1.4 Debanding

+

Libplacebo comes with a built-in debanding filter that is good at counteracting +many common sources of banding and blocking. Turning this on is highly +recommended whenever quality is desired. +

+
deband
+

Enable (fast) debanding algorithm. Disabled by default. +

+
+
deband_iterations
+

Number of deband iterations of the debanding algorithm. Each iteration is +performed with progressively increased radius (and diminished threshold). +Recommended values are in the range 1 to 4. Defaults to 1. +

+
+
deband_threshold
+

Debanding filter strength. Higher numbers lead to more aggressive debanding. +Defaults to 4.0. +

+
+
deband_radius
+

Debanding filter radius. A higher radius is better for slow gradients, while +a lower radius is better for steep gradients. Defaults to 16.0. +

+
+
deband_grain
+

Amount of extra output grain to add. Helps hide imperfections. Defaults to +6.0. +

+
+ + +

32.144.1.5 Color adjustment

+

A collection of subjective color controls. Not very rigorous, so the exact +effect will vary somewhat depending on the input primaries and colorspace. +

+
brightness
+

Brightness boost, between -1.0 and 1.0. Defaults to 0.0. +

+
+
contrast
+

Contrast gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
saturation
+

Saturation gain, between 0.0 and 16.0. Defaults to 1.0. +

+
+
hue
+

Hue shift in radians, between -3.14 and 3.14. Defaults to +0.0. This will rotate the UV subvector, defaulting to BT.709 +coefficients for RGB inputs. +

+
+
gamma
+

Gamma adjustment, between 0.0 and 16.0. Defaults to 1.0. +

+
+
temperature
+

Color temperature adjustment. Lower values make the output warmer/redder, +down to 1667, while higher values make the output cooler/bluer, up to +25000. Defaults to 6500 (neutral white). +

+
+
cones
+

Cone model to use for color blindness simulation. Accepts any combination of +l, m and s. Here are some examples: +

+
‘m’
+

Deuteranomaly / deuteranopia (affecting 3%-4% of the population) +

+
‘l’
+

Protanomaly / protanopia (affecting 1%-2% of the population) +

+
‘l+m’
+

Monochromacy (very rare) +

+
‘l+m+s’
+

Achromatopsy (complete loss of daytime vision, extremely rare) +

+
+ +
+
cone-strength
+

Gain factor for the cones specified by cones, between 0.0 and +10.0. A value of 1.0 results in no change to color vision. A +value of 0.0 (the default) simulates complete loss of those cones. Values +above 1.0 result in exaggerating the differences between cones, which +may help compensate for reduced color vision. +

+
+ + +

32.144.1.6 Peak detection

+

To help deal with sources that only have static HDR10 metadata (or no tagging +whatsoever), libplacebo uses its own internal frame analysis compute shader to +analyze source frames and adapt the tone mapping function in realtime. If this +is too slow, or if exactly reproducible frame-perfect results are needed, it’s +recommended to turn this feature off. +

+
peak_detect
+

Enable HDR peak detection. Ignores static MaxCLL/MaxFALL values in favor of +dynamic detection from the input. Note that the detected values do not get +written back to the output frames, they merely guide the internal tone mapping +process. Enabled by default. +

+
+
smoothing_period
+

Peak detection smoothing period, between 0.0 and 1000.0. Higher +values result in peak detection becoming less responsive to changes in the +input. Defaults to 20.0. +

+
+
scene_threshold_low
+
scene_threshold_high
+

Lower and upper thresholds for scene change detection. Expressed in a +logarithmic scale between 0.0 and 100.0. Default to 1.0 +and 3.0, respectively. Setting either to a negative value disables +this functionality. +

+
+
percentile
+

Which percentile of the frame brightness histogram to use as the source peak +for tone-mapping. Defaults to 99.995, a fairly conservative value. +Setting this to 100.0 disables frame histogram measurement and instead +uses the true peak brightness for tone-mapping. +

+
+ + +

32.144.1.7 Tone mapping

+

The options in this section control how libplacebo performs tone-mapping and +gamut-mapping when dealing with mismatches between wide-gamut or HDR content. +In general, libplacebo relies on accurate source tagging and mastering display +gamut information to produce the best results. +

+
gamut_mode
+

How to handle out-of-gamut colors that can occur as a result of colorimetric +gamut mapping. +

+
‘clip’
+

Do nothing, simply clip out-of-range colors to the RGB volume. Low quality but +extremely fast. +

+
‘perceptual’
+

Perceptually soft-clip colors to the gamut volume. This is the default. +

+
‘relative’
+

Relative colorimetric hard-clip. Similar to perceptual but without +the soft knee. +

+
‘saturation’
+

Saturation mapping, maps primaries directly to primaries in RGB space. +Not recommended except for artificial computer graphics for which a bright, +saturated display is desired. +

+
‘absolute’
+

Absolute colorimetric hard-clip. Performs no adjustment of the white point. +

+
‘desaturate’
+

Hard-desaturates out-of-gamut colors towards white, while preserving the +luminance. Has a tendency to distort the visual appearance of bright objects. +

+
‘darken’
+

Linearly reduces content brightness to preserves saturated details, followed by +clipping the remaining out-of-gamut colors. +

+
‘warn’
+

Highlight out-of-gamut pixels (by inverting/marking them). +

+
‘linear’
+

Linearly reduces chromaticity of the entire image to make it fit within the +target color volume. Be careful when using this on BT.2020 sources without +proper mastering metadata, as doing so will lead to excessive desaturation. +

+
+ +
+
tonemapping
+

Tone-mapping algorithm to use. Available values are: +

+
‘auto’
+

Automatic selection based on internal heuristics. This is the default. +

+
‘clip’
+

Performs no tone-mapping, just clips out-of-range colors. Retains perfect color +accuracy for in-range colors but completely destroys out-of-range information. +Does not perform any black point adaptation. Not configurable. +

+
‘st2094-40’
+

EETF from SMPTE ST 2094-40 Annex B, which applies the Bezier curves from HDR10+ +dynamic metadata based on Bezier curves to perform tone-mapping. The OOTF used +is adjusted based on the ratio between the targeted and actual display peak +luminances. +

+
‘st2094-10’
+

EETF from SMPTE ST 2094-10 Annex B.2, which takes into account the input signal +average luminance in addition to the maximum/minimum. The configurable contrast +parameter influences the slope of the linear output segment, defaulting to +1.0 for no increase/decrease in contrast. Note that this does not +currently include the subjective gain/offset/gamma controls defined in Annex +B.3. +

+
‘bt.2390’
+

EETF from the ITU-R Report BT.2390, a hermite spline roll-off with linear +segment. The knee point offset is configurable. Note that this parameter +defaults to 1.0, rather than the value of 0.5 from the ITU-R +spec. +

+
‘bt.2446a’
+

EETF from ITU-R Report BT.2446, method A. Designed for well-mastered HDR +sources. Can be used for both forward and inverse tone mapping. Not +configurable. +

+
‘spline’
+

Simple spline consisting of two polynomials, joined by a single pivot point. +The parameter gives the pivot point (in PQ space), defaulting to 0.30. +Can be used for both forward and inverse tone mapping. +

+
‘reinhard’
+

Simple non-linear, global tone mapping algorithm. The parameter specifies the +local contrast coefficient at the display peak. Essentially, a parameter of +0.5 implies that the reference white will be about half as bright as +when clipping. Defaults to 0.5, which results in the simplest +formulation of this function. +

+
‘mobius’
+

Generalization of the reinhard tone mapping algorithm to support an additional +linear slope near black. The tone mapping parameter indicates the trade-off +between the linear section and the non-linear section. Essentially, for a given +parameter x, every color value below x will be mapped linearly, +while higher values get non-linearly tone-mapped. Values near 1.0 make +this curve behave like clip, while values near 0.0 make this +curve behave like reinhard. The default value is 0.3, which +provides a good balance between colorimetric accuracy and preserving +out-of-gamut details. +

+
‘hable’
+

Piece-wise, filmic tone-mapping algorithm developed by John Hable for use in +Uncharted 2, inspired by a similar tone-mapping algorithm used by Kodak. +Popularized by its use in video games with HDR rendering. Preserves both dark +and bright details very well, but comes with the drawback of changing the +average brightness quite significantly. This is sort of similar to +reinhard with parameter 0.24. +

+
‘gamma’
+

Fits a gamma (power) function to transfer between the source and target color +spaces, effectively resulting in a perceptual hard-knee joining two roughly +linear sections. This preserves details at all scales fairly accurately, but +can result in an image with a muted or dull appearance. The parameter is used +as the cutoff point, defaulting to 0.5. +

+
‘linear’
+

Linearly stretches the input range to the output range, in PQ space. This will +preserve all details accurately, but results in a significantly different +average brightness. Can be used for inverse tone-mapping in addition to regular +tone-mapping. The parameter can be used as an additional linear gain +coefficient (defaulting to 1.0). +

+
+ +
+
tonemapping_param
+

For tunable tone mapping functions, this parameter can be used to fine-tune the +curve behavior. Refer to the documentation of tonemapping. The default +value of 0.0 is replaced by the curve’s preferred default setting. +

+
+
inverse_tonemapping
+

If enabled, this filter will also attempt stretching SDR signals to fill HDR +output color volumes. Disabled by default. +

+
+
tonemapping_lut_size
+

Size of the tone-mapping LUT, between 2 and 1024. Defaults to +256. Note that this figure is squared when combined with +peak_detect. +

+
+
contrast_recovery
+

Contrast recovery strength. If set to a value above 0.0, the source +image will be divided into high-frequency and low-frequency components, and a +portion of the high-frequency image is added back onto the tone-mapped output. +May cause excessive ringing artifacts for some HDR sources, but can improve the +subjective sharpness and detail left over in the image after tone-mapping. +Defaults to 0.30. +

+
+
contrast_smoothness
+

Contrast recovery lowpass kernel size. Defaults to 3.5. Increasing or +decreasing this will affect the visual appearance substantially. Has no effect +when contrast_recovery is disabled. +

+
+ + +

32.144.1.8 Dithering

+

By default, libplacebo will dither whenever necessary, which includes rendering +to any integer format below 16-bit precision. It’s recommended to always leave +this on, since not doing so may result in visible banding in the output, even +if the debanding filter is enabled. If maximum performance is needed, +use ordered_fixed instead of disabling dithering. +

+
dithering
+

Dithering method to use. Accepts the following values: +

+
‘none’
+

Disables dithering completely. May result in visible banding. +

+
‘blue’
+

Dither with pseudo-blue noise. This is the default. +

+
‘ordered’
+

Tunable ordered dither pattern. +

+
‘ordered_fixed’
+

Faster ordered dither with a fixed size of 6. Texture-less. +

+
‘white’
+

Dither with white noise. Texture-less. +

+
+ +
+
dither_lut_size
+

Dither LUT size, as log base2 between 1 and 8. Defaults to +6, corresponding to a LUT size of 64x64. +

+
+
dither_temporal
+

Enables temporal dithering. Disabled by default. +

+
+ + +

32.144.1.9 Custom shaders

+

libplacebo supports a number of custom shaders based on the mpv .hook GLSL +syntax. A collection of such shaders can be found here: +https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders +

+

A full description of the mpv shader format is beyond the scope of this +section, but a summary can be found here: +https://mpv.io/manual/master/#options-glsl-shader +

+
custom_shader_path
+

Specifies a path to a custom shader file to load at runtime. +

+
+
custom_shader_bin
+

Specifies a complete custom shader as a raw string. +

+
+ + +

32.144.1.10 Debugging / performance

+

All of the options in this section default off. They may be of assistance when +attempting to squeeze the maximum performance at the cost of quality. +

+
skip_aa
+

Disable anti-aliasing when downscaling. +

+
+
disable_linear
+

Disable linear light scaling. +

+
+
disable_builtin
+

Disable built-in GPU sampling (forces LUT). +

+
+
disable_fbos
+

Forcibly disable FBOs, resulting in loss of almost all functionality, but +offering the maximum possible speed. +

+
+ + +

32.144.2 Commands

+

This filter supports almost all of the above options as commands. +

+ +

32.144.3 Examples

+
    +
  • Tone-map input to standard gamut BT.709 output: +
    +
    libplacebo=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv
    +
    + +
  • Rescale input to fit into standard 1080p, with high quality scaling: +
    +
    libplacebo=w=1920:h=1080:force_original_aspect_ratio=decrease:normalize_sar=true:upscaler=ewa_lanczos:downscaler=ewa_lanczos
    +
    + +
  • Interpolate low FPS / VFR input to smoothed constant 60 fps output: +
    +
    libplacebo=fps=60:frame_mixer=mitchell_clamp
    +
    + +
  • Convert input to standard sRGB JPEG: +
    +
    libplacebo=format=yuv420p:colorspace=bt470bg:color_primaries=bt709:color_trc=iec61966-2-1:range=pc
    +
    + +
  • Use higher quality debanding settings: +
    +
    libplacebo=deband=true:deband_iterations=3:deband_radius=8:deband_threshold=6
    +
    + +
  • Run this filter on the CPU, on systems with Mesa installed (and with the most +expensive options disabled): +
    +
    ffmpeg ... -init_hw_device vulkan:llvmpipe ... -vf libplacebo=upscaler=none:downscaler=none:peak_detect=false
    +
    + +
  • Suppress CPU-based AV1/H.274 film grain application in the decoder, in favor of +doing it with this filter. Note that this is only a gain if the frames are +either already on the GPU, or if you’re using libplacebo for other purposes, +since otherwise the VRAM roundtrip will more than offset any expected speedup. +
    +
    ffmpeg -export_side_data +film_grain ... -vf libplacebo=apply_filmgrain=true
    +
    + +
  • Interop with VAAPI hwdec to avoid round-tripping through RAM: +
    +
    ffmpeg -init_hw_device vulkan -hwaccel vaapi -hwaccel_output_format vaapi ... -vf libplacebo
    +
    +
+ + +

32.145 libvmaf

+ +

Calculate the VMAF (Video Multi-Method Assessment Fusion) score for a +reference/distorted pair of input videos. +

+

The first input is the distorted video, and the second input is the reference video. +

+

The obtained VMAF score is printed through the logging system. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-libvmaf. +

+

The filter has following options: +

+
+
model
+

A ‘|‘ delimited list of vmaf models. Each model can be configured with a number of parameters. +Default value: "version=vmaf_v0.6.1" +

+
+
feature
+

A ‘|‘ delimited list of features. Each feature can be configured with a number of parameters. +

+
+
log_path
+

Set the file path to be used to store log files. +

+
+
log_fmt
+

Set the format of the log file (xml, json, csv, or sub). +

+
+
pool
+

Set the pool method to be used for computing vmaf. +Options are min, harmonic_mean or mean (default). +

+
+
n_threads
+

Set number of threads to be used when initializing libvmaf. +Default value: 0, no threads. +

+
+
n_subsample
+

Set frame subsampling interval to be used. +

+
+ +

This filter also supports the framesync options. +

+ +

32.145.1 Examples

+
    +
  • In the examples below, a distorted video distorted.mpg is +compared with a reference file reference.mpg. + +
  • Basic usage: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf=log_path=output.xml -f null -
    +
    + +
  • Example with multiple models: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='model=version=vmaf_v0.6.1\\:name=vmaf|version=vmaf_v0.6.1neg\\:name=vmaf_neg' -f null -
    +
    + +
  • Example with multiple additional features: +
    +
    ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr|name=ciede' -f null -
    +
    + +
  • Example with options and different containers: +
    +
    ffmpeg -i distorted.mpg -i reference.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=log_fmt=json:log_path=output.json" -f null -
    +
    +
+ + +

32.146 libvmaf_cuda

+ +

This is the CUDA variant of the libvmaf filter. It only accepts CUDA frames. +

+

It requires Netflix’s vmaf library (libvmaf) as a pre-requisite. +After installing the library it can be enabled using: +./configure --enable-nonfree --enable-ffnvcodec --enable-libvmaf. +

+ +

32.146.1 Examples

+
    +
  • Basic usage showing CUVID hardware decoding and CUDA scaling with scale_cuda: +
    +
    ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i dis.obu \
    +    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i ref.obu \
    +    -filter_complex "
    +        [0:v]scale_cuda=format=yuv420p[dis]; \
    +        [1:v]scale_cuda=format=yuv420p[ref]; \
    +        [dis][ref]libvmaf_cuda=log_fmt=json:log_path=output.json
    +    " \
    +    -f null -
    +
    +
+ + +

32.147 limitdiff

+

Apply limited difference filter using second and optionally third video stream. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the threshold to use when allowing certain differences between video streams. +Any absolute difference value lower or exact than this threshold will pick pixel components from +first video stream. +

+
+
elasticity
+

Set the elasticity of soft thresholding when processing video streams. +This value multiplied with first one sets second threshold. +Any absolute difference value greater or exact than second threshold will pick pixel components +from second video stream. For values between those two threshold +linear interpolation between first and second video stream will be used. +

+
+
reference
+

Enable the reference (third) video stream processing. By default is disabled. +If set, this video stream will be used for calculating absolute difference with first video +stream. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

32.147.1 Commands

+ +

This filter supports the all above options as commands except option ‘reference’. +

+ +

32.148 limiter

+ +

Limits the pixel components values to the specified range [min, max]. +

+

The filter accepts the following options: +

+
+
min
+

Lower bound. Defaults to the lowest allowed value for the input. +

+
+
max
+

Upper bound. Defaults to the highest allowed value for the input. +

+
+
planes
+

Specify which planes will be processed. Defaults to all available. +

+
+ + +

32.148.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.149 loop

+ +

Loop video frames. +

+

The filter accepts the following options: +

+
+
loop
+

Set the number of loops. Setting this value to -1 will result in infinite loops. +Default is 0. +

+
+
size
+

Set maximal size in number of frames. Default is 0. +

+
+
start
+

Set first frame of loop. Default is 0. +

+
+
time
+

Set the time of loop start in seconds. +Only used if option named start is set to -1. +

+
+ + +

32.149.1 Examples

+ +
    +
  • Loop single first frame infinitely: +
    +
    loop=loop=-1:size=1:start=0
    +
    + +
  • Loop single first frame 10 times: +
    +
    loop=loop=10:size=1:start=0
    +
    + +
  • Loop 10 first frames 5 times: +
    +
    loop=loop=5:size=10:start=0
    +
    +
+ + +

32.150 lut1d

+ +

Apply a 1D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 1D LUT file name. +

+

Currently supported formats: +

+
‘cube’
+

Iridas +

+
‘csp’
+

cineSpace +

+
+ +
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘linear’
+

Interpolate values using the linear interpolation. +

+
‘cosine’
+

Interpolate values using the cosine interpolation. +

+
‘cubic’
+

Interpolate values using the cubic interpolation. +

+
‘spline’
+

Interpolate values using the spline interpolation. +

+
+
+
+ + +

32.150.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.151 lut3d

+ +

Apply a 3D LUT to an input video. +

+

The filter accepts the following options: +

+
+
file
+

Set the 3D LUT file name. +

+

Currently supported formats: +

+
‘3dl’
+

AfterEffects +

+
‘cube’
+

Iridas +

+
‘dat’
+

DaVinci +

+
‘m3d’
+

Pandora +

+
‘csp’
+

cineSpace +

+
+
+
interp
+

Select interpolation mode. +

+

Available values are: +

+
+
‘nearest’
+

Use values from the nearest defined point. +

+
‘trilinear’
+

Interpolate values using the 8 points defining a cube. +

+
‘tetrahedral’
+

Interpolate values using a tetrahedron. +

+
‘pyramid’
+

Interpolate values using a pyramid. +

+
‘prism’
+

Interpolate values using a prism. +

+
+
+
+ + +

32.151.1 Commands

+ +

This filter supports the interp option as commands. +

+ +

32.152 lumakey

+ +

Turn certain luma values into transparency. +

+

The filter accepts the following options: +

+
+
threshold
+

Set the luma which will be used as base for transparency. +Default value is 0. +

+
+
tolerance
+

Set the range of luma values to be keyed out. +Default value is 0.01. +

+
+
softness
+

Set the range of softness. Default value is 0. +Use this to control gradual transition from zero to full transparency. +

+
+ + +

32.152.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.153 lut, lutrgb, lutyuv

+ +

Compute a look-up table for binding each pixel component input value +to an output value, and apply it to the input video. +

+

lutyuv applies a lookup table to a YUV input video, lutrgb +to an RGB input video. +

+

These filters accept the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
r
+

set red component expression +

+
g
+

set green component expression +

+
b
+

set blue component expression +

+
a
+

alpha component expression +

+
+
y
+

set Y/luma component expression +

+
u
+

set U/Cb component expression +

+
v
+

set V/Cr component expression +

+
+ +

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 c* options depends on the +format in input. +

+

The lut filter requires either YUV or RGB pixel formats in input, +lutrgb requires RGB pixel formats in input, and lutyuv requires YUV. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
clipval
+

The input value, clipped to the minval-maxval range. +

+
+
maxval
+

The maximum value for the pixel component. +

+
+
minval
+

The minimum value for the pixel component. +

+
+
negval
+

The negated value for the pixel component value, clipped to the +minval-maxval range; it corresponds to the expression +"maxval-clipval+minval". +

+
+
clip(val)
+

The computed value in val, clipped to the +minval-maxval range. +

+
+
gammaval(gamma)
+

The computed gamma correction value of the pixel component value, +clipped to the minval-maxval range. It corresponds to the +expression +"pow((clipval-minval)/(maxval-minval)\,gamma)*(maxval-minval)+minval" +

+
+
+ +

All expressions default to "clipval". +

+ +

32.153.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.153.2 Examples

+ +
    +
  • Negate input video: +
    +
    lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
    +lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
    +
    + +

    The above is the same as: +

    +
    lutrgb="r=negval:g=negval:b=negval"
    +lutyuv="y=negval:u=negval:v=negval"
    +
    + +
  • Negate luma: +
    +
    lutyuv=y=negval
    +
    + +
  • Remove chroma components, turning the video into a graytone image: +
    +
    lutyuv="u=128:v=128"
    +
    + +
  • Apply a luma burning effect: +
    +
    lutyuv="y=2*val"
    +
    + +
  • Remove green and blue components: +
    +
    lutrgb="g=0:b=0"
    +
    + +
  • Set a constant alpha channel value on input: +
    +
    format=rgba,lutrgb=a="maxval-minval/2"
    +
    + +
  • Correct luma gamma by a factor of 0.5: +
    +
    lutyuv=y=gammaval(0.5)
    +
    + +
  • Discard least significant bits of luma: +
    +
    lutyuv=y='bitand(val, 128+64+32)'
    +
    + +
  • Technicolor like effect: +
    +
    lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
    +
    +
+ + +

32.154 lut2, tlut2

+ +

The lut2 filter takes two input streams and outputs one +stream. +

+

The tlut2 (time lut2) filter takes two consecutive frames +from one single stream. +

+

This filter accepts the following parameters: +

+
c0
+

set first pixel component expression +

+
c1
+

set second pixel component expression +

+
c2
+

set third pixel component expression +

+
c3
+

set fourth pixel component expression, corresponds to the alpha component +

+
+
d
+

set output bit depth, only available for lut2 filter. By default is 0, +which means bit depth is automatically picked from first input format. +

+
+ +

The lut2 filter also supports the framesync options. +

+

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 c* options depends on the +format in inputs. +

+

The expressions can contain the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
x
+

The first input value for the pixel component. +

+
+
y
+

The second input value for the pixel component. +

+
+
bdx
+

The first input video bit depth. +

+
+
bdy
+

The second input video bit depth. +

+
+ +

All expressions default to "x". +

+ +

32.154.1 Commands

+ +

This filter supports the all above options as commands except option d. +

+ +

32.154.2 Examples

+ +
    +
  • Highlight differences between two RGB video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'
    +
    + +
  • Highlight differences between two YUV video streams: +
    +
    lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'
    +
    + +
  • Show max difference between two video streams: +
    +
    lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'
    +
    +
+ + +

32.155 maskedclamp

+ +

Clamp the first input stream with the second input and third input stream. +

+

Returns the value of first stream to be between second input +stream - undershoot and third input stream + overshoot. +

+

This filter accepts the following options: +

+
undershoot
+

Default value is 0. +

+
+
overshoot
+

Default value is 0. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

32.155.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.156 maskedmax

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is greater than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

32.156.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.157 maskedmerge

+ +

Merge the first input stream with the second input stream using per pixel +weights in the third input stream. +

+

A value of 0 in the third stream pixel component means that pixel component +from first stream is returned unchanged, while maximum value (eg. 255 for +8-bit videos) means that pixel component from second stream is returned +unchanged. Intermediate values define the amount of merging between both +input stream’s pixel components. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

32.157.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.158 maskedmin

+ +

Merge the second and third input stream into output stream using absolute differences +between second input stream and first input stream and absolute difference between +third input stream and first input stream. The picked value will be from second input +stream if second absolute difference is less than first one or from third input stream +otherwise. +

+

This filter accepts the following options: +

+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from first stream. +By default value 0xf, all planes will be processed. +

+
+ + +

32.158.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.159 maskedthreshold

+

Pick pixels comparing absolute difference of two video streams with fixed +threshold. +

+

If absolute difference between pixel component of first and second video +stream is equal or lower than user supplied threshold than pixel component +from first video stream is picked, otherwise pixel component from second +video stream is picked. +

+

This filter accepts the following options: +

+
threshold
+

Set threshold used when picking pixels from absolute difference from two input +video streams. +

+
+
planes
+

Set which planes will be processed as bitmap, unprocessed planes will be +copied from second stream. +By default value 0xf, all planes will be processed. +

+
+
mode
+

Set mode of filter operation. Can be abs or diff. +Default is abs. +

+
+ + +

32.159.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.160 maskfun

+

Create mask from input video. +

+

For example it is useful to create motion masks after tblend filter. +

+

This filter accepts the following options: +

+
+
low
+

Set low threshold. Any pixel component lower or exact than this value will be set to 0. +

+
+
high
+

Set high threshold. Any pixel component higher than this value will be set to max value +allowed for current pixel format. +

+
+
planes
+

Set planes to filter, by default all available planes are filtered. +

+
+
fill
+

Fill all frame pixels with this value. +

+
+
sum
+

Set max average pixel value for frame. If sum of all pixel components is higher that this +average, output frame will be completely filled with value set by fill option. +Typically useful for scene changes when used in combination with tblend filter. +

+
+ + +

32.160.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.161 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: +

+
mode
+

Set the deinterlacing mode. +

+

It accepts one of the following values: +

+
‘fast’
+
‘medium’
+
‘slow’
+

use iterative motion estimation +

+
‘extra_slow’
+

like ‘slow’, but use multiple reference frames. +

+
+

Default value is ‘fast’. +

+
+
parity
+

Set the picture field parity assumed for the input video. It must be +one of the following values: +

+
+
‘0, tff’
+

assume top field first +

+
‘1, bff’
+

assume bottom field first +

+
+ +

Default value is ‘bff’. +

+
+
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. +

+
+ + +

32.162 median

+ +

Pick median pixel from certain rectangle defined by radius. +

+

This filter accepts the following options: +

+
+
radius
+

Set horizontal radius size. Default value is 1. +Allowed range is integer from 1 to 127. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+
radiusV
+

Set vertical radius size. Default value is 0. +Allowed range is integer from 0 to 127. +If it is 0, value will be picked from horizontal radius option. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

32.162.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.163 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: +

+
mapping
+

Set input to output plane mapping. Default is 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. +

+
+
format
+

Set output pixel format. Default is yuva444p. +

+
+
map0s
+
map1s
+
map2s
+
map3s
+

Set input to output stream mapping for output Nth plane. Default is 0. +

+
+
map0p
+
map1p
+
map2p
+
map3p
+

Set input to output plane mapping for output Nth plane. Default is 0. +

+
+ + +

32.163.1 Examples

+ +
    +
  • Merge three gray video streams of same width and height into single video stream: +
    +
    [a0][a1][a2]mergeplanes=0x001020:yuv444p
    +
    + +
  • Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: +
    +
    [a0][a1]mergeplanes=0x00010210:yuva444p
    +
    + +
  • Swap Y and A plane in yuva444p stream: +
    +
    format=yuva444p,mergeplanes=0x03010200:yuva444p
    +
    + +
  • Swap U and V plane in yuv420p stream: +
    +
    format=yuv420p,mergeplanes=0x000201:yuv420p
    +
    + +
  • Cast a rgb24 clip to yuv444p: +
    +
    format=rgb24,mergeplanes=0x000102:yuv444p
    +
    +
+ + +

32.164 mestimate

+ +

Estimate and export motion vectors using block matching algorithms. +Motion vectors are stored in frame side data to be used by other filters. +

+

This filter accepts the following options: +

+
method
+

Specify the motion estimation method. Accepts one of the following values: +

+
+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default value is ‘esa’. +

+
+
mb_size
+

Macroblock size. Default 16. +

+
+
search_param
+

Search parameter. Default 7. +

+
+ + +

32.165 mestimate_d3d12

+ +

Estimate and export motion vectors using D3D12 hardware-accelerated motion estimation. +This filter uses GPU hardware motion estimation capabilities available in +DirectX 12 Video APIs to achieve significant performance improvements +over the software-based mestimate filter. +

+

Motion vectors are stored in frame side data to be used by other filters. +

+

This filter requires the input to be in d3d12 hardware pixel format. +The filter uses quarter-pixel precision for motion vector estimation. +

+

This filter accepts the following options: +

+
mb_size
+

Macroblock size. Only 8 and 16 are supported. +Default 16. +

+
+ + +

32.165.1 Examples

+ +

Estimate motion vectors using D3D12 hardware acceleration with 16x16 blocks, +and visualize them: +

+
ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.mp4 \
+        -vf mestimate_d3d12=mb_size=16,hwdownload,format=nv12,codecview=mv=pf \
+        -c:v libx264 -preset fast -b:v 5M output.mp4
+
+ + +

32.166 midequalizer

+ +

Apply Midway Image Equalization effect using two video streams. +

+

Midway Image Equalization adjusts a pair of images to have the same +histogram, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a pair of stereo cameras. +

+

This filter has two inputs and one output, which must be of same pixel format, but +may be of different sizes. The output of filter is first input adjusted with +midway histogram of both inputs. +

+

This filter accepts the following option: +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

32.167 minterpolate

+ +

Convert the video to specified frame rate using motion interpolation. +

+

This filter accepts the following options: +

+
fps
+

Specify the output frame rate. This can be rational e.g. 60000/1001. Frames are dropped if fps is lower than source fps. Default 60. +

+
+
mi_mode
+

Motion interpolation mode. Following values are accepted: +

+
‘dup’
+

Duplicate previous or next frame for interpolating new ones. +

+
‘blend’
+

Blend source frames. Interpolated frame is mean of previous and next frames. +

+
‘mci’
+

Motion compensated interpolation. Following options are effective when this mode is selected: +

+
+
‘mc_mode’
+

Motion compensation mode. Following values are accepted: +

+
‘obmc’
+

Overlapped block motion compensation. +

+
‘aobmc’
+

Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. +

+
+

Default mode is ‘obmc’. +

+
+
‘me_mode’
+

Motion estimation mode. Following values are accepted: +

+
‘bidir’
+

Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. +

+
‘bilat’
+

Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. +

+
+

Default mode is ‘bilat’. +

+
+
‘me’
+

The algorithm to be used for motion estimation. Following values are accepted: +

+
‘esa’
+

Exhaustive search algorithm. +

+
‘tss’
+

Three step search algorithm. +

+
‘tdls’
+

Two dimensional logarithmic search algorithm. +

+
‘ntss’
+

New three step search algorithm. +

+
‘fss’
+

Four step search algorithm. +

+
‘ds’
+

Diamond search algorithm. +

+
‘hexbs’
+

Hexagon-based search algorithm. +

+
‘epzs’
+

Enhanced predictive zonal search algorithm. +

+
‘umh’
+

Uneven multi-hexagon search algorithm. +

+
+

Default algorithm is ‘epzs’. +

+
+
‘mb_size’
+

Macroblock size. Default 16. +

+
+
‘search_param’
+

Motion estimation search parameter. Default 32. +

+
+
‘vsbmc’
+

Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make them less blurry. Default is 0 (disabled). +

+
+
+
+ +
+
scd
+

Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted: +

+
‘none’
+

Disable scene change detection. +

+
‘fdiff’
+

Frame difference. Corresponding pixel values are compared and if it satisfies scd_threshold scene change is detected. +

+
+

Default method is ‘fdiff’. +

+
+
scd_threshold
+

Scene change detection threshold. Default is 10.. +

+
+ + +

32.168 mix

+ +

Mix several video input streams into one video stream. +

+

A description of the accepted options follows. +

+
+
inputs
+

The number of inputs. If unspecified, it defaults to 2. +

+
+
weights
+

Specify weight of each input video stream as sequence. +Each weight is separated by space. If number of weights +is smaller than number of frames last specified +weight will be used for all remaining unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+
duration
+

Specify how end of stream is determined. +

+
‘longest’
+

The duration of the longest input. (default) +

+
+
‘shortest’
+

The duration of the shortest input. +

+
+
‘first’
+

The duration of the first input. +

+
+
+
+ + +

32.168.1 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

32.169 monochrome

+

Convert video to gray using custom color filter. +

+

A description of the accepted options follows. +

+
+
cb
+

Set the chroma blue spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
cr
+

Set the chroma red spot. Allowed range is from -1 to 1. +Default value is 0. +

+
+
size
+

Set the color filter size. Allowed range is from .1 to 10. +Default value is 1. +

+
+
high
+

Set the highlights strength. Allowed range is from 0 to 1. +Default value is 0. +

+
+ + +

32.169.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.170 morpho

+ +

This filter allows to apply main morphological grayscale transforms, +erode and dilate with arbitrary structures set in second input stream. +

+

Unlike naive implementation and much slower performance in erosion +and dilation filters, when speed is critical morpho filter +should be used instead. +

+

A description of accepted options follows, +

+
+
mode
+

Set morphological transform to apply, can be: +

+
+
‘erode’
+
‘dilate’
+
‘open’
+
‘close’
+
‘gradient’
+
‘tophat’
+
‘blackhat’
+
+

Default is erode. +

+
+
planes
+

Set planes to filter, by default all planes except alpha are filtered. +

+
+
structure
+

Set which structure video frames will be processed from second input stream, +can be first or all. Default is all. +

+
+ +

The morpho filter also supports the framesync options. +

+ +

32.170.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.171 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. +

+
+
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 disregarding the +number of previous sequentially dropped frames. +

+

Default value is 0. +

+
+
keep
+

Set the maximum number of consecutive similar frames to ignore before to start dropping them. +If the value is 0, the frame is dropped disregarding the +number of previous sequentially similar frames. +

+

Default value is 0. +

+
+
hi
+
lo
+
frac
+

Set the dropping threshold values. +

+

Values for hi and 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 hi, and if no more than frac blocks (1 +meaning the whole image) differ by more than a threshold of lo. +

+

Default value for hi is 64*12, default value for lo is +64*5, and default value for frac is 0.33. +

+
+ + +

32.172 msad

+ +

Obtain the MSAD (Mean Sum of Absolute Differences) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 per component, average, min and max MSAD is printed through +the logging system. +

+

The filter stores the calculated MSAD of each frame in frame metadata. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi msad -f null -
+
+ + +

32.173 multiply

+

Multiply first video stream pixels values with second video stream pixels values. +

+

The filter accepts the following options: +

+
+
scale
+

Set the scale applied to second video stream. By default is 1. +Allowed range is from 0 to 9. +

+
+
offset
+

Set the offset applied to second video stream. By default is 0.5. +Allowed range is from -1 to 1. +

+
+
planes
+

Specify planes from input video stream that will be processed. +By default all planes are processed. +

+
+ + +

32.173.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.174 negate

+ +

Negate (invert) the input video. +

+

It accepts the following option: +

+
+
components
+

Set components to negate. +

+

Available values for components are: +

+
‘y’
+
‘u’
+
‘v’
+
‘a’
+
‘r’
+
‘g’
+
‘b’
+
+ +
+
negate_alpha
+

With value 1, it negates the alpha component, if present. Default value is 0. +

+
+ + +

32.174.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.175 nlmeans

+ +

Denoise frames using Non-Local Means algorithm. +

+

Each pixel is adjusted by looking for other pixels with similar contexts. This +context similarity is defined by comparing their surrounding patches of size +pxp. Patches are searched in an area of rxr +around the pixel. +

+

Note that the research area defines centers for patches, which means some +patches will be made of pixels outside that research area. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0]. +

+
+
p
+

Set patch size. Default is 7. Must be odd number in range [0, 99]. +

+
+
pc
+

Same as p but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
rc
+

Same as r but for chroma planes. +

+

The default value is 0 and means automatic. +

+
+ + +

32.176 nnedi

+ +

Deinterlace video using neural network edge directed interpolation. +

+

This filter accepts the following options: +

+
+
weights
+

Mandatory option, without binary file filter can not work. +Currently file can be found here: +https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin +

+
+
deint
+

Set which frames to deinterlace, by default it is all. +Can be all or interlaced. +

+
+
field
+

Set mode of operation. +

+

Can be one of the following: +

+
+
‘af’
+

Use frame flags, both fields. +

+
‘a’
+

Use frame flags, single field. +

+
‘t’
+

Use top field only. +

+
‘b’
+

Use bottom field only. +

+
‘tf’
+

Use both fields, top first. +

+
‘bf’
+

Use both fields, bottom first. +

+
+ +
+
planes
+

Set which planes to process, by default filter process all frames. +

+
+
nsize
+

Set size of local neighborhood around each pixel, used by the predictor neural +network. +

+

Can be one of the following: +

+
+
‘s8x6’
+
‘s16x6’
+
‘s32x6’
+
‘s48x6’
+
‘s8x4’
+
‘s16x4’
+
‘s32x4’
+
+ +
+
nns
+

Set the number of neurons in predictor neural network. +Can be one of the following: +

+
+
‘n16’
+
‘n32’
+
‘n64’
+
‘n128’
+
‘n256’
+
+ +
+
qual
+

Controls the number of different neural network predictions that are blended +together to compute the final output value. Can be fast, default or +slow. +

+
+
etype
+

Set which set of weights to use in the predictor. +Can be one of the following: +

+
+
‘a, abs’
+

weights trained to minimize absolute error +

+
‘s, mse’
+

weights trained to minimize squared error +

+
+ +
+
pscrn
+

Controls whether or not the prescreener neural network is used to decide +which pixels should be processed by the predictor neural network and which +can be handled by simple cubic interpolation. +The prescreener is trained to know whether cubic interpolation will be +sufficient for a pixel or whether it should be predicted by the predictor nn. +The computational complexity of the prescreener nn is much less than that of +the predictor nn. Since most pixels can be handled by cubic interpolation, +using the prescreener generally results in much faster processing. +The prescreener is pretty accurate, so the difference between using it and not +using it is almost always unnoticeable. +

+

Can be one of the following: +

+
+
‘none’
+
‘original’
+
‘new’
+
‘new2’
+
‘new3’
+
+ +

Default is new. +

+
+ + +

32.176.1 Commands

+

This filter supports same commands as options, excluding weights option. +

+ +

32.177 noformat

+ +

Force libavfilter not to use any of the specified pixel formats for the +input to the next filter. +

+

It accepts the following parameters: +

+
pix_fmts
+

A ’|’-separated list of pixel format names, such as +pix_fmts=yuv420p|monow|rgb24". +

+
+
+ + +

32.177.1 Examples

+ +
    +
  • Force libavfilter to use a format different from yuv420p for the +input to the vflip filter: +
    +
    noformat=pix_fmts=yuv420p,vflip
    +
    + +
  • Convert the input video to any of the formats not contained in the list: +
    +
    noformat=yuv420p|yuv444p|yuv410p
    +
    +
+ + +

32.178 noise

+ +

Add noise on video input frame. +

+

The filter accepts the following options: +

+
+
all_seed
+
c0_seed
+
c1_seed
+
c2_seed
+
c3_seed
+

Set noise seed for specific pixel component or all pixel components in case +of all_seed. Default value is 123457. +

+
+
all_strength, alls
+
c0_strength, c0s
+
c1_strength, c1s
+
c2_strength, c2s
+
c3_strength, c3s
+

Set noise strength for specific pixel component or all pixel components in case +all_strength. Default value is 0. Allowed range is [0, 100]. +

+
+
all_flags, allf
+
c0_flags, c0f
+
c1_flags, c1f
+
c2_flags, c2f
+
c3_flags, c3f
+

Set pixel component flags or set flags for all components if all_flags. +Available values for component flags are: +

+
‘a’
+

averaged temporal noise (smoother) +

+
‘p’
+

mix random noise with a (semi)regular pattern +

+
‘t’
+

temporal noise (noise pattern changes between frames) +

+
‘u’
+

uniform noise (gaussian otherwise) +

+
+
+
+ + +

32.178.1 Examples

+ +

Add temporal and uniform noise to input video: +

+
noise=alls=20:allf=t+u
+
+ + +

32.179 normalize

+ +

Normalize RGB video (aka histogram stretching, contrast stretching). +See: https://en.wikipedia.org/wiki/Normalization_(image_processing) +

+

For each channel of each frame, the filter computes the input range and maps +it linearly to the user-specified output range. The output range defaults +to the full dynamic range from pure black to pure white. +

+

Temporal smoothing can be used on the input range to reduce flickering (rapid +changes in brightness) caused when small dark or bright objects enter or leave +the scene. This is similar to the auto-exposure (automatic gain control) on a +video camera, and, like a video camera, it may cause a period of over- or +under-exposure of the video. +

+

The R,G,B channels can be normalized independently, which may cause some +color shifting, or linked together as a single channel, which prevents +color shifting. Linked normalization preserves hue. Independent normalization +does not, so it can be used to remove some color casts. Independent and linked +normalization can be combined in any ratio. +

+

The normalize filter accepts the following options: +

+
+
blackpt
+
whitept
+

Colors which define the output range. The minimum input value is mapped to +the blackpt. The maximum input value is mapped to the whitept. +The defaults are black and white respectively. Specifying white for +blackpt and black for whitept will give color-inverted, +normalized video. Shades of grey can be used to reduce the dynamic range +(contrast). Specifying saturated colors here can create some interesting +effects. +

+
+
smoothing
+

The number of previous frames to use for temporal smoothing. The input range +of each channel is smoothed using a rolling average over the current frame +and the smoothing previous frames. The default is 0 (no temporal +smoothing). +

+
+
independence
+

Controls the ratio of independent (color shifting) channel normalization to +linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully +independent. Defaults to 1.0 (fully independent). +

+
+
strength
+

Overall strength of the filter. 1.0 is full strength. 0.0 is a rather +expensive no-op. Defaults to 1.0 (full strength). +

+
+
+ + +

32.179.1 Commands

+

This filter supports same commands as options, excluding smoothing option. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.179.2 Examples

+ +

Stretch video contrast to use the full dynamic range, with no temporal +smoothing; may flicker depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=0
+
+ +

As above, but with 50 frames of temporal smoothing; flicker should be +reduced, depending on the source content: +

+
normalize=blackpt=black:whitept=white:smoothing=50
+
+ +

As above, but with hue-preserving linked channel normalization: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0
+
+ +

As above, but with half strength: +

+
normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
+
+ +

Map the darkest input color to red, the brightest input color to cyan: +

+
normalize=blackpt=red:whitept=cyan
+
+ + +

32.180 null

+ +

Pass the video source unchanged to the output. +

+ +

32.181 ocio

+

OpenColorIO library filter +

+

This filter allows you to do color management using the OpenColorIO library. +See https://opencolorio.org/ for more details. To Enable +compilation of this filter, you need to configure FFmpeg with --enable-libopencolorio. +

+

It accepts the following options: +

+
+
config
+

By default the filter will use the OCIO config defined by the OCIO environment variable, but this parameter allows you to explicitly specify its location. +If you are getting started, you can use config=ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1 which specifies one of the built in defaults. +

+
+
input
+

Set the input colorspace. +

+
+
output
+

Set the output colorspace. +

+
+
display
+

Set the display colorspace, used in combination with view. +

+
+
view
+

Set the view colorspace, used in combination with display. +

+
+
inverse
+

When used in combination with display and view, this inverts the transform, so going from a display/view to the "input colorspace". +

+
+
filetransform
+

Allows you to specify an external file-transform to use instead of the OCIO config file. This is useful for applying a single transform without needing a full OCIO config file. +

+
+
format
+

Allow you to specify the output pix_fmt of the OCIO filter. This *has* to be a RGB colorspace, so you really are limited to rgb24, rgba, rgb48, rgba48, gbrp10, gbrp12, gbrpf32le, gbrapf32le, for most encoding we would recommend rgb48 +

+
+
context_params
+

Allow you to specify additional context parameters for the OCIO filter. This is a list of key=value pairs, separated by colons. +

+
+
+ + +

32.181.1 Examples

+ +

Map from ACEScg to ACEScct, this assumes the OCIO file is defined with the OCIO environment variable. +

+
input=ACEScg:output=ACEScct:format=rgb48
+
+ +

Map from ACEScg to a sRGB display using the "ACES 1.0 - SDR Video" view transform, this assumes the OCIO file is defined with the OCIO environment variable. Note you will need to wrap the argument in quotes to ensure that the spaces are interpreted correctly. +

+
input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ + +

As above but using the OCIO file studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio rather than the OCIO environment variable. +

+
config=studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio:input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48
+
+ +

If you are converting to YCrCb you still will want to set the color matrix for the conversion. This is a good example of combining the two. +

+
ffmpeg -y -i SOURCEFRAMES.%05d.exr -c:v libx265 -vf "ocio=input=ACEScg:output=ACEScct:format=rgb48,scale=in_color_matrix=bt709:out_color_matrix=bt709,format=yuv444p10"  OUTPUTFILE.mov
+
+ + +

32.182 ocr

+

Optical Character Recognition +

+

This filter uses Tesseract for optical character recognition. To enable +compilation of this filter, you need to configure FFmpeg with +--enable-libtesseract. +

+

It accepts the following options: +

+
+
datapath
+

Set datapath to tesseract data. Default is to use whatever was +set at installation. +

+
+
language
+

Set language, default is "eng". +

+
+
whitelist
+

Set character whitelist. +

+
+
blacklist
+

Set character blacklist. +

+
+ +

The filter exports recognized text as the frame metadata lavfi.ocr.text. +The filter exports confidence of recognized words as the frame metadata lavfi.ocr.confidence. +

+ +

32.183 ocv

+ +

Apply a video transform using libopencv. +

+

To enable this filter, install the libopencv library and headers and +configure FFmpeg with --enable-libopencv. +

+

It accepts the following parameters: +

+
+
filter_name
+

The name of the libopencv filter to apply. +

+
+
filter_params
+

The parameters to pass to the libopencv filter. If not specified, the default +values are assumed. +

+
+
+ +

Refer to the official libopencv documentation for more precise +information: +http://docs.opencv.org/master/modules/imgproc/doc/filtering.html +

+

Several libopencv filters are supported; see the following subsections. +

+ +

32.183.1 dilate

+ +

Dilate an image by using a specific structuring element. +It corresponds to the libopencv function cvDilate. +

+

It accepts the parameters: struct_el|nb_iterations. +

+

struct_el represents a structuring element, and has the syntax: +colsxrows+anchor_xxanchor_y/shape +

+

cols and rows represent the number of columns and rows of +the structuring element, anchor_x and anchor_y the anchor +point, and shape the shape for the structuring element. shape +must be "rect", "cross", "ellipse", or "custom". +

+

If the value for shape is "custom", it must be followed by a +string of the form "=filename". The file with name +filename is assumed to represent a binary image, with each +printable character corresponding to a bright pixel. When a custom +shape is used, cols and rows are ignored, the number +or columns and rows of the read file are assumed instead. +

+

The default value for struct_el is "3x3+0x0/rect". +

+

nb_iterations specifies the number of times the transform is +applied to the image, and defaults to 1. +

+

Some examples: +

+
# Use the default values
+ocv=dilate
+
+# Dilate using a structuring element with a 5x5 cross, iterating two times
+ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
+
+# Read the shape from the file diamond.shape, iterating two times.
+# The file diamond.shape may contain a pattern of characters like this
+#   *
+#  ***
+# *****
+#  ***
+#   *
+# The specified columns and rows are ignored
+# but the anchor point coordinates are not
+ocv=dilate:0x0+2x2/custom=diamond.shape|2
+
+ + +

32.183.2 erode

+ +

Erode an image by using a specific structuring element. +It corresponds to the libopencv function cvErode. +

+

It accepts the parameters: struct_el:nb_iterations, +with the same syntax and semantics as the dilate filter. +

+ +

32.183.3 smooth

+ +

Smooth the input video. +

+

The filter takes the following parameters: +type|param1|param2|param3|param4. +

+

type is the type of smooth filter to apply, and must be one of +the following values: "blur", "blur_no_scale", "median", "gaussian", +or "bilateral". The default value is "gaussian". +

+

The meaning of param1, param2, param3, and param4 +depends on the smooth type. param1 and +param2 accept integer positive values or 0. param3 and +param4 accept floating point values. +

+

The default value for param1 is 3. The default value for the +other parameters is 0. +

+

These parameters correspond to the parameters assigned to the +libopencv function cvSmooth. +

+ +

32.184 oscilloscope

+ +

2D Video Oscilloscope. +

+

Useful to measure spatial impulse, step responses, chroma delays, etc. +

+

It accepts the following parameters: +

+
+
x
+

Set scope center x position. +

+
+
y
+

Set scope center y position. +

+
+
s
+

Set scope size, relative to frame diagonal. +

+
+
t
+

Set scope tilt/rotation. +

+
+
o
+

Set trace opacity. +

+
+
tx
+

Set trace center x position. +

+
+
ty
+

Set trace center y position. +

+
+
tw
+

Set trace width, relative to width of frame. +

+
+
th
+

Set trace height, relative to height of frame. +

+
+
c
+

Set which components to trace. By default it traces first three components. +

+
+
g
+

Draw trace grid. By default is enabled. +

+
+
st
+

Draw some statistics. By default is enabled. +

+
+
sc
+

Draw scope. By default is enabled. +

+
+ + +

32.184.1 Commands

+

This filter supports same commands as options. +The command accepts the same syntax of the corresponding option. +

+

If the specified expression is not valid, it is kept at its current +value. +

+ +

32.184.2 Examples

+ +
    +
  • Inspect full first row of video frame. +
    +
    oscilloscope=x=0.5:y=0:s=1
    +
    + +
  • Inspect full last row of video frame. +
    +
    oscilloscope=x=0.5:y=1:s=1
    +
    + +
  • Inspect full 5th line of video frame of height 1080. +
    +
    oscilloscope=x=0.5:y=5/1080:s=1
    +
    + +
  • Inspect full last column of video frame. +
    +
    oscilloscope=x=1:y=0.5:s=1:t=1
    +
    + +
+ + +

32.185 overlay

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+

A description of the accepted options follows. +

+
+
x
+
y
+

Set the expression for the x and y coordinates of the overlaid video +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). +

+
+
eof_action
+

See framesync. +

+
+
eval
+

Set when the expressions for x, and y are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘frame’. +

+
+
shortest
+

See framesync. +

+
+
format
+

Set the format for the output video. +

+

It accepts the following values: +

+
‘yuv420’
+

force YUV 4:2:0 8-bit planar output +

+
+
‘yuv420p10’
+

force YUV 4:2:0 10-bit planar output +

+
+
‘yuv422’
+

force YUV 4:2:2 8-bit planar output +

+
+
‘yuv422p10’
+

force YUV 4:2:2 10-bit planar output +

+
+
‘yuv444’
+

force YUV 4:4:4 8-bit planar output +

+
+
‘yuv444p10’
+

force YUV 4:4:4 10-bit planar output +

+
+
‘rgb’
+

force RGB 8-bit packed output +

+
+
‘gbrp’
+

force RGB 8-bit planar output +

+
+
‘auto’
+

automatically pick format +

+
+ +

Default value is ‘yuv420’. +

+
+
repeatlast
+

See framesync. +

+
+
alpha
+

Set format of alpha of the overlaid video, it can be straight or +premultiplied, or auto to choose the alpha mode automatically. +Default is auto. +

+
+ +

The x, and y expressions can contain the following +parameters. +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values of the output +format. For example for the pixel format "yuv422p" hsub is 2 and +vsub is 1. +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+
t
+

The timestamp, expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
+ +

This filter also supports the framesync options. +

+

Note that the n, t variables are available only +when evaluation is done per frame, and will evaluate to NAN +when eval is set to ‘init’. +

+

Be aware that frames are taken from each input video in timestamp +order, hence, if their initial timestamps differ, it is a good idea +to pass the two inputs through a setpts=PTS-STARTPTS filter to +have them begin in the same zero timestamp, as the example for +the movie filter does. +

+

You can chain together more overlays but you should test the +efficiency of such approach. +

+ +

32.185.1 Commands

+ +

This filter supports the following commands: +

+
x
+
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. +

+
+ + +

32.185.2 Examples

+ +
    +
  • Draw the overlay at 10 pixels from the bottom right corner of the main +video: +
    +
    overlay=main_w-overlay_w-10:main_h-overlay_h-10
    +
    + +

    Using named options the example above becomes: +

    +
    overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
    +
    + +
  • Insert a transparent PNG logo in the bottom left corner of the input, +using the ffmpeg tool with the -filter_complex option: +
    +
    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 ffmpeg tool: +
    +
    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
    +
    + +
  • Add a transparent color layer on top of the main video; WxH +must specify the size of the main input to the overlay filter: +
    +
    color=color=red@.3:size=WxH [over]; [in][over] overlay [out]
    +
    + +
  • Play an original video and a filtered version (here with the deshake +filter) side by side using the ffplay tool: +
    +
    ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
    +
    + +

    The above command is the same as: +

    +
    ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
    +
    + +
  • Make a sliding overlay appearing from the left to the right top part of the +screen starting since time 2: +
    +
    overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
    +
    + +
  • Compose output by putting two input videos side to side: +
    +
    ffmpeg -i left.avi -i right.avi -filter_complex "
    +nullsrc=size=200x100 [background];
    +[0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
    +[1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
    +[background][left]       overlay=shortest=1       [background+left];
    +[background+left][right] overlay=shortest=1:x=100 [left+right]
    +"
    +
    + +
  • Mask 10-20 seconds of a video by applying the delogo filter to a section +
    +
    ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
    +-vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
    +masked.avi
    +
    + +
  • Chain several overlays in cascade: +
    +
    nullsrc=s=200x200 [bg];
    +testsrc=s=100x100, split=4 [in0][in1][in2][in3];
    +[in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
    +[in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
    +[in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
    +[in3] null,       [mid2] overlay=100:100 [out0]
    +
    + +
+ + +

32.186 owdenoise

+ +

Apply Overcomplete Wavelet denoiser. +

+

The filter accepts the following options: +

+
+
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 8. +

+
+
luma_strength, ls
+

Set luma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+
chroma_strength, cs
+

Set chroma strength. +

+

Must be a double value in the range 0-1000, default is 1.0. +

+
+ + +

32.187 pad

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following parameters: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

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 color is "black". +

+
+
eval
+

Specify when to evaluate width, height, x and y expression. +

+

It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when +a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+
+
aspect
+

Pad to aspect instead to a resolution. +

+
+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

32.187.1 Examples

+ +
    +
  • Add paddings with the color "violet" to the input video. The output video +size is 640x480, and the top-left corner of the input video is placed at +column 0, row 40 +
    +
    pad=640:480:0:40:violet
    +
    + +

    The example above is equivalent to the following command: +

    +
    pad=width=640:height=480:x=0:y=40:color=violet
    +
    + +
  • Pad the input to get an output with dimensions increased by 3/2, +and put the input video at the center of the padded area: +
    +
    pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a squared output with size equal to the maximum +value between the input width and height, and put the input video at +the center of the padded area: +
    +
    pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Pad the input to get a final w/h ratio of 16:9: +
    +
    pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • In case of anamorphic video, in order to set the output display aspect +correctly, it is necessary to use sar in the expression, +according to the relation: +
    +
    (ih * X / ih) * sar = output_dar
    +X = output_dar / sar
    +
    + +

    Thus the previous example needs to be modified to: +

    +
    pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
    +
    + +
  • Double the output size and put the input video in the bottom-right +corner of the output padded area: +
    +
    pad="2*iw:2*ih:ow-iw:oh-ih"
    +
    +
+ + +

32.188 palettegen

+ +

Generate one palette for a whole video stream. +

+

It accepts the following options: +

+
+
max_colors
+

Set the maximum number of colors to quantize in the palette. +Note: the palette will still contain 256 colors; the unused palette entries +will be black. +

+
+
reserve_transparent
+

Create a palette of 255 colors maximum and reserve the last one for +transparency. Reserving the transparency color is useful for GIF optimization. +If not set, the maximum of colors in the palette will be 256. You probably want +to disable this option for a standalone image. +Set by default. +

+
+
transparency_color
+

Set the color that will be used as background for transparency. +

+
+
stats_mode
+

Set statistics mode. +

+

It accepts the following values: +

+
‘full’
+

Compute full frame histograms. +

+
‘diff’
+

Compute histograms only for the part that differs from previous frame. This +might be relevant to give more importance to the moving part of your input if +the background is static. +

+
‘single’
+

Compute new histogram for each frame. +

+
+ +

Default value is full. +

+
+ +

The filter also exports the frame metadata lavfi.color_quant_ratio +(nb_color_in / nb_color_out) which you can use to evaluate the degree of +color quantization of the palette. This information is also visible at +info logging level. +

+ +

32.188.1 Examples

+ +
    +
  • Generate a representative palette of a given video using ffmpeg: +
    +
    ffmpeg -i input.mkv -vf palettegen palette.png
    +
    +
+ + +

32.189 paletteuse

+ +

Use a palette to downsample an input video stream. +

+

The filter takes two inputs: one video stream and a palette. The palette must +be a 256 pixels image. +

+

It accepts the following options: +

+
+
dither
+

Select dithering mode. Available algorithms are: +

+
‘bayer’
+

Ordered 8x8 bayer dithering (deterministic) +

+
‘heckbert’
+

Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). +Note: this dithering is sometimes considered "wrong" and is included as a +reference. +

+
‘floyd_steinberg’
+

Floyd and Steingberg dithering (error diffusion) +

+
‘sierra2’
+

Frankie Sierra dithering v2 (error diffusion) +

+
‘sierra2_4a’
+

Frankie Sierra dithering v2 "Lite" (error diffusion) +

+
‘sierra3’
+

Frankie Sierra dithering v3 (error diffusion) +

+
‘burkes’
+

Burkes dithering (error diffusion) +

+
‘atkinson’
+

Atkinson dithering by Bill Atkinson at Apple Computer (error diffusion) +

+
‘none’
+

Disable dithering. +

+
+ +

Default is sierra2_4a. +

+
+
bayer_scale
+

When bayer dithering is selected, this option defines the scale of the +pattern (how much the crosshatch pattern is visible). A low value means more +visible pattern for less banding, and higher value means less visible pattern +at the cost of more banding. +

+

The option must be an integer value in the range [0,5]. Default is 2. +

+
+
diff_mode
+

If set, define the zone to process +

+
+
‘rectangle’
+

Only the changing rectangle will be reprocessed. This is similar to GIF +cropping/offsetting compression mechanism. This option can be useful for speed +if only a part of the image is changing, and has use cases such as limiting the +scope of the error diffusal dither to the rectangle that bounds the +moving scene (it leads to more deterministic output if the scene doesn’t change +much, and as a result less moving noise and better GIF compression). +

+
+ +

Default is none. +

+
+
new
+

Take new palette for each output frame. +

+
+
alpha_threshold
+

Sets the alpha threshold for transparency. Alpha values above this threshold +will be treated as completely opaque, and values below this threshold will be +treated as completely transparent. +

+

The option must be an integer value in the range [0,255]. Default is 128. +

+
+ + +

32.189.1 Examples

+ +
    +
  • Use a palette (generated for example with palettegen) to encode a GIF +using ffmpeg: +
    +
    ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
    +
    +
+ + +

32.190 perspective

+ +

Correct perspective of video not recorded perpendicular to the screen. +

+

A description of the accepted parameters follows. +

+
+
x0
+
y0
+
x1
+
y1
+
x2
+
y2
+
x3
+
y3
+

Set coordinates expression for top left, top right, bottom left and bottom right corners. +Default values are 0:0:W:0:0:H:W:H with which perspective will remain unchanged. +If the sense option is set to source, then the specified points will be sent +to the corners of the destination. If the sense option is set to destination, +then the corners of the source will be sent to the specified coordinates. +

+

The expressions can use the following variables: +

+
+
W
+
H
+

the width and height of video frame. +

+
in
+

Input frame count. +

+
on
+

Output frame count. +

+
+ +
+
interpolation
+

Set interpolation for perspective correction. +

+

It accepts the following values: +

+
‘linear’
+
‘cubic’
+
+ +

Default value is ‘linear’. +

+
+
sense
+

Set interpretation of coordinate options. +

+

It accepts the following values: +

+
‘0, source’
+
+

Send point in the source specified by the given coordinates to +the corners of the destination. +

+
+
‘1, destination’
+
+

Send the corners of the source to the point in the destination specified +by the given coordinates. +

+

Default value is ‘source’. +

+
+ +
+
eval
+

Set when the expressions for coordinates x0,y0,...x3,y3 are evaluated. +

+

It accepts the following values: +

+
‘init’
+

only evaluate expressions once during the filter initialization or +when a command is processed +

+
+
‘frame’
+

evaluate expressions for each incoming frame +

+
+ +

Default value is ‘init’. +

+
+ + +

32.191 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. +

+
+
mode
+

Set phase mode. +

+

It accepts the following values: +

+
‘t’
+

Capture field order top-first, transfer bottom-first. +Filter will delay the bottom field. +

+
+
‘b’
+

Capture field order bottom-first, transfer top-first. +Filter will delay the top field. +

+
+
‘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. +

+
+
‘a’
+

Capture field order determined automatically by field flags, transfer +opposite. +Filter selects among ‘t’ and ‘b’ modes on a frame by frame +basis using field flags. If no field information is available, +then this works just like ‘u’. +

+
+
‘u’
+

Capture unknown or varying, transfer opposite. +Filter selects among ‘t’ and ‘b’ on a frame by frame basis by +analyzing the images and selecting the alternative that produces best +match between the fields. +

+
+
‘T’
+

Capture top-first, transfer unknown or varying. +Filter selects among ‘t’ and ‘p’ using image analysis. +

+
+
‘B’
+

Capture bottom-first, transfer unknown or varying. +Filter selects among ‘b’ and ‘p’ using image analysis. +

+
+
‘A’
+

Capture determined by field flags, transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using field flags and +image analysis. If no field information is available, then this works just +like ‘U’. This is the default mode. +

+
+
‘U’
+

Both capture and transfer unknown or varying. +Filter selects among ‘t’, ‘b’ and ‘p’ using image analysis only. +

+
+
+
+ + +

32.191.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.192 photosensitivity

+

Reduce various flashes in video, so to help users with epilepsy. +

+

It accepts the following options: +

+
frames, f
+

Set how many frames to use when filtering. Default is 30. +

+
+
threshold, t
+

Set detection threshold factor. Default is 1. +Lower is stricter. +

+
+
skip
+

Set how many pixels to skip when sampling frames. Default is 1. +Allowed range is from 1 to 1024. +

+
+
bypass
+

Leave frames unchanged. Default is disabled. +

+
+ + +

32.193 pixdesctest

+ +

Pixel format descriptor test filter, mainly useful for internal +testing. The output video should be equal to the input video. +

+

For example: +

+
format=monow, pixdesctest
+
+ +

can be used to test the monowhite pixel format descriptor definition. +

+ +

32.194 pixelize

+

Apply pixelization to video stream. +

+

The filter accepts the following options: +

+
width, w
+
height, h
+

Set block dimensions that will be used for pixelization. +Default value is 16. +

+
+
mode, m
+

Set the mode of pixelization used. +

+

Possible values are: +

+
‘avg’
+
‘min’
+
‘max’
+
+

Default value is avg. +

+
+
planes, p
+

Set what planes to filter. Default is to filter all planes. +

+
+ + +

32.194.1 Commands

+ +

This filter supports all options as commands. +

+ +

32.195 pixscope

+ +

Display sample values of color channels. Mainly useful for checking color +and levels. Minimum supported resolution is 640x480. +

+

The filters accept the following options: +

+
+
x
+

Set scope X position, relative offset on X axis. +

+
+
y
+

Set scope Y position, relative offset on Y axis. +

+
+
w
+

Set scope width. +

+
+
h
+

Set scope height. +

+
+
o
+

Set window opacity. This window also holds statistics about pixel area. +

+
+
wx
+

Set window X position, relative offset on X axis. +

+
+
wy
+

Set window Y position, relative offset on Y axis. +

+
+ + +

32.195.1 Commands

+ +

This filter supports same commands as options. +

+ +

32.196 pp7

+

Apply Postprocessing filter 7. It is variant of the spp filter, +similar to spp = 6 with 7 point DCT, where only the center sample is +used after IDCT. +

+

The filter accepts the following options: +

+
+
qp
+

Force a constant quantization parameter. It accepts an integer in range +0 to 63. If not set, the filter will use the QP from the video stream +(if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding. +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
‘medium’
+

Set medium thresholding (good results, default). +

+
+
+
+ + +

32.197 premultiply

+

Apply alpha premultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

32.198 premultiply_dynamic

+

Dynamically premultiply or unpremultiply the input video stream as needed, +to match the requirements of the downstream filter graph. This is roughly +equivalent to either premultiply:inplace=yes or +unpremultiply:inplace=yes, or otherwise a noop. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ + +

32.199 prewitt

+

Apply prewitt operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

32.199.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.200 pseudocolor

+ +

Alter frame colors in video with pseudocolors. +

+

This filter accepts the following options: +

+
+
c0
+

set pixel first component expression +

+
+
c1
+

set pixel second component expression +

+
+
c2
+

set pixel third component expression +

+
+
c3
+

set pixel fourth component expression, corresponds to the alpha component +

+
+
index, i
+

set component to use as base for altering colors +

+
+
preset, p
+

Pick one of built-in LUTs. By default is set to none. +

+

Available LUTs: +

+
‘magma’
+
‘inferno’
+
‘plasma’
+
‘viridis’
+
‘turbo’
+
‘cividis’
+
‘range1’
+
‘range2’
+
‘shadows’
+
‘highlights’
+
‘solar’
+
‘nominal’
+
‘preferred’
+
‘total’
+
‘spectral’
+
‘cool’
+
‘heat’
+
‘fiery’
+
‘blues’
+
‘green’
+
‘helix’
+
+ +
+
opacity
+

Set opacity of output colors. Allowed range is from 0 to 1. +Default value is set to 1. +

+
+ +

Each of the expression options specifies the expression to use for computing +the lookup table for the corresponding pixel component values. +

+

The expressions can contain the following constants and functions: +

+
+
w
+
h
+

The input width and height. +

+
+
val
+

The input value for the pixel component. +

+
+
ymin, umin, vmin, amin
+

The minimum allowed component value. +

+
+
ymax, umax, vmax, amax
+

The maximum allowed component value. +

+
+ +

All expressions default to "val". +

+ +

32.200.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.200.2 Examples

+ +
    +
  • Change too high luma values to gradient: +
    +
    pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
    +
    +
+ + +

32.201 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: +

+
+
PSNR = 10*log10(MAX^2/MSE)
+
+ +

Where MAX is the average of the maximum values of each component of the +image. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the PSNR of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+
stats_version
+

Specifies which version of the stats file format to use. Details of +each format are written below. +Default value is 1. +

+
+
output_max
+

Determines whether the max value is output to the stats log. +Default value is 0. +Requires stats_version >= 2. If this is set and stats_version < 2, +the filter will return an error. +

+
+ +

This filter also supports the framesync options. +

+

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

If a stats_version greater than 1 is specified, a header line precedes +the list of per-frame-pair stats, with key value pairs following the frame +format with the following parameters: +

+
+
psnr_log_version
+

The version of the log file format. Will match stats_version. +

+
+
fields
+

A comma separated list of the per-frame-pair parameters included in +the log. +

+
+ +

A description of each shown per-frame-pair parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
mse_avg
+

Mean Square Error pixel-by-pixel average difference of the compared +frames, averaged over all the image components. +

+
+
mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
+

Mean Square Error pixel-by-pixel average difference of the compared +frames for the component specified by the suffix. +

+
+
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. +

+
+
max_avg, max_y, max_u, max_v
+

Maximum allowed value for each channel, and average over all +channels. +

+
+ + +

32.201.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] psnr="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The PSNR of each individual frame +is stored in stats.log. +

    +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -
    +
    +
+ + +

32.202 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 fps=24000/1001 if the input frame rate is 29.97fps, +fps=24 for 30fps and the (rare) telecined 25fps input. +

+

The filter accepts the following options: +

+
+
jl
+
jr
+
jt
+
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. +

+
+
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 0. +

+
+
mp
+

Set the metric plane to use. It accepts the following values: +

+
‘l’
+

Use luma plane. +

+
+
‘u’
+

Use chroma blue plane. +

+
+
‘v’
+

Use chroma red plane. +

+
+ +

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 mp to a chroma plane is to reduce CPU +load and make pullup usable in realtime on slow machines. +

+
+ +

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: +

+
ffmpeg -i input -vf pullup -r 24000/1001 ...
+
+ + +

32.203 qp

+ +

Change video quantization parameters (QP). +

+

The filter accepts the following option: +

+
+
qp
+

Set expression for quantization parameter. +

+
+ +

The expression is evaluated through the eval API and can contain, among others, +the following constants: +

+
+
known
+

1 if index is not 129, 0 otherwise. +

+
+
qp
+

Sequential index starting from -129 to 128. +

+
+ + +

32.203.1 Examples

+ +
    +
  • Some equation like: +
    +
    qp=2+2*sin(PI*qp)
    +
    +
+ + +

32.204 qrencode

+

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/), and overlay it on top of the current +frame. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and overlaid into the video output according to +the specified options. +

+

In case no text is specified, no QR code is overlaied. +

+

This filter accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
x
+
y
+

Specify an expression for positioning the padded QR code top-left corner. The +x expression can reference the value set by the y expression, and +vice. +

+

By default x and y are set set to 0, meaning that the QR code +is placed in the top left corner of the input. +

+

These expressions are evaluated for each new frame. +

+

See the qrencode Expressions section for details. +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section below for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section below for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

32.204.1 qrencode Expressions

+ +

The expressions set by the options contain the following constants and functions. +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
duration
+

the current frame’s duration, in seconds +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
main_h, H
+

the input height +

+
+
main_w, W
+

the input width +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pict_type
+

a number representing the picture type +

+
+
qr_w, w
+

the width of the encoded QR code +

+
+
rendered_qr_w, q
+
rendered_padded_qr_w, Q
+

the width of the rendered QR code, without and without padding. +

+

These parameters allow the q and Q expressions to refer to each +other, so you can for example specify q=3/4*Q. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+
sar
+

the input sample aspect ratio +

+
+
t
+

timestamp expressed in seconds, NAN if the input timestamp is unknown +

+
+
x
+
y
+

the x and y offset coordinates where the text is drawn. +

+

These parameters allow the x and y expressions to refer to each +other, so you can for example specify y=x/dar. +

+
+ + +

32.204.2 qrencode Text expansion

+ +

If expansion is set to none, the text is printed verbatim. +

+

If expansion is set to normal (which is the default), +the following expansion mechanism is used. +

+

The backslash character ‘\’, followed by any character, always expands to +the second character. +

+

Sequences of the form %{...} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ’:’. +If the arguments contain special characters or delimiters (’:’ or ’}’), +they should be escaped. +

+

Note that they probably must also be escaped as the value for the text +option in the filter argument string and as the filter argument in the +filtergraph description, and possibly also for the shell, that makes up to four +levels of escaping; using a text file with the textfile option avoids +these problems. +

+

The following functions are available: +

+
+
n, frame_num
+

return the frame number +

+
+
pts
+

Return the presentation timestamp of the current frame. +

+

It can take up to two arguments. +

+

The first argument is the format of the timestamp; it defaults to flt for +seconds as a decimal number with microsecond accuracy; hms stands for a +formatted [-]HH:MM:SS.mmm timestamp with millisecond accuracy. +gmtime stands for the timestamp of the frame formatted as UTC time; +localtime stands for the timestamp of the frame formatted as local time +zone time. If the format is set to hms24hh, the time is formatted in 24h +format (00-23). +

+

The second argument is an offset added to the timestamp. +

+

If the format is set to localtime or gmtime, a third argument may +be supplied: a strftime C function format string. By default, +YYYY-MM-DD HH:MM:SS format will be used. +

+
+
expr, e
+

Evaluate the expression’s value and output as a double. +

+

It must take one argument specifying the expression to be evaluated, accepting +the constants and functions defined in qrencode_expressions. +

+
+
expr_formatted, ef
+

Evaluate the expression’s value and output as a formatted string. +

+

The first argument is the expression to be evaluated, just as for the expr function. +The second argument specifies the output format. Allowed values are ‘x’, +‘X’, ‘d’ and ‘u’. They are treated exactly as in the +printf function. +The third parameter is optional and sets the number of positions taken by the output. +It can be used to add padding with zeros from the left. +

+
+
gmtime
+

The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
localtime
+

The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime C function format string. +The format string is extended to support the variable %[1-6]N +which prints fractions of the second with optionally specified number of digits. +

+
+
metadata
+

Frame metadata. Takes one or two arguments. +

+

The first argument is mandatory and specifies the metadata key. +

+

The second argument is optional and specifies a default value, used when the +metadata key is not found or empty. +

+

Available metadata can be identified by inspecting entries starting with TAG +included within each frame section printed by running ffprobe +-show_frames. +

+

String metadata generated in filters leading to the qrencode filter are also +available. +

+
+
rand(min, max)
+

return a random number included between min and max +

+
+ + +

32.204.3 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size, overalaid +in the top left corner of the input video, with the default size: +
    +
    qrencode=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencode=text=www.ffmpeg.org:bc=pink@0.5:fc=blue
    +
    + +
  • Place the QR code in the bottom right corner of the input video: +
    +
    qrencode=text=www.ffmpeg.org:x=W-Q:y=H-Q
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencode=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencode=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Make the QR code a fraction of the input video width: +
    +
    qrencode=text=www.ffmpeg.org:q=W/5
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencode=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencode=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencode=text=%{pts}
    +
    + +
+ + +

32.205 quirc

+ +

Identify and decode a QR code using the libquirc library (see +https://github.com/dlbeer/quirc/), and print the identified QR codes +positions and payload as metadata. +

+

To enable the compilation of this filter, you need to configure FFmpeg with +--enable-libquirc. +

+

For each found QR code in the input video, some metadata entries are added with +the prefix lavfi.quirc.N, where N is the index, starting from 0, +associated to the QR code. +

+

A description of each metadata value follows: +

+
+
lavfi.quirc.count
+

the number of found QR codes, it is not set in case none was found +

+
+
lavfi.quirc.N.corner.M.x
+
lavfi.quirc.N.coreer.M.y
+

the x/y positions of the four corners of the square containing the QR code, +where M is the index of the corner starting from 0 +

+
+
lavfi.quirc.N.payload
+

the payload of the QR code +

+
+ + +

32.206 random

+ +

Flush video frames from internal cache of frames into a random order. +No frame is discarded. +Inspired by frei0r nervous filter. +

+
+
frames
+

Set size in number of frames of internal cache, in range from 2 to +512. Default is 30. +

+
+
seed
+

Set seed for random number generator, must be an integer included between +0 and UINT32_MAX. If not specified, or if explicitly set to +less than 0, the filter will try to use a good random seed on a +best effort basis. +

+
+ + +

32.207 readeia608

+ +

Read closed captioning (EIA-608) information from the top lines of a video frame. +

+

This filter adds frame metadata for lavfi.readeia608.X.cc and +lavfi.readeia608.X.line, where X is the number of the identified line +with EIA-608 data (starting from 0). A description of each metadata value follows: +

+
+
lavfi.readeia608.X.cc
+

The two bytes stored as EIA-608 data (printed in hexadecimal). +

+
+
lavfi.readeia608.X.line
+

The number of the line on which the EIA-608 data was identified and read. +

+
+ +

This filter accepts the following options: +

+
+
scan_min
+

Set the line to start scanning for EIA-608 data. Default is 0. +

+
+
scan_max
+

Set the line to end scanning for EIA-608 data. Default is 29. +

+
+
spw
+

Set the ratio of width reserved for sync code detection. +Default is 0.27. Allowed range is [0.1 - 0.7]. +

+
+
chp
+

Enable checking the parity bit. In the event of a parity error, the filter will output +0x00 for that character. Default is false. +

+
+
lp
+

Lowpass lines prior to further processing. Default is enabled. +

+
+ + +

32.207.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.207.2 Examples

+ +
    +
  • Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. +
    +
    ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv
    +
    +
+ + +

32.208 readvitc

+ +

Read vertical interval timecode (VITC) information from the top lines of a +video frame. +

+

The filter adds frame metadata key lavfi.readvitc.tc_str with the +timecode value, if a valid timecode has been detected. Further metadata key +lavfi.readvitc.found is set to 0/1 depending on whether +timecode data has been found or not. +

+

This filter accepts the following options: +

+
+
scan_max
+

Set the maximum number of lines to scan for VITC data. If the value is set to +-1 the full video frame is scanned. Default is 45. +

+
+
thr_b
+

Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], +default value is 0.2. The value must be equal or less than thr_w. +

+
+
thr_w
+

Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], +default value is 0.6. The value must be equal or greater than thr_b. +

+
+ + +

32.208.1 Examples

+ +
    +
  • Detect and draw VITC data onto the video frame; if no valid VITC is detected, +draw --:--:--:-- as a placeholder: +
    +
    ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--}:x=(w-tw)/2:y=400-ascent'
    +
    +
+ + +

32.209 remap

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 16bit depth, single channel. +

+
+
format
+

Specify pixel format of output from this filter. Can be color or gray. +Default is color. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

32.210 removegrain

+ +

The removegrain filter is a spatial denoiser for progressive video. +

+
+
m0
+

Set mode for the first plane. +

+
+
m1
+

Set mode for the second plane. +

+
+
m2
+

Set mode for the third plane. +

+
+
m3
+

Set mode for the fourth plane. +

+
+ +

Range of mode is from 0 to 24. Description of each mode follows: +

+
+
0
+

Leave input plane unchanged. Default. +

+
+
1
+

Clips the pixel with the minimum and maximum of the 8 neighbour pixels. +

+
+
2
+

Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. +

+
+
3
+

Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. +

+
+
4
+

Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. +This is equivalent to a median filter. +

+
+
5
+

Line-sensitive clipping giving the minimal change. +

+
+
6
+

Line-sensitive clipping, intermediate. +

+
+
7
+

Line-sensitive clipping, intermediate. +

+
+
8
+

Line-sensitive clipping, intermediate. +

+
+
9
+

Line-sensitive clipping on a line where the neighbours pixels are the closest. +

+
+
10
+

Replaces the target pixel with the closest neighbour. +

+
+
11
+

[1 2 1] horizontal and vertical kernel blur. +

+
+
12
+

Same as mode 11. +

+
+
13
+

Bob mode, interpolates top field from the line where the neighbours +pixels are the closest. +

+
+
14
+

Bob mode, interpolates bottom field from the line where the neighbours +pixels are the closest. +

+
+
15
+

Bob mode, interpolates top field. Same as 13 but with a more complicated +interpolation formula. +

+
+
16
+

Bob mode, interpolates bottom field. Same as 14 but with a more complicated +interpolation formula. +

+
+
17
+

Clips the pixel with the minimum and maximum of respectively the maximum and +minimum of each pair of opposite neighbour pixels. +

+
+
18
+

Line-sensitive clipping using opposite neighbours whose greatest distance from +the current pixel is minimal. +

+
+
19
+

Replaces the pixel with the average of its 8 neighbours. +

+
+
20
+

Averages the 9 pixels ([1 1 1] horizontal and vertical blur). +

+
+
21
+

Clips pixels using the averages of opposite neighbour. +

+
+
22
+

Same as mode 21 but simpler and faster. +

+
+
23
+

Small edge and halo removal, but reputed useless. +

+
+
24
+

Similar as 23. +

+
+ + +

32.211 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. +

+

The filter accepts the following options: +

+
+
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. +

+
+ +

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 +the logo. If you use white (255) for the logo and black (0) for the +rest, you will be safe. For making the filter bitmap, it is +recommended to take a screen capture of a black frame with the logo +visible, and then using a threshold filter followed by the erode +filter once or twice. +

+

If needed, little splotches can be fixed manually. Remember that if +logo pixels are not covered, the filter quality will be much +reduced. Marking too many pixels as part of the logo does not hurt as +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. +

+ +

32.212 repeatfields

+ +

This filter uses the repeat_field flag from the Video ES headers and hard repeats +fields based on its value. +

+ +

32.213 reverse

+ +

Reverse a video clip. +

+

Warning: This filter requires memory to buffer the entire clip, so trimming +is suggested. +

+ +

32.213.1 Examples

+ +
    +
  • Take the first 5 seconds of a clip, and reverse it. +
    +
    trim=end=5,reverse
    +
    +
+ + +

32.214 rgbashift

+

Shift R/G/B/A pixels horizontally and/or vertically. +

+

The filter accepts the following options: +

+
rh
+

Set amount to shift red horizontally. +

+
rv
+

Set amount to shift red vertically. +

+
gh
+

Set amount to shift green horizontally. +

+
gv
+

Set amount to shift green vertically. +

+
bh
+

Set amount to shift blue horizontally. +

+
bv
+

Set amount to shift blue vertically. +

+
ah
+

Set amount to shift alpha horizontally. +

+
av
+

Set amount to shift alpha vertically. +

+
edge
+

Set edge mode, can be smear, default, or warp. +

+
+ + +

32.214.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.215 roberts

+

Apply roberts cross operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

32.215.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.216 rotate

+ +

Rotate video by an arbitrary angle expressed in radians. +

+

The filter accepts the following options: +

+

A description of the optional parameters follows. +

+
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. +

+
+
out_w, ow
+

Set the output width expression, default value is "iw". +This expression is evaluated just once during configuration. +

+
+
out_h, oh
+

Set the output height expression, default value is "ih". +This expression is evaluated just once during configuration. +

+
+
bilinear
+

Enable bilinear interpolation if set to 1, a value of 0 disables +it. Default value is 1. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the rotated +image. For the general syntax 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". +

+
+ +

The expressions for the angle and the output size can contain the +following constants and functions: +

+
+
n
+

sequential number of the input frame, starting from 0. It is always NAN +before the first frame is filtered. +

+
+
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. +

+
+
hsub
+
vsub
+

horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
in_w, iw
+
in_h, ih
+

the input video width and height +

+
+
out_w, ow
+
out_h, oh
+

the output width and height, that is the size of the padded area as +specified by the width and height expressions +

+
+
rotw(a)
+
roth(a)
+

the minimal width/height required for completely containing the input +video rotated by a radians. +

+

These are only available when computing the out_w and +out_h expressions. +

+
+ + +

32.216.1 Examples

+ +
    +
  • Rotate the input by PI/6 radians clockwise: +
    +
    rotate=PI/6
    +
    + +
  • Rotate the input by PI/6 radians counter-clockwise: +
    +
    rotate=-PI/6
    +
    + +
  • Rotate the input by 45 degrees clockwise: +
    +
    rotate=45*PI/180
    +
    + +
  • Apply a constant rotation with period T, starting from an angle of PI/3: +
    +
    rotate=PI/3+2*PI*t/T
    +
    + +
  • Make the input video rotation oscillating with a period of T +seconds and an amplitude of A radians: +
    +
    rotate=A*sin(2*PI/T*t)
    +
    + +
  • Rotate the video, output size is chosen so that the whole rotating +input video is always completely contained in the output: +
    +
    rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
    +
    + +
  • Rotate the video, reduce the output size so that no background is ever +shown: +
    +
    rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
    +
    +
+ + +

32.216.2 Commands

+ +

The filter supports the following commands: +

+
+
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. +

+
+ + +

32.217 sab

+ +

Apply Shape Adaptive Blur. +

+

The filter accepts the following options: +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
chroma_radius, cr
+

Set chroma blur filter strength, must be a value in range -0.9-4.0. A +greater value will result in a more blurred image, and in slower +processing. +

+
+
chroma_pre_filter_radius, cpfr
+

Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. +

+
+
chroma_strength, cs
+

Set chroma maximum difference between pixels to still be considered, +must be a value in the -0.9-100.0 range. +

+
+ +

Each chroma option value, if not explicitly specified, is set to the +corresponding luma option value. +

+ +

32.218 scale

+ +

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. +

+

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. +

+ +

32.218.1 Options

+

The filter accepts the following options, any of the options supported +by the libswscale scaler, as well as any of the framesync options. +

+

See the ffmpeg-scaler manual for +the complete list of scaler options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the scale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +

Default value is ‘init’. +

+ +
+
interl
+

Set the interlacing mode. It accepts the following values: +

+
+
‘1’
+

Force interlaced aware scaling. +

+
+
‘0’
+

Do not apply interlaced scaling. +

+
+
‘-1’
+

Select interlaced aware scaling depending on whether the source frames +are flagged as interlaced or not. +

+
+ +

Default value is ‘0’. +

+
+
flags
+

Set libswscale scaling flags. See +the ffmpeg-scaler manual for the +complete list of values. If not explicitly specified the filter applies +the default flags. +

+ +
+
param0, param1
+

Set libswscale input parameters for scaling algorithms that need them. See +the ffmpeg-scaler manual for the +complete documentation. If not explicitly specified the filter applies +empty parameters. +

+
+
intent
+

Set the ICC rendering intent to use when transforming between different color +spaces. It accepts the following values: +

+
+
‘perceptual’
+

Use a perceptually guided tone and gamut mapping curve. The exact details of +the mapping used may change at any time and should not be relied on as stable. +This intent is recommended for final viewing of image/video content in typical +viewing settings. +

+
+
‘relative_colorimetric’
+

Statically clip out-of-gamut colors using a colorimetric clipping curve which +attempts to find the colorimetrically least dissimilar in-gamut color. This +intent performs white point adaptation and black point adaptation. This is +the default. This intent is recommended wherever faithful color reproduction +is of the utmost importance, even at the cost of clipping. +

+
+
‘absolute_colorimetric’
+

Hard clip out-of-gamut colors with no attempt at white or black point +reproduction. This intent will reproduce in-gamut colors 1:1 on the output +display as they would appear on the reference display, assuming the output +display is appropriately calibrated. +

+
+
‘saturation’
+

Performs saturation mapping - that is, stretches the input color volume +directly onto the output color volume, in non-linear fashion that preserves the +original signal appearance as much as possible. This intent is recommended for +signal content evaluation, as it will not lead to any clipping. It is roughly +analogous to not performing any color mapping, although it still takes into +account the mastering display primaries and any differences in encoding TRC. +

+
+ +
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
in_color_matrix
+
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: +

+
+
‘auto’
+

Choose automatically. +

+
+
‘bt709’
+

Format conforming to International Telecommunication Union (ITU) +Recommendation BT.709. +

+
+
‘fcc’
+

Set color space conforming to the United States Federal Communications +Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). +

+
+
‘bt601’
+
‘bt470’
+
‘smpte170m’
+

Set color space conforming to: +

+
    +
  • ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 + +
  • ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G + +
  • Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 + +
+ +
+
‘smpte240m’
+

Set color space conforming to SMPTE ST 240:1999. +

+
+
‘bt2020’
+

Set color space conforming to ITU-R BT.2020 non-constant luminance system. +

+
+ +
+
in_range
+
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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
in_chroma_loc
+
out_chroma_loc
+

Set in/output chroma sample location. If not specified, center-sited chroma +is used by default. Possible values: +

+
+
‘auto, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
in_primaries
+
out_primaries
+

Set in/output RGB primaries. +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
‘ebu3213’
+
+ +
+
in_transfer
+
out_transfer
+

Set in/output transfer response curve (TRC). +

+

This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. Possible values: +

+
+
‘auto’
+

Choose automatically. This is the default. +

+
+
‘bt709’
+
‘bt470m’
+
‘gamma22’
+
‘bt470bg’
+
‘gamma28’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘iec61966-2-1’
+
‘srgb’
+
‘iec61966-2-4’
+
‘xvycc’
+
‘bt1361e’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Enabling this option leads to the output SAR being reset to 1. +Additionally, if the user requests proportional scaling either +through the width or height expressions, e.g. w=-4:h=360 or w=iw/2:h=-1 +or by enabling force_original_aspect_ratio, then the input DAR is taken into +account and the output is scaled to produce square pixels. +Default is false. +

+
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+
ref_w, rw
+
ref_h, rh
+
ref_a
+
ref_dar, rdar
+
ref_n
+
ref_t
+
ref_pos
+

Eqvuialent to the above, but for a second reference input. If any of these +variables are present, this filter accepts two inputs. +

+
+ + +

32.218.2 Examples

+ +
    +
  • Scale the input video to a size of 200x100 +
    +
    scale=w=200:h=100
    +
    + +

    This is equivalent to: +

    +
    scale=200:100
    +
    + +

    or: +

    +
    scale=200x100
    +
    + +
  • Specify a size abbreviation for the output size: +
    +
    scale=qcif
    +
    + +

    which can also be written as: +

    +
    scale=size=qcif
    +
    + +
  • Scale the input to 2x: +
    +
    scale=w=2*iw:h=2*ih
    +
    + +
  • The above is the same as: +
    +
    scale=2*in_w:2*in_h
    +
    + +
  • Scale the input to 2x with forced interlaced scaling: +
    +
    scale=2*iw:2*ih:interl=1
    +
    + +
  • Scale the input to half size: +
    +
    scale=w=iw/2:h=ih/2
    +
    + +
  • Increase the width, and set the height to the same size: +
    +
    scale=3/2*iw:ow
    +
    + +
  • Seek Greek harmony: +
    +
    scale=iw:1/PHI*iw
    +scale=ih*PHI:ih
    +
    + +
  • Increase the height, and set the width to 3/2 of the height: +
    +
    scale=w=3/2*oh:h=3/5*ih
    +
    + +
  • Increase the size, making the size a multiple of the chroma +subsample values: +
    +
    scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
    +
    + +
  • Increase the width to a maximum of 500 pixels, +keeping the same aspect ratio as the input: +
    +
    scale=w='min(500\, iw*3/2):h=-1'
    +
    + +
  • Make pixels square by combining scale and setsar: +
    +
    scale='trunc(ih*dar):ih',setsar=1/1
    +
    + +
  • Make pixels square using reset_sar, +making sure the resulting resolution is even (required by some codecs): +
    +
    scale='-2:ih-mod(ih,2):reset_sar=1'
    +
    + +
  • Scale to target exactly, however reset SAR to 1: +
    +
    scale='400:300:reset_sar=1'
    +
    + +
  • Scale to even dimensions that fit within 400x300, preserving input SAR: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2'
    +
    + +
  • Scale to produce square pixels with even dimensions that fit within 400x300: +
    +
    scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2:reset_sar=1'
    +
    + +
  • Scale a subtitle stream (sub) to match the main video (main) in size before +overlaying. ("scale2ref") +
    +
    '[main]split[a][b]; [ref][a]scale=rw:rh[c]; [b][c]overlay'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display +aspect ratio. +
    +
    [logo-in][video-in]scale=w=oh*dar:h=rh/10[logo-out]
    +
    +
+ + +

32.218.3 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + +

32.219 scharr

+

Apply scharr operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

32.219.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.220 scroll

+

Scroll input video horizontally and/or vertically by constant speed. +

+

The filter accepts the following options: +

+
horizontal, h
+

Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
vertical, v
+

Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1. +Negative values changes scrolling direction. +

+
+
hpos
+

Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+
vpos
+

Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1. +

+
+ + +

32.220.1 Commands

+ +

This filter supports the following commands: +

+
horizontal, h
+

Set the horizontal scrolling speed. +

+
vertical, v
+

Set the vertical scrolling speed. +

+
+ + +

32.221 scdet

+ +

Detect video scene change. +

+

This filter sets frame metadata with mafd between frame, the scene score, and +forward the frame to the next filter, so they can use these metadata to detect +scene change or others. +

+

In addition, this filter logs a message and sets frame metadata when it detects +a scene change by threshold. +

+

lavfi.scd.mafd metadata keys are set with mafd for every frame. +

+

lavfi.scd.score metadata keys are set with scene change score for every frame +to detect scene change. +

+

lavfi.scd.time metadata keys are set with current filtered frame time which +detect scene change with threshold. +

+

The filter accepts the following options: +

+
+
threshold, t
+

Set the scene change detection threshold as a percentage of maximum change. Good +values are in the [8.0, 14.0] range. The range for threshold is +[0., 100.]. +

+

Default value is 10.. +

+
+
sc_pass, s
+

Set the flag to pass scene change frames to the next filter. Default value is 0 +You can enable it if you want to get snapshot of scene change frames only. +

+
+ + +

32.222 selectivecolor

+ +

Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such +as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined +by the "purity" of the color (that is, how saturated it already is). +

+

This filter is similar to the Adobe Photoshop Selective Color tool. +

+

The filter accepts the following options: +

+
+
correction_method
+

Select color correction method. +

+

Available values are: +

+
‘absolute’
+

Specified adjustments are applied "as-is" (added/subtracted to original pixel +component value). +

+
‘relative’
+

Specified adjustments are relative to the original component value. +

+
+

Default is absolute. +

+
reds
+

Adjustments for red pixels (pixels where the red component is the maximum) +

+
yellows
+

Adjustments for yellow pixels (pixels where the blue component is the minimum) +

+
greens
+

Adjustments for green pixels (pixels where the green component is the maximum) +

+
cyans
+

Adjustments for cyan pixels (pixels where the red component is the minimum) +

+
blues
+

Adjustments for blue pixels (pixels where the blue component is the maximum) +

+
magentas
+

Adjustments for magenta pixels (pixels where the green component is the minimum) +

+
whites
+

Adjustments for white pixels (pixels where all components are greater than 128) +

+
neutrals
+

Adjustments for all pixels except pure black and pure white +

+
blacks
+

Adjustments for black pixels (pixels where all components are lesser than 128) +

+
psfile
+

Specify a Photoshop selective color file (.asv) to import the settings from. +

+
+ +

All the adjustment settings (reds, yellows, ...) accept up to +4 space separated floating point adjustment values in the [-1,1] range, +respectively to adjust the amount of cyan, magenta, yellow and black for the +pixels of its range. +

+ +

32.222.1 Examples

+ +
    +
  • Increase cyan by 50% and reduce yellow by 33% in every green areas, and +increase magenta by 27% in blue areas: +
    +
    selectivecolor=greens=.5 0 -.33 0:blues=0 .27
    +
    + +
  • Use a Photoshop selective color preset: +
    +
    selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
    +
    +
+ + +

32.223 separatefields

+ +

The 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 setfield filter before separatefields filter. +

+ +

32.224 setdar, setsar

+ +

The setdar filter sets the Display Aspect Ratio for the filter +output video. +

+

This is done by changing the specified Sample (aka Pixel) Aspect +Ratio, according to the following equation: +

+
DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR
+
+ +

Keep in mind that the setdar filter does not modify the pixel +dimensions of the video frame. Also, the display aspect ratio set by +this filter may be changed by later filters in the filterchain, +e.g. in case of scaling or if another "setdar" or a "setsar" filter is +applied. +

+

The setsar filter sets the Sample (aka Pixel) Aspect Ratio for +the filter output video. +

+

Note that as a consequence of the application of this filter, the +output display aspect ratio will change according to the equation +above. +

+

Keep in mind that the sample aspect ratio set by the setsar +filter may be changed by later filters in the filterchain, e.g. if +another "setsar" or a "setdar" filter is applied. +

+

It accepts the following parameters: +

+
+
r, ratio, dar (setdar only), sar (setsar only)
+

Set the aspect ratio used by the filter. +

+

The parameter can be a floating point number string, or an expression. If the +parameter is not specified, the value "0" is assumed, meaning that the same +input value is used. +

+
+
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 100. +

+
+
+ +

The parameter sar is an expression containing the following constants: +

+
+
w, h
+

The input width and height. +

+
+
a
+

Same as w / h. +

+
+
sar
+

The input sample aspect ratio. +

+
+
dar
+

The input display aspect ratio. It is the same as +(w / h) * sar. +

+
+
hsub, vsub
+

Horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

32.224.1 Examples

+ +
    +
  • To change the display aspect ratio to 16:9, specify one of the following: +
    +
    setdar=dar=1.77777
    +setdar=dar=16/9
    +
    + +
  • To change the sample aspect ratio to 10:11, specify: +
    +
    setsar=sar=10/11
    +
    + +
  • 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: +
    +
    setdar=ratio=16/9:max=1000
    +
    + +
+ + +

32.225 setfield

+ +

Force field for the output video frame. +

+

The setfield filter marks the interlace type field for the +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. fieldorder or yadif). +

+

The filter accepts the following options: +

+
+
mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property. +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+
+
+ + +

32.226 setparams

+ +

Force frame parameter for the output video frame. +

+

The setparams filter marks interlace and color range for the +output frames. It does not change the input frame, but only sets the +corresponding property, which affects how the frame is treated by +filters/encoders. +

+
+
field_mode
+

Available values are: +

+
+
‘auto’
+

Keep the same field property (default). +

+
+
‘bff’
+

Mark the frame as bottom-field-first. +

+
+
‘tff’
+

Mark the frame as top-field-first. +

+
+
‘prog’
+

Mark the frame as progressive. +

+
+ +
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property (default). +

+
+
‘unspecified, unknown’
+

Mark the frame as unspecified color range. +

+
+
‘limited, tv, mpeg’
+

Mark the frame as limited range. +

+
+
‘full, pc, jpeg’
+

Mark the frame as full range. +

+
+ +
+
color_primaries
+

Set the color primaries. +Available values are: +

+
+
‘auto’
+

Keep the same color primaries property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘film’
+
‘bt2020’
+
‘smpte428’
+
‘smpte431’
+
‘smpte432’
+
‘jedec-p22’
+
+ +
+
color_trc
+

Set the color transfer. +Available values are: +

+
+
‘auto’
+

Keep the same color trc property (default). +

+
+
‘bt709’
+
‘unknown’
+
‘bt470m’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘linear’
+
‘log100’
+
‘log316’
+
‘iec61966-2-4’
+
‘bt1361e’
+
‘iec61966-2-1’
+
‘bt2020-10’
+
‘bt2020-12’
+
‘smpte2084’
+
‘smpte428’
+
‘arib-std-b67’
+
+ +
+
colorspace
+

Set the colorspace. +Available values are: +

+
+
‘auto’
+

Keep the same colorspace property (default). +

+
+
‘gbr’
+
‘bt709’
+
‘unknown’
+
‘fcc’
+
‘bt470bg’
+
‘smpte170m’
+
‘smpte240m’
+
‘ycgco’
+
‘bt2020nc’
+
‘bt2020c’
+
‘smpte2085’
+
‘chroma-derived-nc’
+
‘chroma-derived-c’
+
‘ictcp’
+
+ +
+
chroma_location
+

Set the chroma sample location. +Available values are: +

+
+
‘auto’
+

Keep the same chroma location (default). +

+
+
‘unspecified, unknown’
+
‘left’
+
‘center’
+
‘topleft’
+
‘top’
+
‘bottomleft’
+
‘bottom’
+
+ +
+
alpha_mode
+

Set the alpha moda. +Available values are: +

+
+
‘auto’
+

Keep the same alpha mode (default). +

+
+
‘unspecified, unknown’
+
‘premultiplied’
+
‘straight’
+
+
+
+ + +

32.227 shear

+

Apply shear transform to input video. +

+

This filter supports the following options: +

+
+
shx
+

Shear factor in X-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
shy
+

Shear factor in Y-direction. Default value is 0. +Allowed range is from -2 to 2. +

+
+
fillcolor, c
+

Set the color used to fill the output area not covered by the transformed +video. For the general syntax 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". +

+
+
interp
+

Set interpolation type. Can be bilinear or nearest. Default is bilinear. +

+
+ + +

32.227.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.228 showinfo

+ +

Show a line containing various information for each input video frame. +The input video is not modified. +

+

This filter supports the following options: +

+
+
checksum
+

Calculate checksums of each plane. By default enabled. +

+
+
udu_sei_as_ascii
+

Try to print user data unregistered SEI as ascii character when possible, +in hex format otherwise. +

+
+ +

The shown line contains a sequence of key/value pairs of the form +key:value. +

+

The following values are shown in the output: +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +

+
+
pts
+

The Presentation TimeStamp of the input frame, expressed as a number of +time base units. The time base unit depends on the filter input pad. +

+
+
pts_time
+

The Presentation TimeStamp of the input frame, expressed as a number of +seconds. +

+
+
fmt
+

The pixel format name. +

+
+
sar
+

The sample aspect ratio of the input frame, expressed in the form +num/den. +

+
+
s
+

The size of the input frame. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
i
+

The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" +for bottom field first). +

+
+
iskey
+

This is 1 if the frame is a key frame, 0 otherwise. +

+
+
type
+

The picture type of the input frame ("I" for an I-frame, "P" for a +P-frame, "B" for a B-frame, or "?" for an unknown type). +Also refer to the documentation of the AVPictureType enum and of +the av_get_picture_type_char function defined in +libavutil/avutil.h. +

+
+
checksum
+

The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. +

+
+
plane_checksum
+

The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, +expressed in the form "[c0 c1 c2 c3]". +

+
+
mean
+

The mean value of pixels in each plane of the input frame, expressed in the form +"[mean0 mean1 mean2 mean3]". +

+
+
stdev
+

The standard deviation of pixel values in each plane of the input frame, expressed +in the form "[stdev0 stdev1 stdev2 stdev3]". +

+
+
+ + +

32.229 showpalette

+ +

Displays the 256 colors palette of each frame. This filter is only relevant for +pal8 pixel format frames. +

+

It accepts the following option: +

+
+
s
+

Set the size of the box used to represent one palette color entry. Default is +30 (for a 30x30 pixel box). +

+
+ + +

32.230 shuffleframes

+ +

Reorder and/or duplicate and/or drop video frames. +

+

It accepts the following parameters: +

+
+
mapping
+

Set the destination indexes of input frames. +This is space or ’|’ separated list of indexes that maps input frames to output +frames. Number of indexes also sets maximal value that each index may have. +’-1’ index have special meaning and that is to drop frame. +

+
+ +

The first frame has the index 0. The default is to keep the input unchanged. +

+ +

32.230.1 Examples

+ +
    +
  • Swap second and third frame of every three frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
    +
    + +
  • Swap 10th and 1st frame of every ten frames of the input: +
    +
    ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
    +
    +
+ + +

32.231 shufflepixels

+ +

Reorder pixels in video frames. +

+

This filter accepts the following options: +

+
+
direction, d
+

Set shuffle direction. Can be forward or inverse direction. +Default direction is forward. +

+
+
mode, m
+

Set shuffle mode. Can be horizontal, vertical or block mode. +

+
+
width, w
+
height, h
+

Set shuffle block_size. In case of horizontal shuffle mode only width +part of size is used, and in case of vertical shuffle mode only height +part of size is used. +

+
+
seed, s
+

Set random seed used with shuffling pixels. Mainly useful to set to be able +to reverse filtering process to get original input. +For example, to reverse forward shuffle you need to use same parameters +and exact same seed and to set direction to inverse. +

+
+ + +

32.232 shuffleplanes

+ +

Reorder and/or duplicate video planes. +

+

It accepts the following parameters: +

+
+
map0
+

The index of the input plane to be used as the first output plane. +

+
+
map1
+

The index of the input plane to be used as the second output plane. +

+
+
map2
+

The index of the input plane to be used as the third output plane. +

+
+
map3
+

The index of the input plane to be used as the fourth output plane. +

+
+
+ +

The first plane has the index 0. The default is to keep the input unchanged. +

+ +

32.232.1 Examples

+ +
    +
  • Swap the second and third planes of the input: +
    +
    ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
    +
    +
+ + +

32.233 signalstats

+

Evaluate various visual metrics that assist in determining issues associated +with the digitization of analog video media. +

+

By default the filter will log these metadata values: +

+
+
YMIN
+

Display the minimal Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
YLOW
+

Display the Y value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YAVG
+

Display the average Y value within the input frame. Expressed in range of +[0-255]. +

+
+
YHIGH
+

Display the Y value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
YMAX
+

Display the maximum Y value contained within the input frame. Expressed in +range of [0-255]. +

+
+
UMIN
+

Display the minimal U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
ULOW
+

Display the U value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UAVG
+

Display the average U value within the input frame. Expressed in range of +[0-255]. +

+
+
UHIGH
+

Display the U value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
UMAX
+

Display the maximum U value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VMIN
+

Display the minimal V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
VLOW
+

Display the V value at the 10% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VAVG
+

Display the average V value within the input frame. Expressed in range of +[0-255]. +

+
+
VHIGH
+

Display the V value at the 90% percentile within the input frame. Expressed in +range of [0-255]. +

+
+
VMAX
+

Display the maximum V value contained within the input frame. Expressed in +range of [0-255]. +

+
+
SATMIN
+

Display the minimal saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATLOW
+

Display the saturation value at the 10% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATAVG
+

Display the average saturation value within the input frame. Expressed in range +of [0-~181.02]. +

+
+
SATHIGH
+

Display the saturation value at the 90% percentile within the input frame. +Expressed in range of [0-~181.02]. +

+
+
SATMAX
+

Display the maximum saturation value contained within the input frame. +Expressed in range of [0-~181.02]. +

+
+
HUEMED
+

Display the median value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
HUEAVG
+

Display the average value for hue within the input frame. Expressed in range of +[0-360]. +

+
+
YDIF
+

Display the average of sample value difference between all values of the Y +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
UDIF
+

Display the average of sample value difference between all values of the U +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
VDIF
+

Display the average of sample value difference between all values of the V +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +

+
+
YBITDEPTH
+

Display bit depth of Y plane in current frame. +Expressed in range of [0-16]. +

+
+
UBITDEPTH
+

Display bit depth of U plane in current frame. +Expressed in range of [0-16]. +

+
+
VBITDEPTH
+

Display bit depth of V plane in current frame. +Expressed in range of [0-16]. +

+
+ +

The filter accepts the following options: +

+
+
stat
+
out
+
+

stat specify an additional form of image analysis. +out output video with the specified type of pixel highlighted. +

+

Both options accept the following values: +

+
+
‘tout’
+

Identify temporal outliers pixels. A temporal outlier is a pixel +unlike the neighboring pixels of the same field. Examples of temporal outliers +include the results of video dropouts, head clogs, or tape tracking issues. +

+
+
‘vrep’
+

Identify vertical line repetition. Vertical line repetition includes +similar rows of pixels within a frame. In born-digital video vertical line +repetition is common, but this pattern is uncommon in video digitized from an +analog source. When it occurs in video that results from the digitization of an +analog source it can indicate concealment from a dropout compensator. +

+
+
‘brng’
+

Identify pixels that fall outside of legal broadcast range. +

+
+ +
+
color, c
+

Set the highlight color for the out option. The default color is +yellow. +

+
+ + +

32.233.1 Examples

+ +
    +
  • Output data of various video metrics: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
    +
    + +
  • Output specific data about the minimum and maximum values of the Y plane per frame: +
    +
    ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
    +
    + +
  • Playback video while highlighting pixels that are outside of broadcast range in red. +
    +
    ffplay example.mov -vf signalstats="out=brng:color=red"
    +
    + +
  • Playback video with signalstats metadata drawn over the frame. +
    +
    ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
    +
    + +

    The contents of signalstat_drawtext.txt used in the command are: +

    +
    time %{pts:hms}
    +Y (%{metadata:lavfi.signalstats.YMIN}-%{metadata:lavfi.signalstats.YMAX})
    +U (%{metadata:lavfi.signalstats.UMIN}-%{metadata:lavfi.signalstats.UMAX})
    +V (%{metadata:lavfi.signalstats.VMIN}-%{metadata:lavfi.signalstats.VMAX})
    +saturation maximum: %{metadata:lavfi.signalstats.SATMAX}
    +
    +
    +
+ + +

32.234 signature

+ +

Calculates the MPEG-7 Video Signature. The filter can handle more than one +input. In this case the matching between the inputs can be calculated additionally. +The filter always passes through the first input. The signature of each stream can +be written into a file. +

+

It accepts the following options: +

+
+
detectmode
+

Enable or disable the matching process. +

+

Available values are: +

+
+
‘off’
+

Disable the calculation of a matching (default). +

+
‘full’
+

Calculate the matching for the whole video and output whether the whole video +matches or only parts. +

+
‘fast’
+

Calculate only until a matching is found or the video ends. Should be faster in +some cases. +

+
+ +
+
nb_inputs
+

Set the number of inputs. The option value must be a non negative integer. +Default value is 1. +

+
+
filename
+

Set the path to which the output is written. If there is more than one input, +the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive +integer), that will be replaced with the input number. If no filename is +specified, no output will be written. This is the default. +

+
+
format
+

Choose the output format. +

+

Available values are: +

+
+
‘binary’
+

Use the specified binary representation (default). +

+
‘xml’
+

Use the specified xml representation. +

+
+ +
+
th_d
+

Set threshold to detect one word as similar. The option value must be an integer +greater than zero. The default value is 9000. +

+
+
th_dc
+

Set threshold to detect all words as similar. The option value must be an integer +greater than zero. The default value is 60000. +

+
+
th_xh
+

Set threshold to detect frames as similar. The option value must be an integer +greater than zero. The default value is 116. +

+
+
th_di
+

Set the minimum length of a sequence in frames to recognize it as matching +sequence. The option value must be a non negative integer value. +The default value is 0. +

+
+
th_it
+

Set the minimum relation, that matching frames to all frames must have. +The option value must be a double value between 0 and 1. The default value is 0.5. +

+
+ + +

32.234.1 Examples

+ +
    +
  • To calculate the signature of an input video and store it in signature.bin: +
    +
    ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
    +
    + +
  • To detect whether two videos match and store the signatures in XML format in +signature0.xml and signature1.xml: +
    +
    ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -
    +
    + +
+ + +

32.235 siti

+ +

Calculate Spatial Information (SI) and Temporal Information (TI) scores for a video, +as defined in ITU-T Rec. P.910 (11/21): Subjective video quality assessment methods +for multimedia applications. Available PDF at https://www.itu.int/rec/T-REC-P.910-202111-S/en. +Note that this is a legacy implementation that corresponds to a superseded recommendation. +Refer to ITU-T Rec. P.910 (07/22) for the latest version: https://www.itu.int/rec/T-REC-P.910-202207-I/en +

+

It accepts the following option: +

+
+
print_summary
+

If set to 1, Summary statistics will be printed to the console. Default 0. +

+
+ + +

32.235.1 Examples

+
    +
  • To calculate SI/TI metrics and print summary: +
    +
    ffmpeg -i input.mp4 -vf siti=print_summary=1 -f null -
    +
    +
+ + +

32.236 smartblur

+ +

Blur the input video without impacting the outlines. +

+

It accepts the following options: +

+
+
luma_radius, lr
+

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. +

+
+
luma_strength, ls
+

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. +

+
+
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. +

+
+
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 luma_radius. +

+
+
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 luma_strength. +

+
+
chroma_threshold, ct
+

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 +in [-30,0] will filter edges. Default value is luma_threshold. +

+
+
alpha_radius, ar
+

Set the alpha 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 luma_radius. +

+
+
alpha_strength, as
+

Set the alpha 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 luma_strength. +

+
+
alpha_threshold, at
+

Set the alpha 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 luma_threshold. +

+
+ +

If a chroma or alpha option is not explicitly set, the corresponding luma value +is set. +

+ +

32.237 sobel

+

Apply sobel operator to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +

+
+
delta
+

Set value which will be added to filtered result. +

+
+ + +

32.237.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.238 spp

+ +

Apply a simple postprocessing filter that compresses and decompresses the image +at several (or - in the case of quality level 6 - all) shifts +and average the results. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-6. If set to 0, the filter will have no +effect. A value of 6 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
mode
+

Set thresholding mode. Available modes are: +

+
+
‘hard’
+

Set hard thresholding (default). +

+
‘soft’
+

Set soft thresholding (better de-ringing effect, but likely blurrier). +

+
+ +
+
use_bframe_qp
+

Enable the use of the QP from the B-Frames if set to 1. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +0 (not enabled). +

+
+ + +

32.238.1 Commands

+ +

This filter supports the following commands: +

+
quality, level
+

Set quality level. The value max can be used to set the maximum level, +currently 6. +

+
+ + +

32.239 sr

+ +

Scale the input by applying one of the super-resolution methods based on +convolutional neural networks. Supported models: +

+ + +

Training scripts as well as scripts for model file (.pb) saving can be found at +https://github.com/XueweiMeng/sr/tree/sr_dnn_native. Original repository +is at https://github.com/HighVoltageRocknRoll/sr.git. +

+

The filter accepts the following options: +

+
+
dnn_backend
+

Specify which DNN backend to use for model loading and execution. This option accepts +the following values: +

+
+
‘tensorflow’
+

TensorFlow backend. To enable this backend you +need to install the TensorFlow for C library (see +https://www.tensorflow.org/install/lang_c) and configure FFmpeg with +--enable-libtensorflow +

+
+ +
+
model
+

Set path to model file specifying network architecture and its parameters. +Note that different backends use different file formats. TensorFlow, OpenVINO backend +can load files for only its format. +

+
+
scale_factor
+

Set scale factor for SRCNN model. Allowed values are 2, 3 and 4. +Default value is 2. Scale factor is necessary for SRCNN model, because it accepts +input upscaled using bicubic upscaling with proper scale factor. +

+
+ +

To get full functionality (such as async execution), please use the dnn_processing filter. +

+ +

32.240 sr_amf

+ +

Upscale (size increasing) for the input video using AMD Advanced Media Framework library for hardware acceleration. +Use advanced algorithms for upscaling with higher output quality. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
algorithm
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+
+
sr1-0
+

Video SR1.0 +This is a default value +

+
+
point
+

Point +

+
+
sr1-1
+

Video SR1.1 +

+
+
+ +
+
sharpness
+

Control hq scaler sharpening. The value is a float in the range of [0.0, 2.0] +

+
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+
+
keep-ratio
+

Force the scaler to keep the aspect ratio of the input image when the output size has a different aspect ratio. +Default value is false. +

+
+
fill
+

Specifies whether the output image outside the region of interest, +which does not fill the entire output surface should be filled with a solid color. +

+
+
+ + +

32.240.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    sr_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K with algorithm video SR1.1. +
    +
    sr_amf=4096:2160:algorithm=sr1-1
    +
    +
+ + +

32.241 ssim

+ +

Obtain the SSIM (Structural SImilarity Metric) 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 SSIM. +

+

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 filter stores the calculated SSIM of each frame. +

+

The description of the accepted parameters follows. +

+
+
stats_file, f
+

If specified the filter will use the named file to save the SSIM of +each individual frame. When filename equals "-" the data is sent to +standard output. +

+
+ +

The file printed if stats_file is selected, contains a sequence of +key/value pairs of the form key:value for each compared +couple of frames. +

+

A description of each shown parameter follows: +

+
+
n
+

sequential number of the input frame, starting from 1 +

+
+
Y, U, V, R, G, B
+

SSIM of the compared frames for the component specified by the suffix. +

+
+
All
+

SSIM of the compared frames for the whole frame. +

+
+
dB
+

Same as above but in dB representation. +

+
+ +

This filter also supports the framesync options. +

+ +

32.241.1 Examples

+
    +
  • For example: +
    +
    movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
    +[main][ref] ssim="stats_file=stats.log" [out]
    +
    + +

    On this example the input file being processed is compared with the +reference file ref_movie.mpg. The SSIM of each individual frame +is stored in stats.log. +

    +
  • Another example with both psnr and ssim at same time: +
    +
    ffmpeg -i main.mpg -i ref.mpg -lavfi  "ssim;[0:v][1:v]psnr" -f null -
    +
    + +
  • Another example with different containers: +
    +
    ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -
    +
    +
+ + +

32.242 stereo3d

+ +

Convert between different stereoscopic image formats. +

+

The filters accept the following options: +

+
+
in
+

Set stereoscopic image format of input. +

+

Available values for input image formats are: +

+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+

Default value is ‘sbsl’. +

+
+ +
+
out
+

Set stereoscopic image format of output. +

+
+
‘sbsl’
+

side by side parallel (left eye left, right eye right) +

+
+
‘sbsr’
+

side by side crosseye (right eye left, left eye right) +

+
+
‘sbs2l’
+

side by side parallel with half width resolution +(left eye left, right eye right) +

+
+
‘sbs2r’
+

side by side crosseye with half width resolution +(right eye left, left eye right) +

+
+
‘abl’
+
‘tbl’
+

above-below (left eye above, right eye below) +

+
+
‘abr’
+
‘tbr’
+

above-below (right eye above, left eye below) +

+
+
‘ab2l’
+
‘tb2l’
+

above-below with half height resolution +(left eye above, right eye below) +

+
+
‘ab2r’
+
‘tb2r’
+

above-below with half height resolution +(right eye above, left eye below) +

+
+
‘al’
+

alternating frames (left eye first, right eye second) +

+
+
‘ar’
+

alternating frames (right eye first, left eye second) +

+
+
‘irl’
+

interleaved rows (left eye has top row, right eye starts on next row) +

+
+
‘irr’
+

interleaved rows (right eye has top row, left eye starts on next row) +

+
+
‘arbg’
+

anaglyph red/blue gray +(red filter on left eye, blue filter on right eye) +

+
+
‘argg’
+

anaglyph red/green gray +(red filter on left eye, green filter on right eye) +

+
+
‘arcg’
+

anaglyph red/cyan gray +(red filter on left eye, cyan filter on right eye) +

+
+
‘arch’
+

anaglyph red/cyan half colored +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcc’
+

anaglyph red/cyan color +(red filter on left eye, cyan filter on right eye) +

+
+
‘arcd’
+

anaglyph red/cyan color optimized with the least squares projection of dubois +(red filter on left eye, cyan filter on right eye) +

+
+
‘agmg’
+

anaglyph green/magenta gray +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmh’
+

anaglyph green/magenta half colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmc’
+

anaglyph green/magenta colored +(green filter on left eye, magenta filter on right eye) +

+
+
‘agmd’
+

anaglyph green/magenta color optimized with the least squares projection of dubois +(green filter on left eye, magenta filter on right eye) +

+
+
‘aybg’
+

anaglyph yellow/blue gray +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybh’
+

anaglyph yellow/blue half colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybc’
+

anaglyph yellow/blue colored +(yellow filter on left eye, blue filter on right eye) +

+
+
‘aybd’
+

anaglyph yellow/blue color optimized with the least squares projection of dubois +(yellow filter on left eye, blue filter on right eye) +

+
+
‘ml’
+

mono output (left eye only) +

+
+
‘mr’
+

mono output (right eye only) +

+
+
‘chl’
+

checkerboard, left eye first +

+
+
‘chr’
+

checkerboard, right eye first +

+
+
‘icl’
+

interleaved columns, left eye first +

+
+
‘icr’
+

interleaved columns, right eye first +

+
+
‘hdmi’
+

HDMI frame pack +

+
+ +

Default value is ‘arcd’. +

+
+ + +

32.242.1 Examples

+ +
    +
  • Convert input video from side by side parallel to anaglyph yellow/blue dubois: +
    +
    stereo3d=sbsl:aybd
    +
    + +
  • Convert input video from above below (left eye above, right eye below) to side by side crosseye. +
    +
    stereo3d=abl:sbsr
    +
    +
+ + +

32.243 streamselect, astreamselect

+

Select video or audio streams. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. Default is 2. +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

32.243.1 Commands

+ +

The streamselect and astreamselect filter supports the following +commands: +

+
+
map
+

Set input indexes to remap to outputs. +

+
+ + +

32.243.2 Examples

+ +
    +
  • Select first 5 seconds 1st stream and rest of time 2nd stream: +
    +
    sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
    +
    + +
  • Same as above, but for audio: +
    +
    asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
    +
    +
+ + +

32.244 subtitles

+ +

Draw subtitles on top of input video using the libass library. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libass. This filter also requires a build with libavcodec and +libavformat to convert the passed subtitles file to ASS (Advanced Substation +Alpha) subtitles format. +

+

The filter accepts the following options: +

+
+
filename, f
+

Set the filename of the subtitle file to read. It must be specified. +

+
+
original_size
+

Specify the size of the original video, the video for which the ASS file +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. +

+
+
fontsdir
+

Set a directory path containing fonts that can be used by the filter. +These fonts will be used in addition to whatever the font provider uses. +

+
+
alpha
+

Process alpha channel, by default alpha channel is untouched. +

+
+
charenc
+

Set subtitles input character encoding. subtitles filter only. Only +useful if not UTF-8. +

+
+
stream_index, si
+

Set subtitles stream index. subtitles filter only. +

+
+
force_style
+

Override default style or script info parameters of the subtitles. It accepts a +string containing ASS style format KEY=VALUE couples separated by ",". +

+
+
wrap_unicode
+

Break lines according to the Unicode Line Breaking Algorithm. Availability requires +at least libass release 0.17.0 (or LIBASS_VERSION 0x01600010), and libass must +have been built with libunibreak. +

+

The option is enabled by default except for native ASS. +

+
+ +

If the first key is not specified, it is assumed that the first value +specifies the filename. +

+

For example, to render the file sub.srt on top of the input +video, use the command: +

+
subtitles=sub.srt
+
+ +

which is equivalent to: +

+
subtitles=filename=sub.srt
+
+ +

To render the default subtitles stream from file video.mkv, use: +

+
subtitles=video.mkv
+
+ +

To render the second subtitles stream from that file, use: +

+
subtitles=video.mkv:si=1
+
+ +

To make the subtitles stream from sub.srt appear in 80% transparent blue +DejaVu Serif, use: +

+
subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
+
+ + +

32.245 super2xsai

+ +

Scale the input by 2x and smooth using the Super2xSaI (Scale and +Interpolate) pixel art scaling algorithm. +

+

Useful for enlarging pixel art images without reducing sharpness. +

+ +

32.246 swaprect

+ +

Swap two rectangular objects in video. +

+

This filter accepts the following options: +

+
+
w
+

Set object width. +

+
+
h
+

Set object height. +

+
+
x1
+

Set 1st rect x coordinate. +

+
+
y1
+

Set 1st rect y coordinate. +

+
+
x2
+

Set 2nd rect x coordinate. +

+
+
y2
+

Set 2nd rect y coordinate. +

+

All expressions are evaluated once for each frame. +

+
+ +

The all options are expressions containing the following constants: +

+
+
w
+
h
+

The input width and height. +

+
+
a
+

same as w / h +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (w / h) * sar +

+
+
n
+

The number of the input frame, starting from 0. +

+
+
t
+

The timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
pos
+

the position in the file of the input frame, NAN if unknown; deprecated, +do not use +

+
+ + +

32.246.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.247 swapuv

+

Swap U & V plane. +

+ +

32.248 tblend

+

Blend successive video frames. +

+

See blend +

+ +

32.249 telecine

+ +

Apply telecine process to the video. +

+

This filter accepts the following options: +

+
+
first_field
+
+
‘top, t’
+

top field first +

+
‘bottom, b’
+

bottom field first +The default value is top. +

+
+ +
+
pattern
+

A string of numbers representing the pulldown pattern you wish to apply. +The default value is 23. +

+
+ +
+
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
+
+ + +

32.250 thistogram

+ +

Compute and draw a color distribution histogram for the input video across time. +

+

Unlike histogram video filter which only shows histogram of single input frame +at certain time, this filter shows also past histograms of number of frames defined +by width option. +

+

The computed histogram is a representation of the color component +distribution in an image. +

+

The filter accepts the following options: +

+
+
width, w
+

Set width of single color component output. Default value is 0. +Value of 0 means width will be picked from input video. +This also set number of passed histograms to keep. +Allowed range is [0, 8192]. +

+
+
display_mode, d
+

Set display mode. +It accepts the following values: +

+
‘stack’
+

Per color component graphs are placed below each other. +

+
+
‘parade’
+

Per color component graphs are placed side by side. +

+
+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+
+

Default is stack. +

+
+
levels_mode, m
+

Set mode. Can be either linear, or logarithmic. +Default is linear. +

+
+
components, c
+

Set what color components to display. +Default is 7. +

+
+
bgopacity, b
+

Set background opacity. Default is 0.9. +

+
+
envelope, e
+

Show envelope. Default is disabled. +

+
+
ecolor, ec
+

Set envelope color. Default is gold. +

+
+
slide
+

Set slide mode. +

+

Available values for slide is: +

+
‘frame’
+

Draw new frame when right border is reached. +

+
+
‘replace’
+

Replace old columns with new ones. +

+
+
‘scroll’
+

Scroll from right to left. +

+
+
‘rscroll’
+

Scroll from left to right. +

+
+
‘picture’
+

Draw single picture. +

+
+ +

Default is replace. +

+
+ + +

32.251 threshold

+ +

Apply threshold effect to video stream. +

+

This filter needs four video streams to perform thresholding. +First stream is stream we are filtering. +Second stream is holding threshold values, third stream is holding min values, +and last, fourth stream is holding max values. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+
+ +

For example if first stream pixel’s component value is less then threshold value +of pixel component from 2nd threshold stream, third stream value will picked, +otherwise fourth stream pixel component value will be picked. +

+

Using color source filter one can perform various types of thresholding: +

+ +

32.251.1 Commands

+ +

This filter supports the all options as commands. +

+ +

32.251.2 Examples

+ +
    +
  • Binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
    +
    + +
  • Inverted binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
    +
    + +
  • Truncate binary threshold, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
    +
    + +
  • Threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
    +
    + +
  • Inverted threshold to zero, using gray color as threshold: +
    +
    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
    +
    +
+ + +

32.252 thumbnail

+

Select the most representative frame in a given sequence of consecutive frames. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+
log
+

Set the log level to display picked frame stats. +Default is info. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

32.252.1 Examples

+ +
    +
  • Extract one picture each 50 frames: +
    +
    thumbnail=50
    +
    + +
  • Complete example of a thumbnail creation with ffmpeg: +
    +
    ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
    +
    +
+ + +

32.253 tile

+ +

Tile several successive frames together. +

+

The untile filter can do the reverse. +

+

The filter accepts the following options: +

+
+
layout
+

Set the grid size in the form COLUMNSxROWS. Range is up to UINT_MAX cells. +Default is 6x5. +

+
+
nb_frames
+

Set the maximum number of frames to render in the given area. It must be less +than or equal to wxh. The default value is 0, meaning all +the area will be used. +

+
+
margin
+

Set the outer border margin in pixels. Range is 0 to 1024. Default is 0. +

+
+
padding
+

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. Range is 0 to 1024. Default is 0. +

+
+
color
+

Specify the color of the unused area. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +The default value of color is "black". +

+
+
overlap
+

Set the number of frames to overlap when tiling several successive frames together. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+
init_padding
+

Set the number of frames to initially be empty before displaying first output frame. +This controls how soon will one get first output frame. +The value must be between 0 and nb_frames - 1. Default is 0. +

+
+ + +

32.253.1 Examples

+ +
    +
  • Produce 8x8 PNG tiles of all keyframes (-skip_frame nokey) in a movie: +
    +
    ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
    +
    +

    The -vsync 0 is necessary to prevent ffmpeg from +duplicating each output frame to accommodate the originally detected frame +rate. +

    +
  • Display 5 pictures in an area of 3x2 frames, +with 7 pixels between them, and 2 pixels of initial margin, using +mixed flat and named options: +
    +
    tile=3x2:nb_frames=5:padding=7:margin=2
    +
    +
+ + +

32.254 tiltandshift

+

Apply tilt-and-shift effect. +

+

What happens when you invert time and space? +

+

Normally a video is composed of several frames that represent a different +instant of time and shows a scene that evolves in the space captured by the +frame. This filter is the antipode of that concept, taking inspiration from +tilt and shift photography. +

+

A filtered frame contains the whole timeline of events composing the sequence, +and this is obtained by placing a slice of pixels from each frame into a single +one. However, since there are no infinite-width frames, this is done up the +width of the input frame, and a video is recomposed by shifting away one +column for each subsequent frame. In order to map space to time, the filter +tilts each input frame as well, so that motion is preserved. This is accomplished +by progressively selecting a different column from each input frame. +

+

The end result is a sort of inverted parallax, so that far away objects move +much faster that the ones in the front. The ideal conditions for this video +effect are when there is either very little motion and the background is static, +or when there is a lot of motion and a very wide depth of field (e.g. wide +panorama, while moving on a train). +

+

The filter accepts the following parameters: +

+
+
tilt
+

Tilt video while shifting (default). When unset, video will be sliding a +static image, composed of the first column of each frame. +

+
+
start
+

What to do at the start of filtering (see below). +

+
+
end
+

What to do at the end of filtering (see below). +

+
+
hold
+

How many columns should pass through before start of filtering. +

+
+
pad
+

How many columns should be inserted before end of filtering. +

+
+
+ +

Normally the filter shifts and tilts from the very first frame, and stops when +the last one is received. However, before filtering starts, normal video may +be preserved, so that the effect is slowly shifted in its place. Similarly, +the last video frame may be reconstructed at the end. Alternatively it is +possible to just start and end with black. +

+
+
‘none’
+

Filtering starts immediately and ends when the last frame is received. +

+
+
‘frame’
+

The first frames or the very last frame are kept intact during processing. +

+
+
‘black’
+

Black is padded at the beginning or at the end of filtering. +

+
+
+ + +

32.255 tinterlace

+ +

Perform various types of temporal field interlacing. +

+

Frames are counted starting from 1, so the first input frame is +considered odd. +

+

The filter accepts the following options: +

+
+
mode
+

Specify the mode of the interlacing. This option can also be specified +as a value alone. See below for a list of values for this option. +

+

Available values are: +

+
+
‘merge, 0’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at half frame rate. +

+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ +
+
‘drop_even, 1’
+

Only output odd frames, even frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111                           33333
+11111                           33333
+11111                           33333
+11111                           33333
+
+ +
+
‘drop_odd, 2’
+

Only output even frames, odd frames are dropped, generating a frame with +unchanged height at half frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+                22222                           44444
+                22222                           44444
+                22222                           44444
+                22222                           44444
+
+ +
+
‘pad, 3’
+

Expand each frame to full height, but pad alternate lines with black, +generating a frame with double height at the same input frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+11111           .....           33333           .....
+.....           22222           .....           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+
+Output:
+11111                           33333
+22222                           44444
+11111                           33333
+22222                           44444
+
+ + +
+
‘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 frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+11111           22222<-         33333           44444<-
+11111<-         22222           33333<-         44444
+
+Output:
+22222                           44444
+11111                           33333
+22222                           44444
+11111                           33333
+
+ + +
+
‘interlacex2, 6’
+

Double frame rate with unchanged height. Frames are inserted each +containing the second temporal field from the previous input frame and +the first temporal field from the next input frame. This mode relies on +the top_field_first flag. Useful for interlaced video displays with no +field synchronisation. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+11111           22222           33333           44444
+ 11111           22222           33333           44444
+
+Output:
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+11111   22222   22222   33333   33333   44444   44444
+ 11111   11111   22222   22222   33333   33333   44444
+
+ + +
+
‘mergex2, 7’
+

Move odd frames into the upper field, even into the lower field, +generating a double height frame at same frame rate. +

+
+
 ------> time
+Input:
+Frame 1         Frame 2         Frame 3         Frame 4
+
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+11111           22222           33333           44444
+
+Output:
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+11111           33333           33333           55555
+22222           22222           44444           44444
+
+ +
+
+ +

Numeric values are deprecated but are accepted for backward +compatibility reasons. +

+

Default mode is merge. +

+
+
flags
+

Specify flags influencing the filter process. +

+

Available value for flags is: +

+
+
low_pass_filter, vlpf
+

Enable linear vertical low-pass filtering in the filter. +Vertical low-pass filtering is required when creating an interlaced +destination from a progressive source which contains high-frequency +vertical detail. Filtering will reduce interlace ’twitter’ and Moire +patterning. +

+
+
complex_filter, cvlpf
+

Enable complex vertical low-pass filtering. +This will slightly less reduce interlace ’twitter’ and Moire +patterning but better retain detail and subjective sharpness impression. +

+
+
bypass_il
+

Bypass already interlaced frames, only adjust the frame rate. +

+
+ +

Vertical low-pass filtering and bypassing already interlaced frames can only be +enabled for mode interleave_top and interleave_bottom. +

+
+
+ + +

32.256 tmedian

+

Pick median pixels from several successive input video frames. +

+

The filter accepts the following options: +

+
+
radius
+

Set radius of median filter. +Default is 1. Allowed range is from 1 to 127. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

32.256.1 Commands

+ +

This filter supports all above options as commands, excluding option radius. +

+ +

32.257 tmidequalizer

+ +

Apply Temporal Midway Video Equalization effect. +

+

Midway Video Equalization adjusts a sequence of video frames to have the same +histograms, while maintaining their dynamics as much as possible. It’s +useful for e.g. matching exposures from a video frames sequence. +

+

This filter accepts the following option: +

+
+
radius
+

Set filtering radius. Default is 5. Allowed range is from 1 to 127. +

+
+
sigma
+

Set filtering sigma. Default is 0.5. This controls strength of filtering. +Setting this option to 0 effectively does nothing. +

+
+
planes
+

Set which planes to process. Default is 15, which is all available planes. +

+
+ + +

32.258 tmix

+ +

Mix successive video frames. +

+

A description of the accepted options follows. +

+
+
frames
+

The number of successive frames to mix. If unspecified, it defaults to 3. +

+
+
weights
+

Specify weight of each input video frame. +Each weight is separated by space. If number of weights is smaller than +number of frames last specified weight will be used for all remaining +unset weights. +

+
+
scale
+

Specify scale, if it is set it will be multiplied with sum +of each weight multiplied with pixel values to give final destination +pixel value. By default scale is auto scaled to sum of weights. +

+
+
planes
+

Set which planes to filter. Default is all. Allowed range is from 0 to 15. +

+
+ + +

32.258.1 Examples

+ +
    +
  • Average 7 successive frames: +
    +
    tmix=frames=7:weights="1 1 1 1 1 1 1"
    +
    + +
  • Apply simple temporal convolution: +
    +
    tmix=frames=3:weights="-1 3 -1"
    +
    + +
  • Similar as above but only showing temporal differences: +
    +
    tmix=frames=3:weights="-1 2 -1":scale=1
    +
    +
+ + +

32.258.2 Commands

+ +

This filter supports the following commands: +

+
weights
+
scale
+
planes
+

Syntax is same as option with same name. +

+
+ + +

32.259 tonemap

+

Tone map colors from different dynamic ranges. +

+

This filter expects data in single precision floating point, as it needs to +operate on (and can output) out-of-range values. Another filter, such as +zscale, is needed to convert the resulting frame to a usable format. +

+

The tonemapping algorithms implemented only work on linear light, so input +data should be linearized beforehand (and possibly correctly tagged). +

+
+
ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
+
+ + +

32.259.1 Options

+

The filter accepts the following options. +

+
+
tonemap
+

Set the tone map algorithm to use. +

+

Possible values are: +

+
none
+

Do not apply any tone map, only desaturate overbright pixels. +

+
+
clip
+

Hard-clip any out-of-range values. Use it for perfect color accuracy for +in-range values, while distorting out-of-range values. +

+
+
linear
+

Stretch the entire reference gamut to a linear multiple of the display. +

+
+
gamma
+

Fit a logarithmic transfer between the tone curves. +

+
+
reinhard
+

Preserve overall image brightness with a simple curve, using nonlinear +contrast, which results in flattening details and degrading color accuracy. +

+
+
hable
+

Preserve both dark and bright details better than reinhard, at the cost +of slightly darkening everything. Use it when detail preservation is more +important than color and brightness accuracy. +

+
+
mobius
+

Smoothly map out-of-range values, while retaining contrast and colors for +in-range material as much as possible. Use it when color accuracy is more +important than detail preservation. +

+
+ +

Default is none. +

+
+
param
+

Tune the tone mapping algorithm. +

+

This affects the following algorithms: +

+
none
+

Ignored. +

+
+
linear
+

Specifies the scale factor to use while stretching. +Default to 1.0. +

+
+
gamma
+

Specifies the exponent of the function. +Default to 1.8. +

+
+
clip
+

Specify an extra linear coefficient to multiply into the signal before clipping. +Default to 1.0. +

+
+
reinhard
+

Specify the local contrast coefficient at the display peak. +Default to 0.5, which means that in-gamut values will be about half as bright +as when clipping. +

+
+
hable
+

Ignored. +

+
+
mobius
+

Specify the transition point from linear to mobius transform. Every value +below this point is guaranteed to be mapped 1:1. The higher the value, the +more accurate the result will be, at the cost of losing bright details. +Default to 0.3, which due to the steep initial slope still preserves in-range +colors fairly accurately. +

+
+ +
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default of 2.0 is somewhat conservative and will mostly just apply to +skies or directly sunlit surfaces. A setting of 0.0 disables this option. +

+

This option works only if the input frame has a supported color tag. +

+
+
peak
+

Override signal/nominal/reference peak with this value. Useful when the +embedded peak information in display metadata is not reliable or when tone +mapping from a lower range to a higher range. +

+
+ + +

32.260 tpad

+ +

Temporarily pad video frames. +

+

The filter accepts the following options: +

+
+
start
+

Specify number of delay frames before input video stream. Default is 0. +

+
+
stop
+

Specify number of padding frames after input video stream. +Set to -1 to pad indefinitely. Default is 0. +

+
+
start_mode
+

Set kind of frames added to beginning of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of first frame. +Default is add. +

+
+
stop_mode
+

Set kind of frames added to end of stream. +Can be either add or clone. +With add frames of solid-color are added. +With clone frames are clones of last frame. +Default is add. +

+
+
start_duration, stop_duration
+

Specify the duration of the start/stop delay. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +These options override start and stop. Default is 0. +

+
+
color
+

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 color is "black". +

+
+ + +

32.261 transpose

+ +

Transpose rows with columns in the input video and optionally flip it. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘0, 4, cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip (default), that is: +

+
L.R     L.l
+. . ->  . .
+l.r     R.r
+
+ +
+
‘1, 5, clock’
+

Rotate by 90 degrees clockwise, that is: +

+
L.R     l.L
+. . ->  . .
+l.r     r.R
+
+ +
+
‘2, 6, cclock’
+

Rotate by 90 degrees counterclockwise, that is: +

+
L.R     R.r
+. . ->  . .
+l.r     L.l
+
+ +
+
‘3, 7, clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip, that is: +

+
L.R     r.R
+. . ->  . .
+l.r     l.L
+
+
+
+ +

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 passthrough option should be used instead. +

+

Numerical values are deprecated, and should be dropped in favor of +symbolic constants. +

+
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +

Default value is none. +

+
+ +

For example to rotate by 90 degrees clockwise and preserve portrait +layout: +

+
transpose=dir=1:passthrough=portrait
+
+ +

The command above can also be specified as: +

+
transpose=1:portrait
+
+ + +

32.262 trim

+

Trim the input so that the output contains one continuous subpart of the input. +

+

It accepts the following parameters: +

+
start
+

Specify the time of the start of the kept section, i.e. the frame with the +timestamp start will be the first frame in the output. +

+
+
end
+

Specify the time of the first frame that will be dropped, i.e. the frame +immediately preceding the one with the timestamp end will be the last +frame in the output. +

+
+
start_pts
+

This is the same as start, except this option sets the start timestamp +in timebase units instead of seconds. +

+
+
end_pts
+

This is the same as end, except this option sets the end timestamp +in timebase units instead of seconds. +

+
+
duration
+

The maximum duration of the output in seconds. +

+
+
start_frame
+

The number of the first frame that should be passed to the output. +

+
+
end_frame
+

The number of the first frame that should be dropped. +

+
+ +

start, end, and duration are expressed as time +duration specifications; see +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

Note that the first two sets of the start/end options and the 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 for the output timestamps to 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: +

    +
  • Drop everything except the second minute of input: +
    +
    ffmpeg -i INPUT -vf trim=60:120
    +
    + +
  • Keep only the first second: +
    +
    ffmpeg -i INPUT -vf trim=duration=1
    +
    + +
+ + +

32.263 unpremultiply

+

Apply alpha unpremultiply effect to input video stream using first plane +of second stream as alpha. +

+

Both streams must have same dimensions and same pixel format. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes will be processed, unprocessed planes will be copied. +By default value 0xf, all planes will be processed. +

+

If the format has 1 or 2 components, then luma is bit 0. +If the format has 3 or 4 components: +for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; +for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. +If present, the alpha channel is always the last bit. +

+
+
inplace
+

Do not require 2nd input for processing, instead use alpha plane from input stream. +

+
+ + +

32.264 unsharp

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. It must be an odd integer between +3 and 23. The default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. It must be an odd integer between 3 +and 23. The default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. It must be a floating point 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. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. It must be a floating point 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 0.0. +

+
+
alpha_msize_x, ax
+

Set the alpha matrix horizontal size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_msize_y, ay
+

Set the alpha matrix vertical size. It must be an odd integer +between 3 and 23. The default value is 5. +

+
+
alpha_amount, aa
+

Set the alpha effect strength. It must be a floating point 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 0.0. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

32.264.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    unsharp=7:7:-2:7:7:-2
    +
    +
+ + +

32.265 untile

+ +

Decompose a video made of tiled images into the individual images. +

+

The frame rate of the output video is the frame rate of the input video +multiplied by the number of tiles. +

+

This filter does the reverse of tile. +

+

The filter accepts the following options: +

+
+
layout
+

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. +

+
+ + +

32.265.1 Examples

+ +
    +
  • Produce a 1-second video from a still image file made of 25 frames stacked +vertically, like an analogic film reel: +
    +
    ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
    +
    +
+ + +

32.266 uspp

+ +

Apply ultra slow/simple postprocessing filter that compresses and decompresses +the image at several (or - in the case of quality level 8 - all) +shifts and average the results. +

+

The way this differs from the behavior of spp is that uspp actually encodes & +decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 +DCT similar to MJPEG. +

+

This filter is not available in ffmpeg versions between 5.0 and 6.0. +

+

The filter accepts the following options: +

+
+
quality
+

Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-8. If set to 0, the filter will have no +effect. A value of 8 means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +3. +

+
+
qp
+

Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). +

+
+
codec
+

Use specified codec instead of snow. +

+
+ + +

32.267 v360

+ +

Convert 360 videos between various formats. +

+

The filter accepts the following options: +

+
+
input
+
output
+

Set format of the input/output video. +

+

Available formats: +

+
+
‘e’
+
‘equirect’
+

Equirectangular projection. +

+
+
‘c3x2’
+
‘c6x1’
+
‘c1x6’
+

Cubemap with 3x2/6x1/1x6 layout. +

+

Format specific options: +

+
+
in_pad
+
out_pad
+

Set padding proportion for the input/output cubemap. Values in decimals. +

+

Example values: +

+
‘0’
+

No padding. +

+
‘0.01’
+

1% of face is padding. For example, with 1920x1280 resolution face size would be 640x640 and padding would be 3 pixels from each side. (640 * 0.01 = 6 pixels) +

+
+ +

Default value is ‘0’. +Maximum value is ‘0.1’. +

+
+
fin_pad
+
fout_pad
+

Set fixed padding for the input/output cubemap. Values in pixels. +

+

Default value is ‘0’. If greater than zero it overrides other padding options. +

+
+
in_forder
+
out_forder
+

Set order of faces for the input/output cubemap. Choose one direction for each position. +

+

Designation of directions: +

+
‘r’
+

right +

+
‘l’
+

left +

+
‘u’
+

up +

+
‘d’
+

down +

+
‘f’
+

forward +

+
‘b’
+

back +

+
+ +

Default value is ‘rludfb’. +

+
+
in_frot
+
out_frot
+

Set rotation of faces for the input/output cubemap. Choose one angle for each position. +

+

Designation of angles: +

+
‘0’
+

0 degrees clockwise +

+
‘1’
+

90 degrees clockwise +

+
‘2’
+

180 degrees clockwise +

+
‘3’
+

270 degrees clockwise +

+
+ +

Default value is ‘000000’. +

+
+ +
+
‘eac’
+

Equi-Angular Cubemap. +

+
+
‘flat’
+
‘gnomonic’
+
‘rectilinear’
+

Regular video. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘dfisheye’
+

Dual fisheye. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘barrel’
+
‘fb’
+
‘barrelsplit’
+

Facebook’s 360 formats. +

+
+
‘sg’
+

Stereographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘mercator’
+

Mercator format. +

+
+
‘ball’
+

Ball format, gives significant distortion toward the back. +

+
+
‘hammer’
+

Hammer-Aitoff map projection format. +

+
+
‘sinusoidal’
+

Sinusoidal map projection format. +

+
+
‘fisheye’
+

Fisheye projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘pannini’
+

Pannini projection. +

+

Format specific options: +

+
h_fov
+

Set output pannini parameter. +

+
+
ih_fov
+

Set input pannini parameter. +

+
+ +
+
‘cylindrical’
+

Cylindrical projection. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘perspective’
+

Perspective projection. (output only) +

+

Format specific options: +

+
v_fov
+

Set perspective parameter. +

+
+ +
+
‘tetrahedron’
+

Tetrahedron projection. +

+
+
‘tsp’
+

Truncated square pyramid projection. +

+
+
‘he’
+
‘hequirect’
+

Half equirectangular projection. +

+
+
‘equisolid’
+

Equisolid format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘og’
+

Orthographic format. +

+

Format specific options: +

+
h_fov
+
v_fov
+
d_fov
+

Set output horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+
ih_fov
+
iv_fov
+
id_fov
+

Set input horizontal/vertical/diagonal field of view. Values in degrees. +

+

If diagonal field of view is set it overrides horizontal and vertical field of view. +

+
+ +
+
‘octahedron’
+

Octahedron projection. +

+
+
‘cylindricalea’
+

Cylindrical Equal Area projection. +

+
+ +
+
interp
+

Set interpolation method.
+Note: more complex interpolation methods require much more memory to run. +

+

Available methods: +

+
+
‘near’
+
‘nearest’
+

Nearest neighbour. +

+
‘line’
+
‘linear’
+

Bilinear interpolation. +

+
‘lagrange9’
+

Lagrange9 interpolation. +

+
‘cube’
+
‘cubic’
+

Bicubic interpolation. +

+
‘lanc’
+
‘lanczos’
+

Lanczos interpolation. +

+
‘sp16’
+
‘spline16’
+

Spline16 interpolation. +

+
‘gauss’
+
‘gaussian’
+

Gaussian interpolation. +

+
‘mitchell’
+

Mitchell interpolation. +

+
+ +

Default value is ‘line’. +

+
+
w
+
h
+

Set the output video resolution. +

+

Default resolution depends on formats. +

+
+
in_stereo
+
out_stereo
+

Set the input/output stereo format. +

+
+
‘2d’
+

2D mono +

+
‘sbs’
+

Side by side +

+
‘tb’
+

Top bottom +

+
+ +

Default value is ‘2d’ for input and output format. +

+
+
yaw
+
pitch
+
roll
+

Set rotation for the output video. Values in degrees. +

+
+
rorder
+

Set rotation order for the output video. Choose one item for each position. +

+
+
‘y, Y’
+

yaw +

+
‘p, P’
+

pitch +

+
‘r, R’
+

roll +

+
+ +

Default value is ‘ypr’. +

+
+
h_flip
+
v_flip
+
d_flip
+

Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values. +

+
+
ih_flip
+
iv_flip
+

Set if input video is flipped horizontally/vertically. Boolean values. +

+
+
in_trans
+

Set if input video is transposed. Boolean value, by default disabled. +

+
+
out_trans
+

Set if output video needs to be transposed. Boolean value, by default disabled. +

+
+
h_offset
+
v_offset
+

Set output horizontal/vertical off-axis offset. Default is set to 0. +Allowed range is from -1 to 1. +

+
+
alpha_mask
+

Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled. +

+
+
reset_rot
+

Reset rotation of output video. Boolean value, by default disabled. +

+
+ + +

32.267.1 Examples

+ +
    +
  • Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation: +
    +
    ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
    +
    +
  • Extract back view of Equi-Angular Cubemap: +
    +
    ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
    +
    +
  • Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format: +
    +
    v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
    +
    +
+ + +

32.267.2 Commands

+ +

This filter supports subset of above options as commands. +

+ +

32.268 vaguedenoiser

+ +

Apply a wavelet based denoiser. +

+

It transforms each frame from the video input into the wavelet domain, +using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to +the obtained coefficients. It does an inverse wavelet transform after. +Due to wavelet properties, it should give a nice smoothed result, and +reduced noise, without blurring picture features. +

+

This filter accepts the following options: +

+
+
threshold
+

The filtering strength. The higher, the more filtered the video will be. +Hard thresholding can use a higher threshold than soft thresholding +before the video looks overfiltered. Default value is 2. +

+
+
method
+

The filtering method the filter will use. +

+

It accepts the following values: +

+
‘hard’
+

All values under the threshold will be zeroed. +

+
+
‘soft’
+

All values under the threshold will be zeroed. All values above will be +reduced by the threshold. +

+
+
‘garrote’
+

Scales or nullifies coefficients - intermediary between (more) soft and +(less) hard thresholding. +

+
+ +

Default is garrote. +

+
+
nsteps
+

Number of times, the wavelet will decompose the picture. Picture can’t +be decomposed beyond a particular point (typically, 8 for a 640x480 +frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. +

+
+
percent
+

Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. +

+
+
planes
+

A list of the planes to process. By default all planes are processed. +

+
+
type
+

The threshold type the filter will use. +

+

It accepts the following values: +

+
‘universal’
+

Threshold used is same for all decompositions. +

+
+
‘bayes’
+

Threshold used depends also on each decomposition coefficients. +

+
+ +

Default is universal. +

+
+ + +

32.269 varblur

+

Apply variable blur filter by using 2nd video stream to set blur radius. +The 2nd stream must have the same dimensions. +

+

This filter accepts the following options: +

+
+
min_r
+

Set min allowed radius. Allowed range is from 0 to 254. Default is 0. +

+
max_r
+

Set max allowed radius. Allowed range is from 1 to 255. Default is 8. +

+
planes
+

Set which planes to process. By default, all are used. +

+
+ +

The varblur filter also supports the framesync options. +

+ +

32.269.1 Commands

+ +

This filter supports all the above options as commands. +

+ +

32.270 vectorscope

+ +

Display 2 color component values in the two dimensional graph (which is called +a vectorscope). +

+

This filter accepts the following options: +

+
+
mode, m
+

Set vectorscope mode. +

+

It accepts the following values: +

+
‘gray’
+
‘tint’
+

Gray values are displayed on graph, higher brightness means more pixels have +same component color value on location in graph. This is the default mode. +

+
+
‘color’
+

Gray values are displayed on graph. Surrounding pixels values which are not +present in video frame are drawn in gradient of 2 color components which are +set by option x and y. The 3rd color component is static. +

+
+
‘color2’
+

Actual color components values present in video frame are displayed on graph. +

+
+
‘color3’
+

Similar as color2 but higher frequency of same values x and y +on graph increases value of another color component, which is luminance by +default values of x and y. +

+
+
‘color4’
+

Actual colors present in video frame are displayed on graph. If two different +colors map to same position on graph then color with higher value of component +not present in graph is picked. +

+
+
‘color5’
+

Gray values are displayed on graph. Similar to color but with 3rd color +component picked from radial gradient. +

+
+ +
+
x
+

Set which color component will be represented on X-axis. Default is 1. +

+
+
y
+

Set which color component will be represented on Y-axis. Default is 2. +

+
+
intensity, i
+

Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness +of color component which represents frequency of (X, Y) location in graph. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, even darkest single pixel will be clearly highlighted. +

+
+
‘peak’
+

Hold maximum and minimum values presented in graph over time. This way you +can still spot out of range values without constantly looking at vectorscope. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
graticule, g
+

Set what kind of graticule to draw. +

+
‘none’
+
‘green’
+
‘color’
+
‘invert’
+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, f
+

Set graticule flags. +

+
+
‘white’
+

Draw graticule for white point. +

+
+
‘black’
+

Draw graticule for black point. +

+
+
‘name’
+

Draw color points short names. +

+
+ +
+
bgopacity, b
+

Set background opacity. +

+
+
lthreshold, l
+

Set low threshold for color component not represented on X or Y axis. +Values lower than this value will be ignored. Default is 0. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and low threshold value of 0.1 actual threshold +is 0.1 * 255 = 25. +

+
+
hthreshold, h
+

Set high threshold for color component not represented on X or Y axis. +Values higher than this value will be ignored. Default is 1. +Note this value is multiplied with actual max possible value one pixel component +can have. So for 8-bit input and high threshold value of 0.9 actual threshold +is 0.9 * 255 = 230. +

+
+
colorspace, c
+

Set what kind of colorspace to use when drawing graticule. +

+
‘auto’
+
‘601’
+
‘709’
+
+

Default is auto. +

+
+
tint0, t0
+
tint1, t1
+

Set color tint for gray/tint vectorscope mode. By default both options are zero. +This means no tint, and output will remain gray. +

+
+ + +

32.271 vidstabdetect

+ +

Analyze video stabilization/deshaking. Perform pass 1 of 2, see +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 vidstabtransform filter. +

+

To enable compilation of this filter you need to configure FFmpeg with +--enable-libvidstab. +

+

This filter accepts the following options: +

+
+
result
+

Set the path to the file used to write the transforms information. +Default value is transforms.trf. +

+
+
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. +

+
+
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 15. +

+
+
stepsize
+

Set stepsize of the search process. The region around minimum is +scanned with 1 pixel resolution. Default value is 6. +

+
+
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. +

+
+
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. +

+
+
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. +

+
+
fileformat
+

Format for the transforms data file to be written. +Acceptable values are +

+
+
‘ascii’
+

Human-readable plain text +

+
+
‘binary’
+

Binary format, roughly 40% smaller than ascii. (default) +

+
+ +
+
+ + +

32.271.1 Examples

+ +
    +
  • Use default values: +
    +
    vidstabdetect
    +
    + +
  • Analyze strongly shaky movie and put the results in file +mytransforms.trf: +
    +
    vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
    +
    + +
  • Visualize the result of internal transformations in the resulting +video: +
    +
    vidstabdetect=show=1
    +
    + +
  • Analyze a video with medium shakiness using ffmpeg: +
    +
    ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
    +
    +
+ + +

32.272 vidstabtransform

+ +

Video stabilization/deshaking: pass 2 of 2, +see vidstabdetect for pass 1. +

+

Read a file with transform information for each frame and +apply/compensate them. Together with the vidstabdetect +filter this can be used to deshake videos. See also +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 +--enable-libvidstab. +

+ +

32.272.1 Options

+ +
+
input
+

Set path to the file used to read the transforms. Default value is +transforms.trf. +

+
+
smoothing
+

Set the number of frames (value*2 + 1) used for lowpass filtering the +camera movements. Default value is 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 value leads to a smoother video, but limits the acceleration of +the camera (pan/tilt movements). 0 is a special case where a static +camera is simulated. +

+
+
optalgo
+

Set the camera path optimization algorithm. +

+

Accepted values are: +

+
‘gauss’
+

gaussian kernel low-pass filter on camera motion (default) +

+
‘avg’
+

averaging on transformations +

+
+ +
+
maxshift
+

Set maximal number of pixels to translate frames. Default value is -1, +meaning no limit. +

+
+
maxangle
+

Set maximal angle in radians (degree*PI/180) to rotate frames. Default +value is -1, meaning no limit. +

+
+
crop
+

Specify how to deal with borders that may be visible due to movement +compensation. +

+

Available values are: +

+
‘keep’
+

keep image information from previous frame (default) +

+
‘black’
+

fill the border black +

+
+ +
+
invert
+

Invert transforms if set to 1. Default value is 0. +

+
+
relative
+

Consider transforms as relative to previous frame if set to 1, +absolute if set to 0. Default value is 0. +

+
+
zoom
+

Set percentage to zoom. A positive value will result in a zoom-in +effect, a negative value in a zoom-out effect. Default value is 0 (no +zoom). +

+
+
optzoom
+

Set optimal zooming to avoid borders. +

+

Accepted values are: +

+
‘0’
+

disabled +

+
‘1’
+

optimal static zoom value is determined (only very strong movements +will lead to visible borders) (default) +

+
‘2’
+

optimal adaptive zoom value is determined (no borders will be +visible), see zoomspeed +

+
+ +

Note that the value given at zoom is added to the one calculated here. +

+
+
zoomspeed
+

Set percent to zoom maximally each frame (enabled when +optzoom is set to 2). Range is from 0 to 5, default value is +0.25. +

+
+
interpol
+

Specify type of interpolation. +

+

Available values are: +

+
‘no’
+

no interpolation +

+
‘linear’
+

linear only horizontal +

+
‘bilinear’
+

linear in both directions (default) +

+
‘bicubic’
+

cubic in both directions (slow) +

+
+ +
+
tripod
+

Enable virtual tripod mode if set to 1, which is equivalent to +relative=0:smoothing=0. Default value is 0. +

+

Use also tripod option of vidstabdetect. +

+
+
debug
+

Increase log verbosity if set to 1. Also the detected global motions +are written to the temporary file global_motions.trf. Default +value is 0. +

+
+ + +

32.272.2 Examples

+ +
    +
  • Use ffmpeg for a typical stabilization with default values: +
    +
    ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
    +
    + +

    Note the use of the unsharp filter which is always recommended. +

    +
  • Zoom in a bit more and load transform data from a given file: +
    +
    vidstabtransform=zoom=5:input="mytransforms.trf"
    +
    + +
  • Smoothen the video even more: +
    +
    vidstabtransform=smoothing=30
    +
    +
+ + +

32.273 vflip

+ +

Flip the input video vertically. +

+

For example, to vertically flip a video with ffmpeg: +

+
ffmpeg -i in.avi -vf "vflip" out.avi
+
+ + +

32.274 vfrdet

+ +

Detect variable frame rate video. +

+

This filter tries to detect if the input is variable or constant frame rate. +

+

At end it will output number of frames detected as having variable delta pts, +and ones with constant delta pts. +If there was frames with variable delta, than it will also show min, max and +average delta encountered. +

+ +

32.275 vibrance

+ +

Boost or alter saturation. +

+

The filter accepts the following options: +

+
intensity
+

Set strength of boost if positive value or strength of alter if negative value. +Default is 0. Allowed range is from -2 to 2. +

+
+
rbal
+

Set the red balance. Default is 1. Allowed range is from -10 to 10. +

+
+
gbal
+

Set the green balance. Default is 1. Allowed range is from -10 to 10. +

+
+
bbal
+

Set the blue balance. Default is 1. Allowed range is from -10 to 10. +

+
+
rlum
+

Set the red luma coefficient. +

+
+
glum
+

Set the green luma coefficient. +

+
+
blum
+

Set the blue luma coefficient. +

+
+
alternate
+

If intensity is negative and this is set to 1, colors will change, +otherwise colors will be less saturated, more towards gray. +

+
+ + +

32.275.1 Commands

+ +

This filter supports the all above options as commands. +

+ +

32.276 vif

+ +

Obtain the average VIF (Visual Information Fidelity) between two input videos. +

+

This filter takes two input videos. +

+

Both input videos 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 VIF score is printed through the logging system. +

+

The filter stores the calculated VIF score of each frame. +

+

This filter also supports the framesync options. +

+

In the below example the input file main.mpg being processed is compared +with the reference file ref.mpg. +

+
+
ffmpeg -i main.mpg -i ref.mpg -lavfi vif -f null -
+
+ + +

32.277 vignette

+ +

Make or reverse a natural vignetting effect. +

+

The filter accepts the following options: +

+
+
angle, a
+

Set lens angle expression as a number of radians. +

+

The value is clipped in the [0,PI/2] range. +

+

Default value: "PI/5" +

+
+
x0
+
y0
+

Set center coordinates expressions. Respectively "w/2" and "h/2" +by default. +

+
+
mode
+

Set forward/backward mode. +

+

Available modes are: +

+
‘forward’
+

The larger the distance from the central point, the darker the image becomes. +

+
+
‘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 angle and other settings (yet). It can +also be used to create a burning effect. +

+
+ +

Default value is ‘forward’. +

+
+
eval
+

Set evaluation mode for the expressions (angle, x0, y0). +

+

It accepts the following values: +

+
‘init’
+

Evaluate expressions only once during the filter initialization. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. This is way slower than the +‘init’ mode since it requires all the scalers to be re-computed, but it +allows advanced dynamic expressions. +

+
+ +

Default value is ‘init’. +

+
+
dither
+

Set dithering to reduce the circular banding effects. Default is 1 +(enabled). +

+
+
aspect
+

Set vignette aspect. This setting allows one 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 1/1. +

+
+ + +

32.277.1 Expressions

+ +

The alpha, x0 and y0 expressions can contain the +following parameters. +

+
+
w
+
h
+

input width and height +

+
+
n
+

the number of input frame, starting from 0 +

+
+
pts
+

the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in +TB units, NAN if undefined +

+
+
r
+

frame rate of the input video, NAN if the input frame rate is unknown +

+
+
t
+

the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined +

+
+
tb
+

time base of the input video +

+
+ + + +

32.277.2 Examples

+ +
    +
  • Apply simple strong vignetting effect: +
    +
    vignette=PI/4
    +
    + +
  • Make a flickering vignetting: +
    +
    vignette='PI/4+random(1)*PI/50':eval=frame
    +
    + +
+ + +

32.278 vmafmotion

+ +

Obtain the average VMAF motion score of a video. +It is one of the component metrics of VMAF. +

+

The obtained average motion score is printed through the logging system. +

+

The filter accepts the following options: +

+
+
stats_file
+

If specified, the filter will use the named file to save the motion score of +each frame with respect to the previous frame. +When filename equals "-" the data is sent to standard output. +

+
+ +

Example: +

+
ffmpeg -i ref.mpg -vf vmafmotion -f null -
+
+ + +

32.279 vpp_amf

+ +

Scale (resize) and convert colorspace, transfer characteristics or color primaries for the input video, using AMD Advanced Media Framework library for hardware acceleration. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
scale_type
+

Sets the algorithm used for scaling: +

+
+
bilinear
+

Bilinear +

+

This is the default. +

+
+
bicubic
+

Bicubic +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+ +
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
color_profile
+

Specify all color properties at once. +

+

The accepted values are: +

+
‘bt601’
+

BT.601 +

+
+
‘bt709’
+

BT.709 +

+
+
‘bt2020’
+

BT.2020 +

+
+
+ +
+
trc
+

Specify output transfer characteristics. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘gamma22’
+

Constant gamma of 2.2 +

+
+
‘gamma28’
+

Constant gamma of 2.8 +

+
+
‘smpte170m’
+

SMPTE-170M +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘linear’
+

Linear +

+
+
‘log’
+

LOG +

+
+
‘log-sqrt’
+

LOG_SQRT +

+
+
‘iec61966-2-4’
+

iec61966-2-4 +

+
+
‘bt1361-ecg’
+

BT1361_ECG +

+
+
‘iec61966-2-1’
+

iec61966-2-1 +

+
+
‘bt2020-10’
+

BT.2020 for 10-bits content +

+
+
‘bt2020-12’
+

BT.2020 for 12-bits content +

+
+
‘smpte2084’
+

SMPTE2084 +

+
+
‘smpte428’
+

SMPTE428 +

+
+
‘arib-std-b67’
+

ARIB_STD_B67 +

+
+
+ +
+
primaries
+

Specify output color primaries. +

+

The accepted values are: +

+
‘bt709’
+

BT.709 +

+
+
‘bt470m’
+

BT.470M +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘film’
+

film +

+
+
‘bt2020’
+

BT.2020 +

+
+
‘smpte428’
+

SMPTE-428 +

+
+
‘smpte431’
+

SMPTE-431 +

+
+
‘smpte432’
+

SMPTE-432 +

+
+
‘jedec-p22’
+

JEDEC P22 phosphors +

+
+
+
+
+ + +

32.279.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    vpp_amf=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K and change color profile to bt2020. +
    +
    vpp_amf=4096:2160:color_profile=bt2020
    +
    +
+ + +

32.280 vstack

+

Stack input videos vertically. +

+

All streams must be of same pixel format and of same width. +

+

Note that this filter is faster than using overlay and pad filter +to create same output. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+ + +

32.281 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. +

+

This filter uses 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 setfield filter before w3fdif filter. +

+

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: +

+
+
filter
+

Set the interlacing filter coefficients. Accepts one of the following values: +

+
+
‘simple’
+

Simple filter coefficient set. +

+
‘complex’
+

More-complex filter coefficient set. +

+
+

Default value is ‘complex’. +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
frame
+

Output one frame for each frame. +

+
field
+

Output one frame for each field. +

+
+ +

The default value is field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
tff
+

Assume the top field is first. +

+
bff
+

Assume the bottom field is first. +

+
auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following values: +

+
+
‘all’
+

Deinterlace all frames, +

+
‘interlaced’
+

Only deinterlace frames marked as interlaced. +

+
+ +

Default value is ‘all’. +

+
+ + +

32.281.1 Commands

+

This filter supports same commands as options. +

+ +

32.282 waveform

+

Video waveform monitor. +

+

The waveform monitor plots color component intensity. By default luma +only. Each column of the waveform corresponds to a column of pixels in the +source video. +

+

It accepts the following options: +

+
+
mode, m
+

Can be either row, or column. Default is column. +In row mode, the graph on the left side represents color component value 0 and +the right side represents value = 255. In column mode, the top side represents +color component value = 0 and bottom side represents value = 255. +

+
+
intensity, i
+

Set intensity. Smaller values are useful to find out how many values of the same +luminance are distributed across input rows/columns. +Default value is 0.04. Allowed range is [0, 1]. +

+
+
mirror, r
+

Set mirroring mode. 0 means unmirrored, 1 means mirrored. +In mirrored mode, higher values will be represented on the left +side for row mode and at the top for column mode. Default is +1 (mirrored). +

+
+
display, d
+

Set display mode. +It accepts the following values: +

+
‘overlay’
+

Presents information identical to that in the parade, except +that the graphs representing color components are superimposed directly +over one another. +

+

This display mode makes it easier to spot relative differences or similarities +in overlapping areas of the color components that are supposed to be identical, +such as neutral whites, grays, or blacks. +

+
+
‘stack’
+

Display separate graph for the color components side by side in +row mode or one below the other in column mode. +

+
+
‘parade’
+

Display separate graph for the color components side by side in +column mode or one below the other in row mode. +

+

Using this display mode makes it easy to spot color casts in the highlights +and shadows of an image, by comparing the contours of the top and the bottom +graphs of each waveform. Since whites, grays, and blacks are characterized +by exactly equal amounts of red, green, and blue, neutral areas of the picture +should display three waveforms of roughly equal width/height. If not, the +correction is easy to perform by making level adjustments the three waveforms. +

+
+

Default is stack. +

+
+
components, c
+

Set which color components to display. Default is 1, which means only luma +or red color component if input is in RGB colorspace. If is set for example to +7 it will display all 3 (if) available color components. +

+
+
envelope, e
+
+
‘none’
+

No envelope, this is default. +

+
+
‘instant’
+

Instant envelope, minimum and maximum values presented in graph will be easily +visible even with small step value. +

+
+
‘peak’
+

Hold minimum and maximum values presented in graph across time. This way you +can still spot out of range values without constantly looking at waveforms. +

+
+
‘peak+instant’
+

Peak and instant envelope combined together. +

+
+ +
+
filter, f
+
+
‘lowpass’
+

No filtering, this is default. +

+
+
‘flat’
+

Luma and chroma combined together. +

+
+
‘aflat’
+

Similar as above, but shows difference between blue and red chroma. +

+
+
‘xflat’
+

Similar as above, but use different colors. +

+
+
‘yflat’
+

Similar as above, but again with different colors. +

+
+
‘chroma’
+

Displays only chroma. +

+
+
‘color’
+

Displays actual color value on waveform. +

+
+
‘acolor’
+

Similar as above, but with luma showing frequency of chroma values. +

+
+ +
+
graticule, g
+

Set which graticule to display. +

+
+
‘none’
+

Do not display graticule. +

+
+
‘green’
+

Display green graticule showing legal broadcast ranges. +

+
+
‘orange’
+

Display orange graticule showing legal broadcast ranges. +

+
+
‘invert’
+

Display invert graticule showing legal broadcast ranges. +

+
+ +
+
opacity, o
+

Set graticule opacity. +

+
+
flags, fl
+

Set graticule flags. +

+
+
‘numbers’
+

Draw numbers above lines. By default enabled. +

+
+
‘dots’
+

Draw dots instead of lines. +

+
+ +
+
scale, s
+

Set scale used for displaying graticule. +

+
+
‘digital’
+
‘millivolts’
+
‘ire’
+
+

Default is digital. +

+
+
bgopacity, b
+

Set background opacity. +

+
+
tint0, t0
+
tint1, t1
+

Set tint for output. +Only used with lowpass filter and when display is not overlay and input +pixel formats are not RGB. +

+
+
fitmode, fm
+

Set sample aspect ratio of video output frames. +Can be used to configure waveform so it is not +stretched too much in one of directions. +

+
+
‘none’
+

Set sample aspect ration to 1/1. +

+
‘size’
+

Set sample aspect ratio to match input size of video +

+
+

Default is ‘none’. +

+
+
input
+

Set input formats for filter to pick from. +Can be ‘all’, for selecting from all available formats, +or ‘first’, for selecting first available format. +Default is ‘first’. +

+
+ + +

32.283 weave, doubleweave

+ +

The weave takes a field-based video input and join +each two sequential fields into single frame, producing a new double +height clip with half the frame rate and half the frame count. +

+

The doubleweave works same as weave but without +halving frame rate and frame count. +

+

It accepts the following option: +

+
+
first_field
+

Set first field. Available values are: +

+
+
‘top, t’
+

Set the frame as top-field-first. +

+
+
‘bottom, b’
+

Set the frame as bottom-field-first. +

+
+
+
+ + +

32.283.1 Examples

+ +
    +
  • Interlace video using select and separatefields filter: +
    +
    separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
    +
    +
+ + +

32.284 xbr

+

Apply the xBR high-quality magnification filter which is designed for pixel +art. It follows a set of edge-detection rules, see +https://forums.libretro.com/t/xbr-algorithm-tutorial/123. +

+

It accepts the following option: +

+
+
n
+

Set the scaling dimension: 2 for 2xBR, 3 for +3xBR and 4 for 4xBR. +Default is 3. +

+
+ + +

32.285 xcorrelate

+

Apply normalized cross-correlation between first and second input video stream. +

+

Second input video stream dimensions must be lower than first input video stream. +

+

The filter accepts the following options: +

+
+
planes
+

Set which planes to process. +

+
+
secondary
+

Set which secondary video frames will be processed from second input video stream, +can be first or all. Default is all. +

+
+ +

The xcorrelate filter also supports the framesync options. +

+ +

32.286 xfade

+ +

Apply cross fade from one input video stream to another input video stream. +The cross fade is applied for specified duration. +

+

Both inputs must be constant frame-rate and have the same resolution, pixel format, +frame rate and timebase. +

+

The filter accepts the following options: +

+
+
transition
+

Set one of available transition effects: +

+
+
‘custom’
+
‘fade’
+
‘wipeleft’
+
‘wiperight’
+
‘wipeup’
+
‘wipedown’
+
‘slideleft’
+
‘slideright’
+
‘slideup’
+
‘slidedown’
+
‘circlecrop’
+
‘rectcrop’
+
‘distance’
+
‘fadeblack’
+
‘fadewhite’
+
‘radial’
+
‘smoothleft’
+
‘smoothright’
+
‘smoothup’
+
‘smoothdown’
+
‘circleopen’
+
‘circleclose’
+
‘vertopen’
+
‘vertclose’
+
‘horzopen’
+
‘horzclose’
+
‘dissolve’
+
‘pixelize’
+
‘diagtl’
+
‘diagtr’
+
‘diagbl’
+
‘diagbr’
+
‘hlslice’
+
‘hrslice’
+
‘vuslice’
+
‘vdslice’
+
‘hblur’
+
‘fadegrays’
+
‘wipetl’
+
‘wipetr’
+
‘wipebl’
+
‘wipebr’
+
‘squeezeh’
+
‘squeezev’
+
‘zoomin’
+
‘fadefast’
+
‘fadeslow’
+
‘hlwind’
+
‘hrwind’
+
‘vuwind’
+
‘vdwind’
+
‘coverleft’
+
‘coverright’
+
‘coverup’
+
‘coverdown’
+
‘revealleft’
+
‘revealright’
+
‘revealup’
+
‘revealdown’
+
+

Default transition effect is fade. +

+
+
duration
+

Set cross fade duration in seconds. +Range is 0 to 60 seconds. +Default duration is 1 second. +

+
+
offset
+

Set cross fade start relative to first input stream in seconds. +Default offset is 0. +

+
+
expr
+

Set expression for custom transition effect. +

+

The expressions can use the following variables and functions: +

+
+
X
+
Y
+

The coordinates of the current sample. +

+
+
W
+
H
+

The width and height of the image. +

+
+
P
+

Progress of transition effect. +

+
+
PLANE
+

Currently processed plane. +

+
+
A
+

Return value of first input at current location and plane. +

+
+
B
+

Return value of second input at current location and plane. +

+
+
a0(x, y)
+
a1(x, y)
+
a2(x, y)
+
a3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of first input. +

+
+
b0(x, y)
+
b1(x, y)
+
b2(x, y)
+
b3(x, y)
+

Return the value of the pixel at location (x,y) of the +first/second/third/fourth component of second input. +

+
+
+
+ + +

32.286.1 Examples

+ +
    +
  • Cross fade from one input video to another input video, with fade transition and duration of transition +of 2 seconds starting at offset of 5 seconds: +
    +
    ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
    +
    +
+ + +

32.287 xmedian

+

Pick median pixels from several input videos. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of inputs. +Default is 3. Allowed range is from 3 to 255. +If number of inputs is even number, than result will be mean value between two median values. +

+
+
planes
+

Set which planes to filter. Default value is 15, by which all planes are processed. +

+
+
percentile
+

Set median percentile. Default value is 0.5. +Default value of 0.5 will pick always median values, while 0 will pick +minimum values, and 1 maximum values. +

+
+ + +

32.287.1 Commands

+ +

This filter supports all above options as commands, excluding option inputs. +

+ +

32.288 xpsnr

+ +

Obtain the average (across all input frames) and minimum (across all color plane averages) +eXtended Perceptually weighted peak Signal-to-Noise Ratio (XPSNR) between two input videos. +

+

The XPSNR is a low-complexity psychovisually motivated distortion measurement algorithm for +assessing the difference between two video streams or images. This is especially useful for +objectively quantifying the distortions caused by video and image codecs, as an alternative +to a formal subjective test. The logarithmic XPSNR output values are in a similar range as +those of traditional psnr assessments but better reflect human impressions of visual +coding quality. More details on the XPSNR measure, which essentially represents a blockwise +weighted variant of the PSNR measure, can be found in the following freely available papers: +

+
    +
  • C. R. Helmrich, M. Siekmann, S. Becker, S. Bosse, D. Marpe, and T. Wiegand, "XPSNR: A +Low-Complexity Extension of the Perceptually Weighted Peak Signal-to-Noise Ratio for +High-Resolution Video Quality Assessment," in Proc. IEEE Int. Conf. Acoustics, Speech, +Sig. Process. (ICASSP), virt./online, May 2020. www.ecodis.de/xpsnr.htm + +
  • C. R. Helmrich, S. Bosse, H. Schwarz, D. Marpe, and T. Wiegand, "A Study of the +Extended Perceptually Weighted Peak Signal-to-Noise Ratio (XPSNR) for Video Compression +with Different Resolutions and Bit Depths," ITU Journal: ICT Discoveries, vol. 3, no. +1, pp. 65 - 72, May 2020. http://handle.itu.int/11.1002/pub/8153d78b-en +
+ +

When publishing the results of XPSNR assessments obtained using, e.g., this FFmpeg filter, a +reference to the above papers as a means of documentation is strongly encouraged. The filter +requires two input videos. The first input is considered a (usually not distorted) reference +source and is passed unchanged to the output, whereas the second input is a (distorted) test +signal. Except for the bit depth, these two video inputs must have the same pixel format. In +addition, for best performance, both compared input videos should be in YCbCr color format. +

+

The obtained overall XPSNR values mentioned above are printed through the logging system. In +case of input with multiple color planes, we suggest reporting of the minimum XPSNR average. +

+

The following parameter, which behaves like the one for the psnr filter, is accepted: +

+
+
stats_file, f
+

If specified, the filter will use the named file to save the XPSNR value of each individual +frame and color plane. When the file name equals "-", that data is sent to standard output. +

+
+ +

This filter also supports the framesync options. +

+ +

32.288.1 Examples

+
    +
  • XPSNR analysis of two 1080p HD videos, ref_source.yuv and test_video.yuv, both at 24 frames +per second, with color format 4:2:0, bit depth 8, and output of a logfile named "xpsnr.log": +
    +
    ffmpeg -s 1920x1080 -framerate 24 -pix_fmt yuv420p -i ref_source.yuv -s 1920x1080 -framerate
    +24 -pix_fmt yuv420p -i test_video.yuv -lavfi xpsnr="stats_file=xpsnr.log" -f null -
    +
    + +
  • XPSNR analysis of two 2160p UHD videos, ref_source.yuv with bit depth 8 and test_video.yuv +with bit depth 10, both at 60 frames per second with color format 4:2:0, no logfile output: +
    +
    ffmpeg -s 3840x2160 -framerate 60 -pix_fmt yuv420p -i ref_source.yuv -s 3840x2160 -framerate
    +60 -pix_fmt yuv420p10le -i test_video.yuv -lavfi xpsnr="stats_file=-" -f null -
    +
    +
+ + +

32.289 xstack

+

Stack video inputs into custom layout. +

+

All streams must be of same pixel format. +

+

The filter accepts the following options: +

+
+
inputs
+

Set number of input streams. Default is 2. +

+
+
layout
+

Specify layout of inputs. +This option requires the desired layout configuration to be explicitly set by the user. +This sets position of each video input in output. Each input +is separated by ’|’. +The first number represents the column, and the second number represents the row. +Numbers start at 0 and are separated by ’_’. Optionally one can use wX and hX, +where X is video input from which to take width or height. +Multiple values can be used when separated by ’+’. In such +case values are summed together. +

+

Note that if inputs are of different sizes gaps may appear, as not all of +the output video frame will be filled. Similarly, videos can overlap each +other if their position doesn’t leave enough space for the full frame of +adjoining videos. +

+

For 2 inputs, a default layout of 0_0|w0_0 (equivalent to +grid=2x1) is set. In all other cases, a layout or a grid must be set by +the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
grid
+

Specify a fixed size grid of inputs. +This option is used to create a fixed size grid of the input streams. Set the +grid size in the form COLUMNSxROWS. There must be ROWS * COLUMNS +input streams and they will be arranged as a grid with ROWS rows and +COLUMNS columns. When using this option, each input stream within a row +must have the same height and all the rows must have the same width. +

+

If grid is set, then inputs option is ignored and is implicitly +set to ROWS * COLUMNS. +

+

For 2 inputs, a default grid of 2x1 (equivalent to +layout=0_0|w0_0) is set. In all other cases, a layout or a grid must be +set by the user. Either grid or layout can be specified at a time. +Specifying both will result in an error. +

+
+
shortest
+

If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. +

+
+
fill
+

If set to valid color, all unused pixels will be filled with that color. +By default fill is set to none, so it is disabled. +

+
+ + +

32.289.1 Examples

+ +
    +
  • Display 4 inputs into 2x2 grid. + +

    Layout: +

    +
    input1(0, 0)  | input3(w0, 0)
    +input2(0, h0) | input4(w0, h0)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 4 inputs into 1x4 grid. + +

    Layout: +

    +
    input1(0, 0)
    +input2(0, h0)
    +input3(0, h0+h1)
    +input4(0, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
    +
    + +

    Note that if inputs are of different widths, unused space will appear. +

    +
  • Display 9 inputs into 3x3 grid. + +

    Layout: +

    +
    input1(0, 0)       | input4(w0, 0)      | input7(w0+w3, 0)
    +input2(0, h0)      | input5(w0, h0)     | input8(w0+w3, h0)
    +input3(0, h0+h1)   | input6(w0, h0+h1)  | input9(w0+w3, h0+h1)
    +
    + +
    +
    xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
  • Display 16 inputs into 4x4 grid. + +

    Layout: +

    +
    input1(0, 0)       | input5(w0, 0)       | input9 (w0+w4, 0)       | input13(w0+w4+w8, 0)
    +input2(0, h0)      | input6(w0, h0)      | input10(w0+w4, h0)      | input14(w0+w4+w8, h0)
    +input3(0, h0+h1)   | input7(w0, h0+h1)   | input11(w0+w4, h0+h1)   | input15(w0+w4+w8, h0+h1)
    +input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
    +
    + +
    +
    xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0|
    +w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2
    +
    + +

    Note that if inputs are of different sizes, gaps or overlaps may occur. +

    +
+ + +

32.290 yadif

+ +

Deinterlace the input video ("yadif" means "yet another deinterlacing +filter"). +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

32.291 yaepblur

+ +

Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter"). +The algorithm is described in +"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980." +

+

It accepts the following parameters: +

+
+
radius, r
+

Set the window radius. Default value is 3. +

+
+
planes, p
+

Set which planes to filter. Default is only the first plane. +

+
+
sigma, s
+

Set blur strength. Default value is 128. +

+
+ + +

32.291.1 Commands

+

This filter supports same commands as options. +

+ +

32.292 zoompan

+ +

Apply Zoom & Pan effect. +

+

This filter accepts the following options: +

+
+
zoom, z
+

Set the zoom expression. Range is 1-10. Default is 1. +

+
+
x
+
y
+

Set the x and y expression. Default is 0. +

+
+
d
+

Set the duration expression in number of frames. +This sets for how many number of frames effect will last for +single input image. Default is 90. +

+
+
s
+

Set the output image size, default is ’hd720’. +

+
+
fps
+

Set the output frame rate, default is ’25’. +

+
+ +

Each expression can contain the following constants: +

+
+
in_w, iw
+

Input width. +

+
+
in_h, ih
+

Input height. +

+
+
out_w, ow
+

Output width. +

+
+
out_h, oh
+

Output height. +

+
+
in
+

Input frame count. +

+
+
on
+

Output frame count. +

+
+
in_time, it
+

The input timestamp expressed in seconds. It’s NAN if the input timestamp is unknown. +

+
+
out_time, time, ot
+

The output timestamp expressed in seconds. +

+
+
x
+
y
+

Last calculated ’x’ and ’y’ position from ’x’ and ’y’ expression +for current input frame. +

+
+
px
+
py
+

’x’ and ’y’ of last output frame of previous input frame or 0 when there was +not yet such frame (first input frame). +

+
+
zoom
+

Last calculated zoom from ’z’ expression for current input frame. +

+
+
pzoom
+

Last calculated zoom of last output frame of previous input frame. +

+
+
duration
+

Number of output frames for current input frame. Calculated from ’d’ expression +for each input frame. +

+
+
pduration
+

number of output frames created for previous input frame +

+
+
a
+

Rational number: input width / input height +

+
+
sar
+

sample aspect ratio +

+
+
dar
+

display aspect ratio +

+
+
+ + +

32.292.1 Examples

+ +
    +
  • Zoom in up to 1.5x and pan at same time to some spot near center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360
    +
    + +
  • Zoom in up to 1.5x and pan always at center of picture: +
    +
    zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Same as above but without pausing: +
    +
    zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
  • Zoom in 2x into center of picture only for the first second of the input video: +
    +
    zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
    +
    + +
+ + +

32.293 zscale

+

Scale (resize) the input video, using the z.lib library: +https://github.com/sekrit-twc/zimg. To enable compilation of this +filter, you need to configure FFmpeg with --enable-libzimg. +

+

The zscale filter forces the output display aspect ratio to be the same +as the input, by changing the output sample aspect ratio. +

+

If the input image format is different from the format requested by +the next filter, the zscale filter will convert the input to the +requested format. +

+ +

32.293.1 Options

+

The filter accepts the following options. +

+
+
width, w
+
height, h
+

Set the output video dimension expression. Default value is the input +dimension. +

+

If the width or w value is 0, the input width is used for +the output. If the height or h value is 0, the input height +is used for the output. +

+

If one and only one of the values is -n with n >= 1, the zscale filter +will use a value that maintains the aspect ratio of the input image, +calculated from the other specified dimension. After that it will, +however, make sure that the calculated dimension is divisible by n and +adjust the value if necessary. +

+

If both values are -n with n >= 1, the behavior will be identical to +both values being set to 0 as previously detailed. +

+

See below for the list of accepted constants for use in the dimension +expression. +

+
+
size, s
+

Set the video size. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
dither, d
+

Set the dither type. +

+

Possible values are: +

+
none
+
ordered
+
random
+
error_diffusion
+
+ +

Default is none. +

+
+
filter, f
+

Set the resize filter type. +

+

Possible values are: +

+
point
+
bilinear
+
bicubic
+
spline16
+
spline36
+
spline64
+
lanczos
+
+ +

Default is bilinear. +

+
+
range, r
+

Set the color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
smpte2084
+
iec61966-2-1
+
arib-std-b67
+
+ +

Default is same as input. +

+
+
matrix, m
+

Set the colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +

Default is same as input. +

+
+
rangein, rin
+

Set the input color range. +

+

Possible values are: +

+
input
+
limited
+
full
+
+ +

Default is same as input. +

+
+
primariesin, pin
+

Set the input color primaries. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
170m
+
240m
+
2020
+
+ +

Default is same as input. +

+
+
transferin, tin
+

Set the input transfer characteristics. +

+

Possible values are: +

+
input
+
709
+
unspecified
+
601
+
linear
+
2020_10
+
2020_12
+
+ +

Default is same as input. +

+
+
matrixin, min
+

Set the input colorspace matrix. +

+

Possible value are: +

+
input
+
709
+
unspecified
+
470bg
+
170m
+
2020_ncl
+
2020_cl
+
+ +
+
chromal, c
+

Set the output chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
chromalin, cin
+

Set the input chroma location. +

+

Possible values are: +

+
input
+
left
+
center
+
topleft
+
top
+
bottomleft
+
bottom
+
+ +
+
npl
+

Set the nominal peak luminance. +

+
+
param_a
+

Parameter A for scaling filters. Parameter "b" for bicubic, and the number of +filter taps for lanczos. +

+
+
param_b
+

Parameter B for scaling filters. Parameter "c" for bicubic. +

+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
hsub
+
vsub
+

horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+
ohsub
+
ovsub
+

horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" hsub is 2 and vsub is 1. +

+
+ + +

32.293.2 Commands

+ +

This filter supports the following commands: +

+
width, w
+
height, h
+

Set the output video dimension 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. +

+
+ + + +

33 CUDA Video Filters

+ +

To enable CUDA and/or NPP filters please refer to configuration guidelines for CUDA and for CUDA NPP filters. +

+

Running CUDA filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device cuda[=name][:device[,key=value...]]
+

Initialise a new hardware device of type cuda called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of initializing second CUDA device on the system and running scale_cuda and bilateral_cuda filters. +
    +
    ./ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -init_hw_device cuda:1 -filter_complex \
    +"[0:v]scale_cuda=format=yuv444p[scaled_video];[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    +
+ +

Since CUDA filters operate exclusively on GPU memory, frame data must sometimes be uploaded (hwupload) to hardware surfaces associated with the appropriate CUDA device before processing, and downloaded (hwdownload) back to normal memory afterward, if required. Whether hwupload or hwdownload is necessary depends on the specific workflow: +

+
    +
  • If the input frames are already in GPU memory (e.g., when using -hwaccel cuda or -hwaccel_output_format cuda), explicit use of hwupload is not needed, as the data is already in the appropriate memory space. +
  • If the input frames are in CPU memory (e.g., software-decoded frames or frames processed by CPU-based filters), it is necessary to use hwupload to transfer the data to GPU memory for CUDA processing. +
  • If the output of the CUDA filters needs to be further processed by software-based filters or saved in a format not supported by GPU-based encoders, hwdownload is required to transfer the data back to CPU memory. +
+

Note that hwupload uploads data to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before hwupload to ensure the input is in the correct format. Similarly, hwdownload may not support all output formats, so an additional format filter may need to be inserted immediately after hwdownload in the filter graph to ensure compatibility. +

+ +

33.1 CUDA

+

Below is a description of the currently available Nvidia CUDA video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
+ +

Note: If FFmpeg detects the Nvidia CUDA Toolkit during configuration, it will enable CUDA filters automatically without requiring any additional flags. If you want to explicitly enable them, use the following options: +

+
    +
  • Configure FFmpeg with --enable-cuda-nvcc --enable-nonfree. +
  • Configure FFmpeg with --enable-cuda-llvm. Additional requirement: llvm lib must be installed. +
+ + +

33.1.1 bilateral_cuda

+

CUDA accelerated bilateral filter, an edge preserving filter. +This filter is mathematically accurate thanks to the use of GPU acceleration. +For best output quality, use one to one chroma subsampling, i.e. yuv444p format. +

+

The filter accepts the following options: +

+
sigmaS
+

Set sigma of gaussian function to calculate spatial weight, also called sigma space. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
sigmaR
+

Set sigma of gaussian function to calculate color range weight, also called sigma color. +Allowed range is 0.1 to 512. Default is 0.1. +

+
+
window_size
+

Set window size of the bilateral function to determine the number of neighbours to loop on. +If the number entered is even, one will be added automatically. +Allowed range is 1 to 255. Default is 1. +

+
+ +

33.1.1.1 Examples

+ +
    +
  • Apply the bilateral filter on a video. + +
    +
    ./ffmpeg -v verbose \
    +-hwaccel cuda -hwaccel_output_format cuda -i input.mp4  \
    +-init_hw_device cuda \
    +-filter_complex \
    +" \
    +[0:v]scale_cuda=format=yuv444p[scaled_video];
    +[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
    +-an -sn -c:v h264_nvenc -cq 20 out.mp4
    +
    + +
+ + +

33.1.2 bwdif_cuda

+ +

Deinterlace the input video using the bwdif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

33.1.3 chromakey_cuda

+

CUDA accelerated YUV colorspace color/chroma keying. +

+

This filter works like normal chromakey filter but operates on CUDA frames. +for more details and parameters see chromakey. +

+ +

33.1.3.1 Examples

+ +
    +
  • Make all the green pixels in the input video transparent and use it as an overlay for another video: + +
    +
    ./ffmpeg \
    +    -hwaccel cuda -hwaccel_output_format cuda -i input_green.mp4  \
    +    -hwaccel cuda -hwaccel_output_format cuda -i base_video.mp4 \
    +    -init_hw_device cuda \
    +    -filter_complex \
    +    " \
    +        [0:v]chromakey_cuda=0x25302D:0.1:0.12:1[overlay_video]; \
    +        [1:v]scale_cuda=format=yuv420p[base]; \
    +        [base][overlay_video]overlay_cuda" \
    +    -an -sn -c:v h264_nvenc -cq 20 output.mp4
    +
    + +
  • Process two software sources, explicitly uploading the frames: + +
    +
    ./ffmpeg -init_hw_device cuda=cuda -filter_hw_device cuda \
    +    -f lavfi -i color=size=800x600:color=white,format=yuv420p \
    +    -f lavfi -i yuvtestsrc=size=200x200,format=yuv420p \
    +    -filter_complex \
    +    " \
    +        [0]hwupload[under]; \
    +        [1]hwupload,chromakey_cuda=green:0.1:0.12[over]; \
    +        [under][over]overlay_cuda" \
    +    -c:v hevc_nvenc -cq 18 -preset slow output.mp4
    +
    + +
+ + +

33.1.4 colorspace_cuda

+ +

CUDA accelerated implementation of the colorspace filter. +

+

It is by no means feature complete compared to the software colorspace filter, +and at the current time only supports color range conversion between jpeg/full +and mpeg/limited range. +

+

The filter accepts the following options: +

+
+
range
+

Specify output color range. +

+

The accepted values are: +

+
‘tv’
+

TV (restricted) range +

+
+
‘mpeg’
+

MPEG (restricted) range +

+
+
‘pc’
+

PC (full) range +

+
+
‘jpeg’
+

JPEG (full) range +

+
+
+ +
+
+ + +

33.1.5 overlay_cuda

+ +

Overlay one video on top of another. +

+

This is the CUDA variant of the overlay filter. +It only accepts CUDA frames. The underlying input pixel formats have to match. +

+

It takes two inputs and has one output. The first input is the "main" +video on which the second input is overlaid. +

+

It accepts the following parameters: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

They can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay input width and height. +

+
+
x
+
y
+

The computed values for x and y. They are evaluated for +each new frame. +

+
+
n
+

The ordinal index of the main input frame, starting from 0. +

+
+
pos
+

The byte offset position in the file of the main input frame, NAN if unknown. +Deprecated, do not use. +

+
+
t
+

The timestamp of the main input frame, expressed in seconds, NAN if unknown. +

+
+
+ +

Default value is "0" for both expressions. +

+
+
eval
+

Set when the expressions for x and y are evaluated. +

+

It accepts the following values: +

+
init
+

Evaluate expressions once during filter initialization or +when a command is processed. +

+
+
frame
+

Evaluate expressions for each incoming frame +

+
+ +

Default value is frame. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+ + +

33.1.6 pad_cuda

+

Add paddings to an input video stream using CUDA. +

+

This filter is the CUDA-accelerated version of the pad filter. It accepts the same options and expressions and provides the same core functionality. +For a detailed description of available options, please see the documentation for the pad filter. +

+ +

33.1.6.1 Examples

+ +
    +
  • Add a 200-pixel black border to all sides of a video frame: +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=iw+400:h=ih+400:x=200:y=200" -c:v h264_nvenc out.mp4
    +
    + +
  • Pad the input video to a 16:9 aspect ratio, filling with the color "blue": +
    +
    ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=ih*16/9/sar:h=ih:x=(ow-iw)/2:y=(oh-ih)/2:color=blue" -c:v h264_nvenc out.mp4
    +
    +
+ + +

33.1.7 scale_cuda

+ +

Scale (resize) and convert (pixel format) the input video, using accelerated CUDA kernels. +Setting the output width and height works in the same way as for the scale filter. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+

Allows for the same expressions as the scale filter. +

+
+
interp_algo
+

Sets the algorithm used for scaling: +

+
+
nearest
+

Nearest neighbour +

+

Used by default if input parameters match the desired output. +

+
+
bilinear
+

Bilinear +

+
+
bicubic
+

Bicubic +

+

This is the default. +

+
+
lanczos
+

Lanczos +

+
+
+ +
+
format
+

Controls the output pixel format. By default, or if none is specified, the input +pixel format is used. +

+

The filter does not support converting between YUV and RGB pixel formats. +

+
+
passthrough
+

If set to 0, every frame is processed, even if no conversion is necessary. +This mode can be useful to use the filter as a buffer for a downstream +frame-consumer that exhausts the limited decoder frame pool. +

+

If set to 1, frames are passed through as-is if they match the desired output +parameters. This is the default behaviour. +

+
+
param
+

Algorithm-Specific parameter. +

+

Affects the curves of the bicubic algorithm. +

+
+
force_original_aspect_ratio
+
force_divisible_by
+

Work the same as the identical scale filter options. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
+ + +

33.1.7.1 Examples

+ +
    +
  • Scale input to 720p, keeping aspect ratio and ensuring the output is yuv420p. +
    +
    scale_cuda=-2:720:format=yuv420p
    +
    + +
  • Upscale to 4K using nearest neighbour algorithm. +
    +
    scale_cuda=4096:2160:interp_algo=nearest
    +
    + +
  • Don’t do any conversion or scaling, but copy all input frames into newly allocated ones. +This can be useful to deal with a filter and encode chain that otherwise exhausts the +decoders frame pool. +
    +
    scale_cuda=passthrough=0
    +
    +
+ + +

33.1.8 thumbnail_cuda

+ +

Select the most representative frame in a given sequence of consecutive frames using CUDA. +

+

The filter accepts the following options: +

+
+
n
+

Set the frames batch size to analyze; in a set of n frames, the filter +will pick one of them, and then handle the next batch of n frames until +the end. Default is 100. +

+
+ +

Since the filter keeps track of the whole frames sequence, a bigger n +value will result in a higher memory usage, so a high value is not recommended. +

+ +

33.1.8.1 Example

+ +
    +
  • Thumbnails are extracted from every n=150-frame batch, selecting one per batch. Chosen frames are then scaled with scale_cuda. +
    +
    ./ffmpeg  -hwaccel cuda -hwaccel_output_format cuda  -i ./input.mp4 -vf "thumbnail_cuda=150,scale_cuda=1920:1080,hwdownload,format=nv12" ./output/out%03d.png
    +
    + +
+ + +

33.1.9 yadif_cuda

+ +

Deinterlace the input video using the yadif algorithm, but implemented +in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec +and/or nvenc. +

+

It accepts the following parameters: +

+ +
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
2, send_frame_nospatial
+

Like send_frame, but it skips the spatial interlacing check. +

+
3, send_field_nospatial
+

Like send_field, but it skips the spatial interlacing check. +

+
+ +

The default value is send_frame. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

33.2 CUDA NPP

+

Below is a description of the currently available NVIDIA Performance Primitives (libnpp) video filters. +

+

Prerequisites: +

    +
  • Install Nvidia CUDA Toolkit +
  • Install libnpp +
+ +

To enable CUDA NPP filters: +

+
    +
  • Configure FFmpeg with --enable-nonfree --enable-libnpp. +
+ + + +

33.2.1 scale_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel +format conversion on CUDA video frames. Setting the output width and height +works in the same way as for the scale filter. +

+

The following additional options are accepted: +

+
format
+

The pixel format of the output CUDA frames. If set to the string "same" (the +default), the input format will be kept. Note that automatic format negotiation +and conversion is not yet supported for hardware frames +

+
+
interp_algo
+

The interpolation algorithm used for resizing. One of the following: +

+
nn
+

Nearest neighbour. +

+
+
linear
+
cubic
+
cubic2p_bspline
+

2-parameter cubic (B=1, C=0) +

+
+
cubic2p_catmullrom
+

2-parameter cubic (B=0, C=1/2) +

+
+
cubic2p_b05c03
+

2-parameter cubic (B=1/2, C=3/10) +

+
+
super
+

Supersampling +

+
+
lanczos
+
+ +
+
force_original_aspect_ratio
+

Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: +

+
+
‘disable’
+

Scale the video as specified and disable this feature. +

+
+
‘decrease’
+

The output video dimensions will automatically be decreased if needed. +

+
+
‘increase’
+

The output video dimensions will automatically be increased if needed. +

+
+
+ +

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 w +or h, you still need to specify the output resolution for this option +to work. +

+
+
force_divisible_by
+

Ensures that both the output dimensions, width and height, are divisible by the +given integer when used together with force_original_aspect_ratio. This +works similar to using -n in the w and h options. +

+

This option respects the value set for force_original_aspect_ratio, +increasing or decreasing the resolution accordingly. The video’s aspect ratio +may be slightly modified. +

+

This option can be handy if you need to have a video fit within or exceed +a defined resolution using force_original_aspect_ratio but also have +encoder restrictions on width or height divisibility. +

+
+
reset_sar
+

Works the same as the identical scale filter option. +

+
+
eval
+

Specify when to evaluate width and height expression. It accepts the following values: +

+
+
‘init’
+

Only evaluate expressions once during the filter initialization or when a command is processed. +

+
+
‘frame’
+

Evaluate expressions for each incoming frame. +

+
+
+ +
+
+ +

The values of the w and h options are expressions +containing the following constants: +

+
+
in_w
+
in_h
+

The input width and height +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output (scaled) width and height +

+
+
ow
+
oh
+

These are the same as out_w and out_h +

+
+
a
+

The same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

The input display aspect ratio. Calculated from (iw / ih) * sar. +

+
+
n
+

The (sequential) number of the input frame, starting from 0. +Only available with eval=frame. +

+
+
t
+

The presentation timestamp of the input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
pos
+

The position (byte offset) of the frame in the input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +Deprecated, do not use. +

+
+ + +

33.2.2 scale2ref_npp

+ +

Use the NVIDIA Performance Primitives (libnpp) to scale (resize) the input +video, based on a reference video. +

+

See the scale_npp filter for available options, scale2ref_npp supports the same +but uses the reference video instead of the main input as basis. scale2ref_npp +also supports the following additional constants for the w and +h options: +

+
+
main_w
+
main_h
+

The main input video’s width and height +

+
+
main_a
+

The same as main_w / main_h +

+
+
main_sar
+

The main input video’s sample aspect ratio +

+
+
main_dar, mdar
+

The main input video’s display aspect ratio. Calculated from +(main_w / main_h) * main_sar. +

+
+
main_n
+

The (sequential) number of the main input frame, starting from 0. +Only available with eval=frame. +

+
+
main_t
+

The presentation timestamp of the main input frame, expressed as a number of +seconds. Only available with eval=frame. +

+
+
main_pos
+

The position (byte offset) of the frame in the main input stream, or NaN if +this information is unavailable and/or meaningless (for example in case of synthetic video). +Only available with eval=frame. +

+
+ + +

33.2.2.1 Examples

+ +
    +
  • Scale a subtitle stream (b) to match the main video (a) in size before overlaying +
    +
    'scale2ref_npp[b][a];[a][b]overlay_cuda'
    +
    + +
  • Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio. +
    +
    [logo-in][video-in]scale2ref_npp=w=oh*mdar:h=ih/10[logo-out][video-out]
    +
    +
+ + +

33.2.3 sharpen_npp

+

Use the NVIDIA Performance Primitives (libnpp) to perform image sharpening with +border control. +

+

The following additional options are accepted: +

+
border_type
+

Type of sampling to be used ad frame borders. One of the following: +

+
replicate
+

Replicate pixel values. +

+
+
+
+
+ + +

33.2.4 transpose_npp

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

34 OpenCL Video Filters

+ +

Below is a description of the currently available OpenCL video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-opencl. +

+

Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device opencl[=name][:device[,key=value...]]
+

Initialise a new hardware device of type opencl called name, using the +given device parameters. +

+
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it. +
    +
    -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
    +
    +
+ +

Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded(hwdownload) back to normal memory. Note that hwupload will upload to a surface with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it may be necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

34.1 avgblur_opencl

+ +

Apply average blur filter. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 1024] and default value is 1. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 1024] and default value is 0. If zero, sizeX value will be used. +

+
+ + +

34.1.1 Example

+ +
    +
  • Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +
    +
    -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
    +
    +
+ + +

34.2 boxblur_opencl

+ +

Apply a boxblur algorithm to the input video. +

+

It accepts the following parameters: +

+
+
luma_radius, lr
+
luma_power, lp
+
chroma_radius, cr
+
chroma_power, cp
+
alpha_radius, ar
+
alpha_power, ap
+
+ +

A description of the accepted options follows. +

+
+
luma_radius, lr
+
chroma_radius, cr
+
alpha_radius, ar
+

Set an expression for the box radius in pixels used for blurring the +corresponding input plane. +

+

The radius value must be a non-negative number, and must not be +greater than the value of the expression min(w,h)/2 for the +luma and alpha planes, and of min(cw,ch)/2 for the chroma +planes. +

+

Default value for luma_radius is "2". If not specified, +chroma_radius and alpha_radius default to the +corresponding value set for luma_radius. +

+

The expressions can contain the following constants: +

+
w
+
h
+

The input width and height in pixels. +

+
+
cw
+
ch
+

The input chroma image width and height in pixels. +

+
+
hsub
+
vsub
+

The horizontal and vertical chroma subsample values. For example, for the +pixel format "yuv422p", hsub is 2 and vsub is 1. +

+
+ +
+
luma_power, lp
+
chroma_power, cp
+
alpha_power, ap
+

Specify how many times the boxblur filter is applied to the +corresponding plane. +

+

Default value for luma_power is 2. If not specified, +chroma_power and alpha_power default to the +corresponding value set for luma_power. +

+

A value of 0 will disable the effect. +

+
+ + +

34.2.1 Examples

+ +

Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses luma_radius, chroma_radius, alpha_radius for each plane respectively. The filter will apply luma_power, chroma_power, alpha_power times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. +

+
    +
  • Apply a boxblur filter with the luma, chroma, and alpha radius +set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image. +
    +
    -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
    +-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
    +
    + +
  • Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7. + +

    For the luma plane, a 2x2 box radius will be run once. +

    +

    For the chroma plane, a 4x4 box radius will be run 5 times. +

    +

    For the alpha plane, a 3x3 box radius will be run 7 times. +

    +
    -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
    +
    +
+ + +

34.3 colorkey_opencl

+

RGB colorspace color keying. +

+

The filter accepts the following options: +

+
+
color
+

The color which will be replaced with transparency. +

+
+
similarity
+

Similarity percentage with the key color. +

+

0.01 matches only the exact key color, while 1.0 matches everything. +

+
+
blend
+

Blend percentage. +

+

0.0 makes pixels either fully transparent, or not transparent at all. +

+

Higher values result in semi-transparent pixels, with a higher transparency +the more similar the pixels color is to the key color. +

+
+ + +

34.3.1 Examples

+ +
    +
  • Make every semi-green pixel in the input transparent with some slight blending: +
    +
    -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
    +
    +
+ + +

34.4 convolution_opencl

+ +

Apply convolution of 3x3, 5x5, 7x7 matrix. +

+

The filter accepts the following options: +

+
+
0m
+
1m
+
2m
+
3m
+

Set matrix for each plane. +Matrix is sequence of 9, 25 or 49 signed numbers. +Default value for each plane is 0 0 0 0 1 0 0 0 0. +

+
+
0rdiv
+
1rdiv
+
2rdiv
+
3rdiv
+

Set multiplier for calculated value for each plane. +If unset or 0, it will be sum of all matrix elements. +The option value must be a float number greater or equal to 0.0. Default value is 1.0. +

+
+
0bias
+
1bias
+
2bias
+
3bias
+

Set bias for each plane. This value is added to the result of the multiplication. +Useful for making the overall image brighter or darker. +The option value must be a float number greater or equal to 0.0. Default value is 0.0. +

+
+
+ + +

34.4.1 Examples

+ +
    +
  • Apply sharpen: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0, hwdownload" OUTPUT
    +
    + +
  • Apply blur: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9, hwdownload" OUTPUT
    +
    + +
  • Apply edge enhance: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply edge detect: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128, hwdownload" OUTPUT
    +
    + +
  • Apply laplacian edge detector which includes diagonals: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT
    +
    + +
  • Apply emboss: +
    +
    -i INPUT -vf "hwupload, convolution_opencl=-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2, hwdownload" OUTPUT
    +
    +
+ + +

34.5 erosion_opencl

+ +

Apply erosion effect to the video. +

+

This filter replaces the pixel by the local(3x3) minimum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

34.5.1 Example

+ +
    +
  • Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

34.6 deshake_opencl

+

Feature-point based video stabilization filter. +

+

The filter accepts the following options: +

+
+
tripod
+

Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to 0. +

+
+
debug
+

Whether or not additional debug info should be displayed, both in the processed output and in the console. +

+

Note that in order to see console debug output you will also need to pass -v verbose to ffmpeg. +

+

Viewing point matches in the output video is only supported for RGB input. +

+

Defaults to 0. +

+
+
adaptive_crop
+

Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels. +

+

Defaults to 1. +

+
+
refine_features
+

Whether or not feature points should be refined at a sub-pixel level. +

+

This can be turned off for a slight performance gain at the cost of precision. +

+

Defaults to 1. +

+
+
smooth_strength
+

The strength of the smoothing applied to the camera path from 0.0 to 1.0. +

+

1.0 is the maximum smoothing strength while values less than that result in less smoothing. +

+

0.0 causes the filter to adaptively choose a smoothing strength on a per-frame basis. +

+

Defaults to 0.0. +

+
+
smooth_window_multiplier
+

Controls the size of the smoothing window (the number of frames buffered to determine motion information from). +

+

The size of the smoothing window is determined by multiplying the framerate of the video by this number. +

+

Acceptable values range from 0.1 to 10.0. +

+

Larger values increase the amount of motion data available for determining how to smooth the camera path, +potentially improving smoothness, but also increase latency and memory usage. +

+

Defaults to 2.0. +

+
+
+ + +

34.6.1 Examples

+ +
    +
  • Stabilize a video with a fixed, medium smoothing strength: +
    +
    -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
    +
    + +
  • Stabilize a video with debugging (both in console and in rendered video): +
    +
    -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
    +
    +
+ + +

34.7 dilation_opencl

+ +

Apply dilation effect to the video. +

+

This filter replaces the pixel by the local(3x3) maximum. +

+

It accepts the following options: +

+
+
threshold0
+
threshold1
+
threshold2
+
threshold3
+

Limit the maximum change for each plane. Range is [0, 65535] and default value is 65535. +If 0, plane will remain unchanged. +

+
+
coordinates
+

Flag which specifies the pixel to refer to. +Range is [0, 255] and default value is 255, i.e. all eight pixels are used. +

+

Flags to local 3x3 coordinates region centered on x: +

+

1 2 3 +

+

4 x 5 +

+

6 7 8 +

+
+ + +

34.7.1 Example

+ +
    +
  • Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane. +
    +
    -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
    +
    +
+ + +

34.8 nlmeans_opencl

+ +

Non-local Means denoise filter through OpenCL, this filter accepts same options as nlmeans. +

+ +

34.9 overlay_opencl

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires same memory layout for all the inputs. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

34.9.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    +
  • The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
    +
    + +
+ + +

34.10 pad_opencl

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

34.11 prewitt_opencl

+ +

Apply the Prewitt operator (https://en.wikipedia.org/wiki/Prewitt_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

34.11.1 Example

+ +
    +
  • Apply the Prewitt operator with scale set to 2 and delta set to 10. +
    +
    -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

34.12 program_opencl

+ +

Filter video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
inputs
+

Number of inputs to the filter. Defaults to 1. +

+
+
size, s
+

Size of output frames. Defaults to the same as the first input. +

+
+
+ +

The program_opencl filter also supports the framesync options. +

+

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

  • Frame index, unsigned int. + +

    This is a counter starting from zero and increasing by one for each frame. +

  • Source images, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

+ +

Example programs: +

+
    +
  • Copy the input to the output (output must be the same size as the input). +
    __kernel void copy(__write_only image2d_t destination,
    +                   unsigned int index,
    +                   __read_only  image2d_t source)
    +{
    +    const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
    +
    +    int2 location = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = read_imagef(source, sampler, location);
    +
    +    write_imagef(destination, location, value);
    +}
    +
    +
  • Apply a simple transformation, rotating the input by an amount increasing +with the index counter. Pixel values are linearly interpolated by the +sampler, and the output need not have the same dimensions as the input. +
    __kernel void rotate_image(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float angle = (float)index / 100.0f;
    +
    +    float2 dst_dim = convert_float2(get_image_dim(dst));
    +    float2 src_dim = convert_float2(get_image_dim(src));
    +
    +    float2 dst_cen = dst_dim / 2.0f;
    +    float2 src_cen = src_dim / 2.0f;
    +
    +    int2   dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float2 dst_pos = convert_float2(dst_loc) - dst_cen;
    +    float2 src_pos = {
    +        cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
    +        sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
    +    };
    +    src_pos = src_pos * src_dim / dst_dim;
    +
    +    float2 src_loc = src_pos + src_cen;
    +
    +    if (src_loc.x < 0.0f      || src_loc.y < 0.0f ||
    +        src_loc.x > src_dim.x || src_loc.y > src_dim.y)
    +        write_imagef(dst, dst_loc, 0.5f);
    +    else
    +        write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
    +}
    +
    +
  • Blend two inputs together, with the amount of each input used varying +with the index counter. +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           unsigned int index,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +
    +    float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
    +
    +    int2  dst_loc = (int2)(get_global_id(0), get_global_id(1));
    +    int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
    +    int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
    +
    +    float4 val1 = read_imagef(src1, sampler, src1_loc);
    +    float4 val2 = read_imagef(src2, sampler, src2_loc);
    +
    +    write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
    +}
    +
    +
+ + +

34.13 remap_opencl

+ +

Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. +

+

Destination pixel at position (X, Y) will be picked from source (x, y) position +where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero +value for pixel will be used for destination pixel. +

+

Xmap and Ymap input video streams must be of same dimensions. Output video stream +will have Xmap/Ymap video stream dimensions. +Xmap and Ymap input video streams are 32bit float pixel format, single channel. +

+
+
interp
+

Specify interpolation used for remapping of pixels. +Allowed values are near and linear. +Default value is linear. +

+
+
fill
+

Specify the color of the unmapped pixels. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. Default color is black. +

+
+ + +

34.14 roberts_opencl

+

Apply the Roberts cross operator (https://en.wikipedia.org/wiki/Roberts_cross) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

34.14.1 Example

+ +
    +
  • Apply the Roberts cross operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

34.15 sobel_opencl

+ +

Apply the Sobel operator (https://en.wikipedia.org/wiki/Sobel_operator) to input video stream. +

+

The filter accepts the following option: +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+
scale
+

Set value which will be multiplied with filtered result. +Range is [0.0, 65535] and default value is 1.0. +

+
+
delta
+

Set value which will be added to filtered result. +Range is [-65535, 65535] and default value is 0.0. +

+
+ + +

34.15.1 Example

+ +
    +
  • Apply sobel operator with scale set to 2 and delta set to 10 +
    +
    -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
    +
    +
+ + +

34.16 tonemap_opencl

+ +

Perform HDR(PQ/HLG) to SDR conversion with tone-mapping. +

+

It accepts the following parameters: +

+
+
tonemap
+

Specify the tone-mapping operator to be used. Same as tonemap option in tonemap. +

+
+
param
+

Tune the tone mapping algorithm. same as param option in tonemap. +

+
+
desat
+

Apply desaturation for highlights that exceed this level of brightness. The +higher the parameter, the more color information will be preserved. This +setting helps prevent unnaturally blown-out colors for super-highlights, by +(smoothly) turning into white instead. This makes images feel more natural, +at the cost of reducing information about out-of-range colors. +

+

The default value is 0.5, and the algorithm here is a little different from +the cpu version tonemap currently. A setting of 0.0 disables this option. +

+
+
threshold
+

The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold +is used to detect whether the scene has changed or not. If the distance between +the current frame average brightness and the current running average exceeds +a threshold value, we would re-calculate scene average and peak brightness. +The default value is 0.2. +

+
+
format
+

Specify the output pixel format. +

+

Currently supported formats are: +

+
p010
+
nv12
+
+ +
+
range, r
+

Set the output color range. +

+

Possible values are: +

+
tv/mpeg
+
pc/jpeg
+
+ +

Default is same as input. +

+
+
primaries, p
+

Set the output color primaries. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Possible values are: +

+
bt709
+
bt2020
+
+ +

Default is bt709. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Possible value are: +

+
bt709
+
bt2020
+
+ +

Default is same as input. +

+
+
+ + +

34.16.1 Example

+ +
    +
  • Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator. +
    +
    -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
    +
    +
+ + +

34.17 unsharp_opencl

+ +

Sharpen or blur the input video. +

+

It accepts the following parameters: +

+
+
luma_msize_x, lx
+

Set the luma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
luma_msize_y, ly
+

Set the luma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
luma_amount, la
+

Set the luma effect strength. +Range is [-10, 10] and default value is 1.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
chroma_msize_x, cx
+

Set the chroma matrix horizontal size. +Range is [1, 23] and default value is 5. +

+
+
chroma_msize_y, cy
+

Set the chroma matrix vertical size. +Range is [1, 23] and default value is 5. +

+
+
chroma_amount, ca
+

Set the chroma effect strength. +Range is [-10, 10] and default value is 0.0. +

+

Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. +

+
+
+ +

All parameters are optional and default to the equivalent of the +string ’5:5:1.0:5:5:0.0’. +

+ +

34.17.1 Examples

+ +
    +
  • Apply strong luma sharpen effect: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
    +
    + +
  • Apply a strong blur of both luma and chroma parameters: +
    +
    -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
    +
    +
+ + +

34.18 xfade_opencl

+ +

Cross fade two videos with custom transition effect by using OpenCL. +

+

It accepts the following options: +

+
+
transition
+

Set one of possible transition effects. +

+
+
custom
+

Select custom transition effect, the actual transition description +will be picked from source and kernel options. +

+
+
fade
+
wipeleft
+
wiperight
+
wipeup
+
wipedown
+
slideleft
+
slideright
+
slideup
+
slidedown
+
+

Default transition is fade. +

+
+ +
+
source
+

OpenCL program source file for custom transition. +

+
+
kernel
+

Set name of kernel to use for custom transition from program source file. +

+
+
duration
+

Set duration of video transition. +

+
+
offset
+

Set time of start of transition relative to first video. +

+
+ +

The program source file must contain a kernel function with the given name, +which will be run once for each plane of the output. Each run on a plane +gets enqueued as a separate 2D global NDRange with one work-item for each +pixel to be generated. The global ID offset for each work-item is therefore +the coordinates of a pixel in the destination image. +

+

The kernel function needs to take the following arguments: +

    +
  • Destination image, __write_only image2d_t. + +

    This image will become the output; the kernel should write all of it. +

    +
  • First Source image, __read_only image2d_t. +Second Source image, __read_only image2d_t. + +

    These are the most recent images on each input. The kernel may read from +them to generate the output, but they can’t be written to. +

    +
  • Transition progress, float. This value is always between 0 and 1 inclusive. +
+ +

Example programs: +

+
    +
  • Apply dots curtain transition effect: +
    __kernel void blend_images(__write_only image2d_t dst,
    +                           __read_only  image2d_t src1,
    +                           __read_only  image2d_t src2,
    +                           float progress)
    +{
    +    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
    +                               CLK_FILTER_LINEAR);
    +    int2  p = (int2)(get_global_id(0), get_global_id(1));
    +    float2 rp = (float2)(get_global_id(0), get_global_id(1));
    +    float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
    +    rp = rp / dim;
    +
    +    float2 dots = (float2)(20.0, 20.0);
    +    float2 center = (float2)(0,0);
    +    float2 unused;
    +
    +    float4 val1 = read_imagef(src1, sampler, p);
    +    float4 val2 = read_imagef(src2, sampler, p);
    +    bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
    +
    +    write_imagef(dst, p, next ? val1 : val2);
    +}
    +
    +
+ + + +

35 VAAPI Video Filters

+ +

VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vaapi. +

+

To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/VAAPI +

+ +

35.1 overlay_vaapi

+ +

Overlay one video on the top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +

+

The filter accepts the following options: +

+
+
x
+
y
+

Set expressions for the x and y coordinates of the overlaid video +on the main video. +

+

Default value is "0" for both expressions. +

+
+
w
+
h
+

Set expressions for the width and height the overlaid video +on the main video. +

+

Default values are ’overlay_iw’ for ’w’ and ’overlay_ih*w/overlay_iw’ for ’h’. +

+

The expressions can contain the following parameters: +

+
+
main_w, W
+
main_h, H
+

The main input width and height. +

+
+
overlay_iw
+
overlay_ih
+

The overlay input width and height. +

+
+
overlay_w, w
+
overlay_h, h
+

The overlay output width and height. +

+
+
overlay_x, x
+
overlay_y, y
+

Position of the overlay layer inside of main +

+
+
+ +
+
alpha
+

Set transparency of overlaid video. Allowed range is 0.0 to 1.0. +Higher value means lower transparency. +Default value is 1.0. +

+
+
eof_action
+

See framesync. +

+
+
shortest
+

See framesync. +

+
+
repeatlast
+

See framesync. +

+
+
+ +

This filter also supports the framesync options. +

+

35.1.1 Examples

+ +
    +
  • Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs for this filter are yuv420p format. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_vaapi" OUTPUT
    +
    +
  • Overlay an image LOGO at the offset (200, 100) from the top-left corner of the INPUT video. +The inputs have same memory layout for color channels, the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. +
    +
    -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_vaapi=x=200:y=100:w=400:h=300:alpha=1.0, hwdownload, format=nv12" OUTPUT
    +
    + +
+ + +

35.2 tonemap_vaapi

+ +

Perform HDR-to-SDR or HDR-to-HDR tone-mapping. +It currently only accepts HDR10 as input. +

+

It accepts the following parameters: +

+
+
format
+

Specify the output pixel format. +

+

Default is nv12 for HDR-to-SDR tone-mapping and p010 for HDR-to-HDR +tone-mapping. +

+
+
primaries, p
+

Set the output color primaries. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
transfer, t
+

Set the output transfer characteristics. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
matrix, m
+

Set the output colorspace matrix. +

+

Default is bt709 for HDR-to-SDR tone-mapping and same as input for HDR-to-HDR +tone-mapping. +

+
+
display
+

Set the output mastering display colour volume. It is given by a ’|’-separated +list of two values, two values are space separated. It set display primaries +x & y in G, B, R order, then white point x & y, the nominal minimum & maximum +display luminances. +

+

HDR-to-HDR tone-mapping will be performed when this option is set. +

+
+
light
+

Set the output content light level information. It accepts 2 space-separated +values, the first input is the maximum light level and the second input is +the maximum average light level. +

+

It is ignored for HDR-to-SDR tone-mapping, and optional for HDR-to-HDR +tone-mapping. +

+
+
+ + +

35.2.1 Example

+ +
    +
  • Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format +
    +
    tonemap_vaapi=format=p010:t=bt2020-10
    +
    +
  • Convert HDR video to HDR video +
    +
    tonemap_vaapi=display=7500\ 3000|34000\ 16000|13250\ 34500|15635\ 16450|500\ 10000000
    +
    +
+ + +

35.3 hstack_vaapi

+

Stack input videos horizontally. +

+

This is the VA-API variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

35.4 vstack_vaapi

+

Stack input videos vertically. +

+

This is the VA-API variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

35.5 xstack_vaapi

+

Stack video inputs into custom layout. +

+

This is the VA-API variant of the xstack filter, each input stream may +have different size, this filter will scale down/up each input stream to the +given output size, or the size of the first input stream. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_vaapi=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + +

35.6 pad_vaapi

+ +

Add paddings to the input image, and place the original input at the +provided x, y coordinates. +

+

It accepts the following options: +

+
+
width, w
+
height, h
+

Specify an expression for the size of the output image with the +paddings added. If the value for width or height is 0, the +corresponding input size is used for the output. +

+

The width expression can reference the value set by the +height expression, and vice versa. +

+

The default value of width and height is 0. +

+
+
x
+
y
+

Specify the offsets to place the input image at within the padded area, +with respect to the top/left border of the output image. +

+

The x expression can reference the value set by the y +expression, and vice versa. +

+

The default value of x and y is 0. +

+

If x or y evaluate to a negative number, they’ll be changed +so the input image is centered on the padded area. +

+
+
color
+

Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils +manual. +

+
+
aspect
+

Pad to an aspect instead to a resolution. +

+
+ +

The value for the width, height, x, and y +options are expressions containing the following constants: +

+
+
in_w
+
in_h
+

The input video width and height. +

+
+
iw
+
ih
+

These are the same as in_w and in_h. +

+
+
out_w
+
out_h
+

The output width and height (the size of the padded area), as +specified by the width and height expressions. +

+
+
ow
+
oh
+

These are the same as out_w and out_h. +

+
+
x
+
y
+

The x and y offsets as specified by the x and y +expressions, or NAN if not yet specified. +

+
+
a
+

same as iw / ih +

+
+
sar
+

input sample aspect ratio +

+
+
dar
+

input display aspect ratio, it is the same as (iw / ih) * sar +

+
+ + +

35.7 drawbox_vaapi

+ +

Draw a colored box on the input image. +

+

It accepts the following parameters: +

+
+
x
+
y
+

The expressions which specify the top left corner coordinates of the box. It defaults to 0. +

+
+
width, w
+
height, h
+

The expressions which specify the width and height of the box; if 0 they are interpreted as +the input width and height. It defaults to 0. +

+
+
color, c
+

Specify the color of the box to write. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. +

+
+
thickness, t
+

The expression which sets the thickness of the box edge. +A value of fill will create a filled box. Default value is 3. +

+

See below for the list of accepted constants. +

+
+
replace
+

With value 1, the pixels of the painted box will overwrite the video’s color and alpha pixels. +Default is 0, which composites the box onto the input video. +

+
+ +

The parameters for x, y, w and h and t are expressions containing the +following constants: +

+
+
in_h, ih
+
in_w, iw
+

The input width and height. +

+
+
x
+
y
+

The x and y offset coordinates where the box is drawn. +

+
+
w
+
h
+

The width and height of the drawn box. +

+
+
t
+

The thickness of the drawn box. +

+
+
+ + +

35.7.1 Examples

+ +
    +
  • Draw a black box around the edge of the input image: +
    +
    drawbox
    +
    + +
  • Draw a box with color red and an opacity of 50%: +
    +
    drawbox=10:20:200:60:red@0.5
    +
    + +

    The previous example can be specified as: +

    +
    drawbox=x=10:y=20:w=200:h=60:color=red@0.5
    +
    + +
  • Fill the box with pink color: +
    +
    drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill
    +
    + +
  • Draw a 2-pixel red 2.40:1 mask: +
    +
    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
    +
    +
+ + + +

36 VideoToolbox Video Filters

+ +

Below is a description of the currently available VideoToolbox video filters. +

+

VideoToolbox filter depends on VideoToolbox framework, and is auto detected +when building ffmpeg for an Apple platform such as macOS. Add +--enable-videotoolbox to configure if autodetect is disabled. +

+ +

36.1 scale_vt

+ +

Scale and convert the color parameters using VTPixelTransferSession. +

+

The filter accepts the following options: +

+
w
+
h
+

Set the output video dimension expression. Default value is the input dimension. +

+
+
color_matrix
+

Set the output colorspace matrix. +

+
+
color_primaries
+

Set the output color primaries. +

+
+
color_transfer
+

Set the output transfer characteristics. +

+
+
+ + +

36.1.1 Examples

+ +
    +
  • Perform HDR to SDR conversion, and scale to half size of input +
    +
    ffmpeg -hwaccel videotoolbox \
    +        -hwaccel_output_format videotoolbox_vld \
    +        -i hdr.mov \
    +        -c:v hevc_videotoolbox \
    +        -profile:v main \
    +        -b:v 3M \
    +        -vf scale_vt=w=iw/2:h=ih/2:color_matrix=bt709:color_primaries=bt709:color_transfer=bt709 \
    +        -c:a copy \
    +        -tag:v hvc1 \
    +        sdr.mp4
    +
    + +
+ + +

36.2 transpose_vt

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+
‘hflip’
+

Flip the input video horizontally. +

+
+
‘vflip’
+

Flip the input video vertically. +

+
+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

37 Vulkan Video Filters

+ +

Below is a description of the currently available Vulkan video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-vulkan and either --enable-libglslang or --enable-libshaderc. +

+

Running Vulkan filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. +

+
-init_hw_device vulkan[=name][:device[,key=value...]]
+

Initialise a new hardware device of type vulkan called name, using the +given device parameters and options in key=value. The following options +are supported: +

+
+
debug
+

Switches validation layers on if set to 1. +

+
+
linear_images
+

Allocates linear images. Does not apply to decoding. +

+
+
disable_multiplane
+

Disables multiplane images. Does not apply to decoding. +

+
+
avoid_host_import
+

Avoids the use of dynamic host memory imports, in favor of a regular memcpy() +into a previously mapped buffer. +

+
+ +
+
-filter_hw_device name
+

Pass the hardware device called name to all filters in any filter graph. +

+
+
+ +

For more detailed information see https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options +

+
    +
  • Example of choosing the first device and running nlmeans_vulkan filter with default parameters on it. +
    +
    -init_hw_device vulkan=vk:0 -filter_hw_device vk -i INPUT -vf "hwupload,nlmeans_vulkan,hwdownload" OUTPUT
    +
    +
+ +

As Vulkan filters are not able to access frame data in normal memory, all frame data needs to be uploaded (hwupload) to hardware surfaces connected to the appropriate device before being used and then downloaded (hwdownload) back to normal memory. Note that hwupload will upload to a frame with the same layout as the software frame, so it may be necessary to add a format filter immediately before to get the input into the right format and hwdownload does not support all formats on the output - it is usually necessary to insert an additional format filter immediately following in the graph to get the output in a supported format. +

+ +

37.1 avgblur_vulkan

+ +

Apply an average blur filter, implemented on the GPU using Vulkan. +

+

The filter accepts the following options: +

+
+
sizeX
+

Set horizontal radius size. +Range is [1, 32] and default value is 3. +

+
+
sizeY
+

Set vertical radius size. Range is [1, 32] and default value is 3. +

+
+
planes
+

Set which planes to filter. Default value is 0xf, by which all planes are processed. +

+
+ + +

37.2 blend_vulkan

+ +

Blend two Vulkan frames into each other. +

+

The blend filter takes two input streams and outputs one +stream, the first input is the "top" layer and second input is +"bottom" layer. By default, the output terminates when the longest input terminates. +

+

A description of the accepted options follows. +

+
+
c0_mode
+
c1_mode
+
c2_mode
+
c3_mode
+
all_mode
+

Set blend mode for specific pixel component or all pixel components in case +of all_mode. Default value is normal. +

+

Available values for component modes are: +

+
‘normal’
+
‘multiply’
+
+ +
+
+ + +

37.3 bwdif_vulkan

+ +

Deinterlacer using bwdif, the "Bob Weaver Deinterlacing Filter" algorithm, implemented +on the GPU using Vulkan. +

+

It accepts the following parameters: +

+
+
mode
+

The interlacing mode to adopt. It accepts one of the following values: +

+
+
0, send_frame
+

Output one frame for each frame. +

+
1, send_field
+

Output one frame for each field. +

+
+ +

The default value is send_field. +

+
+
parity
+

The picture field parity assumed for the input interlaced video. It accepts one +of the following values: +

+
+
0, tff
+

Assume the top field is first. +

+
1, bff
+

Assume the bottom field is first. +

+
-1, auto
+

Enable automatic detection of field parity. +

+
+ +

The default value is auto. +If the interlacing is unknown or the decoder does not export this information, +top field first will be assumed. +

+
+
deint
+

Specify which frames to deinterlace. Accepts one of the following +values: +

+
+
0, all
+

Deinterlace all frames. +

+
1, interlaced
+

Only deinterlace frames marked as interlaced. +

+
+ +

The default value is all. +

+
+ + +

37.4 chromaber_vulkan

+ +

Apply an effect that emulates chromatic aberration. Works best with RGB inputs, +but provides a similar effect with YCbCr inputs too. +

+
+
dist_x
+

Horizontal displacement multiplier. Each chroma pixel’s position will be multiplied +by this amount, starting from the center of the image. Default is 0. +

+
+
dist_y
+

Similarly, this sets the vertical displacement multiplier. Default is 0. +

+
+
+ + +

37.5 color_vulkan

+ +

Video source that creates a Vulkan frame of a solid color. +Useful for benchmarking, or overlaying. +

+

It accepts the following parameters: +

+
+
color
+

The color to use. Either a name, or a hexadecimal value. +The default value is black. +

+
+
size
+

The size of the output frame. Default value is 1920x1080. +

+
+
rate
+

The framerate to output at. Default value is 60 frames per second. +

+
+
duration
+

The video duration. Default value is -0.000001. +

+
+
sar
+

The video signal aspect ratio. Default value is 1/1. +

+
+
format
+

The pixel format of the output Vulkan frames. Default value is yuv444p. +

+
+
out_range
+

Set the 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: +

+
+
‘auto/unknown’
+

Choose automatically. +

+
+
‘jpeg/full/pc’
+

Set full range (0-255 in case of 8-bit luma). +

+
+
‘mpeg/limited/tv’
+

Set "MPEG" range (16-235 in case of 8-bit luma). +

+
+ +
+
+ + +

37.6 vflip_vulkan

+ +

Flips an image vertically. +

+ +

37.7 hflip_vulkan

+ +

Flips an image horizontally. +

+ +

37.8 flip_vulkan

+ +

Flips an image along both the vertical and horizontal axis. +

+ +

37.9 gblur_vulkan

+ +

Apply Gaussian blur filter on Vulkan frames. +

+

The filter accepts the following options: +

+
+
sigma
+

Set horizontal sigma, standard deviation of Gaussian blur. Default is 0.5. +

+
+
sigmaV
+

Set vertical sigma, if negative it will be same as sigma. +Default is -1. +

+
+
planes
+

Set which planes to filter. By default all planes are filtered. +

+
+
size
+

Set the kernel size along the horizontal axis. Default is 19. +

+
+
sizeV
+

Set the kernel size along the vertical axis. Default is 0, +which sets to use the same value as size. +

+
+
+ + +

37.10 nlmeans_vulkan

+ +

Denoise frames using Non-Local Means algorithm, implemented on the GPU using +Vulkan. +Supports more pixel formats than nlmeans or nlmeans_opencl, including +alpha channel support. +

+

The filter accepts the following options. +

+
+
s
+

Set denoising strength for all components. Default is 1.0. Must be in range [0.0, 100.0]. +

+
+
p
+

Set patch size for all planes. Default is 7. Must be odd number in range [0, 99]. +

+
+
r
+

Set research size. Default is 15. Must be odd number in range [0, 99]. +

+
+
t
+

Set parallelism. Default is 8. Must be a number in the range [1, 64]. +Larger values will use more VRAM but may not result in greater speed. +The optimal value is hardware and input dependent. +

+
+
s0
+
s1
+
s2
+
s3
+

Set denoising strength for a specific component. Default is 1.0, equal to s. +Must be in range [0.0, 100.0]. 0.0 disables denoising in that component. +

+
+
p0
+
p1
+
p2
+
p3
+

Set patch size for a specific component. Default is 7, equal to p. +Must be odd number in range [0, 99]. +

+
+
+ + +

37.11 overlay_vulkan

+ +

Overlay one video on top of another. +

+

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. +This filter requires all inputs to use the same pixel format. So, format conversion may be needed. +

+

The filter accepts the following options: +

+
+
x
+

Set the x coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
y
+

Set the y coordinate of the overlaid video on the main video. +Default value is 0. +

+
+
+ + +

37.12 transpose_vulkan

+ +

Transpose rows with columns in the input video and optionally flip it. +For more in depth examples see the transpose video filter, which shares mostly the same options. +

+

It accepts the following parameters: +

+
+
dir
+

Specify the transposition direction. +

+

Can assume the following values: +

+
‘cclock_flip’
+

Rotate by 90 degrees counterclockwise and vertically flip. (default) +

+
+
‘clock’
+

Rotate by 90 degrees clockwise. +

+
+
‘cclock’
+

Rotate by 90 degrees counterclockwise. +

+
+
‘clock_flip’
+

Rotate by 90 degrees clockwise and vertically flip. +

+
+ +
+
passthrough
+

Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +

+
‘none’
+

Always apply transposition. (default) +

+
‘portrait’
+

Preserve portrait geometry (when height >= width). +

+
‘landscape’
+

Preserve landscape geometry (when width >= height). +

+
+ +
+
+ + + +

38 QSV Video Filters

+ +

Below is a description of the currently available QSV video filters. +

+

To enable compilation of these filters you need to configure FFmpeg with +--enable-libmfx or --enable-libvpl. +

+

To use QSV filters, you need to setup the QSV device correctly. For more information, please read https://trac.ffmpeg.org/wiki/Hardware/QuickSync +

+ +

38.1 hstack_qsv

+

Stack input videos horizontally. +

+

This is the QSV variant of the hstack filter, each input stream may +have different height, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See hstack. +

+
+
shortest
+

See hstack. +

+
+
height
+

Set height of output. If set to 0, this filter will set height of output to +height of the first input stream. Default value is 0. +

+
+ + +

38.2 vstack_qsv

+

Stack input videos vertically. +

+

This is the QSV variant of the vstack filter, each input stream may +have different width, this filter will scale down/up each input stream while +keeping the original aspect. +

+

It accepts the following options: +

+
+
inputs
+

See vstack. +

+
+
shortest
+

See vstack. +

+
+
width
+

Set width of output. If set to 0, this filter will set width of output to +width of the first input stream. Default value is 0. +

+
+ + +

38.3 xstack_qsv

+

Stack video inputs into custom layout. +

+

This is the QSV variant of the xstack filter. +

+

It accepts the following options: +

+
+
inputs
+

See xstack. +

+
+
shortest
+

See xstack. +

+
+
layout
+

See xstack. +Moreover, this permits the user to supply output size for each input stream. +

+
xstack_qsv=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080
+
+ +
+
grid
+

See xstack. +

+
+
grid_tile_size
+

Set output size for each input stream when grid is set. If this option +is not set, this filter will set output size by default to the size of the +first input stream. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
fill
+

See xstack. +

+
+ + + +

39 Video Sources

+ +

Below is a description of the currently available video sources. +

+ +

39.1 buffer

+ +

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 libavfilter/buffersrc.h. +

+

It accepts the following parameters: +

+
+
video_size
+

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. +

+
+
width
+

The input video width. +

+
+
height
+

The input video height. +

+
+
pix_fmt
+

A string representing the pixel format of the buffered video frames. +It may be a number corresponding to a pixel format, or a pixel format +name. +

+
+
time_base
+

Specify the timebase assumed by the timestamps of the buffered frames. +

+
+
frame_rate
+

Specify the frame rate expected for the video stream. +

+
+
colorspace
+

A string representing the color space of the buffered video frames. +It may be a number corresponding to a color space, or a color space +name. +

+
+
range
+

A string representing the color range of the buffered video frames. +It may be a number corresponding to a color range, or a color range +name. +

+
+
alpha_mode
+

A string representing the alpha mode of the buffered video frames. +It may be a number corresponding to an alpha mode, or an alpha mode +name. +

+
+
pixel_aspect, sar
+

The sample (pixel) aspect ratio of the input video. +

+
+
hw_frames_ctx
+

When using a hardware pixel format, this should be a reference to an +AVHWFramesContext describing input frames. +

+
+ +

For example: +

+
buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
+
+ +

will instruct the source to accept video frames with size 320x240 and +with format "yuv410p", assuming 1/24 as the timestamps timebase and +square pixels (1:1 sample aspect ratio). +Since the pixel format with name "yuv410p" corresponds to the number 6 +(check the enum AVPixelFormat definition in libavutil/pixfmt.h), +this example corresponds to: +

+
buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
+
+ +

Alternatively, the options can be specified as a flat string, but this +syntax is deprecated: +

+

width:height:pix_fmt:time_base.num:time_base.den:pixel_aspect.num:pixel_aspect.den +

+ +

39.2 cellauto

+ +

Create a pattern generated by an elementary cellular automaton. +

+

The initial state of the cellular automaton can be defined through the +filename and pattern options. If such options are +not specified an initial state is created randomly. +

+

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 scroll option. +

+

This source accepts the following options: +

+
+
filename, f
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified file. +In the file, each non-whitespace character is considered an alive +cell, a newline will terminate the row, and further characters in the +file will be ignored. +

+
+
pattern, p
+

Read the initial cellular automaton state, i.e. the starting row, from +the specified string. +

+

Each non-whitespace character in the string is considered an alive +cell, a newline will terminate the row, and further characters in the +string will be ignored. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial cellular automaton row. It +is a floating point number value ranging from 0 to 1, defaults to +1/PHI. +

+

This option is ignored when a file or a pattern is specified. +

+
+
random_seed, seed
+

Set the seed for filling randomly the initial row, 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. +

+
+
rule
+

Set the cellular automaton rule, it is a number ranging from 0 to 255. +Default value is 110. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename or pattern is specified, the size is set +by default to the width of the specified initial state row, and the +height is set to width * PHI. +

+

If size is set, it must contain the width of the specified +pattern string, and the specified pattern will be centered in the +larger row. +

+

If a filename or a pattern string is not specified, the size value +defaults to "320x518" (used for a randomly generated initial state). +

+
+
scroll
+

If set to 1, scroll the output upward when all the rows in the output +have been already filled. If set to 0, the new generated row will be +written over the top row just after the bottom row is filled. +Defaults to 1. +

+
+
start_full, full
+

If set to 1, completely fill the output with generated rows before +outputting the first frame. +This is the default behavior, for disabling set the value to 0. +

+
+
stitch
+

If set to 1, stitch the left and right row edges together. +This is the default behavior, for disabling set the value to 0. +

+
+ + +

39.2.1 Examples

+ +
    +
  • Read the initial state from pattern, and specify an output of +size 200x400. +
    +
    cellauto=f=pattern:s=200x400
    +
    + +
  • Generate a random initial row with a width of 200 cells, with a fill +ratio of 2/3: +
    +
    cellauto=ratio=2/3:s=200x200
    +
    + +
  • Create a pattern generated by rule 18 starting by a single alive cell +centered on an initial row with width 100: +
    +
    cellauto=p=@:s=100x400:full=0:rule=18
    +
    + +
  • Specify a more elaborated initial pattern: +
    +
    cellauto=p='@@ @ @@':s=100x400:full=0:rule=18
    +
    + +
+ + +

39.3 coreimagesrc

+

Video source generated on GPU using Apple’s CoreImage API on OSX. +

+

This video source is a specialized version of the coreimage video filter. +Use a core image generator at the beginning of the applied filterchain to +generate the content. +

+

The coreimagesrc video source accepts the following options: +

+
list_generators
+

List all available generators along with all their respective options as well as +possible minimum and maximum values along with the default values. +

+
list_generators=true
+
+ +
+
size, s
+

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. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+ +

Additionally, all options of the coreimage video filter are accepted. +A complete filterchain can be used for further processing of the +generated input without CPU-HOST transfer. See coreimage documentation +and examples for details. +

+ +

39.3.1 Examples

+ +
    +
  • Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, +given as complete and escaped command-line for Apple’s standard bash shell: +
    +
    ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png
    +
    +

    This example is equivalent to the QRCode example of coreimage without the +need for a nullsrc video source. +

+ + + +

39.4 ddagrab

+ +

Captures the Windows Desktop via Desktop Duplication API. +

+

The filter exclusively returns D3D11 Hardware Frames, for on-gpu encoding +or processing. So an explicit hwdownload is needed for any kind of +software processing. +

+

It accepts the following options: +

+
+
output_idx
+

DXGI Output Index to capture. +

+

Usually corresponds to the index Windows has given the screen minus one, +so it’s starting at 0. +

+

Defaults to output 0. +

+
+
draw_mouse
+

Whether to draw the mouse cursor. +

+

Defaults to true. +

+

Only affects hardware cursors. If a game or application renders its own cursor, +it’ll always be captured. +

+
+
framerate
+

Maximum framerate at which the desktop will be captured - the interval between +successive frames will not be smaller than the inverse of the framerate. When +dup_frames is true (the default) and the desktop is not being updated +often enough, the filter will duplicate a previous frame. Note that there is no +background buffering going on, so when the filter is not polled often enough +then the actual inter-frame interval may be significantly larger. +

+

Defaults to 30 FPS. +

+
+
video_size
+

Specify the size of the captured video. +

+

Defaults to the full size of the screen. +

+

Cropped from the bottom/right if smaller than screen size. +

+
+
offset_x
+

Horizontal offset of the captured video. +

+
+
offset_y
+

Vertical offset of the captured video. +

+
+
output_fmt
+

Desired filter output format. +Defaults to 8 Bit BGRA. +

+

It accepts the following values: +

+
‘auto’
+

Passes all supported output formats to DDA and returns what DDA decides to use. +

+
‘8bit’
+
‘bgra’
+

8 Bit formats always work, and DDA will convert to them if necessary. +

+
‘10bit’
+
‘x2bgr10’
+

Filter initialization will fail if 10 bit format is requested but unavailable. +

+
+ +
+
dup_frames
+

When this option is set to true (the default), the filter will duplicate frames +when the desktop has not been updated in order to maintain approximately +constant target framerate. When this option is set to false, the filter will +wait for the desktop to be updated (inter-frame intervals may vary significantly +in this case). +

+
+
+ + +

39.4.1 Examples

+ +

Capture primary screen and encode using nvenc: +

+
ffmpeg -f lavfi -i ddagrab -c:v h264_nvenc -cq 18 output.mp4
+
+ +

You can also skip the lavfi device and directly use the filter. +Also demonstrates downloading the frame and encoding with libx264. +Explicit output format specification is required in this case: +

+
ffmpeg -filter_complex ddagrab=output_idx=1:framerate=60,hwdownload,format=bgra -c:v libx264 -crf 18 output.mp4
+
+ +

If you want to capture only a subsection of the desktop, this can be achieved +by specifying a smaller size and its offsets into the screen: +

+
ddagrab=video_size=800x600:offset_x=100:offset_y=100
+
+ + + +

39.5 gfxcapture

+ +

Capture windows or monitors using Windows.Graphics.Capture API. +

+

This source provides low overhead capture of application windows or entire monitors. +The filter outputs hardware frames in d3d11 format; use hwdownload,format= +if system memory frames are required. +

+

The window to be captured can be selected via regular expressions on its title, +class name or backing executable name, by explicit native handles, or by monitor +index or explicit native handle. A window must match all provided expressions to be +selected. The first matching window will be picked, in whatever order Windows +returns them. +

+

Explicit handles (hwnd, hmonitor) override pattern or index +based selection. If neither handles nor a monitor index are given, the first +window matching the provided regular expressions is captured. +

+

This source does NOT hold a stable FPS. It returns frames at whatever rate the compositor +provides them, only capped by the max_framerate. +If you need a stable rate, you need to add an fps filter to drop/duplicate frames as needed. +

+

If the capture source disappears mid-capture (window closed, monitor disconnected), the filter will return EOF. +

+

This source accepts the following options: +

+
window_title
+

ECMAScript regular expression matched against the window title. Supports a +PCRE style (?i) prefix for case-insensitive matching. +

+
+
window_class
+

As window_title, but matched against the window class name. +

+
+
window_exe
+

As window_title, but matched against the executable file name of the +window’s process. +

+
+
monitor_idx
+

Zero-based index of the monitor to capture. +

+

Can also be set to window to capture the monitor the selected window +is displayed on at filter initialization time. +

+
+
hwnd
+

Explicit native window handle (HWND). +

+
+
hmonitor
+

Explicit native monitor handle (HMONITOR). +

+
+
capture_cursor
+

Capture the mouse cursor. Enabled by default. +

+
+
capture_border
+

Capture the full area of the window, including its window decorarions/border. +Disabled by default. +

+
+
display_border
+

Draw a yellow highlight border around the captured window. Disabled by default. +

+
+
max_framerate
+

Maximum capture frame rate. Accepts a video rate (e.g. 30, 60/1, +24000/1001). The default is 60 FPS. +The actual rate is the rate at which the compositor renders the window/monitor, +capped by this option. +

+
+
width
+

Force the output canvas width. If zero (default) the initial captured source +width is used. If a negative number is provided, the width will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
height
+

Force the output canvas height. If zero (default) the initial captured source +height is used. If a negative number is provided, the height will be rounded +down to the next multiple of that number. +

+

See resize_mode. +

+
+
crop_left
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_top
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_right
+

Crop this many pixels from the left side of the captured frames. +

+
+
crop_bottom
+

Crop this many pixels from the left side of the captured frames. +

+
+
premultiplied
+

If set to 1, return frames with premultiplied alpha. Default is 0 (straight +alpha). +

+
+
resize_mode
+

Defines how the captured content is fitted into the output canvas size. +Possible values: +

+
‘crop’
+

Crop (or pad with black) to the canvas size. (default) +

+
‘scale’
+

Scale the source to fill the canvas, potentially altering aspect ratio. +

+
‘scale_aspect’
+

Scale the source to fit inside the canvas while preserving aspect ratio. +Remaining area is filled with black. +

+
+ +
+
scale_mode
+

Scaling algorithm used when resizing is required. +

+

Possible values: +

+
‘point’
+

Nearest neighbour (pixelated) scaling. +

+
‘bilinear’
+

Bilinear filtering. (default) +

+
‘bicubic’
+

Bicubic filtering. Potentially more blurry, but fewer scaling artifacts depending on contents. +

+
+ +
+
output_fmt
+

Desired output pixel format inside the D3D11 hardware frames. +

+

Possible values: +

+
‘bgra’
+
‘8bit’
+

8 bit BGRA output (default) +

+
‘x2bgr10’
+
‘10bit’
+

10 bit BGR output +

+
‘rgbaf16’
+
‘16bit’
+

16bit float RGBA output +

+
+ +
+
+ + +

39.5.1 Examples

+
    +
  • Capture a window by title (case-insensitive) at a maximum of 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_title='(?i)My Application':max_framerate=60,hwdownload,format=bgra,format=yuv420p -c:v libx264 -crf 15 capture.mp4
    +
    + +
  • Capture monitor 1 at native refresh, 10bit color depth, scale to 1920x1080 preserving aspect: +
    +
    ffmpeg -filter_complex gfxcapture=monitor_idx=1:width=1920:height=1080:resize_mode=scale_aspect:output_fmt=10bit -c:v hevc_nvenc -cq 15 capture.mp4
    +
    + +
  • Capture a window by executable name, draw border, force point scaling, fixed 60 fps: +
    +
    ffmpeg -filter_complex gfxcapture=window_exe='^firefox.exe$':display_border=1:scale_mode=point,fps=60 -rc qvbr -qvbr_quality_level 15 -c:v h264_amf capture.mp4
    +
    + +
+ + + +

39.6 gradients

+

Generate several gradients. +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
c0, c1, c2, c3, c4, c5, c6, c7
+

Set 8 colors. Default values for colors is to pick random one. +

+
+
x0, y0, y0, y1
+

Set gradient line source and destination points. If negative or out of range, random ones +are picked. +

+
+
nb_colors, n
+

Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2. +

+
+
seed
+

Set seed for picking gradient line points. +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
speed
+

Set speed of gradients rotation. +

+
+
type, t
+

Set type of gradients. +Available values are: +

+
‘linear’
+
‘radial’
+
‘circular’
+
‘spiral’
+
‘square’
+
+ +

Default type is linear. +

+
+ + +

39.6.1 Commands

+ +

This source supports the some above options as commands. +

+ +

39.7 mandelbrot

+ +

Generate a Mandelbrot set fractal, and progressively zoom towards the +point specified with start_x and start_y. +

+

This source accepts the following options: +

+
+
end_pts
+

Set the terminal pts value. Default value is 400. +

+
+
end_scale
+

Set the terminal scale value. +Must be a floating point value. Default value is 0.3. +

+
+
inner
+

Set the inner coloring mode, that is the algorithm used to draw the +Mandelbrot fractal internal region. +

+

It shall assume one of the following values: +

+
black
+

Set black mode. +

+
convergence
+

Show time until convergence. +

+
mincol
+

Set color based on point closest to the origin of the iterations. +

+
period
+

Set period mode. +

+
+ +

Default value is mincol. +

+
+
bailout
+

Set the bailout value. Default value is 10.0. +

+
+
maxiter
+

Set the maximum of iterations performed by the rendering +algorithm. Default value is 7189. +

+
+
outer
+

Set outer coloring mode. +It shall assume one of following values: +

+
iteration_count
+

Set iteration count mode. +

+
normalized_iteration_count
+

set normalized iteration count mode. +

+
+

Default value is normalized_iteration_count. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
start_scale
+

Set the initial scale value. Default value is 3.0. +

+
+
start_x
+

Set the initial x position. Must be a floating point value between +-100 and 100. Default value is -0.743643887037158704752191506114774. +

+
+
start_y
+

Set the initial y position. Must be a floating point value between +-100 and 100. Default value is -0.131825904205311970493132056385139. +

+
+ + +

39.8 mptestsrc

+ +

Generate various test patterns, as generated by the MPlayer test filter. +

+

The size of the generated video is fixed, and is 512x512. +This source is useful in particular for testing encoding features. +

+

This source accepts the following options: +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
test, t
+
+

Set the number or the name of the test to perform. Supported tests are: +

+
dc_luma
+
dc_chroma
+
freq_luma
+
freq_chroma
+
amp_luma
+
amp_chroma
+
cbp
+
mv
+
ring1
+
ring2
+
all
+
max_frames, m
+

Set the maximum number of frames generated for each test, default value is 30. +

+
+
+ +

Default value is "all", which will cycle through the list of all tests. +

+
+ +

Some examples: +

+
mptestsrc=t=dc_luma
+
+ +

will generate a "dc_luma" test pattern. +

+ +

39.9 frei0r_src

+ +

Provide a frei0r source. +

+

To enable compilation of this filter you need to install the frei0r +header and configure FFmpeg with --enable-frei0r. +

+

This source accepts the following parameters: +

+
+
size
+

The size of the video to generate. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+
+
framerate
+

The framerate of the generated video. It may be a string of the form +num/den or a frame rate abbreviation. +

+
+
filter_name
+

The name to the frei0r source to load. For more information regarding frei0r and +how to set the parameters, read the frei0r section in the video filters +documentation. +

+
+
filter_params
+

A ’|’-separated list of parameters to pass to the frei0r source. +

+
+
+ +

For example, to generate a frei0r partik0l source with size 200x200 +and frame rate 10 which is overlaid on the overlay filter main input: +

+
frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
+
+ + +

39.10 life

+ +

Generate a life pattern. +

+

This source is based on a generalization of John Conway’s life game. +

+

The sourced input represents a life grid, each pixel represents a cell +which can be in one of two possible states, alive or dead. Every cell +interacts with its eight neighbours, which are the cells that are +horizontally, vertically, or diagonally adjacent. +

+

At each interaction the grid evolves according to the adopted rule, +which specifies the number of neighbor alive cells which will make a +cell stay alive or born. The rule option allows one to specify +the rule to adopt. +

+

This source accepts the following options: +

+
+
filename, f
+

Set the file from which to read the initial grid state. In the file, +each non-whitespace character is considered an alive cell, and newline +is used to delimit the end of each row. +

+

If this option is not specified, the initial grid is generated +randomly. +

+
+
rate, r
+

Set the video rate, that is the number of frames generated per second. +Default is 25. +

+
+
random_fill_ratio, ratio
+

Set the random fill ratio for the initial random grid. It is a +floating point number value ranging from 0 to 1, defaults to 1/PHI. +It is ignored when a file is specified. +

+
+
random_seed, seed
+

Set the seed for filling the initial random grid, 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. +

+
+
rule
+

Set the life rule. +

+

A rule can be specified with a code of the kind "SNS/BNB", +where NS and NB are sequences of numbers in the range 0-8, +NS specifies the number of alive neighbor cells which make a +live cell stay alive, and NB the number of alive neighbor cells +which make a dead cell to become alive (i.e. to "born"). +"s" and "b" can be used in place of "S" and "B", respectively. +

+

Alternatively a rule can be specified by an 18-bits integer. The 9 +high order bits are used to encode the next cell state if it is alive +for each number of neighbor alive cells, the low order bits specify +the rule for "borning" new cells. Higher order bits encode for an +higher number of neighbor cells. +For example the number 6153 = (12<<9)+9 specifies a stay alive +rule of 12 and a born rule of 9, which corresponds to "S23/B03". +

+

Default value is "S23/B3", which is the original Conway’s game of life +rule, and will keep a cell alive if it has 2 or 3 neighbor alive +cells, and will born a new cell if there are three alive cells around +a dead cell. +

+
+
size, s
+

Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +

+

If filename is specified, the size is set by default to the +same size of the input file. If size is set, it must contain +the size specified in the input file, and the initial grid defined in +that file is centered in the larger resulting area. +

+

If a filename is not specified, the size value defaults to "320x240" +(used for a randomly generated initial grid). +

+
+
stitch
+

If set to 1, stitch the left and right grid edges together, and the +top and bottom edges also. Defaults to 1. +

+
+
mold
+

Set cell mold speed. If set, a dead cell will go from death_color to +mold_color with a step of mold. mold can have a +value from 0 to 255. +

+
+
life_color
+

Set the color of living (or new born) cells. +

+
+
death_color
+

Set the color of dead cells. If mold is set, this is the first color +used to represent a dead cell. +

+
+
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. +

+
+ + +

39.10.1 Examples

+ +
    +
  • Read a grid from pattern, and center it on a grid of size +300x300 pixels: +
    +
    life=f=pattern:s=300x300
    +
    + +
  • Generate a random grid of size 200x200, with a fill ratio of 2/3: +
    +
    life=ratio=2/3:s=200x200
    +
    + +
  • Specify a custom rule for evolving a randomly generated grid: +
    +
    life=rule=S14/B34
    +
    + +
  • Full example with slow death effect (mold) using ffplay: +
    +
    ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
    +
    +
+ + +

39.11 perlin

+

Generate Perlin noise. +

+

Perlin noise is a kind of noise with local continuity in space. This +can be used to generate patterns with continuity in space and time, +e.g. to simulate smoke, fluids, or terrain. +

+

In case more than one octave is specified through the octaves +option, Perlin noise is generated as a sum of components, each one +with doubled frequency. In this case the persistence option +specify the ratio of the amplitude with respect to the previous +component. More octave components enable to specify more high +frequency details in the generated noise (e.g. small size variations +due to boulders in a generated terrain). +

+ +

39.11.1 Options

+
+
size, s
+

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. +Default value is 320x240. +

+
+
rate, r
+

Specify the frame rate expected for the video stream, expressed as a +number of frames per second. Default value is 25. +

+
+
octaves
+

Specify the total number of components making up the noise, each one +with doubled frequency. Default value is 1. +

+
+
persistence
+

Set the ratio used to compute the amplitude of the next octave +component with respect to the previous component amplitude. Default +value is 1. +

+
+
xscale
+
yscale
+

Define a scale factor used to multiple the x, y coordinates. This can +be useful to define an effect with a pattern stretched along the x or +y axis. Default value is 1. +

+
+
tscale
+

Define a scale factor used to multiple the time coordinate. This can +be useful to change the time variation speed. Default value is 1. +

+
+
random_mode
+

Set random mode used to compute initial pattern. +

+

Supported values are: +

+
random
+

Compute and use random seed. +

+
+
ken
+

Use the predefined initial pattern defined by Ken Perlin in the +original article, can be useful to compare the output with other +sources. +

+
+
seed
+

Use the value specified by random_seed option. +

+
+ +

Default value is random. +

+
+
random_seed, seed
+

When random_mode is set to random_seed, use this value +to compute the initial pattern. Default value is 0. +

+
+ + +

39.11.2 Examples

+
    +
  • Generate single component: +
    +
    perlin
    +
    + +
  • Use Perlin noise with 7 components, each one with a halved contribution +to total amplitude: +
    +
    perlin=octaves=7:persistence=0.5
    +
    + +
  • Chain Perlin noise with the lutyuv to generate a black&white +effect: +
    +
    perlin=octaves=3:tscale=0.3,lutyuv=y='if(lt(val\,128)\,255\,0)'
    +
    + +
  • Stretch noise along the y axis, and convert gray level to red-only +signal: +
    +
    perlin=octaves=7:tscale=0.4:yscale=0.3,lutrgb=r=val:b=0:g=0
    +
    +
+ + +

39.12 qrencodesrc

+ +

Generate a QR code using the libqrencode library (see +https://fukuchi.org/works/qrencode/). +

+

To enable the compilation of this source, you need to configure FFmpeg with +--enable-libqrencode. +

+

The QR code is generated from the provided text or text pattern. The +corresponding QR code is scaled and put in the video output according to the +specified output size options. +

+

In case no text is specified, the QR code is not generated, but an empty colored +output is returned instead. +

+

This source accepts the following options: +

+
+
qrcode_width, q
+
padded_qrcode_width, Q
+

Specify an expression for the width of the rendered QR code, with and without +padding. The qrcode_width expression can reference the value set by the +padded_qrcode_width expression, and vice versa. +By default padded_qrcode_width is set to qrcode_width, meaning that +there is no padding. +

+

These expressions are evaluated only once, when initializing the source. +See the qrencode Expressions section for details. +

+

Note that some of the constants are missing for the source (for example the +x or t or ¸n), since they only makes sense when evaluating the +expression for each frame rather than at initialization time. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
case_sensitive, cs
+

Instruct libqrencode to use case sensitive encoding. This is enabled by +default. This can be disabled to reduce the QR encoding size. +

+
+
level, l
+

Specify the QR encoding error correction level. With an higher correction level, +the encoding size will increase but the code will be more robust to corruption. +Lower level is L. +

+

It accepts the following values: +

+
‘L’
+
‘M’
+
‘Q’
+
‘H’
+
+ +
+
expansion
+

Select how the input text is expanded. Can be either none, or +normal (default). See the qrencode Text expansion +section for details. +

+
+
text
+
textfile
+

Define the text to be rendered. In case neither is specified, no QR is encoded +(just an empty colored frame). +

+

In case expansion is enabled, the text is treated as a text template, using the +qrencode expansion mechanism. See the qrencode +Text expansion section for details. +

+
+
background_color, bc
+
foreground_color, fc
+

Set the QR code and background color. The default value of +foreground_color is "black", the default value of background_color +is "white". +

+

For the syntax of the color options, check the "Color" +section in the ffmpeg-utils manual. +

+
+ + +

39.12.1 Examples

+ +
    +
  • Generate a QR code encoding the specified text with the default size: +
    +
    qrencodesrc=text=www.ffmpeg.org
    +
    + +
  • Same as below, but select blue on pink colors: +
    +
    qrencodesrc=text=www.ffmpeg.org:bc=pink:fc=blue
    +
    + +
  • Generate a QR code with width of 200 pixels and padding, making the padded width +4/3 of the QR code width: +
    +
    qrencodesrc=text=www.ffmpeg.org:q=200:Q=4/3*q
    +
    + +
  • Generate a QR code with padded width of 200 pixels and padding, making the QR +code width 3/4 of the padded width: +
    +
    qrencodesrc=text=www.ffmpeg.org:Q=200:q=3/4*Q
    +
    + +
  • Generate a QR code encoding the frame number: +
    +
    qrencodesrc=text=%{n}
    +
    + +
  • Generate a QR code encoding the GMT timestamp: +
    +
    qrencodesrc=text=%{gmtime}
    +
    + +
  • Generate a QR code encoding the timestamp expressed as a float: +
    +
    qrencodesrc=text=%{pts}
    +
    + +
+ + +

39.13 allrgb, allyuv, color, colorchart, colorspectrum, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc

+ +

The allrgb source returns frames of size 4096x4096 of all rgb colors. +

+

The allyuv source returns frames of size 4096x4096 of all yuv colors. +

+

The color source provides an uniformly colored input. +

+

The colorchart source provides a colors checker chart. +

+

The colorspectrum source provides a color spectrum input. +

+

The haldclutsrc source provides an identity Hald CLUT. See also +haldclut filter. +

+

The 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. +

+

The pal75bars source generates a color bars pattern, based on +EBU PAL recommendations with 75% color levels. +

+

The pal100bars source generates a color bars pattern, based on +EBU PAL recommendations with 100% color levels. +

+

The rgbtestsrc source generates an RGB test pattern useful for +detecting RGB vs BGR issues. You should see a red, green and blue +stripe from top to bottom. +

+

The smptebars source generates a color bars pattern, based on +the SMPTE Engineering Guideline EG 1-1990. +

+

The smptehdbars source generates a color bars pattern, based on +the SMPTE RP 219-2002. +

+

The testsrc source generates a test video pattern, showing a +color pattern, a scrolling gradient and a timestamp. This is mainly +intended for testing purposes. +

+

The testsrc2 source is similar to testsrc, but supports more +pixel formats instead of just rgb24. This allows using it as an +input for other tests without requiring a format conversion. +

+

The yuvtestsrc source generates an YUV test pattern. You should +see a y, cb and cr stripe from top to bottom. +

+

The sources accept the following parameters: +

+
+
level
+

Specify the level of the Hald CLUT, only available in the haldclutsrc +source. A level of N generates a picture of N*N*N by N*N*N +pixels to be used as identity matrix for 3D lookup tables. Each component is +coded on a 1/(N*N) scale. +

+
+
color, c
+

Specify the color of the source, only available in the color +source. For the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. +

+
+
size, s
+

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 allrgb, allyuv, and +haldclutsrc filters. +

+
+
rate, r
+

Specify the frame rate of the sourced video, as the number of frames +generated per second. It has to be a string in the format +frame_rate_num/frame_rate_den, an integer number, a floating point +number or a valid video frame rate abbreviation. The default value is +"25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+

Since the frame rate is used as time base, all frames including the last one +will have their full duration. If the specified duration is not a multiple +of the frame duration, it will be rounded up. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
alpha
+

Specify the alpha (opacity) of the background, only available in the +testsrc2 source. The value must be between 0 (fully transparent) and +255 (fully opaque, the default). +

+
+
decimals, n
+

Set the number of decimals to show in the timestamp, only available in the +testsrc source. +

+

The displayed timestamp value will correspond to the original +timestamp value multiplied by the power of 10 of the specified +value. Default value is 0. +

+
+
type
+

Set the type of the color spectrum, only available in the +colorspectrum source. Can be one of the following: +

+
+
‘black’
+
‘white’
+
‘all’
+
+ +
+
patch_size
+

Set patch size of single color patch, only available in the +colorchart source. Default is 64x64. +

+
+
preset
+

Set colorchecker colors preset, only available in the +colorchart source. +

+

Available values are: +

+
‘reference’
+
‘skintones’
+
+ +

Default value is reference. +

+
+ + +

39.13.1 Examples

+ +
    +
  • Generate a video with a duration of 5.3 seconds, with size +176x144 and a frame rate of 10 frames per second: +
    +
    testsrc=duration=5.3:size=qcif:rate=10
    +
    + +
  • The following graph description will generate a red source +with an opacity of 0.2, with size "qcif" and a frame rate of 10 +frames per second: +
    +
    color=c=red@0.2:s=qcif:r=10
    +
    + +
  • If the input content is to be ignored, nullsrc can be used. The +following command generates noise in the luma plane by employing +the geq filter: +
    +
    nullsrc=s=256x256, geq=random(1)*255:128:128
    +
    +
+ + +

39.13.2 Commands

+ +

The color source supports the following commands: +

+
+
c, color
+

Set the color of the created image. Accepts the same syntax of the +corresponding color option. +

+
+ + +

39.14 openclsrc

+ +

Generate video using an OpenCL program. +

+
+
source
+

OpenCL program source file. +

+
+
kernel
+

Kernel name in program. +

+
+
size, s
+

Size of frames to generate. This must be set. +

+
+
format
+

Pixel format to use for the generated frames. This must be set. +

+
+
rate, r
+

Number of frames generated every second. Default value is ’25’. +

+
+
+ +

For details of how the program loading works, see the program_opencl +filter. +

+

Example programs: +

+
    +
  • Generate a colour ramp by setting pixel values from the position of the pixel +in the output image. (Note that this will work with all pixel formats, but +the generated output will not be the same.) +
    __kernel void ramp(__write_only image2d_t dst,
    +                   unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 val;
    +    val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
    +
    +    write_imagef(dst, loc, val);
    +}
    +
    +
  • Generate a Sierpinski carpet pattern, panning by a single pixel each frame. +
    __kernel void sierpinski_carpet(__write_only image2d_t dst,
    +                                unsigned int index)
    +{
    +    int2 loc = (int2)(get_global_id(0), get_global_id(1));
    +
    +    float4 value = 0.0f;
    +    int x = loc.x + index;
    +    int y = loc.y + index;
    +    while (x > 0 || y > 0) {
    +        if (x % 3 == 1 && y % 3 == 1) {
    +            value = 1.0f;
    +            break;
    +        }
    +        x /= 3;
    +        y /= 3;
    +    }
    +
    +    write_imagef(dst, loc, value);
    +}
    +
    +
+ + +

39.15 sierpinski

+ +

Generate a Sierpinski carpet/triangle fractal, and randomly pan around. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
seed
+

Set seed which is used for random panning. +

+
+
jump
+

Set max jump for single pan destination. Allowed range is from 1 to 10000. +

+
+
type
+

Set fractal type, can be default carpet or triangle. +

+
+ + +

39.16 zoneplate

+

Generate a zoneplate test video pattern. +

+

This source accepts the following options: +

+
+
size, s
+

Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "320x240". +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
duration, d
+

Set the duration of the sourced video. See +the Time duration section in the ffmpeg-utils(1) manual +for the accepted syntax. +

+

If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +

+
+
sar
+

Set the sample aspect ratio of the sourced video. +

+
+
precision
+

Set precision in bits for look-up table for sine calculations. Default value is 10. +Allowed range is from 4 to 16. +

+
+
xo
+

Set horizontal axis offset for output signal. Default value is 0. +

+
+
yo
+

Set vertical axis offset for output signal. Default value is 0. +

+
+
to
+

Set time axis offset for output signal. Default value is 0. +

+
+
k0
+

Set 0-order, constant added to signal phase. Default value is 0. +

+
+
kx
+

Set 1-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky
+

Set 1-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt
+

Set 1-order, phase factor multiplier for time axis. Default value is 0. +

+
+
kxt, kyt, kxy
+

Set phase factor multipliers for combination of spatial and temporal axis. +Default value is 0. +

+
+
kx2
+

Set 2-order, phase factor multiplier for horizontal axis. Default value is 0. +

+
+
ky2
+

Set 2-order, phase factor multiplier for vertical axis. Default value is 0. +

+
+
kt2
+

Set 2-order, phase factor multiplier for time axis. Default value is 0. +

+
+
ku
+

Set the constant added to final phase to produce chroma-blue component of signal. +Default value is 0. +

+
+
kv
+

Set the constant added to final phase to produce chroma-red component of signal. +Default value is 0. +

+
+ + +

39.16.1 Commands

+ +

This source supports the some above options as commands. +

+ +

39.16.2 Examples

+ +
    +
  • Generate horizontal color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:kx2=256:s=wvga:xo=-426:kt=11
    +
    + +
  • Generate vertical color sine sweep: +
    +
    zoneplate=ku=512:kv=0:kt2=0:ky2=156:s=wvga:yo=-240:kt=11
    +
    + +
  • Generate circular zone-plate: +
    +
    zoneplate=ku=512:kv=100:kt2=0:ky2=256:kx2=556:s=wvga:yo=0:kt=11
    +
    +
+ + + +

40 Video Sinks

+ +

Below is a description of the currently available video sinks. +

+ +

40.1 buffersink

+ +

Buffer video frames, and make them available to the end of the filter +graph. +

+

This sink is mainly intended for programmatic use, in particular +through the interface defined in libavfilter/buffersink.h +or the options system. +

+

It accepts a pointer to an AVBufferSinkContext structure, which +defines the incoming buffers’ formats, to be passed as the opaque +parameter to avfilter_init_filter for initialization. +

+ +

40.2 nullsink

+ +

Null video sink: do absolutely nothing with the input video. It is +mainly useful as a template and for use in analysis / debugging +tools. +

+ + +

41 Multimedia Filters

+ +

Below is a description of the currently available multimedia filters. +

+ +

41.1 a3dscope

+ +

Convert input audio to 3d scope video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
fov
+

Set the camera field of view. Default is 90 degrees. +Allowed range is from 40 to 150. +

+
+
roll
+

Set the camera roll. +

+
+
pitch
+

Set the camera pitch. +

+
+
yaw
+

Set the camera yaw. +

+
+
xzoom
+

Set the camera zoom on X-axis. +

+
+
yzoom
+

Set the camera zoom on Y-axis. +

+
+
zzoom
+

Set the camera zoom on Z-axis. +

+
+
xpos
+

Set the camera position on X-axis. +

+
+
ypos
+

Set the camera position on Y-axis. +

+
+
zpos
+

Set the camera position on Z-axis. +

+
+
length
+

Set the length of displayed audio waves in number of frames. +

+
+ + +

41.1.1 Commands

+ +

Filter supports the some above options as commands. +

+ +

41.2 abitscope

+ +

Convert input audio to a video output, displaying the audio bit scope. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 1024x256. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channels. Unrecognized or missing colors will be replaced +by white color. +

+
+
mode, m
+

Set output mode. Can be bars or trace. Default is bars. +

+
+ + +

41.3 adrawgraph

+

Draw a graph using input audio metadata. +

+

See drawgraph +

+ +

41.4 agraphmonitor

+ +

See graphmonitor. +

+ +

41.5 ahistogram

+ +

Convert input audio to a video output, displaying the volume histogram. +

+

The filter accepts the following options: +

+
+
dmode
+

Specify how histogram is calculated. +

+

It accepts the following values: +

+
‘single’
+

Use single histogram for all channels. +

+
‘separate’
+

Use separate histogram for each channel. +

+
+

Default is single. +

+
+
rate, r
+

Set frame rate, expressed as number of frames per second. Default +value is "25". +

+
+
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 hd720. +

+
+
scale
+

Set display scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘sqrt’
+

square root +

+
‘cbrt’
+

cubic root +

+
‘lin’
+

linear +

+
‘rlog’
+

reverse logarithmic +

+
+

Default is log. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘log’
+

logarithmic +

+
‘lin’
+

linear +

+
+

Default is log. +

+
+
acount
+

Set how much frames to accumulate in histogram. +Default is 1. Setting this to -1 accumulates all frames. +

+
+
rheight
+

Set histogram ratio of window height. +

+
+
slide
+

Set sonogram sliding. +

+

It accepts the following values: +

+
‘replace’
+

replace old rows with new ones. +

+
‘scroll’
+

scroll from top to bottom. +

+
+

Default is replace. +

+
+
hmode
+

Set histogram mode. +

+

It accepts the following values: +

+
‘abs’
+

Use absolute values of samples. +

+
‘sign’
+

Use untouched values of samples. +

+
+

Default is abs. +

+
+ + +

41.6 aphasemeter

+ +

Measures phase of input audio, which is exported as metadata lavfi.aphasemeter.phase, +representing mean phase of current audio frame. A video output can also be produced and is +enabled by default. The audio is passed through as first output. +

+

Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in +range [-1, 1] where -1 means left and right channels are completely out of phase +and 1 means channels are in phase. +

+

The filter accepts the following options, all related to its video output: +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
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 800x400. +

+
+
rc
+
gc
+
bc
+

Specify the red, green, blue contrast. Default values are 2, +7 and 1. +Allowed range is [0, 255]. +

+
+
mpc
+

Set color which will be used for drawing median phase. If color is +none which is default, no median phase value will be drawn. +

+
+
video
+

Enable video output. Default is enabled. +

+
+ + +

41.6.1 phasing detection

+ +

The filter also detects out of phase and mono sequences in stereo streams. +It logs the sequence start, end and duration when it lasts longer or as long as the minimum set. +

+

The filter accepts the following options for this detection: +

+
+
phasing
+

Enable mono and out of phase detection. Default is disabled. +

+
+
tolerance, t
+

Set phase tolerance for mono detection, in amplitude ratio. Default is 0. +Allowed range is [0, 1]. +

+
+
angle, a
+

Set angle threshold for out of phase detection, in degree. Default is 170. +Allowed range is [90, 180]. +

+
+
duration, d
+

Set mono or out of phase duration until notification, expressed in seconds. Default is 2. +

+
+ + +

41.6.2 Examples

+ +
    +
  • Complete example with ffmpeg to detect 1 second of mono with 0.001 phase tolerance: +
    +
    ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
    +
    +
+ + +

41.7 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 monaural 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: +

+
+
mode, m
+

Set the vectorscope mode. +

+

Available values are: +

+
‘lissajous’
+

Lissajous rotated by 45 degrees. +

+
+
‘lissajous_xy’
+

Same as above but not rotated. +

+
+
‘polar’
+

Shape resembling half of circle. +

+
+ +

Default value is ‘lissajous’. +

+
+
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 400x400. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
rc
+
gc
+
bc
+
ac
+

Specify the red, green, blue and alpha contrast. Default values are 40, +160, 80 and 255. +Allowed range is [0, 255]. +

+
+
rf
+
gf
+
bf
+
af
+

Specify the red, green, blue and alpha fade. Default values are 15, +10, 5 and 5. +Allowed range is [0, 255]. +

+
+
zoom
+

Set the zoom factor. Default value is 1. Allowed range is [0, 10]. +Values lower than 1 will auto adjust zoom factor to maximal possible value. +

+
+
draw
+

Set the vectorscope drawing mode. +

+

Available values are: +

+
‘dot’
+

Draw dot for each sample. +

+
+
‘line’
+

Draw line between previous and current sample. +

+
+
‘aaline’
+

Draw anti-aliased line between previous and current sample. +

+
+ +

Default value is ‘dot’. +

+
+
scale
+

Specify amplitude scale of audio samples. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+
‘log’
+

Logarithmic. +

+
+ +
+
swap
+

Swap left channel axis with right channel axis. +

+
+
mirror
+

Mirror axis. +

+
+
‘none’
+

No mirror. +

+
+
‘x’
+

Mirror only x axis. +

+
+
‘y’
+

Mirror only y axis. +

+
+
‘xy’
+

Mirror both axis. +

+
+ +
+
+ + +

41.7.1 Examples

+ +
    +
  • Complete example using ffplay: +
    +
    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]'
    +
    +
+ + +

41.7.2 Commands

+ +

This filter supports the all above options as commands except options size and rate. +

+ +

41.8 bench, abench

+ +

Benchmark part of a filtergraph. +

+

The filter accepts the following options: +

+
+
action
+

Start or stop a timer. +

+

Available values are: +

+
‘start’
+

Get the current time, set it as frame metadata (using the key +lavfi.bench.start_time), and forward the frame to the next filter. +

+
+
‘stop’
+

Get the current time and fetch the lavfi.bench.start_time metadata from +the input frame metadata to get the time difference. Time difference, average, +maximum and minimum time (respectively t, avg, max and +min) are then printed. The timestamps are expressed in seconds. +

+
+
+
+ + +

41.8.1 Examples

+ +
    +
  • Benchmark selectivecolor filter: +
    +
    bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
    +
    +
+ + +

41.9 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: +

+
+
n
+

Set the number of segments. Default is 2. +

+
+
v
+

Set the number of output video streams, that is also the number of video +streams in each segment. Default is 1. +

+
+
a
+

Set the number of output audio streams, that is also the number of audio +streams in each segment. Default is 0. +

+
+
unsafe
+

Activate unsafe mode: do not fail if segments have a different format. +

+
+
+ +

The filter has v+a outputs: first v video outputs, then +a audio outputs. +

+

There are nx(v+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. +

+ +

41.9.1 Examples

+ +
    +
  • Concatenate an opening, an episode and an ending, all in bilingual version +(video in stream 0, audio in streams 1 and 2): +
    +
    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
    +
    + +
  • Concatenate two parts, handling audio and video separately, using the +(a)movie sources, and adjusting the resolution: +
    +
    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]
    +
    +

    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. +

    +
+ + +

41.9.2 Commands

+ +

This filter supports the following commands: +

+
next
+

Close the current segment and step to the next one +

+
+ + +

41.10 ebur128

+ +

EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness +level. By default, it logs a message at a frequency of 10Hz with the +Momentary loudness (identified by M), Short-term loudness (S), +Integrated loudness (I) and Loudness Range (LRA). +

+

The filter can only analyze streams which have +sample format is double-precision floating point. The input stream will be converted to +this specification, if needed. Users may need to insert aformat and/or aresample filters +after this filter to obtain the original parameters. +

+

The filter also has a video output (see the 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), but can optionally be configured +to instead display short-term loudness (see gauge). +

+

The green area marks a +/- 1LU target range around the target loudness +(-23LUFS by default, unless modified through target). +

+

More information about the Loudness Recommendation EBU R128 on +http://tech.ebu.ch/loudness. +

+

The filter accepts the following options: +

+
+
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 0. +

+
+
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 640x480. +

+
+
meter
+

Set the EBU scale meter. Default is 9. Common values are 9 and +18, respectively for EBU scale meter +9 and EBU scale meter +18. Any +other integer value between this range is allowed. +

+
+
metadata
+

Set metadata injection. If set to 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 lavfi.r128.. +

+

Default is 0. +

+
+
framelog
+

Force the frame logging level. +

+

Available values are: +

+
‘quiet’
+

logging disabled +

+
‘info’
+

information logging level +

+
‘verbose’
+

verbose logging level +

+
+ +

By default, the logging level is set to info. If the video or +the metadata options are set, it switches to verbose. +

+
+
peak
+

Set peak mode(s). +

+

Available modes can be cumulated (the option is a flag type). Possible +values are: +

+
‘none’
+

Disable any peak mode (default). +

+
‘sample’
+

Enable sample-peak mode. +

+

Simple peak mode looking for the higher sample value. It logs a message +for sample-peak (identified by SPK). +

+
‘true’
+

Enable true-peak mode. +

+

If enabled, the peak lookup is done on an over-sampled version of the input +stream for better peak accuracy. It logs a message for true-peak. +(identified by TPK) and true-peak per frame (identified by FTPK). +This mode requires a build with libswresample. +

+
+ +
+
dualmono
+

Treat mono input files as "dual mono". If a mono file is intended for playback +on a stereo system, its EBU R128 measurement will be perceptually incorrect. +If set to true, this option will compensate for this effect. +Multi-channel input files are not affected by this option. +

+
+
panlaw
+

Set a specific pan law to be used for the measurement of dual mono files. +This parameter is optional, and has a default value of -3.01dB. +

+
+
target
+

Set a specific target level (in LUFS) used as relative zero in the visualization. +This parameter is optional and has a default value of -23LUFS as specified +by EBU R128. However, material published online may prefer a level of -16LUFS +(e.g. for use with podcasts or video platforms). +

+
+
gauge
+

Set the value displayed by the gauge. Valid values are momentary and s +shortterm. By default the momentary value will be used, but in certain +scenarios it may be more useful to observe the short term value instead (e.g. +live mixing). +

+
+
scale
+

Sets the display scale for the loudness. Valid parameters are absolute +(in LUFS) or relative (LU) relative to the target. This only affects the +video output, not the summary or continuous log output. +

+
+
integrated
+

Read-only exported value for measured integrated loudness, in LUFS. +

+
+
range
+

Read-only exported value for measured loudness range, in LU. +

+
+
lra_low
+

Read-only exported value for measured LRA low, in LUFS. +

+
+
lra_high
+

Read-only exported value for measured LRA high, in LUFS. +

+
+
sample_peak
+

Read-only exported value for measured sample peak, in dBFS. +

+
+
true_peak
+

Read-only exported value for measured true peak, in dBFS. +

+
+ + +

41.10.1 Examples

+ +
    +
  • Real-time graph using ffplay, with a EBU scale meter +18: +
    +
    ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
    +
    + +
  • Run an analysis with ffmpeg: +
    +
    ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
    +
    +
+ + +

41.11 interleave, ainterleave

+ +

Temporally interleave frames from several inputs. +

+

interleave works with video inputs, ainterleave with audio. +

+

These filters read frames from several inputs and send the oldest +queued frame to the output. +

+

Input streams must have 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 select filter +which always drops input frames. The interleave filter will keep +reading from that input, but it will never be able to send new frames +to output until the input sends 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: +

+
+
nb_inputs, n
+

Set the number of different inputs, it is 2 by default. +

+
+
duration
+

How to determine the end-of-stream. +

+
+
longest
+

The duration of the longest input. (default) +

+
+
shortest
+

The duration of the shortest input. +

+
+
first
+

The duration of the first input. +

+
+ +
+
+ + +

41.11.1 Examples

+ +
    +
  • Interleave frames belonging to different streams using ffmpeg: +
    +
    ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
    +
    + +
  • Add flickering blur effect: +
    +
    select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
    +
    +
+ + +

41.12 latency, alatency

+

Measure filtering latency. +

+

Report previous filter filtering latency, delay in number of audio samples for audio filters +or number of video frames for video filters. +

+

On end of input stream, filter will report min and max measured latency for previous running filter +in filtergraph. +

+ +

41.13 metadata, ametadata

+ +

Manipulate frame metadata. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

If both value and key is set, select frames +which have such metadata. If only key is set, select +every frame that has such key in metadata. +

+
+
‘add’
+

Add new metadata key and value. If key is already available +do nothing. +

+
+
‘modify’
+

Modify value of already present key. +

+
+
‘delete’
+

If value is set, delete only keys that have such value. +Otherwise, delete key. If key is not set, delete all metadata values in +the frame. +

+
+
‘print’
+

Print key and its value if metadata was found. If key is not set print all +metadata values available in frame. +

+
+ +
+
key
+

Set key used with all modes. Must be set for all modes except print and delete. +

+
+
value
+

Set metadata value which will be used. This option is mandatory for +modify and add mode. +

+
+
function
+

Which function to use when comparing metadata value and value. +

+

Can be one of following: +

+
+
‘same_str’
+

Values are interpreted as strings, returns true if metadata value is same as value. +

+
+
‘starts_with’
+

Values are interpreted as strings, returns true if metadata value starts with +the value option string. +

+
+
‘less’
+

Values are interpreted as floats, returns true if metadata value is less than value. +

+
+
‘equal’
+

Values are interpreted as floats, returns true if value is equal with metadata value. +

+
+
‘greater’
+

Values are interpreted as floats, returns true if metadata value is greater than value. +

+
+
‘expr’
+

Values are interpreted as floats, returns true if expression from option expr +evaluates to true. +

+
+
‘ends_with’
+

Values are interpreted as strings, returns true if metadata value ends with +the value option string. +

+
+ +
+
expr
+

Set expression which is used when function is set to expr. +The expression is evaluated through the eval API and can contain the following +constants: +

+
+
VALUE1, FRAMEVAL
+

Float representation of value from metadata key. +

+
+
VALUE2, USERVAL
+

Float representation of value as supplied by user in value option. +

+
+ +
+
file
+

If specified in print mode, output is written to the named file. Instead of +plain filename any writable url can be specified. Filename “-” is a shorthand +for standard output. If file option is not set, output is written to the log +with AV_LOG_INFO loglevel. +

+
+
direct
+

Reduces buffering in print mode when output is written to a URL set using file. +

+
+
+ + +

41.13.1 Examples

+ +
    +
  • Print all metadata values for frames with key lavfi.signalstats.YDIF with values +between 0 and 1. +
    +
    signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
    +
    +
  • Print silencedetect output to file metadata.txt. +
    +
    silencedetect,ametadata=mode=print:file=metadata.txt
    +
    +
  • Direct all metadata to a pipe with file descriptor 4. +
    +
    metadata=mode=print:file='pipe\:4'
    +
    +
+ + +

41.14 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 the following options: +

+
+
mode
+

Select the permissions mode. +

+

It accepts the following values: +

+
‘none’
+

Do nothing. This is the default. +

+
‘ro’
+

Set all the output frames read-only. +

+
‘rw’
+

Set all the output frames directly writable. +

+
‘toggle’
+

Make the frame read-only if writable, and writable if read-only. +

+
‘random’
+

Set each output frame read-only or writable randomly. +

+
+ +
+
seed
+

Set the seed for the random mode, 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. +

+
+ +

Note: in case of auto-inserted filter between the permission filter and the +following one, the permission might not be received as expected in that +following filter. Inserting a format or aformat filter before the +perms/aperms filter can avoid this problem. +

+ +

41.15 realtime, arealtime

+ +

Slow down filtering to match real time approximately. +

+

These filters will pause the filtering for a variable amount of time to +match the output rate with the input timestamps. +They are similar to the re option to ffmpeg. +

+

They accept the following options: +

+
+
limit
+

Time limit for the pauses. Any pause longer than that will be considered +a timestamp discontinuity and reset the timer. Default is 2 seconds. +

+
speed
+

Speed factor for processing. The value must be a float larger than zero. +Values larger than 1.0 will result in faster than realtime processing, +smaller will slow processing down. The limit is automatically adapted +accordingly. Default is 1.0. +

+

A processing speed faster than what is possible without these filters cannot +be achieved. +

+
+ + +

41.15.1 Commands

+ +

Both filters supports the all above options as commands. +

+ +

41.16 segment, asegment

+ +

Split single input stream into multiple streams. +

+

This filter does opposite of concat filters. +

+

segment works on video frames, asegment on audio samples. +

+

This filter accepts the following options: +

+
+
timestamps
+

Timestamps of output segments separated by ’|’. The first segment will run +from the beginning of the input stream. The last segment will run until +the end of the input stream +

+
+
frames, samples
+

Exact frame/sample count to split the segments. +

+
+ +

In all cases, prefixing an each segment with ’+’ will make it relative to the +previous segment. +

+ +

41.16.1 Examples

+ +
    +
  • Split input audio stream into three output audio streams, starting at start of input audio stream +and storing that in 1st output audio stream, then following at 60th second and storing than in 2nd +output audio stream, and last after 150th second of input audio stream store in 3rd output audio stream: +
    +
    asegment=timestamps="60|150"
    +
    + +
+ + +

41.17 select, aselect

+ +

Select frames to pass in output. +

+

This filter accepts the following options: +

+
+
expr, e
+

Set expression, which is evaluated for each input frame. +

+

If the expression is evaluated to zero, the frame 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 +ceil(val)-1, assuming that the input index starts from 0. +

+

For example a value of 1.2 corresponds to the output with index +ceil(1.2)-1 = 2-1 = 1, that is the second output. +

+
+
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. +

+
+ +

The expression can contain the following constants: +

+
+
n
+

The (sequential) number of the filtered frame, starting from 0. +

+
+
selected_n
+

The (sequential) number of the selected frame, starting from 0. +

+
+
prev_selected_n
+

The sequential number of the last selected frame. It’s NAN if undefined. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
pts
+

The PTS (Presentation TimeStamp) of the filtered frame, +expressed in TB units. It’s NAN if undefined. +

+
+
t
+

The PTS of the filtered frame, +expressed in seconds. It’s NAN if undefined. +

+
+
prev_pts
+

The PTS of the previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_pts
+

The PTS of the last previously filtered frame. It’s NAN if undefined. +

+
+
prev_selected_t
+

The PTS of the last previously selected frame, expressed in seconds. It’s NAN if undefined. +

+
+
start_pts
+

The first PTS in the stream which is not NAN. It remains NAN if not found. +

+
+
start_t
+

The first PTS, in seconds, in the stream which is not NAN. It remains NAN if not found. +

+
+
pict_type (video only)
+

The type of the filtered frame. It can assume one of the following +values: +

+
I
+
P
+
B
+
S
+
SI
+
SP
+
BI
+
+ +
+
interlace_type (video only)
+

The frame interlace type. It can assume one of the following values: +

+
PROGRESSIVE
+

The frame is progressive (not interlaced). +

+
TOPFIRST
+

The frame is top-field-first. +

+
BOTTOMFIRST
+

The frame is bottom-field-first. +

+
+ +
+
consumed_sample_n (audio only)
+

the number of selected samples before the current frame +

+
+
samples_n (audio only)
+

the number of samples in the current frame +

+
+
sample_rate (audio only)
+

the input sample rate +

+
+
key
+

This is 1 if the filtered frame is a key-frame, 0 otherwise. +

+
+
pos
+

the position in the file of the filtered frame, -1 if the information +is not available (e.g. for synthetic video); deprecated, do not use +

+
+
scene (video only)
+

value between 0 and 1 to indicate a new scene; a low value reflects a low +probability for the current frame to introduce a new scene, while a higher +value means the current frame is more likely to be one (see the example below) +

+
+
concatdec_select
+

The concat demuxer can select only part of a concat input file by setting an +inpoint and an outpoint, but the output packets may not be entirely contained +in the selected interval. By using this variable, it is possible to skip frames +generated by the concat demuxer which are not exactly contained in the selected +interval. +

+

This works by comparing the frame pts against the lavf.concat.start_time +and the lavf.concat.duration packet metadata values which are also +present in the decoded frames. +

+

The concatdec_select variable is -1 if the frame pts is at least +start_time and either the duration metadata is missing or the frame pts is less +than start_time + duration, 0 otherwise, and NaN if the start_time metadata is +missing. +

+

That basically means that an input frame is selected if its pts is within the +interval set by the concat demuxer. +

+
+
iw (video only)
+

Represents the width of the input video frame. +

+
+
ih (video only)
+

Represents the height of the input video frame. +

+
+
view (video only)
+

View ID for multi-view video. +

+
+
+ +

The default value of the select expression is "1". +

+ +

41.17.1 Examples

+ +
    +
  • Select all frames in input: +
    +
    select
    +
    + +

    The example above is the same as: +

    +
    select=1
    +
    + +
  • Skip all frames: +
    +
    select=0
    +
    + +
  • Select only I-frames: +
    +
    select='eq(pict_type\,I)'
    +
    + +
  • Select one frame every 100: +
    +
    select='not(mod(n\,100))'
    +
    + +
  • Select only frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)
    +
    + +
  • Select only I-frames contained in the 10-20 time interval: +
    +
    select=between(t\,10\,20)*eq(pict_type\,I)
    +
    + +
  • Select frames with a minimum distance of 10 seconds: +
    +
    select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
    +
    + +
  • Use aselect to select only audio frames with samples number > 100: +
    +
    aselect='gt(samples_n\,100)'
    +
    + +
  • Create a mosaic of the first scenes: +
    +
    ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
    +
    + +

    Comparing scene against a value between 0.3 and 0.5 is generally a sane +choice. +

    +
  • Send even and odd frames to separate outputs, and compose them: +
    +
    select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
    +
    + +
  • Select useful frames from an ffconcat file which is using inpoints and +outpoints but where the source files are not intra frame only. +
    +
    ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
    +
    +
+ + +

41.18 sendcmd, asendcmd

+ +

Send commands to filters in the filtergraph. +

+

These filters read commands to be sent to other filters in the +filtergraph. +

+

sendcmd must be inserted between two video filters, +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 +with the commands option, or in a file specified by the +filename option. +

+

These filters accept the following options: +

+
commands, c
+

Set the commands to be read and sent to the other filters. +

+
filename, f
+

Set the filename of the commands to be read and sent to the other +filters. +

+
+ + +

41.18.1 Commands syntax

+ +

A commands description consists of a sequence of interval +specifications, comprising a list of commands to be executed when a +particular event related to that interval occurs. The occurring event +is typically the current frame time entering or leaving a given time +interval. +

+

An interval is specified by the following syntax: +

+
START[-END] COMMANDS;
+
+ +

The time interval is specified by the START and END times. +END is optional and defaults to the maximum time. +

+

The current frame time is considered within the specified interval if +it is included in the interval [START, END), that is when +the time is greater or equal to START and is lesser than +END. +

+

COMMANDS consists of a sequence of one or more command +specifications, separated by ",", relating to that interval. The +syntax of a command specification is given by: +

+
[FLAGS] TARGET COMMAND ARG
+
+ +

FLAGS is optional and specifies the type of events relating to +the time interval which enable sending the specified command, and must +be a non-null sequence of identifier flags separated by "+" or "|" and +enclosed between "[" and "]". +

+

The following flags are recognized: +

+
enter
+

The command is sent when the current frame timestamp enters the +specified interval. In other words, the command is sent when the +previous frame timestamp was not in the given interval, and the +current is. +

+
+
leave
+

The command is sent when the current frame timestamp leaves the +specified interval. In other words, the command is sent when the +previous frame timestamp was in the given interval, and the +current is not. +

+
+
expr
+

The command ARG is interpreted as expression and result of +expression is passed as ARG. +

+

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
POS
+

Original position in the file of the frame, or undefined if undefined +for the current frame. Deprecated, do not use. +

+
+
PTS
+

The presentation timestamp in input. +

+
+
N
+

The count of the input frame for video or audio, starting from 0. +

+
+
T
+

The time in seconds of the current frame. +

+
+
TS
+

The start time in seconds of the current command interval. +

+
+
TE
+

The end time in seconds of the current command interval. +

+
+
TI
+

The interpolated time of the current command interval, TI = (T - TS) / (TE - TS). +

+
+
W
+

The video frame width. +

+
+
H
+

The video frame height. +

+
+ +
+
+ +

If FLAGS is not specified, a default value of [enter] is +assumed. +

+

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional list of argument for +the given COMMAND. +

+

Between one interval specification and another, whitespaces, or +sequences of characters starting with # until the end of line, +are ignored and can be used to annotate comments. +

+

A simplified BNF description of the commands specification syntax +follows: +

+
COMMAND_FLAG  ::= "enter" | "leave"
+COMMAND_FLAGS ::= COMMAND_FLAG [(+|"|")COMMAND_FLAG]
+COMMAND       ::= ["[" COMMAND_FLAGS "]"] TARGET COMMAND [ARG]
+COMMANDS      ::= COMMAND [,COMMANDS]
+INTERVAL      ::= START[-END] COMMANDS
+INTERVALS     ::= INTERVAL[;INTERVALS]
+
+ + +

41.18.2 Examples

+ +
    +
  • Specify audio tempo change at second 4: +
    +
    asendcmd=c='4.0 atempo tempo 1.5',atempo
    +
    + +
  • Target a specific filter instance: +
    +
    asendcmd=c='4.0 atempo@my tempo 1.5',atempo@my
    +
    + +
  • Specify a list of drawtext and hue commands in a file. +
    +
    # show text in the interval 5-10
    +5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
    +         [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
    +
    +# desaturate the image in the interval 15-20
    +15.0-20.0 [enter] hue s 0,
    +          [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
    +          [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(25-t)
    +
    + +

    A filtergraph allowing to read and process the above command list +stored in a file test.cmd, can be specified with: +

    +
    sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
    +
    +
+ + +

41.19 setpts, asetpts

+ +

Change the PTS (presentation timestamp) of the input frames. +

+

setpts works on video frames, asetpts on audio frames. +

+

This filter accepts the following options: +

+
+
expr
+

The expression which is evaluated for each frame to construct its timestamp. +

+
+
strip_fps (video only)
+

Boolean option which determines if the original framerate and frame duration +metadata is unset. If set to true, be advised that a sane frame rate should be +explicitly specified if output is sent to a constant frame rate muxer. +Default is false. +

+
+
+ +

The expression is evaluated through the eval API and can contain the following +constants: +

+
+
FRAME_RATE, FR
+

frame rate, only defined for constant frame-rate video +

+
+
PTS
+

The presentation timestamp in input +

+
+
N
+

The count of the input frame for video or the number of consumed samples, +not including the current frame for audio, starting from 0. +

+
+
NB_CONSUMED_SAMPLES
+

The number of consumed samples, not including the current frame (only +audio) +

+
+
NB_SAMPLES, S
+

The number of samples in the current frame (only audio) +

+
+
SAMPLE_RATE, SR
+

The audio sample rate. +

+
+
STARTPTS
+

The PTS of the first frame. +

+
+
STARTT
+

the time in seconds of the first frame +

+
+
INTERLACED
+

State whether the current frame is interlaced. +

+
+
T
+

the time in seconds of the current frame +

+
+
POS
+

original position in the file of the frame, or undefined if undefined +for the current frame; deprecated, do not use +

+
+
PREV_INPTS
+

The previous input PTS. +

+
+
PREV_INT
+

previous input time in seconds +

+
+
PREV_OUTPTS
+

The previous output PTS. +

+
+
PREV_OUTT
+

previous output time in seconds +

+
+
RTCTIME
+

The wallclock (RTC) time in microseconds. This is deprecated, use time(0) +instead. +

+
+
RTCSTART
+

The wallclock (RTC) time at the start of the movie in microseconds. +

+
+
TB
+

The timebase of the input timestamps. +

+
+
T_CHANGE
+

Time of the first frame after command was applied or time of the first frame if no commands. +

+
+
+ + +

41.19.1 Examples

+ +
    +
  • Start counting PTS from zero +
    +
    setpts=PTS-STARTPTS
    +
    + +
  • Apply fast motion effect: +
    +
    setpts=0.5*PTS
    +
    + +
  • Apply slow motion effect: +
    +
    setpts=2.0*PTS
    +
    + +
  • Set fixed rate of 25 frames per second: +
    +
    setpts=N/(25*TB)
    +
    + +
  • Apply a random jitter effect of +/-100 TB units: +
    +
    setpts=PTS+randomi(0, -100\,100)
    +
    + +
  • Set fixed rate 25 fps with some jitter: +
    +
    setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
    +
    + +
  • Apply an offset of 10 seconds to the input PTS: +
    +
    setpts=PTS+10/TB
    +
    + +
  • Generate timestamps from a "live source" and rebase onto the current timebase: +
    +
    setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
    +
    + +
  • Generate timestamps by counting samples: +
    +
    asetpts=N/SR/TB
    +
    + +
+ + +

41.19.2 Commands

+ +

Both filters support all above options as commands. +

+ +

41.20 setrange

+ +

Force color range for the output video frame. +

+

The setrange filter marks the color range property for the +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. +

+

The filter accepts the following options: +

+
+
range
+

Available values are: +

+
+
‘auto’
+

Keep the same color range property. +

+
+
‘unspecified, unknown’
+

Set the color range as unspecified. +

+
+
‘limited, tv, mpeg’
+

Set the color range as limited. +

+
+
‘full, pc, jpeg’
+

Set the color range as full. +

+
+
+
+ + +

41.21 settb, asettb

+ +

Set the timebase to use for the output frames timestamps. +It is mainly useful for testing timebase configuration. +

+

It accepts the following parameters: +

+
+
expr, tb
+

The expression which is evaluated into the output timebase. +

+
+
+ +

The value for tb is an arithmetic expression representing a +rational. The expression can contain the constants "AVTB" (the default +timebase), "intb" (the input timebase) and "sr" (the sample rate, +audio only). Default value is "intb". +

+ +

41.21.1 Examples

+ +
    +
  • Set the timebase to 1/25: +
    +
    settb=expr=1/25
    +
    + +
  • Set the timebase to 1/10: +
    +
    settb=expr=0.1
    +
    + +
  • Set the timebase to 1001/1000: +
    +
    settb=1+0.001
    +
    + +
  • Set the timebase to 2*intb: +
    +
    settb=2*intb
    +
    + +
  • Set the default timebase value: +
    +
    settb=AVTB
    +
    +
+ + +

41.22 showcqt

+

Convert input audio to a video output representing frequency spectrum +logarithmically using Brown-Puckette constant Q transform algorithm with +direct frequency domain coefficient calculation (but the transform itself +is not really constant Q, instead the Q factor is actually variable/clamped), +with musical tone scale, from E0 to D#10. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify the video size for the output. It must be even. For the syntax of this option, +check the "Video size" section in the ffmpeg-utils manual. +Default value is 1920x1080. +

+
+
fps, rate, r
+

Set the output frame rate. Default value is 25. +

+
+
bar_h
+

Set the bargraph height. It must be even. Default value is -1 which +computes the bargraph height automatically. +

+
+
axis_h
+

Set the axis height. It must be even. Default value is -1 which computes +the axis height automatically. +

+
+
sono_h
+

Set the sonogram height. It must be even. Default value is -1 which +computes the sonogram height automatically. +

+
+
fullhd
+

Set the fullhd resolution. This option is deprecated, use size, s +instead. Default value is 1. +

+
+
sono_v, volume
+

Specify the sonogram volume expression. It can contain variables: +

+
bar_v
+

the bar_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is 16. +

+
+
bar_v, volume2
+

Specify the bargraph volume expression. It can contain variables: +

+
sono_v
+

the sono_v evaluated expression +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
a_weighting(f)
+

A-weighting of equal loudness +

+
b_weighting(f)
+

B-weighting of equal loudness +

+
c_weighting(f)
+

C-weighting of equal loudness. +

+
+

Default value is sono_v. +

+
+
sono_g, gamma
+

Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, +higher gamma makes the spectrum having more range. Default value is 3. +Acceptable range is [1, 7]. +

+
+
bar_g, gamma2
+

Specify the bargraph gamma. Default value is 1. Acceptable range is +[1, 7]. +

+
+
bar_t
+

Specify the bargraph transparency level. Lower value makes the bargraph sharper. +Default value is 1. Acceptable range is [0, 1]. +

+
+
timeclamp, tc
+

Specify the transform timeclamp. At low frequency, there is trade-off between +accuracy in time domain and frequency domain. If timeclamp is lower, +event in time domain is represented more accurately (such as fast bass drum), +otherwise event in frequency domain is represented more accurately +(such as bass guitar). Acceptable range is [0.002, 1]. Default value is 0.17. +

+
+
attack
+

Set attack time in seconds. The default is 0 (disabled). Otherwise, it +limits future samples by applying asymmetric windowing in time domain, useful +when low latency is required. Accepted range is [0, 1]. +

+
+
basefreq
+

Specify the transform base frequency. Default value is 20.01523126408007475, +which is frequency 50 cents below E0. Acceptable range is [10, 100000]. +

+
+
endfreq
+

Specify the transform end frequency. Default value is 20495.59681441799654, +which is frequency 50 cents above D#10. Acceptable range is [10, 100000]. +

+
+
coeffclamp
+

This option is deprecated and ignored. +

+
+
tlength
+

Specify the transform length in time domain. Use this option to control accuracy +trade-off between time domain and frequency domain at every frequency sample. +It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option. +

+
+

Default value is 384*tc/(384+tc*f). +

+
+
count
+

Specify the transform count for every video frame. Default value is 6. +Acceptable range is [1, 30]. +

+
+
fcount
+

Specify the transform count for every single pixel. Default value is 0, +which makes it computed automatically. Acceptable range is [0, 10]. +

+
+
fontfile
+

Specify font file for use with freetype to draw the axis. If not specified, +use embedded font. Note that drawing with font file or embedded font is not +implemented with custom basefreq and endfreq, use axisfile +option instead. +

+
+
font
+

Specify fontconfig pattern. This has lower priority than fontfile. The +: in the pattern may be replaced by | to avoid unnecessary +escaping. +

+
+
fontcolor
+

Specify font color expression. This is arithmetic expression that should return +integer value 0xRRGGBB. It can contain variables: +

+
frequency, freq, f
+

the frequency where it is evaluated +

+
timeclamp, tc
+

the value of timeclamp option +

+
+

and functions: +

+
midi(f)
+

midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) +

+
r(x), g(x), b(x)
+

red, green, and blue value of intensity x. +

+
+

Default value is st(0, (midi(f)-59.5)/12); +st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); +r(1-ld(1)) + b(ld(1)). +

+
+
axisfile
+

Specify image file to draw the axis. This option override fontfile and +fontcolor option. +

+
+
axis, text
+

Enable/disable drawing text to the axis. If it is set to 0, drawing to +the axis is disabled, ignoring fontfile and axisfile option. +Default value is 1. +

+
+
csp
+

Set colorspace. The accepted values are: +

+
‘unspecified’
+

Unspecified (default) +

+
+
‘bt709’
+

BT.709 +

+
+
‘fcc’
+

FCC +

+
+
‘bt470bg’
+

BT.470BG or BT.601-6 625 +

+
+
‘smpte170m’
+

SMPTE-170M or BT.601-6 525 +

+
+
‘smpte240m’
+

SMPTE-240M +

+
+
‘bt2020ncl’
+

BT.2020 with non-constant luminance +

+
+
+ +
+
cscheme
+

Set spectrogram color scheme. This is list of floating point values with format +left_r|left_g|left_b|right_r|right_g|right_b. +The default is 1|0.5|0|0|0.5|1. +

+
+
+ + +

41.22.1 Examples

+ +
    +
  • Playing audio while showing the spectrum: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with frame rate 30 fps: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
    +
    + +
  • Playing at 1280x720: +
    +
    ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
    +
    + +
  • Disable sonogram display: +
    +
    sono_h=0
    +
    + +
  • A1 and its harmonics: A1, A2, (near)E3, A3: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt [out0]'
    +
    + +
  • Same as above, but with more accuracy in frequency domain: +
    +
    ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
    +                 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
    +
    + +
  • Custom volume: +
    +
    bar_v=10:sono_v=bar_v*a_weighting(f)
    +
    + +
  • Custom gamma, now spectrum is linear to the amplitude. +
    +
    bar_g=2:sono_g=2
    +
    + +
  • Custom tlength equation: +
    +
    tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'
    +
    + +
  • Custom fontcolor and fontfile, C-note is colored green, others are colored blue: +
    +
    fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
    +
    + +
  • Custom font using fontconfig: +
    +
    font='Courier New,Monospace,mono|bold'
    +
    + +
  • Custom frequency range with custom axis using image file: +
    +
    axisfile=myaxis.png:basefreq=40:endfreq=10000
    +
    +
+ + +

41.23 showcwt

+ +

Convert input audio to video output representing frequency spectrum +using Continuous Wavelet Transform and Morlet wavelet. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
rate, r
+

Set the output frame rate. Default value is 25. +

+
+
scale
+

Set the frequency scale used. Allowed values are: +

+
+
linear
+
log
+
bark
+
mel
+
erbs
+
sqrt
+
cbrt
+
qdrt
+
fm
+
+

Default value is linear. +

+
+
iscale
+

Set the intensity scale used. Allowed values are: +

+
+
linear
+
log
+
sqrt
+
cbrt
+
qdrt
+
+

Default value is log. +

+
+
min
+

Set the minimum frequency that will be used in output. +Default is 20 Hz. +

+
+
max
+

Set the maximum frequency that will be used in output. +Default is 20000 Hz. The real frequency upper limit +depends on input audio’s sample rate and such will be enforced +on this value when it is set to value greater than Nyquist frequency. +

+
+
imin
+

Set the minimum intensity that will be used in output. +

+
+
imax
+

Set the maximum intensity that will be used in output. +

+
+
logb
+

Set the logarithmic basis for brightness strength when +mapping calculated magnitude values to pixel values. +Allowed range is from 0 to 1. +Default value is 0.0001. +

+
+
deviation
+

Set the frequency deviation. +Lower values than 1 are more frequency oriented, +while higher values than 1 are more time oriented. +Allowed range is from 0 to 10. +Default value is 1. +

+
+
pps
+

Set the number of pixel output per each second in one row. +Allowed range is from 1 to 1024. +Default value is 64. +

+
+
mode
+

Set the output visual mode. Allowed values are: +

+
+
magnitude
+

Show magnitude. +

+
phase
+

Show only phase. +

+
magphase
+

Show combination of magnitude and phase. +Magnitude is mapped to brightness and phase to color. +

+
channel
+

Show unique color per channel magnitude. +

+
stereo
+

Show unique color per stereo difference. +

+
+ +

Default value is magnitude. +

+
+
slide
+

Set the output slide method. Allowed values are: +

+
+
replace
+
scroll
+
frame
+
+ +
+
direction
+

Set the direction method for output slide method. Allowed values are: +

+
+
lr
+

Direction from left to right. +

+
rl
+

Direction from right to left. +

+
ud
+

Direction from up to down. +

+
du
+

Direction from down to up. +

+
+ +
+
bar
+

Set the ratio of bargraph display to display size. Default is 0. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+ + +

41.24 showfreqs

+ +

Convert input audio to video output representing the audio power spectrum. +Audio amplitude is on Y-axis while frequency is on X-axis. +

+

The filter accepts the following options: +

+
+
size, s
+

Specify size of video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. +Default is 1024x512. +

+
+
rate, r
+

Set video rate. Default is 25. +

+
+
mode
+

Set display mode. +This set how each frequency bin will be represented. +

+

It accepts the following values: +

+
‘line’
+
‘bar’
+
‘dot’
+
+

Default is bar. +

+
+
ascale
+

Set amplitude scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘sqrt’
+

Square root scale. +

+
+
‘cbrt’
+

Cubic root scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+

Default is log. +

+
+
fscale
+

Set frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

Linear scale. +

+
+
‘log’
+

Logarithmic scale. +

+
+
‘rlog’
+

Reverse logarithmic scale. +

+
+

Default is lin. +

+
+
win_size
+

Set window size. Allowed range is from 16 to 65536. +

+

Default is 2048 +

+
+
win_func
+

Set windowing function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default is hanning. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
averaging
+

Set time averaging. Setting this to 0 will display current maximal peaks. +Default is 1, which means time averaging is disabled. +

+
+
colors
+

Specify list of colors separated by space or by ’|’ which will be used to +draw channel frequencies. Unrecognized or missing colors will be replaced +by white color. +

+
+
cmode
+

Set channel display mode. +

+

It accepts the following values: +

+
‘combined’
+
‘separate’
+
+

Default is combined. +

+
+
minamp
+

Set minimum amplitude used in log amplitude scaler. +

+
+
data
+

Set data display mode. +

+

It accepts the following values: +

+
‘magnitude’
+
‘phase’
+
‘delay’
+
+

Default is magnitude. +

+
+
channels
+

Set channels to use when processing audio. By default all are processed. +

+
+ + +

41.25 showspatial

+ +

Convert stereo input audio to a video output, representing the spatial relationship +between two channels. +

+

The filter accepts the following options: +

+
+
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 512x512. +

+
+
win_size
+

Set window size. Allowed range is from 1024 to 65536. Default size is 4096. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
rate, r
+

Set output framerate. +

+
+ + +

41.26 showspectrum

+ +

Convert input audio to a video output, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 640x512. +

+
+
slide
+

Specify how the spectrum should slide along the window. +

+

It accepts the following values: +

+
‘replace’
+

the samples start again on the left when they reach the right +

+
‘scroll’
+

the samples scroll from right to left +

+
‘fullframe’
+

frames are only produced when the samples reach the right +

+
‘rscroll’
+

the samples scroll from left to right +

+
‘lreplace’
+

the samples start again on the right when they reach the left +

+
+ +

Default value is replace. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+ +

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+ +

Default value is ‘channel’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+ +

Default value is ‘sqrt’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+ +

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
overlap
+

Set ratio of overlap window. Default value is 0. +When value is 1 overlap is set to recommended size for specific +window function currently used. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
data
+

Set which data to display. Can be magnitude, default or phase, +or unwrapped phase: uphase. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
fps
+

Set upper frame rate limit. Default is auto, unlimited. +

+
+
legend
+

Draw time and frequency axes and legends. Default is disabled. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ +

The usage is very similar to the showwaves filter; see the examples in that +section. +

+ +

41.26.1 Examples

+ +
    +
  • Large window with logarithmic color scaling: +
    +
    showspectrum=s=1280x480:scale=log
    +
    + +
  • Complete example for a colored and sliding spectrum per channel using ffplay: +
    +
    ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
    +             [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
    +
    +
+ + +

41.27 showspectrumpic

+ +

Convert input audio to a single video frame, representing the audio frequency +spectrum. +

+

The filter accepts the following options: +

+
+
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 4096x2048. +

+
+
mode
+

Specify display mode. +

+

It accepts the following values: +

+
‘combined’
+

all channels are displayed in the same row +

+
‘separate’
+

all channels are displayed in separate rows +

+
+

Default value is ‘combined’. +

+
+
color
+

Specify display color mode. +

+

It accepts the following values: +

+
‘channel’
+

each channel is displayed in a separate color +

+
‘intensity’
+

each channel is displayed using the same color scheme +

+
‘rainbow’
+

each channel is displayed using the rainbow color scheme +

+
‘moreland’
+

each channel is displayed using the moreland color scheme +

+
‘nebulae’
+

each channel is displayed using the nebulae color scheme +

+
‘fire’
+

each channel is displayed using the fire color scheme +

+
‘fiery’
+

each channel is displayed using the fiery color scheme +

+
‘fruit’
+

each channel is displayed using the fruit color scheme +

+
‘cool’
+

each channel is displayed using the cool color scheme +

+
‘magma’
+

each channel is displayed using the magma color scheme +

+
‘green’
+

each channel is displayed using the green color scheme +

+
‘viridis’
+

each channel is displayed using the viridis color scheme +

+
‘plasma’
+

each channel is displayed using the plasma color scheme +

+
‘cividis’
+

each channel is displayed using the cividis color scheme +

+
‘terrain’
+

each channel is displayed using the terrain color scheme +

+
+

Default value is ‘intensity’. +

+
+
scale
+

Specify scale used for calculating intensity color values. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘sqrt’
+

square root, default +

+
‘cbrt’
+

cubic root +

+
‘log’
+

logarithmic +

+
‘4thrt’
+

4th root +

+
‘5thrt’
+

5th root +

+
+

Default value is ‘log’. +

+
+
fscale
+

Specify frequency scale. +

+

It accepts the following values: +

+
‘lin’
+

linear +

+
‘log’
+

logarithmic +

+
+ +

Default value is ‘lin’. +

+
+
saturation
+

Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. 0 is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is 1. +

+
+
win_func
+

Set window function. +

+

It accepts the following values: +

+
‘rect’
+
‘bartlett’
+
‘hann’
+
‘hanning’
+
‘hamming’
+
‘blackman’
+
‘welch’
+
‘flattop’
+
‘bharris’
+
‘bnuttall’
+
‘bhann’
+
‘sine’
+
‘nuttall’
+
‘lanczos’
+
‘gauss’
+
‘tukey’
+
‘dolph’
+
‘cauchy’
+
‘parzen’
+
‘poisson’
+
‘bohman’
+
‘kaiser’
+
+

Default value is hann. +

+
+
orientation
+

Set orientation of time vs frequency axis. Can be vertical or +horizontal. Default is vertical. +

+
+
gain
+

Set scale gain for calculating intensity color values. +Default value is 1. +

+
+
legend
+

Draw time and frequency axes and legends. Default is enabled. +

+
+
rotation
+

Set color rotation, must be in [-1.0, 1.0] range. +Default value is 0. +

+
+
start
+

Set start frequency from which to display spectrogram. Default is 0. +

+
+
stop
+

Set stop frequency to which to display spectrogram. Default is 0. +

+
+
drange
+

Set dynamic range used to calculate intensity color values. Default is 120 dBFS. +Allowed range is from 10 to 200. +

+
+
limit
+

Set upper limit of input audio samples volume in dBFS. Default is 0 dBFS. +Allowed range is from -100 to 100. +

+
+
opacity
+

Set opacity strength when using pixel format output with alpha component. +

+
+ + +

41.27.1 Examples

+ +
    +
  • Extract an audio spectrogram of a whole audio track +in a 1024x1024 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
    +
    +
+ + +

41.28 showvolume

+ +

Convert input audio volume to a video output. +

+

The filter accepts the following options: +

+
+
rate, r
+

Set video rate. +

+
+
b
+

Set border width, allowed range is [0, 5]. Default is 1. +

+
+
w
+

Set channel width, allowed range is [80, 8192]. Default is 400. +

+
+
h
+

Set channel height, allowed range is [1, 900]. Default is 20. +

+
+
f
+

Set fade, allowed range is [0, 1]. Default is 0.95. +

+
+
c
+

Set volume color expression. +

+

The expression can use the following variables: +

+
+
VOLUME
+

Current max volume of channel in dB. +

+
+
PEAK
+

Current peak. +

+
+
CHANNEL
+

Current channel number, starting from 0. +

+
+ +
+
t
+

If set, displays channel names. Default is enabled. +

+
+
v
+

If set, displays volume values. Default is enabled. +

+
+
o
+

Set orientation, can be horizontal: h or vertical: v, +default is h. +

+
+
s
+

Set step size, allowed range is [0, 5]. Default is 0, which means +step is disabled. +

+
+
p
+

Set background opacity, allowed range is [0, 1]. Default is 0. +

+
+
m
+

Set metering mode, can be peak: p or rms: r, +default is p. +

+
+
ds
+

Set display scale, can be linear: lin or log: log, +default is lin. +

+
+
dm
+

In second. +If set to > 0., display a line for the max level +in the previous seconds. +default is disabled: 0. +

+
+
dmc
+

The color of the max line. Use when dm option is set to > 0. +default is: orange +

+
+ + +

41.29 showwaves

+ +

Convert input audio to a video output, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
mode
+

Set display mode. +

+

Available values are: +

+
‘point’
+

Draw a point for each sample. +

+
+
‘line’
+

Draw a vertical line for each sample. +

+
+
‘p2p’
+

Draw a point for each sample and a line between them. +

+
+
‘cline’
+

Draw a centered vertical line for each sample. +

+
+ +

Default value is point. +

+
+
n
+

Set the number of samples which are printed on the same column. A +larger value will decrease the frame rate. Must be a positive +integer. This option can be set only if the value for rate +is not explicitly specified. +

+
+
rate, r
+

Set the (approximate) output frame rate. This is done by setting the +option n. Default value is "25". +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. This is mostly useful to set for high n. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+ + +

41.29.1 Examples

+ +
    +
  • Output the input file audio and the corresponding video representation +at the same time: +
    +
    amovie=a.mp3,asplit[out0],showwaves[out1]
    +
    + +
  • Create a synthetic signal and show it with showwaves, forcing a +frame rate of 30 frames per second: +
    +
    aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
    +
    +
+ + +

41.30 showwavespic

+ +

Convert input audio to a single video frame, representing the samples waves. +

+

The filter accepts the following options: +

+
+
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. +

+
+
split_channels
+

Set if channels should be drawn separately or overlap. Default value is 0. +

+
+
colors
+

Set colors separated by ’|’ which are going to be used for drawing of each channel. +

+
+
scale
+

Set amplitude scale. +

+

Available values are: +

+
‘lin’
+

Linear. +

+
+
‘log’
+

Logarithmic. +

+
+
‘sqrt’
+

Square root. +

+
+
‘cbrt’
+

Cubic root. +

+
+ +

Default is linear. +

+
+
draw
+

Set the draw mode. +

+

Available values are: +

+
‘scale’
+

Scale pixel values for each drawn sample. +

+
+
‘full’
+

Draw every sample directly. +

+
+ +

Default value is scale. +

+
+
filter
+

Set the filter mode. +

+

Available values are: +

+
‘average’
+

Use average samples values for each drawn sample. +

+
+
‘peak’
+

Use peak samples values for each drawn sample. +

+
+ +

Default value is average. +

+
+ + +

41.30.1 Examples

+ +
    +
  • Extract a channel split representation of the wave form of a whole audio track +in a 1024x800 picture using ffmpeg: +
    +
    ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
    +
    +
+ + +

41.31 sidedata, asidedata

+ +

Delete frame side data, or select frames based on it. +

+

This filter accepts the following options: +

+
+
mode
+

Set mode of operation of the filter. +

+

Can be one of the following: +

+
+
‘select’
+

Select every frame with side data of type. +

+
+
‘delete’
+

Delete side data of type. If type is not set, delete all side +data in the frame. +

+
+
+ +
+
type
+

Set side data type used with all modes. Must be set for select mode. +

+

Possible values are: +

+
+
‘PANSCAN’
+
‘A53_CC’
+
‘STEREO3D’
+
‘MATRIXENCODING’
+
‘DOWNMIX_INFO’
+
‘REPLAYGAIN’
+
‘DISPLAYMATRIX’
+
‘AFD’
+
‘MOTION_VECTORS’
+
‘SKIP_SAMPLES’
+
‘AUDIO_SERVICE_TYPE’
+
‘MASTERING_DISPLAY_METADATA’
+
‘GOP_TIMECODE’
+
‘SPHERICAL’
+
‘CONTENT_LIGHT_LEVEL’
+
‘ICC_PROFILE’
+
‘S12M_TIMECODE’
+
‘DYNAMIC_HDR_PLUS’
+
‘REGIONS_OF_INTEREST’
+
‘VIDEO_ENC_PARAMS’
+
‘SEI_UNREGISTERED’
+
‘FILM_GRAIN_PARAMS’
+
‘DETECTION_BOUNDING_BOXES’
+
‘DETECTION_BBOXES’
+
‘DOVI_RPU_BUFFER’
+
‘DOVI_METADATA’
+
‘DYNAMIC_HDR_VIVID’
+
‘AMBIENT_VIEWING_ENVIRONMENT’
+
‘VIDEO_HINT’
+
+ +
+
+ + +

41.32 spectrumsynth

+ +

Synthesize audio from 2 input video spectrums, first input stream represents +magnitude across time and second represents phase across time. +The filter will transform from frequency domain as displayed in videos back +to time domain as presented in audio output. +

+

This filter is primarily created for reversing processed showspectrum +filter outputs, but can synthesize sound from other spectrograms too. +But in such case results are going to be poor if the phase data is not +available, because in such cases phase data need to be recreated, usually +it’s just recreated from random noise. +For best results use gray only output (channel color mode in +showspectrum filter) and log scale for magnitude video and +lin scale for phase video. To produce phase, for 2nd video, use +data option. Inputs videos should generally use fullframe +slide mode as that saves resources needed for decoding video. +

+

The filter accepts the following options: +

+
+
sample_rate
+

Specify sample rate of output audio, the sample rate of audio from which +spectrum was generated may differ. +

+
+
channels
+

Set number of channels represented in input video spectrums. +

+
+
scale
+

Set scale which was used when generating magnitude input spectrum. +Can be lin or log. Default is log. +

+
+
slide
+

Set slide which was used when generating inputs spectrums. +Can be replace, scroll, fullframe or rscroll. +Default is fullframe. +

+
+
win_func
+

Set window function used for resynthesis. +

+
+
overlap
+

Set window overlap. In range [0, 1]. Default is 1, +which means optimal overlap for selected window function will be picked. +

+
+
orientation
+

Set orientation of input videos. Can be vertical or horizontal. +Default is vertical. +

+
+ + +

41.32.1 Examples

+ +
    +
  • First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, +then resynthesize videos back to audio with spectrumsynth: +
    +
    ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
    +ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
    +ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
    +
    +
+ + +

41.33 split, asplit

+ +

Split input into several identical outputs. +

+

asplit works with audio input, split with video. +

+

The filter accepts a single parameter which specifies the number of outputs. If +unspecified, it defaults to 2. +

+ +

41.33.1 Examples

+ +
    +
  • Create two separate outputs from the same input: +
    +
    [in] split [out0][out1]
    +
    + +
  • To create 3 or more outputs, you need to specify the number of +outputs, like in: +
    +
    [in] asplit=3 [out0][out1][out2]
    +
    + +
  • Create two separate outputs from the same input, one cropped and +one padded: +
    +
    [in] split [splitout1][splitout2];
    +[splitout1] crop=100:100:0:0    [cropout];
    +[splitout2] pad=200:200:100:100 [padout];
    +
    + +
  • Create 5 copies of the input audio with ffmpeg: +
    +
    ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
    +
    +
+ + +

41.34 zmq, azmq

+ +

Receive commands sent through a libzmq client, and forward them to +filters in the filtergraph. +

+

zmq and azmq work as a pass-through filters. zmq +must be inserted between two video filters, azmq between two +audio filters. Both are capable to send messages to any filter type. +

+

To enable these filters you need to install the libzmq library and +headers and configure FFmpeg with --enable-libzmq. +

+

For more information about libzmq see: +http://www.zeromq.org/ +

+

The zmq and azmq filters work as a libzmq server, which +receives messages sent through a network interface defined by the +bind_address (or the abbreviation "b") option. +Default value of this option is tcp://localhost:5555. You may +want to alter this value to your needs, but do not forget to escape any +’:’ signs (see filtergraph escaping). +

+

The received message must be in the form: +

+
TARGET COMMAND [ARG]
+
+ +

TARGET specifies the target of the command, usually the name of +the filter class or a specific filter instance name. The default +filter instance name uses the pattern ‘Parsed_<filter_name>_<index>’, +but you can override this by using the ‘filter_name@id’ syntax +(see Filtergraph syntax). +

+

COMMAND specifies the name of the command for the target filter. +

+

ARG is optional and specifies the optional argument list for the +given 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: +

+
ERROR_CODE ERROR_REASON
+MESSAGE
+
+ +

MESSAGE is optional. +

+ +

41.34.1 Examples

+ +

Look at 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 ffplay. +In this example the last overlay filter has an instance name. All other +filters will have default instance names. +

+
+
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@my=x=100 "
+
+ +

To change the color of the left side of the video, the following +command can be used: +

+
echo Parsed_color_0 c yellow | tools/zmqsend
+
+ +

To change the right side: +

+
echo Parsed_color_1 c pink | tools/zmqsend
+
+ +

To change the position of the right side: +

+
echo overlay@my x 150 | tools/zmqsend
+
+ + + + +

42 Multimedia Sources

+ +

Below is a description of the currently available multimedia sources. +

+ +

42.1 amovie

+ +

This is the same as movie source, except it selects an audio +stream by default. +

+ +

42.2 avsynctest

+

Generate an Audio/Video Sync Test. +

+

Generated stream periodically shows flash video frame and emits beep in audio. +Useful to inspect A/V sync issues. +

+

It accepts the following options: +

+
+
size, s
+

Set output video size. Default value is hd720. +

+
+
framerate, fr
+

Set output video frame rate. Default value is 30. +

+
+
samplerate, sr
+

Set output audio sample rate. Default value is 44100. +

+
+
amplitude, a
+

Set output audio beep amplitude. Default value is 0.7. +

+
+
period, p
+

Set output audio beep period in seconds. Default value is 3. +

+
+
delay, dl
+

Set output video flash delay in number of frames. Default value is 0. +

+
+
cycle, c
+

Enable cycling of video delays, by default is disabled. +

+
+
duration, d
+

Set stream output duration. By default duration is unlimited. +

+
+
fg, bg, ag
+

Set foreground/background/additional color. +

+
+ + +

42.2.1 Commands

+ +

This source supports the some above options as commands. +

+ +

42.3 movie

+ +

Read audio and/or video stream(s) from a movie container. +

+

It accepts the following parameters: +

+
+
filename
+

The name of the resource to read (not necessarily a file; it can also be a +device or a stream accessed through some protocol). +

+
+
format_name, f
+

Specifies the format assumed for the movie to read, and can be either +the name of a container or an input device. If not specified, the +format is guessed from movie_name or by probing. +

+
+
seek_point, sp
+

Specifies the seek point in seconds. The frames will be output +starting from this seek point. The parameter is evaluated with +av_strtod, so the numerical value may be suffixed by an IS +postfix. The default value is "0". +

+
+
streams, s
+

Specifies the streams to read. Several streams can be specified, +separated by "+". The source will then have as many outputs, in the +same order. The syntax is explained in the "Stream specifiers" +section in the ffmpeg manual. Two special names, "dv" and "da" specify +respectively the default (best suited) video and audio stream. Default +is "dv", or "da" if the filter is called as "amovie". +

+
+
stream_index, si
+

Specifies the index of the video stream to read. If the value is -1, +the most suitable video stream will be automatically selected. The default +value is "-1". Deprecated. If the filter is called "amovie", it will select +audio instead of video. +

+
+
loop
+

Specifies how many times to read the stream in sequence. +If the value is 0, the stream will be looped infinitely. +Default value is "1". +

+

Note that when the movie is looped the source timestamps are not +changed, so it will generate non monotonically increasing timestamps. +

+
+
discontinuity
+

Specifies the time difference between frames above which the point is +considered a timestamp discontinuity which is removed by adjusting the later +timestamps. +

+
+
dec_threads
+

Specifies the number of threads for decoding +

+
+
format_opts
+

Specify format options for the opened file. Format options can be specified +as a list of key=value pairs separated by ’:’. The following example +shows how to add protocol_whitelist and protocol_blacklist options: +

+
ffplay -f lavfi
+"movie=filename='1.sdp':format_opts='protocol_whitelist=file,rtp,udp\:protocol_blacklist=http'"
+
+
+
+ +

It allows overlaying a second video on top of the main input of +a filtergraph, as shown in this graph: +

+
input -----------> deltapts0 --> overlay --> output
+                                    ^
+                                    |
+movie --> scale--> deltapts1 -------+
+
+ +

42.3.1 Examples

+ +
    +
  • Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it +on top of the input labelled "in": +
    +
    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]
    +
    + +
  • Read from a video4linux2 device, and overlay it on top of the input +labelled "in": +
    +
    movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
    +[in] setpts=PTS-STARTPTS [main];
    +[main][over] overlay=16:16 [out]
    +
    + +
  • Read the first video stream and the audio stream with id 0x81 from +dvd.vob; the video is connected to the pad named "video" and the audio is +connected to the pad named "audio": +
    +
    movie=dvd.vob:s=v:0+#0x81 [video] [audio]
    +
    +
+ + +

42.3.2 Commands

+ +

Both movie and amovie support the following commands: +

+
seek
+

Perform seek using "av_seek_frame". +The syntax is: seek stream_index|timestamp|flags +

    +
  • stream_index: If stream_index is -1, a default +stream is selected, and timestamp is automatically converted +from AV_TIME_BASE units to the stream specific time_base. +
  • timestamp: Timestamp in AVStream.time_base units +or, if no stream is specified, in AV_TIME_BASE units. +
  • flags: Flags which select direction and seeking mode. +
+ +
+
get_duration
+

Get movie duration in AV_TIME_BASE units. +

+
+
+ + +

43 External libraries

+ +

FFmpeg can be hooked up with a number of external libraries to add support +for more formats. None of them are used by default, their use has to be +explicitly requested by passing the appropriate flags to +./configure. +

+ +

43.1 Alliance for Open Media (AOM)

+ +

FFmpeg can make use of the AOM library for AV1 decoding and encoding. +

+

Go to http://aomedia.org/ and follow the instructions for +installing the library. Then pass --enable-libaom to configure to +enable it. +

+ +

43.2 AMD AMF/VCE

+ +

FFmpeg can use the AMD Advanced Media Framework library +for accelerated H.264 and HEVC(only windows) encoding on hardware with Video Coding Engine (VCE). +

+

To enable support you must obtain the AMF framework header files(version 1.4.9+) from +https://github.com/GPUOpen-LibrariesAndSDKs/AMF.git. +

+

Create an AMF/ directory in the system include path. +Copy the contents of AMF/amf/public/include/ into that directory. +Then configure FFmpeg with --enable-amf. +

+

Initialization of amf encoder occurs in this order: +1) trying to initialize through dx11(only windows) +2) trying to initialize through dx9(only windows) +3) trying to initialize through vulkan +

+

To use h.264(AMD VCE) encoder on linux amdgru-pro version 19.20+ and amf-amdgpu-pro +package(amdgru-pro contains, but does not install automatically) are required. +

+

This driver can be installed using amdgpu-pro-install script in official amd driver archive. +

+ +

43.3 AviSynth

+ +

FFmpeg can read AviSynth scripts as input. To enable support, pass +--enable-avisynth to configure after installing the headers +provided by AviSynth+. +AviSynth+ can be configured to install only the headers by either +passing -DHEADERS_ONLY:bool=on to the normal CMake-based build +system, or by using the supplied GNUmakefile. +

+

For Windows, supported AviSynth variants are +AviSynth 2.6 RC1 or higher for 32-bit builds and +AviSynth+ r1718 or higher for 32-bit and 64-bit builds. +

+

For Linux, macOS, and BSD, the only supported AviSynth variant is +AviSynth+, starting with version 3.5. +

+
+

In 2016, AviSynth+ added support for building with GCC. However, due to +the eccentricities of Windows’ calling conventions, 32-bit GCC builds +of AviSynth+ are not compatible with typical 32-bit builds of FFmpeg. +

+

By default, FFmpeg assumes compatibility with 32-bit MSVC builds of +AviSynth+ since that is the most widely-used and entrenched build +configuration. Users can override this and enable support for 32-bit +GCC builds of AviSynth+ by passing -DAVSC_WIN32_GCC32 to +--extra-cflags when configuring FFmpeg. +

+

64-bit builds of FFmpeg are not affected, and can use either MSVC or +GCC builds of AviSynth+ without any special flags. +

+
+

AviSynth(+) is loaded dynamically. Distributors can build FFmpeg +with --enable-avisynth, and the binaries will work regardless +of the end user having AviSynth installed. If/when an end user +would like to use AviSynth scripts, then they can install AviSynth(+) +and FFmpeg will be able to find and use it to open scripts. +

+ +

43.4 Chromaprint

+ +

FFmpeg can make use of the Chromaprint library for generating audio fingerprints. +Pass --enable-chromaprint to configure to +enable it. See https://acoustid.org/chromaprint. +

+ +

43.5 codec2

+ +

FFmpeg can make use of the codec2 library for codec2 decoding and encoding. +There is currently no native decoder, so libcodec2 must be used for decoding. +

+

Go to http://freedv.org/, download "Codec 2 source archive". +Build and install using CMake. Debian users can install the libcodec2-dev package instead. +Once libcodec2 is installed you can pass --enable-libcodec2 to configure to enable it. +

+

The easiest way to use codec2 is with .c2 files, since they contain the mode information required for decoding. +To encode such a file, use a .c2 file extension and give the libcodec2 encoder the -mode option: +ffmpeg -i input.wav -mode 700C output.c2. +Playback is as simple as ffplay output.c2. +For a list of supported modes, run ffmpeg -h encoder=libcodec2. +Raw codec2 files are also supported. +To make sense of them the mode in use needs to be specified as a format option: +ffmpeg -f codec2raw -mode 1300 -i input.raw output.wav. +

+ +

43.6 dav1d

+ +

FFmpeg can make use of the dav1d library for AV1 video decoding. +

+

Go to https://code.videolan.org/videolan/dav1d and follow the instructions for +installing the library. Then pass --enable-libdav1d to configure to enable it. +

+ +

43.7 davs2

+ +

FFmpeg can make use of the davs2 library for AVS2-P2/IEEE1857.4 video decoding. +

+

Go to https://github.com/pkuvcl/davs2 and follow the instructions for +installing the library. Then pass --enable-libdavs2 to configure to +enable it. +

+
+

libdavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

43.8 uavs3d

+ +

FFmpeg can make use of the uavs3d library for AVS3-P2/IEEE1857.10 video decoding. +

+

Go to https://github.com/uavs3/uavs3d and follow the instructions for +installing the library. Then pass --enable-libuavs3d to configure to +enable it. +

+ +

43.9 Game Music Emu

+ +

FFmpeg can make use of the Game Music Emu library to read audio from supported video game +music file formats. Pass --enable-libgme to configure to +enable it. See https://bitbucket.org/mpyne/game-music-emu/overview. +

+ +

43.10 Intel QuickSync Video

+ +

FFmpeg can use Intel QuickSync Video (QSV) for accelerated decoding and encoding +of multiple codecs. To use QSV, FFmpeg must be linked against the libmfx +dispatcher, which loads the actual decoding libraries. +

+

The dispatcher is open source and can be downloaded from +https://github.com/lu-zero/mfx_dispatch.git. FFmpeg needs to be configured +with the --enable-libmfx option and pkg-config needs to be able to +locate the dispatcher’s .pc files. +

+ +

43.11 Kvazaar

+ +

FFmpeg can make use of the Kvazaar library for HEVC encoding. +

+

Go to https://github.com/ultravideo/kvazaar and follow the +instructions for installing the library. Then pass +--enable-libkvazaar to configure to enable it. +

+ +

43.12 LAME

+ +

FFmpeg can make use of the LAME library for MP3 encoding. +

+

Go to http://lame.sourceforge.net/ and follow the +instructions for installing the library. +Then pass --enable-libmp3lame to configure to enable it. +

+ +

43.13 LCEVCdec

+ +

FFmpeg can make use of the liblcevc_dec library for LCEVC enhancement layer +decoding on supported bitstreams. +

+

Go to https://github.com/v-novaltd/LCEVCdec and follow the instructions +for installing the library. Then pass --enable-liblcevc-dec to configure to +enable it. +

+
+

LCEVCdec is under the BSD-3-Clause-Clear License. +

+ +

43.14 libilbc

+ +

iLBC is a narrowband speech codec that has been made freely available +by Google as part of the WebRTC project. libilbc is a packaging friendly +copy of the iLBC codec. FFmpeg can make use of the libilbc library for +iLBC decoding and encoding. +

+

Go to https://github.com/TimothyGu/libilbc and follow the instructions for +installing the library. Then pass --enable-libilbc to configure to +enable it. +

+ +

43.15 libjxl

+ +

JPEG XL is an image format intended to fully replace legacy JPEG for an extended +period of life. See https://jpegxl.info/ for more information, and see +https://github.com/libjxl/libjxl for the library source. You can pass +--enable-libjxl to configure in order enable the libjxl wrapper. +

+ +

43.16 libvpx

+ +

FFmpeg can make use of the libvpx library for VP8/VP9 decoding and encoding. +

+

Go to http://www.webmproject.org/ and follow the instructions for +installing the library. Then pass --enable-libvpx to configure to +enable it. +

+ +

43.17 ModPlug

+ +

FFmpeg can make use of this library, originating in Modplug-XMMS, to read from MOD-like music files. +See https://github.com/Konstanty/libmodplug. Pass --enable-libmodplug to configure to +enable it. +

+ +

43.18 OpenCORE, VisualOn, and Fraunhofer libraries

+ +

Spun off Google Android sources, OpenCore, VisualOn and Fraunhofer +libraries provide encoders for a number of audio codecs. +

+
+

OpenCORE and VisualOn libraries are under the Apache License 2.0 +(see http://www.apache.org/licenses/LICENSE-2.0 for details), which is +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) by passing --enable-version3 to configure in +order to use it. +

+

The license of the Fraunhofer AAC library is incompatible with the GPL. +Therefore, for GPL builds, you have to pass --enable-nonfree to +configure in order to use it. To the best of our knowledge, it is +compatible with the LGPL. +

+ +

43.18.1 OpenCORE AMR

+ +

FFmpeg can make use of the OpenCORE libraries for AMR-NB +decoding/encoding and AMR-WB decoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the libraries. +Then pass --enable-libopencore-amrnb and/or +--enable-libopencore-amrwb to configure to enable them. +

+ +

43.18.2 VisualOn AMR-WB encoder library

+ +

FFmpeg can make use of the VisualOn AMR-WBenc library for AMR-WB encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libvo-amrwbenc to configure to enable it. +

+ +

43.18.3 Fraunhofer AAC library

+ +

FFmpeg can make use of the Fraunhofer AAC library for AAC decoding & encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libfdk-aac to configure to enable it. +

+ +

43.18.4 Fraunhofer MPEG-H 3D Audio decoder library

+ +

FFmpeg can make use of the Fraunhofer MPEG-H decoder library for MPEG-H 3DA decoding. +

+

Go to https://github.com/Fraunhofer-IIS/mpeghdec and follow the +instructions for installing the library. +Then pass --enable-libmpeghdec --enable-nonfree to configure to enable it. +

+ +

43.18.5 LC3 library

+ +

FFmpeg can make use of the Google LC3 library for LC3 decoding & encoding. +

+

Go to https://github.com/google/liblc3/ and follow the instructions for +installing the library. +Then pass --enable-liblc3 to configure to enable it. +

+ +

43.19 OpenH264

+ +

FFmpeg can make use of the OpenH264 library for H.264 decoding and encoding. +

+

Go to http://www.openh264.org/ and follow the instructions for +installing the library. Then pass --enable-libopenh264 to configure to +enable it. +

+

For decoding, this library is much more limited than the built-in decoder +in libavcodec; currently, this library lacks support for decoding B-frames +and some other main/high profile features. (It currently only supports +constrained baseline profile and CABAC.) Using it is mostly useful for +testing and for taking advantage of Cisco’s patent portfolio license +(http://www.openh264.org/BINARY_LICENSE.txt). +

+ +

43.20 OpenJPEG

+ +

FFmpeg can use the OpenJPEG libraries for decoding/encoding J2K videos. Go to +http://www.openjpeg.org/ to get the libraries and follow the installation +instructions. To enable using OpenJPEG in FFmpeg, pass --enable-libopenjpeg to +./configure. +

+ +

43.21 rav1e

+ +

FFmpeg can make use of rav1e (Rust AV1 Encoder) via its C bindings to encode videos. +Go to https://github.com/xiph/rav1e/ and follow the instructions to build +the C library. To enable using rav1e in FFmpeg, pass --enable-librav1e +to ./configure. +

+ +

43.22 SVT-AV1

+ +

FFmpeg can make use of the Scalable Video Technology for AV1 library for AV1 encoding. +

+

Go to https://gitlab.com/AOMediaCodec/SVT-AV1/ and follow the instructions +for installing the library. Then pass --enable-libsvtav1 to configure to +enable it. +

+ +

43.23 SVT-JPEG-XS

+ +

FFmpeg can make use of the Scalable Video Technology for JPEG-XS library for JPEG-XS +decoding and encoding. +

+

Go to https://github.com/OpenVisualCloud/SVT-JPEG-XS and follow the instructions +for installing the library. Then pass --enable-libsvtjpegxs to configure to +enable it. +

+ +

43.24 TwoLAME

+ +

FFmpeg can make use of the TwoLAME library for MP2 encoding. +

+

Go to http://www.twolame.org/ and follow the +instructions for installing the library. +Then pass --enable-libtwolame to configure to enable it. +

+ +

43.25 VapourSynth

+ +

FFmpeg can read VapourSynth scripts as input. To enable support, pass +--enable-vapoursynth to configure. Vapoursynth is detected via +pkg-config. Versions 42 or greater supported. +See http://www.vapoursynth.com/. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+ +

43.26 x264

+ +

FFmpeg can make use of the x264 library for H.264 encoding. +

+

Go to http://www.videolan.org/developers/x264.html and follow the +instructions for installing the library. Then pass --enable-libx264 to +configure to enable it. +

+
+

x264 is under the GNU Public License Version 2 or later +(see 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. +

+ +

43.27 x265

+ +

FFmpeg can make use of the x265 library for HEVC encoding. +

+

Go to http://x265.org/developers.html and follow the instructions +for installing the library. Then pass --enable-libx265 to configure +to enable it. +

+
+

x265 is under the GNU Public License Version 2 or later +(see 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. +

+ +

43.28 xavs

+ +

FFmpeg can make use of the xavs library for AVS encoding. +

+

Go to http://xavs.sf.net/ and follow the instructions for +installing the library. Then pass --enable-libxavs to configure to +enable it. +

+ +

43.29 xavs2

+ +

FFmpeg can make use of the xavs2 library for AVS2-P2/IEEE1857.4 video encoding. +

+

Go to https://github.com/pkuvcl/xavs2 and follow the instructions for +installing the library. Then pass --enable-libxavs2 to configure to +enable it. +

+
+

libxavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

43.30 eXtra-fast Essential Video Encoder (XEVE)

+ +

FFmpeg can make use of the XEVE library for EVC video encoding. +

+

Go to https://github.com/mpeg5/xeve and follow the instructions for +installing the XEVE library. Then pass --enable-libxeve to configure to +enable it. +

+ +

43.31 eXtra-fast Essential Video Decoder (XEVD)

+ +

FFmpeg can make use of the XEVD library for EVC video decoding. +

+

Go to https://github.com/mpeg5/xevd and follow the instructions for +installing the XEVD library. Then pass --enable-libxevd to configure to +enable it. +

+ +

43.32 ZVBI

+ +

ZVBI is a VBI decoding library which can be used by FFmpeg to decode DVB +teletext pages and DVB teletext subtitles. +

+

Go to http://sourceforge.net/projects/zapping/ and follow the instructions for +installing the library. Then pass --enable-libzvbi to configure to +enable it. +

+ +

44 Supported File Formats, Codecs or Features

+ +

You can use the -formats and -codecs options to have an exhaustive list. +

+ +

44.1 File Formats

+ +

FFmpeg supports the following file formats through the libavformat +library: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
3dostrX
4xmX4X Technologies format, used in some games.
8088flex TMVX
AAXXAudible Enhanced Audio format, used in audiobooks.
AAXAudible Format 2, 3, and 4, used in audiobooks.
ACT VoiceXcontains G.729 audio
Adobe FilmstripXX
Audio IFF (AIFF)XX
American Laser Games MMXMultimedia format used in games like Mad Dog McCree.
3GPP AMRXX
Amazing Studio Packed Animation FileXMultimedia format used in game Heart Of Darkness.
Apple HTTP Live StreamingX
Artworx Data FormatX
Interplay ACMXAudio only format used in some Interplay games.
ADPXAudio format used on the Nintendo Gamecube.
AFCXAudio format used on the Nintendo Gamecube.
ADS/SS2XAudio format used on the PS2.
APNGXX
ASFXXAdvanced / Active Streaming Format.
ASTXXAudio format used on the Nintendo Wii.
AVIXX
AviSynthX
AVRXAudio format used on Mac.
AVSXMultimedia format used by the Creature Shock game.
Beam Software SIFFXAudio and video format used in some games by Beam Software.
Bethesda Softworks VIDXUsed in some games from Bethesda Softworks.
Binary textX
BinkXMultimedia format used by many games.
Bink AudioXAudio only multimedia format used by some games.
Bitmap Brothers JVXUsed in Z and Z95 games.
BRPXArgonaut Games format.
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
BFSTMXAudio format used on the Nintendo WiiU (based on BRSTM).
BRSTMXAudio format used on the Nintendo Wii.
BW64XBroadcast Wave 64bit.
BWFXX
codec2 (raw)XXMust be given -mode format option to decode correctly.
codec2 (.c2 files)XXContains header with version and mode info, simplifying playback.
CRI ADXXXAudio-only format used in console video games.
CRI AIXX
CRI HCAXAudio-only format used in console video games.
Discworld II BMVX
Interplay C93XUsed in the game Cyberia from Interplay.
Delphine Software International CINXMultimedia format used by Delphine Software games.
Digital Speech Standard (DSS)X
CD+GXVideo format used by CD+G karaoke disks
Phantom CineX
Commodore CDXLXAmiga CD video format
Core Audio FormatXXApple Core Audio Format
CRC testing formatX
Creative VoiceXXCreated for the Sound Blaster Pro.
CRYO APCXAudio format used in some games by CRYO Interactive Entertainment.
D-Cinema audioXX
Deluxe Paint AnimationX
DCSTRX
DFAXThis format is used in Chronomaster game
DirectDraw SurfaceX
DSD Stream File (DSF)X
DV videoXX
DXAXThis format is used in the non-Windows version of the Feeble Files + game and different game cutscenes repacked for use with ScummVM.
Electronic Arts cdataX
Electronic Arts MultimediaXUsed in various EA games; files have extensions like WVE and UV2.
Ensoniq Paris Audio FileX
FFM (FFserver live feed)XX
Flash (SWF)XX
Flash 9 (AVM2)XXOnly embedded audio is decoded.
FLI/FLC/FLX animationX.fli/.flc files
Flash Video (FLV)XXMacromedia Flash video files
framecrc testing formatX
FunCom ISSXAudio format used in various games from FunCom like The Longest Journey.
G.723.1XX
G.726XBoth left- and right-justified.
G.729 BITXX
G.729 rawX
GENHXAudio format for various games.
GIF AnimationXX
GXFXXGeneral eXchange Format SMPTE 360M, used by Thomson Grass Valley + playout servers.
HNMXOnly version 4 supported, used in some games from Cryo Interactive
iCEDraw FileX
ICOXXMicrosoft Windows ICO
id Quake II CIN videoX
id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
IEC61937 encapsulationXX
IFFXInterchange File Format
IFVXA format used by some old CCTV DVRs.
iLBCXX
Interplay MVEXFormat used in various Interplay computer games.
Iterated Systems ClearVideoXI-frames only
IV8XA format generated by IndigoVision 8000 video server.
IVF (On2)XXA format used by libvpx
Internet Video RecordingX
IRCAMXX
LAFXLimitless Audio Format
LATMXX
LMLM4XUsed by Linux Media Labs MPEG-4 PCI boards
LOASXcontains LATM multiplexed AAC audio
LRCXX
LVFX
LXFXVR native stream format, used by Leitch/Harris’ video servers.
Magic Lantern Video (MLV)X
MatroskaXX
Matroska audioX
FFmpeg metadataXXMetadata in text format.
MAXIS XAXUsed in Sim City 3000; file extension .xa.
MCAXUsed in some games from Capcom; file extension .mca.
MD StudioX
Metal Gear Solid: The Twin SnakesX
Megalux FrameXUsed by Megalux Ultimate Paint
MobiClip MODSX
MobiClip MOFLEXX
Mobotix .mxgX
Monkey’s AudioX
Motion Pixels MVIX
MOV/QuickTime/MP4XX3GP, 3GP2, PSP, iPod variants supported
MP2XX
MP3XX
MPEG-1 SystemXXmuxed audio and video, VCD format supported
MPEG-PS (program stream)XXalso known as VOB file, SVCD and DVD format supported
MPEG-TS (transport stream)XXalso known as DVB Transport Stream
MPEG-4XXMPEG-4 is a variant of QuickTime.
MSFXAudio format used on the PS3.
Mirillis FIC videoXNo cursor rendering.
MIDI Sample Dump StandardX
MIME multipart JPEGX
MSN TCP webcamXUsed by MSN Messenger webcam streams.
MTVX
MusepackX
Musepack SV8X
Material eXchange Format (MXF)XXSMPTE 377M, used by D-Cinema, broadcast industry.
Material eXchange Format (MXF), D-10 MappingXXSMPTE 386M, D-10/IMX Mapping.
NC camera feedXNC (AVIP NC4600) camera streams
NIST SPeech HEader REsourcesX
Computerized Speech Lab NSPX
NTT TwinVQ (VQF)XNippon Telegraph and Telephone Corporation TwinVQ.
Nullsoft Streaming VideoX
NuppelVideoX
NUTXXNUT Open Container Format
OggXX
Playstation Portable PMPX
Portable Voice FormatX
RK Audio (RKA)X
TechnoTrend PVAXUsed by TechnoTrend DVB PCI boards.
QCPX
raw ADTS (AAC)XX
raw AC-3XX
raw AMR-NBX
raw AMR-WBX
raw APACX
raw APVXX
raw aptXXX
raw aptX HDXX
raw BonkX
raw Chinese AVS videoXX
raw DFPWMXX
raw DiracXX
raw DNxHDXX
raw DTSXX
raw DTS-HDX
raw E-AC-3XX
raw EVCXX
raw FLACXX
raw G.728X
raw GSMX
raw H.261XX
raw H.263XX
raw H.264XX
raw HEVCXX
raw Ingenient MJPEGX
raw MJPEGXX
raw MLPX
raw MPEGX
raw MPEG-1X
raw MPEG-2X
raw MPEG-4XX
raw NULLX
raw videoXX
raw id RoQX
raw OBUXX
raw OSQX
raw SBCXX
raw ShortenX
raw TAKX
raw TrueHDXX
raw VC-1XX
raw PCM A-lawXX
raw PCM mu-lawXX
raw PCM Archimedes VIDCXX
raw PCM signed 8 bitXX
raw PCM signed 16 bit big-endianXX
raw PCM signed 16 bit little-endianXX
raw PCM signed 24 bit big-endianXX
raw PCM signed 24 bit little-endianXX
raw PCM signed 32 bit big-endianXX
raw PCM signed 32 bit little-endianXX
raw PCM signed 64 bit big-endianXX
raw PCM signed 64 bit little-endianXX
raw PCM unsigned 8 bitXX
raw PCM unsigned 16 bit big-endianXX
raw PCM unsigned 16 bit little-endianXX
raw PCM unsigned 24 bit big-endianXX
raw PCM unsigned 24 bit little-endianXX
raw PCM unsigned 32 bit big-endianXX
raw PCM unsigned 32 bit little-endianXX
raw PCM 16.8 floating point little-endianX
raw PCM 24.0 floating point little-endianX
raw PCM floating-point 32 bit big-endianXX
raw PCM floating-point 32 bit little-endianXX
raw PCM floating-point 64 bit big-endianXX
raw PCM floating-point 64 bit little-endianXX
RDTX
REDCODE R3DXFile format used by RED Digital cameras, contains JPEG 2000 frames and PCM audio.
RealMediaXX
RedirectorX
RedSparkX
Renderware TeXture DictionaryX
Resolume DXVXXEncoding is only supported for the DXT1 (Normal Quality, No Alpha) texture format.
RF64X
RL2XAudio and video format used in some games by Entertainment Software Partners.
RPL/ARMovieX
Lego Mindstorms RSOXX
RSDX
RTMPXXOutput is performed by publishing stream to RTMP server
RTPXX
RTSPXX
Sample Dump eXchangeX
SAPXX
SBGX
SDNSX
SDPX
SERX
Digital Pictures SGAX
Sega FILM/CPKXXUsed in many Sega Saturn console games.
Silicon Graphics MovieX
Sierra SOLX.sol files used in Sierra Online games.
Sierra VMDXUsed in Sierra CD-ROM games.
SmackerXMultimedia format used by many games.
SMJPEGXXUsed in certain Loki game ports.
SMPTE 337M encapsulationX
SmushXMultimedia format used in some LucasArts games.
Sony OpenMG (OMA)XXAudio format used in Sony Sonic Stage and Sony Vegas.
Sony PlayStation STRX
Sony Wave64 (W64)XX
SoX native formatXX
SUN AU formatXX
SUP raw PGS subtitlesXX
SVAGXAudio format used in Konami PS2 games.
TDSCX
Text filesX
THPXUsed on the Nintendo GameCube.
Tiertex Limited SEQXTiertex .seq files used in the DOS CD-ROM version of the game Flashback.
True AudioXX
VAGXAudio format used in many Sony PS2 games.
VC-1 test bitstreamXX
Vidvox HapXX
VivoX
VPKXAudio format used in Sony PS games.
Marble WADYX
WAVXX
Waveform ArchiverX
WavPackXX
WebMXX
Windows Televison (WTV)XX
Wing Commander III movieXMultimedia format used in Origin’s Wing Commander III computer game.
Westwood Studios audioXXMultimedia format used in Westwood Studios games.
Westwood Studios VQAXMultimedia format used in Westwood Studios games.
Wideband Single-bit Data (WSD)X
WVEX
Konami XMDX
XMVXMicrosoft video container used in Xbox games.
XVAGXAudio format used on the PS3.
xWMAXMicrosoft audio container used by XAudio 2.
eXtended BINary text (XBIN)X
YUV4MPEG pipeXX
Psygnosis YOPX
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+ +

44.2 Image Formats

+ +

FFmpeg can read and write images for each frame of a video sequence. The +following image formats are supported: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
.Y.U.VXXone raw file per component
Alias PIXXXAlias/Wavefront PIX image format
animated GIFXX
APNGXXAnimated Portable Network Graphics
BMPXXMicrosoft BMP image
BRender PIXXArgonaut BRender 3D engine image format.
CRIXCintel RAW
DPXXXDigital Picture Exchange
EXRXOpenEXR
FITSXXFlexible Image Transport System
HDRXXRadiance HDR RGBE Image format
IMGXGEM Raster image
JPEGXXProgressive JPEG is not supported.
JPEG 2000XX
JPEG-LSXX
JPEG-XSEESupported through external library libsvtjpegxs
LJPEGXLossless JPEG
Media 100X
MSPXMicrosoft Paint image
PAMXXPAM is a PNM extension with alpha support.
PBMXXPortable BitMap image
PCDXPhotoCD
PCXXXPC Paintbrush
PFMXXPortable FloatMap image
PGMXXPortable GrayMap image
PGMYUVXXPGM with U and V components in YUV 4:2:0
PGXXPGX file decoder
PHMXXPortable HalfFloatMap image
PICXPictor/PC Paint
PNGXXPortable Network Graphics image
PPMXXPortable PixelMap image
PSDXPhotoshop
PTXXV.Flash PTX format
QOIXXQuite OK Image format
SGIXXSGI RGB image format
Sun RasterfileXXSun RAS image format
TIFFXXYUV, JPEG and some extension is not supported yet.
Truevision TargaXXTarga (.TGA) image format
VBNXXVizrt Binary Image format
WBMPXXWireless Application Protocol Bitmap image format
WebPEXWebP image format, encoding supported through external library libwebp
XBMXXX BitMap image format
XFaceXXX-Face image format
XPMXX PixMap image format
XWDXXX Window Dump image format
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

44.3 Video Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
4X MovieXUsed in certain computer games.
8088flex TMVX
A64 multicolorXCreates video suitable to be played on a commodore 64 (multicolor mode).
Amazing Studio PAF VideoX
American Laser Games MMXUsed in games like Mad Dog McCree.
Amuse Graphics MovieX
AMV VideoXXUsed in Chinese MP3 players.
ANSI/ASCII artX
Apple Intermediate CodecX
Apple MJPEG-BX
Apple PixletX
Apple ProResXXfourcc: apch,apcn,apcs,apco,ap4h,ap4x
Apple QuickDrawXfourcc: qdrw
APVX
Argonaut VideoXUsed in some Argonaut games.
Asus v1XXfourcc: ASV1
Asus v2XXfourcc: ASV2
ATI VCR1Xfourcc: VCR1
ATI VCR2Xfourcc: VCR2
Auravision AuraX
Auravision Aura 2X
Autodesk Animator Flic videoX
Autodesk RLEXfourcc: AASC
AV1EESupported through external libraries libaom, libdav1d, librav1e and libsvtav1
Avid 1:1 10-bit RGB PackerXXfourcc: AVrp
AVS (Audio Video Standard) videoXVideo encoding used by the Creature Shock game.
AVS2-P2/IEEE1857.4EESupported through external libraries libxavs2 and libdavs2
AVS3-P2/IEEE1857.10ESupported through external library libuavs3d
AYUVXXMicrosoft uncompressed packed 4:4:4:4
Beam Software VBX
Bethesda VID videoXUsed in some games from Bethesda Softworks.
Bink VideoX
BitJazz SheerVideoX
Bitmap Brothers JV videoX
y41p Brooktree uncompressed 4:1:1 12-bitXX
Brooktree ProSumer VideoXfourcc: BT20
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
C93 videoXCodec used in Cyberia game.
CamStudioXfourcc: CSCD
CD+GXVideo codec for CD+G karaoke disks
CDXLXAmiga CD video codec
Chinese AVS videoEXAVS1-P2, JiZhun profile, encoding through external library libxavs
Delphine Software International CIN videoXCodec used in Delphine Software International games.
Discworld II BMV VideoX
CineForm HDXX
Canopus HQX
Canopus HQAX
Canopus HQXX
Canopus Lossless CodecX
CDToonsXCodec used in various Broderbund games.
CinepakX
Cirrus Logic AccuPakXXfourcc: CLJR
CPiA Video FormatX
Creative YUV (CYUV)X
DFAXCodec used in Chronomaster game.
DiracEXsupported though the native vc2 (Dirac Pro) encoder
Deluxe Paint AnimationX
DNxHDXXaka SMPTE VC3
Duck TrueMotion 1.0Xfourcc: DUCK
Duck TrueMotion 2.0Xfourcc: TM20
Duck TrueMotion 2.0 RTXfourcc: TR20
DV (Digital Video)XX
Dxtory capture formatX
Feeble Files/ScummVM DXAXCodec originally used in Feeble Files game.
Electronic Arts CMV videoXUsed in NHL 95 game.
Electronic Arts Madcow videoX
Electronic Arts TGV videoX
Electronic Arts TGQ videoX
Electronic Arts TQI videoX
Escape 124X
Escape 130X
EVC / MPEG-5 Part 1EEencoding and decoding supported through external libraries libxeve and libxevd
FFmpeg video codec #1XXlossless codec (fourcc: FFV1)
Flash Screen Video v1XXfourcc: FSV1
Flash Screen Video v2XX
Flash Video (FLV)XXSorenson H.263 used in Flash
FM Screen Capture CodecX
Forward UncompressedX
FrapsX
Go2MeetingXfourcc: G2M2, G2M3
Go2WebinarXfourcc: G2M4
Gremlin Digital VideoX
H.261XX
H.263 / H.263-1996XX
H.263+ / H.263-1998 / H.263 version 2XX
H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10EXencoding supported through external library libx264 and OpenH264
HEVCXXencoding supported through external library libx265 and libkvazaar
HNM version 4X
HuffYUVXX
HuffYUV FFmpeg variantXX
IBM UltimotionXfourcc: ULTI
id Cinematic videoXUsed in Quake II.
id RoQ videoXXUsed in Quake III, Jedi Knight 2, other computer games.
IFF ILBMXIFF interleaved bitmap
IFF ByteRun1XIFF run length encoded bitmap
Infinity IMM4X
Intel H.263X
Intel Indeo 2X
Intel Indeo 3X
Intel Indeo 4X
Intel Indeo 5X
Interplay C93XUsed in the game Cyberia from Interplay.
Interplay MVE videoXUsed in Interplay .MVE files.
J2KXX
Karl Morton’s video codecXCodec used in Worms games.
Kega Game Video (KGV1)XKega emulator screen capture codec.
LagarithX
LCEVC / MPEG-5 LCEVC / MPEG-5 Part 2Edecoding supported through external library liblcevc-dec
LCL (LossLess Codec Library) MSZHX
LCL (LossLess Codec Library) ZLIBEE
LEAD MCMPX
LOCOX
LucasArts SANM/SmushXUsed in LucasArts games / SMUSH animations.
lossless MJPEGXX
MagicYUV VideoXX
Mandsoft Screen Capture CodecX
Microsoft ATC ScreenXAlso known as Microsoft Screen 3.
Microsoft Expression Encoder ScreenXAlso known as Microsoft Titanium Screen 2.
Microsoft RLEXX
Microsoft Screen 1XAlso known as Windows Media Video V7 Screen.
Microsoft Screen 2XAlso known as Windows Media Video V9 Screen.
Microsoft Video 1X
MimicXUsed in MSN Messenger Webcam streams.
Miro VideoXLXfourcc: VIXL
MJPEG (Motion JPEG)XX
Mobotix MxPEG videoX
Motion Pixels videoX
MPEG-1 videoXX
MPEG-2 videoXX
MPEG-4 part 2XXlibxvidcore can be used alternatively for encoding.
MPEG-4 part 2 Microsoft variant version 1X
MPEG-4 part 2 Microsoft variant version 2XX
MPEG-4 part 2 Microsoft variant version 3XX
Newtek SpeedHQXX
Nintendo Gamecube THP videoX
NotchLCX
NuppelVideo/RTjpegXVideo encoding used in NuppelVideo files.
On2 VP3Xstill experimental
On2 VP4Xfourcc: VP40
On2 VP5Xfourcc: VP50
On2 VP6Xfourcc: VP60,VP61,VP62
On2 VP7Xfourcc: VP70,VP71
VP8EXfourcc: VP80, encoding supported through external library libvpx
VP9EXencoding supported through external library libvpx
Pinnacle TARGA CineWave YUV16Xfourcc: Y216
Q-team QPEGXfourccs: QPEG, Q1.0, Q1.1
QuickTime 8BPS videoX
QuickTime Animation (RLE) videoXXfourcc: ’rle ’
QuickTime Graphics (SMC)XXfourcc: ’smc ’
QuickTime video (RPZA)XXfourcc: rpza
R10K AJA Kona 10-bit RGB CodecXX
R210 Quicktime Uncompressed RGB 10-bitXX
Raw VideoXX
RealVideo 1.0XX
RealVideo 2.0XX
RealVideo 3.0Xstill far from ideal
RealVideo 4.0X
RealVideo 6.0X
Renderware TXD (TeXture Dictionary)XTexture dictionaries used by the Renderware Engine.
RivaTuner VideoXfourcc: ’RTV1’
RL2 videoXused in some games by Entertainment Software Partners
ScreenPressorX
ScreenpressoX
Screen Recorder Gold CodecX
Sierra VMD videoXUsed in Sierra VMD files.
Silicon Graphics Motion Video Compressor 1 (MVC1)X
Silicon Graphics Motion Video Compressor 2 (MVC2)X
Silicon Graphics RLE 8-bit videoX
Smacker videoXVideo encoding used in Smacker.
SMPTE VC-1X
SnowXXexperimental wavelet codec (fourcc: SNOW)
Sony PlayStation MDEC (Motion DECoder)X
Sorenson Vector Quantizer 1XXfourcc: SVQ1
Sorenson Vector Quantizer 3Xfourcc: SVQ3
Sunplus JPEG (SP5X)Xfourcc: SP5X
TechSmith Screen Capture CodecXfourcc: TSCC
TechSmith Screen Capture Codec 2Xfourcc: TSC2
TheoraEXencoding supported through external library libtheora
Tiertex Limited SEQ videoXCodec used in DOS CD-ROM FlashBack game.
Ut VideoXX
v210 QuickTime uncompressed 4:2:2 10-bitXX
v308 QuickTime uncompressed 4:4:4XX
v408 QuickTime uncompressed 4:4:4:4XX
v410 QuickTime uncompressed 4:4:4 10-bitXX
VBLE Lossless CodecX
vMix VideoXfourcc: ’VMX1’
VMware Screen Codec / VMware VideoXCodec used in videos captured by VMware.
Westwood Studios VQA (Vector Quantized Animation) videoX
Windows Media ImageX
Windows Media Video 7XX
Windows Media Video 8XX
Windows Media Video 9Xnot completely working
Wing Commander III / XanXUsed in Wing Commander III .MVE files.
Wing Commander IV / XanXUsed in Wing Commander IV.
Winnov WNV1X
WMV7XX
YAMAHA SMAFXX
Psygnosis YOP VideoX
yuv4XXlibquicktime uncompressed packed 4:2:0
ZeroCodec Lossless VideoX
ZLIBXXpart of LCL, encoder experimental
Zip Motion Blocks VideoXXEncoder works only in PAL8.
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

44.4 Audio Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
8SVX exponentialX
8SVX fibonacciX
AACEXXencoding supported through internal encoder and external library libfdk-aac
AAC+EIXencoding supported through external library libfdk-aac
AC-3IXIX
ACELP.KELVINX
ADPCM 4X MovieX
ADPCM Yamaha AICAX
ADPCM AmuseGraphics MovieX
ADPCM Argonaut GamesXX
ADPCM CDROM XAX
ADPCM Creative TechnologyX16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
ADPCM Electronic ArtsXUsed in various EA titles.
ADPCM Electronic Arts Maxis CDROM XSXUsed in Sim City 3000.
ADPCM Electronic Arts R1X
ADPCM Electronic Arts R2X
ADPCM Electronic Arts R3X
ADPCM Electronic Arts XASX
ADPCM G.722XX
ADPCM G.726XX
ADPCM IMA Acorn ReplayX
ADPCM IMA AMVXXUsed in AMV files
ADPCM IMA Cunning DevelopmentsX
ADPCM IMA Electronic Arts EACSX
ADPCM IMA Electronic Arts SEADX
ADPCM IMA FuncomX
ADPCM IMA High Voltage Software ALPXX
ADPCM IMA Mobiclip MOFLEXX
ADPCM IMA QuickTimeXX
ADPCM IMA Simon & Schuster InteractiveXX
ADPCM IMA Ubisoft APMXX
ADPCM IMA Loki SDL MJPEGX
ADPCM IMA WAVXX
ADPCM IMA WestwoodX
ADPCM ISS IMAXUsed in FunCom games.
ADPCM IMA DialogicX
ADPCM IMA Duck DK3XUsed in some Sega Saturn console games.
ADPCM IMA Duck DK4XUsed in some Sega Saturn console games.
ADPCM IMA RadicalX
ADPCM IMA XboxX
ADPCM MicrosoftXX
ADPCM MS IMAXX
ADPCM Nintendo Gamecube AFCX
ADPCM Nintendo Gamecube DTKX
ADPCM Nintendo THPX
ADPCM PlaystationX
ADPCM QT IMAXX
ADPCM SanyoX
ADPCM SEGA CRI ADXXXUsed in Sega Dreamcast games.
ADPCM Shockwave FlashXX
ADPCM Sound Blaster Pro 2-bitX
ADPCM Sound Blaster Pro 2.6-bitX
ADPCM Sound Blaster Pro 4-bitX
ADPCM VIMAXUsed in LucasArts SMUSH animations.
ADPCM Konami XMDX
ADPCM Westwood Studios IMAXXUsed in Westwood Studios games like Command and Conquer.
ADPCM YamahaXX
ADPCM ZorkX
AMR-NBEXencoding supported through external library libopencore-amrnb
AMR-WBEXencoding supported through external library libvo-amrwbenc
Amazing Studio PAF AudioX
Apple lossless audioXXQuickTime fourcc ’alac’
aptXXXUsed in Bluetooth A2DP
aptX HDXXUsed in Bluetooth A2DP
ATRAC1X
ATRAC3X
ATRAC3+X
ATRAC9X
Bink AudioXUsed in Bink and Smacker files in many games.
Bonk audioX
CELTEdecoding supported through external library libcelt
codec2EEen/decoding supported through external library libcodec2
CRI HCAX
Delphine Software International CIN audioXCodec used in Delphine Software International games.
DFPWMXX
Digital Speech Standard - Standard Play mode (DSS SP)X
Discworld II BMV AudioX
COOKXAll versions except 5.1 are supported.
DCA (DTS Coherent Acoustics)XXsupported extensions: XCh, XXCH, X96, XBR, XLL, LBR (partially)
Dolby EX
DPCM Cuberoot-Delta-ExactXUsed in few games.
DPCM GremlinX
DPCM id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
DPCM Marble WADYX
DPCM InterplayXUsed in various Interplay computer games.
DPCM Squareroot-Delta-ExactXUsed in various games.
DPCM Sierra OnlineXUsed in Sierra Online game audio files.
DPCM SolX
DPCM XanXUsed in Origin’s Wing Commander IV AVI files.
DPCM Xilam DERFX
DSD (Direct Stream Digital), least significant bit firstX
DSD (Direct Stream Digital), most significant bit firstX
DSD (Direct Stream Digital), least significant bit first, planarX
DSD (Direct Stream Digital), most significant bit first, planarX
DSP Group TrueSpeechX
DST (Direct Stream Transfer)X
DV audioX
Enhanced AC-3XX
EVRC (Enhanced Variable Rate Codec)X
FLAC (Free Lossless Audio Codec)XIX
FTR VoiceX
G.723.1XX
G.728X
G.729X
GSMEXencoding supported through external library libgsm
GSM Microsoft variantEXencoding supported through external library libgsm
IAC (Indeo Audio Coder)X
iLBC (Internet Low Bitrate Codec)EEXencoding and decoding supported through external library libilbc
IMC (Intel Music Coder)X
Interplay ACMX
LC3EEsupported through external library liblc3
MACE (Macintosh Audio Compression/Expansion) 6:1X
Marian’s A-pac audioX
MI-SC4 (Micronas SC-4 Audio)X
MLP (Meridian Lossless Packing)XXUsed in DVD-Audio discs.
Monkey’s AudioX
MP1 (MPEG audio layer 1)IX
MP2 (MPEG audio layer 2)IXIXencoding supported also through external library TwoLAME
MP3 (MPEG audio layer 3)EIXencoding supported through external library LAME, ADU MP3 and MP3onMP4 also supported
MPEG-4 Audio Lossless Coding (ALS)X
MPEG-H 3D AudioEdecoding supported through external library libmpeghdec
MobiClip FastAudioX
Musepack SV7X
Musepack SV8X
Nellymoser AsaoXX
On2 AVC (Audio for Video Codec)X
OpusEXencoding supported through external library libopus
OSQ (Original Sound Quality)X
PCM A-lawXX
PCM mu-lawXX
PCM Archimedes VIDCXX
PCM signed 8-bit planarXX
PCM signed 16-bit big-endian planarXX
PCM signed 16-bit little-endian planarXX
PCM signed 24-bit little-endian planarXX
PCM signed 32-bit little-endian planarXX
PCM 32-bit floating point big-endianXX
PCM 32-bit floating point little-endianXX
PCM 64-bit floating point big-endianXX
PCM 64-bit floating point little-endianXX
PCM D-Cinema audio signed 24-bitXX
PCM signed 8-bitXX
PCM signed 16-bit big-endianXX
PCM signed 16-bit little-endianXX
PCM signed 24-bit big-endianXX
PCM signed 24-bit little-endianXX
PCM signed 32-bit big-endianXX
PCM signed 32-bit little-endianXX
PCM signed 16/20/24-bit big-endian in MPEG-TSX
PCM unsigned 8-bitXX
PCM unsigned 16-bit big-endianXX
PCM unsigned 16-bit little-endianXX
PCM unsigned 24-bit big-endianXX
PCM unsigned 24-bit little-endianXX
PCM unsigned 32-bit big-endianXX
PCM unsigned 32-bit little-endianXX
PCM SGAX
QCELP / PureVoiceX
QDesign Music Codec 1X
QDesign Music Codec 2XThere are still some distortions.
RealAudio 1.0 (14.4K)XXReal 14400 bit/s codec
RealAudio 2.0 (28.8K)XReal 28800 bit/s codec
RealAudio 3.0 (dnet)IXXReal low bitrate AC-3 codec
RealAudio LosslessX
RealAudio SIPR / ACELP.NETX
RK Audio (RKA)X
SBC (low-complexity subband codec)XXUsed in Bluetooth A2DP
ShortenX
Sierra VMD audioXUsed in Sierra VMD files.
Smacker audioX
SMPTE 302M AES3 audioXX
SonicXXexperimental codec
Sonic losslessXXexperimental codec
SpeexEEXsupported through external library libspeex
TAK (Tom’s lossless Audio Kompressor)X
True Audio (TTA)XX
TrueHDXXUsed in HD-DVD and Blu-Ray discs.
TwinVQ (VQF flavor)X
VIMAXUsed in LucasArts SMUSH animations.
ViewQuest VQCX
VorbisEXA native but very primitive encoder exists.
Voxware MetaSoundX
Waveform ArchiverX
WavPackXX
Westwood Audio (SND1)X
Windows Media Audio 1XX
Windows Media Audio 2XX
Windows Media Audio LosslessX
Windows Media Audio ProX
Windows Media Audio VoiceX
Xbox Media Audio 1X
Xbox Media Audio 2X
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+

I means that an integer-only version is available, too (ensures high +performance on systems without hardware floating point support). +

+ +

44.5 Subtitle Formats

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameMuxingDemuxingEncodingDecoding
3GPP Timed TextXX
AQTitleXX
DVBXXXX
DVB teletextXE
DVDXXXX
JACOsubXXX
MicroDVDXXX
MPL2XX
MPsub (MPlayer)XX
PGSX
PJS (Phoenix)XX
RealTextXX
SAMIXX
Spruce format (STL)XX
SSA/ASSXXXX
SubRip (SRT)XXXX
SubViewer v1XX
SubViewerXX
TED Talks captionsXX
TTMLXX
VobSub (IDX+SUB)XX
VPlayerXX
WebVTTXXXX
XSUBXX
+ +

X means that the feature is supported. +

+

E means that support is provided through an external library. +

+ +

44.6 Network Protocols

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSupport
AMQPE
fileX
FTPX
GopherX
GophersX
HLSX
HTTPX
HTTPSX
IcecastX
MMSHX
MMSTX
pipeX
Pro-MPEG FECX
RTMPX
RTMPEX
RTMPSX
RTMPTX
RTMPTEX
RTMPTSX
RTPX
SAMBAE
SCTPX
SFTPE
TCPX
TLSX
UDPX
ZMQE
+ +

X means that the protocol is supported. +

+

E means that support is provided through an external library. +

+ + +

44.7 Input/Output Devices

+ + + + + + + + + + + + + + + + + + + + + + +
NameInputOutput
ALSAXX
BKTRX
cacaX
DV1394X
Lavfi virtual deviceX
Linux framebufferXX
JACKX
LIBCDIOX
LIBDC1394X
OpenALX
OpenGLX
OSSXX
PulseAudioXX
SDLX
Video4Linux2XX
VfW captureX
X11 grabbingX
Win32 grabbingX
+ +

X means that input/output is supported. +

+ +

44.8 Timecode

+ + + + + + + + + + +
Codec/formatReadWrite
AVIXX
DVXX
GXFXX
MOVXX
MPEG1/2XX
MXFXX
+ + +

45 See Also

+ +

ffprobe, +ffmpeg, ffplay, +ffmpeg-utils, +ffmpeg-scaler, +ffmpeg-resampler, +ffmpeg-codecs, +ffmpeg-bitstream-filters, +ffmpeg-formats, +ffmpeg-devices, +ffmpeg-protocols, +ffmpeg-filters +

+ + +

46 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/ffprobe.html b/ffmpeg-n8.1/doc/ffprobe.html new file mode 100644 index 00000000..d68d8b50 --- /dev/null +++ b/ffmpeg-n8.1/doc/ffprobe.html @@ -0,0 +1,1281 @@ + + + + + + + ffprobe Documentation + + + + + + +
+

+ ffprobe Documentation +

+ + + + + + + +

1 Synopsis

+ +

ffprobe [options] input_url +

+ +

2 Description

+ +

ffprobe gathers information from multimedia streams and prints it in +human- and machine-readable fashion. +

+

For example it can be used to check the format of the container used +by a multimedia stream and the format and type of each media stream +contained in it. +

+

If a url is specified in input, ffprobe will try to open and +probe the url content. If the url cannot be opened or recognized as +a multimedia file, a positive exit code is returned. +

+

If no output is specified as output with o ffprobe will write +to stdout. +

+

ffprobe may be employed both as a standalone application or in +combination with a textual filter, which may perform more +sophisticated processing, e.g. statistical processing or plotting. +

+

Options are used to list some of the formats supported by ffprobe or +for specifying which information to display, and for setting how +ffprobe will show it. +

+

ffprobe output is designed to be easily parsable by a textual filter, +and consists of one or more sections of a form defined by the selected +writer, which is specified by the output_format option. +

+

Sections may contain other nested sections, and are identified by a +name (which may be shared by other sections), and an unique +name. See the output of sections. +

+

Metadata tags stored in the container or in the streams are recognized +and printed in the corresponding "FORMAT", "STREAM", "STREAM_GROUP_STREAM" +or "PROGRAM_STREAM" section. +

+ + +

3 Options

+ +

All the numerical options, if not specified otherwise, accept a string +representing a number as input, which may be followed by one of the SI +unit prefixes, for example: ’K’, ’M’, or ’G’. +

+

If ’i’ is appended to the SI unit prefix, the complete prefix will be +interpreted as a unit prefix for binary multiples, which are based on +powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit +prefix multiplies the value by 8. This allows using, for example: +’KB’, ’MiB’, ’G’ and ’B’ as number suffixes. +

+

Options which do not take arguments are boolean options, and set the +corresponding value to true. They can be set to false by prefixing +the option name with "no". For example using "-nofoo" +will set the boolean option with name "foo" to false. +

+

Options that take arguments support a special syntax where the argument given on +the command line is interpreted as a path to the file from which the actual +argument value is loaded. To use this feature, add a forward slash ’/’ +immediately before the option name (after the leading dash). E.g. +

+
ffmpeg -i INPUT -/filter:v filter.script OUTPUT
+
+

will load a filtergraph description from the file named filter.script. +

+ +

3.1 Stream specifiers

+

Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers +are used to precisely specify which stream(s) a given option belongs to. +

+

A stream specifier is a string generally appended to the option name and +separated from it by a colon. E.g. -codec:a:1 ac3 contains the +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, so that the option is applied to all +of them. E.g. the stream specifier in -b:a 128k matches all audio +streams. +

+

An empty stream specifier matches all streams. For example, -codec copy +or -codec: copy would copy all the streams without reencoding. +

+

Possible forms of stream specifiers are: +

+
stream_index
+

Matches the stream with this index. E.g. -threads:1 4 would set the +thread count for the second stream to 4. If stream_index is used as an +additional stream specifier (see below), then it selects stream number +stream_index from the matching streams. Stream numbering is based on the +order of the streams as detected by libavformat except when a stream group +specifier or program ID is also specified. In this case it is based on the +ordering of the streams in the group or program. +

+
stream_type[:additional_stream_specifier]
+

stream_type is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’ +for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video +streams, ’V’ only matches video streams which are not attached pictures, video +thumbnails or cover arts. If additional_stream_specifier is used, then +it matches streams which both have this type and match the +additional_stream_specifier. Otherwise, it matches all streams of the +specified type. +

+
g:group_specifier[:additional_stream_specifier]
+

Matches streams which are in the group with the specifier group_specifier. +if additional_stream_specifier is used, then it matches streams which both +are part of the group and match the additional_stream_specifier. +group_specifier may be one of the following: +

+
group_index
+

Match the stream with this group index. +

+
#group_id or i:group_id
+

Match the stream with this group id. +

+
+
+
p:program_id[:additional_stream_specifier]
+

Matches streams which are in the program with the id program_id. If +additional_stream_specifier is used, then it matches streams which both +are part of the program and match the additional_stream_specifier. +

+
+
#stream_id or i:stream_id
+

Match the stream by stream id (e.g. PID in MPEG-TS container). +

+
m:key[:value]
+

Matches streams with the metadata tag key having the specified value. If +value is not given, matches streams that contain the given tag with any +value. The colon character ’:’ in key or value needs to be +backslash-escaped. +

+
disp:dispositions[:additional_stream_specifier]
+

Matches streams with the given disposition(s). dispositions is a list of +one or more dispositions (as printed by the -dispositions option) +joined with ’+’. +

+
u
+

Matches streams with usable configuration, the codec must be defined and the +essential information such as video dimension or audio sample rate must be present. +

+

Note that in ffmpeg, matching by metadata will only work properly for +input files. +

+
+ + +

3.2 Generic options

+ +

These options are shared amongst the ff* tools. +

+
+
-L, -license
+

Show license. +

+
+
-h, -?, -help, --help [arg]
+

Show help. An optional parameter may be specified to print help about a specific +item. If no argument is specified, only basic (non advanced) tool +options are shown. +

+

Possible values of arg are: +

+
long
+

Print advanced tool options in addition to the basic tool options. +

+
+
full
+

Print complete list of options, including shared and private options +for encoders, decoders, demuxers, muxers, filters, etc. +

+
+
decoder=decoder_name
+

Print detailed information about the decoder named decoder_name. Use the +-decoders option to get a list of all decoders. +

+
+
encoder=encoder_name
+

Print detailed information about the encoder named encoder_name. Use the +-encoders option to get a list of all encoders. +

+
+
demuxer=demuxer_name
+

Print detailed information about the demuxer named demuxer_name. Use the +-formats option to get a list of all demuxers and muxers. +

+
+
muxer=muxer_name
+

Print detailed information about the muxer named muxer_name. Use the +-formats option to get a list of all muxers and demuxers. +

+
+
filter=filter_name
+

Print detailed information about the filter named filter_name. Use the +-filters option to get a list of all filters. +

+
+
bsf=bitstream_filter_name
+

Print detailed information about the bitstream filter named bitstream_filter_name. +Use the -bsfs option to get a list of all bitstream filters. +

+
+
protocol=protocol_name
+

Print detailed information about the protocol named protocol_name. +Use the -protocols option to get a list of all protocols. +

+
+ +
+
-version
+

Show version. +

+
+
-buildconf
+

Show the build configuration, one option per line. +

+
+
-formats
+

Show available formats (including devices). +

+
+
-demuxers
+

Show available demuxers. +

+
+
-muxers
+

Show available muxers. +

+
+
-devices
+

Show available devices. +

+
+
-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. +

+
+
-decoders
+

Show available decoders. +

+
+
-encoders
+

Show all available encoders. +

+
+
-bsfs
+

Show available bitstream filters. +

+
+
-protocols
+

Show available protocols. +

+
+
-filters
+

Show available libavfilter filters. +

+
+
-pix_fmts
+

Show available pixel formats. +

+
+
-sample_fmts
+

Show available sample formats. +

+
+
-layouts
+

Show channel names and standard channel layouts. +

+
+
-dispositions
+

Show stream dispositions. +

+
+
-colors
+

Show recognized color names. +

+
+
-sources device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sources of the input device. +Some devices may provide system-dependent source names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sources pulse,server=192.168.0.4
+
+ +
+
-sinks device[,opt1=val1[,opt2=val2]...]
+

Show autodetected sinks of the output device. +Some devices may provide system-dependent sink names that cannot be autodetected. +The returned list cannot be assumed to be always complete. +

+
ffmpeg -sinks pulse,server=192.168.0.4
+
+ +
+
-loglevel [flags+]loglevel | -v [flags+]loglevel
+

Set logging level and flags used by the library. +

+

The optional flags prefix can consist of the following values: +

+
‘repeat’
+

Indicates that repeated log output should not be compressed to the first line +and the "Last message repeated n times" line will be omitted. +

+
‘level’
+

Indicates that log output should add a [level] prefix to each message +line. This can be used as an alternative to log coloring, e.g. when dumping the +log to file. +

+
‘time’
+

Indicates that log lines should be prefixed with time information. +

+
‘datetime’
+

Indicates that log lines should be prefixed with date and time information. +

+
+

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single +flag without affecting other flags or changing loglevel. When +setting both flags and loglevel, a ’+’ separator is expected +between the last flags value and before loglevel. +

+

loglevel is a string or a number containing one of the following values: +

+
‘quiet, -8’
+

Show nothing at all; be silent. +

+
‘panic, 0’
+

Only show fatal errors which could lead the process to crash, such as +an assertion failure. This is not currently used for anything. +

+
‘fatal, 8’
+

Only show fatal errors. These are errors after which the process absolutely +cannot continue. +

+
‘error, 16’
+

Show all errors, including ones which can be recovered from. +

+
‘warning, 24’
+

Show all warnings and errors. Any message related to possibly +incorrect or unexpected events will be shown. +

+
‘info, 32’
+

Show informative messages during processing. This is in addition to +warnings and errors. This is the default value. +

+
‘verbose, 40’
+

Same as info, except more verbose. +

+
‘debug, 48’
+

Show everything, including debugging information. +

+
‘trace, 56’
+
+ +

For example to enable repeated log output, add the level prefix, and set +loglevel to verbose: +

+
ffmpeg -loglevel repeat+level+verbose -i input output
+
+

Another example that enables repeated log output without affecting current +state of level prefix flag or loglevel: +

+
ffmpeg [...] -loglevel +repeat
+
+ +

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 +AV_LOG_FORCE_NOCOLOR, or can be forced setting +the environment variable AV_LOG_FORCE_COLOR. +

+
+
-report
+

Dump full command line and log output to a file named +program-YYYYMMDD-HHMMSS.log in the current +directory. +This file can be useful for bug reports. +It also implies -loglevel debug. +

+

Setting the environment variable FFREPORT to any value has the +same effect. If the value is a ’:’-separated key=value sequence, these +options will affect the report; option 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 options are recognized: +

+
file
+

set the file name to use for the report; %p is expanded to the name +of the program, %t is expanded to a timestamp, %% is expanded +to a plain % +

+
level
+

set the log verbosity level using a numerical value (see -loglevel). +

+
+ +

For example, to output a report to a file named ffreport.log +using a log level of 32 (alias for log level info): +

+
+
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+ +

Errors in parsing the environment variable are not fatal, and will not +appear in the report. +

+
+
-hide_banner
+

Suppress printing banner. +

+

All FFmpeg tools will normally show a copyright notice, build options +and library versions. This option can be used to suppress printing +this information. +

+
+
-cpuflags flags (global)
+

Allows setting and clearing cpu flags. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpuflags -sse+mmx ...
+ffmpeg -cpuflags mmx ...
+ffmpeg -cpuflags 0 ...
+
+

Possible flags for this option are: +

+
‘x86’
+
+
‘mmx’
+
‘mmxext’
+
‘sse’
+
‘sse2’
+
‘sse2slow’
+
‘sse3’
+
‘sse3slow’
+
‘ssse3’
+
‘atom’
+
‘sse4.1’
+
‘sse4.2’
+
‘avx’
+
‘avx2’
+
‘xop’
+
‘fma3’
+
‘fma4’
+
‘3dnow’
+
‘3dnowext’
+
‘bmi1’
+
‘bmi2’
+
‘cmov’
+
+
+
‘ARM’
+
+
‘armv5te’
+
‘armv6’
+
‘armv6t2’
+
‘vfp’
+
‘vfpv3’
+
‘neon’
+
‘setend’
+
+
+
‘AArch64’
+
+
‘armv8’
+
‘vfp’
+
‘neon’
+
+
+
‘PowerPC’
+
+
‘altivec’
+
+
+
‘Specific Processors’
+
+
‘pentium2’
+
‘pentium3’
+
‘pentium4’
+
‘k6’
+
‘k62’
+
‘athlon’
+
‘athlonxp’
+
‘k8’
+
+
+
+ +
+
-cpucount count (global)
+

Override detection of CPU count. This option is intended +for testing. Do not use it unless you know what you’re doing. +

+
ffmpeg -cpucount 2
+
+ +
+
-max_alloc bytes
+

Set the maximum size limit for allocating a block on the heap by ffmpeg’s +family of malloc functions. Exercise extreme caution when using +this option. Don’t use if you do not understand the full consequence of doing so. +Default is INT_MAX. +

+
+ + +

3.3 AVOptions

+ +

These options are provided directly by the libavformat, libavdevice and +libavcodec libraries. To see the list of available AVOptions, use the +-help option. They are separated into two categories: +

+
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. +

+
private
+

These options are specific to the given container, device or codec. Private +options are listed under their corresponding containers/devices/codecs. +

+
+ +

For example to write an ID3v2.3 header instead of a default ID3v2.4 to +an MP3 file, use the id3v2_version private option of the MP3 +muxer: +

+
ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+ +

All codec AVOptions are per-stream, and thus a stream specifier +should be attached to them: +

+
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+ +

In the above example, a multichannel audio stream is mapped twice for output. +The first instance is encoded with codec ac3 and bitrate 640k. +The second instance is downmixed to 2 channels and encoded with codec aac. A bitrate of 128k is specified for it using +absolute index of the output stream. +

+

Note: the -nooption syntax cannot be used for boolean +AVOptions, use -option 0/-option 1. +

+

Note: the 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. +

+ +

3.4 Main options

+ +
+
-f format
+

Force format to use. +

+
+
-unit
+

Show the unit of the displayed values. +

+
+
-prefix
+

Use SI prefixes for the displayed values. +Unless the "-byte_binary_prefix" option is used all the prefixes +are decimal. +

+
+
-byte_binary_prefix
+

Force the use of binary prefixes for byte values. +

+
+
-sexagesimal
+

Use sexagesimal format HH:MM:SS.MICROSECONDS for time values. +

+
+
-pretty
+

Prettify the format of the displayed values, it corresponds to the +options "-unit -prefix -byte_binary_prefix -sexagesimal". +

+
+
-output_format, -of, -print_format writer_name[=writer_options]
+

Set the output printing format. +

+

writer_name specifies the name of the writer, and +writer_options specifies the options to be passed to the writer. +

+

For example for printing the output in JSON format, specify: +

+
-output_format json
+
+ +

For more details on the available output printing formats, see the +Writers section below. +

+
+
-sections
+

Print sections structure and section information, and exit. The output +is not meant to be parsed by a machine. +

+
+
-select_streams stream_specifier
+

Select only the streams specified by stream_specifier. This +option affects only the options related to streams +(e.g. show_streams, show_packets, etc.). +

+

For example to show only audio streams, you can use the command: +

+
ffprobe -show_streams -select_streams a INPUT
+
+ +

To show only video packets belonging to the video stream with index 1: +

+
ffprobe -show_packets -select_streams v:1 INPUT
+
+ +
+
-show_data
+

Show payload data, as a hexadecimal and ASCII dump (other formats can be +selected using -data_dump_format). Coupled with +-show_packets, it will dump the packets’ data. Coupled with +-show_streams, it will dump the codec extradata. +

+

The dump is printed as the "data" field. It may contain newlines. +

+
+
-show_data_hash algorithm
+

Show a hash of payload data, for packets with -show_packets and for +codec extradata with -show_streams. +

+
+
-data_dump_format format
+

Select a format used for the data dumps enabled with the -show_data +option. The default is xxd which is a hexdump format compatible with the +well-known xxd program. base64 is also supported. +

+
+
-show_error
+

Show information about the error found when trying to probe the input. +

+

The error information is printed within a section with name "ERROR". +

+
+
-show_format
+

Show information about the container format of the input multimedia +stream. +

+

All the container format information is printed within a section with +name "FORMAT". +

+
+
-show_entries section_entries
+

Set list of entries to show. +

+

Entries are specified according to the following +syntax. section_entries contains a list of section entries +separated by :. Each section entry is composed by a section +name (or unique name), optionally followed by a list of entries local +to that section, separated by ,. +

+

If section name is specified but is followed by no =, all +entries are printed to output, together with all the contained +sections. Otherwise only the entries specified in the local section +entries list are printed. In particular, if = is specified but +the list of local entries is empty, then no entries will be shown for +that section. +

+

Note that the order of specification of the local section entries is +not honored in the output, and the usual display order will be +retained. +

+

The formal syntax is given by: +

+
LOCAL_SECTION_ENTRIES ::= SECTION_ENTRY_NAME[,LOCAL_SECTION_ENTRIES]
+SECTION_ENTRY         ::= SECTION_NAME[=[LOCAL_SECTION_ENTRIES]]
+SECTION_ENTRIES       ::= SECTION_ENTRY[:SECTION_ENTRIES]
+
+ +

For example, to show only the index and type of each stream, and the PTS +time, duration time, and stream index of the packets, you can specify +the argument: +

+
packet=pts_time,duration_time,stream_index : stream=index,codec_type
+
+ +

To show all the entries in the section "format", but only the codec +type in the section "stream", specify the argument: +

+
format : stream=codec_type
+
+ +

To show all the tags in the stream and format sections: +

+
stream_tags : format_tags
+
+ +

To show only the title tag (if available) in the stream +sections: +

+
stream_tags=title
+
+ +
+
-show_packets
+

Show information about each packet contained in the input multimedia +stream. +

+

The information for each single packet is printed within a dedicated +section with name "PACKET". +

+
+
-show_frames
+

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" or "SUBTITLE". +

+
+
-show_log loglevel
+

Show logging information from the decoder about each frame according to +the value set in loglevel, (see -loglevel). This option requires -show_frames. +

+

The information for each log message is printed within a dedicated +section with name "LOG". +

+
+
-show_streams
+

Show information about each media stream contained in the input +multimedia stream. +

+

Each media stream information is printed within a dedicated section +with name "STREAM". +

+
+
-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". +

+
+
-show_stream_groups
+

Show information about stream groups and their streams contained in the +input multimedia stream. +

+

Each media stream information is printed within a dedicated section +with name "STREAM_GROUP_STREAM". +

+
+
-show_chapters
+

Show information about chapters stored in the format. +

+

Each chapter is printed within a dedicated section with name "CHAPTER". +

+
+
-count_frames
+

Count the number of frames per stream and report it in the +corresponding stream section. +

+
+
-count_packets
+

Count the number of packets per stream and report it in the +corresponding stream section. +

+
+
-read_intervals read_intervals
+
+

Read only the specified intervals. read_intervals must be a +sequence of interval specifications separated by ",". +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 absolute 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: +

+
INTERVAL  ::= [START|+START_OFFSET][%[END|+END_OFFSET]]
+INTERVALS ::= INTERVAL[,INTERVALS]
+
+ +

A few examples follow. +

    +
  • Seek to time 10, read packets until 20 seconds after the found seek +point, then seek to position 01:30 (1 minute and thirty +seconds) and read packets until position 01:45. +
    +
    10%+20,01:30%01:45
    +
    + +
  • Read only 42 packets after seeking to position 01:23: +
    +
    01:23%+#42
    +
    + +
  • Read only the first 20 seconds from the start: +
    +
    %+20
    +
    + +
  • Read from the start until position 02:30: +
    +
    %02:30
    +
    +
+ +
+
-show_private_data, -private
+

Show private data, that is data depending on the format of the +particular shown element. +This option is enabled by default, but you may need to disable it +for specific uses, for example when creating XSD-compliant XML output. +

+
+
-show_program_version
+

Show information related to program version. +

+

Version information is printed within a section with name +"PROGRAM_VERSION". +

+
+
-show_library_versions
+

Show information related to library versions. +

+

Version information for each library is printed within a section with +name "LIBRARY_VERSION". +

+
+
-show_versions
+

Show information related to program and library versions. This is the +equivalent of setting both -show_program_version and +-show_library_versions options. +

+
+
-show_pixel_formats
+

Show information about all pixel formats supported by FFmpeg. +

+

Pixel format information for each format is printed within a section +with name "PIXEL_FORMAT". +

+
+
-show_optional_fields value
+

Some writers viz. JSON and XML, omit the printing of fields with invalid or non-applicable values, +while other writers always print them. This option enables one to control this behaviour. +Valid values are always/1, never/0 and auto/-1. +Default is auto. +

+
+
-analyze_frames
+

Analyze frames and/or their side data up to the provided read interval, +providing additional information that may be useful at a stream level. +Must be paired with the -show_streams option or it will have no effect. +

+

Currently, the additional fields provided by this option when enabled are the +closed_captions and film_grain fields. +

+

For example, to analyze the first 20 seconds and populate these fields: +

+
ffprobe -show_streams -analyze_frames -read_intervals "%+20" INPUT
+
+ +
+
-bitexact
+

Force bitexact output, useful to produce output which is not dependent +on the specific build. +

+
+
-i input_url
+

Read input_url. +

+
+
-o output_url
+

Write output to output_url. If not specified, the output is sent +to stdout. +

+
+
-c:media_specifier codec_name
+
-codec:media_specifier codec_name
+

Force a specific decoder implementation for the stream identified by +media_specifier, which can assume the values a (audio), +v (video), s (subtitle), and d (data). +

+
+
+ + +

4 Writers

+ +

A writer defines the output format adopted by ffprobe, and will be +used for printing all the parts of the output. +

+

A writer may accept one or more arguments, which specify the options +to adopt. The options are specified as a list of key=value +pairs, separated by ":". +

+

All writers support the following options: +

+
+
string_validation, sv
+

Set string validation mode. +

+

The following values are accepted. +

+
‘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. +

+
+
‘ignore’
+

Any validation error will be ignored. This will result in possibly +broken output, especially with the json or xml writer. +

+
+
‘replace’
+

The writer will substitute invalid UTF-8 sequences or code points with +the string specified with the string_validation_replacement. +

+
+ +

Default value is ‘replace’. +

+
+
string_validation_replacement, svr
+

Set replacement string to use in case string_validation is +set to ‘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. +

+
+ +

A description of the currently available writers follows. +

+ +

4.1 default

+

Default format. +

+

Print each section in the form: +

+
[SECTION]
+key1=val1
+...
+keyN=valN
+[/SECTION]
+
+ +

Metadata tags are printed as a line in the corresponding FORMAT, STREAM, +STREAM_GROUP_STREAM or PROGRAM_STREAM section, and are prefixed by the +string "TAG:". +

+

A description of the accepted options follows. +

+
+
nokey, nk
+

If set to 1 specify not to print the key of each field. Default value +is 0. +

+
+
noprint_wrappers, nw
+

If set to 1 specify not to print the section header and footer. +Default value is 0. +

+
+ + +

4.2 compact, csv

+

Compact and CSV format. +

+

The csv writer is equivalent to compact, but supports +different defaults. +

+

Each section is printed on a single line. +If no option is specified, the output has the form: +

+
section|key1=val1| ... |keyN=valN
+
+ +

Metadata tags are printed in the corresponding "format" or "stream" +section. A metadata tag key, if printed, is prefixed by the string +"tag:". +

+

The description of the accepted options follows. +

+
+
item_sep, s
+

Specify the character to use for separating fields in the output line. +It must be a single printable character, it is "|" by default ("," for +the csv writer). +

+
+
nokey, nk
+

If set to 1 specify not to print the key of each field. Its default +value is 0 (1 for the csv writer). +

+
+
escape, e
+

Set the escape mode to use, default to "c" ("csv" for the csv +writer). +

+

It can assume one of the following values: +

+
c
+

Perform C-like escaping. Strings containing a newline (‘\n’), carriage +return (‘\r’), a tab (‘\t’), a form feed (‘\f’), the escaping +character (‘\’) or the item separator character SEP are escaped +using C-like fashioned escaping, so that a newline is converted to the +sequence ‘\n’, a carriage return to ‘\r’, ‘\’ to ‘\\’ and +the separator SEP is converted to ‘\SEP’. +

+
+
csv
+

Perform CSV-like escaping, as described in RFC4180. Strings +containing a newline (‘\n’), a carriage return (‘\r’), a double quote +(‘"’), or SEP are enclosed in double-quotes. +

+
+
none
+

Perform no escaping. +

+
+ +
+
print_section, p
+

Print the section name at the beginning of each line if the value is +1, disable it with value set to 0. Default value is +1. +

+
+
+ + +

4.3 flat

+

Flat format. +

+

A free-form output where each line contains an explicit key=value, such as +"streams.stream.3.tags.foo=bar". The output is shell escaped, so it can be +directly embedded in sh scripts as long as the separator character is an +alphanumeric character or an underscore (see sep_char option). +

+

The description of the accepted options follows. +

+
+
sep_char, s
+

Separator character used to separate the chapter, the section name, IDs and +potential tags in the printed field key. +

+

Default value is ‘.’. +

+
+
hierarchical, h
+

Specify if the section name specification should be hierarchical. If +set to 1, and if there is more than one section in the current +chapter, the section name will be prefixed by the name of the +chapter. A value of 0 will disable this behavior. +

+

Default value is 1. +

+
+ + +

4.4 ini

+

INI format output. +

+

Print output in an INI based format. +

+

The following conventions are adopted: +

+
    +
  • all key and values are UTF-8 +
  • ‘.’ is the subgroup separator +
  • newline, ‘\t’, ‘\f’, ‘\b’ and the following characters are +escaped +
  • ‘\’ is the escape character +
  • ‘#’ is the comment indicator +
  • ‘=’ is the key/value separator +
  • ‘:’ is not used but usually parsed as key/value separator +
+ +

This writer accepts options as a list of key=value pairs, +separated by ‘:’. +

+

The description of the accepted options follows. +

+
+
hierarchical, h
+

Specify if the section name specification should be hierarchical. If +set to 1, and if there is more than one section in the current +chapter, the section name will be prefixed by the name of the +chapter. A value of 0 will disable this behavior. +

+

Default value is 1. +

+
+ + +

4.5 json

+

JSON based format. +

+

Each section is printed using JSON notation. +

+

The description of the accepted options follows. +

+
+
compact, c
+

If set to 1 enable compact output, that is each section will be +printed on a single line. Default value is 0. +

+
+ +

For more information about JSON, see http://www.json.org/. +

+ +

4.6 xml

+

XML based format. +

+

The XML output is described in the XML schema description file +ffprobe.xsd installed in the FFmpeg datadir. +

+

An updated version of the schema can be retrieved at the url +http://www.ffmpeg.org/schema/ffprobe.xsd, which redirects to the +latest schema committed into the FFmpeg development source code tree. +

+

Note that the output issued will be compliant to the +ffprobe.xsd schema only when no special global output options +(unit, prefix, byte_binary_prefix, +sexagesimal etc.) are specified. +

+

The description of the accepted options follows. +

+
+
fully_qualified, q
+

If set to 1 specify if the output should be fully qualified. Default +value is 0. +This is required for generating an XML file which can be validated +through an XSD file. +

+
+
xsd_strict, x
+

If set to 1 perform more checks for ensuring that the output is XSD +compliant. Default value is 0. +This option automatically sets fully_qualified to 1. +

+
+ +

For more information about the XML format, see +https://www.w3.org/XML/. +

+ +

5 Timecode

+ +

ffprobe supports Timecode extraction: +

+
    +
  • MPEG1/2 timecode is extracted from the GOP, and is available in the video +stream details (-show_streams, see timecode). + +
  • MOV timecode is extracted from tmcd track, so is available in the tmcd +stream metadata (-show_streams, see TAG:timecode). + +
  • DV, GXF and AVI timecodes are available in format metadata +(-show_format, see TAG:timecode). + +
+ + + +

6 See Also

+ +

ffprobe-all, +ffmpeg, ffplay, +ffmpeg-utils, +ffmpeg-scaler, +ffmpeg-resampler, +ffmpeg-codecs, +ffmpeg-bitstream-filters, +ffmpeg-formats, +ffmpeg-devices, +ffmpeg-protocols, +ffmpeg-filters +

+ + +

7 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/general.html b/ffmpeg-n8.1/doc/general.html new file mode 100644 index 00000000..c12d710c --- /dev/null +++ b/ffmpeg-n8.1/doc/general.html @@ -0,0 +1,1421 @@ + + + + + + + General Documentation + + + + + + +
+

+ General Documentation +

+ + + + + + + +

1 External libraries

+ +

FFmpeg can be hooked up with a number of external libraries to add support +for more formats. None of them are used by default, their use has to be +explicitly requested by passing the appropriate flags to +./configure. +

+ +

1.1 Alliance for Open Media (AOM)

+ +

FFmpeg can make use of the AOM library for AV1 decoding and encoding. +

+

Go to http://aomedia.org/ and follow the instructions for +installing the library. Then pass --enable-libaom to configure to +enable it. +

+ +

1.2 AMD AMF/VCE

+ +

FFmpeg can use the AMD Advanced Media Framework library +for accelerated H.264 and HEVC(only windows) encoding on hardware with Video Coding Engine (VCE). +

+

To enable support you must obtain the AMF framework header files(version 1.4.9+) from +https://github.com/GPUOpen-LibrariesAndSDKs/AMF.git. +

+

Create an AMF/ directory in the system include path. +Copy the contents of AMF/amf/public/include/ into that directory. +Then configure FFmpeg with --enable-amf. +

+

Initialization of amf encoder occurs in this order: +1) trying to initialize through dx11(only windows) +2) trying to initialize through dx9(only windows) +3) trying to initialize through vulkan +

+

To use h.264(AMD VCE) encoder on linux amdgru-pro version 19.20+ and amf-amdgpu-pro +package(amdgru-pro contains, but does not install automatically) are required. +

+

This driver can be installed using amdgpu-pro-install script in official amd driver archive. +

+ +

1.3 AviSynth

+ +

FFmpeg can read AviSynth scripts as input. To enable support, pass +--enable-avisynth to configure after installing the headers +provided by AviSynth+. +AviSynth+ can be configured to install only the headers by either +passing -DHEADERS_ONLY:bool=on to the normal CMake-based build +system, or by using the supplied GNUmakefile. +

+

For Windows, supported AviSynth variants are +AviSynth 2.6 RC1 or higher for 32-bit builds and +AviSynth+ r1718 or higher for 32-bit and 64-bit builds. +

+

For Linux, macOS, and BSD, the only supported AviSynth variant is +AviSynth+, starting with version 3.5. +

+
+

In 2016, AviSynth+ added support for building with GCC. However, due to +the eccentricities of Windows’ calling conventions, 32-bit GCC builds +of AviSynth+ are not compatible with typical 32-bit builds of FFmpeg. +

+

By default, FFmpeg assumes compatibility with 32-bit MSVC builds of +AviSynth+ since that is the most widely-used and entrenched build +configuration. Users can override this and enable support for 32-bit +GCC builds of AviSynth+ by passing -DAVSC_WIN32_GCC32 to +--extra-cflags when configuring FFmpeg. +

+

64-bit builds of FFmpeg are not affected, and can use either MSVC or +GCC builds of AviSynth+ without any special flags. +

+
+

AviSynth(+) is loaded dynamically. Distributors can build FFmpeg +with --enable-avisynth, and the binaries will work regardless +of the end user having AviSynth installed. If/when an end user +would like to use AviSynth scripts, then they can install AviSynth(+) +and FFmpeg will be able to find and use it to open scripts. +

+ +

1.4 Chromaprint

+ +

FFmpeg can make use of the Chromaprint library for generating audio fingerprints. +Pass --enable-chromaprint to configure to +enable it. See https://acoustid.org/chromaprint. +

+ +

1.5 codec2

+ +

FFmpeg can make use of the codec2 library for codec2 decoding and encoding. +There is currently no native decoder, so libcodec2 must be used for decoding. +

+

Go to http://freedv.org/, download "Codec 2 source archive". +Build and install using CMake. Debian users can install the libcodec2-dev package instead. +Once libcodec2 is installed you can pass --enable-libcodec2 to configure to enable it. +

+

The easiest way to use codec2 is with .c2 files, since they contain the mode information required for decoding. +To encode such a file, use a .c2 file extension and give the libcodec2 encoder the -mode option: +ffmpeg -i input.wav -mode 700C output.c2. +Playback is as simple as ffplay output.c2. +For a list of supported modes, run ffmpeg -h encoder=libcodec2. +Raw codec2 files are also supported. +To make sense of them the mode in use needs to be specified as a format option: +ffmpeg -f codec2raw -mode 1300 -i input.raw output.wav. +

+ +

1.6 dav1d

+ +

FFmpeg can make use of the dav1d library for AV1 video decoding. +

+

Go to https://code.videolan.org/videolan/dav1d and follow the instructions for +installing the library. Then pass --enable-libdav1d to configure to enable it. +

+ +

1.7 davs2

+ +

FFmpeg can make use of the davs2 library for AVS2-P2/IEEE1857.4 video decoding. +

+

Go to https://github.com/pkuvcl/davs2 and follow the instructions for +installing the library. Then pass --enable-libdavs2 to configure to +enable it. +

+
+

libdavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

1.8 uavs3d

+ +

FFmpeg can make use of the uavs3d library for AVS3-P2/IEEE1857.10 video decoding. +

+

Go to https://github.com/uavs3/uavs3d and follow the instructions for +installing the library. Then pass --enable-libuavs3d to configure to +enable it. +

+ +

1.9 Game Music Emu

+ +

FFmpeg can make use of the Game Music Emu library to read audio from supported video game +music file formats. Pass --enable-libgme to configure to +enable it. See https://bitbucket.org/mpyne/game-music-emu/overview. +

+ +

1.10 Intel QuickSync Video

+ +

FFmpeg can use Intel QuickSync Video (QSV) for accelerated decoding and encoding +of multiple codecs. To use QSV, FFmpeg must be linked against the libmfx +dispatcher, which loads the actual decoding libraries. +

+

The dispatcher is open source and can be downloaded from +https://github.com/lu-zero/mfx_dispatch.git. FFmpeg needs to be configured +with the --enable-libmfx option and pkg-config needs to be able to +locate the dispatcher’s .pc files. +

+ +

1.11 Kvazaar

+ +

FFmpeg can make use of the Kvazaar library for HEVC encoding. +

+

Go to https://github.com/ultravideo/kvazaar and follow the +instructions for installing the library. Then pass +--enable-libkvazaar to configure to enable it. +

+ +

1.12 LAME

+ +

FFmpeg can make use of the LAME library for MP3 encoding. +

+

Go to http://lame.sourceforge.net/ and follow the +instructions for installing the library. +Then pass --enable-libmp3lame to configure to enable it. +

+ +

1.13 LCEVCdec

+ +

FFmpeg can make use of the liblcevc_dec library for LCEVC enhancement layer +decoding on supported bitstreams. +

+

Go to https://github.com/v-novaltd/LCEVCdec and follow the instructions +for installing the library. Then pass --enable-liblcevc-dec to configure to +enable it. +

+
+

LCEVCdec is under the BSD-3-Clause-Clear License. +

+ +

1.14 libilbc

+ +

iLBC is a narrowband speech codec that has been made freely available +by Google as part of the WebRTC project. libilbc is a packaging friendly +copy of the iLBC codec. FFmpeg can make use of the libilbc library for +iLBC decoding and encoding. +

+

Go to https://github.com/TimothyGu/libilbc and follow the instructions for +installing the library. Then pass --enable-libilbc to configure to +enable it. +

+ +

1.15 libjxl

+ +

JPEG XL is an image format intended to fully replace legacy JPEG for an extended +period of life. See https://jpegxl.info/ for more information, and see +https://github.com/libjxl/libjxl for the library source. You can pass +--enable-libjxl to configure in order enable the libjxl wrapper. +

+ +

1.16 libvpx

+ +

FFmpeg can make use of the libvpx library for VP8/VP9 decoding and encoding. +

+

Go to http://www.webmproject.org/ and follow the instructions for +installing the library. Then pass --enable-libvpx to configure to +enable it. +

+ +

1.17 ModPlug

+ +

FFmpeg can make use of this library, originating in Modplug-XMMS, to read from MOD-like music files. +See https://github.com/Konstanty/libmodplug. Pass --enable-libmodplug to configure to +enable it. +

+ +

1.18 OpenCORE, VisualOn, and Fraunhofer libraries

+ +

Spun off Google Android sources, OpenCore, VisualOn and Fraunhofer +libraries provide encoders for a number of audio codecs. +

+
+

OpenCORE and VisualOn libraries are under the Apache License 2.0 +(see http://www.apache.org/licenses/LICENSE-2.0 for details), which is +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) by passing --enable-version3 to configure in +order to use it. +

+

The license of the Fraunhofer AAC library is incompatible with the GPL. +Therefore, for GPL builds, you have to pass --enable-nonfree to +configure in order to use it. To the best of our knowledge, it is +compatible with the LGPL. +

+ +

1.18.1 OpenCORE AMR

+ +

FFmpeg can make use of the OpenCORE libraries for AMR-NB +decoding/encoding and AMR-WB decoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the libraries. +Then pass --enable-libopencore-amrnb and/or +--enable-libopencore-amrwb to configure to enable them. +

+ +

1.18.2 VisualOn AMR-WB encoder library

+ +

FFmpeg can make use of the VisualOn AMR-WBenc library for AMR-WB encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libvo-amrwbenc to configure to enable it. +

+ +

1.18.3 Fraunhofer AAC library

+ +

FFmpeg can make use of the Fraunhofer AAC library for AAC decoding & encoding. +

+

Go to http://sourceforge.net/projects/opencore-amr/ and follow the +instructions for installing the library. +Then pass --enable-libfdk-aac to configure to enable it. +

+ +

1.18.4 Fraunhofer MPEG-H 3D Audio decoder library

+ +

FFmpeg can make use of the Fraunhofer MPEG-H decoder library for MPEG-H 3DA decoding. +

+

Go to https://github.com/Fraunhofer-IIS/mpeghdec and follow the +instructions for installing the library. +Then pass --enable-libmpeghdec --enable-nonfree to configure to enable it. +

+ +

1.18.5 LC3 library

+ +

FFmpeg can make use of the Google LC3 library for LC3 decoding & encoding. +

+

Go to https://github.com/google/liblc3/ and follow the instructions for +installing the library. +Then pass --enable-liblc3 to configure to enable it. +

+ +

1.19 OpenH264

+ +

FFmpeg can make use of the OpenH264 library for H.264 decoding and encoding. +

+

Go to http://www.openh264.org/ and follow the instructions for +installing the library. Then pass --enable-libopenh264 to configure to +enable it. +

+

For decoding, this library is much more limited than the built-in decoder +in libavcodec; currently, this library lacks support for decoding B-frames +and some other main/high profile features. (It currently only supports +constrained baseline profile and CABAC.) Using it is mostly useful for +testing and for taking advantage of Cisco’s patent portfolio license +(http://www.openh264.org/BINARY_LICENSE.txt). +

+ +

1.20 OpenJPEG

+ +

FFmpeg can use the OpenJPEG libraries for decoding/encoding J2K videos. Go to +http://www.openjpeg.org/ to get the libraries and follow the installation +instructions. To enable using OpenJPEG in FFmpeg, pass --enable-libopenjpeg to +./configure. +

+ +

1.21 rav1e

+ +

FFmpeg can make use of rav1e (Rust AV1 Encoder) via its C bindings to encode videos. +Go to https://github.com/xiph/rav1e/ and follow the instructions to build +the C library. To enable using rav1e in FFmpeg, pass --enable-librav1e +to ./configure. +

+ +

1.22 SVT-AV1

+ +

FFmpeg can make use of the Scalable Video Technology for AV1 library for AV1 encoding. +

+

Go to https://gitlab.com/AOMediaCodec/SVT-AV1/ and follow the instructions +for installing the library. Then pass --enable-libsvtav1 to configure to +enable it. +

+ +

1.23 SVT-JPEG-XS

+ +

FFmpeg can make use of the Scalable Video Technology for JPEG-XS library for JPEG-XS +decoding and encoding. +

+

Go to https://github.com/OpenVisualCloud/SVT-JPEG-XS and follow the instructions +for installing the library. Then pass --enable-libsvtjpegxs to configure to +enable it. +

+ +

1.24 TwoLAME

+ +

FFmpeg can make use of the TwoLAME library for MP2 encoding. +

+

Go to http://www.twolame.org/ and follow the +instructions for installing the library. +Then pass --enable-libtwolame to configure to enable it. +

+ +

1.25 VapourSynth

+ +

FFmpeg can read VapourSynth scripts as input. To enable support, pass +--enable-vapoursynth to configure. Vapoursynth is detected via +pkg-config. Versions 42 or greater supported. +See http://www.vapoursynth.com/. +

+

Due to security concerns, Vapoursynth scripts will not +be autodetected so the input format has to be forced. For ff* CLI tools, +add -f vapoursynth before the input -i yourscript.vpy. +

+ +

1.26 x264

+ +

FFmpeg can make use of the x264 library for H.264 encoding. +

+

Go to http://www.videolan.org/developers/x264.html and follow the +instructions for installing the library. Then pass --enable-libx264 to +configure to enable it. +

+
+

x264 is under the GNU Public License Version 2 or later +(see 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. +

+ +

1.27 x265

+ +

FFmpeg can make use of the x265 library for HEVC encoding. +

+

Go to http://x265.org/developers.html and follow the instructions +for installing the library. Then pass --enable-libx265 to configure +to enable it. +

+
+

x265 is under the GNU Public License Version 2 or later +(see 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. +

+ +

1.28 xavs

+ +

FFmpeg can make use of the xavs library for AVS encoding. +

+

Go to http://xavs.sf.net/ and follow the instructions for +installing the library. Then pass --enable-libxavs to configure to +enable it. +

+ +

1.29 xavs2

+ +

FFmpeg can make use of the xavs2 library for AVS2-P2/IEEE1857.4 video encoding. +

+

Go to https://github.com/pkuvcl/xavs2 and follow the instructions for +installing the library. Then pass --enable-libxavs2 to configure to +enable it. +

+
+

libxavs2 is under the GNU Public License Version 2 or later +(see 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. +

+ +

1.30 eXtra-fast Essential Video Encoder (XEVE)

+ +

FFmpeg can make use of the XEVE library for EVC video encoding. +

+

Go to https://github.com/mpeg5/xeve and follow the instructions for +installing the XEVE library. Then pass --enable-libxeve to configure to +enable it. +

+ +

1.31 eXtra-fast Essential Video Decoder (XEVD)

+ +

FFmpeg can make use of the XEVD library for EVC video decoding. +

+

Go to https://github.com/mpeg5/xevd and follow the instructions for +installing the XEVD library. Then pass --enable-libxevd to configure to +enable it. +

+ +

1.32 ZVBI

+ +

ZVBI is a VBI decoding library which can be used by FFmpeg to decode DVB +teletext pages and DVB teletext subtitles. +

+

Go to http://sourceforge.net/projects/zapping/ and follow the instructions for +installing the library. Then pass --enable-libzvbi to configure to +enable it. +

+ +

2 Supported File Formats, Codecs or Features

+ +

You can use the -formats and -codecs options to have an exhaustive list. +

+ +

2.1 File Formats

+ +

FFmpeg supports the following file formats through the libavformat +library: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
3dostrX
4xmX4X Technologies format, used in some games.
8088flex TMVX
AAXXAudible Enhanced Audio format, used in audiobooks.
AAXAudible Format 2, 3, and 4, used in audiobooks.
ACT VoiceXcontains G.729 audio
Adobe FilmstripXX
Audio IFF (AIFF)XX
American Laser Games MMXMultimedia format used in games like Mad Dog McCree.
3GPP AMRXX
Amazing Studio Packed Animation FileXMultimedia format used in game Heart Of Darkness.
Apple HTTP Live StreamingX
Artworx Data FormatX
Interplay ACMXAudio only format used in some Interplay games.
ADPXAudio format used on the Nintendo Gamecube.
AFCXAudio format used on the Nintendo Gamecube.
ADS/SS2XAudio format used on the PS2.
APNGXX
ASFXXAdvanced / Active Streaming Format.
ASTXXAudio format used on the Nintendo Wii.
AVIXX
AviSynthX
AVRXAudio format used on Mac.
AVSXMultimedia format used by the Creature Shock game.
Beam Software SIFFXAudio and video format used in some games by Beam Software.
Bethesda Softworks VIDXUsed in some games from Bethesda Softworks.
Binary textX
BinkXMultimedia format used by many games.
Bink AudioXAudio only multimedia format used by some games.
Bitmap Brothers JVXUsed in Z and Z95 games.
BRPXArgonaut Games format.
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
BFSTMXAudio format used on the Nintendo WiiU (based on BRSTM).
BRSTMXAudio format used on the Nintendo Wii.
BW64XBroadcast Wave 64bit.
BWFXX
codec2 (raw)XXMust be given -mode format option to decode correctly.
codec2 (.c2 files)XXContains header with version and mode info, simplifying playback.
CRI ADXXXAudio-only format used in console video games.
CRI AIXX
CRI HCAXAudio-only format used in console video games.
Discworld II BMVX
Interplay C93XUsed in the game Cyberia from Interplay.
Delphine Software International CINXMultimedia format used by Delphine Software games.
Digital Speech Standard (DSS)X
CD+GXVideo format used by CD+G karaoke disks
Phantom CineX
Commodore CDXLXAmiga CD video format
Core Audio FormatXXApple Core Audio Format
CRC testing formatX
Creative VoiceXXCreated for the Sound Blaster Pro.
CRYO APCXAudio format used in some games by CRYO Interactive Entertainment.
D-Cinema audioXX
Deluxe Paint AnimationX
DCSTRX
DFAXThis format is used in Chronomaster game
DirectDraw SurfaceX
DSD Stream File (DSF)X
DV videoXX
DXAXThis format is used in the non-Windows version of the Feeble Files + game and different game cutscenes repacked for use with ScummVM.
Electronic Arts cdataX
Electronic Arts MultimediaXUsed in various EA games; files have extensions like WVE and UV2.
Ensoniq Paris Audio FileX
FFM (FFserver live feed)XX
Flash (SWF)XX
Flash 9 (AVM2)XXOnly embedded audio is decoded.
FLI/FLC/FLX animationX.fli/.flc files
Flash Video (FLV)XXMacromedia Flash video files
framecrc testing formatX
FunCom ISSXAudio format used in various games from FunCom like The Longest Journey.
G.723.1XX
G.726XBoth left- and right-justified.
G.729 BITXX
G.729 rawX
GENHXAudio format for various games.
GIF AnimationXX
GXFXXGeneral eXchange Format SMPTE 360M, used by Thomson Grass Valley + playout servers.
HNMXOnly version 4 supported, used in some games from Cryo Interactive
iCEDraw FileX
ICOXXMicrosoft Windows ICO
id Quake II CIN videoX
id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
IEC61937 encapsulationXX
IFFXInterchange File Format
IFVXA format used by some old CCTV DVRs.
iLBCXX
Interplay MVEXFormat used in various Interplay computer games.
Iterated Systems ClearVideoXI-frames only
IV8XA format generated by IndigoVision 8000 video server.
IVF (On2)XXA format used by libvpx
Internet Video RecordingX
IRCAMXX
LAFXLimitless Audio Format
LATMXX
LMLM4XUsed by Linux Media Labs MPEG-4 PCI boards
LOASXcontains LATM multiplexed AAC audio
LRCXX
LVFX
LXFXVR native stream format, used by Leitch/Harris’ video servers.
Magic Lantern Video (MLV)X
MatroskaXX
Matroska audioX
FFmpeg metadataXXMetadata in text format.
MAXIS XAXUsed in Sim City 3000; file extension .xa.
MCAXUsed in some games from Capcom; file extension .mca.
MD StudioX
Metal Gear Solid: The Twin SnakesX
Megalux FrameXUsed by Megalux Ultimate Paint
MobiClip MODSX
MobiClip MOFLEXX
Mobotix .mxgX
Monkey’s AudioX
Motion Pixels MVIX
MOV/QuickTime/MP4XX3GP, 3GP2, PSP, iPod variants supported
MP2XX
MP3XX
MPEG-1 SystemXXmuxed audio and video, VCD format supported
MPEG-PS (program stream)XXalso known as VOB file, SVCD and DVD format supported
MPEG-TS (transport stream)XXalso known as DVB Transport Stream
MPEG-4XXMPEG-4 is a variant of QuickTime.
MSFXAudio format used on the PS3.
Mirillis FIC videoXNo cursor rendering.
MIDI Sample Dump StandardX
MIME multipart JPEGX
MSN TCP webcamXUsed by MSN Messenger webcam streams.
MTVX
MusepackX
Musepack SV8X
Material eXchange Format (MXF)XXSMPTE 377M, used by D-Cinema, broadcast industry.
Material eXchange Format (MXF), D-10 MappingXXSMPTE 386M, D-10/IMX Mapping.
NC camera feedXNC (AVIP NC4600) camera streams
NIST SPeech HEader REsourcesX
Computerized Speech Lab NSPX
NTT TwinVQ (VQF)XNippon Telegraph and Telephone Corporation TwinVQ.
Nullsoft Streaming VideoX
NuppelVideoX
NUTXXNUT Open Container Format
OggXX
Playstation Portable PMPX
Portable Voice FormatX
RK Audio (RKA)X
TechnoTrend PVAXUsed by TechnoTrend DVB PCI boards.
QCPX
raw ADTS (AAC)XX
raw AC-3XX
raw AMR-NBX
raw AMR-WBX
raw APACX
raw APVXX
raw aptXXX
raw aptX HDXX
raw BonkX
raw Chinese AVS videoXX
raw DFPWMXX
raw DiracXX
raw DNxHDXX
raw DTSXX
raw DTS-HDX
raw E-AC-3XX
raw EVCXX
raw FLACXX
raw G.728X
raw GSMX
raw H.261XX
raw H.263XX
raw H.264XX
raw HEVCXX
raw Ingenient MJPEGX
raw MJPEGXX
raw MLPX
raw MPEGX
raw MPEG-1X
raw MPEG-2X
raw MPEG-4XX
raw NULLX
raw videoXX
raw id RoQX
raw OBUXX
raw OSQX
raw SBCXX
raw ShortenX
raw TAKX
raw TrueHDXX
raw VC-1XX
raw PCM A-lawXX
raw PCM mu-lawXX
raw PCM Archimedes VIDCXX
raw PCM signed 8 bitXX
raw PCM signed 16 bit big-endianXX
raw PCM signed 16 bit little-endianXX
raw PCM signed 24 bit big-endianXX
raw PCM signed 24 bit little-endianXX
raw PCM signed 32 bit big-endianXX
raw PCM signed 32 bit little-endianXX
raw PCM signed 64 bit big-endianXX
raw PCM signed 64 bit little-endianXX
raw PCM unsigned 8 bitXX
raw PCM unsigned 16 bit big-endianXX
raw PCM unsigned 16 bit little-endianXX
raw PCM unsigned 24 bit big-endianXX
raw PCM unsigned 24 bit little-endianXX
raw PCM unsigned 32 bit big-endianXX
raw PCM unsigned 32 bit little-endianXX
raw PCM 16.8 floating point little-endianX
raw PCM 24.0 floating point little-endianX
raw PCM floating-point 32 bit big-endianXX
raw PCM floating-point 32 bit little-endianXX
raw PCM floating-point 64 bit big-endianXX
raw PCM floating-point 64 bit little-endianXX
RDTX
REDCODE R3DXFile format used by RED Digital cameras, contains JPEG 2000 frames and PCM audio.
RealMediaXX
RedirectorX
RedSparkX
Renderware TeXture DictionaryX
Resolume DXVXXEncoding is only supported for the DXT1 (Normal Quality, No Alpha) texture format.
RF64X
RL2XAudio and video format used in some games by Entertainment Software Partners.
RPL/ARMovieX
Lego Mindstorms RSOXX
RSDX
RTMPXXOutput is performed by publishing stream to RTMP server
RTPXX
RTSPXX
Sample Dump eXchangeX
SAPXX
SBGX
SDNSX
SDPX
SERX
Digital Pictures SGAX
Sega FILM/CPKXXUsed in many Sega Saturn console games.
Silicon Graphics MovieX
Sierra SOLX.sol files used in Sierra Online games.
Sierra VMDXUsed in Sierra CD-ROM games.
SmackerXMultimedia format used by many games.
SMJPEGXXUsed in certain Loki game ports.
SMPTE 337M encapsulationX
SmushXMultimedia format used in some LucasArts games.
Sony OpenMG (OMA)XXAudio format used in Sony Sonic Stage and Sony Vegas.
Sony PlayStation STRX
Sony Wave64 (W64)XX
SoX native formatXX
SUN AU formatXX
SUP raw PGS subtitlesXX
SVAGXAudio format used in Konami PS2 games.
TDSCX
Text filesX
THPXUsed on the Nintendo GameCube.
Tiertex Limited SEQXTiertex .seq files used in the DOS CD-ROM version of the game Flashback.
True AudioXX
VAGXAudio format used in many Sony PS2 games.
VC-1 test bitstreamXX
Vidvox HapXX
VivoX
VPKXAudio format used in Sony PS games.
Marble WADYX
WAVXX
Waveform ArchiverX
WavPackXX
WebMXX
Windows Televison (WTV)XX
Wing Commander III movieXMultimedia format used in Origin’s Wing Commander III computer game.
Westwood Studios audioXXMultimedia format used in Westwood Studios games.
Westwood Studios VQAXMultimedia format used in Westwood Studios games.
Wideband Single-bit Data (WSD)X
WVEX
Konami XMDX
XMVXMicrosoft video container used in Xbox games.
XVAGXAudio format used on the PS3.
xWMAXMicrosoft audio container used by XAudio 2.
eXtended BINary text (XBIN)X
YUV4MPEG pipeXX
Psygnosis YOPX
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+ +

2.2 Image Formats

+ +

FFmpeg can read and write images for each frame of a video sequence. The +following image formats are supported: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
.Y.U.VXXone raw file per component
Alias PIXXXAlias/Wavefront PIX image format
animated GIFXX
APNGXXAnimated Portable Network Graphics
BMPXXMicrosoft BMP image
BRender PIXXArgonaut BRender 3D engine image format.
CRIXCintel RAW
DPXXXDigital Picture Exchange
EXRXOpenEXR
FITSXXFlexible Image Transport System
HDRXXRadiance HDR RGBE Image format
IMGXGEM Raster image
JPEGXXProgressive JPEG is not supported.
JPEG 2000XX
JPEG-LSXX
JPEG-XSEESupported through external library libsvtjpegxs
LJPEGXLossless JPEG
Media 100X
MSPXMicrosoft Paint image
PAMXXPAM is a PNM extension with alpha support.
PBMXXPortable BitMap image
PCDXPhotoCD
PCXXXPC Paintbrush
PFMXXPortable FloatMap image
PGMXXPortable GrayMap image
PGMYUVXXPGM with U and V components in YUV 4:2:0
PGXXPGX file decoder
PHMXXPortable HalfFloatMap image
PICXPictor/PC Paint
PNGXXPortable Network Graphics image
PPMXXPortable PixelMap image
PSDXPhotoshop
PTXXV.Flash PTX format
QOIXXQuite OK Image format
SGIXXSGI RGB image format
Sun RasterfileXXSun RAS image format
TIFFXXYUV, JPEG and some extension is not supported yet.
Truevision TargaXXTarga (.TGA) image format
VBNXXVizrt Binary Image format
WBMPXXWireless Application Protocol Bitmap image format
WebPEXWebP image format, encoding supported through external library libwebp
XBMXXX BitMap image format
XFaceXXX-Face image format
XPMXX PixMap image format
XWDXXX Window Dump image format
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

2.3 Video Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
4X MovieXUsed in certain computer games.
8088flex TMVX
A64 multicolorXCreates video suitable to be played on a commodore 64 (multicolor mode).
Amazing Studio PAF VideoX
American Laser Games MMXUsed in games like Mad Dog McCree.
Amuse Graphics MovieX
AMV VideoXXUsed in Chinese MP3 players.
ANSI/ASCII artX
Apple Intermediate CodecX
Apple MJPEG-BX
Apple PixletX
Apple ProResXXfourcc: apch,apcn,apcs,apco,ap4h,ap4x
Apple QuickDrawXfourcc: qdrw
APVX
Argonaut VideoXUsed in some Argonaut games.
Asus v1XXfourcc: ASV1
Asus v2XXfourcc: ASV2
ATI VCR1Xfourcc: VCR1
ATI VCR2Xfourcc: VCR2
Auravision AuraX
Auravision Aura 2X
Autodesk Animator Flic videoX
Autodesk RLEXfourcc: AASC
AV1EESupported through external libraries libaom, libdav1d, librav1e and libsvtav1
Avid 1:1 10-bit RGB PackerXXfourcc: AVrp
AVS (Audio Video Standard) videoXVideo encoding used by the Creature Shock game.
AVS2-P2/IEEE1857.4EESupported through external libraries libxavs2 and libdavs2
AVS3-P2/IEEE1857.10ESupported through external library libuavs3d
AYUVXXMicrosoft uncompressed packed 4:4:4:4
Beam Software VBX
Bethesda VID videoXUsed in some games from Bethesda Softworks.
Bink VideoX
BitJazz SheerVideoX
Bitmap Brothers JV videoX
y41p Brooktree uncompressed 4:1:1 12-bitXX
Brooktree ProSumer VideoXfourcc: BT20
Brute Force & IgnoranceXUsed in the game Flash Traffic: City of Angels.
C93 videoXCodec used in Cyberia game.
CamStudioXfourcc: CSCD
CD+GXVideo codec for CD+G karaoke disks
CDXLXAmiga CD video codec
Chinese AVS videoEXAVS1-P2, JiZhun profile, encoding through external library libxavs
Delphine Software International CIN videoXCodec used in Delphine Software International games.
Discworld II BMV VideoX
CineForm HDXX
Canopus HQX
Canopus HQAX
Canopus HQXX
Canopus Lossless CodecX
CDToonsXCodec used in various Broderbund games.
CinepakX
Cirrus Logic AccuPakXXfourcc: CLJR
CPiA Video FormatX
Creative YUV (CYUV)X
DFAXCodec used in Chronomaster game.
DiracEXsupported though the native vc2 (Dirac Pro) encoder
Deluxe Paint AnimationX
DNxHDXXaka SMPTE VC3
Duck TrueMotion 1.0Xfourcc: DUCK
Duck TrueMotion 2.0Xfourcc: TM20
Duck TrueMotion 2.0 RTXfourcc: TR20
DV (Digital Video)XX
Dxtory capture formatX
Feeble Files/ScummVM DXAXCodec originally used in Feeble Files game.
Electronic Arts CMV videoXUsed in NHL 95 game.
Electronic Arts Madcow videoX
Electronic Arts TGV videoX
Electronic Arts TGQ videoX
Electronic Arts TQI videoX
Escape 124X
Escape 130X
EVC / MPEG-5 Part 1EEencoding and decoding supported through external libraries libxeve and libxevd
FFmpeg video codec #1XXlossless codec (fourcc: FFV1)
Flash Screen Video v1XXfourcc: FSV1
Flash Screen Video v2XX
Flash Video (FLV)XXSorenson H.263 used in Flash
FM Screen Capture CodecX
Forward UncompressedX
FrapsX
Go2MeetingXfourcc: G2M2, G2M3
Go2WebinarXfourcc: G2M4
Gremlin Digital VideoX
H.261XX
H.263 / H.263-1996XX
H.263+ / H.263-1998 / H.263 version 2XX
H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10EXencoding supported through external library libx264 and OpenH264
HEVCXXencoding supported through external library libx265 and libkvazaar
HNM version 4X
HuffYUVXX
HuffYUV FFmpeg variantXX
IBM UltimotionXfourcc: ULTI
id Cinematic videoXUsed in Quake II.
id RoQ videoXXUsed in Quake III, Jedi Knight 2, other computer games.
IFF ILBMXIFF interleaved bitmap
IFF ByteRun1XIFF run length encoded bitmap
Infinity IMM4X
Intel H.263X
Intel Indeo 2X
Intel Indeo 3X
Intel Indeo 4X
Intel Indeo 5X
Interplay C93XUsed in the game Cyberia from Interplay.
Interplay MVE videoXUsed in Interplay .MVE files.
J2KXX
Karl Morton’s video codecXCodec used in Worms games.
Kega Game Video (KGV1)XKega emulator screen capture codec.
LagarithX
LCEVC / MPEG-5 LCEVC / MPEG-5 Part 2Edecoding supported through external library liblcevc-dec
LCL (LossLess Codec Library) MSZHX
LCL (LossLess Codec Library) ZLIBEE
LEAD MCMPX
LOCOX
LucasArts SANM/SmushXUsed in LucasArts games / SMUSH animations.
lossless MJPEGXX
MagicYUV VideoXX
Mandsoft Screen Capture CodecX
Microsoft ATC ScreenXAlso known as Microsoft Screen 3.
Microsoft Expression Encoder ScreenXAlso known as Microsoft Titanium Screen 2.
Microsoft RLEXX
Microsoft Screen 1XAlso known as Windows Media Video V7 Screen.
Microsoft Screen 2XAlso known as Windows Media Video V9 Screen.
Microsoft Video 1X
MimicXUsed in MSN Messenger Webcam streams.
Miro VideoXLXfourcc: VIXL
MJPEG (Motion JPEG)XX
Mobotix MxPEG videoX
Motion Pixels videoX
MPEG-1 videoXX
MPEG-2 videoXX
MPEG-4 part 2XXlibxvidcore can be used alternatively for encoding.
MPEG-4 part 2 Microsoft variant version 1X
MPEG-4 part 2 Microsoft variant version 2XX
MPEG-4 part 2 Microsoft variant version 3XX
Newtek SpeedHQXX
Nintendo Gamecube THP videoX
NotchLCX
NuppelVideo/RTjpegXVideo encoding used in NuppelVideo files.
On2 VP3Xstill experimental
On2 VP4Xfourcc: VP40
On2 VP5Xfourcc: VP50
On2 VP6Xfourcc: VP60,VP61,VP62
On2 VP7Xfourcc: VP70,VP71
VP8EXfourcc: VP80, encoding supported through external library libvpx
VP9EXencoding supported through external library libvpx
Pinnacle TARGA CineWave YUV16Xfourcc: Y216
Q-team QPEGXfourccs: QPEG, Q1.0, Q1.1
QuickTime 8BPS videoX
QuickTime Animation (RLE) videoXXfourcc: ’rle ’
QuickTime Graphics (SMC)XXfourcc: ’smc ’
QuickTime video (RPZA)XXfourcc: rpza
R10K AJA Kona 10-bit RGB CodecXX
R210 Quicktime Uncompressed RGB 10-bitXX
Raw VideoXX
RealVideo 1.0XX
RealVideo 2.0XX
RealVideo 3.0Xstill far from ideal
RealVideo 4.0X
RealVideo 6.0X
Renderware TXD (TeXture Dictionary)XTexture dictionaries used by the Renderware Engine.
RivaTuner VideoXfourcc: ’RTV1’
RL2 videoXused in some games by Entertainment Software Partners
ScreenPressorX
ScreenpressoX
Screen Recorder Gold CodecX
Sierra VMD videoXUsed in Sierra VMD files.
Silicon Graphics Motion Video Compressor 1 (MVC1)X
Silicon Graphics Motion Video Compressor 2 (MVC2)X
Silicon Graphics RLE 8-bit videoX
Smacker videoXVideo encoding used in Smacker.
SMPTE VC-1X
SnowXXexperimental wavelet codec (fourcc: SNOW)
Sony PlayStation MDEC (Motion DECoder)X
Sorenson Vector Quantizer 1XXfourcc: SVQ1
Sorenson Vector Quantizer 3Xfourcc: SVQ3
Sunplus JPEG (SP5X)Xfourcc: SP5X
TechSmith Screen Capture CodecXfourcc: TSCC
TechSmith Screen Capture Codec 2Xfourcc: TSC2
TheoraEXencoding supported through external library libtheora
Tiertex Limited SEQ videoXCodec used in DOS CD-ROM FlashBack game.
Ut VideoXX
v210 QuickTime uncompressed 4:2:2 10-bitXX
v308 QuickTime uncompressed 4:4:4XX
v408 QuickTime uncompressed 4:4:4:4XX
v410 QuickTime uncompressed 4:4:4 10-bitXX
VBLE Lossless CodecX
vMix VideoXfourcc: ’VMX1’
VMware Screen Codec / VMware VideoXCodec used in videos captured by VMware.
Westwood Studios VQA (Vector Quantized Animation) videoX
Windows Media ImageX
Windows Media Video 7XX
Windows Media Video 8XX
Windows Media Video 9Xnot completely working
Wing Commander III / XanXUsed in Wing Commander III .MVE files.
Wing Commander IV / XanXUsed in Wing Commander IV.
Winnov WNV1X
WMV7XX
YAMAHA SMAFXX
Psygnosis YOP VideoX
yuv4XXlibquicktime uncompressed packed 4:2:0
ZeroCodec Lossless VideoX
ZLIBXXpart of LCL, encoder experimental
Zip Motion Blocks VideoXXEncoder works only in PAL8.
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+ +

2.4 Audio Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameEncodingDecodingComments
8SVX exponentialX
8SVX fibonacciX
AACEXXencoding supported through internal encoder and external library libfdk-aac
AAC+EIXencoding supported through external library libfdk-aac
AC-3IXIX
ACELP.KELVINX
ADPCM 4X MovieX
ADPCM Yamaha AICAX
ADPCM AmuseGraphics MovieX
ADPCM Argonaut GamesXX
ADPCM CDROM XAX
ADPCM Creative TechnologyX16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
ADPCM Electronic ArtsXUsed in various EA titles.
ADPCM Electronic Arts Maxis CDROM XSXUsed in Sim City 3000.
ADPCM Electronic Arts R1X
ADPCM Electronic Arts R2X
ADPCM Electronic Arts R3X
ADPCM Electronic Arts XASX
ADPCM G.722XX
ADPCM G.726XX
ADPCM IMA Acorn ReplayX
ADPCM IMA AMVXXUsed in AMV files
ADPCM IMA Cunning DevelopmentsX
ADPCM IMA Electronic Arts EACSX
ADPCM IMA Electronic Arts SEADX
ADPCM IMA FuncomX
ADPCM IMA High Voltage Software ALPXX
ADPCM IMA Mobiclip MOFLEXX
ADPCM IMA QuickTimeXX
ADPCM IMA Simon & Schuster InteractiveXX
ADPCM IMA Ubisoft APMXX
ADPCM IMA Loki SDL MJPEGX
ADPCM IMA WAVXX
ADPCM IMA WestwoodX
ADPCM ISS IMAXUsed in FunCom games.
ADPCM IMA DialogicX
ADPCM IMA Duck DK3XUsed in some Sega Saturn console games.
ADPCM IMA Duck DK4XUsed in some Sega Saturn console games.
ADPCM IMA RadicalX
ADPCM IMA XboxX
ADPCM MicrosoftXX
ADPCM MS IMAXX
ADPCM Nintendo Gamecube AFCX
ADPCM Nintendo Gamecube DTKX
ADPCM Nintendo THPX
ADPCM PlaystationX
ADPCM QT IMAXX
ADPCM SanyoX
ADPCM SEGA CRI ADXXXUsed in Sega Dreamcast games.
ADPCM Shockwave FlashXX
ADPCM Sound Blaster Pro 2-bitX
ADPCM Sound Blaster Pro 2.6-bitX
ADPCM Sound Blaster Pro 4-bitX
ADPCM VIMAXUsed in LucasArts SMUSH animations.
ADPCM Konami XMDX
ADPCM Westwood Studios IMAXXUsed in Westwood Studios games like Command and Conquer.
ADPCM YamahaXX
ADPCM ZorkX
AMR-NBEXencoding supported through external library libopencore-amrnb
AMR-WBEXencoding supported through external library libvo-amrwbenc
Amazing Studio PAF AudioX
Apple lossless audioXXQuickTime fourcc ’alac’
aptXXXUsed in Bluetooth A2DP
aptX HDXXUsed in Bluetooth A2DP
ATRAC1X
ATRAC3X
ATRAC3+X
ATRAC9X
Bink AudioXUsed in Bink and Smacker files in many games.
Bonk audioX
CELTEdecoding supported through external library libcelt
codec2EEen/decoding supported through external library libcodec2
CRI HCAX
Delphine Software International CIN audioXCodec used in Delphine Software International games.
DFPWMXX
Digital Speech Standard - Standard Play mode (DSS SP)X
Discworld II BMV AudioX
COOKXAll versions except 5.1 are supported.
DCA (DTS Coherent Acoustics)XXsupported extensions: XCh, XXCH, X96, XBR, XLL, LBR (partially)
Dolby EX
DPCM Cuberoot-Delta-ExactXUsed in few games.
DPCM GremlinX
DPCM id RoQXXUsed in Quake III, Jedi Knight 2 and other computer games.
DPCM Marble WADYX
DPCM InterplayXUsed in various Interplay computer games.
DPCM Squareroot-Delta-ExactXUsed in various games.
DPCM Sierra OnlineXUsed in Sierra Online game audio files.
DPCM SolX
DPCM XanXUsed in Origin’s Wing Commander IV AVI files.
DPCM Xilam DERFX
DSD (Direct Stream Digital), least significant bit firstX
DSD (Direct Stream Digital), most significant bit firstX
DSD (Direct Stream Digital), least significant bit first, planarX
DSD (Direct Stream Digital), most significant bit first, planarX
DSP Group TrueSpeechX
DST (Direct Stream Transfer)X
DV audioX
Enhanced AC-3XX
EVRC (Enhanced Variable Rate Codec)X
FLAC (Free Lossless Audio Codec)XIX
FTR VoiceX
G.723.1XX
G.728X
G.729X
GSMEXencoding supported through external library libgsm
GSM Microsoft variantEXencoding supported through external library libgsm
IAC (Indeo Audio Coder)X
iLBC (Internet Low Bitrate Codec)EEXencoding and decoding supported through external library libilbc
IMC (Intel Music Coder)X
Interplay ACMX
LC3EEsupported through external library liblc3
MACE (Macintosh Audio Compression/Expansion) 6:1X
Marian’s A-pac audioX
MI-SC4 (Micronas SC-4 Audio)X
MLP (Meridian Lossless Packing)XXUsed in DVD-Audio discs.
Monkey’s AudioX
MP1 (MPEG audio layer 1)IX
MP2 (MPEG audio layer 2)IXIXencoding supported also through external library TwoLAME
MP3 (MPEG audio layer 3)EIXencoding supported through external library LAME, ADU MP3 and MP3onMP4 also supported
MPEG-4 Audio Lossless Coding (ALS)X
MPEG-H 3D AudioEdecoding supported through external library libmpeghdec
MobiClip FastAudioX
Musepack SV7X
Musepack SV8X
Nellymoser AsaoXX
On2 AVC (Audio for Video Codec)X
OpusEXencoding supported through external library libopus
OSQ (Original Sound Quality)X
PCM A-lawXX
PCM mu-lawXX
PCM Archimedes VIDCXX
PCM signed 8-bit planarXX
PCM signed 16-bit big-endian planarXX
PCM signed 16-bit little-endian planarXX
PCM signed 24-bit little-endian planarXX
PCM signed 32-bit little-endian planarXX
PCM 32-bit floating point big-endianXX
PCM 32-bit floating point little-endianXX
PCM 64-bit floating point big-endianXX
PCM 64-bit floating point little-endianXX
PCM D-Cinema audio signed 24-bitXX
PCM signed 8-bitXX
PCM signed 16-bit big-endianXX
PCM signed 16-bit little-endianXX
PCM signed 24-bit big-endianXX
PCM signed 24-bit little-endianXX
PCM signed 32-bit big-endianXX
PCM signed 32-bit little-endianXX
PCM signed 16/20/24-bit big-endian in MPEG-TSX
PCM unsigned 8-bitXX
PCM unsigned 16-bit big-endianXX
PCM unsigned 16-bit little-endianXX
PCM unsigned 24-bit big-endianXX
PCM unsigned 24-bit little-endianXX
PCM unsigned 32-bit big-endianXX
PCM unsigned 32-bit little-endianXX
PCM SGAX
QCELP / PureVoiceX
QDesign Music Codec 1X
QDesign Music Codec 2XThere are still some distortions.
RealAudio 1.0 (14.4K)XXReal 14400 bit/s codec
RealAudio 2.0 (28.8K)XReal 28800 bit/s codec
RealAudio 3.0 (dnet)IXXReal low bitrate AC-3 codec
RealAudio LosslessX
RealAudio SIPR / ACELP.NETX
RK Audio (RKA)X
SBC (low-complexity subband codec)XXUsed in Bluetooth A2DP
ShortenX
Sierra VMD audioXUsed in Sierra VMD files.
Smacker audioX
SMPTE 302M AES3 audioXX
SonicXXexperimental codec
Sonic losslessXXexperimental codec
SpeexEEXsupported through external library libspeex
TAK (Tom’s lossless Audio Kompressor)X
True Audio (TTA)XX
TrueHDXXUsed in HD-DVD and Blu-Ray discs.
TwinVQ (VQF flavor)X
VIMAXUsed in LucasArts SMUSH animations.
ViewQuest VQCX
VorbisEXA native but very primitive encoder exists.
Voxware MetaSoundX
Waveform ArchiverX
WavPackXX
Westwood Audio (SND1)X
Windows Media Audio 1XX
Windows Media Audio 2XX
Windows Media Audio LosslessX
Windows Media Audio ProX
Windows Media Audio VoiceX
Xbox Media Audio 1X
Xbox Media Audio 2X
+ +

X means that the feature in that column (encoding / decoding) is supported. +

+

E means that support is provided through an external library. +

+

I means that an integer-only version is available, too (ensures high +performance on systems without hardware floating point support). +

+ +

2.5 Subtitle Formats

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameMuxingDemuxingEncodingDecoding
3GPP Timed TextXX
AQTitleXX
DVBXXXX
DVB teletextXE
DVDXXXX
JACOsubXXX
MicroDVDXXX
MPL2XX
MPsub (MPlayer)XX
PGSX
PJS (Phoenix)XX
RealTextXX
SAMIXX
Spruce format (STL)XX
SSA/ASSXXXX
SubRip (SRT)XXXX
SubViewer v1XX
SubViewerXX
TED Talks captionsXX
TTMLXX
VobSub (IDX+SUB)XX
VPlayerXX
WebVTTXXXX
XSUBXX
+ +

X means that the feature is supported. +

+

E means that support is provided through an external library. +

+ +

2.6 Network Protocols

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSupport
AMQPE
fileX
FTPX
GopherX
GophersX
HLSX
HTTPX
HTTPSX
IcecastX
MMSHX
MMSTX
pipeX
Pro-MPEG FECX
RTMPX
RTMPEX
RTMPSX
RTMPTX
RTMPTEX
RTMPTSX
RTPX
SAMBAE
SCTPX
SFTPE
TCPX
TLSX
UDPX
ZMQE
+ +

X means that the protocol is supported. +

+

E means that support is provided through an external library. +

+ + +

2.7 Input/Output Devices

+ + + + + + + + + + + + + + + + + + + + + + +
NameInputOutput
ALSAXX
BKTRX
cacaX
DV1394X
Lavfi virtual deviceX
Linux framebufferXX
JACKX
LIBCDIOX
LIBDC1394X
OpenALX
OpenGLX
OSSXX
PulseAudioXX
SDLX
Video4Linux2XX
VfW captureX
X11 grabbingX
Win32 grabbingX
+ +

X means that input/output is supported. +

+ +

2.8 Timecode

+ + + + + + + + + + +
Codec/formatReadWrite
AVIXX
DVXX
GXFXX
MOVXX
MPEG1/2XX
MXFXX
+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/git-howto.html b/ffmpeg-n8.1/doc/git-howto.html new file mode 100644 index 00000000..ded00ca0 --- /dev/null +++ b/ffmpeg-n8.1/doc/git-howto.html @@ -0,0 +1,562 @@ + + + + + + + Using Git to develop FFmpeg + + + + + + +
+

+ Using Git to develop FFmpeg +

+ + + + + + + + +

1 Introduction

+ +

This document aims in giving some quick references on a set of useful Git +commands. You should always use the extensive and detailed documentation +provided directly by Git: +

+
+
git --help
+man git
+
+ +

shows you the available subcommands, +

+
+
git <command> --help
+man git-<command>
+
+ +

shows information about the subcommand <command>. +

+

Additional information could be found on the +Git Reference website. +

+

For more information about the Git project, visit the +Git website. +

+

Consult these resources whenever you have problems, they are quite exhaustive. +

+

What follows now is a basic introduction to Git and some FFmpeg-specific +guidelines to ease the contribution to the project. +

+ +

2 Basics Usage

+ + +

2.1 Get Git

+ +

You can get Git from http://git-scm.com/ +Most distribution and operating system provide a package for it. +

+ + +

2.2 Cloning the source tree

+ +
+
git clone https://git.ffmpeg.org/ffmpeg.git <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. +

+
+
git clone git@ffmpeg.org:ffmpeg-web <target>
+
+ +

This will put the source of the FFmpeg website into the directory +<target> and let you push back your changes to the remote repository. +

+

If you don’t have write-access to the ffmpeg-web repository, you can +create patches after making a read-only ffmpeg-web clone: +

+
+
git clone git://ffmpeg.org/ffmpeg-web <target>
+
+ +

Make sure that you do not have Windows line endings in your checkouts, +otherwise you may experience spurious compilation failures. One way to +achieve this is to run +

+
+
git config --global core.autocrlf false
+
+ + + +

2.3 Updating the source tree to the latest revision

+ +
+
git pull (--rebase)
+
+ +

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. +

+
+

--rebase (see below) is recommended. +

+ +

2.4 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. +

+ + +

2.5 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. +

+ + +

2.6 Showing modifications

+ +
+
git diff <filename(s)>
+
+ +

will show all local modifications in your working directory as unified diff. +

+ + +

2.7 Inspecting the changelog

+ +
+
git log <filename(s)>
+
+ +

You may also use the graphical tools like gitview or gitk +or the web interface available at https://git.ffmpeg.org/ffmpeg.git. +

+ +

2.8 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.). +

+ + +

2.9 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, email address and GPG key +

+
+
git config --global user.name "My Name"
+git config --global user.email my@email.invalid
+git config --global user.signingkey ABCDEF0123245
+
+ +

Enable signing all commits or use -S +

+
+
git config --global commit.gpgsign true
+
+ +

Use --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 --global core.editor
+
+ +

or set by one of the following environment variables: +GIT_EDITOR, VISUAL or EDITOR. +

+ +

2.10 Writing a commit message

+ +

Log messages should be concise but descriptive. +

+

The first line must contain the context, a colon and a very short +summary of what the commit does. Details can be added, if necessary, +separated by an empty line. These details should not exceed 60-72 characters +per line, except when containing code. +

+

Example of a good commit message: +

+
+
avcodec/cbs: add a helper to read extradata within packet side data
+
+Using ff_cbs_read() on the raw buffer will not parse it as extradata,
+resulting in parsing errors for example when handling ISOBMFF avcC.
+This helper works around that.
+
+ +
+
ptr might be NULL
+
+ +

If the summary on the first line is not enough, in the body of the message, +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 except in +the context, Git provides that information. +

+

If the commit fixes a registered issue, state it in a separate line of the +body: Fix Trac ticket #42. +

+

The first line will be used to name +the patch by git format-patch. +

+

Common mistakes for the first line, as seen in git log --oneline +include: missing context at the beginning; description of what the code did +before the patch; line too long or wrapped to the second line. +

+ +

2.11 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. +

+ +

2.12 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). +

+ + +

2.13 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
+
+ + + +

3 Git configuration

+ +

In order to simplify a few workflows, it is advisable to configure both +your personal Git installation and your local FFmpeg repository. +

+ +

3.1 Personal Git installation

+ +

Add the following to your ~/.gitconfig to help git send-email +and git format-patch detect renames: +

+
+
[diff]
+        renames = copy
+
+ + +

3.2 Repository configuration

+ +

In order to have git send-email automatically send patches +to the ffmpeg-devel mailing list, add the following stanza +to /path/to/ffmpeg/repository/.git/config: +

+
+
[sendemail]
+        to = ffmpeg-devel@ffmpeg.org
+
+ + +

4 FFmpeg specific

+ + +

4.1 Reverting broken commits

+ +
+
git reset <commit>
+
+ +

git reset will uncommit the changes till <commit> rewriting +the current branch history. +

+
+
git commit --amend
+
+ +

allows one 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. +

+
+

git reset, git commit --amend and git rebase +rewrite history, so you should use them ONLY on your local or topic branches. +The main repository will reject those changes. +

+
+
git revert <commit>
+
+ +

git revert will generate a revert commit. This will not make the +faulty commit disappear from the history. +

+ +

4.2 Pushing changes to remote trees

+ +
+
git push origin master --dry-run
+
+ +

Will simulate a push of the local master branch to the default remote +(origin). And list which branches and ranges or commits would have been +pushed. +Git will prevent you from pushing changes if the local and remote trees are +out of sync. Refer to Updating the source tree to the latest revision. +

+
+
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. +

+ +

4.3 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 hash from the git log output. +

+ + +

5 gpg key generation

+ +

If you have no gpg key yet, we recommend that you create a ed25519 based key as it +is small, fast and secure. Especially it results in small signatures in git. +

+
+
gpg --default-new-key-algo "ed25519/cert,sign+cv25519/encr" --quick-generate-key "human@server.com"
+
+ +

When generating a key, make sure the email specified matches the email used in git as some sites like +github consider mismatches a reason to declare such commits unverified. After generating a key you +can add it to the MAINTAINER file and upload it to a keyserver. +

+ +

6 Pre-push checklist

+ +

Once you have a set of commits that you feel are ready for pushing, +work through the following checklist to doublecheck everything is in +proper order. This list tries to be exhaustive. In case you are just +pushing a typo in a comment, some of the steps may be unnecessary. +Apply your common sense, but if in doubt, err on the side of caution. +

+

First, make sure that the commits and branches you are going to push +match what you want pushed and that nothing is missing, extraneous or +wrong. You can see what will be pushed by running the git push command +with --dry-run first. And then inspecting the commits listed with +git log -p 1234567..987654. The git status command +may help in finding local changes that have been forgotten to be added. +

+

Next let the code pass through a full run of our test suite. +

+
    +
  • make distclean +
  • /path/to/ffmpeg/configure +
  • make fate +
  • if fate fails due to missing samples run make fate-rsync and retry +
+ +

Make sure all your changes have been checked before pushing them, the +test suite only checks against regressions and that only to some extend. It does +obviously not check newly added features/code to be working unless you have +added a test for that (which is recommended). +

+

Also note that every single commit should pass the test suite, not just +the result of a series of patches. +

+

Once everything passed, push the changes to your public ffmpeg clone and post a +merge request to ffmpeg-devel. You can also push them directly but this is not +recommended. +

+ +

7 Server Issues

+ +

Contact the project admins at if you have technical +problems with the Git server. +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libavcodec.html b/ffmpeg-n8.1/doc/libavcodec.html new file mode 100644 index 00000000..5a81c69f --- /dev/null +++ b/ffmpeg-n8.1/doc/libavcodec.html @@ -0,0 +1,74 @@ + + + + + + + Libavcodec Documentation + + + + + + +
+

+ Libavcodec Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The libavcodec library provides a generic encoding/decoding framework +and contains multiple decoders and encoders for audio, video and +subtitle streams, and several bitstream filters. +

+

The shared architecture provides various services ranging from bit +stream I/O to DSP optimizations, and makes it suitable for +implementing robust and fast codecs as well as for experimentation. +

+ + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-codecs, bitstream-filters, +libavutil +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libavdevice.html b/ffmpeg-n8.1/doc/libavdevice.html new file mode 100644 index 00000000..05608a1c --- /dev/null +++ b/ffmpeg-n8.1/doc/libavdevice.html @@ -0,0 +1,71 @@ + + + + + + + Libavdevice Documentation + + + + + + +
+

+ Libavdevice Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The libavdevice library provides a generic framework for grabbing from +and rendering to many common multimedia input/output devices, and +supports several input and output devices, including Video4Linux2, +VfW, DShow, and ALSA. +

+ + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-devices, +libavutil, libavcodec, libavformat +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libavfilter.html b/ffmpeg-n8.1/doc/libavfilter.html new file mode 100644 index 00000000..f284c718 --- /dev/null +++ b/ffmpeg-n8.1/doc/libavfilter.html @@ -0,0 +1,70 @@ + + + + + + + Libavfilter Documentation + + + + + + +
+

+ Libavfilter Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The libavfilter library provides a generic audio/video filtering +framework containing several filters, sources and sinks. +

+ + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-filters, +libavutil, libswscale, libswresample, +libavcodec, libavformat, libavdevice +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libavformat.html b/ffmpeg-n8.1/doc/libavformat.html new file mode 100644 index 00000000..b5324ed2 --- /dev/null +++ b/ffmpeg-n8.1/doc/libavformat.html @@ -0,0 +1,74 @@ + + + + + + + Libavformat Documentation + + + + + + +
+

+ Libavformat Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The libavformat library provides a generic framework for multiplexing +and demultiplexing (muxing and demuxing) audio, video and subtitle +streams. It encompasses multiple muxers and demuxers for multimedia +container formats. +

+

It also supports several input and output protocols to access a media +resource. +

+ + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-formats, ffmpeg-protocols, +libavutil, libavcodec +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libavutil.html b/ffmpeg-n8.1/doc/libavutil.html new file mode 100644 index 00000000..cb9b93f4 --- /dev/null +++ b/ffmpeg-n8.1/doc/libavutil.html @@ -0,0 +1,93 @@ + + + + + + + Libavutil Documentation + + + + + + +
+

+ Libavutil Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

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). It is not a library for +code needed by both libavcodec and libavformat. +

+

The goals for this library is to be: +

+
+
Modular
+

It should have few interdependencies and the possibility of disabling individual +parts during ./configure. +

+
+
Small
+

Both sources and objects should be small. +

+
+
Efficient
+

It should have low CPU and memory usage. +

+
+
Useful
+

It should avoid useless features that almost no one needs. +

+
+ + + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-utils +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libswresample.html b/ffmpeg-n8.1/doc/libswresample.html new file mode 100644 index 00000000..dd9bda56 --- /dev/null +++ b/ffmpeg-n8.1/doc/libswresample.html @@ -0,0 +1,93 @@ + + + + + + + Libswresample Documentation + + + + + + +
+

+ Libswresample Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The libswresample library performs highly optimized audio resampling, +rematrixing and sample format conversion operations. +

+

Specifically, this library performs the following conversions: +

+
    +
  • Resampling: is the process of changing the audio rate, for +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. + +
  • Format conversion: is the process of converting the type of +samples, for example from 16-bit signed samples to unsigned 8-bit or +float samples. It also handles packing conversion, when passing from +packed layout (all samples belonging to distinct channels interleaved +in the same buffer), to planar layout (all samples belonging to the +same channel stored in a dedicated buffer or "plane"). + +
  • Rematrixing: is the process of changing the channel layout, for +example from stereo to mono. When the input channels cannot be mapped +to the output streams, the process is lossy, since it involves +different gain factors and mixing. +
+ +

Various other audio conversions (e.g. stretching and padding) are +enabled through dedicated options. +

+ + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-resampler, +libavutil +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/libswscale.html b/ffmpeg-n8.1/doc/libswscale.html new file mode 100644 index 00000000..1c0b9392 --- /dev/null +++ b/ffmpeg-n8.1/doc/libswscale.html @@ -0,0 +1,87 @@ + + + + + + + Libswscale Documentation + + + + + + +
+

+ Libswscale Documentation +

+ + + + +
+

Table of Contents

+ + +
+ + +

1 Description

+ +

The libswscale library performs highly optimized image scaling and +colorspace and pixel format conversion operations. +

+

Specifically, this library performs the following conversions: +

+
    +
  • Rescaling: is the process of changing the video size. Several +rescaling options and algorithms are available. This is usually a +lossy process. + +
  • Pixel format conversion: is the process of converting the image +format and colorspace of the image, for example from planar YUV420P to +RGB24 packed. It also handles packing conversion, that is converts +from packed layout (all pixels belonging to distinct planes +interleaved in the same buffer), to planar layout (all samples +belonging to the same plane stored in a dedicated buffer or "plane"). + +

    This is usually a lossy process in case the source and destination +colorspaces differ. +

+ + + +

2 See Also

+ +

ffmpeg, ffplay, ffprobe, +ffmpeg-scaler, +libavutil +

+ + +

3 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(https://git.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at https://git.ffmpeg.org/ffmpeg. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ +

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/mailing-list-faq.html b/ffmpeg-n8.1/doc/mailing-list-faq.html new file mode 100644 index 00000000..ccee49a7 --- /dev/null +++ b/ffmpeg-n8.1/doc/mailing-list-faq.html @@ -0,0 +1,443 @@ + + + + + + + FFmpeg Mailing List FAQ + + + + + + +
+

+ FFmpeg Mailing List FAQ +

+ + + + + + + +

1 General Questions

+ + +

1.1 What is a mailing list?

+ +

A mailing list is not much different than emailing someone, but the +main difference is that your message is received by everyone who +subscribes to the list. It is somewhat like a forum but in email form. +

+

See the ffmpeg-user archives +for examples. +

+ +

1.2 What type of questions can I ask?

+ +
    +
  • ffmpeg-user: +For questions involving unscripted usage or compilation of the FFmpeg +command-line tools (ffmpeg, ffprobe, ffplay). + +
  • libav-user: +For questions involving the FFmpeg libav* libraries (libavcodec, +libavformat, libavfilter, etc). + +
  • ffmpeg-devel: +For discussions involving the development of FFmpeg and for submitting +patches. User questions should be asked at ffmpeg-user or libav-user. +
+ +

To report a bug see https://ffmpeg.org/bugreports.html. +

+

We cannot provide help for scripts and/or third-party tools. +

+ +

1.3 How do I ask a question or send a message to a mailing list?

+ +

First you must subscribe. Then all you have to do is +send an email: +

+ + + +

2 Subscribing / Unsubscribing

+ + +

2.1 How do I subscribe?

+ +

Email with the subject +subscribe. +

+

Or visit the ffmpeg-user mailing list info page +and refer to the Subscribing to ffmpeg-user section. +

+

The process is the same for the other mailing lists. +

+ +

2.2 How do I unsubscribe?

+ +

Email with subject unsubscribe. +

+

Or visit the ffmpeg-user mailing list info page, +scroll to bottom of page, enter your email address in the box, and click +the Unsubscribe or edit options button. +

+

The process is the same for the other mailing lists. +

+

Please avoid asking a mailing list admin to unsubscribe you unless you +are absolutely unable to do so by yourself. See Who do I contact if I have a problem with the mailing list? +

+

Note that it is possible to temporarily halt message delivery (vacation mode). +See How do I disable mail delivery without unsubscribing? +

+ +

3 Moderation Queue

+ +

3.1 Why is my message awaiting moderator approval?

+ +

Some messages are automatically held in the moderation queue and +must be manually approved by a mailing list admin: +

+

These are: +

+
    +
  • Messages that exceed the message size limit. + +
  • Messages from users whose accounts have been set with the moderation flag +(very rarely occurs, but may if a user repeatedly ignores the rules +or is abusive towards others). +
+ + +

3.2 How long does it take for my message in the moderation queue to be approved?

+ +

The queue is not checked on a regular basis. You can ask on the +#ffmpeg-devel IRC channel on Libera Chat for someone to approve your message. +

+ +

3.3 How do I delete my message in the moderation queue?

+ +

You should have received an email with the subject Your message to <mailing list name> awaits moderator approval. +A link is in the message that will allow you to delete your message +unless a mailing list admin already approved or rejected it. +

+ +

4 Archives

+ + +

4.1 Where are the archives?

+ +

See the Archives section on the FFmpeg Contact +page for links to all FFmpeg mailing list archives. +

+

Note that the archives are split by month. Discussions that span +several months will be split into separate months in the archives. +

+ +

4.2 How do I reply to a message in the archives?

+ +

Click the email link at the top of the message just under the subject +title. The link will provide the proper headers to keep the message +within the thread. +

+

Note that you must be subscribed to send a message to the ffmpeg-user or +libav-user mailing lists. +

+ +

4.3 How do I search the archives?

+ +

Perform a site search using your favorite search engine. Example: +

+

site:lists.ffmpeg.org/pipermail/ffmpeg-user/ "search term" +

+ +

5 Other

+ + +

5.1 Is there an alternative to the mailing list?

+ +

You can ask for help in the official #ffmpeg IRC channel on Libera Chat. +

+

There are also numerous third-party help sites such as +Super User and +r/ffmpeg on reddit. +

+ +

5.2 What is top-posting?

+ +

See https://en.wikipedia.org/wiki/Posting_style#Top-posting. +

+

Instead, use trimmed interleaved/inline replies (example). +

+ +

5.3 What is the message size limit?

+ +

The message size limit is 1000 kilobytes. Please provide links to larger files +instead of attaching them. +

+ +

5.4 Where can I upload sample files?

+ +

Anywhere that is not too annoying for us to use. +

+

Google Drive and Dropbox are acceptable if you need a file host, and +0x0.st is good for files under 256 MiB. +

+

Small, short samples are preferred if possible. +

+ +

5.5 Will I receive spam if I send and/or subscribe to a mailing list?

+ +

Highly unlikely. +

+
    +
  • The list of subscribed users is not public. + +
  • Email addresses in the archives are obfuscated. + +
  • Several unique test email accounts were utilized and none have yet +received any spam. +
+ +

However, you may see a spam in the mailing lists on rare occasions: +

+
    +
  • Spam in the moderation queue may be accidentally approved due to human +error. + +
  • There have been a few messages from subscribed users who had their own +email addresses hacked and spam messages from (or appearing to be from) +the hacked account were sent to their contacts (a mailing list being a +contact in these cases). + +
  • If you are subscribed to the bug tracker mailing list (ffmpeg-trac) you +may see the occasional spam as a false bug report, but we take measures +to try to prevent this. +
+ + +

5.6 How do I filter mailing list messages?

+ +

Use the List-Id. For example, the ffmpeg-user mailing list is +ffmpeg-user.ffmpeg.org. You can view the List-Id in the raw message +or headers. +

+

You can then filter the mailing list messages to their own folder. +

+ +

5.7 How do I disable mail delivery without unsubscribing?

+ +

Sometimes you may want to temporarily stop receiving all mailing list +messages. This "vacation mode" is simple to do: +

+
    +
  1. Go to the ffmpeg-user mailing list info page + +
  2. Enter your email address in the box at very bottom of the page and click the +Unsubscribe or edit options box. + +
  3. Enter your password and click the Log in button. + +
  4. Look for the Mail delivery option. Here you can disable/enable mail +delivery. If you check Set globally it will apply your choice to all +other FFmpeg mailing lists you are subscribed to. +
+ +

Alternatively, from your subscribed address, send a message to +with the subject set delivery off. To re-enable mail delivery send a +message to with the subject +set delivery on. +

+ +

5.8 Why is the mailing list munging my address?

+ +

This is due to subscribers that use an email service with a DMARC reject policy +which adds difficulties to mailing list operators. +

+

The mailing list must re-write (munge) the From: header for such users; +otherwise their email service will reject and bounce the message resulting in +automatic unsubscribing from the mailing list. +

+

When sending a message these users will see via <mailing list name> +added to their name and the From: address munged to the address of +the particular mailing list. +

+

If you want to avoid this then please use a different email service. +

+

Note that ffmpeg-devel does not apply any munging as it causes issues with +patch authorship. As a result users with an email service with a DMARC reject +policy may be automatically unsubscribed due to rejected and bounced messages. +

+ +

6 Rules and Etiquette

+ + +

6.1 What are the rules and the proper etiquette?

+ +

There may seem to be many things to remember, but we want to help and +following these guidelines will allow you to get answers more quickly +and help avoid getting ignored. +

+
    +
  • Always show your actual, unscripted ffmpeg command and the +complete, uncut console output from your command. + +
  • Use the most simple and minimal command that still shows the issue you +are encountering. + +
  • Provide all necessary information so others can attempt to duplicate +your issue. This includes the actual command, complete uncut console +output, and any inputs that are required to duplicate the issue. + +
  • Use the latest ffmpeg build you can get. See the FFmpeg Download +page for links to recent builds for Linux, macOS, and Windows. Or +compile from the current git master branch. + +
  • Avoid top-posting. +Also see What is top-posting? + +
  • Avoid hijacking threads. Thread hijacking is replying to a message and +changing the subject line to something unrelated to the original thread. +Most email clients will still show the renamed message under the +original thread. This can be confusing and these types of messages are +often ignored. + +
  • Do not send screenshots. Copy and paste console text instead of making +screenshots of the text. + +
  • Avoid sending email disclaimers and legalese if possible as this is a +public list. + +
  • Avoid using the -loglevel debug, -loglevel quiet, and +-hide_banner options unless requested to do so. + +
  • If you attach files avoid compressing small files. Uncompressed is +preferred. + +
  • Please do not send HTML-only messages. The mailing list will ignore the +HTML component of your message. Most mail clients will automatically +include a text component: this is what the mailing list will use. + +
  • Configuring your mail client to break lines after 70 or so characters is +recommended. + +
  • Avoid sending the same message to multiple mailing lists. + +
  • Please follow our Code of Conduct. +
+ + +

7 Help

+ + +

7.1 Why am I not receiving any messages?

+ +

Some email providers have blacklists or spam filters that block or mark +the mailing list messages as false positives. Unfortunately, the user is +often not aware of this and is often out of their control. +

+

When possible we attempt to notify the provider to be removed from the +blacklists or filters. +

+ +

7.2 Why are my sent messages not showing up?

+ +

Excluding messages that are held in the moderation queue +there are a few other reasons why your messages may fail to appear: +

+
    +
  • HTML-only messages are ignored by the mailing lists. Most mail clients +automatically include a text component alongside HTML email: this is what +the mailing list will use. If it does not then consider your client to be +broken, because sending a text component along with the HTML component to +form a multi-part message is recommended by email standards. + +
  • Check your spam folder. +
+ + +

7.3 Why do I keep getting unsubscribed from ffmpeg-devel?

+ +

Users with an email service that has a DMARC reject or quarantine policy may be +automatically unsubscribed from the ffmpeg-devel mailing list due to the mailing +list messages being continuously rejected and bounced back. +

+

Consider using a different email service. +

+ +

7.4 Who do I contact if I have a problem with the mailing list?

+ +

Send a message to . +

+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/nut.html b/ffmpeg-n8.1/doc/nut.html new file mode 100644 index 00000000..8a89696a --- /dev/null +++ b/ffmpeg-n8.1/doc/nut.html @@ -0,0 +1,213 @@ + + + + + + + NUT + + + + + + +
+

+ NUT +

+ + + + + + + + +

1 Description

+

NUT is a low overhead generic container format. It stores audio, video, +subtitle and user-defined streams in a simple, yet efficient, way. +

+

It was created by a group of FFmpeg and MPlayer developers in 2003 +and was finalized in 2008. +

+

The official nut specification is at svn://svn.mplayerhq.hu/nut +In case of any differences between this text and the official specification, +the official specification shall prevail. +

+ +

2 Modes

+

NUT has some variants signaled by using the flags field in its main header. +

+ + + + +
BROADCASTExtend the syncpoint to report the sender wallclock
PIPEOmit completely the syncpoint
+ + +

2.1 BROADCAST

+ +

The BROADCAST variant provides a secondary time reference to facilitate +detecting endpoint latency and network delays. +It assumes all the endpoint clocks are synchronized. +To be used in real-time scenarios. +

+ +

2.2 PIPE

+ +

The PIPE variant assumes NUT is used as non-seekable intermediate container, +by not using syncpoint removes unneeded overhead and reduces the overall +memory usage. +

+ +

3 Container-specific codec tags

+ + +

3.1 Generic raw YUVA formats

+ +

Since many exotic planar YUVA pixel formats are not considered by +the AVI/QuickTime FourCC lists, the following scheme is adopted for +representing them. +

+

The first two bytes can contain the values: +Y1 = only Y +Y2 = Y+A +Y3 = YUV +Y4 = YUVA +

+

The third byte represents the width and height chroma subsampling +values for the UV planes, that is the amount to shift the luma +width/height right to find the chroma width/height. +

+

The fourth byte is the number of bits used (8, 16, ...). +

+

If the order of bytes is inverted, that means that each component has +to be read big-endian. +

+ +

3.2 Raw Audio

+ + + + + + + +
ALAWA-LAW
ULAWMU-LAW
P<type><interleaving><bits>little-endian PCM
<bits><interleaving><type>Pbig-endian PCM
+ +

<type> is S for signed integer, U for unsigned integer, F for IEEE float +<interleaving> is D for default, P is for planar. +<bits> is 8/16/24/32 +

+
+
PFD[32]   would for example be signed 32 bit little-endian IEEE float
+
+ + +

3.3 Subtitles

+ + + + + + + +
UTF8Raw UTF-8
SSA[0]SubStation Alpha
DVDSDVD subtitles
DVBSDVB subtitles
+ + +

3.4 Raw Data

+ + + + +
UTF8Raw UTF-8
+ + +

3.5 Codecs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
3IV1non-compliant MPEG-4 generated by old 3ivx
ASV1Asus Video
ASV2Asus Video 2
CVIDCinepak
CYUVCreative YUV
DIVXnon-compliant MPEG-4 generated by old DivX
DUCKTruemotion 1
FFV1FFmpeg video 1
FFVHFFmpeg Huffyuv
H261ITU H.261
H262ITU H.262
H263ITU H.263
H264ITU H.264
HFYUHuffyuv
I263Intel H.263
IV31Indeo 3.1
IV32Indeo 3.2
IV50Indeo 5.0
LJPGITU JPEG (lossless)
MJLSITU JPEG-LS
MJPGITU JPEG
MPG4MS MPEG-4v1 (not ISO MPEG-4)
MP42MS MPEG-4v2
MP43MS MPEG-4v3
MP4VISO MPEG-4 Part 2 Video (from old encoders)
mpg1ISO MPEG-1 Video
mpg2ISO MPEG-2 Video
MRLEMS RLE
MSVCMS Video 1
RT21Indeo 2.1
RV10RealVideo 1.0
RV20RealVideo 2.0
RV30RealVideo 3.0
RV40RealVideo 4.0
SNOWFFmpeg Snow
SVQ1Sorenson Video 1
SVQ3Sorenson Video 3
theoXiph Theora
TM20Truemotion 2.0
UMP4non-compliant MPEG-4 generated by UB Video MPEG-4
VCR1ATI VCR1
VP30VP 3.0
VP31VP 3.1
VP50VP 5.0
VP60VP 6.0
VP61VP 6.1
VP62VP 6.2
VP70VP 7.0
WMV1MS WMV7
WMV2MS WMV8
WMV3MS WMV9
WV1Fnon-compliant MPEG-4 generated by ?
WVC1VC-1
XVIDnon-compliant MPEG-4 generated by old Xvid
XVIXnon-compliant MPEG-4 generated by old Xvid with interlacing bug
+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/platform.html b/ffmpeg-n8.1/doc/platform.html new file mode 100644 index 00000000..1a1e14d4 --- /dev/null +++ b/ffmpeg-n8.1/doc/platform.html @@ -0,0 +1,408 @@ + + + + + + + Platform Specific Information + + + + + + +
+

+ Platform Specific Information +

+ + + + + + + +

1 Unix-like

+ +

Some parts of FFmpeg cannot be built with version 2.15 of the GNU +assembler which is still provided by a few AMD64 distributions. To +make sure your compiler really uses the required version of gas +after a binutils upgrade, run: +

+
+
$(gcc -print-prog-name=as) --version
+
+ +

If not, then you should install a different compiler that has no +hard-coded path to gas. In the worst case pass --disable-asm +to configure. +

+ +

1.1 Advanced linking configuration

+ +

If you compiled FFmpeg libraries statically and you want to use them to +build your own shared library, you may need to force PIC support (with +--enable-pic during FFmpeg configure) and add the following option +to your project LDFLAGS: +

+
+
-Wl,-Bsymbolic
+
+ +

If your target platform requires position independent binaries, you should +pass the correct linking flag (e.g. -pie) to --extra-ldexeflags. +

+ +

1.2 BSD

+ +

BSD make will not build FFmpeg, you need to install and use GNU Make +(gmake). +

+ +

1.3 (Open)Solaris

+ +

GNU Make is required to build FFmpeg, so you have to invoke (gmake), +standard Solaris Make will not work. When building with a non-c99 front-end +(gcc, generic suncc) add either --extra-libs=/usr/lib/values-xpg6.o +or --extra-libs=/usr/lib/64/values-xpg6.o to the configure options +since the libc is not c99-compliant by default. The probes performed by +configure may raise an exception leading to the death of configure itself +due to a bug in the system shell. Simply invoke a different shell such as +bash directly to work around this: +

+
+
bash ./configure
+
+ + +

1.4 Darwin (Mac OS X, iPhone)

+ +

The toolchain provided with Xcode is sufficient to build the basic +unaccelerated code. +

+

Mac OS X on PowerPC or ARM (iPhone) requires a preprocessor from +https://github.com/FFmpeg/gas-preprocessor or +https://github.com/yuvi/gas-preprocessor(currently outdated) to build the optimized +assembly functions. Put the Perl script somewhere +in your PATH, FFmpeg’s configure will pick it up automatically. +

+

Mac OS X on amd64 and x86 requires nasm to build most of the +optimized assembly functions. Fink, +Gentoo Prefix, +Homebrew +or MacPorts can easily provide it. +

+ + +

2 DOS

+ +

Using a cross-compiler is preferred for various reasons. +http://www.delorie.com/howto/djgpp/linux-x-djgpp.html +

+ + +

3 OS/2

+ +

For information about compiling FFmpeg on OS/2 see +http://www.edm2.com/index.php/FFmpeg. +

+ + +

4 Windows

+ + +

4.1 Native Windows compilation using MinGW or MinGW-w64

+ +

FFmpeg can be built to run natively on Windows using the MinGW-w64 +toolchain. Install the latest versions of MSYS2 and MinGW-w64 from +http://msys2.github.io/ and/or http://mingw-w64.sourceforge.net/. +You can find detailed installation instructions in the download section and +the FAQ. +

+

Notes: +

+
    +
  • Building for the MSYS environment is discouraged, MSYS2 provides a full +MinGW-w64 environment through mingw64_shell.bat or +mingw32_shell.bat that should be used instead of the environment +provided by msys2_shell.bat. + +
  • Building using MSYS2 can be sped up by disabling implicit rules in the +Makefile by calling make -r instead of plain make. This +speed up is close to non-existent for normal one-off builds and is only +noticeable when running make for a second time (for example during +make install). + +
  • In order to compile FFplay, you must have the MinGW development library +of SDL and pkg-config installed. + +
  • By using ./configure --enable-shared when configuring FFmpeg, +you can build the FFmpeg libraries (e.g. libavutil, libavcodec, +libavformat) as DLLs. + +
+ + +

4.1.1 Native Windows compilation using MSYS2

+ +

The MSYS2 MinGW-w64 environment provides ready to use toolchains and dependencies +through pacman. +

+

Make sure to use mingw64_shell.bat or mingw32_shell.bat to have +the correct MinGW-w64 environment. The default install provides shortcuts to +them under MinGW-w64 Win64 Shell and MinGW-w64 Win32 Shell. +

+
+
# normal msys2 packages
+pacman -S make pkgconf diffutils
+
+# mingw-w64 packages and toolchains
+pacman -S mingw-w64-x86_64-nasm mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2
+
+ +

To target 32 bits replace x86_64 with i686 in the command above. +

+ +

4.2 Microsoft Visual C++ or Intel C++ Compiler for Windows

+ +

FFmpeg can be built with MSVC 2013 or later. +

+

You will need the following prerequisites: +

+
    +
  • MSYS2 +
  • NASM +(Also available via MSYS2’s package manager.) +
+ +

To set up a proper environment in MSYS2, you need to run msys_shell.bat from +the Visual Studio or Intel Compiler command prompt. +

+

Place nasm.exe somewhere in your PATH. +

+

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 LIB +and INCLUDE environment variables to include the Windows-style +paths to these directories. Alternatively, you can try to use the +--extra-cflags/--extra-ldflags configure options. +

+

Finally, run: +

+
+
For MSVC:
+./configure --toolchain=msvc
+
+For ICL:
+./configure --toolchain=icl
+
+make
+make install
+
+ +

If you wish to compile shared libraries, add --enable-shared to your +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. +

+

Notes: +

+
    +
  • If you wish to build with zlib support, you will have to grab a compatible +zlib binary from somewhere, with an MSVC import lib, or if you wish to link +statically, you can follow the instructions below to build a compatible +zlib.lib with MSVC. Regardless of which method you use, you must still +follow step 3, or compilation will fail. +
      +
    1. Grab the zlib sources. +
    2. Edit win32/Makefile.msc so that it uses -MT instead of -MD, since +this is how FFmpeg is built as well. +
    3. Edit zconf.h and remove its inclusion of unistd.h. This gets +erroneously included when building FFmpeg. +
    4. Run nmake -f win32/Makefile.msc. +
    5. Move zlib.lib, zconf.h, and zlib.h to somewhere MSVC +can see. +
    + +
  • FFmpeg has been tested with the following on i686 and x86_64: +
      +
    • Visual Studio 2013 Pro and Express +
    • Intel Composer XE 2013 +
    • Intel Composer XE 2013 SP1 +
    +

    Anything else is not officially supported. +

    +
+ + +

4.2.1 Linking to FFmpeg with Microsoft Visual C++

+ +

If you plan to link with MSVC-built static libraries, you will need +to make sure you have Runtime Library set to +Multi-threaded (/MT) in your project’s settings. +

+

You will need to define inline to something MSVC understands: +

+
#define inline __inline
+
+ +

Also note, that as stated in Microsoft Visual C++, you will need +an MSVC-compatible inttypes.h. +

+

If you plan on using import libraries created by dlltool, you must +set References to No (/OPT:NOREF) under the linker optimization +settings, otherwise the resulting binaries will fail during runtime. +This is not required when using import libraries generated by lib.exe. +This issue is reported upstream at +http://sourceware.org/bugzilla/show_bug.cgi?id=12633. +

+

To create import libraries that work with the /OPT:REF option +(which is enabled by default in Release mode), follow these steps: +

+
    +
  1. Open the Visual Studio Command Prompt. + +

    Alternatively, in a normal command line prompt, call vcvars32.bat +which sets up the environment variables for the Visual C++ tools +(the standard location for this file is something like +C:\Program Files (x86_\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat). +

    +
  2. Enter the bin directory where the created LIB and DLL files +are stored. + +
  3. Generate new import libraries with lib.exe: + +
    +
    lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
    +
    + +

    Replace foo-version and foo with the respective library names. +

    +
+ + +

4.3 Cross compilation for Windows with Linux

+ +

You must use the MinGW cross compilation tools available at +http://www.mingw.org/. +

+

Then configure FFmpeg with the following options: +

+
./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
+
+

(you can change the cross-prefix according to the prefix chosen for the +MinGW tools). +

+

Then you can easily test FFmpeg with Wine. +

+ +

4.4 Compilation under Cygwin

+ +

Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack +llrint() in its C library. +

+

Install your Cygwin with all the "Base" packages, plus the +following "Devel" ones: +

+
binutils, gcc4-core, make, git, mingw-runtime, texinfo
+
+ +

In order to run FATE you will also need the following "Utils" packages: +

+
diffutils
+
+ +

If you want to build FFmpeg with additional libraries, download Cygwin +"Devel" packages for Ogg and Vorbis from any Cygwin packages repository: +

+
libogg-devel, libvorbis-devel
+
+ +

These library packages are only available from +Cygwin Ports: +

+
+
libSDL-devel, libgsm-devel, libmp3lame-devel,
+speex-devel, libtheora-devel, libxvidcore-devel
+
+ +

The recommendation for x264 is to build it from source, as it evolves too +quickly for Cygwin Ports to be up to date. +

+ +

4.5 Crosscompilation for Windows under Cygwin

+ +

With Cygwin you can create Windows binaries that do not need the cygwin1.dll. +

+

Just install your Cygwin as explained before, plus these additional +"Devel" packages: +

+
gcc-mingw-core, mingw-runtime, mingw-zlib
+
+ +

and add some special flags to your configure invocation. +

+

For a static build run +

+
./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
+
+ +

and for a build with shared libraries +

+
./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
+
+ + +

4.6 ARM64EC

+ +

FFmpeg does not intend to support the Windows ARM64EC build configuration; +patches for changing the individual libraries for the purposes of ARM64EC will +not be accepted. +

+

It may still be possible to build FFmpeg in this build configuration; +such a build may seem to work to some extent. Such a build may have some +amounts of ABI inconsistencies though - which we are not willing to fix. +

+

(Changing aarch64 assembly code to strictly support ARM64EC would require +ifdeffing/changing essentially all such assembly code, and would be a +huge maintenance burden. Additionally, changing the library ABI +surfaces to fix ABI inconsistencies could require extensive and intrusive +changes.) +

+

+ This document was generated using makeinfo. +

+
+ + diff --git a/ffmpeg-n8.1/doc/style.min.css b/ffmpeg-n8.1/doc/style.min.css new file mode 100644 index 00000000..a502310b --- /dev/null +++ b/ffmpeg-n8.1/doc/style.min.css @@ -0,0 +1,23 @@ +/*! +The MIT License (MIT) + +Copyright (c) 2014 Barbara Lepage + +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. + */body{background-color:#313131;color:#e6e6e6;text-align:justify}body, h1, h2, h3, h4, h5, h6{font-family:"Lucida Grande","Lucida Sans Unicode","Lucida Sans","Helvetica Neue",Helvetica,Verdana,Tahoma,sans-serif}a{color:#4cae4c}a strong{color:#e6e6e6}a:hover{color:#7fc77f}a:hover strong{color:#4cae4c}main{width:100% ! important;min-height:600px;margin:auto}h1, h2, h3, h4{font-weight:bold;text-align:left}h1, h2, h3{color:#bebebe}h1 strong, h2 strong, h3 strong{color:#e6e6e6}h4, h5, h6{color:#3c8b3c}h1{border-bottom:4px #bebebe solid;padding:20px 2%}h3{border-bottom:2px #bebebe solid;padding:15px 1%}h4{border-bottom:1px solid #e6e6e6;padding:10px 0;margin:20px 0;color:#e6e6e6}.list-group .list-group-item{background-color:#3e3e3e;border-color:black}.list-group.list-group-big .list-group-item{padding:25px}.list-group a.list-group-item{color:#7fc77f}.list-group a.list-group-item:hover{background-color:#313131;color:#4cae4c}.well{background-color:#242424;border-color:black;color:#bebebe}.well strong{color:#e6e6e6}.well code{background-color:#313131}.well hr{border-color:#3c8b3c}.well h3{margin:5px 0 15px 0;border:0;padding:0}.well a{color:#4cae4c}.well a.btn{color:white}.well small{display:block;padding:0 10px;font-style:italic}.well.example{padding-top:40px;margin-bottom:130px}.well.example pre{margin:50px;margin-bottom:30px;font-size:1.5em}.well.example .btn{margin-right:50px;margin-bottom:20px}.well.well-with-icon{min-height:136px}.well.well-with-icon .pull-right,.well.well-with-icon .pull-left{background-color:#4cae4c;color:#e6e6e6;padding:10px;border-radius:5px;margin:5px}.well.well-with-icon .pull-right{margin-left:20px}.well.well-with-icon .pull-left{margin-right:20px}a.well{display:block}a.well:hover{text-decoration:none;opacity:0.8}.info, .warning{margin:10px;padding:10px;background-color:#3e3e3e;color:#e6e6e6}.info code, .warning code{background-color:#313131}.info{border-left:10px #4cae4c solid}.warning{border-left:10px #ae4c4c solid}.with-icon{padding:30px}.with-icon .pull-left{padding-right:30px}.with-icon .pull-right{padding-left:30px}dd{margin-left:20px}code{background-color:#242424;color:#7fc77f;display:inline-block;margin:5px}.table{margin:20px 0;border-radius:4px}.table th,.table td,.table tr{border:1px solid #171717}.table tr th{background-color:#3e3e3e;border-bottom:2px solid #e6e6e6}.table tr:nth-child(odd){background-color:#242424}#sidebar-wrapper, .navbar{background-color:#171717;overflow-x:hidden}#sidebar-wrapper .sidebar-brand img,#sidebar-wrapper .navbar-brand img, .navbar .sidebar-brand img, .navbar .navbar-brand img{opacity:0.6;margin-right:8px}#sidebar-wrapper .sidebar-brand:hover,#sidebar-wrapper .navbar-brand:hover, .navbar .sidebar-brand:hover, .navbar .navbar-brand:hover{color:#fff}#sidebar-wrapper .sidebar-brand:hover img,#sidebar-wrapper .navbar-brand:hover img, .navbar .sidebar-brand:hover img, .navbar .navbar-brand:hover img{opacity:1}#sidebar-wrapper .sidebar-nav li ul, .navbar .sidebar-nav li ul{list-style-type:none;padding:0}#sidebar-wrapper .sidebar-nav li ul li, .navbar .sidebar-nav li ul li{line-height:20px}#sidebar-wrapper .sidebar-nav li ul li a, .navbar .sidebar-nav li ul li a{padding-left:20px}.content-header{height:auto;background-color:#242424}.content-header h1{color:#e6e6e6;display:block;margin:0;margin-bottom:20px;line-height:normal;border-bottom:none}#download h4, #index h4{margin-top:180px}#download h4.first, #index h4.first{margin-top:20px}#download h4.first small, #index h4.first small{color:inherit;font-size:1em}#download .btn-download-wrapper, #index .btn-download-wrapper{text-align:center;margin:160px auto}#download .btn-download-wrapper .btn, #index .btn-download-wrapper .btn{font-size:3em;padding:3%;display:inline-block;margin-bottom:5px}#download .btn-download-wrapper small, #index .btn-download-wrapper small{display:block;font-size:0.4em}#download h2.description, #index h2.description{color:#e6e6e6;font-size:2em;font-weight:bold;margin:120px 50px;line-height:2em}#download h2.description .label, #index h2.description .label{font-size:0.5em}#download .btn-download-wrapper{margin:40px auto}#download .os-selector{text-align:center;color:#e6e6e6;margin:30px 0}#download .os-selector a.btn-build{color:#e6e6e6;display:block;padding:20px;border-radius:2px}#download .os-selector .btn-build[href="#build-linux"]{background-color:#e43}#download .os-selector .btn-build[href="#build-linux"]:hover{color:#e43;background-color:#e6e6e6}#download .os-selector .btn-build[href="#build-windows"]{background-color:#06a}#download .os-selector .btn-build[href="#build-windows"]:hover{color:#06a;background-color:#e6e6e6}#download .os-selector .btn-build[href="#build-mac"]{background-color:darkgrey}#download .os-selector .btn-build[href="#build-mac"]:hover{color:darkgrey;background-color:#e6e6e6}#download .os-selector .tab-content{margin-top:20px}#download .os-selector #build-linux h3{color:#e43}#download .os-selector #build-windows h3{color:#06a}#download .os-selector #build-mac h3{color:darkgrey}footer{background-color:#242424;border-top:1px #101010 solid;padding:20px 0%}footer a{display:block}footer img[alt="FFmpeg"]{width:50%;display:block;margin:auto}.example.user-good pre{color:#bfbfbf;border:1px solid #357735;border-left:10px solid #357735;background-color:#242424}.example.user-bad pre{color:#bfbfbf;border:1px solid #ae4c4c;border-left:10px solid #ae4c4c;background-color:#242424} diff --git a/ffmpeg-n8.1/include/libavcodec/ac3_parser.h b/ffmpeg-n8.1/include/libavcodec/ac3_parser.h new file mode 100644 index 00000000..ff8cc4cf --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/ac3_parser.h @@ -0,0 +1,36 @@ +/* + * AC-3 parser prototypes + * Copyright (c) 2003 Fabrice Bellard + * Copyright (c) 2003 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_AC3_PARSER_H +#define AVCODEC_AC3_PARSER_H + +#include +#include + +/** + * Extract the bitstream ID and the frame size from AC-3 data. + */ +int av_ac3_parse_header(const uint8_t *buf, size_t size, + uint8_t *bitstream_id, uint16_t *frame_size); + + +#endif /* AVCODEC_AC3_PARSER_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/adts_parser.h b/ffmpeg-n8.1/include/libavcodec/adts_parser.h new file mode 100644 index 00000000..f85becd1 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/adts_parser.h @@ -0,0 +1,37 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_ADTS_PARSER_H +#define AVCODEC_ADTS_PARSER_H + +#include +#include + +#define AV_AAC_ADTS_HEADER_SIZE 7 + +/** + * Extract the number of samples and frames from AAC data. + * @param[in] buf pointer to AAC data buffer + * @param[out] samples Pointer to where number of samples is written + * @param[out] frames Pointer to where number of frames is written + * @return Returns 0 on success, error code on failure. + */ +int av_adts_header_parse(const uint8_t *buf, uint32_t *samples, + uint8_t *frames); + +#endif /* AVCODEC_ADTS_PARSER_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/avcodec.h b/ffmpeg-n8.1/include/libavcodec/avcodec.h new file mode 100644 index 00000000..6824bfc9 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/avcodec.h @@ -0,0 +1,2995 @@ +/* + * copyright (c) 2001 Fabrice Bellard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_AVCODEC_H +#define AVCODEC_AVCODEC_H + +/** + * @file + * @ingroup libavc + * Libavcodec external API header + */ + +#include "libavutil/samplefmt.h" +#include "libavutil/attributes.h" +#include "libavutil/avutil.h" +#include "libavutil/buffer.h" +#include "libavutil/channel_layout.h" +#include "libavutil/dict.h" +#include "libavutil/frame.h" +#include "libavutil/log.h" +#include "libavutil/pixfmt.h" +#include "libavutil/rational.h" + +#include "codec.h" +#include "codec_id.h" +#include "defs.h" +#include "packet.h" +#include "version_major.h" +#ifndef HAVE_AV_CONFIG_H +/* When included as part of the ffmpeg build, only include the major version + * to avoid unnecessary rebuilds. When included externally, keep including + * the full version information. */ +#include "version.h" + +#include "codec_desc.h" +#include "codec_par.h" +#endif + +struct AVCodecParameters; + +/** + * @defgroup libavc libavcodec + * Encoding/Decoding Library + * + * @{ + * + * @defgroup lavc_decoding Decoding + * @{ + * @} + * + * @defgroup lavc_encoding Encoding + * @{ + * @} + * + * @defgroup lavc_codec Codecs + * @{ + * @defgroup lavc_codec_native Native Codecs + * @{ + * @} + * @defgroup lavc_codec_wrappers External library wrappers + * @{ + * @} + * @defgroup lavc_codec_hwaccel Hardware Accelerators bridge + * @{ + * @} + * @} + * @defgroup lavc_internal Internal + * @{ + * @} + * @} + */ + +/** + * @ingroup libavc + * @defgroup lavc_encdec send/receive encoding and decoding API overview + * @{ + * + * The avcodec_send_packet()/avcodec_receive_frame()/avcodec_send_frame()/ + * avcodec_receive_packet() functions provide an encode/decode API, which + * decouples input and output. + * + * The API is very similar for encoding/decoding and audio/video, and works as + * follows: + * - Set up and open the AVCodecContext as usual. + * - Send valid input: + * - For decoding, call avcodec_send_packet() to give the decoder raw + * compressed data in an AVPacket. + * - For encoding, call avcodec_send_frame() to give the encoder an AVFrame + * containing uncompressed audio or video. + * + * In both cases, it is recommended that AVPackets and AVFrames are + * refcounted, or libavcodec might have to copy the input data. (libavformat + * always returns refcounted AVPackets, and av_frame_get_buffer() allocates + * refcounted AVFrames.) + * - Receive output in a loop. Periodically call one of the avcodec_receive_*() + * functions and process their output: + * - For decoding, call avcodec_receive_frame(). On success, it will return + * an AVFrame containing uncompressed audio or video data. + * - For encoding, call avcodec_receive_packet(). On success, it will return + * an AVPacket with a compressed frame. + * + * Repeat this call until it returns AVERROR(EAGAIN) or an error. The + * AVERROR(EAGAIN) return value means that new input data is required to + * return new output. In this case, continue with sending input. For each + * input frame/packet, the codec will typically return 1 output frame/packet, + * but it can also be 0 or more than 1. + * + * At the beginning of decoding or encoding, the codec might accept multiple + * input frames/packets without returning a frame, until its internal buffers + * are filled. This situation is handled transparently if you follow the steps + * outlined above. + * + * In theory, sending input can result in EAGAIN - this should happen only if + * not all output was received. You can use this to structure alternative decode + * or encode loops other than the one suggested above. For example, you could + * try sending new input on each iteration, and try to receive output if that + * returns EAGAIN. + * + * End of stream situations. These require "flushing" (aka draining) the codec, + * as the codec might buffer multiple frames or packets internally for + * performance or out of necessity (consider B-frames). + * This is handled as follows: + * - Instead of valid input, send NULL to the avcodec_send_packet() (decoding) + * or avcodec_send_frame() (encoding) functions. This will enter draining + * mode. + * - Call avcodec_receive_frame() (decoding) or avcodec_receive_packet() + * (encoding) in a loop until AVERROR_EOF is returned. The functions will + * not return AVERROR(EAGAIN), unless you forgot to enter draining mode. + * - Before decoding can be resumed again, the codec has to be reset with + * avcodec_flush_buffers(). + * + * Using the API as outlined above is highly recommended. But it is also + * possible to call functions outside of this rigid schema. For example, you can + * call avcodec_send_packet() repeatedly without calling + * avcodec_receive_frame(). In this case, avcodec_send_packet() will succeed + * until the codec's internal buffer has been filled up (which is typically of + * size 1 per output frame, after initial input), and then reject input with + * AVERROR(EAGAIN). Once it starts rejecting input, you have no choice but to + * read at least some output. + * + * Not all codecs will follow a rigid and predictable dataflow; the only + * guarantee is that an AVERROR(EAGAIN) return value on a send/receive call on + * one end implies that a receive/send call on the other end will succeed, or + * at least will not fail with AVERROR(EAGAIN). In general, no codec will + * permit unlimited buffering of input or output. + * + * A codec is not allowed to return AVERROR(EAGAIN) for both sending and receiving. This + * would be an invalid state, which could put the codec user into an endless + * loop. The API has no concept of time either: it cannot happen that trying to + * do avcodec_send_packet() results in AVERROR(EAGAIN), but a repeated call 1 second + * later accepts the packet (with no other receive/flush API calls involved). + * The API is a strict state machine, and the passage of time is not supposed + * to influence it. Some timing-dependent behavior might still be deemed + * acceptable in certain cases. But it must never result in both send/receive + * returning EAGAIN at the same time at any point. It must also absolutely be + * avoided that the current state is "unstable" and can "flip-flop" between + * the send/receive APIs allowing progress. For example, it's not allowed that + * the codec randomly decides that it actually wants to consume a packet now + * instead of returning a frame, after it just returned AVERROR(EAGAIN) on an + * avcodec_send_packet() call. + * @} + */ + +/** + * @defgroup lavc_core Core functions/structures. + * @ingroup libavc + * + * Basic definitions, functions for querying libavcodec capabilities, + * allocating core structures, etc. + * @{ + */ + +/** + * @ingroup lavc_encoding + */ +typedef struct RcOverride{ + int start_frame; + int end_frame; + int qscale; // If this is 0 then quality_factor will be used instead. + float quality_factor; +} RcOverride; + +/* encoding support + These flags can be passed in AVCodecContext.flags before initialization. + Note: Not everything is supported yet. +*/ + +/** + * Allow decoders to produce frames with data planes that are not aligned + * to CPU requirements (e.g. due to cropping). + */ +#define AV_CODEC_FLAG_UNALIGNED (1 << 0) +/** + * Use fixed qscale. + */ +#define AV_CODEC_FLAG_QSCALE (1 << 1) +/** + * 4 MV per MB allowed / advanced prediction for H.263. + */ +#define AV_CODEC_FLAG_4MV (1 << 2) +/** + * Output even those frames that might be corrupted. + */ +#define AV_CODEC_FLAG_OUTPUT_CORRUPT (1 << 3) +/** + * Use qpel MC. + */ +#define AV_CODEC_FLAG_QPEL (1 << 4) +/** + * Request the encoder to output reconstructed frames, i.e.\ frames that would + * be produced by decoding the encoded bitstream. These frames may be retrieved + * by calling avcodec_receive_frame() immediately after a successful call to + * avcodec_receive_packet(). + * + * Should only be used with encoders flagged with the + * @ref AV_CODEC_CAP_ENCODER_RECON_FRAME capability. + * + * @note + * Each reconstructed frame returned by the encoder corresponds to the last + * encoded packet, i.e. the frames are returned in coded order rather than + * presentation order. + * + * @note + * Frame parameters (like pixel format or dimensions) do not have to match the + * AVCodecContext values. Make sure to use the values from the returned frame. + */ +#define AV_CODEC_FLAG_RECON_FRAME (1 << 6) +/** + * @par decoding + * Request the decoder to propagate each packet's AVPacket.opaque and + * AVPacket.opaque_ref to its corresponding output AVFrame. + * + * @par encoding: + * Request the encoder to propagate each frame's AVFrame.opaque and + * AVFrame.opaque_ref values to its corresponding output AVPacket. + * + * @par + * May only be set on encoders that have the + * @ref AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE capability flag. + * + * @note + * While in typical cases one input frame produces exactly one output packet + * (perhaps after a delay), in general the mapping of frames to packets is + * M-to-N, so + * - Any number of input frames may be associated with any given output packet. + * This includes zero - e.g. some encoders may output packets that carry only + * metadata about the whole stream. + * - A given input frame may be associated with any number of output packets. + * Again this includes zero - e.g. some encoders may drop frames under certain + * conditions. + * . + * This implies that when using this flag, the caller must NOT assume that + * - a given input frame's opaques will necessarily appear on some output packet; + * - every output packet will have some non-NULL opaque value. + * . + * When an output packet contains multiple frames, the opaque values will be + * taken from the first of those. + * + * @note + * The converse holds for decoders, with frames and packets switched. + */ +#define AV_CODEC_FLAG_COPY_OPAQUE (1 << 7) +/** + * Signal to the encoder that the values of AVFrame.duration are valid and + * should be used (typically for transferring them to output packets). + * + * If this flag is not set, frame durations are ignored. + */ +#define AV_CODEC_FLAG_FRAME_DURATION (1 << 8) +/** + * Use internal 2pass ratecontrol in first pass mode. + */ +#define AV_CODEC_FLAG_PASS1 (1 << 9) +/** + * Use internal 2pass ratecontrol in second pass mode. + */ +#define AV_CODEC_FLAG_PASS2 (1 << 10) +/** + * loop filter. + */ +#define AV_CODEC_FLAG_LOOP_FILTER (1 << 11) +/** + * Only decode/encode grayscale. + */ +#define AV_CODEC_FLAG_GRAY (1 << 13) +/** + * error[?] variables will be set during encoding. + */ +#define AV_CODEC_FLAG_PSNR (1 << 15) +/** + * Use interlaced DCT. + */ +#define AV_CODEC_FLAG_INTERLACED_DCT (1 << 18) +/** + * Force low delay. + */ +#define AV_CODEC_FLAG_LOW_DELAY (1 << 19) +/** + * Place global headers in extradata instead of every keyframe. + */ +#define AV_CODEC_FLAG_GLOBAL_HEADER (1 << 22) +/** + * Use only bitexact stuff (except (I)DCT). + */ +#define AV_CODEC_FLAG_BITEXACT (1 << 23) +/* Fx : Flag for H.263+ extra options */ +/** + * H.263 advanced intra coding / MPEG-4 AC prediction + */ +#define AV_CODEC_FLAG_AC_PRED (1 << 24) +/** + * interlaced motion estimation + */ +#define AV_CODEC_FLAG_INTERLACED_ME (1 << 29) +#define AV_CODEC_FLAG_CLOSED_GOP (1U << 31) + +/** + * Allow non spec compliant speedup tricks. + */ +#define AV_CODEC_FLAG2_FAST (1 << 0) +/** + * Skip bitstream encoding. + */ +#define AV_CODEC_FLAG2_NO_OUTPUT (1 << 2) +/** + * Place global headers at every keyframe instead of in extradata. + */ +#define AV_CODEC_FLAG2_LOCAL_HEADER (1 << 3) + +/** + * Input bitstream might be truncated at a packet boundaries + * instead of only at frame boundaries. + */ +#define AV_CODEC_FLAG2_CHUNKS (1 << 15) +/** + * Discard cropping information from SPS. + */ +#define AV_CODEC_FLAG2_IGNORE_CROP (1 << 16) + +/** + * Show all frames before the first keyframe + */ +#define AV_CODEC_FLAG2_SHOW_ALL (1 << 22) +/** + * Export motion vectors through frame side data + */ +#define AV_CODEC_FLAG2_EXPORT_MVS (1 << 28) +/** + * Do not skip samples and export skip information as frame side data + */ +#define AV_CODEC_FLAG2_SKIP_MANUAL (1 << 29) +/** + * Do not reset ASS ReadOrder field on flush (subtitles decoding) + */ +#define AV_CODEC_FLAG2_RO_FLUSH_NOOP (1 << 30) +/** + * Generate/parse ICC profiles on encode/decode, as appropriate for the type of + * file. No effect on codecs which cannot contain embedded ICC profiles, or + * when compiled without support for lcms2. + */ +#define AV_CODEC_FLAG2_ICC_PROFILES (1U << 31) + +/* Exported side data. + These flags can be passed in AVCodecContext.export_side_data before initialization. +*/ +/** + * Export motion vectors through frame side data + */ +#define AV_CODEC_EXPORT_DATA_MVS (1 << 0) +/** + * Export encoder Producer Reference Time through packet side data + */ +#define AV_CODEC_EXPORT_DATA_PRFT (1 << 1) +/** + * Decoding only. + * Export the AVVideoEncParams structure through frame side data. + */ +#define AV_CODEC_EXPORT_DATA_VIDEO_ENC_PARAMS (1 << 2) +/** + * Decoding only. + * Do not apply film grain, export it instead. + */ +#define AV_CODEC_EXPORT_DATA_FILM_GRAIN (1 << 3) + +/** + * Decoding only. + * Do not apply picture enhancement layers, export them instead. + */ +#define AV_CODEC_EXPORT_DATA_ENHANCEMENTS (1 << 4) + +/** + * The decoder will keep a reference to the frame and may reuse it later. + */ +#define AV_GET_BUFFER_FLAG_REF (1 << 0) + +/** + * The encoder will keep a reference to the packet and may reuse it later. + */ +#define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0) + +/** + * The decoder will bypass frame threading and return the next frame as soon as + * possible. Note that this may deliver frames earlier than the advertised + * `AVCodecContext.delay`. No effect when frame threading is disabled, or on + * encoding. + */ +#define AV_CODEC_RECEIVE_FRAME_FLAG_SYNCHRONOUS (1 << 0) + +/** + * main external API structure. + * New fields can be added to the end with minor version bumps. + * Removal, reordering and changes to existing fields require a major + * version bump. + * You can use AVOptions (av_opt* / av_set/get*()) to access these fields from user + * applications. + * The name string for AVOptions options matches the associated command line + * parameter name and can be found in libavcodec/options_table.h + * The AVOption/command line parameter names differ in some cases from the C + * structure field names for historic reasons or brevity. + * sizeof(AVCodecContext) must not be used outside libav*. + */ +typedef struct AVCodecContext { + /** + * information on struct for av_log + * - set by avcodec_alloc_context3 + */ + const AVClass *av_class; + int log_level_offset; + + enum AVMediaType codec_type; /* see AVMEDIA_TYPE_xxx */ + const struct AVCodec *codec; + enum AVCodecID codec_id; /* see AV_CODEC_ID_xxx */ + + /** + * fourcc (LSB first, so "ABCD" -> ('D'<<24) + ('C'<<16) + ('B'<<8) + 'A'). + * This is used to work around some encoder bugs. + * A demuxer should set this to what is stored in the field used to identify the codec. + * If there are multiple such fields in a container then the demuxer should choose the one + * which maximizes the information about the used codec. + * If the codec tag field in a container is larger than 32 bits then the demuxer should + * remap the longer ID to 32 bits with a table or other structure. Alternatively a new + * extra_codec_tag + size could be added but for this a clear advantage must be demonstrated + * first. + * - encoding: Set by user, if not then the default based on codec_id will be used. + * - decoding: Set by user, will be converted to uppercase by libavcodec during init. + */ + unsigned int codec_tag; + + void *priv_data; + + /** + * Private context used for internal data. + * + * Unlike priv_data, this is not codec-specific. It is used in general + * libavcodec functions. + */ + struct AVCodecInternal *internal; + + /** + * Private data of the user, can be used to carry app specific stuff. + * - encoding: Set by user. + * - decoding: Set by user. + */ + void *opaque; + + /** + * the average bitrate + * - encoding: Set by user; unused for constant quantizer encoding. + * - decoding: Set by user, may be overwritten by libavcodec + * if this info is available in the stream + */ + int64_t bit_rate; + + /** + * AV_CODEC_FLAG_*. + * - encoding: Set by user. + * - decoding: Set by user. + */ + int flags; + + /** + * AV_CODEC_FLAG2_* + * - encoding: Set by user. + * - decoding: Set by user. + */ + int flags2; + + /** + * Out-of-band global headers that may be used by some codecs. + * + * - decoding: Should be set by the caller when available (typically from a + * demuxer) before opening the decoder; some decoders require this to be + * set and will fail to initialize otherwise. + * + * The array must be allocated with the av_malloc() family of functions; + * allocated size must be at least AV_INPUT_BUFFER_PADDING_SIZE bytes + * larger than extradata_size. + * + * - encoding: May be set by the encoder in avcodec_open2() (possibly + * depending on whether the AV_CODEC_FLAG_GLOBAL_HEADER flag is set). + * + * After being set, the array is owned by the codec and freed in + * avcodec_free_context(). + */ + uint8_t *extradata; + int extradata_size; + + /** + * This 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. + * This often, but not always is the inverse of the frame rate or field rate + * for video. 1/time_base is not the average frame rate if the frame rate is not + * constant. + * + * Like containers, elementary streams also can store timestamps, 1/time_base + * is the unit in which these timestamps are specified. + * As example of such codec time base see ISO/IEC 14496-2:2001(E) + * vop_time_increment_resolution and fixed_vop_rate + * (fixed_vop_rate == 0 implies that it is different from the framerate) + * + * - encoding: MUST be set by user. + * - decoding: unused. + */ + AVRational time_base; + + /** + * Timebase in which pkt_dts/pts and AVPacket.dts/pts are expressed. + * - encoding: unused. + * - decoding: set by user. + */ + AVRational pkt_timebase; + + /** + * - decoding: For codecs that store a framerate value in the compressed + * bitstream, the decoder may export it here. { 0, 1} when + * unknown. + * - encoding: May be used to signal the framerate of CFR content to an + * encoder. + */ + AVRational framerate; + + /** + * Codec delay. + * + * Encoding: Number of frames delay there will be from the encoder input to + * the decoder output. (we assume the decoder matches the spec) + * Decoding: Number of frames delay in addition to what a standard decoder + * as specified in the spec would produce. + * + * Video: + * Number of frames the decoded output will be delayed relative to the + * encoded input. + * + * Audio: + * For encoding, this field is unused (see initial_padding). + * + * For decoding, this is the number of samples the decoder needs to + * output before the decoder's output is valid. When seeking, you should + * start decoding this many samples prior to your desired seek point. + * + * - encoding: Set by libavcodec. + * - decoding: Set by libavcodec. + */ + int delay; + + + /* video only */ + /** + * picture width / height. + * + * @note Those fields may not match the values of the last + * AVFrame output by avcodec_receive_frame() due frame + * reordering. + * + * - encoding: MUST be set by user. + * - decoding: May be set by the user before opening the decoder if known e.g. + * from the container. Some decoders will require the dimensions + * to be set by the caller. During decoding, the decoder may + * overwrite those values as required while parsing the data. + */ + int width, height; + + /** + * Bitstream width / height, may be different from width/height e.g. when + * the decoded frame is cropped before being output or lowres is enabled. + * + * @note Those field may not match the value of the last + * AVFrame output by avcodec_receive_frame() due frame + * reordering. + * + * - encoding: unused + * - decoding: May be set by the user before opening the decoder if known + * e.g. from the container. During decoding, the decoder may + * overwrite those values as required while parsing the data. + */ + int coded_width, coded_height; + + /** + * sample aspect ratio (0 if unknown) + * That is the width of a pixel divided by the height of the pixel. + * Numerator and denominator must be relatively prime and smaller than 256 for some video standards. + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + AVRational sample_aspect_ratio; + + /** + * Pixel format, see AV_PIX_FMT_xxx. + * May be set by the demuxer if known from headers. + * May be overridden by the decoder if it knows better. + * + * @note This field may not match the value of the last + * AVFrame output by avcodec_receive_frame() due frame + * reordering. + * + * - encoding: Set by user. + * - decoding: Set by user if known, overridden by libavcodec while + * parsing the data. + */ + enum AVPixelFormat pix_fmt; + + /** + * Nominal unaccelerated pixel format, see AV_PIX_FMT_xxx. + * - encoding: unused. + * - decoding: Set by libavcodec before calling get_format() + */ + enum AVPixelFormat sw_pix_fmt; + + /** + * Chromaticity coordinates of the source primaries. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVColorPrimaries color_primaries; + + /** + * Color Transfer Characteristic. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVColorTransferCharacteristic color_trc; + + /** + * YUV colorspace type. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVColorSpace colorspace; + + /** + * MPEG vs JPEG YUV range. + * - encoding: Set by user to override the default output color range value, + * If not specified, libavcodec sets the color range depending on the + * output format. + * - decoding: Set by libavcodec, can be set by the user to propagate the + * color range to components reading from the decoder context. + */ + enum AVColorRange color_range; + + /** + * This defines the location of chroma samples. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVChromaLocation chroma_sample_location; + + /** Field order + * - encoding: set by libavcodec + * - decoding: Set by user. + */ + enum AVFieldOrder field_order; + + /** + * number of reference frames + * - encoding: Set by user. + * - decoding: Set by lavc. + */ + int refs; + + /** + * Size of the frame reordering buffer in the decoder. + * For MPEG-2 it is 1 IPB or 0 low delay IP. + * - encoding: Set by libavcodec. + * - decoding: Set by libavcodec. + */ + int has_b_frames; + + /** + * slice flags + * - encoding: unused + * - decoding: Set by user. + */ + int slice_flags; +#define SLICE_FLAG_CODED_ORDER 0x0001 ///< draw_horiz_band() is called in coded order instead of display +#define SLICE_FLAG_ALLOW_FIELD 0x0002 ///< allow draw_horiz_band() with field slices (MPEG-2 field pics) +#define SLICE_FLAG_ALLOW_PLANE 0x0004 ///< allow draw_horiz_band() with 1 component at a time (SVQ1) + + /** + * If non NULL, 'draw_horiz_band' is called by the libavcodec + * decoder to draw a horizontal band. It improves cache usage. Not + * all codecs can do that. You must check the codec capabilities + * beforehand. + * When multithreading is used, it may be called from multiple threads + * at the same time; threads might draw different parts of the same AVFrame, + * or multiple AVFrames, and there is no guarantee that slices will be drawn + * in order. + * The function is also used by hardware acceleration APIs. + * It is called at least once during frame decoding to pass + * the data needed for hardware render. + * In that mode instead of pixel data, AVFrame points to + * a structure specific to the acceleration API. The application + * reads the structure and can change some fields to indicate progress + * or mark state. + * - encoding: unused + * - decoding: Set by user. + * @param height the height of the slice + * @param y the y position of the slice + * @param type 1->top field, 2->bottom field, 3->frame + * @param offset offset into the AVFrame.data from which the slice should be read + */ + void (*draw_horiz_band)(struct AVCodecContext *s, + const AVFrame *src, int offset[AV_NUM_DATA_POINTERS], + int y, int type, int height); + + /** + * Callback to negotiate the pixel format. Decoding only, may be set by the + * caller before avcodec_open2(). + * + * Called by some decoders to select the pixel format that will be used for + * the output frames. This is mainly used to set up hardware acceleration, + * then the provided format list contains the corresponding hwaccel pixel + * formats alongside the "software" one. The software pixel format may also + * be retrieved from \ref sw_pix_fmt. + * + * This callback will be called when the coded frame properties (such as + * resolution, pixel format, etc.) change and more than one output format is + * supported for those new properties. If a hardware pixel format is chosen + * and initialization for it fails, the callback may be called again + * immediately. + * + * This callback may be called from different threads if the decoder is + * multi-threaded, but not from more than one thread simultaneously. + * + * @param fmt list of formats which may be used in the current + * configuration, terminated by AV_PIX_FMT_NONE. + * @warning Behavior is undefined if the callback returns a value other + * than one of the formats in fmt or AV_PIX_FMT_NONE. + * @return the chosen format or AV_PIX_FMT_NONE + */ + enum AVPixelFormat (*get_format)(struct AVCodecContext *s, const enum AVPixelFormat * fmt); + + /** + * maximum number of B-frames between non-B-frames + * Note: The output will be delayed by max_b_frames+1 relative to the input. + * - encoding: Set by user. + * - decoding: unused + */ + int max_b_frames; + + /** + * qscale factor between IP and B-frames + * If > 0 then the last P-frame quantizer will be used (q= lastp_q*factor+offset). + * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset). + * - encoding: Set by user. + * - decoding: unused + */ + float b_quant_factor; + + /** + * qscale offset between IP and B-frames + * - encoding: Set by user. + * - decoding: unused + */ + float b_quant_offset; + + /** + * qscale factor between P- and I-frames + * If > 0 then the last P-frame quantizer will be used (q = lastp_q * factor + offset). + * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset). + * - encoding: Set by user. + * - decoding: unused + */ + float i_quant_factor; + + /** + * qscale offset between P and I-frames + * - encoding: Set by user. + * - decoding: unused + */ + float i_quant_offset; + + /** + * luminance masking (0-> disabled) + * - encoding: Set by user. + * - decoding: unused + */ + float lumi_masking; + + /** + * temporary complexity masking (0-> disabled) + * - encoding: Set by user. + * - decoding: unused + */ + float temporal_cplx_masking; + + /** + * spatial complexity masking (0-> disabled) + * - encoding: Set by user. + * - decoding: unused + */ + float spatial_cplx_masking; + + /** + * p block masking (0-> disabled) + * - encoding: Set by user. + * - decoding: unused + */ + float p_masking; + + /** + * darkness masking (0-> disabled) + * - encoding: Set by user. + * - decoding: unused + */ + float dark_masking; + + /** + * noise vs. sse weight for the nsse comparison function + * - encoding: Set by user. + * - decoding: unused + */ + int nsse_weight; + + /** + * motion estimation comparison function + * - encoding: Set by user. + * - decoding: unused + */ + int me_cmp; + /** + * subpixel motion estimation comparison function + * - encoding: Set by user. + * - decoding: unused + */ + int me_sub_cmp; + /** + * macroblock comparison function (not supported yet) + * - encoding: Set by user. + * - decoding: unused + */ + int mb_cmp; + /** + * interlaced DCT comparison function + * - encoding: Set by user. + * - decoding: unused + */ + int ildct_cmp; +#define FF_CMP_SAD 0 +#define FF_CMP_SSE 1 +#define FF_CMP_SATD 2 +#define FF_CMP_DCT 3 +#define FF_CMP_PSNR 4 +#define FF_CMP_BIT 5 +#define FF_CMP_RD 6 +#define FF_CMP_ZERO 7 +#define FF_CMP_VSAD 8 +#define FF_CMP_VSSE 9 +#define FF_CMP_NSSE 10 +#define FF_CMP_W53 11 +#define FF_CMP_W97 12 +#define FF_CMP_DCTMAX 13 +#define FF_CMP_DCT264 14 +#define FF_CMP_MEDIAN_SAD 15 +#define FF_CMP_CHROMA 256 + + /** + * ME diamond size & shape + * - encoding: Set by user. + * - decoding: unused + */ + int dia_size; + + /** + * amount of previous MV predictors (2a+1 x 2a+1 square) + * - encoding: Set by user. + * - decoding: unused + */ + int last_predictor_count; + + /** + * motion estimation prepass comparison function + * - encoding: Set by user. + * - decoding: unused + */ + int me_pre_cmp; + + /** + * ME prepass diamond size & shape + * - encoding: Set by user. + * - decoding: unused + */ + int pre_dia_size; + + /** + * subpel ME quality + * - encoding: Set by user. + * - decoding: unused + */ + int me_subpel_quality; + + /** + * maximum motion estimation search range in subpel units + * If 0 then no limit. + * + * - encoding: Set by user. + * - decoding: unused + */ + int me_range; + + /** + * macroblock decision mode + * - encoding: Set by user. + * - decoding: unused + */ + int mb_decision; +#define FF_MB_DECISION_SIMPLE 0 ///< uses mb_cmp +#define FF_MB_DECISION_BITS 1 ///< chooses the one which needs the fewest bits +#define FF_MB_DECISION_RD 2 ///< rate distortion + + /** + * custom intra quantization matrix + * Must be allocated with the av_malloc() family of functions, and will be freed in + * avcodec_free_context(). + * - encoding: Set/allocated by user, freed by libavcodec. Can be NULL. + * - decoding: Set/allocated/freed by libavcodec. + */ + uint16_t *intra_matrix; + + /** + * custom inter quantization matrix + * Must be allocated with the av_malloc() family of functions, and will be freed in + * avcodec_free_context(). + * - encoding: Set/allocated by user, freed by libavcodec. Can be NULL. + * - decoding: Set/allocated/freed by libavcodec. + */ + uint16_t *inter_matrix; + + /** + * custom intra quantization matrix + * - encoding: Set by user, can be NULL. + * - decoding: unused. + */ + uint16_t *chroma_intra_matrix; + +#if FF_API_INTRA_DC_PRECISION + /** + * precision of the intra DC coefficient - 8 + * - encoding: Set by user. + * - decoding: Set by libavcodec + * @deprecated Use the MPEG-2 encoder's private option "intra_dc_precision" instead. + */ + attribute_deprecated + int intra_dc_precision; +#endif + + /** + * minimum MB Lagrange multiplier + * - encoding: Set by user. + * - decoding: unused + */ + int mb_lmin; + + /** + * maximum MB Lagrange multiplier + * - encoding: Set by user. + * - decoding: unused + */ + int mb_lmax; + + /** + * - encoding: Set by user. + * - decoding: unused + */ + int bidir_refine; + + /** + * minimum GOP size + * - encoding: Set by user. + * - decoding: unused + */ + int keyint_min; + + /** + * the number of pictures in a group of pictures, or 0 for intra_only + * - encoding: Set by user. + * - decoding: unused + */ + int gop_size; + + /** + * Note: Value depends upon the compare function used for fullpel ME. + * - encoding: Set by user. + * - decoding: unused + */ + int mv0_threshold; + + /** + * Number of slices. + * Indicates number of picture subdivisions. Used for parallelized + * decoding. + * - encoding: Set by user + * - decoding: unused + */ + int slices; + + /* audio only */ + int sample_rate; ///< samples per second + + /** + * audio sample format + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + enum AVSampleFormat sample_fmt; ///< sample format + + /** + * Audio channel layout. + * - encoding: must be set by the caller, to one of AVCodec.ch_layouts. + * - decoding: may be set by the caller if known e.g. from the container. + * The decoder can then override during decoding as needed. + */ + AVChannelLayout ch_layout; + + /* The following data should not be initialized. */ + /** + * Number of samples per channel in an audio frame. + * + * - encoding: set by libavcodec in avcodec_open2(). Each submitted frame + * except the last must contain exactly frame_size samples per channel. + * May be 0 when the codec has AV_CODEC_CAP_VARIABLE_FRAME_SIZE set, then the + * frame size is not restricted. + * - decoding: may be set by some decoders to indicate constant frame size + */ + int frame_size; + + /** + * number of bytes per packet if constant and known or 0 + * Used by some WAV based audio codecs. + */ + int block_align; + + /** + * Audio cutoff bandwidth (0 means "automatic") + * - encoding: Set by user. + * - decoding: unused + */ + int cutoff; + + /** + * Type of service that the audio stream conveys. + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + enum AVAudioServiceType audio_service_type; + + /** + * desired sample format + * - encoding: Not used. + * - decoding: Set by user. + * Decoder will decode to this format if it can. + */ + enum AVSampleFormat request_sample_fmt; + + /** + * Audio only. The number of "priming" samples (padding) inserted by the + * encoder at the beginning of the audio. I.e. this number of leading + * decoded samples must be discarded by the caller to get the original audio + * without leading padding. + * + * - decoding: unused + * - encoding: Set by libavcodec. The timestamps on the output packets are + * adjusted by the encoder so that they always refer to the + * first sample of the data actually contained in the packet, + * including any added padding. E.g. if the timebase is + * 1/samplerate and the timestamp of the first input sample is + * 0, the timestamp of the first output packet will be + * -initial_padding. + */ + int initial_padding; + + /** + * Audio only. The amount of padding (in samples) appended by the encoder to + * the end of the audio. I.e. this number of decoded samples must be + * discarded by the caller from the end of the stream to get the original + * audio without any trailing padding. + * + * - decoding: unused + * - encoding: unused + */ + int trailing_padding; + + /** + * Number of samples to skip after a discontinuity + * - decoding: unused + * - encoding: set by libavcodec + */ + int seek_preroll; + + /** + * This callback is called at the beginning of each frame to get data + * buffer(s) for it. There may be one contiguous buffer for all the data or + * there may be a buffer per each data plane or anything in between. What + * this means is, you may set however many entries in buf[] you feel necessary. + * Each buffer must be reference-counted using the AVBuffer API (see description + * of buf[] below). + * + * The following fields will be set in the frame before this callback is + * called: + * - format + * - width, height (video only) + * - sample_rate, channel_layout, nb_samples (audio only) + * Their values may differ from the corresponding values in + * AVCodecContext. This callback must use the frame values, not the codec + * context values, to calculate the required buffer size. + * + * This callback must fill the following fields in the frame: + * - data[] + * - linesize[] + * - extended_data: + * * if the data is planar audio with more than 8 channels, then this + * callback must allocate and fill extended_data to contain all pointers + * to all data planes. data[] must hold as many pointers as it can. + * extended_data must be allocated with av_malloc() and will be freed in + * av_frame_unref(). + * * otherwise extended_data must point to data + * - buf[] must contain one or more pointers to AVBufferRef structures. Each of + * the frame's data and extended_data pointers must be contained in these. That + * is, one AVBufferRef for each allocated chunk of memory, not necessarily one + * AVBufferRef per data[] entry. See: av_buffer_create(), av_buffer_alloc(), + * and av_buffer_ref(). + * - extended_buf and nb_extended_buf must be allocated with av_malloc() by + * this callback and filled with the extra buffers if there are more + * buffers than buf[] can hold. extended_buf will be freed in + * av_frame_unref(). + * Decoders will generally initialize the whole buffer before it is output + * but it can in rare error conditions happen that uninitialized data is passed + * through. \important The buffers returned by get_buffer* should thus not contain sensitive + * data. + * + * If AV_CODEC_CAP_DR1 is not set then get_buffer2() must call + * avcodec_default_get_buffer2() instead of providing buffers allocated by + * some other means. + * + * Each data plane must be aligned to the maximum required by the target + * CPU. + * + * @see avcodec_default_get_buffer2() + * + * Video: + * + * If AV_GET_BUFFER_FLAG_REF is set in flags then the frame may be reused + * (read and/or written to if it is writable) later by libavcodec. + * + * avcodec_align_dimensions2() should be used to find the required width and + * height, as they normally need to be rounded up to the next multiple of 16. + * + * Some decoders do not support linesizes changing between frames. + * + * If frame multithreading is used, this callback may be called from a + * different thread, but not from more than one at once. Does not need to be + * reentrant. + * + * @see avcodec_align_dimensions2() + * + * Audio: + * + * Decoders request a buffer of a particular size by setting + * AVFrame.nb_samples prior to calling get_buffer2(). The decoder may, + * however, utilize only part of the buffer by setting AVFrame.nb_samples + * to a smaller value in the output frame. + * + * As a convenience, av_samples_get_buffer_size() and + * av_samples_fill_arrays() in libavutil may be used by custom get_buffer2() + * functions to find the required data size and to fill data pointers and + * linesize. In AVFrame.linesize, only linesize[0] may be set for audio + * since all planes must be the same size. + * + * @see av_samples_get_buffer_size(), av_samples_fill_arrays() + * + * - encoding: unused + * - decoding: Set by libavcodec, user can override. + */ + int (*get_buffer2)(struct AVCodecContext *s, AVFrame *frame, int flags); + + /* - encoding parameters */ + /** + * number of bits the bitstream is allowed to diverge from the reference. + * the reference can be CBR (for CBR pass1) or VBR (for pass2) + * - encoding: Set by user; unused for constant quantizer encoding. + * - decoding: unused + */ + int bit_rate_tolerance; + + /** + * Global quality for codecs which cannot change it per frame. + * This should be proportional to MPEG-1/2/4 qscale. + * - encoding: Set by user. + * - decoding: unused + */ + int global_quality; + + /** + * - encoding: Set by user. + * - decoding: unused + */ + int compression_level; +#define FF_COMPRESSION_DEFAULT -1 + + float qcompress; ///< amount of qscale change between easy & hard scenes (0.0-1.0) + float qblur; ///< amount of qscale smoothing over time (0.0-1.0) + + /** + * minimum quantizer + * - encoding: Set by user. + * - decoding: unused + */ + int qmin; + + /** + * maximum quantizer + * - encoding: Set by user. + * - decoding: unused + */ + int qmax; + + /** + * maximum quantizer difference between frames + * - encoding: Set by user. + * - decoding: unused + */ + int max_qdiff; + + /** + * decoder bitstream buffer size + * - encoding: Set by user. + * - decoding: May be set by libavcodec. + */ + int rc_buffer_size; + + /** + * ratecontrol override, see RcOverride + * - encoding: Allocated/set/freed by user. + * - decoding: unused + */ + int rc_override_count; + RcOverride *rc_override; + + /** + * maximum bitrate + * - encoding: Set by user. + * - decoding: Set by user, may be overwritten by libavcodec. + */ + int64_t rc_max_rate; + + /** + * minimum bitrate + * - encoding: Set by user. + * - decoding: unused + */ + int64_t rc_min_rate; + + /** + * Ratecontrol attempt to use, at maximum, of what can be used without an underflow. + * - encoding: Set by user. + * - decoding: unused. + */ + float rc_max_available_vbv_use; + + /** + * Ratecontrol attempt to use, at least, times the amount needed to prevent a vbv overflow. + * - encoding: Set by user. + * - decoding: unused. + */ + float rc_min_vbv_overflow_use; + + /** + * Number of bits which should be loaded into the rc buffer before decoding starts. + * - encoding: Set by user. + * - decoding: unused + */ + int rc_initial_buffer_occupancy; + + /** + * trellis RD quantization + * - encoding: Set by user. + * - decoding: unused + */ + int trellis; + + /** + * pass1 encoding statistics output buffer + * - encoding: Set by libavcodec. + * - decoding: unused + */ + char *stats_out; + + /** + * pass2 encoding statistics input buffer + * Concatenated stuff from stats_out of pass1 should be placed here. + * - encoding: Allocated/set/freed by user. + * - decoding: unused + */ + char *stats_in; + + /** + * Work around bugs in encoders which sometimes cannot be detected automatically. + * - encoding: Set by user + * - decoding: Set by user + */ + int workaround_bugs; +#define FF_BUG_AUTODETECT 1 ///< autodetection +#define FF_BUG_XVID_ILACE 4 +#define FF_BUG_UMP4 8 +#define FF_BUG_NO_PADDING 16 +#define FF_BUG_AMV 32 +#define FF_BUG_QPEL_CHROMA 64 +#define FF_BUG_STD_QPEL 128 +#define FF_BUG_QPEL_CHROMA2 256 +#define FF_BUG_DIRECT_BLOCKSIZE 512 +#define FF_BUG_EDGE 1024 +#define FF_BUG_HPEL_CHROMA 2048 +#define FF_BUG_DC_CLIP 4096 +#define FF_BUG_MS 8192 ///< Work around various bugs in Microsoft's broken decoders. +#define FF_BUG_TRUNCATED 16384 +#define FF_BUG_IEDGE 32768 + + /** + * strictly follow the standard (MPEG-4, ...). + * - encoding: Set by user. + * - decoding: Set by user. + * Setting this to STRICT or higher means the encoder and decoder will + * generally do stupid things, whereas setting it to unofficial or lower + * will mean the encoder might produce output that is not supported by all + * spec-compliant decoders. Decoders don't differentiate between normal, + * unofficial and experimental (that is, they always try to decode things + * when they can) unless they are explicitly asked to behave stupidly + * (=strictly conform to the specs) + * This may only be set to one of the FF_COMPLIANCE_* values in defs.h. + */ + int strict_std_compliance; + + /** + * error concealment flags + * - encoding: unused + * - decoding: Set by user. + */ + int error_concealment; +#define FF_EC_GUESS_MVS 1 +#define FF_EC_DEBLOCK 2 +#define FF_EC_FAVOR_INTER 256 + + /** + * debug + * - encoding: Set by user. + * - decoding: Set by user. + */ + int debug; +#define FF_DEBUG_PICT_INFO 1 +#define FF_DEBUG_RC 2 +#define FF_DEBUG_BITSTREAM 4 +#define FF_DEBUG_MB_TYPE 8 +#define FF_DEBUG_QP 16 +#define FF_DEBUG_DCT_COEFF 0x00000040 +#define FF_DEBUG_SKIP 0x00000080 +#define FF_DEBUG_STARTCODE 0x00000100 +#define FF_DEBUG_ER 0x00000400 +#define FF_DEBUG_MMCO 0x00000800 +#define FF_DEBUG_BUGS 0x00001000 +#define FF_DEBUG_BUFFERS 0x00008000 +#define FF_DEBUG_THREADS 0x00010000 +#define FF_DEBUG_GREEN_MD 0x00800000 +#define FF_DEBUG_NOMC 0x01000000 + + /** + * Error recognition; may misdetect some more or less valid parts as errors. + * This is a bitfield of the AV_EF_* values defined in defs.h. + * + * - encoding: Set by user. + * - decoding: Set by user. + */ + int err_recognition; + + /** + * Hardware accelerator in use + * - encoding: unused. + * - decoding: Set by libavcodec + */ + const struct AVHWAccel *hwaccel; + + /** + * Legacy hardware accelerator context. + * + * For some hardware acceleration methods, the caller may use this field to + * signal hwaccel-specific data to the codec. The struct pointed to by this + * pointer is hwaccel-dependent and defined in the respective header. Please + * refer to the FFmpeg HW accelerator documentation to know how to fill + * this. + * + * In most cases this field is optional - the necessary information may also + * be provided to libavcodec through @ref hw_frames_ctx or @ref + * hw_device_ctx (see avcodec_get_hw_config()). However, in some cases it + * may be the only method of signalling some (optional) information. + * + * The struct and its contents are owned by the caller. + * + * - encoding: May be set by the caller before avcodec_open2(). Must remain + * valid until avcodec_free_context(). + * - decoding: May be set by the caller in the get_format() callback. + * Must remain valid until the next get_format() call, + * or avcodec_free_context() (whichever comes first). + */ + void *hwaccel_context; + + /** + * A reference to the AVHWFramesContext describing the input (for encoding) + * or output (decoding) frames. The reference is set by the caller and + * afterwards owned (and freed) by libavcodec - it should never be read by + * the caller after being set. + * + * - decoding: This field should be set by the caller from the get_format() + * callback. The previous reference (if any) will always be + * unreffed by libavcodec before the get_format() call. + * + * If the default get_buffer2() is used with a hwaccel pixel + * format, then this AVHWFramesContext will be used for + * allocating the frame buffers. + * + * - encoding: For hardware encoders configured to use a hwaccel pixel + * format, this field should be set by the caller to a reference + * to the AVHWFramesContext describing input frames. + * AVHWFramesContext.format must be equal to + * AVCodecContext.pix_fmt. + * + * This field should be set before avcodec_open2() is called. + */ + AVBufferRef *hw_frames_ctx; + + /** + * A reference to the AVHWDeviceContext describing the device which will + * be used by a hardware encoder/decoder. The reference is set by the + * caller and afterwards owned (and freed) by libavcodec. + * + * This should be used if either the codec device does not require + * hardware frames or any that are used are to be allocated internally by + * libavcodec. If the user wishes to supply any of the frames used as + * encoder input or decoder output then hw_frames_ctx should be used + * instead. When hw_frames_ctx is set in get_format() for a decoder, this + * field will be ignored while decoding the associated stream segment, but + * may again be used on a following one after another get_format() call. + * + * For both encoders and decoders this field should be set before + * avcodec_open2() is called and must not be written to thereafter. + * + * Note that some decoders may require this field to be set initially in + * order to support hw_frames_ctx at all - in that case, all frames + * contexts used must be created on the same device. + */ + AVBufferRef *hw_device_ctx; + + /** + * Bit set of AV_HWACCEL_FLAG_* flags, which affect hardware accelerated + * decoding (if active). + * - encoding: unused + * - decoding: Set by user (either before avcodec_open2(), or in the + * AVCodecContext.get_format callback) + */ + int hwaccel_flags; + + /** + * Video decoding only. Sets the number of extra hardware frames which + * the decoder will allocate for use by the caller. This must be set + * before avcodec_open2() is called. + * + * Some hardware decoders require all frames that they will use for + * output to be defined in advance before decoding starts. For such + * decoders, the hardware frame pool must therefore be of a fixed size. + * The extra frames set here are on top of any number that the decoder + * needs internally in order to operate normally (for example, frames + * used as reference pictures). + */ + int extra_hw_frames; + + /** + * error + * - encoding: Set by libavcodec if flags & AV_CODEC_FLAG_PSNR. + * - decoding: unused + */ + uint64_t error[AV_NUM_DATA_POINTERS]; + + /** + * DCT algorithm, see FF_DCT_* below + * - encoding: Set by user. + * - decoding: unused + */ + int dct_algo; +#define FF_DCT_AUTO 0 +#define FF_DCT_FASTINT 1 +#define FF_DCT_INT 2 +#define FF_DCT_MMX 3 +#define FF_DCT_ALTIVEC 5 +#define FF_DCT_FAAN 6 +#define FF_DCT_NEON 7 + + /** + * IDCT algorithm, see FF_IDCT_* below. + * - encoding: Set by user. + * - decoding: Set by user. + */ + int idct_algo; +#define FF_IDCT_AUTO 0 +#define FF_IDCT_INT 1 +#define FF_IDCT_SIMPLE 2 +#define FF_IDCT_SIMPLEMMX 3 +#define FF_IDCT_ARM 7 +#define FF_IDCT_ALTIVEC 8 +#define FF_IDCT_SIMPLEARM 10 +#define FF_IDCT_XVID 14 +#define FF_IDCT_SIMPLEARMV5TE 16 +#define FF_IDCT_SIMPLEARMV6 17 +#define FF_IDCT_FAAN 20 +#define FF_IDCT_SIMPLENEON 22 +#define FF_IDCT_SIMPLEAUTO 128 + + /** + * bits per sample/pixel from the demuxer (needed for huffyuv). + * - encoding: Set by libavcodec. + * - decoding: Set by user. + */ + int bits_per_coded_sample; + + /** + * Bits per sample/pixel of internal libavcodec pixel/sample format. + * - encoding: set by user. + * - decoding: set by libavcodec. + */ + int bits_per_raw_sample; + + /** + * thread count + * is used to decide how many independent tasks should be passed to execute() + * - encoding: Set by user. + * - decoding: Set by user. + */ + int thread_count; + + /** + * Which multithreading methods to use. + * Use of FF_THREAD_FRAME will increase decoding delay by one frame per thread, + * so clients which cannot provide future frames should not use it. + * + * - encoding: Set by user, otherwise the default is used. + * - decoding: Set by user, otherwise the default is used. + */ + int thread_type; +#define FF_THREAD_FRAME 1 ///< Decode more than one frame at once +#define FF_THREAD_SLICE 2 ///< Decode more than one part of a single frame at once + + /** + * Which multithreading methods are in use by the codec. + * - encoding: Set by libavcodec. + * - decoding: Set by libavcodec. + */ + int active_thread_type; + + /** + * The codec may call this to execute several independent things. + * It will return only after finishing all tasks. + * The user may replace this with some multithreaded implementation, + * the default implementation will execute the parts serially. + * @param count the number of things to execute + * - encoding: Set by libavcodec, user can override. + * - decoding: Set by libavcodec, user can override. + */ + int (*execute)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg), void *arg2, int *ret, int count, int size); + + /** + * The codec may call this to execute several independent things. + * It will return only after finishing all tasks. + * The user may replace this with some multithreaded implementation, + * the default implementation will execute the parts serially. + * @param c context passed also to func + * @param count the number of things to execute + * @param arg2 argument passed unchanged to func + * @param ret return values of executed functions, must have space for "count" values. May be NULL. + * @param func function that will be called count times, with jobnr from 0 to count-1. + * threadnr will be in the range 0 to c->thread_count-1 < MAX_THREADS and so that no + * two instances of func executing at the same time will have the same threadnr. + * @return always 0 currently, but code should handle a future improvement where when any call to func + * returns < 0 no further calls to func may be done and < 0 is returned. + * - encoding: Set by libavcodec, user can override. + * - decoding: Set by libavcodec, user can override. + */ + int (*execute2)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg, int jobnr, int threadnr), void *arg2, int *ret, int count); + + /** + * profile + * - encoding: Set by user. + * - decoding: Set by libavcodec. + * See the AV_PROFILE_* defines in defs.h. + */ + int profile; + + /** + * Encoding level descriptor. + * - encoding: Set by user, corresponds to a specific level defined by the + * codec, usually corresponding to the profile level, if not specified it + * is set to AV_LEVEL_UNKNOWN. + * - decoding: Set by libavcodec. + * See AV_LEVEL_* in defs.h. + */ + int level; + +#if FF_API_CODEC_PROPS + /** + * Properties of the stream that gets decoded + * - encoding: unused + * - decoding: set by libavcodec + */ + attribute_deprecated + unsigned properties; +#define FF_CODEC_PROPERTY_LOSSLESS 0x00000001 +#define FF_CODEC_PROPERTY_CLOSED_CAPTIONS 0x00000002 +#define FF_CODEC_PROPERTY_FILM_GRAIN 0x00000004 +#endif + + /** + * Skip loop filtering for selected frames. + * - encoding: unused + * - decoding: Set by user. + */ + enum AVDiscard skip_loop_filter; + + /** + * Skip IDCT/dequantization for selected frames. + * - encoding: unused + * - decoding: Set by user. + */ + enum AVDiscard skip_idct; + + /** + * Skip decoding for selected frames. + * - encoding: unused + * - decoding: Set by user. + */ + enum AVDiscard skip_frame; + + /** + * Skip processing alpha if supported by codec. + * Note that if the format uses pre-multiplied alpha (common with VP6, + * and recommended due to better video quality/compression) + * the image will look as if alpha-blended onto a black background. + * However for formats that do not use pre-multiplied alpha + * there might be serious artefacts (though e.g. libswscale currently + * assumes pre-multiplied alpha anyway). + * + * - decoding: set by user + * - encoding: unused + */ + int skip_alpha; + + /** + * Number of macroblock rows at the top which are skipped. + * - encoding: unused + * - decoding: Set by user. + */ + int skip_top; + + /** + * Number of macroblock rows at the bottom which are skipped. + * - encoding: unused + * - decoding: Set by user. + */ + int skip_bottom; + + /** + * low resolution decoding, 1-> 1/2 size, 2->1/4 size + * - encoding: unused + * - decoding: Set by user. + */ + int lowres; + + /** + * AVCodecDescriptor + * - encoding: unused. + * - decoding: set by libavcodec. + */ + const struct AVCodecDescriptor *codec_descriptor; + + /** + * Character encoding of the input subtitles file. + * - decoding: set by user + * - encoding: unused + */ + char *sub_charenc; + + /** + * Subtitles character encoding mode. Formats or codecs might be adjusting + * this setting (if they are doing the conversion themselves for instance). + * - decoding: set by libavcodec + * - encoding: unused + */ + int sub_charenc_mode; +#define FF_SUB_CHARENC_MODE_DO_NOTHING -1 ///< do nothing (demuxer outputs a stream supposed to be already in UTF-8, or the codec is bitmap for instance) +#define FF_SUB_CHARENC_MODE_AUTOMATIC 0 ///< libavcodec will select the mode itself +#define FF_SUB_CHARENC_MODE_PRE_DECODER 1 ///< the AVPacket data needs to be recoded to UTF-8 before being fed to the decoder, requires iconv +#define FF_SUB_CHARENC_MODE_IGNORE 2 ///< neither convert the subtitles, nor check them for valid UTF-8 + + /** + * Header containing style information for text subtitles. + * For SUBTITLE_ASS subtitle type, it should contain the whole ASS + * [Script Info] and [V4+ Styles] section, plus the [Events] line and + * the Format line following. It shouldn't include any Dialogue line. + * + * - encoding: May be set by the caller before avcodec_open2() to an array + * allocated with the av_malloc() family of functions. + * - decoding: May be set by libavcodec in avcodec_open2(). + * + * After being set, the array is owned by the codec and freed in + * avcodec_free_context(). + */ + int subtitle_header_size; + uint8_t *subtitle_header; + + /** + * dump format separator. + * can be ", " or "\n " or anything else + * - encoding: Set by user. + * - decoding: Set by user. + */ + uint8_t *dump_separator; + + /** + * ',' separated list of allowed decoders. + * If NULL then all are allowed + * - encoding: unused + * - decoding: set by user + */ + char *codec_whitelist; + + /** + * Additional data associated with the entire coded stream. + * + * - decoding: may be set by user before calling avcodec_open2(). + * - encoding: may be set by libavcodec after avcodec_open2(). + */ + AVPacketSideData *coded_side_data; + int nb_coded_side_data; + + /** + * Bit set of AV_CODEC_EXPORT_DATA_* flags, which affects the kind of + * metadata exported in frame, packet, or coded stream side data by + * decoders and encoders. + * + * - decoding: set by user + * - encoding: set by user + */ + int export_side_data; + + /** + * The number of pixels per image to maximally accept. + * + * - decoding: set by user + * - encoding: set by user + */ + int64_t max_pixels; + + /** + * Video decoding only. Certain video codecs support cropping, meaning that + * only a sub-rectangle of the decoded frame is intended for display. This + * option controls how cropping is handled by libavcodec. + * + * When set to 1 (the default), libavcodec will apply cropping internally. + * I.e. it will modify the output frame width/height fields and offset the + * data pointers (only by as much as possible while preserving alignment, or + * by the full amount if the AV_CODEC_FLAG_UNALIGNED flag is set) so that + * the frames output by the decoder refer only to the cropped area. The + * crop_* fields of the output frames will be zero. + * + * When set to 0, the width/height fields of the output frames will be set + * to the coded dimensions and the crop_* fields will describe the cropping + * rectangle. Applying the cropping is left to the caller. + * + * @warning When hardware acceleration with opaque output frames is used, + * libavcodec is unable to apply cropping from the top/left border. + * + * @note when this option is set to zero, the width/height fields of the + * AVCodecContext and output AVFrames have different meanings. The codec + * context fields store display dimensions (with the coded dimensions in + * coded_width/height), while the frame fields store the coded dimensions + * (with the display dimensions being determined by the crop_* fields). + */ + int apply_cropping; + + /** + * The percentage of damaged samples to discard a frame. + * + * - decoding: set by user + * - encoding: unused + */ + int discard_damaged_percentage; + + /** + * The number of samples per frame to maximally accept. + * + * - decoding: set by user + * - encoding: set by user + */ + int64_t max_samples; + + /** + * This callback is called at the beginning of each packet to get a data + * buffer for it. + * + * The following field will be set in the packet before this callback is + * called: + * - size + * This callback must use the above value to calculate the required buffer size, + * which must padded by at least AV_INPUT_BUFFER_PADDING_SIZE bytes. + * + * In some specific cases, the encoder may not use the entire buffer allocated by this + * callback. This will be reflected in the size value in the packet once returned by + * avcodec_receive_packet(). + * + * This callback must fill the following fields in the packet: + * - data: alignment requirements for AVPacket apply, if any. Some architectures and + * encoders may benefit from having aligned data. + * - buf: must contain a pointer to an AVBufferRef structure. The packet's + * data pointer must be contained in it. See: av_buffer_create(), av_buffer_alloc(), + * and av_buffer_ref(). + * + * If AV_CODEC_CAP_DR1 is not set then get_encode_buffer() must call + * avcodec_default_get_encode_buffer() instead of providing a buffer allocated by + * some other means. + * + * The flags field may contain a combination of AV_GET_ENCODE_BUFFER_FLAG_ flags. + * They may be used for example to hint what use the buffer may get after being + * created. + * Implementations of this callback may ignore flags they don't understand. + * If AV_GET_ENCODE_BUFFER_FLAG_REF is set in flags then the packet may be reused + * (read and/or written to if it is writable) later by libavcodec. + * + * This callback must be thread-safe, as when frame threading is used, it may + * be called from multiple threads simultaneously. + * + * @see avcodec_default_get_encode_buffer() + * + * - encoding: Set by libavcodec, user can override. + * - decoding: unused + */ + int (*get_encode_buffer)(struct AVCodecContext *s, AVPacket *pkt, int flags); + + /** + * Frame counter, set by libavcodec. + * + * - decoding: total number of frames returned from the decoder so far. + * - encoding: total number of frames passed to the encoder so far. + * + * @note the counter is not incremented if encoding/decoding resulted in + * an error. + */ + int64_t frame_num; + + /** + * Decoding only. May be set by the caller before avcodec_open2() to an + * av_malloc()'ed array (or via AVOptions). Owned and freed by the decoder + * afterwards. + * + * Side data attached to decoded frames may come from several sources: + * 1. coded_side_data, which the decoder will for certain types translate + * from packet-type to frame-type and attach to frames; + * 2. side data attached to an AVPacket sent for decoding (same + * considerations as above); + * 3. extracted from the coded bytestream. + * The first two cases are supplied by the caller and typically come from a + * container. + * + * This array configures decoder behaviour in cases when side data of the + * same type is present both in the coded bytestream and in the + * user-supplied side data (items 1. and 2. above). In all cases, at most + * one instance of each side data type will be attached to output frames. By + * default it will be the bytestream side data. Adding an + * AVPacketSideDataType value to this array will flip the preference for + * this type, thus making the decoder prefer user-supplied side data over + * bytestream. In case side data of the same type is present both in + * coded_data and attacked to a packet, the packet instance always has + * priority. + * + * The array may also contain a single -1, in which case the preference is + * switched for all side data types. + */ + int *side_data_prefer_packet; + /** + * Number of entries in side_data_prefer_packet. + */ + unsigned nb_side_data_prefer_packet; + + /** + * Array containing static side data, such as HDR10 CLL / MDCV structures. + * Side data entries should be allocated by usage of helpers defined in + * libavutil/frame.h. + * + * - encoding: may be set by user before calling avcodec_open2() for + * encoder configuration. Afterwards owned and freed by the + * encoder. + * - decoding: may be set by libavcodec in avcodec_open2(). + */ + AVFrameSideData **decoded_side_data; + int nb_decoded_side_data; + + /** + * Indicates how the alpha channel of the video is represented. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVAlphaMode alpha_mode; +} AVCodecContext; + +/** + * @defgroup lavc_hwaccel AVHWAccel + * + * @note Nothing in this structure should be accessed by the user. At some + * point in future it will not be externally visible at all. + * + * @{ + */ +typedef struct AVHWAccel { + /** + * Name of the hardware accelerated codec. + * The name is globally unique among encoders and among decoders (but an + * encoder and a decoder can share the same name). + */ + const char *name; + + /** + * Type of codec implemented by the hardware accelerator. + * + * See AVMEDIA_TYPE_xxx + */ + enum AVMediaType type; + + /** + * Codec implemented by the hardware accelerator. + * + * See AV_CODEC_ID_xxx + */ + enum AVCodecID id; + + /** + * Supported pixel format. + * + * Only hardware accelerated formats are supported here. + */ + enum AVPixelFormat pix_fmt; + + /** + * Hardware accelerated codec capabilities. + * see AV_HWACCEL_CODEC_CAP_* + */ + int capabilities; +} AVHWAccel; + +/** + * HWAccel is experimental and is thus avoided in favor of non experimental + * codecs + */ +#define AV_HWACCEL_CODEC_CAP_EXPERIMENTAL 0x0200 + +/** + * Hardware acceleration should be used for decoding even if the codec level + * used is unknown or higher than the maximum supported level reported by the + * hardware driver. + * + * It's generally a good idea to pass this flag unless you have a specific + * reason not to, as hardware tends to under-report supported levels. + */ +#define AV_HWACCEL_FLAG_IGNORE_LEVEL (1 << 0) + +/** + * Hardware acceleration can output YUV pixel formats with a different chroma + * sampling than 4:2:0 and/or other than 8 bits per component. + */ +#define AV_HWACCEL_FLAG_ALLOW_HIGH_DEPTH (1 << 1) + +/** + * Hardware acceleration should still be attempted for decoding when the + * codec profile does not match the reported capabilities of the hardware. + * + * For example, this can be used to try to decode baseline profile H.264 + * streams in hardware - it will often succeed, because many streams marked + * as baseline profile actually conform to constrained baseline profile. + * + * @warning If the stream is actually not supported then the behaviour is + * undefined, and may include returning entirely incorrect output + * while indicating success. + */ +#define AV_HWACCEL_FLAG_ALLOW_PROFILE_MISMATCH (1 << 2) + +/** + * Some hardware decoders (namely nvdec) can either output direct decoder + * surfaces, or make an on-device copy and return said copy. + * There is a hard limit on how many decoder surfaces there can be, and it + * cannot be accurately guessed ahead of time. + * For some processing chains, this can be okay, but others will run into the + * limit and in turn produce very confusing errors that require fine tuning of + * more or less obscure options by the user, or in extreme cases cannot be + * resolved at all without inserting an avfilter that forces a copy. + * + * Thus, the hwaccel will by default make a copy for safety and resilience. + * If a users really wants to minimize the amount of copies, they can set this + * flag and ensure their processing chain does not exhaust the surface pool. + */ +#define AV_HWACCEL_FLAG_UNSAFE_OUTPUT (1 << 3) + +/** + * @} + */ + +enum AVSubtitleType { + SUBTITLE_NONE, + + SUBTITLE_BITMAP, ///< A bitmap, pict will be set + + /** + * Plain text, the text field must be set by the decoder and is + * authoritative. ass and pict fields may contain approximations. + */ + SUBTITLE_TEXT, + + /** + * Formatted text, the ass field must be set by the decoder and is + * authoritative. pict and text fields may contain approximations. + */ + SUBTITLE_ASS, +}; + +#define AV_SUBTITLE_FLAG_FORCED 0x00000001 + +typedef struct AVSubtitleRect { + int x; ///< top left corner of pict, undefined when pict is not set + int y; ///< top left corner of pict, undefined when pict is not set + int w; ///< width of pict, undefined when pict is not set + int h; ///< height of pict, undefined when pict is not set + int nb_colors; ///< number of colors in pict, undefined when pict is not set + + /** + * data+linesize for the bitmap of this subtitle. + * Can be set for text/ass as well once they are rendered. + */ + uint8_t *data[4]; + int linesize[4]; + + int flags; + enum AVSubtitleType type; + + char *text; ///< 0 terminated plain UTF-8 text + + /** + * 0 terminated ASS/SSA compatible event line. + * The presentation of this is unaffected by the other values in this + * struct. + */ + char *ass; +} AVSubtitleRect; + +typedef struct AVSubtitle { + uint16_t format; /* 0 = graphics */ + uint32_t start_display_time; /* relative to packet pts, in ms */ + uint32_t end_display_time; /* relative to packet pts, in ms */ + unsigned num_rects; + AVSubtitleRect **rects; + int64_t pts; ///< Same as packet pts, in AV_TIME_BASE +} AVSubtitle; + +/** + * Return the LIBAVCODEC_VERSION_INT constant. + */ +unsigned avcodec_version(void); + +/** + * Return the libavcodec build-time configuration. + */ +const char *avcodec_configuration(void); + +/** + * Return the libavcodec license. + */ +const char *avcodec_license(void); + +/** + * Allocate an AVCodecContext and set its fields to default values. The + * resulting struct should be freed with avcodec_free_context(). + * + * @param codec if non-NULL, allocate private data and initialize defaults + * for the given codec. It is illegal to then call avcodec_open2() + * with a different codec. + * If NULL, then the codec-specific defaults won't be initialized, + * which may result in suboptimal default settings (this is + * important mainly for encoders, e.g. libx264). + * + * @return An AVCodecContext filled with default values or NULL on failure. + */ +AVCodecContext *avcodec_alloc_context3(const AVCodec *codec); + +/** + * Free the codec context and everything associated with it and write NULL to + * the provided pointer. + */ +void avcodec_free_context(AVCodecContext **avctx); + +/** + * Get the AVClass for AVCodecContext. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *avcodec_get_class(void); + +/** + * Get the AVClass for AVSubtitleRect. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *avcodec_get_subtitle_rect_class(void); + +/** + * Fill the parameters struct based on the values from the supplied codec + * context. Any allocated fields in par are freed and replaced with duplicates + * of the corresponding fields in codec. + * + * @return >= 0 on success, a negative AVERROR code on failure + */ +int avcodec_parameters_from_context(struct AVCodecParameters *par, + const AVCodecContext *codec); + +/** + * Fill the codec context based on the values from the supplied codec + * parameters. Any allocated fields in codec that have a corresponding field in + * par are freed and replaced with duplicates of the corresponding field in par. + * Fields in codec that do not have a counterpart in par are not touched. + * + * @return >= 0 on success, a negative AVERROR code on failure. + */ +int avcodec_parameters_to_context(AVCodecContext *codec, + const struct AVCodecParameters *par); + +/** + * Initialize the AVCodecContext to use the given AVCodec. Prior to using this + * function the context has to be allocated with avcodec_alloc_context3(). + * + * The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(), + * avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for + * retrieving a codec. + * + * Depending on the codec, you might need to set options in the codec context + * also for decoding (e.g. width, height, or the pixel or audio sample format in + * the case the information is not available in the bitstream, as when decoding + * raw audio or video). + * + * Options in the codec context can be set either by setting them in the options + * AVDictionary, or by setting the values in the context itself, directly or by + * using the av_opt_set() API before calling this function. + * + * Example: + * @code + * av_dict_set(&opts, "b", "2.5M", 0); + * codec = avcodec_find_decoder(AV_CODEC_ID_H264); + * if (!codec) + * exit(1); + * + * context = avcodec_alloc_context3(codec); + * + * if (avcodec_open2(context, codec, opts) < 0) + * exit(1); + * @endcode + * + * In the case AVCodecParameters are available (e.g. when demuxing a stream + * using libavformat, and accessing the AVStream contained in the demuxer), the + * codec parameters can be copied to the codec context using + * avcodec_parameters_to_context(), as in the following example: + * + * @code + * AVStream *stream = ...; + * context = avcodec_alloc_context3(codec); + * if (avcodec_parameters_to_context(context, stream->codecpar) < 0) + * exit(1); + * if (avcodec_open2(context, codec, NULL) < 0) + * exit(1); + * @endcode + * + * @note Always call this function before using decoding routines (such as + * @ref avcodec_receive_frame()). + * + * @param avctx The context to initialize. + * @param codec The codec to open this context for. If a non-NULL codec has been + * previously passed to avcodec_alloc_context3() or + * for this context, then this parameter MUST be either NULL or + * equal to the previously passed codec. + * @param options A dictionary filled with AVCodecContext and codec-private + * options, which are set on top of the options already set in + * avctx, can be NULL. On return this object will be filled with + * options that were not found in the avctx codec context. + * + * @return zero on success, a negative value on error + * @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(), + * av_dict_set(), av_opt_set(), av_opt_find(), avcodec_parameters_to_context() + */ +int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options); + +/** + * Free all allocated data in the given subtitle struct. + * + * @param sub AVSubtitle to free. + */ +void avsubtitle_free(AVSubtitle *sub); + +/** + * @} + */ + +/** + * @addtogroup lavc_decoding + * @{ + */ + +/** + * The default callback for AVCodecContext.get_buffer2(). It is made public so + * it can be called by custom get_buffer2() implementations for decoders without + * AV_CODEC_CAP_DR1 set. + */ +int avcodec_default_get_buffer2(AVCodecContext *s, AVFrame *frame, int flags); + +/** + * The default callback for AVCodecContext.get_encode_buffer(). It is made public so + * it can be called by custom get_encode_buffer() implementations for encoders without + * AV_CODEC_CAP_DR1 set. + */ +int avcodec_default_get_encode_buffer(AVCodecContext *s, AVPacket *pkt, int flags); + +/** + * Modify width and height values so that they will result in a memory + * buffer that is acceptable for the codec if you do not use any horizontal + * padding. + * + * May only be used if a codec with AV_CODEC_CAP_DR1 has been opened. + */ +void avcodec_align_dimensions(AVCodecContext *s, int *width, int *height); + +/** + * Modify width and height values so that they will result in a memory + * buffer that is acceptable for the codec if you also ensure that all + * line sizes are a multiple of the respective linesize_align[i]. + * + * May only be used if a codec with AV_CODEC_CAP_DR1 has been opened. + */ +void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height, + int linesize_align[AV_NUM_DATA_POINTERS]); + +/** + * Decode a subtitle message. + * Return a negative value on error, otherwise return the number of bytes used. + * If no subtitle could be decompressed, got_sub_ptr is zero. + * Otherwise, the subtitle is stored in *sub. + * Note that AV_CODEC_CAP_DR1 is not available for subtitle codecs. This is for + * simplicity, because the performance difference is expected to be negligible + * and reusing a get_buffer written for video codecs would probably perform badly + * due to a potentially very different allocation pattern. + * + * Some decoders (those marked with AV_CODEC_CAP_DELAY) have a delay between input + * and output. This means that for some packets they will not immediately + * produce decoded output and need to be flushed at the end of decoding to get + * all the decoded data. Flushing is done by calling this function with packets + * with avpkt->data set to NULL and avpkt->size set to 0 until it stops + * returning subtitles. It is safe to flush even those decoders that are not + * marked with AV_CODEC_CAP_DELAY, then no subtitles will be returned. + * + * @note The AVCodecContext MUST have been opened with @ref avcodec_open2() + * before packets may be fed to the decoder. + * + * @param avctx the codec context + * @param[out] sub The preallocated AVSubtitle in which the decoded subtitle will be stored, + * must be freed with avsubtitle_free if *got_sub_ptr is set. + * @param[in,out] got_sub_ptr Zero if no subtitle could be decompressed, otherwise, it is nonzero. + * @param[in] avpkt The input AVPacket containing the input buffer. + */ +int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub, + int *got_sub_ptr, const AVPacket *avpkt); + +/** + * Supply raw packet data as input to a decoder. + * + * Internally, this call will copy relevant AVCodecContext fields, which can + * influence decoding per-packet, and apply them when the packet is actually + * decoded. (For example AVCodecContext.skip_frame, which might direct the + * decoder to drop the frame contained by the packet sent with this function.) + * + * @warning The input buffer, avpkt->data must be AV_INPUT_BUFFER_PADDING_SIZE + * larger than the actual read bytes because some optimized bitstream + * readers read 32 or 64 bits at once and could read over the end. + * + * @note The AVCodecContext MUST have been opened with @ref avcodec_open2() + * before packets may be fed to the decoder. + * + * @param avctx codec context + * @param[in] avpkt The input AVPacket. Usually, this will be a single video + * frame, or several complete audio frames. + * Ownership of the packet remains with the caller, and the + * decoder will not write to the packet. The decoder may create + * a reference to the packet data (or copy it if the packet is + * not reference-counted). + * Unlike with older APIs, the packet is always fully consumed, + * and if it contains multiple frames (e.g. some audio codecs), + * will require you to call avcodec_receive_frame() multiple + * times afterwards before you can send a new packet. + * It can be NULL (or an AVPacket with data set to NULL and + * size set to 0); in this case, it is considered a flush + * packet, which signals the end of the stream. Sending the + * first flush packet will return success. Subsequent ones are + * unnecessary and will return AVERROR_EOF. If the decoder + * still has frames buffered, it will return them after sending + * a flush packet. + * + * @retval 0 success + * @retval AVERROR(EAGAIN) input is not accepted in the current state - user + * must read output with avcodec_receive_frame() (once + * all output is read, the packet should be resent, + * and the call will not fail with EAGAIN). + * @retval AVERROR_EOF the decoder has been flushed, and no new packets can be + * sent to it (also returned if more than 1 flush + * packet is sent) + * @retval AVERROR(EINVAL) codec not opened, it is an encoder, or requires flush + * @retval AVERROR(ENOMEM) failed to add packet to internal queue, or similar + * @retval "another negative error code" legitimate decoding errors + */ +int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt); + +/** + * Return decoded output data from a decoder or encoder (when the + * @ref AV_CODEC_FLAG_RECON_FRAME flag is used). + * + * @param avctx codec context + * @param frame This will be set to a reference-counted video or audio + * frame (depending on the decoder type) allocated by the + * codec. Note that the function will always call + * av_frame_unref(frame) before doing anything else. + * @param flags Combination of AV_CODEC_RECEIVE_FRAME_FLAG_* flags. + * + * @retval 0 success, a frame was returned + * @retval AVERROR(EAGAIN) output is not available in this state - user must + * try to send new input + * @retval AVERROR_EOF the codec has been fully flushed, and there will be + * no more output frames + * @retval AVERROR(EINVAL) codec not opened, or it is an encoder without the + * @ref AV_CODEC_FLAG_RECON_FRAME flag enabled + * @retval "other negative error code" legitimate decoding errors + */ +int avcodec_receive_frame_flags(AVCodecContext *avctx, AVFrame *frame, unsigned flags); + +/** + * Alias for `avcodec_receive_frame_flags(avctx, frame, 0)`. + */ +int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame); + +/** + * Supply a raw video or audio frame to the encoder. Use avcodec_receive_packet() + * to retrieve buffered output packets. + * + * @param avctx codec context + * @param[in] frame AVFrame containing the raw audio or video frame to be encoded. + * Ownership of the frame remains with the caller, and the + * encoder will not write to the frame. The encoder may create + * a reference to the frame data (or copy it if the frame is + * not reference-counted). + * It can be NULL, in which case it is considered a flush + * packet. This signals the end of the stream. If the encoder + * still has packets buffered, it will return them after this + * call. Once flushing mode has been entered, additional flush + * packets are ignored, and sending frames will return + * AVERROR_EOF. + * + * For audio: + * If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame + * can have any number of samples. + * If it is not set, frame->nb_samples must be equal to + * avctx->frame_size for all frames except the last. + * The final frame may be smaller than avctx->frame_size. + * @retval 0 success + * @retval AVERROR(EAGAIN) input is not accepted in the current state - user must + * read output with avcodec_receive_packet() (once all + * output is read, the packet should be resent, and the + * call will not fail with EAGAIN). + * @retval AVERROR_EOF the encoder has been flushed, and no new frames can + * be sent to it + * @retval AVERROR(EINVAL) codec not opened, it is a decoder, or requires flush + * @retval AVERROR(ENOMEM) failed to add packet to internal queue, or similar + * @retval "another negative error code" legitimate encoding errors + */ +int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame); + +/** + * Read encoded data from the encoder. + * + * @param avctx codec context + * @param avpkt This will be set to a reference-counted packet allocated by the + * encoder. Note that the function will always call + * av_packet_unref(avpkt) before doing anything else. + * @retval 0 success + * @retval AVERROR(EAGAIN) output is not available in the current state - user must + * try to send input + * @retval AVERROR_EOF the encoder has been fully flushed, and there will be no + * more output packets + * @retval AVERROR(EINVAL) codec not opened, or it is a decoder + * @retval "another negative error code" legitimate encoding errors + */ +int avcodec_receive_packet(AVCodecContext *avctx, AVPacket *avpkt); + +/** + * Create and return a AVHWFramesContext with values adequate for hardware + * decoding. This is meant to get called from the get_format callback, and is + * a helper for preparing a AVHWFramesContext for AVCodecContext.hw_frames_ctx. + * This API is for decoding with certain hardware acceleration modes/APIs only. + * + * The returned AVHWFramesContext is not initialized. The caller must do this + * with av_hwframe_ctx_init(). + * + * Calling this function is not a requirement, but makes it simpler to avoid + * codec or hardware API specific details when manually allocating frames. + * + * Alternatively to this, an API user can set AVCodecContext.hw_device_ctx, + * which sets up AVCodecContext.hw_frames_ctx fully automatically, and makes + * it unnecessary to call this function or having to care about + * AVHWFramesContext initialization at all. + * + * There are a number of requirements for calling this function: + * + * - It must be called from get_format with the same avctx parameter that was + * passed to get_format. Calling it outside of get_format is not allowed, and + * can trigger undefined behavior. + * - The function is not always supported (see description of return values). + * Even if this function returns successfully, hwaccel initialization could + * fail later. (The degree to which implementations check whether the stream + * is actually supported varies. Some do this check only after the user's + * get_format callback returns.) + * - The hw_pix_fmt must be one of the choices suggested by get_format. If the + * user decides to use a AVHWFramesContext prepared with this API function, + * the user must return the same hw_pix_fmt from get_format. + * - The device_ref passed to this function must support the given hw_pix_fmt. + * - After calling this API function, it is the user's responsibility to + * initialize the AVHWFramesContext (returned by the out_frames_ref parameter), + * and to set AVCodecContext.hw_frames_ctx to it. If done, this must be done + * before returning from get_format (this is implied by the normal + * AVCodecContext.hw_frames_ctx API rules). + * - The AVHWFramesContext parameters may change every time time get_format is + * called. Also, AVCodecContext.hw_frames_ctx is reset before get_format. So + * you are inherently required to go through this process again on every + * get_format call. + * - It is perfectly possible to call this function without actually using + * the resulting AVHWFramesContext. One use-case might be trying to reuse a + * previously initialized AVHWFramesContext, and calling this API function + * only to test whether the required frame parameters have changed. + * - Fields that use dynamically allocated values of any kind must not be set + * by the user unless setting them is explicitly allowed by the documentation. + * If the user sets AVHWFramesContext.free and AVHWFramesContext.user_opaque, + * the new free callback must call the potentially set previous free callback. + * This API call may set any dynamically allocated fields, including the free + * callback. + * + * The function will set at least the following fields on AVHWFramesContext + * (potentially more, depending on hwaccel API): + * + * - All fields set by av_hwframe_ctx_alloc(). + * - Set the format field to hw_pix_fmt. + * - Set the sw_format field to the most suited and most versatile format. (An + * implication is that this will prefer generic formats over opaque formats + * with arbitrary restrictions, if possible.) + * - Set the width/height fields to the coded frame size, rounded up to the + * API-specific minimum alignment. + * - Only _if_ the hwaccel requires a pre-allocated pool: set the initial_pool_size + * field to the number of maximum reference surfaces possible with the codec, + * plus 1 surface for the user to work (meaning the user can safely reference + * at most 1 decoded surface at a time), plus additional buffering introduced + * by frame threading. If the hwaccel does not require pre-allocation, the + * field is left to 0, and the decoder will allocate new surfaces on demand + * during decoding. + * - Possibly AVHWFramesContext.hwctx fields, depending on the underlying + * hardware API. + * + * Essentially, out_frames_ref returns the same as av_hwframe_ctx_alloc(), but + * with basic frame parameters set. + * + * The function is stateless, and does not change the AVCodecContext or the + * device_ref AVHWDeviceContext. + * + * @param avctx The context which is currently calling get_format, and which + * implicitly contains all state needed for filling the returned + * AVHWFramesContext properly. + * @param device_ref A reference to the AVHWDeviceContext describing the device + * which will be used by the hardware decoder. + * @param hw_pix_fmt The hwaccel format you are going to return from get_format. + * @param out_frames_ref On success, set to a reference to an _uninitialized_ + * AVHWFramesContext, created from the given device_ref. + * Fields will be set to values required for decoding. + * Not changed if an error is returned. + * @return zero on success, a negative value on error. The following error codes + * have special semantics: + * AVERROR(ENOENT): the decoder does not support this functionality. Setup + * is always manual, or it is a decoder which does not + * support setting AVCodecContext.hw_frames_ctx at all, + * or it is a software format. + * AVERROR(EINVAL): it is known that hardware decoding is not supported for + * this configuration, or the device_ref is not supported + * for the hwaccel referenced by hw_pix_fmt. + */ +int avcodec_get_hw_frames_parameters(AVCodecContext *avctx, + AVBufferRef *device_ref, + enum AVPixelFormat hw_pix_fmt, + AVBufferRef **out_frames_ref); + +enum AVCodecConfig { + AV_CODEC_CONFIG_PIX_FORMAT, ///< AVPixelFormat, terminated by AV_PIX_FMT_NONE + AV_CODEC_CONFIG_FRAME_RATE, ///< AVRational, terminated by {0, 0} + AV_CODEC_CONFIG_SAMPLE_RATE, ///< int, terminated by 0 + AV_CODEC_CONFIG_SAMPLE_FORMAT, ///< AVSampleFormat, terminated by AV_SAMPLE_FMT_NONE + AV_CODEC_CONFIG_CHANNEL_LAYOUT, ///< AVChannelLayout, terminated by {0} + AV_CODEC_CONFIG_COLOR_RANGE, ///< AVColorRange, terminated by AVCOL_RANGE_UNSPECIFIED + AV_CODEC_CONFIG_COLOR_SPACE, ///< AVColorSpace, terminated by AVCOL_SPC_UNSPECIFIED + AV_CODEC_CONFIG_ALPHA_MODE, ///< AVAlphaMode, terminated by AVALPHA_MODE_UNSPECIFIED +}; + +/** + * Retrieve a list of all supported values for a given configuration type. + * + * @param avctx An optional context to use. Values such as + * `strict_std_compliance` may affect the result. If NULL, + * default values are used. + * @param codec The codec to query, or NULL to use avctx->codec. + * @param config The configuration to query. + * @param flags Currently unused; should be set to zero. + * @param out_configs On success, set to a list of configurations, terminated + * by a config-specific terminator, or NULL if all + * possible values are supported. + * @param out_num_configs On success, set to the number of elements in + *out_configs, excluding the terminator. Optional. + */ +int avcodec_get_supported_config(const AVCodecContext *avctx, + const AVCodec *codec, enum AVCodecConfig config, + unsigned flags, const void **out_configs, + int *out_num_configs); + + + +/** + * @defgroup lavc_parsing Frame parsing + * @{ + */ + +enum AVPictureStructure { + AV_PICTURE_STRUCTURE_UNKNOWN, ///< unknown + AV_PICTURE_STRUCTURE_TOP_FIELD, ///< coded as top field + AV_PICTURE_STRUCTURE_BOTTOM_FIELD, ///< coded as bottom field + AV_PICTURE_STRUCTURE_FRAME, ///< coded as frame +}; + +typedef struct AVCodecParserContext { + void *priv_data; + const struct AVCodecParser *parser; + int64_t frame_offset; /* offset of the current frame */ + int64_t cur_offset; /* current offset + (incremented by each av_parser_parse()) */ + int64_t next_frame_offset; /* offset of the next frame */ + /* video info */ + int pict_type; /* XXX: Put it back in AVCodecContext. */ + /** + * This field is used for proper frame duration computation in lavf. + * It signals, how much longer the frame duration of the current frame + * is compared to normal frame duration. + * + * frame_duration = (1 + repeat_pict) * time_base + * + * It is used by codecs like H.264 to display telecined material. + */ + int repeat_pict; /* XXX: Put it back in AVCodecContext. */ + int64_t pts; /* pts of the current frame */ + int64_t dts; /* dts of the current frame */ + + /* private data */ + int64_t last_pts; + int64_t last_dts; + int fetch_timestamp; + +#define AV_PARSER_PTS_NB 4 + int cur_frame_start_index; + int64_t cur_frame_offset[AV_PARSER_PTS_NB]; + int64_t cur_frame_pts[AV_PARSER_PTS_NB]; + int64_t cur_frame_dts[AV_PARSER_PTS_NB]; + + int flags; +#define PARSER_FLAG_COMPLETE_FRAMES 0x0001 +#define PARSER_FLAG_ONCE 0x0002 +/// Set if the parser has a valid file offset +#define PARSER_FLAG_FETCHED_OFFSET 0x0004 +#define PARSER_FLAG_USE_CODEC_TS 0x1000 + + int64_t offset; ///< byte offset from starting packet start + int64_t cur_frame_end[AV_PARSER_PTS_NB]; + + /** + * Set by parser to 1 for key frames and 0 for non-key frames. + * It is initialized to -1, so if the parser doesn't set this flag, + * old-style fallback using AV_PICTURE_TYPE_I picture type as key frames + * will be used. + */ + int key_frame; + + // Timestamp generation support: + /** + * Synchronization point for start of timestamp generation. + * + * Set to >0 for sync point, 0 for no sync point and <0 for undefined + * (default). + * + * For example, this corresponds to presence of H.264 buffering period + * SEI message. + */ + int dts_sync_point; + + /** + * Offset of the current timestamp against last timestamp sync point in + * units of AVCodecContext.time_base. + * + * Set to INT_MIN when dts_sync_point unused. Otherwise, it must + * contain a valid timestamp offset. + * + * Note that the timestamp of sync point has usually a nonzero + * dts_ref_dts_delta, which refers to the previous sync point. Offset of + * the next frame after timestamp sync point will be usually 1. + * + * For example, this corresponds to H.264 cpb_removal_delay. + */ + int dts_ref_dts_delta; + + /** + * Presentation delay of current frame in units of AVCodecContext.time_base. + * + * Set to INT_MIN when dts_sync_point unused. Otherwise, it must + * contain valid non-negative timestamp delta (presentation time of a frame + * must not lie in the past). + * + * This delay represents the difference between decoding and presentation + * time of the frame. + * + * For example, this corresponds to H.264 dpb_output_delay. + */ + int pts_dts_delta; + + /** + * Position of the packet in file. + * + * Analogous to cur_frame_pts/dts + */ + int64_t cur_frame_pos[AV_PARSER_PTS_NB]; + + /** + * Byte position of currently parsed frame in stream. + */ + int64_t pos; + + /** + * Previous frame byte position. + */ + int64_t last_pos; + + /** + * Duration of the current frame. + * For audio, this is in units of 1 / AVCodecContext.sample_rate. + * For all other types, this is in units of AVCodecContext.time_base. + */ + int duration; + + enum AVFieldOrder field_order; + + /** + * Indicate whether a picture is coded as a frame, top field or bottom field. + * + * For example, H.264 field_pic_flag equal to 0 corresponds to + * AV_PICTURE_STRUCTURE_FRAME. An H.264 picture with field_pic_flag + * equal to 1 and bottom_field_flag equal to 0 corresponds to + * AV_PICTURE_STRUCTURE_TOP_FIELD. + */ + enum AVPictureStructure picture_structure; + + /** + * Picture number incremented in presentation or output order. + * This field may be reinitialized at the first picture of a new sequence. + * + * For example, this corresponds to H.264 PicOrderCnt. + */ + int output_picture_number; + + /** + * Dimensions of the decoded video intended for presentation. + */ + int width; + int height; + + /** + * Dimensions of the coded video. + */ + int coded_width; + int coded_height; + + /** + * The format of the coded data, corresponds to enum AVPixelFormat for video + * and for enum AVSampleFormat for audio. + * + * Note that a decoder can have considerable freedom in how exactly it + * decodes the data, so the format reported here might be different from the + * one returned by a decoder. + */ + int format; +} AVCodecParserContext; + +typedef struct AVCodecParser { +#if FF_API_PARSER_CODECID + int codec_ids[7]; /* several codec IDs are permitted */ +#else + enum AVCodecID codec_ids[7]; /* several codec IDs are permitted */ +#endif +#if FF_API_PARSER_PRIVATE + /***************************************************************** + * All fields below this line are not part of the public API. They + * may not be used outside of libavcodec and can be changed and + * removed at will. + * New public fields should be added right above. + ***************************************************************** + */ + attribute_deprecated + int priv_data_size; + attribute_deprecated + int (*parser_init)(AVCodecParserContext *s); + /* This callback never returns an error, a negative value means that + * the frame start was in a previous packet. */ + attribute_deprecated + int (*parser_parse)(AVCodecParserContext *s, + AVCodecContext *avctx, + const uint8_t **poutbuf, int *poutbuf_size, + const uint8_t *buf, int buf_size); + attribute_deprecated + void (*parser_close)(AVCodecParserContext *s); + attribute_deprecated + int (*split)(AVCodecContext *avctx, const uint8_t *buf, int buf_size); +#endif +} AVCodecParser; + +/** + * Iterate over all registered codec parsers. + * + * @param opaque a pointer where libavcodec will store the iteration state. Must + * point to NULL to start the iteration. + * + * @return the next registered codec parser or NULL when the iteration is + * finished + */ +const AVCodecParser *av_parser_iterate(void **opaque); + +#if FF_API_PARSER_CODECID +AVCodecParserContext *av_parser_init(int codec_id); +#else +AVCodecParserContext *av_parser_init(enum AVCodecID codec_id); +#endif + +/** + * Parse a packet. + * + * @param s parser context. + * @param avctx codec context. + * @param poutbuf set to pointer to parsed buffer or NULL if not yet finished. + * @param poutbuf_size set to size of parsed buffer or zero if not yet finished. + * @param buf input buffer. + * @param buf_size buffer size in bytes without the padding. I.e. the full buffer + size is assumed to be buf_size + AV_INPUT_BUFFER_PADDING_SIZE. + To signal EOF, this should be 0 (so that the last frame + can be output). + * @param pts input presentation timestamp. + * @param dts input decoding timestamp. + * @param pos input byte position in stream. + * @return the number of bytes of the input bitstream used. + * + * Example: + * @code + * while(in_len){ + * len = av_parser_parse2(myparser, AVCodecContext, &data, &size, + * in_data, in_len, + * pts, dts, pos); + * in_data += len; + * in_len -= len; + * + * if(size) + * decode_frame(data, size); + * } + * @endcode + */ +int av_parser_parse2(AVCodecParserContext *s, + AVCodecContext *avctx, + uint8_t **poutbuf, int *poutbuf_size, + const uint8_t *buf, int buf_size, + int64_t pts, int64_t dts, + int64_t pos); + +void av_parser_close(AVCodecParserContext *s); + +/** + * @} + * @} + */ + +/** + * @addtogroup lavc_encoding + * @{ + */ + +int avcodec_encode_subtitle(AVCodecContext *avctx, uint8_t *buf, int buf_size, + const AVSubtitle *sub); + + +/** + * @} + */ + +/** + * @defgroup lavc_misc Utility functions + * @ingroup libavc + * + * Miscellaneous utility functions related to both encoding and decoding + * (or neither). + * @{ + */ + +/** + * @defgroup lavc_misc_pixfmt Pixel formats + * + * Functions for working with pixel formats. + * @{ + */ + +/** + * Return a value representing the fourCC code associated to the + * pixel format pix_fmt, or 0 if no associated fourCC code can be + * found. + */ +unsigned int avcodec_pix_fmt_to_codec_tag(enum AVPixelFormat pix_fmt); + +/** + * Find the best pixel format to convert to given a certain source pixel + * format. When converting from one pixel format to another, information loss + * may occur. For example, when converting from RGB24 to GRAY, the color + * information will be lost. Similarly, other losses occur when converting from + * some formats to other formats. avcodec_find_best_pix_fmt_of_2() searches which of + * the given pixel formats should be used to suffer the least amount of loss. + * The pixel formats from which it chooses one, are determined by the + * pix_fmt_list parameter. + * + * + * @param[in] pix_fmt_list AV_PIX_FMT_NONE terminated array of pixel formats to choose from + * @param[in] src_pix_fmt source pixel format + * @param[in] has_alpha Whether the source pixel format alpha channel is used. + * @param[out] loss_ptr Combination of flags informing you what kind of losses will occur. + * @return The best pixel format to convert to or -1 if none was found. + */ +enum AVPixelFormat avcodec_find_best_pix_fmt_of_list(const enum AVPixelFormat *pix_fmt_list, + enum AVPixelFormat src_pix_fmt, + int has_alpha, int *loss_ptr); + +enum AVPixelFormat avcodec_default_get_format(struct AVCodecContext *s, const enum AVPixelFormat * fmt); + +/** + * @} + */ + +void avcodec_string(char *buf, int buf_size, AVCodecContext *enc, int encode); + +int avcodec_default_execute(AVCodecContext *c, int (*func)(AVCodecContext *c2, void *arg2),void *arg, int *ret, int count, int size); +int avcodec_default_execute2(AVCodecContext *c, int (*func)(AVCodecContext *c2, void *arg2, int, int),void *arg, int *ret, int count); +//FIXME func typedef + +/** + * Fill AVFrame audio data and linesize pointers. + * + * The buffer buf must be a preallocated buffer with a size big enough + * to contain the specified samples amount. The filled AVFrame data + * pointers will point to this buffer. + * + * AVFrame extended_data channel pointers are allocated if necessary for + * planar audio. + * + * @param frame the AVFrame + * frame->nb_samples must be set prior to calling the + * function. This function fills in frame->data, + * frame->extended_data, frame->linesize[0]. + * @param nb_channels channel count + * @param sample_fmt sample format + * @param buf buffer to use for frame data + * @param buf_size size of buffer + * @param align plane size sample alignment (0 = default) + * @return >=0 on success, negative error code on failure + * @todo return the size in bytes required to store the samples in + * case of success, at the next libavutil bump + */ +int avcodec_fill_audio_frame(AVFrame *frame, int nb_channels, + enum AVSampleFormat sample_fmt, const uint8_t *buf, + int buf_size, int align); + +/** + * Reset the internal codec state / flush internal buffers. Should be called + * e.g. when seeking or when switching to a different stream. + * + * @note for decoders, this function just releases any references the decoder + * might keep internally, but the caller's references remain valid. + * + * @note for encoders, this function will only do something if the encoder + * declares support for AV_CODEC_CAP_ENCODER_FLUSH. When called, the encoder + * will drain any remaining packets, and can then be reused for a different + * stream (as opposed to sending a null frame which will leave the encoder + * in a permanent EOF state after draining). This can be desirable if the + * cost of tearing down and replacing the encoder instance is high. + */ +void avcodec_flush_buffers(AVCodecContext *avctx); + +/** + * Return audio frame duration. + * + * @param avctx codec context + * @param frame_bytes size of the frame, or 0 if unknown + * @return frame duration, in samples, if known. 0 if not able to + * determine. + */ +int av_get_audio_frame_duration(AVCodecContext *avctx, int frame_bytes); + +/* memory */ + +/** + * Same behaviour av_fast_malloc but the buffer has additional + * AV_INPUT_BUFFER_PADDING_SIZE at the end which will always be 0. + * + * In addition the whole buffer will initially and after resizes + * be 0-initialized so that no uninitialized data will ever appear. + */ +void av_fast_padded_malloc(void *ptr, unsigned int *size, size_t min_size); + +/** + * Same behaviour av_fast_padded_malloc except that buffer will always + * be 0-initialized after call. + */ +void av_fast_padded_mallocz(void *ptr, unsigned int *size, size_t min_size); + +/** + * @return a positive value if s is open (i.e. avcodec_open2() was called on it), + * 0 otherwise. + */ +int avcodec_is_open(AVCodecContext *s); + +/** + * @} + */ + +#endif /* AVCODEC_AVCODEC_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/avdct.h b/ffmpeg-n8.1/include/libavcodec/avdct.h new file mode 100644 index 00000000..6411fab6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/avdct.h @@ -0,0 +1,88 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_AVDCT_H +#define AVCODEC_AVDCT_H + +#include "libavutil/opt.h" + +/** + * AVDCT context. + * @note function pointers can be NULL if the specific features have been + * disabled at build time. + */ +typedef struct AVDCT { + const AVClass *av_class; + + void (*idct)(int16_t *block /* align 16 */); + + /** + * IDCT input permutation. + * Several optimized IDCTs need a permutated input (relative to the + * normal order of the reference IDCT). + * This permutation must be performed before the idct_put/add. + * Note, normally this can be merged with the zigzag/alternate scan
+ * An example to avoid confusion: + * - (->decode coeffs -> zigzag reorder -> dequant -> reference IDCT -> ...) + * - (x -> reference DCT -> reference IDCT -> x) + * - (x -> reference DCT -> simple_mmx_perm = idct_permutation + * -> simple_idct_mmx -> x) + * - (-> decode coeffs -> zigzag reorder -> simple_mmx_perm -> dequant + * -> simple_idct_mmx -> ...) + */ + uint8_t idct_permutation[64]; + + void (*fdct)(int16_t *block /* align 16 */); + + + /** + * DCT algorithm. + * must use AVOptions to set this field. + */ + int dct_algo; + + /** + * IDCT algorithm. + * must use AVOptions to set this field. + */ + int idct_algo; + + void (*get_pixels)(int16_t *block /* align 16 */, + const uint8_t *pixels /* align 8 */, + ptrdiff_t line_size); + + int bits_per_sample; + + void (*get_pixels_unaligned)(int16_t *block /* align 16 */, + const uint8_t *pixels, + ptrdiff_t line_size); +} AVDCT; + +/** + * Allocates a AVDCT context. + * This needs to be initialized with avcodec_dct_init() after optionally + * configuring it with AVOptions. + * + * To free it use av_free() + */ +AVDCT *avcodec_dct_alloc(void); +int avcodec_dct_init(AVDCT *); + +const AVClass *avcodec_dct_get_class(void); + +#endif /* AVCODEC_AVDCT_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/bsf.h b/ffmpeg-n8.1/include/libavcodec/bsf.h new file mode 100644 index 00000000..a09c69f2 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/bsf.h @@ -0,0 +1,332 @@ +/* + * Bitstream filters public API + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_BSF_H +#define AVCODEC_BSF_H + +#include "libavutil/dict.h" +#include "libavutil/log.h" +#include "libavutil/rational.h" + +#include "codec_id.h" +#include "codec_par.h" +#include "packet.h" + +/** + * @defgroup lavc_bsf Bitstream filters + * @ingroup libavc + * + * Bitstream filters transform encoded media data without decoding it. This + * allows e.g. manipulating various header values. Bitstream filters operate on + * @ref AVPacket "AVPackets". + * + * The bitstream filtering API is centered around two structures: + * AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter + * in abstract, the latter a specific filtering process. Obtain an + * AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass + * it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable + * AVBSFContext fields, as described in its documentation, then call + * av_bsf_init() to prepare the filter context for use. + * + * Submit packets for filtering using av_bsf_send_packet(), obtain filtered + * results with av_bsf_receive_packet(). When no more input packets will be + * sent, submit a NULL AVPacket to signal the end of the stream to the filter. + * av_bsf_receive_packet() will then return trailing packets, if any are + * produced by the filter. + * + * Finally, free the filter context with av_bsf_free(). + * @{ + */ + +/** + * The bitstream filter state. + * + * This struct must be allocated with av_bsf_alloc() and freed with + * av_bsf_free(). + * + * The fields in the struct will only be changed (by the caller or by the + * filter) as described in their documentation, and are to be considered + * immutable otherwise. + */ +typedef struct AVBSFContext { + /** + * A class for logging and AVOptions + */ + const AVClass *av_class; + + /** + * The bitstream filter this context is an instance of. + */ + const struct AVBitStreamFilter *filter; + + /** + * Opaque filter-specific private data. If filter->priv_class is non-NULL, + * this is an AVOptions-enabled struct. + */ + void *priv_data; + + /** + * Parameters of the input stream. This field is allocated in + * av_bsf_alloc(), it needs to be filled by the caller before + * av_bsf_init(). + */ + AVCodecParameters *par_in; + + /** + * Parameters of the output stream. This field is allocated in + * av_bsf_alloc(), it is set by the filter in av_bsf_init(). + */ + AVCodecParameters *par_out; + + /** + * The timebase used for the timestamps of the input packets. Set by the + * caller before av_bsf_init(). + */ + AVRational time_base_in; + + /** + * The timebase used for the timestamps of the output packets. Set by the + * filter in av_bsf_init(). + */ + AVRational time_base_out; +} AVBSFContext; + +typedef struct AVBitStreamFilter { + const char *name; + + /** + * A list of codec ids supported by the filter, terminated by + * AV_CODEC_ID_NONE. + * May be NULL, in that case the bitstream filter works with any codec id. + */ + const enum AVCodecID *codec_ids; + + /** + * A class for the private data, used to declare bitstream filter private + * AVOptions. This field is NULL for bitstream filters that do not declare + * any options. + * + * If this field is non-NULL, the first member of the filter private data + * must be a pointer to AVClass, which will be set by libavcodec generic + * code to this class. + */ + const AVClass *priv_class; +} AVBitStreamFilter; + +/** + * @return a bitstream filter with the specified name or NULL if no such + * bitstream filter exists. + */ +const AVBitStreamFilter *av_bsf_get_by_name(const char *name); + +/** + * Iterate over all registered bitstream filters. + * + * @param opaque a pointer where libavcodec will store the iteration state. Must + * point to NULL to start the iteration. + * + * @return the next registered bitstream filter or NULL when the iteration is + * finished + */ +const AVBitStreamFilter *av_bsf_iterate(void **opaque); + +/** + * Allocate a context for a given bitstream filter. The caller must fill in the + * context parameters as described in the documentation and then call + * av_bsf_init() before sending any data to the filter. + * + * @param filter the filter for which to allocate an instance. + * @param[out] ctx a pointer into which the pointer to the newly-allocated context + * will be written. It must be freed with av_bsf_free() after the + * filtering is done. + * + * @return 0 on success, a negative AVERROR code on failure + */ +int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx); + +/** + * Prepare the filter for use, after all the parameters and options have been + * set. + * + * @param ctx a AVBSFContext previously allocated with av_bsf_alloc() + */ +int av_bsf_init(AVBSFContext *ctx); + +/** + * Submit a packet for filtering. + * + * After sending each packet, the filter must be completely drained by calling + * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or + * AVERROR_EOF. + * + * @param ctx an initialized AVBSFContext + * @param pkt the packet to filter. The bitstream filter will take ownership of + * the packet and reset the contents of pkt. pkt is not touched if an error occurs. + * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero), + * it signals the end of the stream (i.e. no more non-empty packets will be sent; + * sending more empty packets does nothing) and will cause the filter to output + * any packets it may have buffered internally. + * + * @return + * - 0 on success. + * - AVERROR(EAGAIN) if packets need to be retrieved from the filter (using + * av_bsf_receive_packet()) before new input can be consumed. + * - Another negative AVERROR value if an error occurs. + */ +int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt); + +/** + * Retrieve a filtered packet. + * + * @param ctx an initialized AVBSFContext + * @param[out] pkt this struct will be filled with the contents of the filtered + * packet. It is owned by the caller and must be freed using + * av_packet_unref() when it is no longer needed. + * This parameter should be "clean" (i.e. freshly allocated + * with av_packet_alloc() or unreffed with av_packet_unref()) + * when this function is called. If this function returns + * successfully, the contents of pkt will be completely + * overwritten by the returned data. On failure, pkt is not + * touched. + * + * @return + * - 0 on success. + * - AVERROR(EAGAIN) if more packets need to be sent to the filter (using + * av_bsf_send_packet()) to get more output. + * - AVERROR_EOF if there will be no further output from the filter. + * - Another negative AVERROR value if an error occurs. + * + * @note one input packet may result in several output packets, so after sending + * a packet with av_bsf_send_packet(), this function needs to be called + * repeatedly until it stops returning 0. It is also possible for a filter to + * output fewer packets than were sent to it, so this function may return + * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call. + */ +int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt); + +/** + * Reset the internal bitstream filter state. Should be called e.g. when seeking. + */ +void av_bsf_flush(AVBSFContext *ctx); + +/** + * Free a bitstream filter context and everything associated with it; write NULL + * into the supplied pointer. + */ +void av_bsf_free(AVBSFContext **ctx); + +/** + * Get the AVClass for AVBSFContext. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *av_bsf_get_class(void); + +/** + * Structure for chain/list of bitstream filters. + * Empty list can be allocated by av_bsf_list_alloc(). + */ +typedef struct AVBSFList AVBSFList; + +/** + * Allocate empty list of bitstream filters. + * The list must be later freed by av_bsf_list_free() + * or finalized by av_bsf_list_finalize(). + * + * @return Pointer to @ref AVBSFList on success, NULL in case of failure + */ +AVBSFList *av_bsf_list_alloc(void); + +/** + * Free list of bitstream filters. + * + * @param lst Pointer to pointer returned by av_bsf_list_alloc() + */ +void av_bsf_list_free(AVBSFList **lst); + +/** + * Append bitstream filter to the list of bitstream filters. + * + * @param lst List to append to + * @param bsf Filter context to be appended + * + * @return >=0 on success, negative AVERROR in case of failure + */ +int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf); + +/** + * Construct new bitstream filter context given it's name and options + * and append it to the list of bitstream filters. + * + * @param lst List to append to + * @param bsf_name Name of the bitstream filter + * @param options Options for the bitstream filter, can be set to NULL + * + * @return >=0 on success, negative AVERROR in case of failure + */ +int av_bsf_list_append2(AVBSFList *lst, const char * bsf_name, AVDictionary **options); +/** + * Finalize list of bitstream filters. + * + * This function will transform @ref AVBSFList to single @ref AVBSFContext, + * so the whole chain of bitstream filters can be treated as single filter + * freshly allocated by av_bsf_alloc(). + * If the call is successful, @ref AVBSFList structure is freed and lst + * will be set to NULL. In case of failure, caller is responsible for + * freeing the structure by av_bsf_list_free() + * + * @param lst Filter list structure to be transformed + * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure + * representing the chain of bitstream filters + * + * @return >=0 on success, negative AVERROR in case of failure + */ +int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf); + +/** + * Parse string describing list of bitstream filters and create single + * @ref AVBSFContext describing the whole chain of bitstream filters. + * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly + * allocated by av_bsf_alloc(). + * + * @param str String describing chain of bitstream filters in format + * `bsf1[=opt1=val1:opt2=val2][,bsf2]` + * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure + * representing the chain of bitstream filters + * + * @return >=0 on success, negative AVERROR in case of failure + */ +int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf); + +/** + * Get null/pass-through bitstream filter. + * + * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter + * + * @return + */ +int av_bsf_get_null_filter(AVBSFContext **bsf); + +/** + * @} + */ + +#endif // AVCODEC_BSF_H diff --git a/ffmpeg-n8.1/include/libavcodec/codec.h b/ffmpeg-n8.1/include/libavcodec/codec.h new file mode 100644 index 00000000..f509e5d9 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/codec.h @@ -0,0 +1,367 @@ +/* + * AVCodec public API + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_CODEC_H +#define AVCODEC_CODEC_H + +#include + +#include "libavutil/avutil.h" +#include "libavutil/hwcontext.h" +#include "libavutil/log.h" +#include "libavutil/pixfmt.h" +#include "libavutil/rational.h" +#include "libavutil/samplefmt.h" + +#include "libavcodec/codec_id.h" +#include "libavcodec/version_major.h" + +/** + * @addtogroup lavc_core + * @{ + */ + +/** + * Decoder can use draw_horiz_band callback. + */ +#define AV_CODEC_CAP_DRAW_HORIZ_BAND (1 << 0) +/** + * Codec uses get_buffer() or get_encode_buffer() for allocating buffers and + * supports custom allocators. + * If not set, it might not use get_buffer() or get_encode_buffer() at all, or + * use operations that assume the buffer was allocated by + * avcodec_default_get_buffer2 or avcodec_default_get_encode_buffer. + */ +#define AV_CODEC_CAP_DR1 (1 << 1) +/** + * Encoder or decoder requires flushing with NULL input at the end in order to + * give the complete and correct output. + * + * NOTE: If this flag is not set, the codec is guaranteed to never be fed with + * with NULL data. The user can still send NULL data to the public encode + * or decode function, but libavcodec will not pass it along to the codec + * unless this flag is set. + * + * Decoders: + * The decoder has a non-zero delay and needs to be fed with avpkt->data=NULL, + * avpkt->size=0 at the end to get the delayed data until the decoder no longer + * returns frames. + * + * Encoders: + * The encoder needs to be fed with NULL data at the end of encoding until the + * encoder no longer returns data. + * + * NOTE: For encoders implementing the AVCodec.encode2() function, setting this + * flag also means that the encoder must set the pts and duration for + * each output packet. If this flag is not set, the pts and duration will + * be determined by libavcodec from the input frame. + */ +#define AV_CODEC_CAP_DELAY (1 << 5) +/** + * Codec can be fed a final frame with a smaller size. + * This can be used to prevent truncation of the last audio samples. + */ +#define AV_CODEC_CAP_SMALL_LAST_FRAME (1 << 6) + +/** + * Codec is experimental and is thus avoided in favor of non experimental + * encoders + */ +#define AV_CODEC_CAP_EXPERIMENTAL (1 << 9) +/** + * Codec should fill in channel configuration and samplerate instead of container + */ +#define AV_CODEC_CAP_CHANNEL_CONF (1 << 10) +/** + * Codec supports frame-level multithreading. + */ +#define AV_CODEC_CAP_FRAME_THREADS (1 << 12) +/** + * Codec supports slice-based (or partition-based) multithreading. + */ +#define AV_CODEC_CAP_SLICE_THREADS (1 << 13) +/** + * Codec supports changed parameters at any point. + */ +#define AV_CODEC_CAP_PARAM_CHANGE (1 << 14) +/** + * Codec supports multithreading through a method other than slice- or + * frame-level multithreading. Typically this marks wrappers around + * multithreading-capable external libraries. + */ +#define AV_CODEC_CAP_OTHER_THREADS (1 << 15) +/** + * Audio encoder supports receiving a different number of samples in each call. + */ +#define AV_CODEC_CAP_VARIABLE_FRAME_SIZE (1 << 16) +/** + * Decoder is not a preferred choice for probing. + * This indicates that the decoder is not a good choice for probing. + * It could for example be an expensive to spin up hardware decoder, + * or it could simply not provide a lot of useful information about + * the stream. + * A decoder marked with this flag should only be used as last resort + * choice for probing. + */ +#define AV_CODEC_CAP_AVOID_PROBING (1 << 17) + +/** + * Codec is backed by a hardware implementation. Typically used to + * identify a non-hwaccel hardware decoder. For information about hwaccels, use + * avcodec_get_hw_config() instead. + */ +#define AV_CODEC_CAP_HARDWARE (1 << 18) + +/** + * Codec is potentially backed by a hardware implementation, but not + * necessarily. This is used instead of AV_CODEC_CAP_HARDWARE, if the + * implementation provides some sort of internal fallback. + */ +#define AV_CODEC_CAP_HYBRID (1 << 19) + +/** + * This encoder can reorder user opaque values from input AVFrames and return + * them with corresponding output packets. + * @see AV_CODEC_FLAG_COPY_OPAQUE + */ +#define AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE (1 << 20) + +/** + * This encoder can be flushed using avcodec_flush_buffers(). If this flag is + * not set, the encoder must be closed and reopened to ensure that no frames + * remain pending. + */ +#define AV_CODEC_CAP_ENCODER_FLUSH (1 << 21) + +/** + * The encoder is able to output reconstructed frame data, i.e. raw frames that + * would be produced by decoding the encoded bitstream. + * + * Reconstructed frame output is enabled by the AV_CODEC_FLAG_RECON_FRAME flag. + */ +#define AV_CODEC_CAP_ENCODER_RECON_FRAME (1 << 22) + +/** + * AVProfile. + */ +typedef struct AVProfile { + int profile; + const char *name; ///< short name for the profile +} AVProfile; + +/** + * AVCodec. + */ +typedef struct AVCodec { + /** + * Name of the codec implementation. + * The name is globally unique among encoders and among decoders (but an + * encoder and a decoder can share the same name). + * This is the primary way to find a codec from the user perspective. + */ + const char *name; + /** + * Descriptive name for the codec, meant to be more human readable than name. + * You should use the NULL_IF_CONFIG_SMALL() macro to define it. + */ + const char *long_name; + enum AVMediaType type; + enum AVCodecID id; + /** + * Codec capabilities. + * see AV_CODEC_CAP_* + */ + int capabilities; + uint8_t max_lowres; ///< maximum value for lowres supported by the decoder + + /** + * Deprecated codec capabilities. + */ + attribute_deprecated + const AVRational *supported_framerates; ///< @deprecated use avcodec_get_supported_config() + attribute_deprecated + const enum AVPixelFormat *pix_fmts; ///< @deprecated use avcodec_get_supported_config() + attribute_deprecated + const int *supported_samplerates; ///< @deprecated use avcodec_get_supported_config() + attribute_deprecated + const enum AVSampleFormat *sample_fmts; ///< @deprecated use avcodec_get_supported_config() + + const AVClass *priv_class; ///< AVClass for the private context + const AVProfile *profiles; ///< array of recognized profiles, or NULL if unknown, array is terminated by {AV_PROFILE_UNKNOWN} + + /** + * Group name of the codec implementation. + * This is a short symbolic name of the wrapper backing this codec. A + * wrapper uses some kind of external implementation for the codec, such + * as an external library, or a codec implementation provided by the OS or + * the hardware. + * If this field is NULL, this is a builtin, libavcodec native codec. + * If non-NULL, this will be the suffix in AVCodec.name in most cases + * (usually AVCodec.name will be of the form "_"). + */ + const char *wrapper_name; + + /** + * Array of supported channel layouts, terminated with a zeroed layout. + * @deprecated use avcodec_get_supported_config() + */ + attribute_deprecated + const AVChannelLayout *ch_layouts; +} AVCodec; + +/** + * Iterate over all registered codecs. + * + * @param opaque a pointer where libavcodec will store the iteration state. Must + * point to NULL to start the iteration. + * + * @return the next registered codec or NULL when the iteration is + * finished + */ +const AVCodec *av_codec_iterate(void **opaque); + +/** + * Find a registered decoder with a matching codec ID. + * + * @param id AVCodecID of the requested decoder + * @return A decoder if one was found, NULL otherwise. + */ +const AVCodec *avcodec_find_decoder(enum AVCodecID id); + +/** + * Find a registered decoder with the specified name. + * + * @param name name of the requested decoder + * @return A decoder if one was found, NULL otherwise. + */ +const AVCodec *avcodec_find_decoder_by_name(const char *name); + +/** + * Find a registered encoder with a matching codec ID. + * + * @param id AVCodecID of the requested encoder + * @return An encoder if one was found, NULL otherwise. + */ +const AVCodec *avcodec_find_encoder(enum AVCodecID id); + +/** + * Find a registered encoder with the specified name. + * + * @param name name of the requested encoder + * @return An encoder if one was found, NULL otherwise. + */ +const AVCodec *avcodec_find_encoder_by_name(const char *name); +/** + * @return a non-zero number if codec is an encoder, zero otherwise + */ +int av_codec_is_encoder(const AVCodec *codec); + +/** + * @return a non-zero number if codec is a decoder, zero otherwise + */ +int av_codec_is_decoder(const AVCodec *codec); + +/** + * Return a name for the specified profile, if available. + * + * @param codec the codec that is searched for the given profile + * @param profile the profile value for which a name is requested + * @return A name for the profile if found, NULL otherwise. + */ +const char *av_get_profile_name(const AVCodec *codec, int profile); + +enum { + /** + * The codec supports this format via the hw_device_ctx interface. + * + * When selecting this format, AVCodecContext.hw_device_ctx should + * have been set to a device of the specified type before calling + * avcodec_open2(). + */ + AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX = 0x01, + /** + * The codec supports this format via the hw_frames_ctx interface. + * + * When selecting this format for a decoder, + * AVCodecContext.hw_frames_ctx should be set to a suitable frames + * context inside the get_format() callback. The frames context + * must have been created on a device of the specified type. + * + * When selecting this format for an encoder, + * AVCodecContext.hw_frames_ctx should be set to the context which + * will be used for the input frames before calling avcodec_open2(). + */ + AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX = 0x02, + /** + * The codec supports this format by some internal method. + * + * This format can be selected without any additional configuration - + * no device or frames context is required. + */ + AV_CODEC_HW_CONFIG_METHOD_INTERNAL = 0x04, + /** + * The codec supports this format by some ad-hoc method. + * + * Additional settings and/or function calls are required. See the + * codec-specific documentation for details. (Methods requiring + * this sort of configuration are deprecated and others should be + * used in preference.) + */ + AV_CODEC_HW_CONFIG_METHOD_AD_HOC = 0x08, +}; + +typedef struct AVCodecHWConfig { + /** + * For decoders, a hardware pixel format which that decoder may be + * able to decode to if suitable hardware is available. + * + * For encoders, a pixel format which the encoder may be able to + * accept. If set to AV_PIX_FMT_NONE, this applies to all pixel + * formats supported by the codec. + */ + enum AVPixelFormat pix_fmt; + /** + * Bit set of AV_CODEC_HW_CONFIG_METHOD_* flags, describing the possible + * setup methods which can be used with this configuration. + */ + int methods; + /** + * The device type associated with the configuration. + * + * Must be set for AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX and + * AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, otherwise unused. + */ + enum AVHWDeviceType device_type; +} AVCodecHWConfig; + +/** + * Retrieve supported hardware configurations for a codec. + * + * Values of index from zero to some maximum return the indexed configuration + * descriptor; all other values return NULL. If the codec does not support + * any hardware configurations then it will always return NULL. + */ +const AVCodecHWConfig *avcodec_get_hw_config(const AVCodec *codec, int index); + +/** + * @} + */ + +#endif /* AVCODEC_CODEC_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/codec_desc.h b/ffmpeg-n8.1/include/libavcodec/codec_desc.h new file mode 100644 index 00000000..1186433c --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/codec_desc.h @@ -0,0 +1,142 @@ +/* + * Codec descriptors public API + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_CODEC_DESC_H +#define AVCODEC_CODEC_DESC_H + +#include "libavutil/avutil.h" + +#include "codec_id.h" + +/** + * @addtogroup lavc_core + * @{ + */ + +/** + * This struct describes the properties of a single codec described by an + * AVCodecID. + * @see avcodec_descriptor_get() + */ +typedef struct AVCodecDescriptor { + enum AVCodecID id; + enum AVMediaType type; + /** + * Name of the codec described by this descriptor. It is non-empty and + * unique for each codec descriptor. It should contain alphanumeric + * characters and '_' only. + */ + const char *name; + /** + * A more descriptive name for this codec. May be NULL. + */ + const char *long_name; + /** + * Codec properties, a combination of AV_CODEC_PROP_* flags. + */ + int props; + /** + * MIME type(s) associated with the codec. + * May be NULL; if not, a NULL-terminated array of MIME types. + * The first item is always non-NULL and is the preferred MIME type. + */ + const char *const *mime_types; + /** + * If non-NULL, an array of profiles recognized for this codec. + * Terminated with AV_PROFILE_UNKNOWN. + */ + const struct AVProfile *profiles; +} AVCodecDescriptor; + +/** + * Codec uses only intra compression. + * Video and audio codecs only. + */ +#define AV_CODEC_PROP_INTRA_ONLY (1 << 0) +/** + * Codec supports lossy compression. Audio and video codecs only. + * @note a codec may support both lossy and lossless + * compression modes + */ +#define AV_CODEC_PROP_LOSSY (1 << 1) +/** + * Codec supports lossless compression. Audio and video codecs only. + */ +#define AV_CODEC_PROP_LOSSLESS (1 << 2) +/** + * Codec supports frame reordering. That is, the coded order (the order in which + * the encoded packets are output by the encoders / stored / input to the + * decoders) may be different from the presentation order of the corresponding + * frames. + * + * For codecs that do not have this property set, PTS and DTS should always be + * equal. + */ +#define AV_CODEC_PROP_REORDER (1 << 3) + +/** + * Video codec supports separate coding of fields in interlaced frames. + */ +#define AV_CODEC_PROP_FIELDS (1 << 4) + +/** + * Video codec contains enhancement information meant to be applied to other + * existing frames, and can't generate usable image data on its own. + * A standalone decoder is unlikely to be available for it and should not + * be expected. + */ +#define AV_CODEC_PROP_ENHANCEMENT (1 << 5) + +/** + * Subtitle codec is bitmap based + * Decoded AVSubtitle data can be read from the AVSubtitleRect->pict field. + */ +#define AV_CODEC_PROP_BITMAP_SUB (1 << 16) +/** + * Subtitle codec is text based. + * Decoded AVSubtitle data can be read from the AVSubtitleRect->ass field. + */ +#define AV_CODEC_PROP_TEXT_SUB (1 << 17) + +/** + * @return descriptor for given codec ID or NULL if no descriptor exists. + */ +const AVCodecDescriptor *avcodec_descriptor_get(enum AVCodecID id); + +/** + * Iterate over all codec descriptors known to libavcodec. + * + * @param prev previous descriptor. NULL to get the first descriptor. + * + * @return next descriptor or NULL after the last descriptor + */ +const AVCodecDescriptor *avcodec_descriptor_next(const AVCodecDescriptor *prev); + +/** + * @return codec descriptor with the given name or NULL if no such descriptor + * exists. + */ +const AVCodecDescriptor *avcodec_descriptor_get_by_name(const char *name); + +/** + * @} + */ + +#endif // AVCODEC_CODEC_DESC_H diff --git a/ffmpeg-n8.1/include/libavcodec/codec_id.h b/ffmpeg-n8.1/include/libavcodec/codec_id.h new file mode 100644 index 00000000..6529f0a6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/codec_id.h @@ -0,0 +1,693 @@ +/* + * Codec IDs + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_CODEC_ID_H +#define AVCODEC_CODEC_ID_H + +#include "libavutil/avutil.h" +#include "libavutil/samplefmt.h" + +#include "version_major.h" + +/** + * @addtogroup lavc_core + * @{ + */ + +/** + * Identify the syntax and semantics of the bitstream. + * The principle is roughly: + * Two decoders with the same ID can decode the same streams. + * Two encoders with the same ID can encode compatible streams. + * There may be slight deviations from the principle due to implementation + * details. + * + * If you add a codec ID to this list, add it so that + * 1. no value of an existing codec ID changes (that would break ABI), + * 2. it is as close as possible to similar codecs + * + * After adding new codec IDs, do not forget to add an entry to the codec + * descriptor list and bump libavcodec minor version. + */ +enum AVCodecID { + AV_CODEC_ID_NONE, + + /* video codecs */ + AV_CODEC_ID_MPEG1VIDEO, + AV_CODEC_ID_MPEG2VIDEO, ///< preferred ID for MPEG-1/2 video decoding + AV_CODEC_ID_H261, + AV_CODEC_ID_H263, + AV_CODEC_ID_RV10, + AV_CODEC_ID_RV20, + AV_CODEC_ID_MJPEG, + AV_CODEC_ID_MJPEGB, + AV_CODEC_ID_LJPEG, + AV_CODEC_ID_SP5X, + AV_CODEC_ID_JPEGLS, + AV_CODEC_ID_MPEG4, + AV_CODEC_ID_RAWVIDEO, + AV_CODEC_ID_MSMPEG4V1, + AV_CODEC_ID_MSMPEG4V2, + AV_CODEC_ID_MSMPEG4V3, + AV_CODEC_ID_WMV1, + AV_CODEC_ID_WMV2, + AV_CODEC_ID_H263P, + AV_CODEC_ID_H263I, + AV_CODEC_ID_FLV1, + AV_CODEC_ID_SVQ1, + AV_CODEC_ID_SVQ3, + AV_CODEC_ID_DVVIDEO, + AV_CODEC_ID_HUFFYUV, + AV_CODEC_ID_CYUV, + AV_CODEC_ID_H264, + AV_CODEC_ID_INDEO3, + AV_CODEC_ID_VP3, + AV_CODEC_ID_THEORA, + AV_CODEC_ID_ASV1, + AV_CODEC_ID_ASV2, + AV_CODEC_ID_FFV1, + AV_CODEC_ID_4XM, + AV_CODEC_ID_VCR1, + AV_CODEC_ID_CLJR, + AV_CODEC_ID_MDEC, + AV_CODEC_ID_ROQ, + AV_CODEC_ID_INTERPLAY_VIDEO, + AV_CODEC_ID_XAN_WC3, + AV_CODEC_ID_XAN_WC4, + AV_CODEC_ID_RPZA, + AV_CODEC_ID_CINEPAK, + AV_CODEC_ID_WS_VQA, + AV_CODEC_ID_MSRLE, + AV_CODEC_ID_MSVIDEO1, + AV_CODEC_ID_IDCIN, + AV_CODEC_ID_8BPS, + AV_CODEC_ID_SMC, + AV_CODEC_ID_FLIC, + AV_CODEC_ID_TRUEMOTION1, + AV_CODEC_ID_VMDVIDEO, + AV_CODEC_ID_MSZH, + AV_CODEC_ID_ZLIB, + AV_CODEC_ID_QTRLE, + AV_CODEC_ID_TSCC, + AV_CODEC_ID_ULTI, + AV_CODEC_ID_QDRAW, + AV_CODEC_ID_VIXL, + AV_CODEC_ID_QPEG, + AV_CODEC_ID_PNG, + AV_CODEC_ID_PPM, + AV_CODEC_ID_PBM, + AV_CODEC_ID_PGM, + AV_CODEC_ID_PGMYUV, + AV_CODEC_ID_PAM, + AV_CODEC_ID_FFVHUFF, + AV_CODEC_ID_RV30, + AV_CODEC_ID_RV40, + AV_CODEC_ID_VC1, + AV_CODEC_ID_WMV3, + AV_CODEC_ID_LOCO, + AV_CODEC_ID_WNV1, + AV_CODEC_ID_AASC, + AV_CODEC_ID_INDEO2, + AV_CODEC_ID_FRAPS, + AV_CODEC_ID_TRUEMOTION2, + AV_CODEC_ID_BMP, + AV_CODEC_ID_CSCD, + AV_CODEC_ID_MMVIDEO, + AV_CODEC_ID_ZMBV, + AV_CODEC_ID_AVS, + AV_CODEC_ID_SMACKVIDEO, + AV_CODEC_ID_NUV, + AV_CODEC_ID_KMVC, + AV_CODEC_ID_FLASHSV, + AV_CODEC_ID_CAVS, + AV_CODEC_ID_JPEG2000, + AV_CODEC_ID_VMNC, + AV_CODEC_ID_VP5, + AV_CODEC_ID_VP6, + AV_CODEC_ID_VP6F, + AV_CODEC_ID_TARGA, + AV_CODEC_ID_DSICINVIDEO, + AV_CODEC_ID_TIERTEXSEQVIDEO, + AV_CODEC_ID_TIFF, + AV_CODEC_ID_GIF, + AV_CODEC_ID_DXA, + AV_CODEC_ID_DNXHD, + AV_CODEC_ID_THP, + AV_CODEC_ID_SGI, + AV_CODEC_ID_C93, + AV_CODEC_ID_BETHSOFTVID, + AV_CODEC_ID_PTX, + AV_CODEC_ID_TXD, + AV_CODEC_ID_VP6A, + AV_CODEC_ID_AMV, + AV_CODEC_ID_VB, + AV_CODEC_ID_PCX, + AV_CODEC_ID_SUNRAST, + AV_CODEC_ID_INDEO4, + AV_CODEC_ID_INDEO5, + AV_CODEC_ID_MIMIC, + AV_CODEC_ID_RL2, + AV_CODEC_ID_ESCAPE124, + AV_CODEC_ID_DIRAC, + AV_CODEC_ID_BFI, + AV_CODEC_ID_CMV, + AV_CODEC_ID_MOTIONPIXELS, + AV_CODEC_ID_TGV, + AV_CODEC_ID_TGQ, + AV_CODEC_ID_TQI, + AV_CODEC_ID_AURA, + AV_CODEC_ID_AURA2, + AV_CODEC_ID_V210X, + AV_CODEC_ID_TMV, + AV_CODEC_ID_V210, + AV_CODEC_ID_DPX, + AV_CODEC_ID_MAD, + AV_CODEC_ID_FRWU, + AV_CODEC_ID_FLASHSV2, + AV_CODEC_ID_CDGRAPHICS, + AV_CODEC_ID_R210, + AV_CODEC_ID_ANM, + AV_CODEC_ID_BINKVIDEO, + AV_CODEC_ID_IFF_ILBM, +#define AV_CODEC_ID_IFF_BYTERUN1 AV_CODEC_ID_IFF_ILBM + AV_CODEC_ID_KGV1, + AV_CODEC_ID_YOP, + AV_CODEC_ID_VP8, + AV_CODEC_ID_PICTOR, + AV_CODEC_ID_ANSI, + AV_CODEC_ID_A64_MULTI, + AV_CODEC_ID_A64_MULTI5, + AV_CODEC_ID_R10K, + AV_CODEC_ID_MXPEG, + AV_CODEC_ID_LAGARITH, + AV_CODEC_ID_PRORES, + AV_CODEC_ID_JV, + AV_CODEC_ID_DFA, + AV_CODEC_ID_WMV3IMAGE, + AV_CODEC_ID_VC1IMAGE, + AV_CODEC_ID_UTVIDEO, + AV_CODEC_ID_BMV_VIDEO, + AV_CODEC_ID_VBLE, + AV_CODEC_ID_DXTORY, +#if FF_API_V408_CODECID + AV_CODEC_ID_V410, +#endif + AV_CODEC_ID_XWD, + AV_CODEC_ID_CDXL, + AV_CODEC_ID_XBM, + AV_CODEC_ID_ZEROCODEC, + AV_CODEC_ID_MSS1, + AV_CODEC_ID_MSA1, + AV_CODEC_ID_TSCC2, + AV_CODEC_ID_MTS2, + AV_CODEC_ID_CLLC, + AV_CODEC_ID_MSS2, + AV_CODEC_ID_VP9, + AV_CODEC_ID_AIC, + AV_CODEC_ID_ESCAPE130, + AV_CODEC_ID_G2M, + AV_CODEC_ID_WEBP, + AV_CODEC_ID_HNM4_VIDEO, + AV_CODEC_ID_HEVC, +#define AV_CODEC_ID_H265 AV_CODEC_ID_HEVC + AV_CODEC_ID_FIC, + AV_CODEC_ID_ALIAS_PIX, + AV_CODEC_ID_BRENDER_PIX, + AV_CODEC_ID_PAF_VIDEO, + AV_CODEC_ID_EXR, + AV_CODEC_ID_VP7, + AV_CODEC_ID_SANM, + AV_CODEC_ID_SGIRLE, + AV_CODEC_ID_MVC1, + AV_CODEC_ID_MVC2, + AV_CODEC_ID_HQX, + AV_CODEC_ID_TDSC, + AV_CODEC_ID_HQ_HQA, + AV_CODEC_ID_HAP, + AV_CODEC_ID_DDS, + AV_CODEC_ID_DXV, + AV_CODEC_ID_SCREENPRESSO, + AV_CODEC_ID_RSCC, + AV_CODEC_ID_AVS2, + AV_CODEC_ID_PGX, + AV_CODEC_ID_AVS3, + AV_CODEC_ID_MSP2, + AV_CODEC_ID_VVC, +#define AV_CODEC_ID_H266 AV_CODEC_ID_VVC + AV_CODEC_ID_Y41P, + AV_CODEC_ID_AVRP, + AV_CODEC_ID_012V, + AV_CODEC_ID_AVUI, + AV_CODEC_ID_TARGA_Y216, +#if FF_API_V408_CODECID + AV_CODEC_ID_V308, + AV_CODEC_ID_V408, +#endif + AV_CODEC_ID_YUV4, + AV_CODEC_ID_AVRN, + AV_CODEC_ID_CPIA, + AV_CODEC_ID_XFACE, + AV_CODEC_ID_SNOW, + AV_CODEC_ID_SMVJPEG, + AV_CODEC_ID_APNG, + AV_CODEC_ID_DAALA, + AV_CODEC_ID_CFHD, + AV_CODEC_ID_TRUEMOTION2RT, + AV_CODEC_ID_M101, + AV_CODEC_ID_MAGICYUV, + AV_CODEC_ID_SHEERVIDEO, + AV_CODEC_ID_YLC, + AV_CODEC_ID_PSD, + AV_CODEC_ID_PIXLET, + AV_CODEC_ID_SPEEDHQ, + AV_CODEC_ID_FMVC, + AV_CODEC_ID_SCPR, + AV_CODEC_ID_CLEARVIDEO, + AV_CODEC_ID_XPM, + AV_CODEC_ID_AV1, + AV_CODEC_ID_BITPACKED, + AV_CODEC_ID_MSCC, + AV_CODEC_ID_SRGC, + AV_CODEC_ID_SVG, + AV_CODEC_ID_GDV, + AV_CODEC_ID_FITS, + AV_CODEC_ID_IMM4, + AV_CODEC_ID_PROSUMER, + AV_CODEC_ID_MWSC, + AV_CODEC_ID_WCMV, + AV_CODEC_ID_RASC, + AV_CODEC_ID_HYMT, + AV_CODEC_ID_ARBC, + AV_CODEC_ID_AGM, + AV_CODEC_ID_LSCR, + AV_CODEC_ID_VP4, + AV_CODEC_ID_IMM5, + AV_CODEC_ID_MVDV, + AV_CODEC_ID_MVHA, + AV_CODEC_ID_CDTOONS, + AV_CODEC_ID_MV30, + AV_CODEC_ID_NOTCHLC, + AV_CODEC_ID_PFM, + AV_CODEC_ID_MOBICLIP, + AV_CODEC_ID_PHOTOCD, + AV_CODEC_ID_IPU, + AV_CODEC_ID_ARGO, + AV_CODEC_ID_CRI, + AV_CODEC_ID_SIMBIOSIS_IMX, + AV_CODEC_ID_SGA_VIDEO, + AV_CODEC_ID_GEM, + AV_CODEC_ID_VBN, + AV_CODEC_ID_JPEGXL, + AV_CODEC_ID_QOI, + AV_CODEC_ID_PHM, + AV_CODEC_ID_RADIANCE_HDR, + AV_CODEC_ID_WBMP, + AV_CODEC_ID_MEDIA100, + AV_CODEC_ID_VQC, + AV_CODEC_ID_PDV, + AV_CODEC_ID_EVC, + AV_CODEC_ID_RTV1, + AV_CODEC_ID_VMIX, + AV_CODEC_ID_LEAD, + AV_CODEC_ID_DNXUC, + AV_CODEC_ID_RV60, + AV_CODEC_ID_JPEGXL_ANIM, + AV_CODEC_ID_APV, + AV_CODEC_ID_PRORES_RAW, + AV_CODEC_ID_JPEGXS, + + /* various PCM "codecs" */ + AV_CODEC_ID_FIRST_AUDIO = 0x10000, ///< A dummy id pointing at the start of audio codecs + AV_CODEC_ID_PCM_S16LE = 0x10000, + AV_CODEC_ID_PCM_S16BE, + AV_CODEC_ID_PCM_U16LE, + AV_CODEC_ID_PCM_U16BE, + AV_CODEC_ID_PCM_S8, + AV_CODEC_ID_PCM_U8, + AV_CODEC_ID_PCM_MULAW, + AV_CODEC_ID_PCM_ALAW, + AV_CODEC_ID_PCM_S32LE, + AV_CODEC_ID_PCM_S32BE, + AV_CODEC_ID_PCM_U32LE, + AV_CODEC_ID_PCM_U32BE, + AV_CODEC_ID_PCM_S24LE, + AV_CODEC_ID_PCM_S24BE, + AV_CODEC_ID_PCM_U24LE, + AV_CODEC_ID_PCM_U24BE, + AV_CODEC_ID_PCM_S24DAUD, + AV_CODEC_ID_PCM_ZORK, + AV_CODEC_ID_PCM_S16LE_PLANAR, + AV_CODEC_ID_PCM_DVD, + AV_CODEC_ID_PCM_F32BE, + AV_CODEC_ID_PCM_F32LE, + AV_CODEC_ID_PCM_F64BE, + AV_CODEC_ID_PCM_F64LE, + AV_CODEC_ID_PCM_BLURAY, + AV_CODEC_ID_PCM_LXF, + AV_CODEC_ID_S302M, + AV_CODEC_ID_PCM_S8_PLANAR, + AV_CODEC_ID_PCM_S24LE_PLANAR, + AV_CODEC_ID_PCM_S32LE_PLANAR, + AV_CODEC_ID_PCM_S16BE_PLANAR, + AV_CODEC_ID_PCM_S64LE, + AV_CODEC_ID_PCM_S64BE, + AV_CODEC_ID_PCM_F16LE, + AV_CODEC_ID_PCM_F24LE, + AV_CODEC_ID_PCM_VIDC, + AV_CODEC_ID_PCM_SGA, + + /* various ADPCM codecs */ + AV_CODEC_ID_ADPCM_IMA_QT = 0x11000, + AV_CODEC_ID_ADPCM_IMA_WAV, + AV_CODEC_ID_ADPCM_IMA_DK3, + AV_CODEC_ID_ADPCM_IMA_DK4, + AV_CODEC_ID_ADPCM_IMA_WS, + AV_CODEC_ID_ADPCM_IMA_SMJPEG, + AV_CODEC_ID_ADPCM_MS, + AV_CODEC_ID_ADPCM_4XM, + AV_CODEC_ID_ADPCM_XA, + AV_CODEC_ID_ADPCM_ADX, + AV_CODEC_ID_ADPCM_EA, + AV_CODEC_ID_ADPCM_G726, + AV_CODEC_ID_ADPCM_CT, + AV_CODEC_ID_ADPCM_SWF, + AV_CODEC_ID_ADPCM_YAMAHA, + AV_CODEC_ID_ADPCM_SBPRO_4, + AV_CODEC_ID_ADPCM_SBPRO_3, + AV_CODEC_ID_ADPCM_SBPRO_2, + AV_CODEC_ID_ADPCM_THP, + AV_CODEC_ID_ADPCM_IMA_AMV, + AV_CODEC_ID_ADPCM_EA_R1, + AV_CODEC_ID_ADPCM_EA_R3, + AV_CODEC_ID_ADPCM_EA_R2, + AV_CODEC_ID_ADPCM_IMA_EA_SEAD, + AV_CODEC_ID_ADPCM_IMA_EA_EACS, + AV_CODEC_ID_ADPCM_EA_XAS, + AV_CODEC_ID_ADPCM_EA_MAXIS_XA, + AV_CODEC_ID_ADPCM_IMA_ISS, + AV_CODEC_ID_ADPCM_G722, + AV_CODEC_ID_ADPCM_IMA_APC, + AV_CODEC_ID_ADPCM_VIMA, + AV_CODEC_ID_ADPCM_AFC, + AV_CODEC_ID_ADPCM_IMA_OKI, + AV_CODEC_ID_ADPCM_DTK, + AV_CODEC_ID_ADPCM_IMA_RAD, + AV_CODEC_ID_ADPCM_G726LE, + AV_CODEC_ID_ADPCM_THP_LE, + AV_CODEC_ID_ADPCM_PSX, + AV_CODEC_ID_ADPCM_AICA, + AV_CODEC_ID_ADPCM_IMA_DAT4, + AV_CODEC_ID_ADPCM_MTAF, + AV_CODEC_ID_ADPCM_AGM, + AV_CODEC_ID_ADPCM_ARGO, + AV_CODEC_ID_ADPCM_IMA_SSI, + AV_CODEC_ID_ADPCM_ZORK, + AV_CODEC_ID_ADPCM_IMA_APM, + AV_CODEC_ID_ADPCM_IMA_ALP, + AV_CODEC_ID_ADPCM_IMA_MTF, + AV_CODEC_ID_ADPCM_IMA_CUNNING, + AV_CODEC_ID_ADPCM_IMA_MOFLEX, + AV_CODEC_ID_ADPCM_IMA_ACORN, + AV_CODEC_ID_ADPCM_XMD, + AV_CODEC_ID_ADPCM_IMA_XBOX, + AV_CODEC_ID_ADPCM_SANYO, + AV_CODEC_ID_ADPCM_IMA_HVQM4, + AV_CODEC_ID_ADPCM_IMA_PDA, + AV_CODEC_ID_ADPCM_N64, + AV_CODEC_ID_ADPCM_IMA_HVQM2, + AV_CODEC_ID_ADPCM_IMA_MAGIX, + AV_CODEC_ID_ADPCM_PSXC, + AV_CODEC_ID_ADPCM_CIRCUS, + AV_CODEC_ID_ADPCM_IMA_ESCAPE, + + /* AMR */ + AV_CODEC_ID_AMR_NB = 0x12000, + AV_CODEC_ID_AMR_WB, + + /* RealAudio codecs*/ + AV_CODEC_ID_RA_144 = 0x13000, + AV_CODEC_ID_RA_288, + + /* various DPCM codecs */ + AV_CODEC_ID_ROQ_DPCM = 0x14000, + AV_CODEC_ID_INTERPLAY_DPCM, + AV_CODEC_ID_XAN_DPCM, + AV_CODEC_ID_SOL_DPCM, + AV_CODEC_ID_SDX2_DPCM, + AV_CODEC_ID_GREMLIN_DPCM, + AV_CODEC_ID_DERF_DPCM, + AV_CODEC_ID_WADY_DPCM, + AV_CODEC_ID_CBD2_DPCM, + + /* audio codecs */ + AV_CODEC_ID_MP2 = 0x15000, + AV_CODEC_ID_MP3, ///< preferred ID for decoding MPEG audio layer 1, 2 or 3 + AV_CODEC_ID_AAC, + AV_CODEC_ID_AC3, + AV_CODEC_ID_DTS, + AV_CODEC_ID_VORBIS, + AV_CODEC_ID_DVAUDIO, + AV_CODEC_ID_WMAV1, + AV_CODEC_ID_WMAV2, + AV_CODEC_ID_MACE3, + AV_CODEC_ID_MACE6, + AV_CODEC_ID_VMDAUDIO, + AV_CODEC_ID_FLAC, + AV_CODEC_ID_MP3ADU, + AV_CODEC_ID_MP3ON4, + AV_CODEC_ID_SHORTEN, + AV_CODEC_ID_ALAC, + AV_CODEC_ID_WESTWOOD_SND1, + AV_CODEC_ID_GSM, ///< as in Berlin toast format + AV_CODEC_ID_QDM2, + AV_CODEC_ID_COOK, + AV_CODEC_ID_TRUESPEECH, + AV_CODEC_ID_TTA, + AV_CODEC_ID_SMACKAUDIO, + AV_CODEC_ID_QCELP, + AV_CODEC_ID_WAVPACK, + AV_CODEC_ID_DSICINAUDIO, + AV_CODEC_ID_IMC, + AV_CODEC_ID_MUSEPACK7, + AV_CODEC_ID_MLP, + AV_CODEC_ID_GSM_MS, /* as found in WAV */ + AV_CODEC_ID_ATRAC3, + AV_CODEC_ID_APE, + AV_CODEC_ID_NELLYMOSER, + AV_CODEC_ID_MUSEPACK8, + AV_CODEC_ID_SPEEX, + AV_CODEC_ID_WMAVOICE, + AV_CODEC_ID_WMAPRO, + AV_CODEC_ID_WMALOSSLESS, + AV_CODEC_ID_ATRAC3P, + AV_CODEC_ID_EAC3, + AV_CODEC_ID_SIPR, + AV_CODEC_ID_MP1, + AV_CODEC_ID_TWINVQ, + AV_CODEC_ID_TRUEHD, + AV_CODEC_ID_MP4ALS, + AV_CODEC_ID_ATRAC1, + AV_CODEC_ID_BINKAUDIO_RDFT, + AV_CODEC_ID_BINKAUDIO_DCT, + AV_CODEC_ID_AAC_LATM, + AV_CODEC_ID_QDMC, + AV_CODEC_ID_CELT, + AV_CODEC_ID_G723_1, + AV_CODEC_ID_G729, + AV_CODEC_ID_8SVX_EXP, + AV_CODEC_ID_8SVX_FIB, + AV_CODEC_ID_BMV_AUDIO, + AV_CODEC_ID_RALF, + AV_CODEC_ID_IAC, + AV_CODEC_ID_ILBC, + AV_CODEC_ID_OPUS, + AV_CODEC_ID_COMFORT_NOISE, + AV_CODEC_ID_TAK, + AV_CODEC_ID_METASOUND, + AV_CODEC_ID_PAF_AUDIO, + AV_CODEC_ID_ON2AVC, + AV_CODEC_ID_DSS_SP, + AV_CODEC_ID_CODEC2, + AV_CODEC_ID_FFWAVESYNTH, + AV_CODEC_ID_SONIC, + AV_CODEC_ID_SONIC_LS, + AV_CODEC_ID_EVRC, + AV_CODEC_ID_SMV, + AV_CODEC_ID_DSD_LSBF, + AV_CODEC_ID_DSD_MSBF, + AV_CODEC_ID_DSD_LSBF_PLANAR, + AV_CODEC_ID_DSD_MSBF_PLANAR, + AV_CODEC_ID_4GV, + AV_CODEC_ID_INTERPLAY_ACM, + AV_CODEC_ID_XMA1, + AV_CODEC_ID_XMA2, + AV_CODEC_ID_DST, + AV_CODEC_ID_ATRAC3AL, + AV_CODEC_ID_ATRAC3PAL, + AV_CODEC_ID_DOLBY_E, + AV_CODEC_ID_APTX, + AV_CODEC_ID_APTX_HD, + AV_CODEC_ID_SBC, + AV_CODEC_ID_ATRAC9, + AV_CODEC_ID_HCOM, + AV_CODEC_ID_ACELP_KELVIN, + AV_CODEC_ID_MPEGH_3D_AUDIO, + AV_CODEC_ID_SIREN, + AV_CODEC_ID_HCA, + AV_CODEC_ID_FASTAUDIO, + AV_CODEC_ID_MSNSIREN, + AV_CODEC_ID_DFPWM, + AV_CODEC_ID_BONK, + AV_CODEC_ID_MISC4, + AV_CODEC_ID_APAC, + AV_CODEC_ID_FTR, + AV_CODEC_ID_WAVARC, + AV_CODEC_ID_RKA, + AV_CODEC_ID_AC4, + AV_CODEC_ID_OSQ, + AV_CODEC_ID_QOA, + AV_CODEC_ID_LC3, + AV_CODEC_ID_G728, + AV_CODEC_ID_AHX, + + /* subtitle codecs */ + AV_CODEC_ID_FIRST_SUBTITLE = 0x17000, ///< A dummy ID pointing at the start of subtitle codecs. + AV_CODEC_ID_DVD_SUBTITLE = 0x17000, + AV_CODEC_ID_DVB_SUBTITLE, + AV_CODEC_ID_TEXT, ///< raw UTF-8 text + AV_CODEC_ID_XSUB, + AV_CODEC_ID_SSA, + AV_CODEC_ID_MOV_TEXT, + AV_CODEC_ID_HDMV_PGS_SUBTITLE, + AV_CODEC_ID_DVB_TELETEXT, + AV_CODEC_ID_SRT, + AV_CODEC_ID_MICRODVD, + AV_CODEC_ID_EIA_608, + AV_CODEC_ID_JACOSUB, + AV_CODEC_ID_SAMI, + AV_CODEC_ID_REALTEXT, + AV_CODEC_ID_STL, + AV_CODEC_ID_SUBVIEWER1, + AV_CODEC_ID_SUBVIEWER, + AV_CODEC_ID_SUBRIP, + AV_CODEC_ID_WEBVTT, + AV_CODEC_ID_MPL2, + AV_CODEC_ID_VPLAYER, + AV_CODEC_ID_PJS, + AV_CODEC_ID_ASS, + AV_CODEC_ID_HDMV_TEXT_SUBTITLE, + AV_CODEC_ID_TTML, + AV_CODEC_ID_ARIB_CAPTION, + AV_CODEC_ID_IVTV_VBI, + + /* other specific kind of codecs (generally used for attachments) */ + AV_CODEC_ID_FIRST_UNKNOWN = 0x18000, ///< A dummy ID pointing at the start of various fake codecs. + AV_CODEC_ID_TTF = 0x18000, + + AV_CODEC_ID_SCTE_35, ///< Contain timestamp estimated through PCR of program stream. + AV_CODEC_ID_EPG, + AV_CODEC_ID_BINTEXT, + AV_CODEC_ID_XBIN, + AV_CODEC_ID_IDF, + AV_CODEC_ID_OTF, + AV_CODEC_ID_SMPTE_KLV, + AV_CODEC_ID_DVD_NAV, + AV_CODEC_ID_TIMED_ID3, + AV_CODEC_ID_BIN_DATA, + AV_CODEC_ID_SMPTE_2038, + AV_CODEC_ID_LCEVC, + AV_CODEC_ID_SMPTE_436M_ANC, + + + AV_CODEC_ID_PROBE = 0x19000, ///< codec_id is not known (like AV_CODEC_ID_NONE) but lavf should attempt to identify it + + AV_CODEC_ID_MPEG2TS = 0x20000, /**< _FAKE_ codec to indicate a raw MPEG-2 TS + * stream (only used by libavformat) */ + AV_CODEC_ID_MPEG4SYSTEMS = 0x20001, /**< _FAKE_ codec to indicate a MPEG-4 Systems + * stream (only used by libavformat) */ + AV_CODEC_ID_FFMETADATA = 0x21000, ///< Dummy codec for streams containing only metadata information. + AV_CODEC_ID_WRAPPED_AVFRAME = 0x21001, ///< Passthrough codec, AVFrames wrapped in AVPacket + /** + * Dummy null video codec, useful mainly for development and debugging. + * Null encoder/decoder discard all input and never return any output. + */ + AV_CODEC_ID_VNULL, + /** + * Dummy null audio codec, useful mainly for development and debugging. + * Null encoder/decoder discard all input and never return any output. + */ + AV_CODEC_ID_ANULL, +}; + +/** + * Get the type of the given codec. + */ +enum AVMediaType avcodec_get_type(enum AVCodecID codec_id); + +/** + * Get the name of a codec. + * @return a static string identifying the codec; never NULL + */ +const char *avcodec_get_name(enum AVCodecID id); + +/** + * Return codec bits per sample. + * + * @param[in] codec_id the codec + * @return Number of bits per sample or zero if unknown for the given codec. + */ +int av_get_bits_per_sample(enum AVCodecID codec_id); + +/** + * Return codec bits per sample. + * Only return non-zero if the bits per sample is exactly correct, not an + * approximation. + * + * @param[in] codec_id the codec + * @return Number of bits per sample or zero if unknown for the given codec. + */ +int av_get_exact_bits_per_sample(enum AVCodecID codec_id); + +/** + * Return a name for the specified profile, if available. + * + * @param codec_id the ID of the codec to which the requested profile belongs + * @param profile the profile value for which a name is requested + * @return A name for the profile if found, NULL otherwise. + * + * @note unlike av_get_profile_name(), which searches a list of profiles + * supported by a specific decoder or encoder implementation, this + * function searches the list of profiles from the AVCodecDescriptor + */ +const char *avcodec_profile_name(enum AVCodecID codec_id, int profile); + +/** + * Return the PCM codec associated with a sample format. + * @param be endianness, 0 for little, 1 for big, + * -1 (or anything else) for native + * @return AV_CODEC_ID_PCM_* or AV_CODEC_ID_NONE + */ +enum AVCodecID av_get_pcm_codec(enum AVSampleFormat fmt, int be); + +/** + * @} + */ + +#endif // AVCODEC_CODEC_ID_H diff --git a/ffmpeg-n8.1/include/libavcodec/codec_par.h b/ffmpeg-n8.1/include/libavcodec/codec_par.h new file mode 100644 index 00000000..2697605d --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/codec_par.h @@ -0,0 +1,253 @@ +/* + * Codec parameters public API + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_CODEC_PAR_H +#define AVCODEC_CODEC_PAR_H + +#include + +#include "libavutil/avutil.h" +#include "libavutil/channel_layout.h" +#include "libavutil/rational.h" +#include "libavutil/pixfmt.h" + +#include "codec_id.h" +#include "defs.h" +#include "packet.h" + +/** + * @addtogroup lavc_core + * @{ + */ + +/** + * This struct describes the properties of an encoded stream. + * + * sizeof(AVCodecParameters) is not a part of the public ABI, this struct must + * be allocated with avcodec_parameters_alloc() and freed with + * avcodec_parameters_free(). + */ +typedef struct AVCodecParameters { + /** + * General type of the encoded data. + */ + enum AVMediaType codec_type; + /** + * Specific type of the encoded data (the codec used). + */ + enum AVCodecID codec_id; + /** + * Additional information about the codec (corresponds to the AVI FOURCC). + */ + uint32_t codec_tag; + + /** + * Extra binary data needed for initializing the decoder, codec-dependent. + * + * Must be allocated with av_malloc() and will be freed by + * avcodec_parameters_free(). The allocated size of extradata must be at + * least extradata_size + AV_INPUT_BUFFER_PADDING_SIZE, with the padding + * bytes zeroed. + */ + uint8_t *extradata; + /** + * Size of the extradata content in bytes. + */ + int extradata_size; + + /** + * Additional data associated with the entire stream. + * + * Should be allocated with av_packet_side_data_new() or + * av_packet_side_data_add(), and will be freed by avcodec_parameters_free(). + */ + AVPacketSideData *coded_side_data; + + /** + * Amount of entries in @ref coded_side_data. + */ + int nb_coded_side_data; + + /** + * - video: the pixel format, the value corresponds to enum AVPixelFormat. + * - audio: the sample format, the value corresponds to enum AVSampleFormat. + */ + int format; + + /** + * The average bitrate of the encoded data (in bits per second). + */ + int64_t bit_rate; + + /** + * The number of bits per sample in the codedwords. + * + * This is basically the bitrate per sample. It is mandatory for a bunch of + * formats to actually decode them. It's the number of bits for one sample in + * the actual coded bitstream. + * + * This could be for example 4 for ADPCM + * For PCM formats this matches bits_per_raw_sample + * Can be 0 + */ + int bits_per_coded_sample; + + /** + * This is the number of valid bits in each output sample. If the + * sample format has more bits, the least significant bits are additional + * padding bits, which are always 0. Use right shifts to reduce the sample + * to its actual size. For example, audio formats with 24 bit samples will + * have bits_per_raw_sample set to 24, and format set to AV_SAMPLE_FMT_S32. + * To get the original sample use "(int32_t)sample >> 8"." + * + * For ADPCM this might be 12 or 16 or similar + * Can be 0 + */ + int bits_per_raw_sample; + + /** + * Codec-specific bitstream restrictions that the stream conforms to. + */ + int profile; + int level; + + /** + * Video only. The dimensions of the video frame in pixels. + */ + int width; + int height; + + /** + * Video only. The aspect ratio (width / height) which a single pixel + * should have when displayed. + * + * When the aspect ratio is unknown / undefined, the numerator should be + * set to 0 (the denominator may have any value). + */ + AVRational sample_aspect_ratio; + + /** + * Video only. Number of frames per second, for streams with constant frame + * durations. Should be set to { 0, 1 } when some frames have differing + * durations or if the value is not known. + * + * @note This field corresponds to values that are stored in codec-level + * headers and is typically overridden by container/transport-layer + * timestamps, when available. It should thus be used only as a last resort, + * when no higher-level timing information is available. + */ + AVRational framerate; + + /** + * Video only. The order of the fields in interlaced video. + */ + enum AVFieldOrder field_order; + + /** + * Video only. Additional colorspace characteristics. + */ + enum AVColorRange color_range; + enum AVColorPrimaries color_primaries; + enum AVColorTransferCharacteristic color_trc; + enum AVColorSpace color_space; + enum AVChromaLocation chroma_location; + + /** + * Video only. Number of delayed frames. + */ + int video_delay; + + /** + * Audio only. The channel layout and number of channels. + */ + AVChannelLayout ch_layout; + /** + * Audio only. The number of audio samples per second. + */ + int sample_rate; + /** + * Audio only. The number of bytes per coded audio frame, required by some + * formats. + * + * Corresponds to nBlockAlign in WAVEFORMATEX. + */ + int block_align; + /** + * Audio only. Audio frame size, if known. Required by some formats to be static. + */ + int frame_size; + + /** + * Audio only. The amount of padding (in samples) inserted by the encoder at + * the beginning of the audio. I.e. this number of leading decoded samples + * must be discarded by the caller to get the original audio without leading + * padding. + */ + int initial_padding; + /** + * Audio only. The amount of padding (in samples) appended by the encoder to + * the end of the audio. I.e. this number of decoded samples must be + * discarded by the caller from the end of the stream to get the original + * audio without any trailing padding. + */ + int trailing_padding; + /** + * Audio only. Number of samples to skip after a discontinuity. + */ + int seek_preroll; + + /** + * Video with alpha channel only. Alpha channel handling + */ + enum AVAlphaMode alpha_mode; +} AVCodecParameters; + +/** + * Allocate a new AVCodecParameters and set its fields to default values + * (unknown/invalid/0). The returned struct must be freed with + * avcodec_parameters_free(). + */ +AVCodecParameters *avcodec_parameters_alloc(void); + +/** + * Free an AVCodecParameters instance and everything associated with it and + * write NULL to the supplied pointer. + */ +void avcodec_parameters_free(AVCodecParameters **par); + +/** + * Copy the contents of src to dst. Any allocated fields in dst are freed and + * replaced with newly allocated duplicates of the corresponding fields in src. + * + * @return >= 0 on success, a negative AVERROR code on failure. + */ +int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src); + +/** + * This function is the same as av_get_audio_frame_duration(), except it works + * with AVCodecParameters instead of an AVCodecContext. + */ +int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes); + +/** + * @} + */ + +#endif // AVCODEC_CODEC_PAR_H diff --git a/ffmpeg-n8.1/include/libavcodec/d3d11va.h b/ffmpeg-n8.1/include/libavcodec/d3d11va.h new file mode 100644 index 00000000..27f40e55 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/d3d11va.h @@ -0,0 +1,109 @@ +/* + * Direct3D11 HW acceleration + * + * copyright (c) 2009 Laurent Aimar + * copyright (c) 2015 Steve Lhomme + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_D3D11VA_H +#define AVCODEC_D3D11VA_H + +/** + * @file + * @ingroup lavc_codec_hwaccel_d3d11va + * Public libavcodec D3D11VA header. + */ + +#if !defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0602 +#undef _WIN32_WINNT +#define _WIN32_WINNT 0x0602 +#endif + +#include +#include + +/** + * @defgroup lavc_codec_hwaccel_d3d11va Direct3D11 + * @ingroup lavc_codec_hwaccel + * + * @{ + */ + +/** + * This structure is used to provides the necessary configurations and data + * to the Direct3D11 FFmpeg HWAccel implementation. + * + * The application must make it available as AVCodecContext.hwaccel_context. + * + * Use av_d3d11va_alloc_context() exclusively to allocate an AVD3D11VAContext. + */ +typedef struct AVD3D11VAContext { + /** + * D3D11 decoder object + */ + ID3D11VideoDecoder *decoder; + + /** + * D3D11 VideoContext + */ + ID3D11VideoContext *video_context; + + /** + * D3D11 configuration used to create the decoder + */ + D3D11_VIDEO_DECODER_CONFIG *cfg; + + /** + * The number of surface in the surface array + */ + unsigned surface_count; + + /** + * The array of Direct3D surfaces used to create the decoder + */ + ID3D11VideoDecoderOutputView **surface; + + /** + * A bit field configuring the workarounds needed for using the decoder + */ + uint64_t workaround; + + /** + * Private to the FFmpeg AVHWAccel implementation + */ + unsigned report_id; + + /** + * Mutex to access video_context + */ + HANDLE context_mutex; +} AVD3D11VAContext; + +/** + * Allocate an AVD3D11VAContext. + * + * @return Newly-allocated AVD3D11VAContext or NULL on failure. + */ +AVD3D11VAContext *av_d3d11va_alloc_context(void); + +/** + * @} + */ + +#endif /* AVCODEC_D3D11VA_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/defs.h b/ffmpeg-n8.1/include/libavcodec/defs.h new file mode 100644 index 00000000..b13e983b --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/defs.h @@ -0,0 +1,362 @@ +/* + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_DEFS_H +#define AVCODEC_DEFS_H + +/** + * @file + * @ingroup libavc + * Misc types and constants that do not belong anywhere else. + */ + +#include +#include + +/** + * @ingroup lavc_decoding + * Required number of additionally allocated bytes at the end of the input bitstream for decoding. + * This is mainly needed because some optimized bitstream readers read + * 32 or 64 bit at once and could read over the end.
+ * Note: If the first 23 bits of the additional bytes are not 0, then damaged + * MPEG bitstreams could cause overread and segfault. + */ +#define AV_INPUT_BUFFER_PADDING_SIZE 64 + +/** + * Verify checksums embedded in the bitstream (could be of either encoded or + * decoded data, depending on the format) and print an error message on mismatch. + * If AV_EF_EXPLODE is also set, a mismatching checksum will result in the + * decoder/demuxer returning an error. + */ +#define AV_EF_CRCCHECK (1<<0) +#define AV_EF_BITSTREAM (1<<1) ///< detect bitstream specification deviations +#define AV_EF_BUFFER (1<<2) ///< detect improper bitstream length +#define AV_EF_EXPLODE (1<<3) ///< abort decoding on minor error detection + +#define AV_EF_IGNORE_ERR (1<<15) ///< ignore errors and continue +#define AV_EF_CAREFUL (1<<16) ///< consider things that violate the spec, are fast to calculate and have not been seen in the wild as errors +#define AV_EF_COMPLIANT (1<<17) ///< consider all spec non compliances as errors +#define AV_EF_AGGRESSIVE (1<<18) ///< consider things that a sane encoder/muxer should not do as an error + +#define FF_COMPLIANCE_VERY_STRICT 2 ///< Strictly conform to an older more strict version of the spec or reference software. +#define FF_COMPLIANCE_STRICT 1 ///< Strictly conform to all the things in the spec no matter what consequences. +#define FF_COMPLIANCE_NORMAL 0 +#define FF_COMPLIANCE_UNOFFICIAL -1 ///< Allow unofficial extensions +#define FF_COMPLIANCE_EXPERIMENTAL -2 ///< Allow nonstandardized experimental things. + + +#define AV_PROFILE_UNKNOWN -99 +#define AV_PROFILE_RESERVED -100 + +#define AV_PROFILE_AAC_MAIN 0 +#define AV_PROFILE_AAC_LOW 1 +#define AV_PROFILE_AAC_SSR 2 +#define AV_PROFILE_AAC_LTP 3 +#define AV_PROFILE_AAC_HE 4 +#define AV_PROFILE_AAC_HE_V2 28 +#define AV_PROFILE_AAC_LD 22 +#define AV_PROFILE_AAC_ELD 38 +#define AV_PROFILE_AAC_USAC 41 +#define AV_PROFILE_MPEG2_AAC_LOW 128 +#define AV_PROFILE_MPEG2_AAC_HE 131 + +#define AV_PROFILE_DNXHD 0 +#define AV_PROFILE_DNXHR_LB 1 +#define AV_PROFILE_DNXHR_SQ 2 +#define AV_PROFILE_DNXHR_HQ 3 +#define AV_PROFILE_DNXHR_HQX 4 +#define AV_PROFILE_DNXHR_444 5 + +#define AV_PROFILE_DTS 20 +#define AV_PROFILE_DTS_ES 30 +#define AV_PROFILE_DTS_96_24 40 +#define AV_PROFILE_DTS_HD_HRA 50 +#define AV_PROFILE_DTS_HD_MA 60 +#define AV_PROFILE_DTS_EXPRESS 70 +#define AV_PROFILE_DTS_HD_MA_X 61 +#define AV_PROFILE_DTS_HD_MA_X_IMAX 62 + +#define AV_PROFILE_EAC3_DDP_ATMOS 30 + +#define AV_PROFILE_TRUEHD_ATMOS 30 + +#define AV_PROFILE_MPEG2_422 0 +#define AV_PROFILE_MPEG2_HIGH 1 +#define AV_PROFILE_MPEG2_SS 2 +#define AV_PROFILE_MPEG2_SNR_SCALABLE 3 +#define AV_PROFILE_MPEG2_MAIN 4 +#define AV_PROFILE_MPEG2_SIMPLE 5 + +#define AV_PROFILE_H264_CONSTRAINED (1<<9) // 8+1; constraint_set1_flag +#define AV_PROFILE_H264_INTRA (1<<11) // 8+3; constraint_set3_flag + +#define AV_PROFILE_H264_BASELINE 66 +#define AV_PROFILE_H264_CONSTRAINED_BASELINE (66|AV_PROFILE_H264_CONSTRAINED) +#define AV_PROFILE_H264_MAIN 77 +#define AV_PROFILE_H264_EXTENDED 88 +#define AV_PROFILE_H264_HIGH 100 +#define AV_PROFILE_H264_HIGH_10 110 +#define AV_PROFILE_H264_HIGH_10_INTRA (110|AV_PROFILE_H264_INTRA) +#define AV_PROFILE_H264_MULTIVIEW_HIGH 118 +#define AV_PROFILE_H264_HIGH_422 122 +#define AV_PROFILE_H264_HIGH_422_INTRA (122|AV_PROFILE_H264_INTRA) +#define AV_PROFILE_H264_STEREO_HIGH 128 +#define AV_PROFILE_H264_HIGH_444 144 +#define AV_PROFILE_H264_HIGH_444_PREDICTIVE 244 +#define AV_PROFILE_H264_HIGH_444_INTRA (244|AV_PROFILE_H264_INTRA) +#define AV_PROFILE_H264_CAVLC_444 44 + +#define AV_PROFILE_VC1_SIMPLE 0 +#define AV_PROFILE_VC1_MAIN 1 +#define AV_PROFILE_VC1_COMPLEX 2 +#define AV_PROFILE_VC1_ADVANCED 3 + +#define AV_PROFILE_MPEG4_SIMPLE 0 +#define AV_PROFILE_MPEG4_SIMPLE_SCALABLE 1 +#define AV_PROFILE_MPEG4_CORE 2 +#define AV_PROFILE_MPEG4_MAIN 3 +#define AV_PROFILE_MPEG4_N_BIT 4 +#define AV_PROFILE_MPEG4_SCALABLE_TEXTURE 5 +#define AV_PROFILE_MPEG4_SIMPLE_FACE_ANIMATION 6 +#define AV_PROFILE_MPEG4_BASIC_ANIMATED_TEXTURE 7 +#define AV_PROFILE_MPEG4_HYBRID 8 +#define AV_PROFILE_MPEG4_ADVANCED_REAL_TIME 9 +#define AV_PROFILE_MPEG4_CORE_SCALABLE 10 +#define AV_PROFILE_MPEG4_ADVANCED_CODING 11 +#define AV_PROFILE_MPEG4_ADVANCED_CORE 12 +#define AV_PROFILE_MPEG4_ADVANCED_SCALABLE_TEXTURE 13 +#define AV_PROFILE_MPEG4_SIMPLE_STUDIO 14 +#define AV_PROFILE_MPEG4_ADVANCED_SIMPLE 15 + +#define AV_PROFILE_JPEG2000_CSTREAM_RESTRICTION_0 1 +#define AV_PROFILE_JPEG2000_CSTREAM_RESTRICTION_1 2 +#define AV_PROFILE_JPEG2000_CSTREAM_NO_RESTRICTION 32768 +#define AV_PROFILE_JPEG2000_DCINEMA_2K 3 +#define AV_PROFILE_JPEG2000_DCINEMA_4K 4 + +#define AV_PROFILE_VP9_0 0 +#define AV_PROFILE_VP9_1 1 +#define AV_PROFILE_VP9_2 2 +#define AV_PROFILE_VP9_3 3 + +#define AV_PROFILE_HEVC_MAIN 1 +#define AV_PROFILE_HEVC_MAIN_10 2 +#define AV_PROFILE_HEVC_MAIN_STILL_PICTURE 3 +#define AV_PROFILE_HEVC_REXT 4 +#define AV_PROFILE_HEVC_MULTIVIEW_MAIN 6 +#define AV_PROFILE_HEVC_SCC 9 + +#define AV_PROFILE_VVC_MAIN_10 1 +#define AV_PROFILE_VVC_MAIN_10_444 33 + +#define AV_PROFILE_AV1_MAIN 0 +#define AV_PROFILE_AV1_HIGH 1 +#define AV_PROFILE_AV1_PROFESSIONAL 2 + +#define AV_PROFILE_MJPEG_HUFFMAN_BASELINE_DCT 0xc0 +#define AV_PROFILE_MJPEG_HUFFMAN_EXTENDED_SEQUENTIAL_DCT 0xc1 +#define AV_PROFILE_MJPEG_HUFFMAN_PROGRESSIVE_DCT 0xc2 +#define AV_PROFILE_MJPEG_HUFFMAN_LOSSLESS 0xc3 +#define AV_PROFILE_MJPEG_JPEG_LS 0xf7 + +#define AV_PROFILE_SBC_MSBC 1 + +#define AV_PROFILE_PRORES_PROXY 0 +#define AV_PROFILE_PRORES_LT 1 +#define AV_PROFILE_PRORES_STANDARD 2 +#define AV_PROFILE_PRORES_HQ 3 +#define AV_PROFILE_PRORES_4444 4 +#define AV_PROFILE_PRORES_XQ 5 + +#define AV_PROFILE_PRORES_RAW 0 +#define AV_PROFILE_PRORES_RAW_HQ 1 + +#define AV_PROFILE_ARIB_PROFILE_A 0 +#define AV_PROFILE_ARIB_PROFILE_C 1 + +#define AV_PROFILE_KLVA_SYNC 0 +#define AV_PROFILE_KLVA_ASYNC 1 + +#define AV_PROFILE_EVC_BASELINE 0 +#define AV_PROFILE_EVC_MAIN 1 + +#define AV_PROFILE_APV_422_10 33 +#define AV_PROFILE_APV_422_12 44 +#define AV_PROFILE_APV_444_10 55 +#define AV_PROFILE_APV_444_12 66 +#define AV_PROFILE_APV_4444_10 77 +#define AV_PROFILE_APV_4444_12 88 +#define AV_PROFILE_APV_400_10 99 + + +#define AV_LEVEL_UNKNOWN -99 + +enum AVFieldOrder { + AV_FIELD_UNKNOWN, + AV_FIELD_PROGRESSIVE, + AV_FIELD_TT, ///< Top coded_first, top displayed first + AV_FIELD_BB, ///< Bottom coded first, bottom displayed first + AV_FIELD_TB, ///< Top coded first, bottom displayed first + AV_FIELD_BT, ///< Bottom coded first, top displayed first +}; + +/** + * @ingroup lavc_decoding + */ +enum AVDiscard{ + /* We leave some space between them for extensions (drop some + * keyframes for intra-only or drop just some bidir frames). */ + AVDISCARD_NONE =-16, ///< discard nothing + AVDISCARD_DEFAULT = 0, ///< discard useless packets like 0 size packets in avi + AVDISCARD_NONREF = 8, ///< discard all non reference + AVDISCARD_BIDIR = 16, ///< discard all bidirectional frames + AVDISCARD_NONINTRA= 24, ///< discard all non intra frames + AVDISCARD_NONKEY = 32, ///< discard all frames except keyframes + AVDISCARD_ALL = 48, ///< discard all +}; + +enum AVAudioServiceType { + AV_AUDIO_SERVICE_TYPE_MAIN = 0, + AV_AUDIO_SERVICE_TYPE_EFFECTS = 1, + AV_AUDIO_SERVICE_TYPE_VISUALLY_IMPAIRED = 2, + AV_AUDIO_SERVICE_TYPE_HEARING_IMPAIRED = 3, + AV_AUDIO_SERVICE_TYPE_DIALOGUE = 4, + AV_AUDIO_SERVICE_TYPE_COMMENTARY = 5, + AV_AUDIO_SERVICE_TYPE_EMERGENCY = 6, + AV_AUDIO_SERVICE_TYPE_VOICE_OVER = 7, + AV_AUDIO_SERVICE_TYPE_KARAOKE = 8, + AV_AUDIO_SERVICE_TYPE_NB , ///< Not part of ABI +}; + +/** + * Pan Scan area. + * This specifies the area which should be displayed. + * Note there may be multiple such areas for one frame. + */ +typedef struct AVPanScan { + /** + * id + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + int id; + + /** + * width and height in 1/16 pel + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + int width; + int height; + + /** + * position of the top left corner in 1/16 pel for up to 3 fields/frames + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + int16_t position[3][2]; +} AVPanScan; + +/** + * This structure describes the bitrate properties of an encoded bitstream. It + * roughly corresponds to a subset the VBV parameters for MPEG-2 or HRD + * parameters for H.264/HEVC. + */ +typedef struct AVCPBProperties { + /** + * Maximum bitrate of the stream, in bits per second. + * Zero if unknown or unspecified. + */ + int64_t max_bitrate; + /** + * Minimum bitrate of the stream, in bits per second. + * Zero if unknown or unspecified. + */ + int64_t min_bitrate; + /** + * Average bitrate of the stream, in bits per second. + * Zero if unknown or unspecified. + */ + int64_t avg_bitrate; + + /** + * The size of the buffer to which the ratecontrol is applied, in bits. + * Zero if unknown or unspecified. + */ + int64_t buffer_size; + + /** + * The delay between the time the packet this structure is associated with + * is received and the time when it should be decoded, in periods of a 27MHz + * clock. + * + * UINT64_MAX when unknown or unspecified. + */ + uint64_t vbv_delay; +} AVCPBProperties; + +/** + * Allocate a CPB properties structure and initialize its fields to default + * values. + * + * @param size if non-NULL, the size of the allocated struct will be written + * here. This is useful for embedding it in side data. + * + * @return the newly allocated struct or NULL on failure + */ +AVCPBProperties *av_cpb_properties_alloc(size_t *size); + +/** + * This structure supplies correlation between a packet timestamp and a wall clock + * production time. The definition follows the Producer Reference Time ('prft') + * as defined in ISO/IEC 14496-12 + */ +typedef struct AVProducerReferenceTime { + /** + * A UTC timestamp, in microseconds, since Unix epoch (e.g, av_gettime()). + */ + int64_t wallclock; + int flags; +} AVProducerReferenceTime; + +/** + * RTCP SR (Sender Report) information + * + * The received sender report information for an RTSP + * stream, exposed as AV_PKT_DATA_RTCP_SR side data. + */ +typedef struct AVRTCPSenderReport { + uint32_t ssrc; ///< Synchronization source identifier + uint64_t ntp_timestamp; ///< NTP time when the report was sent + uint32_t rtp_timestamp; ///< RTP time when the report was sent + uint32_t sender_nb_packets; ///< Total number of packets sent + uint32_t sender_nb_bytes; ///< Total number of bytes sent (excluding headers or padding) +} AVRTCPSenderReport; + +/** + * Encode extradata length to a buffer. Used by xiph codecs. + * + * @param s buffer to write to; must be at least (v/255+1) bytes long + * @param v size of extradata in bytes + * @return number of bytes written to the buffer. + */ +unsigned int av_xiphlacing(unsigned char *s, unsigned int v); + +#endif // AVCODEC_DEFS_H diff --git a/ffmpeg-n8.1/include/libavcodec/dirac.h b/ffmpeg-n8.1/include/libavcodec/dirac.h new file mode 100644 index 00000000..8c348cdc --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/dirac.h @@ -0,0 +1,135 @@ +/* + * Copyright (C) 2007 Marco Gerards + * Copyright (C) 2009 David Conrad + * Copyright (C) 2011 Jordi Ortiz + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_DIRAC_H +#define AVCODEC_DIRAC_H + +/** + * @file + * Interface to Dirac Decoder/Encoder + * @author Marco Gerards + * @author David Conrad + * @author Jordi Ortiz + */ + +#include +#include + +#include "libavutil/pixfmt.h" +#include "libavutil/rational.h" + +/** + * The spec limits the number of wavelet decompositions to 4 for both + * level 1 (VC-2) and 128 (long-gop default). + * 5 decompositions is the maximum before >16-bit buffers are needed. + * Schroedinger allows this for DD 9,7 and 13,7 wavelets only, limiting + * the others to 4 decompositions (or 3 for the fidelity filter). + * + * We use this instead of MAX_DECOMPOSITIONS to save some memory. + */ +#define MAX_DWT_LEVELS 5 + +/** + * Parse code values: + * + * Dirac Specification -> + * 9.6.1 Table 9.1 + * + * VC-2 Specification -> + * 10.4.1 Table 10.1 + */ + +enum DiracParseCodes { + DIRAC_PCODE_SEQ_HEADER = 0x00, + DIRAC_PCODE_END_SEQ = 0x10, + DIRAC_PCODE_AUX = 0x20, + DIRAC_PCODE_PAD = 0x30, + DIRAC_PCODE_PICTURE_CODED = 0x08, + DIRAC_PCODE_PICTURE_RAW = 0x48, + DIRAC_PCODE_PICTURE_LOW_DEL = 0xC8, + DIRAC_PCODE_PICTURE_HQ = 0xE8, + DIRAC_PCODE_INTER_NOREF_CO1 = 0x0A, + DIRAC_PCODE_INTER_NOREF_CO2 = 0x09, + DIRAC_PCODE_INTER_REF_CO1 = 0x0D, + DIRAC_PCODE_INTER_REF_CO2 = 0x0E, + DIRAC_PCODE_INTRA_REF_CO = 0x0C, + DIRAC_PCODE_INTRA_REF_RAW = 0x4C, + DIRAC_PCODE_INTRA_REF_PICT = 0xCC, + DIRAC_PCODE_MAGIC = 0x42424344, +}; + +typedef struct DiracVersionInfo { + int major; + int minor; +} DiracVersionInfo; + +typedef struct AVDiracSeqHeader { + unsigned width; + unsigned height; + uint8_t chroma_format; ///< 0: 444 1: 422 2: 420 + + uint8_t interlaced; + uint8_t top_field_first; + + uint8_t frame_rate_index; ///< index into dirac_frame_rate[] + uint8_t aspect_ratio_index; ///< index into dirac_aspect_ratio[] + + uint16_t clean_width; + uint16_t clean_height; + uint16_t clean_left_offset; + uint16_t clean_right_offset; + + uint8_t pixel_range_index; ///< index into dirac_pixel_range_presets[] + uint8_t color_spec_index; ///< index into dirac_color_spec_presets[] + + int profile; + int level; + + AVRational framerate; + AVRational sample_aspect_ratio; + + enum AVPixelFormat pix_fmt; + enum AVColorRange color_range; + enum AVColorPrimaries color_primaries; + enum AVColorTransferCharacteristic color_trc; + enum AVColorSpace colorspace; + + DiracVersionInfo version; + int bit_depth; +} AVDiracSeqHeader; + +/** + * Parse a Dirac sequence header. + * + * @param dsh this function will allocate and fill an AVDiracSeqHeader struct + * and write it into this pointer. The caller must free it with + * av_free(). + * @param buf the data buffer + * @param buf_size the size of the data buffer in bytes + * @param log_ctx if non-NULL, this function will log errors here + * @return 0 on success, a negative AVERROR code on failure + */ +int av_dirac_parse_sequence_header(AVDiracSeqHeader **dsh, + const uint8_t *buf, size_t buf_size, + void *log_ctx); + +#endif /* AVCODEC_DIRAC_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/dv_profile.h b/ffmpeg-n8.1/include/libavcodec/dv_profile.h new file mode 100644 index 00000000..4365f1b4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/dv_profile.h @@ -0,0 +1,82 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_DV_PROFILE_H +#define AVCODEC_DV_PROFILE_H + +#include + +#include "libavutil/pixfmt.h" +#include "libavutil/rational.h" + +/* minimum number of bytes to read from a DV stream in order to + * determine the profile */ +#define DV_PROFILE_BYTES (6 * 80) /* 6 DIF blocks */ + + +/* + * AVDVProfile is used to express the differences between various + * DV flavors. For now it's primarily used for differentiating + * 525/60 and 625/50, but the plans are to use it for various + * DV specs as well (e.g. SMPTE314M vs. IEC 61834). + */ +typedef struct AVDVProfile { + int dsf; /* value of the dsf in the DV header */ + int video_stype; /* stype for VAUX source pack */ + int frame_size; /* total size of one frame in bytes */ + int difseg_size; /* number of DIF segments per DIF channel */ + int n_difchan; /* number of DIF channels per frame */ + AVRational time_base; /* 1/framerate */ + int ltc_divisor; /* FPS from the LTS standpoint */ + int height; /* picture height in pixels */ + int width; /* picture width in pixels */ + AVRational sar[2]; /* sample aspect ratios for 4:3 and 16:9 */ + enum AVPixelFormat pix_fmt; /* picture pixel format */ + int bpm; /* blocks per macroblock */ + const uint8_t *block_sizes; /* AC block sizes, in bits */ + int audio_stride; /* size of audio_shuffle table */ + int audio_min_samples[3]; /* min amount of audio samples */ + /* for 48kHz, 44.1kHz and 32kHz */ + int audio_samples_dist[5]; /* how many samples are supposed to be */ + /* in each frame in a 5 frames window */ + const uint8_t (*audio_shuffle)[9]; /* PCM shuffling table */ +} AVDVProfile; + +/** + * Get a DV profile for the provided compressed frame. + * + * @param sys the profile used for the previous frame, may be NULL + * @param frame the compressed data buffer + * @param buf_size size of the buffer in bytes + * @return the DV profile for the supplied data or NULL on failure + */ +const AVDVProfile *av_dv_frame_profile(const AVDVProfile *sys, + const uint8_t *frame, unsigned buf_size); + +/** + * Get a DV profile for the provided stream parameters. + */ +const AVDVProfile *av_dv_codec_profile(int width, int height, enum AVPixelFormat pix_fmt); + +/** + * Get a DV profile for the provided stream parameters. + * The frame rate is used as a best-effort parameter. + */ +const AVDVProfile *av_dv_codec_profile2(int width, int height, enum AVPixelFormat pix_fmt, AVRational frame_rate); + +#endif /* AVCODEC_DV_PROFILE_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/dxva2.h b/ffmpeg-n8.1/include/libavcodec/dxva2.h new file mode 100644 index 00000000..bdec6112 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/dxva2.h @@ -0,0 +1,90 @@ +/* + * DXVA2 HW acceleration + * + * copyright (c) 2009 Laurent Aimar + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_DXVA2_H +#define AVCODEC_DXVA2_H + +/** + * @file + * @ingroup lavc_codec_hwaccel_dxva2 + * Public libavcodec DXVA2 header. + */ + +#if !defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0602 +#undef _WIN32_WINNT +#define _WIN32_WINNT 0x0602 +#endif + +#include +#include +#include + +/** + * @defgroup lavc_codec_hwaccel_dxva2 DXVA2 + * @ingroup lavc_codec_hwaccel + * + * @{ + */ + +/** + * This structure is used to provides the necessary configurations and data + * to the DXVA2 FFmpeg HWAccel implementation. + * + * The application must make it available as AVCodecContext.hwaccel_context. + */ +struct dxva_context { + /** + * DXVA2 decoder object + */ + IDirectXVideoDecoder *decoder; + + /** + * DXVA2 configuration used to create the decoder + */ + const DXVA2_ConfigPictureDecode *cfg; + + /** + * The number of surface in the surface array + */ + unsigned surface_count; + + /** + * The array of Direct3D surfaces used to create the decoder + */ + LPDIRECT3DSURFACE9 *surface; + + /** + * A bit field configuring the workarounds needed for using the decoder + */ + uint64_t workaround; + + /** + * Private to the FFmpeg AVHWAccel implementation + */ + unsigned report_id; +}; + +/** + * @} + */ + +#endif /* AVCODEC_DXVA2_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/exif.h b/ffmpeg-n8.1/include/libavcodec/exif.h new file mode 100644 index 00000000..1824a38d --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/exif.h @@ -0,0 +1,229 @@ +/* + * EXIF metadata parser + * Copyright (c) 2013 Thilo Borgmann + * Copyright (c) 2024-2025 Leo Izen + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * EXIF metadata parser + * @author Thilo Borgmann + * @author Leo Izen + */ + +#ifndef AVCODEC_EXIF_H +#define AVCODEC_EXIF_H + +#include +#include + +#include "libavutil/buffer.h" +#include "libavutil/dict.h" +#include "libavutil/rational.h" +#include "version_major.h" + +/** Data type identifiers for TIFF tags */ +enum AVTiffDataType { + AV_TIFF_BYTE = 1, + AV_TIFF_STRING, + AV_TIFF_SHORT, + AV_TIFF_LONG, + AV_TIFF_RATIONAL, + AV_TIFF_SBYTE, + AV_TIFF_UNDEFINED, + AV_TIFF_SSHORT, + AV_TIFF_SLONG, + AV_TIFF_SRATIONAL, + AV_TIFF_FLOAT, + AV_TIFF_DOUBLE, + AV_TIFF_IFD, +}; + +enum AVExifHeaderMode { + /** + * The TIFF header starts with 0x49492a00, or 0x4d4d002a. + * This one is used internally by FFmpeg. + */ + AV_EXIF_TIFF_HEADER, + /** skip the TIFF header, assume little endian */ + AV_EXIF_ASSUME_LE, + /** skip the TIFF header, assume big endian */ + AV_EXIF_ASSUME_BE, + /** The first four bytes point to the actual start, then it's AV_EXIF_TIFF_HEADER */ + AV_EXIF_T_OFF, + /** The first six bytes contain "Exif\0\0", then it's AV_EXIF_TIFF_HEADER */ + AV_EXIF_EXIF00, +}; + +typedef struct AVExifEntry AVExifEntry; + +typedef struct AVExifMetadata { + /* array of EXIF metadata entries */ + AVExifEntry *entries; + /* number of entries in this array */ + unsigned int count; + /* size of the buffer, used for av_fast_realloc */ + unsigned int size; +} AVExifMetadata; + +struct AVExifEntry { + uint16_t id; + enum AVTiffDataType type; + uint32_t count; + + /* + * These are for IFD-style MakerNote + * entries which occur after a fixed + * offset rather than at the start of + * the entry. The ifd_lead field contains + * the leading bytes which typically + * identify the type of MakerNote. + */ + uint32_t ifd_offset; + uint8_t *ifd_lead; + + /* + * An array of entries of size count + * Unless it's an IFD, in which case + * it's not an array and count = 1 + */ + union { + void *ptr; + int64_t *sint; + uint64_t *uint; + double *dbl; + char *str; + uint8_t *ubytes; + int8_t *sbytes; + AVRational *rat; + AVExifMetadata ifd; + } value; +}; + +/** + * Retrieves the tag name associated with the provided tag ID. + * If the tag ID is unknown, NULL is returned. + * + * For example, av_exif_get_tag_name(0x112) returns "Orientation". + */ +const char *av_exif_get_tag_name(uint16_t id); + +/** + * Retrieves the tag ID associated with the provided tag string name. + * If the tag name is unknown, a negative number is returned. Otherwise + * it always fits inside a uint16_t integer. + * + * For example, av_exif_get_tag_id("Orientation") returns 274 (0x0112). + */ +int32_t av_exif_get_tag_id(const char *name); + +/** + * Add an entry to the provided EXIF metadata struct. If one already exists with the provided + * ID, it will set the existing one to have the other information provided. Otherwise, it + * will allocate a new entry. + * + * This function reallocates ifd->entries using av_realloc and allocates (using av_malloc) + * a new value member of the entry, then copies the contents of value into that buffer. + */ +int av_exif_set_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, enum AVTiffDataType type, + uint32_t count, const uint8_t *ifd_lead, uint32_t ifd_offset, const void *value); + +/** + * Also check subdirectories. + */ +#define AV_EXIF_FLAG_RECURSIVE (1 << 0) + +/** + * Get an entry with the tagged ID from the EXIF metadata struct. A pointer to the entry + * will be written into *value. + * + * If the entry was present and returned successfully, a positive number is returned. + * If the entry was not found, *value is left untouched and zero is returned. + * If an error occurred, a negative number is returned. + */ +int av_exif_get_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, int flags, AVExifEntry **value); + +/** + * Remove an entry from the provided EXIF metadata struct. + * + * If the entry was present and removed successfully, a positive number is returned. + * If the entry was not found, zero is returned. + * If an error occurred, a negative number is returned. + */ +int av_exif_remove_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, int flags); + +/** + * Decodes the EXIF data provided in the buffer and writes it into the + * struct *ifd. If this function succeeds, the IFD is owned by the caller + * and must be cleared after use by calling av_exif_free(); If this function + * fails and returns a negative value, it will call av_exif_free(ifd) before + * returning. + */ +int av_exif_parse_buffer(void *logctx, const uint8_t *data, size_t size, + AVExifMetadata *ifd, enum AVExifHeaderMode header_mode); + +/** + * Allocates a buffer using av_malloc of an appropriate size and writes the + * EXIF data represented by ifd into that buffer. + * + * Upon error, *buffer will be NULL. The buffer becomes owned by the caller upon + * success. The *buffer argument must be NULL before calling. + */ +int av_exif_write(void *logctx, const AVExifMetadata *ifd, AVBufferRef **buffer, enum AVExifHeaderMode header_mode); + +/** + * Frees all resources associated with the given EXIF metadata struct. + * Does not free the pointer passed itself, in case it is stack-allocated. + * The pointer passed to this function must be freed by the caller, + * if it is heap-allocated. Passing NULL is permitted. + */ +void av_exif_free(AVExifMetadata *ifd); + +/** + * Recursively reads all tags from the IFD and stores them in the + * provided metadata dictionary. + */ +int av_exif_ifd_to_dict(void *logctx, const AVExifMetadata *ifd, AVDictionary **metadata); + +/** + * Allocates a duplicate of the provided EXIF metadata struct. The caller owns + * the duplicate and must free it with av_exif_free. Returns NULL if the duplication + * process failed. + */ +AVExifMetadata *av_exif_clone_ifd(const AVExifMetadata *ifd); + +/** + * Convert a display matrix used by AV_FRAME_DATA_DISPLAYMATRIX + * into an orientation constant used by EXIF's orientation tag. + * + * Returns an EXIF orientation between 1 and 8 (inclusive) depending + * on the rotation and flip factors. Returns 0 if the matrix is singular. + */ +int av_exif_matrix_to_orientation(const int32_t *matrix); + +/** + * Convert an orientation constant used by EXIF's orientation tag + * into a display matrix used by AV_FRAME_DATA_DISPLAYMATRIX. + * + * Returns 0 on success and negative if the orientation is invalid, + * i.e. not between 1 and 8 (inclusive). + */ +int av_exif_orientation_to_matrix(int32_t *matrix, int orientation); + +#endif /* AVCODEC_EXIF_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/jni.h b/ffmpeg-n8.1/include/libavcodec/jni.h new file mode 100644 index 00000000..955cd280 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/jni.h @@ -0,0 +1,67 @@ +/* + * JNI public API functions + * + * Copyright (c) 2015-2016 Matthieu Bouron + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_JNI_H +#define AVCODEC_JNI_H + +/* + * Manually set a Java virtual machine which will be used to retrieve the JNI + * environment. Once a Java VM is set it cannot be changed afterwards, meaning + * you can call multiple times av_jni_set_java_vm with the same Java VM pointer + * however it will error out if you try to set a different Java VM. + * + * @param vm Java virtual machine + * @param log_ctx context used for logging, can be NULL + * @return 0 on success, < 0 otherwise + */ +int av_jni_set_java_vm(void *vm, void *log_ctx); + +/* + * Get the Java virtual machine which has been set with av_jni_set_java_vm. + * + * @param vm Java virtual machine + * @return a pointer to the Java virtual machine + */ +void *av_jni_get_java_vm(void *log_ctx); + +/* + * Set the Android application context which will be used to retrieve the Android + * content resolver to handle content uris. + * + * This function is only available on Android. + * + * @param app_ctx global JNI reference to the Android application context + * @return 0 on success, < 0 otherwise + */ +int av_jni_set_android_app_ctx(void *app_ctx, void *log_ctx); + +/* + * Get the Android application context that has been set with + * av_jni_set_android_app_ctx. + * + * This function is only available on Android. + * + * @return a pointer the the Android application context + */ +void *av_jni_get_android_app_ctx(void); + +#endif /* AVCODEC_JNI_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/mediacodec.h b/ffmpeg-n8.1/include/libavcodec/mediacodec.h new file mode 100644 index 00000000..4e9b56a6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/mediacodec.h @@ -0,0 +1,103 @@ +/* + * Android MediaCodec public API + * + * Copyright (c) 2016 Matthieu Bouron + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_MEDIACODEC_H +#define AVCODEC_MEDIACODEC_H + +#include "libavcodec/avcodec.h" + +/** + * This structure holds a reference to a android/view/Surface object that will + * be used as output by the decoder. + * + */ +typedef struct AVMediaCodecContext { + + /** + * android/view/Surface object reference. + */ + void *surface; + +} AVMediaCodecContext; + +/** + * Allocate and initialize a MediaCodec context. + * + * When decoding with MediaCodec is finished, the caller must free the + * MediaCodec context with av_mediacodec_default_free. + * + * @return a pointer to a newly allocated AVMediaCodecContext on success, NULL otherwise + */ +AVMediaCodecContext *av_mediacodec_alloc_context(void); + +/** + * Convenience function that sets up the MediaCodec context. + * + * @param avctx codec context + * @param ctx MediaCodec context to initialize + * @param surface reference to an android/view/Surface + * @return 0 on success, < 0 otherwise + */ +int av_mediacodec_default_init(AVCodecContext *avctx, AVMediaCodecContext *ctx, void *surface); + +/** + * This function must be called to free the MediaCodec context initialized with + * av_mediacodec_default_init(). + * + * @param avctx codec context + */ +void av_mediacodec_default_free(AVCodecContext *avctx); + +/** + * Opaque structure representing a MediaCodec buffer to render. + */ +typedef struct MediaCodecBuffer AVMediaCodecBuffer; + +/** + * Release a MediaCodec buffer and render it to the surface that is associated + * with the decoder. This function should only be called once on a given + * buffer, once released the underlying buffer returns to the codec, thus + * subsequent calls to this function will have no effect. + * + * @param buffer the buffer to render + * @param render 1 to release and render the buffer to the surface or 0 to + * discard the buffer + * @return 0 on success, < 0 otherwise + */ +int av_mediacodec_release_buffer(AVMediaCodecBuffer *buffer, int render); + +/** + * Release a MediaCodec buffer and render it at the given time to the surface + * that is associated with the decoder. The timestamp must be within one second + * of the current `java/lang/System#nanoTime()` (which is implemented using + * `CLOCK_MONOTONIC` on Android). See the Android MediaCodec documentation + * of [`android/media/MediaCodec#releaseOutputBuffer(int,long)`][0] for more details. + * + * @param buffer the buffer to render + * @param time timestamp in nanoseconds of when to render the buffer + * @return 0 on success, < 0 otherwise + * + * [0]: https://developer.android.com/reference/android/media/MediaCodec#releaseOutputBuffer(int,%20long) + */ +int av_mediacodec_render_buffer_at_time(AVMediaCodecBuffer *buffer, int64_t time); + +#endif /* AVCODEC_MEDIACODEC_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/packet.h b/ffmpeg-n8.1/include/libavcodec/packet.h new file mode 100644 index 00000000..59bfddf4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/packet.h @@ -0,0 +1,943 @@ +/* + * AVPacket public API + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_PACKET_H +#define AVCODEC_PACKET_H + +#include +#include + +#include "libavutil/attributes.h" +#include "libavutil/buffer.h" +#include "libavutil/dict.h" +#include "libavutil/rational.h" +#include "libavutil/version.h" + +#include "libavcodec/version_major.h" + +/** + * @defgroup lavc_packet_side_data AVPacketSideData + * + * Types and functions for working with AVPacketSideData. + * @{ + */ +enum AVPacketSideDataType { + /** + * An AV_PKT_DATA_PALETTE side data packet contains exactly AVPALETTE_SIZE + * bytes worth of palette. This side data signals that a new palette is + * present. + */ + AV_PKT_DATA_PALETTE, + + /** + * The AV_PKT_DATA_NEW_EXTRADATA is used to notify the codec or the format + * that the extradata buffer was changed and the receiving side should + * act upon it appropriately. The new extradata is embedded in the side + * data buffer and should be immediately used for processing the current + * frame or packet. + */ + AV_PKT_DATA_NEW_EXTRADATA, + + /** + * An AV_PKT_DATA_PARAM_CHANGE side data packet is laid out as follows: + * @code + * u32le param_flags + * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE) + * s32le sample_rate + * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS) + * s32le width + * s32le height + * @endcode + */ + AV_PKT_DATA_PARAM_CHANGE, + + /** + * An AV_PKT_DATA_H263_MB_INFO side data packet contains a number of + * structures with info about macroblocks relevant to splitting the + * packet into smaller packets on macroblock edges (e.g. as for RFC 2190). + * That is, it does not necessarily contain info about all macroblocks, + * as long as the distance between macroblocks in the info is smaller + * than the target payload size. + * Each MB info structure is 12 bytes, and is laid out as follows: + * @code + * u32le bit offset from the start of the packet + * u8 current quantizer at the start of the macroblock + * u8 GOB number + * u16le macroblock address within the GOB + * u8 horizontal MV predictor + * u8 vertical MV predictor + * u8 horizontal MV predictor for block number 3 + * u8 vertical MV predictor for block number 3 + * @endcode + */ + AV_PKT_DATA_H263_MB_INFO, + + /** + * This side data should be associated with an audio stream and contains + * ReplayGain information in form of the AVReplayGain struct. + */ + AV_PKT_DATA_REPLAYGAIN, + + /** + * This side data contains a 3x3 transformation matrix describing an affine + * transformation that needs to be applied to the decoded video frames for + * correct presentation. + * + * See libavutil/display.h for a detailed description of the data. + */ + AV_PKT_DATA_DISPLAYMATRIX, + + /** + * This side data should be associated with a video stream and contains + * Stereoscopic 3D information in form of the AVStereo3D struct. + */ + AV_PKT_DATA_STEREO3D, + + /** + * This side data should be associated with an audio stream and corresponds + * to enum AVAudioServiceType. + */ + AV_PKT_DATA_AUDIO_SERVICE_TYPE, + + /** + * This side data contains quality related information from the encoder. + * @code + * u32le quality factor of the compressed frame. Allowed range is between 1 (good) and FF_LAMBDA_MAX (bad). + * u8 picture type + * u8 error count + * u16 reserved + * u64le[error count] sum of squared differences between encoder in and output + * @endcode + */ + AV_PKT_DATA_QUALITY_STATS, + + /** + * This side data contains an integer value representing the stream index + * of a "fallback" track. A fallback track indicates an alternate + * track to use when the current track can not be decoded for some reason. + * e.g. no decoder available for codec. + */ + AV_PKT_DATA_FALLBACK_TRACK, + + /** + * This side data corresponds to the AVCPBProperties struct. + */ + AV_PKT_DATA_CPB_PROPERTIES, + + /** + * Recommends skipping the specified number of samples + * @code + * u32le number of samples to skip from start of this packet + * u32le number of samples to skip from end of this packet + * u8 reason for start skip + * u8 reason for end skip (0=padding silence, 1=convergence) + * @endcode + */ + AV_PKT_DATA_SKIP_SAMPLES, + + /** + * An AV_PKT_DATA_JP_DUALMONO side data packet indicates that + * the packet may contain "dual mono" audio specific to Japanese DTV + * and if it is true, recommends only the selected channel to be used. + * @code + * u8 selected channels (0=main/left, 1=sub/right, 2=both) + * @endcode + */ + AV_PKT_DATA_JP_DUALMONO, + + /** + * A list of zero terminated key/value strings. There is no end marker for + * the list, so it is required to rely on the side data size to stop. + */ + AV_PKT_DATA_STRINGS_METADATA, + + /** + * Subtitle event position + * @code + * u32le x1 + * u32le y1 + * u32le x2 + * u32le y2 + * @endcode + */ + AV_PKT_DATA_SUBTITLE_POSITION, + + /** + * Data found in BlockAdditional element of matroska container. There is + * no end marker for the data, so it is required to rely on the side data + * size to recognize the end. 8 byte id (as found in BlockAddId) followed + * by data. + */ + AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL, + + /** + * The optional first identifier line of a WebVTT cue. + */ + AV_PKT_DATA_WEBVTT_IDENTIFIER, + + /** + * The optional settings (rendering instructions) that immediately + * follow the timestamp specifier of a WebVTT cue. + */ + AV_PKT_DATA_WEBVTT_SETTINGS, + + /** + * A list of zero terminated key/value strings. There is no end marker for + * the list, so it is required to rely on the side data size to stop. This + * side data includes updated metadata which appeared in the stream. + */ + AV_PKT_DATA_METADATA_UPDATE, + + /** + * MPEGTS stream ID as uint8_t, this is required to pass the stream ID + * information from the demuxer to the corresponding muxer. + */ + AV_PKT_DATA_MPEGTS_STREAM_ID, + + /** + * Mastering display metadata (based on SMPTE-2086:2014). This metadata + * should be associated with a video stream and contains data in the form + * of the AVMasteringDisplayMetadata struct. + */ + AV_PKT_DATA_MASTERING_DISPLAY_METADATA, + + /** + * This side data should be associated with a video stream and corresponds + * to the AVSphericalMapping structure. + */ + AV_PKT_DATA_SPHERICAL, + + /** + * Content light level (based on CTA-861.3). This metadata should be + * associated with a video stream and contains data in the form of the + * AVContentLightMetadata struct. + */ + AV_PKT_DATA_CONTENT_LIGHT_LEVEL, + + /** + * ATSC A53 Part 4 Closed Captions. This metadata should be associated with + * a video stream. A53 CC bitstream is stored as uint8_t in AVPacketSideData.data. + * The number of bytes of CC data is AVPacketSideData.size. + */ + AV_PKT_DATA_A53_CC, + + /** + * This side data is encryption initialization data. + * The format is not part of ABI, use av_encryption_init_info_* methods to + * access. + */ + AV_PKT_DATA_ENCRYPTION_INIT_INFO, + + /** + * This side data contains encryption info for how to decrypt the packet. + * The format is not part of ABI, use av_encryption_info_* methods to access. + */ + AV_PKT_DATA_ENCRYPTION_INFO, + + /** + * Active Format Description data consisting of a single byte as specified + * in ETSI TS 101 154 using AVActiveFormatDescription enum. + */ + AV_PKT_DATA_AFD, + + /** + * Producer Reference Time data corresponding to the AVProducerReferenceTime struct, + * usually exported by some encoders (on demand through the prft flag set in the + * AVCodecContext export_side_data field). + */ + AV_PKT_DATA_PRFT, + + /** + * ICC profile data consisting of an opaque octet buffer following the + * format described by ISO 15076-1. + */ + AV_PKT_DATA_ICC_PROFILE, + + /** + * DOVI configuration + * ref: + * dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2, section 2.2 + * dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2, section 3.3 + * Tags are stored in struct AVDOVIDecoderConfigurationRecord. + */ + AV_PKT_DATA_DOVI_CONF, + + /** + * Timecode which conforms to SMPTE ST 12-1:2014. The data is an array of 4 uint32_t + * where the first uint32_t describes how many (1-3) of the other timecodes are used. + * The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum() + * function in libavutil/timecode.h. + */ + AV_PKT_DATA_S12M_TIMECODE, + + /** + * HDR10+ dynamic metadata associated with a video frame. The metadata is in + * the form of the AVDynamicHDRPlus struct and contains + * information for color volume transform - application 4 of + * SMPTE 2094-40:2016 standard. + */ + AV_PKT_DATA_DYNAMIC_HDR10_PLUS, + + /** + * IAMF Mix Gain Parameter Data associated with the audio frame. This metadata + * is in the form of the AVIAMFParamDefinition struct and contains information + * defined in sections 3.6.1 and 3.8.1 of the Immersive Audio Model and + * Formats standard. + */ + AV_PKT_DATA_IAMF_MIX_GAIN_PARAM, + + /** + * IAMF Demixing Info Parameter Data associated with the audio frame. This + * metadata is in the form of the AVIAMFParamDefinition struct and contains + * information defined in sections 3.6.1 and 3.8.2 of the Immersive Audio Model + * and Formats standard. + */ + AV_PKT_DATA_IAMF_DEMIXING_INFO_PARAM, + + /** + * IAMF Recon Gain Info Parameter Data associated with the audio frame. This + * metadata is in the form of the AVIAMFParamDefinition struct and contains + * information defined in sections 3.6.1 and 3.8.3 of the Immersive Audio Model + * and Formats standard. + */ + AV_PKT_DATA_IAMF_RECON_GAIN_INFO_PARAM, + + /** + * Ambient viewing environment metadata, as defined by H.274. This metadata + * should be associated with a video stream and contains data in the form + * of the AVAmbientViewingEnvironment struct. + */ + AV_PKT_DATA_AMBIENT_VIEWING_ENVIRONMENT, + + /** + * The number of pixels to discard from the top/bottom/left/right border of the + * decoded frame to obtain the sub-rectangle intended for presentation. + * + * @code + * u32le crop_top + * u32le crop_bottom + * u32le crop_left + * u32le crop_right + * @endcode + */ + AV_PKT_DATA_FRAME_CROPPING, + + /** + * Raw LCEVC payload data, as a uint8_t array, with NAL emulation + * bytes intact. + */ + AV_PKT_DATA_LCEVC, + + /** + * This side data contains information about the reference display width(s) + * and reference viewing distance(s) as well as information about the + * corresponding reference stereo pair(s), i.e., the pair(s) of views to be + * displayed for the viewer's left and right eyes on the reference display + * at the reference viewing distance. + * The payload is the AV3DReferenceDisplaysInfo struct defined in + * libavutil/tdrdi.h. + */ + AV_PKT_DATA_3D_REFERENCE_DISPLAYS, + + /** + * Contains the last received RTCP SR (Sender Report) information + * in the form of the AVRTCPSenderReport struct. + */ + AV_PKT_DATA_RTCP_SR, + + /** + * Extensible image file format metadata. The payload is a buffer containing + * EXIF metadata, starting with either 49 49 2a 00, or 4d 4d 00 2a. + */ + AV_PKT_DATA_EXIF, + + /** + * The number of side data types. + * This is not part of the public API/ABI in the sense that it may + * change when new side data types are added. + * This must stay the last enum value. + * If its value becomes huge, some code using it + * needs to be updated as it assumes it to be smaller than other limits. + */ + AV_PKT_DATA_NB +}; + +/** + * This structure stores auxiliary information for decoding, presenting, or + * otherwise processing the coded stream. It is typically exported by demuxers + * and encoders and can be fed to decoders and muxers either in a per packet + * basis, or as global side data (applying to the entire coded stream). + * + * Global side data is handled as follows: + * - During demuxing, it may be exported through + * @ref AVCodecParameters.coded_side_data "AVStream's codec parameters", which can + * then be passed as input to decoders through the + * @ref AVCodecContext.coded_side_data "decoder context's side data", for + * initialization. + * - For muxing, it can be fed through @ref AVCodecParameters.coded_side_data + * "AVStream's codec parameters", typically the output of encoders through + * the @ref AVCodecContext.coded_side_data "encoder context's side data", for + * initialization. + * + * Packet specific side data is handled as follows: + * - During demuxing, it may be exported through @ref AVPacket.side_data + * "AVPacket's side data", which can then be passed as input to decoders. + * - For muxing, it can be fed through @ref AVPacket.side_data "AVPacket's + * side data", typically the output of encoders. + * + * Different modules may accept or export different types of side data + * depending on media type and codec. Refer to @ref AVPacketSideDataType for a + * list of defined types and where they may be found or used. + */ +typedef struct AVPacketSideData { + uint8_t *data; + size_t size; + enum AVPacketSideDataType type; +} AVPacketSideData; + +/** + * Allocate a new packet side data. + * + * @param sd pointer to an array of side data to which the side data should + * be added. *sd may be NULL, in which case the array will be + * initialized. + * @param nb_sd pointer to an integer containing the number of entries in + * the array. The integer value will be increased by 1 on success. + * @param type side data type + * @param size desired side data size + * @param flags currently unused. Must be zero + * + * @return pointer to freshly allocated side data on success, or NULL otherwise. + */ +AVPacketSideData *av_packet_side_data_new(AVPacketSideData **psd, int *pnb_sd, + enum AVPacketSideDataType type, + size_t size, int flags); + +/** + * Wrap existing data as packet side data. + * + * @param sd pointer to an array of side data to which the side data should + * be added. *sd may be NULL, in which case the array will be + * initialized + * @param nb_sd pointer to an integer containing the number of entries in + * the array. The integer value will be increased by 1 on success. + * @param type side data type + * @param data a data array. It must be allocated with the av_malloc() family + * of functions. The ownership of the data is transferred to the + * side data array on success + * @param size size of the data array + * @param flags currently unused. Must be zero + * + * @return pointer to freshly allocated side data on success, or NULL otherwise + * On failure, the side data array is unchanged and the data remains + * owned by the caller. + */ +AVPacketSideData *av_packet_side_data_add(AVPacketSideData **sd, int *nb_sd, + enum AVPacketSideDataType type, + void *data, size_t size, int flags); + +/** + * Get side information from a side data array. + * + * @param sd the array from which the side data should be fetched + * @param nb_sd value containing the number of entries in the array. + * @param type desired side information type + * + * @return pointer to side data if present or NULL otherwise + */ +const AVPacketSideData *av_packet_side_data_get(const AVPacketSideData *sd, + int nb_sd, + enum AVPacketSideDataType type); + +/** + * Remove side data of the given type from a side data array. + * + * @param sd the array from which the side data should be removed + * @param nb_sd pointer to an integer containing the number of entries in + * the array. Will be reduced by the amount of entries removed + * upon return + * @param type side information type + */ +void av_packet_side_data_remove(AVPacketSideData *sd, int *nb_sd, + enum AVPacketSideDataType type); + +/** + * Convenience function to free all the side data stored in an array, and + * the array itself. + * + * @param sd pointer to array of side data to free. Will be set to NULL + * upon return. + * @param nb_sd pointer to an integer containing the number of entries in + * the array. Will be set to 0 upon return. + */ +void av_packet_side_data_free(AVPacketSideData **sd, int *nb_sd); + +struct AVFrameSideData; + +/** + * Add a new packet side data entry to an array based on existing frame + * side data, if a matching type exists for packet side data. + * + * @param flags Currently unused. Must be 0. + * @retval >= 0 Success + * @retval AVERROR(EINVAL) The frame side data type does not have a matching + * packet side data type. + * @retval AVERROR(ENOMEM) Failed to add a side data entry to the array, or + * similar. + */ +int av_packet_side_data_from_frame(AVPacketSideData **sd, int *nb_sd, + const struct AVFrameSideData *src, unsigned int flags); +/** + * Add a new frame side data entry to an array based on existing packet + * side data, if a matching type exists for frame side data. + * + * @param flags Some combination of AV_FRAME_SIDE_DATA_FLAG_* flags, + * or 0. + * @retval >= 0 Success + * @retval AVERROR(EINVAL) The packet side data type does not have a matching + * frame side data type. + * @retval AVERROR(ENOMEM) Failed to add a side data entry to the array, or + * similar. + */ +int av_packet_side_data_to_frame(struct AVFrameSideData ***sd, int *nb_sd, + const AVPacketSideData *src, unsigned int flags); + +const char *av_packet_side_data_name(enum AVPacketSideDataType type); + +/** + * @} + */ + +/** + * @defgroup lavc_packet AVPacket + * + * Types and functions for working with AVPacket. + * @{ + */ + +/** + * This structure stores compressed data. It is typically exported by demuxers + * and then passed as input to decoders, or received as output from encoders and + * then passed to muxers. + * + * For video, it should typically contain one compressed frame. For audio it may + * contain several compressed frames. Encoders are allowed to output empty + * packets, with no compressed data, containing only side data + * (e.g. to update some stream parameters at the end of encoding). + * + * The semantics of data ownership depends on the buf field. + * If it is set, the packet data is dynamically allocated and is + * valid indefinitely until a call to av_packet_unref() reduces the + * reference count to 0. + * + * If the buf field is not set av_packet_ref() would make a copy instead + * of increasing the reference count. + * + * The side data is always allocated with av_malloc(), copied by + * av_packet_ref() and freed by av_packet_unref(). + * + * sizeof(AVPacket) being a part of the public ABI is deprecated. once + * av_init_packet() is removed, new packets will only be able to be allocated + * with av_packet_alloc(), and new fields may be added to the end of the struct + * with a minor bump. + * + * @see av_packet_alloc + * @see av_packet_ref + * @see av_packet_unref + */ +typedef struct AVPacket { + /** + * A reference to the reference-counted buffer where the packet data is + * stored. + * May be NULL, then the packet data is not reference-counted. + */ + AVBufferRef *buf; + /** + * Presentation timestamp in AVStream->time_base units; the time at which + * the decompressed packet will be presented to the user. + * Can be AV_NOPTS_VALUE if it is not stored in the file. + * pts MUST be larger or equal to dts as presentation cannot happen before + * decompression, unless one wants to view hex dumps. Some formats misuse + * the terms dts and pts/cts to mean something different. Such timestamps + * must be converted to true pts/dts before they are stored in AVPacket. + */ + int64_t pts; + /** + * Decompression timestamp in AVStream->time_base units; the time at which + * the packet is decompressed. + * Can be AV_NOPTS_VALUE if it is not stored in the file. + */ + int64_t dts; + uint8_t *data; + int size; + int stream_index; + /** + * A combination of AV_PKT_FLAG values + */ + int flags; + /** + * Additional packet data that can be provided by the container. + * Packet can contain several types of side information. + */ + AVPacketSideData *side_data; + int side_data_elems; + + /** + * Duration of this packet in AVStream->time_base units, 0 if unknown. + * Equals next_pts - this_pts in presentation order. + */ + int64_t duration; + + int64_t pos; ///< byte position in stream, -1 if unknown + + /** + * for some private data of the user + */ + void *opaque; + + /** + * AVBufferRef for free use by the API user. FFmpeg will never check the + * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when + * the packet is unreferenced. av_packet_copy_props() calls create a new + * reference with av_buffer_ref() for the target packet's opaque_ref field. + * + * This is unrelated to the opaque field, although it serves a similar + * purpose. + */ + AVBufferRef *opaque_ref; + + /** + * Time base of the packet's timestamps. + * In the future, this field may be set on packets output by encoders or + * demuxers, but its value will be by default ignored on input to decoders + * or muxers. + */ + AVRational time_base; +} AVPacket; + +#if FF_API_INIT_PACKET +attribute_deprecated +typedef struct AVPacketList { + AVPacket pkt; + struct AVPacketList *next; +} AVPacketList; +#endif + +#define AV_PKT_FLAG_KEY 0x0001 ///< The packet contains a keyframe +#define AV_PKT_FLAG_CORRUPT 0x0002 ///< The packet content is corrupted +/** + * Flag is used to discard packets which are required to maintain valid + * decoder state but are not required for output and should be dropped + * after decoding. + **/ +#define AV_PKT_FLAG_DISCARD 0x0004 +/** + * The packet comes from a trusted source. + * + * Otherwise-unsafe constructs such as arbitrary pointers to data + * outside the packet may be followed. + */ +#define AV_PKT_FLAG_TRUSTED 0x0008 +/** + * Flag is used to indicate packets that contain frames that can + * be discarded by the decoder. I.e. Non-reference frames. + */ +#define AV_PKT_FLAG_DISPOSABLE 0x0010 + +enum AVSideDataParamChangeFlags { + AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE = 0x0004, + AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS = 0x0008, +}; + +/** + * Allocate an AVPacket and set its fields to default values. The resulting + * struct must be freed using av_packet_free(). + * + * @return An AVPacket filled with default values or NULL on failure. + * + * @note this only allocates the AVPacket itself, not the data buffers. Those + * must be allocated through other means such as av_new_packet. + * + * @see av_new_packet + */ +AVPacket *av_packet_alloc(void); + +/** + * Create a new packet that references the same data as src. + * + * This is a shortcut for av_packet_alloc()+av_packet_ref(). + * + * @return newly created AVPacket on success, NULL on error. + * + * @see av_packet_alloc + * @see av_packet_ref + */ +AVPacket *av_packet_clone(const AVPacket *src); + +/** + * Free the packet, if the packet is reference counted, it will be + * unreferenced first. + * + * @param pkt packet to be freed. The pointer will be set to NULL. + * @note passing NULL is a no-op. + */ +void av_packet_free(AVPacket **pkt); + +#if FF_API_INIT_PACKET +/** + * Initialize optional fields of a packet with default values. + * + * Note, this does not touch the data and size members, which have to be + * initialized separately. + * + * @param pkt packet + * + * @see av_packet_alloc + * @see av_packet_unref + * + * @deprecated This function is deprecated. Once it's removed, + sizeof(AVPacket) will not be a part of the ABI anymore. + */ +attribute_deprecated +void av_init_packet(AVPacket *pkt); +#endif + +/** + * Allocate the payload of a packet and initialize its fields with + * default values. + * + * @param pkt packet + * @param size wanted payload size + * @return 0 if OK, AVERROR_xxx otherwise + */ +int av_new_packet(AVPacket *pkt, int size); + +/** + * Reduce packet size, correctly zeroing padding + * + * @param pkt packet + * @param size new size + */ +void av_shrink_packet(AVPacket *pkt, int size); + +/** + * Increase packet size, correctly zeroing padding + * + * @param pkt packet + * @param grow_by number of bytes by which to increase the size of the packet + */ +int av_grow_packet(AVPacket *pkt, int grow_by); + +/** + * Initialize a reference-counted packet from av_malloc()ed data. + * + * @param pkt packet to be initialized. This function will set the data, size, + * and buf fields, all others are left untouched. + * @param data Data allocated by av_malloc() to be used as packet data. If this + * function returns successfully, the data is owned by the underlying AVBuffer. + * The caller may not access the data through other means. + * @param size size of data in bytes, without the padding. I.e. the full buffer + * size is assumed to be size + AV_INPUT_BUFFER_PADDING_SIZE. + * + * @return 0 on success, a negative AVERROR on error + */ +int av_packet_from_data(AVPacket *pkt, uint8_t *data, int size); + +/** + * Allocate new information of a packet. + * + * @param pkt packet + * @param type side information type + * @param size side information size + * @return pointer to fresh allocated data or NULL otherwise + */ +uint8_t* av_packet_new_side_data(AVPacket *pkt, enum AVPacketSideDataType type, + size_t size); + +/** + * Wrap an existing array as a packet side data. + * + * @param pkt packet + * @param type side information type + * @param data the side data array. It must be allocated with the av_malloc() + * family of functions. The ownership of the data is transferred to + * pkt. + * @param size side information size + * @return a non-negative number on success, a negative AVERROR code on + * failure. On failure, the packet is unchanged and the data remains + * owned by the caller. + */ +int av_packet_add_side_data(AVPacket *pkt, enum AVPacketSideDataType type, + uint8_t *data, size_t size); + +/** + * Shrink the already allocated side data buffer + * + * @param pkt packet + * @param type side information type + * @param size new side information size + * @return 0 on success, < 0 on failure + */ +int av_packet_shrink_side_data(AVPacket *pkt, enum AVPacketSideDataType type, + size_t size); + +/** + * Get side information from packet. + * + * @param pkt packet + * @param type desired side information type + * @param size If supplied, *size will be set to the size of the side data + * or to zero if the desired side data is not present. + * @return pointer to data if present or NULL otherwise + */ +uint8_t* av_packet_get_side_data(const AVPacket *pkt, enum AVPacketSideDataType type, + size_t *size); + +/** + * Pack a dictionary for use in side_data. + * + * @param dict The dictionary to pack. + * @param size pointer to store the size of the returned data + * @return pointer to data if successful, NULL otherwise + */ +uint8_t *av_packet_pack_dictionary(AVDictionary *dict, size_t *size); +/** + * Unpack a dictionary from side_data. + * + * @param data data from side_data + * @param size size of the data + * @param dict the metadata storage dictionary + * @return 0 on success, < 0 on failure + */ +int av_packet_unpack_dictionary(const uint8_t *data, size_t size, + AVDictionary **dict); + +/** + * Convenience function to free all the side data stored. + * All the other fields stay untouched. + * + * @param pkt packet + */ +void av_packet_free_side_data(AVPacket *pkt); + +/** + * Setup a new reference to the data described by a given packet + * + * If src is reference-counted, setup dst as a new reference to the + * buffer in src. Otherwise allocate a new buffer in dst and copy the + * data from src into it. + * + * All the other fields are copied from src. + * + * @see av_packet_unref + * + * @param dst Destination packet. Will be completely overwritten. + * @param src Source packet + * + * @return 0 on success, a negative AVERROR on error. On error, dst + * will be blank (as if returned by av_packet_alloc()). + */ +int av_packet_ref(AVPacket *dst, const AVPacket *src); + +/** + * Wipe the packet. + * + * Unreference the buffer referenced by the packet and reset the + * remaining packet fields to their default values. + * + * @param pkt The packet to be unreferenced. + */ +void av_packet_unref(AVPacket *pkt); + +/** + * Move every field in src to dst and reset src. + * + * @see av_packet_unref + * + * @param src Source packet, will be reset + * @param dst Destination packet + */ +void av_packet_move_ref(AVPacket *dst, AVPacket *src); + +/** + * Copy only "properties" fields from src to dst. + * + * Properties for the purpose of this function are all the fields + * beside those related to the packet data (buf, data, size) + * + * @param dst Destination packet + * @param src Source packet + * + * @return 0 on success AVERROR on failure. + */ +int av_packet_copy_props(AVPacket *dst, const AVPacket *src); + +/** + * Ensure the data described by a given packet is reference counted. + * + * @note This function does not ensure that the reference will be writable. + * Use av_packet_make_writable instead for that purpose. + * + * @see av_packet_ref + * @see av_packet_make_writable + * + * @param pkt packet whose data should be made reference counted. + * + * @return 0 on success, a negative AVERROR on error. On failure, the + * packet is unchanged. + */ +int av_packet_make_refcounted(AVPacket *pkt); + +/** + * Create a writable reference for the data described by a given packet, + * avoiding data copy if possible. + * + * @param pkt Packet whose data should be made writable. + * + * @return 0 on success, a negative AVERROR on failure. On failure, the + * packet is unchanged. + */ +int av_packet_make_writable(AVPacket *pkt); + +/** + * Convert valid timing fields (timestamps / durations) in a packet from one + * timebase to another. Timestamps with unknown values (AV_NOPTS_VALUE) will be + * ignored. + * + * @param pkt packet on which the conversion will be performed + * @param tb_src source timebase, in which the timing fields in pkt are + * expressed + * @param tb_dst destination timebase, to which the timing fields will be + * converted + */ +void av_packet_rescale_ts(AVPacket *pkt, AVRational tb_src, AVRational tb_dst); + +/** + * Allocate an AVContainerFifo instance for AVPacket. + * + * @param flags currently unused + */ +struct AVContainerFifo *av_container_fifo_alloc_avpacket(unsigned flags); + +/** + * @} + */ + +#endif // AVCODEC_PACKET_H diff --git a/ffmpeg-n8.1/include/libavcodec/qsv.h b/ffmpeg-n8.1/include/libavcodec/qsv.h new file mode 100644 index 00000000..c156b08d --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/qsv.h @@ -0,0 +1,109 @@ +/* + * Intel MediaSDK QSV public API + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_QSV_H +#define AVCODEC_QSV_H + +#include + +#include "libavutil/buffer.h" + +/** + * This struct is used for communicating QSV parameters between libavcodec and + * the caller. It is managed by the caller and must be assigned to + * AVCodecContext.hwaccel_context. + * - decoding: hwaccel_context must be set on return from the get_format() + * callback + * - encoding: hwaccel_context must be set before avcodec_open2() + */ +typedef struct AVQSVContext { + /** + * If non-NULL, the session to use for encoding or decoding. + * Otherwise, libavcodec will try to create an internal session. + */ + mfxSession session; + + /** + * The IO pattern to use. + */ + int iopattern; + + /** + * Extra buffers to pass to encoder or decoder initialization. + */ + mfxExtBuffer **ext_buffers; + int nb_ext_buffers; + + /** + * Encoding only. If this field is set to non-zero by the caller, libavcodec + * will create an mfxExtOpaqueSurfaceAlloc extended buffer and pass it to + * the encoder initialization. This only makes sense if iopattern is also + * set to MFX_IOPATTERN_IN_OPAQUE_MEMORY. + * + * The number of allocated opaque surfaces will be the sum of the number + * required by the encoder and the user-provided value nb_opaque_surfaces. + * The array of the opaque surfaces will be exported to the caller through + * the opaque_surfaces field. + * + * The caller must set this field to zero for oneVPL (MFX_VERSION >= 2.0) + */ + int opaque_alloc; + + /** + * Encoding only, and only if opaque_alloc is set to non-zero. Before + * calling avcodec_open2(), the caller should set this field to the number + * of extra opaque surfaces to allocate beyond what is required by the + * encoder. + * + * On return from avcodec_open2(), this field will be set by libavcodec to + * the total number of allocated opaque surfaces. + */ + int nb_opaque_surfaces; + + /** + * Encoding only, and only if opaque_alloc is set to non-zero. On return + * from avcodec_open2(), this field will be used by libavcodec to export the + * array of the allocated opaque surfaces to the caller, so they can be + * passed to other parts of the pipeline. + * + * The buffer reference exported here is owned and managed by libavcodec, + * the callers should make their own reference with av_buffer_ref() and free + * it with av_buffer_unref() when it is no longer needed. + * + * The buffer data is an nb_opaque_surfaces-sized array of mfxFrameSurface1. + */ + AVBufferRef *opaque_surfaces; + + /** + * Encoding only, and only if opaque_alloc is set to non-zero. On return + * from avcodec_open2(), this field will be set to the surface type used in + * the opaque allocation request. + */ + int opaque_alloc_type; +} AVQSVContext; + +/** + * Allocate a new context. + * + * It must be freed by the caller with av_free(). + */ +AVQSVContext *av_qsv_alloc_context(void); + +#endif /* AVCODEC_QSV_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/smpte_436m.h b/ffmpeg-n8.1/include/libavcodec/smpte_436m.h new file mode 100644 index 00000000..9c0e2a5a --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/smpte_436m.h @@ -0,0 +1,254 @@ +/* + * MXF SMPTE-436M VBI/ANC parsing functions + * Copyright (c) 2025 Jacob Lifshay + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_SMPTE_436M_H +#define AVCODEC_SMPTE_436M_H + +#include + +/** + * Iterator over the ANC packets in a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data + */ +typedef struct AVSmpte436mAncIterator { + uint16_t anc_packets_left; + int size_left; + const uint8_t *data_left; +} AVSmpte436mAncIterator; + +/** + * Wrapping Type from Table 7 (page 13) of: + * https://pub.smpte.org/latest/st436/s436m-2006.pdf + */ +typedef enum AVSmpte436mWrappingType +{ + AV_SMPTE_436M_WRAPPING_TYPE_VANC_FRAME = 1, + AV_SMPTE_436M_WRAPPING_TYPE_VANC_FIELD_1 = 2, + AV_SMPTE_436M_WRAPPING_TYPE_VANC_FIELD_2 = 3, + AV_SMPTE_436M_WRAPPING_TYPE_VANC_PROGRESSIVE_FRAME = 4, + AV_SMPTE_436M_WRAPPING_TYPE_HANC_FRAME = 0x11, + AV_SMPTE_436M_WRAPPING_TYPE_HANC_FIELD_1 = 0x12, + AV_SMPTE_436M_WRAPPING_TYPE_HANC_FIELD_2 = 0x13, + AV_SMPTE_436M_WRAPPING_TYPE_HANC_PROGRESSIVE_FRAME = 0x14, + /** not a real wrapping type, just here to guarantee the enum is big enough */ + AV_SMPTE_436M_WRAPPING_TYPE_MAX = 0xFF, +} AVSmpte436mWrappingType; + +/** + * Payload Sample Coding from Table 4 (page 10) and Table 7 (page 13) of: + * https://pub.smpte.org/latest/st436/s436m-2006.pdf + */ +typedef enum AVSmpte436mPayloadSampleCoding +{ + /** only used for VBI */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_1BIT_LUMA = 1, + /** only used for VBI */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_1BIT_COLOR_DIFF = 2, + /** only used for VBI */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_1BIT_LUMA_AND_COLOR_DIFF = 3, + /** used for VBI and ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_8BIT_LUMA = 4, + /** used for VBI and ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_8BIT_COLOR_DIFF = 5, + /** used for VBI and ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_8BIT_LUMA_AND_COLOR_DIFF = 6, + /** used for VBI and ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_10BIT_LUMA = 7, + /** used for VBI and ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_10BIT_COLOR_DIFF = 8, + /** used for VBI and ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_10BIT_LUMA_AND_COLOR_DIFF = 9, + /** only used for ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_8BIT_LUMA_WITH_PARITY_ERROR = 10, + /** only used for ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_8BIT_COLOR_DIFF_WITH_PARITY_ERROR = 11, + /** only used for ANC */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_8BIT_LUMA_AND_COLOR_DIFF_WITH_PARITY_ERROR = 12, + /** not a real sample coding, just here to guarantee the enum is big enough */ + AV_SMPTE_436M_PAYLOAD_SAMPLE_CODING_MAX = 0xFF, +} AVSmpte436mPayloadSampleCoding; + +/** the payload capacity of AVSmpte291mAnc8bit (and of AVSmpte291mAnc10bit when that gets added) */ +#define AV_SMPTE_291M_ANC_PAYLOAD_CAPACITY 0xFF + +/** + * An ANC packet with an 8-bit payload. + * This can be decoded from AVSmpte436mCodedAnc::payload. + * + * Note: Some ANC packets need a 10-bit payload, if stored in this struct, + * the most-significant 2 bits of each sample are discarded. + */ +typedef struct AVSmpte291mAnc8bit { + uint8_t did; + uint8_t sdid_or_dbn; + uint8_t data_count; + uint8_t payload[AV_SMPTE_291M_ANC_PAYLOAD_CAPACITY]; + uint8_t checksum; +} AVSmpte291mAnc8bit; + +/** max number of samples that can be stored in the payload of AVSmpte436mCodedAnc */ +#define AV_SMPTE_436M_CODED_ANC_SAMPLE_CAPACITY \ + (AV_SMPTE_291M_ANC_PAYLOAD_CAPACITY + 4) /* 4 for did, sdid_or_dbn, data_count, and checksum */ +/** max number of bytes that can be stored in the payload of AVSmpte436mCodedAnc */ +#define AV_SMPTE_436M_CODED_ANC_PAYLOAD_CAPACITY (((AV_SMPTE_436M_CODED_ANC_SAMPLE_CAPACITY + 2) / 3) * 4) + +/** + * An encoded ANC packet within a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data. + * The repeated section of Table 7 (page 13) of: + * https://pub.smpte.org/latest/st436/s436m-2006.pdf + */ +typedef struct AVSmpte436mCodedAnc { + uint16_t line_number; + AVSmpte436mWrappingType wrapping_type; + AVSmpte436mPayloadSampleCoding payload_sample_coding; + uint16_t payload_sample_count; + uint32_t payload_array_length; + /** the payload, has size payload_array_length. + * can be decoded into AVSmpte291mAnc8bit + */ + uint8_t payload[AV_SMPTE_436M_CODED_ANC_PAYLOAD_CAPACITY]; +} AVSmpte436mCodedAnc; + +/** + * Validate a AVSmpte436mCodedAnc structure. Doesn't check if the payload is valid. + * @param[in] anc ANC packet to validate + * @return 0 on success, AVERROR codes otherwise. + */ +int av_smpte_436m_coded_anc_validate(const AVSmpte436mCodedAnc *anc); + +/** + * Encode ANC packets into a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data. + * @param[in] anc_packet_count number of ANC packets to encode + * @param[in] anc_packets the ANC packets to encode + * @param[in] size the size of out. ignored if out is NULL. + * @param[out] out Output bytes. Doesn't write anything if out is NULL. + * @return the number of bytes written on success, AVERROR codes otherwise. + * If out is NULL, returns the number of bytes it would have written. + */ +int av_smpte_436m_anc_encode(uint8_t *out, int size, int anc_packet_count, const AVSmpte436mCodedAnc *anc_packets); + +struct AVPacket; + +/** + * Append more ANC packets to a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data. + * @param[in] anc_packet_count number of ANC packets to encode + * @param[in] anc_packets the ANC packets to encode + * @param pkt the AVPacket to append to. + * it must either be size 0 or contain valid SMPTE_436M_ANC data. + * @return 0 on success, AVERROR codes otherwise. + */ +int av_smpte_436m_anc_append(struct AVPacket *pkt, int anc_packet_count, const AVSmpte436mCodedAnc *anc_packets); + +/** + * Set up iteration over the ANC packets in a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data. + * @param[in] buf Pointer to the data from a AV_CODEC_ID_SMPTE_436M_ANC AVPacket. + * @param[in] buf_size Size of the data from a AV_CODEC_ID_SMPTE_436M_ANC AVPacket. + * @param[out] iter Pointer to the iterator. + * @return 0 on success, AVERROR codes otherwise. + */ +int av_smpte_436m_anc_iter_init(AVSmpte436mAncIterator *iter, const uint8_t *buf, int buf_size); + +/** + * Get the next ANC packet from the iterator, advancing the iterator. + * @param[in,out] iter Pointer to the iterator. + * @param[out] anc The returned ANC packet. + * @return 0 on success, AVERROR_EOF when the iterator has reached the end, AVERROR codes otherwise. + */ +int av_smpte_436m_anc_iter_next(AVSmpte436mAncIterator *iter, AVSmpte436mCodedAnc *anc); + +/** + * Get the minimum number of bytes needed to store a AVSmpte436mCodedAnc payload. + * @param sample_coding the payload sample coding + * @param sample_count the number of samples stored in the payload + * @return returns the minimum number of bytes needed, on error returns < 0. + * always <= SMPTE_436M_CODED_ANC_PAYLOAD_CAPACITY + */ +int av_smpte_436m_coded_anc_payload_size(AVSmpte436mPayloadSampleCoding sample_coding, uint16_t sample_count); + +/** + * Decode a AVSmpte436mCodedAnc payload into AVSmpte291mAnc8bit + * @param[in] sample_coding the payload sample coding + * @param[in] sample_count the number of samples stored in the payload + * @param[in] payload the bytes storing the payload, + * the needed size can be obtained from + avpriv_smpte_436m_coded_anc_payload_size + * @param[in] log_ctx context pointer for av_log + * @param[out] out The decoded ANC packet. + * @return returns 0 on success, otherwise < 0. + */ +int av_smpte_291m_anc_8bit_decode(AVSmpte291mAnc8bit *out, + AVSmpte436mPayloadSampleCoding sample_coding, + uint16_t sample_count, + const uint8_t *payload, + void *log_ctx); + +/** + * Fill in the correct checksum for a AVSmpte291mAnc8bit + * @param[in,out] anc The ANC packet. + */ +void av_smpte_291m_anc_8bit_fill_checksum(AVSmpte291mAnc8bit *anc); + +/** + * Compute the sample count needed to encode a AVSmpte291mAnc8bit into a AVSmpte436mCodedAnc payload + * @param[in] anc The ANC packet. + * @param[in] sample_coding The sample coding. + * @param[in] log_ctx context pointer for av_log + * @return returns the sample count on success, otherwise < 0. + */ +int av_smpte_291m_anc_8bit_get_sample_count(const AVSmpte291mAnc8bit *anc, + AVSmpte436mPayloadSampleCoding sample_coding, + void *log_ctx); + +/** + * Encode a AVSmpte291mAnc8bit into a AVSmpte436mCodedAnc + * @param[in] line_number the line number the ANC packet is on + * @param[in] wrapping_type the wrapping type + * @param[in] sample_coding the payload sample coding + * @param[in] payload the ANC packet to encode. + * @param[in] log_ctx context pointer for av_log + * @param[out] out The encoded ANC packet. + * @return returns 0 on success, otherwise < 0. + */ +int av_smpte_291m_anc_8bit_encode(AVSmpte436mCodedAnc *out, + uint16_t line_number, + AVSmpte436mWrappingType wrapping_type, + AVSmpte436mPayloadSampleCoding sample_coding, + const AVSmpte291mAnc8bit *payload, + void *log_ctx); + +/** AVSmpte291mAnc8bit::did when carrying CTA-708 data (for AV_CODEC_ID_EIA_608) */ +#define AV_SMPTE_291M_ANC_DID_CTA_708 0x61 + +/** AVSmpte291mAnc8bit::sdid_or_dbn when carrying CTA-708 data (for AV_CODEC_ID_EIA_608) */ +#define AV_SMPTE_291M_ANC_SDID_CTA_708 0x1 + +/** + * Try to decode an ANC packet into EIA-608/CTA-708 data (AV_CODEC_ID_EIA_608). This + * @param[in] anc The ANC packet. + * @param[in] log_ctx Context pointer for av_log + * @param[out] cc_data the buffer to store the extracted EIA-608/CTA-708 data, + * you can pass NULL to not store the data. + * the required size is 3 * cc_count bytes. + * SMPTE_291M_ANC_PAYLOAD_CAPACITY is always enough size. + * @return returns cc_count (>= 0) on success, AVERROR(EAGAIN) if it wasn't a CTA-708 ANC packet, < 0 on error. + */ +int av_smpte_291m_anc_8bit_extract_cta_708(const AVSmpte291mAnc8bit *anc, uint8_t *cc_data, void *log_ctx); + +#endif /* AVCODEC_SMPTE_436M_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/vdpau.h b/ffmpeg-n8.1/include/libavcodec/vdpau.h new file mode 100644 index 00000000..da77c5da --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/vdpau.h @@ -0,0 +1,138 @@ +/* + * The Video Decode and Presentation API for UNIX (VDPAU) is used for + * hardware-accelerated decoding of MPEG-1/2, H.264 and VC-1. + * + * Copyright (C) 2008 NVIDIA + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_VDPAU_H +#define AVCODEC_VDPAU_H + +/** + * @file + * @ingroup lavc_codec_hwaccel_vdpau + * Public libavcodec VDPAU header. + */ + + +/** + * @defgroup lavc_codec_hwaccel_vdpau VDPAU Decoder and Renderer + * @ingroup lavc_codec_hwaccel + * + * VDPAU hardware acceleration has two modules + * - VDPAU decoding + * - VDPAU presentation + * + * The VDPAU decoding module parses all headers using FFmpeg + * parsing mechanisms and uses VDPAU for the actual decoding. + * + * As per the current implementation, the actual decoding + * and rendering (API calls) are done as part of the VDPAU + * presentation (vo_vdpau.c) module. + * + * @{ + */ + +#include + +#include "libavutil/avconfig.h" +#include "libavutil/attributes.h" + +#include "avcodec.h" + +struct AVCodecContext; +struct AVFrame; + +typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *, + const VdpPictureInfo *, uint32_t, + const VdpBitstreamBuffer *); + +/** + * This structure is used to share data between the libavcodec library and + * the client video application. + * This structure will be allocated and stored in AVCodecContext.hwaccel_context + * by av_vdpau_bind_context(). Members can be set by the user once + * during initialization or through each AVCodecContext.get_buffer() + * function call. In any case, they must be valid prior to calling + * decoding functions. + * + * The size of this structure is not a part of the public ABI and must not + * be used outside of libavcodec. + */ +typedef struct AVVDPAUContext { + /** + * VDPAU decoder handle + * + * Set by user. + */ + VdpDecoder decoder; + + /** + * VDPAU decoder render callback + * + * Set by the user. + */ + VdpDecoderRender *render; + + AVVDPAU_Render2 render2; +} AVVDPAUContext; + +/** + * Associate a VDPAU device with a codec context for hardware acceleration. + * This function is meant to be called from the get_format() codec callback, + * or earlier. It can also be called after avcodec_flush_buffers() to change + * the underlying VDPAU device mid-stream (e.g. to recover from non-transparent + * display preemption). + * + * @note get_format() must return AV_PIX_FMT_VDPAU if this function completes + * successfully. + * + * @param avctx decoding context whose get_format() callback is invoked + * @param device VDPAU device handle to use for hardware acceleration + * @param get_proc_address VDPAU device driver + * @param flags zero of more OR'd AV_HWACCEL_FLAG_* flags + * + * @return 0 on success, an AVERROR code on failure. + */ +int av_vdpau_bind_context(AVCodecContext *avctx, VdpDevice device, + VdpGetProcAddress *get_proc_address, unsigned flags); + +/** + * Gets the parameters to create an adequate VDPAU video surface for the codec + * context using VDPAU hardware decoding acceleration. + * + * @note Behavior is undefined if the context was not successfully bound to a + * VDPAU device using av_vdpau_bind_context(). + * + * @param avctx the codec context being used for decoding the stream + * @param type storage space for the VDPAU video surface chroma type + * (or NULL to ignore) + * @param width storage space for the VDPAU video surface pixel width + * (or NULL to ignore) + * @param height storage space for the VDPAU video surface pixel height + * (or NULL to ignore) + * + * @return 0 on success, a negative AVERROR code on failure. + */ +int av_vdpau_get_surface_parameters(AVCodecContext *avctx, VdpChromaType *type, + uint32_t *width, uint32_t *height); + +/** @} */ + +#endif /* AVCODEC_VDPAU_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/version.h b/ffmpeg-n8.1/include/libavcodec/version.h new file mode 100644 index 00000000..87b7284a --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/version.h @@ -0,0 +1,45 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_VERSION_H +#define AVCODEC_VERSION_H + +/** + * @file + * @ingroup libavc + * Libavcodec version macros. + */ + +#include "libavutil/version.h" + +#include "version_major.h" + +#define LIBAVCODEC_VERSION_MINOR 28 +#define LIBAVCODEC_VERSION_MICRO 100 + +#define LIBAVCODEC_VERSION_INT AV_VERSION_INT(LIBAVCODEC_VERSION_MAJOR, \ + LIBAVCODEC_VERSION_MINOR, \ + LIBAVCODEC_VERSION_MICRO) +#define LIBAVCODEC_VERSION AV_VERSION(LIBAVCODEC_VERSION_MAJOR, \ + LIBAVCODEC_VERSION_MINOR, \ + LIBAVCODEC_VERSION_MICRO) +#define LIBAVCODEC_BUILD LIBAVCODEC_VERSION_INT + +#define LIBAVCODEC_IDENT "Lavc" AV_STRINGIFY(LIBAVCODEC_VERSION) + +#endif /* AVCODEC_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/version_major.h b/ffmpeg-n8.1/include/libavcodec/version_major.h new file mode 100644 index 00000000..6c652374 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/version_major.h @@ -0,0 +1,59 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_VERSION_MAJOR_H +#define AVCODEC_VERSION_MAJOR_H + +/** + * @file + * @ingroup libavc + * Libavcodec version macros. + */ + +#define LIBAVCODEC_VERSION_MAJOR 62 + +/** + * FF_API_* defines may be placed below to indicate public API that will be + * dropped at a future version bump. The defines themselves are not part of + * the public API and may change, break or disappear at any time. + * + * @note, when bumping the major version it is recommended to manually + * disable each FF_API_* in its own commit instead of disabling them all + * at once through the bump. This improves the git bisect-ability of the change. + */ + +#define FF_API_INIT_PACKET (LIBAVCODEC_VERSION_MAJOR < 63) + +#define FF_API_V408_CODECID (LIBAVCODEC_VERSION_MAJOR < 63) +#define FF_API_CODEC_PROPS (LIBAVCODEC_VERSION_MAJOR < 63) +#define FF_API_EXR_GAMMA (LIBAVCODEC_VERSION_MAJOR < 63) +#define FF_API_INTRA_DC_PRECISION (LIBAVCODEC_VERSION_MAJOR < 63) + +#define FF_API_NVDEC_OLD_PIX_FMTS (LIBAVCODEC_VERSION_MAJOR < 63) + +#define FF_API_PARSER_PRIVATE (LIBAVCODEC_VERSION_MAJOR < 63) +#define FF_API_PARSER_CODECID (LIBAVCODEC_VERSION_MAJOR < 63) + +// reminder to remove the OMX encoder on next major bump +#define FF_CODEC_OMX (LIBAVCODEC_VERSION_MAJOR < 63) +// reminder to remove Sonic Lossy/Lossless encoders on next major bump +#define FF_CODEC_SONIC_ENC (LIBAVCODEC_VERSION_MAJOR < 63) +// reminder to remove Sonic decoder on next-next major bump +#define FF_CODEC_SONIC_DEC (LIBAVCODEC_VERSION_MAJOR < 63) + +#endif /* AVCODEC_VERSION_MAJOR_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/videotoolbox.h b/ffmpeg-n8.1/include/libavcodec/videotoolbox.h new file mode 100644 index 00000000..d68d76e4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/videotoolbox.h @@ -0,0 +1,85 @@ +/* + * Videotoolbox hardware acceleration + * + * copyright (c) 2012 Sebastien Zwickert + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_VIDEOTOOLBOX_H +#define AVCODEC_VIDEOTOOLBOX_H + +/** + * @file + * @ingroup lavc_codec_hwaccel_videotoolbox + * Public libavcodec Videotoolbox header. + */ + +/** + * @defgroup lavc_codec_hwaccel_videotoolbox VideoToolbox Decoder + * @ingroup lavc_codec_hwaccel + * + * Hardware accelerated decoding using VideoToolbox on Apple Platforms + * + * @{ + */ + +#include + +#define Picture QuickdrawPicture +#include +#undef Picture + +#include "libavcodec/avcodec.h" + +#include "libavutil/attributes.h" + +/** + * This struct holds all the information that needs to be passed + * between the caller and libavcodec for initializing Videotoolbox decoding. + * Its size is not a part of the public ABI, it must be allocated with + * av_videotoolbox_alloc_context() and freed with av_free(). + */ +typedef struct AVVideotoolboxContext { + /** + * Videotoolbox decompression session object. + */ + VTDecompressionSessionRef session; + + /** + * CVPixelBuffer Format Type that Videotoolbox will use for decoded frames. + * set by the caller. If this is set to 0, then no specific format is + * requested from the decoder, and its native format is output. + */ + OSType cv_pix_fmt_type; + + /** + * CoreMedia Format Description that Videotoolbox will use to create the decompression session. + */ + CMVideoFormatDescriptionRef cm_fmt_desc; + + /** + * CoreMedia codec type that Videotoolbox will use to create the decompression session. + */ + int cm_codec_type; +} AVVideotoolboxContext; + +/** + * @} + */ + +#endif /* AVCODEC_VIDEOTOOLBOX_H */ diff --git a/ffmpeg-n8.1/include/libavcodec/vorbis_parser.h b/ffmpeg-n8.1/include/libavcodec/vorbis_parser.h new file mode 100644 index 00000000..789932ac --- /dev/null +++ b/ffmpeg-n8.1/include/libavcodec/vorbis_parser.h @@ -0,0 +1,74 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * A public API for Vorbis parsing + * + * Determines the duration for each packet. + */ + +#ifndef AVCODEC_VORBIS_PARSER_H +#define AVCODEC_VORBIS_PARSER_H + +#include + +typedef struct AVVorbisParseContext AVVorbisParseContext; + +/** + * Allocate and initialize the Vorbis parser using headers in the extradata. + */ +AVVorbisParseContext *av_vorbis_parse_init(const uint8_t *extradata, + int extradata_size); + +/** + * Free the parser and everything associated with it. + */ +void av_vorbis_parse_free(AVVorbisParseContext **s); + +#define VORBIS_FLAG_HEADER 0x00000001 +#define VORBIS_FLAG_COMMENT 0x00000002 +#define VORBIS_FLAG_SETUP 0x00000004 + +/** + * Get the duration for a Vorbis packet. + * + * If @p flags is @c NULL, + * special frames are considered invalid. + * + * @param s Vorbis parser context + * @param buf buffer containing a Vorbis frame + * @param buf_size size of the buffer + * @param flags flags for special frames + */ +int av_vorbis_parse_frame_flags(AVVorbisParseContext *s, const uint8_t *buf, + int buf_size, int *flags); + +/** + * Get the duration for a Vorbis packet. + * + * @param s Vorbis parser context + * @param buf buffer containing a Vorbis frame + * @param buf_size size of the buffer + */ +int av_vorbis_parse_frame(AVVorbisParseContext *s, const uint8_t *buf, + int buf_size); + +void av_vorbis_parse_reset(AVVorbisParseContext *s); + +#endif /* AVCODEC_VORBIS_PARSER_H */ diff --git a/ffmpeg-n8.1/include/libavdevice/avdevice.h b/ffmpeg-n8.1/include/libavdevice/avdevice.h new file mode 100644 index 00000000..10ffaf4c --- /dev/null +++ b/ffmpeg-n8.1/include/libavdevice/avdevice.h @@ -0,0 +1,397 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVDEVICE_AVDEVICE_H +#define AVDEVICE_AVDEVICE_H + +#include "version_major.h" +#ifndef HAVE_AV_CONFIG_H +/* When included as part of the ffmpeg build, only include the major version + * to avoid unnecessary rebuilds. When included externally, keep including + * the full version information. */ +#include "version.h" +#endif + +/** + * @file + * @ingroup lavd + * Main libavdevice API header + */ + +/** + * @defgroup lavd libavdevice + * Special devices muxing/demuxing library. + * + * Libavdevice is a complementary library to @ref libavf "libavformat". It + * provides various "special" platform-specific muxers and demuxers, e.g. for + * grabbing devices, audio capture and playback etc. As a consequence, the + * (de)muxers in libavdevice are of the AVFMT_NOFILE type (they use their own + * I/O functions). The filename passed to avformat_open_input() often does not + * refer to an actually existing file, but has some special device-specific + * meaning - e.g. for xcbgrab it is the display name. + * + * To use libavdevice, simply call avdevice_register_all() to register all + * compiled muxers and demuxers. They all use standard libavformat API. + * + * @{ + */ + +#include "libavutil/log.h" +#include "libavutil/opt.h" +#include "libavutil/dict.h" +#include "libavformat/avformat.h" + +/** + * Return the LIBAVDEVICE_VERSION_INT constant. + */ +unsigned avdevice_version(void); + +/** + * Return the libavdevice build-time configuration. + */ +const char *avdevice_configuration(void); + +/** + * Return the libavdevice license. + */ +const char *avdevice_license(void); + +/** + * Initialize libavdevice and register all the input and output devices. + */ +void avdevice_register_all(void); + +/** + * Audio input devices iterator. + * + * If d is NULL, returns the first registered input audio/video device, + * if d is non-NULL, returns the next registered input audio/video device after d + * or NULL if d is the last one. + */ +const AVInputFormat *av_input_audio_device_next(const AVInputFormat *d); + +/** + * Video input devices iterator. + * + * If d is NULL, returns the first registered input audio/video device, + * if d is non-NULL, returns the next registered input audio/video device after d + * or NULL if d is the last one. + */ +const AVInputFormat *av_input_video_device_next(const AVInputFormat *d); + +/** + * Audio output devices iterator. + * + * If d is NULL, returns the first registered output audio/video device, + * if d is non-NULL, returns the next registered output audio/video device after d + * or NULL if d is the last one. + */ +const AVOutputFormat *av_output_audio_device_next(const AVOutputFormat *d); + +/** + * Video output devices iterator. + * + * If d is NULL, returns the first registered output audio/video device, + * if d is non-NULL, returns the next registered output audio/video device after d + * or NULL if d is the last one. + */ +const AVOutputFormat *av_output_video_device_next(const AVOutputFormat *d); + +typedef struct AVDeviceRect { + int x; /**< x coordinate of top left corner */ + int y; /**< y coordinate of top left corner */ + int width; /**< width */ + int height; /**< height */ +} AVDeviceRect; + +/** + * Message types used by avdevice_app_to_dev_control_message(). + */ +enum AVAppToDevMessageType { + /** + * Dummy message. + */ + AV_APP_TO_DEV_NONE = MKBETAG('N','O','N','E'), + + /** + * Window size change message. + * + * Message is sent to the device every time the application changes the size + * of the window device renders to. + * Message should also be sent right after window is created. + * + * data: AVDeviceRect: new window size. + */ + AV_APP_TO_DEV_WINDOW_SIZE = MKBETAG('G','E','O','M'), + + /** + * Repaint request message. + * + * Message is sent to the device when window has to be repainted. + * + * data: AVDeviceRect: area required to be repainted. + * NULL: whole area is required to be repainted. + */ + AV_APP_TO_DEV_WINDOW_REPAINT = MKBETAG('R','E','P','A'), + + /** + * Request pause/play. + * + * Application requests pause/unpause playback. + * Mostly usable with devices that have internal buffer. + * By default devices are not paused. + * + * data: NULL + */ + AV_APP_TO_DEV_PAUSE = MKBETAG('P', 'A', 'U', ' '), + AV_APP_TO_DEV_PLAY = MKBETAG('P', 'L', 'A', 'Y'), + AV_APP_TO_DEV_TOGGLE_PAUSE = MKBETAG('P', 'A', 'U', 'T'), + + /** + * Volume control message. + * + * Set volume level. It may be device-dependent if volume + * is changed per stream or system wide. Per stream volume + * change is expected when possible. + * + * data: double: new volume with range of 0.0 - 1.0. + */ + AV_APP_TO_DEV_SET_VOLUME = MKBETAG('S', 'V', 'O', 'L'), + + /** + * Mute control messages. + * + * Change mute state. It may be device-dependent if mute status + * is changed per stream or system wide. Per stream mute status + * change is expected when possible. + * + * data: NULL. + */ + AV_APP_TO_DEV_MUTE = MKBETAG(' ', 'M', 'U', 'T'), + AV_APP_TO_DEV_UNMUTE = MKBETAG('U', 'M', 'U', 'T'), + AV_APP_TO_DEV_TOGGLE_MUTE = MKBETAG('T', 'M', 'U', 'T'), + + /** + * Get volume/mute messages. + * + * Force the device to send AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED or + * AV_DEV_TO_APP_MUTE_STATE_CHANGED command respectively. + * + * data: NULL. + */ + AV_APP_TO_DEV_GET_VOLUME = MKBETAG('G', 'V', 'O', 'L'), + AV_APP_TO_DEV_GET_MUTE = MKBETAG('G', 'M', 'U', 'T'), +}; + +/** + * Message types used by avdevice_dev_to_app_control_message(). + */ +enum AVDevToAppMessageType { + /** + * Dummy message. + */ + AV_DEV_TO_APP_NONE = MKBETAG('N','O','N','E'), + + /** + * Create window buffer message. + * + * Device requests to create a window buffer. Exact meaning is device- + * and application-dependent. Message is sent before rendering first + * frame and all one-shot initializations should be done here. + * Application is allowed to ignore preferred window buffer size. + * + * @note: Application is obligated to inform about window buffer size + * with AV_APP_TO_DEV_WINDOW_SIZE message. + * + * data: AVDeviceRect: preferred size of the window buffer. + * NULL: no preferred size of the window buffer. + */ + AV_DEV_TO_APP_CREATE_WINDOW_BUFFER = MKBETAG('B','C','R','E'), + + /** + * Prepare window buffer message. + * + * Device requests to prepare a window buffer for rendering. + * Exact meaning is device- and application-dependent. + * Message is sent before rendering of each frame. + * + * data: NULL. + */ + AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER = MKBETAG('B','P','R','E'), + + /** + * Display window buffer message. + * + * Device requests to display a window buffer. + * Message is sent when new frame is ready to be displayed. + * Usually buffers need to be swapped in handler of this message. + * + * data: NULL. + */ + AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER = MKBETAG('B','D','I','S'), + + /** + * Destroy window buffer message. + * + * Device requests to destroy a window buffer. + * Message is sent when device is about to be destroyed and window + * buffer is not required anymore. + * + * data: NULL. + */ + AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER = MKBETAG('B','D','E','S'), + + /** + * Buffer fullness status messages. + * + * Device signals buffer overflow/underflow. + * + * data: NULL. + */ + AV_DEV_TO_APP_BUFFER_OVERFLOW = MKBETAG('B','O','F','L'), + AV_DEV_TO_APP_BUFFER_UNDERFLOW = MKBETAG('B','U','F','L'), + + /** + * Buffer readable/writable. + * + * Device informs that buffer is readable/writable. + * When possible, device informs how many bytes can be read/write. + * + * @warning Device may not inform when number of bytes than can be read/write changes. + * + * data: int64_t: amount of bytes available to read/write. + * NULL: amount of bytes available to read/write is not known. + */ + AV_DEV_TO_APP_BUFFER_READABLE = MKBETAG('B','R','D',' '), + AV_DEV_TO_APP_BUFFER_WRITABLE = MKBETAG('B','W','R',' '), + + /** + * Mute state change message. + * + * Device informs that mute state has changed. + * + * data: int: 0 for not muted state, non-zero for muted state. + */ + AV_DEV_TO_APP_MUTE_STATE_CHANGED = MKBETAG('C','M','U','T'), + + /** + * Volume level change message. + * + * Device informs that volume level has changed. + * + * data: double: new volume with range of 0.0 - 1.0. + */ + AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED = MKBETAG('C','V','O','L'), +}; + +/** + * Send control message from application to device. + * + * @param s device context. + * @param type message type. + * @param data message data. Exact type depends on message type. + * @param data_size size of message data. + * @return >= 0 on success, negative on error. + * AVERROR(ENOSYS) when device doesn't implement handler of the message. + */ +int avdevice_app_to_dev_control_message(struct AVFormatContext *s, + enum AVAppToDevMessageType type, + void *data, size_t data_size); + +/** + * Send control message from device to application. + * + * @param s device context. + * @param type message type. + * @param data message data. Can be NULL. + * @param data_size size of message data. + * @return >= 0 on success, negative on error. + * AVERROR(ENOSYS) when application doesn't implement handler of the message. + */ +int avdevice_dev_to_app_control_message(struct AVFormatContext *s, + enum AVDevToAppMessageType type, + void *data, size_t data_size); + +/** + * Structure describes basic parameters of the device. + */ +typedef struct AVDeviceInfo { + char *device_name; /**< device name, format depends on device */ + char *device_description; /**< human friendly name */ + enum AVMediaType *media_types; /**< array indicating what media types(s), if any, a device can provide. If null, cannot provide any */ + int nb_media_types; /**< length of media_types array, 0 if device cannot provide any media types */ +} AVDeviceInfo; + +/** + * List of devices. + */ +typedef struct AVDeviceInfoList { + AVDeviceInfo **devices; /**< list of autodetected devices */ + int nb_devices; /**< number of autodetected devices */ + int default_device; /**< index of default device or -1 if no default */ +} AVDeviceInfoList; + +/** + * List devices. + * + * Returns available device names and their parameters. + * + * @note: Some devices may accept system-dependent device names that cannot be + * autodetected. The list returned by this function cannot be assumed to + * be always completed. + * + * @param s device context. + * @param[out] device_list list of autodetected devices. + * @return count of autodetected devices, negative on error. + */ +int avdevice_list_devices(struct AVFormatContext *s, AVDeviceInfoList **device_list); + +/** + * Convenient function to free result of avdevice_list_devices(). + * + * @param device_list device list to be freed. + */ +void avdevice_free_list_devices(AVDeviceInfoList **device_list); + +/** + * List devices. + * + * Returns available device names and their parameters. + * These are convenient wrappers for avdevice_list_devices(). + * Device context is allocated and deallocated internally. + * + * @param device device format. May be NULL if device name is set. + * @param device_name device name. May be NULL if device format is set. + * @param device_options An AVDictionary filled with device-private options. May be NULL. + * The same options must be passed later to avformat_write_header() for output + * devices or avformat_open_input() for input devices, or at any other place + * that affects device-private options. + * @param[out] device_list list of autodetected devices + * @return count of autodetected devices, negative on error. + * @note device argument takes precedence over device_name when both are set. + */ +int avdevice_list_input_sources(const AVInputFormat *device, const char *device_name, + AVDictionary *device_options, AVDeviceInfoList **device_list); +int avdevice_list_output_sinks(const AVOutputFormat *device, const char *device_name, + AVDictionary *device_options, AVDeviceInfoList **device_list); + +/** + * @} + */ + +#endif /* AVDEVICE_AVDEVICE_H */ diff --git a/ffmpeg-n8.1/include/libavdevice/version.h b/ffmpeg-n8.1/include/libavdevice/version.h new file mode 100644 index 00000000..7608a860 --- /dev/null +++ b/ffmpeg-n8.1/include/libavdevice/version.h @@ -0,0 +1,45 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVDEVICE_VERSION_H +#define AVDEVICE_VERSION_H + +/** + * @file + * @ingroup lavd + * Libavdevice version macros + */ + +#include "libavutil/version.h" + +#include "version_major.h" + +#define LIBAVDEVICE_VERSION_MINOR 3 +#define LIBAVDEVICE_VERSION_MICRO 100 + +#define LIBAVDEVICE_VERSION_INT AV_VERSION_INT(LIBAVDEVICE_VERSION_MAJOR, \ + LIBAVDEVICE_VERSION_MINOR, \ + LIBAVDEVICE_VERSION_MICRO) +#define LIBAVDEVICE_VERSION AV_VERSION(LIBAVDEVICE_VERSION_MAJOR, \ + LIBAVDEVICE_VERSION_MINOR, \ + LIBAVDEVICE_VERSION_MICRO) +#define LIBAVDEVICE_BUILD LIBAVDEVICE_VERSION_INT + +#define LIBAVDEVICE_IDENT "Lavd" AV_STRINGIFY(LIBAVDEVICE_VERSION) + +#endif /* AVDEVICE_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libavdevice/version_major.h b/ffmpeg-n8.1/include/libavdevice/version_major.h new file mode 100644 index 00000000..191511cd --- /dev/null +++ b/ffmpeg-n8.1/include/libavdevice/version_major.h @@ -0,0 +1,38 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVDEVICE_VERSION_MAJOR_H +#define AVDEVICE_VERSION_MAJOR_H + +/** + * @file + * @ingroup lavd + * Libavdevice version macros + */ + +#define LIBAVDEVICE_VERSION_MAJOR 62 + +/** + * FF_API_* defines may be placed below to indicate public API that will be + * dropped at a future version bump. The defines themselves are not part of + * the public API and may change, break or disappear at any time. + */ + +#define FF_API_ALSA_CHANNELS (LIBAVDEVICE_VERSION_MAJOR < 63) + +#endif /* AVDEVICE_VERSION_MAJOR_H */ diff --git a/ffmpeg-n8.1/include/libavfilter/avfilter.h b/ffmpeg-n8.1/include/libavfilter/avfilter.h new file mode 100644 index 00000000..02b58c42 --- /dev/null +++ b/ffmpeg-n8.1/include/libavfilter/avfilter.h @@ -0,0 +1,1222 @@ +/* + * filter layer + * Copyright (c) 2007 Bobby Bingham + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFILTER_AVFILTER_H +#define AVFILTER_AVFILTER_H + +/** + * @file + * @ingroup lavfi + * Main libavfilter public API header + */ + +/** + * @defgroup lavfi libavfilter + * Graph-based frame editing library. + * + * @{ + */ + +#include + +#include "libavutil/attributes.h" +#include "libavutil/avutil.h" +#include "libavutil/buffer.h" +#include "libavutil/dict.h" +#include "libavutil/frame.h" +#include "libavutil/log.h" +#include "libavutil/pixfmt.h" +#include "libavutil/rational.h" + +#include "libavfilter/version_major.h" +#ifndef HAVE_AV_CONFIG_H +/* When included as part of the ffmpeg build, only include the major version + * to avoid unnecessary rebuilds. When included externally, keep including + * the full version information. */ +#include "libavfilter/version.h" +#endif + +/** + * Return the LIBAVFILTER_VERSION_INT constant. + */ +unsigned avfilter_version(void); + +/** + * Return the libavfilter build-time configuration. + */ +const char *avfilter_configuration(void); + +/** + * Return the libavfilter license. + */ +const char *avfilter_license(void); + +typedef struct AVFilterLink AVFilterLink; +typedef struct AVFilterPad AVFilterPad; +typedef struct AVFilterFormats AVFilterFormats; +typedef struct AVFilterChannelLayouts AVFilterChannelLayouts; + +/** + * Get the name of an AVFilterPad. + * + * @param pads an array of AVFilterPads + * @param pad_idx index of the pad in the array; it is the caller's + * responsibility to ensure the index is valid + * + * @return name of the pad_idx'th pad in pads + */ +const char *avfilter_pad_get_name(const AVFilterPad *pads, int pad_idx); + +/** + * Get the type of an AVFilterPad. + * + * @param pads an array of AVFilterPads + * @param pad_idx index of the pad in the array; it is the caller's + * responsibility to ensure the index is valid + * + * @return type of the pad_idx'th pad in pads + */ +enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx); + +/** + * Get the hardware frames context of a filter link. + * + * @param link an AVFilterLink + * + * @return a ref-counted copy of the link's hw_frames_ctx field if there is + * a hardware frames context associated with the link or NULL otherwise. + * The returned AVBufferRef needs to be released with av_buffer_unref() + * when it is no longer used. + */ +AVBufferRef* avfilter_link_get_hw_frames_ctx(AVFilterLink *link); + +/** + * Lists of formats / etc. supported by an end of a link. + * + * This structure is directly part of AVFilterLink, in two copies: + * one for the source filter, one for the destination filter. + + * These lists are used for negotiating the format to actually be used, + * which will be loaded into the format and channel_layout members of + * AVFilterLink, when chosen. + */ +typedef struct AVFilterFormatsConfig { + + /** + * List of supported formats (pixel or sample). + */ + AVFilterFormats *formats; + + /** + * Lists of supported sample rates, only for audio. + */ + AVFilterFormats *samplerates; + + /** + * Lists of supported channel layouts, only for audio. + */ + AVFilterChannelLayouts *channel_layouts; + + /** + * Lists of supported YUV color metadata, only for YUV video. + */ + AVFilterFormats *color_spaces; ///< AVColorSpace + AVFilterFormats *color_ranges; ///< AVColorRange + + /** + * List of supported alpha modes, only for video with an alpha channel. + */ + AVFilterFormats *alpha_modes; ///< AVAlphaMode + +} AVFilterFormatsConfig; + +/** + * The number of the filter inputs is not determined just by AVFilter.inputs. + * The filter might add additional inputs during initialization depending on the + * options supplied to it. + */ +#define AVFILTER_FLAG_DYNAMIC_INPUTS (1 << 0) +/** + * The number of the filter outputs is not determined just by AVFilter.outputs. + * The filter might add additional outputs during initialization depending on + * the options supplied to it. + */ +#define AVFILTER_FLAG_DYNAMIC_OUTPUTS (1 << 1) +/** + * The filter supports multithreading by splitting frames into multiple parts + * and processing them concurrently. + */ +#define AVFILTER_FLAG_SLICE_THREADS (1 << 2) +/** + * The filter is a "metadata" filter - it does not modify the frame data in any + * way. It may only affect the metadata (i.e. those fields copied by + * av_frame_copy_props()). + * + * More precisely, this means: + * - video: the data of any frame output by the filter must be exactly equal to + * some frame that is received on one of its inputs. Furthermore, all frames + * produced on a given output must correspond to frames received on the same + * input and their order must be unchanged. Note that the filter may still + * drop or duplicate the frames. + * - audio: the data produced by the filter on any of its outputs (viewed e.g. + * as an array of interleaved samples) must be exactly equal to the data + * received by the filter on one of its inputs. + */ +#define AVFILTER_FLAG_METADATA_ONLY (1 << 3) + +/** + * The filter can create hardware frames using AVFilterContext.hw_device_ctx. + */ +#define AVFILTER_FLAG_HWDEVICE (1 << 4) +/** + * Some filters support a generic "enable" expression option that can be used + * to enable or disable a filter in the timeline. Filters supporting this + * option have this flag set. When the enable expression is false, the default + * no-op filter_frame() function is called in place of the filter_frame() + * callback defined on each input pad, thus the frame is passed unchanged to + * the next filters. + */ +#define AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC (1 << 16) +/** + * Same as AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC, except that the filter will + * have its filter_frame() callback(s) called as usual even when the enable + * expression is false. The filter will disable filtering within the + * filter_frame() callback(s) itself, for example executing code depending on + * the AVFilterContext->is_disabled value. + */ +#define AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL (1 << 17) +/** + * Handy mask to test whether the filter supports or no the timeline feature + * (internally or generically). + */ +#define AVFILTER_FLAG_SUPPORT_TIMELINE (AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC | AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL) + +/** + * Filter definition. This defines the pads a filter contains, and all the + * callback functions used to interact with the filter. + */ +typedef struct AVFilter { + /** + * Filter name. Must be non-NULL and unique among filters. + */ + const char *name; + + /** + * A description of the filter. May be NULL. + * + * You should use the NULL_IF_CONFIG_SMALL() macro to define it. + */ + const char *description; + + /** + * List of static inputs. + * + * NULL if there are no (static) inputs. Instances of filters with + * AVFILTER_FLAG_DYNAMIC_INPUTS set may have more inputs than present in + * this list. + */ + const AVFilterPad *inputs; + + /** + * List of static outputs. + * + * NULL if there are no (static) outputs. Instances of filters with + * AVFILTER_FLAG_DYNAMIC_OUTPUTS set may have more outputs than present in + * this list. + */ + const AVFilterPad *outputs; + + /** + * A class for the private data, used to declare filter private AVOptions. + * This field is NULL for filters that do not declare any options. + * + * If this field is non-NULL, the first member of the filter private data + * must be a pointer to AVClass, which will be set by libavfilter generic + * code to this class. + */ + const AVClass *priv_class; + + /** + * A combination of AVFILTER_FLAG_* + */ + int flags; +} AVFilter; + +/** + * Get the number of elements in an AVFilter's inputs or outputs array. + */ +unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); + +/** + * Process multiple parts of the frame concurrently. + */ +#define AVFILTER_THREAD_SLICE (1 << 0) + +/** An instance of a filter */ +typedef struct AVFilterContext { + const AVClass *av_class; ///< needed for av_log() and filters common options + + const AVFilter *filter; ///< the AVFilter of which this is an instance + + char *name; ///< name of this filter instance + + AVFilterPad *input_pads; ///< array of input pads + AVFilterLink **inputs; ///< array of pointers to input links + unsigned nb_inputs; ///< number of input pads + + AVFilterPad *output_pads; ///< array of output pads + AVFilterLink **outputs; ///< array of pointers to output links + unsigned nb_outputs; ///< number of output pads + + void *priv; ///< private data for use by the filter + + struct AVFilterGraph *graph; ///< filtergraph this filter belongs to + + /** + * Type of multithreading being allowed/used. A combination of + * AVFILTER_THREAD_* flags. + * + * May be set by the caller before initializing the filter to forbid some + * or all kinds of multithreading for this filter. The default is allowing + * everything. + * + * When the filter is initialized, this field is combined using bit AND with + * AVFilterGraph.thread_type to get the final mask used for determining + * allowed threading types. I.e. a threading type needs to be set in both + * to be allowed. + * + * After the filter is initialized, libavfilter sets this field to the + * threading type that is actually used (0 for no multithreading). + */ + int thread_type; + + /** + * Max number of threads allowed in this filter instance. + * If <= 0, its value is ignored. + * Overrides global number of threads set per filter graph. + */ + int nb_threads; + +#if FF_API_CONTEXT_PUBLIC + /** + * @deprecated unused + */ + attribute_deprecated + struct AVFilterCommand *command_queue; +#endif + + char *enable_str; ///< enable expression string +#if FF_API_CONTEXT_PUBLIC + /** + * @deprecated unused + */ + attribute_deprecated + void *enable; + /** + * @deprecated unused + */ + double *var_values; +#endif + /** + * MUST NOT be accessed from outside avfilter. + * + * the enabled state from the last expression evaluation + */ + int is_disabled; + + /** + * For filters which will create hardware frames, sets the device the + * filter should create them in. All other filters will ignore this field: + * in particular, a filter which consumes or processes hardware frames will + * instead use the hw_frames_ctx field in AVFilterLink to carry the + * hardware context information. + * + * May be set by the caller on filters flagged with AVFILTER_FLAG_HWDEVICE + * before initializing the filter with avfilter_init_str() or + * avfilter_init_dict(). + */ + AVBufferRef *hw_device_ctx; + +#if FF_API_CONTEXT_PUBLIC + /** + * @deprecated this field should never have been accessed by callers + */ + attribute_deprecated + unsigned ready; +#endif + + /** + * Sets the number of extra hardware frames which the filter will + * allocate on its output links for use in following filters or by + * the caller. + * + * Some hardware filters require all frames that they will use for + * output to be defined in advance before filtering starts. For such + * filters, any hardware frame pools used for output must therefore be + * of fixed size. The extra frames set here are on top of any number + * that the filter needs internally in order to operate normally. + * + * This field must be set before the graph containing this filter is + * configured. + */ + int extra_hw_frames; +} AVFilterContext; + +/** + * A link between two filters. This contains pointers to the source and + * destination filters between which this link exists, and the indexes of + * the pads involved. In addition, this link also contains the parameters + * which have been negotiated and agreed upon between the filter, such as + * image dimensions, format, etc. + * + * Applications must not normally access the link structure directly. + * Use the buffersrc and buffersink API instead. + * In the future, access to the header may be reserved for filters + * implementation. + */ +struct AVFilterLink { + AVFilterContext *src; ///< source filter + AVFilterPad *srcpad; ///< output pad on the source filter + + AVFilterContext *dst; ///< dest filter + AVFilterPad *dstpad; ///< input pad on the dest filter + + enum AVMediaType type; ///< filter media type + + int format; ///< agreed upon media format + + /* These parameters apply only to video */ + int w; ///< agreed upon image width + int h; ///< agreed upon image height + AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio + /** + * For non-YUV links, these are respectively set to fallback values (as + * appropriate for that colorspace). + * + * Note: This includes grayscale formats, as these are currently treated + * as forced full range always. + */ + enum AVColorSpace colorspace; ///< agreed upon YUV color space + enum AVColorRange color_range; ///< agreed upon YUV color range + + /* These parameters apply only to audio */ + int sample_rate; ///< samples per second + AVChannelLayout ch_layout; ///< channel layout of current buffer (see libavutil/channel_layout.h) + + /** + * Define the time base used by the PTS of the frames/samples + * which will pass through this link. + * During the configuration stage, each filter is supposed to + * change only the output timebase, while the timebase of the + * input link is assumed to be an unchangeable property. + */ + AVRational time_base; + + AVFrameSideData **side_data; + int nb_side_data; + + enum AVAlphaMode alpha_mode; ///< alpha mode (for videos with an alpha channel) + + /***************************************************************** + * All fields below this line are not part of the public API. They + * may not be used outside of libavfilter and can be changed and + * removed at will. + * New public fields should be added right above. + ***************************************************************** + */ + + /** + * Lists of supported formats / etc. supported by the input filter. + */ + AVFilterFormatsConfig incfg; + + /** + * Lists of supported formats / etc. supported by the output filter. + */ + AVFilterFormatsConfig outcfg; +}; + +/** + * Link two filters together. + * + * @param src the source filter + * @param srcpad index of the output pad on the source filter + * @param dst the destination filter + * @param dstpad index of the input pad on the destination filter + * @return zero on success + */ +int avfilter_link(AVFilterContext *src, unsigned srcpad, + AVFilterContext *dst, unsigned dstpad); + +#define AVFILTER_CMD_FLAG_ONE 1 ///< Stop once a filter understood the command (for target=all for example), fast filters are favored automatically +#define AVFILTER_CMD_FLAG_FAST 2 ///< Only execute command when its fast (like a video out that supports contrast adjustment in hw) + +/** + * Make the filter instance process a command. + * It is recommended to use avfilter_graph_send_command(). + */ +int avfilter_process_command(AVFilterContext *filter, const char *cmd, const char *arg, char *res, int res_len, int flags); + +/** + * Iterate over all registered filters. + * + * @param opaque a pointer where libavfilter will store the iteration state. Must + * point to NULL to start the iteration. + * + * @return the next registered filter or NULL when the iteration is + * finished + */ +const AVFilter *av_filter_iterate(void **opaque); + +/** + * Get a filter definition matching the given name. + * + * @param name the filter name to find + * @return the filter definition, if any matching one is registered. + * NULL if none found. + */ +const AVFilter *avfilter_get_by_name(const char *name); + + +/** + * Initialize a filter with the supplied parameters. + * + * @param ctx uninitialized filter context to initialize + * @param args Options to initialize the filter with. This must be a + * ':'-separated list of options in the 'key=value' form. + * May be NULL if the options have been set directly using the + * AVOptions API or there are no options that need to be set. + * @return 0 on success, a negative AVERROR on failure + */ +int avfilter_init_str(AVFilterContext *ctx, const char *args); + +/** + * Initialize a filter with the supplied dictionary of options. + * + * @param ctx uninitialized filter context to initialize + * @param options An AVDictionary filled with options for this filter. On + * return this parameter will be destroyed and replaced with + * a dict containing options that were not found. This dictionary + * must be freed by the caller. + * May be NULL, then this function is equivalent to + * avfilter_init_str() with the second parameter set to NULL. + * @return 0 on success, a negative AVERROR on failure + * + * @note This function and avfilter_init_str() do essentially the same thing, + * the difference is in manner in which the options are passed. It is up to the + * calling code to choose whichever is more preferable. The two functions also + * behave differently when some of the provided options are not declared as + * supported by the filter. In such a case, avfilter_init_str() will fail, but + * this function will leave those extra options in the options AVDictionary and + * continue as usual. + */ +int avfilter_init_dict(AVFilterContext *ctx, AVDictionary **options); + +/** + * Free a filter context. This will also remove the filter from its + * filtergraph's list of filters. + * + * @param filter the filter to free + */ +void avfilter_free(AVFilterContext *filter); + +/** + * Insert a filter in the middle of an existing link. + * + * @param link the link into which the filter should be inserted + * @param filt the filter to be inserted + * @param filt_srcpad_idx the input pad on the filter to connect + * @param filt_dstpad_idx the output pad on the filter to connect + * @return zero on success + */ +int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt, + unsigned filt_srcpad_idx, unsigned filt_dstpad_idx); + +/** + * @return AVClass for AVFilterContext. + * + * @see av_opt_find(). + */ +const AVClass *avfilter_get_class(void); + +/** + * A function pointer passed to the @ref AVFilterGraph.execute callback to be + * executed multiple times, possibly in parallel. + * + * @param ctx the filter context the job belongs to + * @param arg an opaque parameter passed through from @ref + * AVFilterGraph.execute + * @param jobnr the index of the job being executed + * @param nb_jobs the total number of jobs + * + * @return 0 on success, a negative AVERROR on error + */ +typedef int (avfilter_action_func)(AVFilterContext *ctx, void *arg, int jobnr, int nb_jobs); + +/** + * A function executing multiple jobs, possibly in parallel. + * + * @param ctx the filter context to which the jobs belong + * @param func the function to be called multiple times + * @param arg the argument to be passed to func + * @param ret a nb_jobs-sized array to be filled with return values from each + * invocation of func + * @param nb_jobs the number of jobs to execute + * + * @return 0 on success, a negative AVERROR on error + */ +typedef int (avfilter_execute_func)(AVFilterContext *ctx, avfilter_action_func *func, + void *arg, int *ret, int nb_jobs); + +typedef struct AVFilterGraph { + const AVClass *av_class; + AVFilterContext **filters; + unsigned nb_filters; + + char *scale_sws_opts; ///< sws options to use for the auto-inserted scale filters + + /** + * Type of multithreading allowed for filters in this graph. A combination + * of AVFILTER_THREAD_* flags. + * + * May be set by the caller at any point, the setting will apply to all + * filters initialized after that. The default is allowing everything. + * + * When a filter in this graph is initialized, this field is combined using + * bit AND with AVFilterContext.thread_type to get the final mask used for + * determining allowed threading types. I.e. a threading type needs to be + * set in both to be allowed. + */ + int thread_type; + + /** + * Maximum number of threads used by filters in this graph. May be set by + * the caller before adding any filters to the filtergraph. Zero (the + * default) means that the number of threads is determined automatically. + */ + int nb_threads; + + /** + * Opaque user data. May be set by the caller to an arbitrary value, e.g. to + * be used from callbacks like @ref AVFilterGraph.execute. + * Libavfilter will not touch this field in any way. + */ + void *opaque; + + /** + * This callback may be set by the caller immediately after allocating the + * graph and before adding any filters to it, to provide a custom + * multithreading implementation. + * + * If set, filters with slice threading capability will call this callback + * to execute multiple jobs in parallel. + * + * If this field is left unset, libavfilter will use its internal + * implementation, which may or may not be multithreaded depending on the + * platform and build options. + */ + avfilter_execute_func *execute; + + char *aresample_swr_opts; ///< swr options to use for the auto-inserted aresample filters, Access ONLY through AVOptions + + /** + * Sets the maximum number of buffered frames in the filtergraph combined. + * + * Zero means no limit. This field must be set before calling + * avfilter_graph_config(). + */ + unsigned max_buffered_frames; +} AVFilterGraph; + +/** + * Allocate a filter graph. + * + * @return the allocated filter graph on success or NULL. + */ +AVFilterGraph *avfilter_graph_alloc(void); + +/** + * Create a new filter instance in a filter graph. + * + * @param graph graph in which the new filter will be used + * @param filter the filter to create an instance of + * @param name Name to give to the new instance (will be copied to + * AVFilterContext.name). This may be used by the caller to identify + * different filters, libavfilter itself assigns no semantics to + * this parameter. May be NULL. + * + * @return the context of the newly created filter instance (note that it is + * also retrievable directly through AVFilterGraph.filters or with + * avfilter_graph_get_filter()) on success or NULL on failure. + */ +AVFilterContext *avfilter_graph_alloc_filter(AVFilterGraph *graph, + const AVFilter *filter, + const char *name); + +/** + * Get a filter instance identified by instance name from graph. + * + * @param graph filter graph to search through. + * @param name filter instance name (should be unique in the graph). + * @return the pointer to the found filter instance or NULL if it + * cannot be found. + */ +AVFilterContext *avfilter_graph_get_filter(AVFilterGraph *graph, const char *name); + +/** + * A convenience wrapper that allocates and initializes a filter in a single + * step. The filter instance is created from the filter filt and inited with the + * parameter args. opaque is currently ignored. + * + * In case of success put in *filt_ctx the pointer to the created + * filter instance, otherwise set *filt_ctx to NULL. + * + * @param name the instance name to give to the created filter instance + * @param graph_ctx the filter graph + * @return a negative AVERROR error code in case of failure, a non + * negative value otherwise + * + * @warning Since the filter is initialized after this function successfully + * returns, you MUST NOT set any further options on it. If you need to + * do that, call ::avfilter_graph_alloc_filter(), followed by setting + * the options, followed by ::avfilter_init_dict() instead of this + * function. + */ +int avfilter_graph_create_filter(AVFilterContext **filt_ctx, const AVFilter *filt, + const char *name, const char *args, void *opaque, + AVFilterGraph *graph_ctx); + +/** + * Enable or disable automatic format conversion inside the graph. + * + * Note that format conversion can still happen inside explicitly inserted + * scale and aresample filters. + * + * @param flags any of the AVFILTER_AUTO_CONVERT_* constants + */ +void avfilter_graph_set_auto_convert(AVFilterGraph *graph, unsigned flags); + +enum { + AVFILTER_AUTO_CONVERT_ALL = 0, /**< all automatic conversions enabled */ + AVFILTER_AUTO_CONVERT_NONE = -1, /**< all automatic conversions disabled */ +}; + +/** + * Check validity and configure all the links and formats in the graph. + * + * @param graphctx the filter graph + * @param log_ctx context used for logging + * @return >= 0 in case of success, a negative AVERROR code otherwise + */ +int avfilter_graph_config(AVFilterGraph *graphctx, void *log_ctx); + +/** + * Free a graph, destroy its links, and set *graph to NULL. + * If *graph is NULL, do nothing. + */ +void avfilter_graph_free(AVFilterGraph **graph); + +/** + * A linked-list of the inputs/outputs of the filter chain. + * + * This is mainly useful for avfilter_graph_parse() / avfilter_graph_parse2(), + * where it is used to communicate open (unlinked) inputs and outputs from and + * to the caller. + * This struct specifies, per each not connected pad contained in the graph, the + * filter context and the pad index required for establishing a link. + */ +typedef struct AVFilterInOut { + /** unique name for this input/output in the list */ + char *name; + + /** filter context associated to this input/output */ + AVFilterContext *filter_ctx; + + /** index of the filt_ctx pad to use for linking */ + int pad_idx; + + /** next input/input in the list, NULL if this is the last */ + struct AVFilterInOut *next; +} AVFilterInOut; + +/** + * Allocate a single AVFilterInOut entry. + * Must be freed with avfilter_inout_free(). + * @return allocated AVFilterInOut on success, NULL on failure. + */ +AVFilterInOut *avfilter_inout_alloc(void); + +/** + * Free the supplied list of AVFilterInOut and set *inout to NULL. + * If *inout is NULL, do nothing. + */ +void avfilter_inout_free(AVFilterInOut **inout); + +/** + * Add a graph described by a string to a graph. + * + * @note The caller must provide the lists of inputs and outputs, + * which therefore must be known before calling the function. + * + * @note The inputs parameter describes inputs of the already existing + * part of the graph; i.e. from the point of view of the newly created + * part, they are outputs. Similarly the outputs parameter describes + * outputs of the already existing filters, which are provided as + * inputs to the parsed filters. + * + * @param graph the filter graph where to link the parsed graph context + * @param filters string to be parsed + * @param inputs linked list to the inputs of the graph + * @param outputs linked list to the outputs of the graph + * @return zero on success, a negative AVERROR code on error + */ +int avfilter_graph_parse(AVFilterGraph *graph, const char *filters, + AVFilterInOut *inputs, AVFilterInOut *outputs, + void *log_ctx); + +/** + * Add a graph described by a string to a graph. + * + * In the graph filters description, if the input label of the first + * filter is not specified, "in" is assumed; if the output label of + * the last filter is not specified, "out" is assumed. + * + * @param graph the filter graph where to link the parsed graph context + * @param filters string to be parsed + * @param inputs pointer to a linked list to the inputs of the graph, may be NULL. + * If non-NULL, *inputs is updated to contain the list of open inputs + * after the parsing, should be freed with avfilter_inout_free(). + * @param outputs pointer to a linked list to the outputs of the graph, may be NULL. + * If non-NULL, *outputs is updated to contain the list of open outputs + * after the parsing, should be freed with avfilter_inout_free(). + * @return non negative on success, a negative AVERROR code on error + */ +int avfilter_graph_parse_ptr(AVFilterGraph *graph, const char *filters, + AVFilterInOut **inputs, AVFilterInOut **outputs, + void *log_ctx); + +/** + * Add a graph described by a string to a graph. + * + * @param[in] graph the filter graph where to link the parsed graph context + * @param[in] filters string to be parsed + * @param[out] inputs a linked list of all free (unlinked) inputs of the + * parsed graph will be returned here. It is to be freed + * by the caller using avfilter_inout_free(). + * @param[out] outputs a linked list of all free (unlinked) outputs of the + * parsed graph will be returned here. It is to be freed by the + * caller using avfilter_inout_free(). + * @return zero on success, a negative AVERROR code on error + * + * @note This function returns the inputs and outputs that are left + * unlinked after parsing the graph and the caller then deals with + * them. + * @note This function makes no reference whatsoever to already + * existing parts of the graph and the inputs parameter will on return + * contain inputs of the newly parsed part of the graph. Analogously + * the outputs parameter will contain outputs of the newly created + * filters. + */ +int avfilter_graph_parse2(AVFilterGraph *graph, const char *filters, + AVFilterInOut **inputs, + AVFilterInOut **outputs); + +/** + * Parameters of a filter's input or output pad. + * + * Created as a child of AVFilterParams by avfilter_graph_segment_parse(). + * Freed in avfilter_graph_segment_free(). + */ +typedef struct AVFilterPadParams { + /** + * An av_malloc()'ed string containing the pad label. + * + * May be av_free()'d and set to NULL by the caller, in which case this pad + * will be treated as unlabeled for linking. + * May also be replaced by another av_malloc()'ed string. + */ + char *label; +} AVFilterPadParams; + +/** + * Parameters describing a filter to be created in a filtergraph. + * + * Created as a child of AVFilterGraphSegment by avfilter_graph_segment_parse(). + * Freed in avfilter_graph_segment_free(). + */ +typedef struct AVFilterParams { + /** + * The filter context. + * + * Created by avfilter_graph_segment_create_filters() based on + * AVFilterParams.filter_name and instance_name. + * + * Callers may also create the filter context manually, then they should + * av_free() filter_name and set it to NULL. Such AVFilterParams instances + * are then skipped by avfilter_graph_segment_create_filters(). + */ + AVFilterContext *filter; + + /** + * Name of the AVFilter to be used. + * + * An av_malloc()'ed string, set by avfilter_graph_segment_parse(). Will be + * passed to avfilter_get_by_name() by + * avfilter_graph_segment_create_filters(). + * + * Callers may av_free() this string and replace it with another one or + * NULL. If the caller creates the filter instance manually, this string + * MUST be set to NULL. + * + * When both AVFilterParams.filter an AVFilterParams.filter_name are NULL, + * this AVFilterParams instance is skipped by avfilter_graph_segment_*() + * functions. + */ + char *filter_name; + /** + * Name to be used for this filter instance. + * + * An av_malloc()'ed string, may be set by avfilter_graph_segment_parse() or + * left NULL. The caller may av_free() this string and replace with another + * one or NULL. + * + * Will be used by avfilter_graph_segment_create_filters() - passed as the + * third argument to avfilter_graph_alloc_filter(), then freed and set to + * NULL. + */ + char *instance_name; + + /** + * Options to be applied to the filter. + * + * Filled by avfilter_graph_segment_parse(). Afterwards may be freely + * modified by the caller. + * + * Will be applied to the filter by avfilter_graph_segment_apply_opts() + * with an equivalent of av_opt_set_dict2(filter, &opts, AV_OPT_SEARCH_CHILDREN), + * i.e. any unapplied options will be left in this dictionary. + */ + AVDictionary *opts; + + AVFilterPadParams **inputs; + unsigned nb_inputs; + + AVFilterPadParams **outputs; + unsigned nb_outputs; +} AVFilterParams; + +/** + * A filterchain is a list of filter specifications. + * + * Created as a child of AVFilterGraphSegment by avfilter_graph_segment_parse(). + * Freed in avfilter_graph_segment_free(). + */ +typedef struct AVFilterChain { + AVFilterParams **filters; + size_t nb_filters; +} AVFilterChain; + +/** + * A parsed representation of a filtergraph segment. + * + * A filtergraph segment is conceptually a list of filterchains, with some + * supplementary information (e.g. format conversion flags). + * + * Created by avfilter_graph_segment_parse(). Must be freed with + * avfilter_graph_segment_free(). + */ +typedef struct AVFilterGraphSegment { + /** + * The filtergraph this segment is associated with. + * Set by avfilter_graph_segment_parse(). + */ + AVFilterGraph *graph; + + /** + * A list of filter chain contained in this segment. + * Set in avfilter_graph_segment_parse(). + */ + AVFilterChain **chains; + size_t nb_chains; + + /** + * A string containing a colon-separated list of key=value options applied + * to all scale filters in this segment. + * + * May be set by avfilter_graph_segment_parse(). + * The caller may free this string with av_free() and replace it with a + * different av_malloc()'ed string. + */ + char *scale_sws_opts; +} AVFilterGraphSegment; + +/** + * Parse a textual filtergraph description into an intermediate form. + * + * This intermediate representation is intended to be modified by the caller as + * described in the documentation of AVFilterGraphSegment and its children, and + * then applied to the graph either manually or with other + * avfilter_graph_segment_*() functions. See the documentation for + * avfilter_graph_segment_apply() for the canonical way to apply + * AVFilterGraphSegment. + * + * @param graph Filter graph the parsed segment is associated with. Will only be + * used for logging and similar auxiliary purposes. The graph will + * not be actually modified by this function - the parsing results + * are instead stored in seg for further processing. + * @param graph_str a string describing the filtergraph segment + * @param flags reserved for future use, caller must set to 0 for now + * @param seg A pointer to the newly-created AVFilterGraphSegment is written + * here on success. The graph segment is owned by the caller and must + * be freed with avfilter_graph_segment_free() before graph itself is + * freed. + * + * @retval "non-negative number" success + * @retval "negative error code" failure + */ +int avfilter_graph_segment_parse(AVFilterGraph *graph, const char *graph_str, + int flags, AVFilterGraphSegment **seg); + +/** + * Create filters specified in a graph segment. + * + * Walk through the creation-pending AVFilterParams in the segment and create + * new filter instances for them. + * Creation-pending params are those where AVFilterParams.filter_name is + * non-NULL (and hence AVFilterParams.filter is NULL). All other AVFilterParams + * instances are ignored. + * + * For any filter created by this function, the corresponding + * AVFilterParams.filter is set to the newly-created filter context, + * AVFilterParams.filter_name and AVFilterParams.instance_name are freed and set + * to NULL. + * + * @param seg the filtergraph segment to process + * @param flags reserved for future use, caller must set to 0 for now + * + * @retval "non-negative number" Success, all creation-pending filters were + * successfully created + * @retval AVERROR_FILTER_NOT_FOUND some filter's name did not correspond to a + * known filter + * @retval "another negative error code" other failures + * + * @note Calling this function multiple times is safe, as it is idempotent. + */ +int avfilter_graph_segment_create_filters(AVFilterGraphSegment *seg, int flags); + +/** + * Apply parsed options to filter instances in a graph segment. + * + * Walk through all filter instances in the graph segment that have option + * dictionaries associated with them and apply those options with + * av_opt_set_dict2(..., AV_OPT_SEARCH_CHILDREN). AVFilterParams.opts is + * replaced by the dictionary output by av_opt_set_dict2(), which should be + * empty (NULL) if all options were successfully applied. + * + * If any options could not be found, this function will continue processing all + * other filters and finally return AVERROR_OPTION_NOT_FOUND (unless another + * error happens). The calling program may then deal with unapplied options as + * it wishes. + * + * Any creation-pending filters (see avfilter_graph_segment_create_filters()) + * present in the segment will cause this function to fail. AVFilterParams with + * no associated filter context are simply skipped. + * + * @param seg the filtergraph segment to process + * @param flags reserved for future use, caller must set to 0 for now + * + * @retval "non-negative number" Success, all options were successfully applied. + * @retval AVERROR_OPTION_NOT_FOUND some options were not found in a filter + * @retval "another negative error code" other failures + * + * @note Calling this function multiple times is safe, as it is idempotent. + */ +int avfilter_graph_segment_apply_opts(AVFilterGraphSegment *seg, int flags); + +/** + * Initialize all filter instances in a graph segment. + * + * Walk through all filter instances in the graph segment and call + * avfilter_init_dict(..., NULL) on those that have not been initialized yet. + * + * Any creation-pending filters (see avfilter_graph_segment_create_filters()) + * present in the segment will cause this function to fail. AVFilterParams with + * no associated filter context or whose filter context is already initialized, + * are simply skipped. + * + * @param seg the filtergraph segment to process + * @param flags reserved for future use, caller must set to 0 for now + * + * @retval "non-negative number" Success, all filter instances were successfully + * initialized + * @retval "negative error code" failure + * + * @note Calling this function multiple times is safe, as it is idempotent. + */ +int avfilter_graph_segment_init(AVFilterGraphSegment *seg, int flags); + +/** + * Link filters in a graph segment. + * + * Walk through all filter instances in the graph segment and try to link all + * unlinked input and output pads. Any creation-pending filters (see + * avfilter_graph_segment_create_filters()) present in the segment will cause + * this function to fail. Disabled filters and already linked pads are skipped. + * + * Every filter output pad that has a corresponding AVFilterPadParams with a + * non-NULL label is + * - linked to the input with the matching label, if one exists; + * - exported in the outputs linked list otherwise, with the label preserved. + * Unlabeled outputs are + * - linked to the first unlinked unlabeled input in the next non-disabled + * filter in the chain, if one exists + * - exported in the outputs linked list otherwise, with NULL label + * + * Similarly, unlinked input pads are exported in the inputs linked list. + * + * @param seg the filtergraph segment to process + * @param flags reserved for future use, caller must set to 0 for now + * @param[out] inputs a linked list of all free (unlinked) inputs of the + * filters in this graph segment will be returned here. It + * is to be freed by the caller using avfilter_inout_free(). + * @param[out] outputs a linked list of all free (unlinked) outputs of the + * filters in this graph segment will be returned here. It + * is to be freed by the caller using avfilter_inout_free(). + * + * @retval "non-negative number" success + * @retval "negative error code" failure + * + * @note Calling this function multiple times is safe, as it is idempotent. + */ +int avfilter_graph_segment_link(AVFilterGraphSegment *seg, int flags, + AVFilterInOut **inputs, + AVFilterInOut **outputs); + +/** + * Apply all filter/link descriptions from a graph segment to the associated filtergraph. + * + * This functions is currently equivalent to calling the following in sequence: + * - avfilter_graph_segment_create_filters(); + * - avfilter_graph_segment_apply_opts(); + * - avfilter_graph_segment_init(); + * - avfilter_graph_segment_link(); + * failing if any of them fails. This list may be extended in the future. + * + * Since the above functions are idempotent, the caller may call some of them + * manually, then do some custom processing on the filtergraph, then call this + * function to do the rest. + * + * @param seg the filtergraph segment to process + * @param flags reserved for future use, caller must set to 0 for now + * @param[out] inputs passed to avfilter_graph_segment_link() + * @param[out] outputs passed to avfilter_graph_segment_link() + * + * @retval "non-negative number" success + * @retval "negative error code" failure + * + * @note Calling this function multiple times is safe, as it is idempotent. + */ +int avfilter_graph_segment_apply(AVFilterGraphSegment *seg, int flags, + AVFilterInOut **inputs, + AVFilterInOut **outputs); + +/** + * Free the provided AVFilterGraphSegment and everything associated with it. + * + * @param seg double pointer to the AVFilterGraphSegment to be freed. NULL will + * be written to this pointer on exit from this function. + * + * @note + * The filter contexts (AVFilterParams.filter) are owned by AVFilterGraph rather + * than AVFilterGraphSegment, so they are not freed. + */ +void avfilter_graph_segment_free(AVFilterGraphSegment **seg); + +/** + * Send a command to one or more filter instances. + * + * @param graph the filter graph + * @param target the filter(s) to which the command should be sent + * "all" sends to all filters + * otherwise it can be a filter or filter instance name + * which will send the command to all matching filters. + * @param cmd the command to send, for handling simplicity all commands must be alphanumeric only + * @param arg the argument for the command + * @param res a buffer with size res_size where the filter(s) can return a response. + * + * @returns >=0 on success otherwise an error code. + * AVERROR(ENOSYS) on unsupported commands + */ +int avfilter_graph_send_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, char *res, int res_len, int flags); + +/** + * Queue a command for one or more filter instances. + * + * @param graph the filter graph + * @param target the filter(s) to which the command should be sent + * "all" sends to all filters + * otherwise it can be a filter or filter instance name + * which will send the command to all matching filters. + * @param cmd the command to sent, for handling simplicity all commands must be alphanumeric only + * @param arg the argument for the command + * @param ts time at which the command should be sent to the filter + * + * @note As this executes commands after this function returns, no return code + * from the filter is provided, also AVFILTER_CMD_FLAG_ONE is not supported. + */ +int avfilter_graph_queue_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, int flags, double ts); + + +/** + * Dump a graph into a human-readable string representation. + * + * @param graph the graph to dump + * @param options formatting options; currently ignored + * @return a string, or NULL in case of memory allocation failure; + * the string must be freed using av_free + */ +char *avfilter_graph_dump(AVFilterGraph *graph, const char *options); + +/** + * Request a frame on the oldest sink link. + * + * If the request returns AVERROR_EOF, try the next. + * + * Note that this function is not meant to be the sole scheduling mechanism + * of a filtergraph, only a convenience function to help drain a filtergraph + * in a balanced way under normal circumstances. + * + * Also note that AVERROR_EOF does not mean that frames did not arrive on + * some of the sinks during the process. + * When there are multiple sink links, in case the requested link + * returns an EOF, this may cause a filter to flush pending frames + * which are sent to another sink link, although unrequested. + * + * @return the return value of ff_request_frame(), + * or AVERROR_EOF if all links returned AVERROR_EOF + */ +int avfilter_graph_request_oldest(AVFilterGraph *graph); + +/** + * @} + */ + +#endif /* AVFILTER_AVFILTER_H */ diff --git a/ffmpeg-n8.1/include/libavfilter/buffersink.h b/ffmpeg-n8.1/include/libavfilter/buffersink.h new file mode 100644 index 00000000..4e658a97 --- /dev/null +++ b/ffmpeg-n8.1/include/libavfilter/buffersink.h @@ -0,0 +1,172 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFILTER_BUFFERSINK_H +#define AVFILTER_BUFFERSINK_H + +/** + * @file + * @ingroup lavfi_buffersink + * memory buffer sink API for audio and video + */ + +#include "avfilter.h" + +/** + * @defgroup lavfi_buffersink Buffer sink API + * @ingroup lavfi + * @{ + * + * The buffersink and abuffersink filters are there to connect filter graphs + * to applications. They have a single input, connected to the graph, and no + * output. Frames must be extracted using av_buffersink_get_frame() or + * av_buffersink_get_samples(). + * + * The format negotiated by the graph during configuration can be obtained + * using the accessor functions: + * - av_buffersink_get_time_base(), + * - av_buffersink_get_format(), + * - av_buffersink_get_frame_rate(), + * - av_buffersink_get_w(), + * - av_buffersink_get_h(), + * - av_buffersink_get_sample_aspect_ratio(), + * - av_buffersink_get_channels(), + * - av_buffersink_get_ch_layout(), + * - av_buffersink_get_sample_rate(). + * - av_buffersink_get_side_data(). + * + * The layout returned by av_buffersink_get_ch_layout() must de uninitialized + * by the caller. + * + * The format can be constrained by setting options, using av_opt_set() and + * related functions with the AV_OPT_SEARCH_CHILDREN flag. + * - pixel_formats (array of pixel formats), + * - colorspaces (array of int), + * - colorranges (array of int), + * - alphamodes (array of int), + * - sample_formats (array of sample formats), + * - samplerates (array of int), + * - channel_layouts (array of channel layouts) + * If an option is not set, all corresponding formats are accepted. + */ + +/** + * Get a frame with filtered data from sink and put it in frame. + * + * @param ctx pointer to a buffersink or abuffersink filter context. + * @param frame pointer to an allocated frame that will be filled with data. + * The data must be freed using av_frame_unref() / av_frame_free() + * @param flags a combination of AV_BUFFERSINK_FLAG_* flags + * + * @return >= 0 in for success, a negative AVERROR code for failure. + */ +int av_buffersink_get_frame_flags(AVFilterContext *ctx, AVFrame *frame, int flags); + +/** + * Tell av_buffersink_get_buffer_ref() to read video/samples buffer + * reference, but not remove it from the buffer. This is useful if you + * need only to read a video/samples buffer, without to fetch it. + */ +#define AV_BUFFERSINK_FLAG_PEEK 1 + +/** + * Tell av_buffersink_get_buffer_ref() not to request a frame from its input. + * If a frame is already buffered, it is read (and removed from the buffer), + * but if no frame is present, return AVERROR(EAGAIN). + */ +#define AV_BUFFERSINK_FLAG_NO_REQUEST 2 + +/** + * Set the frame size for an audio buffer sink. + * + * All calls to av_buffersink_get_buffer_ref will return a buffer with + * exactly the specified number of samples, or AVERROR(EAGAIN) if there is + * not enough. The last buffer at EOF will be padded with 0. + */ +void av_buffersink_set_frame_size(AVFilterContext *ctx, unsigned frame_size); + +/** + * @defgroup lavfi_buffersink_accessors Buffer sink accessors + * Get the properties of the stream + * @{ + */ + +enum AVMediaType av_buffersink_get_type (const AVFilterContext *ctx); +AVRational av_buffersink_get_time_base (const AVFilterContext *ctx); +int av_buffersink_get_format (const AVFilterContext *ctx); + +AVRational av_buffersink_get_frame_rate (const AVFilterContext *ctx); +int av_buffersink_get_w (const AVFilterContext *ctx); +int av_buffersink_get_h (const AVFilterContext *ctx); +AVRational av_buffersink_get_sample_aspect_ratio (const AVFilterContext *ctx); +enum AVColorSpace av_buffersink_get_colorspace (const AVFilterContext *ctx); +enum AVColorRange av_buffersink_get_color_range (const AVFilterContext *ctx); +enum AVAlphaMode av_buffersink_get_alpha_mode (const AVFilterContext *ctx); + +int av_buffersink_get_channels (const AVFilterContext *ctx); +int av_buffersink_get_ch_layout (const AVFilterContext *ctx, + AVChannelLayout *ch_layout); +int av_buffersink_get_sample_rate (const AVFilterContext *ctx); + +AVBufferRef * av_buffersink_get_hw_frames_ctx (const AVFilterContext *ctx); + +const AVFrameSideData *const *av_buffersink_get_side_data(const AVFilterContext *ctx, + int *nb_side_data); + +/** @} */ + +/** + * Get a frame with filtered data from sink and put it in frame. + * + * @param ctx pointer to a context of a buffersink or abuffersink AVFilter. + * @param frame pointer to an allocated frame that will be filled with data. + * The data must be freed using av_frame_unref() / av_frame_free() + * + * @return + * - >= 0 if a frame was successfully returned. + * - AVERROR(EAGAIN) if no frames are available at this point; more + * input frames must be added to the filtergraph to get more output. + * - AVERROR_EOF if there will be no more output frames on this sink. + * - A different negative AVERROR code in other failure cases. + */ +int av_buffersink_get_frame(AVFilterContext *ctx, AVFrame *frame); + +/** + * Same as av_buffersink_get_frame(), but with the ability to specify the number + * of samples read. This function is less efficient than + * av_buffersink_get_frame(), because it copies the data around. + * + * @param ctx pointer to a context of the abuffersink AVFilter. + * @param frame pointer to an allocated frame that will be filled with data. + * The data must be freed using av_frame_unref() / av_frame_free() + * frame will contain exactly nb_samples audio samples, except at + * the end of stream, when it can contain less than nb_samples. + * + * @return The return codes have the same meaning as for + * av_buffersink_get_frame(). + * + * @warning do not mix this function with av_buffersink_get_frame(). Use only one or + * the other with a single sink, not both. + */ +int av_buffersink_get_samples(AVFilterContext *ctx, AVFrame *frame, int nb_samples); + +/** + * @} + */ + +#endif /* AVFILTER_BUFFERSINK_H */ diff --git a/ffmpeg-n8.1/include/libavfilter/buffersrc.h b/ffmpeg-n8.1/include/libavfilter/buffersrc.h new file mode 100644 index 00000000..c7225b67 --- /dev/null +++ b/ffmpeg-n8.1/include/libavfilter/buffersrc.h @@ -0,0 +1,231 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFILTER_BUFFERSRC_H +#define AVFILTER_BUFFERSRC_H + +/** + * @file + * @ingroup lavfi_buffersrc + * Memory buffer source API. + */ + +#include "avfilter.h" + +/** + * @defgroup lavfi_buffersrc Buffer source API + * @ingroup lavfi + * @{ + */ + +enum { + + /** + * Do not check for format changes. + */ + AV_BUFFERSRC_FLAG_NO_CHECK_FORMAT = 1, + + /** + * Immediately push the frame to the output. + */ + AV_BUFFERSRC_FLAG_PUSH = 4, + + /** + * Keep a reference to the frame. + * If the frame if reference-counted, create a new reference; otherwise + * copy the frame data. + */ + AV_BUFFERSRC_FLAG_KEEP_REF = 8, + +}; + +/** + * Get the number of failed requests. + * + * A failed request is when the request_frame method is called while no + * frame is present in the buffer. + * The number is reset when a frame is added. + */ +unsigned av_buffersrc_get_nb_failed_requests(AVFilterContext *buffer_src); + +/** + * This structure contains the parameters describing the frames that will be + * passed to this filter. + * + * It should be allocated with av_buffersrc_parameters_alloc() and freed with + * av_free(). All the allocated fields in it remain owned by the caller. + */ +typedef struct AVBufferSrcParameters { + /** + * video: the pixel format, value corresponds to enum AVPixelFormat + * audio: the sample format, value corresponds to enum AVSampleFormat + */ + int format; + /** + * The timebase to be used for the timestamps on the input frames. + */ + AVRational time_base; + + /** + * Video only, the display dimensions of the input frames. + */ + int width, height; + + /** + * Video only, the sample (pixel) aspect ratio. + */ + AVRational sample_aspect_ratio; + + /** + * Video only, the frame rate of the input video. This field must only be + * set to a non-zero value if input stream has a known constant framerate + * and should be left at its initial value if the framerate is variable or + * unknown. + */ + AVRational frame_rate; + + /** + * Video with a hwaccel pixel format only. This should be a reference to an + * AVHWFramesContext instance describing the input frames. + */ + AVBufferRef *hw_frames_ctx; + + /** + * Audio only, the audio sampling rate in samples per second. + */ + int sample_rate; + + /** + * Audio only, the audio channel layout + */ + AVChannelLayout ch_layout; + + /** + * Video only, the YUV colorspace and range. + */ + enum AVColorSpace color_space; + enum AVColorRange color_range; + + AVFrameSideData **side_data; + int nb_side_data; + + /** + * Video only, the alpha mode. + */ + enum AVAlphaMode alpha_mode; +} AVBufferSrcParameters; + +/** + * Allocate a new AVBufferSrcParameters instance. It should be freed by the + * caller with av_free(). + */ +AVBufferSrcParameters *av_buffersrc_parameters_alloc(void); + +/** + * Initialize the buffersrc or abuffersrc filter with the provided parameters. + * This function may be called multiple times, the later calls override the + * previous ones. Some of the parameters may also be set through AVOptions, then + * whatever method is used last takes precedence. + * + * @param ctx an instance of the buffersrc or abuffersrc filter + * @param param the stream parameters. The frames later passed to this filter + * must conform to those parameters. All the allocated fields in + * param remain owned by the caller, libavfilter will make internal + * copies or references when necessary. + * @return 0 on success, a negative AVERROR code on failure. + */ +int av_buffersrc_parameters_set(AVFilterContext *ctx, AVBufferSrcParameters *param); + +/** + * Add a frame to the buffer source. + * + * @param ctx an instance of the buffersrc filter + * @param frame frame to be added. If the frame is reference counted, this + * function will make a new reference to it. Otherwise the frame data will be + * copied. + * + * @return 0 on success, a negative AVERROR on error + * + * This function is equivalent to av_buffersrc_add_frame_flags() with the + * AV_BUFFERSRC_FLAG_KEEP_REF flag. + */ +av_warn_unused_result +int av_buffersrc_write_frame(AVFilterContext *ctx, const AVFrame *frame); + +/** + * Add a frame to the buffer source. + * + * @param ctx an instance of the buffersrc filter + * @param frame frame to be added. If the frame is reference counted, this + * function will take ownership of the reference(s) and reset the frame. + * Otherwise the frame data will be copied. If this function returns an error, + * the input frame is not touched. + * + * @return 0 on success, a negative AVERROR on error. + * + * @note the difference between this function and av_buffersrc_write_frame() is + * that av_buffersrc_write_frame() creates a new reference to the input frame, + * while this function takes ownership of the reference passed to it. + * + * This function is equivalent to av_buffersrc_add_frame_flags() without the + * AV_BUFFERSRC_FLAG_KEEP_REF flag. + */ +av_warn_unused_result +int av_buffersrc_add_frame(AVFilterContext *ctx, AVFrame *frame); + +/** + * Add a frame to the buffer source. + * + * By default, if the frame is reference-counted, this function will take + * ownership of the reference(s) and reset the frame. This can be controlled + * using the flags. + * + * If this function returns an error, the input frame is not touched. + * + * @param buffer_src pointer to a buffer source context + * @param frame a frame, or NULL to mark EOF + * @param flags a combination of AV_BUFFERSRC_FLAG_* + * @return >= 0 in case of success, a negative AVERROR code + * in case of failure + */ +av_warn_unused_result +int av_buffersrc_add_frame_flags(AVFilterContext *buffer_src, + AVFrame *frame, int flags); + +/** + * Close the buffer source after EOF. + * + * This is similar to passing NULL to av_buffersrc_add_frame_flags() + * except it takes the timestamp of the EOF, i.e. the timestamp of the end + * of the last frame. + */ +int av_buffersrc_close(AVFilterContext *ctx, int64_t pts, unsigned flags); + +/** + * Returns 0 or a negative AVERROR code. Currently, this will only ever + * return AVERROR(EOF), to indicate that the buffer source has been closed, + * either as a result of av_buffersrc_close(), or because the downstream + * filter is no longer accepting new data. + */ +int av_buffersrc_get_status(AVFilterContext *ctx); + +/** + * @} + */ + +#endif /* AVFILTER_BUFFERSRC_H */ diff --git a/ffmpeg-n8.1/include/libavfilter/version.h b/ffmpeg-n8.1/include/libavfilter/version.h new file mode 100644 index 00000000..7642b670 --- /dev/null +++ b/ffmpeg-n8.1/include/libavfilter/version.h @@ -0,0 +1,48 @@ +/* + * Version macros. + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFILTER_VERSION_H +#define AVFILTER_VERSION_H + +/** + * @file + * @ingroup lavfi + * Libavfilter version macros + */ + +#include "libavutil/version.h" + +#include "version_major.h" + +#define LIBAVFILTER_VERSION_MINOR 14 +#define LIBAVFILTER_VERSION_MICRO 100 + + +#define LIBAVFILTER_VERSION_INT AV_VERSION_INT(LIBAVFILTER_VERSION_MAJOR, \ + LIBAVFILTER_VERSION_MINOR, \ + LIBAVFILTER_VERSION_MICRO) +#define LIBAVFILTER_VERSION AV_VERSION(LIBAVFILTER_VERSION_MAJOR, \ + LIBAVFILTER_VERSION_MINOR, \ + LIBAVFILTER_VERSION_MICRO) +#define LIBAVFILTER_BUILD LIBAVFILTER_VERSION_INT + +#define LIBAVFILTER_IDENT "Lavfi" AV_STRINGIFY(LIBAVFILTER_VERSION) + +#endif /* AVFILTER_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libavfilter/version_major.h b/ffmpeg-n8.1/include/libavfilter/version_major.h new file mode 100644 index 00000000..539d5caa --- /dev/null +++ b/ffmpeg-n8.1/include/libavfilter/version_major.h @@ -0,0 +1,42 @@ +/* + * Version macros. + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFILTER_VERSION_MAJOR_H +#define AVFILTER_VERSION_MAJOR_H + +/** + * @file + * @ingroup lavfi + * Libavfilter version macros + */ + +#define LIBAVFILTER_VERSION_MAJOR 11 + +/** + * FF_API_* defines may be placed below to indicate public API that will be + * dropped at a future version bump. The defines themselves are not part of + * the public API and may change, break or disappear at any time. + */ + +#define FF_API_BUFFERSINK_OPTS (LIBAVFILTER_VERSION_MAJOR < 12) +#define FF_API_CONTEXT_PUBLIC (LIBAVFILTER_VERSION_MAJOR < 12) +#define FF_API_LIBNPP_SUPPORT (LIBAVFILTER_VERSION_MAJOR < 12) + +#endif /* AVFILTER_VERSION_MAJOR_H */ diff --git a/ffmpeg-n8.1/include/libavformat/avformat.h b/ffmpeg-n8.1/include/libavformat/avformat.h new file mode 100644 index 00000000..ee0ddddf --- /dev/null +++ b/ffmpeg-n8.1/include/libavformat/avformat.h @@ -0,0 +1,3118 @@ +/* + * copyright (c) 2001 Fabrice Bellard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFORMAT_AVFORMAT_H +#define AVFORMAT_AVFORMAT_H + +/** + * @file + * @ingroup libavf + * Main libavformat public API header + */ + +/** + * @defgroup libavf libavformat + * I/O and Muxing/Demuxing Library + * + * Libavformat (lavf) is a library for dealing with various media container + * formats. Its main two purposes are demuxing - i.e. splitting a media file + * into component streams, and the reverse process of muxing - writing supplied + * data in a specified container format. It also has an @ref lavf_io + * "I/O module" which supports a number of protocols for accessing the data (e.g. + * file, tcp, http and others). + * Unless you are absolutely sure you won't use libavformat's network + * capabilities, you should also call avformat_network_init(). + * + * A supported input format is described by an AVInputFormat struct, conversely + * an output format is described by AVOutputFormat. You can iterate over all + * input/output formats using the av_demuxer_iterate / av_muxer_iterate() functions. + * The protocols layer is not part of the public API, so you can only get the names + * of supported protocols with the avio_enum_protocols() function. + * + * Main lavf structure used for both muxing and demuxing is AVFormatContext, + * which exports all information about the file being read or written. As with + * most Libavformat structures, its size is not part of public ABI, so it cannot be + * allocated on stack or directly with av_malloc(). To create an + * AVFormatContext, use avformat_alloc_context() (some functions, like + * avformat_open_input() might do that for you). + * + * Most importantly an AVFormatContext contains: + * @li the @ref AVFormatContext.iformat "input" or @ref AVFormatContext.oformat + * "output" format. It is either autodetected or set by user for input; + * always set by user for output. + * @li an @ref AVFormatContext.streams "array" of AVStreams, which describe all + * elementary streams stored in the file. AVStreams are typically referred to + * using their index in this array. + * @li an @ref AVFormatContext.pb "I/O context". It is either opened by lavf or + * set by user for input, always set by user for output (unless you are dealing + * with an AVFMT_NOFILE format). + * + * @section lavf_options Passing options to (de)muxers + * It is possible to configure lavf muxers and demuxers using the @ref avoptions + * mechanism. Generic (format-independent) libavformat options are provided by + * AVFormatContext, they can be examined from a user program by calling + * av_opt_next() / av_opt_find() on an allocated AVFormatContext (or its AVClass + * from avformat_get_class()). Private (format-specific) options are provided by + * AVFormatContext.priv_data if and only if AVInputFormat.priv_class / + * AVOutputFormat.priv_class of the corresponding format struct is non-NULL. + * Further options may be provided by the @ref AVFormatContext.pb "I/O context", + * if its AVClass is non-NULL, and the protocols layer. See the discussion on + * nesting in @ref avoptions documentation to learn how to access those. + * + * @section urls + * URL strings in libavformat are made of a scheme/protocol, a ':', and a + * scheme specific string. URLs without a scheme and ':' used for local files + * are supported but deprecated. "file:" should be used for local files. + * + * It is important that the scheme string is not taken from untrusted + * sources without checks. + * + * Note that some schemes/protocols are quite powerful, allowing access to + * both local and remote files, parts of them, concatenations of them, local + * audio and video devices and so on. + * + * @{ + * + * @defgroup lavf_decoding Demuxing + * @{ + * Demuxers read a media file and split it into chunks of data (@em packets). A + * @ref AVPacket "packet" contains one or more encoded frames which belongs to a + * single elementary stream. In the lavf API this process is represented by the + * avformat_open_input() function for opening a file, av_read_frame() for + * reading a single packet and finally avformat_close_input(), which does the + * cleanup. + * + * @section lavf_decoding_open Opening a media file + * The minimum information required to open a file is its URL, which + * is passed to avformat_open_input(), as in the following code: + * @code + * const char *url = "file:in.mp3"; + * AVFormatContext *s = NULL; + * int ret = avformat_open_input(&s, url, NULL, NULL); + * if (ret < 0) + * abort(); + * @endcode + * The above code attempts to allocate an AVFormatContext, open the + * specified file (autodetecting the format) and read the header, exporting the + * information stored there into s. Some formats do not have a header or do not + * store enough information there, so it is recommended that you call the + * avformat_find_stream_info() function which tries to read and decode a few + * frames to find missing information. + * + * In some cases you might want to preallocate an AVFormatContext yourself with + * avformat_alloc_context() and do some tweaking on it before passing it to + * avformat_open_input(). One such case is when you want to use custom functions + * for reading input data instead of lavf internal I/O layer. + * To do that, create your own AVIOContext with avio_alloc_context(), passing + * your reading callbacks to it. Then set the @em pb field of your + * AVFormatContext to newly created AVIOContext. + * + * Since the format of the opened file is in general not known until after + * avformat_open_input() has returned, it is not possible to set demuxer private + * options on a preallocated context. Instead, the options should be passed to + * avformat_open_input() wrapped in an AVDictionary: + * @code + * AVDictionary *options = NULL; + * av_dict_set(&options, "video_size", "640x480", 0); + * av_dict_set(&options, "pixel_format", "rgb24", 0); + * + * if (avformat_open_input(&s, url, NULL, &options) < 0) + * abort(); + * av_dict_free(&options); + * @endcode + * This code passes the private options 'video_size' and 'pixel_format' to the + * demuxer. They would be necessary for e.g. the rawvideo demuxer, since it + * cannot know how to interpret raw video data otherwise. If the format turns + * out to be something different than raw video, those options will not be + * recognized by the demuxer and therefore will not be applied. Such unrecognized + * options are then returned in the options dictionary (recognized options are + * consumed). The calling program can handle such unrecognized options as it + * wishes, e.g. + * @code + * const AVDictionaryEntry *e; + * if ((e = av_dict_iterate(options, NULL))) { + * fprintf(stderr, "Option %s not recognized by the demuxer.\n", e->key); + * abort(); + * } + * @endcode + * + * After you have finished reading the file, you must close it with + * avformat_close_input(). It will free everything associated with the file. + * + * @section lavf_decoding_read Reading from an opened file + * Reading data from an opened AVFormatContext is done by repeatedly calling + * av_read_frame() on it. Each call, if successful, will return an AVPacket + * containing encoded data for one AVStream, identified by + * AVPacket.stream_index. This packet may be passed straight into the libavcodec + * decoding functions avcodec_send_packet() or avcodec_decode_subtitle2() if the + * caller wishes to decode the data. + * + * AVPacket.pts, AVPacket.dts and AVPacket.duration timing information will be + * set if known. They may also be unset (i.e. AV_NOPTS_VALUE for + * pts/dts, 0 for duration) if the stream does not provide them. The timing + * information will be in AVStream.time_base units, i.e. it has to be + * multiplied by the timebase to convert them to seconds. + * + * A packet returned by av_read_frame() is always reference-counted, + * i.e. AVPacket.buf is set and the user may keep it indefinitely. + * The packet must be freed with av_packet_unref() when it is no + * longer needed. + * + * @section lavf_decoding_seek Seeking + * @} + * + * @defgroup lavf_encoding Muxing + * @{ + * Muxers take encoded data in the form of @ref AVPacket "AVPackets" and write + * it into files or other output bytestreams in the specified container format. + * + * The main API functions for muxing are avformat_write_header() for writing the + * file header, av_write_frame() / av_interleaved_write_frame() for writing the + * packets and av_write_trailer() for finalizing the file. + * + * At the beginning of the muxing process, the caller must first call + * avformat_alloc_context() to create a muxing context. The caller then sets up + * the muxer by filling the various fields in this context: + * + * - The @ref AVFormatContext.oformat "oformat" field must be set to select the + * muxer that will be used. + * - Unless the format is of the AVFMT_NOFILE type, the @ref AVFormatContext.pb + * "pb" field must be set to an opened IO context, either returned from + * avio_open2() or a custom one. + * - Unless the format is of the AVFMT_NOSTREAMS type, at least one stream must + * be created with the avformat_new_stream() function. The caller should fill + * the @ref AVStream.codecpar "stream codec parameters" information, such as the + * codec @ref AVCodecParameters.codec_type "type", @ref AVCodecParameters.codec_id + * "id" and other parameters (e.g. width / height, the pixel or sample format, + * etc.) as known. The @ref AVStream.time_base "stream timebase" should + * be set to the timebase that the caller desires to use for this stream (note + * that the timebase actually used by the muxer can be different, as will be + * described later). + * - It is advised to manually initialize only the relevant fields in + * AVCodecParameters, rather than using @ref avcodec_parameters_copy() during + * remuxing: there is no guarantee that the codec context values remain valid + * for both input and output format contexts. + * - The caller may fill in additional information, such as @ref + * AVFormatContext.metadata "global" or @ref AVStream.metadata "per-stream" + * metadata, @ref AVFormatContext.chapters "chapters", @ref + * AVFormatContext.programs "programs", etc. as described in the + * AVFormatContext documentation. Whether such information will actually be + * stored in the output depends on what the container format and the muxer + * support. + * + * When the muxing context is fully set up, the caller must call + * avformat_write_header() to initialize the muxer internals and write the file + * header. Whether anything actually is written to the IO context at this step + * depends on the muxer, but this function must always be called. Any muxer + * private options must be passed in the options parameter to this function. + * + * The data is then sent to the muxer by repeatedly calling av_write_frame() or + * av_interleaved_write_frame() (consult those functions' documentation for + * discussion on the difference between them; only one of them may be used with + * a single muxing context, they should not be mixed). Do note that the timing + * information on the packets sent to the muxer must be in the corresponding + * AVStream's timebase. That timebase is set by the muxer (in the + * avformat_write_header() step) and may be different from the timebase + * requested by the caller. + * + * Once all the data has been written, the caller must call av_write_trailer() + * to flush any buffered packets and finalize the output file, then close the IO + * context (if any) and finally free the muxing context with + * avformat_free_context(). + * @} + * + * @defgroup lavf_io I/O Read/Write + * @{ + * @section lavf_io_dirlist Directory listing + * The directory listing API makes it possible to list files on remote servers. + * + * Some of possible use cases: + * - an "open file" dialog to choose files from a remote location, + * - a recursive media finder providing a player with an ability to play all + * files from a given directory. + * + * @subsection lavf_io_dirlist_open Opening a directory + * At first, a directory needs to be opened by calling avio_open_dir() + * supplied with a URL and, optionally, ::AVDictionary containing + * protocol-specific parameters. The function returns zero or positive + * integer and allocates AVIODirContext on success. + * + * @code + * AVIODirContext *ctx = NULL; + * if (avio_open_dir(&ctx, "smb://example.com/some_dir", NULL) < 0) { + * fprintf(stderr, "Cannot open directory.\n"); + * abort(); + * } + * @endcode + * + * This code tries to open a sample directory using smb protocol without + * any additional parameters. + * + * @subsection lavf_io_dirlist_read Reading entries + * Each directory's entry (i.e. file, another directory, anything else + * within ::AVIODirEntryType) is represented by AVIODirEntry. + * Reading consecutive entries from an opened AVIODirContext is done by + * repeatedly calling avio_read_dir() on it. Each call returns zero or + * positive integer if successful. Reading can be stopped right after the + * NULL entry has been read -- it means there are no entries left to be + * read. The following code reads all entries from a directory associated + * with ctx and prints their names to standard output. + * @code + * AVIODirEntry *entry = NULL; + * for (;;) { + * if (avio_read_dir(ctx, &entry) < 0) { + * fprintf(stderr, "Cannot list directory.\n"); + * abort(); + * } + * if (!entry) + * break; + * printf("%s\n", entry->name); + * avio_free_directory_entry(&entry); + * } + * @endcode + * @} + * + * @defgroup lavf_codec Demuxers + * @{ + * @defgroup lavf_codec_native Native Demuxers + * @{ + * @} + * @defgroup lavf_codec_wrappers External library wrappers + * @{ + * @} + * @} + * @defgroup lavf_protos I/O Protocols + * @{ + * @} + * @defgroup lavf_internal Internal + * @{ + * @} + * @} + */ + +#include /* FILE */ + +#include "libavcodec/codec_par.h" +#include "libavcodec/defs.h" +#include "libavcodec/packet.h" + +#include "libavutil/dict.h" +#include "libavutil/log.h" + +#include "avio.h" +#include "libavformat/version_major.h" +#ifndef HAVE_AV_CONFIG_H +/* When included as part of the ffmpeg build, only include the major version + * to avoid unnecessary rebuilds. When included externally, keep including + * the full version information. */ +#include "libavformat/version.h" + +#include "libavutil/frame.h" +#include "libavcodec/codec.h" +#endif + +struct AVFormatContext; +struct AVFrame; + +/** + * @defgroup metadata_api Public Metadata API + * @{ + * @ingroup libavf + * The metadata API allows libavformat to export metadata tags to a client + * application when demuxing. Conversely it allows a client application to + * set metadata when muxing. + * + * Metadata is exported or set as pairs of key/value strings in the 'metadata' + * fields of the AVFormatContext, AVStream, AVChapter and AVProgram structs + * using the @ref lavu_dict "AVDictionary" API. Like all strings in FFmpeg, + * metadata is assumed to be UTF-8 encoded Unicode. Note that metadata + * exported by demuxers isn't checked to be valid UTF-8 in most cases. + * + * Important concepts to keep in mind: + * - Keys are unique; there can never be 2 tags with the same key. This is + * also meant semantically, i.e., a demuxer should not knowingly produce + * several keys that are literally different but semantically identical. + * E.g., key=Author5, key=Author6. In this example, all authors must be + * placed in the same tag. + * - Metadata is flat, not hierarchical; there are no subtags. If you + * want to store, e.g., the email address of the child of producer Alice + * and actor Bob, that could have key=alice_and_bobs_childs_email_address. + * - Several modifiers can be applied to the tag name. This is done by + * appending a dash character ('-') and the modifier name in the order + * they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng. + * - language -- a tag whose value is localized for a particular language + * is appended with the ISO 639-2/B 3-letter language code. + * For example: Author-ger=Michael, Author-eng=Mike + * The original/default language is in the unqualified "Author" tag. + * A demuxer should set a default if it sets any translated tag. + * - sorting -- a modified version of a tag that should be used for + * sorting will have '-sort' appended. E.g. artist="The Beatles", + * artist-sort="Beatles, The". + * - Some protocols and demuxers support metadata updates. After a successful + * call to av_read_frame(), AVFormatContext.event_flags or AVStream.event_flags + * will be updated to indicate if metadata changed. In order to detect metadata + * changes on a stream, you need to loop through all streams in the AVFormatContext + * and check their individual event_flags. + * + * - Demuxers attempt to export metadata in a generic format, however tags + * with no generic equivalents are left as they are stored in the container. + * Follows a list of generic tag names: + * + @verbatim + album -- name of the set this work belongs to + album_artist -- main creator of the set/album, if different from artist. + e.g. "Various Artists" for compilation albums. + artist -- main creator of the work + comment -- any additional description of the file. + composer -- who composed the work, if different from artist. + copyright -- name of copyright holder. + creation_time-- date when the file was created, preferably in ISO 8601. + date -- date when the work was created, preferably in ISO 8601. + disc -- number of a subset, e.g. disc in a multi-disc collection. + encoder -- name/settings of the software/hardware that produced the file. + encoded_by -- person/group who created the file. + filename -- original name of the file. + genre -- . + language -- main language in which the work is performed, preferably + in ISO 639-2 format. Multiple languages can be specified by + separating them with commas. + performer -- artist who performed the work, if different from artist. + E.g for "Also sprach Zarathustra", artist would be "Richard + Strauss" and performer "London Philharmonic Orchestra". + publisher -- name of the label/publisher. + service_name -- name of the service in broadcasting (channel name). + service_provider -- name of the service provider in broadcasting. + title -- name of the work. + track -- number of this work in the set, can be in form current/total. + variant_bitrate -- the total bitrate of the bitrate variant that the current stream is part of + @endverbatim + * + * Look in the examples section for an application example how to use the Metadata API. + * + * @} + */ + +/* packet functions */ + + +/** + * Allocate and read the payload of a packet and initialize its + * fields with default values. + * + * @param s associated IO context + * @param pkt packet + * @param size desired payload size + * @return >0 (read size) if OK, AVERROR_xxx otherwise + */ +int av_get_packet(AVIOContext *s, AVPacket *pkt, int size); + + +/** + * Read data and append it to the current content of the AVPacket. + * If pkt->size is 0 this is identical to av_get_packet. + * Note that this uses av_grow_packet and thus involves a realloc + * which is inefficient. Thus this function should only be used + * when there is no reasonable way to know (an upper bound of) + * the final size. + * + * @param s associated IO context + * @param pkt packet + * @param size amount of data to read + * @return >0 (read size) if OK, AVERROR_xxx otherwise, previous data + * will not be lost even if an error occurs. + */ +int av_append_packet(AVIOContext *s, AVPacket *pkt, int size); + +/*************************************************/ +/* input/output formats */ + +struct AVCodecTag; + +/** + * This structure contains the data a format has to probe a file. + */ +typedef struct AVProbeData { + const char *filename; + unsigned char *buf; /**< Buffer must have AVPROBE_PADDING_SIZE of extra allocated bytes filled with zero. */ + int buf_size; /**< Size of buf except extra allocated bytes */ + const char *mime_type; /**< mime_type, when known. */ +} AVProbeData; + +#define AVPROBE_SCORE_RETRY (AVPROBE_SCORE_MAX/4) +#define AVPROBE_SCORE_STREAM_RETRY (AVPROBE_SCORE_MAX/4-1) + +#define AVPROBE_SCORE_EXTENSION 50 ///< score for file extension +#define AVPROBE_SCORE_MIME_BONUS 30 ///< score added for matching mime type +#define AVPROBE_SCORE_MAX 100 ///< maximum score + +#define AVPROBE_PADDING_SIZE 32 ///< extra allocated bytes at the end of the probe buffer + +/// Demuxer will use avio_open, no opened file should be provided by the caller. +#define AVFMT_NOFILE 0x0001 +#define AVFMT_NEEDNUMBER 0x0002 /**< Needs '%d' in filename. */ +/** + * The muxer/demuxer is experimental and should be used with caution. + * + * It will not be selected automatically, and must be specified explicitly. + */ +#define AVFMT_EXPERIMENTAL 0x0004 +#define AVFMT_SHOW_IDS 0x0008 /**< Show format stream IDs numbers. */ +#define AVFMT_GLOBALHEADER 0x0040 /**< Format wants global header. */ +#define AVFMT_NOTIMESTAMPS 0x0080 /**< Format does not need / have any timestamps. */ +#define AVFMT_GENERIC_INDEX 0x0100 /**< Use generic index building code. */ +#define AVFMT_TS_DISCONT 0x0200 /**< Format allows timestamp discontinuities. Note, muxers always require valid (monotone) timestamps */ +#define AVFMT_VARIABLE_FPS 0x0400 /**< Format allows variable fps. */ +#define AVFMT_NODIMENSIONS 0x0800 /**< Format does not need width/height */ +#define AVFMT_NOSTREAMS 0x1000 /**< Format does not require any streams */ +#define AVFMT_NOBINSEARCH 0x2000 /**< Format does not allow to fall back on binary search via read_timestamp */ +#define AVFMT_NOGENSEARCH 0x4000 /**< Format does not allow to fall back on generic search */ +#define AVFMT_NO_BYTE_SEEK 0x8000 /**< Format does not allow seeking by bytes */ +#define AVFMT_TS_NONSTRICT 0x20000 /**< Format does not require strictly + increasing timestamps, but they must + still be monotonic */ +#define AVFMT_TS_NEGATIVE 0x40000 /**< Format allows muxing negative + timestamps. If not set the timestamp + will be shifted in av_write_frame and + av_interleaved_write_frame so they + start from 0. + The user or muxer can override this through + AVFormatContext.avoid_negative_ts + */ + +#define AVFMT_SEEK_TO_PTS 0x4000000 /**< Seeking is based on PTS */ + +/** + * @addtogroup lavf_encoding + * @{ + */ +typedef struct AVOutputFormat { + const char *name; + /** + * Descriptive name for the format, meant to be more human-readable + * than name. You should use the NULL_IF_CONFIG_SMALL() macro + * to define it. + */ + const char *long_name; + const char *mime_type; + const char *extensions; /**< comma-separated filename extensions */ + /* output support */ + enum AVCodecID audio_codec; /**< default audio codec */ + enum AVCodecID video_codec; /**< default video codec */ + enum AVCodecID subtitle_codec; /**< default subtitle codec */ + /** + * can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, + * AVFMT_GLOBALHEADER, AVFMT_NOTIMESTAMPS, AVFMT_VARIABLE_FPS, + * AVFMT_NODIMENSIONS, AVFMT_NOSTREAMS, + * AVFMT_TS_NONSTRICT, AVFMT_TS_NEGATIVE + */ + int flags; + + /** + * List of supported codec_id-codec_tag pairs, ordered by "better + * choice first". The arrays are all terminated by AV_CODEC_ID_NONE. + */ + const struct AVCodecTag * const *codec_tag; + + + const AVClass *priv_class; ///< AVClass for the private context +} AVOutputFormat; +/** + * @} + */ + +/** + * @addtogroup lavf_decoding + * @{ + */ +typedef struct AVInputFormat { + /** + * A comma separated list of short names for the format. New names + * may be appended with a minor bump. + */ + const char *name; + + /** + * Descriptive name for the format, meant to be more human-readable + * than name. You should use the NULL_IF_CONFIG_SMALL() macro + * to define it. + */ + const char *long_name; + + /** + * Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_SHOW_IDS, + * AVFMT_NOTIMESTAMPS, AVFMT_GENERIC_INDEX, AVFMT_TS_DISCONT, AVFMT_NOBINSEARCH, + * AVFMT_NOGENSEARCH, AVFMT_NO_BYTE_SEEK, AVFMT_SEEK_TO_PTS. + */ + int flags; + + /** + * If extensions are defined, then no probe is done. You should + * usually not use extension format guessing because it is not + * reliable enough + */ + const char *extensions; + + const struct AVCodecTag * const *codec_tag; + + const AVClass *priv_class; ///< AVClass for the private context + + /** + * Comma-separated list of mime types. + * It is used check for matching mime types while probing. + * @see av_probe_input_format2 + */ + const char *mime_type; +} AVInputFormat; +/** + * @} + */ + +enum AVStreamParseType { + AVSTREAM_PARSE_NONE, + AVSTREAM_PARSE_FULL, /**< full parsing and repack */ + AVSTREAM_PARSE_HEADERS, /**< Only parse headers, do not repack. */ + AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on a packet boundary */ + AVSTREAM_PARSE_FULL_ONCE, /**< full parsing and repack of the first frame only, only implemented for H.264 currently */ + AVSTREAM_PARSE_FULL_RAW, /**< full parsing and repack with timestamp and position generation by parser for raw + this assumes that each packet in the file contains no demuxer level headers and + just codec level data, otherwise position generation would fail */ +}; + +typedef struct AVIndexEntry { + int64_t pos; + int64_t timestamp; /**< + * Timestamp in AVStream.time_base units, preferably the time from which on correctly decoded frames are available + * when seeking to this entry. That means preferable PTS on keyframe based formats. + * But demuxers can choose to store a different timestamp, if it is more convenient for the implementation or nothing better + * is known + */ +#define AVINDEX_KEYFRAME 0x0001 +#define AVINDEX_DISCARD_FRAME 0x0002 /** + * Flag is used to indicate which frame should be discarded after decoding. + */ + int flags:2; + int size:30; //Yeah, trying to keep the size of this small to reduce memory requirements (it is 24 vs. 32 bytes due to possible 8-byte alignment). + int min_distance; /**< Minimum distance between this and the previous keyframe, used to avoid unneeded searching. */ +} AVIndexEntry; + +/** + * The stream should be chosen by default among other streams of the same type, + * unless the user has explicitly specified otherwise. + */ +#define AV_DISPOSITION_DEFAULT (1 << 0) +/** + * The stream is not in original language. + * + * @note AV_DISPOSITION_ORIGINAL is the inverse of this disposition. At most + * one of them should be set in properly tagged streams. + * @note This disposition may apply to any stream type, not just audio. + */ +#define AV_DISPOSITION_DUB (1 << 1) +/** + * The stream is in original language. + * + * @see the notes for AV_DISPOSITION_DUB + */ +#define AV_DISPOSITION_ORIGINAL (1 << 2) +/** + * The stream is a commentary track. + */ +#define AV_DISPOSITION_COMMENT (1 << 3) +/** + * The stream contains song lyrics. + */ +#define AV_DISPOSITION_LYRICS (1 << 4) +/** + * The stream contains karaoke audio. + */ +#define AV_DISPOSITION_KARAOKE (1 << 5) + +/** + * Track should be used during playback by default. + * Useful for subtitle track that should be displayed + * even when user did not explicitly ask for subtitles. + */ +#define AV_DISPOSITION_FORCED (1 << 6) +/** + * The stream is intended for hearing impaired audiences. + */ +#define AV_DISPOSITION_HEARING_IMPAIRED (1 << 7) +/** + * The stream is intended for visually impaired audiences. + */ +#define AV_DISPOSITION_VISUAL_IMPAIRED (1 << 8) +/** + * The audio stream contains music and sound effects without voice. + */ +#define AV_DISPOSITION_CLEAN_EFFECTS (1 << 9) +/** + * The stream is stored in the file as an attached picture/"cover art" (e.g. + * APIC frame in ID3v2). The first (usually only) packet associated with it + * will be returned among the first few packets read from the file unless + * seeking takes place. It can also be accessed at any time in + * AVStream.attached_pic. + */ +#define AV_DISPOSITION_ATTACHED_PIC (1 << 10) +/** + * The stream is sparse, and contains thumbnail images, often corresponding + * to chapter markers. Only ever used with AV_DISPOSITION_ATTACHED_PIC. + */ +#define AV_DISPOSITION_TIMED_THUMBNAILS (1 << 11) + +/** + * The stream is intended to be mixed with a spatial audio track. For example, + * it could be used for narration or stereo music, and may remain unchanged by + * listener head rotation. + */ +#define AV_DISPOSITION_NON_DIEGETIC (1 << 12) + +/** + * The subtitle stream contains captions, providing a transcription and possibly + * a translation of audio. Typically intended for hearing-impaired audiences. + */ +#define AV_DISPOSITION_CAPTIONS (1 << 16) +/** + * The subtitle stream contains a textual description of the video content. + * Typically intended for visually-impaired audiences or for the cases where the + * video cannot be seen. + */ +#define AV_DISPOSITION_DESCRIPTIONS (1 << 17) +/** + * The subtitle stream contains time-aligned metadata that is not intended to be + * directly presented to the user. + */ +#define AV_DISPOSITION_METADATA (1 << 18) +/** + * The stream is intended to be mixed with another stream before presentation. + * Used for example to signal the stream contains an image part of a HEIF grid, + * or for mix_type=0 in mpegts. + */ +#define AV_DISPOSITION_DEPENDENT (1 << 19) +/** + * The video stream contains still images. + */ +#define AV_DISPOSITION_STILL_IMAGE (1 << 20) +/** + * The video stream contains multiple layers, e.g. stereoscopic views (cf. H.264 + * Annex G/H, or HEVC Annex F). + */ +#define AV_DISPOSITION_MULTILAYER (1 << 21) + +/** + * @return The AV_DISPOSITION_* flag corresponding to disp or a negative error + * code if disp does not correspond to a known stream disposition. + */ +int av_disposition_from_string(const char *disp); + +/** + * @param disposition a combination of AV_DISPOSITION_* values + * @return The string description corresponding to the lowest set bit in + * disposition. NULL when the lowest set bit does not correspond + * to a known disposition or when disposition is 0. + */ +const char *av_disposition_to_string(int disposition); + +/** + * Options for behavior on timestamp wrap detection. + */ +#define AV_PTS_WRAP_IGNORE 0 ///< ignore the wrap +#define AV_PTS_WRAP_ADD_OFFSET 1 ///< add the format specific offset on wrap detection +#define AV_PTS_WRAP_SUB_OFFSET -1 ///< subtract the format specific offset on wrap detection + +/** + * Stream structure. + * New fields can be added to the end with minor version bumps. + * Removal, reordering and changes to existing fields require a major + * version bump. + * sizeof(AVStream) must not be used outside libav*. + */ +typedef struct AVStream { + /** + * A class for @ref avoptions. Set on stream creation. + */ + const AVClass *av_class; + + int index; /**< stream index in AVFormatContext */ + /** + * Format-specific stream ID. + * decoding: set by libavformat + * encoding: set by the user, replaced by libavformat if left unset + */ + int id; + + /** + * Codec parameters associated with this stream. Allocated and freed by + * libavformat in avformat_new_stream() and avformat_free_context() + * respectively. + * + * - demuxing: filled by libavformat on stream creation or in + * avformat_find_stream_info() + * - muxing: filled by the caller before avformat_write_header() + */ + AVCodecParameters *codecpar; + + void *priv_data; + + /** + * This is the fundamental unit of time (in seconds) in terms + * of which frame timestamps are represented. + * + * decoding: set by libavformat + * encoding: May be set by the caller before avformat_write_header() to + * provide a hint to the muxer about the desired timebase. In + * avformat_write_header(), the muxer will overwrite this field + * with the timebase that will actually be used for the timestamps + * written into the file (which may or may not be related to the + * user-provided one, depending on the format). + */ + AVRational time_base; + + /** + * Decoding: pts of the first frame of the stream in presentation order, in stream time base. + * Only set this if you are absolutely 100% sure that the value you set + * it to really is the pts of the first frame. + * This may be undefined (AV_NOPTS_VALUE). + * @note The ASF header does NOT contain a correct start_time the ASF + * demuxer must NOT set this. + */ + int64_t start_time; + + /** + * Decoding: duration of the stream, in stream time base. + * If a source file does not specify a duration, but does specify + * a bitrate, this value will be estimated from bitrate and file size. + * + * Encoding: May be set by the caller before avformat_write_header() to + * provide a hint to the muxer about the estimated duration. + */ + int64_t duration; + + int64_t nb_frames; ///< number of frames in this stream if known or 0 + + /** + * Stream disposition - a combination of AV_DISPOSITION_* flags. + * - demuxing: set by libavformat when creating the stream or in + * avformat_find_stream_info(). + * - muxing: may be set by the caller before avformat_write_header(). + */ + int disposition; + + enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed. + + /** + * sample aspect ratio (0 if unknown) + * - encoding: Set by user. + * - decoding: Set by libavformat. + */ + AVRational sample_aspect_ratio; + + AVDictionary *metadata; + + /** + * Average framerate + * + * - demuxing: May be set by libavformat when creating the stream or in + * avformat_find_stream_info(). + * - muxing: May be set by the caller before avformat_write_header(). + */ + AVRational avg_frame_rate; + + /** + * For streams with AV_DISPOSITION_ATTACHED_PIC disposition, this packet + * will contain the attached picture. + * + * decoding: set by libavformat, must not be modified by the caller. + * encoding: unused + */ + AVPacket attached_pic; + + /** + * Flags indicating events happening on the stream, a combination of + * AVSTREAM_EVENT_FLAG_*. + * + * - demuxing: may be set by the demuxer in avformat_open_input(), + * avformat_find_stream_info() and av_read_frame(). Flags must be cleared + * by the user once the event has been handled. + * - muxing: may be set by the user after avformat_write_header(). to + * indicate a user-triggered event. The muxer will clear the flags for + * events it has handled in av_[interleaved]_write_frame(). + */ + int event_flags; +/** + * - demuxing: the demuxer read new metadata from the file and updated + * AVStream.metadata accordingly + * - muxing: the user updated AVStream.metadata and wishes the muxer to write + * it into the file + */ +#define AVSTREAM_EVENT_FLAG_METADATA_UPDATED 0x0001 +/** + * - demuxing: new packets for this stream were read from the file. This + * event is informational only and does not guarantee that new packets + * for this stream will necessarily be returned from av_read_frame(). + */ +#define AVSTREAM_EVENT_FLAG_NEW_PACKETS (1 << 1) + + /** + * Real base framerate of the stream. + * This is the lowest framerate with which all timestamps can be + * represented accurately (it is the least common multiple of all + * framerates in the stream). Note, this value is just a guess! + * For example, if the time base is 1/90000 and all frames have either + * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1. + */ + AVRational r_frame_rate; + + /** + * Number of bits in timestamps. Used for wrapping control. + * + * - demuxing: set by libavformat + * - muxing: set by libavformat + * + */ + int pts_wrap_bits; +} AVStream; + +/** + * AVStreamGroupTileGrid holds information on how to combine several + * independent images on a single canvas for presentation. + * + * The output should be a @ref AVStreamGroupTileGrid.background "background" + * colored @ref AVStreamGroupTileGrid.coded_width "coded_width" x + * @ref AVStreamGroupTileGrid.coded_height "coded_height" canvas where a + * @ref AVStreamGroupTileGrid.nb_tiles "nb_tiles" amount of tiles are placed in + * the order they appear in the @ref AVStreamGroupTileGrid.offsets "offsets" + * array, at the exact offset described for them. In particular, if two or more + * tiles overlap, the image with higher index in the + * @ref AVStreamGroupTileGrid.offsets "offsets" array takes priority. + * Note that a single image may be used multiple times, i.e. multiple entries + * in @ref AVStreamGroupTileGrid.offsets "offsets" may have the same value of + * idx. + * + * The following is an example of a simple grid with 3 rows and 4 columns: + * + * +---+---+---+---+ + * | 0 | 1 | 2 | 3 | + * +---+---+---+---+ + * | 4 | 5 | 6 | 7 | + * +---+---+---+---+ + * | 8 | 9 |10 |11 | + * +---+---+---+---+ + * + * Assuming all tiles have a dimension of 512x512, the + * @ref AVStreamGroupTileGrid.offsets "offset" of the topleft pixel of + * the first @ref AVStreamGroup.streams "stream" in the group is "0,0", the + * @ref AVStreamGroupTileGrid.offsets "offset" of the topleft pixel of + * the second @ref AVStreamGroup.streams "stream" in the group is "512,0", the + * @ref AVStreamGroupTileGrid.offsets "offset" of the topleft pixel of + * the fifth @ref AVStreamGroup.streams "stream" in the group is "0,512", the + * @ref AVStreamGroupTileGrid.offsets "offset", of the topleft pixel of + * the sixth @ref AVStreamGroup.streams "stream" in the group is "512,512", + * etc. + * + * The following is an example of a canvas with overlapping tiles: + * + * +-----------+ + * | %%%%% | + * |***%%3%%@@@| + * |**0%%%%%2@@| + * |***##1@@@@@| + * | ##### | + * +-----------+ + * + * Assuming a canvas with size 1024x1024 and all tiles with a dimension of + * 512x512, a possible @ref AVStreamGroupTileGrid.offsets "offset" for the + * topleft pixel of the first @ref AVStreamGroup.streams "stream" in the group + * would be 0x256, the @ref AVStreamGroupTileGrid.offsets "offset" for the + * topleft pixel of the second @ref AVStreamGroup.streams "stream" in the group + * would be 256x512, the @ref AVStreamGroupTileGrid.offsets "offset" for the + * topleft pixel of the third @ref AVStreamGroup.streams "stream" in the group + * would be 512x256, and the @ref AVStreamGroupTileGrid.offsets "offset" for + * the topleft pixel of the fourth @ref AVStreamGroup.streams "stream" in the + * group would be 256x0. + * + * sizeof(AVStreamGroupTileGrid) is not a part of the ABI and may only be + * allocated by avformat_stream_group_create(). + */ +typedef struct AVStreamGroupTileGrid { + const AVClass *av_class; + + /** + * Amount of tiles in the grid. + * + * Must be > 0. + */ + unsigned int nb_tiles; + + /** + * Width of the canvas. + * + * Must be > 0. + */ + int coded_width; + /** + * Width of the canvas. + * + * Must be > 0. + */ + int coded_height; + + /** + * An @ref nb_tiles sized array of offsets in pixels from the topleft edge + * of the canvas, indicating where each stream should be placed. + * It must be allocated with the av_malloc() family of functions. + * + * - demuxing: set by libavformat, must not be modified by the caller. + * - muxing: set by the caller before avformat_write_header(). + * + * Freed by libavformat in avformat_free_context(). + */ + struct { + /** + * Index of the stream in the group this tile references. + * + * Must be < @ref AVStreamGroup.nb_streams "nb_streams". + */ + unsigned int idx; + /** + * Offset in pixels from the left edge of the canvas where the tile + * should be placed. + */ + int horizontal; + /** + * Offset in pixels from the top edge of the canvas where the tile + * should be placed. + */ + int vertical; + } *offsets; + + /** + * The pixel value per channel in RGBA format used if no pixel of any tile + * is located at a particular pixel location. + * + * @see av_image_fill_color(). + * @see av_parse_color(). + */ + uint8_t background[4]; + + /** + * Offset in pixels from the left edge of the canvas where the actual image + * meant for presentation starts. + * + * This field must be >= 0 and < @ref coded_width. + */ + int horizontal_offset; + /** + * Offset in pixels from the top edge of the canvas where the actual image + * meant for presentation starts. + * + * This field must be >= 0 and < @ref coded_height. + */ + int vertical_offset; + + /** + * Width of the final image for presentation. + * + * Must be > 0 and <= (@ref coded_width - @ref horizontal_offset). + * When it's not equal to (@ref coded_width - @ref horizontal_offset), the + * result of (@ref coded_width - width - @ref horizontal_offset) is the + * amount amount of pixels to be cropped from the right edge of the + * final image before presentation. + */ + int width; + /** + * Height of the final image for presentation. + * + * Must be > 0 and <= (@ref coded_height - @ref vertical_offset). + * When it's not equal to (@ref coded_height - @ref vertical_offset), the + * result of (@ref coded_height - height - @ref vertical_offset) is the + * amount amount of pixels to be cropped from the bottom edge of the + * final image before presentation. + */ + int height; + + /** + * Additional data associated with the grid. + * + * Should be allocated with av_packet_side_data_new() or + * av_packet_side_data_add(), and will be freed by avformat_free_context(). + */ + AVPacketSideData *coded_side_data; + + /** + * Amount of entries in @ref coded_side_data. + */ + int nb_coded_side_data; +} AVStreamGroupTileGrid; + +/** + * AVStreamGroupLCEVC is meant to define the relation between video streams + * and a data stream containing LCEVC enhancement layer NALUs. + * + * No more than one stream of + * @ref AVCodecParameters.codec_id "codec_id" AV_CODEC_ID_LCEVC shall be present. + */ +typedef struct AVStreamGroupLCEVC { + const AVClass *av_class; + + /** + * Index of the LCEVC data stream in AVStreamGroup. + */ + unsigned int lcevc_index; + /** + * Width of the final stream for presentation. + */ + int width; + /** + * Height of the final image for presentation. + */ + int height; +} AVStreamGroupLCEVC; + +enum AVStreamGroupParamsType { + AV_STREAM_GROUP_PARAMS_NONE, + AV_STREAM_GROUP_PARAMS_IAMF_AUDIO_ELEMENT, + AV_STREAM_GROUP_PARAMS_IAMF_MIX_PRESENTATION, + AV_STREAM_GROUP_PARAMS_TILE_GRID, + AV_STREAM_GROUP_PARAMS_LCEVC, +}; + +struct AVIAMFAudioElement; +struct AVIAMFMixPresentation; + +typedef struct AVStreamGroup { + /** + * A class for @ref avoptions. Set by avformat_stream_group_create(). + */ + const AVClass *av_class; + + void *priv_data; + + /** + * Group index in AVFormatContext. + */ + unsigned int index; + + /** + * Group type-specific group ID. + * + * decoding: set by libavformat + * encoding: may set by the user + */ + int64_t id; + + /** + * Group type + * + * decoding: set by libavformat on group creation + * encoding: set by avformat_stream_group_create() + */ + enum AVStreamGroupParamsType type; + + /** + * Group type-specific parameters + */ + union { + struct AVIAMFAudioElement *iamf_audio_element; + struct AVIAMFMixPresentation *iamf_mix_presentation; + struct AVStreamGroupTileGrid *tile_grid; + struct AVStreamGroupLCEVC *lcevc; + } params; + + /** + * Metadata that applies to the whole group. + * + * - demuxing: set by libavformat on group creation + * - muxing: may be set by the caller before avformat_write_header() + * + * Freed by libavformat in avformat_free_context(). + */ + AVDictionary *metadata; + + /** + * Number of elements in AVStreamGroup.streams. + * + * Set by avformat_stream_group_add_stream() must not be modified by any other code. + */ + unsigned int nb_streams; + + /** + * A list of streams in the group. New entries are created with + * avformat_stream_group_add_stream(). + * + * - demuxing: entries are created by libavformat on group creation. + * If AVFMTCTX_NOHEADER is set in ctx_flags, then new entries may also + * appear in av_read_frame(). + * - muxing: entries are created by the user before avformat_write_header(). + * + * Freed by libavformat in avformat_free_context(). + */ + AVStream **streams; + + /** + * Stream group disposition - a combination of AV_DISPOSITION_* flags. + * This field currently applies to all defined AVStreamGroupParamsType. + * + * - demuxing: set by libavformat when creating the group or in + * avformat_find_stream_info(). + * - muxing: may be set by the caller before avformat_write_header(). + */ + int disposition; +} AVStreamGroup; + +struct AVCodecParserContext *av_stream_get_parser(const AVStream *s); + +#define AV_PROGRAM_RUNNING 1 + +/** + * New fields can be added to the end with minor version bumps. + * Removal, reordering and changes to existing fields require a major + * version bump. + * sizeof(AVProgram) must not be used outside libav*. + */ +typedef struct AVProgram { + int id; + int flags; + enum AVDiscard discard; ///< selects which program to discard and which to feed to the caller + unsigned int *stream_index; + unsigned int nb_stream_indexes; + AVDictionary *metadata; + + int program_num; + int pmt_pid; + int pcr_pid; + int pmt_version; + + /***************************************************************** + * All fields below this line are not part of the public API. They + * may not be used outside of libavformat and can be changed and + * removed at will. + * New public fields should be added right above. + ***************************************************************** + */ + int64_t start_time; + int64_t end_time; + + int64_t pts_wrap_reference; ///< reference dts for wrap detection + int pts_wrap_behavior; ///< behavior on wrap detection +} AVProgram; + +#define AVFMTCTX_NOHEADER 0x0001 /**< signal that no header is present + (streams are added dynamically) */ +#define AVFMTCTX_UNSEEKABLE 0x0002 /**< signal that the stream is definitely + not seekable, and attempts to call the + seek function will fail. For some + network protocols (e.g. HLS), this can + change dynamically at runtime. */ + +typedef struct AVChapter { + int64_t id; ///< unique ID to identify the chapter + AVRational time_base; ///< time base in which the start/end timestamps are specified + int64_t start, end; ///< chapter start/end time in time_base units + AVDictionary *metadata; +} AVChapter; + + +/** + * Callback used by devices to communicate with application. + */ +typedef int (*av_format_control_message)(struct AVFormatContext *s, int type, + void *data, size_t data_size); + +typedef int (*AVOpenCallback)(struct AVFormatContext *s, AVIOContext **pb, const char *url, int flags, + const AVIOInterruptCB *int_cb, AVDictionary **options); + +/** + * The duration of a video can be estimated through various ways, and this enum can be used + * to know how the duration was estimated. + */ +enum AVDurationEstimationMethod { + AVFMT_DURATION_FROM_PTS, ///< Duration accurately estimated from PTSes + AVFMT_DURATION_FROM_STREAM, ///< Duration estimated from a stream with a known duration + AVFMT_DURATION_FROM_BITRATE ///< Duration estimated from bitrate (less accurate) +}; + +/** + * Format I/O context. + * New fields can be added to the end with minor version bumps. + * Removal, reordering and changes to existing fields require a major + * version bump. + * sizeof(AVFormatContext) must not be used outside libav*, use + * avformat_alloc_context() to create an AVFormatContext. + * + * Fields can be accessed through AVOptions (av_opt*), + * the name string used matches the associated command line parameter name and + * can be found in libavformat/options_table.h. + * The AVOption/command line parameter names differ in some cases from the C + * structure field names for historic reasons or brevity. + */ +typedef struct AVFormatContext { + /** + * A class for logging and @ref avoptions. Set by avformat_alloc_context(). + * Exports (de)muxer private options if they exist. + */ + const AVClass *av_class; + + /** + * The input container format. + * + * Demuxing only, set by avformat_open_input(). + */ + const struct AVInputFormat *iformat; + + /** + * The output container format. + * + * Muxing only, must be set by the caller before avformat_write_header(). + */ + const struct AVOutputFormat *oformat; + + /** + * Format private data. This is an AVOptions-enabled struct + * if and only if iformat/oformat.priv_class is not NULL. + * + * - muxing: set by avformat_write_header() + * - demuxing: set by avformat_open_input() + */ + void *priv_data; + + /** + * I/O context. + * + * - demuxing: either set by the user before avformat_open_input() (then + * the user must close it manually) or set by avformat_open_input(). + * - muxing: set by the user before avformat_write_header(). The caller must + * take care of closing / freeing the IO context. + * + * Do NOT set this field if AVFMT_NOFILE flag is set in + * iformat/oformat.flags. In such a case, the (de)muxer will handle + * I/O in some other way and this field will be NULL. + */ + AVIOContext *pb; + + /* stream info */ + /** + * Flags signalling stream properties. A combination of AVFMTCTX_*. + * Set by libavformat. + */ + int ctx_flags; + + /** + * Number of elements in AVFormatContext.streams. + * + * Set by avformat_new_stream(), must not be modified by any other code. + */ + unsigned int nb_streams; + /** + * A list of all streams in the file. New streams are created with + * avformat_new_stream(). + * + * - demuxing: streams are created by libavformat in avformat_open_input(). + * If AVFMTCTX_NOHEADER is set in ctx_flags, then new streams may also + * appear in av_read_frame(). + * - muxing: streams are created by the user before avformat_write_header(). + * + * Freed by libavformat in avformat_free_context(). + */ + AVStream **streams; + + /** + * Number of elements in AVFormatContext.stream_groups. + * + * Set by avformat_stream_group_create(), must not be modified by any other code. + */ + unsigned int nb_stream_groups; + /** + * A list of all stream groups in the file. New groups are created with + * avformat_stream_group_create(), and filled with avformat_stream_group_add_stream(). + * + * - demuxing: groups may be created by libavformat in avformat_open_input(). + * If AVFMTCTX_NOHEADER is set in ctx_flags, then new groups may also + * appear in av_read_frame(). + * - muxing: groups may be created by the user before avformat_write_header(). + * + * Freed by libavformat in avformat_free_context(). + */ + AVStreamGroup **stream_groups; + + /** + * Number of chapters in AVChapter array. + * When muxing, chapters are normally written in the file header, + * so nb_chapters should normally be initialized before write_header + * is called. Some muxers (e.g. mov and mkv) can also write chapters + * in the trailer. To write chapters in the trailer, nb_chapters + * must be zero when write_header is called and non-zero when + * write_trailer is called. + * - muxing: set by user + * - demuxing: set by libavformat + */ + unsigned int nb_chapters; + AVChapter **chapters; + + /** + * input or output URL. Unlike the old filename field, this field has no + * length restriction. + * + * - demuxing: set by avformat_open_input(), initialized to an empty + * string if url parameter was NULL in avformat_open_input(). + * - muxing: may be set by the caller before calling avformat_write_header() + * (or avformat_init_output() if that is called first) to a string + * which is freeable by av_free(). Set to an empty string if it + * was NULL in avformat_init_output(). + * + * Freed by libavformat in avformat_free_context(). + */ + char *url; + + /** + * Position of the first frame of the component, in + * AV_TIME_BASE fractional seconds. NEVER set this value directly: + * It is deduced from the AVStream values. + * + * Demuxing only, set by libavformat. + */ + int64_t start_time; + + /** + * Duration of the stream, in AV_TIME_BASE fractional + * seconds. Only set this value if you know none of the individual stream + * durations and also do not set any of them. This is deduced from the + * AVStream values if not set. + * + * Demuxing only, set by libavformat. + */ + int64_t duration; + + /** + * Total stream bitrate in bit/s, 0 if not + * available. Never set it directly if the file_size and the + * duration are known as FFmpeg can compute it automatically. + */ + int64_t bit_rate; + + unsigned int packet_size; + int max_delay; + + /** + * Flags modifying the (de)muxer behaviour. A combination of AVFMT_FLAG_*. + * Set by the user before avformat_open_input() / avformat_write_header(). + */ + int flags; +#define AVFMT_FLAG_GENPTS 0x0001 ///< Generate missing pts even if it requires parsing future frames. +#define AVFMT_FLAG_IGNIDX 0x0002 ///< Ignore index. +#define AVFMT_FLAG_NONBLOCK 0x0004 ///< Do not block when reading packets from input. +#define AVFMT_FLAG_IGNDTS 0x0008 ///< Ignore DTS on frames that contain both DTS & PTS +#define AVFMT_FLAG_NOFILLIN 0x0010 ///< Do not infer any values from other values, just return what is stored in the container +#define AVFMT_FLAG_NOPARSE 0x0020 ///< Do not use AVParsers, you also must set AVFMT_FLAG_NOFILLIN as the filling code works on frames and no parsing -> no frames. Also seeking to frames can not work if parsing to find frame boundaries has been disabled +#define AVFMT_FLAG_NOBUFFER 0x0040 ///< Do not buffer frames when possible +#define AVFMT_FLAG_CUSTOM_IO 0x0080 ///< The caller has supplied a custom AVIOContext, don't avio_close() it. +#define AVFMT_FLAG_DISCARD_CORRUPT 0x0100 ///< Discard frames marked corrupted +#define AVFMT_FLAG_FLUSH_PACKETS 0x0200 ///< Flush the AVIOContext every packet. +/** + * When muxing, try to avoid writing any random/volatile data to the output. + * This includes any random IDs, real-time timestamps/dates, muxer version, etc. + * + * This flag is mainly intended for testing. + */ +#define AVFMT_FLAG_BITEXACT 0x0400 +#define AVFMT_FLAG_SORT_DTS 0x10000 ///< try to interleave outputted packets by dts (using this flag can slow demuxing down) +#define AVFMT_FLAG_FAST_SEEK 0x80000 ///< Enable fast, but inaccurate seeks for some formats +#define AVFMT_FLAG_AUTO_BSF 0x200000 ///< Add bitstream filters as requested by the muxer + + /** + * Maximum number of bytes read from input in order to determine stream + * properties. Used when reading the global header and in + * avformat_find_stream_info(). + * + * Demuxing only, set by the caller before avformat_open_input(). + * + * @note this is \e not used for determining the \ref AVInputFormat + * "input format" + * @see format_probesize + */ + int64_t probesize; + + /** + * Maximum duration (in AV_TIME_BASE units) of the data read + * from input in avformat_find_stream_info(). + * Demuxing only, set by the caller before avformat_find_stream_info(). + * Can be set to 0 to let avformat choose using a heuristic. + */ + int64_t max_analyze_duration; + + const uint8_t *key; + int keylen; + + unsigned int nb_programs; + AVProgram **programs; + + /** + * Forced video codec_id. + * Demuxing: Set by user. + */ + enum AVCodecID video_codec_id; + + /** + * Forced audio codec_id. + * Demuxing: Set by user. + */ + enum AVCodecID audio_codec_id; + + /** + * Forced subtitle codec_id. + * Demuxing: Set by user. + */ + enum AVCodecID subtitle_codec_id; + + /** + * Forced Data codec_id. + * Demuxing: Set by user. + */ + enum AVCodecID data_codec_id; + + /** + * Metadata that applies to the whole file. + * + * - demuxing: set by libavformat in avformat_open_input() + * - muxing: may be set by the caller before avformat_write_header() + * + * Freed by libavformat in avformat_free_context(). + */ + AVDictionary *metadata; + + /** + * Start time of the stream in real world time, in microseconds + * since the Unix epoch (00:00 1st January 1970). That is, pts=0 in the + * stream was captured at this real world time. + * - muxing: Set by the caller before avformat_write_header(). If set to + * either 0 or AV_NOPTS_VALUE, then the current wall-time will + * be used. + * - demuxing: Set by libavformat. AV_NOPTS_VALUE if unknown. Note that + * the value may become known after some number of frames + * have been received. + */ + int64_t start_time_realtime; + + /** + * The number of frames used for determining the framerate in + * avformat_find_stream_info(). + * Demuxing only, set by the caller before avformat_find_stream_info(). + */ + int fps_probe_size; + + /** + * Error recognition; higher values will detect more errors but may + * misdetect some more or less valid parts as errors. + * Demuxing only, set by the caller before avformat_open_input(). + */ + int error_recognition; + + /** + * Custom interrupt callbacks for the I/O layer. + * + * demuxing: set by the user before avformat_open_input(). + * muxing: set by the user before avformat_write_header() + * (mainly useful for AVFMT_NOFILE formats). The callback + * should also be passed to avio_open2() if it's used to + * open the file. + */ + AVIOInterruptCB interrupt_callback; + + /** + * Flags to enable debugging. + */ + int debug; +#define FF_FDEBUG_TS 0x0001 + + /** + * The maximum number of streams. + * - encoding: unused + * - decoding: set by user + */ + int max_streams; + + /** + * Maximum amount of memory in bytes to use for the index of each stream. + * If the index exceeds this size, entries will be discarded as + * needed to maintain a smaller size. This can lead to slower or less + * accurate seeking (depends on demuxer). + * Demuxers for which a full in-memory index is mandatory will ignore + * this. + * - muxing: unused + * - demuxing: set by user + */ + unsigned int max_index_size; + + /** + * Maximum amount of memory in bytes to use for buffering frames + * obtained from realtime capture devices. + */ + unsigned int max_picture_buffer; + + /** + * Maximum buffering duration for interleaving. + * + * To ensure all the streams are interleaved correctly, + * av_interleaved_write_frame() will wait until it has at least one packet + * for each stream before actually writing any packets to the output file. + * When some streams are "sparse" (i.e. there are large gaps between + * successive packets), this can result in excessive buffering. + * + * This field specifies the maximum difference between the timestamps of the + * first and the last packet in the muxing queue, above which libavformat + * will output a packet regardless of whether it has queued a packet for all + * the streams. + * + * Muxing only, set by the caller before avformat_write_header(). + */ + int64_t max_interleave_delta; + + /** + * Maximum number of packets to read while waiting for the first timestamp. + * Decoding only. + */ + int max_ts_probe; + + /** + * Max chunk time in microseconds. + * Note, not all formats support this and unpredictable things may happen if it is used when not supported. + * - encoding: Set by user + * - decoding: unused + */ + int max_chunk_duration; + + /** + * Max chunk size in bytes + * Note, not all formats support this and unpredictable things may happen if it is used when not supported. + * - encoding: Set by user + * - decoding: unused + */ + int max_chunk_size; + + /** + * Maximum number of packets that can be probed + * - encoding: unused + * - decoding: set by user + */ + int max_probe_packets; + + /** + * Allow non-standard and experimental extension + * @see AVCodecContext.strict_std_compliance + */ + int strict_std_compliance; + + /** + * Flags indicating events happening on the file, a combination of + * AVFMT_EVENT_FLAG_*. + * + * - demuxing: may be set by the demuxer in avformat_open_input(), + * avformat_find_stream_info() and av_read_frame(). Flags must be cleared + * by the user once the event has been handled. + * - muxing: may be set by the user after avformat_write_header() to + * indicate a user-triggered event. The muxer will clear the flags for + * events it has handled in av_[interleaved]_write_frame(). + */ + int event_flags; +/** + * - demuxing: the demuxer read new metadata from the file and updated + * AVFormatContext.metadata accordingly + * - muxing: the user updated AVFormatContext.metadata and wishes the muxer to + * write it into the file + */ +#define AVFMT_EVENT_FLAG_METADATA_UPDATED 0x0001 + + + /** + * Avoid negative timestamps during muxing. + * Any value of the AVFMT_AVOID_NEG_TS_* constants. + * Note, this works better when using av_interleaved_write_frame(). + * - muxing: Set by user + * - demuxing: unused + */ + int avoid_negative_ts; +#define AVFMT_AVOID_NEG_TS_AUTO -1 ///< Enabled when required by target format +#define AVFMT_AVOID_NEG_TS_DISABLED 0 ///< Do not shift timestamps even when they are negative. +#define AVFMT_AVOID_NEG_TS_MAKE_NON_NEGATIVE 1 ///< Shift timestamps so they are non negative +#define AVFMT_AVOID_NEG_TS_MAKE_ZERO 2 ///< Shift timestamps so that they start at 0 + + /** + * Audio preload in microseconds. + * Note, not all formats support this and unpredictable things may happen if it is used when not supported. + * - encoding: Set by user + * - decoding: unused + */ + int audio_preload; + + /** + * forces the use of wallclock timestamps as pts/dts of packets + * This has undefined results in the presence of B frames. + * - encoding: unused + * - decoding: Set by user + */ + int use_wallclock_as_timestamps; + + /** + * Skip duration calculation in estimate_timings_from_pts. + * - encoding: unused + * - decoding: set by user + * + * @see duration_probesize + */ + int skip_estimate_duration_from_pts; + + /** + * avio flags, used to force AVIO_FLAG_DIRECT. + * - encoding: unused + * - decoding: Set by user + */ + int avio_flags; + + /** + * The duration field can be estimated through various ways, and this field can be used + * to know how the duration was estimated. + * - encoding: unused + * - decoding: Read by user + */ + enum AVDurationEstimationMethod duration_estimation_method; + + /** + * Skip initial bytes when opening stream + * - encoding: unused + * - decoding: Set by user + */ + int64_t skip_initial_bytes; + + /** + * Correct single timestamp overflows + * - encoding: unused + * - decoding: Set by user + */ + unsigned int correct_ts_overflow; + + /** + * Force seeking to any (also non key) frames. + * - encoding: unused + * - decoding: Set by user + */ + int seek2any; + + /** + * Flush the I/O context after each packet. + * - encoding: Set by user + * - decoding: unused + */ + int flush_packets; + + /** + * format probing score. + * The maximal score is AVPROBE_SCORE_MAX, its set when the demuxer probes + * the format. + * - encoding: unused + * - decoding: set by avformat, read by user + */ + int probe_score; + + /** + * Maximum number of bytes read from input in order to identify the + * \ref AVInputFormat "input format". Only used when the format is not set + * explicitly by the caller. + * + * Demuxing only, set by the caller before avformat_open_input(). + * + * @see probesize + */ + int format_probesize; + + /** + * ',' separated list of allowed decoders. + * If NULL then all are allowed + * - encoding: unused + * - decoding: set by user + */ + char *codec_whitelist; + + /** + * ',' separated list of allowed demuxers. + * If NULL then all are allowed + * - encoding: unused + * - decoding: set by user + */ + char *format_whitelist; + + /** + * ',' separated list of allowed protocols. + * - encoding: unused + * - decoding: set by user + */ + char *protocol_whitelist; + + /** + * ',' separated list of disallowed protocols. + * - encoding: unused + * - decoding: set by user + */ + char *protocol_blacklist; + + /** + * IO repositioned flag. + * This is set by avformat when the underlying IO context read pointer + * is repositioned, for example when doing byte based seeking. + * Demuxers can use the flag to detect such changes. + */ + int io_repositioned; + + /** + * Forced video codec. + * This allows forcing a specific decoder, even when there are multiple with + * the same codec_id. + * Demuxing: Set by user + */ + const struct AVCodec *video_codec; + + /** + * Forced audio codec. + * This allows forcing a specific decoder, even when there are multiple with + * the same codec_id. + * Demuxing: Set by user + */ + const struct AVCodec *audio_codec; + + /** + * Forced subtitle codec. + * This allows forcing a specific decoder, even when there are multiple with + * the same codec_id. + * Demuxing: Set by user + */ + const struct AVCodec *subtitle_codec; + + /** + * Forced data codec. + * This allows forcing a specific decoder, even when there are multiple with + * the same codec_id. + * Demuxing: Set by user + */ + const struct AVCodec *data_codec; + + /** + * Number of bytes to be written as padding in a metadata header. + * Demuxing: Unused. + * Muxing: Set by user. + */ + int metadata_header_padding; + + /** + * User data. + * This is a place for some private data of the user. + */ + void *opaque; + + /** + * Callback used by devices to communicate with application. + */ + av_format_control_message control_message_cb; + + /** + * Output timestamp offset, in microseconds. + * Muxing: set by user + */ + int64_t output_ts_offset; + + /** + * dump format separator. + * can be ", " or "\n " or anything else + * - muxing: Set by user. + * - demuxing: Set by user. + */ + uint8_t *dump_separator; + + /** + * A callback for opening new IO streams. + * + * Whenever a muxer or a demuxer needs to open an IO stream (typically from + * avformat_open_input() for demuxers, but for certain formats can happen at + * other times as well), it will call this callback to obtain an IO context. + * + * @param s the format context + * @param pb on success, the newly opened IO context should be returned here + * @param url the url to open + * @param flags a combination of AVIO_FLAG_* + * @param options a dictionary of additional options, with the same + * semantics as in avio_open2() + * @return 0 on success, a negative AVERROR code on failure + * + * @note Certain muxers and demuxers do nesting, i.e. they open one or more + * additional internal format contexts. Thus the AVFormatContext pointer + * passed to this callback may be different from the one facing the caller. + * It will, however, have the same 'opaque' field. + */ + int (*io_open)(struct AVFormatContext *s, AVIOContext **pb, const char *url, + int flags, AVDictionary **options); + + /** + * A callback for closing the streams opened with AVFormatContext.io_open(). + * + * @param s the format context + * @param pb IO context to be closed and freed + * @return 0 on success, a negative AVERROR code on failure + */ + int (*io_close2)(struct AVFormatContext *s, AVIOContext *pb); + + /** + * Maximum number of bytes read from input in order to determine stream durations + * when using estimate_timings_from_pts in avformat_find_stream_info(). + * Demuxing only, set by the caller before avformat_find_stream_info(). + * Can be set to 0 to let avformat choose using a heuristic. + * + * @see skip_estimate_duration_from_pts + */ + int64_t duration_probesize; + + /** + * Name of this format context, only used for logging purposes. + */ + char *name; +} AVFormatContext; + +/** + * @defgroup lavf_core Core functions + * @ingroup libavf + * + * Functions for querying libavformat capabilities, allocating core structures, + * etc. + * @{ + */ + +/** + * Return the LIBAVFORMAT_VERSION_INT constant. + */ +unsigned avformat_version(void); + +/** + * Return the libavformat build-time configuration. + */ +const char *avformat_configuration(void); + +/** + * Return the libavformat license. + */ +const char *avformat_license(void); + +/** + * Do global initialization of network libraries. This is optional, + * and not recommended anymore. + * + * This functions only exists to work around thread-safety issues + * with older GnuTLS or OpenSSL libraries. If libavformat is linked + * to newer versions of those libraries, or if you do not use them, + * calling this function is unnecessary. Otherwise, you need to call + * this function before any other threads using them are started. + * + * This function will be deprecated once support for older GnuTLS and + * OpenSSL libraries is removed, and this function has no purpose + * anymore. + */ +int avformat_network_init(void); + +/** + * Undo the initialization done by avformat_network_init. Call it only + * once for each time you called avformat_network_init. + */ +int avformat_network_deinit(void); + +/** + * Iterate over all registered muxers. + * + * @param opaque a pointer where libavformat will store the iteration state. Must + * point to NULL to start the iteration. + * + * @return the next registered muxer or NULL when the iteration is + * finished + */ +const AVOutputFormat *av_muxer_iterate(void **opaque); + +/** + * Iterate over all registered demuxers. + * + * @param opaque a pointer where libavformat will store the iteration state. + * Must point to NULL to start the iteration. + * + * @return the next registered demuxer or NULL when the iteration is + * finished + */ +const AVInputFormat *av_demuxer_iterate(void **opaque); + +/** + * Allocate an AVFormatContext. + * avformat_free_context() can be used to free the context and everything + * allocated by the framework within it. + */ +AVFormatContext *avformat_alloc_context(void); + +/** + * Free an AVFormatContext and all its streams. + * @param s context to free + */ +void avformat_free_context(AVFormatContext *s); + +/** + * Get the AVClass for AVFormatContext. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *avformat_get_class(void); + +/** + * Get the AVClass for AVStream. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *av_stream_get_class(void); + +/** + * Get the AVClass for AVStreamGroup. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *av_stream_group_get_class(void); + +/** + * @return a string identifying the stream group type, or NULL if unknown + */ +const char *avformat_stream_group_name(enum AVStreamGroupParamsType type); + +/** + * Add a new empty stream group to a media file. + * + * When demuxing, it may be called by the demuxer in read_header(). If the + * flag AVFMTCTX_NOHEADER is set in s.ctx_flags, then it may also + * be called in read_packet(). + * + * When muxing, may be called by the user before avformat_write_header(). + * + * User is required to call avformat_free_context() to clean up the allocation + * by avformat_stream_group_create(). + * + * New streams can be added to the group with avformat_stream_group_add_stream(). + * + * @param s media file handle + * + * @return newly created group or NULL on error. + * @see avformat_new_stream, avformat_stream_group_add_stream. + */ +AVStreamGroup *avformat_stream_group_create(AVFormatContext *s, + enum AVStreamGroupParamsType type, + AVDictionary **options); + +/** + * Add a new stream to a media file. + * + * When demuxing, it is called by the demuxer in read_header(). If the + * flag AVFMTCTX_NOHEADER is set in s.ctx_flags, then it may also + * be called in read_packet(). + * + * When muxing, should be called by the user before avformat_write_header(). + * + * User is required to call avformat_free_context() to clean up the allocation + * by avformat_new_stream(). + * + * @param s media file handle + * @param c unused, does nothing + * + * @return newly created stream or NULL on error. + */ +AVStream *avformat_new_stream(AVFormatContext *s, const struct AVCodec *c); + +/** + * Add an already allocated stream to a stream group. + * + * When demuxing, it may be called by the demuxer in read_header(). If the + * flag AVFMTCTX_NOHEADER is set in s.ctx_flags, then it may also + * be called in read_packet(). + * + * When muxing, may be called by the user before avformat_write_header() after + * having allocated a new group with avformat_stream_group_create() and stream with + * avformat_new_stream(). + * + * User is required to call avformat_free_context() to clean up the allocation + * by avformat_stream_group_add_stream(). + * + * @param stg stream group belonging to a media file. + * @param st stream in the media file to add to the group. + * + * @retval 0 success + * @retval AVERROR(EEXIST) the stream was already in the group + * @retval "another negative error code" legitimate errors + * + * @see avformat_new_stream, avformat_stream_group_create. + */ +int avformat_stream_group_add_stream(AVStreamGroup *stg, AVStream *st); + +AVProgram *av_new_program(AVFormatContext *s, int id); + +/** + * @} + */ + + +/** + * Allocate an AVFormatContext for an output format. + * avformat_free_context() can be used to free the context and + * everything allocated by the framework within it. + * + * @param ctx pointee is set to the created format context, + * or to NULL in case of failure + * @param oformat format to use for allocating the context, if NULL + * format_name and filename are used instead + * @param format_name the name of output format to use for allocating the + * context, if NULL filename is used instead + * @param filename the name of the filename to use for allocating the + * context, may be NULL + * + * @return >= 0 in case of success, a negative AVERROR code in case of + * failure + */ +int avformat_alloc_output_context2(AVFormatContext **ctx, const AVOutputFormat *oformat, + const char *format_name, const char *filename); + +/** + * @addtogroup lavf_decoding + * @{ + */ + +/** + * Find AVInputFormat based on the short name of the input format. + */ +const AVInputFormat *av_find_input_format(const char *short_name); + +/** + * Guess the file format. + * + * @param pd data to be probed + * @param is_opened Whether the file is already opened; determines whether + * demuxers with or without AVFMT_NOFILE are probed. + */ +const AVInputFormat *av_probe_input_format(const AVProbeData *pd, int is_opened); + +/** + * Guess the file format. + * + * @param pd data to be probed + * @param is_opened Whether the file is already opened; determines whether + * demuxers with or without AVFMT_NOFILE are probed. + * @param score_max A probe score larger that this is required to accept a + * detection, the variable is set to the actual detection + * score afterwards. + * If the score is <= AVPROBE_SCORE_MAX / 4 it is recommended + * to retry with a larger probe buffer. + */ +const AVInputFormat *av_probe_input_format2(const AVProbeData *pd, + int is_opened, int *score_max); + +/** + * Guess the file format. + * + * @param is_opened Whether the file is already opened; determines whether + * demuxers with or without AVFMT_NOFILE are probed. + * @param score_ret The score of the best detection. + */ +const AVInputFormat *av_probe_input_format3(const AVProbeData *pd, + int is_opened, int *score_ret); + +/** + * Probe a bytestream to determine the input format. Each time a probe returns + * with a score that is too low, the probe buffer size is increased and another + * attempt is made. When the maximum probe size is reached, the input format + * with the highest score is returned. + * + * @param pb the bytestream to probe + * @param fmt the input format is put here + * @param url the url of the stream + * @param logctx the log context + * @param offset the offset within the bytestream to probe from + * @param max_probe_size the maximum probe buffer size (zero for default) + * + * @return the score in case of success, a negative value corresponding to an + * the maximal score is AVPROBE_SCORE_MAX + * AVERROR code otherwise + */ +int av_probe_input_buffer2(AVIOContext *pb, const AVInputFormat **fmt, + const char *url, void *logctx, + unsigned int offset, unsigned int max_probe_size); + +/** + * Like av_probe_input_buffer2() but returns 0 on success + */ +int av_probe_input_buffer(AVIOContext *pb, const AVInputFormat **fmt, + const char *url, void *logctx, + unsigned int offset, unsigned int max_probe_size); + +/** + * Open an input stream and read the header. The codecs are not opened. + * The stream must be closed with avformat_close_input(). + * + * @param ps Pointer to user-supplied AVFormatContext (allocated by + * avformat_alloc_context). May be a pointer to NULL, in + * which case an AVFormatContext is allocated by this + * function and written into ps. + * Note that a user-supplied AVFormatContext will be freed + * on failure and its pointer set to NULL. + * @param url URL of the stream to open. + * @param fmt If non-NULL, this parameter forces a specific input format. + * Otherwise the format is autodetected. + * @param options A dictionary filled with AVFormatContext and demuxer-private + * options. + * On return this parameter will be destroyed and replaced with + * a dict containing options that were not found. May be NULL. + * + * @return 0 on success; on failure: frees ps, sets its pointer to NULL, + * and returns a negative AVERROR. + * + * @note If you want to use custom IO, preallocate the format context and set its pb field. + */ +int avformat_open_input(AVFormatContext **ps, const char *url, + const AVInputFormat *fmt, AVDictionary **options); + +/** + * Read packets of a media file to get stream information. This + * is useful for file formats with no headers such as MPEG. This + * function also computes the real framerate in case of MPEG-2 repeat + * frame mode. + * The logical file position is not changed by this function; + * examined packets may be buffered for later processing. + * + * @param ic media file handle + * @param options If non-NULL, an ic.nb_streams long array of pointers to + * dictionaries, where i-th member contains options for + * codec corresponding to i-th stream. + * On return each dictionary will be filled with options that were not found. + * @return >=0 if OK, AVERROR_xxx on error + * + * @note this function isn't guaranteed to open all the codecs, so + * options being non-empty at return is a perfectly normal behavior. + * + * @todo Let the user decide somehow what information is needed so that + * we do not waste time getting stuff the user does not need. + */ +int avformat_find_stream_info(AVFormatContext *ic, AVDictionary **options); + +/** + * Find the programs which belong to a given stream. + * + * @param ic media file handle + * @param last the last found program, the search will start after this + * program, or from the beginning if it is NULL + * @param s stream index + * + * @return the next program which belongs to s, NULL if no program is found or + * the last program is not among the programs of ic. + */ +AVProgram *av_find_program_from_stream(AVFormatContext *ic, AVProgram *last, int s); + +void av_program_add_stream_index(AVFormatContext *ac, int progid, unsigned int idx); + +/** + * Find the "best" stream in the file. + * The best stream is determined according to various heuristics as the most + * likely to be what the user expects. + * If the decoder parameter is non-NULL, av_find_best_stream will find the + * default decoder for the stream's codec; streams for which no decoder can + * be found are ignored. + * + * @param ic media file handle + * @param type stream type: video, audio, subtitles, etc. + * @param wanted_stream_nb user-requested stream number, + * or -1 for automatic selection + * @param related_stream try to find a stream related (eg. in the same + * program) to this one, or -1 if none + * @param decoder_ret if non-NULL, returns the decoder for the + * selected stream + * @param flags flags; none are currently defined + * + * @return the non-negative stream number in case of success, + * AVERROR_STREAM_NOT_FOUND if no stream with the requested type + * could be found, + * AVERROR_DECODER_NOT_FOUND if streams were found but no decoder + * + * @note If av_find_best_stream returns successfully and decoder_ret is not + * NULL, then *decoder_ret is guaranteed to be set to a valid AVCodec. + */ +int av_find_best_stream(AVFormatContext *ic, + enum AVMediaType type, + int wanted_stream_nb, + int related_stream, + const struct AVCodec **decoder_ret, + int flags); + +/** + * Return the next frame of a stream. + * This function returns what is stored in the file, and does not validate + * that what is there are valid frames for the decoder. It will split what is + * stored in the file into frames and return one for each call. It will not + * omit invalid data between valid frames so as to give the decoder the maximum + * information possible for decoding. + * + * On success, the returned packet is reference-counted (pkt->buf is set) and + * valid indefinitely. The packet must be freed with av_packet_unref() when + * it is no longer needed. For video, the packet contains exactly one frame. + * For audio, it contains an integer number of frames if each frame has + * a known fixed size (e.g. PCM or ADPCM data). If the audio frames have + * a variable size (e.g. MPEG audio), then it contains one frame. + * + * pkt->pts, pkt->dts and pkt->duration are always set to correct + * values in AVStream.time_base units (and guessed if the format cannot + * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format + * has B-frames, so it is better to rely on pkt->dts if you do not + * decompress the payload. + * + * @return 0 if OK, < 0 on error or end of file. On error, pkt will be blank + * (as if it came from av_packet_alloc()). + * + * @note pkt will be initialized, so it may be uninitialized, but it must not + * contain data that needs to be freed. + */ +int av_read_frame(AVFormatContext *s, AVPacket *pkt); + +/** + * Seek to the keyframe at timestamp. + * 'timestamp' in 'stream_index'. + * + * @param s media file handle + * @param stream_index If stream_index is (-1), a default stream is selected, + * and timestamp is automatically converted from + * AV_TIME_BASE units to the stream specific time_base. + * @param timestamp Timestamp in AVStream.time_base units or, if no stream + * is specified, in AV_TIME_BASE units. + * @param flags flags which select direction and seeking mode + * + * @return >= 0 on success + */ +int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, + int flags); + +/** + * Seek to timestamp ts. + * Seeking will be done so that the point from which all active streams + * can be presented successfully will be closest to ts and within min/max_ts. + * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL. + * + * If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and + * are the file position (this may not be supported by all demuxers). + * If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames + * in the stream with stream_index (this may not be supported by all demuxers). + * Otherwise all timestamps are in units of the stream selected by stream_index + * or if stream_index is -1, in AV_TIME_BASE units. + * If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as + * keyframes (this may not be supported by all demuxers). + * If flags contain AVSEEK_FLAG_BACKWARD, it is ignored. + * + * @param s media file handle + * @param stream_index index of the stream which is used as time base reference + * @param min_ts smallest acceptable timestamp + * @param ts target timestamp + * @param max_ts largest acceptable timestamp + * @param flags flags + * @return >=0 on success, error code otherwise + * + * @note This is part of the new seek API which is still under construction. + */ +int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags); + +/** + * Discard all internally buffered data. This can be useful when dealing with + * discontinuities in the byte stream. Generally works only with formats that + * can resync. This includes headerless formats like MPEG-TS/TS but should also + * work with NUT, Ogg and in a limited way AVI for example. + * + * The set of streams, the detected duration, stream parameters and codecs do + * not change when calling this function. If you want a complete reset, it's + * better to open a new AVFormatContext. + * + * This does not flush the AVIOContext (s->pb). If necessary, call + * avio_flush(s->pb) before calling this function. + * + * @param s media file handle + * @return >=0 on success, error code otherwise + */ +int avformat_flush(AVFormatContext *s); + +/** + * Start playing a network-based stream (e.g. RTSP stream) at the + * current position. + */ +int av_read_play(AVFormatContext *s); + +/** + * Pause a network-based stream (e.g. RTSP stream). + * + * Use av_read_play() to resume it. + */ +int av_read_pause(AVFormatContext *s); + +/** + * Command IDs that can be sent to the demuxer + * + * The following commands can be sent to a demuxer + * using ::avformat_send_command. + */ +enum AVFormatCommandID { + /** + * Send a RTSP `SET_PARAMETER` request to the server + * + * Sends an SET_PARAMETER RTSP command to the server, + * with a data payload of type ::AVRTSPCommandRequest, + * ownership of it and its data remains with the caller. + * + * A reply retrieved is of type ::AVRTSPResponse and it + * and its contents must be freed by the caller. + */ + AVFORMAT_COMMAND_RTSP_SET_PARAMETER, +}; + +typedef struct AVRTSPCommandRequest { + /** + * Headers sent in the request to the server + */ + AVDictionary *headers; + + /** + * Body payload size + */ + size_t body_len; + + /** + * Body payload + */ + char *body; +} AVRTSPCommandRequest; + +typedef struct AVRTSPResponse { + /** + * Response status code from server + */ + int status_code; + + /** + * Reason phrase from the server, describing the + * status in a human-readable way. + */ + char *reason; + + /** + * Body payload size + */ + size_t body_len; + + /** + * Body payload + */ + unsigned char *body; +} AVRTSPResponse; + +/** + * Send a command to the demuxer + * + * Sends the specified command and (depending on the command) + * optionally a command-specific payload to the demuxer to handle. + * + * @param s Format context, must be allocated with + * ::avformat_alloc_context. + * @param id Identifier of type ::AVFormatCommandID, + * indicating the command to send. + * @param data Command-specific data, allocated by the caller + * and ownership remains with the caller. + * For details what is expected here, consult the + * documentation of the respective ::AVFormatCommandID. + */ +int avformat_send_command(AVFormatContext *s, enum AVFormatCommandID id, void *data); + +/** + * Receive a command reply from the demuxer + * + * Retrieves a reply for a previously sent command from the muxer. + * + * @param s Format context, must be allocated with + * ::avformat_alloc_context. + * @param id Identifier of type ::AVFormatCommandID, + * indicating the command for which to retrieve + * the reply. + * @param data_out Pointee is set to the command reply, the actual + * type depends on the command. This is allocated by + * the muxer and must be freed with ::av_free. + * For details on the actual data set here, consult the + * documentation of the respective ::AVFormatCommandID. + */ +int avformat_receive_command_reply(AVFormatContext *s, enum AVFormatCommandID id, void **data_out); + +/** + * Close an opened input AVFormatContext. Free it and all its contents + * and set *s to NULL. + */ +void avformat_close_input(AVFormatContext **s); +/** + * @} + */ + +#define AVSEEK_FLAG_BACKWARD 1 ///< seek backward +#define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes +#define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non-keyframes +#define AVSEEK_FLAG_FRAME 8 ///< seeking based on frame number + +/** + * @addtogroup lavf_encoding + * @{ + */ + +#define AVSTREAM_INIT_IN_WRITE_HEADER 0 ///< stream parameters initialized in avformat_write_header +#define AVSTREAM_INIT_IN_INIT_OUTPUT 1 ///< stream parameters initialized in avformat_init_output + +/** + * Allocate the stream private data and write the stream header to + * an output media file. + * + * @param s Media file handle, must be allocated with + * avformat_alloc_context(). + * Its \ref AVFormatContext.oformat "oformat" field must be set + * to the desired output format; + * Its \ref AVFormatContext.pb "pb" field must be set to an + * already opened ::AVIOContext. + * @param options An ::AVDictionary filled with AVFormatContext and + * muxer-private options. + * On return this parameter will be destroyed and replaced with + * a dict containing options that were not found. May be NULL. + * + * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec had not already been + * fully initialized in avformat_init_output(). + * @retval AVSTREAM_INIT_IN_INIT_OUTPUT On success, if the codec had already been fully + * initialized in avformat_init_output(). + * @retval AVERROR A negative AVERROR on failure. + * + * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_init_output. + */ +av_warn_unused_result +int avformat_write_header(AVFormatContext *s, AVDictionary **options); + +/** + * Allocate the stream private data and initialize the codec, but do not write the header. + * May optionally be used before avformat_write_header() to initialize stream parameters + * before actually writing the header. + * If using this function, do not pass the same options to avformat_write_header(). + * + * @param s Media file handle, must be allocated with + * avformat_alloc_context(). + * Its \ref AVFormatContext.oformat "oformat" field must be set + * to the desired output format; + * Its \ref AVFormatContext.pb "pb" field must be set to an + * already opened ::AVIOContext. + * @param options An ::AVDictionary filled with AVFormatContext and + * muxer-private options. + * On return this parameter will be destroyed and replaced with + * a dict containing options that were not found. May be NULL. + * + * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec requires + * avformat_write_header to fully initialize. + * @retval AVSTREAM_INIT_IN_INIT_OUTPUT On success, if the codec has been fully + * initialized. + * @retval AVERROR Anegative AVERROR on failure. + * + * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_write_header. + */ +av_warn_unused_result +int avformat_init_output(AVFormatContext *s, AVDictionary **options); + +/** + * Write a packet to an output media file. + * + * This function passes the packet directly to the muxer, without any buffering + * or reordering. The caller is responsible for correctly interleaving the + * packets if the format requires it. Callers that want libavformat to handle + * the interleaving should call av_interleaved_write_frame() instead of this + * function. + * + * @param s media file handle + * @param pkt The packet containing the data to be written. Note that unlike + * av_interleaved_write_frame(), this function does not take + * ownership of the packet passed to it (though some muxers may make + * an internal reference to the input packet). + *
+ * This parameter can be NULL (at any time, not just at the end), in + * order to immediately flush data buffered within the muxer, for + * muxers that buffer up data internally before writing it to the + * output. + *
+ * Packet's @ref AVPacket.stream_index "stream_index" field must be + * set to the index of the corresponding stream in @ref + * AVFormatContext.streams "s->streams". + *
+ * The timestamps (@ref AVPacket.pts "pts", @ref AVPacket.dts "dts") + * must be set to correct values in the stream's timebase (unless the + * output format is flagged with the AVFMT_NOTIMESTAMPS flag, then + * they can be set to AV_NOPTS_VALUE). + * The dts for subsequent packets passed to this function must be strictly + * increasing when compared in their respective timebases (unless the + * output format is flagged with the AVFMT_TS_NONSTRICT, then they + * merely have to be nondecreasing). @ref AVPacket.duration + * "duration") should also be set if known. + * @return < 0 on error, = 0 if OK, 1 if flushed and there is no more data to flush + * + * @see av_interleaved_write_frame() + */ +int av_write_frame(AVFormatContext *s, AVPacket *pkt); + +/** + * Write a packet to an output media file ensuring correct interleaving. + * + * This function will buffer the packets internally as needed to make sure the + * packets in the output file are properly interleaved, usually ordered by + * increasing dts. Callers doing their own interleaving should call + * av_write_frame() instead of this function. + * + * Using this function instead of av_write_frame() can give muxers advance + * knowledge of future packets, improving e.g. the behaviour of the mp4 + * muxer for VFR content in fragmenting mode. + * + * @param s media file handle + * @param pkt The packet containing the data to be written. + *
+ * If the packet is reference-counted, this function will take + * ownership of this reference and unreference it later when it sees + * fit. If the packet is not reference-counted, libavformat will + * make a copy. + * The returned packet will be blank (as if returned from + * av_packet_alloc()), even on error. + *
+ * This parameter can be NULL (at any time, not just at the end), to + * flush the interleaving queues. + *
+ * Packet's @ref AVPacket.stream_index "stream_index" field must be + * set to the index of the corresponding stream in @ref + * AVFormatContext.streams "s->streams". + *
+ * The timestamps (@ref AVPacket.pts "pts", @ref AVPacket.dts "dts") + * must be set to correct values in the stream's timebase (unless the + * output format is flagged with the AVFMT_NOTIMESTAMPS flag, then + * they can be set to AV_NOPTS_VALUE). + * The dts for subsequent packets in one stream must be strictly + * increasing (unless the output format is flagged with the + * AVFMT_TS_NONSTRICT, then they merely have to be nondecreasing). + * @ref AVPacket.duration "duration" should also be set if known. + * + * @return 0 on success, a negative AVERROR on error. + * + * @see av_write_frame(), AVFormatContext.max_interleave_delta + */ +int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt); + +/** + * Write an uncoded frame to an output media file. + * + * The frame must be correctly interleaved according to the container + * specification; if not, av_interleaved_write_uncoded_frame() must be used. + * + * See av_interleaved_write_uncoded_frame() for details. + */ +int av_write_uncoded_frame(AVFormatContext *s, int stream_index, + struct AVFrame *frame); + +/** + * Write an uncoded frame to an output media file. + * + * If the muxer supports it, this function makes it possible to write an AVFrame + * structure directly, without encoding it into a packet. + * It is mostly useful for devices and similar special muxers that use raw + * video or PCM data and will not serialize it into a byte stream. + * + * To test whether it is possible to use it with a given muxer and stream, + * use av_write_uncoded_frame_query(). + * + * The caller gives up ownership of the frame and must not access it + * afterwards. + * + * @return >=0 for success, a negative code on error + */ +int av_interleaved_write_uncoded_frame(AVFormatContext *s, int stream_index, + struct AVFrame *frame); + +/** + * Test whether a muxer supports uncoded frame. + * + * @return >=0 if an uncoded frame can be written to that muxer and stream, + * <0 if not + */ +int av_write_uncoded_frame_query(AVFormatContext *s, int stream_index); + +/** + * Write the stream trailer to an output media file and free the + * file private data. + * + * May only be called after a successful call to avformat_write_header. + * + * @param s media file handle + * @return 0 if OK, AVERROR_xxx on error + */ +int av_write_trailer(AVFormatContext *s); + +/** + * Return the output format in the list of registered output formats + * which best matches the provided parameters, or return NULL if + * there is no match. + * + * @param short_name if non-NULL checks if short_name matches with the + * names of the registered formats + * @param filename if non-NULL checks if filename terminates with the + * extensions of the registered formats + * @param mime_type if non-NULL checks if mime_type matches with the + * MIME type of the registered formats + */ +const AVOutputFormat *av_guess_format(const char *short_name, + const char *filename, + const char *mime_type); + +/** + * Guess the codec ID based upon muxer and filename. + */ +enum AVCodecID av_guess_codec(const AVOutputFormat *fmt, const char *short_name, + const char *filename, const char *mime_type, + enum AVMediaType type); + +/** + * Get timing information for the data currently output. + * The exact meaning of "currently output" depends on the format. + * It is mostly relevant for devices that have an internal buffer and/or + * work in real time. + * @param s media file handle + * @param stream stream in the media file + * @param[out] dts DTS of the last packet output for the stream, in stream + * time_base units + * @param[out] wall absolute time when that packet whas output, + * in microsecond + * @retval 0 Success + * @retval AVERROR(ENOSYS) The format does not support it + * + * @note Some formats or devices may not allow to measure dts and wall + * atomically. + */ +int av_get_output_timestamp(struct AVFormatContext *s, int stream, + int64_t *dts, int64_t *wall); + + +/** + * @} + */ + + +/** + * @defgroup lavf_misc Utility functions + * @ingroup libavf + * @{ + * + * Miscellaneous utility functions related to both muxing and demuxing + * (or neither). + */ + +/** + * Send a nice hexadecimal dump of a buffer to the specified file stream. + * + * @param f The file stream pointer where the dump should be sent to. + * @param buf buffer + * @param size buffer size + * + * @see av_hex_dump_log, av_pkt_dump2, av_pkt_dump_log2 + */ +void av_hex_dump(FILE *f, const uint8_t *buf, int size); + +/** + * Send a nice hexadecimal dump of a buffer to the log. + * + * @param avcl A pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct. + * @param level The importance level of the message, lower values signifying + * higher importance. + * @param buf buffer + * @param size buffer size + * + * @see av_hex_dump, av_pkt_dump2, av_pkt_dump_log2 + */ +void av_hex_dump_log(void *avcl, int level, const uint8_t *buf, int size); + +/** + * Send a nice dump of a packet to the specified file stream. + * + * @param f The file stream pointer where the dump should be sent to. + * @param pkt packet to dump + * @param dump_payload True if the payload must be displayed, too. + * @param st AVStream that the packet belongs to + */ +void av_pkt_dump2(FILE *f, const AVPacket *pkt, int dump_payload, const AVStream *st); + + +/** + * Send a nice dump of a packet to the log. + * + * @param avcl A pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct. + * @param level The importance level of the message, lower values signifying + * higher importance. + * @param pkt packet to dump + * @param dump_payload True if the payload must be displayed, too. + * @param st AVStream that the packet belongs to + */ +void av_pkt_dump_log2(void *avcl, int level, const AVPacket *pkt, int dump_payload, + const AVStream *st); + +/** + * Get the AVCodecID for the given codec tag tag. + * If no codec id is found returns AV_CODEC_ID_NONE. + * + * @param tags list of supported codec_id-codec_tag pairs, as stored + * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag + * @param tag codec tag to match to a codec ID + */ +enum AVCodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag); + +/** + * Get the codec tag for the given codec id id. + * If no codec tag is found returns 0. + * + * @param tags list of supported codec_id-codec_tag pairs, as stored + * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag + * @param id codec ID to match to a codec tag + */ +unsigned int av_codec_get_tag(const struct AVCodecTag * const *tags, enum AVCodecID id); + +/** + * Get the codec tag for the given codec id. + * + * @param tags list of supported codec_id - codec_tag pairs, as stored + * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag + * @param id codec id that should be searched for in the list + * @param tag A pointer to the found tag + * @return 0 if id was not found in tags, > 0 if it was found + */ +int av_codec_get_tag2(const struct AVCodecTag * const *tags, enum AVCodecID id, + unsigned int *tag); + +int av_find_default_stream_index(AVFormatContext *s); + +/** + * Get the index for a specific timestamp. + * + * @param st stream that the timestamp belongs to + * @param timestamp timestamp to retrieve the index for + * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond + * to the timestamp which is <= the requested one, if backward + * is 0, then it will be >= + * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise + * @return < 0 if no such timestamp could be found + */ +int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags); + +/** + * Get the index entry count for the given AVStream. + * + * @param st stream + * @return the number of index entries in the stream + */ +int avformat_index_get_entries_count(const AVStream *st); + +/** + * Get the AVIndexEntry corresponding to the given index. + * + * @param st Stream containing the requested AVIndexEntry. + * @param idx The desired index. + * @return A pointer to the requested AVIndexEntry if it exists, NULL otherwise. + * + * @note The pointer returned by this function is only guaranteed to be valid + * until any function that takes the stream or the parent AVFormatContext + * as input argument is called. + */ +const AVIndexEntry *avformat_index_get_entry(AVStream *st, int idx); + +/** + * Get the AVIndexEntry corresponding to the given timestamp. + * + * @param st Stream containing the requested AVIndexEntry. + * @param wanted_timestamp Timestamp to retrieve the index entry for. + * @param flags If AVSEEK_FLAG_BACKWARD then the returned entry will correspond + * to the timestamp which is <= the requested one, if backward + * is 0, then it will be >= + * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise. + * @return A pointer to the requested AVIndexEntry if it exists, NULL otherwise. + * + * @note The pointer returned by this function is only guaranteed to be valid + * until any function that takes the stream or the parent AVFormatContext + * as input argument is called. + */ +const AVIndexEntry *avformat_index_get_entry_from_timestamp(AVStream *st, + int64_t wanted_timestamp, + int flags); +/** + * Add an index entry into a sorted list. Update the entry if the list + * already contains it. + * + * @param timestamp timestamp in the time base of the given stream + */ +int av_add_index_entry(AVStream *st, int64_t pos, int64_t timestamp, + int size, int distance, int flags); + + +/** + * Split a URL string into components. + * + * The pointers to buffers for storing individual components may be null, + * in order to ignore that component. Buffers for components not found are + * set to empty strings. If the port is not found, it is set to a negative + * value. + * + * @param proto the buffer for the protocol + * @param proto_size the size of the proto buffer + * @param authorization the buffer for the authorization + * @param authorization_size the size of the authorization buffer + * @param hostname the buffer for the host name + * @param hostname_size the size of the hostname buffer + * @param port_ptr a pointer to store the port number in + * @param path the buffer for the path + * @param path_size the size of the path buffer + * @param url the URL to split + */ +void av_url_split(char *proto, int proto_size, + char *authorization, int authorization_size, + char *hostname, int hostname_size, + int *port_ptr, + char *path, int path_size, + const char *url); + + +/** + * Print detailed information about the input or output format, such as + * duration, bitrate, streams, container, programs, metadata, side data, + * codec and time base. + * + * @param ic the context to analyze + * @param index index of the stream to dump information about + * @param url the URL to print, such as source or destination file + * @param is_output Select whether the specified context is an input(0) or output(1) + */ +void av_dump_format(AVFormatContext *ic, + int index, + const char *url, + int is_output); + + +#define AV_FRAME_FILENAME_FLAGS_MULTIPLE 1 ///< Allow multiple %d +#define AV_FRAME_FILENAME_FLAGS_IGNORE_TRUNCATION 2 ///< Ignore truncated output instead of returning an error + +/** + * Return in 'buf' the path with '%d' replaced by a number. + * + * Also handles the '%0nd' format where 'n' is the total number + * of digits and '%%'. + * + * @param buf destination buffer + * @param buf_size destination buffer size + * @param path numbered sequence string + * @param number frame number + * @param flags AV_FRAME_FILENAME_FLAGS_* + * @return 0 if OK, -1 on format error + */ +int av_get_frame_filename2(char *buf, int buf_size, + const char *path, int number, int flags); + +int av_get_frame_filename(char *buf, int buf_size, + const char *path, int number); + +/** + * Check whether filename actually is a numbered sequence generator. + * + * @param filename possible numbered sequence string + * @return 1 if a valid numbered sequence string, 0 otherwise + */ +int av_filename_number_test(const char *filename); + +/** + * Generate an SDP for an RTP session. + * + * Note, this overwrites the id values of AVStreams in the muxer contexts + * for getting unique dynamic payload types. + * + * @param ac array of AVFormatContexts describing the RTP streams. If the + * array is composed by only one context, such context can contain + * multiple AVStreams (one AVStream per RTP stream). Otherwise, + * all the contexts in the array (an AVCodecContext per RTP stream) + * must contain only one AVStream. + * @param n_files number of AVCodecContexts contained in ac + * @param buf buffer where the SDP will be stored (must be allocated by + * the caller) + * @param size the size of the buffer + * @return 0 if OK, AVERROR_xxx on error + */ +int av_sdp_create(AVFormatContext *ac[], int n_files, char *buf, int size); + +/** + * Return a positive value if the given filename has one of the given + * extensions, 0 otherwise. + * + * @param filename file name to check against the given extensions + * @param extensions a comma-separated list of filename extensions + */ +int av_match_ext(const char *filename, const char *extensions); + +/** + * Test if the given container can store a codec. + * + * @param ofmt container to check for compatibility + * @param codec_id codec to potentially store in container + * @param std_compliance standards compliance level, one of FF_COMPLIANCE_* + * + * @return 1 if codec with ID codec_id can be stored in ofmt, 0 if it cannot. + * A negative number if this information is not available. + */ +int avformat_query_codec(const AVOutputFormat *ofmt, enum AVCodecID codec_id, + int std_compliance); + +struct AVBPrint; +/** + * Make a RFC 4281/6381 like string describing a codec for MIME types. + * + * @param par pointer to an AVCodecParameters struct describing the codec + * @param frame_rate an AVRational for the frame rate, for deciding the + * right profile for video codecs. Pass an invalid + * AVRational (1/0) to indicate that it is unknown. + * @param out the AVBPrint to write the output to + * @return <0 on error + */ +int av_mime_codec_str(const AVCodecParameters *par, + AVRational frame_rate, struct AVBPrint *out); + +/** + * @defgroup riff_fourcc RIFF FourCCs + * @{ + * Get the tables mapping RIFF FourCCs to libavcodec AVCodecIDs. The tables are + * meant to be passed to av_codec_get_id()/av_codec_get_tag() as in the + * following code: + * @code + * uint32_t tag = MKTAG('H', '2', '6', '4'); + * const struct AVCodecTag *table[] = { avformat_get_riff_video_tags(), 0 }; + * enum AVCodecID id = av_codec_get_id(table, tag); + * @endcode + */ +/** + * @return the table mapping RIFF FourCCs for video to libavcodec AVCodecID. + */ +const struct AVCodecTag *avformat_get_riff_video_tags(void); +/** + * @return the table mapping RIFF FourCCs for audio to AVCodecID. + */ +const struct AVCodecTag *avformat_get_riff_audio_tags(void); +/** + * @return the table mapping MOV FourCCs for video to libavcodec AVCodecID. + */ +const struct AVCodecTag *avformat_get_mov_video_tags(void); +/** + * @return the table mapping MOV FourCCs for audio to AVCodecID. + */ +const struct AVCodecTag *avformat_get_mov_audio_tags(void); + +/** + * @} + */ + +/** + * Guess the sample aspect ratio of a frame, based on both the stream and the + * frame aspect ratio. + * + * Since the frame aspect ratio is set by the codec but the stream aspect ratio + * is set by the demuxer, these two may not be equal. This function tries to + * return the value that you should use if you would like to display the frame. + * + * Basic logic is to use the stream aspect ratio if it is set to something sane + * otherwise use the frame aspect ratio. This way a container setting, which is + * usually easy to modify can override the coded value in the frames. + * + * @param format the format context which the stream is part of + * @param stream the stream which the frame is part of + * @param frame the frame with the aspect ratio to be determined + * @return the guessed (valid) sample_aspect_ratio, 0/1 if no idea + */ +AVRational av_guess_sample_aspect_ratio(AVFormatContext *format, AVStream *stream, + struct AVFrame *frame); + +/** + * Guess the frame rate, based on both the container and codec information. + * + * @param ctx the format context which the stream is part of + * @param stream the stream which the frame is part of + * @param frame the frame for which the frame rate should be determined, may be NULL + * @return the guessed (valid) frame rate, 0/1 if no idea + */ +AVRational av_guess_frame_rate(AVFormatContext *ctx, AVStream *stream, + struct AVFrame *frame); + +/** + * Check if the stream st contained in s is matched by the stream specifier + * spec. + * + * See the "stream specifiers" chapter in the documentation for the syntax + * of spec. + * + * @return >0 if st is matched by spec; + * 0 if st is not matched by spec; + * AVERROR code if spec is invalid + * + * @note A stream specifier can match several streams in the format. + */ +int avformat_match_stream_specifier(AVFormatContext *s, AVStream *st, + const char *spec); + +int avformat_queue_attached_pictures(AVFormatContext *s); + +#if FF_API_INTERNAL_TIMING +enum AVTimebaseSource { + AVFMT_TBCF_AUTO = -1, + AVFMT_TBCF_DECODER, + AVFMT_TBCF_DEMUXER, +#if FF_API_R_FRAME_RATE + AVFMT_TBCF_R_FRAMERATE, +#endif +}; + +/** + * @deprecated do not call this function + */ +attribute_deprecated +int avformat_transfer_internal_stream_timing_info(const AVOutputFormat *ofmt, + AVStream *ost, const AVStream *ist, + enum AVTimebaseSource copy_tb); + +/** + * @deprecated do not call this function + */ +attribute_deprecated +AVRational av_stream_get_codec_timebase(const AVStream *st); +#endif + + +/** + * @} + */ + +#endif /* AVFORMAT_AVFORMAT_H */ diff --git a/ffmpeg-n8.1/include/libavformat/avio.h b/ffmpeg-n8.1/include/libavformat/avio.h new file mode 100644 index 00000000..fbcb7dbf --- /dev/null +++ b/ffmpeg-n8.1/include/libavformat/avio.h @@ -0,0 +1,831 @@ +/* + * copyright (c) 2001 Fabrice Bellard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ +#ifndef AVFORMAT_AVIO_H +#define AVFORMAT_AVIO_H + +/** + * @file + * @ingroup lavf_io + * Buffered I/O operations + */ + +#include +#include + +#include "libavutil/attributes.h" +#include "libavutil/dict.h" +#include "libavutil/log.h" + +#include "libavformat/version_major.h" + +/** + * Seeking works like for a local file. + */ +#define AVIO_SEEKABLE_NORMAL (1 << 0) + +/** + * Seeking by timestamp with avio_seek_time() is possible. + */ +#define AVIO_SEEKABLE_TIME (1 << 1) + +/** + * Callback for checking whether to abort blocking functions. + * AVERROR_EXIT is returned in this case by the interrupted + * function. During blocking operations, callback is called with + * opaque as parameter. If the callback returns 1, the + * blocking operation will be aborted. + * + * No members can be added to this struct without a major bump, if + * new elements have been added after this struct in AVFormatContext + * or AVIOContext. + */ +typedef struct AVIOInterruptCB { + int (*callback)(void*); + void *opaque; +} AVIOInterruptCB; + +/** + * Directory entry types. + */ +enum AVIODirEntryType { + AVIO_ENTRY_UNKNOWN, + AVIO_ENTRY_BLOCK_DEVICE, + AVIO_ENTRY_CHARACTER_DEVICE, + AVIO_ENTRY_DIRECTORY, + AVIO_ENTRY_NAMED_PIPE, + AVIO_ENTRY_SYMBOLIC_LINK, + AVIO_ENTRY_SOCKET, + AVIO_ENTRY_FILE, + AVIO_ENTRY_SERVER, + AVIO_ENTRY_SHARE, + AVIO_ENTRY_WORKGROUP, +}; + +/** + * Describes single entry of the directory. + * + * Only name and type fields are guaranteed be set. + * Rest of fields are protocol or/and platform dependent and might be unknown. + */ +typedef struct AVIODirEntry { + char *name; /**< Filename */ + int type; /**< Type of the entry */ + int utf8; /**< Set to 1 when name is encoded with UTF-8, 0 otherwise. + Name can be encoded with UTF-8 even though 0 is set. */ + int64_t size; /**< File size in bytes, -1 if unknown. */ + int64_t modification_timestamp; /**< Time of last modification in microseconds since unix + epoch, -1 if unknown. */ + int64_t access_timestamp; /**< Time of last access in microseconds since unix epoch, + -1 if unknown. */ + int64_t status_change_timestamp; /**< Time of last status change in microseconds since unix + epoch, -1 if unknown. */ + int64_t user_id; /**< User ID of owner, -1 if unknown. */ + int64_t group_id; /**< Group ID of owner, -1 if unknown. */ + int64_t filemode; /**< Unix file mode, -1 if unknown. */ +} AVIODirEntry; + +typedef struct AVIODirContext AVIODirContext; + +/** + * Different data types that can be returned via the AVIO + * write_data_type callback. + */ +enum AVIODataMarkerType { + /** + * Header data; this needs to be present for the stream to be decodeable. + */ + AVIO_DATA_MARKER_HEADER, + /** + * A point in the output bytestream where a decoder can start decoding + * (i.e. a keyframe). A demuxer/decoder given the data flagged with + * AVIO_DATA_MARKER_HEADER, followed by any AVIO_DATA_MARKER_SYNC_POINT, + * should give decodeable results. + */ + AVIO_DATA_MARKER_SYNC_POINT, + /** + * A point in the output bytestream where a demuxer can start parsing + * (for non self synchronizing bytestream formats). That is, any + * non-keyframe packet start point. + */ + AVIO_DATA_MARKER_BOUNDARY_POINT, + /** + * This is any, unlabelled data. It can either be a muxer not marking + * any positions at all, it can be an actual boundary/sync point + * that the muxer chooses not to mark, or a later part of a packet/fragment + * that is cut into multiple write callbacks due to limited IO buffer size. + */ + AVIO_DATA_MARKER_UNKNOWN, + /** + * Trailer data, which doesn't contain actual content, but only for + * finalizing the output file. + */ + AVIO_DATA_MARKER_TRAILER, + /** + * A point in the output bytestream where the underlying AVIOContext might + * flush the buffer depending on latency or buffering requirements. Typically + * means the end of a packet. + */ + AVIO_DATA_MARKER_FLUSH_POINT, +}; + +/** + * Bytestream IO Context. + * New public fields can be added with minor version bumps. + * Removal, reordering and changes to existing public fields require + * a major version bump. + * sizeof(AVIOContext) must not be used outside libav*. + * + * @note None of the function pointers in AVIOContext should be called + * directly, they should only be set by the client application + * when implementing custom I/O. Normally these are set to the + * function pointers specified in avio_alloc_context() + */ +typedef struct AVIOContext { + /** + * A class for private options. + * + * If this AVIOContext is created by avio_open2(), av_class is set and + * passes the options down to protocols. + * + * If this AVIOContext is manually allocated, then av_class may be set by + * the caller. + * + * warning -- this field can be NULL, be sure to not pass this AVIOContext + * to any av_opt_* functions in that case. + */ + const AVClass *av_class; + + /* + * The following shows the relationship between buffer, buf_ptr, + * buf_ptr_max, buf_end, buf_size, and pos, when reading and when writing + * (since AVIOContext is used for both): + * + ********************************************************************************** + * READING + ********************************************************************************** + * + * | buffer_size | + * |---------------------------------------| + * | | + * + * buffer buf_ptr buf_end + * +---------------+-----------------------+ + * |/ / / / / / / /|/ / / / / / /| | + * read buffer: |/ / consumed / | to be read /| | + * |/ / / / / / / /|/ / / / / / /| | + * +---------------+-----------------------+ + * + * pos + * +-------------------------------------------+-----------------+ + * input file: | | | + * +-------------------------------------------+-----------------+ + * + * + ********************************************************************************** + * WRITING + ********************************************************************************** + * + * | buffer_size | + * |--------------------------------------| + * | | + * + * buf_ptr_max + * buffer (buf_ptr) buf_end + * +-----------------------+--------------+ + * |/ / / / / / / / / / / /| | + * write buffer: | / / to be flushed / / | | + * |/ / / / / / / / / / / /| | + * +-----------------------+--------------+ + * buf_ptr can be in this + * due to a backward seek + * + * pos + * +-------------+----------------------------------------------+ + * output file: | | | + * +-------------+----------------------------------------------+ + * + */ + unsigned char *buffer; /**< Start of the buffer. */ + int buffer_size; /**< Maximum buffer size */ + unsigned char *buf_ptr; /**< Current position in the buffer */ + unsigned char *buf_end; /**< End of the data, may be less than + buffer+buffer_size if the read function returned + less data than requested, e.g. for streams where + no more data has been received yet. */ + void *opaque; /**< A private pointer, passed to the read/write/seek/... + functions. */ + int (*read_packet)(void *opaque, uint8_t *buf, int buf_size); + int (*write_packet)(void *opaque, const uint8_t *buf, int buf_size); + int64_t (*seek)(void *opaque, int64_t offset, int whence); + int64_t pos; /**< position in the file of the current buffer */ + int eof_reached; /**< true if was unable to read due to error or eof */ + int error; /**< contains the error code or 0 if no error happened */ + int write_flag; /**< true if open for writing */ + int max_packet_size; + int min_packet_size; /**< Try to buffer at least this amount of data + before flushing it. */ + unsigned long checksum; + unsigned char *checksum_ptr; + unsigned long (*update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size); + /** + * Pause or resume playback for network streaming protocols - e.g. MMS. + */ + int (*read_pause)(void *opaque, int pause); + /** + * Seek to a given timestamp in stream with the specified stream_index. + * Needed for some network streaming protocols which don't support seeking + * to byte position. + */ + int64_t (*read_seek)(void *opaque, int stream_index, + int64_t timestamp, int flags); + /** + * A combination of AVIO_SEEKABLE_ flags or 0 when the stream is not seekable. + */ + int seekable; + + /** + * avio_read and avio_write should if possible be satisfied directly + * instead of going through a buffer, and avio_seek will always + * call the underlying seek function directly. + */ + int direct; + + /** + * ',' separated list of allowed protocols. + */ + const char *protocol_whitelist; + + /** + * ',' separated list of disallowed protocols. + */ + const char *protocol_blacklist; + + /** + * A callback that is used instead of write_packet. + */ + int (*write_data_type)(void *opaque, const uint8_t *buf, int buf_size, + enum AVIODataMarkerType type, int64_t time); + /** + * If set, don't call write_data_type separately for AVIO_DATA_MARKER_BOUNDARY_POINT, + * but ignore them and treat them as AVIO_DATA_MARKER_UNKNOWN (to avoid needlessly + * small chunks of data returned from the callback). + */ + int ignore_boundary_point; + + /** + * Maximum reached position before a backward seek in the write buffer, + * used keeping track of already written data for a later flush. + */ + unsigned char *buf_ptr_max; + + /** + * Read-only statistic of bytes read for this AVIOContext. + */ + int64_t bytes_read; + + /** + * Read-only statistic of bytes written for this AVIOContext. + */ + int64_t bytes_written; +} AVIOContext; + +/** + * Return the name of the protocol that will handle the passed URL. + * + * NULL is returned if no protocol could be found for the given URL. + * + * @return Name of the protocol or NULL. + */ +const char *avio_find_protocol_name(const char *url); + +/** + * Return AVIO_FLAG_* access flags corresponding to the access permissions + * of the resource in url, or a negative value corresponding to an + * AVERROR code in case of failure. The returned access flags are + * masked by the value in flags. + * + * @note This function is intrinsically unsafe, in the sense that the + * checked resource may change its existence or permission status from + * one call to another. Thus you should not trust the returned value, + * unless you are sure that no other processes are accessing the + * checked resource. + */ +int avio_check(const char *url, int flags); + +/** + * Open directory for reading. + * + * @param s directory read context. Pointer to a NULL pointer must be passed. + * @param url directory to be listed. + * @param options A dictionary filled with protocol-private options. On return + * this parameter will be destroyed and replaced with a dictionary + * containing options that were not found. May be NULL. + * @return >=0 on success or negative on error. + */ +int avio_open_dir(AVIODirContext **s, const char *url, AVDictionary **options); + +/** + * Get next directory entry. + * + * Returned entry must be freed with avio_free_directory_entry(). In particular + * it may outlive AVIODirContext. + * + * @param s directory read context. + * @param[out] next next entry or NULL when no more entries. + * @return >=0 on success or negative on error. End of list is not considered an + * error. + */ +int avio_read_dir(AVIODirContext *s, AVIODirEntry **next); + +/** + * Close directory. + * + * @note Entries created using avio_read_dir() are not deleted and must be + * freeded with avio_free_directory_entry(). + * + * @param s directory read context. + * @return >=0 on success or negative on error. + */ +int avio_close_dir(AVIODirContext **s); + +/** + * Free entry allocated by avio_read_dir(). + * + * @param entry entry to be freed. + */ +void avio_free_directory_entry(AVIODirEntry **entry); + +/** + * Allocate and initialize an AVIOContext for buffered I/O. It must be later + * freed with avio_context_free(). + * + * @param buffer Memory block for input/output operations via AVIOContext. + * The buffer must be allocated with av_malloc() and friends. + * It may be freed and replaced with a new buffer by libavformat. + * AVIOContext.buffer holds the buffer currently in use, + * which must be later freed with av_free(). + * @param buffer_size The buffer size is very important for performance. + * For protocols with fixed blocksize it should be set to this blocksize. + * For others a typical size is a cache page, e.g. 4kb. + * @param write_flag Set to 1 if the buffer should be writable, 0 otherwise. + * @param opaque An opaque pointer to user-specific data. + * @param read_packet A function for refilling the buffer, may be NULL. + * For stream protocols, must never return 0 but rather + * a proper AVERROR code. + * @param write_packet A function for writing the buffer contents, may be NULL. + * The function may not change the input buffers content. + * @param seek A function for seeking to specified byte position, may be NULL. + * + * @return Allocated AVIOContext or NULL on failure. + */ +AVIOContext *avio_alloc_context( + unsigned char *buffer, + int buffer_size, + int write_flag, + void *opaque, + int (*read_packet)(void *opaque, uint8_t *buf, int buf_size), + int (*write_packet)(void *opaque, const uint8_t *buf, int buf_size), + int64_t (*seek)(void *opaque, int64_t offset, int whence)); + +/** + * Free the supplied IO context and everything associated with it. + * + * @param s Double pointer to the IO context. This function will write NULL + * into s. + */ +void avio_context_free(AVIOContext **s); + +void avio_w8(AVIOContext *s, int b); +void avio_write(AVIOContext *s, const unsigned char *buf, int size); +void avio_wl64(AVIOContext *s, uint64_t val); +void avio_wb64(AVIOContext *s, uint64_t val); +void avio_wl32(AVIOContext *s, unsigned int val); +void avio_wb32(AVIOContext *s, unsigned int val); +void avio_wl24(AVIOContext *s, unsigned int val); +void avio_wb24(AVIOContext *s, unsigned int val); +void avio_wl16(AVIOContext *s, unsigned int val); +void avio_wb16(AVIOContext *s, unsigned int val); + +/** + * Write a NULL-terminated string. + * @return number of bytes written. + */ +int avio_put_str(AVIOContext *s, const char *str); + +/** + * Convert an UTF-8 string to UTF-16LE and write it. + * @param s the AVIOContext + * @param str NULL-terminated UTF-8 string + * + * @return number of bytes written. + */ +int avio_put_str16le(AVIOContext *s, const char *str); + +/** + * Convert an UTF-8 string to UTF-16BE and write it. + * @param s the AVIOContext + * @param str NULL-terminated UTF-8 string + * + * @return number of bytes written. + */ +int avio_put_str16be(AVIOContext *s, const char *str); + +/** + * Mark the written bytestream as a specific type. + * + * Zero-length ranges are omitted from the output. + * + * @param s the AVIOContext + * @param time the stream time the current bytestream pos corresponds to + * (in AV_TIME_BASE units), or AV_NOPTS_VALUE if unknown or not + * applicable + * @param type the kind of data written starting at the current pos + */ +void avio_write_marker(AVIOContext *s, int64_t time, enum AVIODataMarkerType type); + +/** + * Passing this as the "whence" parameter to a seek function causes it to + * return the filesize without seeking anywhere. Supporting this is optional. + * If it is not supported then the seek function will return <0. + */ +#define AVSEEK_SIZE 0x10000 + +/** + * OR'ing this flag into the "whence" parameter to a seek function causes it to + * seek by any means (like reopening and linear reading) or other normally unreasonable + * means that can be extremely slow. + * This is the default and therefore ignored by the seek code since 2010. + */ +#define AVSEEK_FORCE 0x20000 + +/** + * fseek() equivalent for AVIOContext. + * @return new position or AVERROR. + */ +int64_t avio_seek(AVIOContext *s, int64_t offset, int whence); + +/** + * Skip given number of bytes forward + * @return new position or AVERROR. + */ +int64_t avio_skip(AVIOContext *s, int64_t offset); + +/** + * ftell() equivalent for AVIOContext. + * @return position or AVERROR. + */ +static av_always_inline int64_t avio_tell(AVIOContext *s) +{ + return avio_seek(s, 0, SEEK_CUR); +} + +/** + * Get the filesize. + * @return filesize or AVERROR + */ +int64_t avio_size(AVIOContext *s); + +/** + * Similar to feof() but also returns nonzero on read errors. + * @return non zero if and only if at end of file or a read error happened when reading. + */ +int avio_feof(AVIOContext *s); + +/** + * Writes a formatted string to the context taking a va_list. + * @return number of bytes written, < 0 on error. + */ +int avio_vprintf(AVIOContext *s, const char *fmt, va_list ap); + +/** + * Writes a formatted string to the context. + * @return number of bytes written, < 0 on error. + */ +int avio_printf(AVIOContext *s, const char *fmt, ...) av_printf_format(2, 3); + +/** + * Write a NULL terminated array of strings to the context. + * Usually you don't need to use this function directly but its macro wrapper, + * avio_print. + */ +void avio_print_string_array(AVIOContext *s, const char * const strings[]); + +/** + * Write strings (const char *) to the context. + * This is a convenience macro around avio_print_string_array and it + * automatically creates the string array from the variable argument list. + * For simple string concatenations this function is more performant than using + * avio_printf since it does not need a temporary buffer. + */ +#define avio_print(s, ...) \ + avio_print_string_array(s, (const char*[]){__VA_ARGS__, NULL}) + +/** + * Force flushing of buffered data. + * + * For write streams, force the buffered data to be immediately written to the output, + * without to wait to fill the internal buffer. + * + * For read streams, discard all currently buffered data, and advance the + * reported file position to that of the underlying stream. This does not + * read new data, and does not perform any seeks. + */ +void avio_flush(AVIOContext *s); + +/** + * Read size bytes from AVIOContext into buf. + * @return number of bytes read or AVERROR + */ +int avio_read(AVIOContext *s, unsigned char *buf, int size); + +/** + * Read size bytes from AVIOContext into buf. Unlike avio_read(), this is allowed + * to read fewer bytes than requested. The missing bytes can be read in the next + * call. This always tries to read at least 1 byte. + * Useful to reduce latency in certain cases. + * @return number of bytes read or AVERROR + */ +int avio_read_partial(AVIOContext *s, unsigned char *buf, int size); + +/** + * @name Functions for reading from AVIOContext + * @{ + * + * @note return 0 if EOF, so you cannot use it if EOF handling is + * necessary + */ +int avio_r8 (AVIOContext *s); +unsigned int avio_rl16(AVIOContext *s); +unsigned int avio_rl24(AVIOContext *s); +unsigned int avio_rl32(AVIOContext *s); +uint64_t avio_rl64(AVIOContext *s); +unsigned int avio_rb16(AVIOContext *s); +unsigned int avio_rb24(AVIOContext *s); +unsigned int avio_rb32(AVIOContext *s); +uint64_t avio_rb64(AVIOContext *s); +/** + * @} + */ + +/** + * Read a string from pb into buf. The reading will terminate when either + * a NULL character was encountered, maxlen bytes have been read, or nothing + * more can be read from pb. The result is guaranteed to be NULL-terminated, it + * will be truncated if buf is too small. + * Note that the string is not interpreted or validated in any way, it + * might get truncated in the middle of a sequence for multi-byte encodings. + * + * @return number of bytes read (is always <= maxlen). + * If reading ends on EOF or error, the return value will be one more than + * bytes actually read. + */ +int avio_get_str(AVIOContext *pb, int maxlen, char *buf, int buflen); + +/** + * Read a UTF-16 string from pb and convert it to UTF-8. + * The reading will terminate when either a null or invalid character was + * encountered or maxlen bytes have been read. + * @return number of bytes read (is always <= maxlen) + */ +int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen); +int avio_get_str16be(AVIOContext *pb, int maxlen, char *buf, int buflen); + + +/** + * @name URL open modes + * The flags argument to avio_open must be one of the following + * constants, optionally ORed with other flags. + * @{ + */ +#define AVIO_FLAG_READ 1 /**< read-only */ +#define AVIO_FLAG_WRITE 2 /**< write-only */ +#define AVIO_FLAG_READ_WRITE (AVIO_FLAG_READ|AVIO_FLAG_WRITE) /**< read-write pseudo flag */ +/** + * @} + */ + +/** + * Use non-blocking mode. + * If this flag is set, operations on the context will return + * AVERROR(EAGAIN) if they can not be performed immediately. + * If this flag is not set, operations on the context will never return + * AVERROR(EAGAIN). + * Note that this flag does not affect the opening/connecting of the + * context. Connecting a protocol will always block if necessary (e.g. on + * network protocols) but never hang (e.g. on busy devices). + * Warning: non-blocking protocols is work-in-progress; this flag may be + * silently ignored. + */ +#define AVIO_FLAG_NONBLOCK 8 + +/** + * Use direct mode. + * avio_read and avio_write should if possible be satisfied directly + * instead of going through a buffer, and avio_seek will always + * call the underlying seek function directly. + */ +#define AVIO_FLAG_DIRECT 0x8000 + +/** + * Create and initialize a AVIOContext for accessing the + * resource indicated by url. + * @note When the resource indicated by url has been opened in + * read+write mode, the AVIOContext can be used only for writing. + * + * @param s Used to return the pointer to the created AVIOContext. + * In case of failure the pointed to value is set to NULL. + * @param url resource to access + * @param flags flags which control how the resource indicated by url + * is to be opened + * @return >= 0 in case of success, a negative value corresponding to an + * AVERROR code in case of failure + */ +int avio_open(AVIOContext **s, const char *url, int flags); + +/** + * Create and initialize a AVIOContext for accessing the + * resource indicated by url. + * @note When the resource indicated by url has been opened in + * read+write mode, the AVIOContext can be used only for writing. + * + * @param s Used to return the pointer to the created AVIOContext. + * In case of failure the pointed to value is set to NULL. + * @param url resource to access + * @param flags flags which control how the resource indicated by url + * is to be opened + * @param int_cb an interrupt callback to be used at the protocols level + * @param options A dictionary filled with protocol-private options. On return + * this parameter will be destroyed and replaced with a dict containing options + * that were not found. May be NULL. + * @return >= 0 in case of success, a negative value corresponding to an + * AVERROR code in case of failure + */ +int avio_open2(AVIOContext **s, const char *url, int flags, + const AVIOInterruptCB *int_cb, AVDictionary **options); + +/** + * Close the resource accessed by the AVIOContext s and free it. + * This function can only be used if s was opened by avio_open(). + * + * The internal buffer is automatically flushed before closing the + * resource. + * + * @return 0 on success, an AVERROR < 0 on error. + * @see avio_closep + */ +int avio_close(AVIOContext *s); + +/** + * Close the resource accessed by the AVIOContext *s, free it + * and set the pointer pointing to it to NULL. + * This function can only be used if s was opened by avio_open(). + * + * The internal buffer is automatically flushed before closing the + * resource. + * + * @return 0 on success, an AVERROR < 0 on error. + * @see avio_close + */ +int avio_closep(AVIOContext **s); + + +/** + * Open a write only memory stream. + * + * @param s new IO context + * @return zero if no error. + */ +int avio_open_dyn_buf(AVIOContext **s); + +/** + * Return the written size and a pointer to the buffer. + * The AVIOContext stream is left intact. + * The buffer must NOT be freed. + * No padding is added to the buffer. + * + * @param s IO context + * @param pbuffer pointer to a byte buffer + * @return the length of the byte buffer + */ +int avio_get_dyn_buf(AVIOContext *s, uint8_t **pbuffer); + +/** + * Return the written size and a pointer to the buffer. The buffer + * must be freed with av_free(). + * Padding of AV_INPUT_BUFFER_PADDING_SIZE is added to the buffer. + * + * @param s IO context + * @param pbuffer pointer to a byte buffer + * @return the length of the byte buffer + */ +int avio_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer); + +/** + * Iterate through names of available protocols. + * + * @param opaque A private pointer representing current protocol. + * It must be a pointer to NULL on first iteration and will + * be updated by successive calls to avio_enum_protocols. + * @param output If set to 1, iterate over output protocols, + * otherwise over input protocols. + * + * @return A static string containing the name of current protocol or NULL + */ +const char *avio_enum_protocols(void **opaque, int output); + +/** + * Get AVClass by names of available protocols. + * + * @return A AVClass of input protocol name or NULL + */ +const AVClass *avio_protocol_get_class(const char *name); + +/** + * Pause and resume playing - only meaningful if using a network streaming + * protocol (e.g. MMS). + * + * @param h IO context from which to call the read_pause function pointer + * @param pause 1 for pause, 0 for resume + */ +int avio_pause(AVIOContext *h, int pause); + +/** + * Seek to a given timestamp relative to some component stream. + * Only meaningful if using a network streaming protocol (e.g. MMS.). + * + * @param h IO context from which to call the seek function pointers + * @param stream_index The stream index that the timestamp is relative to. + * If stream_index is (-1) the timestamp should be in AV_TIME_BASE + * units from the beginning of the presentation. + * If a stream_index >= 0 is used and the protocol does not support + * seeking based on component streams, the call will fail. + * @param timestamp timestamp in AVStream.time_base units + * or if there is no stream specified then in AV_TIME_BASE units. + * @param flags Optional combination of AVSEEK_FLAG_BACKWARD, AVSEEK_FLAG_BYTE + * and AVSEEK_FLAG_ANY. The protocol may silently ignore + * AVSEEK_FLAG_BACKWARD and AVSEEK_FLAG_ANY, but AVSEEK_FLAG_BYTE will + * fail if used and not supported. + * @return >= 0 on success + * @see AVInputFormat::read_seek + */ +int64_t avio_seek_time(AVIOContext *h, int stream_index, + int64_t timestamp, int flags); + +/* Avoid a warning. The header can not be included because it breaks c++. */ +struct AVBPrint; + +/** + * Read contents of h into print buffer, up to max_size bytes, or up to EOF. + * + * @return 0 for success (max_size bytes read or EOF reached), negative error + * code otherwise + */ +int avio_read_to_bprint(AVIOContext *h, struct AVBPrint *pb, size_t max_size); + +/** + * Accept and allocate a client context on a server context. + * @param s the server context + * @param c the client context, must be unallocated + * @return >= 0 on success or a negative value corresponding + * to an AVERROR on failure + */ +int avio_accept(AVIOContext *s, AVIOContext **c); + +/** + * Perform one step of the protocol handshake to accept a new client. + * This function must be called on a client returned by avio_accept() before + * using it as a read/write context. + * It is separate from avio_accept() because it may block. + * A step of the handshake is defined by places where the application may + * decide to change the proceedings. + * For example, on a protocol with a request header and a reply header, each + * one can constitute a step because the application may use the parameters + * from the request to change parameters in the reply; or each individual + * chunk of the request can constitute a step. + * If the handshake is already finished, avio_handshake() does nothing and + * returns 0 immediately. + * + * @param c the client context to perform the handshake on + * @return 0 on a complete and successful handshake + * > 0 if the handshake progressed, but is not complete + * < 0 for an AVERROR code + */ +int avio_handshake(AVIOContext *c); +#endif /* AVFORMAT_AVIO_H */ diff --git a/ffmpeg-n8.1/include/libavformat/version.h b/ffmpeg-n8.1/include/libavformat/version.h new file mode 100644 index 00000000..cb67e0a1 --- /dev/null +++ b/ffmpeg-n8.1/include/libavformat/version.h @@ -0,0 +1,47 @@ +/* + * Version macros. + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFORMAT_VERSION_H +#define AVFORMAT_VERSION_H + +/** + * @file + * @ingroup libavf + * Libavformat version macros + */ + +#include "libavutil/version.h" + +#include "version_major.h" + +#define LIBAVFORMAT_VERSION_MINOR 12 +#define LIBAVFORMAT_VERSION_MICRO 100 + +#define LIBAVFORMAT_VERSION_INT AV_VERSION_INT(LIBAVFORMAT_VERSION_MAJOR, \ + LIBAVFORMAT_VERSION_MINOR, \ + LIBAVFORMAT_VERSION_MICRO) +#define LIBAVFORMAT_VERSION AV_VERSION(LIBAVFORMAT_VERSION_MAJOR, \ + LIBAVFORMAT_VERSION_MINOR, \ + LIBAVFORMAT_VERSION_MICRO) +#define LIBAVFORMAT_BUILD LIBAVFORMAT_VERSION_INT + +#define LIBAVFORMAT_IDENT "Lavf" AV_STRINGIFY(LIBAVFORMAT_VERSION) + +#endif /* AVFORMAT_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libavformat/version_major.h b/ffmpeg-n8.1/include/libavformat/version_major.h new file mode 100644 index 00000000..c2f6e161 --- /dev/null +++ b/ffmpeg-n8.1/include/libavformat/version_major.h @@ -0,0 +1,52 @@ +/* + * Version macros. + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVFORMAT_VERSION_MAJOR_H +#define AVFORMAT_VERSION_MAJOR_H + +/** + * @file + * @ingroup libavf + * Libavformat version macros + */ + +// Major bumping may affect Ticket5467, 5421, 5451(compatibility with Chromium) +// Also please add any ticket numbers that you believe might be affected here +#define LIBAVFORMAT_VERSION_MAJOR 62 + +/** + * FF_API_* defines may be placed below to indicate public API that will be + * dropped at a future version bump. The defines themselves are not part of + * the public API and may change, break or disappear at any time. + * + * @note, when bumping the major version it is recommended to manually + * disable each FF_API_* in its own commit instead of disabling them all + * at once through the bump. This improves the git bisect-ability of the change. + * + */ +#define FF_API_COMPUTE_PKT_FIELDS2 (LIBAVFORMAT_VERSION_MAJOR < 63) + +#define FF_API_INTERNAL_TIMING (LIBAVFORMAT_VERSION_MAJOR < 63) + +#define FF_API_NO_DEFAULT_TLS_VERIFY (LIBAVFORMAT_VERSION_MAJOR < 63) + +#define FF_API_R_FRAME_RATE 1 + +#endif /* AVFORMAT_VERSION_MAJOR_H */ diff --git a/ffmpeg-n8.1/include/libavutil/adler32.h b/ffmpeg-n8.1/include/libavutil/adler32.h new file mode 100644 index 00000000..232d07f5 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/adler32.h @@ -0,0 +1,63 @@ +/* + * copyright (c) 2006 Mans Rullgard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_adler32 + * Public header for Adler-32 hash function implementation. + */ + +#ifndef AVUTIL_ADLER32_H +#define AVUTIL_ADLER32_H + +#include +#include +#include "attributes.h" + +/** + * @defgroup lavu_adler32 Adler-32 + * @ingroup lavu_hash + * Adler-32 hash function implementation. + * + * @{ + */ + +typedef uint32_t AVAdler; + +/** + * Calculate the Adler32 checksum of a buffer. + * + * Passing the return value to a subsequent av_adler32_update() call + * allows the checksum of multiple buffers to be calculated as though + * they were concatenated. + * + * @param adler initial checksum value + * @param buf pointer to input buffer + * @param len size of input buffer + * @return updated checksum + */ +AVAdler av_adler32_update(AVAdler adler, const uint8_t *buf, + size_t len) av_pure; + +/** + * @} + */ + +#endif /* AVUTIL_ADLER32_H */ diff --git a/ffmpeg-n8.1/include/libavutil/aes.h b/ffmpeg-n8.1/include/libavutil/aes.h new file mode 100644 index 00000000..4e734736 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/aes.h @@ -0,0 +1,69 @@ +/* + * copyright (c) 2007 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_AES_H +#define AVUTIL_AES_H + +#include + +#include "attributes.h" + +/** + * @defgroup lavu_aes AES + * @ingroup lavu_crypto + * @{ + */ + +extern const int av_aes_size; + +struct AVAES; + +/** + * Allocate an AVAES context. + */ +struct AVAES *av_aes_alloc(void); + +/** + * Initialize an AVAES context. + * + * @param a The AVAES context + * @param key Pointer to the key + * @param key_bits 128, 192 or 256 + * @param decrypt 0 for encryption, 1 for decryption + */ +int av_aes_init(struct AVAES *a, const uint8_t *key, int key_bits, int decrypt); + +/** + * Encrypt or decrypt a buffer using a previously initialized context. + * + * @param a The AVAES context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 16 byte blocks + * @param iv initialization vector for CBC mode, if NULL then ECB will be used + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_aes_crypt(struct AVAES *a, uint8_t *dst, const uint8_t *src, int count, uint8_t *iv, int decrypt); + +/** + * @} + */ + +#endif /* AVUTIL_AES_H */ diff --git a/ffmpeg-n8.1/include/libavutil/aes_ctr.h b/ffmpeg-n8.1/include/libavutil/aes_ctr.h new file mode 100644 index 00000000..d98c0712 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/aes_ctr.h @@ -0,0 +1,99 @@ +/* + * AES-CTR cipher + * Copyright (c) 2015 Eran Kornblau + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_AES_CTR_H +#define AVUTIL_AES_CTR_H + +/** + * @defgroup lavu_aes_ctr AES-CTR + * @ingroup lavu_crypto + * @{ + */ + +#include + +#include "attributes.h" + +#define AES_CTR_KEY_SIZE (16) +#define AES_CTR_IV_SIZE (8) + +struct AVAESCTR; + +/** + * Allocate an AVAESCTR context. + */ +struct AVAESCTR *av_aes_ctr_alloc(void); + +/** + * Initialize an AVAESCTR context. + * + * @param a The AVAESCTR context to initialize + * @param key encryption key, must have a length of AES_CTR_KEY_SIZE + */ +int av_aes_ctr_init(struct AVAESCTR *a, const uint8_t *key); + +/** + * Release an AVAESCTR context. + * + * @param a The AVAESCTR context + */ +void av_aes_ctr_free(struct AVAESCTR *a); + +/** + * Process a buffer using a previously initialized context. + * + * @param a The AVAESCTR context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param size the size of src and dst + */ +void av_aes_ctr_crypt(struct AVAESCTR *a, uint8_t *dst, const uint8_t *src, int size); + +/** + * Get the current iv + */ +const uint8_t* av_aes_ctr_get_iv(struct AVAESCTR *a); + +/** + * Generate a random iv + */ +void av_aes_ctr_set_random_iv(struct AVAESCTR *a); + +/** + * Forcefully change the 8-byte iv + */ +void av_aes_ctr_set_iv(struct AVAESCTR *a, const uint8_t* iv); + +/** + * Forcefully change the "full" 16-byte iv, including the counter + */ +void av_aes_ctr_set_full_iv(struct AVAESCTR *a, const uint8_t* iv); + +/** + * Increment the top 64 bit of the iv (performed after each frame) + */ +void av_aes_ctr_increment_iv(struct AVAESCTR *a); + +/** + * @} + */ + +#endif /* AVUTIL_AES_CTR_H */ diff --git a/ffmpeg-n8.1/include/libavutil/ambient_viewing_environment.h b/ffmpeg-n8.1/include/libavutil/ambient_viewing_environment.h new file mode 100644 index 00000000..e5e4ac21 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/ambient_viewing_environment.h @@ -0,0 +1,72 @@ +/* + * Copyright (c) 2023 Jan Ekström + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_AMBIENT_VIEWING_ENVIRONMENT_H +#define AVUTIL_AMBIENT_VIEWING_ENVIRONMENT_H + +#include +#include "frame.h" +#include "rational.h" + +/** + * Ambient viewing environment metadata as defined by H.274. The values are + * saved in AVRationals so that they keep their exactness, while allowing for + * easy access to a double value with f.ex. av_q2d. + * + * @note sizeof(AVAmbientViewingEnvironment) is not part of the public ABI, and + * it must be allocated using av_ambient_viewing_environment_alloc. + */ +typedef struct AVAmbientViewingEnvironment { + /** + * Environmental illuminance of the ambient viewing environment in lux. + */ + AVRational ambient_illuminance; + + /** + * Normalized x chromaticity coordinate of the environmental ambient light + * in the nominal viewing environment according to the CIE 1931 definition + * of x and y as specified in ISO/CIE 11664-1. + */ + AVRational ambient_light_x; + + /** + * Normalized y chromaticity coordinate of the environmental ambient light + * in the nominal viewing environment according to the CIE 1931 definition + * of x and y as specified in ISO/CIE 11664-1. + */ + AVRational ambient_light_y; +} AVAmbientViewingEnvironment; + +/** + * Allocate an AVAmbientViewingEnvironment structure. + * + * @return the newly allocated struct or NULL on failure + */ +AVAmbientViewingEnvironment *av_ambient_viewing_environment_alloc(size_t *size); + +/** + * Allocate and add an AVAmbientViewingEnvironment structure to an existing + * AVFrame as side data. + * + * @return the newly allocated struct, or NULL on failure + */ +AVAmbientViewingEnvironment *av_ambient_viewing_environment_create_side_data(AVFrame *frame); + +#endif /* AVUTIL_AMBIENT_VIEWING_ENVIRONMENT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/attributes.h b/ffmpeg-n8.1/include/libavutil/attributes.h new file mode 100644 index 00000000..0e49b22b --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/attributes.h @@ -0,0 +1,227 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * Macro definitions for various function/variable attributes + */ + +#ifndef AVUTIL_ATTRIBUTES_H +#define AVUTIL_ATTRIBUTES_H + +#ifdef __GNUC__ +# define AV_GCC_VERSION_AT_LEAST(x,y) (__GNUC__ > (x) || __GNUC__ == (x) && __GNUC_MINOR__ >= (y)) +# define AV_GCC_VERSION_AT_MOST(x,y) (__GNUC__ < (x) || __GNUC__ == (x) && __GNUC_MINOR__ <= (y)) +#else +# define AV_GCC_VERSION_AT_LEAST(x,y) 0 +# define AV_GCC_VERSION_AT_MOST(x,y) 0 +#endif + +#ifdef __has_builtin +# define AV_HAS_BUILTIN(x) __has_builtin(x) +#else +# define AV_HAS_BUILTIN(x) 0 +#endif + +#ifdef __has_attribute +# define AV_HAS_ATTRIBUTE(x) __has_attribute(x) +#else +# define AV_HAS_ATTRIBUTE(x) 0 +#endif + +#if defined(__cplusplus) && \ + defined(__has_cpp_attribute) && \ + __cplusplus >= 201103L +# define AV_HAS_STD_ATTRIBUTE(x) __has_cpp_attribute(x) +#elif !defined(__cplusplus) && \ + defined(__has_c_attribute) && \ + defined(__STDC_VERSION__) && \ + __STDC_VERSION__ >= 202311L +# define AV_HAS_STD_ATTRIBUTE(x) __has_c_attribute(x) +#else +# define AV_HAS_STD_ATTRIBUTE(x) 0 +#endif + +#ifndef av_always_inline +#if AV_GCC_VERSION_AT_LEAST(3,1) || defined(__clang__) +# define av_always_inline __attribute__((always_inline)) inline +#elif defined(_MSC_VER) +# define av_always_inline __forceinline +#else +# define av_always_inline inline +#endif +#endif + +#ifndef av_extern_inline +#if defined(__ICL) && __ICL >= 1210 || defined(__GNUC_STDC_INLINE__) +# define av_extern_inline extern inline +#else +# define av_extern_inline inline +#endif +#endif + +#if AV_HAS_STD_ATTRIBUTE(nodiscard) +# define av_warn_unused_result [[nodiscard]] +#elif AV_GCC_VERSION_AT_LEAST(3,4) || defined(__clang__) +# define av_warn_unused_result __attribute__((warn_unused_result)) +#else +# define av_warn_unused_result +#endif + +#if AV_GCC_VERSION_AT_LEAST(3,1) || defined(__clang__) +# define av_noinline __attribute__((noinline)) +#elif defined(_MSC_VER) +# define av_noinline __declspec(noinline) +#else +# define av_noinline +#endif + +#if AV_GCC_VERSION_AT_LEAST(3,1) || defined(__clang__) +# define av_pure __attribute__((pure)) +#else +# define av_pure +#endif + +#if AV_GCC_VERSION_AT_LEAST(2,6) || defined(__clang__) +# define av_const __attribute__((const)) +#else +# define av_const +#endif + +#if AV_GCC_VERSION_AT_LEAST(4,3) || defined(__clang__) +# define av_cold __attribute__((cold)) +#else +# define av_cold +#endif + +#if AV_GCC_VERSION_AT_LEAST(4,1) && !defined(__llvm__) +# define av_flatten __attribute__((flatten)) +#else +# define av_flatten +#endif + +#if AV_HAS_STD_ATTRIBUTE(deprecated) +# define attribute_deprecated [[deprecated]] +#elif AV_GCC_VERSION_AT_LEAST(3,1) || defined(__clang__) +# define attribute_deprecated __attribute__((deprecated)) +#elif defined(_MSC_VER) +# define attribute_deprecated __declspec(deprecated) +#else +# define attribute_deprecated +#endif + +/** + * Disable warnings about deprecated features + * This is useful for sections of code kept for backward compatibility and + * scheduled for removal. + */ +#ifndef AV_NOWARN_DEPRECATED +#if AV_GCC_VERSION_AT_LEAST(4,6) || defined(__clang__) +# define AV_NOWARN_DEPRECATED(code) \ + _Pragma("GCC diagnostic push") \ + _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"") \ + code \ + _Pragma("GCC diagnostic pop") +#elif defined(_MSC_VER) +# define AV_NOWARN_DEPRECATED(code) \ + __pragma(warning(push)) \ + __pragma(warning(disable : 4996)) \ + code; \ + __pragma(warning(pop)) +#else +# define AV_NOWARN_DEPRECATED(code) code +#endif +#endif + +#if AV_HAS_STD_ATTRIBUTE(maybe_unused) +# define av_unused [[maybe_unused]] +#elif defined(__GNUC__) || defined(__clang__) +# define av_unused __attribute__((unused)) +#else +# define av_unused +#endif + +/** + * Mark a variable as used and prevent the compiler from optimizing it + * away. This is useful for variables accessed only from inline + * assembler without the compiler being aware. + */ +#if AV_GCC_VERSION_AT_LEAST(3,1) || defined(__clang__) +# define av_used __attribute__((used)) +#else +# define av_used +#endif + +#if AV_GCC_VERSION_AT_LEAST(3,3) || defined(__clang__) +# define av_alias __attribute__((may_alias)) +#else +# define av_alias +#endif + +#if (defined(__GNUC__) || defined(__clang__)) && !defined(__INTEL_COMPILER) +# define av_uninit(x) x=x +#else +# define av_uninit(x) x +#endif + +#if defined(__GNUC__) || defined(__clang__) +# define av_builtin_constant_p __builtin_constant_p +#else +# define av_builtin_constant_p(x) 0 +#endif + +// for __MINGW_PRINTF_FORMAT and __MINGW_SCANF_FORMAT +#ifdef __MINGW32__ +# include +#endif + +#ifdef __MINGW_PRINTF_FORMAT +# define AV_PRINTF_FMT __MINGW_PRINTF_FORMAT +#elif AV_HAS_ATTRIBUTE(format) +# define AV_PRINTF_FMT __printf__ +#endif + +#ifdef __MINGW_SCANF_FORMAT +# define AV_SCANF_FMT __MINGW_SCANF_FORMAT +#elif AV_HAS_ATTRIBUTE(format) +# define AV_SCANF_FMT __scanf__ +#endif + +#ifdef AV_PRINTF_FMT +# define av_printf_format(fmtpos, attrpos) __attribute__((format(AV_PRINTF_FMT, fmtpos, attrpos))) +#else +# define av_printf_format(fmtpos, attrpos) +#endif + +#ifdef AV_SCANF_FMT +# define av_scanf_format(fmtpos, attrpos) __attribute__((format(AV_SCANF_FMT, fmtpos, attrpos))) +#else +# define av_scanf_format(fmtpos, attrpos) +#endif + +#if AV_HAS_STD_ATTRIBUTE(noreturn) +# define av_noreturn [[noreturn]] +#elif AV_GCC_VERSION_AT_LEAST(2,5) || defined(__clang__) +# define av_noreturn __attribute__((noreturn)) +#else +# define av_noreturn +#endif + +#endif /* AVUTIL_ATTRIBUTES_H */ diff --git a/ffmpeg-n8.1/include/libavutil/audio_fifo.h b/ffmpeg-n8.1/include/libavutil/audio_fifo.h new file mode 100644 index 00000000..fa5f59a2 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/audio_fifo.h @@ -0,0 +1,187 @@ +/* + * Audio FIFO + * Copyright (c) 2012 Justin Ruggles + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * Audio FIFO Buffer + */ + +#ifndef AVUTIL_AUDIO_FIFO_H +#define AVUTIL_AUDIO_FIFO_H + +#include "attributes.h" +#include "samplefmt.h" + +/** + * @addtogroup lavu_audio + * @{ + * + * @defgroup lavu_audiofifo Audio FIFO Buffer + * @{ + */ + +/** + * Context for an Audio FIFO Buffer. + * + * - Operates at the sample level rather than the byte level. + * - Supports multiple channels with either planar or packed sample format. + * - Automatic reallocation when writing to a full buffer. + */ +typedef struct AVAudioFifo AVAudioFifo; + +/** + * Free an AVAudioFifo. + * + * @param af AVAudioFifo to free + */ +void av_audio_fifo_free(AVAudioFifo *af); + +/** + * Allocate an AVAudioFifo. + * + * @param sample_fmt sample format + * @param channels number of channels + * @param nb_samples initial allocation size, in samples + * @return newly allocated AVAudioFifo, or NULL on error + */ +AVAudioFifo *av_audio_fifo_alloc(enum AVSampleFormat sample_fmt, int channels, + int nb_samples); + +/** + * Reallocate an AVAudioFifo. + * + * @param af AVAudioFifo to reallocate + * @param nb_samples new allocation size, in samples + * @return 0 if OK, or negative AVERROR code on failure + */ +av_warn_unused_result +int av_audio_fifo_realloc(AVAudioFifo *af, int nb_samples); + +/** + * Write data to an AVAudioFifo. + * + * The AVAudioFifo will be reallocated automatically if the available space + * is less than nb_samples. + * + * @see enum AVSampleFormat + * The documentation for AVSampleFormat describes the data layout. + * + * @param af AVAudioFifo to write to + * @param data audio data plane pointers + * @param nb_samples number of samples to write + * @return number of samples actually written, or negative AVERROR + * code on failure. If successful, the number of samples + * actually written will always be nb_samples. + */ +int av_audio_fifo_write(AVAudioFifo *af, void * const *data, int nb_samples); + +/** + * Peek data from an AVAudioFifo. + * + * @see enum AVSampleFormat + * The documentation for AVSampleFormat describes the data layout. + * + * @param af AVAudioFifo to read from + * @param data audio data plane pointers + * @param nb_samples number of samples to peek + * @return number of samples actually peek, or negative AVERROR code + * on failure. The number of samples actually peek will not + * be greater than nb_samples, and will only be less than + * nb_samples if av_audio_fifo_size is less than nb_samples. + */ +int av_audio_fifo_peek(const AVAudioFifo *af, void * const *data, int nb_samples); + +/** + * Peek data from an AVAudioFifo. + * + * @see enum AVSampleFormat + * The documentation for AVSampleFormat describes the data layout. + * + * @param af AVAudioFifo to read from + * @param data audio data plane pointers + * @param nb_samples number of samples to peek + * @param offset offset from current read position + * @return number of samples actually peek, or negative AVERROR code + * on failure. The number of samples actually peek will not + * be greater than nb_samples, and will only be less than + * nb_samples if av_audio_fifo_size is less than nb_samples. + */ +int av_audio_fifo_peek_at(const AVAudioFifo *af, void * const *data, + int nb_samples, int offset); + +/** + * Read data from an AVAudioFifo. + * + * @see enum AVSampleFormat + * The documentation for AVSampleFormat describes the data layout. + * + * @param af AVAudioFifo to read from + * @param data audio data plane pointers + * @param nb_samples number of samples to read + * @return number of samples actually read, or negative AVERROR code + * on failure. The number of samples actually read will not + * be greater than nb_samples, and will only be less than + * nb_samples if av_audio_fifo_size is less than nb_samples. + */ +int av_audio_fifo_read(AVAudioFifo *af, void * const *data, int nb_samples); + +/** + * Drain data from an AVAudioFifo. + * + * Removes the data without reading it. + * + * @param af AVAudioFifo to drain + * @param nb_samples number of samples to drain + * @return 0 if OK, or negative AVERROR code on failure + */ +int av_audio_fifo_drain(AVAudioFifo *af, int nb_samples); + +/** + * Reset the AVAudioFifo buffer. + * + * This empties all data in the buffer. + * + * @param af AVAudioFifo to reset + */ +void av_audio_fifo_reset(AVAudioFifo *af); + +/** + * Get the current number of samples in the AVAudioFifo available for reading. + * + * @param af the AVAudioFifo to query + * @return number of samples available for reading + */ +int av_audio_fifo_size(AVAudioFifo *af); + +/** + * Get the current number of samples in the AVAudioFifo available for writing. + * + * @param af the AVAudioFifo to query + * @return number of samples available for writing + */ +int av_audio_fifo_space(AVAudioFifo *af); + +/** + * @} + * @} + */ + +#endif /* AVUTIL_AUDIO_FIFO_H */ diff --git a/ffmpeg-n8.1/include/libavutil/avassert.h b/ffmpeg-n8.1/include/libavutil/avassert.h new file mode 100644 index 00000000..e316a3c9 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/avassert.h @@ -0,0 +1,125 @@ +/* + * copyright (c) 2010 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * simple assert() macros that are a bit more flexible than ISO C assert(). + * @author Michael Niedermayer + */ + +#ifndef AVUTIL_AVASSERT_H +#define AVUTIL_AVASSERT_H + +#include +#ifdef HAVE_AV_CONFIG_H +# include "config.h" +#endif +#include "attributes.h" +#include "log.h" +#include "macros.h" +#include "version.h" + +/** + * assert() equivalent, that is always enabled. + */ +#define av_assert0(cond) do { \ + if (!(cond)) { \ + av_log(NULL, AV_LOG_PANIC, "Assertion %s failed at %s:%d\n", \ + AV_STRINGIFY(cond), __FILE__, __LINE__); \ + abort(); \ + } \ +} while (0) + + +/** + * assert() equivalent, that does not lie in speed critical code. + * These asserts() thus can be enabled without fearing speed loss. + */ +#if defined(ASSERT_LEVEL) && ASSERT_LEVEL > 0 +#define av_assert1(cond) av_assert0(cond) +#else +#define av_assert1(cond) ((void)0) +#endif + + +/** + * assert() equivalent, that does lie in speed critical code. + */ +#if defined(ASSERT_LEVEL) && ASSERT_LEVEL > 1 +#define av_assert2(cond) av_assert0(cond) +#else +#define av_assert2(cond) ((void)0) +#endif + +#if FF_API_ASSERT_FPU +#if defined(ASSERT_LEVEL) && ASSERT_LEVEL > 1 +#define av_assert2_fpu() av_assert0_fpu() +#else +#define av_assert2_fpu() ((void)0) +#endif +/** + * Assert that floating point operations can be executed. + * + * This will av_assert0() that the cpu is not in MMX state on X86 + * @deprecated without replacement + */ +attribute_deprecated +void av_assert0_fpu(void); +#endif + +/** + * Asserts that are used as compiler optimization hints depending + * upon ASSERT_LEVEL and NBDEBUG. + * + * Undefined behaviour occurs if execution reaches a point marked + * with av_unreachable() or if a condition used with av_assume() + * is false. + * + * The condition used with av_assume() should not have side-effects + * and should be visible to the compiler. + */ +#if defined(ASSERT_LEVEL) ? ASSERT_LEVEL > 0 : !defined(HAVE_AV_CONFIG_H) && !defined(NDEBUG) +#define av_unreachable(msg) \ +do { \ + av_log(NULL, AV_LOG_PANIC, \ + "Reached supposedly unreachable code at %s:%d: %s\n", \ + __FILE__, __LINE__, msg); \ + abort(); \ +} while (0) +#define av_assume(cond) av_assert0(cond) +#else +#if AV_GCC_VERSION_AT_LEAST(4, 5) || AV_HAS_BUILTIN(__builtin_unreachable) +#define av_unreachable(msg) __builtin_unreachable() +#elif defined(_MSC_VER) +#define av_unreachable(msg) __assume(0) +#elif __STDC_VERSION__ >= 202311L +#include +#define av_unreachable(msg) unreachable() +#else +#define av_unreachable(msg) ((void)0) +#endif + +#define av_assume(cond) do { \ + if (!(cond)) \ + av_unreachable(); \ +} while (0) +#endif + +#endif /* AVUTIL_AVASSERT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/avconfig.h b/ffmpeg-n8.1/include/libavutil/avconfig.h new file mode 100644 index 00000000..c289fbb5 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/avconfig.h @@ -0,0 +1,6 @@ +/* Generated by ffmpeg configure */ +#ifndef AVUTIL_AVCONFIG_H +#define AVUTIL_AVCONFIG_H +#define AV_HAVE_BIGENDIAN 0 +#define AV_HAVE_FAST_UNALIGNED 1 +#endif /* AVUTIL_AVCONFIG_H */ diff --git a/ffmpeg-n8.1/include/libavutil/avstring.h b/ffmpeg-n8.1/include/libavutil/avstring.h new file mode 100644 index 00000000..17f7b03d --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/avstring.h @@ -0,0 +1,428 @@ +/* + * Copyright (c) 2007 Mans Rullgard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_AVSTRING_H +#define AVUTIL_AVSTRING_H + +#include +#include +#include "attributes.h" + +/** + * @addtogroup lavu_string + * @{ + */ + +/** + * Return non-zero if pfx is a prefix of str. If it is, *ptr is set to + * the address of the first character in str after the prefix. + * + * @param str input string + * @param pfx prefix to test + * @param ptr updated if the prefix is matched inside str + * @return non-zero if the prefix matches, zero otherwise + */ +int av_strstart(const char *str, const char *pfx, const char **ptr); + +/** + * Return non-zero if pfx is a prefix of str independent of case. If + * it is, *ptr is set to the address of the first character in str + * after the prefix. + * + * @param str input string + * @param pfx prefix to test + * @param ptr updated if the prefix is matched inside str + * @return non-zero if the prefix matches, zero otherwise + */ +int av_stristart(const char *str, const char *pfx, const char **ptr); + +/** + * Locate the first case-independent occurrence in the string haystack + * of the string needle. A zero-length string needle is considered to + * match at the start of haystack. + * + * This function is a case-insensitive version of the standard strstr(). + * + * @param haystack string to search in + * @param needle string to search for + * @return pointer to the located match within haystack + * or a null pointer if no match + */ +char *av_stristr(const char *haystack, const char *needle); + +/** + * Locate the first occurrence of the string needle in the string haystack + * where not more than hay_length characters are searched. A zero-length + * string needle is considered to match at the start of haystack. + * + * This function is a length-limited version of the standard strstr(). + * + * @param haystack string to search in + * @param needle string to search for + * @param hay_length length of string to search in + * @return pointer to the located match within haystack + * or a null pointer if no match + */ +char *av_strnstr(const char *haystack, const char *needle, size_t hay_length); + +/** + * Copy the string src to dst, but no more than size - 1 bytes, and + * null-terminate dst. + * + * This function is the same as BSD strlcpy(). + * + * @param dst destination buffer + * @param src source string + * @param size size of destination buffer + * @return the length of src + * + * @warning since the return value is the length of src, src absolutely + * _must_ be a properly 0-terminated string, otherwise this will read beyond + * the end of the buffer and possibly crash. + */ +size_t av_strlcpy(char *dst, const char *src, size_t size); + +/** + * Append the string src to the string dst, but to a total length of + * no more than size - 1 bytes, and null-terminate dst. + * + * This function is similar to BSD strlcat(), but differs when + * size <= strlen(dst). + * + * @param dst destination buffer + * @param src source string + * @param size size of destination buffer + * @return the total length of src and dst + * + * @warning since the return value use the length of src and dst, these + * absolutely _must_ be a properly 0-terminated strings, otherwise this + * will read beyond the end of the buffer and possibly crash. + */ +size_t av_strlcat(char *dst, const char *src, size_t size); + +/** + * Append output to a string, according to a format. Never write out of + * the destination buffer, and always put a terminating 0 within + * the buffer. + * @param dst destination buffer (string to which the output is + * appended) + * @param size total size of the destination buffer + * @param fmt printf-compatible format string, specifying how the + * following parameters are used + * @return the length of the string that would have been generated + * if enough space had been available + */ +size_t av_strlcatf(char *dst, size_t size, const char *fmt, ...) av_printf_format(3, 4); + +/** + * Get the count of continuous non zero chars starting from the beginning. + * + * @param s the string whose length to count + * @param len maximum number of characters to check in the string, that + * is the maximum value which is returned by the function + */ +static inline size_t av_strnlen(const char *s, size_t len) +{ + size_t i; + for (i = 0; i < len && s[i]; i++) + ; + return i; +} + +/** + * Print arguments following specified format into a large enough auto + * allocated buffer. It is similar to GNU asprintf(). + * @param fmt printf-compatible format string, specifying how the + * following parameters are used. + * @return the allocated string + * @note You have to free the string yourself with av_free(). + */ +char *av_asprintf(const char *fmt, ...) av_printf_format(1, 2); + +/** + * Unescape the given string until a non escaped terminating char, + * and return the token corresponding to the unescaped string. + * + * The normal \ and ' escaping is supported. Leading and trailing + * whitespaces are removed, unless they are escaped with '\' or are + * enclosed between ''. + * + * @param buf the buffer to parse, buf will be updated to point to the + * terminating char + * @param term a 0-terminated list of terminating chars + * @return the malloced unescaped string, which must be av_freed by + * the user, NULL in case of allocation failure + */ +char *av_get_token(const char **buf, const char *term); + +/** + * Split the string into several tokens which can be accessed by + * successive calls to av_strtok(). + * + * A token is defined as a sequence of characters not belonging to the + * set specified in delim. + * + * On the first call to av_strtok(), s should point to the string to + * parse, and the value of saveptr is ignored. In subsequent calls, s + * should be NULL, and saveptr should be unchanged since the previous + * call. + * + * This function is similar to strtok_r() defined in POSIX.1. + * + * @param s the string to parse, may be NULL + * @param delim 0-terminated list of token delimiters, must be non-NULL + * @param saveptr user-provided pointer which points to stored + * information necessary for av_strtok() to continue scanning the same + * string. saveptr is updated to point to the next character after the + * first delimiter found, or to NULL if the string was terminated + * @return the found token, or NULL when no token is found + */ +char *av_strtok(char *s, const char *delim, char **saveptr); + +/** + * Locale-independent conversion of ASCII isdigit. + */ +static inline av_const int av_isdigit(int c) +{ + return c >= '0' && c <= '9'; +} + +/** + * Locale-independent conversion of ASCII isgraph. + */ +static inline av_const int av_isgraph(int c) +{ + return c > 32 && c < 127; +} + +/** + * Locale-independent conversion of ASCII isspace. + */ +static inline av_const int av_isspace(int c) +{ + return c == ' ' || c == '\f' || c == '\n' || c == '\r' || c == '\t' || + c == '\v'; +} + +/** + * Locale-independent conversion of ASCII characters to uppercase. + */ +static inline av_const int av_toupper(int c) +{ + if (c >= 'a' && c <= 'z') + c ^= 0x20; + return c; +} + +/** + * Locale-independent conversion of ASCII characters to lowercase. + */ +static inline av_const int av_tolower(int c) +{ + if (c >= 'A' && c <= 'Z') + c ^= 0x20; + return c; +} + +/** + * Locale-independent conversion of ASCII isxdigit. + */ +static inline av_const int av_isxdigit(int c) +{ + c = av_tolower(c); + return av_isdigit(c) || (c >= 'a' && c <= 'f'); +} + +/** + * Locale-independent case-insensitive compare. + * @note This means only ASCII-range characters are case-insensitive + */ +int av_strcasecmp(const char *a, const char *b); + +/** + * Locale-independent case-insensitive compare. + * @note This means only ASCII-range characters are case-insensitive + */ +int av_strncasecmp(const char *a, const char *b, size_t n); + +/** + * Locale-independent strings replace. + * @note This means only ASCII-range characters are replaced. + */ +char *av_strireplace(const char *str, const char *from, const char *to); + +/** + * Thread safe basename. + * @param path the string to parse, on DOS both \ and / are considered separators. + * @return pointer to the basename substring. + * If path does not contain a slash, the function returns a copy of path. + * If path is a NULL pointer or points to an empty string, a pointer + * to a string "." is returned. + */ +const char *av_basename(const char *path); + +/** + * Thread safe dirname. + * @param path the string to parse, on DOS both \ and / are considered separators. + * @return A pointer to a string that's the parent directory of path. + * If path is a NULL pointer or points to an empty string, a pointer + * to a string "." is returned. + * @note the function may modify the contents of the path, so copies should be passed. + */ +const char *av_dirname(char *path); + +/** + * Match instances of a name in a comma-separated list of names. + * List entries are checked from the start to the end of the names list, + * the first match ends further processing. If an entry prefixed with '-' + * matches, then 0 is returned. The "ALL" list entry is considered to + * match all names. + * + * @param name Name to look for. + * @param names List of names. + * @return 1 on match, 0 otherwise. + */ +int av_match_name(const char *name, const char *names); + +/** + * Append path component to the existing path. + * Path separator '/' is placed between when needed. + * Resulting string have to be freed with av_free(). + * @param path base path + * @param component component to be appended + * @return new path or NULL on error. + */ +char *av_append_path_component(const char *path, const char *component); + +enum AVEscapeMode { + AV_ESCAPE_MODE_AUTO, ///< Use auto-selected escaping mode. + AV_ESCAPE_MODE_BACKSLASH, ///< Use backslash escaping. + AV_ESCAPE_MODE_QUOTE, ///< Use single-quote escaping. + AV_ESCAPE_MODE_XML, ///< Use XML non-markup character data escaping. +}; + +/** + * Consider spaces special and escape them even in the middle of the + * string. + * + * This is equivalent to adding the whitespace characters to the special + * characters lists, except it is guaranteed to use the exact same list + * of whitespace characters as the rest of libavutil. + */ +#define AV_ESCAPE_FLAG_WHITESPACE (1 << 0) + +/** + * Escape only specified special characters. + * Without this flag, escape also any characters that may be considered + * special by av_get_token(), such as the single quote. + */ +#define AV_ESCAPE_FLAG_STRICT (1 << 1) + +/** + * Within AV_ESCAPE_MODE_XML, additionally escape single quotes for single + * quoted attributes. + */ +#define AV_ESCAPE_FLAG_XML_SINGLE_QUOTES (1 << 2) + +/** + * Within AV_ESCAPE_MODE_XML, additionally escape double quotes for double + * quoted attributes. + */ +#define AV_ESCAPE_FLAG_XML_DOUBLE_QUOTES (1 << 3) + + +/** + * Escape string in src, and put the escaped string in an allocated + * string in *dst, which must be freed with av_free(). + * + * @param dst pointer where an allocated string is put + * @param src string to escape, must be non-NULL + * @param special_chars string containing the special characters which + * need to be escaped, can be NULL + * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros. + * Any unknown value for mode will be considered equivalent to + * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without + * notice. + * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_ macros + * @return the length of the allocated string, or a negative error code in case of error + * @see av_bprint_escape() + */ +av_warn_unused_result +int av_escape(char **dst, const char *src, const char *special_chars, + enum AVEscapeMode mode, int flags); + +#define AV_UTF8_FLAG_ACCEPT_INVALID_BIG_CODES 1 ///< accept codepoints over 0x10FFFF +#define AV_UTF8_FLAG_ACCEPT_NON_CHARACTERS 2 ///< accept non-characters - 0xFFFE and 0xFFFF +#define AV_UTF8_FLAG_ACCEPT_SURROGATES 4 ///< accept UTF-16 surrogates codes +#define AV_UTF8_FLAG_EXCLUDE_XML_INVALID_CONTROL_CODES 8 ///< exclude control codes not accepted by XML + +#define AV_UTF8_FLAG_ACCEPT_ALL \ + AV_UTF8_FLAG_ACCEPT_INVALID_BIG_CODES|AV_UTF8_FLAG_ACCEPT_NON_CHARACTERS|AV_UTF8_FLAG_ACCEPT_SURROGATES + +/** + * Read and decode a single UTF-8 code point (character) from the + * buffer in *buf, and update *buf to point to the next byte to + * decode. + * + * In case of an invalid byte sequence, the pointer will be updated to + * the next byte after the invalid sequence and the function will + * return an error code. + * + * Depending on the specified flags, the function will also fail in + * case the decoded code point does not belong to a valid range. + * + * @note For speed-relevant code a carefully implemented use of + * GET_UTF8() may be preferred. + * + * @param codep pointer used to return the parsed code in case of success. + * The value in *codep is set even in case the range check fails. + * @param bufp pointer to the address the first byte of the sequence + * to decode, updated by the function to point to the + * byte next after the decoded sequence + * @param buf_end pointer to the end of the buffer, points to the next + * byte past the last in the buffer. This is used to + * avoid buffer overreads (in case of an unfinished + * UTF-8 sequence towards the end of the buffer). + * @param flags a collection of AV_UTF8_FLAG_* flags + * @return >= 0 in case a sequence was successfully read, a negative + * value in case of invalid sequence + */ +av_warn_unused_result +int av_utf8_decode(int32_t *codep, const uint8_t **bufp, const uint8_t *buf_end, + unsigned int flags); + +/** + * Check if a name is in a list. + * @returns 0 if not found, or the 1 based index where it has been found in the + * list. + */ +int av_match_list(const char *name, const char *list, char separator); + +/** + * See libc sscanf manual for more information. + * Locale-independent sscanf implementation. + */ +int av_sscanf(const char *string, const char *format, ...) av_scanf_format(2, 3); + +/** + * @} + */ + +#endif /* AVUTIL_AVSTRING_H */ diff --git a/ffmpeg-n8.1/include/libavutil/avutil.h b/ffmpeg-n8.1/include/libavutil/avutil.h new file mode 100644 index 00000000..c8ae114a --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/avutil.h @@ -0,0 +1,364 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_AVUTIL_H +#define AVUTIL_AVUTIL_H + +/** + * @file + * @ingroup lavu + * Convenience header that includes @ref lavu "libavutil"'s core. + */ + +/** + * @mainpage + * + * @section ffmpeg_intro Introduction + * + * This document describes the usage of the different libraries + * provided by FFmpeg. + * + * @li @ref libavc "libavcodec" encoding/decoding library + * @li @ref lavfi "libavfilter" graph-based frame editing library + * @li @ref libavf "libavformat" I/O and muxing/demuxing library + * @li @ref lavd "libavdevice" special devices muxing/demuxing library + * @li @ref lavu "libavutil" common utility library + * @li @ref lswr "libswresample" audio resampling, format conversion and mixing + * @li @ref libsws "libswscale" color conversion and scaling library + * + * @section ffmpeg_versioning Versioning and compatibility + * + * Each of the FFmpeg libraries contains a version.h header, which defines a + * major, minor and micro version number with the + * LIBRARYNAME_VERSION_{MAJOR,MINOR,MICRO} macros. The major version + * number is incremented with backward incompatible changes - e.g. removing + * parts of the public API, reordering public struct members, etc. The minor + * version number is incremented for backward compatible API changes or major + * new features - e.g. adding a new public function or a new decoder. The micro + * version number is incremented for smaller changes that a calling program + * might still want to check for - e.g. changing behavior in a previously + * unspecified situation. + * + * FFmpeg guarantees backward API and ABI compatibility for each library as long + * as its major version number is unchanged. This means that no public symbols + * will be removed or renamed. Types and names of the public struct members and + * values of public macros and enums will remain the same (unless they were + * explicitly declared as not part of the public API). Documented behavior will + * not change. + * + * In other words, any correct program that works with a given FFmpeg snapshot + * should work just as well without any changes with any later snapshot with the + * same major versions. This applies to both rebuilding the program against new + * FFmpeg versions or to replacing the dynamic FFmpeg libraries that a program + * links against. + * + * However, new public symbols may be added and new members may be appended to + * public structs whose size is not part of public ABI (most public structs in + * FFmpeg). New macros and enum values may be added. Behavior in undocumented + * situations may change slightly (and be documented). All those are accompanied + * by an entry in doc/APIchanges and incrementing either the minor or micro + * version number. + */ + +/** + * @defgroup lavu libavutil + * Common code shared across all FFmpeg libraries. + * + * @note + * libavutil is designed to be modular. In most cases, in order to use the + * functions provided by one component of libavutil you must explicitly include + * the specific header containing that feature. If you are only using + * media-related components, you could simply include libavutil/avutil.h, which + * brings in most of the "core" components. + * + * @{ + * + * @defgroup lavu_crypto Crypto and Hashing + * + * @{ + * @} + * + * @defgroup lavu_math Mathematics + * @{ + * + * @} + * + * @defgroup lavu_string String Manipulation + * + * @{ + * + * @} + * + * @defgroup lavu_mem Memory Management + * + * @{ + * + * @} + * + * @defgroup lavu_data Data Structures + * @{ + * + * @} + * + * @defgroup lavu_video Video related + * + * @{ + * + * @} + * + * @defgroup lavu_audio Audio related + * + * @{ + * + * @} + * + * @defgroup lavu_error Error Codes + * + * @{ + * + * @} + * + * @defgroup lavu_log Logging Facility + * + * @{ + * + * @} + * + * @defgroup lavu_misc Other + * + * @{ + * + * @defgroup preproc_misc Preprocessor String Macros + * + * @{ + * + * @} + * + * @defgroup version_utils Library Version Macros + * + * @{ + * + * @} + */ + + +/** + * @addtogroup lavu_ver + * @{ + */ + +/** + * Return the LIBAVUTIL_VERSION_INT constant. + */ +unsigned avutil_version(void); + +/** + * Return an informative version string. This usually is the actual release + * version number or a git commit description. This string has no fixed format + * and can change any time. It should never be parsed by code. + */ +const char *av_version_info(void); + +/** + * Return the libavutil build-time configuration. + */ +const char *avutil_configuration(void); + +/** + * Return the libavutil license. + */ +const char *avutil_license(void); + +/** + * @} + */ + +/** + * @addtogroup lavu_media Media Type + * @brief Media Type + */ + +enum AVMediaType { + AVMEDIA_TYPE_UNKNOWN = -1, ///< Usually treated as AVMEDIA_TYPE_DATA + AVMEDIA_TYPE_VIDEO, + AVMEDIA_TYPE_AUDIO, + AVMEDIA_TYPE_DATA, ///< Opaque data information usually continuous + AVMEDIA_TYPE_SUBTITLE, + AVMEDIA_TYPE_ATTACHMENT, ///< Opaque data information usually sparse + AVMEDIA_TYPE_NB +}; + +/** + * Return a string describing the media_type enum, NULL if media_type + * is unknown. + */ +const char *av_get_media_type_string(enum AVMediaType media_type); + +/** + * @defgroup lavu_const Constants + * @{ + * + * @defgroup lavu_enc Encoding specific + * + * @note those definition should move to avcodec + * @{ + */ + +#define FF_LAMBDA_SHIFT 7 +#define FF_LAMBDA_SCALE (1< + +/** + * @defgroup lavu_base64 Base64 + * @ingroup lavu_crypto + * @{ + */ + +/** + * Decode a base64-encoded string. + * + * @param out buffer for decoded data + * @param in null-terminated input string + * @param out_size size in bytes of the out buffer, must be at + * least 3/4 of the length of in, that is AV_BASE64_DECODE_SIZE(strlen(in)) + * @return number of bytes written, or a negative value in case of + * invalid input + */ +int av_base64_decode(uint8_t *out, const char *in, int out_size); + +/** + * Calculate the output size in bytes needed to decode a base64 string + * with length x to a data buffer. + */ +#define AV_BASE64_DECODE_SIZE(x) ((x) * 3LL / 4) + +/** + * Encode data to base64 and null-terminate. + * + * @param out buffer for encoded data + * @param out_size size in bytes of the out buffer (including the + * null terminator), must be at least AV_BASE64_SIZE(in_size) + * @param in input buffer containing the data to encode + * @param in_size size in bytes of the in buffer + * @return out or NULL in case of error + */ +char *av_base64_encode(char *out, int out_size, const uint8_t *in, int in_size); + +/** + * Calculate the output size needed to base64-encode x bytes to a + * null-terminated string. + */ +#define AV_BASE64_SIZE(x) (((x)+2) / 3 * 4 + 1) + + /** + * @} + */ + +#endif /* AVUTIL_BASE64_H */ diff --git a/ffmpeg-n8.1/include/libavutil/blowfish.h b/ffmpeg-n8.1/include/libavutil/blowfish.h new file mode 100644 index 00000000..9e289a40 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/blowfish.h @@ -0,0 +1,82 @@ +/* + * Blowfish algorithm + * Copyright (c) 2012 Samuel Pitoiset + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_BLOWFISH_H +#define AVUTIL_BLOWFISH_H + +#include + +/** + * @defgroup lavu_blowfish Blowfish + * @ingroup lavu_crypto + * @{ + */ + +#define AV_BF_ROUNDS 16 + +typedef struct AVBlowfish { + uint32_t p[AV_BF_ROUNDS + 2]; + uint32_t s[4][256]; +} AVBlowfish; + +/** + * Allocate an AVBlowfish context. + */ +AVBlowfish *av_blowfish_alloc(void); + +/** + * Initialize an AVBlowfish context. + * + * @param ctx an AVBlowfish context + * @param key a key + * @param key_len length of the key + */ +void av_blowfish_init(struct AVBlowfish *ctx, const uint8_t *key, int key_len); + +/** + * Encrypt or decrypt a buffer using a previously initialized context. + * + * @param ctx an AVBlowfish context + * @param xl left four bytes halves of input to be encrypted + * @param xr right four bytes halves of input to be encrypted + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_blowfish_crypt_ecb(struct AVBlowfish *ctx, uint32_t *xl, uint32_t *xr, + int decrypt); + +/** + * Encrypt or decrypt a buffer using a previously initialized context. + * + * @param ctx an AVBlowfish context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 8 byte blocks + * @param iv initialization vector for CBC mode, if NULL ECB will be used + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_blowfish_crypt(struct AVBlowfish *ctx, uint8_t *dst, const uint8_t *src, + int count, uint8_t *iv, int decrypt); + +/** + * @} + */ + +#endif /* AVUTIL_BLOWFISH_H */ diff --git a/ffmpeg-n8.1/include/libavutil/bprint.h b/ffmpeg-n8.1/include/libavutil/bprint.h new file mode 100644 index 00000000..4ac85705 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/bprint.h @@ -0,0 +1,254 @@ +/* + * Copyright (c) 2012 Nicolas George + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_avbprint + * AVBPrint public header + */ + +#ifndef AVUTIL_BPRINT_H +#define AVUTIL_BPRINT_H + +#include + +#include "attributes.h" +#include "avstring.h" + +/** + * @defgroup lavu_avbprint AVBPrint + * @ingroup lavu_data + * + * A buffer to print data progressively + * @{ + */ + +/** + * Define a structure with extra padding to a fixed size + * This helps ensuring binary compatibility with future versions. + */ + +#define FF_PAD_STRUCTURE(name, size, ...) \ +struct ff_pad_helper_##name { __VA_ARGS__ }; \ +typedef struct name { \ + __VA_ARGS__ \ + char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \ +} name; + +/** + * Buffer to print data progressively + * + * The string buffer grows as necessary and is always 0-terminated. + * The content of the string is never accessed, and thus is + * encoding-agnostic and can even hold binary data. + * + * Small buffers are kept in the structure itself, and thus require no + * memory allocation at all (unless the contents of the buffer is needed + * after the structure goes out of scope). This is almost as lightweight as + * declaring a local `char buf[512]`. + * + * The length of the string can go beyond the allocated size: the buffer is + * then truncated, but the functions still keep account of the actual total + * length. + * + * In other words, AVBPrint.len can be greater than AVBPrint.size and records + * the total length of what would have been to the buffer if there had been + * enough memory. + * + * Append operations do not need to be tested for failure: if a memory + * allocation fails, data stop being appended to the buffer, but the length + * is still updated. This situation can be tested with + * av_bprint_is_complete(). + * + * The AVBPrint.size_max field determines several possible behaviours: + * - `size_max = -1` (= `UINT_MAX`) or any large value will let the buffer be + * reallocated as necessary, with an amortized linear cost. + * - `size_max = 0` prevents writing anything to the buffer: only the total + * length is computed. The write operations can then possibly be repeated in + * a buffer with exactly the necessary size + * (using `size_init = size_max = len + 1`). + * - `size_max = 1` is automatically replaced by the exact size available in the + * structure itself, thus ensuring no dynamic memory allocation. The + * internal buffer is large enough to hold a reasonable paragraph of text, + * such as the current paragraph. + */ + +FF_PAD_STRUCTURE(AVBPrint, 1024, + char *str; /**< string so far */ + unsigned len; /**< length so far */ + unsigned size; /**< allocated memory */ + unsigned size_max; /**< maximum allocated memory */ + char reserved_internal_buffer[1]; +) + +/** + * @name Max size special values + * Convenience macros for special values for av_bprint_init() size_max + * parameter. + * @{ + */ + +/** + * Buffer will be reallocated as necessary, with an amortized linear cost. + */ +#define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1) +/** + * Use the exact size available in the AVBPrint structure itself. + * + * Thus ensuring no dynamic memory allocation. The internal buffer is large + * enough to hold a reasonable paragraph of text, such as the current paragraph. + */ +#define AV_BPRINT_SIZE_AUTOMATIC 1 +/** + * Do not write anything to the buffer, only calculate the total length. + * + * The write operations can then possibly be repeated in a buffer with + * exactly the necessary size (using `size_init = size_max = AVBPrint.len + 1`). + */ +#define AV_BPRINT_SIZE_COUNT_ONLY 0 +/** @} */ + +/** + * Init a print buffer. + * + * @param buf buffer to init + * @param size_init initial size (including the final 0) + * @param size_max maximum size; + * - `0` means do not write anything, just count the length + * - `1` is replaced by the maximum value for automatic storage + * any large value means that the internal buffer will be + * reallocated as needed up to that limit + * - `-1` is converted to `UINT_MAX`, the largest limit possible. + * Check also `AV_BPRINT_SIZE_*` macros. + */ +void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max); + +/** + * Init a print buffer using a pre-existing buffer. + * + * The buffer will not be reallocated. + * In case size equals zero, the AVBPrint will be initialized to use + * the internal buffer as if using AV_BPRINT_SIZE_COUNT_ONLY with + * av_bprint_init(). + * + * @param buf buffer structure to init + * @param buffer byte buffer to use for the string data + * @param size size of buffer + */ +void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size); + +/** + * Append a formatted string to a print buffer. + */ +void av_bprintf(AVBPrint *buf, const char *fmt, ...) av_printf_format(2, 3); + +/** + * Append a formatted string to a print buffer. + */ +void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg); + +/** + * Append char c n times to a print buffer. + */ +void av_bprint_chars(AVBPrint *buf, char c, unsigned n); + +/** + * Append data to a print buffer. + * + * @param buf bprint buffer to use + * @param data pointer to data + * @param size size of data + */ +void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size); + +struct tm; +/** + * Append a formatted date and time to a print buffer. + * + * @param buf bprint buffer to use + * @param fmt date and time format string, see strftime() + * @param tm broken-down time structure to translate + * + * @note due to poor design of the standard strftime function, it may + * produce poor results if the format string expands to a very long text and + * the bprint buffer is near the limit stated by the size_max option. + */ +void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm); + +/** + * Allocate bytes in the buffer for external use. + * + * @param[in] buf buffer structure + * @param[in] size required size + * @param[out] mem pointer to the memory area + * @param[out] actual_size size of the memory area after allocation; + * can be larger or smaller than size + */ +void av_bprint_get_buffer(AVBPrint *buf, unsigned size, + unsigned char **mem, unsigned *actual_size); + +/** + * Reset the string to "" but keep internal allocated data. + */ +void av_bprint_clear(AVBPrint *buf); + +/** + * Test if the print buffer is complete (not truncated). + * + * It may have been truncated due to a memory allocation failure + * or the size_max limit (compare size and size_max if necessary). + */ +static inline int av_bprint_is_complete(const AVBPrint *buf) +{ + return buf->len < buf->size; +} + +/** + * Finalize a print buffer. + * + * The print buffer can no longer be used afterwards, + * but the len and size fields are still valid. + * + * @arg[out] ret_str if not NULL, used to return a permanent copy of the + * buffer contents, or NULL if memory allocation fails; + * if NULL, the buffer is discarded and freed + * @return 0 for success or error code (probably AVERROR(ENOMEM)) + */ +int av_bprint_finalize(AVBPrint *buf, char **ret_str); + +/** + * Escape the content in src and append it to dstbuf. + * + * @param dstbuf already inited destination bprint buffer + * @param src string containing the text to escape + * @param special_chars string containing the special characters which + * need to be escaped, can be NULL + * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros. + * Any unknown value for mode will be considered equivalent to + * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without + * notice. + * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_* macros + */ +void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars, + enum AVEscapeMode mode, int flags); + +/** @} */ + +#endif /* AVUTIL_BPRINT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/bswap.h b/ffmpeg-n8.1/include/libavutil/bswap.h new file mode 100644 index 00000000..f53e5768 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/bswap.h @@ -0,0 +1,105 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * byte swapping routines + */ + +#ifndef AVUTIL_BSWAP_H +#define AVUTIL_BSWAP_H + +#include +#include "libavutil/avconfig.h" +#include "attributes.h" + +#ifdef HAVE_AV_CONFIG_H + +#include "config.h" + +#if ARCH_ARM +# include "arm/bswap.h" +#elif ARCH_RISCV +# include "riscv/bswap.h" +#elif ARCH_X86 +# include "x86/bswap.h" +#endif + +#endif /* HAVE_AV_CONFIG_H */ + +#define AV_BSWAP16C(x) (((x) << 8 & 0xff00) | ((x) >> 8 & 0x00ff)) +#define AV_BSWAP32C(x) (AV_BSWAP16C(x) << 16 | AV_BSWAP16C((x) >> 16)) +#define AV_BSWAP64C(x) (AV_BSWAP32C(x) << 32 | AV_BSWAP32C((x) >> 32)) + +#define AV_BSWAPC(s, x) AV_BSWAP##s##C(x) + +#ifndef av_bswap16 +static av_always_inline av_const uint16_t av_bswap16(uint16_t x) +{ + x= (x>>8) | (x<<8); + return x; +} +#endif + +#ifndef av_bswap32 +static av_always_inline av_const uint32_t av_bswap32(uint32_t x) +{ + return AV_BSWAP32C(x); +} +#endif + +#ifndef av_bswap64 +static inline uint64_t av_const av_bswap64(uint64_t x) +{ + return (uint64_t)av_bswap32(x) << 32 | av_bswap32(x >> 32); +} +#endif + +// be2ne ... big-endian to native-endian +// le2ne ... little-endian to native-endian + +#if AV_HAVE_BIGENDIAN +#define av_be2ne16(x) (x) +#define av_be2ne32(x) (x) +#define av_be2ne64(x) (x) +#define av_le2ne16(x) av_bswap16(x) +#define av_le2ne32(x) av_bswap32(x) +#define av_le2ne64(x) av_bswap64(x) +#define AV_BE2NEC(s, x) (x) +#define AV_LE2NEC(s, x) AV_BSWAPC(s, x) +#else +#define av_be2ne16(x) av_bswap16(x) +#define av_be2ne32(x) av_bswap32(x) +#define av_be2ne64(x) av_bswap64(x) +#define av_le2ne16(x) (x) +#define av_le2ne32(x) (x) +#define av_le2ne64(x) (x) +#define AV_BE2NEC(s, x) AV_BSWAPC(s, x) +#define AV_LE2NEC(s, x) (x) +#endif + +#define AV_BE2NE16C(x) AV_BE2NEC(16, x) +#define AV_BE2NE32C(x) AV_BE2NEC(32, x) +#define AV_BE2NE64C(x) AV_BE2NEC(64, x) +#define AV_LE2NE16C(x) AV_LE2NEC(16, x) +#define AV_LE2NE32C(x) AV_LE2NEC(32, x) +#define AV_LE2NE64C(x) AV_LE2NEC(64, x) + +#endif /* AVUTIL_BSWAP_H */ diff --git a/ffmpeg-n8.1/include/libavutil/buffer.h b/ffmpeg-n8.1/include/libavutil/buffer.h new file mode 100644 index 00000000..e1ef5b7f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/buffer.h @@ -0,0 +1,322 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_buffer + * refcounted data buffer API + */ + +#ifndef AVUTIL_BUFFER_H +#define AVUTIL_BUFFER_H + +#include +#include + +/** + * @defgroup lavu_buffer AVBuffer + * @ingroup lavu_data + * + * @{ + * AVBuffer is an API for reference-counted data buffers. + * + * There are two core objects in this API -- AVBuffer and AVBufferRef. AVBuffer + * represents the data buffer itself; it is opaque and not meant to be accessed + * by the caller directly, but only through AVBufferRef. However, the caller may + * e.g. compare two AVBuffer pointers to check whether two different references + * are describing the same data buffer. AVBufferRef represents a single + * reference to an AVBuffer and it is the object that may be manipulated by the + * caller directly. + * + * There are two functions provided for creating a new AVBuffer with a single + * reference -- av_buffer_alloc() to just allocate a new buffer, and + * av_buffer_create() to wrap an existing array in an AVBuffer. From an existing + * reference, additional references may be created with av_buffer_ref(). + * Use av_buffer_unref() to free a reference (this will automatically free the + * data once all the references are freed). + * + * The convention throughout this API and the rest of FFmpeg is such that the + * buffer is considered writable if there exists only one reference to it (and + * it has not been marked as read-only). The av_buffer_is_writable() function is + * provided to check whether this is true and av_buffer_make_writable() will + * automatically create a new writable buffer when necessary. + * Of course nothing prevents the calling code from violating this convention, + * however that is safe only when all the existing references are under its + * control. + * + * @note Referencing and unreferencing the buffers is thread-safe and thus + * may be done from multiple threads simultaneously without any need for + * additional locking. + * + * @note Two different references to the same buffer can point to different + * parts of the buffer (i.e. their AVBufferRef.data will not be equal). + */ + +/** + * A reference counted buffer type. It is opaque and is meant to be used through + * references (AVBufferRef). + */ +typedef struct AVBuffer AVBuffer; + +/** + * A reference to a data buffer. + * + * The size of this struct is not a part of the public ABI and it is not meant + * to be allocated directly. + */ +typedef struct AVBufferRef { + AVBuffer *buffer; + + /** + * The data buffer. It is considered writable if and only if + * this is the only reference to the buffer, in which case + * av_buffer_is_writable() returns 1. + */ + uint8_t *data; + /** + * Size of data in bytes. + */ + size_t size; +} AVBufferRef; + +/** + * Allocate an AVBuffer of the given size using av_malloc(). + * + * @return an AVBufferRef of given size or NULL when out of memory + */ +AVBufferRef *av_buffer_alloc(size_t size); + +/** + * Same as av_buffer_alloc(), except the returned buffer will be initialized + * to zero. + */ +AVBufferRef *av_buffer_allocz(size_t size); + +/** + * Always treat the buffer as read-only, even when it has only one + * reference. + */ +#define AV_BUFFER_FLAG_READONLY (1 << 0) + +/** + * Create an AVBuffer from an existing array. + * + * If this function is successful, data is owned by the AVBuffer. The caller may + * only access data through the returned AVBufferRef and references derived from + * it. + * If this function fails, data is left untouched. + * @param data data array + * @param size size of data in bytes + * @param free a callback for freeing this buffer's data + * @param opaque parameter to be got for processing or passed to free + * @param flags a combination of AV_BUFFER_FLAG_* + * + * @return an AVBufferRef referring to data on success, NULL on failure. + */ +AVBufferRef *av_buffer_create(uint8_t *data, size_t size, + void (*free)(void *opaque, uint8_t *data), + void *opaque, int flags); + +/** + * Default free callback, which calls av_free() on the buffer data. + * This function is meant to be passed to av_buffer_create(), not called + * directly. + */ +void av_buffer_default_free(void *opaque, uint8_t *data); + +/** + * Create a new reference to an AVBuffer. + * + * @return a new AVBufferRef referring to the same AVBuffer as buf or NULL on + * failure. + */ +AVBufferRef *av_buffer_ref(const AVBufferRef *buf); + +/** + * Free a given reference and automatically free the buffer if there are no more + * references to it. + * + * @param buf the reference to be freed. The pointer is set to NULL on return. + */ +void av_buffer_unref(AVBufferRef **buf); + +/** + * @return 1 if the caller may write to the data referred to by buf (which is + * true if and only if buf is the only reference to the underlying AVBuffer). + * Return 0 otherwise. + * A positive answer is valid until av_buffer_ref() is called on buf. + */ +int av_buffer_is_writable(const AVBufferRef *buf); + +/** + * @return the opaque parameter set by av_buffer_create. + */ +void *av_buffer_get_opaque(const AVBufferRef *buf); + +int av_buffer_get_ref_count(const AVBufferRef *buf); + +/** + * Create a writable reference from a given buffer reference, avoiding data copy + * if possible. + * + * @param buf buffer reference to make writable. On success, buf is either left + * untouched, or it is unreferenced and a new writable AVBufferRef is + * written in its place. On failure, buf is left untouched. + * @return 0 on success, a negative AVERROR on failure. + */ +int av_buffer_make_writable(AVBufferRef **buf); + +/** + * Reallocate a given buffer. + * + * @param buf a buffer reference to reallocate. On success, buf will be + * unreferenced and a new reference with the required size will be + * written in its place. On failure buf will be left untouched. *buf + * may be NULL, then a new buffer is allocated. + * @param size required new buffer size. + * @return 0 on success, a negative AVERROR on failure. + * + * @note the buffer is actually reallocated with av_realloc() only if it was + * initially allocated through av_buffer_realloc(NULL) and there is only one + * reference to it (i.e. the one passed to this function). In all other cases + * a new buffer is allocated and the data is copied. + */ +int av_buffer_realloc(AVBufferRef **buf, size_t size); + +/** + * Ensure dst refers to the same data as src. + * + * When *dst is already equivalent to src, do nothing. Otherwise unreference dst + * and replace it with a new reference to src. + * + * @param dst Pointer to either a valid buffer reference or NULL. On success, + * this will point to a buffer reference equivalent to src. On + * failure, dst will be left untouched. + * @param src A buffer reference to replace dst with. May be NULL, then this + * function is equivalent to av_buffer_unref(dst). + * @return 0 on success + * AVERROR(ENOMEM) on memory allocation failure. + */ +int av_buffer_replace(AVBufferRef **dst, const AVBufferRef *src); + +/** + * @} + */ + +/** + * @defgroup lavu_bufferpool AVBufferPool + * @ingroup lavu_data + * + * @{ + * AVBufferPool is an API for a lock-free thread-safe pool of AVBuffers. + * + * Frequently allocating and freeing large buffers may be slow. AVBufferPool is + * meant to solve this in cases when the caller needs a set of buffers of the + * same size (the most obvious use case being buffers for raw video or audio + * frames). + * + * At the beginning, the user must call av_buffer_pool_init() to create the + * buffer pool. Then whenever a buffer is needed, call av_buffer_pool_get() to + * get a reference to a new buffer, similar to av_buffer_alloc(). This new + * reference works in all aspects the same way as the one created by + * av_buffer_alloc(). However, when the last reference to this buffer is + * unreferenced, it is returned to the pool instead of being freed and will be + * reused for subsequent av_buffer_pool_get() calls. + * + * When the caller is done with the pool and no longer needs to allocate any new + * buffers, av_buffer_pool_uninit() must be called to mark the pool as freeable. + * Once all the buffers are released, it will automatically be freed. + * + * Allocating and releasing buffers with this API is thread-safe as long as + * either the default alloc callback is used, or the user-supplied one is + * thread-safe. + */ + +/** + * The buffer pool. This structure is opaque and not meant to be accessed + * directly. It is allocated with av_buffer_pool_init() and freed with + * av_buffer_pool_uninit(). + */ +typedef struct AVBufferPool AVBufferPool; + +/** + * Allocate and initialize a buffer pool. + * + * @param size size of each buffer in this pool + * @param alloc a function that will be used to allocate new buffers when the + * pool is empty. May be NULL, then the default allocator will be used + * (av_buffer_alloc()). + * @return newly created buffer pool on success, NULL on error. + */ +AVBufferPool *av_buffer_pool_init(size_t size, AVBufferRef* (*alloc)(size_t size)); + +/** + * Allocate and initialize a buffer pool with a more complex allocator. + * + * @param size size of each buffer in this pool + * @param opaque arbitrary user data used by the allocator + * @param alloc a function that will be used to allocate new buffers when the + * pool is empty. May be NULL, then the default allocator will be + * used (av_buffer_alloc()). + * @param pool_free a function that will be called immediately before the pool + * is freed. I.e. after av_buffer_pool_uninit() is called + * by the caller and all the frames are returned to the pool + * and freed. It is intended to uninitialize the user opaque + * data. May be NULL. + * @return newly created buffer pool on success, NULL on error. + */ +AVBufferPool *av_buffer_pool_init2(size_t size, void *opaque, + AVBufferRef* (*alloc)(void *opaque, size_t size), + void (*pool_free)(void *opaque)); + +/** + * Mark the pool as being available for freeing. It will actually be freed only + * once all the allocated buffers associated with the pool are released. Thus it + * is safe to call this function while some of the allocated buffers are still + * in use. + * + * @param pool pointer to the pool to be freed. It will be set to NULL. + */ +void av_buffer_pool_uninit(AVBufferPool **pool); + +/** + * Allocate a new AVBuffer, reusing an old buffer from the pool when available. + * This function may be called simultaneously from multiple threads. + * + * @return a reference to the new buffer on success, NULL on error. + */ +AVBufferRef *av_buffer_pool_get(AVBufferPool *pool); + +/** + * Query the original opaque parameter of an allocated buffer in the pool. + * + * @param ref a buffer reference to a buffer returned by av_buffer_pool_get. + * @return the opaque parameter set by the buffer allocator function of the + * buffer pool. + * + * @note the opaque parameter of ref is used by the buffer pool implementation, + * therefore you have to use this function to access the original opaque + * parameter of an allocated buffer. + */ +void *av_buffer_pool_buffer_get_opaque(const AVBufferRef *ref); + +/** + * @} + */ + +#endif /* AVUTIL_BUFFER_H */ diff --git a/ffmpeg-n8.1/include/libavutil/camellia.h b/ffmpeg-n8.1/include/libavutil/camellia.h new file mode 100644 index 00000000..96787102 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/camellia.h @@ -0,0 +1,70 @@ +/* + * An implementation of the CAMELLIA algorithm as mentioned in RFC3713 + * Copyright (c) 2014 Supraja Meedinti + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_CAMELLIA_H +#define AVUTIL_CAMELLIA_H + +#include + + +/** + * @file + * @brief Public header for libavutil CAMELLIA algorithm + * @defgroup lavu_camellia CAMELLIA + * @ingroup lavu_crypto + * @{ + */ + +extern const int av_camellia_size; + +struct AVCAMELLIA; + +/** + * Allocate an AVCAMELLIA context + * To free the struct: av_free(ptr) + */ +struct AVCAMELLIA *av_camellia_alloc(void); + +/** + * Initialize an AVCAMELLIA context. + * + * @param ctx an AVCAMELLIA context + * @param key a key of 16, 24, 32 bytes used for encryption/decryption + * @param key_bits number of keybits: possible are 128, 192, 256 + */ +int av_camellia_init(struct AVCAMELLIA *ctx, const uint8_t *key, int key_bits); + +/** + * Encrypt or decrypt a buffer using a previously initialized context + * + * @param ctx an AVCAMELLIA context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 16 byte blocks + * @param iv initialization vector for CBC mode, NULL for ECB mode + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_camellia_crypt(struct AVCAMELLIA *ctx, uint8_t *dst, const uint8_t *src, int count, uint8_t* iv, int decrypt); + +/** + * @} + */ +#endif /* AVUTIL_CAMELLIA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/cast5.h b/ffmpeg-n8.1/include/libavutil/cast5.h new file mode 100644 index 00000000..ad5b347e --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/cast5.h @@ -0,0 +1,80 @@ +/* + * An implementation of the CAST128 algorithm as mentioned in RFC2144 + * Copyright (c) 2014 Supraja Meedinti + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_CAST5_H +#define AVUTIL_CAST5_H + +#include + + +/** + * @file + * @brief Public header for libavutil CAST5 algorithm + * @defgroup lavu_cast5 CAST5 + * @ingroup lavu_crypto + * @{ + */ + +extern const int av_cast5_size; + +struct AVCAST5; + +/** + * Allocate an AVCAST5 context + * To free the struct: av_free(ptr) + */ +struct AVCAST5 *av_cast5_alloc(void); +/** + * Initialize an AVCAST5 context. + * + * @param ctx an AVCAST5 context + * @param key a key of 5,6,...16 bytes used for encryption/decryption + * @param key_bits number of keybits: possible are 40,48,...,128 + * @return 0 on success, less than 0 on failure + */ +int av_cast5_init(struct AVCAST5 *ctx, const uint8_t *key, int key_bits); + +/** + * Encrypt or decrypt a buffer using a previously initialized context, ECB mode only + * + * @param ctx an AVCAST5 context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 8 byte blocks + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_cast5_crypt(struct AVCAST5 *ctx, uint8_t *dst, const uint8_t *src, int count, int decrypt); + +/** + * Encrypt or decrypt a buffer using a previously initialized context + * + * @param ctx an AVCAST5 context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 8 byte blocks + * @param iv initialization vector for CBC mode, NULL for ECB mode + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_cast5_crypt2(struct AVCAST5 *ctx, uint8_t *dst, const uint8_t *src, int count, uint8_t *iv, int decrypt); +/** + * @} + */ +#endif /* AVUTIL_CAST5_H */ diff --git a/ffmpeg-n8.1/include/libavutil/channel_layout.h b/ffmpeg-n8.1/include/libavutil/channel_layout.h new file mode 100644 index 00000000..5ad2d5ed --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/channel_layout.h @@ -0,0 +1,762 @@ +/* + * Copyright (c) 2006 Michael Niedermayer + * Copyright (c) 2008 Peter Ross + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_CHANNEL_LAYOUT_H +#define AVUTIL_CHANNEL_LAYOUT_H + +#include +#include + +#include "version.h" +#include "attributes.h" + +/** + * @file + * @ingroup lavu_audio_channels + * Public libavutil channel layout APIs header. + */ + + +/** + * @defgroup lavu_audio_channels Audio channels + * @ingroup lavu_audio + * + * Audio channel layout utility functions + * + * @{ + */ + +enum AVChannel { + /// Invalid channel index + AV_CHAN_NONE = -1, + AV_CHAN_FRONT_LEFT, + AV_CHAN_FRONT_RIGHT, + AV_CHAN_FRONT_CENTER, + AV_CHAN_LOW_FREQUENCY, + AV_CHAN_BACK_LEFT, + AV_CHAN_BACK_RIGHT, + AV_CHAN_FRONT_LEFT_OF_CENTER, + AV_CHAN_FRONT_RIGHT_OF_CENTER, + AV_CHAN_BACK_CENTER, + AV_CHAN_SIDE_LEFT, + AV_CHAN_SIDE_RIGHT, + AV_CHAN_TOP_CENTER, + AV_CHAN_TOP_FRONT_LEFT, + AV_CHAN_TOP_FRONT_CENTER, + AV_CHAN_TOP_FRONT_RIGHT, + AV_CHAN_TOP_BACK_LEFT, + AV_CHAN_TOP_BACK_CENTER, + AV_CHAN_TOP_BACK_RIGHT, + /** Stereo downmix. */ + AV_CHAN_STEREO_LEFT = 29, + /** See above. */ + AV_CHAN_STEREO_RIGHT, + AV_CHAN_WIDE_LEFT, + AV_CHAN_WIDE_RIGHT, + AV_CHAN_SURROUND_DIRECT_LEFT, + AV_CHAN_SURROUND_DIRECT_RIGHT, + AV_CHAN_LOW_FREQUENCY_2, + AV_CHAN_TOP_SIDE_LEFT, + AV_CHAN_TOP_SIDE_RIGHT, + AV_CHAN_BOTTOM_FRONT_CENTER, + AV_CHAN_BOTTOM_FRONT_LEFT, + AV_CHAN_BOTTOM_FRONT_RIGHT, + AV_CHAN_SIDE_SURROUND_LEFT, ///< +90 degrees, Lss, SiL + AV_CHAN_SIDE_SURROUND_RIGHT, ///< -90 degrees, Rss, SiR + AV_CHAN_TOP_SURROUND_LEFT, ///< +110 degrees, Lvs, TpLS + AV_CHAN_TOP_SURROUND_RIGHT, ///< -110 degrees, Rvs, TpRS + + AV_CHAN_BINAURAL_LEFT = 61, + AV_CHAN_BINAURAL_RIGHT, + + /** Channel is empty can be safely skipped. */ + AV_CHAN_UNUSED = 0x200, + + /** Channel contains data, but its position is unknown. */ + AV_CHAN_UNKNOWN = 0x300, + + /** + * Range of channels between AV_CHAN_AMBISONIC_BASE and + * AV_CHAN_AMBISONIC_END represent Ambisonic components using the ACN system. + * + * Given a channel id `` between AV_CHAN_AMBISONIC_BASE and + * AV_CHAN_AMBISONIC_END (inclusive), the ACN index of the channel `` is + * ` = - AV_CHAN_AMBISONIC_BASE`. + * + * @note these values are only used for AV_CHANNEL_ORDER_CUSTOM channel + * orderings, the AV_CHANNEL_ORDER_AMBISONIC ordering orders the channels + * implicitly by their position in the stream. + */ + AV_CHAN_AMBISONIC_BASE = 0x400, + // leave space for 1024 ids, which correspond to maximum order-32 harmonics, + // which should be enough for the foreseeable use cases + AV_CHAN_AMBISONIC_END = 0x7ff, +}; + +enum AVChannelOrder { + /** + * Only the channel count is specified, without any further information + * about the channel order. + */ + AV_CHANNEL_ORDER_UNSPEC, + /** + * The native channel order, i.e. the channels are in the same order in + * which they are defined in the AVChannel enum. This supports up to 63 + * different channels. + */ + AV_CHANNEL_ORDER_NATIVE, + /** + * The channel order does not correspond to any other predefined order and + * is stored as an explicit map. For example, this could be used to support + * layouts with 64 or more channels, or with empty/skipped (AV_CHAN_UNUSED) + * channels at arbitrary positions. + */ + AV_CHANNEL_ORDER_CUSTOM, + /** + * The audio is represented as the decomposition of the sound field into + * spherical harmonics. Each channel corresponds to a single expansion + * component. Channels are ordered according to ACN (Ambisonic Channel + * Number). + * + * The channel with the index n in the stream contains the spherical + * harmonic of degree l and order m given by + * @code{.unparsed} + * l = floor(sqrt(n)), + * m = n - l * (l + 1). + * @endcode + * + * Conversely given a spherical harmonic of degree l and order m, the + * corresponding channel index n is given by + * @code{.unparsed} + * n = l * (l + 1) + m. + * @endcode + * + * Normalization is assumed to be SN3D (Schmidt Semi-Normalization) + * as defined in AmbiX format $ 2.1. + */ + AV_CHANNEL_ORDER_AMBISONIC, + /** + * Number of channel orders, not part of ABI/API + */ + FF_CHANNEL_ORDER_NB +}; + + +/** + * @defgroup channel_masks Audio channel masks + * + * A channel layout is a 64-bits integer with a bit set for every channel. + * The number of bits set must be equal to the number of channels. + * The value 0 means that the channel layout is not known. + * @note this data structure is not powerful enough to handle channels + * combinations that have the same channel multiple times, such as + * dual-mono. + * + * @{ + */ +#define AV_CH_FRONT_LEFT (1ULL << AV_CHAN_FRONT_LEFT ) +#define AV_CH_FRONT_RIGHT (1ULL << AV_CHAN_FRONT_RIGHT ) +#define AV_CH_FRONT_CENTER (1ULL << AV_CHAN_FRONT_CENTER ) +#define AV_CH_LOW_FREQUENCY (1ULL << AV_CHAN_LOW_FREQUENCY ) +#define AV_CH_BACK_LEFT (1ULL << AV_CHAN_BACK_LEFT ) +#define AV_CH_BACK_RIGHT (1ULL << AV_CHAN_BACK_RIGHT ) +#define AV_CH_FRONT_LEFT_OF_CENTER (1ULL << AV_CHAN_FRONT_LEFT_OF_CENTER ) +#define AV_CH_FRONT_RIGHT_OF_CENTER (1ULL << AV_CHAN_FRONT_RIGHT_OF_CENTER) +#define AV_CH_BACK_CENTER (1ULL << AV_CHAN_BACK_CENTER ) +#define AV_CH_SIDE_LEFT (1ULL << AV_CHAN_SIDE_LEFT ) +#define AV_CH_SIDE_RIGHT (1ULL << AV_CHAN_SIDE_RIGHT ) +#define AV_CH_TOP_CENTER (1ULL << AV_CHAN_TOP_CENTER ) +#define AV_CH_TOP_FRONT_LEFT (1ULL << AV_CHAN_TOP_FRONT_LEFT ) +#define AV_CH_TOP_FRONT_CENTER (1ULL << AV_CHAN_TOP_FRONT_CENTER ) +#define AV_CH_TOP_FRONT_RIGHT (1ULL << AV_CHAN_TOP_FRONT_RIGHT ) +#define AV_CH_TOP_BACK_LEFT (1ULL << AV_CHAN_TOP_BACK_LEFT ) +#define AV_CH_TOP_BACK_CENTER (1ULL << AV_CHAN_TOP_BACK_CENTER ) +#define AV_CH_TOP_BACK_RIGHT (1ULL << AV_CHAN_TOP_BACK_RIGHT ) +#define AV_CH_STEREO_LEFT (1ULL << AV_CHAN_STEREO_LEFT ) +#define AV_CH_STEREO_RIGHT (1ULL << AV_CHAN_STEREO_RIGHT ) +#define AV_CH_WIDE_LEFT (1ULL << AV_CHAN_WIDE_LEFT ) +#define AV_CH_WIDE_RIGHT (1ULL << AV_CHAN_WIDE_RIGHT ) +#define AV_CH_SURROUND_DIRECT_LEFT (1ULL << AV_CHAN_SURROUND_DIRECT_LEFT ) +#define AV_CH_SURROUND_DIRECT_RIGHT (1ULL << AV_CHAN_SURROUND_DIRECT_RIGHT) +#define AV_CH_LOW_FREQUENCY_2 (1ULL << AV_CHAN_LOW_FREQUENCY_2 ) +#define AV_CH_TOP_SIDE_LEFT (1ULL << AV_CHAN_TOP_SIDE_LEFT ) +#define AV_CH_TOP_SIDE_RIGHT (1ULL << AV_CHAN_TOP_SIDE_RIGHT ) +#define AV_CH_BOTTOM_FRONT_CENTER (1ULL << AV_CHAN_BOTTOM_FRONT_CENTER ) +#define AV_CH_BOTTOM_FRONT_LEFT (1ULL << AV_CHAN_BOTTOM_FRONT_LEFT ) +#define AV_CH_BOTTOM_FRONT_RIGHT (1ULL << AV_CHAN_BOTTOM_FRONT_RIGHT ) +#define AV_CH_SIDE_SURROUND_LEFT (1ULL << AV_CHAN_SIDE_SURROUND_LEFT ) +#define AV_CH_SIDE_SURROUND_RIGHT (1ULL << AV_CHAN_SIDE_SURROUND_RIGHT ) +#define AV_CH_TOP_SURROUND_LEFT (1ULL << AV_CHAN_TOP_SURROUND_LEFT ) +#define AV_CH_TOP_SURROUND_RIGHT (1ULL << AV_CHAN_TOP_SURROUND_RIGHT ) +#define AV_CH_BINAURAL_LEFT (1ULL << AV_CHAN_BINAURAL_LEFT ) +#define AV_CH_BINAURAL_RIGHT (1ULL << AV_CHAN_BINAURAL_RIGHT ) + +/** + * @} + * @defgroup channel_mask_c Audio channel layouts + * @{ + * */ +#define AV_CH_LAYOUT_MONO (AV_CH_FRONT_CENTER) +#define AV_CH_LAYOUT_STEREO (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT) +#define AV_CH_LAYOUT_2POINT1 (AV_CH_LAYOUT_STEREO|AV_CH_LOW_FREQUENCY) +#define AV_CH_LAYOUT_2_1 (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER) +#define AV_CH_LAYOUT_SURROUND (AV_CH_LAYOUT_STEREO|AV_CH_FRONT_CENTER) +#define AV_CH_LAYOUT_3POINT1 (AV_CH_LAYOUT_SURROUND|AV_CH_LOW_FREQUENCY) +#define AV_CH_LAYOUT_4POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_CENTER) +#define AV_CH_LAYOUT_4POINT1 (AV_CH_LAYOUT_4POINT0|AV_CH_LOW_FREQUENCY) +#define AV_CH_LAYOUT_2_2 (AV_CH_LAYOUT_STEREO|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT) +#define AV_CH_LAYOUT_QUAD (AV_CH_LAYOUT_STEREO|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT) +#define AV_CH_LAYOUT_5POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT) +#define AV_CH_LAYOUT_5POINT1 (AV_CH_LAYOUT_5POINT0|AV_CH_LOW_FREQUENCY) +#define AV_CH_LAYOUT_5POINT0_BACK (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT) +#define AV_CH_LAYOUT_5POINT1_BACK (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_LOW_FREQUENCY) +#define AV_CH_LAYOUT_6POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_CENTER) +#define AV_CH_LAYOUT_6POINT0_FRONT (AV_CH_LAYOUT_2_2|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER) +#define AV_CH_LAYOUT_HEXAGONAL (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_BACK_CENTER) +#define AV_CH_LAYOUT_3POINT1POINT2 (AV_CH_LAYOUT_3POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT) +#define AV_CH_LAYOUT_6POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_CENTER) +#define AV_CH_LAYOUT_6POINT1_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_BACK_CENTER) +#define AV_CH_LAYOUT_6POINT1_FRONT (AV_CH_LAYOUT_6POINT0_FRONT|AV_CH_LOW_FREQUENCY) +#define AV_CH_LAYOUT_7POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT) +#define AV_CH_LAYOUT_7POINT0_FRONT (AV_CH_LAYOUT_5POINT0|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER) +#define AV_CH_LAYOUT_7POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT) +#define AV_CH_LAYOUT_7POINT1_WIDE (AV_CH_LAYOUT_5POINT1|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER) +#define AV_CH_LAYOUT_7POINT1_WIDE_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER) +#define AV_CH_LAYOUT_5POINT1POINT2 (AV_CH_LAYOUT_5POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT) +#define AV_CH_LAYOUT_5POINT1POINT2_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT) +#define AV_CH_LAYOUT_OCTAGONAL (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_CENTER|AV_CH_BACK_RIGHT) +#define AV_CH_LAYOUT_CUBE (AV_CH_LAYOUT_QUAD|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT) +#define AV_CH_LAYOUT_5POINT1POINT4_BACK (AV_CH_LAYOUT_5POINT1POINT2|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT) +#define AV_CH_LAYOUT_7POINT1POINT2 (AV_CH_LAYOUT_7POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT) +#define AV_CH_LAYOUT_7POINT1POINT4_BACK (AV_CH_LAYOUT_7POINT1POINT2|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT) +#define AV_CH_LAYOUT_7POINT2POINT3 (AV_CH_LAYOUT_7POINT1POINT2|AV_CH_TOP_BACK_CENTER|AV_CH_LOW_FREQUENCY_2) +#define AV_CH_LAYOUT_9POINT1POINT4_BACK (AV_CH_LAYOUT_7POINT1POINT4_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER) +#define AV_CH_LAYOUT_9POINT1POINT6 (AV_CH_LAYOUT_9POINT1POINT4_BACK|AV_CH_TOP_SIDE_LEFT|AV_CH_TOP_SIDE_RIGHT) +#define AV_CH_LAYOUT_HEXADECAGONAL (AV_CH_LAYOUT_OCTAGONAL|AV_CH_WIDE_LEFT|AV_CH_WIDE_RIGHT|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT|AV_CH_TOP_BACK_CENTER|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT) +#define AV_CH_LAYOUT_BINAURAL (AV_CH_BINAURAL_LEFT|AV_CH_BINAURAL_RIGHT) +#define AV_CH_LAYOUT_STEREO_DOWNMIX (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT) +#define AV_CH_LAYOUT_22POINT2 (AV_CH_LAYOUT_9POINT1POINT6|AV_CH_BACK_CENTER|AV_CH_LOW_FREQUENCY_2|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_CENTER|AV_CH_TOP_BACK_CENTER|AV_CH_BOTTOM_FRONT_CENTER|AV_CH_BOTTOM_FRONT_LEFT|AV_CH_BOTTOM_FRONT_RIGHT) + +#define AV_CH_LAYOUT_7POINT1_TOP_BACK AV_CH_LAYOUT_5POINT1POINT2_BACK + +enum AVMatrixEncoding { + AV_MATRIX_ENCODING_NONE, + AV_MATRIX_ENCODING_DOLBY, + AV_MATRIX_ENCODING_DPLII, + AV_MATRIX_ENCODING_DPLIIX, + AV_MATRIX_ENCODING_DPLIIZ, + AV_MATRIX_ENCODING_DOLBYEX, + AV_MATRIX_ENCODING_DOLBYHEADPHONE, + AV_MATRIX_ENCODING_NB +}; + +/** + * @} + */ + +/** + * An AVChannelCustom defines a single channel within a custom order layout + * + * Unlike most structures in FFmpeg, sizeof(AVChannelCustom) is a part of the + * public ABI. + * + * No new fields may be added to it without a major version bump. + */ +typedef struct AVChannelCustom { + enum AVChannel id; + char name[16]; + void *opaque; +} AVChannelCustom; + +/** + * An AVChannelLayout holds information about the channel layout of audio data. + * + * A channel layout here is defined as a set of channels ordered in a specific + * way (unless the channel order is AV_CHANNEL_ORDER_UNSPEC, in which case an + * AVChannelLayout carries only the channel count). + * All orders may be treated as if they were AV_CHANNEL_ORDER_UNSPEC by + * ignoring everything but the channel count, as long as av_channel_layout_check() + * considers they are valid. + * + * Unlike most structures in FFmpeg, sizeof(AVChannelLayout) is a part of the + * public ABI and may be used by the caller. E.g. it may be allocated on stack + * or embedded in caller-defined structs. + * + * AVChannelLayout can be initialized as follows: + * - default initialization with {0}, followed by setting all used fields + * correctly; + * - by assigning one of the predefined AV_CHANNEL_LAYOUT_* initializers; + * - with a constructor function, such as av_channel_layout_default(), + * av_channel_layout_from_mask() or av_channel_layout_from_string(). + * + * The channel layout must be uninitialized with av_channel_layout_uninit() + * + * Copying an AVChannelLayout via assigning is forbidden, + * av_channel_layout_copy() must be used instead (and its return value should + * be checked) + * + * No new fields may be added to it without a major version bump, except for + * new elements of the union fitting in sizeof(uint64_t). + */ +typedef struct AVChannelLayout { + /** + * Channel order used in this layout. + * This is a mandatory field. + */ + enum AVChannelOrder order; + + /** + * Number of channels in this layout. Mandatory field. + */ + int nb_channels; + + /** + * Details about which channels are present in this layout. + * For AV_CHANNEL_ORDER_UNSPEC, this field is undefined and must not be + * used. + */ + union { + /** + * This member must be used for AV_CHANNEL_ORDER_NATIVE, and may be used + * for AV_CHANNEL_ORDER_AMBISONIC to signal non-diegetic channels. + * It is a bitmask, where the position of each set bit means that the + * AVChannel with the corresponding value is present. + * + * I.e. when (mask & (1 << AV_CHAN_FOO)) is non-zero, then AV_CHAN_FOO + * is present in the layout. Otherwise it is not present. + * + * @note when a channel layout using a bitmask is constructed or + * modified manually (i.e. not using any of the av_channel_layout_* + * functions), the code doing it must ensure that the number of set bits + * is equal to nb_channels. + */ + uint64_t mask; + /** + * This member must be used when the channel order is + * AV_CHANNEL_ORDER_CUSTOM. It is a nb_channels-sized array, with each + * element signalling the presence of the AVChannel with the + * corresponding value in map[i].id. + * + * I.e. when map[i].id is equal to AV_CHAN_FOO, then AV_CH_FOO is the + * i-th channel in the audio data. + * + * When map[i].id is in the range between AV_CHAN_AMBISONIC_BASE and + * AV_CHAN_AMBISONIC_END (inclusive), the channel contains an ambisonic + * component with ACN index (as defined above) + * n = map[i].id - AV_CHAN_AMBISONIC_BASE. + * + * map[i].name may be filled with a 0-terminated string, in which case + * it will be used for the purpose of identifying the channel with the + * convenience functions below. Otherwise it must be zeroed. + */ + AVChannelCustom *map; + } u; + + /** + * For some private data of the user. + */ + void *opaque; +} AVChannelLayout; + +/** + * Macro to define native channel layouts + * + * @note This doesn't use designated initializers for compatibility with C++ 17 and older. + */ +#define AV_CHANNEL_LAYOUT_MASK(nb, m) \ + { /* .order */ AV_CHANNEL_ORDER_NATIVE, \ + /* .nb_channels */ (nb), \ + /* .u.mask */ { m }, \ + /* .opaque */ NULL } + +/** + * @name Common pre-defined channel layouts + * @{ + */ +#define AV_CHANNEL_LAYOUT_MONO AV_CHANNEL_LAYOUT_MASK(1, AV_CH_LAYOUT_MONO) +#define AV_CHANNEL_LAYOUT_STEREO AV_CHANNEL_LAYOUT_MASK(2, AV_CH_LAYOUT_STEREO) +#define AV_CHANNEL_LAYOUT_2POINT1 AV_CHANNEL_LAYOUT_MASK(3, AV_CH_LAYOUT_2POINT1) +#define AV_CHANNEL_LAYOUT_2_1 AV_CHANNEL_LAYOUT_MASK(3, AV_CH_LAYOUT_2_1) +#define AV_CHANNEL_LAYOUT_SURROUND AV_CHANNEL_LAYOUT_MASK(3, AV_CH_LAYOUT_SURROUND) +#define AV_CHANNEL_LAYOUT_3POINT1 AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_3POINT1) +#define AV_CHANNEL_LAYOUT_4POINT0 AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_4POINT0) +#define AV_CHANNEL_LAYOUT_4POINT1 AV_CHANNEL_LAYOUT_MASK(5, AV_CH_LAYOUT_4POINT1) +#define AV_CHANNEL_LAYOUT_2_2 AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_2_2) +#define AV_CHANNEL_LAYOUT_QUAD AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_QUAD) +#define AV_CHANNEL_LAYOUT_5POINT0 AV_CHANNEL_LAYOUT_MASK(5, AV_CH_LAYOUT_5POINT0) +#define AV_CHANNEL_LAYOUT_5POINT1 AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_5POINT1) +#define AV_CHANNEL_LAYOUT_5POINT0_BACK AV_CHANNEL_LAYOUT_MASK(5, AV_CH_LAYOUT_5POINT0_BACK) +#define AV_CHANNEL_LAYOUT_5POINT1_BACK AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_5POINT1_BACK) +#define AV_CHANNEL_LAYOUT_6POINT0 AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_6POINT0) +#define AV_CHANNEL_LAYOUT_6POINT0_FRONT AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_6POINT0_FRONT) +#define AV_CHANNEL_LAYOUT_3POINT1POINT2 AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_3POINT1POINT2) +#define AV_CHANNEL_LAYOUT_HEXAGONAL AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_HEXAGONAL) +#define AV_CHANNEL_LAYOUT_6POINT1 AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_6POINT1) +#define AV_CHANNEL_LAYOUT_6POINT1_BACK AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_6POINT1_BACK) +#define AV_CHANNEL_LAYOUT_6POINT1_FRONT AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_6POINT1_FRONT) +#define AV_CHANNEL_LAYOUT_7POINT0 AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_7POINT0) +#define AV_CHANNEL_LAYOUT_7POINT0_FRONT AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_7POINT0_FRONT) +#define AV_CHANNEL_LAYOUT_7POINT1 AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_7POINT1) +#define AV_CHANNEL_LAYOUT_7POINT1_WIDE AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_7POINT1_WIDE) +#define AV_CHANNEL_LAYOUT_7POINT1_WIDE_BACK AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_7POINT1_WIDE_BACK) +#define AV_CHANNEL_LAYOUT_5POINT1POINT2 AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_5POINT1POINT2) +#define AV_CHANNEL_LAYOUT_5POINT1POINT2_BACK AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_5POINT1POINT2_BACK) +#define AV_CHANNEL_LAYOUT_OCTAGONAL AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_OCTAGONAL) +#define AV_CHANNEL_LAYOUT_CUBE AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_CUBE) +#define AV_CHANNEL_LAYOUT_5POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(10, AV_CH_LAYOUT_5POINT1POINT4_BACK) +#define AV_CHANNEL_LAYOUT_7POINT1POINT2 AV_CHANNEL_LAYOUT_MASK(10, AV_CH_LAYOUT_7POINT1POINT2) +#define AV_CHANNEL_LAYOUT_7POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(12, AV_CH_LAYOUT_7POINT1POINT4_BACK) +#define AV_CHANNEL_LAYOUT_7POINT2POINT3 AV_CHANNEL_LAYOUT_MASK(12, AV_CH_LAYOUT_7POINT2POINT3) +#define AV_CHANNEL_LAYOUT_9POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(14, AV_CH_LAYOUT_9POINT1POINT4_BACK) +#define AV_CHANNEL_LAYOUT_9POINT1POINT6 AV_CHANNEL_LAYOUT_MASK(16, AV_CH_LAYOUT_9POINT1POINT6) +#define AV_CHANNEL_LAYOUT_HEXADECAGONAL AV_CHANNEL_LAYOUT_MASK(16, AV_CH_LAYOUT_HEXADECAGONAL) +#define AV_CHANNEL_LAYOUT_BINAURAL AV_CHANNEL_LAYOUT_MASK(2, AV_CH_LAYOUT_BINAURAL) +#define AV_CHANNEL_LAYOUT_STEREO_DOWNMIX AV_CHANNEL_LAYOUT_MASK(2, AV_CH_LAYOUT_STEREO_DOWNMIX) +#define AV_CHANNEL_LAYOUT_22POINT2 AV_CHANNEL_LAYOUT_MASK(24, AV_CH_LAYOUT_22POINT2) + +#define AV_CHANNEL_LAYOUT_7POINT1_TOP_BACK AV_CHANNEL_LAYOUT_5POINT1POINT2_BACK + +#define AV_CHANNEL_LAYOUT_AMBISONIC_FIRST_ORDER \ + { /* .order */ AV_CHANNEL_ORDER_AMBISONIC, \ + /* .nb_channels */ 4, \ + /* .u.mask */ { 0 }, \ + /* .opaque */ NULL } +/** @} */ + +struct AVBPrint; + +/** + * Get a human readable string in an abbreviated form describing a given channel. + * This is the inverse function of @ref av_channel_from_string(). + * + * @param buf pre-allocated buffer where to put the generated string + * @param buf_size size in bytes of the buffer. + * @param channel the AVChannel whose name to get + * @return amount of bytes needed to hold the output string, or a negative AVERROR + * on failure. If the returned value is bigger than buf_size, then the + * string was truncated. + */ +int av_channel_name(char *buf, size_t buf_size, enum AVChannel channel); + +/** + * bprint variant of av_channel_name(). + * + * @note the string will be appended to the bprint buffer. + */ +void av_channel_name_bprint(struct AVBPrint *bp, enum AVChannel channel_id); + +/** + * Get a human readable string describing a given channel. + * + * @param buf pre-allocated buffer where to put the generated string + * @param buf_size size in bytes of the buffer. + * @param channel the AVChannel whose description to get + * @return amount of bytes needed to hold the output string, or a negative AVERROR + * on failure. If the returned value is bigger than buf_size, then the + * string was truncated. + */ +int av_channel_description(char *buf, size_t buf_size, enum AVChannel channel); + +/** + * bprint variant of av_channel_description(). + * + * @note the string will be appended to the bprint buffer. + */ +void av_channel_description_bprint(struct AVBPrint *bp, enum AVChannel channel_id); + +/** + * This is the inverse function of @ref av_channel_name(). + * + * @return the channel with the given name + * AV_CHAN_NONE when name does not identify a known channel + */ +enum AVChannel av_channel_from_string(const char *name); + +/** + * Initialize a custom channel layout with the specified number of channels. + * The channel map will be allocated and the designation of all channels will + * be set to AV_CHAN_UNKNOWN. + * + * This is only a convenience helper function, a custom channel layout can also + * be constructed without using this. + * + * @param channel_layout the layout structure to be initialized + * @param nb_channels the number of channels + * + * @return 0 on success + * AVERROR(EINVAL) if the number of channels <= 0 + * AVERROR(ENOMEM) if the channel map could not be allocated + */ +int av_channel_layout_custom_init(AVChannelLayout *channel_layout, int nb_channels); + +/** + * Initialize a native channel layout from a bitmask indicating which channels + * are present. + * + * @param channel_layout the layout structure to be initialized + * @param mask bitmask describing the channel layout + * + * @return 0 on success + * AVERROR(EINVAL) for invalid mask values + */ +int av_channel_layout_from_mask(AVChannelLayout *channel_layout, uint64_t mask); + +/** + * Initialize a channel layout from a given string description. + * The input string can be represented by: + * - the formal channel layout name (returned by av_channel_layout_describe()) + * - single or multiple channel names (returned by av_channel_name(), eg. "FL", + * or concatenated with "+", each optionally containing a custom name after + * a "@", eg. "FL@Left+FR@Right+LFE") + * - a decimal or hexadecimal value of a native channel layout (eg. "4" or "0x4") + * - the number of channels with default layout (eg. "4c") + * - the number of unordered channels (eg. "4C" or "4 channels") + * - the ambisonic order followed by optional non-diegetic channels (eg. + * "ambisonic 2+stereo") + * On error, the channel layout will remain uninitialized, but not necessarily + * untouched. + * + * @param channel_layout uninitialized channel layout for the result + * @param str string describing the channel layout + * @return 0 on success parsing the channel layout + * AVERROR(EINVAL) if an invalid channel layout string was provided + * AVERROR(ENOMEM) if there was not enough memory + */ +int av_channel_layout_from_string(AVChannelLayout *channel_layout, + const char *str); + +/** + * Get the default channel layout for a given number of channels. + * + * @param ch_layout the layout structure to be initialized + * @param nb_channels number of channels + */ +void av_channel_layout_default(AVChannelLayout *ch_layout, int nb_channels); + +/** + * Iterate over all standard channel layouts. + * + * @param opaque a pointer where libavutil will store the iteration state. Must + * point to NULL to start the iteration. + * + * @return the standard channel layout or NULL when the iteration is + * finished + */ +const AVChannelLayout *av_channel_layout_standard(void **opaque); + +/** + * Free any allocated data in the channel layout and reset the channel + * count to 0. + * + * @param channel_layout the layout structure to be uninitialized + */ +void av_channel_layout_uninit(AVChannelLayout *channel_layout); + +/** + * Make a copy of a channel layout. This differs from just assigning src to dst + * in that it allocates and copies the map for AV_CHANNEL_ORDER_CUSTOM. + * + * @note the destination channel_layout will be always uninitialized before copy. + * + * @param dst destination channel layout + * @param src source channel layout + * @return 0 on success, a negative AVERROR on error. + */ +int av_channel_layout_copy(AVChannelLayout *dst, const AVChannelLayout *src); + +/** + * Get a human-readable string describing the channel layout properties. + * The string will be in the same format that is accepted by + * @ref av_channel_layout_from_string(), allowing to rebuild the same + * channel layout, except for opaque pointers. + * + * @param channel_layout channel layout to be described + * @param buf pre-allocated buffer where to put the generated string + * @param buf_size size in bytes of the buffer. + * @return amount of bytes needed to hold the output string, or a negative AVERROR + * on failure. If the returned value is bigger than buf_size, then the + * string was truncated. + */ +int av_channel_layout_describe(const AVChannelLayout *channel_layout, + char *buf, size_t buf_size); + +/** + * bprint variant of av_channel_layout_describe(). + * + * @note the string will be appended to the bprint buffer. + * @return 0 on success, or a negative AVERROR value on failure. + */ +int av_channel_layout_describe_bprint(const AVChannelLayout *channel_layout, + struct AVBPrint *bp); + +/** + * Get the channel with the given index in a channel layout. + * + * @param channel_layout input channel layout + * @param idx index of the channel + * @return channel with the index idx in channel_layout on success or + * AV_CHAN_NONE on failure (if idx is not valid or the channel order is + * unspecified) + */ +enum AVChannel +av_channel_layout_channel_from_index(const AVChannelLayout *channel_layout, unsigned int idx); + +/** + * Get the index of a given channel in a channel layout. In case multiple + * channels are found, only the first match will be returned. + * + * @param channel_layout input channel layout + * @param channel the channel whose index to obtain + * @return index of channel in channel_layout on success or a negative number if + * channel is not present in channel_layout. + */ +int av_channel_layout_index_from_channel(const AVChannelLayout *channel_layout, + enum AVChannel channel); + +/** + * Get the index in a channel layout of a channel described by the given string. + * In case multiple channels are found, only the first match will be returned. + * + * This function accepts channel names in the same format as + * @ref av_channel_from_string(). + * + * @param channel_layout input channel layout + * @param name string describing the channel whose index to obtain + * @return a channel index described by the given string, or a negative AVERROR + * value. + */ +int av_channel_layout_index_from_string(const AVChannelLayout *channel_layout, + const char *name); + +/** + * Get a channel described by the given string. + * + * This function accepts channel names in the same format as + * @ref av_channel_from_string(). + * + * @param channel_layout input channel layout + * @param name string describing the channel to obtain + * @return a channel described by the given string in channel_layout on success + * or AV_CHAN_NONE on failure (if the string is not valid or the channel + * order is unspecified) + */ +enum AVChannel +av_channel_layout_channel_from_string(const AVChannelLayout *channel_layout, + const char *name); + +/** + * Find out what channels from a given set are present in a channel layout, + * without regard for their positions. + * + * @param channel_layout input channel layout + * @param mask a combination of AV_CH_* representing a set of channels + * @return a bitfield representing all the channels from mask that are present + * in channel_layout + */ +uint64_t av_channel_layout_subset(const AVChannelLayout *channel_layout, + uint64_t mask); + +/** + * Check whether a channel layout is valid, i.e. can possibly describe audio + * data. + * + * @param channel_layout input channel layout + * @return 1 if channel_layout is valid, 0 otherwise. + */ +int av_channel_layout_check(const AVChannelLayout *channel_layout); + +/** + * Check whether two channel layouts are semantically the same, i.e. the same + * channels are present on the same positions in both. + * + * If one of the channel layouts is AV_CHANNEL_ORDER_UNSPEC, while the other is + * not, they are considered to be unequal. If both are AV_CHANNEL_ORDER_UNSPEC, + * they are considered equal iff the channel counts are the same in both. + * + * @param chl input channel layout + * @param chl1 input channel layout + * @return 0 if chl and chl1 are equal, 1 if they are not equal. A negative + * AVERROR code if one or both are invalid. + */ +int av_channel_layout_compare(const AVChannelLayout *chl, const AVChannelLayout *chl1); + +/** + * Return the order if the layout is n-th order standard-order ambisonic. + * The presence of optional extra non-diegetic channels at the end is not taken + * into account. + * + * @param channel_layout input channel layout + * @return the order of the layout, a negative error code otherwise. + */ +int av_channel_layout_ambisonic_order(const AVChannelLayout *channel_layout); + +/** + * The conversion must be lossless. + */ +#define AV_CHANNEL_LAYOUT_RETYPE_FLAG_LOSSLESS (1 << 0) + +/** + * The specified retype target order is ignored and the simplest possible + * (canonical) order is used for which the input layout can be losslessy + * represented. + */ +#define AV_CHANNEL_LAYOUT_RETYPE_FLAG_CANONICAL (1 << 1) + +/** + * Change the AVChannelOrder of a channel layout. + * + * Change of AVChannelOrder can be either lossless or lossy. In case of a + * lossless conversion all the channel designations and the associated channel + * names (if any) are kept. On a lossy conversion the channel names and channel + * designations might be lost depending on the capabilities of the desired + * AVChannelOrder. Note that some conversions are simply not possible in which + * case this function returns AVERROR(ENOSYS). + * + * The following conversions are supported: + * + * Any -> Custom : Always possible, always lossless. + * Any -> Unspecified: Always possible, lossless if channel designations + * are all unknown and channel names are not used, lossy otherwise. + * Custom -> Ambisonic : Possible if it contains ambisonic channels with + * optional non-diegetic channels in the end. Lossy if the channels have + * custom names, lossless otherwise. + * Custom -> Native : Possible if it contains native channels in native + * order. Lossy if the channels have custom names, lossless otherwise. + * + * On error this function keeps the original channel layout untouched. + * + * @param channel_layout channel layout which will be changed + * @param order the desired channel layout order + * @param flags a combination of AV_CHANNEL_LAYOUT_RETYPE_FLAG_* constants + * @return 0 if the conversion was successful and lossless or if the channel + * layout was already in the desired order + * >0 if the conversion was successful but lossy + * AVERROR(ENOSYS) if the conversion was not possible (or would be + * lossy and AV_CHANNEL_LAYOUT_RETYPE_FLAG_LOSSLESS was specified) + * AVERROR(EINVAL), AVERROR(ENOMEM) on error + */ +int av_channel_layout_retype(AVChannelLayout *channel_layout, enum AVChannelOrder order, int flags); + +/** + * @} + */ + +#endif /* AVUTIL_CHANNEL_LAYOUT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/common.h b/ffmpeg-n8.1/include/libavutil/common.h new file mode 100644 index 00000000..bf23aa50 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/common.h @@ -0,0 +1,589 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * common internal and external API header + */ + +#ifndef AVUTIL_COMMON_H +#define AVUTIL_COMMON_H + +#if defined(__cplusplus) && !defined(__STDC_CONSTANT_MACROS) && !defined(UINT64_C) +#error missing -D__STDC_CONSTANT_MACROS / #define __STDC_CONSTANT_MACROS +#endif + +#include +#include +#include +#include +#include +#include +#include +#include + +#include "attributes.h" +#include "error.h" +#include "macros.h" +#include "version.h" + +#ifdef HAVE_AV_CONFIG_H +# include "config.h" +# include "intmath.h" +# include "internal.h" +#else +# include "mem.h" +#endif /* HAVE_AV_CONFIG_H */ + +//rounded division & shift +#define RSHIFT(a,b) ((a) > 0 ? ((a) + ((1<<(b))>>1))>>(b) : ((a) + ((1<<(b))>>1)-1)>>(b)) +/* assume b>0 */ +#define ROUNDED_DIV(a,b) (((a)>=0 ? (a) + ((b)>>1) : (a) - ((b)>>1))/(b)) +/* Fast a/(1<=0 and b>=0 */ +#define AV_CEIL_RSHIFT(a,b) (!av_builtin_constant_p(b) ? -((-(a)) >> (b)) \ + : ((a) + (1<<(b)) - 1) >> (b)) +/* Backwards compat. */ +#define FF_CEIL_RSHIFT AV_CEIL_RSHIFT + +#define FFUDIV(a,b) (((a)>0 ?(a):(a)-(b)+1) / (b)) +#define FFUMOD(a,b) ((a)-(b)*FFUDIV(a,b)) + +/** + * Absolute value, Note, INT_MIN / INT64_MIN result in undefined behavior as they + * are not representable as absolute values of their type. This is the same + * as with *abs() + * @see FFNABS() + */ +#define FFABS(a) ((a) >= 0 ? (a) : (-(a))) +#define FFSIGN(a) ((a) > 0 ? 1 : -1) + +/** + * Negative Absolute value. + * this works for all integers of all types. + * As with many macros, this evaluates its argument twice, it thus must not have + * a sideeffect, that is FFNABS(x++) has undefined behavior. + */ +#define FFNABS(a) ((a) <= 0 ? (a) : (-(a))) + +/** + * Unsigned Absolute value. + * This takes the absolute value of a signed int and returns it as a unsigned. + * This also works with INT_MIN which would otherwise not be representable + * As with many macros, this evaluates its argument twice. + */ +#define FFABSU(a) ((a) <= 0 ? -(unsigned)(a) : (unsigned)(a)) +#define FFABS64U(a) ((a) <= 0 ? -(uint64_t)(a) : (uint64_t)(a)) + +/* misc math functions */ + +#ifndef av_ceil_log2 +# define av_ceil_log2 av_ceil_log2_c +#endif +#ifndef av_clip +# define av_clip av_clip_c +#endif +#ifndef av_clip64 +# define av_clip64 av_clip64_c +#endif +#ifndef av_clip_uint8 +# define av_clip_uint8 av_clip_uint8_c +#endif +#ifndef av_clip_int8 +# define av_clip_int8 av_clip_int8_c +#endif +#ifndef av_clip_uint16 +# define av_clip_uint16 av_clip_uint16_c +#endif +#ifndef av_clip_int16 +# define av_clip_int16 av_clip_int16_c +#endif +#ifndef av_clipl_int32 +# define av_clipl_int32 av_clipl_int32_c +#endif +#ifndef av_clip_intp2 +# define av_clip_intp2 av_clip_intp2_c +#endif +#ifndef av_clip_uintp2 +# define av_clip_uintp2 av_clip_uintp2_c +#endif +#ifndef av_sat_add32 +# define av_sat_add32 av_sat_add32_c +#endif +#ifndef av_sat_dadd32 +# define av_sat_dadd32 av_sat_dadd32_c +#endif +#ifndef av_sat_sub32 +# define av_sat_sub32 av_sat_sub32_c +#endif +#ifndef av_sat_dsub32 +# define av_sat_dsub32 av_sat_dsub32_c +#endif +#ifndef av_sat_add64 +# define av_sat_add64 av_sat_add64_c +#endif +#ifndef av_sat_sub64 +# define av_sat_sub64 av_sat_sub64_c +#endif +#ifndef av_clipf +# define av_clipf av_clipf_c +#endif +#ifndef av_clipd +# define av_clipd av_clipd_c +#endif +#ifndef av_zero_extend +# define av_zero_extend av_zero_extend_c +#endif +#ifndef av_popcount +# define av_popcount av_popcount_c +#endif +#ifndef av_popcount64 +# define av_popcount64 av_popcount64_c +#endif +#ifndef av_parity +# define av_parity av_parity_c +#endif + +#ifndef av_log2 +av_const int av_log2(unsigned v); +#endif + +#ifndef av_log2_16bit +av_const int av_log2_16bit(unsigned v); +#endif + +/** + * Clip a signed integer value into the amin-amax range. + * @param a value to clip + * @param amin minimum value of the clip range + * @param amax maximum value of the clip range + * @return clipped value + */ +static av_always_inline av_const int av_clip_c(int a, int amin, int amax) +{ +#if defined(HAVE_AV_CONFIG_H) && defined(ASSERT_LEVEL) && ASSERT_LEVEL >= 2 + if (amin > amax) abort(); +#endif + if (a < amin) return amin; + else if (a > amax) return amax; + else return a; +} + +/** + * Clip a signed 64bit integer value into the amin-amax range. + * @param a value to clip + * @param amin minimum value of the clip range + * @param amax maximum value of the clip range + * @return clipped value + */ +static av_always_inline av_const int64_t av_clip64_c(int64_t a, int64_t amin, int64_t amax) +{ +#if defined(HAVE_AV_CONFIG_H) && defined(ASSERT_LEVEL) && ASSERT_LEVEL >= 2 + if (amin > amax) abort(); +#endif + if (a < amin) return amin; + else if (a > amax) return amax; + else return a; +} + +/** + * Clip a signed integer value into the 0-255 range. + * @param a value to clip + * @return clipped value + */ +static av_always_inline av_const uint8_t av_clip_uint8_c(int a) +{ + if (a&(~0xFF)) return (~a)>>31; + else return a; +} + +/** + * Clip a signed integer value into the -128,127 range. + * @param a value to clip + * @return clipped value + */ +static av_always_inline av_const int8_t av_clip_int8_c(int a) +{ + if ((a+0x80U) & ~0xFF) return (a>>31) ^ 0x7F; + else return a; +} + +/** + * Clip a signed integer value into the 0-65535 range. + * @param a value to clip + * @return clipped value + */ +static av_always_inline av_const uint16_t av_clip_uint16_c(int a) +{ + if (a&(~0xFFFF)) return (~a)>>31; + else return a; +} + +/** + * Clip a signed integer value into the -32768,32767 range. + * @param a value to clip + * @return clipped value + */ +static av_always_inline av_const int16_t av_clip_int16_c(int a) +{ + if ((a+0x8000U) & ~0xFFFF) return (a>>31) ^ 0x7FFF; + else return a; +} + +/** + * Clip a signed 64-bit integer value into the -2147483648,2147483647 range. + * @param a value to clip + * @return clipped value + */ +static av_always_inline av_const int32_t av_clipl_int32_c(int64_t a) +{ + if ((a+UINT64_C(0x80000000)) & ~UINT64_C(0xFFFFFFFF)) return (int32_t)((a>>63) ^ 0x7FFFFFFF); + else return (int32_t)a; +} + +/** + * Clip a signed integer into the -(2^p),(2^p-1) range. + * @param a value to clip + * @param p bit position to clip at + * @return clipped value + */ +static av_always_inline av_const int av_clip_intp2_c(int a, int p) +{ + if (((unsigned)a + (1U << p)) & ~((2U << p) - 1)) + return (a >> 31) ^ ((1 << p) - 1); + else + return a; +} + +/** + * Clip a signed integer to an unsigned power of two range. + * @param a value to clip + * @param p bit position to clip at + * @return clipped value + */ +static av_always_inline av_const unsigned av_clip_uintp2_c(int a, int p) +{ + if (a & ~((1U<> 31 & ((1U<= 2 + if (p > 31) abort(); +#endif + return a & ((1U << p) - 1); +} + +#if FF_API_MOD_UINTP2 +#ifndef av_mod_uintp2 +# define av_mod_uintp2 av_mod_uintp2_c +#endif +attribute_deprecated +static av_always_inline av_const unsigned av_mod_uintp2_c(unsigned a, unsigned p) +{ + return av_zero_extend_c(a, p); +} +#endif + +/** + * Add two signed 32-bit values with saturation. + * + * @param a one value + * @param b another value + * @return sum with signed saturation + */ +static av_always_inline int av_sat_add32_c(int a, int b) +{ + return av_clipl_int32((int64_t)a + b); +} + +/** + * Add a doubled value to another value with saturation at both stages. + * + * @param a first value + * @param b value doubled and added to a + * @return sum sat(a + sat(2*b)) with signed saturation + */ +static av_always_inline int av_sat_dadd32_c(int a, int b) +{ + return av_sat_add32(a, av_sat_add32(b, b)); +} + +/** + * Subtract two signed 32-bit values with saturation. + * + * @param a one value + * @param b another value + * @return difference with signed saturation + */ +static av_always_inline int av_sat_sub32_c(int a, int b) +{ + return av_clipl_int32((int64_t)a - b); +} + +/** + * Subtract a doubled value from another value with saturation at both stages. + * + * @param a first value + * @param b value doubled and subtracted from a + * @return difference sat(a - sat(2*b)) with signed saturation + */ +static av_always_inline int av_sat_dsub32_c(int a, int b) +{ + return av_sat_sub32(a, av_sat_add32(b, b)); +} + +/** + * Add two signed 64-bit values with saturation. + * + * @param a one value + * @param b another value + * @return sum with signed saturation + */ +static av_always_inline int64_t av_sat_add64_c(int64_t a, int64_t b) { +#if (!defined(__INTEL_COMPILER) && AV_GCC_VERSION_AT_LEAST(5,1)) || AV_HAS_BUILTIN(__builtin_add_overflow) + int64_t tmp; + return !__builtin_add_overflow(a, b, &tmp) ? tmp : (tmp < 0 ? INT64_MAX : INT64_MIN); +#else + int64_t s = a+(uint64_t)b; + if ((int64_t)(a^b | ~s^b) >= 0) + return INT64_MAX ^ (b >> 63); + return s; +#endif +} + +/** + * Subtract two signed 64-bit values with saturation. + * + * @param a one value + * @param b another value + * @return difference with signed saturation + */ +static av_always_inline int64_t av_sat_sub64_c(int64_t a, int64_t b) { +#if (!defined(__INTEL_COMPILER) && AV_GCC_VERSION_AT_LEAST(5,1)) || AV_HAS_BUILTIN(__builtin_sub_overflow) + int64_t tmp; + return !__builtin_sub_overflow(a, b, &tmp) ? tmp : (tmp < 0 ? INT64_MAX : INT64_MIN); +#else + if (b <= 0 && a >= INT64_MAX + b) + return INT64_MAX; + if (b >= 0 && a <= INT64_MIN + b) + return INT64_MIN; + return a - b; +#endif +} + +/** + * Clip a float value into the amin-amax range. + * If a is nan or -inf amin will be returned. + * If a is +inf amax will be returned. + * @param a value to clip + * @param amin minimum value of the clip range + * @param amax maximum value of the clip range + * @return clipped value + */ +static av_always_inline av_const float av_clipf_c(float a, float amin, float amax) +{ +#if defined(HAVE_AV_CONFIG_H) && defined(ASSERT_LEVEL) && ASSERT_LEVEL >= 2 + if (amin > amax) abort(); +#endif + return FFMIN(FFMAX(a, amin), amax); +} + +/** + * Clip a double value into the amin-amax range. + * If a is nan or -inf amin will be returned. + * If a is +inf amax will be returned. + * @param a value to clip + * @param amin minimum value of the clip range + * @param amax maximum value of the clip range + * @return clipped value + */ +static av_always_inline av_const double av_clipd_c(double a, double amin, double amax) +{ +#if defined(HAVE_AV_CONFIG_H) && defined(ASSERT_LEVEL) && ASSERT_LEVEL >= 2 + if (amin > amax) abort(); +#endif + return FFMIN(FFMAX(a, amin), amax); +} + +/** Compute ceil(log2(x)). + * @param x value used to compute ceil(log2(x)) + * @return computed ceiling of log2(x) + */ +static av_always_inline av_const int av_ceil_log2_c(int x) +{ + return av_log2((x - 1U) << 1); +} + +/** + * Count number of bits set to one in x + * @param x value to count bits of + * @return the number of bits set to one in x + */ +static av_always_inline av_const int av_popcount_c(uint32_t x) +{ + x -= (x >> 1) & 0x55555555; + x = (x & 0x33333333) + ((x >> 2) & 0x33333333); + x = (x + (x >> 4)) & 0x0F0F0F0F; + x += x >> 8; + return (x + (x >> 16)) & 0x3F; +} + +/** + * Count number of bits set to one in x + * @param x value to count bits of + * @return the number of bits set to one in x + */ +static av_always_inline av_const int av_popcount64_c(uint64_t x) +{ + return av_popcount((uint32_t)x) + av_popcount((uint32_t)(x >> 32)); +} + +static av_always_inline av_const int av_parity_c(uint32_t v) +{ + return av_popcount(v) & 1; +} + +/** + * Convert a UTF-8 character (up to 4 bytes) to its 32-bit UCS-4 encoded form. + * + * @param val Output value, must be an lvalue of type uint32_t. + * @param GET_BYTE Expression reading one byte from the input. + * Evaluated up to 7 times (4 for the currently + * assigned Unicode range). With a memory buffer + * input, this could be *ptr++, or if you want to make sure + * that *ptr stops at the end of a NULL terminated string then + * *ptr ? *ptr++ : 0 + * @param ERROR Expression to be evaluated on invalid input, + * typically a goto statement. + * + * @warning ERROR should not contain a loop control statement which + * could interact with the internal while loop, and should force an + * exit from the macro code (e.g. through a goto or a return) in order + * to prevent undefined results. + */ +#define GET_UTF8(val, GET_BYTE, ERROR)\ + val= (uint8_t)(GET_BYTE);\ + {\ + uint32_t top = (val & 128) >> 1;\ + if ((val & 0xc0) == 0x80 || val >= 0xFE)\ + {ERROR}\ + while (val & top) {\ + unsigned int tmp = (uint8_t)(GET_BYTE) - 128;\ + if(tmp>>6)\ + {ERROR}\ + val= (val<<6) + tmp;\ + top <<= 5;\ + }\ + val &= (top << 1) - 1;\ + } + +/** + * Convert a UTF-16 character (2 or 4 bytes) to its 32-bit UCS-4 encoded form. + * + * @param val Output value, must be an lvalue of type uint32_t. + * @param GET_16BIT Expression returning two bytes of UTF-16 data converted + * to native byte order. Evaluated one or two times. + * @param ERROR Expression to be evaluated on invalid input, + * typically a goto statement. + */ +#define GET_UTF16(val, GET_16BIT, ERROR)\ + val = (uint16_t)(GET_16BIT);\ + {\ + unsigned int hi = val - 0xD800;\ + if (hi < 0x800) {\ + val = (uint16_t)(GET_16BIT) - 0xDC00;\ + if (val > 0x3FFU || hi > 0x3FFU)\ + {ERROR}\ + val += (hi<<10) + 0x10000;\ + }\ + }\ + +/** + * @def PUT_UTF8(val, tmp, PUT_BYTE) + * Convert a 32-bit Unicode character to its UTF-8 encoded form (up to 4 bytes long). + * @param val is an input-only argument and should be of type uint32_t. It holds + * a UCS-4 encoded Unicode character that is to be converted to UTF-8. If + * val is given as a function it is executed only once. + * @param tmp is a temporary variable and should be of type uint8_t. It + * represents an intermediate value during conversion that is to be + * output by PUT_BYTE. + * @param PUT_BYTE writes the converted UTF-8 bytes to any proper destination. + * It could be a function or a statement, and uses tmp as the input byte. + * For example, PUT_BYTE could be "*output++ = tmp;" PUT_BYTE will be + * executed up to 4 times for values in the valid UTF-8 range and up to + * 7 times in the general case, depending on the length of the converted + * Unicode character. + */ +#define PUT_UTF8(val, tmp, PUT_BYTE)\ + {\ + int bytes, shift;\ + uint32_t in = val;\ + if (in < 0x80) {\ + tmp = in;\ + PUT_BYTE\ + } else {\ + bytes = (av_log2(in) + 4) / 5;\ + shift = (bytes - 1) * 6;\ + tmp = (256 - (256 >> bytes)) | (in >> shift);\ + PUT_BYTE\ + while (shift >= 6) {\ + shift -= 6;\ + tmp = 0x80 | ((in >> shift) & 0x3f);\ + PUT_BYTE\ + }\ + }\ + } + +/** + * @def PUT_UTF16(val, tmp, PUT_16BIT) + * Convert a 32-bit Unicode character to its UTF-16 encoded form (2 or 4 bytes). + * @param val is an input-only argument and should be of type uint32_t. It holds + * a UCS-4 encoded Unicode character that is to be converted to UTF-16. If + * val is given as a function it is executed only once. + * @param tmp is a temporary variable and should be of type uint16_t. It + * represents an intermediate value during conversion that is to be + * output by PUT_16BIT. + * @param PUT_16BIT writes the converted UTF-16 data to any proper destination + * in desired endianness. It could be a function or a statement, and uses tmp + * as the input byte. For example, PUT_BYTE could be "*output++ = tmp;" + * PUT_BYTE will be executed 1 or 2 times depending on input character. + */ +#define PUT_UTF16(val, tmp, PUT_16BIT)\ + {\ + uint32_t in = val;\ + if (in < 0x10000) {\ + tmp = in;\ + PUT_16BIT\ + } else {\ + tmp = 0xD800 | ((in - 0x10000) >> 10);\ + PUT_16BIT\ + tmp = 0xDC00 | ((in - 0x10000) & 0x3FF);\ + PUT_16BIT\ + }\ + }\ + +#endif /* AVUTIL_COMMON_H */ diff --git a/ffmpeg-n8.1/include/libavutil/container_fifo.h b/ffmpeg-n8.1/include/libavutil/container_fifo.h new file mode 100644 index 00000000..ff924931 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/container_fifo.h @@ -0,0 +1,130 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_CONTAINER_FIFO_H +#define AVUTIL_CONTAINER_FIFO_H + +#include + +/** + * AVContainerFifo is a FIFO for "containers" - dynamically allocated reusable + * structs (e.g. AVFrame or AVPacket). AVContainerFifo uses an internal pool of + * such containers to avoid allocating and freeing them repeatedly. + */ +typedef struct AVContainerFifo AVContainerFifo; + +enum AVContainerFifoFlags { + /** + * Signal to av_container_fifo_write() that it should make a new reference + * to data in src rather than consume its contents. + * + * @note you must handle this flag manually in your own fifo_transfer() + * callback + */ + AV_CONTAINER_FIFO_FLAG_REF = (1 << 0), + + /** + * This and all higher bits in flags may be set to any value by the caller + * and are guaranteed to be passed through to the fifo_transfer() callback + * and not be interpreted by AVContainerFifo code. + */ + AV_CONTAINER_FIFO_FLAG_USER = (1 << 16), +}; + +/** + * Allocate a new AVContainerFifo for the container type defined by provided + * callbacks. + * + * @param opaque user data that will be passed to the callbacks provided to this + * function + * @param container_alloc allocate a new container instance and return a pointer + * to it, or NULL on failure + * @param container_reset reset the provided container instance to a clean state + * @param container_free free the provided container instance + * @param fifo_transfer Transfer the contents of container src to dst. + * @param flags currently unused + * + * @return newly allocated AVContainerFifo, or NULL on failure + */ +AVContainerFifo* +av_container_fifo_alloc(void *opaque, + void* (*container_alloc)(void *opaque), + void (*container_reset)(void *opaque, void *obj), + void (*container_free) (void *opaque, void *obj), + int (*fifo_transfer) (void *opaque, void *dst, void *src, unsigned flags), + unsigned flags); + +/** + * Allocate an AVContainerFifo instance for AVFrames. + * + * @param flags currently unused + */ +AVContainerFifo *av_container_fifo_alloc_avframe(unsigned flags); + +/** + * Free a AVContainerFifo and everything in it. + */ +void av_container_fifo_free(AVContainerFifo **cf); + +/** + * Write the contents of obj to the FIFO. + * + * The fifo_transfer() callback previously provided to av_container_fifo_alloc() + * will be called with obj as src in order to perform the actual transfer. + */ +int av_container_fifo_write(AVContainerFifo *cf, void *obj, unsigned flags); + +/** + * Read the next available object from the FIFO into obj. + * + * The fifo_read() callback previously provided to av_container_fifo_alloc() + * will be called with obj as dst in order to perform the actual transfer. + */ +int av_container_fifo_read(AVContainerFifo *cf, void *obj, unsigned flags); + +/** + * Access objects stored in the FIFO without retrieving them. The + * fifo_transfer() callback will NOT be invoked and the FIFO state will not be + * modified. + * + * @param pobj Pointer to the object stored in the FIFO will be written here on + * success. The object remains owned by the FIFO and the caller may + * only access it as long as the FIFO is not modified. + * @param offset Position of the object to retrieve - 0 is the next item that + * would be read, 1 the one after, etc. Must be smaller than + * av_container_fifo_can_read(). + * + * @retval 0 success, a pointer was written into pobj + * @retval AVERROR(EINVAL) invalid offset value + */ +int av_container_fifo_peek(AVContainerFifo *cf, void **pobj, size_t offset); + +/** + * Discard the specified number of elements from the FIFO. + * + * @param nb_elems number of elements to discard, MUST NOT be larger than + * av_fifo_can_read(f) + */ +void av_container_fifo_drain(AVContainerFifo *cf, size_t nb_elems); + +/** + * @return number of objects available for reading + */ +size_t av_container_fifo_can_read(const AVContainerFifo *cf); + +#endif // AVCODEC_CONTAINER_FIFO_H diff --git a/ffmpeg-n8.1/include/libavutil/cpu.h b/ffmpeg-n8.1/include/libavutil/cpu.h new file mode 100644 index 00000000..464d4cd5 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/cpu.h @@ -0,0 +1,157 @@ +/* + * Copyright (c) 2000, 2001, 2002 Fabrice Bellard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_CPU_H +#define AVUTIL_CPU_H + +#include +#include "version.h" + +#if FF_API_CPU_FLAG_FORCE +#define AV_CPU_FLAG_FORCE 0x80000000 /* @deprecated, should not be used */ +#endif + + /* lower 16 bits - CPU features */ +#define AV_CPU_FLAG_MMX 0x0001 ///< standard MMX +#define AV_CPU_FLAG_MMXEXT 0x0002 ///< SSE integer functions or AMD MMX ext +#define AV_CPU_FLAG_MMX2 0x0002 ///< SSE integer functions or AMD MMX ext +#define AV_CPU_FLAG_3DNOW 0x0004 ///< AMD 3DNOW +#define AV_CPU_FLAG_SSE 0x0008 ///< SSE functions +#define AV_CPU_FLAG_SSE2 0x0010 ///< PIV SSE2 functions +#define AV_CPU_FLAG_SSE2SLOW 0x40000000 ///< SSE2 supported, but usually not faster + ///< than regular MMX/SSE (e.g. Core1) +#define AV_CPU_FLAG_3DNOWEXT 0x0020 ///< AMD 3DNowExt +#define AV_CPU_FLAG_SSE3 0x0040 ///< Prescott SSE3 functions +#define AV_CPU_FLAG_SSE3SLOW 0x20000000 ///< SSE3 supported, but usually not faster + ///< than regular MMX/SSE (e.g. Core1) +#define AV_CPU_FLAG_SSSE3 0x0080 ///< Conroe SSSE3 functions +#define AV_CPU_FLAG_SSSE3SLOW 0x4000000 ///< SSSE3 supported, but usually not faster +#define AV_CPU_FLAG_ATOM 0x10000000 ///< Atom processor, some SSSE3 instructions are slower +#define AV_CPU_FLAG_SSE4 0x0100 ///< Penryn SSE4.1 functions +#define AV_CPU_FLAG_SSE42 0x0200 ///< Nehalem SSE4.2 functions +#define AV_CPU_FLAG_AESNI 0x80000 ///< Advanced Encryption Standard functions +#define AV_CPU_FLAG_CLMUL 0x400000 ///< Carry-less Multiplication instruction +#define AV_CPU_FLAG_AVX 0x4000 ///< AVX functions: requires OS support even if YMM registers aren't used +#define AV_CPU_FLAG_AVXSLOW 0x8000000 ///< AVX supported, but slow when using YMM registers (e.g. Bulldozer) +#define AV_CPU_FLAG_XOP 0x0400 ///< Bulldozer XOP functions +#define AV_CPU_FLAG_FMA4 0x0800 ///< Bulldozer FMA4 functions +#define AV_CPU_FLAG_CMOV 0x1000 ///< supports cmov instruction +#define AV_CPU_FLAG_AVX2 0x8000 ///< AVX2 functions: requires OS support even if YMM registers aren't used +#define AV_CPU_FLAG_FMA3 0x10000 ///< Haswell FMA3 functions +#define AV_CPU_FLAG_BMI1 0x20000 ///< Bit Manipulation Instruction Set 1 +#define AV_CPU_FLAG_BMI2 0x40000 ///< Bit Manipulation Instruction Set 2 +#define AV_CPU_FLAG_AVX512 0x100000 ///< AVX-512 functions: requires OS support even if YMM/ZMM registers aren't used +#define AV_CPU_FLAG_AVX512ICL 0x200000 ///< F/CD/BW/DQ/VL/VNNI/IFMA/VBMI/VBMI2/VPOPCNTDQ/BITALG/GFNI/VAES/VPCLMULQDQ +#define AV_CPU_FLAG_SLOW_GATHER 0x2000000 ///< CPU has slow gathers. + +#define AV_CPU_FLAG_ALTIVEC 0x0001 ///< standard +#define AV_CPU_FLAG_VSX 0x0002 ///< ISA 2.06 +#define AV_CPU_FLAG_POWER8 0x0004 ///< ISA 2.07 + +#define AV_CPU_FLAG_ARMV5TE (1 << 0) +#define AV_CPU_FLAG_ARMV6 (1 << 1) +#define AV_CPU_FLAG_ARMV6T2 (1 << 2) +#define AV_CPU_FLAG_VFP (1 << 3) +#define AV_CPU_FLAG_VFPV3 (1 << 4) +#define AV_CPU_FLAG_NEON (1 << 5) +#define AV_CPU_FLAG_ARMV8 (1 << 6) +#define AV_CPU_FLAG_VFP_VM (1 << 7) ///< VFPv2 vector mode, deprecated in ARMv7-A and unavailable in various CPUs implementations +#define AV_CPU_FLAG_DOTPROD (1 << 8) +#define AV_CPU_FLAG_I8MM (1 << 9) +#define AV_CPU_FLAG_SVE (1 <<10) +#define AV_CPU_FLAG_SVE2 (1 <<11) +#define AV_CPU_FLAG_SME (1 <<12) +#define AV_CPU_FLAG_ARM_CRC (1 <<13) +#define AV_CPU_FLAG_SME2 (1 <<14) +#define AV_CPU_FLAG_SME_I16I64 (1 <<15) +#define AV_CPU_FLAG_SETEND (1 <<16) + +#define AV_CPU_FLAG_MMI (1 << 0) +#define AV_CPU_FLAG_MSA (1 << 1) + +//Loongarch SIMD extension. +#define AV_CPU_FLAG_LSX (1 << 0) +#define AV_CPU_FLAG_LASX (1 << 1) + +// RISC-V extensions +#define AV_CPU_FLAG_RVI (1 << 0) ///< I (full GPR bank) +#if FF_API_RISCV_FD_ZBA +#define AV_CPU_FLAG_RVF (1 << 1) ///< F (single precision FP) +#define AV_CPU_FLAG_RVD (1 << 2) ///< D (double precision FP) +#endif +#define AV_CPU_FLAG_RVV_I32 (1 << 3) ///< Vectors of 8/16/32-bit int's */ +#define AV_CPU_FLAG_RVV_F32 (1 << 4) ///< Vectors of float's */ +#define AV_CPU_FLAG_RVV_I64 (1 << 5) ///< Vectors of 64-bit int's */ +#define AV_CPU_FLAG_RVV_F64 (1 << 6) ///< Vectors of double's +#define AV_CPU_FLAG_RVB_BASIC (1 << 7) ///< Basic bit-manipulations +#if FF_API_RISCV_FD_ZBA +#define AV_CPU_FLAG_RVB_ADDR (1 << 8) ///< Address bit-manipulations +#endif +#define AV_CPU_FLAG_RV_ZVBB (1 << 9) ///< Vector basic bit-manipulations +#define AV_CPU_FLAG_RV_MISALIGNED (1 <<10) ///< Fast misaligned accesses +#define AV_CPU_FLAG_RVB (1 <<11) ///< B (bit manipulations) + +// WASM extensions +#define AV_CPU_FLAG_SIMD128 (1 << 0) + +/** + * Return the flags which specify extensions supported by the CPU. + * The returned value is affected by av_force_cpu_flags() if that was used + * before. So av_get_cpu_flags() can easily be used in an application to + * detect the enabled cpu flags. + */ +int av_get_cpu_flags(void); + +/** + * Disables cpu detection and forces the specified flags. + * -1 is a special case that disables forcing of specific flags. + */ +void av_force_cpu_flags(int flags); + +/** + * Parse CPU caps from a string and update the given AV_CPU_* flags based on that. + * + * @return negative on error. + */ +int av_parse_cpu_caps(unsigned *flags, const char *s); + +/** + * @return the number of logical CPU cores present. + */ +int av_cpu_count(void); + +/** + * Overrides cpu count detection and forces the specified count. + * Count < 1 disables forcing of specific count. + */ +void av_cpu_force_count(int count); + +/** + * Get the maximum data alignment that may be required by FFmpeg. + * + * Note that this is affected by the build configuration and the CPU flags mask, + * so e.g. if the CPU supports AVX, but libavutil has been built with + * --disable-avx or the AV_CPU_FLAG_AVX flag has been disabled through + * av_set_cpu_flags_mask(), then this function will behave as if AVX is not + * present. + */ +size_t av_cpu_max_align(void); + +#endif /* AVUTIL_CPU_H */ diff --git a/ffmpeg-n8.1/include/libavutil/crc.h b/ffmpeg-n8.1/include/libavutil/crc.h new file mode 100644 index 00000000..7f59812a --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/crc.h @@ -0,0 +1,102 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_crc32 + * Public header for CRC hash function implementation. + */ + +#ifndef AVUTIL_CRC_H +#define AVUTIL_CRC_H + +#include +#include +#include "attributes.h" + +/** + * @defgroup lavu_crc32 CRC + * @ingroup lavu_hash + * CRC (Cyclic Redundancy Check) hash function implementation. + * + * This module supports numerous CRC polynomials, in addition to the most + * widely used CRC-32-IEEE. See @ref AVCRCId for a list of available + * polynomials. + * + * @{ + */ + +typedef uint32_t AVCRC; + +typedef enum { + AV_CRC_8_ATM, + AV_CRC_16_ANSI, + AV_CRC_16_CCITT, + AV_CRC_32_IEEE, + AV_CRC_32_IEEE_LE, /*< reversed bitorder version of AV_CRC_32_IEEE */ + AV_CRC_16_ANSI_LE, /*< reversed bitorder version of AV_CRC_16_ANSI */ + AV_CRC_24_IEEE, + AV_CRC_8_EBU, + AV_CRC_MAX, /*< Not part of public API! Do not use outside libavutil. */ +}AVCRCId; + +/** + * Initialize a CRC table. + * @param ctx must be an array of size sizeof(AVCRC)*257 or sizeof(AVCRC)*1024 + * @param le If 1, the lowest bit represents the coefficient for the highest + * exponent of the corresponding polynomial (both for poly and + * actual CRC). + * If 0, you must swap the CRC parameter and the result of av_crc + * if you need the standard representation (can be simplified in + * most cases to e.g. bswap16): + * av_bswap32(crc << (32-bits)) + * @param bits number of bits for the CRC + * @param poly generator polynomial without the x**bits coefficient, in the + * representation as specified by le + * @param ctx_size size of ctx in bytes + * @return <0 on failure + */ +int av_crc_init(AVCRC *ctx, int le, int bits, uint32_t poly, int ctx_size); + +/** + * Get an initialized standard CRC table. + * @param crc_id ID of a standard CRC + * @return a pointer to the CRC table or NULL on failure + */ +const AVCRC *av_crc_get_table(AVCRCId crc_id); + +/** + * Calculate the CRC of a block. + * @param ctx initialized AVCRC array (see av_crc_init()) + * @param crc CRC of previous blocks if any or initial value for CRC + * @param buffer buffer whose CRC to calculate + * @param length length of the buffer + * @return CRC updated with the data from the given block + * + * @see av_crc_init() "le" parameter + */ +uint32_t av_crc(const AVCRC *ctx, uint32_t crc, + const uint8_t *buffer, size_t length) av_pure; + +/** + * @} + */ + +#endif /* AVUTIL_CRC_H */ diff --git a/ffmpeg-n8.1/include/libavutil/csp.h b/ffmpeg-n8.1/include/libavutil/csp.h new file mode 100644 index 00000000..9d75ccbb --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/csp.h @@ -0,0 +1,208 @@ +/* + * Copyright (c) 2015 Kevin Wheatley + * Copyright (c) 2016 Ronald S. Bultje + * Copyright (c) 2023 Leo Izen + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_CSP_H +#define AVUTIL_CSP_H + +#include "pixfmt.h" +#include "rational.h" + +/** + * @file + * Colorspace value utility functions for libavutil. + * @ingroup lavu_math_csp + * @author Ronald S. Bultje + * @author Leo Izen + * @author Kevin Wheatley + */ + +/** + * @defgroup lavu_math_csp Colorspace Utility + * @ingroup lavu_math + * @{ + */ + +/** + * Struct containing luma coefficients to be used for RGB to YUV/YCoCg, or similar + * calculations. + */ +typedef struct AVLumaCoefficients { + AVRational cr, cg, cb; +} AVLumaCoefficients; + +/** + * Struct containing chromaticity x and y values for the standard CIE 1931 + * chromaticity definition. + */ +typedef struct AVCIExy { + AVRational x, y; +} AVCIExy; + +/** + * Struct defining the red, green, and blue primary locations in terms of CIE + * 1931 chromaticity x and y. + */ +typedef struct AVPrimaryCoefficients { + AVCIExy r, g, b; +} AVPrimaryCoefficients; + +/** + * Struct defining white point location in terms of CIE 1931 chromaticity x + * and y. + */ +typedef AVCIExy AVWhitepointCoefficients; + +/** + * Struct that contains both white point location and primaries location, providing + * the complete description of a color gamut. + */ +typedef struct AVColorPrimariesDesc { + AVWhitepointCoefficients wp; + AVPrimaryCoefficients prim; +} AVColorPrimariesDesc; + +/** + * Function pointer representing a double -> double transfer function that + * performs either an OETF transfer function, or alternatively an inverse EOTF + * function (in particular, for SMPTE ST 2084 / PQ). This function inputs + * linear light, and outputs gamma encoded light. + * + * See ITU-T H.273 for more information. + */ +typedef double (*av_csp_trc_function)(double); + +/** + * Retrieves the Luma coefficients necessary to construct a conversion matrix + * from an enum constant describing the colorspace. + * @param csp An enum constant indicating YUV or similar colorspace. + * @return The Luma coefficients associated with that colorspace, or NULL + * if the constant is unknown to libavutil. + */ +const AVLumaCoefficients *av_csp_luma_coeffs_from_avcsp(enum AVColorSpace csp); + +/** + * Retrieves a complete gamut description from an enum constant describing the + * color primaries. + * @param prm An enum constant indicating primaries + * @return A description of the colorspace gamut associated with that enum + * constant, or NULL if the constant is unknown to libavutil. + */ +const AVColorPrimariesDesc *av_csp_primaries_desc_from_id(enum AVColorPrimaries prm); + +/** + * Detects which enum AVColorPrimaries constant corresponds to the given complete + * gamut description. + * @see enum AVColorPrimaries + * @param prm A description of the colorspace gamut + * @return The enum constant associated with this gamut, or + * AVCOL_PRI_UNSPECIFIED if no clear match can be identified. + */ +enum AVColorPrimaries av_csp_primaries_id_from_desc(const AVColorPrimariesDesc *prm); + +/** + * Determine a suitable 'gamma' value to match the supplied + * AVColorTransferCharacteristic. + * + * See Apple Technical Note TN2257 (https://developer.apple.com/library/mac/technotes/tn2257/_index.html) + * + * This function returns the gamma exponent for the OETF. For example, sRGB is approximated + * by gamma 2.2, not by gamma 0.45455. + * + * @return Will return an approximation to the simple gamma function matching + * the supplied Transfer Characteristic, Will return 0.0 for any + * we cannot reasonably match against. + */ +double av_csp_approximate_trc_gamma(enum AVColorTransferCharacteristic trc); + +/** + * Determine a suitable EOTF 'gamma' value to match the supplied + * AVColorTransferCharacteristic. + * + * This function returns the gamma value (exponent) for a simple pure power + * function approximation of the supplied AVColorTransferCharacteristic, or 0. + * if no reasonable approximation exists. + * + * EOTF(v) = (L_w - L_b) * v^gamma + L_b + * + * @return Will return an approximation to the simple gamma function matching + * the supplied Transfer Characteristic EOTF, Will return 0.0 for any + * we cannot reasonably match against. + */ +double av_csp_approximate_eotf_gamma(enum AVColorTransferCharacteristic trc); + +/** + * Determine the function needed to apply the given + * AVColorTransferCharacteristic to linear input. + * + * The function returned should expect a nominal domain and range of [0.0-1.0] + * values outside of this range maybe valid depending on the chosen + * characteristic function. + * + * @return Will return pointer to the function matching the + * supplied Transfer Characteristic. If unspecified will + * return NULL: + */ +av_csp_trc_function av_csp_trc_func_from_id(enum AVColorTransferCharacteristic trc); + +/** + * Returns the mathematical inverse of the corresponding TRC function. + */ +av_csp_trc_function av_csp_trc_func_inv_from_id(enum AVColorTransferCharacteristic trc); + +/** + * Function pointer representing an ITU EOTF transfer for a given reference + * display configuration. + * + * @param Lw The white point luminance of the display, in nits (cd/m^2). + * @param Lb The black point luminance of the display, in nits (cd/m^2). + */ +typedef void (*av_csp_eotf_function)(double Lw, double Lb, double c[3]); + +/** + * Returns the ITU EOTF corresponding to a given TRC. This converts from the + * signal level [0,1] to the raw output display luminance in nits (cd/m^2). + * This is done per channel in RGB space, except for AVCOL_TRC_SMPTE428, which + * assumes CIE XYZ in- and output. + * + * @return A pointer to the function implementing the given TRC, or NULL if no + * such function is defined. + * + * @note In general, the resulting function is defined (wherever possible) for + * out-of-range values, even though these values do not have a physical + * meaning on the given display. Users should clamp inputs (or outputs) + * if this behavior is not desired. + * + * This is also the case for functions like PQ, which are defined over an + * absolute signal range independent of the target display capabilities. + */ +av_csp_eotf_function av_csp_itu_eotf(enum AVColorTransferCharacteristic trc); + +/** + * Returns the mathematical inverse of the corresponding EOTF. + */ +av_csp_eotf_function av_csp_itu_eotf_inv(enum AVColorTransferCharacteristic trc); + +/** + * @} + */ + +#endif /* AVUTIL_CSP_H */ diff --git a/ffmpeg-n8.1/include/libavutil/des.h b/ffmpeg-n8.1/include/libavutil/des.h new file mode 100644 index 00000000..3a3e6fa4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/des.h @@ -0,0 +1,81 @@ +/* + * DES encryption/decryption + * Copyright (c) 2007 Reimar Doeffinger + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_DES_H +#define AVUTIL_DES_H + +#include + +/** + * @defgroup lavu_des DES + * @ingroup lavu_crypto + * @{ + */ + +typedef struct AVDES { + uint64_t round_keys[3][16]; + int triple_des; +} AVDES; + +/** + * Allocate an AVDES context. + */ +AVDES *av_des_alloc(void); + +/** + * @brief Initializes an AVDES context. + * + * @param d pointer to a AVDES structure to initialize + * @param key pointer to the key to use + * @param key_bits must be 64 or 192 + * @param decrypt 0 for encryption/CBC-MAC, 1 for decryption + * @return zero on success, negative value otherwise + */ +int av_des_init(struct AVDES *d, const uint8_t *key, int key_bits, int decrypt); + +/** + * @brief Encrypts / decrypts using the DES algorithm. + * + * @param d pointer to the AVDES structure + * @param dst destination array, can be equal to src, must be 8-byte aligned + * @param src source array, can be equal to dst, must be 8-byte aligned, may be NULL + * @param count number of 8 byte blocks + * @param iv initialization vector for CBC mode, if NULL then ECB will be used, + * must be 8-byte aligned + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_des_crypt(struct AVDES *d, uint8_t *dst, const uint8_t *src, int count, uint8_t *iv, int decrypt); + +/** + * @brief Calculates CBC-MAC using the DES algorithm. + * + * @param d pointer to the AVDES structure + * @param dst destination array, can be equal to src, must be 8-byte aligned + * @param src source array, can be equal to dst, must be 8-byte aligned, may be NULL + * @param count number of 8 byte blocks + */ +void av_des_mac(struct AVDES *d, uint8_t *dst, const uint8_t *src, int count); + +/** + * @} + */ + +#endif /* AVUTIL_DES_H */ diff --git a/ffmpeg-n8.1/include/libavutil/detection_bbox.h b/ffmpeg-n8.1/include/libavutil/detection_bbox.h new file mode 100644 index 00000000..01198805 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/detection_bbox.h @@ -0,0 +1,108 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_DETECTION_BBOX_H +#define AVUTIL_DETECTION_BBOX_H + +#include "rational.h" +#include "avassert.h" +#include "frame.h" + +typedef struct AVDetectionBBox { + /** + * Distance in pixels from the left/top edge of the frame, + * together with width and height, defining the bounding box. + */ + int x; + int y; + int w; + int h; + +#define AV_DETECTION_BBOX_LABEL_NAME_MAX_SIZE 64 + + /** + * Detect result with confidence + */ + char detect_label[AV_DETECTION_BBOX_LABEL_NAME_MAX_SIZE]; + AVRational detect_confidence; + + /** + * At most 4 classifications based on the detected bounding box. + * For example, we can get max 4 different attributes with 4 different + * DNN models on one bounding box. + * classify_count is zero if no classification. + */ +#define AV_NUM_DETECTION_BBOX_CLASSIFY 4 + uint32_t classify_count; + char classify_labels[AV_NUM_DETECTION_BBOX_CLASSIFY][AV_DETECTION_BBOX_LABEL_NAME_MAX_SIZE]; + AVRational classify_confidences[AV_NUM_DETECTION_BBOX_CLASSIFY]; +} AVDetectionBBox; + +typedef struct AVDetectionBBoxHeader { + /** + * Information about how the bounding box is generated. + * for example, the DNN model name. + */ + char source[256]; + + /** + * Number of bounding boxes in the array. + */ + uint32_t nb_bboxes; + + /** + * Offset in bytes from the beginning of this structure at which + * the array of bounding boxes starts. + */ + size_t bboxes_offset; + + /** + * Size of each bounding box in bytes. + */ + size_t bbox_size; +} AVDetectionBBoxHeader; + +/* + * Get the bounding box at the specified {@code idx}. Must be between 0 and nb_bboxes. + */ +static av_always_inline AVDetectionBBox * +av_get_detection_bbox(const AVDetectionBBoxHeader *header, unsigned int idx) +{ + av_assert0(idx < header->nb_bboxes); + return (AVDetectionBBox *)((uint8_t *)header + header->bboxes_offset + + idx * header->bbox_size); +} + +/** + * Allocates memory for AVDetectionBBoxHeader, plus an array of {@code nb_bboxes} + * AVDetectionBBox, and initializes the variables. + * Can be freed with a normal av_free() call. + * + * @param nb_bboxes number of AVDetectionBBox structures to allocate + * @param out_size if non-NULL, the size in bytes of the resulting data array is + * written here. + */ +AVDetectionBBoxHeader *av_detection_bbox_alloc(uint32_t nb_bboxes, size_t *out_size); + +/** + * Allocates memory for AVDetectionBBoxHeader, plus an array of {@code nb_bboxes} + * AVDetectionBBox, in the given AVFrame {@code frame} as AVFrameSideData of type + * AV_FRAME_DATA_DETECTION_BBOXES and initializes the variables. + */ +AVDetectionBBoxHeader *av_detection_bbox_create_side_data(AVFrame *frame, uint32_t nb_bboxes); +#endif diff --git a/ffmpeg-n8.1/include/libavutil/dict.h b/ffmpeg-n8.1/include/libavutil/dict.h new file mode 100644 index 00000000..93c7cbf1 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/dict.h @@ -0,0 +1,242 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * Public dictionary API. + * @deprecated + * AVDictionary is provided for compatibility with libav. It is both in + * implementation as well as API inefficient. It does not scale and is + * extremely slow with large dictionaries. + * It is recommended that new code uses our tree container from tree.c/h + * where applicable, which uses AVL trees to achieve O(log n) performance. + */ + +#ifndef AVUTIL_DICT_H +#define AVUTIL_DICT_H + +#include + +/** + * @addtogroup lavu_dict AVDictionary + * @ingroup lavu_data + * + * @brief Simple key:value store + * + * @{ + * Dictionaries are used for storing key-value pairs. + * + * - To **create an AVDictionary**, simply pass an address of a NULL + * pointer to av_dict_set(). NULL can be used as an empty dictionary + * wherever a pointer to an AVDictionary is required. + * - To **insert an entry**, use av_dict_set(). + * - Use av_dict_get() to **retrieve an entry**. + * - To **iterate over all entries**, use av_dict_iterate(). + * - In order to **free the dictionary and all its contents**, use av_dict_free(). + * + @code + AVDictionary *d = NULL; // "create" an empty dictionary + AVDictionaryEntry *t = NULL; + + av_dict_set(&d, "foo", "bar", 0); // add an entry + + char *k = av_strdup("key"); // if your strings are already allocated, + char *v = av_strdup("value"); // you can avoid copying them like this + av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL); + + while ((t = av_dict_iterate(d, t))) { + <....> // iterate over all entries in d + } + av_dict_free(&d); + @endcode + */ + +/** + * @name AVDictionary Flags + * Flags that influence behavior of the matching of keys or insertion to the dictionary. + * @{ + */ +#define AV_DICT_MATCH_CASE 1 /**< Only get an entry with exact-case key match. Only relevant in av_dict_get(). */ +#define AV_DICT_IGNORE_SUFFIX 2 /**< Return first entry in a dictionary whose first part corresponds to the search key, + ignoring the suffix of the found key string. Only relevant in av_dict_get(). */ +#define AV_DICT_DONT_STRDUP_KEY 4 /**< Take ownership of a key that's been + allocated with av_malloc() or another memory allocation function. */ +#define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been + allocated with av_malloc() or another memory allocation function. */ +#define AV_DICT_DONT_OVERWRITE 16 /**< Don't overwrite existing entries. */ +#define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no + delimiter is added, the strings are simply concatenated. */ +#define AV_DICT_MULTIKEY 64 /**< Allow to store several equal keys in the dictionary */ +#define AV_DICT_DEDUP 128 /**< If inserting a value that already exists for a key, do nothing. Only relevant with AV_DICT_MULTIKEY. */ +/** + * @} + */ + +typedef struct AVDictionaryEntry { + char *key; + char *value; +} AVDictionaryEntry; + +typedef struct AVDictionary AVDictionary; + +/** + * Get a dictionary entry with matching key. + * + * The returned entry key or value must not be changed, or it will + * cause undefined behavior. + * + * @param prev Set to the previous matching element to find the next. + * If set to NULL the first matching element is returned. + * @param key Matching key + * @param flags A collection of AV_DICT_* flags controlling how the + * entry is retrieved + * + * @return Found entry or NULL in case no matching entry was found in the dictionary + */ +AVDictionaryEntry *av_dict_get(const AVDictionary *m, const char *key, + const AVDictionaryEntry *prev, int flags); + +/** + * Iterate over a dictionary + * + * Iterates through all entries in the dictionary. + * + * @warning The returned AVDictionaryEntry key/value must not be changed. + * + * @warning As av_dict_set() invalidates all previous entries returned + * by this function, it must not be called while iterating over the dict. + * + * Typical usage: + * @code + * const AVDictionaryEntry *e = NULL; + * while ((e = av_dict_iterate(m, e))) { + * // ... + * } + * @endcode + * + * @param m The dictionary to iterate over + * @param prev Pointer to the previous AVDictionaryEntry, NULL initially + * + * @retval AVDictionaryEntry* The next element in the dictionary + * @retval NULL No more elements in the dictionary + */ +const AVDictionaryEntry *av_dict_iterate(const AVDictionary *m, + const AVDictionaryEntry *prev); + +/** + * Get number of entries in dictionary. + * + * @param m dictionary + * @return number of entries in dictionary + */ +int av_dict_count(const AVDictionary *m); + +/** + * Set the given entry in *pm, overwriting an existing entry. + * + * Note: If AV_DICT_DONT_STRDUP_KEY or AV_DICT_DONT_STRDUP_VAL is set, + * these arguments will be freed on error. + * + * @warning Adding a new entry to a dictionary invalidates all existing entries + * previously returned with av_dict_get() or av_dict_iterate(). + * + * @param pm Pointer to a pointer to a dictionary struct. If *pm is NULL + * a dictionary struct is allocated and put in *pm. + * @param key Entry key to add to *pm (will either be av_strduped or added as a new key depending on flags) + * @param value Entry value to add to *pm (will be av_strduped or added as a new key depending on flags). + * Passing a NULL value will cause an existing entry to be deleted. + * + * @return >= 0 on success otherwise an error code <0 + */ +int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags); + +/** + * Convenience wrapper for av_dict_set() that converts the value to a string + * and stores it. + * + * Note: If ::AV_DICT_DONT_STRDUP_KEY is set, key will be freed on error. + */ +int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags); + +/** + * Parse the key/value pairs list and add the parsed entries to a dictionary. + * + * In case of failure, all the successfully set entries are stored in + * *pm. You may need to manually free the created dictionary. + * + * @param key_val_sep A 0-terminated list of characters used to separate + * key from value + * @param pairs_sep A 0-terminated list of characters used to separate + * two pairs from each other + * @param flags Flags to use when adding to the dictionary. + * ::AV_DICT_DONT_STRDUP_KEY and ::AV_DICT_DONT_STRDUP_VAL + * are ignored since the key/value tokens will always + * be duplicated. + * + * @return 0 on success, negative AVERROR code on failure + */ +int av_dict_parse_string(AVDictionary **pm, const char *str, + const char *key_val_sep, const char *pairs_sep, + int flags); + +/** + * Copy entries from one AVDictionary struct into another. + * + * @note Metadata is read using the ::AV_DICT_IGNORE_SUFFIX flag + * + * @param dst Pointer to a pointer to a AVDictionary struct to copy into. If *dst is NULL, + * this function will allocate a struct for you and put it in *dst + * @param src Pointer to the source AVDictionary struct to copy items from. + * @param flags Flags to use when setting entries in *dst + * + * @return 0 on success, negative AVERROR code on failure. If dst was allocated + * by this function, callers should free the associated memory. + */ +int av_dict_copy(AVDictionary **dst, const AVDictionary *src, int flags); + +/** + * Free all the memory allocated for an AVDictionary struct + * and all keys and values. + */ +void av_dict_free(AVDictionary **m); + +/** + * Get dictionary entries as a string. + * + * Create a string containing dictionary's entries. + * Such string may be passed back to av_dict_parse_string(). + * @note String is escaped with backslashes ('\'). + * + * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same. + * + * @param[in] m The dictionary + * @param[out] buffer Pointer to buffer that will be allocated with string containing entries. + * Buffer must be freed by the caller when is no longer needed. + * @param[in] key_val_sep Character used to separate key from value + * @param[in] pairs_sep Character used to separate two pairs from each other + * + * @return >= 0 on success, negative on error + */ +int av_dict_get_string(const AVDictionary *m, char **buffer, + const char key_val_sep, const char pairs_sep); + +/** + * @} + */ + +#endif /* AVUTIL_DICT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/display.h b/ffmpeg-n8.1/include/libavutil/display.h new file mode 100644 index 00000000..50f2b44c --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/display.h @@ -0,0 +1,109 @@ +/* + * Copyright (c) 2014 Vittorio Giovara + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_video_display + * Display matrix + */ + +#ifndef AVUTIL_DISPLAY_H +#define AVUTIL_DISPLAY_H + +#include + +/** + * @defgroup lavu_video_display Display transformation matrix functions + * @ingroup lavu_video + * + * The display transformation matrix specifies an affine transformation that + * should be applied to video frames for correct presentation. It is compatible + * with the matrices stored in the ISO/IEC 14496-12 container format. + * + * The data is a 3x3 matrix represented as a 9-element array: + * + * @code{.unparsed} + * | a b u | + * (a, b, u, c, d, v, x, y, w) -> | c d v | + * | x y w | + * @endcode + * + * All numbers are stored in native endianness, as 16.16 fixed-point values, + * except for u, v and w, which are stored as 2.30 fixed-point values. + * + * The transformation maps a point (p, q) in the source (pre-transformation) + * frame to the point (p', q') in the destination (post-transformation) frame as + * follows: + * + * @code{.unparsed} + * | a b u | + * (p, q, 1) . | c d v | = z * (p', q', 1) + * | x y w | + * @endcode + * + * The transformation can also be more explicitly written in components as + * follows: + * + * @code{.unparsed} + * p' = (a * p + c * q + x) / z; + * q' = (b * p + d * q + y) / z; + * z = u * p + v * q + w + * @endcode + * + * @{ + */ + +/** + * Extract the rotation component of the transformation matrix. + * + * @param matrix the transformation matrix + * @return the angle (in degrees) by which the transformation rotates the frame + * counterclockwise. The angle will be in range [-180.0, 180.0], + * or NaN if the matrix is singular. + * + * @note floating point numbers are inherently inexact, so callers are + * recommended to round the return value to nearest integer before use. + */ +double av_display_rotation_get(const int32_t matrix[9]); + +/** + * Initialize a transformation matrix describing a pure clockwise + * rotation by the specified angle (in degrees). + * + * @param[out] matrix a transformation matrix (will be fully overwritten + * by this function) + * @param angle rotation angle in degrees. + */ +void av_display_rotation_set(int32_t matrix[9], double angle); + +/** + * Flip the input matrix horizontally and/or vertically. + * + * @param[in,out] matrix a transformation matrix + * @param hflip whether the matrix should be flipped horizontally + * @param vflip whether the matrix should be flipped vertically + */ +void av_display_matrix_flip(int32_t matrix[9], int hflip, int vflip); + +/** + * @} + */ + +#endif /* AVUTIL_DISPLAY_H */ diff --git a/ffmpeg-n8.1/include/libavutil/dovi_meta.h b/ffmpeg-n8.1/include/libavutil/dovi_meta.h new file mode 100644 index 00000000..c102bf38 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/dovi_meta.h @@ -0,0 +1,408 @@ +/* + * Copyright (c) 2020 Vacing Fang + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * DOVI configuration + */ + + +#ifndef AVUTIL_DOVI_META_H +#define AVUTIL_DOVI_META_H + +#include +#include + +#include "rational.h" +#include "csp.h" + +/* + * DOVI configuration + * ref: dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2 + dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2 + * @code + * uint8_t dv_version_major, the major version number that the stream complies with + * uint8_t dv_version_minor, the minor version number that the stream complies with + * uint8_t dv_profile, the Dolby Vision profile + * uint8_t dv_level, the Dolby Vision level + * uint8_t rpu_present_flag + * uint8_t el_present_flag + * uint8_t bl_present_flag + * uint8_t dv_bl_signal_compatibility_id + * uint8_t dv_md_compression, the compression method in use + * @endcode + * + * @note The struct must be allocated with av_dovi_alloc() and + * its size is not a part of the public ABI. + */ +typedef struct AVDOVIDecoderConfigurationRecord { + uint8_t dv_version_major; + uint8_t dv_version_minor; + uint8_t dv_profile; + uint8_t dv_level; + uint8_t rpu_present_flag; + uint8_t el_present_flag; + uint8_t bl_present_flag; + uint8_t dv_bl_signal_compatibility_id; + uint8_t dv_md_compression; +} AVDOVIDecoderConfigurationRecord; + +enum AVDOVICompression { + AV_DOVI_COMPRESSION_NONE = 0, + AV_DOVI_COMPRESSION_LIMITED = 1, + AV_DOVI_COMPRESSION_RESERVED = 2, + AV_DOVI_COMPRESSION_EXTENDED = 3, +}; + +/** + * Allocate a AVDOVIDecoderConfigurationRecord structure and initialize its + * fields to default values. + * + * @return the newly allocated struct or NULL on failure + */ +AVDOVIDecoderConfigurationRecord *av_dovi_alloc(size_t *size); + +/** + * Dolby Vision RPU data header. + * + * @note sizeof(AVDOVIRpuDataHeader) is not part of the public ABI. + */ +typedef struct AVDOVIRpuDataHeader { + uint8_t rpu_type; + uint16_t rpu_format; + uint8_t vdr_rpu_profile; + uint8_t vdr_rpu_level; + uint8_t chroma_resampling_explicit_filter_flag; + uint8_t coef_data_type; /* informative, lavc always converts to fixed */ + uint8_t coef_log2_denom; + uint8_t vdr_rpu_normalized_idc; + uint8_t bl_video_full_range_flag; + uint8_t bl_bit_depth; /* [8, 16] */ + uint8_t el_bit_depth; /* [8, 16] */ + uint8_t vdr_bit_depth; /* [8, 16] */ + uint8_t spatial_resampling_filter_flag; + uint8_t el_spatial_resampling_filter_flag; + uint8_t disable_residual_flag; + uint8_t ext_mapping_idc_0_4; /* extended base layer inverse mapping indicator */ + uint8_t ext_mapping_idc_5_7; /* reserved */ +} AVDOVIRpuDataHeader; + +enum AVDOVIMappingMethod { + AV_DOVI_MAPPING_POLYNOMIAL = 0, + AV_DOVI_MAPPING_MMR = 1, +}; + +/** + * Coefficients of a piece-wise function. The pieces of the function span the + * value ranges between two adjacent pivot values. + */ +#define AV_DOVI_MAX_PIECES 8 +typedef struct AVDOVIReshapingCurve { + uint8_t num_pivots; /* [2, 9] */ + uint16_t pivots[AV_DOVI_MAX_PIECES + 1]; /* sorted ascending */ + enum AVDOVIMappingMethod mapping_idc[AV_DOVI_MAX_PIECES]; + /* AV_DOVI_MAPPING_POLYNOMIAL */ + uint8_t poly_order[AV_DOVI_MAX_PIECES]; /* [1, 2] */ + int64_t poly_coef[AV_DOVI_MAX_PIECES][3]; /* x^0, x^1, x^2 */ + /* AV_DOVI_MAPPING_MMR */ + uint8_t mmr_order[AV_DOVI_MAX_PIECES]; /* [1, 3] */ + int64_t mmr_constant[AV_DOVI_MAX_PIECES]; + int64_t mmr_coef[AV_DOVI_MAX_PIECES][3/* order - 1 */][7]; +} AVDOVIReshapingCurve; + +enum AVDOVINLQMethod { + AV_DOVI_NLQ_NONE = -1, + AV_DOVI_NLQ_LINEAR_DZ = 0, +}; + +/** + * Coefficients of the non-linear inverse quantization. For the interpretation + * of these, see ETSI GS CCM 001. + */ +typedef struct AVDOVINLQParams { + uint16_t nlq_offset; + uint64_t vdr_in_max; + /* AV_DOVI_NLQ_LINEAR_DZ */ + uint64_t linear_deadzone_slope; + uint64_t linear_deadzone_threshold; +} AVDOVINLQParams; + +/** + * Dolby Vision RPU data mapping parameters. + * + * @note sizeof(AVDOVIDataMapping) is not part of the public ABI. + */ +typedef struct AVDOVIDataMapping { + uint8_t vdr_rpu_id; + uint8_t mapping_color_space; + uint8_t mapping_chroma_format_idc; + AVDOVIReshapingCurve curves[3]; /* per component */ + + /* Non-linear inverse quantization */ + enum AVDOVINLQMethod nlq_method_idc; + uint32_t num_x_partitions; + uint32_t num_y_partitions; + AVDOVINLQParams nlq[3]; /* per component */ + uint16_t nlq_pivots[2]; +} AVDOVIDataMapping; + +/** + * Dolby Vision RPU colorspace metadata parameters. + * + * @note sizeof(AVDOVIColorMetadata) is not part of the public ABI. + */ +typedef struct AVDOVIColorMetadata { + uint8_t dm_metadata_id; + uint8_t scene_refresh_flag; + + /** + * Coefficients of the custom Dolby Vision IPT-PQ matrices. These are to be + * used instead of the matrices indicated by the frame's colorspace tags. + * The output of rgb_to_lms_matrix is to be fed into a BT.2020 LMS->RGB + * matrix based on a Hunt-Pointer-Estevez transform, but without any + * crosstalk. (See the definition of the ICtCp colorspace for more + * information.) + */ + AVRational ycc_to_rgb_matrix[9]; /* before PQ linearization */ + AVRational ycc_to_rgb_offset[3]; /* input offset of neutral value */ + AVRational rgb_to_lms_matrix[9]; /* after PQ linearization */ + + /** + * Extra signal metadata (see Dolby patents for more info). + */ + uint16_t signal_eotf; + uint16_t signal_eotf_param0; + uint16_t signal_eotf_param1; + uint32_t signal_eotf_param2; + uint8_t signal_bit_depth; + uint8_t signal_color_space; + uint8_t signal_chroma_format; + uint8_t signal_full_range_flag; /* [0, 3] */ + uint16_t source_min_pq; + uint16_t source_max_pq; + uint16_t source_diagonal; +} AVDOVIColorMetadata; + +typedef struct AVDOVIDmLevel1 { + /* Per-frame brightness metadata */ + uint16_t min_pq; + uint16_t max_pq; + uint16_t avg_pq; +} AVDOVIDmLevel1; + +typedef struct AVDOVIDmLevel2 { + /* Usually derived from level 8 (at different levels) */ + uint16_t target_max_pq; + uint16_t trim_slope; + uint16_t trim_offset; + uint16_t trim_power; + uint16_t trim_chroma_weight; + uint16_t trim_saturation_gain; + int16_t ms_weight; +} AVDOVIDmLevel2; + +typedef struct AVDOVIDmLevel3 { + uint16_t min_pq_offset; + uint16_t max_pq_offset; + uint16_t avg_pq_offset; +} AVDOVIDmLevel3; + +typedef struct AVDOVIDmLevel4 { + uint16_t anchor_pq; + uint16_t anchor_power; +} AVDOVIDmLevel4; + +typedef struct AVDOVIDmLevel5 { + /* Active area definition */ + uint16_t left_offset; + uint16_t right_offset; + uint16_t top_offset; + uint16_t bottom_offset; +} AVDOVIDmLevel5; + +typedef struct AVDOVIDmLevel6 { + /* Static HDR10 metadata */ + uint16_t max_luminance; + uint16_t min_luminance; + uint16_t max_cll; + uint16_t max_fall; +} AVDOVIDmLevel6; + +typedef struct AVDOVIDmLevel8 { + /* Extended version of level 2 */ + uint8_t target_display_index; + uint16_t trim_slope; + uint16_t trim_offset; + uint16_t trim_power; + uint16_t trim_chroma_weight; + uint16_t trim_saturation_gain; + uint16_t ms_weight; + uint16_t target_mid_contrast; + uint16_t clip_trim; + uint8_t saturation_vector_field[6]; + uint8_t hue_vector_field[6]; +} AVDOVIDmLevel8; + +typedef struct AVDOVIDmLevel9 { + /* Source display characteristics */ + uint8_t source_primary_index; + AVColorPrimariesDesc source_display_primaries; +} AVDOVIDmLevel9; + +typedef struct AVDOVIDmLevel10 { + /* Target display characteristics */ + uint8_t target_display_index; + uint16_t target_max_pq; + uint16_t target_min_pq; + uint8_t target_primary_index; + AVColorPrimariesDesc target_display_primaries; +} AVDOVIDmLevel10; + +typedef struct AVDOVIDmLevel11 { + uint8_t content_type; + uint8_t whitepoint; + uint8_t reference_mode_flag; +#if FF_API_DOVI_L11_INVALID_PROPS + attribute_deprecated + uint8_t sharpness; + attribute_deprecated + uint8_t noise_reduction; + attribute_deprecated + uint8_t mpeg_noise_reduction; + attribute_deprecated + uint8_t frame_rate_conversion; + attribute_deprecated + uint8_t brightness; + attribute_deprecated + uint8_t color; +#endif +} AVDOVIDmLevel11; + +typedef struct AVDOVIDmLevel254 { + /* DMv2 info block, always present in samples with DMv2 metadata */ + uint8_t dm_mode; + uint8_t dm_version_index; +} AVDOVIDmLevel254; + +typedef struct AVDOVIDmLevel255 { + /* Debug block, not really used in samples */ + uint8_t dm_run_mode; + uint8_t dm_run_version; + uint8_t dm_debug[4]; +} AVDOVIDmLevel255; + +/** + * Dolby Vision metadata extension block. Dynamic extension blocks may change + * from frame to frame, while static blocks are constant throughout the entire + * sequence. + * + * @note sizeof(AVDOVIDmData) is not part of the public API. + */ +typedef struct AVDOVIDmData { + uint8_t level; /* [1, 255] */ + union { + AVDOVIDmLevel1 l1; /* dynamic */ + AVDOVIDmLevel2 l2; /* dynamic, may appear multiple times */ + AVDOVIDmLevel3 l3; /* dynamic */ + AVDOVIDmLevel4 l4; /* dynamic */ + AVDOVIDmLevel5 l5; /* dynamic */ + AVDOVIDmLevel6 l6; /* static */ + /* level 7 is currently unused */ + AVDOVIDmLevel8 l8; /* dynamic, may appear multiple times */ + AVDOVIDmLevel9 l9; /* dynamic */ + AVDOVIDmLevel10 l10; /* static, may appear multiple times */ + AVDOVIDmLevel11 l11; /* dynamic */ + AVDOVIDmLevel254 l254; /* static */ + AVDOVIDmLevel255 l255; /* static */ + }; +} AVDOVIDmData; + +/** + * Combined struct representing a combination of header, mapping and color + * metadata, for attaching to frames as side data. + * + * @note The struct must be allocated with av_dovi_metadata_alloc() and + * its size is not a part of the public ABI. + */ + +typedef struct AVDOVIMetadata { + /** + * Offset in bytes from the beginning of this structure at which the + * respective structs start. + */ + size_t header_offset; /* AVDOVIRpuDataHeader */ + size_t mapping_offset; /* AVDOVIDataMapping */ + size_t color_offset; /* AVDOVIColorMetadata */ + + size_t ext_block_offset; /* offset to start of ext blocks array */ + size_t ext_block_size; /* size per element */ + int num_ext_blocks; /* number of extension blocks */ + + /* static limit on num_ext_blocks, derived from bitstream limitations */ +#define AV_DOVI_MAX_EXT_BLOCKS 32 +} AVDOVIMetadata; + +static av_always_inline AVDOVIRpuDataHeader * +av_dovi_get_header(const AVDOVIMetadata *data) +{ + return (AVDOVIRpuDataHeader *)((uint8_t *) data + data->header_offset); +} + +static av_always_inline AVDOVIDataMapping * +av_dovi_get_mapping(const AVDOVIMetadata *data) +{ + return (AVDOVIDataMapping *)((uint8_t *) data + data->mapping_offset); +} + +static av_always_inline AVDOVIColorMetadata * +av_dovi_get_color(const AVDOVIMetadata *data) +{ + return (AVDOVIColorMetadata *)((uint8_t *) data + data->color_offset); +} + +/** + * Gets the specified Dolby Vision Display Management (DM) metadata + * @param index must be non negative and below data->num_ext_blocks + */ +static av_always_inline AVDOVIDmData * +av_dovi_get_ext(const AVDOVIMetadata *data, int index) +{ + return (AVDOVIDmData *)((uint8_t *) data + data->ext_block_offset + + data->ext_block_size * index); +} + +/** + * Find an extension block with a given level, or NULL. In the case of + * multiple extension blocks, only the first is returned. + */ +AVDOVIDmData *av_dovi_find_level(const AVDOVIMetadata *data, uint8_t level); + +/** + * Allocate an AVDOVIMetadata structure and initialize its + * fields to default values. + * + * @param size If this parameter is non-NULL, the size in bytes of the + * allocated struct will be written here on success + * + * @return the newly allocated struct or NULL on failure + */ +AVDOVIMetadata *av_dovi_metadata_alloc(size_t *size); + +#endif /* AVUTIL_DOVI_META_H */ diff --git a/ffmpeg-n8.1/include/libavutil/downmix_info.h b/ffmpeg-n8.1/include/libavutil/downmix_info.h new file mode 100644 index 00000000..221cf5bf --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/downmix_info.h @@ -0,0 +1,115 @@ +/* + * Copyright (c) 2014 Tim Walker + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_DOWNMIX_INFO_H +#define AVUTIL_DOWNMIX_INFO_H + +#include "frame.h" + +/** + * @file + * audio downmix medatata + */ + +/** + * @addtogroup lavu_audio + * @{ + */ + +/** + * @defgroup downmix_info Audio downmix metadata + * @{ + */ + +/** + * Possible downmix types. + */ +enum AVDownmixType { + AV_DOWNMIX_TYPE_UNKNOWN, /**< Not indicated. */ + AV_DOWNMIX_TYPE_LORO, /**< Lo/Ro 2-channel downmix (Stereo). */ + AV_DOWNMIX_TYPE_LTRT, /**< Lt/Rt 2-channel downmix, Dolby Surround compatible. */ + AV_DOWNMIX_TYPE_DPLII, /**< Lt/Rt 2-channel downmix, Dolby Pro Logic II compatible. */ + AV_DOWNMIX_TYPE_NB /**< Number of downmix types. Not part of ABI. */ +}; + +/** + * This structure describes optional metadata relevant to a downmix procedure. + * + * All fields are set by the decoder to the value indicated in the audio + * bitstream (if present), or to a "sane" default otherwise. + */ +typedef struct AVDownmixInfo { + /** + * Type of downmix preferred by the mastering engineer. + */ + enum AVDownmixType preferred_downmix_type; + + /** + * Absolute scale factor representing the nominal level of the center + * channel during a regular downmix. + */ + double center_mix_level; + + /** + * Absolute scale factor representing the nominal level of the center + * channel during an Lt/Rt compatible downmix. + */ + double center_mix_level_ltrt; + + /** + * Absolute scale factor representing the nominal level of the surround + * channels during a regular downmix. + */ + double surround_mix_level; + + /** + * Absolute scale factor representing the nominal level of the surround + * channels during an Lt/Rt compatible downmix. + */ + double surround_mix_level_ltrt; + + /** + * Absolute scale factor representing the level at which the LFE data is + * mixed into L/R channels during downmixing. + */ + double lfe_mix_level; +} AVDownmixInfo; + +/** + * Get a frame's AV_FRAME_DATA_DOWNMIX_INFO side data for editing. + * + * If the side data is absent, it is created and added to the frame. + * + * @param frame the frame for which the side data is to be obtained or created + * + * @return the AVDownmixInfo structure to be edited by the caller, or NULL if + * the structure cannot be allocated. + */ +AVDownmixInfo *av_downmix_info_update_side_data(AVFrame *frame); + +/** + * @} + */ + +/** + * @} + */ + +#endif /* AVUTIL_DOWNMIX_INFO_H */ diff --git a/ffmpeg-n8.1/include/libavutil/encryption_info.h b/ffmpeg-n8.1/include/libavutil/encryption_info.h new file mode 100644 index 00000000..8fe7ebfe --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/encryption_info.h @@ -0,0 +1,205 @@ +/** + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_ENCRYPTION_INFO_H +#define AVUTIL_ENCRYPTION_INFO_H + +#include +#include + +typedef struct AVSubsampleEncryptionInfo { + /** The number of bytes that are clear. */ + unsigned int bytes_of_clear_data; + + /** + * The number of bytes that are protected. If using pattern encryption, + * the pattern applies to only the protected bytes; if not using pattern + * encryption, all these bytes are encrypted. + */ + unsigned int bytes_of_protected_data; +} AVSubsampleEncryptionInfo; + +/** + * This describes encryption info for a packet. This contains frame-specific + * info for how to decrypt the packet before passing it to the decoder. + * + * The size of this struct is not part of the public ABI. + */ +typedef struct AVEncryptionInfo { + /** The fourcc encryption scheme, in big-endian byte order. */ + uint32_t scheme; + + /** + * Only used for pattern encryption. This is the number of 16-byte blocks + * that are encrypted. + */ + uint32_t crypt_byte_block; + + /** + * Only used for pattern encryption. This is the number of 16-byte blocks + * that are clear. + */ + uint32_t skip_byte_block; + + /** + * The ID of the key used to encrypt the packet. This should always be + * 16 bytes long, but may be changed in the future. + */ + uint8_t *key_id; + uint32_t key_id_size; + + /** + * The initialization vector. This may have been zero-filled to be the + * correct block size. This should always be 16 bytes long, but may be + * changed in the future. + */ + uint8_t *iv; + uint32_t iv_size; + + /** + * An array of subsample encryption info specifying how parts of the sample + * are encrypted. If there are no subsamples, then the whole sample is + * encrypted. + */ + AVSubsampleEncryptionInfo *subsamples; + uint32_t subsample_count; +} AVEncryptionInfo; + +/** + * This describes info used to initialize an encryption key system. + * + * The size of this struct is not part of the public ABI. + */ +typedef struct AVEncryptionInitInfo { + /** + * A unique identifier for the key system this is for, can be NULL if it + * is not known. This should always be 16 bytes, but may change in the + * future. + */ + uint8_t* system_id; + uint32_t system_id_size; + + /** + * An array of key IDs this initialization data is for. All IDs are the + * same length. Can be NULL if there are no known key IDs. + */ + uint8_t** key_ids; + /** The number of key IDs. */ + uint32_t num_key_ids; + /** + * The number of bytes in each key ID. This should always be 16, but may + * change in the future. + */ + uint32_t key_id_size; + + /** + * Key-system specific initialization data. This data is copied directly + * from the file and the format depends on the specific key system. This + * can be NULL if there is no initialization data; in that case, there + * will be at least one key ID. + */ + uint8_t* data; + uint32_t data_size; + + /** + * An optional pointer to the next initialization info in the list. + */ + struct AVEncryptionInitInfo *next; +} AVEncryptionInitInfo; + +/** + * Allocates an AVEncryptionInfo structure and sub-pointers to hold the given + * number of subsamples. This will allocate pointers for the key ID, IV, + * and subsample entries, set the size members, and zero-initialize the rest. + * + * @param subsample_count The number of subsamples. + * @param key_id_size The number of bytes in the key ID, should be 16. + * @param iv_size The number of bytes in the IV, should be 16. + * + * @return The new AVEncryptionInfo structure, or NULL on error. + */ +AVEncryptionInfo *av_encryption_info_alloc(uint32_t subsample_count, uint32_t key_id_size, uint32_t iv_size); + +/** + * Allocates an AVEncryptionInfo structure with a copy of the given data. + * @return The new AVEncryptionInfo structure, or NULL on error. + */ +AVEncryptionInfo *av_encryption_info_clone(const AVEncryptionInfo *info); + +/** + * Frees the given encryption info object. This MUST NOT be used to free the + * side-data data pointer, that should use normal side-data methods. + */ +void av_encryption_info_free(AVEncryptionInfo *info); + +/** + * Creates a copy of the AVEncryptionInfo that is contained in the given side + * data. The resulting object should be passed to av_encryption_info_free() + * when done. + * + * @return The new AVEncryptionInfo structure, or NULL on error. + */ +AVEncryptionInfo *av_encryption_info_get_side_data(const uint8_t *side_data, size_t side_data_size); + +/** + * Allocates and initializes side data that holds a copy of the given encryption + * info. The resulting pointer should be either freed using av_free or given + * to av_packet_add_side_data(). + * + * @return The new side-data pointer, or NULL. + */ +uint8_t *av_encryption_info_add_side_data( + const AVEncryptionInfo *info, size_t *side_data_size); + + +/** + * Allocates an AVEncryptionInitInfo structure and sub-pointers to hold the + * given sizes. This will allocate pointers and set all the fields. + * + * @return The new AVEncryptionInitInfo structure, or NULL on error. + */ +AVEncryptionInitInfo *av_encryption_init_info_alloc( + uint32_t system_id_size, uint32_t num_key_ids, uint32_t key_id_size, uint32_t data_size); + +/** + * Frees the given encryption init info object. This MUST NOT be used to free + * the side-data data pointer, that should use normal side-data methods. + */ +void av_encryption_init_info_free(AVEncryptionInitInfo* info); + +/** + * Creates a copy of the AVEncryptionInitInfo that is contained in the given + * side data. The resulting object should be passed to + * av_encryption_init_info_free() when done. + * + * @return The new AVEncryptionInitInfo structure, or NULL on error. + */ +AVEncryptionInitInfo *av_encryption_init_info_get_side_data( + const uint8_t* side_data, size_t side_data_size); + +/** + * Allocates and initializes side data that holds a copy of the given encryption + * init info. The resulting pointer should be either freed using av_free or + * given to av_packet_add_side_data(). + * + * @return The new side-data pointer, or NULL. + */ +uint8_t *av_encryption_init_info_add_side_data( + const AVEncryptionInitInfo *info, size_t *side_data_size); + +#endif /* AVUTIL_ENCRYPTION_INFO_H */ diff --git a/ffmpeg-n8.1/include/libavutil/error.h b/ffmpeg-n8.1/include/libavutil/error.h new file mode 100644 index 00000000..1efa86c4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/error.h @@ -0,0 +1,129 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * error code definitions + */ + +#ifndef AVUTIL_ERROR_H +#define AVUTIL_ERROR_H + +#include +#include + +#include "macros.h" + +/** + * @addtogroup lavu_error + * + * @{ + */ + + +/* error handling */ +#if EDOM > 0 +#define AVERROR(e) (-(e)) ///< Returns a negative error code from a POSIX error code, to return from library functions. +#define AVUNERROR(e) (-(e)) ///< Returns a POSIX error code from a library function error return value. +#else +/* Some platforms have E* and errno already negated. */ +#define AVERROR(e) (e) +#define AVUNERROR(e) (e) +#endif + +#define FFERRTAG(a, b, c, d) (-(int)MKTAG(a, b, c, d)) + +#define AVERROR_BSF_NOT_FOUND FFERRTAG(0xF8,'B','S','F') ///< Bitstream filter not found +#define AVERROR_BUG FFERRTAG( 'B','U','G','!') ///< Internal bug, also see AVERROR_BUG2 +#define AVERROR_BUFFER_TOO_SMALL FFERRTAG( 'B','U','F','S') ///< Buffer too small +#define AVERROR_DECODER_NOT_FOUND FFERRTAG(0xF8,'D','E','C') ///< Decoder not found +#define AVERROR_DEMUXER_NOT_FOUND FFERRTAG(0xF8,'D','E','M') ///< Demuxer not found +#define AVERROR_ENCODER_NOT_FOUND FFERRTAG(0xF8,'E','N','C') ///< Encoder not found +#define AVERROR_EOF FFERRTAG( 'E','O','F',' ') ///< End of file +#define AVERROR_EXIT FFERRTAG( 'E','X','I','T') ///< Immediate exit was requested; the called function should not be restarted +#define AVERROR_EXTERNAL FFERRTAG( 'E','X','T',' ') ///< Generic error in an external library +#define AVERROR_FILTER_NOT_FOUND FFERRTAG(0xF8,'F','I','L') ///< Filter not found +#define AVERROR_INVALIDDATA FFERRTAG( 'I','N','D','A') ///< Invalid data found when processing input +#define AVERROR_MUXER_NOT_FOUND FFERRTAG(0xF8,'M','U','X') ///< Muxer not found +#define AVERROR_OPTION_NOT_FOUND FFERRTAG(0xF8,'O','P','T') ///< Option not found +#define AVERROR_PATCHWELCOME FFERRTAG( 'P','A','W','E') ///< Not yet implemented in FFmpeg, patches welcome +#define AVERROR_PROTOCOL_NOT_FOUND FFERRTAG(0xF8,'P','R','O') ///< Protocol not found + +#define AVERROR_STREAM_NOT_FOUND FFERRTAG(0xF8,'S','T','R') ///< Stream not found +/** + * This is semantically identical to AVERROR_BUG + * it has been introduced in Libav after our AVERROR_BUG and with a modified value. + */ +#define AVERROR_BUG2 FFERRTAG( 'B','U','G',' ') +#define AVERROR_UNKNOWN FFERRTAG( 'U','N','K','N') ///< Unknown error, typically from an external library +#define AVERROR_EXPERIMENTAL (-0x2bb2afa8) ///< Requested feature is flagged experimental. Set strict_std_compliance if you really want to use it. +#define AVERROR_INPUT_CHANGED (-0x636e6701) ///< Input changed between calls. Reconfiguration is required. (can be OR-ed with AVERROR_OUTPUT_CHANGED) +#define AVERROR_OUTPUT_CHANGED (-0x636e6702) ///< Output changed between calls. Reconfiguration is required. (can be OR-ed with AVERROR_INPUT_CHANGED) +/* HTTP & RTSP errors */ +#define AVERROR_HTTP_BAD_REQUEST FFERRTAG(0xF8,'4','0','0') +#define AVERROR_HTTP_UNAUTHORIZED FFERRTAG(0xF8,'4','0','1') +#define AVERROR_HTTP_FORBIDDEN FFERRTAG(0xF8,'4','0','3') +#define AVERROR_HTTP_NOT_FOUND FFERRTAG(0xF8,'4','0','4') +#define AVERROR_HTTP_TOO_MANY_REQUESTS FFERRTAG(0xF8,'4','2','9') +#define AVERROR_HTTP_OTHER_4XX FFERRTAG(0xF8,'4','X','X') +#define AVERROR_HTTP_SERVER_ERROR FFERRTAG(0xF8,'5','X','X') + +#define AV_ERROR_MAX_STRING_SIZE 64 + +/** + * Put a description of the AVERROR code errnum in errbuf. + * In case of failure the global variable errno is set to indicate the + * error. Even in case of failure av_strerror() will print a generic + * error message indicating the errnum provided to errbuf. + * + * @param errnum error code to describe + * @param errbuf buffer to which description is written + * @param errbuf_size the size in bytes of errbuf + * @return 0 on success, a negative value if a description for errnum + * cannot be found + */ +int av_strerror(int errnum, char *errbuf, size_t errbuf_size); + +/** + * Fill the provided buffer with a string containing an error string + * corresponding to the AVERROR code errnum. + * + * @param errbuf a buffer + * @param errbuf_size size in bytes of errbuf + * @param errnum error code to describe + * @return the buffer in input, filled with the error description + * @see av_strerror() + */ +static inline char *av_make_error_string(char *errbuf, size_t errbuf_size, int errnum) +{ + av_strerror(errnum, errbuf, errbuf_size); + return errbuf; +} + +/** + * Convenience macro, the return value should be used only directly in + * function arguments but never stand-alone. + */ +#define av_err2str(errnum) \ + av_make_error_string((char[AV_ERROR_MAX_STRING_SIZE]){0}, AV_ERROR_MAX_STRING_SIZE, errnum) + +/** + * @} + */ + +#endif /* AVUTIL_ERROR_H */ diff --git a/ffmpeg-n8.1/include/libavutil/eval.h b/ffmpeg-n8.1/include/libavutil/eval.h new file mode 100644 index 00000000..0d3eaeb3 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/eval.h @@ -0,0 +1,140 @@ +/* + * Copyright (c) 2002 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * simple arithmetic expression evaluator + */ + +#ifndef AVUTIL_EVAL_H +#define AVUTIL_EVAL_H + +typedef struct AVExpr AVExpr; + +/** + * Parse and evaluate an expression. + * Note, this is significantly slower than av_expr_eval(). + * + * @param res a pointer to a double where is put the result value of + * the expression, or NAN in case of error + * @param s expression as a zero terminated string, for example "1+2^3+5*5+sin(2/3)" + * @param const_names NULL terminated array of zero terminated strings of constant identifiers, for example {"PI", "E", 0} + * @param const_values a zero terminated array of values for the identifiers from const_names + * @param func1_names NULL terminated array of zero terminated strings of funcs1 identifiers + * @param funcs1 NULL terminated array of function pointers for functions which take 1 argument + * @param func2_names NULL terminated array of zero terminated strings of funcs2 identifiers + * @param funcs2 NULL terminated array of function pointers for functions which take 2 arguments + * @param opaque a pointer which will be passed to all functions from funcs1 and funcs2 + * @param log_offset log level offset, can be used to silence error messages + * @param log_ctx parent logging context + * @return >= 0 in case of success, a negative value corresponding to an + * AVERROR code otherwise + */ +int av_expr_parse_and_eval(double *res, const char *s, + const char * const *const_names, const double *const_values, + const char * const *func1_names, double (* const *funcs1)(void *, double), + const char * const *func2_names, double (* const *funcs2)(void *, double, double), + void *opaque, int log_offset, void *log_ctx); + +/** + * Parse an expression. + * + * @param expr a pointer where is put an AVExpr containing the parsed + * value in case of successful parsing, or NULL otherwise. + * The pointed to AVExpr must be freed with av_expr_free() by the user + * when it is not needed anymore. + * @param s expression as a zero terminated string, for example "1+2^3+5*5+sin(2/3)" + * @param const_names NULL terminated array of zero terminated strings of constant identifiers, for example {"PI", "E", 0} + * @param func1_names NULL terminated array of zero terminated strings of funcs1 identifiers + * @param funcs1 NULL terminated array of function pointers for functions which take 1 argument + * @param func2_names NULL terminated array of zero terminated strings of funcs2 identifiers + * @param funcs2 NULL terminated array of function pointers for functions which take 2 arguments + * @param log_offset log level offset, can be used to silence error messages + * @param log_ctx parent logging context + * @return >= 0 in case of success, a negative value corresponding to an + * AVERROR code otherwise + */ +int av_expr_parse(AVExpr **expr, const char *s, + const char * const *const_names, + const char * const *func1_names, double (* const *funcs1)(void *, double), + const char * const *func2_names, double (* const *funcs2)(void *, double, double), + int log_offset, void *log_ctx); + +/** + * Evaluate a previously parsed expression. + * + * @param e the AVExpr to evaluate + * @param const_values a zero terminated array of values for the identifiers from av_expr_parse() const_names + * @param opaque a pointer which will be passed to all functions from funcs1 and funcs2 + * @return the value of the expression + */ +double av_expr_eval(AVExpr *e, const double *const_values, void *opaque); + +/** + * Track the presence of variables and their number of occurrences in a parsed expression + * + * @param e the AVExpr to track variables in + * @param counter a zero-initialized array where the count of each variable will be stored + * @param size size of array + * @return 0 on success, a negative value indicates that no expression or array was passed + * or size was zero + */ +int av_expr_count_vars(AVExpr *e, unsigned *counter, int size); + +/** + * Track the presence of user provided functions and their number of occurrences + * in a parsed expression. + * + * @param e the AVExpr to track user provided functions in + * @param counter a zero-initialized array where the count of each function will be stored + * if you passed 5 functions with 2 arguments to av_expr_parse() + * then for arg=2 this will use up to 5 entries. + * @param size size of array + * @param arg number of arguments the counted functions have + * @return 0 on success, a negative value indicates that no expression or array was passed + * or size was zero + */ +int av_expr_count_func(AVExpr *e, unsigned *counter, int size, int arg); + +/** + * Free a parsed expression previously created with av_expr_parse(). + */ +void av_expr_free(AVExpr *e); + +/** + * Parse the string in numstr and return its value as a double. If + * the string is empty, contains only whitespaces, or does not contain + * an initial substring that has the expected syntax for a + * floating-point number, no conversion is performed. In this case, + * returns a value of zero and the value returned in tail is the value + * of numstr. + * + * @param numstr a string representing a number, may contain one of + * the International System number postfixes, for example 'K', 'M', + * 'G'. If 'i' is appended after the postfix, powers of 2 are used + * instead of powers of 10. The 'B' postfix multiplies the value by + * 8, and can be appended after another postfix or used alone. This + * allows using for example 'KB', 'MiB', 'G' and 'B' as postfix. + * @param tail if non-NULL puts here the pointer to the char next + * after the last parsed character + */ +double av_strtod(const char *numstr, char **tail); + +#endif /* AVUTIL_EVAL_H */ diff --git a/ffmpeg-n8.1/include/libavutil/executor.h b/ffmpeg-n8.1/include/libavutil/executor.h new file mode 100644 index 00000000..0eb21c10 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/executor.h @@ -0,0 +1,67 @@ +/* + * Copyright (C) 2023 Nuo Mi + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_EXECUTOR_H +#define AVUTIL_EXECUTOR_H + +typedef struct AVExecutor AVExecutor; +typedef struct AVTask AVTask; + +struct AVTask { + AVTask *next; +}; + +typedef struct AVTaskCallbacks { + void *user_data; + + int local_context_size; + + // return 1 if a's priority > b's priority + int (*priority_higher)(const AVTask *a, const AVTask *b); + + // task is ready for run + int (*ready)(const AVTask *t, void *user_data); + + // run the task + int (*run)(AVTask *t, void *local_context, void *user_data); +} AVTaskCallbacks; + +/** + * Alloc executor + * @param callbacks callback structure for executor + * @param thread_count worker thread number, 0 for run on caller's thread directly + * @return return the executor + */ +AVExecutor* av_executor_alloc(const AVTaskCallbacks *callbacks, int thread_count); + +/** + * Free executor + * @param e pointer to executor + */ +void av_executor_free(AVExecutor **e); + +/** + * Add task to executor + * @param e pointer to executor + * @param t pointer to task. If NULL, it will wakeup one work thread + */ +void av_executor_execute(AVExecutor *e, AVTask *t); + +#endif //AVUTIL_EXECUTOR_H diff --git a/ffmpeg-n8.1/include/libavutil/ffversion.h b/ffmpeg-n8.1/include/libavutil/ffversion.h new file mode 100644 index 00000000..f7a72b1c --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/ffversion.h @@ -0,0 +1,5 @@ +/* Automatically generated by version.sh, do not manually edit! */ +#ifndef AVUTIL_FFVERSION_H +#define AVUTIL_FFVERSION_H +#define FFMPEG_VERSION "n8.1-7-ga3475e2554-20260414" +#endif /* AVUTIL_FFVERSION_H */ diff --git a/ffmpeg-n8.1/include/libavutil/fifo.h b/ffmpeg-n8.1/include/libavutil/fifo.h new file mode 100644 index 00000000..f2206c35 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/fifo.h @@ -0,0 +1,242 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_fifo + * A generic FIFO API + */ + +#ifndef AVUTIL_FIFO_H +#define AVUTIL_FIFO_H + +#include + +/** + * @defgroup lavu_fifo AVFifo + * @ingroup lavu_data + * + * @{ + * A generic FIFO API + */ + +typedef struct AVFifo AVFifo; + +/** + * Callback for writing or reading from a FIFO, passed to (and invoked from) the + * av_fifo_*_cb() functions. It may be invoked multiple times from a single + * av_fifo_*_cb() call and may process less data than the maximum size indicated + * by nb_elems. + * + * @param opaque the opaque pointer provided to the av_fifo_*_cb() function + * @param buf the buffer for reading or writing the data, depending on which + * av_fifo_*_cb function is called + * @param nb_elems On entry contains the maximum number of elements that can be + * read from / written into buf. On success, the callback should + * update it to contain the number of elements actually written. + * + * @return 0 on success, a negative error code on failure (will be returned from + * the invoking av_fifo_*_cb() function) + */ +typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems); + +/** + * Automatically resize the FIFO on writes, so that the data fits. This + * automatic resizing happens up to a limit that can be modified with + * av_fifo_auto_grow_limit(). + */ +#define AV_FIFO_FLAG_AUTO_GROW (1 << 0) + +/** + * Allocate and initialize an AVFifo with a given element size. + * + * @param elems initial number of elements that can be stored in the FIFO + * @param elem_size Size in bytes of a single element. Further operations on + * the returned FIFO will implicitly use this element size. + * @param flags a combination of AV_FIFO_FLAG_* + * + * @return newly-allocated AVFifo on success, a negative error code on failure + */ +AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size, + unsigned int flags); + +/** + * @return Element size for FIFO operations. This element size is set at + * FIFO allocation and remains constant during its lifetime + */ +size_t av_fifo_elem_size(const AVFifo *f); + +/** + * Set the maximum size (in elements) to which the FIFO can be resized + * automatically. Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used. + */ +void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems); + +/** + * @return number of elements available for reading from the given FIFO. + */ +size_t av_fifo_can_read(const AVFifo *f); + +/** + * @return Number of elements that can be written into the given FIFO without + * growing it. + * + * In other words, this number of elements or less is guaranteed to fit + * into the FIFO. More data may be written when the + * AV_FIFO_FLAG_AUTO_GROW flag was specified at FIFO creation, but this + * may involve memory allocation, which can fail. + */ +size_t av_fifo_can_write(const AVFifo *f); + +/** + * Enlarge an AVFifo. + * + * On success, the FIFO will be large enough to hold exactly + * inc + av_fifo_can_read() + av_fifo_can_write() + * elements. In case of failure, the old FIFO is kept unchanged. + * + * @param f AVFifo to resize + * @param inc number of elements to allocate for, in addition to the current + * allocated size + * @return a non-negative number on success, a negative error code on failure + */ +int av_fifo_grow2(AVFifo *f, size_t inc); + +/** + * Write data into a FIFO. + * + * In case nb_elems > av_fifo_can_write(f) and the AV_FIFO_FLAG_AUTO_GROW flag + * was not specified at FIFO creation, nothing is written and an error + * is returned. + * + * Calling function is guaranteed to succeed if nb_elems <= av_fifo_can_write(f). + * + * @param f the FIFO buffer + * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be + * read from buf on success. + * @param nb_elems number of elements to write into FIFO + * + * @return a non-negative number on success, a negative error code on failure + */ +int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems); + +/** + * Write data from a user-provided callback into a FIFO. + * + * @param f the FIFO buffer + * @param read_cb Callback supplying the data to the FIFO. May be called + * multiple times. + * @param opaque opaque user data to be provided to read_cb + * @param nb_elems Should point to the maximum number of elements that can be + * written. Will be updated to contain the number of elements + * actually written. + * + * @return non-negative number on success, a negative error code on failure + */ +int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb, + void *opaque, size_t *nb_elems); + +/** + * Read data from a FIFO. + * + * In case nb_elems > av_fifo_can_read(f), nothing is read and an error + * is returned. + * + * @param f the FIFO buffer + * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes + * will be written into buf on success. + * @param nb_elems number of elements to read from FIFO + * + * @return a non-negative number on success, a negative error code on failure + */ +int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems); + +/** + * Feed data from a FIFO into a user-provided callback. + * + * @param f the FIFO buffer + * @param write_cb Callback the data will be supplied to. May be called + * multiple times. + * @param opaque opaque user data to be provided to write_cb + * @param nb_elems Should point to the maximum number of elements that can be + * read. Will be updated to contain the total number of elements + * actually sent to the callback. + * + * @return non-negative number on success, a negative error code on failure + */ +int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb, + void *opaque, size_t *nb_elems); + +/** + * Read data from a FIFO without modifying FIFO state. + * + * Returns an error if an attempt is made to peek to nonexistent elements + * (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)). + * + * @param f the FIFO buffer + * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes + * will be written into buf. + * @param nb_elems number of elements to read from FIFO + * @param offset number of initial elements to skip. + * + * @return a non-negative number on success, a negative error code on failure + */ +int av_fifo_peek(const AVFifo *f, void *buf, size_t nb_elems, size_t offset); + +/** + * Feed data from a FIFO into a user-provided callback. + * + * @param f the FIFO buffer + * @param write_cb Callback the data will be supplied to. May be called + * multiple times. + * @param opaque opaque user data to be provided to write_cb + * @param nb_elems Should point to the maximum number of elements that can be + * read. Will be updated to contain the total number of elements + * actually sent to the callback. + * @param offset number of initial elements to skip; offset + *nb_elems must not + * be larger than av_fifo_can_read(f). + * + * @return a non-negative number on success, a negative error code on failure + */ +int av_fifo_peek_to_cb(const AVFifo *f, AVFifoCB write_cb, void *opaque, + size_t *nb_elems, size_t offset); + +/** + * Discard the specified amount of data from an AVFifo. + * @param size number of elements to discard, MUST NOT be larger than + * av_fifo_can_read(f) + */ +void av_fifo_drain2(AVFifo *f, size_t size); + +/* + * Empty the AVFifo. + * @param f AVFifo to reset + */ +void av_fifo_reset2(AVFifo *f); + +/** + * Free an AVFifo and reset pointer to NULL. + * @param f Pointer to an AVFifo to free. *f == NULL is allowed. + */ +void av_fifo_freep2(AVFifo **f); + +/** + * @} + */ + +#endif /* AVUTIL_FIFO_H */ diff --git a/ffmpeg-n8.1/include/libavutil/file.h b/ffmpeg-n8.1/include/libavutil/file.h new file mode 100644 index 00000000..fced1701 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/file.h @@ -0,0 +1,62 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_FILE_H +#define AVUTIL_FILE_H + +#include +#include + +#include "attributes.h" + +/** + * @file + * Misc file utilities. + */ + +/** + * Read the file with name filename, and put its content in a newly + * allocated buffer or map it with mmap() when available. + * In case of success set *bufptr to the read or mmapped buffer, and + * *size to the size in bytes of the buffer in *bufptr. + * Unlike mmap this function succeeds with zero sized files, in this + * case *bufptr will be set to NULL and *size will be set to 0. + * The returned buffer must be released with av_file_unmap(). + * + * @param filename path to the file + * @param[out] bufptr pointee is set to the mapped or allocated buffer + * @param[out] size pointee is set to the size in bytes of the buffer + * @param log_offset loglevel offset used for logging + * @param log_ctx context used for logging + * @return a non negative number in case of success, a negative value + * corresponding to an AVERROR error code in case of failure + */ +av_warn_unused_result +int av_file_map(const char *filename, uint8_t **bufptr, size_t *size, + int log_offset, void *log_ctx); + +/** + * Unmap or free the buffer bufptr created by av_file_map(). + * + * @param bufptr the buffer previously created with av_file_map() + * @param size size in bytes of bufptr, must be the same as returned + * by av_file_map() + */ +void av_file_unmap(uint8_t *bufptr, size_t size); + +#endif /* AVUTIL_FILE_H */ diff --git a/ffmpeg-n8.1/include/libavutil/film_grain_params.h b/ffmpeg-n8.1/include/libavutil/film_grain_params.h new file mode 100644 index 00000000..2915611c --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/film_grain_params.h @@ -0,0 +1,282 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_FILM_GRAIN_PARAMS_H +#define AVUTIL_FILM_GRAIN_PARAMS_H + +#include "frame.h" + +enum AVFilmGrainParamsType { + AV_FILM_GRAIN_PARAMS_NONE = 0, + + /** + * The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom) + */ + AV_FILM_GRAIN_PARAMS_AV1, + + /** + * The union is valid when interpreted as AVFilmGrainH274Params (codec.h274) + */ + AV_FILM_GRAIN_PARAMS_H274, +}; + +/** + * This structure describes how to handle film grain synthesis for AOM codecs. + * + * @note The struct must be allocated as part of AVFilmGrainParams using + * av_film_grain_params_alloc(). Its size is not a part of the public ABI. + */ +typedef struct AVFilmGrainAOMParams { + /** + * Number of points, and the scale and value for each point of the + * piecewise linear scaling function for the uma plane. + */ + int num_y_points; + uint8_t y_points[14][2 /* value, scaling */]; + + /** + * Signals whether to derive the chroma scaling function from the luma. + * Not equivalent to copying the luma values and scales. + */ + int chroma_scaling_from_luma; + + /** + * If chroma_scaling_from_luma is set to 0, signals the chroma scaling + * function parameters. + */ + int num_uv_points[2 /* cb, cr */]; + uint8_t uv_points[2 /* cb, cr */][10][2 /* value, scaling */]; + + /** + * Specifies the shift applied to the chroma components. For AV1, its within + * [8; 11] and determines the range and quantization of the film grain. + */ + int scaling_shift; + + /** + * Specifies the auto-regression lag. + */ + int ar_coeff_lag; + + /** + * Luma auto-regression coefficients. The number of coefficients is given by + * 2 * ar_coeff_lag * (ar_coeff_lag + 1). + */ + int8_t ar_coeffs_y[24]; + + /** + * Chroma auto-regression coefficients. The number of coefficients is given by + * 2 * ar_coeff_lag * (ar_coeff_lag + 1) + !!num_y_points. + */ + int8_t ar_coeffs_uv[2 /* cb, cr */][25]; + + /** + * Specifies the range of the auto-regressive coefficients. Values of 6, + * 7, 8 and so on represent a range of [-2, 2), [-1, 1), [-0.5, 0.5) and + * so on. For AV1 must be between 6 and 9. + */ + int ar_coeff_shift; + + /** + * Signals the down shift applied to the generated gaussian numbers during + * synthesis. + */ + int grain_scale_shift; + + /** + * Specifies the luma/chroma multipliers for the index to the component + * scaling function. + */ + int uv_mult[2 /* cb, cr */]; + int uv_mult_luma[2 /* cb, cr */]; + + /** + * Offset used for component scaling function. For AV1 its a 9-bit value + * with a range [-256, 255] + */ + int uv_offset[2 /* cb, cr */]; + + /** + * Signals whether to overlap film grain blocks. + */ + int overlap_flag; + + /** + * Signals to clip to limited color levels after film grain application. + */ + int limit_output_range; +} AVFilmGrainAOMParams; + +/** + * This structure describes how to handle film grain synthesis for codecs using + * the ITU-T H.274 Versatile supplemental enhancement information message. + * + * @note The struct must be allocated as part of AVFilmGrainParams using + * av_film_grain_params_alloc(). Its size is not a part of the public ABI. + */ +typedef struct AVFilmGrainH274Params { + /** + * Specifies the film grain simulation mode. + * 0 = Frequency filtering, 1 = Auto-regression + */ + int model_id; + + /** + * Specifies the blending mode used to blend the simulated film grain + * with the decoded images. + * + * 0 = Additive, 1 = Multiplicative + */ + int blending_mode_id; + + /** + * Specifies a scale factor used in the film grain characterization equations. + */ + int log2_scale_factor; + + /** + * Indicates if the modelling of film grain for a given component is present. + */ + int component_model_present[3 /* y, cb, cr */]; + + /** + * Specifies the number of intensity intervals for which a specific set of + * model values has been estimated, with a range of [1, 256]. + */ + uint16_t num_intensity_intervals[3 /* y, cb, cr */]; + + /** + * Specifies the number of model values present for each intensity interval + * in which the film grain has been modelled, with a range of [1, 6]. + */ + uint8_t num_model_values[3 /* y, cb, cr */]; + + /** + * Specifies the lower ounds of each intensity interval for whichthe set of + * model values applies for the component. + */ + uint8_t intensity_interval_lower_bound[3 /* y, cb, cr */][256 /* intensity interval */]; + + /** + * Specifies the upper bound of each intensity interval for which the set of + * model values applies for the component. + */ + uint8_t intensity_interval_upper_bound[3 /* y, cb, cr */][256 /* intensity interval */]; + + /** + * Specifies the model values for the component for each intensity interval. + * - When model_id == 0, the following applies: + * For comp_model_value[y], the range of values is [0, 2^bit_depth_luma - 1] + * For comp_model_value[cb..cr], the range of values is [0, 2^bit_depth_chroma - 1] + * - Otherwise, the following applies: + * For comp_model_value[y], the range of values is [-2^(bit_depth_luma - 1), 2^(bit_depth_luma - 1) - 1] + * For comp_model_value[cb..cr], the range of values is [-2^(bit_depth_chroma - 1), 2^(bit_depth_chroma - 1) - 1] + */ + int16_t comp_model_value[3 /* y, cb, cr */][256 /* intensity interval */][6 /* model value */]; +} AVFilmGrainH274Params; + +/** + * This structure describes how to handle film grain synthesis in video + * for specific codecs. Must be present on every frame where film grain is + * meant to be synthesised for correct presentation. + * + * @note The struct must be allocated with av_film_grain_params_alloc() and + * its size is not a part of the public ABI. + */ +typedef struct AVFilmGrainParams { + /** + * Specifies the codec for which this structure is valid. + */ + enum AVFilmGrainParamsType type; + + /** + * Seed to use for the synthesis process, if the codec allows for it. + * + * @note For H.264, this refers to `pic_offset` as defined in + * SMPTE RDD 5-2006. + */ + uint64_t seed; + + /** + * Intended display resolution. May be 0 if the codec does not specify + * any restrictions. + */ + + int width, height; + + /** + * Intended subsampling ratio, or 0 for luma-only streams. + */ + int subsampling_x, subsampling_y; + + /** + * Intended video signal characteristics. + */ + enum AVColorRange color_range; + enum AVColorPrimaries color_primaries; + enum AVColorTransferCharacteristic color_trc; + enum AVColorSpace color_space; + + /** + * Intended bit depth, or 0 for unknown/unspecified. + */ + int bit_depth_luma; + int bit_depth_chroma; + + /** + * Additional fields may be added both here and in any structure included. + * If a codec's film grain structure differs slightly over another + * codec's, fields within may change meaning depending on the type. + */ + union { + AVFilmGrainAOMParams aom; + AVFilmGrainH274Params h274; + } codec; +} AVFilmGrainParams; + +/** + * Allocate an AVFilmGrainParams structure and set its fields to + * default values. The resulting struct can be freed using av_freep(). + * If size is not NULL it will be set to the number of bytes allocated. + * + * @return An AVFilmGrainParams filled with default values or NULL + * on failure. + */ +AVFilmGrainParams *av_film_grain_params_alloc(size_t *size); + +/** + * Allocate a complete AVFilmGrainParams and add it to the frame. + * + * @param frame The frame which side data is added to. + * + * @return The AVFilmGrainParams structure to be filled by caller. + */ +AVFilmGrainParams *av_film_grain_params_create_side_data(AVFrame *frame); + +/** + * Select the most appropriate film grain parameters set for the frame, + * taking into account the frame's format, resolution and video signal + * characteristics. + * + * @note, for H.274, this may select a film grain parameter set with + * greater chroma resolution than the frame. Users should take care to + * correctly adjust the chroma grain frequency to the frame. + */ +const AVFilmGrainParams *av_film_grain_params_select(const AVFrame *frame); + +#endif /* AVUTIL_FILM_GRAIN_PARAMS_H */ diff --git a/ffmpeg-n8.1/include/libavutil/frame.h b/ffmpeg-n8.1/include/libavutil/frame.h new file mode 100644 index 00000000..771c9ce4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/frame.h @@ -0,0 +1,1176 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_frame + * reference-counted frame API + */ + +#ifndef AVUTIL_FRAME_H +#define AVUTIL_FRAME_H + +#include +#include + +#include "avutil.h" +#include "buffer.h" +#include "channel_layout.h" +#include "dict.h" +#include "rational.h" +#include "samplefmt.h" +#include "pixfmt.h" +#include "version.h" + + +/** + * @defgroup lavu_frame AVFrame + * @ingroup lavu_data + * + * @{ + * AVFrame is an abstraction for reference-counted raw multimedia data. + */ + +enum AVFrameSideDataType { + /** + * The data is the AVPanScan struct defined in libavcodec. + */ + AV_FRAME_DATA_PANSCAN, + /** + * ATSC A53 Part 4 Closed Captions. + * A53 CC bitstream is stored as uint8_t in AVFrameSideData.data. + * The number of bytes of CC data is AVFrameSideData.size. + */ + AV_FRAME_DATA_A53_CC, + /** + * Stereoscopic 3d metadata. + * The data is the AVStereo3D struct defined in libavutil/stereo3d.h. + */ + AV_FRAME_DATA_STEREO3D, + /** + * The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h. + */ + AV_FRAME_DATA_MATRIXENCODING, + /** + * Metadata relevant to a downmix procedure. + * The data is the AVDownmixInfo struct defined in libavutil/downmix_info.h. + */ + AV_FRAME_DATA_DOWNMIX_INFO, + /** + * ReplayGain information in the form of the AVReplayGain struct. + */ + AV_FRAME_DATA_REPLAYGAIN, + /** + * This side data contains a 3x3 transformation matrix describing an affine + * transformation that needs to be applied to the frame for correct + * presentation. + * + * See libavutil/display.h for a detailed description of the data. + */ + AV_FRAME_DATA_DISPLAYMATRIX, + /** + * Active Format Description data consisting of a single byte as specified + * in ETSI TS 101 154 using AVActiveFormatDescription enum. + */ + AV_FRAME_DATA_AFD, + /** + * Motion vectors exported by some codecs (on demand through the export_mvs + * flag set in the libavcodec AVCodecContext flags2 option). + * The data is the AVMotionVector struct defined in + * libavutil/motion_vector.h. + */ + AV_FRAME_DATA_MOTION_VECTORS, + /** + * Recommends skipping the specified number of samples. This is exported + * only if the "skip_manual" AVOption is set in libavcodec. + * This has the same format as AV_PKT_DATA_SKIP_SAMPLES. + * @code + * u32le number of samples to skip from start of this packet + * u32le number of samples to skip from end of this packet + * u8 reason for start skip + * u8 reason for end skip (0=padding silence, 1=convergence) + * @endcode + */ + AV_FRAME_DATA_SKIP_SAMPLES, + /** + * This side data must be associated with an audio frame and corresponds to + * enum AVAudioServiceType defined in avcodec.h. + */ + AV_FRAME_DATA_AUDIO_SERVICE_TYPE, + /** + * Mastering display metadata associated with a video frame. The payload is + * an AVMasteringDisplayMetadata type and contains information about the + * mastering display color volume. + */ + AV_FRAME_DATA_MASTERING_DISPLAY_METADATA, + /** + * The GOP timecode in 25 bit timecode format. Data format is 64-bit integer. + * This is set on the first frame of a GOP that has a temporal reference of 0. + */ + AV_FRAME_DATA_GOP_TIMECODE, + + /** + * The data represents the AVSphericalMapping structure defined in + * libavutil/spherical.h. + */ + AV_FRAME_DATA_SPHERICAL, + + /** + * Content light level (based on CTA-861.3). This payload contains data in + * the form of the AVContentLightMetadata struct. + */ + AV_FRAME_DATA_CONTENT_LIGHT_LEVEL, + + /** + * The data contains an ICC profile as an opaque octet buffer following the + * format described by ISO 15076-1 with an optional name defined in the + * metadata key entry "name". + */ + AV_FRAME_DATA_ICC_PROFILE, + + /** + * Timecode which conforms to SMPTE ST 12-1. The data is an array of 4 uint32_t + * where the first uint32_t describes how many (1-3) of the other timecodes are used. + * The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum() + * function in libavutil/timecode.h. + */ + AV_FRAME_DATA_S12M_TIMECODE, + + /** + * HDR dynamic metadata associated with a video frame. The payload is + * an AVDynamicHDRPlus type and contains information for color + * volume transform - application 4 of SMPTE 2094-40:2016 standard. + */ + AV_FRAME_DATA_DYNAMIC_HDR_PLUS, + + /** + * Regions Of Interest, the data is an array of AVRegionOfInterest type, the number of + * array element is implied by AVFrameSideData.size / AVRegionOfInterest.self_size. + */ + AV_FRAME_DATA_REGIONS_OF_INTEREST, + + /** + * Encoding parameters for a video frame, as described by AVVideoEncParams. + */ + AV_FRAME_DATA_VIDEO_ENC_PARAMS, + + /** + * User data unregistered metadata associated with a video frame. + * This is the H.26[45] UDU SEI message, and shouldn't be used for any other purpose + * The data is stored as uint8_t in AVFrameSideData.data which is 16 bytes of + * uuid_iso_iec_11578 followed by AVFrameSideData.size - 16 bytes of user_data_payload_byte. + */ + AV_FRAME_DATA_SEI_UNREGISTERED, + + /** + * Film grain parameters for a frame, described by AVFilmGrainParams. + * Must be present for every frame which should have film grain applied. + * + * May be present multiple times, for example when there are multiple + * alternative parameter sets for different video signal characteristics. + * The user should select the most appropriate set for the application. + */ + AV_FRAME_DATA_FILM_GRAIN_PARAMS, + + /** + * Bounding boxes for object detection and classification, + * as described by AVDetectionBBoxHeader. + */ + AV_FRAME_DATA_DETECTION_BBOXES, + + /** + * Dolby Vision RPU raw data, suitable for passing to x265 + * or other libraries. Array of uint8_t, with NAL emulation + * bytes intact. + */ + AV_FRAME_DATA_DOVI_RPU_BUFFER, + + /** + * Parsed Dolby Vision metadata, suitable for passing to a software + * implementation. The payload is the AVDOVIMetadata struct defined in + * libavutil/dovi_meta.h. + */ + AV_FRAME_DATA_DOVI_METADATA, + + /** + * HDR Vivid dynamic metadata associated with a video frame. The payload is + * an AVDynamicHDRVivid type and contains information for color + * volume transform - CUVA 005.1-2021. + */ + AV_FRAME_DATA_DYNAMIC_HDR_VIVID, + + /** + * Ambient viewing environment metadata, as defined by H.274. + */ + AV_FRAME_DATA_AMBIENT_VIEWING_ENVIRONMENT, + + /** + * Provide encoder-specific hinting information about changed/unchanged + * portions of a frame. It can be used to pass information about which + * macroblocks can be skipped because they didn't change from the + * corresponding ones in the previous frame. This could be useful for + * applications which know this information in advance to speed up + * encoding. + */ + AV_FRAME_DATA_VIDEO_HINT, + + /** + * Raw LCEVC payload data, as a uint8_t array, with NAL emulation + * bytes intact. + */ + AV_FRAME_DATA_LCEVC, + + /** + * This side data must be associated with a video frame. + * The presence of this side data indicates that the video stream is + * composed of multiple views (e.g. stereoscopic 3D content, + * cf. H.264 Annex H or H.265 Annex G). + * The data is an int storing the view ID. + */ + AV_FRAME_DATA_VIEW_ID, + + /** + * This side data contains information about the reference display width(s) + * and reference viewing distance(s) as well as information about the + * corresponding reference stereo pair(s), i.e., the pair(s) of views to be + * displayed for the viewer's left and right eyes on the reference display + * at the reference viewing distance. + * The payload is the AV3DReferenceDisplaysInfo struct defined in + * libavutil/tdrdi.h. + */ + AV_FRAME_DATA_3D_REFERENCE_DISPLAYS, + + /** + * Extensible image file format metadata. The payload is a buffer containing + * EXIF metadata, starting with either 49 49 2a 00, or 4d 4d 00 2a. + */ + AV_FRAME_DATA_EXIF, +}; + +enum AVActiveFormatDescription { + AV_AFD_SAME = 8, + AV_AFD_4_3 = 9, + AV_AFD_16_9 = 10, + AV_AFD_14_9 = 11, + AV_AFD_4_3_SP_14_9 = 13, + AV_AFD_16_9_SP_14_9 = 14, + AV_AFD_SP_4_3 = 15, +}; + + +/** + * Structure to hold side data for an AVFrame. + * + * sizeof(AVFrameSideData) is not a part of the public ABI, so new fields may be added + * to the end with a minor bump. + */ +typedef struct AVFrameSideData { + enum AVFrameSideDataType type; + uint8_t *data; + size_t size; + AVDictionary *metadata; + AVBufferRef *buf; +} AVFrameSideData; + +enum AVSideDataProps { + /** + * The side data type can be used in stream-global structures. + * Side data types without this property are only meaningful on per-frame + * basis. + */ + AV_SIDE_DATA_PROP_GLOBAL = (1 << 0), + + /** + * Multiple instances of this side data type can be meaningfully present in + * a single side data array. + */ + AV_SIDE_DATA_PROP_MULTI = (1 << 1), + + /** + * Side data depends on the video dimensions. Side data with this property + * loses its meaning when rescaling or cropping the image, unless + * either recomputed or adjusted to the new resolution. + */ + AV_SIDE_DATA_PROP_SIZE_DEPENDENT = (1 << 2), + + /** + * Side data depends on the video color space. Side data with this property + * loses its meaning when changing the video color encoding, e.g. by + * adapting to a different set of primaries or transfer characteristics. + */ + AV_SIDE_DATA_PROP_COLOR_DEPENDENT = (1 << 3), + + /** + * Side data depends on the channel layout. Side data with this property + * loses its meaning when downmixing or upmixing, unless either recomputed + * or adjusted to the new layout. + */ + AV_SIDE_DATA_PROP_CHANNEL_DEPENDENT = (1 << 4), +}; + +/** + * This struct describes the properties of a side data type. Its instance + * corresponding to a given type can be obtained from av_frame_side_data_desc(). + */ +typedef struct AVSideDataDescriptor { + /** + * Human-readable side data description. + */ + const char *name; + + /** + * Side data property flags, a combination of AVSideDataProps values. + */ + unsigned props; +} AVSideDataDescriptor; + +/** + * Structure describing a single Region Of Interest. + * + * When multiple regions are defined in a single side-data block, they + * should be ordered from most to least important - some encoders are only + * capable of supporting a limited number of distinct regions, so will have + * to truncate the list. + * + * When overlapping regions are defined, the first region containing a given + * area of the frame applies. + */ +typedef struct AVRegionOfInterest { + /** + * Must be set to the size of this data structure (that is, + * sizeof(AVRegionOfInterest)). + */ + uint32_t self_size; + /** + * Distance in pixels from the top edge of the frame to the top and + * bottom edges and from the left edge of the frame to the left and + * right edges of the rectangle defining this region of interest. + * + * The constraints on a region are encoder dependent, so the region + * actually affected may be slightly larger for alignment or other + * reasons. + */ + int top; + int bottom; + int left; + int right; + /** + * Quantisation offset. + * + * Must be in the range -1 to +1. A value of zero indicates no quality + * change. A negative value asks for better quality (less quantisation), + * while a positive value asks for worse quality (greater quantisation). + * + * The range is calibrated so that the extreme values indicate the + * largest possible offset - if the rest of the frame is encoded with the + * worst possible quality, an offset of -1 indicates that this region + * should be encoded with the best possible quality anyway. Intermediate + * values are then interpolated in some codec-dependent way. + * + * For example, in 10-bit H.264 the quantisation parameter varies between + * -12 and 51. A typical qoffset value of -1/10 therefore indicates that + * this region should be encoded with a QP around one-tenth of the full + * range better than the rest of the frame. So, if most of the frame + * were to be encoded with a QP of around 30, this region would get a QP + * of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). + * An extreme value of -1 would indicate that this region should be + * encoded with the best possible quality regardless of the treatment of + * the rest of the frame - that is, should be encoded at a QP of -12. + */ + AVRational qoffset; +} AVRegionOfInterest; + +/** + * This structure describes decoded (raw) audio or video data. + * + * AVFrame must be allocated using av_frame_alloc(). Note that this only + * allocates the AVFrame itself, the buffers for the data must be managed + * through other means (see below). + * AVFrame must be freed with av_frame_free(). + * + * AVFrame is typically allocated once and then reused multiple times to hold + * different data (e.g. a single AVFrame to hold frames received from a + * decoder). In such a case, av_frame_unref() will free any references held by + * the frame and reset it to its original clean state before it + * is reused again. + * + * The data described by an AVFrame is usually reference counted through the + * AVBuffer API. The underlying buffer references are stored in AVFrame.buf / + * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at + * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case, + * every single data plane must be contained in one of the buffers in + * AVFrame.buf or AVFrame.extended_buf. + * There may be a single buffer for all the data, or one separate buffer for + * each plane, or anything in between. + * + * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added + * to the end with a minor bump. + * + * Fields can be accessed through AVOptions, the name string used, matches the + * C structure field name for fields accessible through AVOptions. + */ +typedef struct AVFrame { +#define AV_NUM_DATA_POINTERS 8 + /** + * pointer to the picture/channel planes. + * This might be different from the first allocated byte. For video, + * it could even point to the end of the image data. + * + * All pointers in data and extended_data must point into one of the + * AVBufferRef in buf or extended_buf. + * + * Some decoders access areas outside 0,0 - width,height, please + * see avcodec_align_dimensions2(). Some filters and swscale can read + * up to 16 bytes beyond the planes, if these filters are to be used, + * then 16 extra bytes must be allocated. + * + * NOTE: Pointers not needed by the format MUST be set to NULL. + * + * @attention In case of video, the data[] pointers can point to the + * end of image data in order to reverse line order, when used in + * combination with negative values in the linesize[] array. + */ + uint8_t *data[AV_NUM_DATA_POINTERS]; + + /** + * For video, a positive or negative value, which is typically indicating + * the size in bytes of each picture line, but it can also be: + * - the negative byte size of lines for vertical flipping + * (with data[n] pointing to the end of the data + * - a positive or negative multiple of the byte size as for accessing + * even and odd fields of a frame (possibly flipped) + * + * For audio, only linesize[0] may be set. For planar audio, each channel + * plane must be the same size. + * + * For video the linesizes should be multiples of the CPUs alignment + * preference, this is 16 or 32 for modern desktop CPUs. + * Some code requires such alignment other code can be slower without + * correct alignment, for yet other it makes no difference. + * + * @note The linesize may be larger than the size of usable data -- there + * may be extra padding present for performance reasons. + * + * @attention In case of video, line size values can be negative to achieve + * a vertically inverted iteration over image lines. + */ + int linesize[AV_NUM_DATA_POINTERS]; + + /** + * pointers to the data planes/channels. + * + * For video, this should simply point to data[]. + * + * For planar audio, each channel has a separate data pointer, and + * linesize[0] contains the size of each channel buffer. + * For packed audio, there is just one data pointer, and linesize[0] + * contains the total size of the buffer for all channels. + * + * Note: Both data and extended_data should always be set in a valid frame, + * but for planar audio with more channels that can fit in data, + * extended_data must be used in order to access all channels. + */ + uint8_t **extended_data; + + /** + * @name Video dimensions + * Video frames only. The coded dimensions (in pixels) of the video frame, + * i.e. the size of the rectangle that contains some well-defined values. + * + * @note The part of the frame intended for display/presentation is further + * restricted by the @ref cropping "Cropping rectangle". + * @{ + */ + int width, height; + /** + * @} + */ + + /** + * number of audio samples (per channel) described by this frame + */ + int nb_samples; + + /** + * format of the frame, -1 if unknown or unset + * Values correspond to enum AVPixelFormat for video frames, + * enum AVSampleFormat for audio) + */ + int format; + + /** + * Picture type of the frame. + */ + enum AVPictureType pict_type; + + /** + * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified. + */ + AVRational sample_aspect_ratio; + + /** + * Presentation timestamp in time_base units (time when frame should be shown to user). + */ + int64_t pts; + + /** + * DTS copied from the AVPacket that triggered returning this frame. (if frame threading isn't used) + * This is also the Presentation time of this AVFrame calculated from + * only AVPacket.dts values without pts values. + */ + int64_t pkt_dts; + + /** + * Time base for the timestamps in this frame. + * In the future, this field may be set on frames output by decoders or + * filters, but its value will be by default ignored on input to encoders + * or filters. + */ + AVRational time_base; + + /** + * quality (between 1 (good) and FF_LAMBDA_MAX (bad)) + */ + int quality; + + /** + * Frame owner's private data. + * + * This field may be set by the code that allocates/owns the frame data. + * It is then not touched by any library functions, except: + * - it is copied to other references by av_frame_copy_props() (and hence by + * av_frame_ref()); + * - it is set to NULL when the frame is cleared by av_frame_unref() + * - on the caller's explicit request. E.g. libavcodec encoders/decoders + * will copy this field to/from @ref AVPacket "AVPackets" if the caller sets + * @ref AV_CODEC_FLAG_COPY_OPAQUE. + * + * @see opaque_ref the reference-counted analogue + */ + void *opaque; + + /** + * Number of fields in this frame which should be repeated, i.e. the total + * duration of this frame should be repeat_pict + 2 normal field durations. + * + * For interlaced frames this field may be set to 1, which signals that this + * frame should be presented as 3 fields: beginning with the first field (as + * determined by AV_FRAME_FLAG_TOP_FIELD_FIRST being set or not), followed + * by the second field, and then the first field again. + * + * For progressive frames this field may be set to a multiple of 2, which + * signals that this frame's duration should be (repeat_pict + 2) / 2 + * normal frame durations. + * + * @note This field is computed from MPEG2 repeat_first_field flag and its + * associated flags, H.264 pic_struct from picture timing SEI, and + * their analogues in other codecs. Typically it should only be used when + * higher-layer timing information is not available. + */ + int repeat_pict; + + /** + * Sample rate of the audio data. + */ + int sample_rate; + + /** + * AVBuffer references backing the data for this frame. All the pointers in + * data and extended_data must point inside one of the buffers in buf or + * extended_buf. This array must be filled contiguously -- if buf[i] is + * non-NULL then buf[j] must also be non-NULL for all j < i. + * + * There may be at most one AVBuffer per data plane, so for video this array + * always contains all the references. For planar audio with more than + * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in + * this array. Then the extra AVBufferRef pointers are stored in the + * extended_buf array. + */ + AVBufferRef *buf[AV_NUM_DATA_POINTERS]; + + /** + * For planar audio which requires more than AV_NUM_DATA_POINTERS + * AVBufferRef pointers, this array will hold all the references which + * cannot fit into AVFrame.buf. + * + * Note that this is different from AVFrame.extended_data, which always + * contains all the pointers. This array only contains the extra pointers, + * which cannot fit into AVFrame.buf. + * + * This array is always allocated using av_malloc() by whoever constructs + * the frame. It is freed in av_frame_unref(). + */ + AVBufferRef **extended_buf; + /** + * Number of elements in extended_buf. + */ + int nb_extended_buf; + + AVFrameSideData **side_data; + int nb_side_data; + +/** + * @defgroup lavu_frame_flags AV_FRAME_FLAGS + * @ingroup lavu_frame + * Flags describing additional frame properties. + * + * @{ + */ + +/** + * The frame data may be corrupted, e.g. due to decoding errors. + */ +#define AV_FRAME_FLAG_CORRUPT (1 << 0) +/** + * A flag to mark frames that are keyframes. + */ +#define AV_FRAME_FLAG_KEY (1 << 1) +/** + * A flag to mark the frames which need to be decoded, but shouldn't be output. + */ +#define AV_FRAME_FLAG_DISCARD (1 << 2) +/** + * A flag to mark frames whose content is interlaced. + */ +#define AV_FRAME_FLAG_INTERLACED (1 << 3) +/** + * A flag to mark frames where the top field is displayed first if the content + * is interlaced. + */ +#define AV_FRAME_FLAG_TOP_FIELD_FIRST (1 << 4) +/** + * A decoder can use this flag to mark frames which were originally encoded losslessly. + * + * For coding bitstream formats which support both lossless and lossy + * encoding, it is sometimes possible for a decoder to determine which method + * was used when the bitstream was encoded. + */ +#define AV_FRAME_FLAG_LOSSLESS (1 << 5) +/** + * @} + */ + + /** + * Frame flags, a combination of @ref lavu_frame_flags + */ + int flags; + + /** + * MPEG vs JPEG YUV range. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVColorRange color_range; + + enum AVColorPrimaries color_primaries; + + enum AVColorTransferCharacteristic color_trc; + + /** + * YUV colorspace type. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVColorSpace colorspace; + + enum AVChromaLocation chroma_location; + + /** + * frame timestamp estimated using various heuristics, in stream time base + * - encoding: unused + * - decoding: set by libavcodec, read by user. + */ + int64_t best_effort_timestamp; + + /** + * metadata. + * - encoding: Set by user. + * - decoding: Set by libavcodec. + */ + AVDictionary *metadata; + + /** + * decode error flags of the frame, set to a combination of + * FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there + * were errors during the decoding. + * - encoding: unused + * - decoding: set by libavcodec, read by user. + */ + int decode_error_flags; +#define FF_DECODE_ERROR_INVALID_BITSTREAM 1 +#define FF_DECODE_ERROR_MISSING_REFERENCE 2 +#define FF_DECODE_ERROR_CONCEALMENT_ACTIVE 4 +#define FF_DECODE_ERROR_DECODE_SLICES 8 + + /** + * For hwaccel-format frames, this should be a reference to the + * AVHWFramesContext describing the frame. + */ + AVBufferRef *hw_frames_ctx; + + /** + * Frame owner's private data. + * + * This field may be set by the code that allocates/owns the frame data. + * It is then not touched by any library functions, except: + * - a new reference to the underlying buffer is propagated by + * av_frame_copy_props() (and hence by av_frame_ref()); + * - it is unreferenced in av_frame_unref(); + * - on the caller's explicit request. E.g. libavcodec encoders/decoders + * will propagate a new reference to/from @ref AVPacket "AVPackets" if the + * caller sets @ref AV_CODEC_FLAG_COPY_OPAQUE. + * + * @see opaque the plain pointer analogue + */ + AVBufferRef *opaque_ref; + + /** + * @anchor cropping + * @name Cropping + * Video frames only. The number of pixels to discard from the + * top/bottom/left/right border of the frame to obtain the sub-rectangle of + * the frame intended for presentation. + * @{ + */ + size_t crop_top; + size_t crop_bottom; + size_t crop_left; + size_t crop_right; + /** + * @} + */ + + /** + * RefStruct reference for internal use by a single libav* library. + * Must not be used to transfer data between libraries. + * Has to be NULL when ownership of the frame leaves the respective library. + * + * Code outside the FFmpeg libs must never check or change private_ref. + */ + void *private_ref; + + /** + * Channel layout of the audio data. + */ + AVChannelLayout ch_layout; + + /** + * Duration of the frame, in the same units as pts. 0 if unknown. + */ + int64_t duration; + + /** + * Indicates how the alpha channel of the video is to be handled. + * - encoding: Set by user + * - decoding: Set by libavcodec + */ + enum AVAlphaMode alpha_mode; +} AVFrame; + + +/** + * Allocate an AVFrame and set its fields to default values. The resulting + * struct must be freed using av_frame_free(). + * + * @return An AVFrame filled with default values or NULL on failure. + * + * @note this only allocates the AVFrame itself, not the data buffers. Those + * must be allocated through other means, e.g. with av_frame_get_buffer() or + * manually. + */ +AVFrame *av_frame_alloc(void); + +/** + * Free the frame and any dynamically allocated objects in it, + * e.g. extended_data. If the frame is reference counted, it will be + * unreferenced first. + * + * @param frame frame to be freed. The pointer will be set to NULL. + */ +void av_frame_free(AVFrame **frame); + +/** + * Set up a new reference to the data described by the source frame. + * + * Copy frame properties from src to dst and create a new reference for each + * AVBufferRef from src. + * + * If src is not reference counted, new buffers are allocated and the data is + * copied. + * + * @warning: dst MUST have been either unreferenced with av_frame_unref(dst), + * or newly allocated with av_frame_alloc() before calling this + * function, or undefined behavior will occur. + * + * @return 0 on success, a negative AVERROR on error + */ +int av_frame_ref(AVFrame *dst, const AVFrame *src); + +/** + * Ensure the destination frame refers to the same data described by the source + * frame, either by creating a new reference for each AVBufferRef from src if + * they differ from those in dst, by allocating new buffers and copying data if + * src is not reference counted, or by unreferencing it if src is empty. + * + * Frame properties on dst will be replaced by those from src. + * + * @return 0 on success, a negative AVERROR on error. On error, dst is + * unreferenced. + */ +int av_frame_replace(AVFrame *dst, const AVFrame *src); + +/** + * Create a new frame that references the same data as src. + * + * This is a shortcut for av_frame_alloc()+av_frame_ref(). + * + * @return newly created AVFrame on success, NULL on error. + */ +AVFrame *av_frame_clone(const AVFrame *src); + +/** + * Unreference all the buffers referenced by frame and reset the frame fields. + */ +void av_frame_unref(AVFrame *frame); + +/** + * Move everything contained in src to dst and reset src. + * + * @warning: dst is not unreferenced, but directly overwritten without reading + * or deallocating its contents. Call av_frame_unref(dst) manually + * before calling this function to ensure that no memory is leaked. + */ +void av_frame_move_ref(AVFrame *dst, AVFrame *src); + +/** + * Allocate new buffer(s) for audio or video data. + * + * The following fields must be set on frame before calling this function: + * - format (pixel format for video, sample format for audio) + * - width and height for video + * - nb_samples and ch_layout for audio + * + * This function will fill AVFrame.data and AVFrame.buf arrays and, if + * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf. + * For planar formats, one buffer will be allocated for each plane. + * + * @warning: if frame already has been allocated, calling this function will + * leak memory. In addition, undefined behavior can occur in certain + * cases. + * + * @param frame frame in which to store the new buffers. + * @param align Required buffer size and data pointer alignment. If equal to 0, + * alignment will be chosen automatically for the current CPU. + * It is highly recommended to pass 0 here unless you know what + * you are doing. + * + * @return 0 on success, a negative AVERROR on error. + */ +int av_frame_get_buffer(AVFrame *frame, int align); + +/** + * Check if the frame data is writable. + * + * @return A positive value if the frame data is writable (which is true if and + * only if each of the underlying buffers has only one reference, namely the one + * stored in this frame). Return 0 otherwise. + * + * If 1 is returned the answer is valid until av_buffer_ref() is called on any + * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly). + * + * @see av_frame_make_writable(), av_buffer_is_writable() + */ +int av_frame_is_writable(AVFrame *frame); + +/** + * Ensure that the frame data is writable, avoiding data copy if possible. + * + * Do nothing if the frame is writable, allocate new buffers and copy the data + * if it is not. Non-refcounted frames behave as non-writable, i.e. a copy + * is always made. + * + * @return 0 on success, a negative AVERROR on error. + * + * @see av_frame_is_writable(), av_buffer_is_writable(), + * av_buffer_make_writable() + */ +int av_frame_make_writable(AVFrame *frame); + +/** + * Copy the frame data from src to dst. + * + * This function does not allocate anything, dst must be already initialized and + * allocated with the same parameters as src. + * + * This function only copies the frame data (i.e. the contents of the data / + * extended data arrays), not any other properties. + * + * @return >= 0 on success, a negative AVERROR on error. + */ +int av_frame_copy(AVFrame *dst, const AVFrame *src); + +/** + * Copy only "metadata" fields from src to dst. + * + * Metadata for the purpose of this function are those fields that do not affect + * the data layout in the buffers. E.g. pts, sample rate (for audio) or sample + * aspect ratio (for video), but not width/height or channel layout. + * Side data is also copied. + */ +int av_frame_copy_props(AVFrame *dst, const AVFrame *src); + +/** + * Get the buffer reference a given data plane is stored in. + * + * @param frame the frame to get the plane's buffer from + * @param plane index of the data plane of interest in frame->extended_data. + * + * @return the buffer reference that contains the plane or NULL if the input + * frame is not valid. + */ +AVBufferRef *av_frame_get_plane_buffer(const AVFrame *frame, int plane); + +/** + * Add a new side data to a frame. + * + * @param frame a frame to which the side data should be added + * @param type type of the added side data + * @param size size of the side data + * + * @return newly added side data on success, NULL on error + */ +AVFrameSideData *av_frame_new_side_data(AVFrame *frame, + enum AVFrameSideDataType type, + size_t size); + +/** + * Add a new side data to a frame from an existing AVBufferRef + * + * @param frame a frame to which the side data should be added + * @param type the type of the added side data + * @param buf an AVBufferRef to add as side data. The ownership of + * the reference is transferred to the frame. + * + * @return newly added side data on success, NULL on error. On failure + * the frame is unchanged and the AVBufferRef remains owned by + * the caller. + */ +AVFrameSideData *av_frame_new_side_data_from_buf(AVFrame *frame, + enum AVFrameSideDataType type, + AVBufferRef *buf); + +/** + * @return a pointer to the side data of a given type on success, NULL if there + * is no side data with such type in this frame. + */ +AVFrameSideData *av_frame_get_side_data(const AVFrame *frame, + enum AVFrameSideDataType type); + +/** + * Remove and free all side data instances of the given type. + */ +void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type); + + +/** + * Flags for frame cropping. + */ +enum { + /** + * Apply the maximum possible cropping, even if it requires setting the + * AVFrame.data[] entries to unaligned pointers. Passing unaligned data + * to FFmpeg API is generally not allowed, and causes undefined behavior + * (such as crashes). You can pass unaligned data only to FFmpeg APIs that + * are explicitly documented to accept it. Use this flag only if you + * absolutely know what you are doing. + */ + AV_FRAME_CROP_UNALIGNED = 1 << 0, +}; + +/** + * Crop the given video AVFrame according to its crop_left/crop_top/crop_right/ + * crop_bottom fields. If cropping is successful, the function will adjust the + * data pointers and the width/height fields, and set the crop fields to 0. + * + * In all cases, the cropping boundaries will be rounded to the inherent + * alignment of the pixel format. In some cases, such as for opaque hwaccel + * formats, the left/top cropping is ignored. The crop fields are set to 0 even + * if the cropping was rounded or ignored. + * + * @param frame the frame which should be cropped + * @param flags Some combination of AV_FRAME_CROP_* flags, or 0. + * + * @return >= 0 on success, a negative AVERROR on error. If the cropping fields + * were invalid, AVERROR(ERANGE) is returned, and nothing is changed. + */ +int av_frame_apply_cropping(AVFrame *frame, int flags); + +/** + * @return a string identifying the side data type + */ +const char *av_frame_side_data_name(enum AVFrameSideDataType type); + +/** + * @return side data descriptor corresponding to a given side data type, NULL + * when not available. + */ +const AVSideDataDescriptor *av_frame_side_data_desc(enum AVFrameSideDataType type); + +/** + * Free all side data entries and their contents, then zeroes out the + * values which the pointers are pointing to. + * + * @param sd pointer to array of side data to free. Will be set to NULL + * upon return. + * @param nb_sd pointer to an integer containing the number of entries in + * the array. Will be set to 0 upon return. + */ +void av_frame_side_data_free(AVFrameSideData ***sd, int *nb_sd); + +/** + * Remove existing entries before adding new ones. + */ +#define AV_FRAME_SIDE_DATA_FLAG_UNIQUE (1 << 0) +/** + * Don't add a new entry if another of the same type exists. + * Applies only for side data types without the AV_SIDE_DATA_PROP_MULTI prop. + */ +#define AV_FRAME_SIDE_DATA_FLAG_REPLACE (1 << 1) +/** + * Create a new reference to the passed in buffer instead of taking ownership + * of it. + */ +#define AV_FRAME_SIDE_DATA_FLAG_NEW_REF (1 << 2) + +/** + * Add new side data entry to an array. + * + * @param sd pointer to array of side data to which to add another entry, + * or to NULL in order to start a new array. + * @param nb_sd pointer to an integer containing the number of entries in + * the array. + * @param type type of the added side data + * @param size size of the side data + * @param flags Some combination of AV_FRAME_SIDE_DATA_FLAG_* flags, or 0. + * + * @return newly added side data on success, NULL on error. + * @note In case of AV_FRAME_SIDE_DATA_FLAG_UNIQUE being set, entries of + * matching AVFrameSideDataType will be removed before the addition + * is attempted. + * @note In case of AV_FRAME_SIDE_DATA_FLAG_REPLACE being set, if an + * entry of the same type already exists, it will be replaced instead. + */ +AVFrameSideData *av_frame_side_data_new(AVFrameSideData ***sd, int *nb_sd, + enum AVFrameSideDataType type, + size_t size, unsigned int flags); + +/** + * Add a new side data entry to an array from an existing AVBufferRef. + * + * @param sd pointer to array of side data to which to add another entry, + * or to NULL in order to start a new array. + * @param nb_sd pointer to an integer containing the number of entries in + * the array. + * @param type type of the added side data + * @param buf Pointer to AVBufferRef to add to the array. On success, + * the function takes ownership of the AVBufferRef and *buf is + * set to NULL, unless AV_FRAME_SIDE_DATA_FLAG_NEW_REF is set + * in which case the ownership will remain with the caller. + * @param flags Some combination of AV_FRAME_SIDE_DATA_FLAG_* flags, or 0. + * + * @return newly added side data on success, NULL on error. + * @note In case of AV_FRAME_SIDE_DATA_FLAG_UNIQUE being set, entries of + * matching AVFrameSideDataType will be removed before the addition + * is attempted. + * @note In case of AV_FRAME_SIDE_DATA_FLAG_REPLACE being set, if an + * entry of the same type already exists, it will be replaced instead. + * + */ +AVFrameSideData *av_frame_side_data_add(AVFrameSideData ***sd, int *nb_sd, + enum AVFrameSideDataType type, + AVBufferRef **buf, unsigned int flags); + +/** + * Add a new side data entry to an array based on existing side data, taking + * a reference towards the contained AVBufferRef. + * + * @param sd pointer to array of side data to which to add another entry, + * or to NULL in order to start a new array. + * @param nb_sd pointer to an integer containing the number of entries in + * the array. + * @param src side data to be cloned, with a new reference utilized + * for the buffer. + * @param flags Some combination of AV_FRAME_SIDE_DATA_FLAG_* flags, or 0. + * + * @return negative error code on failure, >=0 on success. + * @note In case of AV_FRAME_SIDE_DATA_FLAG_UNIQUE being set, entries of + * matching AVFrameSideDataType will be removed before the addition + * is attempted. + * @note In case of AV_FRAME_SIDE_DATA_FLAG_REPLACE being set, if an + * entry of the same type already exists, it will be replaced instead. + */ +int av_frame_side_data_clone(AVFrameSideData ***sd, int *nb_sd, + const AVFrameSideData *src, unsigned int flags); + +/** + * Get a side data entry of a specific type from an array. + * + * @param sd array of side data. + * @param nb_sd integer containing the number of entries in the array. + * @param type type of side data to be queried + * + * @return a pointer to the side data of a given type on success, NULL if there + * is no side data with such type in this set. + */ +const AVFrameSideData *av_frame_side_data_get_c(const AVFrameSideData * const *sd, + const int nb_sd, + enum AVFrameSideDataType type); + +/** + * Wrapper around av_frame_side_data_get_c() to workaround the limitation + * that for any type T the conversion from T * const * to const T * const * + * is not performed automatically in C. + * @see av_frame_side_data_get_c() + */ +static inline +const AVFrameSideData *av_frame_side_data_get(AVFrameSideData * const *sd, + const int nb_sd, + enum AVFrameSideDataType type) +{ + return av_frame_side_data_get_c((const AVFrameSideData * const *)sd, + nb_sd, type); +} + +/** + * Remove and free all side data instances of the given type from an array. + */ +void av_frame_side_data_remove(AVFrameSideData ***sd, int *nb_sd, + enum AVFrameSideDataType type); + +/** + * Remove and free all side data instances that match any of the given + * side data properties. (See enum AVSideDataProps) + */ +void av_frame_side_data_remove_by_props(AVFrameSideData ***sd, int *nb_sd, + int props); + +/** + * @} + */ + +#endif /* AVUTIL_FRAME_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hash.h b/ffmpeg-n8.1/include/libavutil/hash.h new file mode 100644 index 00000000..94151ded --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hash.h @@ -0,0 +1,264 @@ +/* + * Copyright (C) 2013 Reimar Döffinger + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_hash_generic + * Generic hashing API + */ + +#ifndef AVUTIL_HASH_H +#define AVUTIL_HASH_H + +#include +#include + +/** + * @defgroup lavu_hash Hash Functions + * @ingroup lavu_crypto + * Hash functions useful in multimedia. + * + * Hash functions are widely used in multimedia, from error checking and + * concealment to internal regression testing. libavutil has efficient + * implementations of a variety of hash functions that may be useful for + * FFmpeg and other multimedia applications. + * + * @{ + * + * @defgroup lavu_hash_generic Generic Hashing API + * An abstraction layer for all hash functions supported by libavutil. + * + * If your application needs to support a wide range of different hash + * functions, then the Generic Hashing API is for you. It provides a generic, + * reusable API for @ref lavu_hash "all hash functions" implemented in libavutil. + * If you just need to use one particular hash function, use the @ref lavu_hash + * "individual hash" directly. + * + * @section Sample Code + * + * A basic template for using the Generic Hashing API follows: + * + * @code + * struct AVHashContext *ctx = NULL; + * const char *hash_name = NULL; + * uint8_t *output_buf = NULL; + * + * // Select from a string returned by av_hash_names() + * hash_name = ...; + * + * // Allocate a hash context + * ret = av_hash_alloc(&ctx, hash_name); + * if (ret < 0) + * return ret; + * + * // Initialize the hash context + * av_hash_init(ctx); + * + * // Update the hash context with data + * while (data_left) { + * av_hash_update(ctx, data, size); + * } + * + * // Now we have no more data, so it is time to finalize the hash and get the + * // output. But we need to first allocate an output buffer. Note that you can + * // use any memory allocation function, including malloc(), not just + * // av_malloc(). + * output_buf = av_malloc(av_hash_get_size(ctx)); + * if (!output_buf) + * return AVERROR(ENOMEM); + * + * // Finalize the hash context. + * // You can use any of the av_hash_final*() functions provided, for other + * // output formats. If you do so, be sure to adjust the memory allocation + * // above. See the function documentation below for the exact amount of extra + * // memory needed. + * av_hash_final(ctx, output_buffer); + * + * // Free the context + * av_hash_freep(&ctx); + * @endcode + * + * @section Hash Function-Specific Information + * If the CRC32 hash is selected, the #AV_CRC_32_IEEE polynomial will be + * used. + * + * If the Murmur3 hash is selected, the default seed will be used. See @ref + * lavu_murmur3_seedinfo "Murmur3" for more information. + * + * @{ + */ + +/** + * @example ffhash.c + * This example is a simple command line application that takes one or more + * arguments. It demonstrates a typical use of the hashing API with allocation, + * initialization, updating, and finalizing. + */ + +struct AVHashContext; + +/** + * Allocate a hash context for the algorithm specified by name. + * + * @return >= 0 for success, a negative error code for failure + * + * @note The context is not initialized after a call to this function; you must + * call av_hash_init() to do so. + */ +int av_hash_alloc(struct AVHashContext **ctx, const char *name); + +/** + * Get the names of available hash algorithms. + * + * This function can be used to enumerate the algorithms. + * + * @param[in] i Index of the hash algorithm, starting from 0 + * @return Pointer to a static string or `NULL` if `i` is out of range + */ +const char *av_hash_names(int i); + +/** + * Get the name of the algorithm corresponding to the given hash context. + */ +const char *av_hash_get_name(const struct AVHashContext *ctx); + +/** + * Maximum value that av_hash_get_size() will currently return. + * + * You can use this if you absolutely want or need to use static allocation for + * the output buffer and are fine with not supporting hashes newly added to + * libavutil without recompilation. + * + * @warning + * Adding new hashes with larger sizes, and increasing the macro while doing + * so, will not be considered an ABI change. To prevent your code from + * overflowing a buffer, either dynamically allocate the output buffer with + * av_hash_get_size(), or limit your use of the Hashing API to hashes that are + * already in FFmpeg during the time of compilation. + */ +#define AV_HASH_MAX_SIZE 64 + +/** + * Get the size of the resulting hash value in bytes. + * + * The maximum value this function will currently return is available as macro + * #AV_HASH_MAX_SIZE. + * + * @param[in] ctx Hash context + * @return Size of the hash value in bytes + */ +int av_hash_get_size(const struct AVHashContext *ctx); + +/** + * Initialize or reset a hash context. + * + * @param[in,out] ctx Hash context + */ +void av_hash_init(struct AVHashContext *ctx); + +/** + * Update a hash context with additional data. + * + * @param[in,out] ctx Hash context + * @param[in] src Data to be added to the hash context + * @param[in] len Size of the additional data + */ +void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, size_t len); + +/** + * Finalize a hash context and compute the actual hash value. + * + * The minimum size of `dst` buffer is given by av_hash_get_size() or + * #AV_HASH_MAX_SIZE. The use of the latter macro is discouraged. + * + * It is not safe to update or finalize a hash context again, if it has already + * been finalized. + * + * @param[in,out] ctx Hash context + * @param[out] dst Where the final hash value will be stored + * + * @see av_hash_final_bin() provides an alternative API + */ +void av_hash_final(struct AVHashContext *ctx, uint8_t *dst); + +/** + * Finalize a hash context and store the actual hash value in a buffer. + * + * It is not safe to update or finalize a hash context again, if it has already + * been finalized. + * + * If `size` is smaller than the hash size (given by av_hash_get_size()), the + * hash is truncated; if size is larger, the buffer is padded with 0. + * + * @param[in,out] ctx Hash context + * @param[out] dst Where the final hash value will be stored + * @param[in] size Number of bytes to write to `dst` + */ +void av_hash_final_bin(struct AVHashContext *ctx, uint8_t *dst, int size); + +/** + * Finalize a hash context and store the hexadecimal representation of the + * actual hash value as a string. + * + * It is not safe to update or finalize a hash context again, if it has already + * been finalized. + * + * The string is always 0-terminated. + * + * If `size` is smaller than `2 * hash_size + 1`, where `hash_size` is the + * value returned by av_hash_get_size(), the string will be truncated. + * + * @param[in,out] ctx Hash context + * @param[out] dst Where the string will be stored + * @param[in] size Maximum number of bytes to write to `dst` + */ +void av_hash_final_hex(struct AVHashContext *ctx, uint8_t *dst, int size); + +/** + * Finalize a hash context and store the Base64 representation of the + * actual hash value as a string. + * + * It is not safe to update or finalize a hash context again, if it has already + * been finalized. + * + * The string is always 0-terminated. + * + * If `size` is smaller than AV_BASE64_SIZE(hash_size), where `hash_size` is + * the value returned by av_hash_get_size(), the string will be truncated. + * + * @param[in,out] ctx Hash context + * @param[out] dst Where the final hash value will be stored + * @param[in] size Maximum number of bytes to write to `dst` + */ +void av_hash_final_b64(struct AVHashContext *ctx, uint8_t *dst, int size); + +/** + * Free hash context and set hash context pointer to `NULL`. + * + * @param[in,out] ctx Pointer to hash context + */ +void av_hash_freep(struct AVHashContext **ctx); + +/** + * @} + * @} + */ + +#endif /* AVUTIL_HASH_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hdr_dynamic_metadata.h b/ffmpeg-n8.1/include/libavutil/hdr_dynamic_metadata.h new file mode 100644 index 00000000..5100ed6f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hdr_dynamic_metadata.h @@ -0,0 +1,376 @@ +/* + * Copyright (c) 2018 Mohammad Izadi + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HDR_DYNAMIC_METADATA_H +#define AVUTIL_HDR_DYNAMIC_METADATA_H + +#include "frame.h" +#include "rational.h" + +/** + * Option for overlapping elliptical pixel selectors in an image. + */ +enum AVHDRPlusOverlapProcessOption { + AV_HDR_PLUS_OVERLAP_PROCESS_WEIGHTED_AVERAGING = 0, + AV_HDR_PLUS_OVERLAP_PROCESS_LAYERING = 1, +}; + +/** + * Represents the percentile at a specific percentage in + * a distribution. + */ +typedef struct AVHDRPlusPercentile { + /** + * The percentage value corresponding to a specific percentile linearized + * RGB value in the processing window in the scene. The value shall be in + * the range of 0 to100, inclusive. + */ + uint8_t percentage; + + /** + * The linearized maxRGB value at a specific percentile in the processing + * window in the scene. The value shall be in the range of 0 to 1, inclusive + * and in multiples of 0.00001. + */ + AVRational percentile; +} AVHDRPlusPercentile; + +/** + * Color transform parameters at a processing window in a dynamic metadata for + * SMPTE 2094-40. + */ +typedef struct AVHDRPlusColorTransformParams { + /** + * The relative x coordinate of the top left pixel of the processing + * window. The value shall be in the range of 0 and 1, inclusive and + * in multiples of 1/(width of Picture - 1). The value 1 corresponds + * to the absolute coordinate of width of Picture - 1. The value for + * first processing window shall be 0. + */ + AVRational window_upper_left_corner_x; + + /** + * The relative y coordinate of the top left pixel of the processing + * window. The value shall be in the range of 0 and 1, inclusive and + * in multiples of 1/(height of Picture - 1). The value 1 corresponds + * to the absolute coordinate of height of Picture - 1. The value for + * first processing window shall be 0. + */ + AVRational window_upper_left_corner_y; + + /** + * The relative x coordinate of the bottom right pixel of the processing + * window. The value shall be in the range of 0 and 1, inclusive and + * in multiples of 1/(width of Picture - 1). The value 1 corresponds + * to the absolute coordinate of width of Picture - 1. The value for + * first processing window shall be 1. + */ + AVRational window_lower_right_corner_x; + + /** + * The relative y coordinate of the bottom right pixel of the processing + * window. The value shall be in the range of 0 and 1, inclusive and + * in multiples of 1/(height of Picture - 1). The value 1 corresponds + * to the absolute coordinate of height of Picture - 1. The value for + * first processing window shall be 1. + */ + AVRational window_lower_right_corner_y; + + /** + * The x coordinate of the center position of the concentric internal and + * external ellipses of the elliptical pixel selector in the processing + * window. The value shall be in the range of 0 to (width of Picture - 1), + * inclusive and in multiples of 1 pixel. + */ + uint16_t center_of_ellipse_x; + + /** + * The y coordinate of the center position of the concentric internal and + * external ellipses of the elliptical pixel selector in the processing + * window. The value shall be in the range of 0 to (height of Picture - 1), + * inclusive and in multiples of 1 pixel. + */ + uint16_t center_of_ellipse_y; + + /** + * The clockwise rotation angle in degree of arc with respect to the + * positive direction of the x-axis of the concentric internal and external + * ellipses of the elliptical pixel selector in the processing window. The + * value shall be in the range of 0 to 180, inclusive and in multiples of 1. + */ + uint8_t rotation_angle; + + /** + * The semi-major axis value of the internal ellipse of the elliptical pixel + * selector in amount of pixels in the processing window. The value shall be + * in the range of 1 to 65535, inclusive and in multiples of 1 pixel. + */ + uint16_t semimajor_axis_internal_ellipse; + + /** + * The semi-major axis value of the external ellipse of the elliptical pixel + * selector in amount of pixels in the processing window. The value + * shall not be less than semimajor_axis_internal_ellipse of the current + * processing window. The value shall be in the range of 1 to 65535, + * inclusive and in multiples of 1 pixel. + */ + uint16_t semimajor_axis_external_ellipse; + + /** + * The semi-minor axis value of the external ellipse of the elliptical pixel + * selector in amount of pixels in the processing window. The value shall be + * in the range of 1 to 65535, inclusive and in multiples of 1 pixel. + */ + uint16_t semiminor_axis_external_ellipse; + + /** + * Overlap process option indicates one of the two methods of combining + * rendered pixels in the processing window in an image with at least one + * elliptical pixel selector. For overlapping elliptical pixel selectors + * in an image, overlap_process_option shall have the same value. + */ + enum AVHDRPlusOverlapProcessOption overlap_process_option; + + /** + * The maximum of the color components of linearized RGB values in the + * processing window in the scene. The values should be in the range of 0 to + * 1, inclusive and in multiples of 0.00001. maxscl[ 0 ], maxscl[ 1 ], and + * maxscl[ 2 ] are corresponding to R, G, B color components respectively. + */ + AVRational maxscl[3]; + + /** + * The average of linearized maxRGB values in the processing window in the + * scene. The value should be in the range of 0 to 1, inclusive and in + * multiples of 0.00001. + */ + AVRational average_maxrgb; + + /** + * The number of linearized maxRGB values at given percentiles in the + * processing window in the scene. The maximum value shall be 15. + */ + uint8_t num_distribution_maxrgb_percentiles; + + /** + * The linearized maxRGB values at given percentiles in the + * processing window in the scene. + */ + AVHDRPlusPercentile distribution_maxrgb[15]; + + /** + * The fraction of selected pixels in the image that contains the brightest + * pixel in the scene. The value shall be in the range of 0 to 1, inclusive + * and in multiples of 0.001. + */ + AVRational fraction_bright_pixels; + + /** + * This flag indicates that the metadata for the tone mapping function in + * the processing window is present (for value of 1). + */ + uint8_t tone_mapping_flag; + + /** + * The x coordinate of the separation point between the linear part and the + * curved part of the tone mapping function. The value shall be in the range + * of 0 to 1, excluding 0 and in multiples of 1/4095. + */ + AVRational knee_point_x; + + /** + * The y coordinate of the separation point between the linear part and the + * curved part of the tone mapping function. The value shall be in the range + * of 0 to 1, excluding 0 and in multiples of 1/4095. + */ + AVRational knee_point_y; + + /** + * The number of the intermediate anchor parameters of the tone mapping + * function in the processing window. The maximum value shall be 15. + */ + uint8_t num_bezier_curve_anchors; + + /** + * The intermediate anchor parameters of the tone mapping function in the + * processing window in the scene. The values should be in the range of 0 + * to 1, inclusive and in multiples of 1/1023. + */ + AVRational bezier_curve_anchors[15]; + + /** + * This flag shall be equal to 0 in bitstreams conforming to this version of + * this Specification. Other values are reserved for future use. + */ + uint8_t color_saturation_mapping_flag; + + /** + * The color saturation gain in the processing window in the scene. The + * value shall be in the range of 0 to 63/8, inclusive and in multiples of + * 1/8. The default value shall be 1. + */ + AVRational color_saturation_weight; +} AVHDRPlusColorTransformParams; + +/** + * This struct represents dynamic metadata for color volume transform - + * application 4 of SMPTE 2094-40:2016 standard. + * + * To be used as payload of a AVFrameSideData or AVPacketSideData with the + * appropriate type. + * + * @note The struct should be allocated with + * av_dynamic_hdr_plus_alloc() and its size is not a part of + * the public ABI. + */ +typedef struct AVDynamicHDRPlus { + /** + * Country code by Rec. ITU-T T.35 Annex A. The value shall be 0xB5. + */ + uint8_t itu_t_t35_country_code; + + /** + * Application version in the application defining document in ST-2094 + * suite. The value shall be set to 0. + */ + uint8_t application_version; + + /** + * The number of processing windows. The value shall be in the range + * of 1 to 3, inclusive. + */ + uint8_t num_windows; + + /** + * The color transform parameters for every processing window. + */ + AVHDRPlusColorTransformParams params[3]; + + /** + * The nominal maximum display luminance of the targeted system display, + * in units of 0.0001 candelas per square metre. The value shall be in + * the range of 0 to 10000, inclusive. + */ + AVRational targeted_system_display_maximum_luminance; + + /** + * This flag shall be equal to 0 in bit streams conforming to this version + * of this Specification. The value 1 is reserved for future use. + */ + uint8_t targeted_system_display_actual_peak_luminance_flag; + + /** + * The number of rows in the targeted system_display_actual_peak_luminance + * array. The value shall be in the range of 2 to 25, inclusive. + */ + uint8_t num_rows_targeted_system_display_actual_peak_luminance; + + /** + * The number of columns in the + * targeted_system_display_actual_peak_luminance array. The value shall be + * in the range of 2 to 25, inclusive. + */ + uint8_t num_cols_targeted_system_display_actual_peak_luminance; + + /** + * The normalized actual peak luminance of the targeted system display. The + * values should be in the range of 0 to 1, inclusive and in multiples of + * 1/15. + */ + AVRational targeted_system_display_actual_peak_luminance[25][25]; + + /** + * This flag shall be equal to 0 in bitstreams conforming to this version of + * this Specification. The value 1 is reserved for future use. + */ + uint8_t mastering_display_actual_peak_luminance_flag; + + /** + * The number of rows in the mastering_display_actual_peak_luminance array. + * The value shall be in the range of 2 to 25, inclusive. + */ + uint8_t num_rows_mastering_display_actual_peak_luminance; + + /** + * The number of columns in the mastering_display_actual_peak_luminance + * array. The value shall be in the range of 2 to 25, inclusive. + */ + uint8_t num_cols_mastering_display_actual_peak_luminance; + + /** + * The normalized actual peak luminance of the mastering display used for + * mastering the image essence. The values should be in the range of 0 to 1, + * inclusive and in multiples of 1/15. + */ + AVRational mastering_display_actual_peak_luminance[25][25]; +} AVDynamicHDRPlus; + +/** + * Allocate an AVDynamicHDRPlus structure and set its fields to + * default values. The resulting struct can be freed using av_freep(). + * + * @return An AVDynamicHDRPlus filled with default values or NULL + * on failure. + */ +AVDynamicHDRPlus *av_dynamic_hdr_plus_alloc(size_t *size); + +/** + * Allocate a complete AVDynamicHDRPlus and add it to the frame. + * @param frame The frame which side data is added to. + * + * @return The AVDynamicHDRPlus structure to be filled by caller or NULL + * on failure. + */ +AVDynamicHDRPlus *av_dynamic_hdr_plus_create_side_data(AVFrame *frame); + +/** + * Parse the user data registered ITU-T T.35 to AVbuffer (AVDynamicHDRPlus). + * The T.35 buffer must begin with the application mode, skipping the + * country code, terminal provider codes, and application identifier. + * @param s A pointer containing the decoded AVDynamicHDRPlus structure. + * @param data The byte array containing the raw ITU-T T.35 data. + * @param size Size of the data array in bytes. + * + * @return >= 0 on success. Otherwise, returns the appropriate AVERROR. + */ +int av_dynamic_hdr_plus_from_t35(AVDynamicHDRPlus *s, const uint8_t *data, + size_t size); + +#define AV_HDR_PLUS_MAX_PAYLOAD_SIZE 907 + +/** + * Serialize dynamic HDR10+ metadata to a user data registered ITU-T T.35 buffer, + * excluding the first 48 bytes of the header, and beginning with the application mode. + * @param s A pointer containing the decoded AVDynamicHDRPlus structure. + * @param[in,out] data A pointer to pointer to a byte buffer to be filled with the + * serialized metadata. + * If *data is NULL, a buffer be will be allocated and a pointer to + * it stored in its place. The caller assumes ownership of the buffer. + * May be NULL, in which case the function will only store the + * required buffer size in *size. + * @param[in,out] size A pointer to a size to be set to the returned buffer's size. + * If *data is not NULL, *size must contain the size of the input + * buffer. May be NULL only if *data is NULL. + * + * @return >= 0 on success. Otherwise, returns the appropriate AVERROR. + */ +int av_dynamic_hdr_plus_to_t35(const AVDynamicHDRPlus *s, uint8_t **data, size_t *size); + +#endif /* AVUTIL_HDR_DYNAMIC_METADATA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hdr_dynamic_vivid_metadata.h b/ffmpeg-n8.1/include/libavutil/hdr_dynamic_vivid_metadata.h new file mode 100644 index 00000000..d45b4a0f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hdr_dynamic_vivid_metadata.h @@ -0,0 +1,292 @@ +/* + * Copyright (c) 2021 Limin Wang + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H +#define AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H + +#include "frame.h" +#include "rational.h" + +/** + * HDR Vivid three spline params. + */ +typedef struct AVHDRVivid3SplineParams { + /** + * The mode of three Spline. the value shall be in the range + * of 0 to 3, inclusive. + */ + int th_mode; + + /** + * three_Spline_TH_enable_MB is in the range of 0.0 to 1.0, inclusive + * and in multiples of 1.0/255. + * + */ + AVRational th_enable_mb; + + /** + * 3Spline_TH_enable of three Spline. + * The value shall be in the range of 0.0 to 1.0, inclusive. + * and in multiples of 1.0/4095. + */ + AVRational th_enable; + + /** + * 3Spline_TH_Delta1 of three Spline. + * The value shall be in the range of 0.0 to 0.25, inclusive, + * and in multiples of 0.25/1023. + */ + AVRational th_delta1; + + /** + * 3Spline_TH_Delta2 of three Spline. + * The value shall be in the range of 0.0 to 0.25, inclusive, + * and in multiples of 0.25/1023. + */ + AVRational th_delta2; + + /** + * 3Spline_enable_Strength of three Spline. + * The value shall be in the range of 0.0 to 1.0, inclusive, + * and in multiples of 1.0/255. + */ + AVRational enable_strength; +} AVHDRVivid3SplineParams; + +/** + * Color tone mapping parameters at a processing window in a dynamic metadata for + * CUVA 005.1:2021. + */ +typedef struct AVHDRVividColorToneMappingParams { + /** + * The nominal maximum display luminance of the targeted system display, + * in multiples of 1.0/4095 candelas per square metre. The value shall be in + * the range of 0.0 to 1.0, inclusive. + */ + AVRational targeted_system_display_maximum_luminance; + + /** + * This flag indicates that transfer the base parameter(for value of 1) + */ + int base_enable_flag; + + /** + * base_param_m_p in the base parameter, + * in multiples of 1.0/16383. The value shall be in + * the range of 0.0 to 1.0, inclusive. + */ + AVRational base_param_m_p; + + /** + * base_param_m_m in the base parameter, + * in multiples of 1.0/10. The value shall be in + * the range of 0.0 to 6.3, inclusive. + */ + AVRational base_param_m_m; + + /** + * base_param_m_a in the base parameter, + * in multiples of 1.0/1023. The value shall be in + * the range of 0.0 to 1.0 inclusive. + */ + AVRational base_param_m_a; + + /** + * base_param_m_b in the base parameter, + * in multiples of 1/1023. The value shall be in + * the range of 0.0 to 1.0, inclusive. + */ + AVRational base_param_m_b; + + /** + * base_param_m_n in the base parameter, + * in multiples of 1.0/10. The value shall be in + * the range of 0.0 to 6.3, inclusive. + */ + AVRational base_param_m_n; + + /** + * indicates k1_0 in the base parameter, + * base_param_k1 <= 1: k1_0 = base_param_k1 + * base_param_k1 > 1: reserved + */ + int base_param_k1; + + /** + * indicates k2_0 in the base parameter, + * base_param_k2 <= 1: k2_0 = base_param_k2 + * base_param_k2 > 1: reserved + */ + int base_param_k2; + + /** + * indicates k3_0 in the base parameter, + * base_param_k3 == 1: k3_0 = base_param_k3 + * base_param_k3 == 2: k3_0 = maximum_maxrgb + * base_param_k3 > 2: reserved + */ + int base_param_k3; + + /** + * This flag indicates that delta mode of base parameter(for value of 1) + */ + int base_param_Delta_enable_mode; + + /** + * base_param_Delta in the base parameter, + * in multiples of 1.0/127. The value shall be in + * the range of 0.0 to 1.0, inclusive. + */ + AVRational base_param_Delta; + + /** + * indicates 3Spline_enable_flag in the base parameter, + * This flag indicates that transfer three Spline of base parameter(for value of 1) + */ + int three_Spline_enable_flag; + + /** + * The number of three Spline. The value shall be in the range + * of 1 to 2, inclusive. + */ + int three_Spline_num; + + AVHDRVivid3SplineParams three_spline[2]; +} AVHDRVividColorToneMappingParams; + + +/** + * Color transform parameters at a processing window in a dynamic metadata for + * CUVA 005.1:2021. + */ +typedef struct AVHDRVividColorTransformParams { + /** + * Indicates the minimum brightness of the displayed content. + * The values should be in the range of 0.0 to 1.0, + * inclusive and in multiples of 1/4095. + */ + AVRational minimum_maxrgb; + + /** + * Indicates the average brightness of the displayed content. + * The values should be in the range of 0.0 to 1.0, + * inclusive and in multiples of 1/4095. + */ + AVRational average_maxrgb; + + /** + * Indicates the variance brightness of the displayed content. + * The values should be in the range of 0.0 to 1.0, + * inclusive and in multiples of 1/4095. + */ + AVRational variance_maxrgb; + + /** + * Indicates the maximum brightness of the displayed content. + * The values should be in the range of 0.0 to 1.0, inclusive + * and in multiples of 1/4095. + */ + AVRational maximum_maxrgb; + + /** + * This flag indicates that the metadata for the tone mapping function in + * the processing window is present (for value of 1). + */ + int tone_mapping_mode_flag; + + /** + * The number of tone mapping param. The value shall be in the range + * of 1 to 2, inclusive. + */ + int tone_mapping_param_num; + + /** + * The color tone mapping parameters. + */ + AVHDRVividColorToneMappingParams tm_params[2]; + + /** + * This flag indicates that the metadata for the color saturation mapping in + * the processing window is present (for value of 1). + */ + int color_saturation_mapping_flag; + + /** + * The number of color saturation param. The value shall be in the range + * of 0 to 7, inclusive. + */ + int color_saturation_num; + + /** + * Indicates the color correction strength parameter. + * The values should be in the range of 0.0 to 2.0, inclusive + * and in multiples of 1/128. + */ + AVRational color_saturation_gain[8]; +} AVHDRVividColorTransformParams; + +/** + * This struct represents dynamic metadata for color volume transform - + * CUVA 005.1:2021 standard + * + * To be used as payload of a AVFrameSideData or AVPacketSideData with the + * appropriate type. + * + * @note The struct should be allocated with + * av_dynamic_hdr_vivid_alloc() and its size is not a part of + * the public ABI. + */ +typedef struct AVDynamicHDRVivid { + /** + * The system start code. The value shall be set to 0x01. + */ + uint8_t system_start_code; + + /** + * The number of processing windows. The value shall be set to 0x01 + * if the system_start_code is 0x01. + */ + uint8_t num_windows; + + /** + * The color transform parameters for every processing window. + */ + AVHDRVividColorTransformParams params[3]; +} AVDynamicHDRVivid; + +/** + * Allocate an AVDynamicHDRVivid structure and set its fields to + * default values. The resulting struct can be freed using av_freep(). + * + * @return An AVDynamicHDRVivid filled with default values or NULL + * on failure. + */ +AVDynamicHDRVivid *av_dynamic_hdr_vivid_alloc(size_t *size); + +/** + * Allocate a complete AVDynamicHDRVivid and add it to the frame. + * @param frame The frame which side data is added to. + * + * @return The AVDynamicHDRVivid structure to be filled by caller or NULL + * on failure. + */ +AVDynamicHDRVivid *av_dynamic_hdr_vivid_create_side_data(AVFrame *frame); + +#endif /* AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hmac.h b/ffmpeg-n8.1/include/libavutil/hmac.h new file mode 100644 index 00000000..ca4da6a6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hmac.h @@ -0,0 +1,99 @@ +/* + * Copyright (C) 2012 Martin Storsjo + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HMAC_H +#define AVUTIL_HMAC_H + +#include + +/** + * @defgroup lavu_hmac HMAC + * @ingroup lavu_crypto + * @{ + */ + +enum AVHMACType { + AV_HMAC_MD5, + AV_HMAC_SHA1, + AV_HMAC_SHA224, + AV_HMAC_SHA256, + AV_HMAC_SHA384, + AV_HMAC_SHA512, +}; + +typedef struct AVHMAC AVHMAC; + +/** + * Allocate an AVHMAC context. + * @param type The hash function used for the HMAC. + */ +AVHMAC *av_hmac_alloc(enum AVHMACType type); + +/** + * Free an AVHMAC context. + * @param ctx The context to free, may be NULL + */ +void av_hmac_free(AVHMAC *ctx); + +/** + * Initialize an AVHMAC context with an authentication key. + * @param ctx The HMAC context + * @param key The authentication key + * @param keylen The length of the key, in bytes + */ +void av_hmac_init(AVHMAC *ctx, const uint8_t *key, unsigned int keylen); + +/** + * Hash data with the HMAC. + * @param ctx The HMAC context + * @param data The data to hash + * @param len The length of the data, in bytes + */ +void av_hmac_update(AVHMAC *ctx, const uint8_t *data, unsigned int len); + +/** + * Finish hashing and output the HMAC digest. + * @param ctx The HMAC context + * @param out The output buffer to write the digest into + * @param outlen The length of the out buffer, in bytes + * @return The number of bytes written to out, or a negative error code. + */ +int av_hmac_final(AVHMAC *ctx, uint8_t *out, unsigned int outlen); + +/** + * Hash an array of data with a key. + * @param ctx The HMAC context + * @param data The data to hash + * @param len The length of the data, in bytes + * @param key The authentication key + * @param keylen The length of the key, in bytes + * @param out The output buffer to write the digest into + * @param outlen The length of the out buffer, in bytes + * @return The number of bytes written to out, or a negative error code. + */ +int av_hmac_calc(AVHMAC *ctx, const uint8_t *data, unsigned int len, + const uint8_t *key, unsigned int keylen, + uint8_t *out, unsigned int outlen); + +/** + * @} + */ + +#endif /* AVUTIL_HMAC_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext.h b/ffmpeg-n8.1/include/libavutil/hwcontext.h new file mode 100644 index 00000000..29374cf0 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext.h @@ -0,0 +1,601 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_H +#define AVUTIL_HWCONTEXT_H + +#include "buffer.h" +#include "frame.h" +#include "log.h" +#include "pixfmt.h" + +enum AVHWDeviceType { + AV_HWDEVICE_TYPE_NONE, + AV_HWDEVICE_TYPE_VDPAU, + AV_HWDEVICE_TYPE_CUDA, + AV_HWDEVICE_TYPE_VAAPI, + AV_HWDEVICE_TYPE_DXVA2, + AV_HWDEVICE_TYPE_QSV, + AV_HWDEVICE_TYPE_VIDEOTOOLBOX, + AV_HWDEVICE_TYPE_D3D11VA, + AV_HWDEVICE_TYPE_DRM, + AV_HWDEVICE_TYPE_OPENCL, + AV_HWDEVICE_TYPE_MEDIACODEC, + AV_HWDEVICE_TYPE_VULKAN, + AV_HWDEVICE_TYPE_D3D12VA, + AV_HWDEVICE_TYPE_AMF, + /* OpenHarmony Codec device */ + AV_HWDEVICE_TYPE_OHCODEC, +}; + +/** + * This struct aggregates all the (hardware/vendor-specific) "high-level" state, + * i.e. state that is not tied to a concrete processing configuration. + * E.g., in an API that supports hardware-accelerated encoding and decoding, + * this struct will (if possible) wrap the state that is common to both encoding + * and decoding and from which specific instances of encoders or decoders can be + * derived. + * + * This struct is reference-counted with the AVBuffer mechanism. The + * av_hwdevice_ctx_alloc() constructor yields a reference, whose data field + * points to the actual AVHWDeviceContext. Further objects derived from + * AVHWDeviceContext (such as AVHWFramesContext, describing a frame pool with + * specific properties) will hold an internal reference to it. After all the + * references are released, the AVHWDeviceContext itself will be freed, + * optionally invoking a user-specified callback for uninitializing the hardware + * state. + */ +typedef struct AVHWDeviceContext { + /** + * A class for logging. Set by av_hwdevice_ctx_alloc(). + */ + const AVClass *av_class; + + /** + * This field identifies the underlying API used for hardware access. + * + * This field is set when this struct is allocated and never changed + * afterwards. + */ + enum AVHWDeviceType type; + + /** + * The format-specific data, allocated and freed by libavutil along with + * this context. + * + * Should be cast by the user to the format-specific context defined in the + * corresponding header (hwcontext_*.h) and filled as described in the + * documentation before calling av_hwdevice_ctx_init(). + * + * After calling av_hwdevice_ctx_init() this struct should not be modified + * by the caller. + */ + void *hwctx; + + /** + * This field may be set by the caller before calling av_hwdevice_ctx_init(). + * + * If non-NULL, this callback will be called when the last reference to + * this context is unreferenced, immediately before it is freed. + * + * @note when other objects (e.g an AVHWFramesContext) are derived from this + * struct, this callback will be invoked after all such child objects + * are fully uninitialized and their respective destructors invoked. + */ + void (*free)(struct AVHWDeviceContext *ctx); + + /** + * Arbitrary user data, to be used e.g. by the free() callback. + */ + void *user_opaque; +} AVHWDeviceContext; + +/** + * This struct describes a set or pool of "hardware" frames (i.e. those with + * data not located in normal system memory). All the frames in the pool are + * assumed to be allocated in the same way and interchangeable. + * + * This struct is reference-counted with the AVBuffer mechanism and tied to a + * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor + * yields a reference, whose data field points to the actual AVHWFramesContext + * struct. + */ +typedef struct AVHWFramesContext { + /** + * A class for logging. + */ + const AVClass *av_class; + + /** + * A reference to the parent AVHWDeviceContext. This reference is owned and + * managed by the enclosing AVHWFramesContext, but the caller may derive + * additional references from it. + */ + AVBufferRef *device_ref; + + /** + * The parent AVHWDeviceContext. This is simply a pointer to + * device_ref->data provided for convenience. + * + * Set by libavutil in av_hwframe_ctx_init(). + */ + AVHWDeviceContext *device_ctx; + + /** + * The format-specific data, allocated and freed automatically along with + * this context. + * + * The user shall ignore this field if the corresponding format-specific + * header (hwcontext_*.h) does not define a context to be used as + * AVHWFramesContext.hwctx. + * + * Otherwise, it should be cast by the user to said context and filled + * as described in the documentation before calling av_hwframe_ctx_init(). + * + * After any frames using this context are created, the contents of this + * struct should not be modified by the caller. + */ + void *hwctx; + + /** + * This field may be set by the caller before calling av_hwframe_ctx_init(). + * + * If non-NULL, this callback will be called when the last reference to + * this context is unreferenced, immediately before it is freed. + */ + void (*free)(struct AVHWFramesContext *ctx); + + /** + * Arbitrary user data, to be used e.g. by the free() callback. + */ + void *user_opaque; + + /** + * A pool from which the frames are allocated by av_hwframe_get_buffer(). + * This field may be set by the caller before calling av_hwframe_ctx_init(). + * The buffers returned by calling av_buffer_pool_get() on this pool must + * have the properties described in the documentation in the corresponding hw + * type's header (hwcontext_*.h). The pool will be freed strictly before + * this struct's free() callback is invoked. + * + * This field may be NULL, then libavutil will attempt to allocate a pool + * internally. Note that certain device types enforce pools allocated at + * fixed size (frame count), which cannot be extended dynamically. In such a + * case, initial_pool_size must be set appropriately. + */ + AVBufferPool *pool; + + /** + * Initial size of the frame pool. If a device type does not support + * dynamically resizing the pool, then this is also the maximum pool size. + * + * May be set by the caller before calling av_hwframe_ctx_init(). Must be + * set if pool is NULL and the device type does not support dynamic pools. + */ + int initial_pool_size; + + /** + * The pixel format identifying the underlying HW surface type. + * + * Must be a hwaccel format, i.e. the corresponding descriptor must have the + * AV_PIX_FMT_FLAG_HWACCEL flag set. + * + * Must be set by the user before calling av_hwframe_ctx_init(). + */ + enum AVPixelFormat format; + + /** + * The pixel format identifying the actual data layout of the hardware + * frames. + * + * Must be set by the caller before calling av_hwframe_ctx_init(). + * + * @note when the underlying API does not provide the exact data layout, but + * only the colorspace/bit depth, this field should be set to the fully + * planar version of that format (e.g. for 8-bit 420 YUV it should be + * AV_PIX_FMT_YUV420P, not AV_PIX_FMT_NV12 or anything else). + */ + enum AVPixelFormat sw_format; + + /** + * The allocated dimensions of the frames in this pool. + * + * Must be set by the user before calling av_hwframe_ctx_init(). + */ + int width, height; +} AVHWFramesContext; + +/** + * Look up an AVHWDeviceType by name. + * + * @param name String name of the device type (case-insensitive). + * @return The type from enum AVHWDeviceType, or AV_HWDEVICE_TYPE_NONE if + * not found. + */ +enum AVHWDeviceType av_hwdevice_find_type_by_name(const char *name); + +/** Get the string name of an AVHWDeviceType. + * + * @param type Type from enum AVHWDeviceType. + * @return Pointer to a static string containing the name, or NULL if the type + * is not valid. + */ +const char *av_hwdevice_get_type_name(enum AVHWDeviceType type); + +/** + * Iterate over supported device types. + * + * @param prev AV_HWDEVICE_TYPE_NONE initially, then the previous type + * returned by this function in subsequent iterations. + * @return The next usable device type from enum AVHWDeviceType, or + * AV_HWDEVICE_TYPE_NONE if there are no more. + */ +enum AVHWDeviceType av_hwdevice_iterate_types(enum AVHWDeviceType prev); + +/** + * Allocate an AVHWDeviceContext for a given hardware type. + * + * @param type the type of the hardware device to allocate. + * @return a reference to the newly created AVHWDeviceContext on success or NULL + * on failure. + */ +AVBufferRef *av_hwdevice_ctx_alloc(enum AVHWDeviceType type); + +/** + * Finalize the device context before use. This function must be called after + * the context is filled with all the required information and before it is + * used in any way. + * + * @param ref a reference to the AVHWDeviceContext + * @return 0 on success, a negative AVERROR code on failure + */ +int av_hwdevice_ctx_init(AVBufferRef *ref); + +/** + * Open a device of the specified type and create an AVHWDeviceContext for it. + * + * This is a convenience function intended to cover the simple cases. Callers + * who need to fine-tune device creation/management should open the device + * manually and then wrap it in an AVHWDeviceContext using + * av_hwdevice_ctx_alloc()/av_hwdevice_ctx_init(). + * + * The returned context is already initialized and ready for use, the caller + * should not call av_hwdevice_ctx_init() on it. The user_opaque/free fields of + * the created AVHWDeviceContext are set by this function and should not be + * touched by the caller. + * + * @param device_ctx On success, a reference to the newly-created device context + * will be written here. The reference is owned by the caller + * and must be released with av_buffer_unref() when no longer + * needed. On failure, NULL will be written to this pointer. + * @param type The type of the device to create. + * @param device A type-specific string identifying the device to open. + * @param opts A dictionary of additional (type-specific) options to use in + * opening the device. The dictionary remains owned by the caller. + * @param flags currently unused + * + * @return 0 on success, a negative AVERROR code on failure. + */ +int av_hwdevice_ctx_create(AVBufferRef **device_ctx, enum AVHWDeviceType type, + const char *device, AVDictionary *opts, int flags); + +/** + * Create a new device of the specified type from an existing device. + * + * If the source device is a device of the target type or was originally + * derived from such a device (possibly through one or more intermediate + * devices of other types), then this will return a reference to the + * existing device of the same type as is requested. + * + * Otherwise, it will attempt to derive a new device from the given source + * device. If direct derivation to the new type is not implemented, it will + * attempt the same derivation from each ancestor of the source device in + * turn looking for an implemented derivation method. + * + * @param dst_ctx On success, a reference to the newly-created + * AVHWDeviceContext. + * @param type The type of the new device to create. + * @param src_ctx A reference to an existing AVHWDeviceContext which will be + * used to create the new device. + * @param flags Currently unused; should be set to zero. + * @return Zero on success, a negative AVERROR code on failure. + */ +int av_hwdevice_ctx_create_derived(AVBufferRef **dst_ctx, + enum AVHWDeviceType type, + AVBufferRef *src_ctx, int flags); + +/** + * Create a new device of the specified type from an existing device. + * + * This function performs the same action as av_hwdevice_ctx_create_derived, + * however, it is able to set options for the new device to be derived. + * + * @param dst_ctx On success, a reference to the newly-created + * AVHWDeviceContext. + * @param type The type of the new device to create. + * @param src_ctx A reference to an existing AVHWDeviceContext which will be + * used to create the new device. + * @param options Options for the new device to create, same format as in + * av_hwdevice_ctx_create. + * @param flags Currently unused; should be set to zero. + * @return Zero on success, a negative AVERROR code on failure. + */ +int av_hwdevice_ctx_create_derived_opts(AVBufferRef **dst_ctx, + enum AVHWDeviceType type, + AVBufferRef *src_ctx, + AVDictionary *options, int flags); + +/** + * Allocate an AVHWFramesContext tied to a given device context. + * + * @param device_ctx a reference to a AVHWDeviceContext. This function will make + * a new reference for internal use, the one passed to the + * function remains owned by the caller. + * @return a reference to the newly created AVHWFramesContext on success or NULL + * on failure. + */ +AVBufferRef *av_hwframe_ctx_alloc(AVBufferRef *device_ctx); + +/** + * Finalize the context before use. This function must be called after the + * context is filled with all the required information and before it is attached + * to any frames. + * + * @param ref a reference to the AVHWFramesContext + * @return 0 on success, a negative AVERROR code on failure + */ +int av_hwframe_ctx_init(AVBufferRef *ref); + +/** + * Allocate a new frame attached to the given AVHWFramesContext. + * + * @param hwframe_ctx a reference to an AVHWFramesContext + * @param frame an empty (freshly allocated or unreffed) frame to be filled with + * newly allocated buffers. + * @param flags currently unused, should be set to zero + * @return 0 on success, a negative AVERROR code on failure + */ +int av_hwframe_get_buffer(AVBufferRef *hwframe_ctx, AVFrame *frame, int flags); + +/** + * Copy data to or from a hw surface. At least one of dst/src must have an + * AVHWFramesContext attached. + * + * If src has an AVHWFramesContext attached, then the format of dst (if set) + * must use one of the formats returned by av_hwframe_transfer_get_formats(src, + * AV_HWFRAME_TRANSFER_DIRECTION_FROM). + * If dst has an AVHWFramesContext attached, then the format of src must use one + * of the formats returned by av_hwframe_transfer_get_formats(dst, + * AV_HWFRAME_TRANSFER_DIRECTION_TO) + * + * dst may be "clean" (i.e. with data/buf pointers unset), in which case the + * data buffers will be allocated by this function using av_frame_get_buffer(). + * If dst->format is set, then this format will be used, otherwise (when + * dst->format is AV_PIX_FMT_NONE) the first acceptable format will be chosen. + * + * The two frames must have matching allocated dimensions (i.e. equal to + * AVHWFramesContext.width/height), since not all device types support + * transferring a sub-rectangle of the whole surface. The display dimensions + * (i.e. AVFrame.width/height) may be smaller than the allocated dimensions, but + * also have to be equal for both frames. When the display dimensions are + * smaller than the allocated dimensions, the content of the padding in the + * destination frame is unspecified. + * + * @param dst the destination frame. dst is not touched on failure. + * @param src the source frame. + * @param flags currently unused, should be set to zero + * @return 0 on success, a negative AVERROR error code on failure. + */ +int av_hwframe_transfer_data(AVFrame *dst, const AVFrame *src, int flags); + +enum AVHWFrameTransferDirection { + /** + * Transfer the data from the queried hw frame. + */ + AV_HWFRAME_TRANSFER_DIRECTION_FROM, + + /** + * Transfer the data to the queried hw frame. + */ + AV_HWFRAME_TRANSFER_DIRECTION_TO, +}; + +/** + * Get a list of possible source or target formats usable in + * av_hwframe_transfer_data(). + * + * @param hwframe_ctx the frame context to obtain the information for + * @param dir the direction of the transfer + * @param formats the pointer to the output format list will be written here. + * The list is terminated with AV_PIX_FMT_NONE and must be freed + * by the caller when no longer needed using av_free(). + * If this function returns successfully, the format list will + * have at least one item (not counting the terminator). + * On failure, the contents of this pointer are unspecified. + * @param flags currently unused, should be set to zero + * @return 0 on success, a negative AVERROR code on failure. + */ +int av_hwframe_transfer_get_formats(AVBufferRef *hwframe_ctx, + enum AVHWFrameTransferDirection dir, + enum AVPixelFormat **formats, int flags); + + +/** + * This struct describes the constraints on hardware frames attached to + * a given device with a hardware-specific configuration. This is returned + * by av_hwdevice_get_hwframe_constraints() and must be freed by + * av_hwframe_constraints_free() after use. + */ +typedef struct AVHWFramesConstraints { + /** + * A list of possible values for format in the hw_frames_ctx, + * terminated by AV_PIX_FMT_NONE. This member will always be filled. + */ + enum AVPixelFormat *valid_hw_formats; + + /** + * A list of possible values for sw_format in the hw_frames_ctx, + * terminated by AV_PIX_FMT_NONE. Can be NULL if this information is + * not known. + */ + enum AVPixelFormat *valid_sw_formats; + + /** + * The minimum size of frames in this hw_frames_ctx. + * (Zero if not known.) + */ + int min_width; + int min_height; + + /** + * The maximum size of frames in this hw_frames_ctx. + * (INT_MAX if not known / no limit.) + */ + int max_width; + int max_height; +} AVHWFramesConstraints; + +/** + * Allocate a HW-specific configuration structure for a given HW device. + * After use, the user must free all members as required by the specific + * hardware structure being used, then free the structure itself with + * av_free(). + * + * @param device_ctx a reference to the associated AVHWDeviceContext. + * @return The newly created HW-specific configuration structure on + * success or NULL on failure. + */ +void *av_hwdevice_hwconfig_alloc(AVBufferRef *device_ctx); + +/** + * Get the constraints on HW frames given a device and the HW-specific + * configuration to be used with that device. If no HW-specific + * configuration is provided, returns the maximum possible capabilities + * of the device. + * + * @param ref a reference to the associated AVHWDeviceContext. + * @param hwconfig a filled HW-specific configuration structure, or NULL + * to return the maximum possible capabilities of the device. + * @return AVHWFramesConstraints structure describing the constraints + * on the device, or NULL if not available. + */ +AVHWFramesConstraints *av_hwdevice_get_hwframe_constraints(AVBufferRef *ref, + const void *hwconfig); + +/** + * Free an AVHWFrameConstraints structure. + * + * @param constraints The (filled or unfilled) AVHWFrameConstraints structure. + */ +void av_hwframe_constraints_free(AVHWFramesConstraints **constraints); + + +/** + * Flags to apply to frame mappings. + */ +enum { + /** + * The mapping must be readable. + */ + AV_HWFRAME_MAP_READ = 1 << 0, + /** + * The mapping must be writeable. + */ + AV_HWFRAME_MAP_WRITE = 1 << 1, + /** + * The mapped frame will be overwritten completely in subsequent + * operations, so the current frame data need not be loaded. Any values + * which are not overwritten are unspecified. + */ + AV_HWFRAME_MAP_OVERWRITE = 1 << 2, + /** + * The mapping must be direct. That is, there must not be any copying in + * the map or unmap steps. Note that performance of direct mappings may + * be much lower than normal memory. + */ + AV_HWFRAME_MAP_DIRECT = 1 << 3, +}; + +/** + * Map a hardware frame. + * + * This has a number of different possible effects, depending on the format + * and origin of the src and dst frames. On input, src should be a usable + * frame with valid buffers and dst should be blank (typically as just created + * by av_frame_alloc()). src should have an associated hwframe context, and + * dst may optionally have a format and associated hwframe context. + * + * If src was created by mapping a frame from the hwframe context of dst, + * then this function undoes the mapping - dst is replaced by a reference to + * the frame that src was originally mapped from. + * + * If both src and dst have an associated hwframe context, then this function + * attempts to map the src frame from its hardware context to that of dst and + * then fill dst with appropriate data to be usable there. This will only be + * possible if the hwframe contexts and associated devices are compatible - + * given compatible devices, av_hwframe_ctx_create_derived() can be used to + * create a hwframe context for dst in which mapping should be possible. + * + * If src has a hwframe context but dst does not, then the src frame is + * mapped to normal memory and should thereafter be usable as a normal frame. + * If the format is set on dst, then the mapping will attempt to create dst + * with that format and fail if it is not possible. If format is unset (is + * AV_PIX_FMT_NONE) then dst will be mapped with whatever the most appropriate + * format to use is (probably the sw_format of the src hwframe context). + * + * A return value of AVERROR(ENOSYS) indicates that the mapping is not + * possible with the given arguments and hwframe setup, while other return + * values indicate that it failed somehow. + * + * On failure, the destination frame will be left blank, except for the + * hw_frames_ctx/format fields they may have been set by the caller - those will + * be preserved as they were. + * + * @param dst Destination frame, to contain the mapping. + * @param src Source frame, to be mapped. + * @param flags Some combination of AV_HWFRAME_MAP_* flags. + * @return Zero on success, negative AVERROR code on failure. + */ +int av_hwframe_map(AVFrame *dst, const AVFrame *src, int flags); + + +/** + * Create and initialise an AVHWFramesContext as a mapping of another existing + * AVHWFramesContext on a different device. + * + * av_hwframe_ctx_init() should not be called after this. + * + * @param derived_frame_ctx On success, a reference to the newly created + * AVHWFramesContext. + * @param format The AVPixelFormat for the derived context. + * @param derived_device_ctx A reference to the device to create the new + * AVHWFramesContext on. + * @param source_frame_ctx A reference to an existing AVHWFramesContext + * which will be mapped to the derived context. + * @param flags Some combination of AV_HWFRAME_MAP_* flags, defining the + * mapping parameters to apply to frames which are allocated + * in the derived device. + * @return Zero on success, negative AVERROR code on failure. + */ +int av_hwframe_ctx_create_derived(AVBufferRef **derived_frame_ctx, + enum AVPixelFormat format, + AVBufferRef *derived_device_ctx, + AVBufferRef *source_frame_ctx, + int flags); + +#endif /* AVUTIL_HWCONTEXT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_amf.h b/ffmpeg-n8.1/include/libavutil/hwcontext_amf.h new file mode 100644 index 00000000..6f2cabc8 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_amf.h @@ -0,0 +1,50 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + + +#ifndef AVUTIL_HWCONTEXT_AMF_H +#define AVUTIL_HWCONTEXT_AMF_H + +#include "pixfmt.h" +#include "hwcontext.h" +#include +#include +#include +#include + +/** + * This struct is allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVAMFDeviceContext { + void * library; + AMFFactory *factory; + void *trace_writer; + + int64_t version; ///< version of AMF runtime + AMFContext *context; + AMF_MEMORY_TYPE memory_type; + + void (*lock)(void *lock_ctx); + void (*unlock)(void *lock_ctx); + void *lock_ctx; +} AVAMFDeviceContext; + +enum AMF_SURFACE_FORMAT av_av_to_amf_format(enum AVPixelFormat fmt); +enum AVPixelFormat av_amf_to_av_format(enum AMF_SURFACE_FORMAT fmt); + +#endif /* AVUTIL_HWCONTEXT_AMF_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_cuda.h b/ffmpeg-n8.1/include/libavutil/hwcontext_cuda.h new file mode 100644 index 00000000..cbad434f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_cuda.h @@ -0,0 +1,74 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + + +#ifndef AVUTIL_HWCONTEXT_CUDA_H +#define AVUTIL_HWCONTEXT_CUDA_H + +#ifndef CUDA_VERSION +#include +#endif + +#include "pixfmt.h" + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_CUDA. + * + * This API supports dynamic frame pools. AVHWFramesContext.pool must return + * AVBufferRefs whose data pointer is a CUdeviceptr. + */ + +typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal; + +/** + * This struct is allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVCUDADeviceContext { + CUcontext cuda_ctx; + CUstream stream; + AVCUDADeviceContextInternal *internal; +} AVCUDADeviceContext; + +/** + * AVHWFramesContext.hwctx is currently not used + */ + +/** + * @defgroup hwcontext_cuda Device context creation flags + * + * Flags for av_hwdevice_ctx_create. + * + * @{ + */ + +/** + * Use primary device context instead of creating a new one. + */ +#define AV_CUDA_USE_PRIMARY_CONTEXT (1 << 0) + +/** + * Use current device context instead of creating a new one. + */ +#define AV_CUDA_USE_CURRENT_CONTEXT (1 << 1) + +/** + * @} + */ + +#endif /* AVUTIL_HWCONTEXT_CUDA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_d3d11va.h b/ffmpeg-n8.1/include/libavutil/hwcontext_d3d11va.h new file mode 100644 index 00000000..b87b1e8f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_d3d11va.h @@ -0,0 +1,192 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_D3D11VA_H +#define AVUTIL_HWCONTEXT_D3D11VA_H + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_D3D11VA. + * + * The default pool implementation will be fixed-size if initial_pool_size is + * set (and allocate elements from an array texture). Otherwise it will allocate + * individual textures. Be aware that decoding requires a single array texture. + * + * Using sw_format==AV_PIX_FMT_YUV420P has special semantics, and maps to + * DXGI_FORMAT_420_OPAQUE. av_hwframe_transfer_data() is not supported for + * this format. Refer to MSDN for details. + * + * av_hwdevice_ctx_create() for this device type supports a key named "debug" + * for the AVDictionary entry. If this is set to any value, the device creation + * code will try to load various supported D3D debugging layers. + */ + +#include +#include + +/** + * This struct is allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVD3D11VADeviceContext { + /** + * Device used for texture creation and access. This can also be used to + * set the libavcodec decoding device. + * + * Must be set by the user. This is the only mandatory field - the other + * device context fields are set from this and are available for convenience. + * + * Deallocating the AVHWDeviceContext will always release this interface, + * and it does not matter whether it was user-allocated. + */ + ID3D11Device *device; + + /** + * If unset, this will be set from the device field on init. + * + * Deallocating the AVHWDeviceContext will always release this interface, + * and it does not matter whether it was user-allocated. + */ + ID3D11DeviceContext *device_context; + + /** + * If unset, this will be set from the device field on init. + * + * Deallocating the AVHWDeviceContext will always release this interface, + * and it does not matter whether it was user-allocated. + */ + ID3D11VideoDevice *video_device; + + /** + * If unset, this will be set from the device_context field on init. + * + * Deallocating the AVHWDeviceContext will always release this interface, + * and it does not matter whether it was user-allocated. + */ + ID3D11VideoContext *video_context; + + /** + * Callbacks for locking. They protect accesses to device_context and + * video_context calls. They also protect access to the internal staging + * texture (for av_hwframe_transfer_data() calls). They do NOT protect + * access to hwcontext or decoder state in general. + * + * If unset on init, the hwcontext implementation will set them to use an + * internal mutex. + * + * The underlying lock must be recursive. lock_ctx is for free use by the + * locking implementation. + */ + void (*lock)(void *lock_ctx); + void (*unlock)(void *lock_ctx); + void *lock_ctx; + /** + * D3D11_TEXTURE2D_DESC.BindFlags to be applied to D3D11 resources allocated + * for frames using this device context. + * + * It applies globally to all AVD3D11VAFramesContext allocated from this device context. + */ + UINT BindFlags; + /** + * D3D11_TEXTURE2D_DESC.MiscFlags to be applied to D3D11 resources allocated + * for frames using this device context. + * + * It applies globally to all AVD3D11VAFramesContext allocated from this device context. + */ + UINT MiscFlags; +} AVD3D11VADeviceContext; + +/** + * D3D11 frame descriptor for pool allocation. + * + * In user-allocated pools, AVHWFramesContext.pool must return AVBufferRefs + * with the data pointer pointing at an object of this type describing the + * planes of the frame. + * + * This has no use outside of custom allocation, and AVFrame AVBufferRef do not + * necessarily point to an instance of this struct. + */ +typedef struct AVD3D11FrameDescriptor { + /** + * The texture in which the frame is located. The reference count is + * managed by the AVBufferRef, and destroying the reference will release + * the interface. + * + * Normally stored in AVFrame.data[0]. + */ + ID3D11Texture2D *texture; + + /** + * The index into the array texture element representing the frame, or 0 + * if the texture is not an array texture. + * + * Normally stored in AVFrame.data[1] (cast from intptr_t). + */ + intptr_t index; +} AVD3D11FrameDescriptor; + +/** + * This struct is allocated as AVHWFramesContext.hwctx + */ +typedef struct AVD3D11VAFramesContext { + /** + * The canonical texture used for pool allocation. If this is set to NULL + * on init, the hwframes implementation will allocate and set an array + * texture if initial_pool_size > 0. + * + * The only situation when the API user should set this is: + * - the user wants to do manual pool allocation (setting + * AVHWFramesContext.pool), instead of letting AVHWFramesContext + * allocate the pool + * - of an array texture + * - and wants it to use it for decoding + * - this has to be done before calling av_hwframe_ctx_init() + * + * Deallocating the AVHWFramesContext will always release this interface, + * and it does not matter whether it was user-allocated. + * + * This is in particular used by the libavcodec D3D11VA hwaccel, which + * requires a single array texture. It will create ID3D11VideoDecoderOutputView + * objects for each array texture element on decoder initialization. + */ + ID3D11Texture2D *texture; + + /** + * D3D11_TEXTURE2D_DESC.BindFlags used for texture creation. The user must + * at least set D3D11_BIND_DECODER if the frames context is to be used for + * video decoding. + * This field is ignored/invalid if a user-allocated texture is provided. + */ + UINT BindFlags; + + /** + * D3D11_TEXTURE2D_DESC.MiscFlags used for texture creation. + * This field is ignored/invalid if a user-allocated texture is provided. + */ + UINT MiscFlags; + + /** + * In case if texture structure member above is not NULL contains the same texture + * pointer for all elements and different indexes into the array texture. + * In case if texture structure member above is NULL, all elements contains + * pointers to separate non-array textures and 0 indexes. + * This field is ignored/invalid if a user-allocated texture is provided. + */ + AVD3D11FrameDescriptor *texture_infos; +} AVD3D11VAFramesContext; + +#endif /* AVUTIL_HWCONTEXT_D3D11VA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_d3d12va.h b/ffmpeg-n8.1/include/libavutil/hwcontext_d3d12va.h new file mode 100644 index 00000000..adbec881 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_d3d12va.h @@ -0,0 +1,209 @@ +/* + * Direct3D 12 HW acceleration. + * + * copyright (c) 2022-2023 Wu Jianhua + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_D3D12VA_H +#define AVUTIL_HWCONTEXT_D3D12VA_H + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_D3D12VA. + * + * AVHWFramesContext.pool must contain AVBufferRefs whose + * data pointer points to an AVD3D12VAFrame struct. + */ +#include +#include +#include +#include +#include + +/** + * @brief This struct is allocated as AVHWDeviceContext.hwctx + * + */ +typedef struct AVD3D12VADeviceContext { + /** + * Device used for objects creation and access. This can also be + * used to set the libavcodec decoding device. + * + * Can be set by the user. This is the only mandatory field - the other + * device context fields are set from this and are available for convenience. + * + * Deallocating the AVHWDeviceContext will always release this interface, + * and it does not matter whether it was user-allocated. + */ + ID3D12Device *device; + + /** + * If unset, this will be set from the device field on init. + * + * Deallocating the AVHWDeviceContext will always release this interface, + * and it does not matter whether it was user-allocated. + */ + ID3D12VideoDevice *video_device; + + /** + * Callbacks for locking. They protect access to the internal staging + * texture (for av_hwframe_transfer_data() calls). They do NOT protect + * access to hwcontext or decoder state in general. + * + * If unset on init, the hwcontext implementation will set them to use an + * internal mutex. + * + * The underlying lock must be recursive. lock_ctx is for free use by the + * locking implementation. + */ + void (*lock)(void *lock_ctx); + void (*unlock)(void *lock_ctx); + void *lock_ctx; + + /** + * Resource flags to be applied to D3D12 resources allocated + * for frames using this device context. + * + * If unset, this will be D3D12_RESOURCE_FLAG_NONE. + * + * It applies globally to all AVD3D12VAFramesContext allocated from this device context. + */ + D3D12_RESOURCE_FLAGS resource_flags; + + /** + * Heap flags to be applied to D3D12 resources allocated + * for frames using this device context. + * + * If unset, this will be D3D12_HEAP_FLAG_NONE. + * + * It applies globally to all AVD3D12VAFramesContext allocated from this device context. + */ + D3D12_HEAP_FLAGS heap_flags; +} AVD3D12VADeviceContext; + +/** + * @brief This struct is used to sync d3d12 execution + * + */ +typedef struct AVD3D12VASyncContext { + /** + * D3D12 fence object + */ + ID3D12Fence *fence; + + /** + * A handle to the event object that's raised when the fence + * reaches a certain value. + */ + HANDLE event; + + /** + * The fence value used for sync + */ + uint64_t fence_value; +} AVD3D12VASyncContext; + +/** + * Define the behaviours of frame allocation. + */ +typedef enum AVD3D12VAFrameFlags { + AV_D3D12VA_FRAME_FLAG_NONE = 0, + + /** + * Indicates that frame data should be allocated using a texture array resource. + */ + AV_D3D12VA_FRAME_FLAG_TEXTURE_ARRAY = (1 << 1), +} AVD3D12VAFrameFlags; + +/** + * @brief D3D12VA frame descriptor for pool allocation. + * + */ +typedef struct AVD3D12VAFrame { + /** + * The texture in which the frame is located. The reference count is + * managed by the AVBufferRef, and destroying the reference will release + * the interface. + */ + ID3D12Resource *texture; + + /** + * Index of the subresource within the texture. + * + * In texture array mode, this specifies the array slice index. + * When texture array mode is not used, this value is always 0. + */ + int subresource_index; + + /** + * The sync context for the texture + * + * @see: https://learn.microsoft.com/en-us/windows/win32/medfound/direct3d-12-video-overview#directx-12-fences + */ + AVD3D12VASyncContext sync_ctx; + + /** + * A combination of AVD3D12VAFrameFlags. + * Set by AVD3D12VAFramesContext. + */ + AVD3D12VAFrameFlags flags; +} AVD3D12VAFrame; + +/** + * @brief This struct is allocated as AVHWFramesContext.hwctx + * + */ +typedef struct AVD3D12VAFramesContext { + /** + * DXGI_FORMAT format. MUST be compatible with the pixel format. + * If unset, will be automatically set. + */ + DXGI_FORMAT format; + + /** + * Options for working with resources. + * If unset, this will be D3D12_RESOURCE_FLAG_NONE. + * + * @see https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_resource_flags + */ + D3D12_RESOURCE_FLAGS resource_flags; + + /** + * Options for working with heaps allocation when creating resources. + * If unset, this will be D3D12_HEAP_FLAG_NONE. + * + * @see https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_heap_flags + */ + D3D12_HEAP_FLAGS heap_flags; + + /** + * In texture array mode, the D3D12 uses the same texture array (resource)for all + * pictures. + */ + ID3D12Resource *texture_array; + + /** + * A combination of AVD3D12VAFrameFlags. Unless AV_D3D12VA_FRAME_FLAG_NONE is set, + * autodetected flags will be OR'd based on the device and frame features during + * av_hwframe_ctx_init(). + */ + AVD3D12VAFrameFlags flags; +} AVD3D12VAFramesContext; + +#endif /* AVUTIL_HWCONTEXT_D3D12VA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_drm.h b/ffmpeg-n8.1/include/libavutil/hwcontext_drm.h new file mode 100644 index 00000000..42709f21 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_drm.h @@ -0,0 +1,169 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_DRM_H +#define AVUTIL_HWCONTEXT_DRM_H + +#include +#include + +/** + * @file + * API-specific header for AV_HWDEVICE_TYPE_DRM. + * + * Internal frame allocation is not currently supported - all frames + * must be allocated by the user. Thus AVHWFramesContext is always + * NULL, though this may change if support for frame allocation is + * added in future. + */ + +enum { + /** + * The maximum number of layers/planes in a DRM frame. + */ + AV_DRM_MAX_PLANES = 4 +}; + +/** + * DRM object descriptor. + * + * Describes a single DRM object, addressing it as a PRIME file + * descriptor. + */ +typedef struct AVDRMObjectDescriptor { + /** + * DRM PRIME fd for the object. + */ + int fd; + /** + * Total size of the object. + * + * (This includes any parts not which do not contain image data.) + */ + size_t size; + /** + * Format modifier applied to the object (DRM_FORMAT_MOD_*). + * + * If the format modifier is unknown then this should be set to + * DRM_FORMAT_MOD_INVALID. + */ + uint64_t format_modifier; +} AVDRMObjectDescriptor; + +/** + * DRM plane descriptor. + * + * Describes a single plane of a layer, which is contained within + * a single object. + */ +typedef struct AVDRMPlaneDescriptor { + /** + * Index of the object containing this plane in the objects + * array of the enclosing frame descriptor. + */ + int object_index; + /** + * Offset within that object of this plane. + */ + ptrdiff_t offset; + /** + * Pitch (linesize) of this plane. + */ + ptrdiff_t pitch; +} AVDRMPlaneDescriptor; + +/** + * DRM layer descriptor. + * + * Describes a single layer within a frame. This has the structure + * defined by its format, and will contain one or more planes. + */ +typedef struct AVDRMLayerDescriptor { + /** + * Format of the layer (DRM_FORMAT_*). + */ + uint32_t format; + /** + * Number of planes in the layer. + * + * This must match the number of planes required by format. + */ + int nb_planes; + /** + * Array of planes in this layer. + */ + AVDRMPlaneDescriptor planes[AV_DRM_MAX_PLANES]; +} AVDRMLayerDescriptor; + +/** + * DRM frame descriptor. + * + * This is used as the data pointer for AV_PIX_FMT_DRM_PRIME frames. + * It is also used by user-allocated frame pools - allocating in + * AVHWFramesContext.pool must return AVBufferRefs which contain + * an object of this type. + * + * The fields of this structure should be set such it can be + * imported directly by EGL using the EGL_EXT_image_dma_buf_import + * and EGL_EXT_image_dma_buf_import_modifiers extensions. + * (Note that the exact layout of a particular format may vary between + * platforms - we only specify that the same platform should be able + * to import it.) + * + * The total number of planes must not exceed AV_DRM_MAX_PLANES, and + * the order of the planes by increasing layer index followed by + * increasing plane index must be the same as the order which would + * be used for the data pointers in the equivalent software format. + */ +typedef struct AVDRMFrameDescriptor { + /** + * Number of DRM objects making up this frame. + */ + int nb_objects; + /** + * Array of objects making up the frame. + */ + AVDRMObjectDescriptor objects[AV_DRM_MAX_PLANES]; + /** + * Number of layers in the frame. + */ + int nb_layers; + /** + * Array of layers in the frame. + */ + AVDRMLayerDescriptor layers[AV_DRM_MAX_PLANES]; +} AVDRMFrameDescriptor; + +/** + * DRM device. + * + * Allocated as AVHWDeviceContext.hwctx. + */ +typedef struct AVDRMDeviceContext { + /** + * File descriptor of DRM device. + * + * This is used as the device to create frames on, and may also be + * used in some derivation and mapping operations. + * + * If no device is required, set to -1. + */ + int fd; +} AVDRMDeviceContext; + +#endif /* AVUTIL_HWCONTEXT_DRM_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_dxva2.h b/ffmpeg-n8.1/include/libavutil/hwcontext_dxva2.h new file mode 100644 index 00000000..e1b79bc0 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_dxva2.h @@ -0,0 +1,75 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + + +#ifndef AVUTIL_HWCONTEXT_DXVA2_H +#define AVUTIL_HWCONTEXT_DXVA2_H + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_DXVA2. + * + * Only fixed-size pools are supported. + * + * For user-allocated pools, AVHWFramesContext.pool must return AVBufferRefs + * with the data pointer set to a pointer to IDirect3DSurface9. + */ + +#include +#include + +/** + * This struct is allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVDXVA2DeviceContext { + IDirect3DDeviceManager9 *devmgr; +} AVDXVA2DeviceContext; + +/** + * This struct is allocated as AVHWFramesContext.hwctx + */ +typedef struct AVDXVA2FramesContext { + /** + * The surface type (e.g. DXVA2_VideoProcessorRenderTarget or + * DXVA2_VideoDecoderRenderTarget). Must be set by the caller. + */ + DWORD surface_type; + + /** + * The surface pool. When an external pool is not provided by the caller, + * this will be managed (allocated and filled on init, freed on uninit) by + * libavutil. + */ + IDirect3DSurface9 **surfaces; + int nb_surfaces; + + /** + * Certain drivers require the decoder to be destroyed before the surfaces. + * To allow internally managed pools to work properly in such cases, this + * field is provided. + * + * If it is non-NULL, libavutil will call IDirectXVideoDecoder_Release() on + * it just before the internal surface pool is freed. + * + * This is for convenience only. Some code uses other methods to manage the + * decoder reference. + */ + IDirectXVideoDecoder *decoder_to_release; +} AVDXVA2FramesContext; + +#endif /* AVUTIL_HWCONTEXT_DXVA2_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_mediacodec.h b/ffmpeg-n8.1/include/libavutil/hwcontext_mediacodec.h new file mode 100644 index 00000000..fc0263ca --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_mediacodec.h @@ -0,0 +1,61 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_MEDIACODEC_H +#define AVUTIL_HWCONTEXT_MEDIACODEC_H + +/** + * MediaCodec details. + * + * Allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVMediaCodecDeviceContext { + /** + * android/view/Surface handle, to be filled by the user. + * + * This is the default surface used by decoders on this device. + */ + void *surface; + + /** + * Pointer to ANativeWindow. + * + * It both surface and native_window is NULL, try to create it + * automatically if create_window is true and OS support + * createPersistentInputSurface. + * + * It can be used as output surface for decoder and input surface for + * encoder. + */ + void *native_window; + + /** + * Enable createPersistentInputSurface automatically. + * + * Disabled by default. + * + * It can be enabled by setting this flag directly, or by setting + * AVDictionary of av_hwdevice_ctx_create(), with "create_window" as key. + * The second method is useful for ffmpeg cmdline, e.g., we can enable it + * via: + * -init_hw_device mediacodec=mediacodec,create_window=1 + */ + int create_window; +} AVMediaCodecDeviceContext; + +#endif /* AVUTIL_HWCONTEXT_MEDIACODEC_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_oh.h b/ffmpeg-n8.1/include/libavutil/hwcontext_oh.h new file mode 100644 index 00000000..2794f85b --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_oh.h @@ -0,0 +1,34 @@ +/* + * This file is part of FFmpeg. + * + * Copyright (c) 2025 Zhao Zhili + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_OH_H +#define AVUTIL_HWCONTEXT_OH_H + +/** + * OpenHarmony codec device + */ +typedef struct AVOHCodecDeviceContext { + /** + * Pointer to OHNativeWindow + */ + void *native_window; +} AVOHCodecDeviceContext; + +#endif /* AVUTIL_HWCONTEXT_OH_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_opencl.h b/ffmpeg-n8.1/include/libavutil/hwcontext_opencl.h new file mode 100644 index 00000000..22702300 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_opencl.h @@ -0,0 +1,100 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_OPENCL_H +#define AVUTIL_HWCONTEXT_OPENCL_H + +#ifdef __APPLE__ +#include +#else +#include +#endif + +#include "frame.h" + +/** + * @file + * API-specific header for AV_HWDEVICE_TYPE_OPENCL. + * + * Pools allocated internally are always dynamic, and are primarily intended + * to be used in OpenCL-only cases. If interoperation is required, it is + * typically required to allocate frames in the other API and then map the + * frames context to OpenCL with av_hwframe_ctx_create_derived(). + */ + +/** + * OpenCL frame descriptor for pool allocation. + * + * In user-allocated pools, AVHWFramesContext.pool must return AVBufferRefs + * with the data pointer pointing at an object of this type describing the + * planes of the frame. + */ +typedef struct AVOpenCLFrameDescriptor { + /** + * Number of planes in the frame. + */ + int nb_planes; + /** + * OpenCL image2d objects for each plane of the frame. + */ + cl_mem planes[AV_NUM_DATA_POINTERS]; +} AVOpenCLFrameDescriptor; + +/** + * OpenCL device details. + * + * Allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVOpenCLDeviceContext { + /** + * The primary device ID of the device. If multiple OpenCL devices + * are associated with the context then this is the one which will + * be used for all operations internal to FFmpeg. + */ + cl_device_id device_id; + /** + * The OpenCL context which will contain all operations and frames on + * this device. + */ + cl_context context; + /** + * The default command queue for this device, which will be used by all + * frames contexts which do not have their own command queue. If not + * initialised by the user, a default queue will be created on the + * primary device. + */ + cl_command_queue command_queue; +} AVOpenCLDeviceContext; + +/** + * OpenCL-specific data associated with a frame pool. + * + * Allocated as AVHWFramesContext.hwctx. + */ +typedef struct AVOpenCLFramesContext { + /** + * The command queue used for internal asynchronous operations on this + * device (av_hwframe_transfer_data(), av_hwframe_map()). + * + * If this is not set, the command queue from the associated device is + * used instead. + */ + cl_command_queue command_queue; +} AVOpenCLFramesContext; + +#endif /* AVUTIL_HWCONTEXT_OPENCL_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_qsv.h b/ffmpeg-n8.1/include/libavutil/hwcontext_qsv.h new file mode 100644 index 00000000..3c16a8ab --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_qsv.h @@ -0,0 +1,86 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_QSV_H +#define AVUTIL_HWCONTEXT_QSV_H + +#include + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_QSV. + * + * AVHWFramesContext.pool must contain AVBufferRefs whose data pointer points + * to a mfxFrameSurface1 struct. + */ + +/** + * This struct is allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVQSVDeviceContext { + mfxSession session; + /** + * The mfxLoader handle used for mfxSession creation + * + * This field is only available for oneVPL user. For non-oneVPL user, this + * field must be set to NULL. + * + * Filled by the user before calling av_hwdevice_ctx_init() and should be + * cast to mfxLoader handle. Deallocating the AVHWDeviceContext will always + * release this interface. + */ + void *loader; +} AVQSVDeviceContext; + +/** + * This struct is allocated as AVHWFramesContext.hwctx + */ +typedef struct AVQSVFramesContext { + /** + * A pointer to a mfxFrameSurface1 struct + * + * It is available when nb_surfaces is non-zero. + */ + mfxFrameSurface1 *surfaces; + + /** + * Number of frames in the pool + * + * It is 0 for dynamic frame pools or AVHWFramesContext.initial_pool_size + * for fixed frame pools. + * + * Note only oneVPL GPU runtime 2.9+ can support dynamic frame pools + * on d3d11va or vaapi + */ + int nb_surfaces; + + /** + * A combination of MFX_MEMTYPE_* describing the frame pool. + */ + int frame_type; + + /** + * A pointer to a mfxFrameInfo struct + * + * It is available when nb_surfaces is 0, all buffers allocated from the + * pool have the same mfxFrameInfo. + */ + mfxFrameInfo *info; +} AVQSVFramesContext; + +#endif /* AVUTIL_HWCONTEXT_QSV_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_vaapi.h b/ffmpeg-n8.1/include/libavutil/hwcontext_vaapi.h new file mode 100644 index 00000000..82e4194a --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_vaapi.h @@ -0,0 +1,117 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_VAAPI_H +#define AVUTIL_HWCONTEXT_VAAPI_H + +#include + +/** + * @file + * API-specific header for AV_HWDEVICE_TYPE_VAAPI. + * + * Dynamic frame pools are supported, but note that any pool used as a render + * target is required to be of fixed size in order to be usable as an + * argument to vaCreateContext(). + * + * For user-allocated pools, AVHWFramesContext.pool must return AVBufferRefs + * with the data pointer set to a VASurfaceID. + */ + +enum { + /** + * The quirks field has been set by the user and should not be detected + * automatically by av_hwdevice_ctx_init(). + */ + AV_VAAPI_DRIVER_QUIRK_USER_SET = (1 << 0), + /** + * The driver does not destroy parameter buffers when they are used by + * vaRenderPicture(). Additional code will be required to destroy them + * separately afterwards. + */ + AV_VAAPI_DRIVER_QUIRK_RENDER_PARAM_BUFFERS = (1 << 1), + + /** + * The driver does not support the VASurfaceAttribMemoryType attribute, + * so the surface allocation code will not try to use it. + */ + AV_VAAPI_DRIVER_QUIRK_ATTRIB_MEMTYPE = (1 << 2), + + /** + * The driver does not support surface attributes at all. + * The surface allocation code will never pass them to surface allocation, + * and the results of the vaQuerySurfaceAttributes() call will be faked. + */ + AV_VAAPI_DRIVER_QUIRK_SURFACE_ATTRIBUTES = (1 << 3), +}; + +/** + * VAAPI connection details. + * + * Allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVVAAPIDeviceContext { + /** + * The VADisplay handle, to be filled by the user. + */ + VADisplay display; + /** + * Driver quirks to apply - this is filled by av_hwdevice_ctx_init(), + * with reference to a table of known drivers, unless the + * AV_VAAPI_DRIVER_QUIRK_USER_SET bit is already present. The user + * may need to refer to this field when performing any later + * operations using VAAPI with the same VADisplay. + */ + unsigned int driver_quirks; +} AVVAAPIDeviceContext; + +/** + * VAAPI-specific data associated with a frame pool. + * + * Allocated as AVHWFramesContext.hwctx. + */ +typedef struct AVVAAPIFramesContext { + /** + * Set by the user to apply surface attributes to all surfaces in + * the frame pool. If null, default settings are used. + */ + VASurfaceAttrib *attributes; + int nb_attributes; + /** + * The surfaces IDs of all surfaces in the pool after creation. + * Only valid if AVHWFramesContext.initial_pool_size was positive. + * These are intended to be used as the render_targets arguments to + * vaCreateContext(). + */ + VASurfaceID *surface_ids; + int nb_surfaces; +} AVVAAPIFramesContext; + +/** + * VAAPI hardware pipeline configuration details. + * + * Allocated with av_hwdevice_hwconfig_alloc(). + */ +typedef struct AVVAAPIHWConfig { + /** + * ID of a VAAPI pipeline configuration. + */ + VAConfigID config_id; +} AVVAAPIHWConfig; + +#endif /* AVUTIL_HWCONTEXT_VAAPI_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_vdpau.h b/ffmpeg-n8.1/include/libavutil/hwcontext_vdpau.h new file mode 100644 index 00000000..1b7ea1e4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_vdpau.h @@ -0,0 +1,44 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_VDPAU_H +#define AVUTIL_HWCONTEXT_VDPAU_H + +#include + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_VDPAU. + * + * This API supports dynamic frame pools. AVHWFramesContext.pool must return + * AVBufferRefs whose data pointer is a VdpVideoSurface. + */ + +/** + * This struct is allocated as AVHWDeviceContext.hwctx + */ +typedef struct AVVDPAUDeviceContext { + VdpDevice device; + VdpGetProcAddress *get_proc_address; +} AVVDPAUDeviceContext; + +/** + * AVHWFramesContext.hwctx is currently not used + */ + +#endif /* AVUTIL_HWCONTEXT_VDPAU_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_videotoolbox.h b/ffmpeg-n8.1/include/libavutil/hwcontext_videotoolbox.h new file mode 100644 index 00000000..d35cfbb6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_videotoolbox.h @@ -0,0 +1,106 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_VIDEOTOOLBOX_H +#define AVUTIL_HWCONTEXT_VIDEOTOOLBOX_H + +#include + +#include + +#include "frame.h" +#include "pixfmt.h" + +/** + * @file + * An API-specific header for AV_HWDEVICE_TYPE_VIDEOTOOLBOX. + * + * This API supports frame allocation using a native CVPixelBufferPool + * instead of an AVBufferPool. + * + * If the API user sets a custom pool, AVHWFramesContext.pool must return + * AVBufferRefs whose data pointer is a CVImageBufferRef or CVPixelBufferRef. + * Note that the underlying CVPixelBuffer could be retained by OS frameworks + * depending on application usage, so it is preferable to let CoreVideo manage + * the pool using the default implementation. + * + * Currently AVHWDeviceContext.hwctx are always NULL. + */ + +typedef struct AVVTFramesContext { + enum AVColorRange color_range; +} AVVTFramesContext; + +/** + * Convert a VideoToolbox (actually CoreVideo) format to AVPixelFormat. + * Returns AV_PIX_FMT_NONE if no known equivalent was found. + */ +enum AVPixelFormat av_map_videotoolbox_format_to_pixfmt(uint32_t cv_fmt); + +/** + * Convert an AVPixelFormat to a VideoToolbox (actually CoreVideo) format. + * Returns 0 if no known equivalent was found. + */ +uint32_t av_map_videotoolbox_format_from_pixfmt(enum AVPixelFormat pix_fmt); + +/** + * Same as av_map_videotoolbox_format_from_pixfmt function, but can map and + * return full range pixel formats via a flag. + */ +uint32_t av_map_videotoolbox_format_from_pixfmt2(enum AVPixelFormat pix_fmt, bool full_range); + +/** + * Convert an AVChromaLocation to a VideoToolbox/CoreVideo chroma location string. + * Returns 0 if no known equivalent was found. + */ +CFStringRef av_map_videotoolbox_chroma_loc_from_av(enum AVChromaLocation loc); + +/** + * Convert an AVColorSpace to a VideoToolbox/CoreVideo color matrix string. + * Returns 0 if no known equivalent was found. + */ +CFStringRef av_map_videotoolbox_color_matrix_from_av(enum AVColorSpace space); + +/** + * Convert an AVColorPrimaries to a VideoToolbox/CoreVideo color primaries string. + * Returns 0 if no known equivalent was found. + */ +CFStringRef av_map_videotoolbox_color_primaries_from_av(enum AVColorPrimaries pri); + +/** + * Convert an AVColorTransferCharacteristic to a VideoToolbox/CoreVideo color transfer + * function string. + * Returns 0 if no known equivalent was found. + */ +CFStringRef av_map_videotoolbox_color_trc_from_av(enum AVColorTransferCharacteristic trc); + +/** + * Set CVPixelBufferRef's metadata based on an AVFrame. + * + * Sets/unsets the CVPixelBuffer attachments to match as closely as possible the + * AVFrame metadata. To prevent inconsistent attachments, the attachments for properties + * that could not be matched or are unspecified in the given AVFrame are unset. So if + * any attachments already covered by AVFrame metadata need to be set to a specific + * value, this should happen after calling this function. + * + * Returns < 0 in case of an error. + */ +int av_vt_pixbuf_set_attachments(void *log_ctx, + CVPixelBufferRef pixbuf, const struct AVFrame *src); + +#endif /* AVUTIL_HWCONTEXT_VIDEOTOOLBOX_H */ diff --git a/ffmpeg-n8.1/include/libavutil/hwcontext_vulkan.h b/ffmpeg-n8.1/include/libavutil/hwcontext_vulkan.h new file mode 100644 index 00000000..b9a841a1 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/hwcontext_vulkan.h @@ -0,0 +1,404 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_HWCONTEXT_VULKAN_H +#define AVUTIL_HWCONTEXT_VULKAN_H + +#if defined(_WIN32) && !defined(VK_USE_PLATFORM_WIN32_KHR) +#define VK_USE_PLATFORM_WIN32_KHR +#endif +#include + +#include "pixfmt.h" +#include "frame.h" +#include "hwcontext.h" + +typedef struct AVVkFrame AVVkFrame; + +typedef struct AVVulkanDeviceQueueFamily { + /* Queue family index */ + int idx; + /* Number of queues in the queue family in use */ + int num; + /* Queue family capabilities. Must be non-zero. + * Flags may be removed to indicate the queue family may not be used + * for a given purpose. */ + VkQueueFlagBits flags; + /* Vulkan implementations are allowed to list multiple video queues + * which differ in what they can encode or decode. */ + VkVideoCodecOperationFlagBitsKHR video_caps; +} AVVulkanDeviceQueueFamily; + +/** + * @file + * API-specific header for AV_HWDEVICE_TYPE_VULKAN. + * + * For user-allocated pools, AVHWFramesContext.pool must return AVBufferRefs + * with the data pointer set to an AVVkFrame. + */ + +/** + * Main Vulkan context, allocated as AVHWDeviceContext.hwctx. + * All of these can be set before init to change what the context uses + */ +typedef struct AVVulkanDeviceContext { + /** + * Custom memory allocator, else NULL + */ + const VkAllocationCallbacks *alloc; + + /** + * Pointer to a vkGetInstanceProcAddr loading function. + * If unset, will dynamically load and use libvulkan. + */ + PFN_vkGetInstanceProcAddr get_proc_addr; + + /** + * Vulkan instance. Must be at least version 1.3. + */ + VkInstance inst; + + /** + * Physical device + */ + VkPhysicalDevice phys_dev; + + /** + * Active device + */ + VkDevice act_dev; + + /** + * This structure should be set to the set of features that present and enabled + * during device creation. When a device is created by FFmpeg, it will default to + * enabling all that are present of the shaderImageGatherExtended, + * fragmentStoresAndAtomics, shaderInt64 and vertexPipelineStoresAndAtomics features. + */ + VkPhysicalDeviceFeatures2 device_features; + + /** + * Enabled instance extensions. + * If supplying your own device context, set this to an array of strings, with + * each entry containing the specified Vulkan extension string to enable. + * Duplicates are possible and accepted. + * If no extensions are enabled, set these fields to NULL, and 0 respectively. + * av_vk_get_optional_instance_extensions() can be used to enumerate extensions + * that FFmpeg may use if enabled. + */ + const char * const *enabled_inst_extensions; + int nb_enabled_inst_extensions; + + /** + * Enabled device extensions. By default, VK_KHR_external_memory_fd, + * VK_EXT_external_memory_dma_buf, VK_EXT_image_drm_format_modifier, + * VK_KHR_external_semaphore_fd and VK_EXT_external_memory_host are enabled if found. + * If supplying your own device context, these fields takes the same format as + * the above fields, with the same conditions that duplicates are possible + * and accepted, and that NULL and 0 respectively means no extensions are enabled. + * av_vk_get_optional_device_extensions() can be used to enumerate extensions + * that FFmpeg may use if enabled. + */ + const char * const *enabled_dev_extensions; + int nb_enabled_dev_extensions; + +#if FF_API_VULKAN_FIXED_QUEUES + /** + * Queue family index for graphics operations, and the number of queues + * enabled for it. If unavailable, will be set to -1. Not required. + * av_hwdevice_create() will attempt to find a dedicated queue for each + * queue family, or pick the one with the least unrelated flags set. + * Queue indices here may overlap if a queue has to share capabilities. + */ + attribute_deprecated + int queue_family_index; + attribute_deprecated + int nb_graphics_queues; + + /** + * Queue family index for transfer operations and the number of queues + * enabled. Required. + */ + attribute_deprecated + int queue_family_tx_index; + attribute_deprecated + int nb_tx_queues; + + /** + * Queue family index for compute operations and the number of queues + * enabled. Required. + */ + attribute_deprecated + int queue_family_comp_index; + attribute_deprecated + int nb_comp_queues; + + /** + * Queue family index for video encode ops, and the amount of queues enabled. + * If the device doesn't support such, queue_family_encode_index will be -1. + * Not required. + */ + attribute_deprecated + int queue_family_encode_index; + attribute_deprecated + int nb_encode_queues; + + /** + * Queue family index for video decode ops, and the amount of queues enabled. + * If the device doesn't support such, queue_family_decode_index will be -1. + * Not required. + */ + attribute_deprecated + int queue_family_decode_index; + attribute_deprecated + int nb_decode_queues; +#endif + +#if FF_API_VULKAN_SYNC_QUEUES + /** + * Locks a queue, preventing other threads from submitting any command + * buffers to this queue. + * If set to NULL, will be set to lavu-internal functions that utilize a + * mutex. + * + * Deprecated: use VK_KHR_internally_synchronized_queues. + */ + attribute_deprecated + void (*lock_queue)(struct AVHWDeviceContext *ctx, uint32_t queue_family, uint32_t index); + + /** + * Similar to lock_queue(), unlocks a queue. Must only be called after locking. + * + * Deprecated: use VK_KHR_internally_synchronized_queues. + */ + attribute_deprecated + void (*unlock_queue)(struct AVHWDeviceContext *ctx, uint32_t queue_family, uint32_t index); +#endif + + /** + * Queue families used. Must be preferentially ordered. List may contain + * duplicates. + * + * For compatibility reasons, all the enabled queue families listed above + * (queue_family_(tx/comp/encode/decode)_index) must also be included in + * this list until they're removed after deprecation. + */ + AVVulkanDeviceQueueFamily qf[64]; + int nb_qf; +} AVVulkanDeviceContext; + +/** + * Defines the behaviour of frame allocation. + */ +typedef enum AVVkFrameFlags { + /* Unless this flag is set, autodetected flags will be OR'd based on the + * device and tiling during av_hwframe_ctx_init(). */ + AV_VK_FRAME_FLAG_NONE = (1ULL << 0), + + /* Disables multiplane images. + * This is required to export/import images from CUDA. */ + AV_VK_FRAME_FLAG_DISABLE_MULTIPLANE = (1ULL << 2), +} AVVkFrameFlags; + +/** + * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options + */ +typedef struct AVVulkanFramesContext { + /** + * Controls the tiling of allocated frames. + * If left as VK_IMAGE_TILING_OPTIMAL (0), will use optimal tiling. + * Can be set to VK_IMAGE_TILING_LINEAR to force linear images, + * or VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT to force DMABUF-backed + * images. + * @note Imported frames from other APIs ignore this. + */ + VkImageTiling tiling; + + /** + * Defines extra usage of output frames. If non-zero, all flags MUST be + * supported by the VkFormat. Regardless, frames will always have the + * following usage flags enabled, if supported by the format: + * - VK_IMAGE_USAGE_SAMPLED_BIT + * - VK_IMAGE_USAGE_STORAGE_BIT + * - VK_IMAGE_USAGE_TRANSFER_SRC_BIT + * - VK_IMAGE_USAGE_TRANSFER_DST_BIT + */ + VkImageUsageFlagBits usage; + + /** + * Extension data for image creation. + * If DRM tiling is used, a VkImageDrmFormatModifierListCreateInfoEXT structure + * can be added to specify the exact modifier to use. + * + * Additional structures may be added at av_hwframe_ctx_init() time, + * which will be freed automatically on uninit(), so users must only free + * any structures they've allocated themselves. + */ + void *create_pnext; + + /** + * Extension data for memory allocation. Must have as many entries as + * the number of planes of the sw_format. + * This will be chained to VkExportMemoryAllocateInfo, which is used + * to make all pool images exportable to other APIs if the necessary + * extensions are present in enabled_dev_extensions. + */ + void *alloc_pnext[AV_NUM_DATA_POINTERS]; + + /** + * A combination of AVVkFrameFlags. Unless AV_VK_FRAME_FLAG_NONE is set, + * autodetected flags will be OR'd based on the device and tiling during + * av_hwframe_ctx_init(). + */ + AVVkFrameFlags flags; + + /** + * Flags to set during image creation. If unset, defaults to + * VK_IMAGE_CREATE_ALIAS_BIT. + */ + VkImageCreateFlags img_flags; + + /** + * Vulkan format for each image. MUST be compatible with the pixel format. + * If unset, will be automatically set. + * There are at most two compatible formats for a frame - a multiplane + * format, and a single-plane multi-image format. + */ + VkFormat format[AV_NUM_DATA_POINTERS]; + + /** + * Number of layers each image will have. + */ + int nb_layers; + + /** + * Locks a frame, preventing other threads from changing frame properties. + * Users SHOULD only ever lock just before command submission in order + * to get accurate frame properties, and unlock immediately after command + * submission without waiting for it to finish. + * + * If unset, will be set to lavu-internal functions that utilize a mutex. + */ + void (*lock_frame)(struct AVHWFramesContext *fc, AVVkFrame *vkf); + + /** + * Similar to lock_frame(), unlocks a frame. Must only be called after locking. + */ + void (*unlock_frame)(struct AVHWFramesContext *fc, AVVkFrame *vkf); +} AVVulkanFramesContext; + +/* + * Frame structure. + * + * @note the size of this structure is not part of the ABI, to allocate + * you must use @av_vk_frame_alloc(). + */ +struct AVVkFrame { + /** + * Vulkan images to which the memory is bound to. + * May be one for multiplane formats, or multiple. + */ + VkImage img[AV_NUM_DATA_POINTERS]; + + /** + * Tiling for the frame. + */ + VkImageTiling tiling; + + /** + * Memory backing the images. Either one, or as many as there are planes + * in the sw_format. + * In case of having multiple VkImages, but one memory, the offset field + * will indicate the bound offset for each image. + */ + VkDeviceMemory mem[AV_NUM_DATA_POINTERS]; + size_t size[AV_NUM_DATA_POINTERS]; + + /** + * OR'd flags for all memory allocated + */ + VkMemoryPropertyFlagBits flags; + + /** + * Updated after every barrier. One per VkImage. + */ + VkAccessFlagBits access[AV_NUM_DATA_POINTERS]; + VkImageLayout layout[AV_NUM_DATA_POINTERS]; + + /** + * Synchronization timeline semaphores, one for each VkImage. + * Must not be freed manually. Must be waited on at every submission using + * the value in sem_value, and must be signalled at every submission, + * using an incremented value. + */ + VkSemaphore sem[AV_NUM_DATA_POINTERS]; + + /** + * Up to date semaphore value at which each image becomes accessible. + * One per VkImage. + * Clients must wait on this value when submitting a command queue, + * and increment it when signalling. + */ + uint64_t sem_value[AV_NUM_DATA_POINTERS]; + + /** + * Internal data. + */ + struct AVVkFrameInternal *internal; + + /** + * Describes the binding offset of each image to the VkDeviceMemory. + * One per VkImage. + */ + ptrdiff_t offset[AV_NUM_DATA_POINTERS]; + + /** + * Queue family of the images. Must be VK_QUEUE_FAMILY_IGNORED if + * the image was allocated with the CONCURRENT concurrency option. + * One per VkImage. + */ + uint32_t queue_family[AV_NUM_DATA_POINTERS]; +}; + +/** + * Allocates a single AVVkFrame and initializes everything as 0. + * @note Must be freed via av_free() + */ +AVVkFrame *av_vk_frame_alloc(void); + +/** + * Returns the optimal per-plane Vulkan format for a given sw_format, + * one for each plane. + * Returns NULL on unsupported formats. + */ +const VkFormat *av_vkfmt_from_pixfmt(enum AVPixelFormat p); + +/** + * Returns an array of optional Vulkan instance extensions that FFmpeg + * may use if enabled. + * @note Must be freed via av_free() + */ +const char **av_vk_get_optional_instance_extensions(int *count); + +/** + * Returns an array of optional Vulkan device extensions that FFmpeg + * may use if enabled. + * @note Must be freed via av_free() + */ +const char **av_vk_get_optional_device_extensions(int *count); + +#endif /* AVUTIL_HWCONTEXT_VULKAN_H */ diff --git a/ffmpeg-n8.1/include/libavutil/iamf.h b/ffmpeg-n8.1/include/libavutil/iamf.h new file mode 100644 index 00000000..a755e7d6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/iamf.h @@ -0,0 +1,697 @@ +/* + * Immersive Audio Model and Formats helper functions and defines + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_IAMF_H +#define AVUTIL_IAMF_H + +/** + * @file + * Immersive Audio Model and Formats API header + * @see Immersive Audio Model and Formats + */ + +#include +#include + +#include "attributes.h" +#include "avassert.h" +#include "channel_layout.h" +#include "dict.h" +#include "rational.h" + +/** + * @defgroup lavu_iamf Immersive Audio Model and Formats + * @ingroup lavu_audio + * + * Immersive Audio Model and Formats related functions and defines + * + * @defgroup lavu_iamf_params Parameter Definition + * @ingroup lavu_iamf + * @{ + * Parameters as defined in section 3.6.1 and 3.8 of IAMF. + * @} + * + * @defgroup lavu_iamf_audio Audio Element + * @ingroup lavu_iamf + * @{ + * Audio Elements as defined in section 3.6 of IAMF. + * @} + * + * @defgroup lavu_iamf_mix Mix Presentation + * @ingroup lavu_iamf + * @{ + * Mix Presentations as defined in section 3.7 of IAMF. + * @} + * + * @addtogroup lavu_iamf_params + * @{ + */ +enum AVIAMFAnimationType { + AV_IAMF_ANIMATION_TYPE_STEP, + AV_IAMF_ANIMATION_TYPE_LINEAR, + AV_IAMF_ANIMATION_TYPE_BEZIER, +}; + +/** + * Mix Gain Parameter Data as defined in section 3.8.1 of IAMF. + * + * @note This struct's size is not a part of the public ABI. + */ +typedef struct AVIAMFMixGain { + const AVClass *av_class; + + /** + * Duration for the given subblock, in units of + * 1 / @ref AVIAMFParamDefinition.parameter_rate "parameter_rate". + * It must not be 0. + */ + unsigned int subblock_duration; + /** + * The type of animation applied to the parameter values. + */ + enum AVIAMFAnimationType animation_type; + /** + * Parameter value that is applied at the start of the subblock. + * Applies to all defined Animation Types. + * + * Valid range of values is -128.0 to 128.0 + */ + AVRational start_point_value; + /** + * Parameter value that is applied at the end of the subblock. + * Applies only to AV_IAMF_ANIMATION_TYPE_LINEAR and + * AV_IAMF_ANIMATION_TYPE_BEZIER Animation Types. + * + * Valid range of values is -128.0 to 128.0 + */ + AVRational end_point_value; + /** + * Parameter value of the middle control point of a quadratic Bezier + * curve, i.e., its y-axis value. + * Applies only to AV_IAMF_ANIMATION_TYPE_BEZIER Animation Type. + * + * Valid range of values is -128.0 to 128.0 + */ + AVRational control_point_value; + /** + * Parameter value of the time of the middle control point of a + * quadratic Bezier curve, i.e., its x-axis value. + * Applies only to AV_IAMF_ANIMATION_TYPE_BEZIER Animation Type. + * + * Valid range of values is 0.0 to 1.0 + */ + AVRational control_point_relative_time; +} AVIAMFMixGain; + +/** + * Demixing Info Parameter Data as defined in section 3.8.2 of IAMF. + * + * @note This struct's size is not a part of the public ABI. + */ +typedef struct AVIAMFDemixingInfo { + const AVClass *av_class; + + /** + * Duration for the given subblock, in units of + * 1 / @ref AVIAMFParamDefinition.parameter_rate "parameter_rate". + * It must not be 0. + */ + unsigned int subblock_duration; + /** + * Pre-defined combination of demixing parameters. + */ + unsigned int dmixp_mode; +} AVIAMFDemixingInfo; + +/** + * Recon Gain Info Parameter Data as defined in section 3.8.3 of IAMF. + * + * @note This struct's size is not a part of the public ABI. + */ +typedef struct AVIAMFReconGain { + const AVClass *av_class; + + /** + * Duration for the given subblock, in units of + * 1 / @ref AVIAMFParamDefinition.parameter_rate "parameter_rate". + * It must not be 0. + */ + unsigned int subblock_duration; + + /** + * Array of gain values to be applied to each channel for each layer + * defined in the Audio Element referencing the parent Parameter Definition. + * Values for layers where the AV_IAMF_LAYER_FLAG_RECON_GAIN flag is not set + * are undefined. + * + * Channel order is: FL, C, FR, SL, SR, TFL, TFR, BL, BR, TBL, TBR, LFE + */ + uint8_t recon_gain[6][12]; +} AVIAMFReconGain; + +enum AVIAMFParamDefinitionType { + /** + * Subblocks are of struct type AVIAMFMixGain + */ + AV_IAMF_PARAMETER_DEFINITION_MIX_GAIN, + /** + * Subblocks are of struct type AVIAMFDemixingInfo + */ + AV_IAMF_PARAMETER_DEFINITION_DEMIXING, + /** + * Subblocks are of struct type AVIAMFReconGain + */ + AV_IAMF_PARAMETER_DEFINITION_RECON_GAIN, +}; + +/** + * Parameters as defined in section 3.6.1 of IAMF. + * + * The struct is allocated by av_iamf_param_definition_alloc() along with an + * array of subblocks, its type depending on the value of type. + * This array is placed subblocks_offset bytes after the start of this struct. + * + * @note This struct's size is not a part of the public ABI. + */ +typedef struct AVIAMFParamDefinition { + const AVClass *av_class; + + /** + * Offset in bytes from the start of this struct, at which the subblocks + * array is located. + */ + size_t subblocks_offset; + /** + * Size in bytes of each element in the subblocks array. + */ + size_t subblock_size; + /** + * Number of subblocks in the array. + */ + unsigned int nb_subblocks; + + /** + * Parameters type. Determines the type of the subblock elements. + */ + enum AVIAMFParamDefinitionType type; + + /** + * Identifier for the parameter substream. + */ + unsigned int parameter_id; + /** + * Sample rate for the parameter substream. It must not be 0. + */ + unsigned int parameter_rate; + + /** + * The accumulated duration of all blocks in this parameter definition, + * in units of 1 / @ref parameter_rate. + * + * May be 0, in which case all duration values should be specified in + * another parameter definition referencing the same parameter_id. + */ + unsigned int duration; + /** + * The duration of every subblock in the case where all subblocks, with + * the optional exception of the last subblock, have equal durations. + * + * Must be 0 if subblocks have different durations. + */ + unsigned int constant_subblock_duration; +} AVIAMFParamDefinition; + +const AVClass *av_iamf_param_definition_get_class(void); + +/** + * Allocates memory for AVIAMFParamDefinition, plus an array of {@code nb_subblocks} + * amount of subblocks of the given type and initializes the variables. Can be + * freed with a normal av_free() call. + * + * @param size if non-NULL, the size in bytes of the resulting data array is written here. + */ +AVIAMFParamDefinition *av_iamf_param_definition_alloc(enum AVIAMFParamDefinitionType type, + unsigned int nb_subblocks, size_t *size); + +/** + * Get the subblock at the specified {@code idx}. Must be between 0 and nb_subblocks - 1. + * + * The @ref AVIAMFParamDefinition.type "param definition type" defines + * the struct type of the returned pointer. + */ +static av_always_inline void* +av_iamf_param_definition_get_subblock(const AVIAMFParamDefinition *par, unsigned int idx) +{ + av_assert0(idx < par->nb_subblocks); + return (void *)((uint8_t *)par + par->subblocks_offset + idx * par->subblock_size); +} + +/** + * @} + * @addtogroup lavu_iamf_audio + * @{ + */ + +enum AVIAMFAmbisonicsMode { + AV_IAMF_AMBISONICS_MODE_MONO, + AV_IAMF_AMBISONICS_MODE_PROJECTION, +}; + +/** + * Recon gain information for the layer is present in AVIAMFReconGain + */ +#define AV_IAMF_LAYER_FLAG_RECON_GAIN (1 << 0) + +/** + * A layer defining a Channel Layout in the Audio Element. + * + * When @ref AVIAMFAudioElement.audio_element_type "the parent's Audio Element type" + * is AV_IAMF_AUDIO_ELEMENT_TYPE_CHANNEL, this corresponds to an Scalable Channel + * Layout layer as defined in section 3.6.2 of IAMF. + * For AV_IAMF_AUDIO_ELEMENT_TYPE_SCENE, it is an Ambisonics channel + * layout as defined in section 3.6.3 of IAMF. + * + * @note The struct should be allocated with av_iamf_audio_element_add_layer() + * and its size is not a part of the public ABI. + */ +typedef struct AVIAMFLayer { + const AVClass *av_class; + + AVChannelLayout ch_layout; + + /** + * A bitmask which may contain a combination of AV_IAMF_LAYER_FLAG_* flags. + */ + unsigned int flags; + /** + * Output gain channel flags as defined in section 3.6.2 of IAMF. + * + * This field is defined only if @ref AVIAMFAudioElement.audio_element_type + * "the parent's Audio Element type" is AV_IAMF_AUDIO_ELEMENT_TYPE_CHANNEL, + * must be 0 otherwise. + */ + unsigned int output_gain_flags; + /** + * Output gain as defined in section 3.6.2 of IAMF. + * + * Must be 0 if @ref output_gain_flags is 0. + */ + AVRational output_gain; + /** + * Ambisonics mode as defined in section 3.6.3 of IAMF. + * + * This field is defined only if @ref AVIAMFAudioElement.audio_element_type + * "the parent's Audio Element type" is AV_IAMF_AUDIO_ELEMENT_TYPE_SCENE. + * + * If AV_IAMF_AMBISONICS_MODE_MONO, channel_mapping is defined implicitly + * (Ambisonic Order) or explicitly (Custom Order with ambi channels) in + * @ref ch_layout. + * If AV_IAMF_AMBISONICS_MODE_PROJECTION, @ref demixing_matrix must be set. + */ + enum AVIAMFAmbisonicsMode ambisonics_mode; + + /** + * Demixing matrix as defined in section 3.6.3 of IAMF. + * + * May be set only if @ref ambisonics_mode == AV_IAMF_AMBISONICS_MODE_PROJECTION, + * must be NULL otherwise. + */ + AVRational *demixing_matrix; + + /** + * The length of the Demixing matrix array. Must be ch_layout.nb_channels multiplied + * by the sum of the amount of streams in the group plus the amount of streams in + * the group that are stereo. + */ + unsigned int nb_demixing_matrix; +} AVIAMFLayer; + + +enum AVIAMFAudioElementType { + AV_IAMF_AUDIO_ELEMENT_TYPE_CHANNEL, + AV_IAMF_AUDIO_ELEMENT_TYPE_SCENE, +}; + +/** + * Information on how to combine one or more audio streams, as defined in + * section 3.6 of IAMF. + * + * @note The struct should be allocated with av_iamf_audio_element_alloc() + * and its size is not a part of the public ABI. + */ +typedef struct AVIAMFAudioElement { + const AVClass *av_class; + + AVIAMFLayer **layers; + /** + * Number of layers, or channel groups, in the Audio Element. + * There may be 6 layers at most, and for @ref audio_element_type + * AV_IAMF_AUDIO_ELEMENT_TYPE_SCENE, there may be exactly 1. + * + * Set by av_iamf_audio_element_add_layer(), must not be + * modified by any other code. + */ + unsigned int nb_layers; + + /** + * Demixing information used to reconstruct a scalable channel audio + * representation. + * The @ref AVIAMFParamDefinition.type "type" must be + * AV_IAMF_PARAMETER_DEFINITION_DEMIXING. + */ + AVIAMFParamDefinition *demixing_info; + /** + * Recon gain information used to reconstruct a scalable channel audio + * representation. + * The @ref AVIAMFParamDefinition.type "type" must be + * AV_IAMF_PARAMETER_DEFINITION_RECON_GAIN. + */ + AVIAMFParamDefinition *recon_gain_info; + + /** + * Audio element type as defined in section 3.6 of IAMF. + */ + enum AVIAMFAudioElementType audio_element_type; + + /** + * Default weight value as defined in section 3.6 of IAMF. + */ + unsigned int default_w; +} AVIAMFAudioElement; + +const AVClass *av_iamf_audio_element_get_class(void); + +/** + * Allocates a AVIAMFAudioElement, and initializes its fields with default values. + * No layers are allocated. Must be freed with av_iamf_audio_element_free(). + * + * @see av_iamf_audio_element_add_layer() + */ +AVIAMFAudioElement *av_iamf_audio_element_alloc(void); + +/** + * Allocate a layer and add it to a given AVIAMFAudioElement. + * It is freed by av_iamf_audio_element_free() alongside the rest of the parent + * AVIAMFAudioElement. + * + * @return a pointer to the allocated layer. + */ +AVIAMFLayer *av_iamf_audio_element_add_layer(AVIAMFAudioElement *audio_element); + +/** + * Free an AVIAMFAudioElement and all its contents. + * + * @param audio_element pointer to pointer to an allocated AVIAMFAudioElement. + * upon return, *audio_element will be set to NULL. + */ +void av_iamf_audio_element_free(AVIAMFAudioElement **audio_element); + +/** + * @} + * @addtogroup lavu_iamf_mix + * @{ + */ + +enum AVIAMFHeadphonesMode { + /** + * The referenced Audio Element shall be rendered to stereo loudspeakers. + */ + AV_IAMF_HEADPHONES_MODE_STEREO, + /** + * The referenced Audio Element shall be rendered with a binaural renderer. + */ + AV_IAMF_HEADPHONES_MODE_BINAURAL, +}; + +/** + * Submix element as defined in section 3.7 of IAMF. + * + * @note The struct should be allocated with av_iamf_submix_add_element() + * and its size is not a part of the public ABI. + */ +typedef struct AVIAMFSubmixElement { + const AVClass *av_class; + + /** + * The id of the Audio Element this submix element references. + */ + unsigned int audio_element_id; + + /** + * Information required required for applying any processing to the + * referenced and rendered Audio Element before being summed with other + * processed Audio Elements. + * The @ref AVIAMFParamDefinition.type "type" must be + * AV_IAMF_PARAMETER_DEFINITION_MIX_GAIN. + */ + AVIAMFParamDefinition *element_mix_config; + + /** + * Default mix gain value to apply when there are no AVIAMFParamDefinition + * with @ref element_mix_config "element_mix_config's" + * @ref AVIAMFParamDefinition.parameter_id "parameter_id" available for a + * given audio frame. + */ + AVRational default_mix_gain; + + /** + * A value that indicates whether the referenced channel-based Audio Element + * shall be rendered to stereo loudspeakers or spatialized with a binaural + * renderer when played back on headphones. + * If the Audio Element is not of @ref AVIAMFAudioElement.audio_element_type + * "type" AV_IAMF_AUDIO_ELEMENT_TYPE_CHANNEL, then this field is undefined. + */ + enum AVIAMFHeadphonesMode headphones_rendering_mode; + + /** + * A dictionary of strings describing the submix in different languages. + * Must have the same amount of entries as + * @ref AVIAMFMixPresentation.annotations "the mix's annotations", stored + * in the same order, and with the same key strings. + * + * @ref AVDictionaryEntry.key "key" is a string conforming to BCP-47 that + * specifies the language for the string stored in + * @ref AVDictionaryEntry.value "value". + */ + AVDictionary *annotations; +} AVIAMFSubmixElement; + +enum AVIAMFSubmixLayoutType { + /** + * The layout follows the loudspeaker sound system convention of ITU-2051-3. + * @ref AVIAMFSubmixLayout.sound_system must be set. + */ + AV_IAMF_SUBMIX_LAYOUT_TYPE_LOUDSPEAKERS = 2, + /** + * The layout is binaural. + * + * @note @ref AVIAMFSubmixLayout.sound_system may be set to + * AV_CHANNEL_LAYOUT_BINAURAL to simplify API usage, but it's not mandatory. + */ + AV_IAMF_SUBMIX_LAYOUT_TYPE_BINAURAL = 3, +}; + +/** + * Submix layout as defined in section 3.7.6 of IAMF. + * + * @note The struct should be allocated with av_iamf_submix_add_layout() + * and its size is not a part of the public ABI. + */ +typedef struct AVIAMFSubmixLayout { + const AVClass *av_class; + + enum AVIAMFSubmixLayoutType layout_type; + + /** + * Channel layout matching one of Sound Systems A to J of ITU-2051-3, plus + * 7.1.2ch, 3.1.2ch, and binaural. + * If layout_type is not AV_IAMF_SUBMIX_LAYOUT_TYPE_LOUDSPEAKERS or + * AV_IAMF_SUBMIX_LAYOUT_TYPE_BINAURAL, this field is undefined. + */ + AVChannelLayout sound_system; + /** + * The program integrated loudness information, as defined in + * ITU-1770-4. + */ + AVRational integrated_loudness; + /** + * The digital (sampled) peak value of the audio signal, as defined + * in ITU-1770-4. + */ + AVRational digital_peak; + /** + * The true peak of the audio signal, as defined in ITU-1770-4. + */ + AVRational true_peak; + /** + * The Dialogue loudness information, as defined in ITU-1770-4. + */ + AVRational dialogue_anchored_loudness; + /** + * The Album loudness information, as defined in ITU-1770-4. + */ + AVRational album_anchored_loudness; +} AVIAMFSubmixLayout; + +/** + * Submix layout as defined in section 3.7 of IAMF. + * + * @note The struct should be allocated with av_iamf_mix_presentation_add_submix() + * and its size is not a part of the public ABI. + */ +typedef struct AVIAMFSubmix { + const AVClass *av_class; + + /** + * Array of submix elements. + * + * Set by av_iamf_submix_add_element(), must not be modified by any + * other code. + */ + AVIAMFSubmixElement **elements; + /** + * Number of elements in the submix. + * + * Set by av_iamf_submix_add_element(), must not be modified by any + * other code. + */ + unsigned int nb_elements; + + /** + * Array of submix layouts. + * + * Set by av_iamf_submix_add_layout(), must not be modified by any + * other code. + */ + AVIAMFSubmixLayout **layouts; + /** + * Number of layouts in the submix. + * + * Set by av_iamf_submix_add_layout(), must not be modified by any + * other code. + */ + unsigned int nb_layouts; + + /** + * Information required for post-processing the mixed audio signal to + * generate the audio signal for playback. + * The @ref AVIAMFParamDefinition.type "type" must be + * AV_IAMF_PARAMETER_DEFINITION_MIX_GAIN. + */ + AVIAMFParamDefinition *output_mix_config; + + /** + * Default mix gain value to apply when there are no AVIAMFParamDefinition + * with @ref output_mix_config "output_mix_config's" + * @ref AVIAMFParamDefinition.parameter_id "parameter_id" available for a + * given audio frame. + */ + AVRational default_mix_gain; +} AVIAMFSubmix; + +/** + * Information on how to render and mix one or more AVIAMFAudioElement to generate + * the final audio output, as defined in section 3.7 of IAMF. + * + * @note The struct should be allocated with av_iamf_mix_presentation_alloc() + * and its size is not a part of the public ABI. + */ +typedef struct AVIAMFMixPresentation { + const AVClass *av_class; + + /** + * Array of submixes. + * + * Set by av_iamf_mix_presentation_add_submix(), must not be modified + * by any other code. + */ + AVIAMFSubmix **submixes; + /** + * Number of submixes in the presentation. + * + * Set by av_iamf_mix_presentation_add_submix(), must not be modified + * by any other code. + */ + unsigned int nb_submixes; + + /** + * A dictionary of strings describing the mix in different languages. + * Must have the same amount of entries as every + * @ref AVIAMFSubmixElement.annotations "Submix element annotations", + * stored in the same order, and with the same key strings. + * + * @ref AVDictionaryEntry.key "key" is a string conforming to BCP-47 + * that specifies the language for the string stored in + * @ref AVDictionaryEntry.value "value". + */ + AVDictionary *annotations; +} AVIAMFMixPresentation; + +const AVClass *av_iamf_mix_presentation_get_class(void); + +/** + * Allocates a AVIAMFMixPresentation, and initializes its fields with default + * values. No submixes are allocated. + * Must be freed with av_iamf_mix_presentation_free(). + * + * @see av_iamf_mix_presentation_add_submix() + */ +AVIAMFMixPresentation *av_iamf_mix_presentation_alloc(void); + +/** + * Allocate a submix and add it to a given AVIAMFMixPresentation. + * It is freed by av_iamf_mix_presentation_free() alongside the rest of the + * parent AVIAMFMixPresentation. + * + * @return a pointer to the allocated submix. + */ +AVIAMFSubmix *av_iamf_mix_presentation_add_submix(AVIAMFMixPresentation *mix_presentation); + +/** + * Allocate a submix element and add it to a given AVIAMFSubmix. + * It is freed by av_iamf_mix_presentation_free() alongside the rest of the + * parent AVIAMFSubmix. + * + * @return a pointer to the allocated submix. + */ +AVIAMFSubmixElement *av_iamf_submix_add_element(AVIAMFSubmix *submix); + +/** + * Allocate a submix layout and add it to a given AVIAMFSubmix. + * It is freed by av_iamf_mix_presentation_free() alongside the rest of the + * parent AVIAMFSubmix. + * + * @return a pointer to the allocated submix. + */ +AVIAMFSubmixLayout *av_iamf_submix_add_layout(AVIAMFSubmix *submix); + +/** + * Free an AVIAMFMixPresentation and all its contents. + * + * @param mix_presentation pointer to pointer to an allocated AVIAMFMixPresentation. + * upon return, *mix_presentation will be set to NULL. + */ +void av_iamf_mix_presentation_free(AVIAMFMixPresentation **mix_presentation); + +/** + * @} + */ + +#endif /* AVUTIL_IAMF_H */ diff --git a/ffmpeg-n8.1/include/libavutil/imgutils.h b/ffmpeg-n8.1/include/libavutil/imgutils.h new file mode 100644 index 00000000..123a9e5c --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/imgutils.h @@ -0,0 +1,377 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_IMGUTILS_H +#define AVUTIL_IMGUTILS_H + +/** + * @file + * misc image utilities + * + * @addtogroup lavu_picture + * @{ + */ + +#include +#include +#include "pixdesc.h" +#include "pixfmt.h" +#include "rational.h" + +/** + * Compute the max pixel step for each plane of an image with a + * format described by pixdesc. + * + * The pixel step is the distance in bytes between the first byte of + * the group of bytes which describe a pixel component and the first + * byte of the successive group in the same plane for the same + * component. + * + * @param max_pixsteps an array which is filled with the max pixel step + * for each plane. Since a plane may contain different pixel + * components, the computed max_pixsteps[plane] is relative to the + * component in the plane with the max pixel step. + * @param max_pixstep_comps an array which is filled with the component + * for each plane which has the max pixel step. May be NULL. + * @param pixdesc the AVPixFmtDescriptor for the image, describing its format + */ +void av_image_fill_max_pixsteps(int max_pixsteps[4], int max_pixstep_comps[4], + const AVPixFmtDescriptor *pixdesc); + +/** + * Compute the size of an image line with format pix_fmt and width + * width for the plane plane. + * + * @return the computed size in bytes + */ +int av_image_get_linesize(enum AVPixelFormat pix_fmt, int width, int plane); + +/** + * Fill plane linesizes for an image with pixel format pix_fmt and + * width width. + * + * @param linesizes array to be filled with the linesize for each plane + * @param pix_fmt the AVPixelFormat of the image + * @param width width of the image in pixels + * @return >= 0 in case of success, a negative error code otherwise + */ +int av_image_fill_linesizes(int linesizes[4], enum AVPixelFormat pix_fmt, int width); + +/** + * Fill plane sizes for an image with pixel format pix_fmt and height height. + * + * @param size the array to be filled with the size of each image plane + * @param pix_fmt the AVPixelFormat of the image + * @param height height of the image in pixels + * @param linesizes the array containing the linesize for each + * plane, should be filled by av_image_fill_linesizes() + * @return >= 0 in case of success, a negative error code otherwise + * + * @note The linesize parameters have the type ptrdiff_t here, while they are + * int for av_image_fill_linesizes(). + */ +int av_image_fill_plane_sizes(size_t size[4], enum AVPixelFormat pix_fmt, + int height, const ptrdiff_t linesizes[4]); + +/** + * Fill plane data pointers for an image with pixel format pix_fmt and + * height height. + * + * @param data pointers array to be filled with the pointer for each image plane + * @param pix_fmt the AVPixelFormat of the image + * @param height height of the image in pixels + * @param ptr the pointer to a buffer which will contain the image + * @param linesizes the array containing the linesize for each + * plane, should be filled by av_image_fill_linesizes() + * @return the size in bytes required for the image buffer, a negative + * error code in case of failure + */ +int av_image_fill_pointers(uint8_t *data[4], enum AVPixelFormat pix_fmt, int height, + uint8_t *ptr, const int linesizes[4]); + +/** + * Allocate an image with size w and h and pixel format pix_fmt, and + * fill pointers and linesizes accordingly. + * The allocated image buffer has to be freed by using + * av_freep(&pointers[0]). + * + * @param pointers array to be filled with the pointer for each image plane + * @param linesizes the array filled with the linesize for each plane + * @param w width of the image in pixels + * @param h height of the image in pixels + * @param pix_fmt the AVPixelFormat of the image + * @param align the value to use for buffer size alignment + * @return the size in bytes required for the image buffer, a negative + * error code in case of failure + */ +int av_image_alloc(uint8_t *pointers[4], int linesizes[4], + int w, int h, enum AVPixelFormat pix_fmt, int align); + +/** + * Copy image plane from src to dst. + * That is, copy "height" number of lines of "bytewidth" bytes each. + * The first byte of each successive line is separated by *_linesize + * bytes. + * + * bytewidth must be contained by both absolute values of dst_linesize + * and src_linesize, otherwise the function behavior is undefined. + * + * @param dst destination plane to copy to + * @param dst_linesize linesize for the image plane in dst + * @param src source plane to copy from + * @param src_linesize linesize for the image plane in src + * @param height height (number of lines) of the plane + */ +void av_image_copy_plane(uint8_t *dst, int dst_linesize, + const uint8_t *src, int src_linesize, + int bytewidth, int height); + +/** + * Copy image data located in uncacheable (e.g. GPU mapped) memory. Where + * available, this function will use special functionality for reading from such + * memory, which may result in greatly improved performance compared to plain + * av_image_copy_plane(). + * + * bytewidth must be contained by both absolute values of dst_linesize + * and src_linesize, otherwise the function behavior is undefined. + * + * @note The linesize parameters have the type ptrdiff_t here, while they are + * int for av_image_copy_plane(). + * @note On x86, the linesizes currently need to be aligned to the cacheline + * size (i.e. 64) to get improved performance. + */ +void av_image_copy_plane_uc_from(uint8_t *dst, ptrdiff_t dst_linesize, + const uint8_t *src, ptrdiff_t src_linesize, + ptrdiff_t bytewidth, int height); + +/** + * Copy image in src_data to dst_data. + * + * @param dst_data destination image data buffer to copy to + * @param dst_linesizes linesizes for the image in dst_data + * @param src_data source image data buffer to copy from + * @param src_linesizes linesizes for the image in src_data + * @param pix_fmt the AVPixelFormat of the image + * @param width width of the image in pixels + * @param height height of the image in pixels + */ +void av_image_copy(uint8_t * const dst_data[4], const int dst_linesizes[4], + const uint8_t * const src_data[4], const int src_linesizes[4], + enum AVPixelFormat pix_fmt, int width, int height); + +/** + * Wrapper around av_image_copy() to workaround the limitation + * that the conversion from uint8_t * const * to const uint8_t * const * + * is not performed automatically in C. + * @see av_image_copy() + */ +static inline +void av_image_copy2(uint8_t * const dst_data[4], const int dst_linesizes[4], + uint8_t * const src_data[4], const int src_linesizes[4], + enum AVPixelFormat pix_fmt, int width, int height) +{ + av_image_copy(dst_data, dst_linesizes, + (const uint8_t * const *)src_data, src_linesizes, + pix_fmt, width, height); +} + +/** + * Copy image data located in uncacheable (e.g. GPU mapped) memory. Where + * available, this function will use special functionality for reading from such + * memory, which may result in greatly improved performance compared to plain + * av_image_copy(). + * + * The data pointers and the linesizes must be aligned to the maximum required + * by the CPU architecture. + * + * @note The linesize parameters have the type ptrdiff_t here, while they are + * int for av_image_copy(). + * @note On x86, the linesizes currently need to be aligned to the cacheline + * size (i.e. 64) to get improved performance. + */ +void av_image_copy_uc_from(uint8_t * const dst_data[4], const ptrdiff_t dst_linesizes[4], + const uint8_t * const src_data[4], const ptrdiff_t src_linesizes[4], + enum AVPixelFormat pix_fmt, int width, int height); + +/** + * Setup the data pointers and linesizes based on the specified image + * parameters and the provided array. + * + * The fields of the given image are filled in by using the src + * address which points to the image data buffer. Depending on the + * specified pixel format, one or multiple image data pointers and + * line sizes will be set. If a planar format is specified, several + * pointers will be set pointing to the different picture planes and + * the line sizes of the different planes will be stored in the + * lines_sizes array. Call with src == NULL to get the required + * size for the src buffer. + * + * To allocate the buffer and fill in the dst_data and dst_linesize in + * one call, use av_image_alloc(). + * + * @param dst_data data pointers to be filled in + * @param dst_linesize linesizes for the image in dst_data to be filled in + * @param src buffer which will contain or contains the actual image data, can be NULL + * @param pix_fmt the pixel format of the image + * @param width the width of the image in pixels + * @param height the height of the image in pixels + * @param align the value used in src for linesize alignment + * @return the size in bytes required for src, a negative error code + * in case of failure + */ +int av_image_fill_arrays(uint8_t *dst_data[4], int dst_linesize[4], + const uint8_t *src, + enum AVPixelFormat pix_fmt, int width, int height, int align); + +/** + * Return the size in bytes of the amount of data required to store an + * image with the given parameters. + * + * @param pix_fmt the pixel format of the image + * @param width the width of the image in pixels + * @param height the height of the image in pixels + * @param align the assumed linesize alignment + * @return the buffer size in bytes, a negative error code in case of failure + */ +int av_image_get_buffer_size(enum AVPixelFormat pix_fmt, int width, int height, int align); + +/** + * Copy image data from an image into a buffer. + * + * av_image_get_buffer_size() can be used to compute the required size + * for the buffer to fill. + * + * @param dst a buffer into which picture data will be copied + * @param dst_size the size in bytes of dst + * @param src_data pointers containing the source image data + * @param src_linesize linesizes for the image in src_data + * @param pix_fmt the pixel format of the source image + * @param width the width of the source image in pixels + * @param height the height of the source image in pixels + * @param align the assumed linesize alignment for dst + * @return the number of bytes written to dst, or a negative value + * (error code) on error + */ +int av_image_copy_to_buffer(uint8_t *dst, int dst_size, + const uint8_t * const src_data[4], const int src_linesize[4], + enum AVPixelFormat pix_fmt, int width, int height, int align); + +/** + * Check if the given dimension of an image is valid, meaning that all + * bytes of the image can be addressed with a signed int. + * + * @param w the width of the picture + * @param h the height of the picture + * @param log_offset the offset to sum to the log level for logging with log_ctx + * @param log_ctx the parent logging context, it may be NULL + * @return >= 0 if valid, a negative error code otherwise + */ +int av_image_check_size(unsigned int w, unsigned int h, int log_offset, void *log_ctx); + +/** + * Check if the given dimension of an image is valid, meaning that all + * bytes of a plane of an image with the specified pix_fmt can be addressed + * with a signed int. + * + * @param w the width of the picture + * @param h the height of the picture + * @param max_pixels the maximum number of pixels the user wants to accept + * @param pix_fmt the pixel format, can be AV_PIX_FMT_NONE if unknown. + * @param log_offset the offset to sum to the log level for logging with log_ctx + * @param log_ctx the parent logging context, it may be NULL + * @return >= 0 if valid, a negative error code otherwise + */ +int av_image_check_size2(unsigned int w, unsigned int h, int64_t max_pixels, enum AVPixelFormat pix_fmt, int log_offset, void *log_ctx); + +/** + * Check if the given sample aspect ratio of an image is valid. + * + * It is considered invalid if the denominator is 0 or if applying the ratio + * to the image size would make the smaller dimension less than 1. If the + * sar numerator is 0, it is considered unknown and will return as valid. + * + * @param w width of the image + * @param h height of the image + * @param sar sample aspect ratio of the image + * @return 0 if valid, a negative AVERROR code otherwise + */ +int av_image_check_sar(unsigned int w, unsigned int h, AVRational sar); + +/** + * Overwrite the image data with black. This is suitable for filling a + * sub-rectangle of an image, meaning the padding between the right most pixel + * and the left most pixel on the next line will not be overwritten. For some + * formats, the image size might be rounded up due to inherent alignment. + * + * If the pixel format has alpha, the alpha is cleared to opaque. + * + * This can return an error if the pixel format is not supported. Normally, all + * non-hwaccel pixel formats should be supported. + * + * Passing NULL for dst_data is allowed. Then the function returns whether the + * operation would have succeeded. (It can return an error if the pix_fmt is + * not supported.) + * + * @param dst_data data pointers to destination image + * @param dst_linesize linesizes for the destination image + * @param pix_fmt the pixel format of the image + * @param range the color range of the image (important for colorspaces such as YUV) + * @param width the width of the image in pixels + * @param height the height of the image in pixels + * @return 0 if the image data was cleared, a negative AVERROR code otherwise + */ +int av_image_fill_black(uint8_t * const dst_data[4], const ptrdiff_t dst_linesize[4], + enum AVPixelFormat pix_fmt, enum AVColorRange range, + int width, int height); + +/** + * Overwrite the image data with a color. This is suitable for filling a + * sub-rectangle of an image, meaning the padding between the right most pixel + * and the left most pixel on the next line will not be overwritten. For some + * formats, the image size might be rounded up due to inherent alignment. + * + * If the pixel format has alpha, it is also replaced. Color component values + * are interpreted as native integers (or intfloats) regardless of actual pixel + * format endianness. + * + * This can return an error if the pixel format is not supported. Normally, all + * non-hwaccel pixel formats should be supported. + * + * Passing NULL for dst_data is allowed. Then the function returns whether the + * operation would have succeeded. (It can return an error if the pix_fmt is + * not supported.) + * + * @param dst_data data pointers to destination image + * @param dst_linesize linesizes for the destination image + * @param pix_fmt the pixel format of the image + * @param color the color components to be used for the fill + * @param width the width of the image in pixels + * @param height the height of the image in pixels + * @param flags currently unused + * @return 0 if the image data was filled, a negative AVERROR code otherwise + */ +int av_image_fill_color(uint8_t * const dst_data[4], const ptrdiff_t dst_linesize[4], + enum AVPixelFormat pix_fmt, const uint32_t color[4], + int width, int height, int flags); + +/** + * @} + */ + + +#endif /* AVUTIL_IMGUTILS_H */ diff --git a/ffmpeg-n8.1/include/libavutil/intfloat.h b/ffmpeg-n8.1/include/libavutil/intfloat.h new file mode 100644 index 00000000..fe3d7ec4 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/intfloat.h @@ -0,0 +1,77 @@ +/* + * Copyright (c) 2011 Mans Rullgard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_INTFLOAT_H +#define AVUTIL_INTFLOAT_H + +#include +#include "attributes.h" + +union av_intfloat32 { + uint32_t i; + float f; +}; + +union av_intfloat64 { + uint64_t i; + double f; +}; + +/** + * Reinterpret a 32-bit integer as a float. + */ +static av_always_inline float av_int2float(uint32_t i) +{ + union av_intfloat32 v; + v.i = i; + return v.f; +} + +/** + * Reinterpret a float as a 32-bit integer. + */ +static av_always_inline uint32_t av_float2int(float f) +{ + union av_intfloat32 v; + v.f = f; + return v.i; +} + +/** + * Reinterpret a 64-bit integer as a double. + */ +static av_always_inline double av_int2double(uint64_t i) +{ + union av_intfloat64 v; + v.i = i; + return v.f; +} + +/** + * Reinterpret a double as a 64-bit integer. + */ +static av_always_inline uint64_t av_double2int(double f) +{ + union av_intfloat64 v; + v.f = f; + return v.i; +} + +#endif /* AVUTIL_INTFLOAT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/intreadwrite.h b/ffmpeg-n8.1/include/libavutil/intreadwrite.h new file mode 100644 index 00000000..ffd15a15 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/intreadwrite.h @@ -0,0 +1,677 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_INTREADWRITE_H +#define AVUTIL_INTREADWRITE_H + +#include +#include "libavutil/avconfig.h" +#include "attributes.h" +#include "bswap.h" + +typedef union { + uint64_t u64; + uint32_t u32[2]; + uint16_t u16[4]; + uint8_t u8 [8]; + double f64; + float f32[2]; +} av_alias av_alias64; + +typedef union { + uint32_t u32; + uint16_t u16[2]; + uint8_t u8 [4]; + float f32; +} av_alias av_alias32; + +typedef union { + uint16_t u16; + uint8_t u8 [2]; +} av_alias av_alias16; + +/* + * Arch-specific headers can provide any combination of + * AV_[RW][BLN](16|24|32|48|64) and AV_(COPY|SWAP|ZERO)(64|128) macros. + * Preprocessor symbols must be defined, even if these are implemented + * as inline functions. + * + * R/W means read/write, B/L/N means big/little/native endianness. + * The following macros require aligned access, compared to their + * unaligned variants: AV_(COPY|SWAP|ZERO)(64|128), AV_[RW]N[8-64]A. + * Incorrect usage may range from abysmal performance to crash + * depending on the platform. + * + * The unaligned variants are AV_[RW][BLN][8-64] and AV_COPY*U. + */ + +#ifdef HAVE_AV_CONFIG_H + +#include "config.h" + +#if ARCH_AARCH64 +# include "aarch64/intreadwrite.h" +#elif ARCH_MIPS +# include "mips/intreadwrite.h" +#elif ARCH_PPC +# include "ppc/intreadwrite.h" +#elif ARCH_X86 +# include "x86/intreadwrite.h" +#endif + +#endif /* HAVE_AV_CONFIG_H */ + +/* + * Map AV_RNXX <-> AV_R[BL]XX for all variants provided by per-arch headers. + */ + +#if AV_HAVE_BIGENDIAN + +# if defined(AV_RN16) && !defined(AV_RB16) +# define AV_RB16(p) AV_RN16(p) +# elif !defined(AV_RN16) && defined(AV_RB16) +# define AV_RN16(p) AV_RB16(p) +# endif + +# if defined(AV_WN16) && !defined(AV_WB16) +# define AV_WB16(p, v) AV_WN16(p, v) +# elif !defined(AV_WN16) && defined(AV_WB16) +# define AV_WN16(p, v) AV_WB16(p, v) +# endif + +# if defined(AV_RN24) && !defined(AV_RB24) +# define AV_RB24(p) AV_RN24(p) +# elif !defined(AV_RN24) && defined(AV_RB24) +# define AV_RN24(p) AV_RB24(p) +# endif + +# if defined(AV_WN24) && !defined(AV_WB24) +# define AV_WB24(p, v) AV_WN24(p, v) +# elif !defined(AV_WN24) && defined(AV_WB24) +# define AV_WN24(p, v) AV_WB24(p, v) +# endif + +# if defined(AV_RN32) && !defined(AV_RB32) +# define AV_RB32(p) AV_RN32(p) +# elif !defined(AV_RN32) && defined(AV_RB32) +# define AV_RN32(p) AV_RB32(p) +# endif + +# if defined(AV_WN32) && !defined(AV_WB32) +# define AV_WB32(p, v) AV_WN32(p, v) +# elif !defined(AV_WN32) && defined(AV_WB32) +# define AV_WN32(p, v) AV_WB32(p, v) +# endif + +# if defined(AV_RN48) && !defined(AV_RB48) +# define AV_RB48(p) AV_RN48(p) +# elif !defined(AV_RN48) && defined(AV_RB48) +# define AV_RN48(p) AV_RB48(p) +# endif + +# if defined(AV_WN48) && !defined(AV_WB48) +# define AV_WB48(p, v) AV_WN48(p, v) +# elif !defined(AV_WN48) && defined(AV_WB48) +# define AV_WN48(p, v) AV_WB48(p, v) +# endif + +# if defined(AV_RN64) && !defined(AV_RB64) +# define AV_RB64(p) AV_RN64(p) +# elif !defined(AV_RN64) && defined(AV_RB64) +# define AV_RN64(p) AV_RB64(p) +# endif + +# if defined(AV_WN64) && !defined(AV_WB64) +# define AV_WB64(p, v) AV_WN64(p, v) +# elif !defined(AV_WN64) && defined(AV_WB64) +# define AV_WN64(p, v) AV_WB64(p, v) +# endif + +#else /* AV_HAVE_BIGENDIAN */ + +# if defined(AV_RN16) && !defined(AV_RL16) +# define AV_RL16(p) AV_RN16(p) +# elif !defined(AV_RN16) && defined(AV_RL16) +# define AV_RN16(p) AV_RL16(p) +# endif + +# if defined(AV_WN16) && !defined(AV_WL16) +# define AV_WL16(p, v) AV_WN16(p, v) +# elif !defined(AV_WN16) && defined(AV_WL16) +# define AV_WN16(p, v) AV_WL16(p, v) +# endif + +# if defined(AV_RN24) && !defined(AV_RL24) +# define AV_RL24(p) AV_RN24(p) +# elif !defined(AV_RN24) && defined(AV_RL24) +# define AV_RN24(p) AV_RL24(p) +# endif + +# if defined(AV_WN24) && !defined(AV_WL24) +# define AV_WL24(p, v) AV_WN24(p, v) +# elif !defined(AV_WN24) && defined(AV_WL24) +# define AV_WN24(p, v) AV_WL24(p, v) +# endif + +# if defined(AV_RN32) && !defined(AV_RL32) +# define AV_RL32(p) AV_RN32(p) +# elif !defined(AV_RN32) && defined(AV_RL32) +# define AV_RN32(p) AV_RL32(p) +# endif + +# if defined(AV_WN32) && !defined(AV_WL32) +# define AV_WL32(p, v) AV_WN32(p, v) +# elif !defined(AV_WN32) && defined(AV_WL32) +# define AV_WN32(p, v) AV_WL32(p, v) +# endif + +# if defined(AV_RN48) && !defined(AV_RL48) +# define AV_RL48(p) AV_RN48(p) +# elif !defined(AV_RN48) && defined(AV_RL48) +# define AV_RN48(p) AV_RL48(p) +# endif + +# if defined(AV_WN48) && !defined(AV_WL48) +# define AV_WL48(p, v) AV_WN48(p, v) +# elif !defined(AV_WN48) && defined(AV_WL48) +# define AV_WN48(p, v) AV_WL48(p, v) +# endif + +# if defined(AV_RN64) && !defined(AV_RL64) +# define AV_RL64(p) AV_RN64(p) +# elif !defined(AV_RN64) && defined(AV_RL64) +# define AV_RN64(p) AV_RL64(p) +# endif + +# if defined(AV_WN64) && !defined(AV_WL64) +# define AV_WL64(p, v) AV_WN64(p, v) +# elif !defined(AV_WN64) && defined(AV_WL64) +# define AV_WN64(p, v) AV_WL64(p, v) +# endif + +#endif /* !AV_HAVE_BIGENDIAN */ + +/* + * Define AV_[RW]N helper macros to simplify definitions not provided + * by per-arch headers. + */ + +#if defined(__GNUC__) || defined(__clang__) + +union unaligned_64 { uint64_t l; } __attribute__((packed)) av_alias; +union unaligned_32 { uint32_t l; } __attribute__((packed)) av_alias; +union unaligned_16 { uint16_t l; } __attribute__((packed)) av_alias; + +# define AV_RN(s, p) (((const union unaligned_##s *) (p))->l) +# define AV_WN(s, p, v) ((((union unaligned_##s *) (p))->l) = (v)) + +#elif defined(_MSC_VER) && (defined(_M_ARM) || defined(_M_X64) || defined(_M_ARM64)) && AV_HAVE_FAST_UNALIGNED + +# define AV_RN(s, p) (*((const __unaligned uint##s##_t*)(p))) +# define AV_WN(s, p, v) (*((__unaligned uint##s##_t*)(p)) = (v)) + +#elif AV_HAVE_FAST_UNALIGNED + +# define AV_RN(s, p) (((const av_alias##s*)(p))->u##s) +# define AV_WN(s, p, v) (((av_alias##s*)(p))->u##s = (v)) + +#else + +#ifndef AV_RB16 +# define AV_RB16(x) \ + ((((const uint8_t*)(x))[0] << 8) | \ + ((const uint8_t*)(x))[1]) +#endif +#ifndef AV_WB16 +# define AV_WB16(p, val) do { \ + uint16_t d = (val); \ + ((uint8_t*)(p))[1] = (d); \ + ((uint8_t*)(p))[0] = (d)>>8; \ + } while(0) +#endif + +#ifndef AV_RL16 +# define AV_RL16(x) \ + ((((const uint8_t*)(x))[1] << 8) | \ + ((const uint8_t*)(x))[0]) +#endif +#ifndef AV_WL16 +# define AV_WL16(p, val) do { \ + uint16_t d = (val); \ + ((uint8_t*)(p))[0] = (d); \ + ((uint8_t*)(p))[1] = (d)>>8; \ + } while(0) +#endif + +#ifndef AV_RB32 +# define AV_RB32(x) \ + (((uint32_t)((const uint8_t*)(x))[0] << 24) | \ + (((const uint8_t*)(x))[1] << 16) | \ + (((const uint8_t*)(x))[2] << 8) | \ + ((const uint8_t*)(x))[3]) +#endif +#ifndef AV_WB32 +# define AV_WB32(p, val) do { \ + uint32_t d = (val); \ + ((uint8_t*)(p))[3] = (d); \ + ((uint8_t*)(p))[2] = (d)>>8; \ + ((uint8_t*)(p))[1] = (d)>>16; \ + ((uint8_t*)(p))[0] = (d)>>24; \ + } while(0) +#endif + +#ifndef AV_RL32 +# define AV_RL32(x) \ + (((uint32_t)((const uint8_t*)(x))[3] << 24) | \ + (((const uint8_t*)(x))[2] << 16) | \ + (((const uint8_t*)(x))[1] << 8) | \ + ((const uint8_t*)(x))[0]) +#endif +#ifndef AV_WL32 +# define AV_WL32(p, val) do { \ + uint32_t d = (val); \ + ((uint8_t*)(p))[0] = (d); \ + ((uint8_t*)(p))[1] = (d)>>8; \ + ((uint8_t*)(p))[2] = (d)>>16; \ + ((uint8_t*)(p))[3] = (d)>>24; \ + } while(0) +#endif + +#ifndef AV_RB64 +# define AV_RB64(x) \ + (((uint64_t)((const uint8_t*)(x))[0] << 56) | \ + ((uint64_t)((const uint8_t*)(x))[1] << 48) | \ + ((uint64_t)((const uint8_t*)(x))[2] << 40) | \ + ((uint64_t)((const uint8_t*)(x))[3] << 32) | \ + ((uint64_t)((const uint8_t*)(x))[4] << 24) | \ + ((uint64_t)((const uint8_t*)(x))[5] << 16) | \ + ((uint64_t)((const uint8_t*)(x))[6] << 8) | \ + (uint64_t)((const uint8_t*)(x))[7]) +#endif +#ifndef AV_WB64 +# define AV_WB64(p, val) do { \ + uint64_t d = (val); \ + ((uint8_t*)(p))[7] = (d); \ + ((uint8_t*)(p))[6] = (d)>>8; \ + ((uint8_t*)(p))[5] = (d)>>16; \ + ((uint8_t*)(p))[4] = (d)>>24; \ + ((uint8_t*)(p))[3] = (d)>>32; \ + ((uint8_t*)(p))[2] = (d)>>40; \ + ((uint8_t*)(p))[1] = (d)>>48; \ + ((uint8_t*)(p))[0] = (d)>>56; \ + } while(0) +#endif + +#ifndef AV_RL64 +# define AV_RL64(x) \ + (((uint64_t)((const uint8_t*)(x))[7] << 56) | \ + ((uint64_t)((const uint8_t*)(x))[6] << 48) | \ + ((uint64_t)((const uint8_t*)(x))[5] << 40) | \ + ((uint64_t)((const uint8_t*)(x))[4] << 32) | \ + ((uint64_t)((const uint8_t*)(x))[3] << 24) | \ + ((uint64_t)((const uint8_t*)(x))[2] << 16) | \ + ((uint64_t)((const uint8_t*)(x))[1] << 8) | \ + (uint64_t)((const uint8_t*)(x))[0]) +#endif +#ifndef AV_WL64 +# define AV_WL64(p, val) do { \ + uint64_t d = (val); \ + ((uint8_t*)(p))[0] = (d); \ + ((uint8_t*)(p))[1] = (d)>>8; \ + ((uint8_t*)(p))[2] = (d)>>16; \ + ((uint8_t*)(p))[3] = (d)>>24; \ + ((uint8_t*)(p))[4] = (d)>>32; \ + ((uint8_t*)(p))[5] = (d)>>40; \ + ((uint8_t*)(p))[6] = (d)>>48; \ + ((uint8_t*)(p))[7] = (d)>>56; \ + } while(0) +#endif + +#if AV_HAVE_BIGENDIAN +# define AV_RN(s, p) AV_RB##s(p) +# define AV_WN(s, p, v) AV_WB##s(p, v) +#else +# define AV_RN(s, p) AV_RL##s(p) +# define AV_WN(s, p, v) AV_WL##s(p, v) +#endif + +#endif /* HAVE_FAST_UNALIGNED */ + +#ifndef AV_RN16 +# define AV_RN16(p) AV_RN(16, p) +#endif + +#ifndef AV_RN32 +# define AV_RN32(p) AV_RN(32, p) +#endif + +#ifndef AV_RN64 +# define AV_RN64(p) AV_RN(64, p) +#endif + +#ifndef AV_WN16 +# define AV_WN16(p, v) AV_WN(16, p, v) +#endif + +#ifndef AV_WN32 +# define AV_WN32(p, v) AV_WN(32, p, v) +#endif + +#ifndef AV_WN64 +# define AV_WN64(p, v) AV_WN(64, p, v) +#endif + +#if AV_HAVE_BIGENDIAN +# define AV_RB(s, p) AV_RN##s(p) +# define AV_WB(s, p, v) AV_WN##s(p, v) +# define AV_RL(s, p) av_bswap##s(AV_RN##s(p)) +# define AV_WL(s, p, v) AV_WN##s(p, av_bswap##s(v)) +#else +# define AV_RB(s, p) av_bswap##s(AV_RN##s(p)) +# define AV_WB(s, p, v) AV_WN##s(p, av_bswap##s(v)) +# define AV_RL(s, p) AV_RN##s(p) +# define AV_WL(s, p, v) AV_WN##s(p, v) +#endif + +#define AV_RB8(x) (((const uint8_t*)(x))[0]) +#define AV_WB8(p, d) do { ((uint8_t*)(p))[0] = (d); } while(0) + +#define AV_RL8(x) AV_RB8(x) +#define AV_WL8(p, d) AV_WB8(p, d) + +#ifndef AV_RB16 +# define AV_RB16(p) AV_RB(16, p) +#endif +#ifndef AV_WB16 +# define AV_WB16(p, v) AV_WB(16, p, v) +#endif + +#ifndef AV_RL16 +# define AV_RL16(p) AV_RL(16, p) +#endif +#ifndef AV_WL16 +# define AV_WL16(p, v) AV_WL(16, p, v) +#endif + +#ifndef AV_RB32 +# define AV_RB32(p) AV_RB(32, p) +#endif +#ifndef AV_WB32 +# define AV_WB32(p, v) AV_WB(32, p, v) +#endif + +#ifndef AV_RL32 +# define AV_RL32(p) AV_RL(32, p) +#endif +#ifndef AV_WL32 +# define AV_WL32(p, v) AV_WL(32, p, v) +#endif + +#ifndef AV_RB64 +# define AV_RB64(p) AV_RB(64, p) +#endif +#ifndef AV_WB64 +# define AV_WB64(p, v) AV_WB(64, p, v) +#endif + +#ifndef AV_RL64 +# define AV_RL64(p) AV_RL(64, p) +#endif +#ifndef AV_WL64 +# define AV_WL64(p, v) AV_WL(64, p, v) +#endif + +#ifndef AV_RB24 +# define AV_RB24(x) \ + ((((const uint8_t*)(x))[0] << 16) | \ + (((const uint8_t*)(x))[1] << 8) | \ + ((const uint8_t*)(x))[2]) +#endif +#ifndef AV_WB24 +# define AV_WB24(p, d) do { \ + ((uint8_t*)(p))[2] = (d); \ + ((uint8_t*)(p))[1] = (d)>>8; \ + ((uint8_t*)(p))[0] = (d)>>16; \ + } while(0) +#endif + +#ifndef AV_RL24 +# define AV_RL24(x) \ + ((((const uint8_t*)(x))[2] << 16) | \ + (((const uint8_t*)(x))[1] << 8) | \ + ((const uint8_t*)(x))[0]) +#endif +#ifndef AV_WL24 +# define AV_WL24(p, d) do { \ + ((uint8_t*)(p))[0] = (d); \ + ((uint8_t*)(p))[1] = (d)>>8; \ + ((uint8_t*)(p))[2] = (d)>>16; \ + } while(0) +#endif + +#ifndef AV_RB48 +# define AV_RB48(x) \ + (((uint64_t)((const uint8_t*)(x))[0] << 40) | \ + ((uint64_t)((const uint8_t*)(x))[1] << 32) | \ + ((uint64_t)((const uint8_t*)(x))[2] << 24) | \ + ((uint64_t)((const uint8_t*)(x))[3] << 16) | \ + ((uint64_t)((const uint8_t*)(x))[4] << 8) | \ + (uint64_t)((const uint8_t*)(x))[5]) +#endif +#ifndef AV_WB48 +# define AV_WB48(p, darg) do { \ + uint64_t d = (darg); \ + ((uint8_t*)(p))[5] = (d); \ + ((uint8_t*)(p))[4] = (d)>>8; \ + ((uint8_t*)(p))[3] = (d)>>16; \ + ((uint8_t*)(p))[2] = (d)>>24; \ + ((uint8_t*)(p))[1] = (d)>>32; \ + ((uint8_t*)(p))[0] = (d)>>40; \ + } while(0) +#endif + +#ifndef AV_RL48 +# define AV_RL48(x) \ + (((uint64_t)((const uint8_t*)(x))[5] << 40) | \ + ((uint64_t)((const uint8_t*)(x))[4] << 32) | \ + ((uint64_t)((const uint8_t*)(x))[3] << 24) | \ + ((uint64_t)((const uint8_t*)(x))[2] << 16) | \ + ((uint64_t)((const uint8_t*)(x))[1] << 8) | \ + (uint64_t)((const uint8_t*)(x))[0]) +#endif +#ifndef AV_WL48 +# define AV_WL48(p, darg) do { \ + uint64_t d = (darg); \ + ((uint8_t*)(p))[0] = (d); \ + ((uint8_t*)(p))[1] = (d)>>8; \ + ((uint8_t*)(p))[2] = (d)>>16; \ + ((uint8_t*)(p))[3] = (d)>>24; \ + ((uint8_t*)(p))[4] = (d)>>32; \ + ((uint8_t*)(p))[5] = (d)>>40; \ + } while(0) +#endif + +/* + * The AV_[RW]NA macros access naturally aligned data + * in a type-safe way. + */ + +#define AV_RNA(s, p) (((const av_alias##s*)(p))->u##s) +#define AV_WNA(s, p, v) (((av_alias##s*)(p))->u##s = (v)) + +#ifndef AV_RN16A +# define AV_RN16A(p) AV_RNA(16, p) +#endif + +#ifndef AV_RN32A +# define AV_RN32A(p) AV_RNA(32, p) +#endif + +#ifndef AV_RN64A +# define AV_RN64A(p) AV_RNA(64, p) +#endif + +#ifndef AV_WN16A +# define AV_WN16A(p, v) AV_WNA(16, p, v) +#endif + +#ifndef AV_WN32A +# define AV_WN32A(p, v) AV_WNA(32, p, v) +#endif + +#ifndef AV_WN64A +# define AV_WN64A(p, v) AV_WNA(64, p, v) +#endif + +#if AV_HAVE_BIGENDIAN +# define AV_RLA(s, p) av_bswap##s(AV_RN##s##A(p)) +# define AV_WLA(s, p, v) AV_WN##s##A(p, av_bswap##s(v)) +# define AV_RBA(s, p) AV_RN##s##A(p) +# define AV_WBA(s, p, v) AV_WN##s##A(p, v) +#else +# define AV_RLA(s, p) AV_RN##s##A(p) +# define AV_WLA(s, p, v) AV_WN##s##A(p, v) +# define AV_RBA(s, p) av_bswap##s(AV_RN##s##A(p)) +# define AV_WBA(s, p, v) AV_WN##s##A(p, av_bswap##s(v)) +#endif + +#ifndef AV_RL16A +# define AV_RL16A(p) AV_RLA(16, p) +#endif +#ifndef AV_WL16A +# define AV_WL16A(p, v) AV_WLA(16, p, v) +#endif + +#ifndef AV_RB16A +# define AV_RB16A(p) AV_RBA(16, p) +#endif +#ifndef AV_WB16A +# define AV_WB16A(p, v) AV_WBA(16, p, v) +#endif + +#ifndef AV_RL32A +# define AV_RL32A(p) AV_RLA(32, p) +#endif +#ifndef AV_WL32A +# define AV_WL32A(p, v) AV_WLA(32, p, v) +#endif + +#ifndef AV_RB32A +# define AV_RB32A(p) AV_RBA(32, p) +#endif +#ifndef AV_WB32A +# define AV_WB32A(p, v) AV_WBA(32, p, v) +#endif + +#ifndef AV_RL64A +# define AV_RL64A(p) AV_RLA(64, p) +#endif +#ifndef AV_WL64A +# define AV_WL64A(p, v) AV_WLA(64, p, v) +#endif + +#ifndef AV_RB64A +# define AV_RB64A(p) AV_RBA(64, p) +#endif +#ifndef AV_WB64A +# define AV_WB64A(p, v) AV_WBA(64, p, v) +#endif + +/* + * The AV_COPYxxU macros are suitable for copying data to/from unaligned + * memory locations. + */ + +#define AV_COPYU(n, d, s) AV_WN##n(d, AV_RN##n(s)); + +#ifndef AV_COPY16U +# define AV_COPY16U(d, s) AV_COPYU(16, d, s) +#endif + +#ifndef AV_COPY32U +# define AV_COPY32U(d, s) AV_COPYU(32, d, s) +#endif + +#ifndef AV_COPY64U +# define AV_COPY64U(d, s) AV_COPYU(64, d, s) +#endif + +#ifndef AV_COPY128U +# define AV_COPY128U(d, s) \ + do { \ + AV_COPY64U(d, s); \ + AV_COPY64U((char *)(d) + 8, (const char *)(s) + 8); \ + } while(0) +#endif + +/* Parameters for AV_COPY*, AV_SWAP*, AV_ZERO* must be + * naturally aligned. + */ + +#define AV_COPY(n, d, s) \ + (((av_alias##n*)(d))->u##n = ((const av_alias##n*)(s))->u##n) + +#ifndef AV_COPY16 +# define AV_COPY16(d, s) AV_COPY(16, d, s) +#endif + +#ifndef AV_COPY32 +# define AV_COPY32(d, s) AV_COPY(32, d, s) +#endif + +#ifndef AV_COPY64 +# define AV_COPY64(d, s) AV_COPY(64, d, s) +#endif + +#ifndef AV_COPY128 +# define AV_COPY128(d, s) \ + do { \ + AV_COPY64(d, s); \ + AV_COPY64((char*)(d)+8, (char*)(s)+8); \ + } while(0) +#endif + +#define AV_SWAP(n, a, b) FFSWAP(av_alias##n, *(av_alias##n*)(a), *(av_alias##n*)(b)) + +#ifndef AV_SWAP64 +# define AV_SWAP64(a, b) AV_SWAP(64, a, b) +#endif + +#define AV_ZERO(n, d) (((av_alias##n*)(d))->u##n = 0) + +#ifndef AV_ZERO16 +# define AV_ZERO16(d) AV_ZERO(16, d) +#endif + +#ifndef AV_ZERO32 +# define AV_ZERO32(d) AV_ZERO(32, d) +#endif + +#ifndef AV_ZERO64 +# define AV_ZERO64(d) AV_ZERO(64, d) +#endif + +#ifndef AV_ZERO128 +# define AV_ZERO128(d) \ + do { \ + AV_ZERO64(d); \ + AV_ZERO64((char*)(d)+8); \ + } while(0) +#endif + +#endif /* AVUTIL_INTREADWRITE_H */ diff --git a/ffmpeg-n8.1/include/libavutil/lfg.h b/ffmpeg-n8.1/include/libavutil/lfg.h new file mode 100644 index 00000000..043d0ab3 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/lfg.h @@ -0,0 +1,81 @@ +/* + * Lagged Fibonacci PRNG + * Copyright (c) 2008 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_LFG_H +#define AVUTIL_LFG_H + +#include + +/** + * Context structure for the Lagged Fibonacci PRNG. + * The exact layout, types and content of this struct may change and should + * not be accessed directly. Only its `sizeof()` is guaranteed to stay the same + * to allow easy instantiation. + */ +typedef struct AVLFG { + unsigned int state[64]; + int index; +} AVLFG; + +void av_lfg_init(AVLFG *c, unsigned int seed); + +/** + * Seed the state of the ALFG using binary data. + * + * @return 0 on success, negative value (AVERROR) on failure. + */ +int av_lfg_init_from_data(AVLFG *c, const uint8_t *data, unsigned int length); + +/** + * Get the next random unsigned 32-bit number using an ALFG. + * + * Please also consider a simple LCG like state= state*1664525+1013904223, + * it may be good enough and faster for your specific use case. + */ +static inline unsigned int av_lfg_get(AVLFG *c){ + unsigned a = c->state[c->index & 63] = c->state[(c->index-24) & 63] + c->state[(c->index-55) & 63]; + c->index += 1U; + return a; +} + +/** + * Get the next random unsigned 32-bit number using a MLFG. + * + * Please also consider av_lfg_get() above, it is faster. + */ +static inline unsigned int av_mlfg_get(AVLFG *c){ + unsigned int a= c->state[(c->index-55) & 63]; + unsigned int b= c->state[(c->index-24) & 63]; + a = c->state[c->index & 63] = 2*a*b+a+b; + c->index += 1U; + return a; +} + +/** + * Get the next two numbers generated by a Box-Muller Gaussian + * generator using the random numbers issued by lfg. + * + * @param lfg pointer to the context structure + * @param out array where the two generated numbers are placed + */ +void av_bmg_get(AVLFG *lfg, double out[2]); + +#endif /* AVUTIL_LFG_H */ diff --git a/ffmpeg-n8.1/include/libavutil/log.h b/ffmpeg-n8.1/include/libavutil/log.h new file mode 100644 index 00000000..4a111ca9 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/log.h @@ -0,0 +1,427 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_LOG_H +#define AVUTIL_LOG_H + +#include +#include "attributes.h" +#include "version.h" + +typedef enum { + AV_CLASS_CATEGORY_NA = 0, + AV_CLASS_CATEGORY_INPUT, + AV_CLASS_CATEGORY_OUTPUT, + AV_CLASS_CATEGORY_MUXER, + AV_CLASS_CATEGORY_DEMUXER, + AV_CLASS_CATEGORY_ENCODER, + AV_CLASS_CATEGORY_DECODER, + AV_CLASS_CATEGORY_FILTER, + AV_CLASS_CATEGORY_BITSTREAM_FILTER, + AV_CLASS_CATEGORY_SWSCALER, + AV_CLASS_CATEGORY_SWRESAMPLER, + AV_CLASS_CATEGORY_HWDEVICE, + AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT = 40, + AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT, + AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT, + AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT, + AV_CLASS_CATEGORY_DEVICE_OUTPUT, + AV_CLASS_CATEGORY_DEVICE_INPUT, + AV_CLASS_CATEGORY_NB ///< not part of ABI/API +}AVClassCategory; + +enum AVClassStateFlags { + /** + * Object initialization has finished and it is now in the 'runtime' stage. + * This affects e.g. what options can be set on the object (only + * AV_OPT_FLAG_RUNTIME_PARAM options can be set on initialized objects). + */ + AV_CLASS_STATE_INITIALIZED = (1 << 0), +}; + +#define AV_IS_INPUT_DEVICE(category) \ + (((category) == AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT) || \ + ((category) == AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT) || \ + ((category) == AV_CLASS_CATEGORY_DEVICE_INPUT)) + +#define AV_IS_OUTPUT_DEVICE(category) \ + (((category) == AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT) || \ + ((category) == AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT) || \ + ((category) == AV_CLASS_CATEGORY_DEVICE_OUTPUT)) + +struct AVOptionRanges; + +/** + * Describe the class of an AVClass context structure. That is an + * arbitrary struct of which the first field is a pointer to an + * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.). + */ +typedef struct AVClass { + /** + * The name of the class; usually it is the same name as the + * context structure type to which the AVClass is associated. + */ + const char* class_name; + + /** + * A pointer to a function which returns the name of a context + * instance ctx associated with the class. + */ + const char* (*item_name)(void* ctx); + + /** + * An array of options for the structure or NULL. + * When non-NULL, the array must be terminated by an option with a NULL + * name. + * + * @see av_set_default_options() + */ + const struct AVOption *option; + + /** + * LIBAVUTIL_VERSION with which this structure was created. + * This is used to allow fields to be added to AVClass without requiring + * major version bumps everywhere. + */ + + int version; + + /** + * Offset in the structure where the log level offset is stored. The log + * level offset is an int added to the log level for logging with this + * object as the context. + * + * 0 means there is no such variable. + */ + int log_level_offset_offset; + + /** + * Offset in the structure where a pointer to the parent context for + * logging is stored. For example a decoder could pass its AVCodecContext + * to eval as such a parent context, which an ::av_log() implementation + * could then leverage to display the parent context. + * + * When the pointer is NULL, or this offset is zero, the object is assumed + * to have no parent. + */ + int parent_log_context_offset; + + /** + * Category used for visualization (like color). + * + * Only used when ::get_category() is NULL. Use this field when all + * instances of this class have the same category, use ::get_category() + * otherwise. + */ + AVClassCategory category; + + /** + * Callback to return the instance category. Use this callback when + * different instances of this class may have different categories, + * ::category otherwise. + */ + AVClassCategory (*get_category)(void* ctx); + + /** + * Callback to return the supported/allowed ranges. + */ + int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags); + + /** + * Return next AVOptions-enabled child or NULL + */ + void* (*child_next)(void *obj, void *prev); + + /** + * Iterate over the AVClasses corresponding to potential AVOptions-enabled + * children. + * + * @param iter pointer to opaque iteration state. The caller must initialize + * *iter to NULL before the first call. + * @return AVClass for the next AVOptions-enabled child or NULL if there are + * no more such children. + * + * @note The difference between ::child_next() and ::child_class_iterate() + * is that ::child_next() iterates over _actual_ children of an + * _existing_ object instance, while ::child_class_iterate() iterates + * over the classes of all _potential_ children of any possible + * instance of this class. + */ + const struct AVClass* (*child_class_iterate)(void **iter); + + /** + * When non-zero, offset in the object to an unsigned int holding object + * state flags, a combination of AVClassStateFlags values. The flags are + * updated by the object to signal its state to the generic code. + * + * Added in version 59.41.100. + */ + int state_flags_offset; +} AVClass; + +/** + * @addtogroup lavu_log + * + * @{ + * + * @defgroup lavu_log_constants Logging Constants + * + * @{ + */ + +/** + * Print no output. + */ +#define AV_LOG_QUIET -8 + +/** + * Something went really wrong and we will crash now. + */ +#define AV_LOG_PANIC 0 + +/** + * Something went wrong and recovery is not possible. + * For example, no header was found for a format which depends + * on headers or an illegal combination of parameters is used. + */ +#define AV_LOG_FATAL 8 + +/** + * Something went wrong and cannot losslessly be recovered. + * However, not all future data is affected. + */ +#define AV_LOG_ERROR 16 + +/** + * Something somehow does not look correct. This may or may not + * lead to problems. An example would be the use of '-vstrict -2'. + */ +#define AV_LOG_WARNING 24 + +/** + * Standard information. + */ +#define AV_LOG_INFO 32 + +/** + * Detailed information. + */ +#define AV_LOG_VERBOSE 40 + +/** + * Stuff which is only useful for libav* developers. + */ +#define AV_LOG_DEBUG 48 + +/** + * Extremely verbose debugging, useful for libav* development. + */ +#define AV_LOG_TRACE 56 + +#define AV_LOG_MAX_OFFSET (AV_LOG_TRACE - AV_LOG_QUIET) + +/** + * @} + */ + +/** + * Sets additional colors for extended debugging sessions. + * @code + av_log(ctx, AV_LOG_DEBUG|AV_LOG_C(134), "Message in purple\n"); + @endcode + * Requires 256color terminal support. Uses outside debugging is not + * recommended. + */ +#define AV_LOG_C(x) ((x) << 8) + +/** + * Send the specified message to the log if the level is less than or equal + * to the current av_log_level. By default, all logging messages are sent to + * stderr. This behavior can be altered by setting a different logging callback + * function. + * @see av_log_set_callback + * + * @param avcl A pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct or NULL if general log. + * @param level The importance level of the message expressed using a @ref + * lavu_log_constants "Logging Constant". + * @param fmt The format string (printf-compatible) that specifies how + * subsequent arguments are converted to output. + */ +void av_log(void *avcl, int level, const char *fmt, ...) av_printf_format(3, 4); + +/** + * Send the specified message to the log once with the initial_level and then with + * the subsequent_level. By default, all logging messages are sent to + * stderr. This behavior can be altered by setting a different logging callback + * function. + * @see av_log + * + * @param avcl A pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct or NULL if general log. + * @param initial_level importance level of the message expressed using a @ref + * lavu_log_constants "Logging Constant" for the first occurrence. + * @param subsequent_level importance level of the message expressed using a @ref + * lavu_log_constants "Logging Constant" after the first occurrence. + * @param fmt The format string (printf-compatible) that specifies how + * subsequent arguments are converted to output. + * @param state a variable to keep trak of if a message has already been printed + * this must be initialized to 0 before the first use. The same state + * must not be accessed by 2 Threads simultaneously. + */ +void av_log_once(void* avcl, int initial_level, int subsequent_level, int *state, const char *fmt, ...) av_printf_format(5, 6); + + +/** + * Send the specified message to the log if the level is less than or equal + * to the current av_log_level. By default, all logging messages are sent to + * stderr. This behavior can be altered by setting a different logging callback + * function. + * @see av_log_set_callback + * + * @param avcl A pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct. + * @param level The importance level of the message expressed using a @ref + * lavu_log_constants "Logging Constant". + * @param fmt The format string (printf-compatible) that specifies how + * subsequent arguments are converted to output. + * @param vl The arguments referenced by the format string. + */ +void av_vlog(void *avcl, int level, const char *fmt, va_list vl); + +/** + * Get the current log level + * + * @see lavu_log_constants + * + * @return Current log level + */ +int av_log_get_level(void); + +/** + * Set the log level + * + * @see lavu_log_constants + * + * @param level Logging level + */ +void av_log_set_level(int level); + +/** + * Set the logging callback + * + * @note The callback must be thread safe, even if the application does not use + * threads itself as some codecs are multithreaded. + * + * @see av_log_default_callback + * + * @param callback A logging function with a compatible signature. + */ +void av_log_set_callback(void (*callback)(void*, int, const char*, va_list)); + +/** + * Default logging callback + * + * It prints the message to stderr, optionally colorizing it. + * + * @param avcl A pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct. + * @param level The importance level of the message expressed using a @ref + * lavu_log_constants "Logging Constant". + * @param fmt The format string (printf-compatible) that specifies how + * subsequent arguments are converted to output. + * @param vl The arguments referenced by the format string. + */ +void av_log_default_callback(void *avcl, int level, const char *fmt, + va_list vl); + +/** + * Return the context name + * + * @param ctx The AVClass context + * + * @return The AVClass class_name + */ +const char* av_default_item_name(void* ctx); +AVClassCategory av_default_get_category(void *ptr); + +/** + * Format a line of log the same way as the default callback. + * @param line buffer to receive the formatted line + * @param line_size size of the buffer + * @param print_prefix used to store whether the prefix must be printed; + * must point to a persistent integer initially set to 1 + */ +void av_log_format_line(void *ptr, int level, const char *fmt, va_list vl, + char *line, int line_size, int *print_prefix); + +/** + * Format a line of log the same way as the default callback. + * @param line buffer to receive the formatted line; + * may be NULL if line_size is 0 + * @param line_size size of the buffer; at most line_size-1 characters will + * be written to the buffer, plus one null terminator + * @param print_prefix used to store whether the prefix must be printed; + * must point to a persistent integer initially set to 1 + * @return Returns a negative value if an error occurred, otherwise returns + * the number of characters that would have been written for a + * sufficiently large buffer, not including the terminating null + * character. If the return value is not less than line_size, it means + * that the log message was truncated to fit the buffer. + */ +int av_log_format_line2(void *ptr, int level, const char *fmt, va_list vl, + char *line, int line_size, int *print_prefix); + +/** + * Skip repeated messages, this requires the user app to use av_log() instead of + * (f)printf as the 2 would otherwise interfere and lead to + * "Last message repeated x times" messages below (f)printf messages with some + * bad luck. + * Also to receive the last, "last repeated" line if any, the user app must + * call av_log(NULL, AV_LOG_QUIET, "%s", ""); at the end + */ +#define AV_LOG_SKIP_REPEATED 1 + +/** + * Include the log severity in messages originating from codecs. + * + * Results in messages such as: + * [rawvideo @ 0xDEADBEEF] [error] encode did not produce valid pts + */ +#define AV_LOG_PRINT_LEVEL 2 + +/** + * Include system time in log output. + */ +#define AV_LOG_PRINT_TIME 4 + +/** + * Include system date and time in log output. + */ +#define AV_LOG_PRINT_DATETIME 8 + +void av_log_set_flags(int arg); +int av_log_get_flags(void); + +/** + * @} + */ + +#endif /* AVUTIL_LOG_H */ diff --git a/ffmpeg-n8.1/include/libavutil/lzo.h b/ffmpeg-n8.1/include/libavutil/lzo.h new file mode 100644 index 00000000..c0340399 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/lzo.h @@ -0,0 +1,66 @@ +/* + * LZO 1x decompression + * copyright (c) 2006 Reimar Doeffinger + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_LZO_H +#define AVUTIL_LZO_H + +/** + * @defgroup lavu_lzo LZO + * @ingroup lavu_crypto + * + * @{ + */ + +#include + +/** @name Error flags returned by av_lzo1x_decode + * @{ */ +/// end of the input buffer reached before decoding finished +#define AV_LZO_INPUT_DEPLETED 1 +/// decoded data did not fit into output buffer +#define AV_LZO_OUTPUT_FULL 2 +/// a reference to previously decoded data was wrong +#define AV_LZO_INVALID_BACKPTR 4 +/// a non-specific error in the compressed bitstream +#define AV_LZO_ERROR 8 +/** @} */ + +#define AV_LZO_INPUT_PADDING 8 +#define AV_LZO_OUTPUT_PADDING 12 + +/** + * @brief Decodes LZO 1x compressed data. + * @param out output buffer + * @param outlen size of output buffer, number of bytes left are returned here + * @param in input buffer + * @param inlen size of input buffer, number of bytes left are returned here + * @return 0 on success, otherwise a combination of the error flags above + * + * Make sure all buffers are appropriately padded, in must provide + * AV_LZO_INPUT_PADDING, out must provide AV_LZO_OUTPUT_PADDING additional bytes. + */ +int av_lzo1x_decode(void *out, int *outlen, const void *in, int *inlen); + +/** + * @} + */ + +#endif /* AVUTIL_LZO_H */ diff --git a/ffmpeg-n8.1/include/libavutil/macros.h b/ffmpeg-n8.1/include/libavutil/macros.h new file mode 100644 index 00000000..2a7567c3 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/macros.h @@ -0,0 +1,80 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu + * Utility Preprocessor macros + */ + +#ifndef AVUTIL_MACROS_H +#define AVUTIL_MACROS_H + +#include "libavutil/avconfig.h" + +#if AV_HAVE_BIGENDIAN +# define AV_NE(be, le) (be) +#else +# define AV_NE(be, le) (le) +#endif + +/** + * Comparator. + * For two numerical expressions x and y, gives 1 if x > y, -1 if x < y, and 0 + * if x == y. This is useful for instance in a qsort comparator callback. + * Furthermore, compilers are able to optimize this to branchless code, and + * there is no risk of overflow with signed types. + * As with many macros, this evaluates its argument multiple times, it thus + * must not have a side-effect. + */ +#define FFDIFFSIGN(x,y) (((x)>(y)) - ((x)<(y))) + +#define FFMAX(a,b) ((a) > (b) ? (a) : (b)) +#define FFMAX3(a,b,c) FFMAX(FFMAX(a,b),c) +#define FFMIN(a,b) ((a) > (b) ? (b) : (a)) +#define FFMIN3(a,b,c) FFMIN(FFMIN(a,b),c) + +#define FFSWAP(type,a,b) do{type SWAP_tmp= b; b= a; a= SWAP_tmp;}while(0) +#define FF_ARRAY_ELEMS(a) (sizeof(a) / sizeof((a)[0])) + +#define MKTAG(a,b,c,d) ((a) | ((b) << 8) | ((c) << 16) | ((unsigned)(d) << 24)) +#define MKBETAG(a,b,c,d) ((d) | ((c) << 8) | ((b) << 16) | ((unsigned)(a) << 24)) + +/** + * @addtogroup preproc_misc Preprocessor String Macros + * + * String manipulation macros + * + * @{ + */ + +#define AV_STRINGIFY(s) AV_TOSTRING(s) +#define AV_TOSTRING(s) #s + +#define AV_GLUE(a, b) a ## b +#define AV_JOIN(a, b) AV_GLUE(a, b) + +/** + * @} + */ + +#define AV_PRAGMA(s) _Pragma(#s) + +#define FFALIGN(x, a) (((x)+(a)-1)&~((a)-1)) + +#endif /* AVUTIL_MACROS_H */ diff --git a/ffmpeg-n8.1/include/libavutil/mastering_display_metadata.h b/ffmpeg-n8.1/include/libavutil/mastering_display_metadata.h new file mode 100644 index 00000000..52fcef9e --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/mastering_display_metadata.h @@ -0,0 +1,137 @@ +/* + * Copyright (c) 2016 Neil Birkbeck + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_MASTERING_DISPLAY_METADATA_H +#define AVUTIL_MASTERING_DISPLAY_METADATA_H + +#include "frame.h" +#include "rational.h" + + +/** + * Mastering display metadata capable of representing the color volume of + * the display used to master the content (SMPTE 2086:2014). + * + * To be used as payload of a AVFrameSideData or AVPacketSideData with the + * appropriate type. + * + * @note The struct should be allocated with av_mastering_display_metadata_alloc() + * and its size is not a part of the public ABI. + */ +typedef struct AVMasteringDisplayMetadata { + /** + * CIE 1931 xy chromaticity coords of color primaries (r, g, b order). + */ + AVRational display_primaries[3][2]; + + /** + * CIE 1931 xy chromaticity coords of white point. + */ + AVRational white_point[2]; + + /** + * Min luminance of mastering display (cd/m^2). + */ + AVRational min_luminance; + + /** + * Max luminance of mastering display (cd/m^2). + */ + AVRational max_luminance; + + /** + * Flag indicating whether the display primaries (and white point) are set. + */ + int has_primaries; + + /** + * Flag indicating whether the luminance (min_ and max_) have been set. + */ + int has_luminance; + +} AVMasteringDisplayMetadata; + +/** + * Allocate an AVMasteringDisplayMetadata structure and set its fields to + * default values. The resulting struct can be freed using av_freep(). + * + * @return An AVMasteringDisplayMetadata filled with default values or NULL + * on failure. + */ +AVMasteringDisplayMetadata *av_mastering_display_metadata_alloc(void); + +/** + * Allocate an AVMasteringDisplayMetadata structure and set its fields to + * default values. The resulting struct can be freed using av_freep(). + * + * @return An AVMasteringDisplayMetadata filled with default values or NULL + * on failure. + */ +AVMasteringDisplayMetadata *av_mastering_display_metadata_alloc_size(size_t *size); + +/** + * Allocate a complete AVMasteringDisplayMetadata and add it to the frame. + * + * @param frame The frame which side data is added to. + * + * @return The AVMasteringDisplayMetadata structure to be filled by caller. + */ +AVMasteringDisplayMetadata *av_mastering_display_metadata_create_side_data(AVFrame *frame); + +/** + * Content light level needed by to transmit HDR over HDMI (CTA-861.3). + * + * To be used as payload of a AVFrameSideData or AVPacketSideData with the + * appropriate type. + * + * @note The struct should be allocated with av_content_light_metadata_alloc() + * and its size is not a part of the public ABI. + */ +typedef struct AVContentLightMetadata { + /** + * Max content light level (cd/m^2). + */ + unsigned MaxCLL; + + /** + * Max average light level per frame (cd/m^2). + */ + unsigned MaxFALL; +} AVContentLightMetadata; + +/** + * Allocate an AVContentLightMetadata structure and set its fields to + * default values. The resulting struct can be freed using av_freep(). + * + * @return An AVContentLightMetadata filled with default values or NULL + * on failure. + */ +AVContentLightMetadata *av_content_light_metadata_alloc(size_t *size); + +/** + * Allocate a complete AVContentLightMetadata and add it to the frame. + * + * @param frame The frame which side data is added to. + * + * @return The AVContentLightMetadata structure to be filled by caller. + */ +AVContentLightMetadata *av_content_light_metadata_create_side_data(AVFrame *frame); + +#endif /* AVUTIL_MASTERING_DISPLAY_METADATA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/mathematics.h b/ffmpeg-n8.1/include/libavutil/mathematics.h new file mode 100644 index 00000000..486de530 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/mathematics.h @@ -0,0 +1,300 @@ +/* + * copyright (c) 2005-2012 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @addtogroup lavu_math + * Mathematical utilities for working with timestamp and time base. + */ + +#ifndef AVUTIL_MATHEMATICS_H +#define AVUTIL_MATHEMATICS_H + +#include +#include +#include "attributes.h" +#include "rational.h" +#include "intfloat.h" + +#ifndef M_E +#define M_E 2.7182818284590452354 /* e */ +#endif +#ifndef M_Ef +#define M_Ef 2.7182818284590452354f /* e */ +#endif +#ifndef M_LN2 +#define M_LN2 0.69314718055994530942 /* log_e 2 */ +#endif +#ifndef M_LN2f +#define M_LN2f 0.69314718055994530942f /* log_e 2 */ +#endif +#ifndef M_LN10 +#define M_LN10 2.30258509299404568402 /* log_e 10 */ +#endif +#ifndef M_LN10f +#define M_LN10f 2.30258509299404568402f /* log_e 10 */ +#endif +#ifndef M_LOG2_10 +#define M_LOG2_10 3.32192809488736234787 /* log_2 10 */ +#endif +#ifndef M_LOG2_10f +#define M_LOG2_10f 3.32192809488736234787f /* log_2 10 */ +#endif +#ifndef M_PHI +#define M_PHI 1.61803398874989484820 /* phi / golden ratio */ +#endif +#ifndef M_PHIf +#define M_PHIf 1.61803398874989484820f /* phi / golden ratio */ +#endif +#ifndef M_PI +#define M_PI 3.14159265358979323846 /* pi */ +#endif +#ifndef M_PIf +#define M_PIf 3.14159265358979323846f /* pi */ +#endif +#ifndef M_PI_2 +#define M_PI_2 1.57079632679489661923 /* pi/2 */ +#endif +#ifndef M_PI_2f +#define M_PI_2f 1.57079632679489661923f /* pi/2 */ +#endif +#ifndef M_PI_4 +#define M_PI_4 0.78539816339744830962 /* pi/4 */ +#endif +#ifndef M_PI_4f +#define M_PI_4f 0.78539816339744830962f /* pi/4 */ +#endif +#ifndef M_1_PI +#define M_1_PI 0.31830988618379067154 /* 1/pi */ +#endif +#ifndef M_1_PIf +#define M_1_PIf 0.31830988618379067154f /* 1/pi */ +#endif +#ifndef M_2_PI +#define M_2_PI 0.63661977236758134308 /* 2/pi */ +#endif +#ifndef M_2_PIf +#define M_2_PIf 0.63661977236758134308f /* 2/pi */ +#endif +#ifndef M_2_SQRTPI +#define M_2_SQRTPI 1.12837916709551257390 /* 2/sqrt(pi) */ +#endif +#ifndef M_2_SQRTPIf +#define M_2_SQRTPIf 1.12837916709551257390f /* 2/sqrt(pi) */ +#endif +#ifndef M_SQRT1_2 +#define M_SQRT1_2 0.70710678118654752440 /* 1/sqrt(2) */ +#endif +#ifndef M_SQRT1_2f +#define M_SQRT1_2f 0.70710678118654752440f /* 1/sqrt(2) */ +#endif +#ifndef M_SQRT2 +#define M_SQRT2 1.41421356237309504880 /* sqrt(2) */ +#endif +#ifndef M_SQRT2f +#define M_SQRT2f 1.41421356237309504880f /* sqrt(2) */ +#endif +#ifndef NAN +#define NAN av_int2float(0x7fc00000) +#endif +#ifndef INFINITY +#define INFINITY av_int2float(0x7f800000) +#endif + +/** + * @addtogroup lavu_math + * + * @{ + */ + +/** + * Rounding methods. + */ +enum AVRounding { + AV_ROUND_ZERO = 0, ///< Round toward zero. + AV_ROUND_INF = 1, ///< Round away from zero. + AV_ROUND_DOWN = 2, ///< Round toward -infinity. + AV_ROUND_UP = 3, ///< Round toward +infinity. + AV_ROUND_NEAR_INF = 5, ///< Round to nearest and halfway cases away from zero. + /** + * Flag telling rescaling functions to pass `INT64_MIN`/`MAX` through + * unchanged, avoiding special cases for #AV_NOPTS_VALUE. + * + * Unlike other values of the enumeration AVRounding, this value is a + * bitmask that must be used in conjunction with another value of the + * enumeration through a bitwise OR, in order to set behavior for normal + * cases. + * + * @code{.c} + * av_rescale_rnd(3, 1, 2, AV_ROUND_UP | AV_ROUND_PASS_MINMAX); + * // Rescaling 3: + * // Calculating 3 * 1 / 2 + * // 3 / 2 is rounded up to 2 + * // => 2 + * + * av_rescale_rnd(AV_NOPTS_VALUE, 1, 2, AV_ROUND_UP | AV_ROUND_PASS_MINMAX); + * // Rescaling AV_NOPTS_VALUE: + * // AV_NOPTS_VALUE == INT64_MIN + * // AV_NOPTS_VALUE is passed through + * // => AV_NOPTS_VALUE + * @endcode + */ + AV_ROUND_PASS_MINMAX = 8192, +}; + +/** + * Compute the greatest common divisor of two integer operands. + * + * @param a Operand + * @param b Operand + * @return GCD of a and b up to sign; if a >= 0 and b >= 0, return value is >= 0; + * if a == 0 and b == 0, returns 0. + */ +int64_t av_const av_gcd(int64_t a, int64_t b); + +/** + * Rescale a 64-bit integer with rounding to nearest. + * + * The operation is mathematically equivalent to `a * b / c`, but writing that + * directly can overflow. + * + * This function is equivalent to av_rescale_rnd() with #AV_ROUND_NEAR_INF. + * + * @see av_rescale_rnd(), av_rescale_q(), av_rescale_q_rnd() + */ +int64_t av_rescale(int64_t a, int64_t b, int64_t c) av_const; + +/** + * Rescale a 64-bit integer with specified rounding. + * + * The operation is mathematically equivalent to `a * b / c`, but writing that + * directly can overflow, and does not support different rounding methods. + * If the result is not representable then INT64_MIN is returned. + * + * @see av_rescale(), av_rescale_q(), av_rescale_q_rnd() + */ +int64_t av_rescale_rnd(int64_t a, int64_t b, int64_t c, enum AVRounding rnd) av_const; + +/** + * Rescale a 64-bit integer by 2 rational numbers. + * + * The operation is mathematically equivalent to `a * bq / cq`. + * + * This function is equivalent to av_rescale_q_rnd() with #AV_ROUND_NEAR_INF. + * + * @see av_rescale(), av_rescale_rnd(), av_rescale_q_rnd() + */ +int64_t av_rescale_q(int64_t a, AVRational bq, AVRational cq) av_const; + +/** + * Rescale a 64-bit integer by 2 rational numbers with specified rounding. + * + * The operation is mathematically equivalent to `a * bq / cq`. + * + * @see av_rescale(), av_rescale_rnd(), av_rescale_q() + */ +int64_t av_rescale_q_rnd(int64_t a, AVRational bq, AVRational cq, + enum AVRounding rnd) av_const; + +/** + * Compare two timestamps each in its own time base. + * + * @return One of the following values: + * - -1 if `ts_a` is before `ts_b` + * - 1 if `ts_a` is after `ts_b` + * - 0 if they represent the same position + * + * @warning + * The result of the function is undefined if one of the timestamps is outside + * the `int64_t` range when represented in the other's timebase. + */ +int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b); + +/** + * Compare the remainders of two integer operands divided by a common divisor. + * + * In other words, compare the least significant `log2(mod)` bits of integers + * `a` and `b`. + * + * @code{.c} + * av_compare_mod(0x11, 0x02, 0x10) < 0 // since 0x11 % 0x10 (0x1) < 0x02 % 0x10 (0x2) + * av_compare_mod(0x11, 0x02, 0x20) > 0 // since 0x11 % 0x20 (0x11) > 0x02 % 0x20 (0x02) + * @endcode + * + * @param a Operand + * @param b Operand + * @param mod Divisor; must be a power of 2 + * @return + * - a negative value if `a % mod < b % mod` + * - a positive value if `a % mod > b % mod` + * - zero if `a % mod == b % mod` + */ +int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod); + +/** + * Rescale a timestamp while preserving known durations. + * + * This function is designed to be called per audio packet to scale the input + * timestamp to a different time base. Compared to a simple av_rescale_q() + * call, this function is robust against possible inconsistent frame durations. + * + * The `last` parameter is a state variable that must be preserved for all + * subsequent calls for the same stream. For the first call, `*last` should be + * initialized to #AV_NOPTS_VALUE. + * + * @param[in] in_tb Input time base + * @param[in] in_ts Input timestamp + * @param[in] fs_tb Duration time base; typically this is finer-grained + * (greater) than `in_tb` and `out_tb` + * @param[in] duration Duration till the next call to this function (i.e. + * duration of the current packet/frame) + * @param[in,out] last Pointer to a timestamp expressed in terms of + * `fs_tb`, acting as a state variable + * @param[in] out_tb Output timebase + * @return Timestamp expressed in terms of `out_tb` + * + * @note In the context of this function, "duration" is in term of samples, not + * seconds. + */ +int64_t av_rescale_delta(AVRational in_tb, int64_t in_ts, AVRational fs_tb, int duration, int64_t *last, AVRational out_tb); + +/** + * Add a value to a timestamp. + * + * This function guarantees that when the same value is repeatedly added that + * no accumulation of rounding errors occurs. + * + * @param[in] ts Input timestamp + * @param[in] ts_tb Input timestamp time base + * @param[in] inc Value to be added + * @param[in] inc_tb Time base of `inc` + */ +int64_t av_add_stable(AVRational ts_tb, int64_t ts, AVRational inc_tb, int64_t inc); + +/** + * 0th order modified bessel function of the first kind. + */ +double av_bessel_i0(double x); + +/** + * @} + */ + +#endif /* AVUTIL_MATHEMATICS_H */ diff --git a/ffmpeg-n8.1/include/libavutil/md5.h b/ffmpeg-n8.1/include/libavutil/md5.h new file mode 100644 index 00000000..fc2eabdb --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/md5.h @@ -0,0 +1,89 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_md5 + * Public header for MD5 hash function implementation. + */ + +#ifndef AVUTIL_MD5_H +#define AVUTIL_MD5_H + +#include +#include + +#include "attributes.h" + +/** + * @defgroup lavu_md5 MD5 + * @ingroup lavu_hash + * MD5 hash function implementation. + * + * @{ + */ + +extern const int av_md5_size; + +struct AVMD5; + +/** + * Allocate an AVMD5 context. + */ +struct AVMD5 *av_md5_alloc(void); + +/** + * Initialize MD5 hashing. + * + * @param ctx pointer to the function context (of size av_md5_size) + */ +void av_md5_init(struct AVMD5 *ctx); + +/** + * Update hash value. + * + * @param ctx hash function context + * @param src input data to update hash with + * @param len input data length + */ +void av_md5_update(struct AVMD5 *ctx, const uint8_t *src, size_t len); + +/** + * Finish hashing and output digest value. + * + * @param ctx hash function context + * @param dst buffer where output digest value is stored + */ +void av_md5_final(struct AVMD5 *ctx, uint8_t *dst); + +/** + * Hash an array of data. + * + * @param dst The output buffer to write the digest into + * @param src The data to hash + * @param len The length of the data, in bytes + */ +void av_md5_sum(uint8_t *dst, const uint8_t *src, size_t len); + +/** + * @} + */ + +#endif /* AVUTIL_MD5_H */ diff --git a/ffmpeg-n8.1/include/libavutil/mem.h b/ffmpeg-n8.1/include/libavutil/mem.h new file mode 100644 index 00000000..ab7648ac --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/mem.h @@ -0,0 +1,607 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_mem + * Memory handling functions + */ + +#ifndef AVUTIL_MEM_H +#define AVUTIL_MEM_H + +#include +#include + +#include "attributes.h" + +/** + * @addtogroup lavu_mem + * Utilities for manipulating memory. + * + * FFmpeg has several applications of memory that are not required of a typical + * program. For example, the computing-heavy components like video decoding and + * encoding can be sped up significantly through the use of aligned memory. + * + * However, for each of FFmpeg's applications of memory, there might not be a + * recognized or standardized API for that specific use. Memory alignment, for + * instance, varies wildly depending on operating systems, architectures, and + * compilers. Hence, this component of @ref libavutil is created to make + * dealing with memory consistently possible on all platforms. + * + * @{ + */ + +/** + * @defgroup lavu_mem_attrs Function Attributes + * Function attributes applicable to memory handling functions. + * + * These function attributes can help compilers emit more useful warnings, or + * generate better code. + * @{ + */ + +/** + * @def av_malloc_attrib + * Function attribute denoting a malloc-like function. + * + * @see Function attribute `malloc` in GCC's documentation + */ + +#if AV_GCC_VERSION_AT_LEAST(3,1) + #define av_malloc_attrib __attribute__((__malloc__)) +#else + #define av_malloc_attrib +#endif + +/** + * @def av_alloc_size(...) + * Function attribute used on a function that allocates memory, whose size is + * given by the specified parameter(s). + * + * @code{.c} + * void *av_malloc(size_t size) av_alloc_size(1); + * void *av_calloc(size_t nmemb, size_t size) av_alloc_size(1, 2); + * @endcode + * + * @param ... One or two parameter indexes, separated by a comma + * + * @see Function attribute `alloc_size` in GCC's documentation + */ + +#if AV_GCC_VERSION_AT_LEAST(4,3) + #define av_alloc_size(...) __attribute__((alloc_size(__VA_ARGS__))) +#else + #define av_alloc_size(...) +#endif + +/** + * @} + */ + +/** + * @defgroup lavu_mem_funcs Heap Management + * Functions responsible for allocating, freeing, and copying memory. + * + * All memory allocation functions have a built-in upper limit of `INT_MAX` + * bytes. This may be changed with av_max_alloc(), although exercise extreme + * caution when doing so. + * + * @{ + */ + +/** + * Allocate a memory block with alignment suitable for all memory accesses + * (including vectors if available on the CPU). + * + * @param size Size in bytes for the memory block to be allocated + * @return Pointer to the allocated block, or `NULL` if the block cannot + * be allocated + * @see av_mallocz() + */ +void *av_malloc(size_t size) av_malloc_attrib av_alloc_size(1); + +/** + * Allocate a memory block with alignment suitable for all memory accesses + * (including vectors if available on the CPU) and zero all the bytes of the + * block. + * + * @param size Size in bytes for the memory block to be allocated + * @return Pointer to the allocated block, or `NULL` if it cannot be allocated + * @see av_malloc() + */ +void *av_mallocz(size_t size) av_malloc_attrib av_alloc_size(1); + +/** + * Allocate a memory block for an array with av_malloc(). + * + * The allocated memory will have size `size * nmemb` bytes. + * + * @param nmemb Number of element + * @param size Size of a single element + * @return Pointer to the allocated block, or `NULL` if the block cannot + * be allocated + * @see av_malloc() + */ +av_alloc_size(1, 2) void *av_malloc_array(size_t nmemb, size_t size); + +/** + * Allocate a memory block for an array with av_mallocz(). + * + * The allocated memory will have size `size * nmemb` bytes. + * + * @param nmemb Number of elements + * @param size Size of the single element + * @return Pointer to the allocated block, or `NULL` if the block cannot + * be allocated + * + * @see av_mallocz() + * @see av_malloc_array() + */ +void *av_calloc(size_t nmemb, size_t size) av_malloc_attrib av_alloc_size(1, 2); + +/** + * Allocate, reallocate, or free a block of memory. + * + * If `ptr` is `NULL` and `size` > 0, allocate a new block. Otherwise, expand or + * shrink that block of memory according to `size`. + * + * @param ptr Pointer to a memory block already allocated with + * av_realloc() or `NULL` + * @param size Size in bytes of the memory block to be allocated or + * reallocated + * + * @return Pointer to a newly-reallocated block or `NULL` if the block + * cannot be reallocated + * + * @warning Unlike av_malloc(), the returned pointer is not guaranteed to be + * correctly aligned. The returned pointer must be freed after even + * if size is zero. + * @see av_fast_realloc() + * @see av_reallocp() + */ +void *av_realloc(void *ptr, size_t size) av_alloc_size(2); + +/** + * Allocate, reallocate, or free a block of memory through a pointer to a + * pointer. + * + * If `*ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is + * zero, free the memory block pointed to by `*ptr`. Otherwise, expand or + * shrink that block of memory according to `size`. + * + * @param[in,out] ptr Pointer to a pointer to a memory block already allocated + * with av_realloc(), or a pointer to `NULL`. The pointer + * is updated on success, or freed on failure. + * @param[in] size Size in bytes for the memory block to be allocated or + * reallocated + * + * @return Zero on success, an AVERROR error code on failure + * + * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be + * correctly aligned. + */ +av_warn_unused_result +int av_reallocp(void *ptr, size_t size); + +/** + * Allocate, reallocate, or free a block of memory. + * + * This function does the same thing as av_realloc(), except: + * - It takes two size arguments and allocates `nelem * elsize` bytes, + * after checking the result of the multiplication for integer overflow. + * - It frees the input block in case of failure, thus avoiding the memory + * leak with the classic + * @code{.c} + * buf = realloc(buf); + * if (!buf) + * return -1; + * @endcode + * pattern. + */ +void *av_realloc_f(void *ptr, size_t nelem, size_t elsize); + +/** + * Allocate, reallocate, or free an array. + * + * If `ptr` is `NULL` and `nmemb` > 0, allocate a new block. + * + * @param ptr Pointer to a memory block already allocated with + * av_realloc() or `NULL` + * @param nmemb Number of elements in the array + * @param size Size of the single element of the array + * + * @return Pointer to a newly-reallocated block or NULL if the block + * cannot be reallocated + * + * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be + * correctly aligned. The returned pointer must be freed after even if + * nmemb is zero. + * @see av_reallocp_array() + */ +av_alloc_size(2, 3) void *av_realloc_array(void *ptr, size_t nmemb, size_t size); + +/** + * Allocate, reallocate an array through a pointer to a pointer. + * + * If `*ptr` is `NULL` and `nmemb` > 0, allocate a new block. + * + * @param[in,out] ptr Pointer to a pointer to a memory block already + * allocated with av_realloc(), or a pointer to `NULL`. + * The pointer is updated on success, or freed on failure. + * @param[in] nmemb Number of elements + * @param[in] size Size of the single element + * + * @return Zero on success, an AVERROR error code on failure + * + * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be + * correctly aligned. *ptr must be freed after even if nmemb is zero. + */ +int av_reallocp_array(void *ptr, size_t nmemb, size_t size); + +/** + * Reallocate the given buffer if it is not large enough, otherwise do nothing. + * + * If the given buffer is `NULL`, then a new uninitialized buffer is allocated. + * + * If the given buffer is not large enough, and reallocation fails, `NULL` is + * returned and `*size` is set to 0, but the original buffer is not changed or + * freed. + * + * A typical use pattern follows: + * + * @code{.c} + * uint8_t *buf = ...; + * uint8_t *new_buf = av_fast_realloc(buf, ¤t_size, size_needed); + * if (!new_buf) { + * // Allocation failed; clean up original buffer + * av_freep(&buf); + * return AVERROR(ENOMEM); + * } + * @endcode + * + * @param[in,out] ptr Already allocated buffer, or `NULL` + * @param[in,out] size Pointer to the size of buffer `ptr`. `*size` is + * updated to the new allocated size, in particular 0 + * in case of failure. + * @param[in] min_size Desired minimal size of buffer `ptr` + * @return `ptr` if the buffer is large enough, a pointer to newly reallocated + * buffer if the buffer was not large enough, or `NULL` in case of + * error + * @see av_realloc() + * @see av_fast_malloc() + */ +void *av_fast_realloc(void *ptr, unsigned int *size, size_t min_size); + +/** + * Allocate a buffer, reusing the given one if large enough. + * + * Contrary to av_fast_realloc(), the current buffer contents might not be + * preserved and on error the old buffer is freed, thus no special handling to + * avoid memleaks is necessary. + * + * `*ptr` is allowed to be `NULL`, in which case allocation always happens if + * `size_needed` is greater than 0. + * + * @code{.c} + * uint8_t *buf = ...; + * av_fast_malloc(&buf, ¤t_size, size_needed); + * if (!buf) { + * // Allocation failed; buf already freed + * return AVERROR(ENOMEM); + * } + * @endcode + * + * @param[in,out] ptr Pointer to pointer to an already allocated buffer. + * `*ptr` will be overwritten with pointer to new + * buffer on success or `NULL` on failure + * @param[in,out] size Pointer to the size of buffer `*ptr`. `*size` is + * updated to the new allocated size, in particular 0 + * in case of failure. + * @param[in] min_size Desired minimal size of buffer `*ptr` + * @see av_realloc() + * @see av_fast_mallocz() + */ +void av_fast_malloc(void *ptr, unsigned int *size, size_t min_size); + +/** + * Allocate and clear a buffer, reusing the given one if large enough. + * + * Like av_fast_malloc(), but all newly allocated space is initially cleared. + * Reused buffer is not cleared. + * + * `*ptr` is allowed to be `NULL`, in which case allocation always happens if + * `size_needed` is greater than 0. + * + * @param[in,out] ptr Pointer to pointer to an already allocated buffer. + * `*ptr` will be overwritten with pointer to new + * buffer on success or `NULL` on failure + * @param[in,out] size Pointer to the size of buffer `*ptr`. `*size` is + * updated to the new allocated size, in particular 0 + * in case of failure. + * @param[in] min_size Desired minimal size of buffer `*ptr` + * @see av_fast_malloc() + */ +void av_fast_mallocz(void *ptr, unsigned int *size, size_t min_size); + +/** + * Free a memory block which has been allocated with a function of av_malloc() + * or av_realloc() family. + * + * @param ptr Pointer to the memory block which should be freed. + * + * @note `ptr = NULL` is explicitly allowed. + * @note It is recommended that you use av_freep() instead, to prevent leaving + * behind dangling pointers. + * @see av_freep() + */ +void av_free(void *ptr); + +/** + * Free a memory block which has been allocated with a function of av_malloc() + * or av_realloc() family, and set the pointer pointing to it to `NULL`. + * + * @code{.c} + * uint8_t *buf = av_malloc(16); + * av_free(buf); + * // buf now contains a dangling pointer to freed memory, and accidental + * // dereference of buf will result in a use-after-free, which may be a + * // security risk. + * + * uint8_t *buf = av_malloc(16); + * av_freep(&buf); + * // buf is now NULL, and accidental dereference will only result in a + * // NULL-pointer dereference. + * @endcode + * + * @param ptr Pointer to the pointer to the memory block which should be freed + * @note `*ptr = NULL` is safe and leads to no action. + * @see av_free() + */ +void av_freep(void *ptr); + +/** + * Duplicate a string. + * + * @param s String to be duplicated + * @return Pointer to a newly-allocated string containing a + * copy of `s` or `NULL` if the string cannot be allocated + * @see av_strndup() + */ +char *av_strdup(const char *s) av_malloc_attrib; + +/** + * Duplicate a substring of a string. + * + * @param s String to be duplicated + * @param len Maximum length of the resulting string (not counting the + * terminating byte) + * @return Pointer to a newly-allocated string containing a + * substring of `s` or `NULL` if the string cannot be allocated + */ +char *av_strndup(const char *s, size_t len) av_malloc_attrib; + +/** + * Duplicate a buffer with av_malloc(). + * + * @param p Buffer to be duplicated + * @param size Size in bytes of the buffer copied + * @return Pointer to a newly allocated buffer containing a + * copy of `p` or `NULL` if the buffer cannot be allocated + */ +void *av_memdup(const void *p, size_t size); + +/** + * Overlapping memcpy() implementation. + * + * @param dst Destination buffer + * @param back Number of bytes back to start copying (i.e. the initial size of + * the overlapping window); must be > 0 + * @param cnt Number of bytes to copy; must be >= 0 + * + * @note `cnt > back` is valid, this will copy the bytes we just copied, + * thus creating a repeating pattern with a period length of `back`. + */ +void av_memcpy_backptr(uint8_t *dst, int back, int cnt); + +/** + * @} + */ + +/** + * @defgroup lavu_mem_dynarray Dynamic Array + * + * Utilities to make an array grow when needed. + * + * Sometimes, the programmer would want to have an array that can grow when + * needed. The libavutil dynamic array utilities fill that need. + * + * libavutil supports two systems of appending elements onto a dynamically + * allocated array, the first one storing the pointer to the value in the + * array, and the second storing the value directly. In both systems, the + * caller is responsible for maintaining a variable containing the length of + * the array, as well as freeing of the array after use. + * + * The first system stores pointers to values in a block of dynamically + * allocated memory. Since only pointers are stored, the function does not need + * to know the size of the type. Both av_dynarray_add() and + * av_dynarray_add_nofree() implement this system. + * + * @code + * type **array = NULL; //< an array of pointers to values + * int nb = 0; //< a variable to keep track of the length of the array + * + * type to_be_added = ...; + * type to_be_added2 = ...; + * + * av_dynarray_add(&array, &nb, &to_be_added); + * if (nb == 0) + * return AVERROR(ENOMEM); + * + * av_dynarray_add(&array, &nb, &to_be_added2); + * if (nb == 0) + * return AVERROR(ENOMEM); + * + * // Now: + * // nb == 2 + * // &to_be_added == array[0] + * // &to_be_added2 == array[1] + * + * av_freep(&array); + * @endcode + * + * The second system stores the value directly in a block of memory. As a + * result, the function has to know the size of the type. av_dynarray2_add() + * implements this mechanism. + * + * @code + * type *array = NULL; //< an array of values + * int nb = 0; //< a variable to keep track of the length of the array + * + * type to_be_added = ...; + * type to_be_added2 = ...; + * + * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array), NULL); + * if (!addr) + * return AVERROR(ENOMEM); + * memcpy(addr, &to_be_added, sizeof(to_be_added)); + * + * // Shortcut of the above. + * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array), + * (const void *)&to_be_added2); + * if (!addr) + * return AVERROR(ENOMEM); + * + * // Now: + * // nb == 2 + * // to_be_added == array[0] + * // to_be_added2 == array[1] + * + * av_freep(&array); + * @endcode + * + * @{ + */ + +/** + * Add the pointer to an element to a dynamic array. + * + * The array to grow is supposed to be an array of pointers to + * structures, and the element to add must be a pointer to an already + * allocated structure. + * + * The array is reallocated when its size reaches powers of 2. + * Therefore, the amortized cost of adding an element is constant. + * + * In case of success, the pointer to the array is updated in order to + * point to the new grown array, and the number pointed to by `nb_ptr` + * is incremented. + * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and + * `*nb_ptr` is set to 0. + * + * @param[in,out] tab_ptr Pointer to the array to grow + * @param[in,out] nb_ptr Pointer to the number of elements in the array + * @param[in] elem Element to add + * @see av_dynarray_add_nofree(), av_dynarray2_add() + */ +void av_dynarray_add(void *tab_ptr, int *nb_ptr, void *elem); + +/** + * Add an element to a dynamic array. + * + * Function has the same functionality as av_dynarray_add(), + * but it doesn't free memory on fails. It returns error code + * instead and leave current buffer untouched. + * + * @return >=0 on success, negative otherwise + * @see av_dynarray_add(), av_dynarray2_add() + */ +av_warn_unused_result +int av_dynarray_add_nofree(void *tab_ptr, int *nb_ptr, void *elem); + +/** + * Add an element of size `elem_size` to a dynamic array. + * + * The array is reallocated when its number of elements reaches powers of 2. + * Therefore, the amortized cost of adding an element is constant. + * + * In case of success, the pointer to the array is updated in order to + * point to the new grown array, and the number pointed to by `nb_ptr` + * is incremented. + * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and + * `*nb_ptr` is set to 0. + * + * @param[in,out] tab_ptr Pointer to the array to grow + * @param[in,out] nb_ptr Pointer to the number of elements in the array + * @param[in] elem_size Size in bytes of an element in the array + * @param[in] elem_data Pointer to the data of the element to add. If + * `NULL`, the space of the newly added element is + * allocated but left uninitialized. + * + * @return Pointer to the data of the element to copy in the newly allocated + * space + * @see av_dynarray_add(), av_dynarray_add_nofree() + */ +void *av_dynarray2_add(void **tab_ptr, int *nb_ptr, size_t elem_size, + const uint8_t *elem_data); + +/** + * @} + */ + +/** + * @defgroup lavu_mem_misc Miscellaneous Functions + * + * Other functions related to memory allocation. + * + * @{ + */ + +/** + * Multiply two `size_t` values checking for overflow. + * + * @param[in] a Operand of multiplication + * @param[in] b Operand of multiplication + * @param[out] r Pointer to the result of the operation + * @return 0 on success, AVERROR(EINVAL) on overflow + */ +int av_size_mult(size_t a, size_t b, size_t *r); + +/** + * Set the maximum size that may be allocated in one block. + * + * The value specified with this function is effective for all libavutil's @ref + * lavu_mem_funcs "heap management functions." + * + * By default, the max value is defined as `INT_MAX`. + * + * @param max Value to be set as the new maximum size + * + * @warning Exercise extreme caution when using this function. Don't touch + * this if you do not understand the full consequence of doing so. + */ +void av_max_alloc(size_t max); + +/** + * @} + * @} + */ + +#endif /* AVUTIL_MEM_H */ diff --git a/ffmpeg-n8.1/include/libavutil/motion_vector.h b/ffmpeg-n8.1/include/libavutil/motion_vector.h new file mode 100644 index 00000000..ec295563 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/motion_vector.h @@ -0,0 +1,57 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_MOTION_VECTOR_H +#define AVUTIL_MOTION_VECTOR_H + +#include + +typedef struct AVMotionVector { + /** + * Where the current macroblock comes from; negative value when it comes + * from the past, positive value when it comes from the future. + * XXX: set exact relative ref frame reference instead of a +/- 1 "direction". + */ + int32_t source; + /** + * Width and height of the block. + */ + uint8_t w, h; + /** + * Absolute source position. Can be outside the frame area. + */ + int16_t src_x, src_y; + /** + * Absolute destination position. Can be outside the frame area. + */ + int16_t dst_x, dst_y; + /** + * Extra flag information. + * Currently unused. + */ + uint64_t flags; + /** + * Motion vector + * src_x = dst_x + motion_x / motion_scale + * src_y = dst_y + motion_y / motion_scale + */ + int32_t motion_x, motion_y; + uint16_t motion_scale; +} AVMotionVector; + +#endif /* AVUTIL_MOTION_VECTOR_H */ diff --git a/ffmpeg-n8.1/include/libavutil/murmur3.h b/ffmpeg-n8.1/include/libavutil/murmur3.h new file mode 100644 index 00000000..d90bc2fc --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/murmur3.h @@ -0,0 +1,115 @@ +/* + * Copyright (C) 2013 Reimar Döffinger + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_murmur3 + * Public header for MurmurHash3 hash function implementation. + */ + +#ifndef AVUTIL_MURMUR3_H +#define AVUTIL_MURMUR3_H + +#include +#include + +/** + * @defgroup lavu_murmur3 Murmur3 + * @ingroup lavu_hash + * MurmurHash3 hash function implementation. + * + * MurmurHash3 is a non-cryptographic hash function, of which three + * incompatible versions were created by its inventor Austin Appleby: + * + * - 32-bit output + * - 128-bit output for 32-bit platforms + * - 128-bit output for 64-bit platforms + * + * FFmpeg only implements the last variant: 128-bit output designed for 64-bit + * platforms. Even though the hash function was designed for 64-bit platforms, + * the function in reality works on 32-bit systems too, only with reduced + * performance. + * + * @anchor lavu_murmur3_seedinfo + * By design, MurmurHash3 requires a seed to operate. In response to this, + * libavutil provides two functions for hash initiation, one that requires a + * seed (av_murmur3_init_seeded()) and one that uses a fixed arbitrary integer + * as the seed, and therefore does not (av_murmur3_init()). + * + * To make hashes comparable, you should provide the same seed for all calls to + * this hash function -- if you are supplying one yourself, that is. + * + * @{ + */ + +/** + * Allocate an AVMurMur3 hash context. + * + * @return Uninitialized hash context or `NULL` in case of error + */ +struct AVMurMur3 *av_murmur3_alloc(void); + +/** + * Initialize or reinitialize an AVMurMur3 hash context with a seed. + * + * @param[out] c Hash context + * @param[in] seed Random seed + * + * @see av_murmur3_init() + * @see @ref lavu_murmur3_seedinfo "Detailed description" on a discussion of + * seeds for MurmurHash3. + */ +void av_murmur3_init_seeded(struct AVMurMur3 *c, uint64_t seed); + +/** + * Initialize or reinitialize an AVMurMur3 hash context. + * + * Equivalent to av_murmur3_init_seeded() with a built-in seed. + * + * @param[out] c Hash context + * + * @see av_murmur3_init_seeded() + * @see @ref lavu_murmur3_seedinfo "Detailed description" on a discussion of + * seeds for MurmurHash3. + */ +void av_murmur3_init(struct AVMurMur3 *c); + +/** + * Update hash context with new data. + * + * @param[out] c Hash context + * @param[in] src Input data to update hash with + * @param[in] len Number of bytes to read from `src` + */ +void av_murmur3_update(struct AVMurMur3 *c, const uint8_t *src, size_t len); + +/** + * Finish hashing and output digest value. + * + * @param[in,out] c Hash context + * @param[out] dst Buffer where output digest value is stored + */ +void av_murmur3_final(struct AVMurMur3 *c, uint8_t dst[16]); + +/** + * @} + */ + +#endif /* AVUTIL_MURMUR3_H */ diff --git a/ffmpeg-n8.1/include/libavutil/opt.h b/ffmpeg-n8.1/include/libavutil/opt.h new file mode 100644 index 00000000..ab24fae7 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/opt.h @@ -0,0 +1,1194 @@ +/* + * AVOptions + * copyright (c) 2005 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_OPT_H +#define AVUTIL_OPT_H + +/** + * @file + * AVOptions + */ + +#include "rational.h" +#include "avutil.h" +#include "channel_layout.h" +#include "dict.h" +#include "log.h" +#include "pixfmt.h" +#include "samplefmt.h" + +/** + * @defgroup avoptions AVOptions + * @ingroup lavu_data + * @{ + * AVOptions provide a generic system to declare options on arbitrary structs + * ("objects"). An option can have a help text, a type and a range of possible + * values. Options may then be enumerated, read and written to. + * + * There are two modes of access to members of AVOption and its child structs. + * One is called 'native access', and refers to access from the code that + * declares the AVOption in question. The other is 'foreign access', and refers + * to access from other code. + * + * Certain struct members in this header are documented as 'native access only' + * or similar - it means that only the code that declared the AVOption in + * question is allowed to access the field. This allows us to extend the + * semantics of those fields without breaking API compatibility. + * + * @section avoptions_scope Scope of AVOptions + * + * AVOptions is designed to support any set of multimedia configuration options + * that can be defined at compile-time. Although it is mainly used to expose + * FFmpeg options, you are welcome to adapt it to your own use case. + * + * No single approach can ever fully solve the problem of configuration, + * but please submit a patch if you believe you have found a problem + * that is best solved by extending AVOptions. + * + * @section avoptions_implement Implementing AVOptions + * This section describes how to add AVOptions capabilities to a struct. + * + * All AVOptions-related information is stored in an AVClass. Therefore + * the first member of the struct should be a pointer to an AVClass describing it. + * The option field of the AVClass must be set to a NULL-terminated static array + * of AVOptions. Each AVOption must have a non-empty name, a type, a default + * value and for number-type AVOptions also a range of allowed values. It must + * also declare an offset in bytes from the start of the struct, where the field + * associated with this AVOption is located. Other fields in the AVOption struct + * should also be set when applicable, but are not required. + * + * The following example illustrates an AVOptions-enabled struct: + * @code + * typedef struct test_struct { + * const AVClass *class; + * int int_opt; + * char *str_opt; + * uint8_t *bin_opt; + * int bin_len; + * } test_struct; + * + * static const AVOption test_options[] = { + * { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt), + * AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX }, + * { "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt), + * AV_OPT_TYPE_STRING }, + * { "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt), + * AV_OPT_TYPE_BINARY }, + * { NULL }, + * }; + * + * static const AVClass test_class = { + * .class_name = "test class", + * .item_name = av_default_item_name, + * .option = test_options, + * .version = LIBAVUTIL_VERSION_INT, + * }; + * @endcode + * + * Next, when allocating your struct, you must ensure that the AVClass pointer + * is set to the correct value. Then, av_opt_set_defaults() can be called to + * initialize defaults. After that the struct is ready to be used with the + * AVOptions API. + * + * When cleaning up, you may use the av_opt_free() function to automatically + * free all the allocated string and binary options. + * + * Continuing with the above example: + * + * @code + * test_struct *alloc_test_struct(void) + * { + * test_struct *ret = av_mallocz(sizeof(*ret)); + * ret->class = &test_class; + * av_opt_set_defaults(ret); + * return ret; + * } + * void free_test_struct(test_struct **foo) + * { + * av_opt_free(*foo); + * av_freep(foo); + * } + * @endcode + * + * @subsection avoptions_implement_nesting Nesting + * It may happen that an AVOptions-enabled struct contains another + * AVOptions-enabled struct as a member (e.g. AVCodecContext in + * libavcodec exports generic options, while its priv_data field exports + * codec-specific options). In such a case, it is possible to set up the + * parent struct to export a child's options. To do that, simply + * implement AVClass.child_next() and AVClass.child_class_iterate() in the + * parent struct's AVClass. + * Assuming that the test_struct from above now also contains a + * child_struct field: + * + * @code + * typedef struct child_struct { + * AVClass *class; + * int flags_opt; + * } child_struct; + * static const AVOption child_opts[] = { + * { "test_flags", "This is a test option of flags type.", + * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX }, + * { NULL }, + * }; + * static const AVClass child_class = { + * .class_name = "child class", + * .item_name = av_default_item_name, + * .option = child_opts, + * .version = LIBAVUTIL_VERSION_INT, + * }; + * + * void *child_next(void *obj, void *prev) + * { + * test_struct *t = obj; + * if (!prev && t->child_struct) + * return t->child_struct; + * return NULL + * } + * const AVClass child_class_iterate(void **iter) + * { + * const AVClass *c = *iter ? NULL : &child_class; + * *iter = (void*)(uintptr_t)c; + * return c; + * } + * @endcode + * Putting child_next() and child_class_iterate() as defined above into + * test_class will now make child_struct's options accessible through + * test_struct (again, proper setup as described above needs to be done on + * child_struct right after it is created). + * + * From the above example it might not be clear why both child_next() + * and child_class_iterate() are needed. The distinction is that child_next() + * iterates over actually existing objects, while child_class_iterate() + * iterates over all possible child classes. E.g. if an AVCodecContext + * was initialized to use a codec which has private options, then its + * child_next() will return AVCodecContext.priv_data and finish + * iterating. OTOH child_class_iterate() on AVCodecContext.av_class will + * iterate over all available codecs with private options. + * + * @subsection avoptions_implement_named_constants Named constants + * It is possible to create named constants for options. Simply set the unit + * field of the option the constants should apply to a string and + * create the constants themselves as options of type AV_OPT_TYPE_CONST + * with their unit field set to the same string. + * Their default_val field should contain the value of the named + * constant. + * For example, to add some named constants for the test_flags option + * above, put the following into the child_opts array: + * @code + * { "test_flags", "This is a test option of flags type.", + * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" }, + * { "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" }, + * @endcode + * + * @section avoptions_use Using AVOptions + * This section deals with accessing options in an AVOptions-enabled struct. + * Such structs in FFmpeg are e.g. AVCodecContext in libavcodec or + * AVFormatContext in libavformat. + * + * @subsection avoptions_use_examine Examining AVOptions + * The basic functions for examining options are av_opt_next(), which iterates + * over all options defined for one object, and av_opt_find(), which searches + * for an option with the given name. + * + * The situation is more complicated with nesting. An AVOptions-enabled struct + * may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag + * to av_opt_find() will make the function search children recursively. + * + * For enumerating there are basically two cases. The first is when you want to + * get all options that may potentially exist on the struct and its children + * (e.g. when constructing documentation). In that case you should call + * av_opt_child_class_iterate() recursively on the parent struct's AVClass. The + * second case is when you have an already initialized struct with all its + * children and you want to get all options that can be actually written or read + * from it. In that case you should call av_opt_child_next() recursively (and + * av_opt_next() on each result). + * + * @subsection avoptions_use_get_set Reading and writing AVOptions + * When setting options, you often have a string read directly from the + * user. In such a case, simply passing it to av_opt_set() is enough. For + * non-string type options, av_opt_set() will parse the string according to the + * option type. + * + * Similarly av_opt_get() will read any option type and convert it to a string + * which will be returned. Do not forget that the string is allocated, so you + * have to free it with av_free(). + * + * In some cases it may be more convenient to put all options into an + * AVDictionary and call av_opt_set_dict() on it. A specific case of this + * are the format/codec open functions in lavf/lavc which take a dictionary + * filled with option as a parameter. This makes it possible to set some options + * that cannot be set otherwise, since e.g. the input file format is not known + * before the file is actually opened. + */ + +/** + * An option type determines: + * - for native access, the underlying C type of the field that an AVOption + * refers to; + * - for foreign access, the semantics of accessing the option through this API, + * e.g. which av_opt_get_*() and av_opt_set_*() functions can be called, or + * what format will av_opt_get()/av_opt_set() expect/produce. + */ +enum AVOptionType{ + /** + * Underlying C type is unsigned int. + */ + AV_OPT_TYPE_FLAGS = 1, + /** + * Underlying C type is int. + */ + AV_OPT_TYPE_INT, + /** + * Underlying C type is int64_t. + */ + AV_OPT_TYPE_INT64, + /** + * Underlying C type is double. + */ + AV_OPT_TYPE_DOUBLE, + /** + * Underlying C type is float. + */ + AV_OPT_TYPE_FLOAT, + /** + * Underlying C type is a uint8_t* that is either NULL or points to a C + * string allocated with the av_malloc() family of functions. + */ + AV_OPT_TYPE_STRING, + /** + * Underlying C type is AVRational. + */ + AV_OPT_TYPE_RATIONAL, + /** + * Underlying C type is a uint8_t* that is either NULL or points to an array + * allocated with the av_malloc() family of functions. The pointer is + * immediately followed by an int containing the array length in bytes. + */ + AV_OPT_TYPE_BINARY, + /** + * Underlying C type is AVDictionary*. + */ + AV_OPT_TYPE_DICT, + /** + * Underlying C type is uint64_t. + */ + AV_OPT_TYPE_UINT64, + /** + * Special option type for declaring named constants. Does not correspond to + * an actual field in the object, offset must be 0. + */ + AV_OPT_TYPE_CONST, + /** + * Underlying C type is two consecutive integers. + */ + AV_OPT_TYPE_IMAGE_SIZE, + /** + * Underlying C type is enum AVPixelFormat. + */ + AV_OPT_TYPE_PIXEL_FMT, + /** + * Underlying C type is enum AVSampleFormat. + */ + AV_OPT_TYPE_SAMPLE_FMT, + /** + * Underlying C type is AVRational. + */ + AV_OPT_TYPE_VIDEO_RATE, + /** + * Underlying C type is int64_t. + */ + AV_OPT_TYPE_DURATION, + /** + * Underlying C type is uint8_t[4]. + */ + AV_OPT_TYPE_COLOR, + /** + * Underlying C type is int. + */ + AV_OPT_TYPE_BOOL, + /** + * Underlying C type is AVChannelLayout. + */ + AV_OPT_TYPE_CHLAYOUT, + /** + * Underlying C type is unsigned int. + */ + AV_OPT_TYPE_UINT, + + /** + * May be combined with another regular option type to declare an array + * option. + * + * For array options, @ref AVOption.offset should refer to a pointer + * corresponding to the option type. The pointer should be immediately + * followed by an unsigned int that will store the number of elements in the + * array. + */ + AV_OPT_TYPE_FLAG_ARRAY = (1 << 16), +}; + +/** + * A generic parameter which can be set by the user for muxing or encoding. + */ +#define AV_OPT_FLAG_ENCODING_PARAM (1 << 0) +/** + * A generic parameter which can be set by the user for demuxing or decoding. + */ +#define AV_OPT_FLAG_DECODING_PARAM (1 << 1) +#define AV_OPT_FLAG_AUDIO_PARAM (1 << 3) +#define AV_OPT_FLAG_VIDEO_PARAM (1 << 4) +#define AV_OPT_FLAG_SUBTITLE_PARAM (1 << 5) +/** + * The option is intended for exporting values to the caller. + */ +#define AV_OPT_FLAG_EXPORT (1 << 6) +/** + * The option may not be set through the AVOptions API, only read. + * This flag only makes sense when AV_OPT_FLAG_EXPORT is also set. + */ +#define AV_OPT_FLAG_READONLY (1 << 7) +/** + * A generic parameter which can be set by the user for bit stream filtering. + */ +#define AV_OPT_FLAG_BSF_PARAM (1 << 8) + +/** + * A generic parameter which can be set by the user at runtime. + */ +#define AV_OPT_FLAG_RUNTIME_PARAM (1 << 15) +/** + * A generic parameter which can be set by the user for filtering. + */ +#define AV_OPT_FLAG_FILTERING_PARAM (1 << 16) +/** + * Set if option is deprecated, users should refer to AVOption.help text for + * more information. + */ +#define AV_OPT_FLAG_DEPRECATED (1 << 17) +/** + * Set if option constants can also reside in child objects. + */ +#define AV_OPT_FLAG_CHILD_CONSTS (1 << 18) + +/** + * May be set as default_val for AV_OPT_TYPE_FLAG_ARRAY options. + */ +typedef struct AVOptionArrayDef { + /** + * Native access only. + * + * Default value of the option, as would be serialized by av_opt_get() (i.e. + * using the value of sep as the separator). + */ + const char *def; + + /** + * Minimum number of elements in the array. When this field is non-zero, def + * must be non-NULL and contain at least this number of elements. + */ + unsigned size_min; + /** + * Maximum number of elements in the array, 0 when unlimited. + */ + unsigned size_max; + + /** + * Separator between array elements in string representations of this + * option, used by av_opt_set() and av_opt_get(). It must be a printable + * ASCII character, excluding alphanumeric and the backslash. A comma is + * used when sep=0. + * + * The separator and the backslash must be backslash-escaped in order to + * appear in string representations of the option value. + */ + char sep; +} AVOptionArrayDef; + +/** + * AVOption + */ +typedef struct AVOption { + const char *name; + + /** + * short English help text + * @todo What about other languages? + */ + const char *help; + + /** + * Native access only. + * + * The offset relative to the context structure where the option + * value is stored. It should be 0 for named constants. + */ + int offset; + enum AVOptionType type; + + /** + * Native access only, except when documented otherwise. + * the default value for scalar options + */ + union { + int64_t i64; + double dbl; + const char *str; + /* TODO those are unused now */ + AVRational q; + + /** + * Used for AV_OPT_TYPE_FLAG_ARRAY options. May be NULL. + * + * Foreign access to some members allowed, as noted in AVOptionArrayDef + * documentation. + */ + const AVOptionArrayDef *arr; + } default_val; + double min; ///< minimum valid value for the option + double max; ///< maximum valid value for the option + + /** + * A combination of AV_OPT_FLAG_*. + */ + int flags; + + /** + * The logical unit to which the option belongs. Non-constant + * options and corresponding named constants share the same + * unit. May be NULL. + */ + const char *unit; +} AVOption; + +/** + * A single allowed range of values, or a single allowed value. + */ +typedef struct AVOptionRange { + const char *str; + /** + * Value range. + * For string ranges this represents the min/max length. + * For dimensions this represents the min/max pixel count or width/height in multi-component case. + */ + double value_min, value_max; + /** + * Value's component range. + * For string this represents the unicode range for chars, 0-127 limits to ASCII. + */ + double component_min, component_max; + /** + * Range flag. + * If set to 1 the struct encodes a range, if set to 0 a single value. + */ + int is_range; +} AVOptionRange; + +/** + * List of AVOptionRange structs. + */ +typedef struct AVOptionRanges { + /** + * Array of option ranges. + * + * Most of option types use just one component. + * Following describes multi-component option types: + * + * AV_OPT_TYPE_IMAGE_SIZE: + * component index 0: range of pixel count (width * height). + * component index 1: range of width. + * component index 2: range of height. + * + * @note To obtain multi-component version of this structure, user must + * provide AV_OPT_MULTI_COMPONENT_RANGE to av_opt_query_ranges or + * av_opt_query_ranges_default function. + * + * Multi-component range can be read as in following example: + * + * @code + * int range_index, component_index; + * AVOptionRanges *ranges; + * AVOptionRange *range[3]; //may require more than 3 in the future. + * av_opt_query_ranges(&ranges, obj, key, AV_OPT_MULTI_COMPONENT_RANGE); + * for (range_index = 0; range_index < ranges->nb_ranges; range_index++) { + * for (component_index = 0; component_index < ranges->nb_components; component_index++) + * range[component_index] = ranges->range[ranges->nb_ranges * component_index + range_index]; + * //do something with range here. + * } + * av_opt_freep_ranges(&ranges); + * @endcode + */ + AVOptionRange **range; + /** + * Number of ranges per component. + */ + int nb_ranges; + /** + * Number of components. + */ + int nb_components; +} AVOptionRanges; + +/** + * @defgroup opt_mng AVOption (un)initialization and inspection. + * @{ + */ + +/** + * Set the values of all AVOption fields to their default values. + * + * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass) + */ +void av_opt_set_defaults(void *s); + +/** + * Set the values of all AVOption fields to their default values. Only these + * AVOption fields for which (opt->flags & mask) == flags will have their + * default applied to s. + * + * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass) + * @param mask combination of AV_OPT_FLAG_* + * @param flags combination of AV_OPT_FLAG_* + */ +void av_opt_set_defaults2(void *s, int mask, int flags); + +/** + * Free all allocated objects in obj. + */ +void av_opt_free(void *obj); + +/** + * Iterate over all AVOptions belonging to obj. + * + * @param obj an AVOptions-enabled struct or a double pointer to an + * AVClass describing it. + * @param prev result of the previous call to av_opt_next() on this object + * or NULL + * @return next AVOption or NULL + */ +const AVOption *av_opt_next(const void *obj, const AVOption *prev); + +/** + * Iterate over AVOptions-enabled children of obj. + * + * @param prev result of a previous call to this function or NULL + * @return next AVOptions-enabled child or NULL + */ +void *av_opt_child_next(void *obj, void *prev); + +/** + * Iterate over potential AVOptions-enabled children of parent. + * + * @param iter a pointer where iteration state is stored. + * @return AVClass corresponding to next potential child or NULL + */ +const AVClass *av_opt_child_class_iterate(const AVClass *parent, void **iter); + +#define AV_OPT_SEARCH_CHILDREN (1 << 0) /**< Search in possible children of the + given object first. */ +/** + * The obj passed to av_opt_find() is fake -- only a double pointer to AVClass + * instead of a required pointer to a struct containing AVClass. This is + * useful for searching for options without needing to allocate the corresponding + * object. + */ +#define AV_OPT_SEARCH_FAKE_OBJ (1 << 1) + +/** + * In av_opt_get, return NULL if the option has a pointer type and is set to NULL, + * rather than returning an empty string. + */ +#define AV_OPT_ALLOW_NULL (1 << 2) + +/** + * May be used with av_opt_set_array() to signal that new elements should + * replace the existing ones in the indicated range. + */ +#define AV_OPT_ARRAY_REPLACE (1 << 3) + +/** + * Allows av_opt_query_ranges and av_opt_query_ranges_default to return more than + * one component for certain option types. + * @see AVOptionRanges for details. + */ +#define AV_OPT_MULTI_COMPONENT_RANGE (1 << 12) + +/** + * Look for an option in an object. Consider only options which + * have all the specified flags set. + * + * @param[in] obj A pointer to a struct whose first element is a + * pointer to an AVClass. + * Alternatively a double pointer to an AVClass, if + * AV_OPT_SEARCH_FAKE_OBJ search flag is set. + * @param[in] name The name of the option to look for. + * @param[in] unit When searching for named constants, name of the unit + * it belongs to. + * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG). + * @param search_flags A combination of AV_OPT_SEARCH_*. + * + * @return A pointer to the option found, or NULL if no option + * was found. + * + * @note Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable + * directly with av_opt_set(). Use special calls which take an options + * AVDictionary (e.g. avformat_open_input()) to set options found with this + * flag. + */ +const AVOption *av_opt_find(void *obj, const char *name, const char *unit, + int opt_flags, int search_flags); + +/** + * Look for an option in an object. Consider only options which + * have all the specified flags set. + * + * @param[in] obj A pointer to a struct whose first element is a + * pointer to an AVClass. + * Alternatively a double pointer to an AVClass, if + * AV_OPT_SEARCH_FAKE_OBJ search flag is set. + * @param[in] name The name of the option to look for. + * @param[in] unit When searching for named constants, name of the unit + * it belongs to. + * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG). + * @param search_flags A combination of AV_OPT_SEARCH_*. + * @param[out] target_obj if non-NULL, an object to which the option belongs will be + * written here. It may be different from obj if AV_OPT_SEARCH_CHILDREN is present + * in search_flags. This parameter is ignored if search_flags contain + * AV_OPT_SEARCH_FAKE_OBJ. + * + * @return A pointer to the option found, or NULL if no option + * was found. + */ +const AVOption *av_opt_find2(void *obj, const char *name, const char *unit, + int opt_flags, int search_flags, void **target_obj); + +/** + * Show the obj options. + * + * @param req_flags requested flags for the options to show. Show only the + * options for which it is opt->flags & req_flags. + * @param rej_flags rejected flags for the options to show. Show only the + * options for which it is !(opt->flags & req_flags). + * @param av_log_obj log context to use for showing the options + */ +int av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags); + +/** + * Extract a key-value pair from the beginning of a string. + * + * @param ropts pointer to the options string, will be updated to + * point to the rest of the string (one of the pairs_sep + * or the final NUL) + * @param key_val_sep a 0-terminated list of characters used to separate + * key from value, for example '=' + * @param pairs_sep a 0-terminated list of characters used to separate + * two pairs from each other, for example ':' or ',' + * @param flags flags; see the AV_OPT_FLAG_* values below + * @param rkey parsed key; must be freed using av_free() + * @param rval parsed value; must be freed using av_free() + * + * @return >=0 for success, or a negative value corresponding to an + * AVERROR code in case of error; in particular: + * AVERROR(EINVAL) if no key is present + * + */ +int av_opt_get_key_value(const char **ropts, + const char *key_val_sep, const char *pairs_sep, + unsigned flags, + char **rkey, char **rval); + +enum { + + /** + * Accept to parse a value without a key; the key will then be returned + * as NULL. + */ + AV_OPT_FLAG_IMPLICIT_KEY = 1, +}; + +/** + * @} + */ + +/** + * @defgroup opt_write Setting and modifying option values + * @{ + */ + +/** + * Parse the key/value pairs list in opts. For each key/value pair + * found, stores the value in the field in ctx that is named like the + * key. ctx must be an AVClass context, storing is done using + * AVOptions. + * + * @param opts options string to parse, may be NULL + * @param key_val_sep a 0-terminated list of characters used to + * separate key from value + * @param pairs_sep a 0-terminated list of characters used to separate + * two pairs from each other + * @return the number of successfully set key/value pairs, or a negative + * value corresponding to an AVERROR code in case of error: + * AVERROR(EINVAL) if opts cannot be parsed, + * the error code issued by av_opt_set() if a key/value pair + * cannot be set + */ +int av_set_options_string(void *ctx, const char *opts, + const char *key_val_sep, const char *pairs_sep); + +/** + * Parse the key-value pairs list in opts. For each key=value pair found, + * set the value of the corresponding option in ctx. + * + * @param ctx the AVClass object to set options on + * @param opts the options string, key-value pairs separated by a + * delimiter + * @param shorthand a NULL-terminated array of options names for shorthand + * notation: if the first field in opts has no key part, + * the key is taken from the first element of shorthand; + * then again for the second, etc., until either opts is + * finished, shorthand is finished or a named option is + * found; after that, all options must be named + * @param key_val_sep a 0-terminated list of characters used to separate + * key from value, for example '=' + * @param pairs_sep a 0-terminated list of characters used to separate + * two pairs from each other, for example ':' or ',' + * @return the number of successfully set key=value pairs, or a negative + * value corresponding to an AVERROR code in case of error: + * AVERROR(EINVAL) if opts cannot be parsed, + * the error code issued by av_set_string3() if a key/value pair + * cannot be set + * + * Options names must use only the following characters: a-z A-Z 0-9 - . / _ + * Separators must use characters distinct from option names and from each + * other. + */ +int av_opt_set_from_string(void *ctx, const char *opts, + const char *const *shorthand, + const char *key_val_sep, const char *pairs_sep); + +/** + * Set all the options from a given dictionary on an object. + * + * @param obj a struct whose first element is a pointer to AVClass + * @param options options to process. This dictionary will be freed and replaced + * by a new one containing all options not found in obj. + * Of course this new dictionary needs to be freed by caller + * with av_dict_free(). + * + * @return 0 on success, a negative AVERROR if some option was found in obj, + * but could not be set. + * + * @see av_dict_copy() + */ +int av_opt_set_dict(void *obj, struct AVDictionary **options); + + +/** + * Set all the options from a given dictionary on an object. + * + * @param obj a struct whose first element is a pointer to AVClass + * @param options options to process. This dictionary will be freed and replaced + * by a new one containing all options not found in obj. + * Of course this new dictionary needs to be freed by caller + * with av_dict_free(). + * @param search_flags A combination of AV_OPT_SEARCH_*. + * + * @return 0 on success, a negative AVERROR if some option was found in obj, + * but could not be set. + * + * @see av_dict_copy() + */ +int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags); + +/** + * Copy options from src object into dest object. + * + * The underlying AVClass of both src and dest must coincide. The guarantee + * below does not apply if this is not fulfilled. + * + * Options that require memory allocation (e.g. string or binary) are malloc'ed in dest object. + * Original memory allocated for such options is freed unless both src and dest options points to the same memory. + * + * Even on error it is guaranteed that allocated options from src and dest + * no longer alias each other afterwards; in particular calling av_opt_free() + * on both src and dest is safe afterwards if dest has been memdup'ed from src. + * + * @param dest Object to copy from + * @param src Object to copy into + * @return 0 on success, negative on error + */ +int av_opt_copy(void *dest, const void *src); + +/** + * @defgroup opt_set_funcs Option setting functions + * @{ + * Those functions set the field of obj with the given name to value. + * + * @param[in] obj A struct whose first element is a pointer to an AVClass. + * @param[in] name the name of the field to set + * @param[in] val The value to set. In case of av_opt_set() if the field is not + * of a string type, then the given string is parsed. + * SI postfixes and some named scalars are supported. + * If the field is of a numeric type, it has to be a numeric or named + * scalar. Behavior with more than one scalar and +- infix operators + * is undefined. + * If the field is of a flags type, it has to be a sequence of numeric + * scalars or named flags separated by '+' or '-'. Prefixing a flag + * with '+' causes it to be set without affecting the other flags; + * similarly, '-' unsets a flag. + * If the field is of a dictionary type, it has to be a ':' separated list of + * key=value parameters. Values containing ':' special characters must be + * escaped. + * @param search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN + * is passed here, then the option may be set on a child of obj. + * + * @return 0 if the value has been set, or an AVERROR code in case of + * error: + * AVERROR_OPTION_NOT_FOUND if no matching option exists + * AVERROR(ERANGE) if the value is out of range + * AVERROR(EINVAL) if the value is not valid + */ +int av_opt_set (void *obj, const char *name, const char *val, int search_flags); +int av_opt_set_int (void *obj, const char *name, int64_t val, int search_flags); +int av_opt_set_double (void *obj, const char *name, double val, int search_flags); +int av_opt_set_q (void *obj, const char *name, AVRational val, int search_flags); +int av_opt_set_bin (void *obj, const char *name, const uint8_t *val, int size, int search_flags); +int av_opt_set_image_size(void *obj, const char *name, int w, int h, int search_flags); +int av_opt_set_pixel_fmt (void *obj, const char *name, enum AVPixelFormat fmt, int search_flags); +int av_opt_set_sample_fmt(void *obj, const char *name, enum AVSampleFormat fmt, int search_flags); +int av_opt_set_video_rate(void *obj, const char *name, AVRational val, int search_flags); +/** + * @note Any old chlayout present is discarded and replaced with a copy of the new one. The + * caller still owns layout and is responsible for uninitializing it. + */ +int av_opt_set_chlayout(void *obj, const char *name, const AVChannelLayout *layout, int search_flags); +/** + * @note Any old dictionary present is discarded and replaced with a copy of the new one. The + * caller still owns val is and responsible for freeing it. + */ +int av_opt_set_dict_val(void *obj, const char *name, const AVDictionary *val, int search_flags); + +#if FF_API_OPT_INT_LIST +/** + * Set a binary option to an integer list. + * + * @param obj AVClass object to set options on + * @param name name of the binary option + * @param val pointer to an integer list (must have the correct type with + * regard to the contents of the list) + * @param term list terminator (usually 0 or -1) + * @param flags search flags + */ +#define av_opt_set_int_list(obj, name, val, term, flags) \ + (av_int_list_length(val, term) > INT_MAX / sizeof(*(val)) ? \ + AVERROR(EINVAL) : \ + av_opt_set_bin(obj, name, (const uint8_t *)(val), \ + av_int_list_length(val, term) * sizeof(*(val)), flags)) +#endif + +/** + * Add, replace, or remove elements for an array option. Which of these + * operations is performed depends on the values of val and search_flags. + * + * @param start_elem Index of the first array element to modify; must not be + * larger than array size as returned by + * av_opt_get_array_size(). + * @param nb_elems number of array elements to modify; when val is NULL, + * start_elem+nb_elems must not be larger than array size as + * returned by av_opt_get_array_size() + * + * @param val_type Option type corresponding to the type of val, ignored when val is + * NULL. + * + * The effect of this function will will be as if av_opt_setX() + * was called for each element, where X is specified by type. + * E.g. AV_OPT_TYPE_STRING corresponds to av_opt_set(). + * + * Typically this should be the same as the scalarized type of + * the AVOption being set, but certain conversions are also + * possible - the same as those done by the corresponding + * av_opt_set*() function. E.g. any option type can be set from + * a string, numeric types can be set from int64, double, or + * rational, etc. + * + * @param val Array with nb_elems elements or NULL. + * + * When NULL, nb_elems array elements starting at start_elem are + * removed from the array. Any array elements remaining at the end + * are shifted by nb_elems towards the first element in order to keep + * the array contiguous. + * + * Otherwise (val is non-NULL), the type of val must match the + * underlying C type as documented for val_type. + * + * When AV_OPT_ARRAY_REPLACE is not set in search_flags, the array is + * enlarged by nb_elems, and the contents of val are inserted at + * start_elem. Previously existing array elements from start_elem + * onwards (if present) are shifted by nb_elems away from the first + * element in order to make space for the new elements. + * + * When AV_OPT_ARRAY_REPLACE is set in search_flags, the contents + * of val replace existing array elements from start_elem to + * start_elem+nb_elems (if present). New array size is + * max(start_elem + nb_elems, old array size). + */ +int av_opt_set_array(void *obj, const char *name, int search_flags, + unsigned int start_elem, unsigned int nb_elems, + enum AVOptionType val_type, const void *val); + +/** + * @} + * @} + */ + +/** + * @defgroup opt_read Reading option values + * @{ + */ + +/** + * @defgroup opt_get_funcs Option getting functions + * @{ + * Those functions get a value of the option with the given name from an object. + * + * @param[in] obj a struct whose first element is a pointer to an AVClass. + * @param[in] name name of the option to get. + * @param[in] search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN + * is passed here, then the option may be found in a child of obj. + * @param[out] out_val value of the option will be written here + * @return >=0 on success, a negative error code otherwise + */ +/** + * @note the returned string will be av_malloc()ed and must be av_free()ed by the caller + * + * @note if AV_OPT_ALLOW_NULL is set in search_flags in av_opt_get, and the + * option is of type AV_OPT_TYPE_STRING, AV_OPT_TYPE_BINARY or AV_OPT_TYPE_DICT + * and is set to NULL, *out_val will be set to NULL instead of an allocated + * empty string. + */ +int av_opt_get (void *obj, const char *name, int search_flags, uint8_t **out_val); +int av_opt_get_int (void *obj, const char *name, int search_flags, int64_t *out_val); +int av_opt_get_double (void *obj, const char *name, int search_flags, double *out_val); +int av_opt_get_q (void *obj, const char *name, int search_flags, AVRational *out_val); +int av_opt_get_image_size(void *obj, const char *name, int search_flags, int *w_out, int *h_out); +int av_opt_get_pixel_fmt (void *obj, const char *name, int search_flags, enum AVPixelFormat *out_fmt); +int av_opt_get_sample_fmt(void *obj, const char *name, int search_flags, enum AVSampleFormat *out_fmt); +int av_opt_get_video_rate(void *obj, const char *name, int search_flags, AVRational *out_val); +/** + * @param[out] layout The returned layout is a copy of the actual value and must + * be freed with av_channel_layout_uninit() by the caller + */ +int av_opt_get_chlayout(void *obj, const char *name, int search_flags, AVChannelLayout *layout); +/** + * @param[out] out_val The returned dictionary is a copy of the actual value and must + * be freed with av_dict_free() by the caller + */ +int av_opt_get_dict_val(void *obj, const char *name, int search_flags, AVDictionary **out_val); + +/** + * For an array-type option, get the number of elements in the array. + */ +int av_opt_get_array_size(void *obj, const char *name, int search_flags, + unsigned int *out_val); + +/** + * For an array-type option, retrieve the values of one or more array elements. + * + * @param start_elem index of the first array element to retrieve + * @param nb_elems number of array elements to retrieve; start_elem+nb_elems + * must not be larger than array size as returned by + * av_opt_get_array_size() + * + * @param out_type Option type corresponding to the desired output. + * + * The array elements produced by this function will + * will be as if av_opt_getX() was called for each element, + * where X is specified by out_type. E.g. AV_OPT_TYPE_STRING + * corresponds to av_opt_get(). + * + * Typically this should be the same as the scalarized type of + * the AVOption being retrieved, but certain conversions are + * also possible - the same as those done by the corresponding + * av_opt_get*() function. E.g. any option type can be retrieved + * as a string, numeric types can be retrieved as int64, double, + * or rational, etc. + * + * @param out_val Array with nb_elems members into which the output will be + * written. The array type must match the underlying C type as + * documented for out_type, and be zeroed on entry to this + * function. + * + * For dynamically allocated types (strings, binary, dicts, + * etc.), the result is owned and freed by the caller. + */ +int av_opt_get_array(void *obj, const char *name, int search_flags, + unsigned int start_elem, unsigned int nb_elems, + enum AVOptionType out_type, void *out_val); +/** + * @} + */ + +/** + * @defgroup opt_eval_funcs Evaluating option strings + * @{ + * This group of functions can be used to evaluate option strings + * and get numbers out of them. They do the same thing as av_opt_set(), + * except the result is written into the caller-supplied pointer. + * + * @param obj a struct whose first element is a pointer to AVClass. + * @param o an option for which the string is to be evaluated. + * @param val string to be evaluated. + * @param *_out value of the string will be written here. + * + * @return 0 on success, a negative number on failure. + */ +int av_opt_eval_flags (void *obj, const AVOption *o, const char *val, int *flags_out); +int av_opt_eval_int (void *obj, const AVOption *o, const char *val, int *int_out); +int av_opt_eval_uint (void *obj, const AVOption *o, const char *val, unsigned *uint_out); +int av_opt_eval_int64 (void *obj, const AVOption *o, const char *val, int64_t *int64_out); +int av_opt_eval_float (void *obj, const AVOption *o, const char *val, float *float_out); +int av_opt_eval_double(void *obj, const AVOption *o, const char *val, double *double_out); +int av_opt_eval_q (void *obj, const AVOption *o, const char *val, AVRational *q_out); +/** + * @} + */ + +#if FF_API_OPT_PTR +/** + * Gets a pointer to the requested field in a struct. + * This function allows accessing a struct even when its fields are moved or + * renamed since the application making the access has been compiled, + * + * @returns a pointer to the field, it can be cast to the correct type and read + * or written to. + * + * @deprecated direct access to AVOption-exported fields is not supported + */ +attribute_deprecated +void *av_opt_ptr(const AVClass *avclass, void *obj, const char *name); +#endif + +/** + * Check if given option is set to its default value. + * + * Options o must belong to the obj. This function must not be called to check child's options state. + * @see av_opt_is_set_to_default_by_name(). + * + * @param obj AVClass object to check option on + * @param o option to be checked + * @return >0 when option is set to its default, + * 0 when option is not set its default, + * <0 on error + */ +int av_opt_is_set_to_default(void *obj, const AVOption *o); + +/** + * Check if given option is set to its default value. + * + * @param obj AVClass object to check option on + * @param name option name + * @param search_flags combination of AV_OPT_SEARCH_* + * @return >0 when option is set to its default, + * 0 when option is not set its default, + * <0 on error + */ +int av_opt_is_set_to_default_by_name(void *obj, const char *name, int search_flags); + +/** + * Check whether a particular flag is set in a flags field. + * + * @param field_name the name of the flag field option + * @param flag_name the name of the flag to check + * @return non-zero if the flag is set, zero if the flag isn't set, + * isn't of the right type, or the flags field doesn't exist. + */ +int av_opt_flag_is_set(void *obj, const char *field_name, const char *flag_name); + +#define AV_OPT_SERIALIZE_SKIP_DEFAULTS 0x00000001 ///< Serialize options that are not set to default values only. +#define AV_OPT_SERIALIZE_OPT_FLAGS_EXACT 0x00000002 ///< Serialize options that exactly match opt_flags only. +#define AV_OPT_SERIALIZE_SEARCH_CHILDREN 0x00000004 ///< Serialize options in possible children of the given object. + +/** + * Serialize object's options. + * + * Create a string containing object's serialized options. + * Such string may be passed back to av_opt_set_from_string() in order to restore option values. + * A key/value or pairs separator occurring in the serialized value or + * name string are escaped through the av_escape() function. + * + * @param[in] obj AVClass object to serialize + * @param[in] opt_flags serialize options with all the specified flags set (AV_OPT_FLAG) + * @param[in] flags combination of AV_OPT_SERIALIZE_* flags + * @param[out] buffer Pointer to buffer that will be allocated with string containing serialized options. + * Buffer must be freed by the caller when is no longer needed. + * @param[in] key_val_sep character used to separate key from value + * @param[in] pairs_sep character used to separate two pairs from each other + * @return >= 0 on success, negative on error + * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same. + */ +int av_opt_serialize(void *obj, int opt_flags, int flags, char **buffer, + const char key_val_sep, const char pairs_sep); + +/** + * @} + */ + +/** + * Free an AVOptionRanges struct and set it to NULL. + */ +void av_opt_freep_ranges(AVOptionRanges **ranges); + +/** + * Get a list of allowed ranges for the given option. + * + * The returned list may depend on other fields in obj like for example profile. + * + * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored + * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance + * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges + * + * The result must be freed with av_opt_freep_ranges. + * + * @return number of components returned on success, a negative error code otherwise + */ +int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags); + +/** + * Get a default list of allowed ranges for the given option. + * + * This list is constructed without using the AVClass.query_ranges() callback + * and can be used as fallback from within the callback. + * + * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored + * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance + * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges + * + * The result must be freed with av_opt_free_ranges. + * + * @return number of components returned on success, a negative error code otherwise + */ +int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags); + +/** + * @} + */ + +#endif /* AVUTIL_OPT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/parseutils.h b/ffmpeg-n8.1/include/libavutil/parseutils.h new file mode 100644 index 00000000..dad5c277 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/parseutils.h @@ -0,0 +1,197 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_PARSEUTILS_H +#define AVUTIL_PARSEUTILS_H + +#include + +#include "rational.h" + +/** + * @file + * misc parsing utilities + */ + +/** + * Parse str and store the parsed ratio in q. + * + * 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. + * + * @param[in,out] q pointer to the AVRational which will contain the ratio + * @param[in] str the string to parse: it has to be a string in the format + * num:den, a float number or an expression + * @param[in] max the maximum allowed numerator and denominator + * @param[in] log_offset log level offset which is applied to the log + * level of log_ctx + * @param[in] log_ctx parent logging context + * @return >= 0 on success, a negative error code otherwise + */ +int av_parse_ratio(AVRational *q, const char *str, int max, + int log_offset, void *log_ctx); + +#define av_parse_ratio_quiet(rate, str, max) \ + av_parse_ratio(rate, str, max, AV_LOG_MAX_OFFSET, NULL) + +/** + * Parse str and put in width_ptr and height_ptr the detected values. + * + * @param[in,out] width_ptr pointer to the variable which will contain the detected + * width value + * @param[in,out] height_ptr pointer to the variable which will contain the detected + * height value + * @param[in] str the string to parse: it has to be a string in the format + * width x height or a valid video size abbreviation. + * @return >= 0 on success, a negative error code otherwise + */ +int av_parse_video_size(int *width_ptr, int *height_ptr, const char *str); + +/** + * Parse str and store the detected values in *rate. + * + * @param[in,out] rate pointer to the AVRational which will contain the detected + * frame rate + * @param[in] str the string to parse: it has to be a string in the format + * rate_num / rate_den, a float number or a valid video rate abbreviation + * @return >= 0 on success, a negative error code otherwise + */ +int av_parse_video_rate(AVRational *rate, const char *str); + +/** + * Put the RGBA values that correspond to color_string in rgba_color. + * + * @param rgba_color 4-elements array of uint8_t values, where the respective + * red, green, blue and alpha component values are written. + * @param color_string a string specifying a 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. + * @param slen length of the initial part of color_string containing the + * color. It can be set to -1 if color_string is a null terminated string + * containing nothing else than the color. + * @param log_ctx a pointer to an arbitrary struct of which the first field + * is a pointer to an AVClass struct (used for av_log()). Can be NULL. + * @return >= 0 in case of success, a negative value in case of + * failure (for example if color_string cannot be parsed). + */ +int av_parse_color(uint8_t *rgba_color, const char *color_string, int slen, + void *log_ctx); + +/** + * Get the name of a color from the internal table of hard-coded named + * colors. + * + * This function is meant to enumerate the color names recognized by + * av_parse_color(). + * + * @param color_idx index of the requested color, starting from 0 + * @param rgb if not NULL, will point to a 3-elements array with the color value in RGB + * @return the color name string or NULL if color_idx is not in the array + */ +const char *av_get_known_color_name(int color_idx, const uint8_t **rgb); + +/** + * Parse timestr and return in *time a corresponding number of + * microseconds. + * + * @param timeval puts here the number of microseconds corresponding + * to the string in timestr. If the string represents a duration, it + * is the number of microseconds contained in the time interval. If + * the string is a date, is the number of microseconds since 1st of + * January, 1970 up to the time of the parsed date. If timestr cannot + * be successfully parsed, set *time to INT64_MIN. + + * @param timestr a string representing a date or a duration. + * - If a date the syntax is: + * @code + * [{YYYY-MM-DD|YYYYMMDD}[T|t| ]]{{HH:MM:SS[.m...]]]}|{HHMMSS[.m...]]]}}[Z] + * now + * @endcode + * 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. + * - If a duration the syntax is: + * @code + * [-][HH:]MM:SS[.m...] + * [-]S+[.m...] + * @endcode + * @param duration flag which tells how to interpret timestr, if not + * zero timestr is interpreted as a duration, otherwise as a date + * @return >= 0 in case of success, a negative value corresponding to an + * AVERROR code otherwise + */ +int av_parse_time(int64_t *timeval, const char *timestr, int duration); + +/** + * Attempt to find a specific tag in a URL. + * + * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done. + * Return 1 if found. + */ +int av_find_info_tag(char *arg, int arg_size, const char *tag1, const char *info); + +/** + * Simplified version of strptime + * + * Parse the input string p according to the format string fmt and + * store its results in the structure dt. + * This implementation supports only a subset of the formats supported + * by the standard strptime(). + * + * The supported input field descriptors are listed below. + * - `%%H`: the hour as a decimal number, using a 24-hour clock, in the + * range '00' through '23' + * - `%%J`: hours as a decimal number, in the range '0' through INT_MAX + * - `%%M`: the minute as a decimal number, using a 24-hour clock, in the + * range '00' through '59' + * - `%%S`: the second as a decimal number, using a 24-hour clock, in the + * range '00' through '59' + * - `%%Y`: the year as a decimal number, using the Gregorian calendar + * - `%%m`: the month as a decimal number, in the range '1' through '12' + * - `%%d`: the day of the month as a decimal number, in the range '1' + * through '31' + * - `%%T`: alias for `%%H:%%M:%%S` + * - `%%`: a literal `%` + * + * @return a pointer to the first character not processed in this function + * call. In case the input string contains more characters than + * required by the format string the return value points right after + * the last consumed input character. In case the whole input string + * is consumed the return value points to the null byte at the end of + * the string. On failure NULL is returned. + */ +char *av_small_strptime(const char *p, const char *fmt, struct tm *dt); + +/** + * Convert the decomposed UTC time in tm to a time_t value. + */ +time_t av_timegm(struct tm *tm); + +#endif /* AVUTIL_PARSEUTILS_H */ diff --git a/ffmpeg-n8.1/include/libavutil/pixdesc.h b/ffmpeg-n8.1/include/libavutil/pixdesc.h new file mode 100644 index 00000000..0cc70eb6 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/pixdesc.h @@ -0,0 +1,450 @@ +/* + * pixel format descriptor + * Copyright (c) 2009 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_PIXDESC_H +#define AVUTIL_PIXDESC_H + +#include + +#include "attributes.h" +#include "pixfmt.h" + +typedef struct AVComponentDescriptor { + /** + * Which of the 4 planes contains the component. + */ + int plane; + + /** + * Number of elements between 2 horizontally consecutive pixels. + * Elements are bits for bitstream formats, bytes otherwise. + */ + int step; + + /** + * Number of elements before the component of the first pixel. + * Elements are bits for bitstream formats, bytes otherwise. + */ + int offset; + + /** + * Number of least significant bits that must be shifted away + * to get the value. + */ + int shift; + + /** + * Number of bits in the component. + */ + int depth; +} AVComponentDescriptor; + +/** + * Descriptor that unambiguously describes how the bits of a pixel are + * stored in the up to 4 data planes of an image. It also stores the + * subsampling factors and number of components. + * + * @note This is separate of the colorspace (RGB, YCbCr, YPbPr, JPEG-style YUV + * and all the YUV variants) AVPixFmtDescriptor just stores how values + * are stored not what these values represent. + */ +typedef struct AVPixFmtDescriptor { + const char *name; + uint8_t nb_components; ///< The number of components each pixel has, (1-4) + + /** + * Amount to shift the luma width right to find the chroma width. + * For YV12 this is 1 for example. + * chroma_width = AV_CEIL_RSHIFT(luma_width, log2_chroma_w) + * The note above is needed to ensure rounding up. + * This value only refers to the chroma components. + */ + uint8_t log2_chroma_w; + + /** + * Amount to shift the luma height right to find the chroma height. + * For YV12 this is 1 for example. + * chroma_height= AV_CEIL_RSHIFT(luma_height, log2_chroma_h) + * The note above is needed to ensure rounding up. + * This value only refers to the chroma components. + */ + uint8_t log2_chroma_h; + + /** + * Combination of AV_PIX_FMT_FLAG_... flags. + */ + uint64_t flags; + + /** + * Parameters that describe how pixels are packed. + * If the format has 1 or 2 components, then luma is 0. + * If the format has 3 or 4 components: + * if the RGB flag is set then 0 is red, 1 is green and 2 is blue; + * otherwise 0 is luma, 1 is chroma-U and 2 is chroma-V. + * + * If present, the Alpha channel is always the last component. + */ + AVComponentDescriptor comp[4]; + + /** + * Alternative comma-separated names. + */ + const char *alias; +} AVPixFmtDescriptor; + +/** + * Pixel format is big-endian. + */ +#define AV_PIX_FMT_FLAG_BE (1 << 0) +/** + * Pixel format has a palette in data[1], values are indexes in this palette. + */ +#define AV_PIX_FMT_FLAG_PAL (1 << 1) +/** + * All values of a component are bit-wise packed end to end. + */ +#define AV_PIX_FMT_FLAG_BITSTREAM (1 << 2) +/** + * Pixel format is an HW accelerated format. + */ +#define AV_PIX_FMT_FLAG_HWACCEL (1 << 3) +/** + * At least one pixel component is not in the first data plane. + */ +#define AV_PIX_FMT_FLAG_PLANAR (1 << 4) +/** + * The pixel format contains RGB-like data (as opposed to YUV/grayscale). + */ +#define AV_PIX_FMT_FLAG_RGB (1 << 5) + +/** + * The pixel format has an alpha channel. This is set on all formats that + * support alpha in some way, including AV_PIX_FMT_PAL8. The alpha is always + * straight, never pre-multiplied. + * + * If a codec or a filter does not support alpha, it should set all alpha to + * opaque, or use the equivalent pixel formats without alpha component, e.g. + * AV_PIX_FMT_RGB0 (or AV_PIX_FMT_RGB24 etc.) instead of AV_PIX_FMT_RGBA. + */ +#define AV_PIX_FMT_FLAG_ALPHA (1 << 7) + +/** + * The pixel format is following a Bayer pattern + */ +#define AV_PIX_FMT_FLAG_BAYER (1 << 8) + +/** + * The pixel format contains IEEE-754 floating point values. Precision (double, + * single, or half) should be determined by the pixel size (64, 32, or 16 bits). + */ +#define AV_PIX_FMT_FLAG_FLOAT (1 << 9) + +/** + * The pixel format contains XYZ-like data (as opposed to YUV/RGB/grayscale). + */ +#define AV_PIX_FMT_FLAG_XYZ (1 << 10) + +/** + * Return the number of bits per pixel used by the pixel format + * described by pixdesc. Note that this is not the same as the number + * of bits per sample. + * + * The returned number of bits refers to the number of bits actually + * used for storing the pixel information, that is padding bits are + * not counted. + */ +int av_get_bits_per_pixel(const AVPixFmtDescriptor *pixdesc); + +/** + * Return the number of bits per pixel for the pixel format + * described by pixdesc, including any padding or unused bits. + */ +int av_get_padded_bits_per_pixel(const AVPixFmtDescriptor *pixdesc); + +/** + * @return a pixel format descriptor for provided pixel format or NULL if + * this pixel format is unknown. + */ +const AVPixFmtDescriptor *av_pix_fmt_desc_get(enum AVPixelFormat pix_fmt); + +/** + * Iterate over all pixel format descriptors known to libavutil. + * + * @param prev previous descriptor. NULL to get the first descriptor. + * + * @return next descriptor or NULL after the last descriptor + */ +const AVPixFmtDescriptor *av_pix_fmt_desc_next(const AVPixFmtDescriptor *prev); + +/** + * @return an AVPixelFormat id described by desc, or AV_PIX_FMT_NONE if desc + * is not a valid pointer to a pixel format descriptor. + */ +enum AVPixelFormat av_pix_fmt_desc_get_id(const AVPixFmtDescriptor *desc); + +/** + * Utility function to access log2_chroma_w log2_chroma_h from + * the pixel format AVPixFmtDescriptor. + * + * @param[in] pix_fmt the pixel format + * @param[out] h_shift store log2_chroma_w (horizontal/width shift) + * @param[out] v_shift store log2_chroma_h (vertical/height shift) + * + * @return 0 on success, AVERROR(ENOSYS) on invalid or unknown pixel format + */ +int av_pix_fmt_get_chroma_sub_sample(enum AVPixelFormat pix_fmt, + int *h_shift, int *v_shift); + +/** + * @return number of planes in pix_fmt, a negative AVERROR if pix_fmt is not a + * valid pixel format. + */ +int av_pix_fmt_count_planes(enum AVPixelFormat pix_fmt); + +/** + * @return the name for provided color range or NULL if unknown. + */ +const char *av_color_range_name(enum AVColorRange range); + +/** + * @return the AVColorRange value for name or an AVError if not found. + */ +int av_color_range_from_name(const char *name); + +/** + * @return the name for provided color primaries or NULL if unknown. + */ +const char *av_color_primaries_name(enum AVColorPrimaries primaries); + +/** + * @return the AVColorPrimaries value for name or an AVError if not found. + */ +int av_color_primaries_from_name(const char *name); + +/** + * @return the name for provided color transfer or NULL if unknown. + */ +const char *av_color_transfer_name(enum AVColorTransferCharacteristic transfer); + +/** + * @return the AVColorTransferCharacteristic value for name or an AVError if not found. + */ +int av_color_transfer_from_name(const char *name); + +/** + * @return the name for provided color space or NULL if unknown. + */ +const char *av_color_space_name(enum AVColorSpace space); + +/** + * @return the AVColorSpace value for name or an AVError if not found. + */ +int av_color_space_from_name(const char *name); + +/** + * @return the name for provided chroma location or NULL if unknown. + */ +const char *av_chroma_location_name(enum AVChromaLocation location); + +/** + * @return the AVChromaLocation value for name or an AVError if not found. + */ +int av_chroma_location_from_name(const char *name); + +/** + * Converts AVChromaLocation to swscale x/y chroma position. + * + * The positions represent the chroma (0,0) position in a coordinates system + * with luma (0,0) representing the origin and luma(1,1) representing 256,256 + * + * @param xpos horizontal chroma sample position + * @param ypos vertical chroma sample position + */ +int av_chroma_location_enum_to_pos(int *xpos, int *ypos, enum AVChromaLocation pos); + +/** + * Converts swscale x/y chroma position to AVChromaLocation. + * + * The positions represent the chroma (0,0) position in a coordinates system + * with luma (0,0) representing the origin and luma(1,1) representing 256,256 + * + * @param xpos horizontal chroma sample position + * @param ypos vertical chroma sample position + */ +enum AVChromaLocation av_chroma_location_pos_to_enum(int xpos, int ypos); + +/** + * @return the name for provided alpha mode or NULL if unknown. + */ +const char *av_alpha_mode_name(enum AVAlphaMode mode); + +/** + * @return the AVAlphaMode value for name or an AVError if not found. + */ +enum AVAlphaMode av_alpha_mode_from_name(const char *name); + +/** + * Return the pixel format corresponding to name. + * + * If there is no pixel format with name name, then looks for a + * pixel format with the name corresponding to the native endian + * format of name. + * For example in a little-endian system, first looks for "gray16", + * then for "gray16le". + * + * Finally if no pixel format has been found, returns AV_PIX_FMT_NONE. + */ +enum AVPixelFormat av_get_pix_fmt(const char *name); + +/** + * Return the short name for a pixel format, NULL in case pix_fmt is + * unknown. + * + * @see av_get_pix_fmt(), av_get_pix_fmt_string() + */ +const char *av_get_pix_fmt_name(enum AVPixelFormat pix_fmt); + +/** + * Print in buf the string corresponding to the pixel format with + * number pix_fmt, or a header if pix_fmt is negative. + * + * @param buf the buffer where to write the string + * @param buf_size the size of buf + * @param pix_fmt the number of the pixel format to print the + * corresponding info string, or a negative value to print the + * corresponding header. + */ +char *av_get_pix_fmt_string(char *buf, int buf_size, + enum AVPixelFormat pix_fmt); + +/** + * Read a line from an image, and write the values of the + * pixel format component c to dst. + * + * @param data the array containing the pointers to the planes of the image + * @param linesize the array containing the linesizes of the image + * @param desc the pixel format descriptor for the image + * @param x the horizontal coordinate of the first pixel to read + * @param y the vertical coordinate of the first pixel to read + * @param w the width of the line to read, that is the number of + * values to write to dst + * @param read_pal_component if not zero and the format is a paletted + * format writes the values corresponding to the palette + * component c in data[1] to dst, rather than the palette indexes in + * data[0]. The behavior is undefined if the format is not paletted. + * @param dst_element_size size of elements in dst array (2 or 4 byte) + */ +void av_read_image_line2(void *dst, const uint8_t *data[4], + const int linesize[4], const AVPixFmtDescriptor *desc, + int x, int y, int c, int w, int read_pal_component, + int dst_element_size); + +void av_read_image_line(uint16_t *dst, const uint8_t *data[4], + const int linesize[4], const AVPixFmtDescriptor *desc, + int x, int y, int c, int w, int read_pal_component); + +/** + * Write the values from src to the pixel format component c of an + * image line. + * + * @param src array containing the values to write + * @param data the array containing the pointers to the planes of the + * image to write into. It is supposed to be zeroed. + * @param linesize the array containing the linesizes of the image + * @param desc the pixel format descriptor for the image + * @param x the horizontal coordinate of the first pixel to write + * @param y the vertical coordinate of the first pixel to write + * @param w the width of the line to write, that is the number of + * values to write to the image line + * @param src_element_size size of elements in src array (2 or 4 byte) + */ +void av_write_image_line2(const void *src, uint8_t *data[4], + const int linesize[4], const AVPixFmtDescriptor *desc, + int x, int y, int c, int w, int src_element_size); + +void av_write_image_line(const uint16_t *src, uint8_t *data[4], + const int linesize[4], const AVPixFmtDescriptor *desc, + int x, int y, int c, int w); + +/** + * Utility function to swap the endianness of a pixel format. + * + * @param[in] pix_fmt the pixel format + * + * @return pixel format with swapped endianness if it exists, + * otherwise AV_PIX_FMT_NONE + */ +enum AVPixelFormat av_pix_fmt_swap_endianness(enum AVPixelFormat pix_fmt); + +#define FF_LOSS_RESOLUTION 0x0001 /**< loss due to resolution change */ +#define FF_LOSS_DEPTH 0x0002 /**< loss due to color depth change */ +#define FF_LOSS_COLORSPACE 0x0004 /**< loss due to color space conversion */ +#define FF_LOSS_ALPHA 0x0008 /**< loss of alpha bits */ +#define FF_LOSS_COLORQUANT 0x0010 /**< loss due to color quantization */ +#define FF_LOSS_CHROMA 0x0020 /**< loss of chroma (e.g. RGB to gray conversion) */ +#define FF_LOSS_EXCESS_RESOLUTION 0x0040 /**< loss due to unneeded extra resolution */ +#define FF_LOSS_EXCESS_DEPTH 0x0080 /**< loss due to unneeded extra color depth */ + + +/** + * Compute what kind of losses will occur when converting from one specific + * pixel format to another. + * When converting from one pixel format to another, information loss may occur. + * For example, when converting from RGB24 to GRAY, the color information will + * be lost. Similarly, other losses occur when converting from some formats to + * other formats. These losses can involve loss of chroma, but also loss of + * resolution, loss of color depth, loss due to the color space conversion, loss + * of the alpha bits or loss due to color quantization. + * av_get_fix_fmt_loss() informs you about the various types of losses + * which will occur when converting from one pixel format to another. + * + * @param[in] dst_pix_fmt destination pixel format + * @param[in] src_pix_fmt source pixel format + * @param[in] has_alpha Whether the source pixel format alpha channel is used. + * @return Combination of flags informing you what kind of losses will occur + * (maximum loss for an invalid dst_pix_fmt). + */ +int av_get_pix_fmt_loss(enum AVPixelFormat dst_pix_fmt, + enum AVPixelFormat src_pix_fmt, + int has_alpha); + +/** + * Compute what kind of losses will occur when converting from one specific + * pixel format to another. + * When converting from one pixel format to another, information loss may occur. + * For example, when converting from RGB24 to GRAY, the color information will + * be lost. Similarly, other losses occur when converting from some formats to + * other formats. These losses can involve loss of chroma, but also loss of + * resolution, loss of color depth, loss due to the color space conversion, loss + * of the alpha bits or loss due to color quantization. + * av_get_fix_fmt_loss() informs you about the various types of losses + * which will occur when converting from one pixel format to another. + * + * @param[in] dst_pix_fmt destination pixel format + * @param[in] src_pix_fmt source pixel format + * @param[in] has_alpha Whether the source pixel format alpha channel is used. + * @return Combination of flags informing you what kind of losses will occur + * (maximum loss for an invalid dst_pix_fmt). + */ +enum AVPixelFormat av_find_best_pix_fmt_of_2(enum AVPixelFormat dst_pix_fmt1, enum AVPixelFormat dst_pix_fmt2, + enum AVPixelFormat src_pix_fmt, int has_alpha, int *loss_ptr); + +#endif /* AVUTIL_PIXDESC_H */ diff --git a/ffmpeg-n8.1/include/libavutil/pixelutils.h b/ffmpeg-n8.1/include/libavutil/pixelutils.h new file mode 100644 index 00000000..7a997cde --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/pixelutils.h @@ -0,0 +1,51 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_PIXELUTILS_H +#define AVUTIL_PIXELUTILS_H + +#include +#include + +/** + * Sum of abs(src1[x] - src2[x]) + */ +typedef int (*av_pixelutils_sad_fn)(const uint8_t *src1, ptrdiff_t stride1, + const uint8_t *src2, ptrdiff_t stride2); + +/** + * Get a potentially optimized pointer to a Sum-of-absolute-differences + * function (see the av_pixelutils_sad_fn prototype). + * + * @param w_bits 1< + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_PIXFMT_H +#define AVUTIL_PIXFMT_H + +/** + * @file + * pixel format definitions + */ + +#include "libavutil/avconfig.h" +#include "version.h" + +#define AVPALETTE_SIZE 1024 +#define AVPALETTE_COUNT 256 + +/** + * Maximum number of planes in any pixel format. + * This should be used when a maximum is needed, but code should not + * be written to require a maximum for no good reason. + */ +#define AV_VIDEO_MAX_PLANES 4 + +/** + * Pixel format. + * + * @note + * AV_PIX_FMT_RGB32 is handled in an endian-specific manner. An RGBA + * color is put together as: + * (A << 24) | (R << 16) | (G << 8) | B + * This is stored as BGRA on little-endian CPU architectures and ARGB on + * big-endian CPUs. + * + * @note + * If the resolution is not a multiple of the chroma subsampling factor + * then the chroma plane resolution must be rounded up. + * + * @par + * When the pixel format is palettized RGB32 (AV_PIX_FMT_PAL8), the palettized + * image data is stored in AVFrame.data[0]. The palette is transported in + * AVFrame.data[1], is 1024 bytes long (256 4-byte entries) and is + * formatted the same as in AV_PIX_FMT_RGB32 described above (i.e., it is + * also endian-specific). Note also that the individual RGB32 palette + * components stored in AVFrame.data[1] should be in the range 0..255. + * This is important as many custom PAL8 video codecs that were designed + * to run on the IBM VGA graphics adapter use 6-bit palette components. + * + * @par + * For all the 8 bits per pixel formats, an RGB32 palette is in data[1] like + * for pal8. This palette is filled in automatically by the function + * allocating the picture. + */ +enum AVPixelFormat { + AV_PIX_FMT_NONE = -1, + AV_PIX_FMT_YUV420P, ///< planar YUV 4:2:0, 12bpp, (1 Cr & Cb sample per 2x2 Y samples) + AV_PIX_FMT_YUYV422, ///< packed YUV 4:2:2, 16bpp, Y0 Cb Y1 Cr + AV_PIX_FMT_RGB24, ///< packed RGB 8:8:8, 24bpp, RGBRGB... + AV_PIX_FMT_BGR24, ///< packed RGB 8:8:8, 24bpp, BGRBGR... + AV_PIX_FMT_YUV422P, ///< planar YUV 4:2:2, 16bpp, (1 Cr & Cb sample per 2x1 Y samples) + AV_PIX_FMT_YUV444P, ///< planar YUV 4:4:4, 24bpp, (1 Cr & Cb sample per 1x1 Y samples) + AV_PIX_FMT_YUV410P, ///< planar YUV 4:1:0, 9bpp, (1 Cr & Cb sample per 4x4 Y samples) + AV_PIX_FMT_YUV411P, ///< planar YUV 4:1:1, 12bpp, (1 Cr & Cb sample per 4x1 Y samples) + AV_PIX_FMT_GRAY8, ///< Y , 8bpp + AV_PIX_FMT_MONOWHITE, ///< Y , 1bpp, 0 is white, 1 is black, in each byte pixels are ordered from the msb to the lsb + AV_PIX_FMT_MONOBLACK, ///< Y , 1bpp, 0 is black, 1 is white, in each byte pixels are ordered from the msb to the lsb + AV_PIX_FMT_PAL8, ///< 8 bits with AV_PIX_FMT_RGB32 palette + AV_PIX_FMT_YUVJ420P, ///< planar YUV 4:2:0, 12bpp, full scale (JPEG), deprecated in favor of AV_PIX_FMT_YUV420P and setting color_range + AV_PIX_FMT_YUVJ422P, ///< planar YUV 4:2:2, 16bpp, full scale (JPEG), deprecated in favor of AV_PIX_FMT_YUV422P and setting color_range + AV_PIX_FMT_YUVJ444P, ///< planar YUV 4:4:4, 24bpp, full scale (JPEG), deprecated in favor of AV_PIX_FMT_YUV444P and setting color_range + AV_PIX_FMT_UYVY422, ///< packed YUV 4:2:2, 16bpp, Cb Y0 Cr Y1 + AV_PIX_FMT_UYYVYY411, ///< packed YUV 4:1:1, 12bpp, Cb Y0 Y1 Cr Y2 Y3 + AV_PIX_FMT_BGR8, ///< packed RGB 3:3:2, 8bpp, (msb)2B 3G 3R(lsb) + AV_PIX_FMT_BGR4, ///< packed RGB 1:2:1 bitstream, 4bpp, (msb)1B 2G 1R(lsb), a byte contains two pixels, the first pixel in the byte is the one composed by the 4 msb bits + AV_PIX_FMT_BGR4_BYTE, ///< packed RGB 1:2:1, 8bpp, (msb)1B 2G 1R(lsb) + AV_PIX_FMT_RGB8, ///< packed RGB 3:3:2, 8bpp, (msb)3R 3G 2B(lsb) + AV_PIX_FMT_RGB4, ///< packed RGB 1:2:1 bitstream, 4bpp, (msb)1R 2G 1B(lsb), a byte contains two pixels, the first pixel in the byte is the one composed by the 4 msb bits + AV_PIX_FMT_RGB4_BYTE, ///< packed RGB 1:2:1, 8bpp, (msb)1R 2G 1B(lsb) + AV_PIX_FMT_NV12, ///< planar YUV 4:2:0, 12bpp, 1 plane for Y and 1 plane for the UV components, which are interleaved (first byte U and the following byte V) + AV_PIX_FMT_NV21, ///< as above, but U and V bytes are swapped + + AV_PIX_FMT_ARGB, ///< packed ARGB 8:8:8:8, 32bpp, ARGBARGB... + AV_PIX_FMT_RGBA, ///< packed RGBA 8:8:8:8, 32bpp, RGBARGBA... + AV_PIX_FMT_ABGR, ///< packed ABGR 8:8:8:8, 32bpp, ABGRABGR... + AV_PIX_FMT_BGRA, ///< packed BGRA 8:8:8:8, 32bpp, BGRABGRA... + + AV_PIX_FMT_GRAY16BE, ///< Y , 16bpp, big-endian + AV_PIX_FMT_GRAY16LE, ///< Y , 16bpp, little-endian + AV_PIX_FMT_YUV440P, ///< planar YUV 4:4:0 (1 Cr & Cb sample per 1x2 Y samples) + AV_PIX_FMT_YUVJ440P, ///< planar YUV 4:4:0 full scale (JPEG), deprecated in favor of AV_PIX_FMT_YUV440P and setting color_range + AV_PIX_FMT_YUVA420P, ///< planar YUV 4:2:0, 20bpp, (1 Cr & Cb sample per 2x2 Y & A samples) + AV_PIX_FMT_RGB48BE, ///< packed RGB 16:16:16, 48bpp, 16R, 16G, 16B, the 2-byte value for each R/G/B component is stored as big-endian + AV_PIX_FMT_RGB48LE, ///< packed RGB 16:16:16, 48bpp, 16R, 16G, 16B, the 2-byte value for each R/G/B component is stored as little-endian + + AV_PIX_FMT_RGB565BE, ///< packed RGB 5:6:5, 16bpp, (msb) 5R 6G 5B(lsb), big-endian + AV_PIX_FMT_RGB565LE, ///< packed RGB 5:6:5, 16bpp, (msb) 5R 6G 5B(lsb), little-endian + AV_PIX_FMT_RGB555BE, ///< packed RGB 5:5:5, 16bpp, (msb)1X 5R 5G 5B(lsb), big-endian , X=unused/undefined + AV_PIX_FMT_RGB555LE, ///< packed RGB 5:5:5, 16bpp, (msb)1X 5R 5G 5B(lsb), little-endian, X=unused/undefined + + AV_PIX_FMT_BGR565BE, ///< packed BGR 5:6:5, 16bpp, (msb) 5B 6G 5R(lsb), big-endian + AV_PIX_FMT_BGR565LE, ///< packed BGR 5:6:5, 16bpp, (msb) 5B 6G 5R(lsb), little-endian + AV_PIX_FMT_BGR555BE, ///< packed BGR 5:5:5, 16bpp, (msb)1X 5B 5G 5R(lsb), big-endian , X=unused/undefined + AV_PIX_FMT_BGR555LE, ///< packed BGR 5:5:5, 16bpp, (msb)1X 5B 5G 5R(lsb), little-endian, X=unused/undefined + + /** + * Hardware acceleration through VA-API, data[3] contains a + * VASurfaceID. + */ + AV_PIX_FMT_VAAPI, + + AV_PIX_FMT_YUV420P16LE, ///< planar YUV 4:2:0, 24bpp, (1 Cr & Cb sample per 2x2 Y samples), little-endian + AV_PIX_FMT_YUV420P16BE, ///< planar YUV 4:2:0, 24bpp, (1 Cr & Cb sample per 2x2 Y samples), big-endian + AV_PIX_FMT_YUV422P16LE, ///< planar YUV 4:2:2, 32bpp, (1 Cr & Cb sample per 2x1 Y samples), little-endian + AV_PIX_FMT_YUV422P16BE, ///< planar YUV 4:2:2, 32bpp, (1 Cr & Cb sample per 2x1 Y samples), big-endian + AV_PIX_FMT_YUV444P16LE, ///< planar YUV 4:4:4, 48bpp, (1 Cr & Cb sample per 1x1 Y samples), little-endian + AV_PIX_FMT_YUV444P16BE, ///< planar YUV 4:4:4, 48bpp, (1 Cr & Cb sample per 1x1 Y samples), big-endian + AV_PIX_FMT_DXVA2_VLD, ///< HW decoding through DXVA2, Picture.data[3] contains a LPDIRECT3DSURFACE9 pointer + + AV_PIX_FMT_RGB444LE, ///< packed RGB 4:4:4, 16bpp, (msb)4X 4R 4G 4B(lsb), little-endian, X=unused/undefined + AV_PIX_FMT_RGB444BE, ///< packed RGB 4:4:4, 16bpp, (msb)4X 4R 4G 4B(lsb), big-endian, X=unused/undefined + AV_PIX_FMT_BGR444LE, ///< packed BGR 4:4:4, 16bpp, (msb)4X 4B 4G 4R(lsb), little-endian, X=unused/undefined + AV_PIX_FMT_BGR444BE, ///< packed BGR 4:4:4, 16bpp, (msb)4X 4B 4G 4R(lsb), big-endian, X=unused/undefined + AV_PIX_FMT_YA8, ///< 8 bits gray, 8 bits alpha + + AV_PIX_FMT_Y400A = AV_PIX_FMT_YA8, ///< alias for AV_PIX_FMT_YA8 + AV_PIX_FMT_GRAY8A= AV_PIX_FMT_YA8, ///< alias for AV_PIX_FMT_YA8 + + AV_PIX_FMT_BGR48BE, ///< packed RGB 16:16:16, 48bpp, 16B, 16G, 16R, the 2-byte value for each R/G/B component is stored as big-endian + AV_PIX_FMT_BGR48LE, ///< packed RGB 16:16:16, 48bpp, 16B, 16G, 16R, the 2-byte value for each R/G/B component is stored as little-endian + + /** + * The following 12 formats have the disadvantage of needing 1 format for each bit depth. + * Notice that each 9/10 bits sample is stored in 16 bits with extra padding. + * If you want to support multiple bit depths, then using AV_PIX_FMT_YUV420P16* with the bpp stored separately is better. + */ + AV_PIX_FMT_YUV420P9BE, ///< planar YUV 4:2:0, 13.5bpp, (1 Cr & Cb sample per 2x2 Y samples), big-endian + AV_PIX_FMT_YUV420P9LE, ///< planar YUV 4:2:0, 13.5bpp, (1 Cr & Cb sample per 2x2 Y samples), little-endian + AV_PIX_FMT_YUV420P10BE,///< planar YUV 4:2:0, 15bpp, (1 Cr & Cb sample per 2x2 Y samples), big-endian + AV_PIX_FMT_YUV420P10LE,///< planar YUV 4:2:0, 15bpp, (1 Cr & Cb sample per 2x2 Y samples), little-endian + AV_PIX_FMT_YUV422P10BE,///< planar YUV 4:2:2, 20bpp, (1 Cr & Cb sample per 2x1 Y samples), big-endian + AV_PIX_FMT_YUV422P10LE,///< planar YUV 4:2:2, 20bpp, (1 Cr & Cb sample per 2x1 Y samples), little-endian + AV_PIX_FMT_YUV444P9BE, ///< planar YUV 4:4:4, 27bpp, (1 Cr & Cb sample per 1x1 Y samples), big-endian + AV_PIX_FMT_YUV444P9LE, ///< planar YUV 4:4:4, 27bpp, (1 Cr & Cb sample per 1x1 Y samples), little-endian + AV_PIX_FMT_YUV444P10BE,///< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), big-endian + AV_PIX_FMT_YUV444P10LE,///< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), little-endian + AV_PIX_FMT_YUV422P9BE, ///< planar YUV 4:2:2, 18bpp, (1 Cr & Cb sample per 2x1 Y samples), big-endian + AV_PIX_FMT_YUV422P9LE, ///< planar YUV 4:2:2, 18bpp, (1 Cr & Cb sample per 2x1 Y samples), little-endian + AV_PIX_FMT_GBRP, ///< planar GBR 4:4:4 24bpp + AV_PIX_FMT_GBR24P = AV_PIX_FMT_GBRP, // alias for #AV_PIX_FMT_GBRP + AV_PIX_FMT_GBRP9BE, ///< planar GBR 4:4:4 27bpp, big-endian + AV_PIX_FMT_GBRP9LE, ///< planar GBR 4:4:4 27bpp, little-endian + AV_PIX_FMT_GBRP10BE, ///< planar GBR 4:4:4 30bpp, big-endian + AV_PIX_FMT_GBRP10LE, ///< planar GBR 4:4:4 30bpp, little-endian + AV_PIX_FMT_GBRP16BE, ///< planar GBR 4:4:4 48bpp, big-endian + AV_PIX_FMT_GBRP16LE, ///< planar GBR 4:4:4 48bpp, little-endian + AV_PIX_FMT_YUVA422P, ///< planar YUV 4:2:2 24bpp, (1 Cr & Cb sample per 2x1 Y & A samples) + AV_PIX_FMT_YUVA444P, ///< planar YUV 4:4:4 32bpp, (1 Cr & Cb sample per 1x1 Y & A samples) + AV_PIX_FMT_YUVA420P9BE, ///< planar YUV 4:2:0 22.5bpp, (1 Cr & Cb sample per 2x2 Y & A samples), big-endian + AV_PIX_FMT_YUVA420P9LE, ///< planar YUV 4:2:0 22.5bpp, (1 Cr & Cb sample per 2x2 Y & A samples), little-endian + AV_PIX_FMT_YUVA422P9BE, ///< planar YUV 4:2:2 27bpp, (1 Cr & Cb sample per 2x1 Y & A samples), big-endian + AV_PIX_FMT_YUVA422P9LE, ///< planar YUV 4:2:2 27bpp, (1 Cr & Cb sample per 2x1 Y & A samples), little-endian + AV_PIX_FMT_YUVA444P9BE, ///< planar YUV 4:4:4 36bpp, (1 Cr & Cb sample per 1x1 Y & A samples), big-endian + AV_PIX_FMT_YUVA444P9LE, ///< planar YUV 4:4:4 36bpp, (1 Cr & Cb sample per 1x1 Y & A samples), little-endian + AV_PIX_FMT_YUVA420P10BE, ///< planar YUV 4:2:0 25bpp, (1 Cr & Cb sample per 2x2 Y & A samples, big-endian) + AV_PIX_FMT_YUVA420P10LE, ///< planar YUV 4:2:0 25bpp, (1 Cr & Cb sample per 2x2 Y & A samples, little-endian) + AV_PIX_FMT_YUVA422P10BE, ///< planar YUV 4:2:2 30bpp, (1 Cr & Cb sample per 2x1 Y & A samples, big-endian) + AV_PIX_FMT_YUVA422P10LE, ///< planar YUV 4:2:2 30bpp, (1 Cr & Cb sample per 2x1 Y & A samples, little-endian) + AV_PIX_FMT_YUVA444P10BE, ///< planar YUV 4:4:4 40bpp, (1 Cr & Cb sample per 1x1 Y & A samples, big-endian) + AV_PIX_FMT_YUVA444P10LE, ///< planar YUV 4:4:4 40bpp, (1 Cr & Cb sample per 1x1 Y & A samples, little-endian) + AV_PIX_FMT_YUVA420P16BE, ///< planar YUV 4:2:0 40bpp, (1 Cr & Cb sample per 2x2 Y & A samples, big-endian) + AV_PIX_FMT_YUVA420P16LE, ///< planar YUV 4:2:0 40bpp, (1 Cr & Cb sample per 2x2 Y & A samples, little-endian) + AV_PIX_FMT_YUVA422P16BE, ///< planar YUV 4:2:2 48bpp, (1 Cr & Cb sample per 2x1 Y & A samples, big-endian) + AV_PIX_FMT_YUVA422P16LE, ///< planar YUV 4:2:2 48bpp, (1 Cr & Cb sample per 2x1 Y & A samples, little-endian) + AV_PIX_FMT_YUVA444P16BE, ///< planar YUV 4:4:4 64bpp, (1 Cr & Cb sample per 1x1 Y & A samples, big-endian) + AV_PIX_FMT_YUVA444P16LE, ///< planar YUV 4:4:4 64bpp, (1 Cr & Cb sample per 1x1 Y & A samples, little-endian) + + AV_PIX_FMT_VDPAU, ///< HW acceleration through VDPAU, Picture.data[3] contains a VdpVideoSurface + + AV_PIX_FMT_XYZ12LE, ///< packed XYZ 4:4:4, 36 bpp, (msb) 12X, 12Y, 12Z (lsb), the 2-byte value for each X/Y/Z is stored as little-endian, the 4 lower bits are set to 0 + AV_PIX_FMT_XYZ12BE, ///< packed XYZ 4:4:4, 36 bpp, (msb) 12X, 12Y, 12Z (lsb), the 2-byte value for each X/Y/Z is stored as big-endian, the 4 lower bits are set to 0 + AV_PIX_FMT_NV16, ///< interleaved chroma YUV 4:2:2, 16bpp, (1 Cr & Cb sample per 2x1 Y samples) + AV_PIX_FMT_NV20LE, ///< interleaved chroma YUV 4:2:2, 20bpp, (1 Cr & Cb sample per 2x1 Y samples), little-endian + AV_PIX_FMT_NV20BE, ///< interleaved chroma YUV 4:2:2, 20bpp, (1 Cr & Cb sample per 2x1 Y samples), big-endian + + AV_PIX_FMT_RGBA64BE, ///< packed RGBA 16:16:16:16, 64bpp, 16R, 16G, 16B, 16A, the 2-byte value for each R/G/B/A component is stored as big-endian + AV_PIX_FMT_RGBA64LE, ///< packed RGBA 16:16:16:16, 64bpp, 16R, 16G, 16B, 16A, the 2-byte value for each R/G/B/A component is stored as little-endian + AV_PIX_FMT_BGRA64BE, ///< packed RGBA 16:16:16:16, 64bpp, 16B, 16G, 16R, 16A, the 2-byte value for each R/G/B/A component is stored as big-endian + AV_PIX_FMT_BGRA64LE, ///< packed RGBA 16:16:16:16, 64bpp, 16B, 16G, 16R, 16A, the 2-byte value for each R/G/B/A component is stored as little-endian + + AV_PIX_FMT_YVYU422, ///< packed YUV 4:2:2, 16bpp, Y0 Cr Y1 Cb + + AV_PIX_FMT_YA16BE, ///< 16 bits gray, 16 bits alpha (big-endian) + AV_PIX_FMT_YA16LE, ///< 16 bits gray, 16 bits alpha (little-endian) + + AV_PIX_FMT_GBRAP, ///< planar GBRA 4:4:4:4 32bpp + AV_PIX_FMT_GBRAP16BE, ///< planar GBRA 4:4:4:4 64bpp, big-endian + AV_PIX_FMT_GBRAP16LE, ///< planar GBRA 4:4:4:4 64bpp, little-endian + /** + * HW acceleration through QSV, data[3] contains a pointer to the + * mfxFrameSurface1 structure. + * + * Before FFmpeg 5.0: + * mfxFrameSurface1.Data.MemId contains a pointer when importing + * the following frames as QSV frames: + * + * VAAPI: + * mfxFrameSurface1.Data.MemId contains a pointer to VASurfaceID + * + * DXVA2: + * mfxFrameSurface1.Data.MemId contains a pointer to IDirect3DSurface9 + * + * FFmpeg 5.0 and above: + * mfxFrameSurface1.Data.MemId contains a pointer to the mfxHDLPair + * structure when importing the following frames as QSV frames: + * + * VAAPI: + * mfxHDLPair.first contains a VASurfaceID pointer. + * mfxHDLPair.second is always MFX_INFINITE. + * + * DXVA2: + * mfxHDLPair.first contains IDirect3DSurface9 pointer. + * mfxHDLPair.second is always MFX_INFINITE. + * + * D3D11: + * mfxHDLPair.first contains a ID3D11Texture2D pointer. + * mfxHDLPair.second contains the texture array index of the frame if the + * ID3D11Texture2D is an array texture, or always MFX_INFINITE if it is a + * normal texture. + */ + AV_PIX_FMT_QSV, + /** + * HW acceleration though MMAL, data[3] contains a pointer to the + * MMAL_BUFFER_HEADER_T structure. + */ + AV_PIX_FMT_MMAL, + + AV_PIX_FMT_D3D11VA_VLD, ///< HW decoding through Direct3D11 via old API, Picture.data[3] contains a ID3D11VideoDecoderOutputView pointer + + /** + * HW acceleration through CUDA. data[i] contain CUdeviceptr pointers + * exactly as for system memory frames. + */ + AV_PIX_FMT_CUDA, + + AV_PIX_FMT_0RGB, ///< packed RGB 8:8:8, 32bpp, XRGBXRGB... X=unused/undefined + AV_PIX_FMT_RGB0, ///< packed RGB 8:8:8, 32bpp, RGBXRGBX... X=unused/undefined + AV_PIX_FMT_0BGR, ///< packed BGR 8:8:8, 32bpp, XBGRXBGR... X=unused/undefined + AV_PIX_FMT_BGR0, ///< packed BGR 8:8:8, 32bpp, BGRXBGRX... X=unused/undefined + + AV_PIX_FMT_YUV420P12BE, ///< planar YUV 4:2:0,18bpp, (1 Cr & Cb sample per 2x2 Y samples), big-endian + AV_PIX_FMT_YUV420P12LE, ///< planar YUV 4:2:0,18bpp, (1 Cr & Cb sample per 2x2 Y samples), little-endian + AV_PIX_FMT_YUV420P14BE, ///< planar YUV 4:2:0,21bpp, (1 Cr & Cb sample per 2x2 Y samples), big-endian + AV_PIX_FMT_YUV420P14LE, ///< planar YUV 4:2:0,21bpp, (1 Cr & Cb sample per 2x2 Y samples), little-endian + AV_PIX_FMT_YUV422P12BE, ///< planar YUV 4:2:2,24bpp, (1 Cr & Cb sample per 2x1 Y samples), big-endian + AV_PIX_FMT_YUV422P12LE, ///< planar YUV 4:2:2,24bpp, (1 Cr & Cb sample per 2x1 Y samples), little-endian + AV_PIX_FMT_YUV422P14BE, ///< planar YUV 4:2:2,28bpp, (1 Cr & Cb sample per 2x1 Y samples), big-endian + AV_PIX_FMT_YUV422P14LE, ///< planar YUV 4:2:2,28bpp, (1 Cr & Cb sample per 2x1 Y samples), little-endian + AV_PIX_FMT_YUV444P12BE, ///< planar YUV 4:4:4,36bpp, (1 Cr & Cb sample per 1x1 Y samples), big-endian + AV_PIX_FMT_YUV444P12LE, ///< planar YUV 4:4:4,36bpp, (1 Cr & Cb sample per 1x1 Y samples), little-endian + AV_PIX_FMT_YUV444P14BE, ///< planar YUV 4:4:4,42bpp, (1 Cr & Cb sample per 1x1 Y samples), big-endian + AV_PIX_FMT_YUV444P14LE, ///< planar YUV 4:4:4,42bpp, (1 Cr & Cb sample per 1x1 Y samples), little-endian + AV_PIX_FMT_GBRP12BE, ///< planar GBR 4:4:4 36bpp, big-endian + AV_PIX_FMT_GBRP12LE, ///< planar GBR 4:4:4 36bpp, little-endian + AV_PIX_FMT_GBRP14BE, ///< planar GBR 4:4:4 42bpp, big-endian + AV_PIX_FMT_GBRP14LE, ///< planar GBR 4:4:4 42bpp, little-endian + AV_PIX_FMT_YUVJ411P, ///< planar YUV 4:1:1, 12bpp, (1 Cr & Cb sample per 4x1 Y samples) full scale (JPEG), deprecated in favor of AV_PIX_FMT_YUV411P and setting color_range + + AV_PIX_FMT_BAYER_BGGR8, ///< bayer, BGBG..(odd line), GRGR..(even line), 8-bit samples + AV_PIX_FMT_BAYER_RGGB8, ///< bayer, RGRG..(odd line), GBGB..(even line), 8-bit samples + AV_PIX_FMT_BAYER_GBRG8, ///< bayer, GBGB..(odd line), RGRG..(even line), 8-bit samples + AV_PIX_FMT_BAYER_GRBG8, ///< bayer, GRGR..(odd line), BGBG..(even line), 8-bit samples + AV_PIX_FMT_BAYER_BGGR16LE, ///< bayer, BGBG..(odd line), GRGR..(even line), 16-bit samples, little-endian + AV_PIX_FMT_BAYER_BGGR16BE, ///< bayer, BGBG..(odd line), GRGR..(even line), 16-bit samples, big-endian + AV_PIX_FMT_BAYER_RGGB16LE, ///< bayer, RGRG..(odd line), GBGB..(even line), 16-bit samples, little-endian + AV_PIX_FMT_BAYER_RGGB16BE, ///< bayer, RGRG..(odd line), GBGB..(even line), 16-bit samples, big-endian + AV_PIX_FMT_BAYER_GBRG16LE, ///< bayer, GBGB..(odd line), RGRG..(even line), 16-bit samples, little-endian + AV_PIX_FMT_BAYER_GBRG16BE, ///< bayer, GBGB..(odd line), RGRG..(even line), 16-bit samples, big-endian + AV_PIX_FMT_BAYER_GRBG16LE, ///< bayer, GRGR..(odd line), BGBG..(even line), 16-bit samples, little-endian + AV_PIX_FMT_BAYER_GRBG16BE, ///< bayer, GRGR..(odd line), BGBG..(even line), 16-bit samples, big-endian + + AV_PIX_FMT_YUV440P10LE, ///< planar YUV 4:4:0,20bpp, (1 Cr & Cb sample per 1x2 Y samples), little-endian + AV_PIX_FMT_YUV440P10BE, ///< planar YUV 4:4:0,20bpp, (1 Cr & Cb sample per 1x2 Y samples), big-endian + AV_PIX_FMT_YUV440P12LE, ///< planar YUV 4:4:0,24bpp, (1 Cr & Cb sample per 1x2 Y samples), little-endian + AV_PIX_FMT_YUV440P12BE, ///< planar YUV 4:4:0,24bpp, (1 Cr & Cb sample per 1x2 Y samples), big-endian + AV_PIX_FMT_AYUV64LE, ///< packed AYUV 4:4:4,64bpp (1 Cr & Cb sample per 1x1 Y & A samples), little-endian + AV_PIX_FMT_AYUV64BE, ///< packed AYUV 4:4:4,64bpp (1 Cr & Cb sample per 1x1 Y & A samples), big-endian + + AV_PIX_FMT_VIDEOTOOLBOX, ///< hardware decoding through Videotoolbox + + AV_PIX_FMT_P010LE, ///< like NV12, with 10bpp per component, data in the high bits, zeros in the low bits, little-endian + AV_PIX_FMT_P010BE, ///< like NV12, with 10bpp per component, data in the high bits, zeros in the low bits, big-endian + + AV_PIX_FMT_GBRAP12BE, ///< planar GBR 4:4:4:4 48bpp, big-endian + AV_PIX_FMT_GBRAP12LE, ///< planar GBR 4:4:4:4 48bpp, little-endian + + AV_PIX_FMT_GBRAP10BE, ///< planar GBR 4:4:4:4 40bpp, big-endian + AV_PIX_FMT_GBRAP10LE, ///< planar GBR 4:4:4:4 40bpp, little-endian + + AV_PIX_FMT_MEDIACODEC, ///< hardware decoding through MediaCodec + + AV_PIX_FMT_GRAY12BE, ///< Y , 12bpp, big-endian + AV_PIX_FMT_GRAY12LE, ///< Y , 12bpp, little-endian + AV_PIX_FMT_GRAY10BE, ///< Y , 10bpp, big-endian + AV_PIX_FMT_GRAY10LE, ///< Y , 10bpp, little-endian + + AV_PIX_FMT_P016LE, ///< like NV12, with 16bpp per component, little-endian + AV_PIX_FMT_P016BE, ///< like NV12, with 16bpp per component, big-endian + + /** + * Hardware surfaces for Direct3D11. + * + * This is preferred over the legacy AV_PIX_FMT_D3D11VA_VLD. The new D3D11 + * hwaccel API and filtering support AV_PIX_FMT_D3D11 only. + * + * data[0] contains a ID3D11Texture2D pointer, and data[1] contains the + * texture array index of the frame as intptr_t if the ID3D11Texture2D is + * an array texture (or always 0 if it's a normal texture). + */ + AV_PIX_FMT_D3D11, + + AV_PIX_FMT_GRAY9BE, ///< Y , 9bpp, big-endian + AV_PIX_FMT_GRAY9LE, ///< Y , 9bpp, little-endian + + AV_PIX_FMT_GBRPF32BE, ///< IEEE-754 single precision planar GBR 4:4:4, 96bpp, big-endian + AV_PIX_FMT_GBRPF32LE, ///< IEEE-754 single precision planar GBR 4:4:4, 96bpp, little-endian + AV_PIX_FMT_GBRAPF32BE, ///< IEEE-754 single precision planar GBRA 4:4:4:4, 128bpp, big-endian + AV_PIX_FMT_GBRAPF32LE, ///< IEEE-754 single precision planar GBRA 4:4:4:4, 128bpp, little-endian + + /** + * DRM-managed buffers exposed through PRIME buffer sharing. + * + * data[0] points to an AVDRMFrameDescriptor. + */ + AV_PIX_FMT_DRM_PRIME, + /** + * Hardware surfaces for OpenCL. + * + * data[i] contain 2D image objects (typed in C as cl_mem, used + * in OpenCL as image2d_t) for each plane of the surface. + */ + AV_PIX_FMT_OPENCL, + + AV_PIX_FMT_GRAY14BE, ///< Y , 14bpp, big-endian + AV_PIX_FMT_GRAY14LE, ///< Y , 14bpp, little-endian + + AV_PIX_FMT_GRAYF32BE, ///< IEEE-754 single precision Y, 32bpp, big-endian + AV_PIX_FMT_GRAYF32LE, ///< IEEE-754 single precision Y, 32bpp, little-endian + + AV_PIX_FMT_YUVA422P12BE, ///< planar YUV 4:2:2,24bpp, (1 Cr & Cb sample per 2x1 Y samples), 12b alpha, big-endian + AV_PIX_FMT_YUVA422P12LE, ///< planar YUV 4:2:2,24bpp, (1 Cr & Cb sample per 2x1 Y samples), 12b alpha, little-endian + AV_PIX_FMT_YUVA444P12BE, ///< planar YUV 4:4:4,36bpp, (1 Cr & Cb sample per 1x1 Y samples), 12b alpha, big-endian + AV_PIX_FMT_YUVA444P12LE, ///< planar YUV 4:4:4,36bpp, (1 Cr & Cb sample per 1x1 Y samples), 12b alpha, little-endian + + AV_PIX_FMT_NV24, ///< planar YUV 4:4:4, 24bpp, 1 plane for Y and 1 plane for the UV components, which are interleaved (first byte U and the following byte V) + AV_PIX_FMT_NV42, ///< as above, but U and V bytes are swapped + + /** + * Vulkan hardware images. + * + * data[0] points to an AVVkFrame + */ + AV_PIX_FMT_VULKAN, + + AV_PIX_FMT_Y210BE, ///< packed YUV 4:2:2 like YUYV422, 20bpp, data in the high bits, big-endian + AV_PIX_FMT_Y210LE, ///< packed YUV 4:2:2 like YUYV422, 20bpp, data in the high bits, little-endian + + AV_PIX_FMT_X2RGB10LE, ///< packed RGB 10:10:10, 30bpp, (msb)2X 10R 10G 10B(lsb), little-endian, X=unused/undefined + AV_PIX_FMT_X2RGB10BE, ///< packed RGB 10:10:10, 30bpp, (msb)2X 10R 10G 10B(lsb), big-endian, X=unused/undefined + AV_PIX_FMT_X2BGR10LE, ///< packed BGR 10:10:10, 30bpp, (msb)2X 10B 10G 10R(lsb), little-endian, X=unused/undefined + AV_PIX_FMT_X2BGR10BE, ///< packed BGR 10:10:10, 30bpp, (msb)2X 10B 10G 10R(lsb), big-endian, X=unused/undefined + + AV_PIX_FMT_P210BE, ///< interleaved chroma YUV 4:2:2, 20bpp, data in the high bits, big-endian + AV_PIX_FMT_P210LE, ///< interleaved chroma YUV 4:2:2, 20bpp, data in the high bits, little-endian + + AV_PIX_FMT_P410BE, ///< interleaved chroma YUV 4:4:4, 30bpp, data in the high bits, big-endian + AV_PIX_FMT_P410LE, ///< interleaved chroma YUV 4:4:4, 30bpp, data in the high bits, little-endian + + AV_PIX_FMT_P216BE, ///< interleaved chroma YUV 4:2:2, 32bpp, big-endian + AV_PIX_FMT_P216LE, ///< interleaved chroma YUV 4:2:2, 32bpp, little-endian + + AV_PIX_FMT_P416BE, ///< interleaved chroma YUV 4:4:4, 48bpp, big-endian + AV_PIX_FMT_P416LE, ///< interleaved chroma YUV 4:4:4, 48bpp, little-endian + + AV_PIX_FMT_VUYA, ///< packed VUYA 4:4:4:4, 32bpp (1 Cr & Cb sample per 1x1 Y & A samples), VUYAVUYA... + + AV_PIX_FMT_RGBAF16BE, ///< IEEE-754 half precision packed RGBA 16:16:16:16, 64bpp, RGBARGBA..., big-endian + AV_PIX_FMT_RGBAF16LE, ///< IEEE-754 half precision packed RGBA 16:16:16:16, 64bpp, RGBARGBA..., little-endian + + AV_PIX_FMT_VUYX, ///< packed VUYX 4:4:4:4, 32bpp, Variant of VUYA where alpha channel is left undefined + + AV_PIX_FMT_P012LE, ///< like NV12, with 12bpp per component, data in the high bits, zeros in the low bits, little-endian + AV_PIX_FMT_P012BE, ///< like NV12, with 12bpp per component, data in the high bits, zeros in the low bits, big-endian + + AV_PIX_FMT_Y212BE, ///< packed YUV 4:2:2 like YUYV422, 24bpp, data in the high bits, zeros in the low bits, big-endian + AV_PIX_FMT_Y212LE, ///< packed YUV 4:2:2 like YUYV422, 24bpp, data in the high bits, zeros in the low bits, little-endian + + AV_PIX_FMT_XV30BE, ///< packed XVYU 4:4:4, 32bpp, (msb)2X 10V 10Y 10U(lsb), big-endian, variant of Y410 where alpha channel is left undefined + AV_PIX_FMT_XV30LE, ///< packed XVYU 4:4:4, 32bpp, (msb)2X 10V 10Y 10U(lsb), little-endian, variant of Y410 where alpha channel is left undefined + + AV_PIX_FMT_XV36BE, ///< packed XVYU 4:4:4, 48bpp, data in the high bits, zeros in the low bits, big-endian, variant of Y412 where alpha channel is left undefined + AV_PIX_FMT_XV36LE, ///< packed XVYU 4:4:4, 48bpp, data in the high bits, zeros in the low bits, little-endian, variant of Y412 where alpha channel is left undefined + + AV_PIX_FMT_RGBF32BE, ///< IEEE-754 single precision packed RGB 32:32:32, 96bpp, RGBRGB..., big-endian + AV_PIX_FMT_RGBF32LE, ///< IEEE-754 single precision packed RGB 32:32:32, 96bpp, RGBRGB..., little-endian + + AV_PIX_FMT_RGBAF32BE, ///< IEEE-754 single precision packed RGBA 32:32:32:32, 128bpp, RGBARGBA..., big-endian + AV_PIX_FMT_RGBAF32LE, ///< IEEE-754 single precision packed RGBA 32:32:32:32, 128bpp, RGBARGBA..., little-endian + + AV_PIX_FMT_P212BE, ///< interleaved chroma YUV 4:2:2, 24bpp, data in the high bits, big-endian + AV_PIX_FMT_P212LE, ///< interleaved chroma YUV 4:2:2, 24bpp, data in the high bits, little-endian + + AV_PIX_FMT_P412BE, ///< interleaved chroma YUV 4:4:4, 36bpp, data in the high bits, big-endian + AV_PIX_FMT_P412LE, ///< interleaved chroma YUV 4:4:4, 36bpp, data in the high bits, little-endian + + AV_PIX_FMT_GBRAP14BE, ///< planar GBR 4:4:4:4 56bpp, big-endian + AV_PIX_FMT_GBRAP14LE, ///< planar GBR 4:4:4:4 56bpp, little-endian + + /** + * Hardware surfaces for Direct3D 12. + * + * data[0] points to an AVD3D12VAFrame + */ + AV_PIX_FMT_D3D12, + + AV_PIX_FMT_AYUV, ///< packed AYUV 4:4:4:4, 32bpp (1 Cr & Cb sample per 1x1 Y & A samples), AYUVAYUV... + + AV_PIX_FMT_UYVA, ///< packed UYVA 4:4:4:4, 32bpp (1 Cr & Cb sample per 1x1 Y & A samples), UYVAUYVA... + + AV_PIX_FMT_VYU444, ///< packed VYU 4:4:4, 24bpp (1 Cr & Cb sample per 1x1 Y), VYUVYU... + + AV_PIX_FMT_V30XBE, ///< packed VYUX 4:4:4 like XV30, 32bpp, (msb)10V 10Y 10U 2X(lsb), big-endian + AV_PIX_FMT_V30XLE, ///< packed VYUX 4:4:4 like XV30, 32bpp, (msb)10V 10Y 10U 2X(lsb), little-endian + + AV_PIX_FMT_RGBF16BE, ///< IEEE-754 half precision packed RGB 16:16:16, 48bpp, RGBRGB..., big-endian + AV_PIX_FMT_RGBF16LE, ///< IEEE-754 half precision packed RGB 16:16:16, 48bpp, RGBRGB..., little-endian + + AV_PIX_FMT_RGBA128BE, ///< packed RGBA 32:32:32:32, 128bpp, RGBARGBA..., big-endian + AV_PIX_FMT_RGBA128LE, ///< packed RGBA 32:32:32:32, 128bpp, RGBARGBA..., little-endian + + AV_PIX_FMT_RGB96BE, ///< packed RGBA 32:32:32, 96bpp, RGBRGB..., big-endian + AV_PIX_FMT_RGB96LE, ///< packed RGBA 32:32:32, 96bpp, RGBRGB..., little-endian + + AV_PIX_FMT_Y216BE, ///< packed YUV 4:2:2 like YUYV422, 32bpp, big-endian + AV_PIX_FMT_Y216LE, ///< packed YUV 4:2:2 like YUYV422, 32bpp, little-endian + + AV_PIX_FMT_XV48BE, ///< packed XVYU 4:4:4, 64bpp, big-endian, variant of Y416 where alpha channel is left undefined + AV_PIX_FMT_XV48LE, ///< packed XVYU 4:4:4, 64bpp, little-endian, variant of Y416 where alpha channel is left undefined + + AV_PIX_FMT_GBRPF16BE, ///< IEEE-754 half precision planer GBR 4:4:4, 48bpp, big-endian + AV_PIX_FMT_GBRPF16LE, ///< IEEE-754 half precision planer GBR 4:4:4, 48bpp, little-endian + AV_PIX_FMT_GBRAPF16BE, ///< IEEE-754 half precision planar GBRA 4:4:4:4, 64bpp, big-endian + AV_PIX_FMT_GBRAPF16LE, ///< IEEE-754 half precision planar GBRA 4:4:4:4, 64bpp, little-endian + + AV_PIX_FMT_GRAYF16BE, ///< IEEE-754 half precision Y, 16bpp, big-endian + AV_PIX_FMT_GRAYF16LE, ///< IEEE-754 half precision Y, 16bpp, little-endian + + /** + * HW acceleration through AMF. data[0] contain AMFSurface pointer + */ + AV_PIX_FMT_AMF_SURFACE, + + AV_PIX_FMT_GRAY32BE, ///< Y , 32bpp, big-endian + AV_PIX_FMT_GRAY32LE, ///< Y , 32bpp, little-endian + + AV_PIX_FMT_YAF32BE, ///< IEEE-754 single precision packed YA, 32 bits gray, 32 bits alpha, 64bpp, big-endian + AV_PIX_FMT_YAF32LE, ///< IEEE-754 single precision packed YA, 32 bits gray, 32 bits alpha, 64bpp, little-endian + + AV_PIX_FMT_YAF16BE, ///< IEEE-754 half precision packed YA, 16 bits gray, 16 bits alpha, 32bpp, big-endian + AV_PIX_FMT_YAF16LE, ///< IEEE-754 half precision packed YA, 16 bits gray, 16 bits alpha, 32bpp, little-endian + + AV_PIX_FMT_GBRAP32BE, ///< planar GBRA 4:4:4:4 128bpp, big-endian + AV_PIX_FMT_GBRAP32LE, ///< planar GBRA 4:4:4:4 128bpp, little-endian + + AV_PIX_FMT_YUV444P10MSBBE, ///< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), lowest bits zero, big-endian + AV_PIX_FMT_YUV444P10MSBLE, ///< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), lowest bits zero, little-endian + AV_PIX_FMT_YUV444P12MSBBE, ///< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), lowest bits zero, big-endian + AV_PIX_FMT_YUV444P12MSBLE, ///< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), lowest bits zero, little-endian + AV_PIX_FMT_GBRP10MSBBE, ///< planar GBR 4:4:4 30bpp, lowest bits zero, big-endian + AV_PIX_FMT_GBRP10MSBLE, ///< planar GBR 4:4:4 30bpp, lowest bits zero, little-endian + AV_PIX_FMT_GBRP12MSBBE, ///< planar GBR 4:4:4 36bpp, lowest bits zero, big-endian + AV_PIX_FMT_GBRP12MSBLE, ///< planar GBR 4:4:4 36bpp, lowest bits zero, little-endian + + AV_PIX_FMT_OHCODEC, /// hardware decoding through openharmony + + AV_PIX_FMT_NB ///< number of pixel formats, DO NOT USE THIS if you want to link with shared libav* because the number of formats might differ between versions +}; + +#if AV_HAVE_BIGENDIAN +# define AV_PIX_FMT_NE(be, le) AV_PIX_FMT_##be +#else +# define AV_PIX_FMT_NE(be, le) AV_PIX_FMT_##le +#endif + +#define AV_PIX_FMT_RGB32 AV_PIX_FMT_NE(ARGB, BGRA) +#define AV_PIX_FMT_RGB32_1 AV_PIX_FMT_NE(RGBA, ABGR) +#define AV_PIX_FMT_BGR32 AV_PIX_FMT_NE(ABGR, RGBA) +#define AV_PIX_FMT_BGR32_1 AV_PIX_FMT_NE(BGRA, ARGB) +#define AV_PIX_FMT_0RGB32 AV_PIX_FMT_NE(0RGB, BGR0) +#define AV_PIX_FMT_0BGR32 AV_PIX_FMT_NE(0BGR, RGB0) + +#define AV_PIX_FMT_GRAY9 AV_PIX_FMT_NE(GRAY9BE, GRAY9LE) +#define AV_PIX_FMT_GRAY10 AV_PIX_FMT_NE(GRAY10BE, GRAY10LE) +#define AV_PIX_FMT_GRAY12 AV_PIX_FMT_NE(GRAY12BE, GRAY12LE) +#define AV_PIX_FMT_GRAY14 AV_PIX_FMT_NE(GRAY14BE, GRAY14LE) +#define AV_PIX_FMT_GRAY16 AV_PIX_FMT_NE(GRAY16BE, GRAY16LE) +#define AV_PIX_FMT_GRAY32 AV_PIX_FMT_NE(GRAY32BE, GRAY32LE) +#define AV_PIX_FMT_YA16 AV_PIX_FMT_NE(YA16BE, YA16LE) +#define AV_PIX_FMT_RGB48 AV_PIX_FMT_NE(RGB48BE, RGB48LE) +#define AV_PIX_FMT_RGB565 AV_PIX_FMT_NE(RGB565BE, RGB565LE) +#define AV_PIX_FMT_RGB555 AV_PIX_FMT_NE(RGB555BE, RGB555LE) +#define AV_PIX_FMT_RGB444 AV_PIX_FMT_NE(RGB444BE, RGB444LE) +#define AV_PIX_FMT_RGBA64 AV_PIX_FMT_NE(RGBA64BE, RGBA64LE) +#define AV_PIX_FMT_BGR48 AV_PIX_FMT_NE(BGR48BE, BGR48LE) +#define AV_PIX_FMT_BGR565 AV_PIX_FMT_NE(BGR565BE, BGR565LE) +#define AV_PIX_FMT_BGR555 AV_PIX_FMT_NE(BGR555BE, BGR555LE) +#define AV_PIX_FMT_BGR444 AV_PIX_FMT_NE(BGR444BE, BGR444LE) +#define AV_PIX_FMT_BGRA64 AV_PIX_FMT_NE(BGRA64BE, BGRA64LE) + +#define AV_PIX_FMT_YUV420P9 AV_PIX_FMT_NE(YUV420P9BE , YUV420P9LE) +#define AV_PIX_FMT_YUV422P9 AV_PIX_FMT_NE(YUV422P9BE , YUV422P9LE) +#define AV_PIX_FMT_YUV444P9 AV_PIX_FMT_NE(YUV444P9BE , YUV444P9LE) +#define AV_PIX_FMT_YUV420P10 AV_PIX_FMT_NE(YUV420P10BE, YUV420P10LE) +#define AV_PIX_FMT_YUV422P10 AV_PIX_FMT_NE(YUV422P10BE, YUV422P10LE) +#define AV_PIX_FMT_YUV440P10 AV_PIX_FMT_NE(YUV440P10BE, YUV440P10LE) +#define AV_PIX_FMT_YUV444P10 AV_PIX_FMT_NE(YUV444P10BE, YUV444P10LE) +#define AV_PIX_FMT_YUV420P12 AV_PIX_FMT_NE(YUV420P12BE, YUV420P12LE) +#define AV_PIX_FMT_YUV422P12 AV_PIX_FMT_NE(YUV422P12BE, YUV422P12LE) +#define AV_PIX_FMT_YUV440P12 AV_PIX_FMT_NE(YUV440P12BE, YUV440P12LE) +#define AV_PIX_FMT_YUV444P12 AV_PIX_FMT_NE(YUV444P12BE, YUV444P12LE) +#define AV_PIX_FMT_YUV420P14 AV_PIX_FMT_NE(YUV420P14BE, YUV420P14LE) +#define AV_PIX_FMT_YUV422P14 AV_PIX_FMT_NE(YUV422P14BE, YUV422P14LE) +#define AV_PIX_FMT_YUV444P14 AV_PIX_FMT_NE(YUV444P14BE, YUV444P14LE) +#define AV_PIX_FMT_YUV420P16 AV_PIX_FMT_NE(YUV420P16BE, YUV420P16LE) +#define AV_PIX_FMT_YUV422P16 AV_PIX_FMT_NE(YUV422P16BE, YUV422P16LE) +#define AV_PIX_FMT_YUV444P16 AV_PIX_FMT_NE(YUV444P16BE, YUV444P16LE) + +#define AV_PIX_FMT_YUV444P10MSB AV_PIX_FMT_NE(YUV444P10MSBBE, YUV444P10MSBLE) +#define AV_PIX_FMT_YUV444P12MSB AV_PIX_FMT_NE(YUV444P12MSBBE, YUV444P12MSBLE) + +#define AV_PIX_FMT_GBRP9 AV_PIX_FMT_NE(GBRP9BE , GBRP9LE) +#define AV_PIX_FMT_GBRP10 AV_PIX_FMT_NE(GBRP10BE, GBRP10LE) +#define AV_PIX_FMT_GBRP12 AV_PIX_FMT_NE(GBRP12BE, GBRP12LE) +#define AV_PIX_FMT_GBRP14 AV_PIX_FMT_NE(GBRP14BE, GBRP14LE) +#define AV_PIX_FMT_GBRP16 AV_PIX_FMT_NE(GBRP16BE, GBRP16LE) +#define AV_PIX_FMT_GBRAP10 AV_PIX_FMT_NE(GBRAP10BE, GBRAP10LE) +#define AV_PIX_FMT_GBRAP12 AV_PIX_FMT_NE(GBRAP12BE, GBRAP12LE) +#define AV_PIX_FMT_GBRAP14 AV_PIX_FMT_NE(GBRAP14BE, GBRAP14LE) +#define AV_PIX_FMT_GBRAP16 AV_PIX_FMT_NE(GBRAP16BE, GBRAP16LE) +#define AV_PIX_FMT_GBRAP32 AV_PIX_FMT_NE(GBRAP32BE, GBRAP32LE) + +#define AV_PIX_FMT_GBRP10MSB AV_PIX_FMT_NE(GBRP10MSBBE, GBRP10MSBLE) +#define AV_PIX_FMT_GBRP12MSB AV_PIX_FMT_NE(GBRP12MSBBE, GBRP12MSBLE) + +#define AV_PIX_FMT_BAYER_BGGR16 AV_PIX_FMT_NE(BAYER_BGGR16BE, BAYER_BGGR16LE) +#define AV_PIX_FMT_BAYER_RGGB16 AV_PIX_FMT_NE(BAYER_RGGB16BE, BAYER_RGGB16LE) +#define AV_PIX_FMT_BAYER_GBRG16 AV_PIX_FMT_NE(BAYER_GBRG16BE, BAYER_GBRG16LE) +#define AV_PIX_FMT_BAYER_GRBG16 AV_PIX_FMT_NE(BAYER_GRBG16BE, BAYER_GRBG16LE) + +#define AV_PIX_FMT_GBRPF16 AV_PIX_FMT_NE(GBRPF16BE, GBRPF16LE) +#define AV_PIX_FMT_GBRAPF16 AV_PIX_FMT_NE(GBRAPF16BE, GBRAPF16LE) +#define AV_PIX_FMT_GBRPF32 AV_PIX_FMT_NE(GBRPF32BE, GBRPF32LE) +#define AV_PIX_FMT_GBRAPF32 AV_PIX_FMT_NE(GBRAPF32BE, GBRAPF32LE) + +#define AV_PIX_FMT_GRAYF16 AV_PIX_FMT_NE(GRAYF16BE, GRAYF16LE) +#define AV_PIX_FMT_GRAYF32 AV_PIX_FMT_NE(GRAYF32BE, GRAYF32LE) + +#define AV_PIX_FMT_YAF16 AV_PIX_FMT_NE(YAF16BE, YAF16LE) +#define AV_PIX_FMT_YAF32 AV_PIX_FMT_NE(YAF32BE, YAF32LE) + +#define AV_PIX_FMT_YUVA420P9 AV_PIX_FMT_NE(YUVA420P9BE , YUVA420P9LE) +#define AV_PIX_FMT_YUVA422P9 AV_PIX_FMT_NE(YUVA422P9BE , YUVA422P9LE) +#define AV_PIX_FMT_YUVA444P9 AV_PIX_FMT_NE(YUVA444P9BE , YUVA444P9LE) +#define AV_PIX_FMT_YUVA420P10 AV_PIX_FMT_NE(YUVA420P10BE, YUVA420P10LE) +#define AV_PIX_FMT_YUVA422P10 AV_PIX_FMT_NE(YUVA422P10BE, YUVA422P10LE) +#define AV_PIX_FMT_YUVA444P10 AV_PIX_FMT_NE(YUVA444P10BE, YUVA444P10LE) +#define AV_PIX_FMT_YUVA422P12 AV_PIX_FMT_NE(YUVA422P12BE, YUVA422P12LE) +#define AV_PIX_FMT_YUVA444P12 AV_PIX_FMT_NE(YUVA444P12BE, YUVA444P12LE) +#define AV_PIX_FMT_YUVA420P16 AV_PIX_FMT_NE(YUVA420P16BE, YUVA420P16LE) +#define AV_PIX_FMT_YUVA422P16 AV_PIX_FMT_NE(YUVA422P16BE, YUVA422P16LE) +#define AV_PIX_FMT_YUVA444P16 AV_PIX_FMT_NE(YUVA444P16BE, YUVA444P16LE) + +#define AV_PIX_FMT_XYZ12 AV_PIX_FMT_NE(XYZ12BE, XYZ12LE) +#define AV_PIX_FMT_NV20 AV_PIX_FMT_NE(NV20BE, NV20LE) +#define AV_PIX_FMT_AYUV64 AV_PIX_FMT_NE(AYUV64BE, AYUV64LE) +#define AV_PIX_FMT_P010 AV_PIX_FMT_NE(P010BE, P010LE) +#define AV_PIX_FMT_P012 AV_PIX_FMT_NE(P012BE, P012LE) +#define AV_PIX_FMT_P016 AV_PIX_FMT_NE(P016BE, P016LE) + +#define AV_PIX_FMT_Y210 AV_PIX_FMT_NE(Y210BE, Y210LE) +#define AV_PIX_FMT_Y212 AV_PIX_FMT_NE(Y212BE, Y212LE) +#define AV_PIX_FMT_Y216 AV_PIX_FMT_NE(Y216BE, Y216LE) +#define AV_PIX_FMT_XV30 AV_PIX_FMT_NE(XV30BE, XV30LE) +#define AV_PIX_FMT_XV36 AV_PIX_FMT_NE(XV36BE, XV36LE) +#define AV_PIX_FMT_XV48 AV_PIX_FMT_NE(XV48BE, XV48LE) +#define AV_PIX_FMT_V30X AV_PIX_FMT_NE(V30XBE, V30XLE) +#define AV_PIX_FMT_X2RGB10 AV_PIX_FMT_NE(X2RGB10BE, X2RGB10LE) +#define AV_PIX_FMT_X2BGR10 AV_PIX_FMT_NE(X2BGR10BE, X2BGR10LE) + +#define AV_PIX_FMT_P210 AV_PIX_FMT_NE(P210BE, P210LE) +#define AV_PIX_FMT_P410 AV_PIX_FMT_NE(P410BE, P410LE) +#define AV_PIX_FMT_P212 AV_PIX_FMT_NE(P212BE, P212LE) +#define AV_PIX_FMT_P412 AV_PIX_FMT_NE(P412BE, P412LE) +#define AV_PIX_FMT_P216 AV_PIX_FMT_NE(P216BE, P216LE) +#define AV_PIX_FMT_P416 AV_PIX_FMT_NE(P416BE, P416LE) + +#define AV_PIX_FMT_RGBF16 AV_PIX_FMT_NE(RGBF16BE, RGBF16LE) +#define AV_PIX_FMT_RGBAF16 AV_PIX_FMT_NE(RGBAF16BE, RGBAF16LE) + +#define AV_PIX_FMT_RGBF32 AV_PIX_FMT_NE(RGBF32BE, RGBF32LE) +#define AV_PIX_FMT_RGBAF32 AV_PIX_FMT_NE(RGBAF32BE, RGBAF32LE) + +#define AV_PIX_FMT_RGB96 AV_PIX_FMT_NE(RGB96BE, RGB96LE) +#define AV_PIX_FMT_RGBA128 AV_PIX_FMT_NE(RGBA128BE, RGBA128LE) + +/** + * Chromaticity coordinates of the source primaries. + * These values match the ones defined by ISO/IEC 23091-2_2019 subclause 8.1 and ITU-T H.273. + */ +enum AVColorPrimaries { + AVCOL_PRI_RESERVED0 = 0, + AVCOL_PRI_BT709 = 1, ///< also ITU-R BT1361 / IEC 61966-2-4 / SMPTE RP 177 Annex B + AVCOL_PRI_UNSPECIFIED = 2, + AVCOL_PRI_RESERVED = 3, + AVCOL_PRI_BT470M = 4, ///< also FCC Title 47 Code of Federal Regulations 73.682 (a)(20) + + AVCOL_PRI_BT470BG = 5, ///< also ITU-R BT601-6 625 / ITU-R BT1358 625 / ITU-R BT1700 625 PAL & SECAM + AVCOL_PRI_SMPTE170M = 6, ///< also ITU-R BT601-6 525 / ITU-R BT1358 525 / ITU-R BT1700 NTSC + AVCOL_PRI_SMPTE240M = 7, ///< identical to above, also called "SMPTE C" even though it uses D65 + AVCOL_PRI_FILM = 8, ///< colour filters using Illuminant C + AVCOL_PRI_BT2020 = 9, ///< ITU-R BT2020 + AVCOL_PRI_SMPTE428 = 10, ///< SMPTE ST 428-1 (CIE 1931 XYZ) + AVCOL_PRI_SMPTEST428_1 = AVCOL_PRI_SMPTE428, + AVCOL_PRI_SMPTE431 = 11, ///< SMPTE ST 431-2 (2011) / DCI P3 + AVCOL_PRI_SMPTE432 = 12, ///< SMPTE ST 432-1 (2010) / P3 D65 / Display P3 + AVCOL_PRI_EBU3213 = 22, ///< EBU Tech. 3213-E (nothing there) / one of JEDEC P22 group phosphors + AVCOL_PRI_JEDEC_P22 = AVCOL_PRI_EBU3213, + AVCOL_PRI_NB, ///< Not part of ABI + + /* The following entries are not part of H.273, but custom extensions */ + AVCOL_PRI_EXT_BASE = 256, + AVCOL_PRI_V_GAMUT = AVCOL_PRI_EXT_BASE, + AVCOL_PRI_EXT_NB ///< Not part of ABI +}; + +/** + * Color Transfer Characteristic. + * These values match the ones defined by ISO/IEC 23091-2_2019 subclause 8.2. + */ +enum AVColorTransferCharacteristic { + AVCOL_TRC_RESERVED0 = 0, + AVCOL_TRC_BT709 = 1, ///< also ITU-R BT1361 + AVCOL_TRC_UNSPECIFIED = 2, + AVCOL_TRC_RESERVED = 3, + AVCOL_TRC_GAMMA22 = 4, ///< also ITU-R BT470M / ITU-R BT1700 625 PAL & SECAM + AVCOL_TRC_GAMMA28 = 5, ///< also ITU-R BT470BG + AVCOL_TRC_SMPTE170M = 6, ///< also ITU-R BT601-6 525 or 625 / ITU-R BT1358 525 or 625 / ITU-R BT1700 NTSC + AVCOL_TRC_SMPTE240M = 7, + AVCOL_TRC_LINEAR = 8, ///< "Linear transfer characteristics" + AVCOL_TRC_LOG = 9, ///< "Logarithmic transfer characteristic (100:1 range)" + AVCOL_TRC_LOG_SQRT = 10, ///< "Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range)" + AVCOL_TRC_IEC61966_2_4 = 11, ///< IEC 61966-2-4 + AVCOL_TRC_BT1361_ECG = 12, ///< ITU-R BT1361 Extended Colour Gamut + AVCOL_TRC_IEC61966_2_1 = 13, ///< IEC 61966-2-1 (sRGB or sYCC) + AVCOL_TRC_BT2020_10 = 14, ///< ITU-R BT2020 for 10-bit system + AVCOL_TRC_BT2020_12 = 15, ///< ITU-R BT2020 for 12-bit system + AVCOL_TRC_SMPTE2084 = 16, ///< SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems + AVCOL_TRC_SMPTEST2084 = AVCOL_TRC_SMPTE2084, + AVCOL_TRC_SMPTE428 = 17, ///< SMPTE ST 428-1 + AVCOL_TRC_SMPTEST428_1 = AVCOL_TRC_SMPTE428, + AVCOL_TRC_ARIB_STD_B67 = 18, ///< ARIB STD-B67, known as "Hybrid log-gamma" + AVCOL_TRC_NB, ///< Not part of ABI + + /* The following entries are not part of H.273, but custom extensions */ + AVCOL_TRC_EXT_BASE = 256, + AVCOL_TRC_V_LOG = AVCOL_TRC_EXT_BASE, + AVCOL_TRC_EXT_NB ///< Not part of ABI +}; + +/** + * YUV colorspace type. + * These values match the ones defined by ISO/IEC 23091-2_2019 subclause 8.3. + */ +enum AVColorSpace { + AVCOL_SPC_RGB = 0, ///< order of coefficients is actually GBR, also IEC 61966-2-1 (sRGB), YZX and ST 428-1 + AVCOL_SPC_BT709 = 1, ///< also ITU-R BT1361 / IEC 61966-2-4 xvYCC709 / derived in SMPTE RP 177 Annex B + AVCOL_SPC_UNSPECIFIED = 2, + AVCOL_SPC_RESERVED = 3, ///< reserved for future use by ITU-T and ISO/IEC just like 15-255 are + AVCOL_SPC_FCC = 4, ///< FCC Title 47 Code of Federal Regulations 73.682 (a)(20) + AVCOL_SPC_BT470BG = 5, ///< also ITU-R BT601-6 625 / ITU-R BT1358 625 / ITU-R BT1700 625 PAL & SECAM / IEC 61966-2-4 xvYCC601 + AVCOL_SPC_SMPTE170M = 6, ///< also ITU-R BT601-6 525 / ITU-R BT1358 525 / ITU-R BT1700 NTSC / functionally identical to above + AVCOL_SPC_SMPTE240M = 7, ///< derived from 170M primaries and D65 white point, 170M is derived from BT470 System M's primaries + AVCOL_SPC_YCGCO = 8, ///< used by Dirac / VC-2 and H.264 FRext, see ITU-T SG16 + AVCOL_SPC_YCOCG = AVCOL_SPC_YCGCO, + AVCOL_SPC_BT2020_NCL = 9, ///< ITU-R BT2020 non-constant luminance system + AVCOL_SPC_BT2020_CL = 10, ///< ITU-R BT2020 constant luminance system + AVCOL_SPC_SMPTE2085 = 11, ///< SMPTE 2085, Y'D'zD'x + AVCOL_SPC_CHROMA_DERIVED_NCL = 12, ///< Chromaticity-derived non-constant luminance system + AVCOL_SPC_CHROMA_DERIVED_CL = 13, ///< Chromaticity-derived constant luminance system + AVCOL_SPC_ICTCP = 14, ///< ITU-R BT.2100-0, ICtCp + AVCOL_SPC_IPT_C2 = 15, ///< SMPTE ST 2128, IPT-C2 + AVCOL_SPC_YCGCO_RE = 16, ///< YCgCo-R, even addition of bits + AVCOL_SPC_YCGCO_RO = 17, ///< YCgCo-R, odd addition of bits + AVCOL_SPC_NB ///< Not part of ABI +}; + +/** + * Visual content value range. + * + * These values are based on definitions that can be found in multiple + * specifications, such as ITU-T BT.709 (3.4 - Quantization of RGB, luminance + * and colour-difference signals), ITU-T BT.2020 (Table 5 - Digital + * Representation) as well as ITU-T BT.2100 (Table 9 - Digital 10- and 12-bit + * integer representation). At the time of writing, the BT.2100 one is + * recommended, as it also defines the full range representation. + * + * Common definitions: + * - For RGB and luma planes such as Y in YCbCr and I in ICtCp, + * 'E' is the original value in range of 0.0 to 1.0. + * - For chroma planes such as Cb,Cr and Ct,Cp, 'E' is the original + * value in range of -0.5 to 0.5. + * - 'n' is the output bit depth. + * - For additional definitions such as rounding and clipping to valid n + * bit unsigned integer range, please refer to BT.2100 (Table 9). + */ +enum AVColorRange { + AVCOL_RANGE_UNSPECIFIED = 0, + + /** + * Narrow or limited range content. + * + * - For luma planes: + * + * (219 * E + 16) * 2^(n-8) + * + * F.ex. the range of 16-235 for 8 bits + * + * - For chroma planes: + * + * (224 * E + 128) * 2^(n-8) + * + * F.ex. the range of 16-240 for 8 bits + */ + AVCOL_RANGE_MPEG = 1, + + /** + * Full range content. + * + * - For RGB and luma planes: + * + * (2^n - 1) * E + * + * F.ex. the range of 0-255 for 8 bits + * + * - For chroma planes: + * + * (2^n - 1) * E + 2^(n - 1) + * + * F.ex. the range of 1-255 for 8 bits + */ + AVCOL_RANGE_JPEG = 2, + AVCOL_RANGE_NB ///< Not part of ABI +}; + +/** + * Location of chroma samples. + * + * Illustration showing the location of the first (top left) chroma sample of the + * image, the left shows only luma, the right + * shows the location of the chroma sample, the 2 could be imagined to overlay + * each other but are drawn separately due to limitations of ASCII + * + * 1st 2nd 1st 2nd horizontal luma sample positions + * v v v v + * ______ ______ + *1st luma line > |X X ... |3 4 X ... X are luma samples, + * | |1 2 1-6 are possible chroma positions + *2nd luma line > |X X ... |5 6 X ... 0 is undefined/unknown position + */ +enum AVChromaLocation { + AVCHROMA_LOC_UNSPECIFIED = 0, + AVCHROMA_LOC_LEFT = 1, ///< MPEG-2/4 4:2:0, H.264 default for 4:2:0 + AVCHROMA_LOC_CENTER = 2, ///< MPEG-1 4:2:0, JPEG 4:2:0, H.263 4:2:0 + AVCHROMA_LOC_TOPLEFT = 3, ///< ITU-R 601, SMPTE 274M 296M S314M(DV 4:1:1), mpeg2 4:2:2 + AVCHROMA_LOC_TOP = 4, + AVCHROMA_LOC_BOTTOMLEFT = 5, + AVCHROMA_LOC_BOTTOM = 6, + AVCHROMA_LOC_NB ///< Not part of ABI +}; + +/** + * Correlation between the alpha channel and color values. + */ +enum AVAlphaMode { + AVALPHA_MODE_UNSPECIFIED = 0, ///< Unknown alpha handling, or no alpha channel + AVALPHA_MODE_PREMULTIPLIED = 1, ///< Alpha channel is multiplied into color values + AVALPHA_MODE_STRAIGHT = 2, ///< Alpha channel is independent of color values + AVALPHA_MODE_NB ///< Not part of ABI +}; + +#endif /* AVUTIL_PIXFMT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/random_seed.h b/ffmpeg-n8.1/include/libavutil/random_seed.h new file mode 100644 index 00000000..8a47be96 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/random_seed.h @@ -0,0 +1,57 @@ +/* + * Copyright (c) 2009 Baptiste Coudurier + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_RANDOM_SEED_H +#define AVUTIL_RANDOM_SEED_H + +#include +#include +/** + * @addtogroup lavu_crypto + * @{ + */ + +/** + * Get a seed to use in conjunction with random functions. + * This function tries to provide a good seed at a best effort bases. + * Its possible to call this function multiple times if more bits are needed. + * It can be quite slow, which is why it should only be used as seed for a faster + * PRNG. The quality of the seed depends on the platform. + */ +uint32_t av_get_random_seed(void); + +/** + * Generate cryptographically secure random data, i.e. suitable for use as + * encryption keys and similar. + * + * @param buf buffer into which the random data will be written + * @param len size of buf in bytes + * + * @retval 0 success, len bytes of random data was written + * into buf + * @retval "a negative AVERROR code" random data could not be generated + */ +int av_random_bytes(uint8_t *buf, size_t len); + +/** + * @} + */ + +#endif /* AVUTIL_RANDOM_SEED_H */ diff --git a/ffmpeg-n8.1/include/libavutil/rational.h b/ffmpeg-n8.1/include/libavutil/rational.h new file mode 100644 index 00000000..30ac2ace --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/rational.h @@ -0,0 +1,225 @@ +/* + * rational numbers + * Copyright (c) 2003 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_math_rational + * Utilities for rational number calculation. + * @author Michael Niedermayer + */ + +#ifndef AVUTIL_RATIONAL_H +#define AVUTIL_RATIONAL_H + +#include +#include +#include "attributes.h" + +/** + * @defgroup lavu_math_rational AVRational + * @ingroup lavu_math + * Rational number calculation. + * + * While rational numbers can be expressed as floating-point numbers, the + * conversion process is a lossy one, so are floating-point operations. On the + * other hand, the nature of FFmpeg demands highly accurate calculation of + * timestamps. This set of rational number utilities serves as a generic + * interface for manipulating rational numbers as pairs of numerators and + * denominators. + * + * Many of the functions that operate on AVRational's have the suffix `_q`, in + * reference to the mathematical symbol "ℚ" (Q) which denotes the set of all + * rational numbers. + * + * @{ + */ + +/** + * Rational number (pair of numerator and denominator). + */ +typedef struct AVRational{ + int num; ///< Numerator + int den; ///< Denominator +} AVRational; + +/** + * Create an AVRational. + * + * Useful for compilers that do not support compound literals. + * + * @note The return value is not reduced. + * @see av_reduce() + */ +static inline AVRational av_make_q(int num, int den) +{ + AVRational r = { num, den }; + return r; +} + +/** + * Compare two rationals. + * + * @param a First rational + * @param b Second rational + * + * @return One of the following values: + * - 0 if `a == b` + * - 1 if `a > b` + * - -1 if `a < b` + * - `INT_MIN` if one of the values is of the form `0 / 0` + */ +static inline int av_cmp_q(AVRational a, AVRational b){ + const int64_t tmp= a.num * (int64_t)b.den - b.num * (int64_t)a.den; + + if(tmp) return (int)((tmp ^ a.den ^ b.den)>>63)|1; + else if(b.den && a.den) return 0; + else if(a.num && b.num) return (a.num>>31) - (b.num>>31); + else return INT_MIN; +} + +/** + * Convert an AVRational to a `double`. + * @param a AVRational to convert + * @return `a` in floating-point form + * @see av_d2q() + */ +static inline double av_q2d(AVRational a){ + return a.num / (double) a.den; +} + +/** + * Reduce a fraction. + * + * This is useful for framerate calculations. + * + * @param[out] dst_num Destination numerator + * @param[out] dst_den Destination denominator + * @param[in] num Source numerator + * @param[in] den Source denominator + * @param[in] max Maximum allowed values for `dst_num` & `dst_den` + * @return 1 if the operation is exact, 0 otherwise + */ +int av_reduce(int *dst_num, int *dst_den, int64_t num, int64_t den, int64_t max); + +/** + * Multiply two rationals. + * @param b First rational + * @param c Second rational + * @return b*c + */ +AVRational av_mul_q(AVRational b, AVRational c) av_const; + +/** + * Divide one rational by another. + * @param b First rational + * @param c Second rational + * @return b/c + */ +AVRational av_div_q(AVRational b, AVRational c) av_const; + +/** + * Add two rationals. + * @param b First rational + * @param c Second rational + * @return b+c + */ +AVRational av_add_q(AVRational b, AVRational c) av_const; + +/** + * Subtract one rational from another. + * @param b First rational + * @param c Second rational + * @return b-c + */ +AVRational av_sub_q(AVRational b, AVRational c) av_const; + +/** + * Invert a rational. + * @param q value + * @return 1 / q + */ +static av_always_inline AVRational av_inv_q(AVRational q) +{ + AVRational r = { q.den, q.num }; + return r; +} + +/** + * Convert a double precision floating point number to a rational. + * + * In case of infinity, the returned value is expressed as `{1, 0}` or + * `{-1, 0}` depending on the sign. + * + * In general rational numbers with |num| <= 1<<26 && |den| <= 1<<26 + * can be recovered exactly from their double representation. + * (no exceptions were found within 1B random ones) + * + * @param d `double` to convert + * @param max Maximum allowed numerator and denominator + * @return `d` in AVRational form + * @see av_q2d() + */ +AVRational av_d2q(double d, int max) av_const; + +/** + * Find which of the two rationals is closer to another rational. + * + * @param q Rational to be compared against + * @param q1 Rational to be tested + * @param q2 Rational to be tested + * @return One of the following values: + * - 1 if `q1` is nearer to `q` than `q2` + * - -1 if `q2` is nearer to `q` than `q1` + * - 0 if they have the same distance + */ +int av_nearer_q(AVRational q, AVRational q1, AVRational q2); + +/** + * Find the value in a list of rationals nearest a given reference rational. + * + * @param q Reference rational + * @param q_list Array of rationals terminated by `{0, 0}` + * @return Index of the nearest value found in the array + */ +int av_find_nearest_q_idx(AVRational q, const AVRational* q_list); + +/** + * Convert an AVRational to a IEEE 32-bit `float` expressed in fixed-point + * format. + * + * @param q Rational to be converted + * @return Equivalent floating-point value, expressed as an unsigned 32-bit + * integer. + * @note The returned value is platform-indepedant. + */ +uint32_t av_q2intfloat(AVRational q); + +/** + * Return the best rational so that a and b are multiple of it. + * If the resulting denominator is larger than max_den, return def. + */ +AVRational av_gcd_q(AVRational a, AVRational b, int max_den, AVRational def); + +/** + * @} + */ + +#endif /* AVUTIL_RATIONAL_H */ diff --git a/ffmpeg-n8.1/include/libavutil/rc4.h b/ffmpeg-n8.1/include/libavutil/rc4.h new file mode 100644 index 00000000..0c72a88e --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/rc4.h @@ -0,0 +1,69 @@ +/* + * RC4 encryption/decryption/pseudo-random number generator + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_RC4_H +#define AVUTIL_RC4_H + +#include + +/** + * @defgroup lavu_rc4 RC4 + * @ingroup lavu_crypto + * @{ + */ + +typedef struct AVRC4 { + uint8_t state[256]; + int x, y; +} AVRC4; + +/** + * Allocate an AVRC4 context. + */ +AVRC4 *av_rc4_alloc(void); + +/** + * @brief Initializes an AVRC4 context. + * + * @param d pointer to the AVRC4 context + * @param key buffer containing the key + * @param key_bits must be a multiple of 8 + * @param decrypt 0 for encryption, 1 for decryption, currently has no effect + * @return zero on success, negative value otherwise + */ +int av_rc4_init(struct AVRC4 *d, const uint8_t *key, int key_bits, int decrypt); + +/** + * @brief Encrypts / decrypts using the RC4 algorithm. + * + * @param d pointer to the AVRC4 context + * @param count number of bytes + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst, may be NULL + * @param iv not (yet) used for RC4, should be NULL + * @param decrypt 0 for encryption, 1 for decryption, not (yet) used + */ +void av_rc4_crypt(struct AVRC4 *d, uint8_t *dst, const uint8_t *src, int count, uint8_t *iv, int decrypt); + +/** + * @} + */ + +#endif /* AVUTIL_RC4_H */ diff --git a/ffmpeg-n8.1/include/libavutil/refstruct.h b/ffmpeg-n8.1/include/libavutil/refstruct.h new file mode 100644 index 00000000..4e9d78eb --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/refstruct.h @@ -0,0 +1,297 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_REFSTRUCT_H +#define AVUTIL_REFSTRUCT_H + +#include + +/** + * RefStruct is an API for creating reference-counted objects + * with minimal overhead. The API is designed for objects, + * not buffers like the AVBuffer API. The main differences + * to the AVBuffer API are as follows: + * + * - It uses void* instead of uint8_t* as its base type due to + * its focus on objects. + * - There are no equivalents of AVBuffer and AVBufferRef. + * E.g. there is no way to get the usable size of the object: + * The user is supposed to know what is at the other end of + * the pointer. It also avoids one level of indirection. + * - Custom allocators are not supported. This allows to simplify + * the implementation and reduce the amount of allocations. + * - It also has the advantage that the user's free callback need + * only free the resources owned by the object, but not the + * object itself. + * - Because referencing (and replacing) an object managed by the + * RefStruct API does not involve allocations, they can not fail + * and therefore need not be checked. + * + * @note Referencing and unreferencing the buffers is thread-safe and thus + * may be done from multiple threads simultaneously without any need for + * additional locking. + */ + +/** + * This union is used for all opaque parameters in this API to spare the user + * to cast const away in case the opaque to use is const-qualified. + * + * The functions provided by this API with an AVRefStructOpaque come in pairs + * named foo_c and foo. The foo function accepts void* as opaque and is just + * a wrapper around the foo_c function; "_c" means "(potentially) const". + */ +typedef union { + void *nc; + const void *c; +} AVRefStructOpaque; + +/** + * If this flag is set in av_refstruct_alloc_ext_c(), the object will not + * be initially zeroed. + */ +#define AV_REFSTRUCT_FLAG_NO_ZEROING (1 << 0) + +/** + * Allocate a refcounted object of usable size `size` managed via + * the RefStruct API. + * + * By default (in the absence of flags to the contrary), + * the returned object is initially zeroed. + * + * @param size Desired usable size of the returned object. + * @param flags A bitwise combination of AV_REFSTRUCT_FLAG_* flags. + * @param opaque A pointer that will be passed to the free_cb callback. + * @param free_cb A callback for freeing this object's content + * when its reference count reaches zero; + * it must not free the object itself. + * @return A pointer to an object of the desired size or NULL on failure. + */ +void *av_refstruct_alloc_ext_c(size_t size, unsigned flags, AVRefStructOpaque opaque, + void (*free_cb)(AVRefStructOpaque opaque, void *obj)); + +/** + * A wrapper around av_refstruct_alloc_ext_c() for the common case + * of a non-const qualified opaque. + * + * @see av_refstruct_alloc_ext_c() + */ +static inline +void *av_refstruct_alloc_ext(size_t size, unsigned flags, void *opaque, + void (*free_cb)(AVRefStructOpaque opaque, void *obj)) +{ + return av_refstruct_alloc_ext_c(size, flags, (AVRefStructOpaque){.nc = opaque}, + free_cb); +} + +/** + * Equivalent to av_refstruct_alloc_ext(size, 0, NULL, NULL) + */ +static inline +void *av_refstruct_allocz(size_t size) +{ + return av_refstruct_alloc_ext(size, 0, NULL, NULL); +} + +/** + * Decrement the reference count of the underlying object and automatically + * free the object if there are no more references to it. + * + * `*objp == NULL` is legal and a no-op. + * + * @param objp Pointer to a pointer that is either NULL or points to an object + * managed via this API. `*objp` is set to NULL on return. + */ +void av_refstruct_unref(void *objp); + +/** + * Create a new reference to an object managed via this API, + * i.e. increment the reference count of the underlying object + * and return obj. + * @return a pointer equal to obj. + */ +void *av_refstruct_ref(void *obj); + +/** + * Analog of av_refstruct_ref(), but for constant objects. + * @see av_refstruct_ref() + */ +const void *av_refstruct_ref_c(const void *obj); + +/** + * Ensure `*dstp` refers to the same object as src. + * + * If `*dstp` is already equal to src, do nothing. Otherwise unreference `*dstp` + * and replace it with a new reference to src in case `src != NULL` (this + * involves incrementing the reference count of src's underlying object) or + * with NULL otherwise. + * + * @param dstp Pointer to a pointer that is either NULL or points to an object + * managed via this API. + * @param src A pointer to an object managed via this API or NULL. + */ +void av_refstruct_replace(void *dstp, const void *src); + +/** + * Check whether the reference count of an object managed + * via this API is 1. + * + * @param obj A pointer to an object managed via this API. + * @return 1 if the reference count of obj is 1; 0 otherwise. + */ +int av_refstruct_exclusive(const void *obj); + +/** + * AVRefStructPool is an API for a thread-safe pool of objects managed + * via the RefStruct API. + * + * Frequently allocating and freeing large or complicated objects may be slow + * and wasteful. This API is meant to solve this in cases when the caller + * needs a set of interchangeable objects. + * + * At the beginning, the user must call allocate the pool via + * av_refstruct_pool_alloc() or its analogue av_refstruct_pool_alloc_ext(). + * Then whenever an object is needed, call av_refstruct_pool_get() to + * get a new or reused object from the pool. This new object works in all + * aspects the same way as the ones created by av_refstruct_alloc_ext(). + * However, when the last reference to this object is unreferenced, it is + * (optionally) reset and returned to the pool instead of being freed and + * will be reused for subsequent av_refstruct_pool_get() calls. + * + * When the caller is done with the pool and no longer needs to create any new + * objects, av_refstruct_pool_uninit() must be called to mark the pool as + * freeable. Then entries returned to the pool will then be freed. + * Once all the entries are freed, the pool will automatically be freed. + * + * Allocating and releasing objects with this API is thread-safe as long as + * the user-supplied callbacks (if provided) are thread-safe. + */ + +/** + * The buffer pool. This structure is opaque and not meant to be accessed + * directly. It is allocated with the allocators below and freed with + * av_refstruct_pool_uninit(). + */ +typedef struct AVRefStructPool AVRefStructPool; + +/** + * If this flag is not set, every object in the pool will be zeroed before + * the init callback is called or before it is turned over to the user + * for the first time if no init callback has been provided. + */ +#define AV_REFSTRUCT_POOL_FLAG_NO_ZEROING AV_REFSTRUCT_FLAG_NO_ZEROING +/** + * If this flag is set and both init_cb and reset_cb callbacks are provided, + * then reset_cb will be called if init_cb fails. + * The object passed to reset_cb will be in the state left by init_cb. + */ +#define AV_REFSTRUCT_POOL_FLAG_RESET_ON_INIT_ERROR (1 << 16) +/** + * If this flag is set and both init_cb and free_entry_cb callbacks are + * provided, then free_cb will be called if init_cb fails. + * + * It will be called after reset_cb in case reset_cb and the + * AV_REFSTRUCT_POOL_FLAG_RESET_ON_INIT_ERROR flag are also set. + * + * The object passed to free_cb will be in the state left by + * the callbacks applied earlier (init_cb potentially followed by reset_cb). + */ +#define AV_REFSTRUCT_POOL_FLAG_FREE_ON_INIT_ERROR (1 << 17) +/** + * If this flag is set, the entries will be zeroed before + * being returned to the user (after the init or reset callbacks + * have been called (if provided)). Furthermore, to avoid zeroing twice + * it also makes the pool behave as if the AV_REFSTRUCT_POOL_FLAG_NO_ZEROING + * flag had been provided. + */ +#define AV_REFSTRUCT_POOL_FLAG_ZERO_EVERY_TIME (1 << 18) + +/** + * Equivalent to av_refstruct_pool_alloc(size, flags, NULL, NULL, NULL, NULL, NULL) + */ +AVRefStructPool *av_refstruct_pool_alloc(size_t size, unsigned flags); + +/** + * Allocate an AVRefStructPool, potentially using complex callbacks. + * + * @param size size of the entries of the pool + * @param flags a bitwise combination of AV_REFSTRUCT_POOL_FLAG_* flags + * @param opaque A pointer that will be passed to the callbacks below. + * @param init A callback that will be called directly after a new entry + * has been allocated. obj has already been zeroed unless + * the AV_REFSTRUCT_POOL_FLAG_NO_ZEROING flag is in use. + * @param reset A callback that will be called after an entry has been + * returned to the pool and before it is reused. + * @param free_entry A callback that will be called when an entry is freed + * after the pool has been marked as to be uninitialized. + * @param free A callback that will be called when the pool itself is + * freed (after the last entry has been returned and freed). + */ +AVRefStructPool *av_refstruct_pool_alloc_ext_c(size_t size, unsigned flags, + AVRefStructOpaque opaque, + int (*init_cb)(AVRefStructOpaque opaque, void *obj), + void (*reset_cb)(AVRefStructOpaque opaque, void *obj), + void (*free_entry_cb)(AVRefStructOpaque opaque, void *obj), + void (*free_cb)(AVRefStructOpaque opaque)); + +/** + * A wrapper around av_refstruct_pool_alloc_ext_c() for the common case + * of a non-const qualified opaque. + * + * @see av_refstruct_pool_alloc_ext_c() + */ +static inline +AVRefStructPool *av_refstruct_pool_alloc_ext(size_t size, unsigned flags, + void *opaque, + int (*init_cb)(AVRefStructOpaque opaque, void *obj), + void (*reset_cb)(AVRefStructOpaque opaque, void *obj), + void (*free_entry_cb)(AVRefStructOpaque opaque, void *obj), + void (*free_cb)(AVRefStructOpaque opaque)) +{ + return av_refstruct_pool_alloc_ext_c(size, flags, (AVRefStructOpaque){.nc = opaque}, + init_cb, reset_cb, free_entry_cb, free_cb); +} + +/** + * Get an object from the pool, reusing an old one from the pool when + * available. + * + * Every call to this function must happen before av_refstruct_pool_uninit(). + * Otherwise undefined behaviour may occur. + * + * @param pool the pool from which to get the object + * @return a reference to the object on success, NULL on error. + */ +void *av_refstruct_pool_get(AVRefStructPool *pool); + +/** + * Mark the pool as being available for freeing. It will actually be freed + * only once all the allocated buffers associated with the pool are released. + * Thus it is safe to call this function while some of the allocated buffers + * are still in use. + * + * It is illegal to try to get a new entry after this function has been called. + * + * @param poolp pointer to a pointer to either NULL or a pool to be freed. + * `*poolp` will be set to NULL. + */ +static inline void av_refstruct_pool_uninit(AVRefStructPool **poolp) +{ + av_refstruct_unref(poolp); +} + +#endif /* AVUTIL_REFSTRUCT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/replaygain.h b/ffmpeg-n8.1/include/libavutil/replaygain.h new file mode 100644 index 00000000..b49bf1a3 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/replaygain.h @@ -0,0 +1,50 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_REPLAYGAIN_H +#define AVUTIL_REPLAYGAIN_H + +#include + +/** + * ReplayGain information (see + * http://wiki.hydrogenaudio.org/index.php?title=ReplayGain_1.0_specification). + * The size of this struct is a part of the public ABI. + */ +typedef struct AVReplayGain { + /** + * Track replay gain in microbels (divide by 100000 to get the value in dB). + * Should be set to INT32_MIN when unknown. + */ + int32_t track_gain; + /** + * Peak track amplitude, with 100000 representing full scale (but values + * may overflow). 0 when unknown. + */ + uint32_t track_peak; + /** + * Same as track_gain, but for the whole album. + */ + int32_t album_gain; + /** + * Same as track_peak, but for the whole album, + */ + uint32_t album_peak; +} AVReplayGain; + +#endif /* AVUTIL_REPLAYGAIN_H */ diff --git a/ffmpeg-n8.1/include/libavutil/ripemd.h b/ffmpeg-n8.1/include/libavutil/ripemd.h new file mode 100644 index 00000000..9df9f905 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/ripemd.h @@ -0,0 +1,83 @@ +/* + * Copyright (C) 2007 Michael Niedermayer + * Copyright (C) 2013 James Almer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_ripemd + * Public header for RIPEMD hash function implementation. + */ + +#ifndef AVUTIL_RIPEMD_H +#define AVUTIL_RIPEMD_H + +#include +#include + +#include "attributes.h" + +/** + * @defgroup lavu_ripemd RIPEMD + * @ingroup lavu_hash + * RIPEMD hash function implementation. + * + * @{ + */ + +extern const int av_ripemd_size; + +struct AVRIPEMD; + +/** + * Allocate an AVRIPEMD context. + */ +struct AVRIPEMD *av_ripemd_alloc(void); + +/** + * Initialize RIPEMD hashing. + * + * @param context pointer to the function context (of size av_ripemd_size) + * @param bits number of bits in digest (128, 160, 256 or 320 bits) + * @return zero if initialization succeeded, -1 otherwise + */ +int av_ripemd_init(struct AVRIPEMD* context, int bits); + +/** + * Update hash value. + * + * @param context hash function context + * @param data input data to update hash with + * @param len input data length + */ +void av_ripemd_update(struct AVRIPEMD* context, const uint8_t* data, size_t len); + +/** + * Finish hashing and output digest value. + * + * @param context hash function context + * @param digest buffer where output digest value is stored + */ +void av_ripemd_final(struct AVRIPEMD* context, uint8_t *digest); + +/** + * @} + */ + +#endif /* AVUTIL_RIPEMD_H */ diff --git a/ffmpeg-n8.1/include/libavutil/samplefmt.h b/ffmpeg-n8.1/include/libavutil/samplefmt.h new file mode 100644 index 00000000..43a57a42 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/samplefmt.h @@ -0,0 +1,269 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_SAMPLEFMT_H +#define AVUTIL_SAMPLEFMT_H + +#include + +/** + * @addtogroup lavu_audio + * @{ + * + * @defgroup lavu_sampfmts Audio sample formats + * + * Audio sample format enumeration and related convenience functions. + * @{ + */ + +/** + * Audio sample formats + * + * - The data described by the sample format is always in native-endian order. + * Sample values can be expressed by native C types, hence the lack of a signed + * 24-bit sample format even though it is a common raw audio data format. + * + * - The floating-point formats are based on full volume being in the range + * [-1.0, 1.0]. Any values outside this range are beyond full volume level. + * + * - The data layout as used in av_samples_fill_arrays() and elsewhere in FFmpeg + * (such as AVFrame in libavcodec) is as follows: + * + * @par + * For planar sample formats, each audio channel is in a separate data plane, + * and linesize is the buffer size, in bytes, for a single plane. All data + * planes must be the same size. For packed sample formats, only the first data + * plane is used, and samples for each channel are interleaved. In this case, + * linesize is the buffer size, in bytes, for the 1 plane. + * + */ +enum AVSampleFormat { + AV_SAMPLE_FMT_NONE = -1, + AV_SAMPLE_FMT_U8, ///< unsigned 8 bits + AV_SAMPLE_FMT_S16, ///< signed 16 bits + AV_SAMPLE_FMT_S32, ///< signed 32 bits + AV_SAMPLE_FMT_FLT, ///< float + AV_SAMPLE_FMT_DBL, ///< double + + AV_SAMPLE_FMT_U8P, ///< unsigned 8 bits, planar + AV_SAMPLE_FMT_S16P, ///< signed 16 bits, planar + AV_SAMPLE_FMT_S32P, ///< signed 32 bits, planar + AV_SAMPLE_FMT_FLTP, ///< float, planar + AV_SAMPLE_FMT_DBLP, ///< double, planar + AV_SAMPLE_FMT_S64, ///< signed 64 bits + AV_SAMPLE_FMT_S64P, ///< signed 64 bits, planar + + AV_SAMPLE_FMT_NB ///< Number of sample formats. DO NOT USE if linking dynamically +}; + +/** + * Return the name of sample_fmt, or NULL if sample_fmt is not + * recognized. + */ +const char *av_get_sample_fmt_name(enum AVSampleFormat sample_fmt); + +/** + * Return a sample format corresponding to name, or AV_SAMPLE_FMT_NONE + * on error. + */ +enum AVSampleFormat av_get_sample_fmt(const char *name); + +/** + * Return the planar<->packed alternative form of the given sample format, or + * AV_SAMPLE_FMT_NONE on error. If the passed sample_fmt is already in the + * requested planar/packed format, the format returned is the same as the + * input. + */ +enum AVSampleFormat av_get_alt_sample_fmt(enum AVSampleFormat sample_fmt, int planar); + +/** + * Get the packed alternative form of the given sample format. + * + * If the passed sample_fmt is already in packed format, the format returned is + * the same as the input. + * + * @return the packed alternative form of the given sample format or + AV_SAMPLE_FMT_NONE on error. + */ +enum AVSampleFormat av_get_packed_sample_fmt(enum AVSampleFormat sample_fmt); + +/** + * Get the planar alternative form of the given sample format. + * + * If the passed sample_fmt is already in planar format, the format returned is + * the same as the input. + * + * @return the planar alternative form of the given sample format or + AV_SAMPLE_FMT_NONE on error. + */ +enum AVSampleFormat av_get_planar_sample_fmt(enum AVSampleFormat sample_fmt); + +/** + * Generate a string corresponding to the sample format with + * sample_fmt, or a header if sample_fmt is negative. + * + * @param buf the buffer where to write the string + * @param buf_size the size of buf + * @param sample_fmt the number of the sample format to print the + * corresponding info string, or a negative value to print the + * corresponding header. + * @return the pointer to the filled buffer or NULL if sample_fmt is + * unknown or in case of other errors + */ +char *av_get_sample_fmt_string(char *buf, int buf_size, enum AVSampleFormat sample_fmt); + +/** + * Return number of bytes per sample. + * + * @param sample_fmt the sample format + * @return number of bytes per sample or zero if unknown for the given + * sample format + */ +int av_get_bytes_per_sample(enum AVSampleFormat sample_fmt); + +/** + * Check if the sample format is planar. + * + * @param sample_fmt the sample format to inspect + * @return 1 if the sample format is planar, 0 if it is interleaved + */ +int av_sample_fmt_is_planar(enum AVSampleFormat sample_fmt); + +/** + * Get the required buffer size for the given audio parameters. + * + * @param[out] linesize calculated linesize, may be NULL + * @param nb_channels the number of channels + * @param nb_samples the number of samples in a single channel + * @param sample_fmt the sample format + * @param align buffer size alignment (0 = default, 1 = no alignment) + * @return required buffer size, or negative error code on failure + */ +int av_samples_get_buffer_size(int *linesize, int nb_channels, int nb_samples, + enum AVSampleFormat sample_fmt, int align); + +/** + * @} + * + * @defgroup lavu_sampmanip Samples manipulation + * + * Functions that manipulate audio samples + * @{ + */ + +/** + * Fill plane data pointers and linesize for samples with sample + * format sample_fmt. + * + * The audio_data array is filled with the pointers to the samples data planes: + * for planar, set the start point of each channel's data within the buffer, + * for packed, set the start point of the entire buffer only. + * + * The value pointed to by linesize is set to the aligned size of each + * channel's data buffer for planar layout, or to the aligned size of the + * buffer for all channels for packed layout. + * + * The buffer in buf must be big enough to contain all the samples + * (use av_samples_get_buffer_size() to compute its minimum size), + * otherwise the audio_data pointers will point to invalid data. + * + * @see enum AVSampleFormat + * The documentation for AVSampleFormat describes the data layout. + * + * @param[out] audio_data array to be filled with the pointer for each channel + * @param[out] linesize calculated linesize, may be NULL + * @param buf the pointer to a buffer containing the samples + * @param nb_channels the number of channels + * @param nb_samples the number of samples in a single channel + * @param sample_fmt the sample format + * @param align buffer size alignment (0 = default, 1 = no alignment) + * @return minimum size in bytes required for the buffer on success, + * or a negative error code on failure + */ +int av_samples_fill_arrays(uint8_t **audio_data, int *linesize, + const uint8_t *buf, + int nb_channels, int nb_samples, + enum AVSampleFormat sample_fmt, int align); + +/** + * Allocate a samples buffer for nb_samples samples, and fill data pointers and + * linesize accordingly. + * The allocated samples buffer can be freed by using av_freep(&audio_data[0]) + * Allocated data will be initialized to silence. + * + * @see enum AVSampleFormat + * The documentation for AVSampleFormat describes the data layout. + * + * @param[out] audio_data array to be filled with the pointer for each channel + * @param[out] linesize aligned size for audio buffer(s), may be NULL + * @param nb_channels number of audio channels + * @param nb_samples number of samples per channel + * @param sample_fmt the sample format + * @param align buffer size alignment (0 = default, 1 = no alignment) + * @return >=0 on success or a negative error code on failure + * @todo return the size of the allocated buffer in case of success at the next bump + * @see av_samples_fill_arrays() + * @see av_samples_alloc_array_and_samples() + */ +int av_samples_alloc(uint8_t **audio_data, int *linesize, int nb_channels, + int nb_samples, enum AVSampleFormat sample_fmt, int align); + +/** + * Allocate a data pointers array, samples buffer for nb_samples + * samples, and fill data pointers and linesize accordingly. + * + * This is the same as av_samples_alloc(), but also allocates the data + * pointers array. + * + * @see av_samples_alloc() + */ +int av_samples_alloc_array_and_samples(uint8_t ***audio_data, int *linesize, int nb_channels, + int nb_samples, enum AVSampleFormat sample_fmt, int align); + +/** + * Copy samples from src to dst. + * + * @param dst destination array of pointers to data planes + * @param src source array of pointers to data planes + * @param dst_offset offset in samples at which the data will be written to dst + * @param src_offset offset in samples at which the data will be read from src + * @param nb_samples number of samples to be copied + * @param nb_channels number of audio channels + * @param sample_fmt audio sample format + */ +int av_samples_copy(uint8_t * const *dst, uint8_t * const *src, int dst_offset, + int src_offset, int nb_samples, int nb_channels, + enum AVSampleFormat sample_fmt); + +/** + * Fill an audio buffer with silence. + * + * @param audio_data array of pointers to data planes + * @param offset offset in samples at which to start filling + * @param nb_samples number of samples to fill + * @param nb_channels number of audio channels + * @param sample_fmt audio sample format + */ +int av_samples_set_silence(uint8_t * const *audio_data, int offset, int nb_samples, + int nb_channels, enum AVSampleFormat sample_fmt); + +/** + * @} + * @} + */ +#endif /* AVUTIL_SAMPLEFMT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/sha.h b/ffmpeg-n8.1/include/libavutil/sha.h new file mode 100644 index 00000000..2e1220ab --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/sha.h @@ -0,0 +1,90 @@ +/* + * Copyright (C) 2007 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_sha + * Public header for SHA-1 & SHA-256 hash function implementations. + */ + +#ifndef AVUTIL_SHA_H +#define AVUTIL_SHA_H + +#include +#include + +#include "attributes.h" + +/** + * @defgroup lavu_sha SHA + * @ingroup lavu_hash + * SHA-1 and SHA-256 (Secure Hash Algorithm) hash function implementations. + * + * This module supports the following SHA hash functions: + * + * - SHA-1: 160 bits + * - SHA-224: 224 bits, as a variant of SHA-2 + * - SHA-256: 256 bits, as a variant of SHA-2 + * + * @see For SHA-384, SHA-512, and variants thereof, see @ref lavu_sha512. + * + * @{ + */ + +extern const int av_sha_size; + +struct AVSHA; + +/** + * Allocate an AVSHA context. + */ +struct AVSHA *av_sha_alloc(void); + +/** + * Initialize SHA-1 or SHA-2 hashing. + * + * @param context pointer to the function context (of size av_sha_size) + * @param bits number of bits in digest (SHA-1 - 160 bits, SHA-2 224 or 256 bits) + * @return zero if initialization succeeded, -1 otherwise + */ +int av_sha_init(struct AVSHA* context, int bits); + +/** + * Update hash value. + * + * @param ctx hash function context + * @param data input data to update hash with + * @param len input data length + */ +void av_sha_update(struct AVSHA *ctx, const uint8_t *data, size_t len); + +/** + * Finish hashing and output digest value. + * + * @param context hash function context + * @param digest buffer where output digest value is stored + */ +void av_sha_final(struct AVSHA* context, uint8_t *digest); + +/** + * @} + */ + +#endif /* AVUTIL_SHA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/sha512.h b/ffmpeg-n8.1/include/libavutil/sha512.h new file mode 100644 index 00000000..a4a3f23d --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/sha512.h @@ -0,0 +1,92 @@ +/* + * Copyright (C) 2007 Michael Niedermayer + * Copyright (C) 2013 James Almer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_sha512 + * Public header for SHA-512 implementation. + */ + +#ifndef AVUTIL_SHA512_H +#define AVUTIL_SHA512_H + +#include +#include + +#include "attributes.h" + +/** + * @defgroup lavu_sha512 SHA-512 + * @ingroup lavu_hash + * SHA-512 (Secure Hash Algorithm) hash function implementations. + * + * This module supports the following SHA-2 hash functions: + * + * - SHA-512/224: 224 bits + * - SHA-512/256: 256 bits + * - SHA-384: 384 bits + * - SHA-512: 512 bits + * + * @see For SHA-1, SHA-256, and variants thereof, see @ref lavu_sha. + * + * @{ + */ + +extern const int av_sha512_size; + +struct AVSHA512; + +/** + * Allocate an AVSHA512 context. + */ +struct AVSHA512 *av_sha512_alloc(void); + +/** + * Initialize SHA-2 512 hashing. + * + * @param context pointer to the function context (of size av_sha512_size) + * @param bits number of bits in digest (224, 256, 384 or 512 bits) + * @return zero if initialization succeeded, -1 otherwise + */ +int av_sha512_init(struct AVSHA512* context, int bits); + +/** + * Update hash value. + * + * @param context hash function context + * @param data input data to update hash with + * @param len input data length + */ +void av_sha512_update(struct AVSHA512* context, const uint8_t* data, size_t len); + +/** + * Finish hashing and output digest value. + * + * @param context hash function context + * @param digest buffer where output digest value is stored + */ +void av_sha512_final(struct AVSHA512* context, uint8_t *digest); + +/** + * @} + */ + +#endif /* AVUTIL_SHA512_H */ diff --git a/ffmpeg-n8.1/include/libavutil/spherical.h b/ffmpeg-n8.1/include/libavutil/spherical.h new file mode 100644 index 00000000..4b78978e --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/spherical.h @@ -0,0 +1,249 @@ +/* + * Copyright (c) 2016 Vittorio Giovara + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_video_spherical + * Spherical video + */ + +#ifndef AVUTIL_SPHERICAL_H +#define AVUTIL_SPHERICAL_H + +#include +#include + +/** + * @defgroup lavu_video_spherical Spherical video mapping + * @ingroup lavu_video + * + * A spherical video file contains surfaces that need to be mapped onto a + * sphere. Depending on how the frame was converted, a different distortion + * transformation or surface recomposition function needs to be applied before + * the video should be mapped and displayed. + * @{ + */ + +/** + * Projection of the video surface(s) on a sphere. + */ +enum AVSphericalProjection { + /** + * Video represents a sphere mapped on a flat surface using + * equirectangular projection. + */ + AV_SPHERICAL_EQUIRECTANGULAR, + + /** + * Video frame is split into 6 faces of a cube, and arranged on a + * 3x2 layout. Faces are oriented upwards for the front, left, right, + * and back faces. The up face is oriented so the top of the face is + * forwards and the down face is oriented so the top of the face is + * to the back. + */ + AV_SPHERICAL_CUBEMAP, + + /** + * Video represents a portion of a sphere mapped on a flat surface + * using equirectangular projection. The @ref bounding fields indicate + * the position of the current video in a larger surface. + */ + AV_SPHERICAL_EQUIRECTANGULAR_TILE, + + /** + * Video frame displays as a 180 degree equirectangular projection. + */ + AV_SPHERICAL_HALF_EQUIRECTANGULAR, + + /** + * Video frame displays on a flat, rectangular 2D surface. + */ + AV_SPHERICAL_RECTILINEAR, + + /** + * Fisheye projection (Apple). + * See: https://developer.apple.com/documentation/coremedia/cmprojectiontype/fisheye + */ + AV_SPHERICAL_FISHEYE, + + /** + * Parametric Immersive projection (Apple). + * See: https://developer.apple.com/documentation/coremedia/cmprojectiontype/parametricimmersive + */ + AV_SPHERICAL_PARAMETRIC_IMMERSIVE, +}; + +/** + * This structure describes how to handle spherical videos, outlining + * information about projection, initial layout, and any other view modifier. + * + * @note The struct must be allocated with av_spherical_alloc() and + * its size is not a part of the public ABI. + */ +typedef struct AVSphericalMapping { + /** + * Projection type. + */ + enum AVSphericalProjection projection; + + /** + * @name Initial orientation + * @{ + * There fields describe additional rotations applied to the sphere after + * the video frame is mapped onto it. The sphere is rotated around the + * viewer, who remains stationary. The order of transformation is always + * yaw, followed by pitch, and finally by roll. + * + * The coordinate system matches the one defined in OpenGL, where the + * forward vector (z) is coming out of screen, and it is equivalent to + * a rotation matrix of R = r_y(yaw) * r_x(pitch) * r_z(roll). + * + * A positive yaw rotates the portion of the sphere in front of the viewer + * toward their right. A positive pitch rotates the portion of the sphere + * in front of the viewer upwards. A positive roll tilts the portion of + * the sphere in front of the viewer to the viewer's right. + * + * These values are exported as 16.16 fixed point. + * + * See this equirectangular projection as example: + * + * @code{.unparsed} + * Yaw + * -180 0 180 + * 90 +-------------+-------------+ 180 + * | | | up + * P | | | y| forward + * i | ^ | | /z + * t 0 +-------------X-------------+ 0 Roll | / + * c | | | | / + * h | | | 0|/_____right + * | | | x + * -90 +-------------+-------------+ -180 + * + * X - the default camera center + * ^ - the default up vector + * @endcode + */ + int32_t yaw; ///< Rotation around the up vector [-180, 180]. + int32_t pitch; ///< Rotation around the right vector [-90, 90]. + int32_t roll; ///< Rotation around the forward vector [-180, 180]. + /** + * @} + */ + + /** + * @name Bounding rectangle + * @anchor bounding + * @{ + * These fields indicate the location of the current tile, and where + * it should be mapped relative to the original surface. They are + * exported as 0.32 fixed point, and can be converted to classic + * pixel values with av_spherical_bounds(). + * + * @code{.unparsed} + * +----------------+----------+ + * | |bound_top | + * | +--------+ | + * | bound_left |tile | | + * +<---------->| |<--->+bound_right + * | +--------+ | + * | | | + * | bound_bottom| | + * +----------------+----------+ + * @endcode + * + * If needed, the original video surface dimensions can be derived + * by adding the current stream or frame size to the related bounds, + * like in the following example: + * + * @code{c} + * original_width = tile->width + bound_left + bound_right; + * original_height = tile->height + bound_top + bound_bottom; + * @endcode + * + * @note These values are valid only for the tiled equirectangular + * projection type (@ref AV_SPHERICAL_EQUIRECTANGULAR_TILE), + * and should be ignored in all other cases. + */ + uint32_t bound_left; ///< Distance from the left edge + uint32_t bound_top; ///< Distance from the top edge + uint32_t bound_right; ///< Distance from the right edge + uint32_t bound_bottom; ///< Distance from the bottom edge + /** + * @} + */ + + /** + * Number of pixels to pad from the edge of each cube face. + * + * @note This value is valid for only for the cubemap projection type + * (@ref AV_SPHERICAL_CUBEMAP), and should be ignored in all other + * cases. + */ + uint32_t padding; +} AVSphericalMapping; + +/** + * Allocate a AVSphericalVideo structure and initialize its fields to default + * values. + * + * @return the newly allocated struct or NULL on failure + */ +AVSphericalMapping *av_spherical_alloc(size_t *size); + +/** + * Convert the @ref bounding fields from an AVSphericalVideo + * from 0.32 fixed point to pixels. + * + * @param map The AVSphericalVideo map to read bound values from. + * @param width Width of the current frame or stream. + * @param height Height of the current frame or stream. + * @param left Pixels from the left edge. + * @param top Pixels from the top edge. + * @param right Pixels from the right edge. + * @param bottom Pixels from the bottom edge. + */ +void av_spherical_tile_bounds(const AVSphericalMapping *map, + size_t width, size_t height, + size_t *left, size_t *top, + size_t *right, size_t *bottom); + +/** + * Provide a human-readable name of a given AVSphericalProjection. + * + * @param projection The input AVSphericalProjection. + * + * @return The name of the AVSphericalProjection, or "unknown". + */ +const char *av_spherical_projection_name(enum AVSphericalProjection projection); + +/** + * Get the AVSphericalProjection form a human-readable name. + * + * @param name The input string. + * + * @return The AVSphericalProjection value, or -1 if not found. + */ +int av_spherical_from_name(const char *name); +/** + * @} + */ + +#endif /* AVUTIL_SPHERICAL_H */ diff --git a/ffmpeg-n8.1/include/libavutil/stereo3d.h b/ffmpeg-n8.1/include/libavutil/stereo3d.h new file mode 100644 index 00000000..c0a4ab3f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/stereo3d.h @@ -0,0 +1,325 @@ +/* + * Copyright (c) 2013 Vittorio Giovara + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_video_stereo3d + * Stereoscopic video + */ + +#ifndef AVUTIL_STEREO3D_H +#define AVUTIL_STEREO3D_H + +#include + +#include "frame.h" + +/** + * @defgroup lavu_video_stereo3d Stereo3D types and functions + * @ingroup lavu_video + * + * A stereoscopic video file consists in multiple views embedded in a single + * frame, usually describing two views of a scene. This file describes all + * possible codec-independent view arrangements. + * + * @{ + */ + +/** + * List of possible 3D Types + */ +enum AVStereo3DType { + /** + * Video is not stereoscopic (and metadata has to be there). + */ + AV_STEREO3D_2D, + + /** + * Views are next to each other. + * + * @code{.unparsed} + * LLLLRRRR + * LLLLRRRR + * LLLLRRRR + * ... + * @endcode + */ + AV_STEREO3D_SIDEBYSIDE, + + /** + * Views are on top of each other. + * + * @code{.unparsed} + * LLLLLLLL + * LLLLLLLL + * RRRRRRRR + * RRRRRRRR + * @endcode + */ + AV_STEREO3D_TOPBOTTOM, + + /** + * Views are alternated temporally. + * + * @code{.unparsed} + * frame0 frame1 frame2 ... + * LLLLLLLL RRRRRRRR LLLLLLLL + * LLLLLLLL RRRRRRRR LLLLLLLL + * LLLLLLLL RRRRRRRR LLLLLLLL + * ... ... ... + * @endcode + */ + AV_STEREO3D_FRAMESEQUENCE, + + /** + * Views are packed in a checkerboard-like structure per pixel. + * + * @code{.unparsed} + * LRLRLRLR + * RLRLRLRL + * LRLRLRLR + * ... + * @endcode + */ + AV_STEREO3D_CHECKERBOARD, + + /** + * Views are next to each other, but when upscaling + * apply a checkerboard pattern. + * + * @code{.unparsed} + * LLLLRRRR L L L L R R R R + * LLLLRRRR => L L L L R R R R + * LLLLRRRR L L L L R R R R + * LLLLRRRR L L L L R R R R + * @endcode + */ + AV_STEREO3D_SIDEBYSIDE_QUINCUNX, + + /** + * Views are packed per line, as if interlaced. + * + * @code{.unparsed} + * LLLLLLLL + * RRRRRRRR + * LLLLLLLL + * ... + * @endcode + */ + AV_STEREO3D_LINES, + + /** + * Views are packed per column. + * + * @code{.unparsed} + * LRLRLRLR + * LRLRLRLR + * LRLRLRLR + * ... + * @endcode + */ + AV_STEREO3D_COLUMNS, + + /** + * Video is stereoscopic but the packing is unspecified. + */ + AV_STEREO3D_UNSPEC, +}; + +/** + * List of possible view types. + */ +enum AVStereo3DView { + /** + * Frame contains two packed views. + */ + AV_STEREO3D_VIEW_PACKED, + + /** + * Frame contains only the left view. + */ + AV_STEREO3D_VIEW_LEFT, + + /** + * Frame contains only the right view. + */ + AV_STEREO3D_VIEW_RIGHT, + + /** + * Content is unspecified. + */ + AV_STEREO3D_VIEW_UNSPEC, +}; + +/** + * List of possible primary eyes. + */ +enum AVStereo3DPrimaryEye { + /** + * Neither eye. + */ + AV_PRIMARY_EYE_NONE, + + /** + * Left eye. + */ + AV_PRIMARY_EYE_LEFT, + + /** + * Right eye + */ + AV_PRIMARY_EYE_RIGHT, +}; + +/** + * Inverted views, Right/Bottom represents the left view. + */ +#define AV_STEREO3D_FLAG_INVERT (1 << 0) + +/** + * Stereo 3D type: this structure describes how two videos are packed + * within a single video surface, with additional information as needed. + * + * @note The struct must be allocated with av_stereo3d_alloc() and + * its size is not a part of the public ABI. + */ +typedef struct AVStereo3D { + /** + * How views are packed within the video. + */ + enum AVStereo3DType type; + + /** + * Additional information about the frame packing. + */ + int flags; + + /** + * Determines which views are packed. + */ + enum AVStereo3DView view; + + /** + * Which eye is the primary eye when rendering in 2D. + */ + enum AVStereo3DPrimaryEye primary_eye; + + /** + * The distance between the centres of the lenses of the camera system, + * in micrometers. Zero if unset. + */ + uint32_t baseline; + + /** + * Relative shift of the left and right images, which changes the zero parallax plane. + * Range is -1.0 to 1.0. Zero if unset. + */ + AVRational horizontal_disparity_adjustment; + + /** + * Horizontal field of view, in degrees. Zero if unset. + */ + AVRational horizontal_field_of_view; +} AVStereo3D; + +/** + * Allocate an AVStereo3D structure and set its fields to default values. + * The resulting struct can be freed using av_freep(). + * + * @return An AVStereo3D filled with default values or NULL on failure. + */ +AVStereo3D *av_stereo3d_alloc(void); + +/** + * Allocate an AVStereo3D structure and set its fields to default values. + * The resulting struct can be freed using av_freep(). + * + * @return An AVStereo3D filled with default values or NULL on failure. + */ +AVStereo3D *av_stereo3d_alloc_size(size_t *size); + +/** + * Allocate a complete AVFrameSideData and add it to the frame. + * + * @param frame The frame which side data is added to. + * + * @return The AVStereo3D structure to be filled by caller. + */ +AVStereo3D *av_stereo3d_create_side_data(AVFrame *frame); + +/** + * Provide a human-readable name of a given stereo3d type. + * + * @param type The input stereo3d type value. + * + * @return The name of the stereo3d value, or "unknown". + */ +const char *av_stereo3d_type_name(unsigned int type); + +/** + * Get the AVStereo3DType form a human-readable name. + * + * @param name The input string. + * + * @return The AVStereo3DType value, or -1 if not found. + */ +int av_stereo3d_from_name(const char *name); + +/** + * Provide a human-readable name of a given stereo3d view. + * + * @param type The input stereo3d view value. + * + * @return The name of the stereo3d view value, or "unknown". + */ +const char *av_stereo3d_view_name(unsigned int view); + +/** + * Get the AVStereo3DView form a human-readable name. + * + * @param name The input string. + * + * @return The AVStereo3DView value, or -1 if not found. + */ +int av_stereo3d_view_from_name(const char *name); + +/** + * Provide a human-readable name of a given stereo3d primary eye. + * + * @param type The input stereo3d primary eye value. + * + * @return The name of the stereo3d primary eye value, or "unknown". + */ +const char *av_stereo3d_primary_eye_name(unsigned int eye); + +/** + * Get the AVStereo3DPrimaryEye form a human-readable name. + * + * @param name The input string. + * + * @return The AVStereo3DPrimaryEye value, or -1 if not found. + */ +int av_stereo3d_primary_eye_from_name(const char *name); + +/** + * @} + */ + +#endif /* AVUTIL_STEREO3D_H */ diff --git a/ffmpeg-n8.1/include/libavutil/tdrdi.h b/ffmpeg-n8.1/include/libavutil/tdrdi.h new file mode 100644 index 00000000..8629775a --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/tdrdi.h @@ -0,0 +1,164 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu_video_3d_reference_displays_info + * Spherical video + */ + +#ifndef AVUTIL_TDRDI_H +#define AVUTIL_TDRDI_H + +#include +#include + +#include "libavutil/avassert.h" + +/** + * @defgroup lavu_video_3d_reference_displays_info 3D Reference Displays Information + * @ingroup lavu_video + * + * The 3D Reference Displays Information describes information about the reference display + * width(s) and reference viewing distance(s) as well as information about the corresponding + * reference stereo pair(s). + * @{ + */ + +#define AV_TDRDI_MAX_NUM_REF_DISPLAY 32 + +/** + * This structure describes information about the reference display width(s) and reference + * viewing distance(s) as well as information about the corresponding reference stereo pair(s). + * See section G.14.3.2.3 of ITU-T H.265 for more information. + * + * @note The struct must be allocated with av_tdrdi_alloc() and + * its size is not a part of the public ABI. + */ +typedef struct AV3DReferenceDisplaysInfo { + /** + * The exponent of the maximum allowable truncation error for + * {exponent,mantissa}_ref_display_width as given by 2(-prec_ref_display_width). + */ + uint8_t prec_ref_display_width; + + /** + * A flag to indicate the presence of reference viewing distance. + * If false, the values of prec_ref_viewing_dist, exponent_ref_viewing_distance, + * and mantissa_ref_viewing_distance are undefined. + */ + uint8_t ref_viewing_distance_flag; + + /** + * The exponent of the maximum allowable truncation error for + * {exponent,mantissa}_ref_viewing_distance as given by 2^(-prec_ref_viewing_dist). + * The value of prec_ref_viewing_dist shall be in the range of 0 to 31, inclusive. + */ + uint8_t prec_ref_viewing_dist; + + /** + * The number of reference displays that are signalled in this struct. + * Allowed range is 1 to 32, inclusive. + */ + uint8_t num_ref_displays; + + /** + * Offset in bytes from the beginning of this structure at which the array + * of reference displays starts. + */ + size_t entries_offset; + + /** + * Size of each entry in bytes. May not match sizeof(AV3DReferenceDisplay). + */ + size_t entry_size; +} AV3DReferenceDisplaysInfo; + +/** + * Data structure for single deference display information. + * It is allocated as a part of AV3DReferenceDisplaysInfo and should be retrieved with + * av_tdrdi_get_display(). + * + * sizeof(AV3DReferenceDisplay) is not a part of the ABI and new fields may be + * added to it. +*/ +typedef struct AV3DReferenceDisplay { + /** + * The ViewId of the left view of a stereo pair corresponding to the n-th reference display. + */ + uint16_t left_view_id; + + /** + * The ViewId of the left view of a stereo pair corresponding to the n-th reference display. + */ + uint16_t right_view_id; + + /** + * The exponent part of the reference display width of the n-th reference display. + */ + uint8_t exponent_ref_display_width; + + /** + * The mantissa part of the reference display width of the n-th reference display. + */ + uint8_t mantissa_ref_display_width; + + /** + * The exponent part of the reference viewing distance of the n-th reference display. + */ + uint8_t exponent_ref_viewing_distance; + + /** + * The mantissa part of the reference viewing distance of the n-th reference display. + */ + uint8_t mantissa_ref_viewing_distance; + + /** + * An array of flags to indicates that the information about additional horizontal shift of + * the left and right views for the n-th reference display is present. + */ + uint8_t additional_shift_present_flag; + + /** + * The recommended additional horizontal shift for a stereo pair corresponding to the n-th + * reference baseline and the n-th reference display. + */ + int16_t num_sample_shift; +} AV3DReferenceDisplay; + +static av_always_inline AV3DReferenceDisplay* +av_tdrdi_get_display(AV3DReferenceDisplaysInfo *tdrdi, unsigned int idx) +{ + av_assert0(idx < tdrdi->num_ref_displays); + return (AV3DReferenceDisplay *)((uint8_t *)tdrdi + tdrdi->entries_offset + + idx * tdrdi->entry_size); +} + +/** + * Allocate a AV3DReferenceDisplaysInfo structure and initialize its fields to default + * values. + * + * @return the newly allocated struct or NULL on failure + */ +AV3DReferenceDisplaysInfo *av_tdrdi_alloc(unsigned int nb_displays, size_t *size); + +/** + * @} + */ + +#endif /* AVUTIL_TDRDI_H */ diff --git a/ffmpeg-n8.1/include/libavutil/tea.h b/ffmpeg-n8.1/include/libavutil/tea.h new file mode 100644 index 00000000..dd929bda --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/tea.h @@ -0,0 +1,71 @@ +/* + * A 32-bit implementation of the TEA algorithm + * Copyright (c) 2015 Vesselin Bontchev + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_TEA_H +#define AVUTIL_TEA_H + +#include + +/** + * @file + * @brief Public header for libavutil TEA algorithm + * @defgroup lavu_tea TEA + * @ingroup lavu_crypto + * @{ + */ + +extern const int av_tea_size; + +struct AVTEA; + +/** + * Allocate an AVTEA context + * To free the struct: av_free(ptr) + */ +struct AVTEA *av_tea_alloc(void); + +/** + * Initialize an AVTEA context. + * + * @param ctx an AVTEA context + * @param key a key of 16 bytes used for encryption/decryption + * @param rounds the number of rounds in TEA (64 is the "standard") + */ +void av_tea_init(struct AVTEA *ctx, const uint8_t key[16], int rounds); + +/** + * Encrypt or decrypt a buffer using a previously initialized context. + * + * @param ctx an AVTEA context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 8 byte blocks + * @param iv initialization vector for CBC mode, if NULL then ECB will be used + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_tea_crypt(struct AVTEA *ctx, uint8_t *dst, const uint8_t *src, + int count, uint8_t *iv, int decrypt); + +/** + * @} + */ + +#endif /* AVUTIL_TEA_H */ diff --git a/ffmpeg-n8.1/include/libavutil/threadmessage.h b/ffmpeg-n8.1/include/libavutil/threadmessage.h new file mode 100644 index 00000000..42ce655f --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/threadmessage.h @@ -0,0 +1,115 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_THREADMESSAGE_H +#define AVUTIL_THREADMESSAGE_H + +typedef struct AVThreadMessageQueue AVThreadMessageQueue; + +typedef enum AVThreadMessageFlags { + + /** + * Perform non-blocking operation. + * If this flag is set, send and recv operations are non-blocking and + * return AVERROR(EAGAIN) immediately if they can not proceed. + */ + AV_THREAD_MESSAGE_NONBLOCK = 1, + +} AVThreadMessageFlags; + +/** + * Allocate a new message queue. + * + * @param mq pointer to the message queue + * @param nelem maximum number of elements in the queue + * @param elsize size of each element in the queue + * @return >=0 for success; <0 for error, in particular AVERROR(ENOSYS) if + * lavu was built without thread support + */ +int av_thread_message_queue_alloc(AVThreadMessageQueue **mq, + unsigned nelem, + unsigned elsize); + +/** + * Free a message queue. + * + * The message queue must no longer be in use by another thread. + */ +void av_thread_message_queue_free(AVThreadMessageQueue **mq); + +/** + * Send a message on the queue. + */ +int av_thread_message_queue_send(AVThreadMessageQueue *mq, + void *msg, + unsigned flags); + +/** + * Receive a message from the queue. + */ +int av_thread_message_queue_recv(AVThreadMessageQueue *mq, + void *msg, + unsigned flags); + +/** + * Set the sending error code. + * + * If the error code is set to non-zero, av_thread_message_queue_send() will + * return it immediately. Conventional values, such as AVERROR_EOF or + * AVERROR(EAGAIN), can be used to cause the sending thread to stop or + * suspend its operation. + */ +void av_thread_message_queue_set_err_send(AVThreadMessageQueue *mq, + int err); + +/** + * Set the receiving error code. + * + * If the error code is set to non-zero, av_thread_message_queue_recv() will + * return it immediately when there are no longer available messages. + * Conventional values, such as AVERROR_EOF or AVERROR(EAGAIN), can be used + * to cause the receiving thread to stop or suspend its operation. + */ +void av_thread_message_queue_set_err_recv(AVThreadMessageQueue *mq, + int err); + +/** + * Set the optional free message callback function which will be called if an + * operation is removing messages from the queue. + */ +void av_thread_message_queue_set_free_func(AVThreadMessageQueue *mq, + void (*free_func)(void *msg)); + +/** + * Return the current number of messages in the queue. + * + * @return the current number of messages or AVERROR(ENOSYS) if lavu was built + * without thread support + */ +int av_thread_message_queue_nb_elems(AVThreadMessageQueue *mq); + +/** + * Flush the message queue + * + * This function is mostly equivalent to reading and free-ing every message + * except that it will be done in a single operation (no lock/unlock between + * reads). + */ +void av_thread_message_flush(AVThreadMessageQueue *mq); + +#endif /* AVUTIL_THREADMESSAGE_H */ diff --git a/ffmpeg-n8.1/include/libavutil/time.h b/ffmpeg-n8.1/include/libavutil/time.h new file mode 100644 index 00000000..dc169b06 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/time.h @@ -0,0 +1,56 @@ +/* + * Copyright (c) 2000-2003 Fabrice Bellard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_TIME_H +#define AVUTIL_TIME_H + +#include + +/** + * Get the current time in microseconds. + */ +int64_t av_gettime(void); + +/** + * Get the current time in microseconds since some unspecified starting point. + * On platforms that support it, the time comes from a monotonic clock + * This property makes this time source ideal for measuring relative time. + * The returned values may not be monotonic on platforms where a monotonic + * clock is not available. + */ +int64_t av_gettime_relative(void); + +/** + * Indicates with a boolean result if the av_gettime_relative() time source + * is monotonic. + */ +int av_gettime_relative_is_monotonic(void); + +/** + * Sleep for a period of time. Although the duration is expressed in + * microseconds, the actual delay may be rounded to the precision of the + * system timer. + * + * @param usec Number of microseconds to sleep. + * @return zero on success or (negative) error code. + */ +int av_usleep(unsigned usec); + +#endif /* AVUTIL_TIME_H */ diff --git a/ffmpeg-n8.1/include/libavutil/timecode.h b/ffmpeg-n8.1/include/libavutil/timecode.h new file mode 100644 index 00000000..fe0fc835 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/timecode.h @@ -0,0 +1,199 @@ +/* + * Copyright (c) 2006 Smartjog S.A.S, Baptiste Coudurier + * Copyright (c) 2011-2012 Smartjog S.A.S, Clément Bœsch + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * Timecode helpers header + */ + +#ifndef AVUTIL_TIMECODE_H +#define AVUTIL_TIMECODE_H + +#include +#include "rational.h" + +#define AV_TIMECODE_STR_SIZE 23 + +enum AVTimecodeFlag { + AV_TIMECODE_FLAG_DROPFRAME = 1<<0, ///< timecode is drop frame + AV_TIMECODE_FLAG_24HOURSMAX = 1<<1, ///< timecode wraps after 24 hours + AV_TIMECODE_FLAG_ALLOWNEGATIVE = 1<<2, ///< negative time values are allowed +}; + +typedef struct { + int start; ///< timecode frame start (first base frame number) + uint32_t flags; ///< flags such as drop frame, +24 hours support, ... + AVRational rate; ///< frame rate in rational form + unsigned fps; ///< frame per second; must be consistent with the rate field +} AVTimecode; + +/** + * Adjust frame number for NTSC drop frame time code. + * + * @param framenum frame number to adjust + * @param fps frame per second, multiples of 30 + * @return adjusted frame number + * @warning adjustment is only valid for multiples of NTSC 29.97 + */ +int av_timecode_adjust_ntsc_framenum2(int framenum, int fps); + +/** + * Convert frame number to SMPTE 12M binary representation. + * + * @param tc timecode data correctly initialized + * @param framenum frame number + * @return the SMPTE binary representation + * + * See SMPTE ST 314M-2005 Sec 4.4.2.2.1 "Time code pack (TC)" + * the format description as follows: + * bits 0-5: hours, in BCD(6bits) + * bits 6: BGF1 + * bits 7: BGF2 (NTSC) or FIELD (PAL) + * bits 8-14: minutes, in BCD(7bits) + * bits 15: BGF0 (NTSC) or BGF2 (PAL) + * bits 16-22: seconds, in BCD(7bits) + * bits 23: FIELD (NTSC) or BGF0 (PAL) + * bits 24-29: frames, in BCD(6bits) + * bits 30: drop frame flag (0: non drop, 1: drop) + * bits 31: color frame flag (0: unsync mode, 1: sync mode) + * @note BCD numbers (6 or 7 bits): 4 or 5 lower bits for units, 2 higher bits for tens. + * @note Frame number adjustment is automatically done in case of drop timecode, + * you do NOT have to call av_timecode_adjust_ntsc_framenum2(). + * @note The frame number is relative to tc->start. + * @note Color frame (CF) and binary group flags (BGF) bits are set to zero. + */ +uint32_t av_timecode_get_smpte_from_framenum(const AVTimecode *tc, int framenum); + +/** + * Convert sei info to SMPTE 12M binary representation. + * + * @param rate frame rate in rational form + * @param drop drop flag + * @param hh hour + * @param mm minute + * @param ss second + * @param ff frame number + * @return the SMPTE binary representation + */ +uint32_t av_timecode_get_smpte(AVRational rate, int drop, int hh, int mm, int ss, int ff); + +/** + * Load timecode string in buf. + * + * @param tc timecode data correctly initialized + * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long + * @param framenum frame number + * @return the buf parameter + * + * @note Timecode representation can be a negative timecode and have more than + * 24 hours, but will only be honored if the flags are correctly set. + * @note The frame number is relative to tc->start. + */ +char *av_timecode_make_string(const AVTimecode *tc, char *buf, int framenum); + +/** + * Get the timecode string from the SMPTE timecode format. + * + * In contrast to av_timecode_make_smpte_tc_string this function supports 50/60 + * fps timecodes by using the field bit. + * + * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long + * @param rate frame rate of the timecode + * @param tcsmpte the 32-bit SMPTE timecode + * @param prevent_df prevent the use of a drop flag when it is known the DF bit + * is arbitrary + * @param skip_field prevent the use of a field flag when it is known the field + * bit is arbitrary (e.g. because it is used as PC flag) + * @return the buf parameter + */ +char *av_timecode_make_smpte_tc_string2(char *buf, AVRational rate, uint32_t tcsmpte, int prevent_df, int skip_field); + +/** + * Get the timecode string from the SMPTE timecode format. + * + * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long + * @param tcsmpte the 32-bit SMPTE timecode + * @param prevent_df prevent the use of a drop flag when it is known the DF bit + * is arbitrary + * @return the buf parameter + */ +char *av_timecode_make_smpte_tc_string(char *buf, uint32_t tcsmpte, int prevent_df); + +/** + * Get the timecode string from the 25-bit timecode format (MPEG GOP format). + * + * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long + * @param tc25bit the 25-bits timecode + * @return the buf parameter + */ +char *av_timecode_make_mpeg_tc_string(char *buf, uint32_t tc25bit); + +/** + * Init a timecode struct with the passed parameters. + * + * @param tc pointer to an allocated AVTimecode + * @param rate frame rate in rational form + * @param flags miscellaneous flags such as drop frame, +24 hours, ... + * (see AVTimecodeFlag) + * @param frame_start the first frame number + * @param log_ctx a pointer to an arbitrary struct of which the first field + * is a pointer to an AVClass struct (used for av_log) + * @return 0 on success, AVERROR otherwise + */ +int av_timecode_init(AVTimecode *tc, AVRational rate, int flags, int frame_start, void *log_ctx); + +/** + * Init a timecode struct from the passed timecode components. + * + * @param tc pointer to an allocated AVTimecode + * @param rate frame rate in rational form + * @param flags miscellaneous flags such as drop frame, +24 hours, ... + * (see AVTimecodeFlag) + * @param hh hours + * @param mm minutes + * @param ss seconds + * @param ff frames + * @param log_ctx a pointer to an arbitrary struct of which the first field + * is a pointer to an AVClass struct (used for av_log) + * @return 0 on success, AVERROR otherwise + */ +int av_timecode_init_from_components(AVTimecode *tc, AVRational rate, int flags, int hh, int mm, int ss, int ff, void *log_ctx); + +/** + * Parse timecode representation (hh:mm:ss[:;.]ff). + * + * @param tc pointer to an allocated AVTimecode + * @param rate frame rate in rational form + * @param str timecode string which will determine the frame start + * @param log_ctx a pointer to an arbitrary struct of which the first field is a + * pointer to an AVClass struct (used for av_log). + * @return 0 on success, AVERROR otherwise + */ +int av_timecode_init_from_string(AVTimecode *tc, AVRational rate, const char *str, void *log_ctx); + +/** + * Check if the timecode feature is available for the given frame rate + * + * @return 0 if supported, <0 otherwise + */ +int av_timecode_check_frame_rate(AVRational rate); + +#endif /* AVUTIL_TIMECODE_H */ diff --git a/ffmpeg-n8.1/include/libavutil/timestamp.h b/ffmpeg-n8.1/include/libavutil/timestamp.h new file mode 100644 index 00000000..fa53a46b --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/timestamp.h @@ -0,0 +1,85 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * timestamp utils, mostly useful for debugging/logging purposes + */ + +#ifndef AVUTIL_TIMESTAMP_H +#define AVUTIL_TIMESTAMP_H + +#include "avutil.h" + +#if defined(__cplusplus) && !defined(__STDC_FORMAT_MACROS) && !defined(PRId64) +#error missing -D__STDC_FORMAT_MACROS / #define __STDC_FORMAT_MACROS +#endif + +#define AV_TS_MAX_STRING_SIZE 32 + +/** + * Fill the provided buffer with a string containing a timestamp + * representation. + * + * @param buf a buffer with size in bytes of at least AV_TS_MAX_STRING_SIZE + * @param ts the timestamp to represent + * @return the buffer in input + */ +static inline char *av_ts_make_string(char *buf, int64_t ts) +{ + if (ts == AV_NOPTS_VALUE) snprintf(buf, AV_TS_MAX_STRING_SIZE, "NOPTS"); + else snprintf(buf, AV_TS_MAX_STRING_SIZE, "%" PRId64, ts); + return buf; +} + +/** + * Convenience macro, the return value should be used only directly in + * function arguments but never stand-alone. + */ +#define av_ts2str(ts) av_ts_make_string((char[AV_TS_MAX_STRING_SIZE]){0}, ts) + +/** + * Fill the provided buffer with a string containing a timestamp time + * representation. + * + * @param buf a buffer with size in bytes of at least AV_TS_MAX_STRING_SIZE + * @param ts the timestamp to represent + * @param tb the timebase of the timestamp + * @return the buffer in input + */ +char *av_ts_make_time_string2(char *buf, int64_t ts, AVRational tb); + +/** + * Fill the provided buffer with a string containing a timestamp + * representation. + * + * @see av_ts_make_time_string2 + */ +static inline char *av_ts_make_time_string(char *buf, int64_t ts, + const AVRational *tb) +{ + return av_ts_make_time_string2(buf, ts, *tb); +} + +/** + * Convenience macro, the return value should be used only directly in + * function arguments but never stand-alone. + */ +#define av_ts2timestr(ts, tb) av_ts_make_time_string((char[AV_TS_MAX_STRING_SIZE]){0}, ts, tb) + +#endif /* AVUTIL_TIMESTAMP_H */ diff --git a/ffmpeg-n8.1/include/libavutil/tree.h b/ffmpeg-n8.1/include/libavutil/tree.h new file mode 100644 index 00000000..bbb8fbb1 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/tree.h @@ -0,0 +1,137 @@ +/* + * copyright (c) 2006 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * A tree container. + * @author Michael Niedermayer + */ + +#ifndef AVUTIL_TREE_H +#define AVUTIL_TREE_H + +#include "attributes.h" + +/** + * @addtogroup lavu_tree AVTree + * @ingroup lavu_data + * + * Low-complexity tree container + * + * Insertion, removal, finding equal, largest which is smaller than and + * smallest which is larger than, all have O(log n) worst-case complexity. + * @{ + */ + + +struct AVTreeNode; +extern const int av_tree_node_size; + +/** + * Allocate an AVTreeNode. + */ +struct AVTreeNode *av_tree_node_alloc(void); + +/** + * Find an element. + * @param root a pointer to the root node of the tree + * @param next If next is not NULL, then next[0] will contain the previous + * element and next[1] the next element. If either does not exist, + * then the corresponding entry in next is unchanged. + * @param cmp compare function used to compare elements in the tree, + * API identical to that of Standard C's qsort + * It is guaranteed that the first and only the first argument to cmp() + * will be the key parameter to av_tree_find(), thus it could if the + * user wants, be a different type (like an opaque context). + * @return An element with cmp(key, elem) == 0 or NULL if no such element + * exists in the tree. + */ +void *av_tree_find(const struct AVTreeNode *root, void *key, + int (*cmp)(const void *key, const void *b), void *next[2]); + +/** + * Insert or remove an element. + * + * If *next is NULL, then the supplied element will be removed if it exists. + * If *next is non-NULL, then the supplied element will be inserted, unless + * it already exists in the tree. + * + * @param rootp A pointer to a pointer to the root node of the tree; note that + * the root node can change during insertions, this is required + * to keep the tree balanced. + * @param key pointer to the element key to insert in the tree + * @param next Used to allocate and free AVTreeNodes. For insertion the user + * must set it to an allocated and zeroed object of at least + * av_tree_node_size bytes size. av_tree_insert() will set it to + * NULL if it has been consumed. + * For deleting elements *next is set to NULL by the user and + * av_tree_insert() will set it to the AVTreeNode which was + * used for the removed element. + * This allows the use of flat arrays, which have + * lower overhead compared to many malloced elements. + * You might want to define a function like: + * @code + * void *tree_insert(struct AVTreeNode **rootp, void *key, + * int (*cmp)(void *key, const void *b), + * AVTreeNode **next) + * { + * if (!*next) + * *next = av_mallocz(av_tree_node_size); + * return av_tree_insert(rootp, key, cmp, next); + * } + * void *tree_remove(struct AVTreeNode **rootp, void *key, + * int (*cmp)(void *key, const void *b, AVTreeNode **next)) + * { + * av_freep(next); + * return av_tree_insert(rootp, key, cmp, next); + * } + * @endcode + * @param cmp compare function used to compare elements in the tree, API identical + * to that of Standard C's qsort + * @return If no insertion happened, the found element; if an insertion or + * removal happened, then either key or NULL will be returned. + * Which one it is depends on the tree state and the implementation. You + * should make no assumptions that it's one or the other in the code. + */ +void *av_tree_insert(struct AVTreeNode **rootp, void *key, + int (*cmp)(const void *key, const void *b), + struct AVTreeNode **next); + +void av_tree_destroy(struct AVTreeNode *t); + +/** + * Apply enu(opaque, &elem) to all the elements in the tree in a given range. + * + * @param cmp a comparison function that returns < 0 for an element below the + * range, > 0 for an element above the range and == 0 for an + * element inside the range + * + * @note The cmp function should use the same ordering used to construct the + * tree. + */ +void av_tree_enumerate(struct AVTreeNode *t, void *opaque, + int (*cmp)(void *opaque, void *elem), + int (*enu)(void *opaque, void *elem)); + +/** + * @} + */ + +#endif /* AVUTIL_TREE_H */ diff --git a/ffmpeg-n8.1/include/libavutil/twofish.h b/ffmpeg-n8.1/include/libavutil/twofish.h new file mode 100644 index 00000000..67f359e8 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/twofish.h @@ -0,0 +1,70 @@ +/* + * An implementation of the TwoFish algorithm + * Copyright (c) 2015 Supraja Meedinti + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_TWOFISH_H +#define AVUTIL_TWOFISH_H + +#include + + +/** + * @file + * @brief Public header for libavutil TWOFISH algorithm + * @defgroup lavu_twofish TWOFISH + * @ingroup lavu_crypto + * @{ + */ + +extern const int av_twofish_size; + +struct AVTWOFISH; + +/** + * Allocate an AVTWOFISH context + * To free the struct: av_free(ptr) + */ +struct AVTWOFISH *av_twofish_alloc(void); + +/** + * Initialize an AVTWOFISH context. + * + * @param ctx an AVTWOFISH context + * @param key a key of size ranging from 1 to 32 bytes used for encryption/decryption + * @param key_bits number of keybits: 128, 192, 256 If less than the required, padded with zeroes to nearest valid value; return value is 0 if key_bits is 128/192/256, -1 if less than 0, 1 otherwise + */ +int av_twofish_init(struct AVTWOFISH *ctx, const uint8_t *key, int key_bits); + +/** + * Encrypt or decrypt a buffer using a previously initialized context + * + * @param ctx an AVTWOFISH context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 16 byte blocks + * @param iv initialization vector for CBC mode, NULL for ECB mode + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_twofish_crypt(struct AVTWOFISH *ctx, uint8_t *dst, const uint8_t *src, int count, uint8_t* iv, int decrypt); + +/** + * @} + */ +#endif /* AVUTIL_TWOFISH_H */ diff --git a/ffmpeg-n8.1/include/libavutil/tx.h b/ffmpeg-n8.1/include/libavutil/tx.h new file mode 100644 index 00000000..c9500957 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/tx.h @@ -0,0 +1,210 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_TX_H +#define AVUTIL_TX_H + +#include +#include + +typedef struct AVTXContext AVTXContext; + +typedef struct AVComplexFloat { + float re, im; +} AVComplexFloat; + +typedef struct AVComplexDouble { + double re, im; +} AVComplexDouble; + +typedef struct AVComplexInt32 { + int32_t re, im; +} AVComplexInt32; + +enum AVTXType { + /** + * Standard complex to complex FFT with sample data type of AVComplexFloat, + * AVComplexDouble or AVComplexInt32, for each respective variant. + * + * Output is not 1/len normalized. Scaling currently unsupported. + * The stride parameter must be set to the size of a single sample in bytes. + */ + AV_TX_FLOAT_FFT = 0, + AV_TX_DOUBLE_FFT = 2, + AV_TX_INT32_FFT = 4, + + /** + * Standard MDCT with a sample data type of float, double or int32_t, + * respectively. For the float and int32 variants, the scale type is + * 'float', while for the double variant, it's 'double'. + * If scale is NULL, 1.0 will be used as a default. + * + * Length is the frame size, not the window size (which is 2x frame). + * For forward transforms, the stride specifies the spacing between each + * sample in the output array in bytes. The input must be a flat array. + * + * For inverse transforms, the stride specifies the spacing between each + * sample in the input array in bytes. The output must be a flat array. + * + * NOTE: the inverse transform is half-length, meaning the output will not + * contain redundant data. This is what most codecs work with. To do a full + * inverse transform, set the AV_TX_FULL_IMDCT flag on init. + */ + AV_TX_FLOAT_MDCT = 1, + AV_TX_DOUBLE_MDCT = 3, + AV_TX_INT32_MDCT = 5, + + /** + * Real to complex and complex to real DFTs. + * For the float and int32 variants, the scale type is 'float', while for + * the double variant, it's a 'double'. If scale is NULL, 1.0 will be used + * as a default. + * + * For forward transforms (R2C), stride must be the spacing between two + * samples in bytes. For inverse transforms, the stride must be set + * to the spacing between two complex values in bytes. + * + * The forward transform performs a real-to-complex DFT of N samples to + * N/2+1 complex values. + * + * The inverse transform performs a complex-to-real DFT of N/2+1 complex + * values to N real samples. The output is not normalized, but can be + * made so by setting the scale value to 1.0/len. + * NOTE: the inverse transform always overwrites the input. + */ + AV_TX_FLOAT_RDFT = 6, + AV_TX_DOUBLE_RDFT = 7, + AV_TX_INT32_RDFT = 8, + + /** + * Real to real (DCT) transforms. + * + * The forward transform is a DCT-II. + * The inverse transform is a DCT-III. + * + * The input array is always overwritten. DCT-III requires that the + * input be padded with 2 extra samples. Stride must be set to the + * spacing between two samples in bytes. + */ + AV_TX_FLOAT_DCT = 9, + AV_TX_DOUBLE_DCT = 10, + AV_TX_INT32_DCT = 11, + + /** + * Discrete Cosine Transform I + * + * The forward transform is a DCT-I. + * The inverse transform is a DCT-I multiplied by 2/(N + 1). + * + * The input array is always overwritten. + */ + AV_TX_FLOAT_DCT_I = 12, + AV_TX_DOUBLE_DCT_I = 13, + AV_TX_INT32_DCT_I = 14, + + /** + * Discrete Sine Transform I + * + * The forward transform is a DST-I. + * The inverse transform is a DST-I multiplied by 2/(N + 1). + * + * The input array is always overwritten. + */ + AV_TX_FLOAT_DST_I = 15, + AV_TX_DOUBLE_DST_I = 16, + AV_TX_INT32_DST_I = 17, + + /* Not part of the API, do not use */ + AV_TX_NB, +}; + +/** + * Function pointer to a function to perform the transform. + * + * @note Using a different context than the one allocated during av_tx_init() + * is not allowed. + * + * @param s the transform context + * @param out the output array + * @param in the input array + * @param stride the input or output stride in bytes + * + * The out and in arrays must be aligned to the maximum required by the CPU + * architecture unless the AV_TX_UNALIGNED flag was set in av_tx_init(). + * The stride must follow the constraints the transform type has specified. + */ +typedef void (*av_tx_fn)(AVTXContext *s, void *out, void *in, ptrdiff_t stride); + +/** + * Flags for av_tx_init() + */ +enum AVTXFlags { + /** + * Allows for in-place transformations, where input == output. + * May be unsupported or slower for some transform types. + */ + AV_TX_INPLACE = 1ULL << 0, + + /** + * Relaxes alignment requirement for the in and out arrays of av_tx_fn(). + * May be slower with certain transform types. + */ + AV_TX_UNALIGNED = 1ULL << 1, + + /** + * Performs a full inverse MDCT rather than leaving out samples that can be + * derived through symmetry. Requires an output array of 'len' floats, + * rather than the usual 'len/2' floats. + * Ignored for all transforms but inverse MDCTs. + */ + AV_TX_FULL_IMDCT = 1ULL << 2, + + /** + * Perform a real to half-complex RDFT. + * Only the real, or imaginary coefficients will + * be output, depending on the flag used. Only available for forward RDFTs. + * Output array must have enough space to hold N complex values + * (regular size for a real to complex transform). + */ + AV_TX_REAL_TO_REAL = 1ULL << 3, + AV_TX_REAL_TO_IMAGINARY = 1ULL << 4, +}; + +/** + * Initialize a transform context with the given configuration + * (i)MDCTs with an odd length are currently not supported. + * + * @param ctx the context to allocate, will be NULL on error + * @param tx pointer to the transform function pointer to set + * @param type type the type of transform + * @param inv whether to do an inverse or a forward transform + * @param len the size of the transform in samples + * @param scale pointer to the value to scale the output if supported by type + * @param flags a bitmask of AVTXFlags or 0 + * + * @return 0 on success, negative error code on failure + */ +int av_tx_init(AVTXContext **ctx, av_tx_fn *tx, enum AVTXType type, + int inv, int len, const void *scale, uint64_t flags); + +/** + * Frees a context and sets *ctx to NULL, does nothing when *ctx == NULL. + */ +void av_tx_uninit(AVTXContext **ctx); + +#endif /* AVUTIL_TX_H */ diff --git a/ffmpeg-n8.1/include/libavutil/uuid.h b/ffmpeg-n8.1/include/libavutil/uuid.h new file mode 100644 index 00000000..748b7ed3 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/uuid.h @@ -0,0 +1,146 @@ +/* + * Copyright (c) 2022 Pierre-Anthony Lemieux + * Zane van Iperen + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * UUID parsing and serialization utilities. + * The library treats the UUID as an opaque sequence of 16 unsigned bytes, + * i.e. ignoring the internal layout of the UUID, which depends on the type + * of the UUID. + * + * @author Pierre-Anthony Lemieux + * @author Zane van Iperen + */ + +#ifndef AVUTIL_UUID_H +#define AVUTIL_UUID_H + +#include +#include + +#define AV_PRI_UUID \ + "%02hhx%02hhx%02hhx%02hhx-%02hhx%02hhx-" \ + "%02hhx%02hhx-%02hhx%02hhx-%02hhx%02hhx%02hhx%02hhx%02hhx%02hhx" + +#define AV_PRI_URN_UUID \ + "urn:uuid:%02hhx%02hhx%02hhx%02hhx-%02hhx%02hhx-" \ + "%02hhx%02hhx-%02hhx%02hhx-%02hhx%02hhx%02hhx%02hhx%02hhx%02hhx" + +/* AV_UUID_ARG() is used together with AV_PRI_UUID() or AV_PRI_URN_UUID + * to print UUIDs, e.g. + * av_log(NULL, AV_LOG_DEBUG, "UUID: " AV_PRI_UUID, AV_UUID_ARG(uuid)); + */ +#define AV_UUID_ARG(x) \ + (x)[ 0], (x)[ 1], (x)[ 2], (x)[ 3], \ + (x)[ 4], (x)[ 5], (x)[ 6], (x)[ 7], \ + (x)[ 8], (x)[ 9], (x)[10], (x)[11], \ + (x)[12], (x)[13], (x)[14], (x)[15] + +#define AV_UUID_LEN 16 + +/* Binary representation of a UUID */ +typedef uint8_t AVUUID[AV_UUID_LEN]; + +/** + * Parses a string representation of a UUID formatted according to IETF RFC 4122 + * into an AVUUID. The parsing is case-insensitive. The string must be 37 + * characters long, including the terminating NUL character. + * + * Example string representation: "2fceebd0-7017-433d-bafb-d073a7116696" + * + * @param[in] in String representation of a UUID, + * e.g. 2fceebd0-7017-433d-bafb-d073a7116696 + * @param[out] uu AVUUID + * @return A non-zero value in case of an error. + */ +int av_uuid_parse(const char *in, AVUUID uu); + +/** + * Parses a URN representation of a UUID, as specified at IETF RFC 4122, + * into an AVUUID. The parsing is case-insensitive. The string must be 46 + * characters long, including the terminating NUL character. + * + * Example string representation: "urn:uuid:2fceebd0-7017-433d-bafb-d073a7116696" + * + * @param[in] in URN UUID + * @param[out] uu AVUUID + * @return A non-zero value in case of an error. + */ +int av_uuid_urn_parse(const char *in, AVUUID uu); + +/** + * Parses a string representation of a UUID formatted according to IETF RFC 4122 + * into an AVUUID. The parsing is case-insensitive. + * + * @param[in] in_start Pointer to the first character of the string representation + * @param[in] in_end Pointer to the character after the last character of the + * string representation. That memory location is never + * accessed. It is an error if `in_end - in_start != 36`. + * @param[out] uu AVUUID + * @return A non-zero value in case of an error. + */ +int av_uuid_parse_range(const char *in_start, const char *in_end, AVUUID uu); + +/** + * Serializes a AVUUID into a string representation according to IETF RFC 4122. + * The string is lowercase and always 37 characters long, including the + * terminating NUL character. + * + * @param[in] uu AVUUID + * @param[out] out Pointer to an array of no less than 37 characters. + */ +void av_uuid_unparse(const AVUUID uu, char *out); + +/** + * Compares two UUIDs for equality. + * + * @param[in] uu1 AVUUID + * @param[in] uu2 AVUUID + * @return Nonzero if uu1 and uu2 are identical, 0 otherwise + */ +static inline int av_uuid_equal(const AVUUID uu1, const AVUUID uu2) +{ + return memcmp(uu1, uu2, AV_UUID_LEN) == 0; +} + +/** + * Copies the bytes of src into dest. + * + * @param[out] dest AVUUID + * @param[in] src AVUUID + */ +static inline void av_uuid_copy(AVUUID dest, const AVUUID src) +{ + memcpy(dest, src, AV_UUID_LEN); +} + +/** + * Sets a UUID to the nil UUID, i.e. a UUID with have all + * its 128 bits set to zero. + * + * @param[in,out] uu UUID to be set to the nil UUID + */ +static inline void av_uuid_nil(AVUUID uu) +{ + memset(uu, 0, AV_UUID_LEN); +} + +#endif /* AVUTIL_UUID_H */ diff --git a/ffmpeg-n8.1/include/libavutil/version.h b/ffmpeg-n8.1/include/libavutil/version.h new file mode 100644 index 00000000..5d69f445 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/version.h @@ -0,0 +1,123 @@ +/* + * copyright (c) 2003 Fabrice Bellard + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/** + * @file + * @ingroup lavu + * Libavutil version macros + */ + +#ifndef AVUTIL_VERSION_H +#define AVUTIL_VERSION_H + +#include "macros.h" + +/** + * @addtogroup version_utils + * + * Useful to check and match library version in order to maintain + * backward compatibility. + * + * The FFmpeg libraries follow a versioning scheme very similar to + * Semantic Versioning (http://semver.org/) + * The difference is that the component called PATCH is called MICRO in FFmpeg + * and its value is reset to 100 instead of 0 to keep it above or equal to 100. + * Also we do not increase MICRO for every bugfix or change in git master. + * + * Prior to FFmpeg 3.2 point releases did not change any lib version number to + * avoid aliassing different git master checkouts. + * Starting with FFmpeg 3.2, the released library versions will occupy + * a separate MAJOR.MINOR that is not used on the master development branch. + * That is if we branch a release of master 55.10.123 we will bump to 55.11.100 + * for the release and master will continue at 55.12.100 after it. Each new + * point release will then bump the MICRO improving the usefulness of the lib + * versions. + * + * @{ + */ + +#define AV_VERSION_INT(a, b, c) ((a)<<16 | (b)<<8 | (c)) +#define AV_VERSION_DOT(a, b, c) a ##.## b ##.## c +#define AV_VERSION(a, b, c) AV_VERSION_DOT(a, b, c) + +/** + * Extract version components from the full ::AV_VERSION_INT int as returned + * by functions like ::avformat_version() and ::avcodec_version() + */ +#define AV_VERSION_MAJOR(a) ((a) >> 16) +#define AV_VERSION_MINOR(a) (((a) & 0x00FF00) >> 8) +#define AV_VERSION_MICRO(a) ((a) & 0xFF) + +/** + * @} + */ + +/** + * @defgroup lavu_ver Version and Build diagnostics + * + * Macros and function useful to check at compile time and at runtime + * which version of libavutil is in use. + * + * @{ + */ + +#define LIBAVUTIL_VERSION_MAJOR 60 +#define LIBAVUTIL_VERSION_MINOR 26 +#define LIBAVUTIL_VERSION_MICRO 100 + +#define LIBAVUTIL_VERSION_INT AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \ + LIBAVUTIL_VERSION_MINOR, \ + LIBAVUTIL_VERSION_MICRO) +#define LIBAVUTIL_VERSION AV_VERSION(LIBAVUTIL_VERSION_MAJOR, \ + LIBAVUTIL_VERSION_MINOR, \ + LIBAVUTIL_VERSION_MICRO) +#define LIBAVUTIL_BUILD LIBAVUTIL_VERSION_INT + +#define LIBAVUTIL_IDENT "Lavu" AV_STRINGIFY(LIBAVUTIL_VERSION) + +/** + * @defgroup lavu_depr_guards Deprecation Guards + * FF_API_* defines may be placed below to indicate public API that will be + * dropped at a future version bump. The defines themselves are not part of + * the public API and may change, break or disappear at any time. + * + * @note, when bumping the major version it is recommended to manually + * disable each FF_API_* in its own commit instead of disabling them all + * at once through the bump. This improves the git bisect-ability of the change. + * + * @{ + */ + +#define FF_API_MOD_UINTP2 (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_RISCV_FD_ZBA (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_VULKAN_FIXED_QUEUES (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_OPT_INT_LIST (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_OPT_PTR (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_CPU_FLAG_FORCE (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_DOVI_L11_INVALID_PROPS (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_ASSERT_FPU (LIBAVUTIL_VERSION_MAJOR < 61) +#define FF_API_VULKAN_SYNC_QUEUES (LIBAVUTIL_VERSION_MAJOR < 62) + +/** + * @} + * @} + */ + +#endif /* AVUTIL_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libavutil/video_enc_params.h b/ffmpeg-n8.1/include/libavutil/video_enc_params.h new file mode 100644 index 00000000..62265a5c --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/video_enc_params.h @@ -0,0 +1,171 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_VIDEO_ENC_PARAMS_H +#define AVUTIL_VIDEO_ENC_PARAMS_H + +#include +#include + +#include "libavutil/avassert.h" +#include "libavutil/frame.h" + +enum AVVideoEncParamsType { + AV_VIDEO_ENC_PARAMS_NONE = -1, + /** + * VP9 stores: + * - per-frame base (luma AC) quantizer index, exported as AVVideoEncParams.qp + * - deltas for luma DC, chroma AC and chroma DC, exported in the + * corresponding entries in AVVideoEncParams.delta_qp + * - per-segment delta, exported as for each block as AVVideoBlockParams.delta_qp + * + * To compute the resulting quantizer index for a block: + * - for luma AC, add the base qp and the per-block delta_qp, saturating to + * unsigned 8-bit. + * - for luma DC and chroma AC/DC, add the corresponding + * AVVideoBlockParams.delta_qp to the luma AC index, again saturating to + * unsigned 8-bit. + */ + AV_VIDEO_ENC_PARAMS_VP9, + + /** + * H.264 stores: + * - in PPS (per-picture): + * * initial QP_Y (luma) value, exported as AVVideoEncParams.qp + * * delta(s) for chroma QP values (same for both, or each separately), + * exported as in the corresponding entries in AVVideoEncParams.delta_qp + * - per-slice QP delta, not exported directly, added to the per-MB value + * - per-MB delta; not exported directly; the final per-MB quantizer + * parameter - QP_Y - minus the value in AVVideoEncParams.qp is exported + * as AVVideoBlockParams.qp_delta. + */ + AV_VIDEO_ENC_PARAMS_H264, + + /* + * MPEG-2-compatible quantizer. + * + * Summing the frame-level qp with the per-block delta_qp gives the + * resulting quantizer for the block. + */ + AV_VIDEO_ENC_PARAMS_MPEG2, +}; + +/** + * Video encoding parameters for a given frame. This struct is allocated along + * with an optional array of per-block AVVideoBlockParams descriptors. + * Must be allocated with av_video_enc_params_alloc(). + */ +typedef struct AVVideoEncParams { + /** + * Number of blocks in the array. + * + * May be 0, in which case no per-block information is present. In this case + * the values of blocks_offset / block_size are unspecified and should not + * be accessed. + */ + unsigned int nb_blocks; + /** + * Offset in bytes from the beginning of this structure at which the array + * of blocks starts. + */ + size_t blocks_offset; + /* + * Size of each block in bytes. May not match sizeof(AVVideoBlockParams). + */ + size_t block_size; + + /** + * Type of the parameters (the codec they are used with). + */ + enum AVVideoEncParamsType type; + + /** + * Base quantisation parameter for the frame. The final quantiser for a + * given block in a given plane is obtained from this value, possibly + * combined with {@code delta_qp} and the per-block delta in a manner + * documented for each type. + */ + int32_t qp; + + /** + * Quantisation parameter offset from the base (per-frame) qp for a given + * plane (first index) and AC/DC coefficients (second index). + */ + int32_t delta_qp[4][2]; +} AVVideoEncParams; + +/** + * Data structure for storing block-level encoding information. + * It is allocated as a part of AVVideoEncParams and should be retrieved with + * av_video_enc_params_block(). + * + * sizeof(AVVideoBlockParams) is not a part of the ABI and new fields may be + * added to it. + */ +typedef struct AVVideoBlockParams { + /** + * Distance in luma pixels from the top-left corner of the visible frame + * to the top-left corner of the block. + * Can be negative if top/right padding is present on the coded frame. + */ + int src_x, src_y; + /** + * Width and height of the block in luma pixels. + */ + int w, h; + + /** + * Difference between this block's final quantization parameter and the + * corresponding per-frame value. + */ + int32_t delta_qp; +} AVVideoBlockParams; + +/** + * Get the block at the specified {@code idx}. Must be between 0 and nb_blocks - 1. + */ +static av_always_inline AVVideoBlockParams* +av_video_enc_params_block(AVVideoEncParams *par, unsigned int idx) +{ + av_assert0(idx < par->nb_blocks); + return (AVVideoBlockParams *)((uint8_t *)par + par->blocks_offset + + idx * par->block_size); +} + +/** + * Allocates memory for AVVideoEncParams of the given type, plus an array of + * {@code nb_blocks} AVVideoBlockParams and initializes the variables. Can be + * freed with a normal av_free() call. + * + * @param out_size if non-NULL, the size in bytes of the resulting data array is + * written here. + */ +AVVideoEncParams *av_video_enc_params_alloc(enum AVVideoEncParamsType type, + unsigned int nb_blocks, size_t *out_size); + +/** + * Allocates memory for AVEncodeInfoFrame plus an array of + * {@code nb_blocks} AVEncodeInfoBlock in the given AVFrame {@code frame} + * as AVFrameSideData of type AV_FRAME_DATA_VIDEO_ENC_PARAMS + * and initializes the variables. + */ +AVVideoEncParams* +av_video_enc_params_create_side_data(AVFrame *frame, enum AVVideoEncParamsType type, + unsigned int nb_blocks); + +#endif /* AVUTIL_VIDEO_ENC_PARAMS_H */ diff --git a/ffmpeg-n8.1/include/libavutil/video_hint.h b/ffmpeg-n8.1/include/libavutil/video_hint.h new file mode 100644 index 00000000..8e8af0ae --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/video_hint.h @@ -0,0 +1,107 @@ +/** + * Copyright 2023 Elias Carotti + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_VIDEO_HINT_H +#define AVUTIL_VIDEO_HINT_H + +#include +#include +#include "libavutil/avassert.h" +#include "libavutil/frame.h" + +typedef struct AVVideoRect { + uint32_t x, y; + uint32_t width, height; +} AVVideoRect; + +typedef enum AVVideoHintType { + /* rectangled delimit the constant areas (unchanged), default is changed */ + AV_VIDEO_HINT_TYPE_CONSTANT, + + /* rectangled delimit the constant areas (changed), default is not changed */ + AV_VIDEO_HINT_TYPE_CHANGED, +} AVVideoHintType; + +typedef struct AVVideoHint { + /** + * Number of AVVideoRect present. + * + * May be 0, in which case no per-rectangle information is present. In this + * case the values of rect_offset / rect_size are unspecified and should + * not be accessed. + */ + size_t nb_rects; + + /** + * Offset in bytes from the beginning of this structure at which the array + * of AVVideoRect starts. + */ + size_t rect_offset; + + /** + * Size in bytes of AVVideoRect. + */ + size_t rect_size; + + AVVideoHintType type; +} AVVideoHint; + +static av_always_inline AVVideoRect * +av_video_hint_rects(const AVVideoHint *hints) { + return (AVVideoRect *)((uint8_t *)hints + hints->rect_offset); +} + +static av_always_inline AVVideoRect * +av_video_hint_get_rect(const AVVideoHint *hints, size_t idx) { + return (AVVideoRect *)((uint8_t *)hints + hints->rect_offset + idx * hints->rect_size); +} + +/** + * Allocate memory for the AVVideoHint struct along with an nb_rects-sized + * arrays of AVVideoRect. + * + * The side data contains a list of rectangles for the portions of the frame + * which changed from the last encoded one (and the remainder are assumed to be + * changed), or, alternately (depending on the type parameter) the unchanged + * ones (and the remaining ones are those which changed). + * Macroblocks will thus be hinted either to be P_SKIP-ped or go through the + * regular encoding procedure. + * + * It's responsibility of the caller to fill the AVRects accordingly, and to set + * the proper AVVideoHintType field. + * + * @param out_size if non-NULL, the size in bytes of the resulting data array is + * written here + * + * @return newly allocated AVVideoHint struct (must be freed by the caller using + * av_free()) on success, NULL on memory allocation failure + */ +AVVideoHint *av_video_hint_alloc(size_t nb_rects, + size_t *out_size); + +/** + * Same as av_video_hint_alloc(), except newly-allocated AVVideoHint is attached + * as side data of type AV_FRAME_DATA_VIDEO_HINT_INFO to frame. + */ +AVVideoHint *av_video_hint_create_side_data(AVFrame *frame, + size_t nb_rects); + + +#endif /* AVUTIL_VIDEO_HINT_H */ diff --git a/ffmpeg-n8.1/include/libavutil/xtea.h b/ffmpeg-n8.1/include/libavutil/xtea.h new file mode 100644 index 00000000..735427c1 --- /dev/null +++ b/ffmpeg-n8.1/include/libavutil/xtea.h @@ -0,0 +1,94 @@ +/* + * A 32-bit implementation of the XTEA algorithm + * Copyright (c) 2012 Samuel Pitoiset + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVUTIL_XTEA_H +#define AVUTIL_XTEA_H + +#include + +/** + * @file + * @brief Public header for libavutil XTEA algorithm + * @defgroup lavu_xtea XTEA + * @ingroup lavu_crypto + * @{ + */ + +typedef struct AVXTEA { + uint32_t key[16]; +} AVXTEA; + +/** + * Allocate an AVXTEA context. + */ +AVXTEA *av_xtea_alloc(void); + +/** + * Initialize an AVXTEA context. + * + * @param ctx an AVXTEA context + * @param key a key of 16 bytes used for encryption/decryption, + * interpreted as big endian 32 bit numbers + */ +void av_xtea_init(struct AVXTEA *ctx, const uint8_t key[16]); + +/** + * Initialize an AVXTEA context. + * + * @param ctx an AVXTEA context + * @param key a key of 16 bytes used for encryption/decryption, + * interpreted as little endian 32 bit numbers + */ +void av_xtea_le_init(struct AVXTEA *ctx, const uint8_t key[16]); + +/** + * Encrypt or decrypt a buffer using a previously initialized context, + * in big endian format. + * + * @param ctx an AVXTEA context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 8 byte blocks + * @param iv initialization vector for CBC mode, if NULL then ECB will be used + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_xtea_crypt(struct AVXTEA *ctx, uint8_t *dst, const uint8_t *src, + int count, uint8_t *iv, int decrypt); + +/** + * Encrypt or decrypt a buffer using a previously initialized context, + * in little endian format. + * + * @param ctx an AVXTEA context + * @param dst destination array, can be equal to src + * @param src source array, can be equal to dst + * @param count number of 8 byte blocks + * @param iv initialization vector for CBC mode, if NULL then ECB will be used + * @param decrypt 0 for encryption, 1 for decryption + */ +void av_xtea_le_crypt(struct AVXTEA *ctx, uint8_t *dst, const uint8_t *src, + int count, uint8_t *iv, int decrypt); + +/** + * @} + */ + +#endif /* AVUTIL_XTEA_H */ diff --git a/ffmpeg-n8.1/include/libswresample/swresample.h b/ffmpeg-n8.1/include/libswresample/swresample.h new file mode 100644 index 00000000..052089ac --- /dev/null +++ b/ffmpeg-n8.1/include/libswresample/swresample.h @@ -0,0 +1,587 @@ +/* + * Copyright (C) 2011-2013 Michael Niedermayer (michaelni@gmx.at) + * + * This file is part of libswresample + * + * libswresample 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. + * + * libswresample 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 libswresample; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SWRESAMPLE_SWRESAMPLE_H +#define SWRESAMPLE_SWRESAMPLE_H + +/** + * @file + * @ingroup lswr + * libswresample public header + */ + +/** + * @defgroup lswr libswresample + * @{ + * + * Audio resampling, sample format conversion and mixing library. + * + * Interaction with lswr is done through SwrContext, which is + * allocated with swr_alloc() or swr_alloc_set_opts2(). It is opaque, so all parameters + * must be set with the @ref avoptions API. + * + * The first thing you will need to do in order to use lswr is to allocate + * SwrContext. This can be done with swr_alloc() or swr_alloc_set_opts2(). If you + * are using the former, you must set options through the @ref avoptions API. + * The latter function provides the same feature, but it allows you to set some + * common options in the same statement. + * + * For example the following code will setup conversion from planar float sample + * format to interleaved signed 16-bit integer, downsampling from 48kHz to + * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing + * matrix). This is using the swr_alloc() function. + * @code + * SwrContext *swr = swr_alloc(); + * av_opt_set_chlayout(swr, "in_chlayout", &(AVChannelLayout)AV_CHANNEL_LAYOUT_5POINT1, 0); + * av_opt_set_chlayout(swr, "out_chlayout", &(AVChannelLayout)AV_CHANNEL_LAYOUT_STEREO, 0); + * av_opt_set_int(swr, "in_sample_rate", 48000, 0); + * av_opt_set_int(swr, "out_sample_rate", 44100, 0); + * av_opt_set_sample_fmt(swr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0); + * av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0); + * @endcode + * + * The same job can be done using swr_alloc_set_opts2() as well: + * @code + * SwrContext *swr = NULL; + * int ret = swr_alloc_set_opts2(&swr, // we're allocating a new context + * &(AVChannelLayout)AV_CHANNEL_LAYOUT_STEREO, // out_ch_layout + * AV_SAMPLE_FMT_S16, // out_sample_fmt + * 44100, // out_sample_rate + * &(AVChannelLayout)AV_CHANNEL_LAYOUT_5POINT1, // in_ch_layout + * AV_SAMPLE_FMT_FLTP, // in_sample_fmt + * 48000, // in_sample_rate + * 0, // log_offset + * NULL); // log_ctx + * @endcode + * + * Once all values have been set, it must be initialized with swr_init(). If + * you need to change the conversion parameters, you can change the parameters + * using @ref avoptions, as described above in the first example; or by using + * swr_alloc_set_opts2(), but with the first argument the allocated context. + * You must then call swr_init() again. + * + * The conversion itself is done by repeatedly calling swr_convert(). + * Note that the samples may get buffered in swr if you provide insufficient + * output space or if sample rate conversion is done, which requires "future" + * samples. Samples that do not require future input can be retrieved at any + * time by using swr_convert() (in_count can be set to 0). + * At the end of conversion the resampling buffer can be flushed by calling + * swr_convert() with NULL in and 0 in_count. + * + * The samples used in the conversion process can be managed with the libavutil + * @ref lavu_sampmanip "samples manipulation" API, including av_samples_alloc() + * function used in the following example. + * + * The delay between input and output, can at any time be found by using + * swr_get_delay(). + * + * The following code demonstrates the conversion loop assuming the parameters + * from above and caller-defined functions get_input() and handle_output(): + * @code + * uint8_t **input; + * int in_samples; + * + * while (get_input(&input, &in_samples)) { + * uint8_t *output; + * int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) + + * in_samples, 44100, 48000, AV_ROUND_UP); + * av_samples_alloc(&output, NULL, 2, out_samples, + * AV_SAMPLE_FMT_S16, 0); + * out_samples = swr_convert(swr, &output, out_samples, + * input, in_samples); + * handle_output(output, out_samples); + * av_freep(&output); + * } + * @endcode + * + * When the conversion is finished, the conversion + * context and everything associated with it must be freed with swr_free(). + * A swr_close() function is also available, but it exists mainly for + * compatibility with libavresample, and is not required to be called. + * + * There will be no memory leak if the data is not completely flushed before + * swr_free(). + */ + +#include +#include "libavutil/channel_layout.h" +#include "libavutil/frame.h" +#include "libavutil/samplefmt.h" + +#include "libswresample/version_major.h" +#ifndef HAVE_AV_CONFIG_H +/* When included as part of the ffmpeg build, only include the major version + * to avoid unnecessary rebuilds. When included externally, keep including + * the full version information. */ +#include "libswresample/version.h" +#endif + +/** + * @name Option constants + * These constants are used for the @ref avoptions interface for lswr. + * @{ + * + */ + +#define SWR_FLAG_RESAMPLE 1 ///< Force resampling even if equal sample rate +//TODO use int resample ? +//long term TODO can we enable this dynamically? + +/** Dithering algorithms */ +enum SwrDitherType { + SWR_DITHER_NONE = 0, + SWR_DITHER_RECTANGULAR, + SWR_DITHER_TRIANGULAR, + SWR_DITHER_TRIANGULAR_HIGHPASS, + + SWR_DITHER_NS = 64, ///< not part of API/ABI + SWR_DITHER_NS_LIPSHITZ, + SWR_DITHER_NS_F_WEIGHTED, + SWR_DITHER_NS_MODIFIED_E_WEIGHTED, + SWR_DITHER_NS_IMPROVED_E_WEIGHTED, + SWR_DITHER_NS_SHIBATA, + SWR_DITHER_NS_LOW_SHIBATA, + SWR_DITHER_NS_HIGH_SHIBATA, + SWR_DITHER_NB, ///< not part of API/ABI +}; + +/** Resampling Engines */ +enum SwrEngine { + SWR_ENGINE_SWR, /**< SW Resampler */ + SWR_ENGINE_SOXR, /**< SoX Resampler */ + SWR_ENGINE_NB, ///< not part of API/ABI +}; + +/** Resampling Filter Types */ +enum SwrFilterType { + SWR_FILTER_TYPE_CUBIC, /**< Cubic */ + SWR_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall windowed sinc */ + SWR_FILTER_TYPE_KAISER, /**< Kaiser windowed sinc */ +}; + +/** + * @} + */ + +/** + * The libswresample context. Unlike libavcodec and libavformat, this structure + * is opaque. This means that if you would like to set options, you must use + * the @ref avoptions API and cannot directly set values to members of the + * structure. + */ +typedef struct SwrContext SwrContext; + +/** + * Get the AVClass for SwrContext. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + * @return the AVClass of SwrContext + */ +const AVClass *swr_get_class(void); + +/** + * @name SwrContext constructor functions + * @{ + */ + +/** + * Allocate SwrContext. + * + * If you use this function you will need to set the parameters (manually or + * with swr_alloc_set_opts2()) before calling swr_init(). + * + * @see swr_alloc_set_opts2(), swr_init(), swr_free() + * @return NULL on error, allocated context otherwise + */ +struct SwrContext *swr_alloc(void); + +/** + * Initialize context after user parameters have been set. + * @note The context must be configured using the AVOption API. + * + * @see av_opt_set_int() + * @see av_opt_set_dict() + * + * @param[in,out] s Swr context to initialize + * @return AVERROR error code in case of failure. + */ +int swr_init(struct SwrContext *s); + +/** + * Check whether an swr context has been initialized or not. + * + * @param[in] s Swr context to check + * @see swr_init() + * @return positive if it has been initialized, 0 if not initialized + */ +int swr_is_initialized(struct SwrContext *s); + +/** + * Allocate SwrContext if needed and set/reset common parameters. + * + * This function does not require *ps to be allocated with swr_alloc(). On the + * other hand, swr_alloc() can use swr_alloc_set_opts2() to set the parameters + * on the allocated context. + * + * @param ps Pointer to an existing Swr context if available, or to NULL if not. + * On success, *ps will be set to the allocated context. + * @param out_ch_layout output channel layout (e.g. AV_CHANNEL_LAYOUT_*) + * @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*). + * @param out_sample_rate output sample rate (frequency in Hz) + * @param in_ch_layout input channel layout (e.g. AV_CHANNEL_LAYOUT_*) + * @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*). + * @param in_sample_rate input sample rate (frequency in Hz) + * @param log_offset logging level offset + * @param log_ctx parent logging context, can be NULL + * + * @see swr_init(), swr_free() + * @return 0 on success, a negative AVERROR code on error. + * On error, the Swr context is freed and *ps set to NULL. + */ +int swr_alloc_set_opts2(struct SwrContext **ps, + const AVChannelLayout *out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate, + const AVChannelLayout *in_ch_layout, enum AVSampleFormat in_sample_fmt, int in_sample_rate, + int log_offset, void *log_ctx); +/** + * @} + * + * @name SwrContext destructor functions + * @{ + */ + +/** + * Free the given SwrContext and set the pointer to NULL. + * + * @param[in] s a pointer to a pointer to Swr context + */ +void swr_free(struct SwrContext **s); + +/** + * Closes the context so that swr_is_initialized() returns 0. + * + * The context can be brought back to life by running swr_init(), + * swr_init() can also be used without swr_close(). + * This function is mainly provided for simplifying the usecase + * where one tries to support libavresample and libswresample. + * + * @param[in,out] s Swr context to be closed + */ +void swr_close(struct SwrContext *s); + +/** + * @} + * + * @name Core conversion functions + * @{ + */ + +/** Convert audio. + * + * in and in_count can be set to 0 to flush the last few samples out at the + * end. + * + * If more input is provided than output space, then the input will be buffered. + * You can avoid this buffering by using swr_get_out_samples() to retrieve an + * upper bound on the required number of output samples for the given number of + * input samples. Conversion will run directly without copying whenever possible. + * + * @param s allocated Swr context, with parameters set + * @param out output buffers, only the first one need be set in case of packed audio + * @param out_count amount of space available for output in samples per channel + * @param in input buffers, only the first one need to be set in case of packed audio + * @param in_count number of input samples available in one channel + * + * @return number of samples output per channel, negative value on error + */ +int swr_convert(struct SwrContext *s, uint8_t * const *out, int out_count, + const uint8_t * const *in , int in_count); + +/** + * Convert the next timestamp from input to output + * timestamps are in 1/(in_sample_rate * out_sample_rate) units. + * + * @note There are 2 slightly differently behaving modes. + * @li When automatic timestamp compensation is not used, (min_compensation >= FLT_MAX) + * in this case timestamps will be passed through with delays compensated + * @li When automatic timestamp compensation is used, (min_compensation < FLT_MAX) + * in this case the output timestamps will match output sample numbers. + * See ffmpeg-resampler(1) for the two modes of compensation. + * + * @param[in] s initialized Swr context + * @param[in] pts timestamp for the next input sample, INT64_MIN if unknown + * @see swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are + * function used internally for timestamp compensation. + * @return the output timestamp for the next output sample + */ +int64_t swr_next_pts(struct SwrContext *s, int64_t pts); + +/** + * @} + * + * @name Low-level option setting functions + * These functions provide a means to set low-level options that is not possible + * with the AVOption API. + * @{ + */ + +/** + * Activate resampling compensation ("soft" compensation). This function is + * internally called when needed in swr_next_pts(). + * + * @param[in,out] s allocated Swr context. If it is not initialized, + * or SWR_FLAG_RESAMPLE is not set, swr_init() is + * called with the flag set. + * @param[in] sample_delta delta in PTS per sample + * @param[in] compensation_distance number of samples to compensate for + * @return >= 0 on success, AVERROR error codes if: + * @li @c s is NULL, + * @li @c compensation_distance is less than 0, + * @li @c compensation_distance is 0 but sample_delta is not, + * @li compensation unsupported by resampler, or + * @li swr_init() fails when called. + */ +int swr_set_compensation(struct SwrContext *s, int sample_delta, int compensation_distance); + +/** + * Set a customized input channel mapping. + * + * @param[in,out] s allocated Swr context, not yet initialized + * @param[in] channel_map customized input channel mapping (array of channel + * indexes, -1 for a muted channel) + * @return >= 0 on success, or AVERROR error code in case of failure. + */ +int swr_set_channel_mapping(struct SwrContext *s, const int *channel_map); + +/** + * Generate a channel mixing matrix. + * + * This function is the one used internally by libswresample for building the + * default mixing matrix. It is made public just as a utility function for + * building custom matrices. + * + * @param in_layout input channel layout + * @param out_layout output channel layout + * @param center_mix_level mix level for the center channel + * @param surround_mix_level mix level for the surround channel(s) + * @param lfe_mix_level mix level for the low-frequency effects channel + * @param rematrix_maxval if 1.0, coefficients will be normalized to prevent + * overflow. if INT_MAX, coefficients will not be + * normalized. + * @param[out] matrix mixing coefficients; matrix[i + stride * o] is + * the weight of input channel i in output channel o. + * @param stride distance between adjacent input channels in the + * matrix array + * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii) + * @param log_ctx parent logging context, can be NULL + * @return 0 on success, negative AVERROR code on failure + */ +int swr_build_matrix2(const AVChannelLayout *in_layout, const AVChannelLayout *out_layout, + double center_mix_level, double surround_mix_level, + double lfe_mix_level, double maxval, + double rematrix_volume, double *matrix, + ptrdiff_t stride, enum AVMatrixEncoding matrix_encoding, + void *log_context); + +/** + * Set a customized remix matrix. + * + * @param s allocated Swr context, not yet initialized + * @param matrix remix coefficients; matrix[i + stride * o] is + * the weight of input channel i in output channel o + * @param stride offset between lines of the matrix + * @return >= 0 on success, or AVERROR error code in case of failure. + */ +int swr_set_matrix(struct SwrContext *s, const double *matrix, int stride); + +/** + * @} + * + * @name Sample handling functions + * @{ + */ + +/** + * Drops the specified number of output samples. + * + * This function, along with swr_inject_silence(), is called by swr_next_pts() + * if needed for "hard" compensation. + * + * @param s allocated Swr context + * @param count number of samples to be dropped + * + * @return >= 0 on success, or a negative AVERROR code on failure + */ +int swr_drop_output(struct SwrContext *s, int count); + +/** + * Injects the specified number of silence samples. + * + * This function, along with swr_drop_output(), is called by swr_next_pts() + * if needed for "hard" compensation. + * + * @param s allocated Swr context + * @param count number of samples to be dropped + * + * @return >= 0 on success, or a negative AVERROR code on failure + */ +int swr_inject_silence(struct SwrContext *s, int count); + +/** + * Gets the delay the next input sample will experience relative to the next output sample. + * + * Swresample can buffer data if more input has been provided than available + * output space, also converting between sample rates needs a delay. + * This function returns the sum of all such delays. + * The exact delay is not necessarily an integer value in either input or + * output sample rate. Especially when downsampling by a large value, the + * output sample rate may be a poor choice to represent the delay, similarly + * for upsampling and the input sample rate. + * + * @param s swr context + * @param base timebase in which the returned delay will be: + * @li if it's set to 1 the returned delay is in seconds + * @li if it's set to 1000 the returned delay is in milliseconds + * @li if it's set to the input sample rate then the returned + * delay is in input samples + * @li if it's set to the output sample rate then the returned + * delay is in output samples + * @li if it's the least common multiple of in_sample_rate and + * out_sample_rate then an exact rounding-free delay will be + * returned + * @returns the delay in 1 / @c base units. + */ +int64_t swr_get_delay(struct SwrContext *s, int64_t base); + +/** + * Find an upper bound on the number of samples that the next swr_convert + * call will output, if called with in_samples of input samples. This + * depends on the internal state, and anything changing the internal state + * (like further swr_convert() calls) will may change the number of samples + * swr_get_out_samples() returns for the same number of input samples. + * + * @param in_samples number of input samples. + * @note any call to swr_inject_silence(), swr_convert(), swr_next_pts() + * or swr_set_compensation() invalidates this limit + * @note it is recommended to pass the correct available buffer size + * to all functions like swr_convert() even if swr_get_out_samples() + * indicates that less would be used. + * @returns an upper bound on the number of samples that the next swr_convert + * will output or a negative value to indicate an error + */ +int swr_get_out_samples(struct SwrContext *s, int in_samples); + +/** + * @} + * + * @name Configuration accessors + * @{ + */ + +/** + * Return the @ref LIBSWRESAMPLE_VERSION_INT constant. + * + * This is useful to check if the build-time libswresample has the same version + * as the run-time one. + * + * @returns the unsigned int-typed version + */ +unsigned swresample_version(void); + +/** + * Return the swr build-time configuration. + * + * @returns the build-time @c ./configure flags + */ +const char *swresample_configuration(void); + +/** + * Return the swr license. + * + * @returns the license of libswresample, determined at build-time + */ +const char *swresample_license(void); + +/** + * @} + * + * @name AVFrame based API + * @{ + */ + +/** + * Convert the samples in the input AVFrame and write them to the output AVFrame. + * + * Input and output AVFrames must have channel_layout, sample_rate and format set. + * + * If the output AVFrame does not have the data pointers allocated the nb_samples + * field will be set using av_frame_get_buffer() + * is called to allocate the frame. + * + * The output AVFrame can be NULL or have fewer allocated samples than required. + * In this case, any remaining samples not written to the output will be added + * to an internal FIFO buffer, to be returned at the next call to this function + * or to swr_convert(). + * + * If converting sample rate, there may be data remaining in the internal + * resampling delay buffer. swr_get_delay() tells the number of + * remaining samples. To get this data as output, call this function or + * swr_convert() with NULL input. + * + * If the SwrContext configuration does not match the output and + * input AVFrame settings the conversion does not take place and depending on + * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED + * or the result of a bitwise-OR of them is returned. + * + * @see swr_delay() + * @see swr_convert() + * @see swr_get_delay() + * + * @param swr audio resample context + * @param output output AVFrame + * @param input input AVFrame + * @return 0 on success, AVERROR on failure or nonmatching + * configuration. + */ +int swr_convert_frame(SwrContext *swr, + AVFrame *output, const AVFrame *input); + +/** + * Configure or reconfigure the SwrContext using the information + * provided by the AVFrames. + * + * The original resampling context is reset even on failure. + * The function calls swr_close() internally if the context is open. + * + * @see swr_close(); + * + * @param swr audio resample context + * @param out output AVFrame + * @param in input AVFrame + * @return 0 on success, AVERROR on failure. + */ +int swr_config_frame(SwrContext *swr, const AVFrame *out, const AVFrame *in); + +/** + * @} + * @} + */ + +#endif /* SWRESAMPLE_SWRESAMPLE_H */ diff --git a/ffmpeg-n8.1/include/libswresample/version.h b/ffmpeg-n8.1/include/libswresample/version.h new file mode 100644 index 00000000..d1795b55 --- /dev/null +++ b/ffmpeg-n8.1/include/libswresample/version.h @@ -0,0 +1,46 @@ +/* + * Version macros. + * + * This file is part of libswresample + * + * libswresample 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. + * + * libswresample 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 libswresample; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SWRESAMPLE_VERSION_H +#define SWRESAMPLE_VERSION_H + +/** + * @file + * Libswresample version macros + */ + +#include "libavutil/version.h" + +#include "version_major.h" + +#define LIBSWRESAMPLE_VERSION_MINOR 3 +#define LIBSWRESAMPLE_VERSION_MICRO 100 + +#define LIBSWRESAMPLE_VERSION_INT AV_VERSION_INT(LIBSWRESAMPLE_VERSION_MAJOR, \ + LIBSWRESAMPLE_VERSION_MINOR, \ + LIBSWRESAMPLE_VERSION_MICRO) +#define LIBSWRESAMPLE_VERSION AV_VERSION(LIBSWRESAMPLE_VERSION_MAJOR, \ + LIBSWRESAMPLE_VERSION_MINOR, \ + LIBSWRESAMPLE_VERSION_MICRO) +#define LIBSWRESAMPLE_BUILD LIBSWRESAMPLE_VERSION_INT + +#define LIBSWRESAMPLE_IDENT "SwR" AV_STRINGIFY(LIBSWRESAMPLE_VERSION) + +#endif /* SWRESAMPLE_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libswresample/version_major.h b/ffmpeg-n8.1/include/libswresample/version_major.h new file mode 100644 index 00000000..4e0bc0ab --- /dev/null +++ b/ffmpeg-n8.1/include/libswresample/version_major.h @@ -0,0 +1,31 @@ +/* + * Version macros. + * + * This file is part of libswresample + * + * libswresample 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. + * + * libswresample 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 libswresample; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SWRESAMPLE_VERSION_MAJOR_H +#define SWRESAMPLE_VERSION_MAJOR_H + +/** + * @file + * Libswresample version macros + */ + +#define LIBSWRESAMPLE_VERSION_MAJOR 6 + +#endif /* SWRESAMPLE_VERSION_MAJOR_H */ diff --git a/ffmpeg-n8.1/include/libswscale/swscale.h b/ffmpeg-n8.1/include/libswscale/swscale.h new file mode 100644 index 00000000..1cfd4068 --- /dev/null +++ b/ffmpeg-n8.1/include/libswscale/swscale.h @@ -0,0 +1,700 @@ +/* + * Copyright (C) 2024 Niklas Haas + * Copyright (C) 2001-2011 Michael Niedermayer + * + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SWSCALE_SWSCALE_H +#define SWSCALE_SWSCALE_H + +/** + * @file + * @ingroup libsws + * external API header + */ + +#include + +#include "libavutil/avutil.h" +#include "libavutil/frame.h" +#include "libavutil/log.h" +#include "libavutil/pixfmt.h" +#include "version_major.h" +#ifndef HAVE_AV_CONFIG_H +/* When included as part of the ffmpeg build, only include the major version + * to avoid unnecessary rebuilds. When included externally, keep including + * the full version information. */ +#include "version.h" +#endif + +/** + * @defgroup libsws libswscale + * Color conversion and scaling library. + * + * @{ + * + * Return the LIBSWSCALE_VERSION_INT constant. + */ +unsigned swscale_version(void); + +/** + * Return the libswscale build-time configuration. + */ +const char *swscale_configuration(void); + +/** + * Return the libswscale license. + */ +const char *swscale_license(void); + +/** + * Get the AVClass for SwsContext. It can be used in combination with + * AV_OPT_SEARCH_FAKE_OBJ for examining options. + * + * @see av_opt_find(). + */ +const AVClass *sws_get_class(void); + +/****************************** + * Flags and quality settings * + ******************************/ + +typedef enum SwsDither { + SWS_DITHER_NONE = 0, /* disable dithering */ + SWS_DITHER_AUTO, /* auto-select from preset */ + SWS_DITHER_BAYER, /* ordered dither matrix */ + SWS_DITHER_ED, /* error diffusion */ + SWS_DITHER_A_DITHER, /* arithmetic addition */ + SWS_DITHER_X_DITHER, /* arithmetic xor */ + SWS_DITHER_NB, /* not part of the ABI */ + SWS_DITHER_MAX_ENUM = 0x7FFFFFFF, /* force size to 32 bits, not a valid dither type */ +} SwsDither; + +typedef enum SwsAlphaBlend { + SWS_ALPHA_BLEND_NONE = 0, + SWS_ALPHA_BLEND_UNIFORM, + SWS_ALPHA_BLEND_CHECKERBOARD, + SWS_ALPHA_BLEND_NB, /* not part of the ABI */ + SWS_ALPHA_BLEND_MAX_ENUM = 0x7FFFFFFF, /* force size to 32 bits, not a valid blend mode */ +} SwsAlphaBlend; + +typedef enum SwsFlags { + /** + * Scaler selection options. Only one may be active at a time. + */ + SWS_FAST_BILINEAR = 1 << 0, ///< fast bilinear filtering + SWS_BILINEAR = 1 << 1, ///< bilinear filtering + SWS_BICUBIC = 1 << 2, ///< 2-tap cubic B-spline + SWS_X = 1 << 3, ///< experimental + SWS_POINT = 1 << 4, ///< nearest neighbor + SWS_AREA = 1 << 5, ///< area averaging + SWS_BICUBLIN = 1 << 6, ///< bicubic luma, bilinear chroma + SWS_GAUSS = 1 << 7, ///< gaussian approximation + SWS_SINC = 1 << 8, ///< unwindowed sinc + SWS_LANCZOS = 1 << 9, ///< 3-tap sinc/sinc + SWS_SPLINE = 1 << 10, ///< cubic Keys spline + + /** + * Return an error on underspecified conversions. Without this flag, + * unspecified fields are defaulted to sensible values. + */ + SWS_STRICT = 1 << 11, + + /** + * Emit verbose log of scaling parameters. + */ + SWS_PRINT_INFO = 1 << 12, + + /** + * Perform full chroma upsampling when upscaling to RGB. + * + * For example, when converting 50x50 yuv420p to 100x100 rgba, setting this flag + * will scale the chroma plane from 25x25 to 100x100 (4:4:4), and then convert + * the 100x100 yuv444p image to rgba in the final output step. + * + * Without this flag, the chroma plane is instead scaled to 50x100 (4:2:2), + * with a single chroma sample being reused for both of the horizontally + * adjacent RGBA output pixels. + */ + SWS_FULL_CHR_H_INT = 1 << 13, + + /** + * Perform full chroma interpolation when downscaling RGB sources. + * + * For example, when converting a 100x100 rgba source to 50x50 yuv444p, setting + * this flag will generate a 100x100 (4:4:4) chroma plane, which is then + * downscaled to the required 50x50. + * + * Without this flag, the chroma plane is instead generated at 50x100 (dropping + * every other pixel), before then being downscaled to the required 50x50 + * resolution. + */ + SWS_FULL_CHR_H_INP = 1 << 14, + + /** + * Force bit-exact output. This will prevent the use of platform-specific + * optimizations that may lead to slight difference in rounding, in favor + * of always maintaining exact bit output compatibility with the reference + * C code. + * + * Note: It is recommended to set both of these flags simultaneously. + */ + SWS_ACCURATE_RND = 1 << 18, + SWS_BITEXACT = 1 << 19, + + /** + * Allow using experimental new code paths. This may be faster, slower, + * or produce different output, with semantics subject to change at any + * point in time. For testing and debugging purposes only. + */ + SWS_UNSTABLE = 1 << 20, + + /** + * Deprecated flags. + */ + SWS_DIRECT_BGR = 1 << 15, ///< This flag has no effect + SWS_ERROR_DIFFUSION = 1 << 23, ///< Set `SwsContext.dither` instead +} SwsFlags; + +typedef enum SwsIntent { + SWS_INTENT_PERCEPTUAL = 0, ///< Perceptual tone mapping + SWS_INTENT_RELATIVE_COLORIMETRIC = 1, ///< Relative colorimetric clipping + SWS_INTENT_SATURATION = 2, ///< Saturation mapping + SWS_INTENT_ABSOLUTE_COLORIMETRIC = 3, ///< Absolute colorimetric clipping + SWS_INTENT_NB, ///< not part of the ABI +} SwsIntent; + +/*********************************** + * Context creation and management * + ***********************************/ + +/** + * Main external API structure. New fields can be added to the end with + * minor version bumps. Removal, reordering and changes to existing fields + * require a major version bump. sizeof(SwsContext) is not part of the ABI. + */ +typedef struct SwsContext { + const AVClass *av_class; + + /** + * Private data of the user, can be used to carry app specific stuff. + */ + void *opaque; + + /** + * Bitmask of SWS_*. See `SwsFlags` for details. + */ + unsigned flags; + + /** + * Extra parameters for fine-tuning certain scalers. + */ + double scaler_params[2]; + + /** + * How many threads to use for processing, or 0 for automatic selection. + */ + int threads; + + /** + * Dither mode. + */ + SwsDither dither; + + /** + * Alpha blending mode. See `SwsAlphaBlend` for details. + */ + SwsAlphaBlend alpha_blend; + + /** + * Use gamma correct scaling. + */ + int gamma_flag; + + /** + * Deprecated frame property overrides, for the legacy API only. + * + * Ignored by sws_scale_frame() when used in dynamic mode, in which + * case all properties are instead taken from the frame directly. + */ + int src_w, src_h; ///< Width and height of the source frame + int dst_w, dst_h; ///< Width and height of the destination frame + int src_format; ///< Source pixel format + int dst_format; ///< Destination pixel format + int src_range; ///< Source is full range + int dst_range; ///< Destination is full range + int src_v_chr_pos; ///< Source vertical chroma position in luma grid / 256 + int src_h_chr_pos; ///< Source horizontal chroma position + int dst_v_chr_pos; ///< Destination vertical chroma position + int dst_h_chr_pos; ///< Destination horizontal chroma position + + /** + * Desired ICC intent for color space conversions. + */ + int intent; + + /* Remember to add new fields to graph.c:opts_equal() */ +} SwsContext; + +/** + * Allocate an empty SwsContext and set its fields to default values. + */ +SwsContext *sws_alloc_context(void); + +/** + * Free the context and everything associated with it, and write NULL + * to the provided pointer. + */ +void sws_free_context(SwsContext **ctx); + +/*************************** + * Supported frame formats * + ***************************/ + +/** + * Test if a given (software) pixel format is supported. + * + * @param output If 0, test if compatible with the source/input frame; + * otherwise, with the destination/output frame. + * @param format The format to check. + * + * @return A positive integer if supported, 0 otherwise. + */ +int sws_test_format(enum AVPixelFormat format, int output); + +/** + * Test if a given hardware pixel format is supported. + * + * @param format The hardware format to check, or AV_PIX_FMT_NONE. + * + * @return A positive integer if supported or AV_PIX_FMT_NONE, 0 otherwise. + */ +int sws_test_hw_format(enum AVPixelFormat format); + +/** + * Test if a given color space is supported. + * + * @param output If 0, test if compatible with the source/input frame; + * otherwise, with the destination/output frame. + * @param colorspace The colorspace to check. + * + * @return A positive integer if supported, 0 otherwise. + */ +int sws_test_colorspace(enum AVColorSpace colorspace, int output); + +/** + * Test if a given set of color primaries is supported. + * + * @param output If 0, test if compatible with the source/input frame; + * otherwise, with the destination/output frame. + * @param primaries The color primaries to check. + * + * @return A positive integer if supported, 0 otherwise. + */ +int sws_test_primaries(enum AVColorPrimaries primaries, int output); + +/** + * Test if a given color transfer function is supported. + * + * @param output If 0, test if compatible with the source/input frame; + * otherwise, with the destination/output frame. + * @param trc The color transfer function to check. + * + * @return A positive integer if supported, 0 otherwise. + */ +int sws_test_transfer(enum AVColorTransferCharacteristic trc, int output); + +/** + * Helper function to run all sws_test_* against a frame, as well as testing + * the basic frame properties for sanity. Ignores irrelevant properties - for + * example, AVColorSpace is not checked for RGB frames. + */ +int sws_test_frame(const AVFrame *frame, int output); + +/** + * Like `sws_scale_frame`, but without actually scaling. It will instead + * merely initialize internal state that *would* be required to perform the + * operation, as well as returning the correct error code for unsupported + * frame combinations. + * + * @param ctx The scaling context. + * @param dst The destination frame to consider. + * @param src The source frame to consider. + * @return 0 on success, a negative AVERROR code on failure. + */ +int sws_frame_setup(SwsContext *ctx, const AVFrame *dst, const AVFrame *src); + +/******************** + * Main scaling API * + ********************/ + +/** + * Check if a given conversion is a noop. Returns a positive integer if + * no operation needs to be performed, 0 otherwise. + */ +int sws_is_noop(const AVFrame *dst, const AVFrame *src); + +/** + * Scale source data from `src` and write the output to `dst`. + * + * This function can be used directly on an allocated context, without setting + * up any frame properties or calling `sws_init_context()`. Such usage is fully + * dynamic and does not require reallocation if the frame properties change. + * + * Alternatively, this function can be called on a context that has been + * explicitly initialized. However, this is provided only for backwards + * compatibility. In this usage mode, all frame properties must be correctly + * set at init time, and may no longer change after initialization. + * + * @param ctx The scaling context. + * @param dst The destination frame. The data buffers may either be already + * allocated by the caller or left clear, in which case they will + * be allocated by the scaler. The latter may have performance + * advantages - e.g. in certain cases some (or all) output planes + * may be references to input planes, rather than copies. + * @param src The source frame. If the data buffers are set to NULL, then + * this function behaves identically to `sws_frame_setup`. + * @return >= 0 on success, a negative AVERROR code on failure. + */ +int sws_scale_frame(SwsContext *c, AVFrame *dst, const AVFrame *src); + +/************************* + * Legacy (stateful) API * + *************************/ + +#define SWS_SRC_V_CHR_DROP_MASK 0x30000 +#define SWS_SRC_V_CHR_DROP_SHIFT 16 + +#define SWS_PARAM_DEFAULT 123456 + +#define SWS_MAX_REDUCE_CUTOFF 0.002 + +#define SWS_CS_ITU709 1 +#define SWS_CS_FCC 4 +#define SWS_CS_ITU601 5 +#define SWS_CS_ITU624 5 +#define SWS_CS_SMPTE170M 5 +#define SWS_CS_SMPTE240M 7 +#define SWS_CS_DEFAULT 5 +#define SWS_CS_BT2020 9 + +/** + * Return a pointer to yuv<->rgb coefficients for the given colorspace + * suitable for sws_setColorspaceDetails(). + * + * @param colorspace One of the SWS_CS_* macros. If invalid, + * SWS_CS_DEFAULT is used. + */ +const int *sws_getCoefficients(int colorspace); + +// when used for filters they must have an odd number of elements +// coeffs cannot be shared between vectors +typedef struct SwsVector { + double *coeff; ///< pointer to the list of coefficients + int length; ///< number of coefficients in the vector +} SwsVector; + +// vectors can be shared +typedef struct SwsFilter { + SwsVector *lumH; + SwsVector *lumV; + SwsVector *chrH; + SwsVector *chrV; +} SwsFilter; + +/** + * Return a positive value if pix_fmt is a supported input format, 0 + * otherwise. + */ +int sws_isSupportedInput(enum AVPixelFormat pix_fmt); + +/** + * Return a positive value if pix_fmt is a supported output format, 0 + * otherwise. + */ +int sws_isSupportedOutput(enum AVPixelFormat pix_fmt); + +/** + * @param[in] pix_fmt the pixel format + * @return a positive value if an endianness conversion for pix_fmt is + * supported, 0 otherwise. + */ +int sws_isSupportedEndiannessConversion(enum AVPixelFormat pix_fmt); + +/** + * Initialize the swscaler context sws_context. + * + * This function is considered deprecated, and provided only for backwards + * compatibility with sws_scale() and sws_frame_start(). The preferred way to + * use libswscale is to set all frame properties correctly and call + * sws_scale_frame() directly, without explicitly initializing the context. + * + * @return zero or positive value on success, a negative value on + * error + */ +av_warn_unused_result +int sws_init_context(SwsContext *sws_context, SwsFilter *srcFilter, SwsFilter *dstFilter); + +/** + * Free the swscaler context swsContext. + * If swsContext is NULL, then does nothing. + */ +void sws_freeContext(SwsContext *swsContext); + +/** + * Allocate and return an SwsContext. You need it to perform + * scaling/conversion operations using sws_scale(). + * + * @param srcW the width of the source image + * @param srcH the height of the source image + * @param srcFormat the source image format + * @param dstW the width of the destination image + * @param dstH the height of the destination image + * @param dstFormat the destination image format + * @param flags specify which algorithm and options to use for rescaling + * @param param extra parameters to tune the used scaler + * For SWS_BICUBIC param[0] and [1] tune the shape of the basis + * function, param[0] tunes f(1) and param[1] f´(1) + * For SWS_GAUSS param[0] tunes the exponent and thus cutoff + * frequency + * For SWS_LANCZOS param[0] tunes the width of the window function + * @return a pointer to an allocated context, or NULL in case of error + * @note this function is to be removed after a saner alternative is + * written + */ +SwsContext *sws_getContext(int srcW, int srcH, enum AVPixelFormat srcFormat, + int dstW, int dstH, enum AVPixelFormat dstFormat, + int flags, SwsFilter *srcFilter, + SwsFilter *dstFilter, const double *param); + +/** + * Scale the image slice in srcSlice and put the resulting scaled + * slice in the image in dst. A slice is a sequence of consecutive + * rows in an image. Requires a context that has previously been + * initialized with sws_init_context(). + * + * Slices have to be provided in sequential order, either in + * top-bottom or bottom-top order. If slices are provided in + * non-sequential order the behavior of the function is undefined. + * + * @param c the scaling context previously created with + * sws_getContext() + * @param srcSlice the array containing the pointers to the planes of + * the source slice + * @param srcStride the array containing the strides for each plane of + * the source image + * @param srcSliceY the position in the source image of the slice to + * process, that is the number (counted starting from + * zero) in the image of the first row of the slice + * @param srcSliceH the height of the source slice, that is the number + * of rows in the slice + * @param dst the array containing the pointers to the planes of + * the destination image + * @param dstStride the array containing the strides for each plane of + * the destination image + * @return the height of the output slice + */ +int sws_scale(SwsContext *c, const uint8_t *const srcSlice[], + const int srcStride[], int srcSliceY, int srcSliceH, + uint8_t *const dst[], const int dstStride[]); + +/** + * Initialize the scaling process for a given pair of source/destination frames. + * Must be called before any calls to sws_send_slice() and sws_receive_slice(). + * Requires a context that has previously been initialized with sws_init_context(). + * + * This function will retain references to src and dst, so they must both use + * refcounted buffers (if allocated by the caller, in case of dst). + * + * @param c The scaling context + * @param dst The destination frame. + * + * The data buffers may either be already allocated by the caller or + * left clear, in which case they will be allocated by the scaler. + * The latter may have performance advantages - e.g. in certain cases + * some output planes may be references to input planes, rather than + * copies. + * + * Output data will be written into this frame in successful + * sws_receive_slice() calls. + * @param src The source frame. The data buffers must be allocated, but the + * frame data does not have to be ready at this point. Data + * availability is then signalled by sws_send_slice(). + * @return 0 on success, a negative AVERROR code on failure + * + * @see sws_frame_end() + */ +int sws_frame_start(SwsContext *c, AVFrame *dst, const AVFrame *src); + +/** + * Finish the scaling process for a pair of source/destination frames previously + * submitted with sws_frame_start(). Must be called after all sws_send_slice() + * and sws_receive_slice() calls are done, before any new sws_frame_start() + * calls. + * + * @param c The scaling context + */ +void sws_frame_end(SwsContext *c); + +/** + * Indicate that a horizontal slice of input data is available in the source + * frame previously provided to sws_frame_start(). The slices may be provided in + * any order, but may not overlap. For vertically subsampled pixel formats, the + * slices must be aligned according to subsampling. + * + * @param c The scaling context + * @param slice_start first row of the slice + * @param slice_height number of rows in the slice + * + * @return a non-negative number on success, a negative AVERROR code on failure. + */ +int sws_send_slice(SwsContext *c, unsigned int slice_start, + unsigned int slice_height); + +/** + * Request a horizontal slice of the output data to be written into the frame + * previously provided to sws_frame_start(). + * + * @param c The scaling context + * @param slice_start first row of the slice; must be a multiple of + * sws_receive_slice_alignment() + * @param slice_height number of rows in the slice; must be a multiple of + * sws_receive_slice_alignment(), except for the last slice + * (i.e. when slice_start+slice_height is equal to output + * frame height) + * + * @return a non-negative number if the data was successfully written into the output + * AVERROR(EAGAIN) if more input data needs to be provided before the + * output can be produced + * another negative AVERROR code on other kinds of scaling failure + */ +int sws_receive_slice(SwsContext *c, unsigned int slice_start, + unsigned int slice_height); + +/** + * Get the alignment required for slices. Requires a context that has + * previously been initialized with sws_init_context(). + * + * @param c The scaling context + * @return alignment required for output slices requested with sws_receive_slice(). + * Slice offsets and sizes passed to sws_receive_slice() must be + * multiples of the value returned from this function. + */ +unsigned int sws_receive_slice_alignment(const SwsContext *c); + +/** + * @param c the scaling context + * @param dstRange flag indicating the white-black range of the output (1=jpeg / 0=mpeg) + * @param srcRange flag indicating the white-black range of the input (1=jpeg / 0=mpeg) + * @param table the yuv2rgb coefficients describing the output yuv space, normally ff_yuv2rgb_coeffs[x] + * @param inv_table the yuv2rgb coefficients describing the input yuv space, normally ff_yuv2rgb_coeffs[x] + * @param brightness 16.16 fixed point brightness correction + * @param contrast 16.16 fixed point contrast correction + * @param saturation 16.16 fixed point saturation correction + * + * @return A negative error code on error, non negative otherwise. + * If `LIBSWSCALE_VERSION_MAJOR < 7`, returns -1 if not supported. + */ +int sws_setColorspaceDetails(SwsContext *c, const int inv_table[4], + int srcRange, const int table[4], int dstRange, + int brightness, int contrast, int saturation); + +/** + * @return A negative error code on error, non negative otherwise. + * If `LIBSWSCALE_VERSION_MAJOR < 7`, returns -1 if not supported. + */ +int sws_getColorspaceDetails(SwsContext *c, int **inv_table, + int *srcRange, int **table, int *dstRange, + int *brightness, int *contrast, int *saturation); + +/** + * Allocate and return an uninitialized vector with length coefficients. + */ +SwsVector *sws_allocVec(int length); + +/** + * Return a normalized Gaussian curve used to filter stuff + * quality = 3 is high quality, lower is lower quality. + */ +SwsVector *sws_getGaussianVec(double variance, double quality); + +/** + * Scale all the coefficients of a by the scalar value. + */ +void sws_scaleVec(SwsVector *a, double scalar); + +/** + * Scale all the coefficients of a so that their sum equals height. + */ +void sws_normalizeVec(SwsVector *a, double height); + +void sws_freeVec(SwsVector *a); + +SwsFilter *sws_getDefaultFilter(float lumaGBlur, float chromaGBlur, + float lumaSharpen, float chromaSharpen, + float chromaHShift, float chromaVShift, + int verbose); +void sws_freeFilter(SwsFilter *filter); + +/** + * Check if context can be reused, otherwise reallocate a new one. + * + * If context is NULL, just calls sws_getContext() to get a new + * context. Otherwise, checks if the parameters are the ones already + * saved in context. If that is the case, returns the current + * context. Otherwise, frees context and gets a new context with + * the new parameters. + * + * Be warned that srcFilter and dstFilter are not checked, they + * are assumed to remain the same. + */ +SwsContext *sws_getCachedContext(SwsContext *context, int srcW, int srcH, + enum AVPixelFormat srcFormat, int dstW, int dstH, + enum AVPixelFormat dstFormat, int flags, + SwsFilter *srcFilter, SwsFilter *dstFilter, + const double *param); + +/** + * Convert an 8-bit paletted frame into a frame with a color depth of 32 bits. + * + * The output frame will have the same packed format as the palette. + * + * @param src source frame buffer + * @param dst destination frame buffer + * @param num_pixels number of pixels to convert + * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src + */ +void sws_convertPalette8ToPacked32(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette); + +/** + * Convert an 8-bit paletted frame into a frame with a color depth of 24 bits. + * + * With the palette format "ABCD", the destination frame ends up with the format "ABC". + * + * @param src source frame buffer + * @param dst destination frame buffer + * @param num_pixels number of pixels to convert + * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src + */ +void sws_convertPalette8ToPacked24(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette); + +/** + * @} + */ + +#endif /* SWSCALE_SWSCALE_H */ diff --git a/ffmpeg-n8.1/include/libswscale/version.h b/ffmpeg-n8.1/include/libswscale/version.h new file mode 100644 index 00000000..c13db31c --- /dev/null +++ b/ffmpeg-n8.1/include/libswscale/version.h @@ -0,0 +1,44 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SWSCALE_VERSION_H +#define SWSCALE_VERSION_H + +/** + * @file + * swscale version macros + */ + +#include "libavutil/version.h" + +#include "version_major.h" + +#define LIBSWSCALE_VERSION_MINOR 5 +#define LIBSWSCALE_VERSION_MICRO 100 + +#define LIBSWSCALE_VERSION_INT AV_VERSION_INT(LIBSWSCALE_VERSION_MAJOR, \ + LIBSWSCALE_VERSION_MINOR, \ + LIBSWSCALE_VERSION_MICRO) +#define LIBSWSCALE_VERSION AV_VERSION(LIBSWSCALE_VERSION_MAJOR, \ + LIBSWSCALE_VERSION_MINOR, \ + LIBSWSCALE_VERSION_MICRO) +#define LIBSWSCALE_BUILD LIBSWSCALE_VERSION_INT + +#define LIBSWSCALE_IDENT "SwS" AV_STRINGIFY(LIBSWSCALE_VERSION) + +#endif /* SWSCALE_VERSION_H */ diff --git a/ffmpeg-n8.1/include/libswscale/version_major.h b/ffmpeg-n8.1/include/libswscale/version_major.h new file mode 100644 index 00000000..0dc50792 --- /dev/null +++ b/ffmpeg-n8.1/include/libswscale/version_major.h @@ -0,0 +1,35 @@ +/* + * This file is part of FFmpeg. + * + * 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. + * + * 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 FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SWSCALE_VERSION_MAJOR_H +#define SWSCALE_VERSION_MAJOR_H + +/** + * @file + * swscale version macros + */ + +#define LIBSWSCALE_VERSION_MAJOR 9 + +/** + * FF_API_* defines may be placed below to indicate public API that will be + * dropped at a future version bump. The defines themselves are not part of + * the public API and may change, break or disappear at any time. + */ + +#endif /* SWSCALE_VERSION_MAJOR_H */ diff --git a/ffmpeg-n8.1/lib/avcodec-62.def b/ffmpeg-n8.1/lib/avcodec-62.def new file mode 100644 index 00000000..d7ebcbab --- /dev/null +++ b/ffmpeg-n8.1/lib/avcodec-62.def @@ -0,0 +1,179 @@ +EXPORTS + av_ac3_parse_header + av_adts_header_parse + av_bsf_alloc + av_bsf_flush + av_bsf_free + av_bsf_get_by_name + av_bsf_get_class + av_bsf_get_null_filter + av_bsf_init + av_bsf_iterate + av_bsf_list_alloc + av_bsf_list_append + av_bsf_list_append2 + av_bsf_list_finalize + av_bsf_list_free + av_bsf_list_parse_str + av_bsf_receive_packet + av_bsf_send_packet + av_codec_ffversion + av_codec_is_decoder + av_codec_is_encoder + av_codec_iterate + av_container_fifo_alloc_avpacket + av_cpb_properties_alloc + av_d3d11va_alloc_context + av_dirac_parse_sequence_header + av_dv_codec_profile + av_dv_codec_profile2 + av_dv_frame_profile + av_exif_clone_ifd + av_exif_free + av_exif_get_entry + av_exif_get_tag_id + av_exif_get_tag_name + av_exif_ifd_to_dict + av_exif_matrix_to_orientation + av_exif_orientation_to_matrix + av_exif_parse_buffer + av_exif_remove_entry + av_exif_set_entry + av_exif_write + av_fast_padded_malloc + av_fast_padded_mallocz + av_get_audio_frame_duration + av_get_audio_frame_duration2 + av_get_bits_per_sample + av_get_exact_bits_per_sample + av_get_pcm_codec + av_get_profile_name + av_grow_packet + av_init_packet + av_jni_get_java_vm + av_jni_set_java_vm + av_mediacodec_alloc_context + av_mediacodec_default_free + av_mediacodec_default_init + av_mediacodec_release_buffer + av_mediacodec_render_buffer_at_time + av_new_packet + av_packet_add_side_data + av_packet_alloc + av_packet_clone + av_packet_copy_props + av_packet_free + av_packet_free_side_data + av_packet_from_data + av_packet_get_side_data + av_packet_make_refcounted + av_packet_make_writable + av_packet_move_ref + av_packet_new_side_data + av_packet_pack_dictionary + av_packet_ref + av_packet_rescale_ts + av_packet_shrink_side_data + av_packet_side_data_add + av_packet_side_data_free + av_packet_side_data_from_frame + av_packet_side_data_get + av_packet_side_data_name + av_packet_side_data_new + av_packet_side_data_remove + av_packet_side_data_to_frame + av_packet_unpack_dictionary + av_packet_unref + av_parser_close + av_parser_init + av_parser_iterate + av_parser_parse2 + av_qsv_alloc_context + av_shrink_packet + av_smpte_291m_anc_8bit_decode + av_smpte_291m_anc_8bit_encode + av_smpte_291m_anc_8bit_extract_cta_708 + av_smpte_291m_anc_8bit_fill_checksum + av_smpte_291m_anc_8bit_get_sample_count + av_smpte_436m_anc_append + av_smpte_436m_anc_encode + av_smpte_436m_anc_iter_init + av_smpte_436m_anc_iter_next + av_smpte_436m_coded_anc_payload_size + av_smpte_436m_coded_anc_validate + av_vorbis_parse_frame + av_vorbis_parse_frame_flags + av_vorbis_parse_free + av_vorbis_parse_init + av_vorbis_parse_reset + av_xiphlacing + avcodec_align_dimensions + avcodec_align_dimensions2 + avcodec_alloc_context3 + avcodec_configuration + avcodec_dct_alloc + avcodec_dct_get_class + avcodec_dct_init + avcodec_decode_subtitle2 + avcodec_default_execute + avcodec_default_execute2 + avcodec_default_get_buffer2 + avcodec_default_get_encode_buffer + avcodec_default_get_format + avcodec_descriptor_get + avcodec_descriptor_get_by_name + avcodec_descriptor_next + avcodec_encode_subtitle + avcodec_fill_audio_frame + avcodec_find_best_pix_fmt_of_list + avcodec_find_decoder + avcodec_find_decoder_by_name + avcodec_find_encoder + avcodec_find_encoder_by_name + avcodec_flush_buffers + avcodec_free_context + avcodec_get_class + avcodec_get_hw_config + avcodec_get_hw_frames_parameters + avcodec_get_name + avcodec_get_subtitle_rect_class + avcodec_get_supported_config + avcodec_get_type + avcodec_is_open + avcodec_license + avcodec_open2 + avcodec_parameters_alloc + avcodec_parameters_copy + avcodec_parameters_free + avcodec_parameters_from_context + avcodec_parameters_to_context + avcodec_pix_fmt_to_codec_tag + avcodec_profile_name + avcodec_receive_frame + avcodec_receive_frame_flags + avcodec_receive_packet + avcodec_send_frame + avcodec_send_packet + avcodec_string + avcodec_version + avpriv_ac3_parse_header + avpriv_adts_header_parse + avpriv_codec_get_cap_skip_frame_fill_param + avpriv_dca_convert_bitstream + avpriv_dca_parse_core_frame_header + avpriv_elbg_do + avpriv_elbg_free + avpriv_exif_decode_ifd + avpriv_find_start_code + avpriv_fits_header_init + avpriv_fits_header_parse_line + avpriv_h264_has_num_reorder_frames + avpriv_mpeg4audio_get_config2 + avpriv_mpegaudio_decode_header + avpriv_packet_list_free + avpriv_packet_list_get + avpriv_packet_list_put + avpriv_pix_fmt_find + avpriv_split_xiph_headers + avpriv_tak_parse_streaminfo + avsubtitle_free diff --git a/ffmpeg-n8.1/lib/avcodec.lib b/ffmpeg-n8.1/lib/avcodec.lib new file mode 100644 index 00000000..227e80e9 Binary files /dev/null and b/ffmpeg-n8.1/lib/avcodec.lib differ diff --git a/ffmpeg-n8.1/lib/avdevice-62.def b/ffmpeg-n8.1/lib/avdevice-62.def new file mode 100644 index 00000000..4aa5db22 --- /dev/null +++ b/ffmpeg-n8.1/lib/avdevice-62.def @@ -0,0 +1,16 @@ +EXPORTS + av_device_ffversion + av_input_audio_device_next + av_input_video_device_next + av_output_audio_device_next + av_output_video_device_next + avdevice_app_to_dev_control_message + avdevice_configuration + avdevice_dev_to_app_control_message + avdevice_free_list_devices + avdevice_license + avdevice_list_devices + avdevice_list_input_sources + avdevice_list_output_sinks + avdevice_register_all + avdevice_version diff --git a/ffmpeg-n8.1/lib/avdevice.lib b/ffmpeg-n8.1/lib/avdevice.lib new file mode 100644 index 00000000..b01f01d7 Binary files /dev/null and b/ffmpeg-n8.1/lib/avdevice.lib differ diff --git a/ffmpeg-n8.1/lib/avfilter-11.def b/ffmpeg-n8.1/lib/avfilter-11.def new file mode 100644 index 00000000..d0f84645 --- /dev/null +++ b/ffmpeg-n8.1/lib/avfilter-11.def @@ -0,0 +1,68 @@ +EXPORTS + av_buffersink_get_alpha_mode + av_buffersink_get_ch_layout + av_buffersink_get_channels + av_buffersink_get_color_range + av_buffersink_get_colorspace + av_buffersink_get_format + av_buffersink_get_frame + av_buffersink_get_frame_flags + av_buffersink_get_frame_rate + av_buffersink_get_h + av_buffersink_get_hw_frames_ctx + av_buffersink_get_sample_aspect_ratio + av_buffersink_get_sample_rate + av_buffersink_get_samples + av_buffersink_get_side_data + av_buffersink_get_time_base + av_buffersink_get_type + av_buffersink_get_w + av_buffersink_set_frame_size + av_buffersrc_add_frame + av_buffersrc_add_frame_flags + av_buffersrc_close + av_buffersrc_get_nb_failed_requests + av_buffersrc_get_status + av_buffersrc_parameters_alloc + av_buffersrc_parameters_set + av_buffersrc_write_frame + av_filter_ffversion + av_filter_iterate + avfilter_configuration + avfilter_filter_pad_count + avfilter_free + avfilter_get_by_name + avfilter_get_class + avfilter_graph_alloc + avfilter_graph_alloc_filter + avfilter_graph_config + avfilter_graph_create_filter + avfilter_graph_dump + avfilter_graph_free + avfilter_graph_get_filter + avfilter_graph_parse + avfilter_graph_parse2 + avfilter_graph_parse_ptr + avfilter_graph_queue_command + avfilter_graph_request_oldest + avfilter_graph_segment_apply + avfilter_graph_segment_apply_opts + avfilter_graph_segment_create_filters + avfilter_graph_segment_free + avfilter_graph_segment_init + avfilter_graph_segment_link + avfilter_graph_segment_parse + avfilter_graph_send_command + avfilter_graph_set_auto_convert + avfilter_init_dict + avfilter_init_str + avfilter_inout_alloc + avfilter_inout_free + avfilter_insert_filter + avfilter_license + avfilter_link + avfilter_link_get_hw_frames_ctx + avfilter_pad_get_name + avfilter_pad_get_type + avfilter_process_command + avfilter_version diff --git a/ffmpeg-n8.1/lib/avfilter.lib b/ffmpeg-n8.1/lib/avfilter.lib new file mode 100644 index 00000000..9fb1c801 Binary files /dev/null and b/ffmpeg-n8.1/lib/avfilter.lib differ diff --git a/ffmpeg-n8.1/lib/avformat-62.def b/ffmpeg-n8.1/lib/avformat-62.def new file mode 100644 index 00000000..3c9f7a5f --- /dev/null +++ b/ffmpeg-n8.1/lib/avformat-62.def @@ -0,0 +1,157 @@ +EXPORTS + av_add_index_entry + av_append_packet + av_codec_get_id + av_codec_get_tag + av_codec_get_tag2 + av_demuxer_iterate + av_disposition_from_string + av_disposition_to_string + av_dump_format + av_filename_number_test + av_find_best_stream + av_find_default_stream_index + av_find_input_format + av_find_program_from_stream + av_format_ffversion + av_get_frame_filename + av_get_frame_filename2 + av_get_output_timestamp + av_get_packet + av_guess_codec + av_guess_format + av_guess_frame_rate + av_guess_sample_aspect_ratio + av_hex_dump + av_hex_dump_log + av_index_search_timestamp + av_interleaved_write_frame + av_interleaved_write_uncoded_frame + av_match_ext + av_mime_codec_str + av_muxer_iterate + av_new_program + av_pkt_dump2 + av_pkt_dump_log2 + av_probe_input_buffer + av_probe_input_buffer2 + av_probe_input_format + av_probe_input_format2 + av_probe_input_format3 + av_program_add_stream_index + av_read_frame + av_read_pause + av_read_play + av_sdp_create + av_seek_frame + av_stream_get_class + av_stream_get_codec_timebase + av_stream_get_parser + av_stream_group_get_class + av_url_split + av_write_frame + av_write_trailer + av_write_uncoded_frame + av_write_uncoded_frame_query + avformat_alloc_context + avformat_alloc_output_context2 + avformat_close_input + avformat_configuration + avformat_find_stream_info + avformat_flush + avformat_free_context + avformat_get_class + avformat_get_mov_audio_tags + avformat_get_mov_video_tags + avformat_get_riff_audio_tags + avformat_get_riff_video_tags + avformat_index_get_entries_count + avformat_index_get_entry + avformat_index_get_entry_from_timestamp + avformat_init_output + avformat_license + avformat_match_stream_specifier + avformat_network_deinit + avformat_network_init + avformat_new_stream + avformat_open_input + avformat_query_codec + avformat_queue_attached_pictures + avformat_receive_command_reply + avformat_seek_file + avformat_send_command + avformat_stream_group_add_stream + avformat_stream_group_create + avformat_stream_group_name + avformat_transfer_internal_stream_timing_info + avformat_version + avformat_write_header + avio_accept + avio_alloc_context + avio_check + avio_close + avio_close_dir + avio_close_dyn_buf + avio_closep + avio_context_free + avio_enum_protocols + avio_feof + avio_find_protocol_name + avio_flush + avio_free_directory_entry + avio_get_dyn_buf + avio_get_str + avio_get_str16be + avio_get_str16le + avio_handshake + avio_open + avio_open2 + avio_open_dir + avio_open_dyn_buf + avio_pause + avio_print_string_array + avio_printf + avio_protocol_get_class + avio_put_str + avio_put_str16be + avio_put_str16le + avio_r8 + avio_rb16 + avio_rb24 + avio_rb32 + avio_rb64 + avio_read + avio_read_dir + avio_read_partial + avio_read_to_bprint + avio_rl16 + avio_rl24 + avio_rl32 + avio_rl64 + avio_seek + avio_seek_time + avio_size + avio_skip + avio_vprintf + avio_w8 + avio_wb16 + avio_wb24 + avio_wb32 + avio_wb64 + avio_wl16 + avio_wl24 + avio_wl32 + avio_wl64 + avio_write + avio_write_marker + avpriv_dv_get_packet + avpriv_dv_init_demux + avpriv_dv_produce_packet + avpriv_mpegts_parse_close + avpriv_mpegts_parse_open + avpriv_mpegts_parse_packet + avpriv_new_chapter + avpriv_register_devices + avpriv_set_pts_info + avpriv_stream_set_need_parsing + avpriv_update_cur_dts diff --git a/ffmpeg-n8.1/lib/avformat.lib b/ffmpeg-n8.1/lib/avformat.lib new file mode 100644 index 00000000..6999fd65 Binary files /dev/null and b/ffmpeg-n8.1/lib/avformat.lib differ diff --git a/ffmpeg-n8.1/lib/avutil-60.def b/ffmpeg-n8.1/lib/avutil-60.def new file mode 100644 index 00000000..be95e0ab --- /dev/null +++ b/ffmpeg-n8.1/lib/avutil-60.def @@ -0,0 +1,629 @@ +EXPORTS + av_add_i + av_add_q + av_add_stable + av_adler32_update + av_aes_alloc + av_aes_crypt + av_aes_ctr_alloc + av_aes_ctr_crypt + av_aes_ctr_free + av_aes_ctr_get_iv + av_aes_ctr_increment_iv + av_aes_ctr_init + av_aes_ctr_set_full_iv + av_aes_ctr_set_iv + av_aes_ctr_set_random_iv + av_aes_init + av_aes_size + av_alpha_mode_from_name + av_alpha_mode_name + av_ambient_viewing_environment_alloc + av_ambient_viewing_environment_create_side_data + av_amf_to_av_format + av_append_path_component + av_asprintf + av_assert0_fpu + av_audio_fifo_alloc + av_audio_fifo_drain + av_audio_fifo_free + av_audio_fifo_peek + av_audio_fifo_peek_at + av_audio_fifo_read + av_audio_fifo_realloc + av_audio_fifo_reset + av_audio_fifo_size + av_audio_fifo_space + av_audio_fifo_write + av_av_to_amf_format + av_base64_decode + av_base64_encode + av_basename + av_bessel_i0 + av_blowfish_alloc + av_blowfish_crypt + av_blowfish_crypt_ecb + av_blowfish_init + av_bmg_get + av_bprint_append_data + av_bprint_chars + av_bprint_clear + av_bprint_escape + av_bprint_finalize + av_bprint_get_buffer + av_bprint_init + av_bprint_init_for_buffer + av_bprint_strftime + av_bprintf + av_buffer_alloc + av_buffer_allocz + av_buffer_create + av_buffer_default_free + av_buffer_get_opaque + av_buffer_get_ref_count + av_buffer_is_writable + av_buffer_make_writable + av_buffer_pool_buffer_get_opaque + av_buffer_pool_get + av_buffer_pool_init + av_buffer_pool_init2 + av_buffer_pool_uninit + av_buffer_realloc + av_buffer_ref + av_buffer_replace + av_buffer_unref + av_calloc + av_camellia_alloc + av_camellia_crypt + av_camellia_init + av_camellia_size + av_cast5_alloc + av_cast5_crypt + av_cast5_crypt2 + av_cast5_init + av_cast5_size + av_channel_description + av_channel_description_bprint + av_channel_from_string + av_channel_layout_ambisonic_order + av_channel_layout_channel_from_index + av_channel_layout_channel_from_string + av_channel_layout_check + av_channel_layout_compare + av_channel_layout_copy + av_channel_layout_custom_init + av_channel_layout_default + av_channel_layout_describe + av_channel_layout_describe_bprint + av_channel_layout_from_mask + av_channel_layout_from_string + av_channel_layout_index_from_channel + av_channel_layout_index_from_string + av_channel_layout_retype + av_channel_layout_standard + av_channel_layout_subset + av_channel_layout_uninit + av_channel_name + av_channel_name_bprint + av_chroma_location_enum_to_pos + av_chroma_location_from_name + av_chroma_location_name + av_chroma_location_pos_to_enum + av_cmp_i + av_color_primaries_from_name + av_color_primaries_name + av_color_range_from_name + av_color_range_name + av_color_space_from_name + av_color_space_name + av_color_transfer_from_name + av_color_transfer_name + av_compare_mod + av_compare_ts + av_container_fifo_alloc + av_container_fifo_alloc_avframe + av_container_fifo_can_read + av_container_fifo_drain + av_container_fifo_free + av_container_fifo_peek + av_container_fifo_read + av_container_fifo_write + av_content_light_metadata_alloc + av_content_light_metadata_create_side_data + av_cpu_count + av_cpu_force_count + av_cpu_max_align + av_crc + av_crc_get_table + av_crc_init + av_csp_approximate_eotf_gamma + av_csp_approximate_trc_gamma + av_csp_itu_eotf + av_csp_itu_eotf_inv + av_csp_luma_coeffs_from_avcsp + av_csp_primaries_desc_from_id + av_csp_primaries_id_from_desc + av_csp_trc_func_from_id + av_csp_trc_func_inv_from_id + av_d2q + av_default_get_category + av_default_item_name + av_des_alloc + av_des_crypt + av_des_init + av_des_mac + av_detection_bbox_alloc + av_detection_bbox_create_side_data + av_dict_copy + av_dict_count + av_dict_free + av_dict_get + av_dict_get_string + av_dict_iterate + av_dict_parse_string + av_dict_set + av_dict_set_int + av_dirname + av_display_matrix_flip + av_display_rotation_get + av_display_rotation_set + av_div_i + av_div_q + av_dovi_alloc + av_dovi_find_level + av_dovi_metadata_alloc + av_downmix_info_update_side_data + av_dynamic_hdr_plus_alloc + av_dynamic_hdr_plus_create_side_data + av_dynamic_hdr_plus_from_t35 + av_dynamic_hdr_plus_to_t35 + av_dynamic_hdr_vivid_alloc + av_dynamic_hdr_vivid_create_side_data + av_dynarray2_add + av_dynarray_add + av_dynarray_add_nofree + av_encryption_info_add_side_data + av_encryption_info_alloc + av_encryption_info_clone + av_encryption_info_free + av_encryption_info_get_side_data + av_encryption_init_info_add_side_data + av_encryption_init_info_alloc + av_encryption_init_info_free + av_encryption_init_info_get_side_data + av_escape + av_executor_alloc + av_executor_execute + av_executor_free + av_expr_count_func + av_expr_count_vars + av_expr_eval + av_expr_free + av_expr_parse + av_expr_parse_and_eval + av_fast_malloc + av_fast_mallocz + av_fast_realloc + av_fifo_alloc2 + av_fifo_auto_grow_limit + av_fifo_can_read + av_fifo_can_write + av_fifo_drain2 + av_fifo_elem_size + av_fifo_freep2 + av_fifo_grow2 + av_fifo_peek + av_fifo_peek_to_cb + av_fifo_read + av_fifo_read_to_cb + av_fifo_reset2 + av_fifo_write + av_fifo_write_from_cb + av_file_map + av_file_unmap + av_film_grain_params_alloc + av_film_grain_params_create_side_data + av_film_grain_params_select + av_find_best_pix_fmt_of_2 + av_find_info_tag + av_find_nearest_q_idx + av_force_cpu_flags + av_fourcc_make_string + av_frame_alloc + av_frame_apply_cropping + av_frame_clone + av_frame_copy + av_frame_copy_props + av_frame_free + av_frame_get_buffer + av_frame_get_plane_buffer + av_frame_get_side_data + av_frame_is_writable + av_frame_make_writable + av_frame_move_ref + av_frame_new_side_data + av_frame_new_side_data_from_buf + av_frame_ref + av_frame_remove_side_data + av_frame_replace + av_frame_side_data_add + av_frame_side_data_clone + av_frame_side_data_desc + av_frame_side_data_free + av_frame_side_data_get_c + av_frame_side_data_name + av_frame_side_data_new + av_frame_side_data_remove + av_frame_side_data_remove_by_props + av_frame_unref + av_free + av_freep + av_gcd + av_gcd_q + av_get_alt_sample_fmt + av_get_bits_per_pixel + av_get_bytes_per_sample + av_get_cpu_flags + av_get_known_color_name + av_get_media_type_string + av_get_packed_sample_fmt + av_get_padded_bits_per_pixel + av_get_picture_type_char + av_get_pix_fmt + av_get_pix_fmt_loss + av_get_pix_fmt_name + av_get_pix_fmt_string + av_get_planar_sample_fmt + av_get_random_seed + av_get_sample_fmt + av_get_sample_fmt_name + av_get_sample_fmt_string + av_get_time_base_q + av_get_token + av_gettime + av_gettime_relative + av_gettime_relative_is_monotonic + av_hash_alloc + av_hash_final + av_hash_final_b64 + av_hash_final_bin + av_hash_final_hex + av_hash_freep + av_hash_get_name + av_hash_get_size + av_hash_init + av_hash_names + av_hash_update + av_hmac_alloc + av_hmac_calc + av_hmac_final + av_hmac_free + av_hmac_init + av_hmac_update + av_hwdevice_ctx_alloc + av_hwdevice_ctx_create + av_hwdevice_ctx_create_derived + av_hwdevice_ctx_create_derived_opts + av_hwdevice_ctx_init + av_hwdevice_find_type_by_name + av_hwdevice_get_hwframe_constraints + av_hwdevice_get_type_name + av_hwdevice_hwconfig_alloc + av_hwdevice_iterate_types + av_hwframe_constraints_free + av_hwframe_ctx_alloc + av_hwframe_ctx_create_derived + av_hwframe_ctx_init + av_hwframe_get_buffer + av_hwframe_map + av_hwframe_transfer_data + av_hwframe_transfer_get_formats + av_i2int + av_iamf_audio_element_add_layer + av_iamf_audio_element_alloc + av_iamf_audio_element_free + av_iamf_audio_element_get_class + av_iamf_mix_presentation_add_submix + av_iamf_mix_presentation_alloc + av_iamf_mix_presentation_free + av_iamf_mix_presentation_get_class + av_iamf_param_definition_alloc + av_iamf_param_definition_get_class + av_iamf_submix_add_element + av_iamf_submix_add_layout + av_image_alloc + av_image_check_sar + av_image_check_size + av_image_check_size2 + av_image_copy + av_image_copy_plane + av_image_copy_plane_uc_from + av_image_copy_to_buffer + av_image_copy_uc_from + av_image_fill_arrays + av_image_fill_black + av_image_fill_color + av_image_fill_linesizes + av_image_fill_max_pixsteps + av_image_fill_plane_sizes + av_image_fill_pointers + av_image_get_buffer_size + av_image_get_linesize + av_int2i + av_int_list_length_for_size + av_lfg_init + av_lfg_init_from_data + av_log + av_log2 + av_log2_16bit + av_log2_i + av_log_default_callback + av_log_format_line + av_log_format_line2 + av_log_get_flags + av_log_get_level + av_log_once + av_log_set_callback + av_log_set_flags + av_log_set_level + av_lzo1x_decode + av_malloc + av_malloc_array + av_mallocz + av_mastering_display_metadata_alloc + av_mastering_display_metadata_alloc_size + av_mastering_display_metadata_create_side_data + av_match_list + av_match_name + av_max_alloc + av_md5_alloc + av_md5_final + av_md5_init + av_md5_size + av_md5_sum + av_md5_update + av_memcpy_backptr + av_memdup + av_mod_i + av_mul_i + av_mul_q + av_murmur3_alloc + av_murmur3_final + av_murmur3_init + av_murmur3_init_seeded + av_murmur3_update + av_nearer_q + av_opt_child_class_iterate + av_opt_child_next + av_opt_copy + av_opt_eval_double + av_opt_eval_flags + av_opt_eval_float + av_opt_eval_int + av_opt_eval_int64 + av_opt_eval_q + av_opt_eval_uint + av_opt_find + av_opt_find2 + av_opt_flag_is_set + av_opt_free + av_opt_freep_ranges + av_opt_get + av_opt_get_array + av_opt_get_array_size + av_opt_get_chlayout + av_opt_get_dict_val + av_opt_get_double + av_opt_get_image_size + av_opt_get_int + av_opt_get_key_value + av_opt_get_pixel_fmt + av_opt_get_q + av_opt_get_sample_fmt + av_opt_get_video_rate + av_opt_is_set_to_default + av_opt_is_set_to_default_by_name + av_opt_next + av_opt_ptr + av_opt_query_ranges + av_opt_query_ranges_default + av_opt_serialize + av_opt_set + av_opt_set_array + av_opt_set_bin + av_opt_set_chlayout + av_opt_set_defaults + av_opt_set_defaults2 + av_opt_set_dict + av_opt_set_dict2 + av_opt_set_dict_val + av_opt_set_double + av_opt_set_from_string + av_opt_set_image_size + av_opt_set_int + av_opt_set_pixel_fmt + av_opt_set_q + av_opt_set_sample_fmt + av_opt_set_video_rate + av_opt_show2 + av_parse_color + av_parse_cpu_caps + av_parse_ratio + av_parse_time + av_parse_video_rate + av_parse_video_size + av_pix_fmt_count_planes + av_pix_fmt_desc_get + av_pix_fmt_desc_get_id + av_pix_fmt_desc_next + av_pix_fmt_get_chroma_sub_sample + av_pix_fmt_swap_endianness + av_pixelutils_get_sad_fn + av_q2intfloat + av_random_bytes + av_rc4_alloc + av_rc4_crypt + av_rc4_init + av_read_image_line + av_read_image_line2 + av_realloc + av_realloc_array + av_realloc_f + av_reallocp + av_reallocp_array + av_reduce + av_refstruct_alloc_ext_c + av_refstruct_exclusive + av_refstruct_pool_alloc + av_refstruct_pool_alloc_ext_c + av_refstruct_pool_get + av_refstruct_ref + av_refstruct_ref_c + av_refstruct_replace + av_refstruct_unref + av_rescale + av_rescale_delta + av_rescale_q + av_rescale_q_rnd + av_rescale_rnd + av_ripemd_alloc + av_ripemd_final + av_ripemd_init + av_ripemd_size + av_ripemd_update + av_sample_fmt_is_planar + av_samples_alloc + av_samples_alloc_array_and_samples + av_samples_copy + av_samples_fill_arrays + av_samples_get_buffer_size + av_samples_set_silence + av_set_options_string + av_sha512_alloc + av_sha512_final + av_sha512_init + av_sha512_size + av_sha512_update + av_sha_alloc + av_sha_final + av_sha_init + av_sha_size + av_sha_update + av_shr_i + av_size_mult + av_small_strptime + av_spherical_alloc + av_spherical_from_name + av_spherical_projection_name + av_spherical_tile_bounds + av_sscanf + av_stereo3d_alloc + av_stereo3d_alloc_size + av_stereo3d_create_side_data + av_stereo3d_from_name + av_stereo3d_primary_eye_from_name + av_stereo3d_primary_eye_name + av_stereo3d_type_name + av_stereo3d_view_from_name + av_stereo3d_view_name + av_strcasecmp + av_strdup + av_strerror + av_strireplace + av_stristart + av_stristr + av_strlcat + av_strlcatf + av_strlcpy + av_strncasecmp + av_strndup + av_strnstr + av_strstart + av_strtod + av_strtok + av_sub_i + av_sub_q + av_tdrdi_alloc + av_tea_alloc + av_tea_crypt + av_tea_init + av_tea_size + av_thread_message_flush + av_thread_message_queue_alloc + av_thread_message_queue_free + av_thread_message_queue_nb_elems + av_thread_message_queue_recv + av_thread_message_queue_send + av_thread_message_queue_set_err_recv + av_thread_message_queue_set_err_send + av_thread_message_queue_set_free_func + av_timecode_adjust_ntsc_framenum2 + av_timecode_check_frame_rate + av_timecode_get_smpte + av_timecode_get_smpte_from_framenum + av_timecode_init + av_timecode_init_from_components + av_timecode_init_from_string + av_timecode_make_mpeg_tc_string + av_timecode_make_smpte_tc_string + av_timecode_make_smpte_tc_string2 + av_timecode_make_string + av_timegm + av_tree_destroy + av_tree_enumerate + av_tree_find + av_tree_insert + av_tree_node_alloc + av_tree_node_size + av_ts_make_time_string2 + av_twofish_alloc + av_twofish_crypt + av_twofish_init + av_twofish_size + av_tx_init + av_tx_uninit + av_usleep + av_utf8_decode + av_util_ffversion + av_uuid_parse + av_uuid_parse_range + av_uuid_unparse + av_uuid_urn_parse + av_vbprintf + av_version_info + av_video_enc_params_alloc + av_video_enc_params_create_side_data + av_video_hint_alloc + av_video_hint_create_side_data + av_vk_frame_alloc + av_vk_get_optional_device_extensions + av_vk_get_optional_instance_extensions + av_vkfmt_from_pixfmt + av_vlog + av_write_image_line + av_write_image_line2 + av_xtea_alloc + av_xtea_crypt + av_xtea_init + av_xtea_le_crypt + av_xtea_le_init + avpriv_alloc_fixed_dsp + avpriv_cga_font + avpriv_cga_font_get + avpriv_float_dsp_alloc + avpriv_fopen_utf8 + avpriv_init_lls + avpriv_open + avpriv_report_missing_feature + avpriv_request_sample + avpriv_set_systematic_pal2 + avpriv_slicethread_create + avpriv_slicethread_execute + avpriv_slicethread_free + avpriv_solve_lls + avpriv_tempfile + avpriv_vga16_font + avpriv_vga16_font_get + avutil_configuration + avutil_license + avutil_version diff --git a/ffmpeg-n8.1/lib/avutil.lib b/ffmpeg-n8.1/lib/avutil.lib new file mode 100644 index 00000000..f56a85c8 Binary files /dev/null and b/ffmpeg-n8.1/lib/avutil.lib differ diff --git a/ffmpeg-n8.1/lib/libavcodec.dll.a b/ffmpeg-n8.1/lib/libavcodec.dll.a new file mode 100644 index 00000000..65856c30 Binary files /dev/null and b/ffmpeg-n8.1/lib/libavcodec.dll.a differ diff --git a/ffmpeg-n8.1/lib/libavdevice.dll.a b/ffmpeg-n8.1/lib/libavdevice.dll.a new file mode 100644 index 00000000..9f562ff1 Binary files /dev/null and b/ffmpeg-n8.1/lib/libavdevice.dll.a differ diff --git a/ffmpeg-n8.1/lib/libavfilter.dll.a b/ffmpeg-n8.1/lib/libavfilter.dll.a new file mode 100644 index 00000000..d7849324 Binary files /dev/null and b/ffmpeg-n8.1/lib/libavfilter.dll.a differ diff --git a/ffmpeg-n8.1/lib/libavformat.dll.a b/ffmpeg-n8.1/lib/libavformat.dll.a new file mode 100644 index 00000000..62abe84d Binary files /dev/null and b/ffmpeg-n8.1/lib/libavformat.dll.a differ diff --git a/ffmpeg-n8.1/lib/libavutil.dll.a b/ffmpeg-n8.1/lib/libavutil.dll.a new file mode 100644 index 00000000..c599b931 Binary files /dev/null and b/ffmpeg-n8.1/lib/libavutil.dll.a differ diff --git a/ffmpeg-n8.1/lib/libswresample.dll.a b/ffmpeg-n8.1/lib/libswresample.dll.a new file mode 100644 index 00000000..4fc34167 Binary files /dev/null and b/ffmpeg-n8.1/lib/libswresample.dll.a differ diff --git a/ffmpeg-n8.1/lib/libswscale.dll.a b/ffmpeg-n8.1/lib/libswscale.dll.a new file mode 100644 index 00000000..c22ad2cf Binary files /dev/null and b/ffmpeg-n8.1/lib/libswscale.dll.a differ diff --git a/ffmpeg-n8.1/lib/pkgconfig/libavcodec.pc b/ffmpeg-n8.1/lib/pkgconfig/libavcodec.pc new file mode 100644 index 00000000..01ba11a7 --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libavcodec.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libavcodec +Description: FFmpeg codec library +Version: 62.28.100 +Requires: +Requires.private: libswresample >= 6.3.100, libavutil >= 60.26.100 +Conflicts: +Libs: -L${libdir} -lavcodec +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/pkgconfig/libavdevice.pc b/ffmpeg-n8.1/lib/pkgconfig/libavdevice.pc new file mode 100644 index 00000000..382a9b87 --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libavdevice.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libavdevice +Description: FFmpeg device handling library +Version: 62.3.100 +Requires: +Requires.private: libavfilter >= 11.14.100, libswscale >= 9.5.100, libavformat >= 62.12.100, libavcodec >= 62.28.100, libswresample >= 6.3.100, libavutil >= 60.26.100 +Conflicts: +Libs: -L${libdir} -lavdevice +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/pkgconfig/libavfilter.pc b/ffmpeg-n8.1/lib/pkgconfig/libavfilter.pc new file mode 100644 index 00000000..349113dd --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libavfilter.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libavfilter +Description: FFmpeg audio/video filtering library +Version: 11.14.100 +Requires: +Requires.private: libswscale >= 9.5.100, libavformat >= 62.12.100, libavcodec >= 62.28.100, libswresample >= 6.3.100, libavutil >= 60.26.100 +Conflicts: +Libs: -L${libdir} -lavfilter +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/pkgconfig/libavformat.pc b/ffmpeg-n8.1/lib/pkgconfig/libavformat.pc new file mode 100644 index 00000000..e1b1fd09 --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libavformat.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libavformat +Description: FFmpeg container format library +Version: 62.12.100 +Requires: +Requires.private: libavcodec >= 62.28.100, libswresample >= 6.3.100, libavutil >= 60.26.100 +Conflicts: +Libs: -L${libdir} -lavformat +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/pkgconfig/libavutil.pc b/ffmpeg-n8.1/lib/pkgconfig/libavutil.pc new file mode 100644 index 00000000..68a130c8 --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libavutil.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libavutil +Description: FFmpeg utility library +Version: 60.26.100 +Requires: +Requires.private: +Conflicts: +Libs: -L${libdir} -lavutil +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/pkgconfig/libswresample.pc b/ffmpeg-n8.1/lib/pkgconfig/libswresample.pc new file mode 100644 index 00000000..7619c5e4 --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libswresample.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libswresample +Description: FFmpeg audio resampling library +Version: 6.3.100 +Requires: +Requires.private: libavutil >= 60.26.100 +Conflicts: +Libs: -L${libdir} -lswresample +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/pkgconfig/libswscale.pc b/ffmpeg-n8.1/lib/pkgconfig/libswscale.pc new file mode 100644 index 00000000..75a200eb --- /dev/null +++ b/ffmpeg-n8.1/lib/pkgconfig/libswscale.pc @@ -0,0 +1,13 @@ +prefix=${pcfiledir}/../.. +exec_prefix=${prefix} +libdir=${prefix}/lib +includedir=${prefix}/include + +Name: libswscale +Description: FFmpeg image rescaling library +Version: 9.5.100 +Requires: +Requires.private: libavutil >= 60.26.100 +Conflicts: +Libs: -L${libdir} -lswscale +Cflags: -I${includedir} diff --git a/ffmpeg-n8.1/lib/swresample-6.def b/ffmpeg-n8.1/lib/swresample-6.def new file mode 100644 index 00000000..ee713195 --- /dev/null +++ b/ffmpeg-n8.1/lib/swresample-6.def @@ -0,0 +1,24 @@ +EXPORTS + swr_alloc + swr_alloc_set_opts2 + swr_build_matrix2 + swr_close + swr_config_frame + swr_convert + swr_convert_frame + swr_drop_output + swr_ffversion + swr_free + swr_get_class + swr_get_delay + swr_get_out_samples + swr_init + swr_inject_silence + swr_is_initialized + swr_next_pts + swr_set_channel_mapping + swr_set_compensation + swr_set_matrix + swresample_configuration + swresample_license + swresample_version diff --git a/ffmpeg-n8.1/lib/swresample.lib b/ffmpeg-n8.1/lib/swresample.lib new file mode 100644 index 00000000..cb913a41 Binary files /dev/null and b/ffmpeg-n8.1/lib/swresample.lib differ diff --git a/ffmpeg-n8.1/lib/swscale-9.def b/ffmpeg-n8.1/lib/swscale-9.def new file mode 100644 index 00000000..e1187b14 --- /dev/null +++ b/ffmpeg-n8.1/lib/swscale-9.def @@ -0,0 +1,41 @@ +EXPORTS + sws_allocVec + sws_alloc_context + sws_convertPalette8ToPacked24 + sws_convertPalette8ToPacked32 + sws_frame_end + sws_frame_setup + sws_frame_start + sws_freeContext + sws_freeFilter + sws_freeVec + sws_free_context + sws_getCachedContext + sws_getCoefficients + sws_getColorspaceDetails + sws_getContext + sws_getDefaultFilter + sws_getGaussianVec + sws_get_class + sws_init_context + sws_isSupportedEndiannessConversion + sws_isSupportedInput + sws_isSupportedOutput + sws_is_noop + sws_normalizeVec + sws_receive_slice + sws_receive_slice_alignment + sws_scale + sws_scaleVec + sws_scale_frame + sws_send_slice + sws_setColorspaceDetails + sws_test_colorspace + sws_test_format + sws_test_frame + sws_test_hw_format + sws_test_primaries + sws_test_transfer + swscale_configuration + swscale_license + swscale_version diff --git a/ffmpeg-n8.1/lib/swscale.lib b/ffmpeg-n8.1/lib/swscale.lib new file mode 100644 index 00000000..3751cddb Binary files /dev/null and b/ffmpeg-n8.1/lib/swscale.lib differ diff --git a/ffmpeg-n8.1/presets/libvpx-1080p.ffpreset b/ffmpeg-n8.1/presets/libvpx-1080p.ffpreset new file mode 100644 index 00000000..cf259321 --- /dev/null +++ b/ffmpeg-n8.1/presets/libvpx-1080p.ffpreset @@ -0,0 +1,19 @@ +vcodec=libvpx + +g=120 +lag-in-frames=16 +deadline=good +cpu-used=0 +vprofile=1 +qmax=51 +qmin=11 +slices=4 +b=2M + +#ignored unless using -pass 2 +maxrate=24M +minrate=100k +auto-alt-ref=1 +arnr-maxframes=7 +arnr-strength=5 +arnr-type=centered diff --git a/ffmpeg-n8.1/presets/libvpx-1080p50_60.ffpreset b/ffmpeg-n8.1/presets/libvpx-1080p50_60.ffpreset new file mode 100644 index 00000000..4a88040d --- /dev/null +++ b/ffmpeg-n8.1/presets/libvpx-1080p50_60.ffpreset @@ -0,0 +1,19 @@ +vcodec=libvpx + +g=120 +lag-in-frames=25 +deadline=good +cpu-used=0 +vprofile=1 +qmax=51 +qmin=11 +slices=4 +b=2M + +#ignored unless using -pass 2 +maxrate=24M +minrate=100k +auto-alt-ref=1 +arnr-maxframes=7 +arnr-strength=5 +arnr-type=centered diff --git a/ffmpeg-n8.1/presets/libvpx-360p.ffpreset b/ffmpeg-n8.1/presets/libvpx-360p.ffpreset new file mode 100644 index 00000000..f9729ba2 --- /dev/null +++ b/ffmpeg-n8.1/presets/libvpx-360p.ffpreset @@ -0,0 +1,18 @@ +vcodec=libvpx + +g=120 +lag-in-frames=16 +deadline=good +cpu-used=0 +vprofile=0 +qmax=63 +qmin=0 +b=768k + +#ignored unless using -pass 2 +maxrate=1.5M +minrate=40k +auto-alt-ref=1 +arnr-maxframes=7 +arnr-strength=5 +arnr-type=centered diff --git a/ffmpeg-n8.1/presets/libvpx-720p.ffpreset b/ffmpeg-n8.1/presets/libvpx-720p.ffpreset new file mode 100644 index 00000000..e84cc150 --- /dev/null +++ b/ffmpeg-n8.1/presets/libvpx-720p.ffpreset @@ -0,0 +1,19 @@ +vcodec=libvpx + +g=120 +lag-in-frames=16 +deadline=good +cpu-used=0 +vprofile=0 +qmax=51 +qmin=11 +slices=4 +b=2M + +#ignored unless using -pass 2 +maxrate=24M +minrate=100k +auto-alt-ref=1 +arnr-maxframes=7 +arnr-strength=5 +arnr-type=centered diff --git a/ffmpeg-n8.1/presets/libvpx-720p50_60.ffpreset b/ffmpeg-n8.1/presets/libvpx-720p50_60.ffpreset new file mode 100644 index 00000000..8fce2bfb --- /dev/null +++ b/ffmpeg-n8.1/presets/libvpx-720p50_60.ffpreset @@ -0,0 +1,19 @@ +vcodec=libvpx + +g=120 +lag-in-frames=25 +deadline=good +cpu-used=0 +vprofile=0 +qmax=51 +qmin=11 +slices=4 +b=2M + +#ignored unless using -pass 2 +maxrate=24M +minrate=100k +auto-alt-ref=1 +arnr-maxframes=7 +arnr-strength=5 +arnr-type=centered diff --git a/onnxruntime/include/onnxruntime_c_api.h b/onnxruntime/include/onnxruntime_c_api.h index 8561de9c..6ae1539d 100644 --- a/onnxruntime/include/onnxruntime_c_api.h +++ b/onnxruntime/include/onnxruntime_c_api.h @@ -1,4 +1,4 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. +// Copyright (c) Microsoft Corporation. All rights reserved. // Licensed under the MIT License. // See docs\c_cxx\README.md on generating the Doxygen documentation from this file @@ -38,7 +38,7 @@ * * This value is used by some API functions to behave as this version of the header expects. */ -#define ORT_API_VERSION 23 +#define ORT_API_VERSION 24 #ifdef __cplusplus extern "C" { @@ -87,7 +87,7 @@ extern "C" { #else #define ORT_EXPORT #endif -#define ORT_API_CALL _stdcall +#define ORT_API_CALL __stdcall #define ORT_MUST_USE_RESULT #define ORTCHAR_T wchar_t #else @@ -206,7 +206,12 @@ typedef enum ONNXTensorElementDataType { ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT8E5M2FNUZ, // Non-IEEE floating-point format based on IEEE754 single-precision // Int4 types were introduced in ONNX 1.16. See https://onnx.ai/onnx/technical/int4.html ONNX_TENSOR_ELEMENT_DATA_TYPE_UINT4, // maps to a pair of packed uint4 values (size == 1 byte) - ONNX_TENSOR_ELEMENT_DATA_TYPE_INT4 // maps to a pair of packed int4 values (size == 1 byte) + ONNX_TENSOR_ELEMENT_DATA_TYPE_INT4, // maps to a pair of packed int4 values (size == 1 byte) + // Float4 types were introduced in ONNX 1.18. See https://onnx.ai/onnx/technical/float4.html + ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT4E2M1, // maps to a pair of packed float4 values (size == 1 byte) + // Int2 types were introduced in ONNX 1.20. See https://onnx.ai/onnx/technical/int2.html + ONNX_TENSOR_ELEMENT_DATA_TYPE_UINT2, // maps to 4 packed uint2 values (size == 1 byte) + ONNX_TENSOR_ELEMENT_DATA_TYPE_INT2, // maps to 4 packed int2 values (size == 1 byte) } ONNXTensorElementDataType; // Synced with onnx TypeProto oneof @@ -328,6 +333,12 @@ ORT_RUNTIME_CLASS(EpDevice); ORT_RUNTIME_CLASS(KeyValuePairs); ORT_RUNTIME_CLASS(SyncStream); // Opaque class to create an onnxruntime::Stream. ORT_RUNTIME_CLASS(ExternalInitializerInfo); +ORT_RUNTIME_CLASS(ExternalResourceImporter); // Capability object for external resource import +ORT_RUNTIME_CLASS(ExternalMemoryHandle); // EP-imported view of shared external allocation +ORT_RUNTIME_CLASS(ExternalSemaphoreHandle); // EP-imported view of shared external semaphore +ORT_RUNTIME_CLASS(DeviceEpIncompatibilityDetails); +ORT_RUNTIME_CLASS(EpAssignedSubgraph); +ORT_RUNTIME_CLASS(EpAssignedNode); #ifdef _MSC_VER typedef _Return_type_success_(return == 0) OrtStatus* OrtStatusPtr; @@ -505,6 +516,16 @@ typedef enum OrtExecutionProviderDevicePolicy { OrtExecutionProviderDevicePolicy_MIN_OVERALL_POWER, } OrtExecutionProviderDevicePolicy; +/** \brief Reasons why an execution provider might not be compatible with a device + */ +typedef enum OrtDeviceEpIncompatibilityReason { + OrtDeviceEpIncompatibility_NONE = 0, + OrtDeviceEpIncompatibility_DRIVER_INCOMPATIBLE = 1 << 0, + OrtDeviceEpIncompatibility_DEVICE_INCOMPATIBLE = 1 << 1, + OrtDeviceEpIncompatibility_MISSING_DEPENDENCY = 1 << 2, + OrtDeviceEpIncompatibility_UNKNOWN = 1 << 31 +} OrtDeviceEpIncompatibilityReason; + /** \brief Delegate to allow providing custom OrtEpDevice selection logic * * This delegate is called by the EP selection code to allow the user to provide custom device selection logic. @@ -876,6 +897,9 @@ typedef struct OrtModelEditorApi OrtModelEditorApi; struct OrtCompileApi; typedef struct OrtCompileApi OrtCompileApi; +struct OrtInteropApi; +typedef struct OrtInteropApi OrtInteropApi; + struct OrtEpApi; typedef struct OrtEpApi OrtEpApi; @@ -946,13 +970,73 @@ typedef OrtStatus*(ORT_API_CALL* RegisterCustomOpsFn)(OrtSessionOptions* options */ typedef void (*RunAsyncCallbackFn)(void* user_data, OrtValue** outputs, size_t num_outputs, OrtStatusPtr status); -/** \brief The C API +/** \brief External memory handle type for importing GPU resources. * - * All C API functions are defined inside this structure as pointers to functions. - * Call OrtApiBase::GetApi to get a pointer to it + * \todo Add OPAQUE_WIN32 for Windows Vulkan-specific memory handles + * \todo Add POSIX file descriptor (OPAQUE_FD) for Linux Vulkan/CUDA/OpenCL interop + * \todo Add Linux DMA-BUF file descriptor for embedded GPU memory sharing * - * \nosubgrouping + * \since Version 1.24. */ +typedef enum OrtExternalMemoryHandleType { + ORT_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE = 0, /**< Shared HANDLE from ID3D12Device::CreateSharedHandle(resource) */ + ORT_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP = 1, /**< Shared HANDLE from ID3D12Device::CreateSharedHandle(heap) */ +} OrtExternalMemoryHandleType; + +/** \brief Descriptor for importing external memory. + * + * \note The version field must be set to ORT_API_VERSION. + * This ensures forward compatibility as fields may be added in future versions. + * + * \since Version 1.24. + */ +typedef struct OrtExternalMemoryDescriptor { + uint32_t version; /**< Must be ORT_API_VERSION */ + OrtExternalMemoryHandleType handle_type; /**< Type of the external memory handle */ + void* native_handle; /**< Platform-specific handle (e.g., Windows HANDLE) */ + size_t size_bytes; /**< Total size in bytes of the external allocation */ + size_t offset_bytes; /**< Offset in bytes into the allocation (default 0). + Base offset for the imported memory region. */ +} OrtExternalMemoryDescriptor; + +/** \brief External semaphore type for GPU synchronization. + * + * \since Version 1.24. + */ +typedef enum OrtExternalSemaphoreType { + ORT_EXTERNAL_SEMAPHORE_D3D12_FENCE = 0, /**< Shared HANDLE from ID3D12Device::CreateSharedHandle(fence) */ +} OrtExternalSemaphoreType; + +/** \brief Descriptor for importing external semaphores. + * + * \note The version field must be set to ORT_API_VERSION. + * This ensures forward compatibility as fields may be added in future versions. + * + * \since Version 1.24. + */ +typedef struct OrtExternalSemaphoreDescriptor { + uint32_t version; /**< Must be ORT_API_VERSION */ + OrtExternalSemaphoreType type; /**< Type of the external semaphore */ + void* native_handle; /**< Platform-specific handle (e.g., Windows HANDLE) */ +} OrtExternalSemaphoreDescriptor; + +/** \brief Descriptor for creating a tensor from imported external memory. + * + * \note The version field must be set to ORT_API_VERSION. + * This ensures forward compatibility as fields may be added in future versions. + * + * \since Version 1.24. + */ +typedef struct OrtExternalTensorDescriptor { + uint32_t version; /**< Must be ORT_API_VERSION */ + ONNXTensorElementDataType element_type; /**< Data type of tensor elements */ + const int64_t* shape; /**< Array of dimension sizes */ + size_t rank; /**< Number of dimensions */ + size_t offset_bytes; /**< Additional offset within imported memory (default 0). + Applied relative to OrtExternalMemoryDescriptor::offset_bytes. + Enables multiple tensors from the same imported memory handle. */ +} OrtExternalTensorDescriptor; + /* * Public enum for compiled model compatibility across EPs. */ @@ -963,6 +1047,101 @@ typedef enum OrtCompiledModelCompatibility { OrtCompiledModelCompatibility_EP_UNSUPPORTED, } OrtCompiledModelCompatibility; +/** \brief Configuration options for creating an OrtEnv. + * + * \note The version field must be set to ORT_API_VERSION. + * This ensures forward compatibility as fields may be added in future versions. + * + * \since Version 1.24. + */ +typedef struct OrtEnvCreationOptions { + uint32_t version; ///< Must be set to ORT_API_VERSION + + /** \brief The logging severity level for the environment. Must be set to a value from OrtLoggingLevel. + * + * \note Logging messages which are less severe than the `logging_severity_level` are not emitted. + * + * \note Serves as the default logging severity level for session creation and runs. + * Use OrtApi::SetSessionLogSeverityLevel to set a logging severity level for the creation of specific session. + * Use OrtApi::RunOptionsSetRunLogSeverityLevel to set a logging severity level for a specific session run. + * + * \since Version 1.24. + */ + int32_t logging_severity_level; + + /** \brief The log identifier. Must be set to a valid UTF-8 null-terminated string. + * + * \note This string identifier is copied by ORT. + * + * \since Version 1.24. + */ + const char* log_id; + + /** \brief Optional custom logging function. May be set to NULL. + * + * \note The OrtEnvCreationOptions::custom_logging_param is provided as the first argument to this logging function. + * This allows passing custom state into the logging function. + * + * \note This function is only called when a message's severity meets or exceeds the set logging severity level. + * + * \since Version 1.24. + */ + OrtLoggingFunction custom_logging_function; + + /** \brief Optional state to pass as the first argument to OrtEnvCreationOptions::custom_logger_function. + * May be set to NULL. + * + * \since Version 1.24. + */ + void* custom_logging_param; + + /** \brief Optional threading options for creating an environment with global thread pools shared across sessions. + * May be set to NULL. + * + * \note The OrtThreadingOptions instance is copied by ORT. + * + * \note Use OrtApi::CreateThreadingOptions() to create an instance of OrtThreadingOptions. + * + * \note Use this in conjunction with OrtApi::DisablePerSessionThreads or else the session will use its own + * thread pools. + * + * \since Version 1.24. + */ + const OrtThreadingOptions* threading_options; + + /** \brief Optional environment configuration entries represented as string key-value pairs. May be set to NULL. + * + * \note The OrtKeyValuePairs instance is copied by ORT. + * + * \note Refer to onnxruntime_env_config_keys.h for common config entry keys and their supported values. + * + * \note An application provides environment-level configuration options for execution provider libraries by + * using keys with the prefix 'ep_factory.\\.'. Ex: the key 'ep_factory.my_ep.some_ep_key' represents + * a key named 'some_ep_key' that is meant to be consumed by an execution provider named 'my_ep'. Refer to + * the specific execution provider's documentation for valid keys and values. + * + * \note An application may separately set session-level configuration options for execution providers via other APIs + * such as SessionOptionsAppendExecutionProvider_V2, which store configuration entries within OrtSessionOptions. + * If an environment-level configuration conflicts with a session-level configuration, then + * precedence is determined by the execution provider library itself. + * + * \since Version 1.24. + */ + const OrtKeyValuePairs* config_entries; + + // + // End of fields available in ORT 1.24 + // + +} OrtEnvCreationOptions; + +/** \brief The C API + * + * All C API functions are defined inside this structure as pointers to functions. + * Call OrtApiBase::GetApi to get a pointer to it + * + * \nosubgrouping + */ struct OrtApi { /// \name OrtStatus /// @{ @@ -3935,6 +4114,7 @@ struct OrtApi { * -# "69" * -# "73" * -# "75" + * -# "81" * "device_id": The ID of the device to use when setting 'htp_arch'. Defaults to "0" (for single device). * "enable_htp_fp16_precision": Used for float32 model for HTP backend. * Enable the float32 model to be inferenced with fp16 precision. Otherwise, it will be fp32 precision. @@ -3961,6 +4141,9 @@ struct OrtApi { *   where op_type is the name of the operation, op_package_path is the path to the op package shared library, * interface is the symbol name to register the op life cycle functions, and target is the backend type. For more * details, refer to: https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-50/op_packages.html + * [Advanced] "skip_qnn_version_check": Set to "1" to allow a different version of QNN to be used than what was compiled + * into ONNX Runtime. Differences in operator support, accuracy, performance, and QNN's ABI may lead to crashes, inaccurate + * results, and poor performance. Use with caution and test thoroughly. * * XNNPACK supported keys: * "intra_op_num_threads": number of thread-pool size to use for XNNPACK execution provider. @@ -4198,7 +4381,7 @@ struct OrtApi { * If `out` is nullptr, the value of `size` is set to the size of the name * string (including null-terminator), and a success status is returned. * - * If the `size` parameter is greater than or equal to the name string's size, + * If the `size` parameter is greater than or equal to the name string's size and `out` is not nullptr, * the value of `size` is set to the true size of the string (including null-terminator), * the provided memory is filled with the string's contents, and a success status is returned. * @@ -4214,7 +4397,7 @@ struct OrtApi { * \snippet{doc} snippets.dox OrtStatus Return Value * \since Version 1.14 */ - ORT_API2_STATUS(KernelInfo_GetInputName, _In_ const OrtKernelInfo* info, size_t index, _Out_ char* out, + ORT_API2_STATUS(KernelInfo_GetInputName, _In_ const OrtKernelInfo* info, size_t index, _Out_opt_ char* out, _Inout_ size_t* size); /** \brief Get the name of a ::OrtKernelInfo's output. @@ -4225,7 +4408,7 @@ struct OrtApi { * If `out` is nullptr, the value of `size` is set to the size of the name * string (including null-terminator), and a success status is returned. * - * If the `size` parameter is greater than or equal to the name string's size, + * If the `size` parameter is greater than or equal to the name string's size and `out` is not nullptr, * the value of `size` is set to the true size of the string (including null-terminator), * the provided memory is filled with the string's contents, and a success status is returned. * @@ -4242,7 +4425,7 @@ struct OrtApi { * \snippet{doc} snippets.dox OrtStatus Return Value * \since Version 1.14 */ - ORT_API2_STATUS(KernelInfo_GetOutputName, _In_ const OrtKernelInfo* info, size_t index, _Out_ char* out, + ORT_API2_STATUS(KernelInfo_GetOutputName, _In_ const OrtKernelInfo* info, size_t index, _Out_opt_ char* out, _Inout_ size_t* size); /** \brief Get the type information for a ::OrtKernelInfo's input. @@ -4422,7 +4605,7 @@ struct OrtApi { * If `out` is nullptr, the value of `size` is set to the size of the name * string (including null-terminator), and a success status is returned. * - * If the `size` parameter is greater than or equal to the name string's size, + * If the `size` parameter is greater than or equal to the name string's size and `out` is not nullptr, * the value of `size` is set to the true size of the string (including null-terminator), * the provided memory is filled with the string's contents, and a success status is returned. * @@ -4439,7 +4622,7 @@ struct OrtApi { * \snippet{doc} snippets.dox OrtStatus Return Value * \since Version 1.15 */ - ORT_API2_STATUS(KernelInfo_GetNodeName, _In_ const OrtKernelInfo* info, _Out_ char* out, _Inout_ size_t* size); + ORT_API2_STATUS(KernelInfo_GetNodeName, _In_ const OrtKernelInfo* info, _Out_opt_ char* out, _Inout_ size_t* size); /** \brief Get the session logger from ::OrtKernelInfo. * @@ -4587,7 +4770,7 @@ struct OrtApi { * * \param[in] context OrtKernelContext instance * \param[in] mem_info OrtMemoryInfo instance - * \param[out] out A pointer to OrtAllocator. + * \param[out] out A pointer to OrtAllocator. Must be released with OrtApi::ReleaseAllocator. * * \snippet{doc} snippets.dox OrtStatus Return Value * @@ -5106,7 +5289,7 @@ struct OrtApi { * * \since Version 1.22. */ - const OrtModelEditorApi*(ORT_API_CALL* GetModelEditorApi)(); + const OrtModelEditorApi*(ORT_API_CALL* GetModelEditorApi)(void); /** \brief Create an OrtValue for a Tensor that uses pre-existing memory. * @@ -5164,7 +5347,7 @@ struct OrtApi { * * \since Version 1.22. */ - const OrtCompileApi*(ORT_API_CALL* GetCompileApi)(); + const OrtCompileApi*(ORT_API_CALL* GetCompileApi)(void); // // OrtKeyValuePairs @@ -5432,7 +5615,7 @@ struct OrtApi { * * \since Version 1.22. */ - const OrtEpApi*(ORT_API_CALL* GetEpApi)(); + const OrtEpApi*(ORT_API_CALL* GetEpApi)(void); /** \brief Compute total size in bytes of the tensor data contained in an OrtValue. * @@ -5911,7 +6094,8 @@ struct OrtApi { /** \brief Returns an OrtGraph that contains a subset of nodes in the source OrtGraph. * * \note The lifetime of "dst_graph" is tied to that of "src_graph", as they both internally reference - * the same underlying graph. + * the same underlying graph. "dst_graph" preserves the input order of "src_graph", and + * its output order corresponds to the outputs produced by the nodes in "nodes" with the given order. * * \param[in] src_graph The source OrtGraph instance. * \param[in] nodes A subset of the nodes/OrtNodes in 'graph'. @@ -6200,6 +6384,9 @@ struct OrtApi { /** \brief Get the node's parent OrtGraph instance. * * Can return NULL if the OrtNode was created without an owning graph. + * In another case, this API may also return NULL if `node` is obtained by calling Graph_GetParentNode() + * on an OrtGraph that is a subgraph of a control-flow op, and the parent graph has not been created yet, + * for example during ORT's GetCapability() when processing the innermost subgraph. * * \param[in] node The OrtNode instance. * \param[out] graph Output parameter set to the node's OrtGraph. Can be set to NULL @@ -6578,6 +6765,461 @@ struct OrtApi { _In_ size_t byte_size, _Outptr_ OrtExternalInitializerInfo** out); /// @} + /** \brief Fetch whether the tensor has shape information. + * \param[in] info The OrtTensorTypeAndShapeInfo instance. + * \return true if the tensor has shape information, false otherwise. + * + * \since Version 1.24 + */ + ORT_API_T(bool, TensorTypeAndShape_HasShape, _In_ const OrtTensorTypeAndShapeInfo* info); + + /** \brief Get all config entries from ::OrtKernelInfo. + * + * Gets all configuration entries from the ::OrtKernelInfo object as key-value pairs. + * Config entries are set on the ::OrtSessionOptions and are accessible in custom operator kernels. + * + * Used in the CreateKernel callback of an OrtCustomOp to access all session configuration entries + * during kernel construction. + * + * \param[in] info An instance of ::OrtKernelInfo. + * \param[out] out A pointer to a newly created OrtKeyValuePairs instance containing all config entries. + * Note: the user should call OrtApi::ReleaseKeyValuePairs. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(KernelInfo_GetConfigEntries, _In_ const OrtKernelInfo* info, _Outptr_ OrtKeyValuePairs** out); + + /** \brief Get the graph node's operator domain from ::OrtKernelInfo. + * + * If `out` is nullptr, the value of `size` is set to the size of the operator domain + * string (including null-terminator), and a success status is returned. + * + * If the `size` parameter is greater than or equal to the string's size and `out` is not nullptr, + * the value of `size` is set to the true size of the string (including null-terminator), + * the provided memory is filled with the string's contents, and a success status is returned. + * + * If the `size` parameter is less than the actual string's size and `out` + * is not nullptr, the value of `size` is set to the true size of the string + * and a failure status with error code ORT_INVALID_ARGUMENT is returned. + * + * \param[in] info An instance of ::OrtKernelInfo. + * \param[out] out Memory location into which to write the UTF-8 null-terminated string representing the + * operator domain. + * \param[in,out] size Pointer to the size of the `out` buffer. See above comments for details. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(KernelInfo_GetOperatorDomain, _In_ const OrtKernelInfo* info, _Out_opt_ char* out, + _Inout_ size_t* size); + + /** \brief Get the graph node's operator type from ::OrtKernelInfo. + * + * If `out` is nullptr, the value of `size` is set to the size of the operator type + * string (including null-terminator), and a success status is returned. + * + * If the `size` parameter is greater than or equal to the string's size and `out` is not nullptr, + * the value of `size` is set to the true size of the string (including null-terminator), + * the provided memory is filled with the string's contents, and a success status is returned. + * + * If the `size` parameter is less than the actual string's size and `out` + * is not nullptr, the value of `size` is set to the true size of the string + * and a failure status with error code ORT_INVALID_ARGUMENT is returned. + * + * \param[in] info An instance of ::OrtKernelInfo. + * \param[out] out Memory location into which to write the UTF-8 null-terminated string representing the + * operator type. + * \param[in,out] size Pointer to the size of the `out` buffer. See above comments for details. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(KernelInfo_GetOperatorType, _In_ const OrtKernelInfo* info, _Out_opt_ char* out, + _Inout_ size_t* size); + + /** \brief Get the opset version in which the given node's operator type was first defined from ::OrtKernelInfo. + * + * \param[in] info An instance of ::OrtKernelInfo. + * \param[out] since_version The opset version in which the node's operator type was first defined. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(KernelInfo_GetOperatorSinceVersion, _In_ const OrtKernelInfo* info, + _Out_ int* since_version); + + /** \brief Get the EP Interop API instance. + * + * Get the Interop API instance to work with external resources. This API provides functions + * for importing external GPU memory and semaphores for zero-copy sharing between ORT inference + * and other GPU workloads. + * + * \return Interop API struct instance. + * + * \since Version 1.24. + */ + const OrtInteropApi*(ORT_API_CALL* GetInteropApi)(void); + + /** \brief Get the EP device assigned to each session output. + * + * Returns the OrtEpDevice assigned to each output of the session after graph partitioning. + * This allows validation that outputs are placed on the expected device for external resource sharing. + * + * The EP device for each output is determined by which execution provider will produce that output + * during inferencing. This information is useful for: + * - Validating that outputs will be placed on the expected device for external resource sharing + * - Deciding whether to use external memory handles for outputs + * + * \param[in] session The OrtSession instance to query. + * \param[out] outputs_ep_devices An array to be filled with the EP device for each output. + * The array must be allocated by the caller with space for + * OrtEpDevice* values for each output. + * The order is the same as returned by SessionGetOutputName. + * \param[in] num_outputs The number of outputs in the session. Must match SessionGetOutputCount. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24 + */ + ORT_API2_STATUS(SessionGetEpDeviceForOutputs, _In_ const OrtSession* session, + _Out_writes_(num_outputs) const OrtEpDevice** outputs_ep_devices, + _In_ size_t num_outputs); + /** \brief Get the number of available hardware devices. + * + * Returns the count of hardware devices discovered on the system. + * Use this to allocate an array before calling GetHardwareDevices(). + * + * \param[in] env The OrtEnv instance where device discovery results are stored. + * \param[out] num_devices The number of OrtHardwareDevice instances available. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetNumHardwareDevices, _In_ const OrtEnv* env, _Out_ size_t* num_devices); + + /** \brief Get the list of available hardware devices. + * + * Enumerates hardware devices available on the system. + * Populates a user-provided array with pointers to OrtHardwareDevice instances. The caller is responsible + * for allocating the array with sufficient space (use GetNumHardwareDevices() to get the count). + * + * The returned pointers reference internal ORT data structures that are discovered once at process + * startup and remain valid for the lifetime of the OrtEnv. The caller does not need to release these + * pointers, but should not use them after calling ReleaseEnv(). + * + * \param[in] env The OrtEnv instance where device discovery results are stored. + * \param[out] devices User-allocated array to receive pointers to OrtHardwareDevice instances. + * The array must have space for at least num_devices elements. + * \param[in] num_devices The size of the user-allocated devices array. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetHardwareDevices, _In_ const OrtEnv* env, + _Out_writes_(num_devices) const OrtHardwareDevice** devices, + _In_ size_t num_devices); + + /** \brief Check for known incompatibility issues between hardware device and a specific execution provider. + * + * This function checks for known incompatibility issues between the specified hardware device + * and a specific execution provider. + * If returned incompatibility details have non-zero reasons, it indicates the device is not compatible. + * However, if returned detail have reason == 0, it doesn't guarantee 100% compatibility for all models, + * as models may have specific requirements. + * + * Note: This method should only be called when the OrtEnv has been initialized with execution + * providers (after RegisterExecutionProviderLibrary is called). + * + * \param[in] env The OrtEnv instance with registered execution providers. + * \param[in] ep_name The name of the execution provider to check. Required and cannot be null or empty. + * \param[in] hw The hardware device to check for incompatibility. + * \param[out] details Compatibility details including reasons for incompatibility if any. + * Must be freed with OrtApi::ReleaseDeviceEpIncompatibilityDetails. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetHardwareDeviceEpIncompatibilityDetails, _In_ const OrtEnv* env, + _In_ const char* ep_name, + _In_ const OrtHardwareDevice* hw, + _Outptr_ OrtDeviceEpIncompatibilityDetails** details); + + /// \name OrtDeviceEpIncompatibilityDetails + /// Accessor functions for device incompatibility details + /// @{ + + /** \brief Get the incompatibility reasons bitmask from OrtDeviceEpIncompatibilityDetails. + * + * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query. + * \param[out] reasons_bitmask Pointer to store the bitmask of incompatibility reasons. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetReasonsBitmask, + _In_ const OrtDeviceEpIncompatibilityDetails* details, + _Out_ uint32_t* reasons_bitmask); + + /** \brief Get the notes from OrtDeviceEpIncompatibilityDetails. + * + * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query. + * \param[out] notes Pointer to the notes string. May be nullptr if no notes are available. + * The returned string is owned by the details object and should not be freed. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetNotes, + _In_ const OrtDeviceEpIncompatibilityDetails* details, + _Outptr_result_maybenull_ const char** notes); + + /** \brief Get the execution provider error code from OrtDeviceEpIncompatibilityDetails. + * + * This allows Independent Hardware Vendors (IHVs) to define their own error codes + * to provide additional details about device incompatibility. + * + * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query. + * \param[out] error_code Pointer to store the EP-specific error code. A value of 0 indicates no error code was set. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetErrorCode, + _In_ const OrtDeviceEpIncompatibilityDetails* details, + _Out_ int32_t* error_code); + + /** \brief Release an OrtDeviceEpIncompatibilityDetails instance. + * + * \since Version 1.24. + */ + ORT_CLASS_RELEASE(DeviceEpIncompatibilityDetails); + + /// @} + + /// \name Model Compatibility APIs + /// @{ + + /** \brief Extract EP compatibility info from a precompiled model file. + * + * Parses the model file to extract the compatibility info string for a specific execution provider + * from the model's metadata properties. This is only applicable to models that have been precompiled + * for an EP (e.g., via OrtCompileApi). Standard ONNX models do not contain this information. + * + * The compatibility info string must be valid UTF-8 without embedded NUL characters. + * + * \note This API performs standalone model parsing, separate from session creation. This means + * the protobuf parsing cost is incurred here and again during session creation. It is intended + * for scenarios where applications need to check compatibility before deciding whether to proceed + * with session creation, such as providing early user feedback. + * + * \note This operation parses the full ONNX ModelProto from disk. For very large models, consider + * using GetCompatibilityInfoFromModelBytes with a pre-loaded buffer if the model is already in memory. + * + * The compatibility info can then be passed to GetModelCompatibilityForEpDevices to check if a + * precompiled model is compatible with the current system. + * + * \param[in] model_path Path to the ONNX model file. + * \param[in] ep_type The execution provider type string. Must be non-empty. + * Use OrtApi::EpDevice_EpName to get this value from an OrtEpDevice. + * \param[in] allocator Allocator to use for the output string. Use OrtApi::GetAllocatorWithDefaultOptions. + * \param[out] compatibility_info Output pointer to the compatibility info string. + * Returns nullptr if no compatibility info exists for the specified EP. + * Caller must free with OrtApi::AllocatorFree when non-null. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetCompatibilityInfoFromModel, + _In_ const ORTCHAR_T* model_path, + _In_ const char* ep_type, + _Inout_ OrtAllocator* allocator, + _Outptr_result_maybenull_ char** compatibility_info); + + /** \brief Extract EP compatibility info from precompiled model bytes in memory. + * + * Same as GetCompatibilityInfoFromModel but reads from a memory buffer instead of a file. + * Useful when precompiled models are loaded from encrypted storage, network, or other non-file sources. + * + * \note This API performs standalone model parsing, separate from session creation. This means + * the protobuf parsing cost is incurred here and again during session creation. It is intended + * for scenarios where applications need to check compatibility before deciding whether to proceed + * with session creation, such as providing early user feedback. + * + * \param[in] model_data Pointer to the model data in memory. + * \param[in] model_data_length Size of the model data in bytes. + * \param[in] ep_type The execution provider type string. Must be non-empty. + * \param[in] allocator Allocator to use for the output string. Use OrtApi::GetAllocatorWithDefaultOptions. + * \param[out] compatibility_info Output pointer to the compatibility info string. + * Returns nullptr if no compatibility info exists for the specified EP. + * Caller must free with OrtApi::AllocatorFree when non-null. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetCompatibilityInfoFromModelBytes, + _In_reads_(model_data_length) const void* model_data, + _In_ size_t model_data_length, + _In_ const char* ep_type, + _Inout_ OrtAllocator* allocator, + _Outptr_result_maybenull_ char** compatibility_info); + + /// @} + + /** \brief Create an OrtEnv instance with the given options. + * + * \note Invoking this function will return the same instance of the environment as that returned by a previous call + * to another env creation function; all arguments to this function will be ignored. + * + * \param[in] options The OrtEnvCreationOptions instance that contains creation options. + * \param[out] out Output parameter set to the new OrtEnv instance. Must be freed with OrtApi::ReleaseEnv. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24 + */ + ORT_API2_STATUS(CreateEnvWithOptions, _In_ const OrtEnvCreationOptions* options, _Outptr_ OrtEnv** out); + + /** \brief Get information about the subgraphs assigned to each execution provider (EP) and the nodes within. + * + * Each returned OrtEpAssignedSubgraph instance contains details of the subgraph/nodes assigned to an execution + * provider, including the execution provider's name, and the name, domain, and operator type for every node. + * + * For compiling execution providers, a single OrtEpAssignedSubgraph instance contains information about the + * nodes that are fused and compiled within a single subgraph assigned to the execution provider. + * + * For execution providers that use kernel registration (e.g., CPU EP), each node with a registered kernel is + * contained in its own OrtEpAssignedSubgraph instance. + * + * \note The caller must enable the collection of this information by enabling the session + * configuration entry "session.record_ep_graph_assignment_info" during session creation. + * Refer to onnxruntime_session_options_config_keys.h. Otherwise, if not enabled, this function returns a + * status with error code ORT_FAIL. + * + * \note The information reported by this function is obtained immediately after running basic optimizations on the + * original graph if the session optimization level is set to ORT_ENABLE_BASIC or higher. If the session + * optimization level is set to ORT_DISABLE_ALL, only minimal/required optimizations are run before + * the information is collected. + * + * \param[in] session The OrtSession instance. + * \param[out] ep_subgraphs Output parameter set to the array of OrtEpAssignedSubgraph instances. + * \param[out] num_ep_subgraphs Output parameter set to the number of elements in the `ep_subgraphs` array. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(Session_GetEpGraphAssignmentInfo, _In_ const OrtSession* session, + _Outptr_ const OrtEpAssignedSubgraph* const** ep_subgraphs, + _Out_ size_t* num_ep_subgraphs); + + /** \brief Get the name of the execution provider to which the subgraph was assigned. + * + * \param[in] ep_subgraph The OrtEpAssignedSubgraph instance. + * \param[out] out Output parameter set to the execution provider's name as a UTF-8 null-terminated string. + * Owned by the OrtEpAssignedSubgraph instance (do not free). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(EpAssignedSubgraph_GetEpName, _In_ const OrtEpAssignedSubgraph* ep_subgraph, + _Outptr_ const char** out); + + /** \brief Get the nodes in a subgraph assigned to a specific execution provider. + * + * \param[in] ep_subgraph The OrtEpAssignedSubgraph instance. + * \param[out] ep_nodes Output parameter set to the array of OrtEpAssignedNode instances. + * \param[out] num_ep_nodes Output parameter set to the number of OrtEpAssignedNode instance returned. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(EpAssignedSubgraph_GetNodes, _In_ const OrtEpAssignedSubgraph* ep_subgraph, + _Outptr_ const OrtEpAssignedNode* const** ep_nodes, _Out_ size_t* num_ep_nodes); + + /** \brief Get the name of the node assigned to an execution provider. + * + * \param[in] ep_node The OrtEpAssignedNode instance. + * \param[out] out Output parameter set to the node's name as a UTF-8 null-terminated string. + * Owned by the OrtEpAssignedNode instance (do not free). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(EpAssignedNode_GetName, _In_ const OrtEpAssignedNode* ep_node, _Outptr_ const char** out); + + /** \brief Get the domain of the node assigned to an execution provider. + * + * \param[in] ep_node The OrtEpAssignedNode instance. + * \param[out] out Output parameter set to the node's domain as a UTF-8 null-terminated string. + * Owned by the OrtEpAssignedNode instance (do not free). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(EpAssignedNode_GetDomain, _In_ const OrtEpAssignedNode* ep_node, _Outptr_ const char** out); + + /** \brief Get the operator type of the node assigned to an execution provider. + * + * \param[in] ep_node The OrtEpAssignedNode instance. + * \param[out] out Output parameter set to the node's operator type as a UTF-8 null-terminated string. + * Owned by the OrtEpAssignedNode instance (do not free). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(EpAssignedNode_GetOperatorType, _In_ const OrtEpAssignedNode* ep_node, _Outptr_ const char** out); + + /** \brief Sets OrtSyncStream for the run options + * + * OrtSyncStream is used to synchronize the execution of the model run for the device + * of the stream. It overrides the existing stream for the duration of the Run(). + * The stream instance must be alive for the duration of the Run() call. + * + * \param[in] options + * \param[in] sync_stream The synchronization stream. Pass nullptr to clear previous setting. + * + * \since 1.24 + */ + ORT_API_T(void, RunOptionsSetSyncStream, _Inout_ OrtRunOptions* options, _In_ OrtSyncStream* sync_stream); + + /** \brief Get the element data type and shape for an OrtValue that represents a Tensor (scalar, dense, or sparse). + * + * \note This function is an alternative to ::GetTensorTypeAndShape() that does not allocate a new array for + * the shape data. The OrtValue instance's internal shape data is returned directly. + * + * \note Returns an error if the underlying OrtValue is not a Tensor. + * + * \param[in] value The OrtValue instance. + * \param[out] elem_type Output parameter set to the tensor element data type. + * \param[out] shape_data Output parameter set to the OrtValue instance's internal shape data array. + * For a scalar, `shape_data` is NULL and `shape_data_count` is 0. + * Must not be released as it is owned by the OrtValue instance. This pointer becomes invalid + * when the OrtValue is released or if the underlying shape data is updated or reallocated. + * \param[out] shape_data_count Output parameter set to the number of elements in `shape_data`. + * `shape_data_count` is 0 for a scalar. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetTensorElementTypeAndShapeDataReference, _In_ const OrtValue* value, + _Out_ ONNXTensorElementDataType* elem_type, + _Outptr_result_maybenull_ const int64_t** shape_data, + _Out_ size_t* shape_data_count); }; /* @@ -7375,6 +8017,224 @@ struct OrtCompileApi { _In_ OrtGetInitializerLocationFunc get_initializer_location_func, _In_ void* state); }; +/** + * \brief The OrtInteropApi struct provides functions for external resource interop with execution providers. + * + * This API enables importing external GPU resources (memory and semaphores) for zero-copy sharing + * between ORT inference and other GPU workloads (e.g., D3D12 applications, media pipelines). + * + * The API is designed to be EP-agnostic and can be extended to support various GPU interop mechanisms + * (D3D12 shared handles, CUDA external memory, Vulkan, etc.). + * + * Example usage (error handling not shown): + * const OrtInteropApi* interop_api = ort_api->GetInteropApi(); + * OrtExternalResourceImporter* importer = NULL; + * + * status = interop_api->CreateExternalResourceImporterForDevice(ep_device, &importer); + * if (importer == nullptr) { + * // External resource import is optional for EPs to implement + * return; + * } + * bool can_import = false; + * status = interop_api->CanImportMemory(importer, ORT_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE, &can_import); + * if (can_import) { + * OrtExternalMemoryHandle* mem_handle = NULL; + * status = interop_api->ImportMemory(importer, &mem_desc, &mem_handle); + * // ... use mem_handle to create tensors ... + * interop_api->ReleaseExternalMemoryHandle(mem_handle); + * } + * interop_api->ReleaseExternalResourceImporter(importer); + * + * \since Version 1.24. + */ +struct OrtInteropApi { + /// \name OrtExternalResourceImporter + /// @{ + + /** \brief Create an external resource importer for a specific EP device. + * + * The external resource importer is a capability object that provides methods for importing + * external GPU memory and semaphores for zero-copy import with an execution provider. + * + * This is an optional EP capability. If the EP does not support external resource import, + * out_importer is set to nullptr and the function returns success (nullptr status). + * This allows callers to use the simple "if (status != nullptr) handle_error()" pattern + * and check out_importer separately for capability detection. + * + * \param[in] ep_device The OrtEpDevice instance to create the importer for. + * \param[out] out_importer Output parameter set to the created OrtExternalResourceImporter instance, + * or nullptr if the EP does not support external resource import. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateExternalResourceImporterForDevice, + _In_ const OrtEpDevice* ep_device, + _Outptr_result_maybenull_ OrtExternalResourceImporter** out_importer); + + /** \brief Release an OrtExternalResourceImporter instance. + * + * \param[in] input The OrtExternalResourceImporter instance to release. May be nullptr. + * + * \since Version 1.24. + */ + ORT_CLASS_RELEASE(ExternalResourceImporter); + + /// @} + /// \name Memory Import + /// @{ + + /** \brief Check if the external resource importer can import a specific memory handle type. + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] handle_type The type of external memory handle to check. + * \param[out] out_supported Set to true if the handle type is supported. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CanImportMemory, + _In_ const OrtExternalResourceImporter* importer, + _In_ OrtExternalMemoryHandleType handle_type, + _Out_ bool* out_supported); + + /** \brief Import external memory into the execution provider. + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] desc Descriptor containing the external memory handle and properties. + * \param[out] out_handle Output parameter set to the created OrtExternalMemoryHandle. + * The caller owns the returned handle and must call ReleaseExternalMemoryHandle to free it. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(ImportMemory, + _In_ OrtExternalResourceImporter* importer, + _In_ const OrtExternalMemoryDescriptor* desc, + _Outptr_ OrtExternalMemoryHandle** out_handle); + + /** \brief Release an OrtExternalMemoryHandle instance. + * + * \param[in] input The OrtExternalMemoryHandle instance to release. May be nullptr. + * + * \since Version 1.24. + */ + ORT_CLASS_RELEASE(ExternalMemoryHandle); + + /** \brief Create a tensor backed by imported external memory. + * + * The created tensor is a view over the imported memory and does not copy data. + * The OrtExternalMemoryHandle must remain valid for the lifetime of the tensor. + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] mem_handle The imported external memory handle. + * \param[in] tensor_desc Descriptor specifying tensor element type, shape, and optional offset. + * \param[out] out_tensor Output parameter set to the created OrtValue containing the tensor. + * The caller owns the returned tensor and must call ReleaseValue to free it. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateTensorFromMemory, + _In_ OrtExternalResourceImporter* importer, + _In_ const OrtExternalMemoryHandle* mem_handle, + _In_ const OrtExternalTensorDescriptor* tensor_desc, + _Outptr_ OrtValue** out_tensor); + + /// @} + /// \name Semaphore Import + /// @{ + + /** \brief Check if the external resource importer can import a specific semaphore type. + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] type The type of external semaphore to check. + * \param[out] out_supported Set to true if the semaphore type is supported. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CanImportSemaphore, + _In_ const OrtExternalResourceImporter* importer, + _In_ OrtExternalSemaphoreType type, + _Out_ bool* out_supported); + + /** \brief Import an external semaphore into the execution provider. + * + * The returned OrtExternalSemaphoreHandle can be used with WaitSemaphore and an OrtSyncStream + * to synchronize execution with external operations. + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] desc Descriptor containing the external semaphore handle and type. + * \param[out] out_handle Output parameter set to the created OrtExternalSemaphoreHandle. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(ImportSemaphore, + _In_ OrtExternalResourceImporter* importer, + _In_ const OrtExternalSemaphoreDescriptor* desc, + _Outptr_ OrtExternalSemaphoreHandle** out_handle); + + /** \brief Release an OrtExternalSemaphoreHandle instance. + * + * \param[in] input The OrtExternalSemaphoreHandle instance to release. May be nullptr. + * + * \since Version 1.24. + */ + ORT_CLASS_RELEASE(ExternalSemaphoreHandle); + + /** \brief Wait on an external semaphore on the EP's stream. + * + * Inserts a wait operation into the EP's stream that blocks until the semaphore + * reaches the specified value. This is used to synchronize with external GPU work + * (e.g., D3D12 timeline fence). + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] semaphore_handle The imported external semaphore. + * \param[in] stream The OrtSyncStream to wait on. + * \param[in] value The fence/semaphore value to wait for. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(WaitSemaphore, + _In_ OrtExternalResourceImporter* importer, + _In_ OrtExternalSemaphoreHandle* semaphore_handle, + _In_ OrtSyncStream* stream, + _In_ uint64_t value); + + /** \brief Signal an external semaphore from the EP's stream. + * + * Inserts a signal operation into the EP's stream that sets the semaphore + * to the specified value when reached. This is used to notify external GPU work + * (e.g., D3D12 timeline fence) that ORT inference is complete. + * + * \param[in] importer The OrtExternalResourceImporter instance. + * \param[in] semaphore_handle The imported external semaphore. + * \param[in] stream The OrtSyncStream to signal from. + * \param[in] value The fence/semaphore value to signal. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(SignalSemaphore, + _In_ OrtExternalResourceImporter* importer, + _In_ OrtExternalSemaphoreHandle* semaphore_handle, + _In_ OrtSyncStream* stream, + _In_ uint64_t value); + + /// @} +}; + /* * This is the old way to add the CUDA provider to the session, please use SessionOptionsAppendExecutionProvider_CUDA above to access the latest functionality * This function always exists, but will only succeed if Onnxruntime was built with CUDA support and the CUDA provider shared library exists diff --git a/onnxruntime/include/onnxruntime_cxx_api.h b/onnxruntime/include/onnxruntime_cxx_api.h index 9fa79156..5cf8cf88 100644 --- a/onnxruntime/include/onnxruntime_cxx_api.h +++ b/onnxruntime/include/onnxruntime_cxx_api.h @@ -80,22 +80,19 @@ struct Exception : std::exception { throw Ort::Exception(string, code) #endif -// This is used internally by the C++ API. This class holds the global variable that points to the OrtApi, -// it's in a template so that we can define a global variable in a header and make -// it transparent to the users of the API. -template -struct Global { - static const OrtApi* api_; -}; - -// If macro ORT_API_MANUAL_INIT is defined, no static initialization will be performed. Instead, user must call InitApi() before using it. -template #ifdef ORT_API_MANUAL_INIT -const OrtApi* Global::api_{}; -inline void InitApi() noexcept { Global::api_ = OrtGetApiBase()->GetApi(ORT_API_VERSION); } +// If the macro ORT_API_MANUAL_INIT is defined, no static initialization +// will be performed. Instead, users must call InitApi() before using the +// ORT C++ APIs.. +// +// InitApi() sets the global API object using the default initialization +// logic. Users call this to initialize the ORT C++ APIs at a time that +// makes sense in their program. +inline void InitApi() noexcept; -// Used by custom operator libraries that are not linked to onnxruntime. Sets the global API object, which is -// required by C++ APIs. +// InitApi(const OrtApi*) is used by custom operator libraries that are not +// linked to onnxruntime. It sets the global API object, which is required +// by the ORT C++ APIs. // // Example mycustomop.cc: // @@ -108,22 +105,88 @@ inline void InitApi() noexcept { Global::api_ = OrtGetApiBase()->GetApi(OR // // ... // } // -inline void InitApi(const OrtApi* api) noexcept { Global::api_ = api; } -#else -#if defined(_MSC_VER) && !defined(__clang__) -#pragma warning(push) -// "Global initializer calls a non-constexpr function." Therefore you can't use ORT APIs in the other global initializers. -// Please define ORT_API_MANUAL_INIT if it conerns you. -#pragma warning(disable : 26426) -#endif -const OrtApi* Global::api_ = OrtGetApiBase()->GetApi(ORT_API_VERSION); -#if defined(_MSC_VER) && !defined(__clang__) -#pragma warning(pop) -#endif +inline void InitApi(const OrtApi* api) noexcept; #endif +namespace detail { +// This is used internally by the C++ API. This class holds the global +// variable that points to the OrtApi. +struct Global { + static const OrtApi* Api(const OrtApi* newValue = nullptr) noexcept { + // This block-level static will be initialized once when this function is + // first executed, delaying the call to DefaultInit() until it is first needed. + // + // When ORT_API_MANUAL_INIT is not defined, DefaultInit() calls + // OrtGetApiBase()->GetApi(), which may result in a shared library being + // loaded. + // + // Using a block-level static instead of a class-level static helps + // avoid issues with static initialization order and dynamic libraries + // loading other dynamic libraries. + // + // This makes it safe to include the C++ API headers in a shared library + // that is delay loaded or delay loads its dependencies. + // + // This DOES NOT make it safe to _use_ arbitrary ORT C++ APIs when + // initializing static members, however. + static const OrtApi* api = DefaultInit(); + + if (newValue) { + api = newValue; + } + + return api; + } + + private: + // Has different definitions based on ORT_API_MANUAL_INIT + static const OrtApi* DefaultInit() noexcept; + +#ifdef ORT_API_MANUAL_INIT + // Public APIs to set the OrtApi* to use. + friend void ::Ort::InitApi() noexcept; + friend void ::Ort::InitApi(const OrtApi*) noexcept; +#endif +}; +} // namespace detail + +#ifdef ORT_API_MANUAL_INIT + +// See comments on declaration above for usage. +inline void InitApi(const OrtApi* api) noexcept { detail::Global::Api(api); } +inline void InitApi() noexcept { InitApi(OrtGetApiBase()->GetApi(ORT_API_VERSION)); } + +#ifdef _MSC_VER +// If you get a linker error about a mismatch here, you are trying to +// link two compilation units that have different definitions for +// ORT_API_MANUAL_INIT together. All compilation units must agree on the +// definition of ORT_API_MANUAL_INIT. +#pragma detect_mismatch("ORT_API_MANUAL_INIT", "enabled") +#endif + +inline const OrtApi* detail::Global::DefaultInit() noexcept { + // When ORT_API_MANUAL_INIT is defined, there's no default init that can + // be done. + return nullptr; +} + +#else // ORT_API_MANUAL_INIT + +#ifdef _MSC_VER +// If you get a linker error about a mismatch here, you are trying to link +// two compilation units that have different definitions for +// ORT_API_MANUAL_INIT together. All compilation units must agree on the +// definition of ORT_API_MANUAL_INIT. +#pragma detect_mismatch("ORT_API_MANUAL_INIT", "disabled") +#endif + +inline const OrtApi* detail::Global::DefaultInit() noexcept { + return OrtGetApiBase()->GetApi(ORT_API_VERSION); +} +#endif // ORT_API_MANUAL_INIT + /// This returns a reference to the ORT C API. -inline const OrtApi& GetApi() noexcept { return *Global::api_; } +inline const OrtApi& GetApi() noexcept { return *detail::Global::Api(); } /// /// This function returns the onnxruntime version string @@ -173,6 +236,20 @@ inline const OrtCompileApi& GetCompileApi() { return *api; } +/// +/// This returns a reference to the ORT C Interop API. Used for external resource import with EPs. +/// +/// ORT C Interop API reference +inline const OrtInteropApi& GetInteropApi() { + auto* api = GetApi().GetInteropApi(); + if (api == nullptr) { + // minimal build + ORT_CXX_API_THROW("Interop API is not available in this build", ORT_FAIL); + } + + return *api; +} + /// /// This returns a reference to the ORT C EP API. Used if authoring a plugin execution provider. /// @@ -581,6 +658,9 @@ ORT_DEFINE_RELEASE(ValueInfo); ORT_DEFINE_RELEASE_FROM_API_STRUCT(ModelCompilationOptions, GetCompileApi); ORT_DEFINE_RELEASE_FROM_API_STRUCT(EpDevice, GetEpApi); +ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelDef, GetEpApi); +ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelDefBuilder, GetEpApi); +ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelRegistry, GetEpApi); // This is defined explicitly since OrtTensorRTProviderOptionsV2 is not a C API type, // but the struct has V2 in its name to indicate that it is the second version of the options. @@ -993,6 +1073,9 @@ struct AllocatorWithDefaultOptions : detail::AllocatorImpl { explicit Allocator(std::nullptr_t) {} ///< Convenience to create a class member and then replace with an instance Allocator(const Session& session, const OrtMemoryInfo*); + + ///< Take ownership of a pointer created by C API + explicit Allocator(OrtAllocator* p) : AllocatorImpl{p} {} }; using UnownedAllocator = detail::AllocatorImpl>; @@ -1000,11 +1083,25 @@ using UnownedAllocator = detail::AllocatorImpl>; /** \brief Wrapper around ::OrtSyncStream * */ -struct SyncStream : detail::Base { - explicit SyncStream(std::nullptr_t) {} ///< Create an empty SyncStream object, must be assigned a valid one to be used - explicit SyncStream(OrtSyncStream* p) : Base{p} {} ///< Take ownership of a pointer created by C API - void* GetHandle() const; ///< Wraps SyncStream_GetHandle + +namespace detail { +template +struct SyncStreamImpl : Base { + using B = Base; + using B::B; + // For some reason this is not a const method on the stream + void* GetHandle(); ///< Wraps SyncStream_GetHandle }; +} // namespace detail + +struct SyncStream : detail::SyncStreamImpl { + ///< Create an empty SyncStream object, must be assigned a valid one to be used + explicit SyncStream(std::nullptr_t) {} + ///< Take ownership of a pointer created by C API + explicit SyncStream(OrtSyncStream* p) : SyncStreamImpl{p} {} +}; + +using UnownedSyncStream = detail::SyncStreamImpl>; namespace detail { template @@ -1067,6 +1164,72 @@ OrtCompiledModelCompatibility GetModelCompatibilityForEpDevices( const std::vector& ep_devices, const char* compatibility_info); +/** \brief Extract EP compatibility info from a precompiled model file. + * + * Parses the model file to extract the compatibility info string for a specific execution provider + * from the model's metadata properties. This is only applicable to models that have been precompiled + * for an EP. Standard ONNX models do not contain this information. + * + * \note This operation parses the full ONNX ModelProto from disk. + * + * \param model_path Path to the ONNX model file. + * \param ep_type The execution provider type string. Must be non-empty. + * Use ConstEpDevice::EpName() to get this value. + * \param allocator Allocator to use for the output string. + * \return The compatibility info string, or nullptr if not found for this EP. Caller must free via allocator. + * \throws Ort::Exception on error. + */ +AllocatedStringPtr GetCompatibilityInfoFromModelAllocated(const ORTCHAR_T* model_path, const char* ep_type, + OrtAllocator* allocator); + +/** \brief Extract EP compatibility info from precompiled model bytes in memory. + * + * Same as GetCompatibilityInfoFromModelAllocated but reads from a memory buffer. + * Useful when precompiled models are loaded from encrypted storage, network, or other non-file sources. + * + * \param model_data Pointer to the model data in memory. + * \param model_data_length Size of the model data in bytes. + * \param ep_type The execution provider type string. Must be non-empty. + * \param allocator Allocator to use for the output string. + * \return The compatibility info string, or nullptr if not found for this EP. Caller must free via allocator. + * \throws Ort::Exception on error. + */ +AllocatedStringPtr GetCompatibilityInfoFromModelBytesAllocated(const void* model_data, size_t model_data_length, + const char* ep_type, OrtAllocator* allocator); + +namespace detail { +template +struct EpAssignedNodeImpl : Ort::detail::Base { + using B = Ort::detail::Base; + using B::B; + + std::string GetName() const; + std::string GetDomain() const; + std::string GetOperatorType() const; +}; +} // namespace detail + +/** \brief Constant wrapper around ::OrtEpAssignedNode + * \remarks EpAssignedNode is always read-only for ORT API users. + */ +using ConstEpAssignedNode = detail::EpAssignedNodeImpl>; + +namespace detail { +template +struct EpAssignedSubgraphImpl : Ort::detail::Base { + using B = Ort::detail::Base; + using B::B; + + std::string GetEpName() const; + std::vector GetNodes() const; +}; +} // namespace detail + +/** \brief Constant wrapper around ::OrtEpAssignedSubgraph + * \remarks EpAssignedSubgraph is always read-only for ORT API users. + */ +using ConstEpAssignedSubgraph = detail::EpAssignedSubgraphImpl>; + /** \brief The Env (Environment) * * The Env holds the logging state used by all other objects. @@ -1088,6 +1251,9 @@ struct Env : detail::Base { Env(const OrtThreadingOptions* tp_options, OrtLoggingFunction logging_function, void* logger_param, OrtLoggingLevel logging_level = ORT_LOGGING_LEVEL_WARNING, _In_ const char* logid = ""); + /// \brief Wraps OrtApi::CreateEnvWithOptions + explicit Env(const OrtEnvCreationOptions* options); + /// \brief C Interop Helper explicit Env(OrtEnv* p) : Base{p} {} @@ -1207,6 +1373,15 @@ struct RunOptions : detail::Base { * \param adapter The LoraAdapter to be used as the active adapter */ RunOptions& AddActiveLoraAdapter(const LoraAdapter& adapter); + + /** \brief Associate a sync stream with the run options. + * + * When set, the EP uses this stream for execution, enabling proper + * synchronization with imported external semaphores. Wraps OrtApi::RunOptionsSetSyncStream. + * + * \param stream The OrtSyncStream to associate with these run options. May be nullptr to clear. + */ + RunOptions& SetSyncStream(OrtSyncStream* stream); }; namespace detail { @@ -1364,6 +1539,12 @@ struct SessionOptionsImpl : ConstSessionOptionsImpl { ///< Wraps OrtApi::SessionOptionsAppendExecutionProvider_VitisAI SessionOptionsImpl& AppendExecutionProvider_VitisAI(const std::unordered_map& provider_options = {}); + + ///< Wraps OrtApi::AddFreeDimensionOverride + SessionOptionsImpl& AddFreeDimensionOverride(const char* dim_denotation, int64_t dim_value); + + ///< Wraps OrtApi::AddFreeDimensionOverrideByName + SessionOptionsImpl& AddFreeDimensionOverrideByName(const char* dim_name, int64_t dim_value); }; } // namespace detail @@ -1521,6 +1702,7 @@ struct ConstSessionImpl : Base { std::vector GetMemoryInfoForInputs() const; ///< Wrapper for OrtApi::SessionGetMemoryInfoForInputs std::vector GetMemoryInfoForOutputs() const; ///< Wrapper for OrtApi::SessionGetMemoryInfoForOutputs std::vector GetEpDeviceForInputs() const; ///< Wrapper for OrtApi::SessionGetEpDeviceForInputs + std::vector GetEpDeviceForOutputs() const; ///< Wrapper for OrtApi::SessionGetEpDeviceForOutputs /** \brief Returns a copy of input name at the specified index. * @@ -1558,9 +1740,14 @@ struct ConstSessionImpl : Base { int GetOpset(const std::string& domain) const; ///< Wraps OrtApi::SessionGetOpsetForDomain - // Will move before checkin if that's the case. std::vector GetInputs() const; std::vector GetOutputs() const; + + /** \brief Returns information on the subgraph/nodes assigned to execution providers in the session. + * + * \return A list of ConstEpAssignedSubgraph instances. + */ + std::vector GetEpGraphAssignmentInfo() const; }; template @@ -1705,6 +1892,7 @@ struct TensorTypeAndShapeInfoImpl : Base { void GetSymbolicDimensions(const char** values, size_t values_count) const; ///< Wraps OrtApi::GetSymbolicDimensions std::vector GetSymbolicDimensions() const; + bool HasShape() const; ///< Wraps OrtApi::TensorTypeAndShape_HasShape std::vector GetShape() const; ///< Uses GetDimensionsCount & GetDimensions to return a std::vector of the shape }; @@ -2032,6 +2220,19 @@ struct ConstValueImpl : Base { const R* GetSparseTensorValues() const; #endif + + /// + /// Returns the tensor's element type and a reference to the tensor's internal shape data. The shape data is owned + /// by the Ort::Value and becomes invalid when the Ort::Value is destroyed or if the underlying shape data is + /// updated or reallocated. + /// + /// For a scalar, shape.shape is nullptr and shape.shape_len is 0. + /// + /// Wraps OrtApi::GetTensorElementTypeAndShapeDataReference. + /// + /// Output parameter set to the element's data type. + /// Output parameter set to the OrtValue instance's shape data and number of elements. + void GetTensorElementTypeAndShapeDataReference(ONNXTensorElementDataType& elem_type, Shape& shape) const; }; template @@ -2635,7 +2836,7 @@ struct KernelContext { UnownedValue GetOutput(size_t index, const std::vector& dims) const; void* GetGPUComputeStream() const; Logger GetLogger() const; - OrtAllocator* GetAllocator(const OrtMemoryInfo& memory_info) const; + Ort::Allocator GetAllocator(const OrtMemoryInfo& memory_info) const; OrtKernelContext* GetOrtKernelContext() const { return ctx_; } void ParallelFor(void (*fn)(void*, size_t), size_t total, size_t num_batch, void* usr_data) const; @@ -2690,6 +2891,13 @@ struct KernelInfoImpl : Base { std::string GetNodeName() const; Logger GetLogger() const; + + KeyValuePairs GetConfigEntries() const; + + std::string GetOperatorDomain() const; ///< Wraps OrtApi::KernelInfo_GetOperatorDomain + std::string GetOperatorType() const; ///< Wraps OrtApi::KernelInfo_GetOperatorType + int GetOperatorSinceVersion() const; ///< Wraps OrtApi::KernelInfo_GetOperatorSinceVersion + const OrtEp* GetEp() const; ///< Wraps OrtEpApi::KernelInfo_GetEp }; } // namespace detail @@ -3206,5 +3414,121 @@ struct Model : detail::ModelImpl { explicit Model(const std::vector& opsets); #endif }; + +namespace detail { +template +struct ConstKernelDefImpl : Base { + using B = Base; + using B::B; + + ///< Wraps OrtEpApi::KernelDef_GetOperatorType + const char* GetOperatorType() const; + + ///< Wraps OrtEpApi::KernelDef_GetDomain + const char* GetDomain() const; + + ///< Wraps OrtEpApi::KernelDef_GetSinceVersion + std::pair GetSinceVersion() const; + + ///< Wraps OrtEpApi::KernelDef_GetExecutionProvider + const char* GetExecutionProvider() const; + + ///< Wraps OrtEpApi::KernelDef_GetInputMemType + OrtMemType GetInputMemType(size_t input_index) const; + + ///< Wraps OrtEpApi::KernelDef_GetOutputMemType + OrtMemType GetOutputMemType(size_t output_index) const; +}; +} // namespace detail + +using ConstKernelDef = detail::ConstKernelDefImpl>; + +struct KernelDef : detail::ConstKernelDefImpl { + using Base = detail::ConstKernelDefImpl; + using Base::Base; + + explicit KernelDef(std::nullptr_t) {} + explicit KernelDef(OrtKernelDef* p) : detail::ConstKernelDefImpl{p} {} + + ConstKernelDef GetConst() const { return ConstKernelDef{this->p_}; } +}; + +/** \brief Builder for OrtKernelDef. + * + * Used by plugin EPs to build a kernel definition. + */ +struct KernelDefBuilder : detail::Base { + KernelDefBuilder(); ///< Wraps OrtEpApi::CreateKernelDefBuilder + explicit KernelDefBuilder(std::nullptr_t) {} ///< Create an empty object, must be assigned a valid one to be used + explicit KernelDefBuilder(OrtKernelDefBuilder* ort_kernel_def_builder); + + KernelDefBuilder& SetOperatorType(const char* op_type); + KernelDefBuilder& SetDomain(const char* domain); + KernelDefBuilder& SetSinceVersion(int since_version_start, int since_version_end); + KernelDefBuilder& SetExecutionProvider(const char* ep_name); + KernelDefBuilder& SetInputMemType(size_t input_index, OrtMemType mem_type); + KernelDefBuilder& SetOutputMemType(size_t output_index, OrtMemType mem_type); + KernelDefBuilder& AddTypeConstraint(const char* arg_name, const OrtDataType* data_type); + KernelDefBuilder& AddTypeConstraint(const char* arg_name, const std::vector& data_types); + KernelDefBuilder& AddInputOutputAlias(int input_index, int output_index); + KernelDefBuilder& AddInputOutputAliases(const std::vector& input_indices, + const std::vector& output_indices); + KernelDefBuilder& AddInputOutputMutableAlias(int input_index, int output_index); + KernelDefBuilder& AddInputOutputMutableAliases(const std::vector& input_indices, + const std::vector& output_indices); + + KernelDef Build(); +}; + +/** \brief Registry for kernels supported by an EP. + * + * Used by plugin EPs to register definitions for supported kernels. + */ +struct KernelRegistry : detail::Base { + ///< Wrapper around OrtEpApi::CreateKernelRegistry + KernelRegistry(); + + ///< Create an empty object, must be assigned a valid one to be used + explicit KernelRegistry(std::nullptr_t) {} + + ///< Take ownership of a pointer created with the C API. + explicit KernelRegistry(OrtKernelRegistry* ort_kernel_registry); + + ///< Wraps KernelRegistry_AddKernel + Status AddKernel(const OrtKernelDef* kernel_def, OrtKernelCreateFunc kernel_create_func, + void* kernel_create_func_state); +}; + +namespace detail { +template +struct SharedPrePackedWeightCacheImpl : Ort::detail::Base { + using B = Ort::detail::Base; + using B::B; + + //< Wraps SharedPrePackedWeightCache_StoreWeightData + Status StoreWeightData(void** buffer_data_ptrs, size_t* buffer_sizes, size_t num_buffers); +}; +} // namespace detail + +/** \brief Convenience C++ wrapper class around a ::OrtSharedPrePackedWeightCache instance owned by ORT. + * + * An `OrtSharedPrePackedWeightCache*` instance is passed as an argument to OrtKernelImpl::PrePackWeight. + * Example use: + * OrtStatus* MyKernel::PrePackWeightImpl(OrtKernelImpl*, ..., OrtSharedPrePackedWeightCache* c_cache, ...) { + * ... + * if (c_cache != nullptr) { + * Ort::UnownedSharedPrePackedWeightCache cpp_cache(c_cache); + * Ort::Status status = cpp_cache.StoreWeightData(...); + * } + * ... + * } + * + * \remarks OrtSharedPrePackedWeightCache is always unowned, but mutable, for EpApi users. + */ +using UnownedSharedPrePackedWeightCache = + detail::SharedPrePackedWeightCacheImpl>; + +///< Wraps OrtEpApi::GetEnvConfigEntries() +Ort::KeyValuePairs GetEnvConfigEntries(); } // namespace Ort #include "onnxruntime_cxx_inline.h" diff --git a/onnxruntime/include/onnxruntime_cxx_inline.h b/onnxruntime/include/onnxruntime_cxx_inline.h index 59979189..1a3e4913 100644 --- a/onnxruntime/include/onnxruntime_cxx_inline.h +++ b/onnxruntime/include/onnxruntime_cxx_inline.h @@ -12,6 +12,7 @@ #include #include #include +#include #include // Convert OrtStatus to Ort::Status and return @@ -669,9 +670,12 @@ inline void KeyValuePairs::Remove(const char* key) { GetApi().RemoveKeyValuePair(this->p_, key); } -inline void* SyncStream::GetHandle() const { +namespace detail { +template +inline void* SyncStreamImpl::GetHandle() { return GetApi().SyncStream_GetHandle(this->p_); } +} // namespace detail namespace detail { template @@ -743,6 +747,61 @@ inline EpDevice::EpDevice(OrtEpFactory& ep_factory, ConstHardwareDevice& hardwar ThrowOnError(GetEpApi().CreateEpDevice(&ep_factory, hardware_device, ep_metadata, ep_options, &p_)); } +namespace detail { +template +inline std::string EpAssignedSubgraphImpl::GetEpName() const { + const char* ep_name = nullptr; + + // Returned null-terminated string will not be null if API function returns successfully. + ThrowOnError(GetApi().EpAssignedSubgraph_GetEpName(this->p_, &ep_name)); + return std::string(ep_name); +} + +template +inline std::vector EpAssignedSubgraphImpl::GetNodes() const { + size_t num_ep_nodes = 0; + const OrtEpAssignedNode* const* ep_node_ptrs = nullptr; + ThrowOnError(GetApi().EpAssignedSubgraph_GetNodes(this->p_, &ep_node_ptrs, &num_ep_nodes)); + + std::vector ep_nodes; + if (num_ep_nodes > 0) { + ep_nodes.reserve(num_ep_nodes); + for (size_t i = 0; i < num_ep_nodes; ++i) { + ep_nodes.emplace_back(ep_node_ptrs[i]); + } + } + + return ep_nodes; +} + +template +inline std::string EpAssignedNodeImpl::GetName() const { + const char* node_name = nullptr; + + // Returned null-terminated string will not be null if API function returns successfully. + ThrowOnError(GetApi().EpAssignedNode_GetName(this->p_, &node_name)); + return std::string(node_name); +} + +template +inline std::string EpAssignedNodeImpl::GetDomain() const { + const char* domain = nullptr; + + // Returned null-terminated string will not be null if API function returns successfully. + ThrowOnError(GetApi().EpAssignedNode_GetDomain(this->p_, &domain)); + return std::string(domain); +} + +template +inline std::string EpAssignedNodeImpl::GetOperatorType() const { + const char* op_type = nullptr; + + // Returned null-terminated string will not be null if API function returns successfully. + ThrowOnError(GetApi().EpAssignedNode_GetOperatorType(this->p_, &op_type)); + return std::string(op_type); +} +} // namespace detail + inline Env::Env(OrtLoggingLevel logging_level, _In_ const char* logid) { ThrowOnError(GetApi().CreateEnv(logging_level, logid, &p_)); if (strcmp(logid, "onnxruntime-node") == 0) { @@ -780,6 +839,15 @@ inline Env::Env(const OrtThreadingOptions* tp_options, OrtLoggingFunction loggin } } +inline Env::Env(const OrtEnvCreationOptions* options) { + ThrowOnError(GetApi().CreateEnvWithOptions(options, &p_)); + if (strcmp(options->log_id, "onnxruntime-node") == 0) { + ThrowOnError(GetApi().SetLanguageProjection(p_, OrtLanguageProjection::ORT_PROJECTION_NODEJS)); + } else { + ThrowOnError(GetApi().SetLanguageProjection(p_, OrtLanguageProjection::ORT_PROJECTION_CPLUSPLUS)); + } +} + inline Env& Env::EnableTelemetryEvents() { ThrowOnError(GetApi().EnableTelemetryEvents(p_)); return *this; @@ -915,6 +983,20 @@ inline OrtCompiledModelCompatibility GetModelCompatibilityForEpDevices( return status; } +inline AllocatedStringPtr GetCompatibilityInfoFromModelAllocated(const ORTCHAR_T* model_path, const char* ep_type, + OrtAllocator* allocator) { + char* compat_info = nullptr; + ThrowOnError(GetApi().GetCompatibilityInfoFromModel(model_path, ep_type, allocator, &compat_info)); + return AllocatedStringPtr(compat_info, detail::AllocatedFree(allocator)); +} + +inline AllocatedStringPtr GetCompatibilityInfoFromModelBytesAllocated(const void* model_data, size_t model_data_length, + const char* ep_type, OrtAllocator* allocator) { + char* compat_info = nullptr; + ThrowOnError(GetApi().GetCompatibilityInfoFromModelBytes(model_data, model_data_length, ep_type, allocator, &compat_info)); + return AllocatedStringPtr(compat_info, detail::AllocatedFree(allocator)); +} + inline LoraAdapter LoraAdapter::CreateLoraAdapter(const std::basic_string& adapter_path, OrtAllocator* allocator) { OrtLoraAdapter* p; @@ -990,6 +1072,11 @@ inline RunOptions& RunOptions::AddActiveLoraAdapter(const LoraAdapter& adapter) return *this; } +inline RunOptions& RunOptions::SetSyncStream(OrtSyncStream* stream) { + GetApi().RunOptionsSetSyncStream(p_, stream); + return *this; +} + inline ModelCompilationOptions::ModelCompilationOptions(const Env& env, const SessionOptions& session_options) { ThrowOnError(GetCompileApi().CreateModelCompilationOptionsFromSessionOptions(env, session_options, &this->p_)); } @@ -1500,6 +1587,18 @@ inline SessionOptionsImpl& SessionOptionsImpl::RegisterCustomOpsUsingFunct return *this; } +template +inline SessionOptionsImpl& SessionOptionsImpl::AddFreeDimensionOverride(const char* dim_denotation, int64_t dim_value) { + ThrowOnError(GetApi().AddFreeDimensionOverrideByName(this->p_, dim_denotation, dim_value)); + return *this; +} + +template +inline SessionOptionsImpl& SessionOptionsImpl::AddFreeDimensionOverrideByName(const char* dim_name, int64_t dim_value) { + ThrowOnError(GetApi().AddFreeDimensionOverrideByName(this->p_, dim_name, dim_value)); + return *this; +} + /// Session template inline size_t ConstSessionImpl::GetInputCount() const { @@ -1582,11 +1681,13 @@ inline std::vector ConstSessionImpl::GetMemoryInfoForInputs( auto num_inputs = GetInputCount(); std::vector mem_infos; - mem_infos.resize(num_inputs); + if (num_inputs > 0) { + mem_infos.resize(num_inputs); - ThrowOnError(GetApi().SessionGetMemoryInfoForInputs(this->p_, - reinterpret_cast(mem_infos.data()), - num_inputs)); + ThrowOnError(GetApi().SessionGetMemoryInfoForInputs(this->p_, + reinterpret_cast(mem_infos.data()), + num_inputs)); + } return mem_infos; } @@ -1598,11 +1699,13 @@ inline std::vector ConstSessionImpl::GetMemoryInfoForOutputs auto num_outputs = GetOutputCount(); std::vector mem_infos; - mem_infos.resize(num_outputs); + if (num_outputs > 0) { + mem_infos.resize(num_outputs); - ThrowOnError(GetApi().SessionGetMemoryInfoForOutputs(this->p_, - reinterpret_cast(mem_infos.data()), - num_outputs)); + ThrowOnError(GetApi().SessionGetMemoryInfoForOutputs(this->p_, + reinterpret_cast(mem_infos.data()), + num_outputs)); + } return mem_infos; } @@ -1631,15 +1734,28 @@ template inline std::vector ConstSessionImpl::GetEpDeviceForInputs() const { auto num_inputs = GetInputCount(); std::vector input_devices; - input_devices.resize(num_inputs); - - ThrowOnError(GetApi().SessionGetEpDeviceForInputs(this->p_, - reinterpret_cast(input_devices.data()), - num_inputs)); - + if (num_inputs > 0) { + input_devices.resize(num_inputs); + ThrowOnError(GetApi().SessionGetEpDeviceForInputs(this->p_, + reinterpret_cast(input_devices.data()), + num_inputs)); + } return input_devices; } +template +inline std::vector ConstSessionImpl::GetEpDeviceForOutputs() const { + auto num_outputs = GetOutputCount(); + std::vector output_devices; + if (num_outputs > 0) { + output_devices.resize(num_outputs); + ThrowOnError(GetApi().SessionGetEpDeviceForOutputs(this->p_, + reinterpret_cast(output_devices.data()), + num_outputs)); + } + return output_devices; +} + template inline uint64_t ConstSessionImpl::GetProfilingStartTimeNs() const { uint64_t out; @@ -1714,6 +1830,23 @@ std::vector ConstSessionImpl::GetOutputs() const { return outputs; } +template +inline std::vector ConstSessionImpl::GetEpGraphAssignmentInfo() const { + size_t num_ep_subgraphs = 0; + const OrtEpAssignedSubgraph* const* ep_subgraph_ptrs = nullptr; + ThrowOnError(GetApi().Session_GetEpGraphAssignmentInfo(this->p_, &ep_subgraph_ptrs, &num_ep_subgraphs)); + + std::vector ep_subgraphs; + if (num_ep_subgraphs > 0) { + ep_subgraphs.reserve(num_ep_subgraphs); + for (size_t i = 0; i < num_ep_subgraphs; ++i) { + ep_subgraphs.emplace_back(ep_subgraph_ptrs[i]); + } + } + + return ep_subgraphs; +} + template inline std::vector SessionImpl::Run(const RunOptions& run_options, const char* const* input_names, const Value* input_values, size_t input_count, const char* const* output_names, size_t output_count) { @@ -1975,7 +2108,12 @@ template inline size_t TensorTypeAndShapeInfoImpl::GetElementCount() const { size_t out; ThrowOnError(GetApi().GetTensorShapeElementCount(this->p_, &out)); - return static_cast(out); + return out; +} + +template +inline bool TensorTypeAndShapeInfoImpl::HasShape() const { + return GetApi().TensorTypeAndShape_HasShape(this->p_); } template @@ -1997,8 +2135,12 @@ inline void TensorTypeAndShapeInfoImpl::GetSymbolicDimensions(const char** va template inline std::vector TensorTypeAndShapeInfoImpl::GetSymbolicDimensions() const { - std::vector out(GetDimensionsCount(), nullptr); - ThrowOnError(GetApi().GetSymbolicDimensions(this->p_, out.data(), out.size())); + std::vector out; + size_t dim_count = GetDimensionsCount(); + if (dim_count > 0) { + out.resize(dim_count, nullptr); + ThrowOnError(GetApi().GetSymbolicDimensions(this->p_, out.data(), out.size())); + } return out; } @@ -2235,6 +2377,13 @@ inline const R* ConstValueImpl::GetSparseTensorValues() const { #endif +template +void ConstValueImpl::GetTensorElementTypeAndShapeDataReference(ONNXTensorElementDataType& elem_type, + Shape& shape) const { + ThrowOnError(GetApi().GetTensorElementTypeAndShapeDataReference(this->p_, &elem_type, &shape.shape, + &shape.shape_len)); +} + template void ValueImpl::FillStringTensor(const char* const* s, size_t s_len) { ThrowOnError(GetApi().FillStringTensor(this->p_, s, s_len)); @@ -2518,10 +2667,10 @@ inline void* KernelContext::GetGPUComputeStream() const { return out; } -inline OrtAllocator* KernelContext::GetAllocator(const OrtMemoryInfo& memory_info) const { +inline Ort::Allocator KernelContext::GetAllocator(const OrtMemoryInfo& memory_info) const { OrtAllocator* out = nullptr; Ort::ThrowOnError(GetApi().KernelContext_GetAllocator(ctx_, &memory_info, &out)); - return out; + return Ort::Allocator{out}; } inline Logger KernelContext::GetLogger() const { @@ -2806,6 +2955,57 @@ inline Logger KernelInfoImpl::GetLogger() const { return Logger{out}; } +template +inline KeyValuePairs KernelInfoImpl::GetConfigEntries() const { + OrtKeyValuePairs* out = nullptr; + Ort::ThrowOnError(GetApi().KernelInfo_GetConfigEntries(this->p_, &out)); + return KeyValuePairs{out}; +} + +template +inline std::string KernelInfoImpl::GetOperatorDomain() const { + size_t size = 0; + + // Feed nullptr for the data buffer to query the true size of the string value + Ort::ThrowOnError(GetApi().KernelInfo_GetOperatorDomain(this->p_, nullptr, &size)); + + std::string out; + out.resize(size); + Ort::ThrowOnError(GetApi().KernelInfo_GetOperatorDomain(this->p_, &out[0], &size)); + out.resize(size - 1); // remove the terminating character '\0' + + return out; +} + +template +inline std::string KernelInfoImpl::GetOperatorType() const { + size_t size = 0; + + // Feed nullptr for the data buffer to query the true size of the string value + Ort::ThrowOnError(GetApi().KernelInfo_GetOperatorType(this->p_, nullptr, &size)); + + std::string out; + out.resize(size); + Ort::ThrowOnError(GetApi().KernelInfo_GetOperatorType(this->p_, &out[0], &size)); + out.resize(size - 1); // remove the terminating character '\0' + + return out; +} + +template +inline int KernelInfoImpl::GetOperatorSinceVersion() const { + int out = 0; + Ort::ThrowOnError(GetApi().KernelInfo_GetOperatorSinceVersion(this->p_, &out)); + return out; +} + +template +inline const OrtEp* KernelInfoImpl::GetEp() const { + const OrtEp* ep = nullptr; + Ort::ThrowOnError(GetEpApi().KernelInfo_GetEp(this->p_, &ep)); + return ep; +} + inline void attr_utils::GetAttr(const OrtKernelInfo* p, const char* name, float& out) { Ort::ThrowOnError(GetApi().KernelInfoGetAttribute_float(p, name, &out)); } @@ -3537,4 +3737,160 @@ inline Model::Model(const std::vector& opsets) { } #endif +namespace detail { +template +inline const char* ConstKernelDefImpl::GetOperatorType() const { + return GetEpApi().KernelDef_GetOperatorType(this->p_); +} + +template +inline const char* ConstKernelDefImpl::GetDomain() const { + return GetEpApi().KernelDef_GetDomain(this->p_); +} + +template +inline std::pair ConstKernelDefImpl::GetSinceVersion() const { + int start = 0; + int end = 0; + + ThrowOnError(GetEpApi().KernelDef_GetSinceVersion(this->p_, &start, &end)); + return std::pair(start, end); +} + +template +inline const char* ConstKernelDefImpl::GetExecutionProvider() const { + return GetEpApi().KernelDef_GetExecutionProvider(this->p_); +} + +template +inline OrtMemType ConstKernelDefImpl::GetInputMemType(size_t input_index) const { + OrtMemType mem_type{}; + ThrowOnError(GetEpApi().KernelDef_GetInputMemType(this->p_, input_index, &mem_type)); + + return mem_type; +} + +template +inline OrtMemType ConstKernelDefImpl::GetOutputMemType(size_t output_index) const { + OrtMemType mem_type{}; + ThrowOnError(GetEpApi().KernelDef_GetOutputMemType(this->p_, output_index, &mem_type)); + + return mem_type; +} +} // namespace detail + +inline KernelDefBuilder::KernelDefBuilder() { + ThrowOnError(GetEpApi().CreateKernelDefBuilder(&p_)); +} + +inline KernelDefBuilder::KernelDefBuilder(OrtKernelDefBuilder* p) : detail::Base{p} { +} + +inline KernelDefBuilder& KernelDefBuilder::SetOperatorType(const char* op_type) { + ThrowOnError(GetEpApi().KernelDefBuilder_SetOperatorType(p_, op_type)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::SetDomain(const char* domain) { + ThrowOnError(GetEpApi().KernelDefBuilder_SetDomain(p_, domain)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::SetSinceVersion(int since_version_start, int since_version_end) { + ThrowOnError(GetEpApi().KernelDefBuilder_SetSinceVersion(p_, since_version_start, since_version_end)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::SetExecutionProvider(const char* ep_name) { + ThrowOnError(GetEpApi().KernelDefBuilder_SetExecutionProvider(p_, ep_name)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::SetInputMemType(size_t input_index, OrtMemType mem_type) { + ThrowOnError(GetEpApi().KernelDefBuilder_SetInputMemType(p_, input_index, mem_type)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::SetOutputMemType(size_t output_index, OrtMemType mem_type) { + ThrowOnError(GetEpApi().KernelDefBuilder_SetOutputMemType(p_, output_index, mem_type)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::AddTypeConstraint(const char* arg_name, + const OrtDataType* data_type) { + ThrowOnError(GetEpApi().KernelDefBuilder_AddTypeConstraint(p_, arg_name, &data_type, 1)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::AddTypeConstraint(const char* arg_name, + const std::vector& data_types) { + ThrowOnError(GetEpApi().KernelDefBuilder_AddTypeConstraint(p_, arg_name, data_types.data(), data_types.size())); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::AddInputOutputAlias(int input_index, int output_index) { + ThrowOnError(GetEpApi().KernelDefBuilder_AddInputOutputAliases(p_, &input_index, &output_index, 1)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::AddInputOutputAliases(const std::vector& input_indices, + const std::vector& output_indices) { + if (input_indices.size() != output_indices.size()) { + ORT_CXX_API_THROW("Expecting input and output indices to have the same element count", ORT_INVALID_ARGUMENT); + } + + ThrowOnError(GetEpApi().KernelDefBuilder_AddInputOutputAliases(p_, input_indices.data(), output_indices.data(), + input_indices.size())); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::AddInputOutputMutableAlias(int input_index, int output_index) { + ThrowOnError(GetEpApi().KernelDefBuilder_AddInputOutputMutableAliases(p_, &input_index, &output_index, 1)); + return *this; +} + +inline KernelDefBuilder& KernelDefBuilder::AddInputOutputMutableAliases(const std::vector& input_indices, + const std::vector& output_indices) { + if (input_indices.size() != output_indices.size()) { + ORT_CXX_API_THROW("Expecting input and output indices to have the same element count", ORT_INVALID_ARGUMENT); + } + + ThrowOnError(GetEpApi().KernelDefBuilder_AddInputOutputMutableAliases(p_, input_indices.data(), output_indices.data(), + input_indices.size())); + return *this; +} + +inline KernelDef KernelDefBuilder::Build() { + OrtKernelDef* kernel_def = nullptr; + ThrowOnError(GetEpApi().KernelDefBuilder_Build(p_, &kernel_def)); + return KernelDef(kernel_def); +} + +inline KernelRegistry::KernelRegistry() { + ThrowOnError(GetEpApi().CreateKernelRegistry(&p_)); +} + +inline KernelRegistry::KernelRegistry(OrtKernelRegistry* p) : detail::Base{p} { +} + +inline Status KernelRegistry::AddKernel(const OrtKernelDef* kernel_def, OrtKernelCreateFunc kernel_create_func, + void* kernel_create_func_state) { + return Status{GetEpApi().KernelRegistry_AddKernel(p_, kernel_def, kernel_create_func, kernel_create_func_state)}; +} + +namespace detail { +template +inline Status SharedPrePackedWeightCacheImpl::StoreWeightData(void** buffer_data_ptrs, size_t* buffer_sizes, + size_t num_buffers) { + return Status{GetEpApi().SharedPrePackedWeightCache_StoreWeightData(this->p_, buffer_data_ptrs, buffer_sizes, + num_buffers)}; +} +} // namespace detail + +inline Ort::KeyValuePairs GetEnvConfigEntries() { + OrtKeyValuePairs* entries = nullptr; + Ort::ThrowOnError(GetEpApi().GetEnvConfigEntries(&entries)); + + return Ort::KeyValuePairs{entries}; +} } // namespace Ort diff --git a/onnxruntime/include/onnxruntime_ep_c_api.h b/onnxruntime/include/onnxruntime_ep_c_api.h index 975f6b45..b888d0d6 100644 --- a/onnxruntime/include/onnxruntime_ep_c_api.h +++ b/onnxruntime/include/onnxruntime_ep_c_api.h @@ -3,6 +3,13 @@ // Do not include this file directly. Please include "onnxruntime_c_api.h" instead. +#if defined(__DOXYGEN__) +// When running a Doxygen build, include onnxruntime_c_api.h. Doxygen expects header files to be self-contained. +#include "onnxruntime_c_api.h" +#else +// In normal usage, do not include onnxruntime_c_api.h. This file is explicitly included in onnxruntime_c_api.h. +#endif + #ifdef __cplusplus extern "C" { #endif @@ -17,7 +24,75 @@ ORT_RUNTIME_CLASS(DataTransferImpl); ORT_RUNTIME_CLASS(SyncNotificationImpl); ORT_RUNTIME_CLASS(SyncStreamImpl); -// struct that an EP implements for IDataTransfer to copy between devices it uses and CPU +ORT_RUNTIME_CLASS(ExternalResourceImporterImpl); + +/** \brief Base struct for imported external memory handles. + * + * EPs derive from this struct to add EP-specific fields (e.g., CUdeviceptr for CUDA). + * EP is responsible for creating and releasing instances of the derived type. + * + * Example derived type for CUDA EP: + * \code + * struct MyCudaExternalMemoryHandle : OrtExternalMemoryHandle { + * CUexternalMemory ext_memory; + * CUdeviceptr mapped_ptr; + * bool is_dedicated; + * }; + * \endcode + * + * \since Version 1.24. + */ +struct OrtExternalMemoryHandle { + uint32_t version; ///< Must be ORT_API_VERSION + const OrtEpDevice* ep_device; ///< EP device that created this handle + OrtExternalMemoryDescriptor descriptor; ///< External memory descriptor + + /** \brief Release callback for this handle. EP sets this to its release function. + * + * ORT calls this when ReleaseExternalMemoryHandle is invoked. The EP's callback + * should cast the handle to its derived type and delete it. + */ + void(ORT_API_CALL* Release)(_In_ OrtExternalMemoryHandle* handle); +}; + +/** \brief Base struct for imported external semaphore handles. + * + * EPs derive from this struct to add EP-specific fields (e.g., CUexternalSemaphore for CUDA). + * EP is responsible for creating and releasing instances of the derived type. + * + * Example derived type for CUDA EP: + * \code + * struct MyCudaExternalSemaphoreHandle : OrtExternalSemaphoreHandle { + * CUexternalSemaphore ext_semaphore; + * }; + * \endcode + * + * \since Version 1.24. + */ +struct OrtExternalSemaphoreHandle { + uint32_t version; ///< Must be ORT_API_VERSION + const OrtEpDevice* ep_device; ///< EP device that created this handle + OrtExternalSemaphoreDescriptor descriptor; ///< External semaphore descriptor + + /** \brief Release callback for this handle. EP sets this to its release function. + * + * ORT calls this when ReleaseExternalSemaphoreHandle is invoked. The EP's callback + * should cast the handle to its derived type and delete it. + */ + void(ORT_API_CALL* Release)(_In_ OrtExternalSemaphoreHandle* handle); +}; + +// Opaque types for kernel-based EPs +ORT_RUNTIME_CLASS(KernelRegistry); +ORT_RUNTIME_CLASS(KernelDefBuilder); +ORT_RUNTIME_CLASS(KernelDef); +ORT_RUNTIME_CLASS(DataType); // combination of ONNXType (e.g., Tensor, Map, Sequence) and ONNXTensorElementDataType +ORT_RUNTIME_CLASS(SharedPrePackedWeightCache); + +/** \brief Struct that an EP implements for IDataTransfer to copy between devices it uses and CPU. + * + * \since Version 1.23. + */ struct OrtDataTransferImpl { uint32_t ort_version_supported; ///< Must be initialized to ORT_API_VERSION @@ -96,7 +171,7 @@ struct OrtSyncNotificationImpl { /** \brief Wait for a device to device operation to complete. * * \param[in] this_ptr Pointer to the OrtSyncNotificationImpl instance. - * \param[in] stream The OrtSyncStream instance that will wait on this notification to be activated. + * \param[in] consumer_stream The OrtSyncStream instance that will wait on this notification to be activated. * * \since Version 1.23. */ @@ -174,6 +249,180 @@ struct OrtSyncStreamImpl { ORT_API2_STATUS(OnSessionRunEnd, _In_ OrtSyncStreamImpl* this_ptr); }; +/** \brief Struct that an EP implements for external resource import (memory + semaphore import). + * + * This capability object provides methods for importing external GPU memory and semaphores + * for zero-copy import. EPs that support D3D12, CUDA, HIP, or Vulkan external resource APIs + * can implement this interface. + * + * \since Version 1.24. + */ +struct OrtExternalResourceImporterImpl { + uint32_t ort_version_supported; ///< Must be initialized to ORT_API_VERSION + + // Memory operations (stream-independent) + + /** \brief Check if the implementation can import external memory of the given handle type. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] handle_type The type of external memory handle to check. + * \return True if the handle type is supported. + * + * \since Version 1.24. + */ + ORT_API_T(bool, CanImportMemory, + _In_ const OrtExternalResourceImporterImpl* this_ptr, + _In_ OrtExternalMemoryHandleType handle_type); + + /** \brief Import external memory. + * + * The EP creates a derived type of OrtExternalMemoryHandle and returns a pointer to the base. + * EP is responsible for the lifetime of the handle (release via ReleaseMemory). + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] desc Descriptor containing the external memory handle and properties. + * \param[out] out_handle Output parameter set to the created OrtExternalMemoryHandle (EP's derived type). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(ImportMemory, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ const OrtExternalMemoryDescriptor* desc, + _Outptr_ OrtExternalMemoryHandle** out_handle); + + /** \brief Release an imported external memory handle. + * + * The EP deletes its derived type instance. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] handle The OrtExternalMemoryHandle to release (EP casts to its derived type). + * + * \since Version 1.24. + */ + ORT_API_T(void, ReleaseMemory, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ OrtExternalMemoryHandle* handle); + + /** \brief Create a tensor backed by imported external memory. + * + * The created tensor is a view over the imported memory and does not copy data. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] mem_handle The imported external memory handle (EP casts to its derived type). + * \param[in] tensor_desc Descriptor specifying tensor element type, shape, and optional offset. + * \param[out] out_tensor Output parameter set to the created OrtValue containing the tensor. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateTensorFromMemory, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ const OrtExternalMemoryHandle* mem_handle, + _In_ const OrtExternalTensorDescriptor* tensor_desc, + _Outptr_ OrtValue** out_tensor); + + // Semaphore operations (require stream) + + /** \brief Check if the implementation can import external semaphores of the given type. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] type The type of external semaphore to check. + * \return True if the semaphore type is supported. + * + * \since Version 1.24. + */ + ORT_API_T(bool, CanImportSemaphore, + _In_ const OrtExternalResourceImporterImpl* this_ptr, + _In_ OrtExternalSemaphoreType type); + + /** \brief Import an external semaphore. + * + * The EP creates a derived type of OrtExternalSemaphoreHandle and returns a pointer to the base. + * EP is responsible for the lifetime of the handle (release via ReleaseSemaphore). + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] desc Descriptor containing the external semaphore handle and type. + * \param[out] out_handle Output parameter set to the created OrtExternalSemaphoreHandle (EP's derived type). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(ImportSemaphore, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ const OrtExternalSemaphoreDescriptor* desc, + _Outptr_ OrtExternalSemaphoreHandle** out_handle); + + /** \brief Release an imported external semaphore handle. + * + * The EP deletes its derived type instance. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] handle The OrtExternalSemaphoreHandle to release (EP casts to its derived type). + * + * \since Version 1.24. + */ + ORT_API_T(void, ReleaseSemaphore, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ OrtExternalSemaphoreHandle* handle); + + /** \brief Wait on an external semaphore on the EP's stream. + * + * Inserts a wait operation into the EP's stream that blocks until the semaphore + * reaches the specified value. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] handle The imported external semaphore (EP casts to its derived type). + * \param[in] stream The OrtSyncStream to wait on. + * \param[in] value The fence/semaphore value to wait for. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(WaitSemaphore, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ OrtExternalSemaphoreHandle* handle, + _In_ OrtSyncStream* stream, + _In_ uint64_t value); + + /** \brief Signal an external semaphore from the EP's stream. + * + * Inserts a signal operation into the EP's stream that sets the semaphore + * to the specified value when reached. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * \param[in] handle The imported external semaphore (EP casts to its derived type). + * \param[in] stream The OrtSyncStream to signal from. + * \param[in] value The fence/semaphore value to signal. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(SignalSemaphore, + _In_ OrtExternalResourceImporterImpl* this_ptr, + _In_ OrtExternalSemaphoreHandle* handle, + _In_ OrtSyncStream* stream, + _In_ uint64_t value); + + // Release the capability object itself + + /** \brief Release the OrtExternalResourceImporterImpl instance. + * + * This is called by ORT when the OrtExternalResourceImporterImpl instance is no longer needed. + * The implementation should release any resources held by the instance. + * + * \param[in] this_ptr Pointer to the OrtExternalResourceImporterImpl instance. + * + * \since Version 1.24. + */ + ORT_API_T(void, Release, _In_ OrtExternalResourceImporterImpl* this_ptr); +}; + struct OrtNodeFusionOptions; typedef struct OrtNodeFusionOptions OrtNodeFusionOptions; @@ -264,6 +513,241 @@ struct OrtNodeComputeInfo { void(ORT_API_CALL* ReleaseState)(_In_ OrtNodeComputeInfo* this_ptr, _Frees_ptr_opt_ void* compute_state); }; +struct OrtKernelImpl; +typedef struct OrtKernelImpl OrtKernelImpl; + +/** + * \brief Contains functions that an OrtEp implements to specify the computation for an operator kernel. + * \since Version 1.24. + */ +struct OrtKernelImpl { + uint32_t ort_version_supported; ///< Must be initialized to ORT_API_VERSION + uint32_t flags; ///< EP must initialize to 0. Used internally by ORT. + + /** \brief Computation function called to execute the kernel on an EP. + * + * \note Implementation of this function is required. + * + * \param[in] this_ptr The OrtKernelImpl instance. + * \param[in] context The OrtKernelContext instance that provides access to the inputs and outputs. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(Compute, _In_ OrtKernelImpl* this_ptr, _In_ OrtKernelContext* context); + + /** \brief Called by ORT to release the OrtKernelImpl instance and its resources. + * + * \note Implementation of this function is required. + * + * \param[in] this_ptr The OrtKernelImpl instance. + * + * \since Version 1.24. + */ + ORT_API_T(void, Release, _In_ OrtKernelImpl* this_ptr); + + /** \brief Optional function to pre-pack a constant tensor (i.e., a weight) to the kernel's preferred data layout. + * + * For example, a Conv kernel can define this function to pack input W to the channel-last data layout + * before inference. + * + * Pre-packing can operate in three different modes: no pre-packing mode, sharing mode, and non-sharing mode. + * 1) No pre-packing mode: The kernel can forgo any weight pre-packing for the given `input_index` by setting + * `is_packed` to false and returning a successful OrtStatus. In this mode, the kernel's + * OrtKernelImpl::SetSharedPrePackedWeight() function is not called for that specific + * `input_index`. + * 2) Sharing mode: Sharing is allowed if the `prepacked_weight_cache` argument is not NULL and the EP stores + * weight data in CPU-accessible memory. In this case, the kernel can optionally choose + * to share the packed weight with other kernels that use the same weight + * (compared by content hash). To do so, the kernel must allocate the packed weight with the + * provided `allocator`, then it stores the packed weight data into `prepacked_weight_cache` + * via SharedPrePackedWeightCache_StoreWeightData(), sets `is_packed` to true, and returns a + * successful OrtStatus. ORT will subsequently call OrtKernelImpl::SetSharedPrePackedWeight() + * to provide this kernel with the actual shared weight data, whose memory location could + * differ (i.e., if shared data was allocated by a previously processed kernel). + * 3) Non-sharing mode: In non-sharing mode, the `prepacked_weight_cache` argument is ignored. In this mode, + * the implementation allocates the packed data with the provided `allocator`, sets + * `is_packed` to true, and returns a successful OrtStatus. The kernel is ultimately + * responsible for releasing the packed data for the weight with `allocator`. + * ORT may release the original (unpacked) weight, which must not be accessed in + * OrtKernelImpl::Compute(). Note that in this mode, the kernel's + * OrtKernelImpl::SetSharedPrePackedWeight() function is not called by ORT for that specific + * `input_index`. + * + * \note This function is based on the internal OpKernel::PrePack() virtual function used within ORT. + * + * \param[in] this_ptr The OrtKernelImpl instance. + * \param[in] tensor The OrtValue instance representing the constant tensor (weight). Do not cache in the kernel. + * \param[in] input_index The input index of the tensor in this kernel. + * \param[in] allocator Allocator for allocating the pre-packed data. Its use is required in sharing mode and + * recommended, but not required, in the non-sharing mode. This will be an allocator set by + * the application for the session/environment (e.g., via CreateAndRegisterAllocator[V2] + * or RegisterAllocator), or an allocator on the OrtEpDevice (read-only or default) otherwise. + * The allocator remains valid throughout the lifetime of the OrtKernelImpl instance. + * \param[in] prepacked_weight_cache May be NULL. If not NULL, the kernel may choose to share a packed weight by + * first storing it in the OrtSharedPrePackedWeightCache instance and then + * receiving the actual shared weight data in the call to + * OrtKernelImpl::SetSharedPrePackedWeight(). See the above description for + * "sharing mode". + * \param[out] is_packed Output parameter that the implementation sets to true if the kernel packed the tensor data. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \note Implementation of this function is optional. If not implemented (set to NULL), ORT assumes the kernel + * does not pre-pack weight data (i.e., `is_packed` defaults to false). + * + * \since Version 1.24. + */ + ORT_API2_STATUS(PrePackWeight, _In_ OrtKernelImpl* this_ptr, _In_ const OrtValue* tensor, + _In_ int input_index, _Inout_ OrtAllocator* allocator, + _In_opt_ OrtSharedPrePackedWeightCache* prepacked_weight_cache, _Out_ bool* is_packed); + + /** \brief Optional function that receives data for a shared pre-packed weight from ORT. + * + * ORT calls this function after calling OrtKernelImpl::PrePackWeight for a specific `input_index` if: + * - OrtKernelImpl::PrePackWeight set the output parameter `is_packed` to true. + * - OrtKernelImpl::PrePackWeight stored weight data to share into the provided OrtSharedPrePackedWeightCache + * parameter (`prepacked_weight_cache`) via the API SharedPrePackedWeightCache_StoreWeightData. + * + * Refer to the description of the "sharing-mode" in the documentation for OrtKernelImpl::PrePackWeight(). + * + * \note ORT will not call this function for an `input_index` that a previous call to + * OrtKernelImpl::PrePackWeight() did not elect to pre-pack and share. + * + * \note This function is based on the internal OpKernel::UseSharedPrePackedBuffers() virtual function used + * within ORT. + * + * \param[in] this_ptr The OrtKernelImpl instance. + * \param[in] buffer_data_ptrs An array of buffer data pointers that collectively hold the pre-packed data for a + * single shared weight. The buffers are provided in the same order and with the same + * contents (in a potentially different memory location) as the buffers + * passed into SharedPrePackedWeightCache_StoreWeightData() within the + * OrtKernelImpl::PrePackWeight() call for the same `input_index`. + * \param[in] buffer_data_sizes An array of buffer byte sizes, one per element in `buffer_data_ptrs`. + * \param[in] num_buffers The number of buffers used to store the data for the shared pre-packed weight. + * Specifies the number of elements in the `buffer_data_ptrs` and `buffer_data_sizes` arrays. + * \param[in] input_index The input index of the tensor in this kernel. This index identifies the identity of + * the weight. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \note Implementation of this function is generally optional. It is only required if OrtKernelImpl::PrePack() + * elects to share pre-packed weights. + * + * \since Version 1.24. + */ + ORT_API2_STATUS(SetSharedPrePackedWeight, _In_ OrtKernelImpl* this_ptr, + _In_reads_(num_buffers) const void* const* buffer_data_ptrs, + _In_reads_(num_buffers) const size_t* buffer_data_sizes, + _In_ size_t num_buffers, _In_ int input_index); +}; + +/** \brief Type definition for a function that creates an OrtKernelImpl instance for an operator kernel. + * + * \param[in] kernel_create_func_state Opaque state initially provided by the EP that registered the kernel. + * Refer to OrtEpApi::KernelRegistry_AddKernel(). May be null. + * \param[in] info The OrtKernelInfo instance that provides access to the kernel's input and output characteristics. + * \param[out] kernel_out Output parameter set to the new OrtKernelImpl instance. On success, ownership of this + * OrtKernelImpl instance transfers to ORT, which will call OrtKernelImpl::Release() to + * release the instance when it is no longer used. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ +typedef OrtStatus*(ORT_API_CALL* OrtKernelCreateFunc)(_In_ void* kernel_create_func_state, + _In_ const OrtKernelInfo* info, + _Outptr_result_maybenull_ OrtKernelImpl** kernel_out); + +struct OrtLoopKernelHelper; +typedef struct OrtLoopKernelHelper OrtLoopKernelHelper; + +/** + * \brief Contains helper functions for a Loop OrtKernelImpl created via OrtEpApi::CreateLoopKernel. + * \since Version 1.24. + */ +struct OrtLoopKernelHelper { + uint32_t ort_version_supported; ///< Must be initialized to ORT_API_VERSION + + /** \brief Called by ORT to release the OrtLoopKernelHelper instance and its resources. + * + * \param[in] this_ptr The OrtLoopKernelHelper instance. + * + * \since Version 1.24. + */ + ORT_API_T(void, Release, _In_ OrtLoopKernelHelper* this_ptr); + + /** \brief Helper function that concatenates OrtValue instances from each loop iteration into a single + * pre-allocated output buffer. + * + * \note Implementing this function is required for all Loop opset versions. + * + * \param[in] this_ptr The OrtLoopKernelHelper instance. + * \param[in] stream_handle Optional native stream handle that enables asynchronous operations. May be NULL. + * \param[in] per_iteration_outputs Array of OrtValue instances from each iteration. All OrtValue elements have the + * same shape. + * \param[in] num_per_iteration_outputs The number of OrtValue* elements in the `per_iteration_outputs` array. + * \param[out] output The pre-allocated output buffer. Memory is allocated on the device for the EP running the + * Loop node. + * \param[in] output_size_in_bytes The size in bytes of the `output` buffer. It is guaranteed to be large enough + * to hold the concatenated data of each element in `per_iteration_outputs`. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(ConcatOutput, _In_ OrtLoopKernelHelper* this_ptr, _In_opt_ void* stream_handle, + _In_reads_(num_per_iteration_outputs) const OrtValue* const* per_iteration_outputs, + _In_ size_t num_per_iteration_outputs, _Out_writes_bytes_all_(output_size_in_bytes) void* output, + _In_ size_t output_size_in_bytes); +}; + +struct OrtScanKernelHelper; +typedef struct OrtScanKernelHelper OrtScanKernelHelper; + +/** + * \brief Contains helper functions for a Scan OrtKernelImpl created via OrtEpApi::CreateScanKernel. + * \since Version 1.24. + */ +struct OrtScanKernelHelper { + uint32_t ort_version_supported; ///< Must be initialized to ORT_API_VERSION + + /** \brief Called by ORT to release the OrtScanKernelHelper instance and its resources. + * + * \param[in] this_ptr The OrtScanKernelHelper instance. + * + * \since Version 1.24. + */ + ORT_API_T(void, Release, _In_ OrtScanKernelHelper* this_ptr); + + /** \brief Helper function that transposes an OrtValue instance during execution of a Scan kernel. + * + * \note Called for Scan (opset >= 9) when the 'scan_input_axes' or 'scan_output_axes' attributes contain + * non-zero values. Implementing this function is required for Scan opset versions >= 9. + * + * \param[in] this_ptr The OrtScanKernelHelper instance. + * \param[in] permutation An array of integers that defines how the input tensor's axes should be permuted. + * \param[in] num_permutation_elems The number of integer elements in the `permutation` array. + * \param[in] input The input OrtValue tensor to transpose. + * \param[in] stream An optional OrtSyncStream instance to be used for asynchronous operations. May be NULL. + * \param[out] output The pre-allocated output OrtValue instance into which to store the results of the + * transpose operation. Must not be released as it is owned by ORT. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(Transpose, _In_ OrtScanKernelHelper* this_ptr, + _In_reads_(num_permutation_elems) const size_t* permutation, _In_ size_t num_permutation_elems, + _In_ const OrtValue* input, _In_opt_ OrtSyncStream* stream, _Inout_ OrtValue* output); +}; + +/** + * \brief The OrtEpApi struct provides functions that are relevant to the implementation of an execution provider. + * + * \since Version 1.22. + */ struct OrtEpApi { /** \brief Create an OrtEpDevice for the EP and an OrtHardwareDevice. * \param[in] ep_factory Execution provider factory that is creating the instance. @@ -465,6 +949,501 @@ struct OrtEpApi { */ ORT_API_T(uint64_t, GetSyncIdForLastWaitOnSyncStream, _In_ const OrtSyncStream* producer_stream, _In_ const OrtSyncStream* consumer_stream); + + /** \brief Create an OrtHardwareDevice. + * + * \note Called within OrtEpFactory::GetSupportedDevices to create a new hardware device (e.g., virtual). + * + * \param[in] type The hardware device type. + * \param[in] vendor_id The hardware device's vendor identifier. + * \param[in] device_id The hardware device's identifier. + * \param[in] vendor_name The hardware device's vendor name as a null-terminated string. Copied by ORT. + * \param[in] metadata Optional OrtKeyValuePairs instance for hardware device metadata that may be queried by + * applications via OrtApi::GetEpDevices(). + * Refer to onnxruntime_ep_device_ep_metadata_keys.h for common OrtHardwareDevice metadata keys. + * \param[out] hardware_device Output parameter set to the new OrtHardwareDevice instance that is created. + * Must be release with ReleaseHardwareDevice(). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateHardwareDevice, _In_ OrtHardwareDeviceType type, + _In_ uint32_t vendor_id, + _In_ uint32_t device_id, + _In_ const char* vendor_name, + _In_opt_ const OrtKeyValuePairs* metadata, + _Out_ OrtHardwareDevice** hardware_device); + + ORT_CLASS_RELEASE(HardwareDevice); + + /** \brief Creates an empty kernel registry. A kernel registry contains kernel creation information for + * every operator kernel supported by an EP. + * + * \remarks Refer to OrtEp::GetKernelRegistry, which returns an EP's kernel registry to ORT. + * + * \param[out] kernel_registry Output parameter set to the new OrtKernelRegistry instance. + * Must be released with OrtEpApi::ReleaseKernelRegistry. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateKernelRegistry, _Outptr_ OrtKernelRegistry** kernel_registry); + + ORT_CLASS_RELEASE(KernelRegistry); + + /** \brief Adds kernel creation information for a supported operator kernel to the given kernel registry. + * + * \remarks Refer to OrtEp::GetKernelRegistry, which returns an EP's kernel registry to ORT. + * + * \param[in] kernel_registry The OrtKernelRegistry instance. + * \param[in] kernel_def The kernel definition, which includes operator type, version, EP name, type constraints, etc. + * \param[in] kernel_create_func Function that creates an instance of the operator kernel as a OrtKernelImpl instance. + * \param[in] kernel_create_func_state Custom state passed to the kernel creation function. Can be null. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelRegistry_AddKernel, _In_ OrtKernelRegistry* kernel_registry, + _In_ const OrtKernelDef* kernel_def, _In_ OrtKernelCreateFunc kernel_create_func, + _In_ void* kernel_create_func_state); + + /** \brief Creates a kernel definition builder used to create instances of OrtKernelDef. + * + * \param[out] kernel_def_builder_out Output parameter set to the new OrtKernelDefBuilder instance. + * Must be released with OrtEpApi::ReleaseKernelDefBuilder(). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateKernelDefBuilder, _Outptr_ OrtKernelDefBuilder** kernel_def_builder_out); + + ORT_CLASS_RELEASE(KernelDefBuilder); + + /** \brief Sets the kernel's operator type. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] op_type A null-terminated string representing the operator type. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_SetOperatorType, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_ const char* op_type); + + /** \brief Sets the kernel's domain. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] domain A null-terminated string representing the operator's domain. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_SetDomain, _In_ OrtKernelDefBuilder* kernel_def_builder, _In_ const char* domain); + + /** \brief Sets the kernel's opset version range that is supported. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] since_version_start The starting opset version that is supported. + * \param[in] since_version_end The ending opset version (inclusive) that is supported. + * Can be set equal to the starting version to indicate that only one + * version is supported. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_SetSinceVersion, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_ int since_version_start, _In_ int since_version_end); + + /** \brief Sets the name of the kernel's intended execution provider. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] ep_name A null-terminated string representing the execution provider's name. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_SetExecutionProvider, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_ const char* ep_name); + + /** \brief Sets the memory type for a kernel input. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] input_index The index of the input. + * \param[in] mem_type The input's memory type. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_SetInputMemType, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_ size_t input_index, _In_ OrtMemType mem_type); + + /** \brief Sets the memory type for a kernel output. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] output_index The index of the output. + * \param[in] mem_type The output's memory type. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_SetOutputMemType, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_ size_t output_index, _In_ OrtMemType mem_type); + + /** \brief Adds type constraints for a kernel argument represented as a string (e.g., "T"). + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] arg_name A null-terminated string representing the argument to constrain (e.g., "T"). + * \param[in] types Array of OrtDataType instances representing allowed types for the argument. + * Must contain `num_types` elements. + * \param[in] num_types The number of OrtDataType elements in the `types` array. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_AddTypeConstraint, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_ const char* arg_name, _In_reads_(num_types) const OrtDataType* const* types, + _In_ size_t num_types); + + /** \brief Adds aliases for the given input and output pairs. + * + * \note Used for operators like Identity and Reshape to allow ORT to reuse the input buffer for the output + * without modification. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] input_indices Array of input indices. Array must contain `num_io_indices` elements. + * \param[in] output_indices Array of output indices. Each output index is aliased with a corresponding + * input index in `input_indices`. Array must contain `num_io_indices` elements. + * \param[in] num_io_indices The number of input/output index pairs to alias. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_AddInputOutputAliases, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_reads_(num_io_indices) int const* input_indices, + _In_reads_(num_io_indices) int const* output_indices, + _In_ size_t num_io_indices); + + /** \brief Adds mutable aliases for the given input and output pairs. + * + * \note Allows ORT to reuse and *modify* an input buffer (in-place) for the output buffer. + * This is also known as "MayInplace" within the ORT codebase. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[in] input_indices Array of input indices. Array must contain `num_io_indices` elements. + * \param[in] output_indices Array of output indices. Each output index is aliased with a corresponding + * input index in `input_indices`. Array must contain `num_io_indices` elements. + * \param[in] num_io_indices The number of input/output index pairs to alias. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_AddInputOutputMutableAliases, _In_ OrtKernelDefBuilder* kernel_def_builder, + _In_reads_(num_io_indices) int const* input_indices, + _In_reads_(num_io_indices) int const* output_indices, + _In_ size_t num_io_indices); + + /** \brief Creates a OrtKernelDef instance from the given kernel definition builder. + * + * \param[in] kernel_def_builder The OrtKernelDefBuilder instance. + * \param[out] kernel_def_out The new OrtKernelDef instance. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDefBuilder_Build, _In_ OrtKernelDefBuilder* kernel_def_builder, + _Outptr_ OrtKernelDef** kernel_def_out); + + ORT_CLASS_RELEASE(KernelDef); + + /** \brief Returns the operator type from the kernel definition. + * + * \param[in] kernel_def The OrtKernelDef instance. + * \return A null-terminated string representing the operator type. + * + * \since Version 1.24. + */ + ORT_API_T(const char*, KernelDef_GetOperatorType, _In_ const OrtKernelDef* kernel_def); + + /** \brief Returns the operator's domain from the kernel definition. + * + * \param[in] kernel_def The OrtKernelDef instance. + * \return A null-terminated string representing the operator's domain. + * + * \since Version 1.24. + */ + ORT_API_T(const char*, KernelDef_GetDomain, _In_ const OrtKernelDef* kernel_def); + + /** \brief Gets the kernel's opset version range that is supported. + * + * \param[in] kernel_def The OrtKernelDef instance. + * \param[out] start_version Output parameter set to the starting opset version that is supported. + * \param[out] end_version Output parameter set to the ending opset version (inclusive) that is supported. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDef_GetSinceVersion, _In_ const OrtKernelDef* kernel_def, + _Out_ int* start_version, _Out_ int* end_version); + + /** \brief Returns the name of the kernel's intended execution provider. + * + * \param[in] kernel_def The OrtKernelDef instance. + * \return A null-terminated string representing the name of the execution provider. + * + * \since Version 1.24. + */ + ORT_API_T(const char*, KernelDef_GetExecutionProvider, _In_ const OrtKernelDef* kernel_def); + + /** \brief Gets the memory type for a kernel input. + * + * \param[in] kernel_def The OrtKernelDef instance. + * \param[in] input_index The index of the input. + * \param[out] mem_type Output parameter set to the input's memory type. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDef_GetInputMemType, _In_ const OrtKernelDef* kernel_def, + _In_ size_t input_index, _Out_ OrtMemType* mem_type); + + /** \brief Gets the memory type for a kernel output. + * + * \param[in] kernel_def The OrtKernelDef instance. + * \param[in] output_index The index of the output. + * \param[out] mem_type Output parameter set to the output's memory type. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(KernelDef_GetOutputMemType, _In_ const OrtKernelDef* kernel_def, + _In_ size_t output_index, _Out_ OrtMemType* mem_type); + + /** \brief Gets the OrtDataType that represents the data type for a tensor of the given element type. + * + * \param[in] elem_type The tensor's element type. + * \param[out] out Output parameter set to the OrtDataType. Owned by ORT and must not be released. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetTensorDataType, _In_ ONNXTensorElementDataType elem_type, + _Outptr_ const OrtDataType** out); + + /** \brief Gets the kernel definition for a given node, if any exists for the calling execution provider. + * + * Used within OrtEp::GetCapability() to get the registered kernel definition for the given node. + * The kernel definition is set to NULL if there is no registered kernel definition for the node + * and execution provider. + * + * \param[in] graph_support_info The OrtEpGraphSupportInfo instance to query. + * \param[in] node The node for which to look up a kernel definition. + * \param[out] out_kernel_def Output parameter set to the OrtKernelDef or NULL. + * Owned by ORT and must not be released. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(EpGraphSupportInfo_LookUpKernel, _In_ OrtEpGraphSupportInfo* graph_support_info, + _In_ const OrtNode* node, _Outptr_result_maybenull_ const OrtKernelDef** out_kernel_def); + + /** \brief Sets one or more data buffers that collectively hold the pre-packed data for a single shared weight. + * + * \note Used within the implementation of OrtKernelImpl::PrePackWeight() when the kernel wants to share pre-packed + * weight data with other kernels. The buffer data MUST be allocated with the OrtAllocator provided to + * OrtKernelImpl::PrePack. + * + * \note Ownership of weight data transfers to the OrtSharedPrePackedWeightCache instance on success. + * If this function returns an error status, the caller retains ownership of the weight data. + * + * \note Subsequent calls with the same OrtSharedPrePackedWeightCache instance release and replace the old data. + * + * \param[in] prepacked_weight_cache The OrtSharedPrePackedWeightCache instance. + * \param[in] buffer_data_ptrs An array of buffer data pointers that collectively hold the pre-packed data for a + * single shared weight. Note that sometimes a single weight may have multiple pre-packed + * buffers and it is up to the kernel implementation to determine how to split the data + * into multiple buffers (if desired). + * \param[in] buffer_data_sizes An array of buffer byte sizes, one per element in `buffer_data_ptrs`. + * \param[in] num_buffers The number of buffers used to store the data for the shared pre-packed weight. + * Specifies the number of elements in the `buffer_data_ptrs` and `buffer_data_sizes` arrays. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(SharedPrePackedWeightCache_StoreWeightData, + _In_ OrtSharedPrePackedWeightCache* prepacked_weight_cache, + _In_reads_(num_buffers) void** buffer_data_ptrs, _In_reads_(num_buffers) size_t* buffer_data_sizes, + _In_ size_t num_buffers); + + /** \brief Get the OrtEp instance to which the node is assigned from the OrtKernelInfo. + * + * \note Used within OrtKernelImpl implementations to obtain a reference to the OrtEp. + * + * \param[in] info The ::OrtKernelInfo instance. + * \param[out] ep Output parameter set to the OrtEp instance associated with the OrtKernelInfo. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(KernelInfo_GetEp, _In_ const OrtKernelInfo* info, _Outptr_ const OrtEp** ep); + + /** \brief Set the details of an OrtDeviceEpIncompatibilityDetails instance. + * + * Used by execution provider factories to set incompatibility details in their + * GetHardwareDeviceIncompatibilityDetails implementation. ORT creates and initializes the object + * before passing it to the EP, so calling this function is optional. The EP uses this function + * to set incompatibility information when the device is not compatible. + * + * \param[in,out] details The OrtDeviceEpIncompatibilityDetails instance to update. + * \param[in] reasons_bitmask Bitmask of OrtDeviceEpIncompatibilityReason values. (0 = no incompatibility). + * \param[in] error_code Optional EP-specific error code (0 = no error). + * \param[in] notes Optional human-readable notes. Can be null. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_SetDetails, _Inout_ OrtDeviceEpIncompatibilityDetails* details, + _In_ uint32_t reasons_bitmask, + _In_ int32_t error_code, + _In_opt_z_ const char* notes); + + /** \brief Creates an OrtKernelImpl instance for an If operator. + * + * Control flow operators require access to ORT session internals to orchestrate subgraph operations. + * This function allows an EP to create a properly configured OrtKernelImpl with access to ORT internals that + * the EP can add to its kernel registry. + * + * An EP is required to create an OrtKernelDef that keeps input[0] ('cond') on the CPU (i.e., OrtMemTypeCPUInput) + * as this input is used by CPU logic. The output should remain on the device (i.e., OrtMemTypeDefault), which is + * the default setting, to avoid copying to/from CPU. + * + * Example kernel definition (CXX API): + * Ort::KernelDef kernel_def = Ort::KernelDefBuilder() + * .SetDomain("").SetOperatorType("If").SetSinceVersion(21, 22) + * .SetExecutionProvider("MyEp") + * .SetInputMemType(0, OrtMemTypeCPUInput) // 'cond' on CPU + * .SetOutputMemType(0, OrtMemTypeDefault) // output on EP device + * .AddTypeConstraint("B", ...) + * .AddTypeConstraint("V", ...).Build(); + * + * \param[in] kernel_info The ::OrtKernelInfo instance for an If node. This function returns error ORT_FAIL + * if the opset version specified by `kernel_info` is unsupported. + * \param[out] kernel_out Output parameter set to the OrtKernelImpl instance for the If node. + * Must be released via ::ReleaseKernelImpl, unless ownership is transferred + * to ORT (see OrtKernelCreateFunc and ::KernelRegistry_AddKernel()). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(CreateIfKernel, _In_ const OrtKernelInfo* kernel_info, _Outptr_ OrtKernelImpl** kernel_out); + + /** \brief Creates an OrtKernelImpl instance for a Loop operator. + * + * Control flow operators require access to ORT session internals to orchestrate subgraph operations. + * This function allows an EP to create a properly configured OrtKernelImpl with access to ORT internals that + * the EP can add to its kernel registry. + * + * An EP is required to create an OrtKernelDef that keeps input[0] ('M') and input[1] ('cond') on the CPU + * (i.e., OrtMemTypeCPUInput) as these inputs are used by CPU logic. Input[2] ('v_initial') and the output should + * remain on the device (i.e., OrtMemTypeDefault), which is the default setting, to avoid copying to/from CPU. + * + * Example kernel definition (CXX API): + * Ort::KernelDef kernel_def = Ort::KernelDefBuilder() + * .SetDomain("").SetOperatorType("Loop").SetSinceVersion(21, 22) + * .SetExecutionProvider("MyEp") + * .SetInputMemType(0, OrtMemTypeCPUInput) // 'M' on CPU + * .SetInputMemType(1, OrtMemTypeCPUInput) // 'cond' on CPU + * .SetInputMemType(2, OrtMemTypeDefault) // 'v_initial' on EP device + * .SetOutputMemType(0, OrtMemTypeDefault) // output on EP device + * .AddTypeConstraint("I", ...) + * .AddTypeConstraint("B", ...) + * .AddTypeConstraint("V", ...).Build(); + * + * \param[in] kernel_info The ::OrtKernelInfo instance for a Loop node. This function returns error ORT_FAIL + * if the opset version specified by `kernel_info` is unsupported. + * \param[in] helper A OrtLoopKernelHelper instance that contains helper functions that ORT calls during kernel + * execution to operate on tensors allocated with the EP's device memory. + * ORT will call OrtLoopKernelHelper::Release() to release the helper and its resources. + * \param[out] kernel_out Output parameter set to the OrtKernelImpl instance for the Loop node. + * Must be released via ::ReleaseKernelImpl, unless ownership is transferred + * to ORT (see OrtKernelCreateFunc and ::KernelRegistry_AddKernel()). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(CreateLoopKernel, _In_ const OrtKernelInfo* kernel_info, _In_ OrtLoopKernelHelper* helper, + _Outptr_ OrtKernelImpl** kernel_out); + + /** \brief Creates an OrtKernelImpl instance for a Scan operator. Does not support opset versions older than 9. + * + * Control flow operators require access to ORT session internals to orchestrate subgraph operations. + * This function allows an EP to create a properly configured OrtKernelImpl with access to ORT internals that + * the EP can add to its kernel registry. + * + * It is recommended that an EP create an OrtKernelDef that keeps the inputs and outputs on the EP's + * device (i.e., OrtMemTypeDefault), which is the default setting, to avoid copying to/from CPU. + * + * Example kernel definition (CXX API): + * Ort::KernelDef kernel_def = Ort::KernelDefBuilder() + * .SetDomain("").SetOperatorType("Scan").SetSinceVersion(21, 22) + * .SetExecutionProvider("MyEp") + * .SetInputMemType(0, OrtMemTypeDefault) // input[0] on EP device + * .SetOutputMemType(0, OrtMemTypeDefault) // output[0] on EP device + * .AddTypeConstraint("V", ...).Build(); + * + * \param[in] kernel_info The ::OrtKernelInfo instance for a Scan node. This function returns error ORT_FAIL + * if the opset version specified by `kernel_info` is unsupported. + * \param[in] helper A OrtScanKernelHelper instance that contains helper functions that ORT calls during kernel + * execution to operate on tensors allocated with the EP's device memory. + * ORT will call OrtScanKernelHelper::Release() to release the helper and its resources. + * \param[out] kernel_out Output parameter set to the OrtKernelImpl instance for the Scan node. + * Must be released via ::ReleaseKernelImpl, unless ownership is transferred + * to ORT (see OrtKernelCreateFunc and ::KernelRegistry_AddKernel()). + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(CreateScanKernel, _In_ const OrtKernelInfo* kernel_info, _In_ OrtScanKernelHelper* helper, + _Outptr_ OrtKernelImpl** kernel_out); + + ORT_CLASS_RELEASE(KernelImpl); + + /** \brief Gets a new OrtKeyValuePairs instance containing a copy of all configuration entries set on the environment. + * + * \note An application provides environment-level configuration options for execution provider libraries by + * using keys with the prefix 'ep_factory.\\.'. Ex: the key 'ep_factory.my_ep.some_ep_key' represents + * a key named 'some_ep_key' that is meant to be consumed by an execution provider named 'my_ep'. Refer to + * the specific execution provider's documentation for valid keys and values. + * + * \note Refer to onnxruntime_env_config_keys.h for common configuration entry keys and their supported values. + * + * \param[out] config_entries Output parameter set to the OrtKeyValuePairs instance containing all configuration entries. + * Must be released via OrtApi::ReleaseKeyValuePairs. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * \since Version 1.24 + */ + ORT_API2_STATUS(GetEnvConfigEntries, _Outptr_ OrtKeyValuePairs** config_entries); }; /** @@ -561,6 +1540,9 @@ struct OrtEp { * graphs are only valid for the duration of the call to Compile. Any graph/node/input/output * names that are needed by the OrtNodeComputeInfo functions must be copied and stored by the OrtEp. * + * \note As of version 1.24, implementation of this function is optional if the EP does not compile nodes and + * uses a kernel registry instead. + * * \since Version 1.23. */ ORT_API2_STATUS(Compile, _In_ OrtEp* this_ptr, _In_ const OrtGraph** graphs, @@ -574,6 +1556,9 @@ struct OrtEp { * \param[inout] node_compute_infos The OrtNodeComputeInfo instances to release. * \param[in] num_node_compute_infos The number of OrtNodeComputeInfo instances. * + * \note As of version 1.24, implementation of this function is optional if the EP does not compile nodes and + * uses a kernel registry instead. + * * \since Version 1.23. */ ORT_API_T(void, ReleaseNodeComputeInfos, _In_ OrtEp* this_ptr, @@ -726,6 +1711,36 @@ struct OrtEp { */ ORT_API_T(const char*, GetCompiledModelCompatibilityInfo, _In_ OrtEp* this_ptr, _In_ const OrtGraph* graph); + + /** \brief Gets the execution provider's kernel registry, if any. + * + * A kernel registry contains kernel creation information for operator kernels supported by an EP. + * + * \param[in] this_ptr The OrtEp instance. + * \param[out] kernel_registry Output parameter set to the EP's kernel registry, which must remain valid throughout + * the lifetime of the EP. Can be NULL if the EP doesn't use a kernel registry. + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \note Implementation of this function is optional. If set to NULL, ORT assumes the EP compiles nodes. + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetKernelRegistry, _In_ OrtEp* this_ptr, + _Outptr_result_maybenull_ const OrtKernelRegistry** kernel_registry); + + /** \brief Gets whether the execution provider supports concurrent run calls made on the session. + * + * \param[in] this_ptr The OrtEp instance. + * \param[out] is_supported Whether concurrent runs are supported. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \note Implementation of this function is optional and it may be set to NULL. + * If not implemented, ORT assumes that concurrent runs are supported. + * + * \since Version 1.24. + */ + ORT_API2_STATUS(IsConcurrentRunSupported, _In_ OrtEp* this_ptr, _Outptr_ bool* is_supported); }; /** \brief The function signature that ORT will call to create OrtEpFactory instances. @@ -981,6 +1996,115 @@ struct OrtEpFactory { _In_ const OrtMemoryDevice* memory_device, _In_opt_ const OrtKeyValuePairs* stream_options, _Outptr_ OrtSyncStreamImpl** stream); + + /** \brief Check for known incompatibility reasons between a hardware device and this execution provider. + * + * This function allows an execution provider to check if a specific hardware device is compatible + * with the execution provider. The EP can set specific incompatibility reasons via the + * OrtDeviceEpIncompatibilityDetails parameter using OrtEpApi::DeviceEpIncompatibilityDetails_SetDetails. + * + * \param[in] this_ptr The OrtEpFactory instance. + * \param[in] hw The hardware device to check for incompatibility. + * \param[in,out] details Pre-allocated incompatibility details object created and initialized by ORT. + * The EP can use OrtEpApi::DeviceEpIncompatibilityDetails_SetDetails to set + * incompatibility information. If the device is compatible, the EP can + * leave the object unchanged (it defaults to no incompatibility). + * + * \note Implementation of this function is optional. + * If not implemented, ORT will assume the device is compatible with this EP. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetHardwareDeviceIncompatibilityDetails, _In_ OrtEpFactory* this_ptr, + _In_ const OrtHardwareDevice* hw, + _Inout_ OrtDeviceEpIncompatibilityDetails* details); + + /** \brief Create an OrtExternalResourceImporterImpl for external resource import. + * + * This is used to create an external resource importer that enables zero-copy import of + * external GPU memory (e.g., D3D12 shared resources) and synchronization primitives + * (e.g., D3D12 timeline fences). + * + * EPs that support external resource import (via CUDA, HIP, Vulkan, or D3D12 APIs) can + * implement this to allow applications to share GPU resources without copies. + * + * \param[in] this_ptr The OrtEpFactory instance. + * \param[in] ep_device The OrtEpDevice to create the external resource importer for. + * \param[out] out_importer The created OrtExternalResourceImporterImpl instance. + * Set to nullptr if external resource import is not supported. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \note Implementation of this function is optional. + * An EP factory should only implement this if it supports external resource import. + * If not implemented or not supported, return ORT_NOT_IMPLEMENTED or set out_importer to nullptr. + * + * \since Version 1.24. + */ + ORT_API2_STATUS(CreateExternalResourceImporterForDevice, _In_ OrtEpFactory* this_ptr, + _In_ const OrtEpDevice* ep_device, + _Outptr_result_maybenull_ OrtExternalResourceImporterImpl** out_importer); + + /** \brief Returns the number of OrtCustomOpDomains that this factory provides. + * + * \param[in] this_ptr The OrtEpFactory instance. + * \param[out] num_domains Output parameter set to the number of provided OrtCustomOpDomain instances. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetNumCustomOpDomains, _In_ OrtEpFactory* this_ptr, _Out_ size_t* num_domains); + + /** \brief Gets the EP-specific OrtCustomOpDomains. + * + * This function is used when running inference on a model that contains EP-specific custom operations. + * + * Workflow: + * 1. The EP factory implements this function to supply a list of OrtCustomOpDomain instances. + * 2. The application either 1) calls SessionOptionsAppendExecutionProvider_V2() with an OrtEpDevice containing + * the plugin EP's factory or 2) enables auto ep selection. + * 3. 1) SessionOptionsAppendExecutionProvider_V2() appends the provided OrtCustomOpDomains to the + * session options or 2) ORT registers the OrtCustomOpDomains provided by the EP devices + * that could be potentially selected. + * + * As a result, any session created from these session options will have these custom op domains registered + * in ORT, ensuring that the custom ops are properly recognized and validated when the model is loaded. + * + * Plugin EPs can provide two types of custom ops: + * 1. A full OrtCustomOp with a concrete kernel implementation + * - A Plugin EP can supply an OrtCustomOp and a corresponding CustomKernel::Compute() implementation. + * - In GetCapability(), it calls EpGraphSupportInfo_AddSingleNode() to inform ORT + * that the custom node should NOT be fused or compiled. Instead, ORT should invoke + * the custom node's Compute() function at runtime. + * + * 2. A "placeholder" OrtCustomOp with an empty kernel implementation + * - A compile-based Plugin EP can supply an OrtCustomOp whose CustomKernel::Compute() + * does nothing. The purpose is to satisfy model validation during model loading by + * registering the custom op as a valid operator in the session. + * - In GetCapability(), the EP should call EpGraphSupportInfo_AddNodesToFuse() to + * notify ORT that this custom node should be fused and compiled by the EP. + * - In Compile(), the EP executes its compiled bits to perform inference for + * the fused custom node. + * + * Note: The OrtCustomOpDomain instances must be valid while any session is using them. + EP factory has the responsibility to release OrtCustomOpDomain instances it creates. It happens + * automatically if using the C++ Ort::CustomOpDomain class. + * + * \param[in] this_ptr The OrtEpFactory instance. + * \param[out] domains Array of `num_domains` elements pre-allocated by ORT that should be filled with + OrtCustomOpDomain instances created by the EP. The `num_domains` is the value returned by + GetNumCustomOpDomains(). + * \param[in] num_domains The size of the `domains` array pre-allocated by ORT. + * + * \snippet{doc} snippets.dox OrtStatus Return Value + * + * \since Version 1.24. + */ + ORT_API2_STATUS(GetCustomOpDomains, _In_ OrtEpFactory* this_ptr, + _Out_writes_all_(num_domains) OrtCustomOpDomain** domains, _In_ size_t num_domains); }; #ifdef __cplusplus diff --git a/onnxruntime/include/onnxruntime_ep_device_ep_metadata_keys.h b/onnxruntime/include/onnxruntime_ep_device_ep_metadata_keys.h index bbd6a43b..5ea42618 100644 --- a/onnxruntime/include/onnxruntime_ep_device_ep_metadata_keys.h +++ b/onnxruntime/include/onnxruntime_ep_device_ep_metadata_keys.h @@ -3,12 +3,15 @@ #pragma once -// This file contains well-known keys for OrtEpDevice EP metadata entries. +// This file contains well-known keys for OrtEpDevice and OrtHardwareDevice metadata entries. // It does NOT specify all available metadata keys. // Key for the execution provider version string. This should be available for all plugin EPs. static const char* const kOrtEpDevice_EpMetadataKey_Version = "version"; +// Key for the execution provider OS driver version. +static const char* const kOrtEpDevice_EpMetadataKey_OSDriverVersion = "os_driver_version"; + // Prefix for execution provider compatibility information stored in model metadata. // Used when generating EP context models to store compatibility strings for each EP. // Full key format: "ep_compatibility_info." @@ -16,3 +19,10 @@ static const char* const kOrtModelMetadata_EpCompatibilityInfoPrefix = "ep_compa // Key for the execution provider library path (for dynamically loaded EPs) static const char* const kOrtEpDevice_EpMetadataKey_LibraryPath = "library_path"; + +// Optional metadata key to determine if a OrtHardwareDevice represents a virtual (non-hardware) device. +// Possible values: +// - "0": OrtHardwareDevice is not virtual (i.e., actual hardware device). This is the assumed default value +// if this metadata key is not present. +// - "1": OrtHardwareDevice is virtual. +static const char* const kOrtHardwareDevice_MetadataKey_IsVirtual = "is_virtual"; diff --git a/onnxruntime/include/onnxruntime_float16.h b/onnxruntime/include/onnxruntime_float16.h index 408d3ccf..625a1e82 100644 --- a/onnxruntime/include/onnxruntime_float16.h +++ b/onnxruntime/include/onnxruntime_float16.h @@ -76,6 +76,7 @@ struct Float16Impl { static constexpr uint16_t kPositiveQNaNBits = 0x7E00U; static constexpr uint16_t kNegativeQNaNBits = 0xFE00U; static constexpr uint16_t kMaxValueBits = 0x7BFFU; // Largest normal number + static constexpr uint16_t kMinValueBits = 0xFBFFU; // Lowest normal number static constexpr uint16_t kOneBits = 0x3C00U; static constexpr uint16_t kMinusOneBits = 0xBC00U; @@ -363,6 +364,7 @@ struct BFloat16Impl { static constexpr uint16_t kPositiveQNaNBits = 0x7FC1U; static constexpr uint16_t kNegativeQNaNBits = 0xFFC1U; static constexpr uint16_t kMaxValueBits = 0x7F7FU; + static constexpr uint16_t kMinValueBits = 0xFF7FU; static constexpr uint16_t kRoundToNearest = 0x7FFFU; static constexpr uint16_t kOneBits = 0x3F80U; static constexpr uint16_t kMinusOneBits = 0xBF80U; diff --git a/onnxruntime/include/onnxruntime_lite_custom_op.h b/onnxruntime/include/onnxruntime_lite_custom_op.h index 5002e16b..81c20768 100644 --- a/onnxruntime/include/onnxruntime_lite_custom_op.h +++ b/onnxruntime/include/onnxruntime_lite_custom_op.h @@ -447,18 +447,6 @@ struct OrtLiteCustomOp : public OrtCustomOp { } #endif -#ifdef ORT_ROCM_CTX - template - static typename std::enable_if::value, std::tuple>::type - CreateTuple(OrtKernelContext* context, ArgPtrs& args, size_t num_input, size_t num_output, const std::string& ep) { - thread_local RocmContext rocm_context; - rocm_context.Init(*context); - std::tuple current = std::tuple{rocm_context}; - auto next = CreateTuple(context, args, num_input, num_output, ep); - return std::tuple_cat(current, next); - } -#endif - template static typename std::enable_if::value, std::tuple>::type CreateTuple(OrtKernelContext* context, ArgPtrs& args, size_t num_input, size_t num_output, const std::string& ep) { @@ -674,14 +662,6 @@ struct OrtLiteCustomOp : public OrtCustomOp { } #endif -#ifdef ORT_ROCM_CTX - template - static typename std::enable_if<0 <= sizeof...(Ts) && std::is_same::value>::type - ParseArgs(std::vector& input_types, std::vector& output_types) { - ParseArgs(input_types, output_types); - } -#endif - template static typename std::enable_if<0 <= sizeof...(Ts) && std::is_same::value>::type ParseArgs(std::vector& input_types, std::vector& output_types) { diff --git a/onnxruntime/include/onnxruntime_session_options_config_keys.h b/onnxruntime/include/onnxruntime_session_options_config_keys.h index 7eb5f765..1ea147a0 100644 --- a/onnxruntime/include/onnxruntime_session_options_config_keys.h +++ b/onnxruntime/include/onnxruntime_session_options_config_keys.h @@ -374,6 +374,12 @@ static const char* const kOrtSessionOptionsEpContextModelExternalInitializersFil // - "1": Gemm FastMath mode is enabled. static const char* const kOrtSessionOptionsMlasGemmFastMathArm64Bfloat16 = "mlas.enable_gemm_fastmath_arm64_bfloat16"; +// Use LUT (Lookup Table) based GEMM for quantized models when available. +// Option values: +// - "0": Do not use LUT based GEMM. [DEFAULT] +// - "1": Use LUT based GEMM when available. +static const char* const kOrtSessionOptionsMlasLutGemm = "mlas.use_lut_gemm"; + // When converting DQ + MatMul -> MatMulNBits, the accuracy level of the MatMulNBits is controlled by this option. // Refer to MatMulNBits op schema for more details. // If not provided, default is 4. @@ -408,3 +414,18 @@ static const char* const kOrtSessionOptionsDisableModelCompile = "session.disabl // Note: UNSUPPORTED models always fail regardless of this setting. static const char* const kOrtSessionOptionsFailOnSuboptimalCompiledModel = "session.fail_on_suboptimal_compiled_model"; + +// THIS OPTION IS NOT A REGULAR SESSION OPTION SINCE IT CAN BE MODIFIED AT ANY TIME +// Meant to be used with SetEpDynamicOptions +// options for HTP performance mode: "burst", "balanced", "default", "high_performance", +// "high_power_saver", "low_balanced", "extreme_power_saver", "low_power_saver", "power_saver", +// "sustained_high_performance". Default to "default". +static const char* const kOrtEpDynamicOptionsQnnHtpPerformanceMode = "ep.dynamic.qnn_htp_performance_mode"; + +// Enables the session to record information about the subgraphs/nodes assigned to execution providers. +// When enabled, an application may call Session_GetEpGraphAssignmentInfo() to retrieve the information. +// +// Option values: +// - "0": Recording of EP graph assignment information is disabled. [DEFAULT] +// - "1": Recording of EP graph assignment information is enabled. +static const char* const kOrtSessionOptionsRecordEpGraphAssignmentInfo = "session.record_ep_graph_assignment_info"; diff --git a/onnxruntime/include/onnxruntime_training_c_api.h b/onnxruntime/include/onnxruntime_training_c_api.h deleted file mode 100644 index ed6d151a..00000000 --- a/onnxruntime/include/onnxruntime_training_c_api.h +++ /dev/null @@ -1,731 +0,0 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. -// Licensed under the MIT License. - -// This file contains the training c apis. - -#pragma once -#include -#include "onnxruntime_c_api.h" - -/** \page training_c_cpp_api Training C & C++ APIs - * - * Training C and C++ APIs are an extension of the \ref c_cpp_api "onnxruntime core C and C++ APIs" and should be used in conjunction with them. - * - * In order to train a model with onnxruntime, the following training artifacts must be generated: - * - The training onnx model - * - The checkpoint file - * - The optimizer onnx model - * - The eval onnx model model (optional) - * - * These training artifacts can be generated as part of an offline step using the python [utilities](https://github.com/microsoft/onnxruntime/blob/main/orttraining/orttraining/python/training/onnxblock/README.md) made available in the `onnxruntime-training` python package. - * - * After these artifacts have been generated, the C and C++ utilities listed in this documentation can be leveraged to perform training. - * - * If any problem is encountered, please create an [issue](https://github.com/microsoft/onnxruntime/issues/new) with your scenario and requirements, and we will be sure to respond and follow up on the request. - * - *

Training C API

- * - * ::OrtTrainingApi - Training C API functions. - * - * This C structure contains functions that enable users to perform training with onnxruntime. - * - * _Sample Code_: - * - * ```c - * #include - * - * OrtApi* g_ort_api = OrtGetApiBase()->GetApi(ORT_API_VERSION); - * OrtTrainingApi* g_ort_training_api = g_ort_api->GetTrainingApi(ORT_API_VERSION); - * - * OrtEnv* env = NULL; - * g_ort_api->CreateEnv(logging_level, logid, &env); - * OrtSessionOptions* session_options = NULL; - * g_ort_api->CreateSessionOptions(&session_options); - * - * OrtCheckpointState* state = NULL; - * g_ort_training_api->LoadCheckpoint(path_to_checkpoint, &state); - * - * OrtTrainingSession* training_session = NULL; - * g_ort_training_api->CreateTrainingSession(env, session_options, training_model_path, - * state, eval_model_path, optimizer_model_path, - * &training_session); - * // Training loop - * { - * g_ort_training_api->TrainStep(...); - * g_ort_training_api->OptimizerStep(...); - * g_ort_training_api->LazyResetGrad(...); - * } - * - * g_ort_training_api->ExportModelForInferencing(training_session, inference_model_path, ...); - * g_ort_training_api->SaveCheckpoint(state, path_to_checkpoint, false); - * - * g_ort_training_api->ReleaseTrainingSession(training_session); - * g_ort_training_api->ReleaseCheckpointState(state); - * ``` - * - * > **Note** - * > The ::OrtCheckpointState contains the entire training state that the ::OrtTrainingSession uses. As a result, the training session must always have access to the state. That is to say, the ::OrtCheckpointState instance must outlive the lifetime of the ::OrtTrainingSession instance. - * - *

Training C++ API

- * - * @ref TrainingCpp - Training C++ API classes and functions. - * - * These C++ classes and functions enable users to perform training with onnxruntime. - * - * _Sample Code_: - * - * ```cc - * #include - * - * Ort::Env env; - * Ort::SessionOptions session_options; - * - * auto state = Ort::CheckpointState::LoadCheckpoint(path_to_checkpoint); - * auto training_session = Ort::TrainingSession(env, session_options, state, training_model_path, - * eval_model_path, optimizer_model_path); - * - * // Training Loop - * { - * training_session.TrainStep(...); - * training_session.OptimizerStep(...); - * training_session.LazyResetGrad(...); - * } - * - * training_session->ExportModelForInferencing(inference_model_path, ...); - * Ort::CheckpointState::SaveCheckpoint(state, path_to_checkpoint, false); - * ``` - * > **Note** - * > The ::Ort::CheckpointState contains the entire training state that the ::Ort::TrainingSession uses. As a result, the training session must always have access to the state. That is to say, the ::Ort::CheckpointState instance must outlive the lifetime of the ::Ort::TrainingSession instance. - */ - -/** @defgroup TrainingC Ort Training C API - * @{ - */ -ORT_RUNTIME_CLASS(TrainingSession); // Type that enables performing training for the given user models. -ORT_RUNTIME_CLASS(CheckpointState); // Type that holds the training states for the training session. - -/** \brief Type of property to be added to or returned from the ::OrtCheckpointState. - */ -typedef enum OrtPropertyType { - OrtIntProperty = 0, - OrtFloatProperty = 1, - OrtStringProperty = 2, -} OrtPropertyType; - -/** \brief The Training C API that holds onnxruntime training function pointers - * - * All the Training C API functions are defined inside this structure as pointers to functions. - * Call OrtApi::GetTrainingApi to get a pointer to this struct. - * - * \nosubgrouping - */ -struct OrtTrainingApi { - /// \name Accessing The Training Session State - /// @{ - - /** \brief Load a checkpoint state from a file on disk into checkpoint_state. - * - * This function will parse a checkpoint file, pull relevant data and load the training - * state into the checkpoint_state. This checkpoint state can then be used to create the - * training session by invoking OrtTrainingApi::CreateTrainingSession. By doing so, the training - * session will resume training from the given checkpoint state. - * \note Note that the training session created with a checkpoint state uses this state to store the entire - * training state (including model parameters, its gradients, the optimizer states and the properties). - * As a result, it is required that the checkpoint state outlive the lifetime of the training session. - * \note Note that the checkpoint file can be either the complete checkpoint or the nominal checkpoint. - * - * \param[in] checkpoint_path Path to the checkpoint file - * \param[out] checkpoint_state Checkpoint state that contains the states of the training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(LoadCheckpoint, _In_ const ORTCHAR_T* checkpoint_path, - _Outptr_ OrtCheckpointState** checkpoint_state); - - /** \brief Save the given state to a checkpoint file on disk. - * - * This function serializes the provided checkpoint state to a file on disk. - * This checkpoint can later be loaded by invoking OrtTrainingApi::LoadCheckpoint to resume - * training from this snapshot of the state. - * - * \param[in] checkpoint_state The checkpoint state to save. - * \param[in] checkpoint_path Path to the checkpoint file. - * \param[in] include_optimizer_state Flag to indicate whether to save the optimizer state or not. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(SaveCheckpoint, _In_ OrtCheckpointState* checkpoint_state, _In_ const ORTCHAR_T* checkpoint_path, - const bool include_optimizer_state); - - /// @} - - /// \name Implementing The Training Loop - /// @{ - /** \brief Create a training session that can be used to begin or resume training. - * - * This function creates a training session based on the env and session options provided that can - * begin or resume training from a given checkpoint state for the given onnx models. - * The checkpoint state represents the parameters of the training session which will be moved - * to the device specified by the user through the session options (if necessary). - * The training session requires four training artifacts - * - The training onnx model - * - The evaluation onnx model (optional) - * - The optimizer onnx model - * - The checkpoint file - * - * These artifacts can be generated using the `onnxruntime-training` python [utility](https://github.com/microsoft/onnxruntime/blob/main/orttraining/orttraining/python/training/onnxblock/README.md). - * - * \param[in] env Environment to be used for the training session. - * \param[in] options Session options that the user can customize for this training session. - * \param[in] checkpoint_state Training states that the training session uses as a starting point for training. - * \param[in] train_model_path Model to be used to perform training. - * \param[in] eval_model_path Model to be used to perform evaluation. - * \param[in] optimizer_model_path Model to be used to perform gradient descent. - * \param[out] out Created training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(CreateTrainingSession, _In_ const OrtEnv* env, _In_ const OrtSessionOptions* options, - _Inout_ OrtCheckpointState* checkpoint_state, _In_ const ORTCHAR_T* train_model_path, - _In_ const ORTCHAR_T* eval_model_path, _In_ const ORTCHAR_T* optimizer_model_path, - _Outptr_result_maybenull_ OrtTrainingSession** out); - - /** \brief Create a training session that can be used to begin or resume training. - * This api provides a way to load all the training artifacts from buffers instead of files. - * - * \param[in] env Environment to be used for the training session. - * \param[in] options Session options that the user can customize for this training session. - * \param[in] checkpoint_state Training states that the training session uses as a starting point for training. - * \param[in] train_model_data Buffer containing the model data to be used to perform training - * \param[in] train_data_length Length of the buffer containing train_model_data - * \param[in] eval_model_data Buffer containing the model data to be used to perform evaluation - * \param[in] eval_data_length Length of the buffer containing eval_model_data - * \param[in] optim_model_data Buffer containing the model data to be used to perform weight update - * \param[in] optim_data_length Length of the buffer containing optim_model_data - * \param[out] out Created training session. - * - */ - ORT_API2_STATUS(CreateTrainingSessionFromBuffer, _In_ const OrtEnv* env, - _In_ const OrtSessionOptions* options, _Inout_ OrtCheckpointState* checkpoint_state, - _In_ const void* train_model_data, size_t train_data_length, - _In_ const void* eval_model_data, size_t eval_data_length, - _In_ const void* optim_model_data, size_t optim_data_length, - _Outptr_result_maybenull_ OrtTrainingSession** out); - - /// @} - - /// \name Model IO Information - /// @{ - - /** \brief Retrieves the number of user outputs in the training model. - * - * This function returns the number of outputs of the training model so that the user can - * allocate space for the number of outputs when OrtTrainingApi::TrainStep is invoked. - * - * \param[in] sess The `this` pointer to the training session. - * \param[out] out Number of user outputs in the training model. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetTrainingModelOutputCount, _In_ const OrtTrainingSession* sess, _Out_ size_t* out); - - /** \brief Retrieves the number of user outputs in the eval model. - * - * This function returns the number of outputs of the eval model so that the user can - * allocate space for the number of outputs when OrtTrainingApi::EvalStep is invoked. - * - * \param[in] sess The `this` pointer to the training session. - * \param[out] out Number of user outputs in the eval model. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetEvalModelOutputCount, _In_ const OrtTrainingSession* sess, _Out_ size_t* out); - - /** \brief Retrieves the names of user outputs in the training model. - * - * This function returns the names of outputs of the training model that can be associated with the OrtValue(s) - * returned by the OrtTrainingApi::TrainStep function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] index Index of the output name requested. - * \param[in] allocator Allocator to use to allocate the memory for the name. - * \param[out] output Name of the training model output at the given index. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetTrainingModelOutputName, _In_ const OrtTrainingSession* sess, size_t index, _Inout_ OrtAllocator* allocator, _Outptr_ char** output); - - /** \brief Retrieves the names of user outputs in the eval model. - * - * This function returns the names of outputs of the eval model that can be associated with the OrtValue(s) returned - * by the OrtTrainingApi::EvalStep function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] index Index of the output name requested. - * \param[in] allocator Allocator to use to allocate the memory for the name. - * \param[out] output Name of the eval model output at the given index. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetEvalModelOutputName, _In_ const OrtTrainingSession* sess, size_t index, _Inout_ OrtAllocator* allocator, _Outptr_ char** output); - - /// @} - - /// \name Implementing The Training Loop - /// @{ - - /** \brief Reset the gradients of all trainable parameters to zero lazily. - * - * This function sets the internal state of the training session such that the gradients of the trainable - * parameters in the OrtCheckpointState will be scheduled to be reset just before the new gradients are - * computed on the next invocation of the next OrtTrainingApi::TrainStep. - * - * \param[in] session The `this` pointer to the training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(LazyResetGrad, _Inout_ OrtTrainingSession* session); - - /** \brief Computes the outputs of the training model and the gradients of the trainable parameters for the given inputs - * - * This function performs a training step that computes the outputs of the training model and the gradients - * of the trainable parameters for the given inputs. The train step is performed based on the training model - * that was provided to the training session. - * The OrtTrainingApi::TrainStep is equivalent of running forward propagation and backward propagation in a single - * step. - * The gradients computed are stored inside the training session state so they can be later consumed - * by the OrtTrainingApi::OptimizerStep function. - * The gradients can be lazily reset by invoking the OrtTrainingApi::LazyResetGrad function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] run_options Run options for this training step. - * \param[in] inputs_len Number of user inputs to the training model. - * \param[in] inputs The user inputs to the training model. - * \param[in] outputs_len Number of user outputs expected from this training step. - * \param[out] outputs User outputs computed by train step. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainStep, _Inout_ OrtTrainingSession* sess, _In_opt_ const OrtRunOptions* run_options, - _In_ size_t inputs_len, _In_reads_(inputs_len) const OrtValue* const* inputs, - _In_ size_t outputs_len, _Inout_updates_all_(outputs_len) OrtValue** outputs); - - /** \brief Computes the outputs for the eval model for the given inputs - * - * This function performs an eval step that computes the outputs of the eval model for the given inputs. - * The eval step is performed based on the eval model that was provided to the training session. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] run_options Run options for this eval step. - * \param[in] inputs_len Number of user inputs to the eval model. - * \param[in] inputs The user inputs to the eval model. - * \param[in] outputs_len Number of user outputs expected from this eval step. - * \param[out] outputs User outputs computed by eval step. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(EvalStep, _In_ const OrtTrainingSession* sess, _In_opt_ const OrtRunOptions* run_options, - _In_ size_t inputs_len, _In_reads_(inputs_len) const OrtValue* const* inputs, - _In_ size_t outputs_len, _Inout_updates_all_(outputs_len) OrtValue** outputs); - - /** \brief Sets the learning rate for this training session. - * - * This function allows users to set the learning rate for the training session. The current - * learning rate is maintained by the training session and can be overwritten by invoking - * this function with the desired learning rate. This function should not be used when a valid - * learning rate scheduler is registered. It should be used either to set the learning rate - * derived from a custom learning rate scheduler or to set a constant learning rate to be used - * throughout the training session. - * \note Please note that this function does not set the initial learning rate that may be needed - * by the predefined learning rate schedulers. To set the initial learning rate for learning - * rate schedulers, please look at the function OrtTrainingApi::RegisterLinearLRScheduler. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] learning_rate Desired learning rate to be set. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(SetLearningRate, _Inout_ OrtTrainingSession* sess, _In_ float learning_rate); - - /** \brief Gets the current learning rate for this training session. - * - * This function allows users to get the learning rate for the training session. The current - * learning rate is maintained by the training session, and users can query it for the purpose - * of implementing their own learning rate schedulers. - * - * \param[in] sess The `this` pointer to the training session. - * \param[out] learning_rate Learning rate currently in use by the training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(GetLearningRate, _Inout_ OrtTrainingSession* sess, _Out_ float* learning_rate); - - /** \brief Performs the weight updates for the trainable parameters using the optimizer model. - * - * This function performs the weight update step that updates the trainable parameters such that they - * take a step in the direction of their gradients (gradient descent). The optimizer step is performed - * based on the optimizer model that was provided to the training session. - * The updated parameters are stored inside the training state so that they can be used by the next - * OrtTrainingApi::TrainStep function call. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] run_options Run options for this optimizer step. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(OptimizerStep, _Inout_ OrtTrainingSession* sess, - _In_opt_ const OrtRunOptions* run_options); - - /** \brief Registers a linear learning rate scheduler for the training session. - * - * Register a linear learning rate scheduler that decays the learning rate by linearly updated - * multiplicative factor from the initial learning rate set on the training session to 0. The decay - * is performed after the initial warm up phase where the learning rate is linearly incremented - * from 0 to the initial learning rate provided. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] warmup_step_count Warmup steps for LR warmup. - * \param[in] total_step_count Total step count. - * \param[in] initial_lr The initial learning rate to be used by the training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(RegisterLinearLRScheduler, _Inout_ OrtTrainingSession* sess, _In_ const int64_t warmup_step_count, - _In_ const int64_t total_step_count, _In_ const float initial_lr); - - /** \brief Update the learning rate based on the registered learing rate scheduler. - * - * Takes a scheduler step that updates the learning rate that is being used by the training session. - * This function should typically be called before invoking the optimizer step for each round, - * or as determined necessary to update the learning rate being used by the training session. - * \note Please note that a valid predefined learning rate scheduler must be first registered to invoke this - * function. - * - * \param[in] sess The `this` pointer to the training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(SchedulerStep, _Inout_ OrtTrainingSession* sess); - - /// @} - - /// \name Accessing The Training Session State - /// @{ - /** \brief Retrieves the size of all the parameters. - * - * Calculates the total number of primitive (datatype of the parameters) elements of all the parameters in the - * training state. - * When trainable_only argument is true, the size is calculated for trainable params only. - * - * \param[in] sess The `this` pointer to the training session. - * \param[out] out Size of all parameter elements. - * \param[in] trainable_only Whether to skip non-trainable parameters - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(GetParametersSize, _Inout_ OrtTrainingSession* sess, _Out_ size_t* out, bool trainable_only); - - /** \brief Copy all parameters to a contiguous buffer held by the argument parameters_buffer - * - * The parameters_buffer has to be of the size given by GetParametersSize api call, - * with matching setting for the argument trainable_only. All the target parameters must be of the same - * datatype. The OrtValue must be pre-allocated onto - * the desired device. This is a complementary function to OrtTrainingApi::CopyBufferToParameters. - * Parameter ordering is preserved. - * User is responsible for allocating and freeing the resources used by the parameters_buffer. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] trainable_only Whether to skip non-trainable parameters - * \param[out] parameters_buffer The pre-allocated OrtValue buffer to copy onto. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(CopyParametersToBuffer, _Inout_ OrtTrainingSession* sess, - _Inout_ OrtValue* parameters_buffer, bool trainable_only); - - /** \brief Copy parameter values from the given contiguous buffer held by parameters_buffer to the training state - * - * The parameters_buffer argument has to be of the size given by OrtTrainingApi::GetParametersSize api call, - * with matching setting for trainable_only argument. All the target parameters must be of the same - * datatype. This is a complementary function to OrtTrainingApi::CopyParametersToBuffer - * and can be used to load updated buffer values onto the training state. - * Parameter ordering is preserved. - * User is responsible for allocating and freeing the resources used by the parameters_buffer. - * In case the training session was created with a nominal checkpoint, invoking this function is required - * to load the updated parameters onto the checkpoint to complete it. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] trainable_only Whether to skip non-trainable parameters - * \param[out] parameters_buffer The pre-allocated OrtValue buffer to copy from. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(CopyBufferToParameters, _Inout_ OrtTrainingSession* sess, - _Inout_ OrtValue* parameters_buffer, bool trainable_only); - - /// @} - - /// \name Release Training Resources - /// @{ - - /** \brief Frees up the memory used up by the training session. - * - * This function frees up any memory that was allocated in the training session. The training - * session can no longer be used after this call. - * - */ - ORT_CLASS_RELEASE(TrainingSession); - - /** \brief Frees up the memory used up by the checkpoint state. - * - * This function frees up any memory that was allocated in the checkpoint state. The checkpoint - * state can no longer be used after this call. - * \note Note that the checkpoint state must be released only after the training session has been released. - * - */ - ORT_CLASS_RELEASE(CheckpointState); - - /// @} - - /// \name Prepare For Inferencing - /// @{ - /** \brief Export a model that can be used for inferencing. - * - * If the training session was provided with an eval model, the training session can generate - * an inference model if it knows the inference graph outputs. The input inference graph outputs - * are used to prune the eval model so that the inference model's outputs align with the provided outputs. - * The exported model is saved at the path provided and can be used for inferencing with InferenceSession. - * \note Note that the function re-loads the eval model from the path provided to OrtTrainingApi::CreateTrainingSession - * and expects that this path still be valid. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] inference_model_path Path where the inference model should be serialized to. - * \param[in] graph_outputs_len Size of the graph output names array. - * \param[in] graph_output_names Names of the outputs that are needed in the inference model. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(ExportModelForInferencing, _Inout_ OrtTrainingSession* sess, - _In_ const ORTCHAR_T* inference_model_path, size_t graph_outputs_len, - _In_reads_(graph_outputs_len) const char* const* graph_output_names); - - /// @} - - /// \name Training Utilities - /// @{ - /** \brief Sets the seed used for random number generation in Onnxruntime. - * - * Use this function to generate reproducible results. It should be noted that completely reproducible - * results are not guaranteed. - * - * \param[in] seed The seed to be set. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(SetSeed, _In_ const int64_t seed); - - /// @} - - /// \name Model IO Information - /// @{ - /** \brief Retrieves the number of user inputs in the training model. - * - * This function returns the number of inputs of the training model so that the user can accordingly - * allocate the OrtValue(s) provided to the OrtTrainingApi::TrainStep function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[out] out Number of user inputs in the training model. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetTrainingModelInputCount, _In_ const OrtTrainingSession* sess, _Out_ size_t* out); - - /** \brief Retrieves the number of user inputs in the eval model. - * - * This function returns the number of inputs of the eval model so that the user can accordingly - * allocate the OrtValue(s) provided to the OrtTrainingApi::EvalStep function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[out] out Number of user inputs in the eval model. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetEvalModelInputCount, _In_ const OrtTrainingSession* sess, _Out_ size_t* out); - - /** \brief Retrieves the name of the user input at given index in the training model. - * - * This function returns the names of inputs of the training model that can be associated with the - * OrtValue(s) provided to the OrtTrainingApi::TrainStep function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] index The index of the training model input name requested. - * \param[in] allocator The allocator to use to allocate the memory for the requested name. - * \param[out] output Name of the user input for the training model at the given index. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetTrainingModelInputName, _In_ const OrtTrainingSession* sess, size_t index, - _In_ OrtAllocator* allocator, _Outptr_ char** output); - - /** \brief Retrieves the name of the user input at given index in the eval model. - * - * This function returns the names of inputs of the eval model that can be associated with the OrtValue(s) provided - * to the OrtTrainingApi::EvalStep function. - * - * \param[in] sess The `this` pointer to the training session. - * \param[in] index The index of the eval model input name requested. - * \param[in] allocator The allocator to use to allocate the memory for the requested name. - * \param[out] output Name of the user input for the eval model at the given index. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(TrainingSessionGetEvalModelInputName, _In_ const OrtTrainingSession* sess, size_t index, - _In_ OrtAllocator* allocator, _Outptr_ char** output); - - /// @} - - /// \name Accessing The Training Session State - /// @{ - - /** \brief Adds or updates the given property to/in the checkpoint state. - * - * Runtime properties such as epoch, training step, best score, and others can be added to the checkpoint - * state by the user by calling this function with the corresponding property name and value. - * The given property name must be unique to be able to successfully add the property. - * - * \param[in] checkpoint_state The checkpoint state which should hold the property. - * \param[in] property_name Name of the property being added or updated. - * \param[in] property_type Type of the property associated with the given name. - * \param[in] property_value Property value associated with the given name. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(AddProperty, _Inout_ OrtCheckpointState* checkpoint_state, - _In_ const char* property_name, _In_ enum OrtPropertyType property_type, - _In_ void* property_value); - - /** \brief Gets the property value associated with the given name from the checkpoint state. - * - * Gets the property value from an existing entry in the checkpoint state. The property must - * exist in the checkpoint state to be able to retrieve it successfully. - * - * \param[in] checkpoint_state The checkpoint state that is currently holding the property. - * \param[in] property_name Name of the property being retrieved. - * \param[in] allocator Allocator used to allocate the memory for the property_value. - * \param[out] property_type Type of the property associated with the given name. - * \param[out] property_value Property value associated with the given name. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(GetProperty, _In_ const OrtCheckpointState* checkpoint_state, - _In_ const char* property_name, _Inout_ OrtAllocator* allocator, - _Out_ enum OrtPropertyType* property_type, _Outptr_ void** property_value); - - /// @} - - /// \name Accessing The Training Session State - /// @{ - - /** \brief Load a checkpoint state from a buffer into checkpoint_state. - * - * This function will parse a checkpoint bytes buffer, pull relevant data and load the training - * state into the checkpoint_state. This checkpoint state can then be used to create the - * training session by invoking OrtTrainingApi::CreateTrainingSession. By doing so, the training - * session will resume training from the given checkpoint state. - * \note Note that the training session created with a checkpoint state uses this state to store the entire - * training state (including model parameters, its gradients, the optimizer states and the properties). - * As a result, it is required that the checkpoint state outlive the lifetime of the training session. - * - * \param[in] checkpoint_buffer Path to the checkpoint bytes buffer. - * \param[in] num_bytes Number of bytes in the checkpoint buffer. - * \param[out] checkpoint_state Checkpoint state that contains the states of the training session. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(LoadCheckpointFromBuffer, _In_ const void* checkpoint_buffer, - _In_ const size_t num_bytes, _Outptr_ OrtCheckpointState** checkpoint_state); - - /** \brief Retrieves the type and shape information of the parameter associated with the given parameter name. - * - * This function retrieves the type and shape of the parameter associated with the given parameter name. - * The parameter must exist in the checkpoint state to be able to retrieve its type and shape information successfully. - * - * \param[in] checkpoint_state The checkpoint state. - * \param[in] parameter_name Name of the parameter being retrieved. - * \param[out] parameter_type_and_shape The type and shape of the parameter being retrieved. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(GetParameterTypeAndShape, _In_ const OrtCheckpointState* checkpoint_state, - _In_ const char* parameter_name, _Outptr_ OrtTensorTypeAndShapeInfo** parameter_type_and_shape); - - /** \brief Updates the data associated with the model parameter in the checkpoint state for the given parameter name. - * - * This function updates a model parameter in the checkpoint state with the given parameter data. - * The training session must be already created with the checkpoint state that contains the parameter - * being updated. The given parameter is copied over to the registered device for the training session. - * The parameter must exist in the checkpoint state to be able to update it successfully. - * - * \param[in] checkpoint_state The checkpoint state. - * \param[in] parameter_name Name of the parameter being updated. - * \param[in] parameter The parameter data that should replace the existing parameter data. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(UpdateParameter, _Inout_ OrtCheckpointState* checkpoint_state, - _In_ const char* parameter_name, _In_ OrtValue* parameter); - - /** \brief Gets the data associated with the model parameter from the checkpoint state for the given parameter name. - * - * This function retrieves the model parameter data from the checkpoint state for the given parameter name. - * The parameter is copied over and returned as an OrtValue. The training session must be already created - * with the checkpoint state that contains the parameter being retrieved. - * The parameter must exist in the checkpoint state to be able to retrieve it successfully. - * - * \param[in] checkpoint_state The checkpoint state. - * \param[in] parameter_name Name of the parameter being retrieved. - * \param[in] allocator Allocator used to allocate the memory for the parameter. - * \param[out] parameter The parameter data that is retrieved from the checkpoint state. - * - * \snippet{doc} snippets.dox OrtStatus Return Value - * - */ - ORT_API2_STATUS(GetParameter, _In_ const OrtCheckpointState* checkpoint_state, - _In_ const char* parameter_name, _Inout_ OrtAllocator* allocator, - _Outptr_ OrtValue** parameter); - - /// @} -}; - -typedef struct OrtTrainingApi OrtTrainingApi; - -/// @} diff --git a/onnxruntime/include/onnxruntime_training_cxx_api.h b/onnxruntime/include/onnxruntime_training_cxx_api.h deleted file mode 100644 index e78c1613..00000000 --- a/onnxruntime/include/onnxruntime_training_cxx_api.h +++ /dev/null @@ -1,418 +0,0 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. -// Licensed under the MIT License. - -#pragma once -#include "onnxruntime_training_c_api.h" -#include -#include - -namespace Ort::detail { - -#define ORT_DECLARE_TRAINING_RELEASE(NAME) \ - void OrtRelease(Ort##NAME* ptr); - -// These release methods must be forward declared before including onnxruntime_cxx_api.h -// otherwise class Base won't be aware of them -ORT_DECLARE_TRAINING_RELEASE(CheckpointState); -ORT_DECLARE_TRAINING_RELEASE(TrainingSession); - -} // namespace Ort::detail - -#include "onnxruntime_cxx_api.h" - -namespace Ort { - -/// -/// This function returns the C training api struct with the pointers to the ort training C functions. -/// If using C++, please use the class instances instead of invoking the C functions directly. -/// -/// OrtTrainingApi struct with ort training C function pointers. -inline const OrtTrainingApi& GetTrainingApi() { return *GetApi().GetTrainingApi(ORT_API_VERSION); } - -namespace detail { - -#define ORT_DEFINE_TRAINING_RELEASE(NAME) \ - inline void OrtRelease(Ort##NAME* ptr) { GetTrainingApi().Release##NAME(ptr); } - -ORT_DEFINE_TRAINING_RELEASE(CheckpointState); -ORT_DEFINE_TRAINING_RELEASE(TrainingSession); - -#undef ORT_DECLARE_TRAINING_RELEASE -#undef ORT_DEFINE_TRAINING_RELEASE - -} // namespace detail - -using Property = std::variant; - -/** - * \defgroup TrainingCpp Ort Training C++ API - * @{ - */ - -/** \brief Holds the state of the training session. - * - * This class holds the entire training session state that includes model parameters, their gradients, - * optimizer parameters, and user properties. The Ort::TrainingSession leverages the Ort::CheckpointState - * by accessing and updating the contained training state. - * \note Note that the training session created with a checkpoint state uses this state to store the entire - * training state (including model parameters, its gradients, the optimizer states and the properties). - * The Ort::TrainingSession does not hold a copy of the Ort::CheckpointState and as a result, it is required - * that the checkpoint state outlive the lifetime of the training session. - * \note Note that the checkpoint state can be either the complete checkpoint state or the nominal checkpoint - * state depending on the version provided while loading the checkpoint. - * - */ -class CheckpointState : public detail::Base { - private: - CheckpointState(OrtCheckpointState* checkpoint_state) { p_ = checkpoint_state; } - - public: - // Construct the checkpoint state by loading the checkpoint by calling LoadCheckpoint - CheckpointState() = delete; - - /// \name Accessing The Training Session State - /// @{ - - /** \brief Load a checkpoint state from a file on disk into checkpoint_state. - * - * This function will parse a checkpoint file, pull relevant data and load the training - * state and return an instance of Ort::CheckpointState. This checkpoint state can then be used to create the - * training session by instantiating Ort::TrainingSession. By doing so, the training session will resume - * training from the given checkpoint state. - * - * \param[in] path_to_checkpoint Path to the checkpoint file - * \return Ort::CheckpointState object which holds the state of the training session parameters. - * - */ - static CheckpointState LoadCheckpoint(const std::basic_string& path_to_checkpoint); - - /** \brief Load a checkpoint state from a buffer. - * - * This function will parse a checkpoint buffer, pull relevant data and load the training - * state and return an instance of Ort::CheckpointState. This checkpoint state can then be used to create the - * training session by instantiating Ort::TrainingSession. By doing so, the training session will resume - * training from the given checkpoint state. - * - * \param[in] buffer Buffer containing the checkpoint data. - * \return Ort::CheckpointState object which holds the state of the training session parameters. - * - */ - static CheckpointState LoadCheckpointFromBuffer(const std::vector& buffer); - - /** \brief Save the given state to a checkpoint file on disk. - * - * This function serializes the provided checkpoint state to a file on disk. - * This checkpoint can later be loaded by invoking Ort::CheckpointState::LoadCheckpoint to resume - * training from this snapshot of the state. - * - * \param[in] checkpoint_state The checkpoint state to save. - * \param[in] path_to_checkpoint Path to the checkpoint file. - * \param[in] include_optimizer_state Flag to indicate whether to save the optimizer state or not. - * - */ - static void SaveCheckpoint(const CheckpointState& checkpoint_state, - const std::basic_string& path_to_checkpoint, - const bool include_optimizer_state = false); - - /** \brief Adds or updates the given property to/in the checkpoint state. - * - * Runtime properties such as epoch, training step, best score, and others can be added to the checkpoint - * state by the user by calling this function with the corresponding property name and value. - * The given property name must be unique to be able to successfully add the property. - * - * \param[in] property_name Name of the property being added or updated. - * \param[in] property_value Property value associated with the given name. - * - */ - void AddProperty(const std::string& property_name, const Property& property_value); - - /** \brief Gets the property value associated with the given name from the checkpoint state. - * - * Gets the property value from an existing entry in the checkpoint state. The property must - * exist in the checkpoint state to be able to retrieve it successfully. - * - * \param[in] property_name Name of the property being retrieved. - * \return Property value associated with the given property name. - * - */ - Property GetProperty(const std::string& property_name); - - /** \brief Updates the data associated with the model parameter in the checkpoint state for the given parameter name. - * - * This function updates a model parameter in the checkpoint state with the given parameter data. - * The training session must be already created with the checkpoint state that contains the parameter - * being updated. The given parameter is copied over to the registered device for the training session. - * The parameter must exist in the checkpoint state to be able to update it successfully. - * - * \param[in] parameter_name Name of the parameter being updated. - * \param[in] parameter The parameter data that should replace the existing parameter data. - * - */ - void UpdateParameter(const std::string& parameter_name, const Value& parameter); - - /** \brief Gets the data associated with the model parameter from the checkpoint state for the given parameter name. - * - * This function retrieves the model parameter data from the checkpoint state for the given parameter name. - * The parameter is copied over to the provided OrtValue. The training session must be already created - * with the checkpoint state that contains the parameter being retrieved. - * The parameter must exist in the checkpoint state to be able to retrieve it successfully. - * - * \param[in] parameter_name Name of the parameter being retrieved. - * \return The parameter data that is retrieved from the checkpoint state. - * - */ - Value GetParameter(const std::string& parameter_name); - - /// @} -}; - -/** \brief Trainer class that provides training, evaluation and optimizer methods for training an ONNX models. - * - * The training session requires four training artifacts - * - The training onnx model - * - The evaluation onnx model (optional) - * - The optimizer onnx model - * - The checkpoint file - * - * These artifacts can be generated using the `onnxruntime-training` python [utility](https://github.com/microsoft/onnxruntime/blob/main/orttraining/orttraining/python/training/onnxblock/README.md). - * - */ -class TrainingSession : public detail::Base { - private: - size_t training_model_output_count_, eval_model_output_count_; - - public: - /// \name Constructing the Training Session - /// @{ - /** \brief Create a training session that can be used to begin or resume training. - * - * This constructor instantiates the training session based on the env and session options provided that can - * begin or resume training from a given checkpoint state for the given onnx models. - * The checkpoint state represents the parameters of the training session which will be moved - * to the device specified by the user through the session options (if necessary). - * - * \param[in] env Env to be used for the training session. - * \param[in] session_options SessionOptions that the user can customize for this training session. - * \param[in] checkpoint_state Training states that the training session uses as a starting point for training. - * \param[in] train_model_path Model to be used to perform training. - * \param[in] eval_model_path Model to be used to perform evaluation. - * \param[in] optimizer_model_path Model to be used to perform gradient descent. - * - */ - TrainingSession(const Env& env, const SessionOptions& session_options, CheckpointState& checkpoint_state, - const std::basic_string& train_model_path, - const std::optional>& eval_model_path = std::nullopt, - const std::optional>& optimizer_model_path = std::nullopt); - - /** \brief Create a training session that can be used to begin or resume training. - * This constructor allows the users to load the models from buffers instead of files. - * - * \param[in] env Env to be used for the training session. - * \param[in] session_options SessionOptions that the user can customize for this training session. - * \param[in] checkpoint_state Training states that the training session uses as a starting point for training. - * \param[in] train_model_data Buffer containing training model data. - * \param[in] eval_model_data Buffer containing evaluation model data. - * \param[in] optim_model_data Buffer containing optimizer model (used for performing weight/parameter update). - * - */ - TrainingSession(const Env& env, const SessionOptions& session_options, CheckpointState& checkpoint_state, - const std::vector& train_model_data, const std::vector& eval_model_data = {}, - const std::vector& optim_model_data = {}); - /// @} - - /// \name Implementing The Training Loop - /// @{ - /** \brief Computes the outputs of the training model and the gradients of the trainable parameters for the given inputs - * - * This function performs a training step that computes the outputs of the training model and the gradients - * of the trainable parameters for the given inputs. The train step is performed based on the training model - * that was provided to the training session. - * The Ort::TrainingSession::TrainStep is equivalent of running forward propagation and backward propagation in a single - * step. - * The gradients computed are stored inside the training session state so they can be later consumed - * by the Ort::TrainingSession::OptimizerStep function. - * The gradients can be lazily reset by invoking the Ort::TrainingSession::LazyResetGrad function. - * - * \param[in] input_values The user inputs to the training model. - * \return A std::vector of Ort::Value objects that represents the output of the forward pass of the training model. - * - * - */ - std::vector TrainStep(const std::vector& input_values); - - /** \brief Reset the gradients of all trainable parameters to zero lazily. - * - * This function sets the internal state of the training session such that the gradients of the trainable - * parameters in the OrtCheckpointState will be scheduled to be reset just before the new gradients are - * computed on the next invocation of the next Ort::TrainingSession::TrainStep. - * - */ - void LazyResetGrad(); - - /** \brief Computes the outputs for the eval model for the given inputs - * - * This function performs an eval step that computes the outputs of the eval model for the given inputs. - * The eval step is performed based on the eval model that was provided to the training session. - * - * \param[in] input_values The user inputs to the eval model. - * \return A std::vector of Ort::Value objects that represents the output of the eval pass. - * - */ - std::vector EvalStep(const std::vector& input_values); - - /** \brief Sets the learning rate for this training session. - * - * This function allows users to set the learning rate for the training session. The current - * learning rate is maintained by the training session and can be overwritten by invoking - * this function with the desired learning rate. This function should not be used when a valid - * learning rate scheduler is registered. It should be used either to set the learning rate - * derived from a custom learning rate scheduler or to set a constant learning rate to be used - * throughout the training session. - * \note Please note that this function does not set the initial learning rate that may be needed - * by the predefined learning rate schedulers. To set the initial learning rate for learning - * rate schedulers, please look at the function Ort::TrainingSession::RegisterLinearLRScheduler. - * - * \param[in] learning_rate Desired learning rate to be set. - * - */ - void SetLearningRate(float learning_rate); - - /** \brief Gets the current learning rate for this training session. - * - * This function allows users to get the learning rate for the training session. The current - * learning rate is maintained by the training session, and users can query it for the purpose - * of implementing their own learning rate schedulers. - * - * \return float representing the current learning rate. - * - */ - float GetLearningRate() const; - - /** \brief Registers a linear learning rate scheduler for the training session. - * - * Register a linear learning rate scheduler that decays the learning rate by linearly updated - * multiplicative factor from the initial learning rate set on the training session to 0. The decay - * is performed after the initial warm up phase where the learning rate is linearly incremented - * from 0 to the initial learning rate provided. - * - * \param[in] warmup_step_count Warmup steps for LR warmup. - * \param[in] total_step_count Total step count. - * \param[in] initial_lr The initial learning rate to be used by the training session. - * - */ - void RegisterLinearLRScheduler(int64_t warmup_step_count, int64_t total_step_count, - float initial_lr); - - /** \brief Update the learning rate based on the registered learing rate scheduler. - * - * Takes a scheduler step that updates the learning rate that is being used by the training session. - * This function should typically be called before invoking the optimizer step for each round, - * or as determined necessary to update the learning rate being used by the training session. - * \note Please note that a valid predefined learning rate scheduler must be first registered to invoke this - * function. - * - */ - void SchedulerStep(); - - /** \brief Performs the weight updates for the trainable parameters using the optimizer model. - * - * This function performs the weight update step that updates the trainable parameters such that they - * take a step in the direction of their gradients (gradient descent). The optimizer step is performed - * based on the optimizer model that was provided to the training session. - * The updated parameters are stored inside the training state so that they can be used by the next - * Ort::TrainingSession::TrainStep function call. - * - */ - void OptimizerStep(); - - /// @} - - /// \name Prepare For Inferencing - /// @{ - - /** \brief Export a model that can be used for inferencing. - * - * If the training session was provided with an eval model, the training session can generate - * an inference model if it knows the inference graph outputs. The input inference graph outputs - * are used to prune the eval model so that the inference model's outputs align with the provided outputs. - * The exported model is saved at the path provided and can be used for inferencing with Ort::Session. - * \note Note that the function re-loads the eval model from the path provided to Ort::TrainingSession - * and expects that this path still be valid. - * - * \param[in] inference_model_path Path where the inference model should be serialized to. - * \param[in] graph_output_names Names of the outputs that are needed in the inference model. - * - */ - void ExportModelForInferencing(const std::basic_string& inference_model_path, - const std::vector& graph_output_names); - - /// @} - - /// \name Model IO Information - /// @{ - /** \brief Retrieves the names of the user inputs for the training and eval models. - * - * This function returns the names of inputs of the training or eval model that can be associated - * with the Ort::Value(s) provided to the Ort::TrainingSession::TrainStep or Ort::TrainingSession::EvalStep - * function. - * - * \param[in] training Whether the training model input names are requested or eval model input names. - * \return Graph input names for either the training model or the eval model. - * - */ - std::vector InputNames(const bool training); - - /** \brief Retrieves the names of the user outputs for the training and eval models. - * - * This function returns the names of outputs of the training or eval model that can be associated - * with the Ort::Value(s) returned by the Ort::TrainingSession::TrainStep or Ort::TrainingSession::EvalStep - * function. - * - * \param[in] training Whether the training model output names are requested or eval model output names. - * \return Graph output names for either the training model or the eval model. - * - */ - std::vector OutputNames(const bool training); - - /// @} - - /// \name Accessing The Training Session State - /// @{ - - /** \brief Returns a contiguous buffer that holds a copy of all training state parameters - * - * \param[in] only_trainable Whether to only copy trainable parameters or to copy all parameters. - * \return Contiguous buffer to the model parameters. - * - */ - Value ToBuffer(const bool only_trainable); - - /** \brief Loads the training session model parameters from a contiguous buffer - * - * In case the training session was created with a nominal checkpoint, invoking this function is required - * to load the updated parameters onto the checkpoint to complete it. - * - * \param[in] buffer Contiguous buffer to load the parameters from. - */ - void FromBuffer(Value& buffer); - - /// @} -}; - -/// \name Training Utilities -/// @{ -/** \brief This function sets the seed for generating random numbers. - * - * Use this function to generate reproducible results. It should be noted that completely - * reproducible results are not guaranteed. - * - * \param[in] seed Manual seed to use for random number generation. - */ -void SetSeed(const int64_t seed); -/// @} - -/// @} - -} // namespace Ort - -#include "onnxruntime_training_cxx_inline.h" diff --git a/onnxruntime/include/onnxruntime_training_cxx_inline.h b/onnxruntime/include/onnxruntime_training_cxx_inline.h deleted file mode 100644 index 397cba0b..00000000 --- a/onnxruntime/include/onnxruntime_training_cxx_inline.h +++ /dev/null @@ -1,295 +0,0 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. -// Licensed under the MIT License. - -#pragma once -#include "onnxruntime_training_c_api.h" -#include "onnxruntime_cxx_api.h" - -namespace Ort { - -inline TrainingSession::TrainingSession(const Env& env, const SessionOptions& session_options, - CheckpointState& checkpoint_state, - const std::basic_string& train_model_path, - const std::optional>& eval_model_path, - const std::optional>& optimizer_model_path) { - ThrowOnError(GetTrainingApi().CreateTrainingSession( - env, session_options, checkpoint_state, - train_model_path.c_str(), - eval_model_path.has_value() ? eval_model_path.value().c_str() : nullptr, - optimizer_model_path.has_value() ? optimizer_model_path.value().c_str() : nullptr, - &p_)); - - ThrowOnError(GetTrainingApi().TrainingSessionGetTrainingModelOutputCount(p_, &training_model_output_count_)); - - ThrowOnError(GetTrainingApi().TrainingSessionGetEvalModelOutputCount(p_, &eval_model_output_count_)); -} - -inline TrainingSession::TrainingSession(const Env& env, const SessionOptions& session_options, - CheckpointState& checkpoint_state, - const std::vector& train_model_data, - const std::vector& eval_model_data, - const std::vector& optim_model_data) { - ThrowOnError(GetTrainingApi().CreateTrainingSessionFromBuffer( - env, session_options, checkpoint_state, - train_model_data.data(), train_model_data.size(), - eval_model_data.data(), eval_model_data.size(), - optim_model_data.data(), optim_model_data.size(), - &p_)); - - ThrowOnError(GetTrainingApi().TrainingSessionGetTrainingModelOutputCount(p_, &training_model_output_count_)); - - ThrowOnError(GetTrainingApi().TrainingSessionGetEvalModelOutputCount(p_, &eval_model_output_count_)); -} - -inline std::vector TrainingSession::TrainStep(const std::vector& input_values) { - std::vector output_values; - output_values.reserve(training_model_output_count_); - for (size_t i = 0; i < training_model_output_count_; i++) output_values.emplace_back(nullptr); - auto ort_input_values = reinterpret_cast(input_values.data()); - auto ort_output_values = reinterpret_cast(output_values.data()); - RunOptions run_options; - ThrowOnError(GetTrainingApi().TrainStep( - p_, run_options, input_values.size(), ort_input_values, - training_model_output_count_, ort_output_values)); - - return output_values; -} - -inline void TrainingSession::LazyResetGrad() { - ThrowOnError(GetTrainingApi().LazyResetGrad(p_)); -} - -inline std::vector TrainingSession::EvalStep(const std::vector& input_values) { - std::vector output_values; - output_values.reserve(eval_model_output_count_); - for (size_t i = 0; i < eval_model_output_count_; i++) output_values.emplace_back(nullptr); - auto ort_input_values = reinterpret_cast(input_values.data()); - auto ort_output_values = reinterpret_cast(output_values.data()); - RunOptions run_options; - ThrowOnError(GetTrainingApi().EvalStep( - p_, run_options, input_values.size(), ort_input_values, - eval_model_output_count_, ort_output_values)); - - return output_values; -} - -inline void TrainingSession::SetLearningRate(float learning_rate) { - ThrowOnError(GetTrainingApi().SetLearningRate(p_, learning_rate)); -} - -inline float TrainingSession::GetLearningRate() const { - float learning_rate = 0; - ThrowOnError(GetTrainingApi().GetLearningRate(p_, &learning_rate)); - return learning_rate; -} - -inline void TrainingSession::RegisterLinearLRScheduler(int64_t warmup_step_count, int64_t total_step_count, - float initial_lr) { - ThrowOnError(GetTrainingApi().RegisterLinearLRScheduler(p_, warmup_step_count, total_step_count, - initial_lr)); -} - -inline void TrainingSession::SchedulerStep() { - ThrowOnError(GetTrainingApi().SchedulerStep(p_)); -} - -inline void TrainingSession::OptimizerStep() { - RunOptions run_options; - ThrowOnError(GetTrainingApi().OptimizerStep(p_, run_options)); -} - -inline std::vector TrainingSession::InputNames(const bool training) { - auto& input_count_function = training ? GetTrainingApi().TrainingSessionGetTrainingModelInputCount - : GetTrainingApi().TrainingSessionGetEvalModelInputCount; - auto& input_name_function = training ? GetTrainingApi().TrainingSessionGetTrainingModelInputName - : GetTrainingApi().TrainingSessionGetEvalModelInputName; - - size_t input_count = 0; - ThrowOnError(input_count_function(p_, &input_count)); - std::vector input_names(input_count); - AllocatorWithDefaultOptions allocator; - for (size_t index = 0; index < input_count; ++index) { - char* input_name; - ThrowOnError(input_name_function(p_, index, allocator, &input_name)); - input_names[index] = std::string(input_name); - allocator.Free(input_name); - } - - return input_names; -} - -inline std::vector TrainingSession::OutputNames(const bool training) { - auto& output_count_function = training ? GetTrainingApi().TrainingSessionGetTrainingModelOutputCount - : GetTrainingApi().TrainingSessionGetEvalModelOutputCount; - auto& output_name_function = training ? GetTrainingApi().TrainingSessionGetTrainingModelOutputName - : GetTrainingApi().TrainingSessionGetEvalModelOutputName; - - size_t output_count = 0; - ThrowOnError(output_count_function(p_, &output_count)); - std::vector output_names(output_count); - AllocatorWithDefaultOptions allocator; - for (size_t index = 0; index < output_count; ++index) { - char* output_name; - ThrowOnError(output_name_function(p_, index, allocator, &output_name)); - output_names[index] = std::string(output_name); - allocator.Free(output_name); - } - - return output_names; -} - -inline Value TrainingSession::ToBuffer(const bool only_trainable) { - size_t buffer_size = 0U; - ThrowOnError(GetTrainingApi().GetParametersSize(p_, &buffer_size, only_trainable)); - - std::array buffer_shape{static_cast(buffer_size)}; - - AllocatorWithDefaultOptions allocator; - Value buffer = Value::CreateTensor(allocator, buffer_shape.data(), 1U, - ONNXTensorElementDataType::ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT); - - ThrowOnError(GetTrainingApi().CopyParametersToBuffer(p_, buffer, only_trainable)); - - return buffer; -} - -inline void TrainingSession::FromBuffer(Value& buffer) { - if (!buffer.IsTensor()) { - ThrowStatus(Status("Incorrect buffer received. Expected a tensor buffer.", OrtErrorCode::ORT_INVALID_ARGUMENT)); - } - - auto tensor_info = buffer.GetTensorTypeAndShapeInfo(); - auto buffer_shape = tensor_info.GetShape(); - - if (buffer_shape.size() != 1U) { - ThrowStatus(Status("Incorrect buffer received. Expected a contiguous tensor buffer.", - OrtErrorCode::ORT_INVALID_ARGUMENT)); - } - - auto buffer_size = buffer_shape.front(); - - size_t session_buffer_size = 0U; - ThrowOnError(GetTrainingApi().GetParametersSize(p_, &session_buffer_size, false)); - - if (buffer_size == static_cast(session_buffer_size)) { - ThrowOnError(GetTrainingApi().CopyBufferToParameters(p_, buffer, false)); - return; - } - - size_t session_buffer_size_trainable_only = 0U; - ThrowOnError(GetTrainingApi().GetParametersSize(p_, &session_buffer_size_trainable_only, true)); - - if (buffer_size == static_cast(session_buffer_size_trainable_only)) { - ThrowOnError(GetTrainingApi().CopyBufferToParameters(p_, buffer, true)); - return; - } else { - ThrowStatus(Status("Incorrect buffer size received.", OrtErrorCode::ORT_INVALID_ARGUMENT)); - } -} - -inline CheckpointState CheckpointState::LoadCheckpoint(const std::basic_string& path_to_checkpoint) { - OrtCheckpointState* checkpoint_state; - ThrowOnError(GetTrainingApi().LoadCheckpoint(path_to_checkpoint.c_str(), &checkpoint_state)); - return CheckpointState(checkpoint_state); -} - -inline CheckpointState CheckpointState::LoadCheckpointFromBuffer(const std::vector& buffer) { - OrtCheckpointState* checkpoint_state; - ThrowOnError(GetTrainingApi().LoadCheckpointFromBuffer(buffer.data(), buffer.size(), &checkpoint_state)); - return CheckpointState(checkpoint_state); -} - -inline void CheckpointState::SaveCheckpoint(const CheckpointState& checkpoint_states, - const std::basic_string& path_to_checkpoint, - const bool include_optimizer_state) { - ThrowOnError(GetTrainingApi().SaveCheckpoint(checkpoint_states, path_to_checkpoint.c_str(), - include_optimizer_state)); -} - -inline void TrainingSession::ExportModelForInferencing(const std::basic_string& inference_model_path, - const std::vector& graph_output_names) { - std::vector output_names; - output_names.reserve(graph_output_names.size()); - for (const auto& output_name : graph_output_names) { - output_names.push_back(output_name.c_str()); - } - ThrowOnError(GetTrainingApi().ExportModelForInferencing( - p_, inference_model_path.c_str(), graph_output_names.size(), output_names.data())); -} - -inline void SetSeed(const int64_t seed) { - ThrowOnError(GetTrainingApi().SetSeed(seed)); -} - -inline void CheckpointState::AddProperty(const std::string& property_name, const Property& property_value) { - if (std::holds_alternative(property_value)) { - int64_t value = std::get(property_value); - void* value_p = &value; - ThrowOnError(GetTrainingApi().AddProperty(p_, property_name.c_str(), OrtPropertyType::OrtIntProperty, value_p)); - } else if (std::holds_alternative(property_value)) { - float value = std::get(property_value); - void* value_p = &value; - ThrowOnError(GetTrainingApi().AddProperty(p_, property_name.c_str(), OrtPropertyType::OrtFloatProperty, value_p)); - } else if (std::holds_alternative(property_value)) { - std::string value = std::get(property_value); - auto buffer = std::make_unique(value.length() + 1); - memcpy(buffer.get(), value.c_str(), value.length()); - // AddProperty takes a char* and calls PropertyBag::AddProperty which takes a std::string. The data will be - // copied at that point so buffer can free the local allocation once the call is made. - ThrowOnError(GetTrainingApi().AddProperty(p_, property_name.c_str(), OrtPropertyType::OrtStringProperty, - buffer.get())); - } else { - ThrowStatus(Status("Unknown property type received.", OrtErrorCode::ORT_INVALID_ARGUMENT)); - } -} - -inline Property CheckpointState::GetProperty(const std::string& property_name) { - void* property_value = nullptr; - OrtPropertyType property_type; - - AllocatorWithDefaultOptions allocator; - ThrowOnError(GetTrainingApi().GetProperty(p_, property_name.c_str(), allocator, &property_type, &property_value)); - - Property property; - - switch (property_type) { - case OrtPropertyType::OrtIntProperty: { - auto value_p = reinterpret_cast(property_value); - property = *value_p; - allocator.Free(property_value); - break; - } - case OrtPropertyType::OrtFloatProperty: { - auto value_p = reinterpret_cast(property_value); - property = *value_p; - allocator.Free(property_value); - break; - } - case OrtPropertyType::OrtStringProperty: { - auto value_p = reinterpret_cast(property_value); - property = std::string(value_p); - allocator.Free(property_value); - break; - } - default: { - ThrowStatus(Status("Unknown property type received.", OrtErrorCode::ORT_INVALID_ARGUMENT)); - break; - } - } - - return property; -} - -inline void CheckpointState::UpdateParameter(const std::string& parameter_name, const Value& parameter) { - ThrowOnError(GetTrainingApi().UpdateParameter(p_, parameter_name.c_str(), parameter)); -} - -inline Value CheckpointState::GetParameter(const std::string& parameter_name) { - AllocatorWithDefaultOptions allocator; - OrtValue* parameter; - ThrowOnError(GetTrainingApi().GetParameter(p_, parameter_name.c_str(), allocator, ¶meter)); - - return Value{parameter}; -} - -} // namespace Ort diff --git a/onnxruntime/runtime1.23.0_openvino2025.3.0.txt b/onnxruntime/runtime1.24.0_openvino2025.3.0.txt similarity index 100% rename from onnxruntime/runtime1.23.0_openvino2025.3.0.txt rename to onnxruntime/runtime1.24.0_openvino2025.3.0.txt diff --git a/opencv/x64/vc17/bin/opencv_img_hash4130.dll b/opencv/x64/vc17/bin/opencv_img_hash4130.dll new file mode 100644 index 00000000..681bf351 Binary files /dev/null and b/opencv/x64/vc17/bin/opencv_img_hash4130.dll differ diff --git a/opencv/x64/vc17/bin/opencv_videoio_ffmpeg4130_64.dll b/opencv/x64/vc17/bin/opencv_videoio_ffmpeg4130_64.dll new file mode 100644 index 00000000..afdb972f Binary files /dev/null and b/opencv/x64/vc17/bin/opencv_videoio_ffmpeg4130_64.dll differ diff --git a/opencv/x64/vc17/bin/opencv_world4130.dll b/opencv/x64/vc17/bin/opencv_world4130.dll new file mode 100644 index 00000000..1402fa3b Binary files /dev/null and b/opencv/x64/vc17/bin/opencv_world4130.dll differ