详细列出 drawtext 滤镜在 ffmpeg7.1.1 支持的参数列表

2025-07-04 18:21:18 5 分享链接 开发笔记 ffmpeg

以下是 FFmpeg 7.1.1 中 drawtext 滤镜支持的参数列表：

文本内容相关参数

• text ：指定要绘制的文本字符串，必须是 UTF-8 编码的字符。
• textfile ：指定包含要绘制文本的文件，文本必须是 UTF-8 编码的字符序列。如果未指定 text 参数，此参数是必需的。
• reload ：指定 textfile 文件重新加载的帧间隔。范围是 0 到 INT_MAX，默认为 0。
• text_source ：如果要使用边数据检测边界框中的文本数据，可将文本源设置为 side_data_detection_bboxes。若设置了此参数，将忽略 text 和 textfile 参数。

文本显示相关参数

• fontcolor ：指定字体颜色，语法参考 (ffmpeg-utils) 手册中的 “颜色” 部分，默认为 “黑色”。
• fontcolor_expr ：以与 text 相同的方式扩展的字符串，用于获取动态字体颜色值。默认值为空，不进行处理。设置后覆盖 fontcolor 参数。
• fontsize ：指定字体大小。
• fontfile ：指定字体文件，用于从文件中读取字体。
• font ：指定字体系列，默认值为 Sans。
• fontstyle ：指定字体风格，可选择的值有 normal、italic、oblique。
• fontweight ：指定字体粗细，可选择的值有 normal、bold、lighter，或设置为具体的数值，数值范围为 100 - 900，间隔为 100。
• line_spacing ：设置行间距，以像素为单位，默认值为 0。

文本位置相关参数

• x ：指定文本在视频帧内的 x 偏移量，默认值为 “0”。可使用表达式，表达式中可包含以下常量和函数：dar（输入显示宽高比）、hsub、vsub（水平和垂直色度子采样值）、line_h、lh（每行文本的高度）、main_h、h、H（输入高度）、main_w、w、W（输入宽度）、max_glyph_a、ascent（字形的最大上升值）、max_glyph_d、descent（字形的最大下降值）、max_glyph_h（最大字形高度）、max_glyph_w（最大字形宽度）、font_a（字体指标中定义的上升尺寸）、font_d（字体指标中定义的下降尺寸）、top_a（第一行文本字形的最大上升值）、bottom_d（最后一行文本字形的最大下降值）、n（输入帧数）、rand（返回指定范围的随机数）、sar（输入采样宽高比）、t（时间戳）、text_h、th（渲染文本的高度）、text_w、tw（渲染文本的宽度）等。
• y ：指定文本在视频帧内的 y 偏移量，默认值为 “0”。与 x 参数类似，可使用相同的表达式和常量。
• text_align ：设置文本相对于框边界的垂直和水平对齐方式。值为垂直对齐标志（T=顶部、M=中间、B=底部）和水平对齐标志（L=左侧、C=居中、R=右侧）的组合。注意，制表符仅支持左侧水平对齐。
• y_align ：指定 y 值引用的内容。可能的值为：text（第一行文本的最高字形的顶部位于 y 处）、baseline（第一行文本的基线位于 y 处）、font（第一行文本的基线位于 y 加上字体度量中定义的上升高度处）。默认值为 “text”，以便向后兼容。

文本边框及背景相关参数

• box ：用于在文本周围绘制一个框，默认颜色为白色。该值必须为 1（启用）或 0（禁用），默认值为 0。
• boxcolor ：设置用于在文本周围绘制框的颜色。语法参考 (ffmpeg-utils)手册中的 “颜色” 部分，默认值为 “白色”。
• boxborderw ：设置使用 boxcolor 在框周围绘制的边框的宽度。可使用以下格式之一指定：boxborderw=10（所有边框宽度设为 10）、boxborderw=10|20（顶部和底部边框宽度为 10，左、右边框宽度为 20）、boxborderw=10|20|30（顶部边框宽度为 10，底部为 30，左右为 20）、boxborderw=10|20|30|40（分别设置顶、右、底、左边框宽度）。
• borderw ：设置使用 bordercolor 在文本周围绘制的边框的宽度，默认值为 0。
• bordercolor ：设置用于在文本周围绘制边框的颜色，默认值为 “黑色”。

其他参数

• enable ：指定滤镜启用的条件表达式。
• fix_bounds ：如果为 true，则检查并修复文本坐标以避免剪切。
• expansion ：选择如何扩展 text。可取值为 none、strftime（已弃用）或 normal（默认）。
• basetime ：设置计数的起始时间，单位为微秒。仅在已弃用的 strftime 扩展模式下应用。