ffmpeg-python中文文档（三）——API参考

class ffmpeg.Stream（upstream_node，upstream_label，node_types，upstream_selector=None ）

表示上游节点的传出边缘；可以用来创建更多的下游节点。

某些 ffmpeg滤波器会丢弃音频流，因此必须注意在最终输出中保留音频。.audio和 .video运算符可用于引用流的音频/视频部分，以便可以单独处理它们，然后在以后的管道中重新组合它们。这种困境是ffmpeg固有的，ffmpeg-python试图远离，而用户可以参考官方ffmpeg文档，了解为什么某些过滤器会掉落音频。

• 属性audio
  选择流的音频部分。
  stream.audio是stream['a']的简写。

  独立处理流的音频和视频部分：

input = ffmpeg.input('in.mp4')
audio = input.audio.filter("aecho", 0.8, 0.9, 1000, 0.3)
video = input.video.hflip()
out = ffmpeg.output(audio, video, 'out.mp4')

• 属性video
  选择流的视频部分。
  stream.video是 的简写stream['v']。
  例子
  独立处理流的音频和视频部分：

  input = ffmpeg.input('in.mp4')
  audio = input.audio.filter("aecho", 0.8, 0.9, 1000, 0.3)
  video = input.video.hflip()
  out = ffmpeg.output(audio, video, 'out.mp4')

ffmpeg.input( filename , **kwargs )

输入文件 URL （ffmpeg -i option）

• 任何提供的 kwargs 都会逐字传递给 ffmpeg（例如 t=20、f='mp4'、acodec='pcm'等）。

• 要告诉 ffmpeg 从 stdin 读取，请使用 pipe：作为文件名。

ffmpeg.merge_outputs（* streams ）

在一个 ffmpeg 命令行中包含所有给定的输出

ffmpeg.output( streams_and_filename* , kwargs )

输出文件地址

• 句法：

  ffmpeg.output(stream1[, stream2, stream3…], 文件名, ffmpeg_args)

• 任何提供的关键字参数被传递给ffmpeg的逐字（例如 t=20，f='mp4'，acodec='pcm'，vcodec='rawvideo'，等等）。一些关键字参数经过特殊处理，如下所示。

• 参数:

  • video_bitrate – 的参数-b:v，例如video_bitrate=1000。

  • audio_bitrate – 的参数-b:a，例如audio_bitrate=200。

  • format –-f参数的别名，例如format='mp4' （等价于f='mp4'）。

• 如果提供了多个流，它们将映射到相同的输出。

• 要告诉 ffmpeg 写入标准输出，请pipe:用作文件名。

ffmpeg.overwrite_output（stream）

不询问就覆盖输出文件（ffmpeg -y 选项）

ffmpeg.probe( filename , cmd='ffprobe' , **kwargs )

在指定文件上运行 ffprobe 并返回输出的 JSON 表示。

• 加注:

  ffmpeg.Error – 如果 ffprobe 返回非零退出代码，Error则返回an并带有通用错误消息。可以通过访问stderr异常的属性来检索 stderr 输出 。*

ffmpeg.compile( stream_spec , cmd='ffmpeg' , overwrite_output=False )

构建用于调用 ffmpeg 的命令行。

• 该run()函数使用它来构建命令行参数并且在大多数情况下应该可以工作，但是直接调用这个函数对于调试或者无论出于何种原因需要手动调用 ffmpeg 很有用。

• 这与调用get_args()相同，只是它还包括ffmpeg命令作为第一个参数。

• 异常ffmpeg.Error（cmd，stdout，stderr ）

ffmpeg.get_args( stream_spec , overwrite_output=False )

构建要传递给 ffmpeg 的命令行参数。

ffmpeg.run( stream_spec , cmd='ffmpeg' , capture_stdout=False , capture_stderr=False , input=None , quiet=False , overwrite_output=False )

为提供的节点图调用 ffmpeg。

参数

• capture_stdout – 如果为 True，则捕获标准输出（与pipe:ffmpeg 输出一起使用 ）。

• capture_stderr – 如果为真，则捕获标准错误。

• quiet – 设置capture_stdout和 的简写capture_stderr。

• 输入- 要发送到标准输入的文本（与pipe: ffmpeg 输入一起使用）

• **kwargs – 传递给get_args()（例如 overwrite_output=True）的关键字参数。

• 返回： (out, err) 元组，包含捕获的 stdout 和 stderr 数据。

ffmpeg.run_async( stream_spec , cmd='ffmpeg' , pipe_stdin=False , pipe_stdout=False , pipe_stderr=False , quiet=False , overwrite_output=False )

为提供的节点图异步调用 ffmpeg。

参数

• pipe_stdin – 如果为 True，则将管道连接到子进程标准输入（与pipe:ffmpeg 输入一起使用）。
• pipe_stdout – 如果为 True，则将管道连接到子进程stdout（与pipe:ffmpeg 输出一起使用）。
• pipe_stderr – 如果为 True，则将管道连接到子进程stderr。
• quiet – 设置capture_stdout和 的 简写capture_stderr。
• **kwargs – 传递给get_args()（例如 overwrite_output=True）的关键字参数。

例子

运行和流式输入：

process = (
  ffmpeg
  .input('pipe:', format='rawvideo', pix_fmt='rgb24', s='*{}*x*{}*'.format(width, height))
  .output(out_filename, pix_fmt='yuv420p')
  .overwrite_output()
  .run_async(pipe_stdin=**True**)
)
process.communicate(input=input_data)

运行并捕获输出：

process = (
  ffmpeg
  .input(in_filename)
  .output('pipe':, format='rawvideo', pix_fmt='rgb24')
  .run_async(pipe_stdout=**True**, pipe_stderr=**True**)
)
out, err = process.communicate()

使用 numpy 逐帧处理视频：

process1 = (
  ffmpeg
  .input(in_filename)
  .output('pipe:', format='rawvideo', pix_fmt='rgb24')
  .run_async(pipe_stdout=True)
)
process2 = (
   ffmpeg
  .input('pipe:', format='rawvideo', pix_fmt='rgb24', s='{}x{}'.format(width, height))
  .output(out_filename, pix_fmt='yuv420p')
  .overwrite_output()
  .run_async(pipe_stdin=True)
)
while True:
  in_bytes = process1.stdout.read(width * height * 3)
  if not in_bytes:
    break
  in_frame = (
    np
    .frombuffer(in_bytes, np.uint8)
    .reshape([height, width, 3])
  )
  out_frame = in_frame * 0.3
  process2.stdin.write(frame.astype(np.uint8).tobytes())
  
process2.stdin.close()
process1.wait()
process2.wait()

ffmpeg.view( stream_spec , detail=False , filename=None , pipe=False , **kwargs )

ffmpeg.colorchannelmixer（stream，args，kwargs* ）

通过重新混合颜色通道来调整视频输入帧。

ffmpeg.concat( * Streams , ** kwargs )

连接音频和视频流，将它们一个接一个地连接在一起。

筛选器适用于同步视频和音频流的片段。所有段必须具有每种类型的相同数量的流，这也是输出时的流数。

参数

• unsafe – 激活不安全模式：如果段具有不同的格式，则不会失败。
• 由于各种原因，包括编解码器帧大小或草率创作，相关流并不总是具有完全相同的持续时间。出于这个原因，相关的同步流（例如视频及其音轨）应该立即连接起来。concat 过滤器将使用每个片段中最长流的持续时间（最后一个除外），并在必要时用静音填充较短的音频流。
• 要使此过滤器正常工作，所有段必须从时间戳 0 开始。
• 所有对应的流必须在所有段中具有相同的参数；过滤系统会自动为视频流选择常用的像素格式，为音频流选择常用的采样格式、采样率和通道布局，但其他设置，如分辨率，必须由用户明确转换。
• 不同的帧率是可以接受的，但会导致输出时的帧率可变；一定要配置输出文件来处理它。

ffmpeg.crop(stream, x , y ,width,height, **kwargs )

裁剪输入视频。

参数

• x – 输出视频左边缘在输入视频中的水平位置。

• y – 输出视频上边缘在输入视频中的垂直位置。

• width – 输出视频的宽度。必须大于 0。

• heigth - 输出视频的高度。必须大于 0。

ffmpeg.drawbox（stream，x，y，width，height，color， thickness =None，**kwargs ）

在输入图像上绘制一个彩色框。

参数

• x – 指定框左上角 x 坐标的表达式。它默认为 0。

• y – 指定框左上角 y 坐标的表达式。它默认为 0。

• width – 指定框的宽度；如果 0 解释为输入宽度。它默认为 0。

• heigth – 指定盒子的高度；如果 0 解释为输入高度。它默认为 0。

• color - 指定要写入的框的颜色。有关此选项的一般语法，请查看 ffmpeg-utils 手册中的“颜色”部分。如果使用 特殊值反转，则框边缘颜色与具有反转亮度的视频相同。

• thickness ——设置盒子边缘厚度的表达式。默认值为 3。

• w – 的别名width。

• h – 的别名height。

• c – 的别名color。

• t – 的别名thickness。

ffmpeg.drawtext(stream, text=None , x=0 , y=0 , escape_text=True , **kwargs )

使用 libfreetype 库从视频顶部的指定文件中绘制文本字符串或文本。

要启用此过滤器的编译，您需要使用--enable-libfreetype. 要启用默认字体回退和字体选项，您需要使用--enable-libfontconfig. 要启用text_shaping选项，您需要使用--enable-libfribidi

参数

· box - 用于使用背景颜色在文本周围绘制一个框。该值必须是 1（启用）或 0（禁用）。框的默认值为 0。

· boxborderw – 使用 boxcolor 设置要在框周围绘制的边框宽度。boxborderw 的默认值为 0。

· boxcolor - 用于在文本周围绘制框的颜色。有关此选项的语法，请查看 ffmpeg-utils 手册中的“颜色”部分。 boxcolor 的默认值为“white”。

· line_spacing – 使用 box 设置要在框周围绘制的边框的行间距（以像素为单位）。line_spacing 的默认值为 0。

· borderw – 使用边框颜色设置要在文本周围绘制的边框宽度。边框的默认值为 0。

· bordercolor – 设置用于在文本周围绘制边框的颜色。有关此选项的语法，请查看 ffmpeg-utils 手册中的“颜色”部分。边框颜色的默认值为“黑色”。

· 扩展- 选择文本的扩展方式。可以是 none、strftime（已弃用）或 normal（默认）。有关详细信息，请参阅下面的文本扩展部分。

· basetime – 设置计数的开始时间。值以微秒为单位。仅适用于已弃用的 strftime 扩展模式。要在正常扩展模式下进行模拟，请使用 pts 函数，提供开始时间（以秒为单位）作为第二个参数。

· fix_bounds - 如果为 true，检查并修复文本坐标以避免剪切。

· fontcolor - 用于绘制字体的颜色。有关此选项的语法，请查看 ffmpeg-utils 手册中的“颜色”部分。fontcolor 的默认值为“黑色”。

· fontcolor_expr – 与文本相同的扩展字符串以获得动态字体颜色值。默认情况下，此选项具有空值并且不被处理。设置此选项时，它会覆盖 fontcolor 选项。

· font - 用于绘制文本的字体系列。默认情况下无。

· fontfile – 用于绘制文本的字体文件。必须包含路径。如果禁用了 fontconfig 支持，则此参数是必需的。

· alpha – 绘制应用 alpha 混合的文本。该值可以是介于 0.0 和 1.0 之间的数字。该表达式也接受相同的变量 x、y。默认值为 1。请参阅 fontcolor_expr。

· fontsize – 用于绘制文本的字体大小。字体大小的默认值为 16。

· text_shaping – 如果设置为 1，则在绘制文本之前尝试对文本进行整形（例如，反转从右到左文本的顺序并加入阿拉伯字符）。否则，只需按照给定的方式绘制文本。默认为 1（如果支持）。

· ft_load_flags –用于加载字体的标志。这些标志映射了 libfreetype 支持的相应标志，并且是以下值的组合：

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

默认值为“默认”。有关更多信息，请参阅 FT_LOAD_* libfreetype 标志的文档。

· shadowcolor – 用于在已绘制文本后面绘制阴影的颜色。有关此选项的语法，请查看 ffmpeg-utils 手册中的“颜色”部分。shadowcolor 的默认值为“黑色”。

· shadowx – 文本阴影位置相对于文本位置的 x 偏移量。它可以是正值或负值。默认值为“0”。

· shadowy – 文本阴影位置相对于文本位置的 y 偏移量。它可以是正值或负值。默认值为“0”。

· start_number – n/frame_num 变量的起始帧号。默认值为“0”。

· tabsize - 用于呈现选项卡的空格数大小。默认值为 4。

· timecode – 以“hh:mm:ss[:;.]ff”格式设置初始时间码表示。它可以带或不带文本参数使用。必须指定 timecode_rate 选项。

· rate – 设置时间码帧率（仅限时间码）。

· timecode_rate – 的别名rate。

· r – 的别名rate。

· tc24hmax – 如果设置为 1，时间码选项的输出将在 24 小时左右回绕。默认值为 0（禁用）。

· text -- 要绘制的文本字符串。文本必须是 UTF-8 编码字符序列。如果没有使用参数 textfile 指定文件，则此参数是必需的。

· textfile – 包含要绘制的文本的文本文件。文本必须是 UTF-8 编码字符序列。如果没有使用参数 text 指定文本字符串，则此参数是必需的。如果同时指定了 text 和 textfile，则会引发错误。

· reload – 如果设置为 1，文本文件将在每一帧之前重新加载。一定要自动更新它，否则它可能会被部分读取，甚至失败。

· x – 指定将在视频帧内绘制文本的偏移量的表达式。它相对于输出图像的左边框。默认值为“0”。

· y - 指定将在视频帧内绘制文本的偏移量的表达式。它相对于输出图像的上边框。默认值为“0”。有关接受的常量和函数的列表，请参见下文。

表达式常量：

x 和 y 的参数是包含以下常量和函数的表达式：

· dar：输入显示纵横比，同 (w / h) * sar

· hsub：水平色度子样本值。例如，对于像素格式“yuv422p”，hsub 为 2，vsub 为 1。

· vsub：垂直色度子样本值。例如，对于像素格式“yuv422p”，hsub 为 2，vsub 为 1。

· line_h：每个文本行的高度

· lh：别名为line_h.

· main_h：输入高度

· h: 的别名main_h。

· H： 的别名main_h。

· main_w：输入宽度

· w: 的别名main_w。

· W： 的别名main_w。

· ascent：对于所有渲染的字形，从基线到用于放置字形轮廓点的最高/上网格坐标的最大距离。这是一个正值，因为网格的 Y 轴向上。

· max_glyph_a: 的别名ascent。

· 下降：对于所有渲染的字形，从基线到用于放置字形轮廓点的最低网格坐标的最大距离。由于网格的方向，这是一个负值，Y 轴向上。

· max_glyph_d: 的别名descent。

· max_glyph_h：最大字形高度，即渲染文本中包含的所有字形的最大高度，相当于上升-下降。

· max_glyph_w：最大字形宽度，即渲染文本中包含的所有字形的最大宽度。

· n：输入帧数，从0开始

· rand(min, max)：返回一个包含在 min 和 max 之间的随机数

· sar：输入样本纵横比。

· t：时间戳，以秒为单位，如果输入时间戳未知，则为 NAN

· text_h：渲染文本的高度

· th： 的别名text_h。

· text_w：渲染文本的宽度

· tw: 的别名text_w。

· x：绘制文本的 x 偏移坐标。

· y：绘制文本的 y 偏移坐标。

这些参数允许 x 和 y 表达式相互引用，因此您可以例如指定 y=x/dar.

ffmpeg.filter( stream_spec , filter_name , args* , kwargs )

应用自定义过滤器。

filter通常由更高级别的过滤器函数使用，例如hflip，但如果缺少过滤器实现ffmpeg-python，您可以filter直接调用以ffmpeg-python将过滤器名称和参数逐字传递给ffmpeg。

参数

• stream_spec – 流、流列表或标签到流字典映射
• filter_name – ffmpeg 过滤器名称，例如colorchannelmixer
• *args– 逐字传递给 ffmpeg 的 args 列表
• **kwargs – 逐字传递给 ffmpeg 的关键字参数列表

函数名称后缀_是为了避免与标准pythonfilter函数混淆。

例子

ffmpeg.input('in.mp4').filter('hflip').output('out.mp4').run()

ffmpeg.filter_( stream_spec , filter_name , args* , kwargs )

替代名称filter，以免与内置的pythonfilter运算符冲突。

ffmpeg.filter_multi_output( stream_spec , filter_name , args* , kwargs )

应用具有一个或多个输出的自定义过滤器。

这filter与过滤器可以产生多个输出相同。

要引用输出流，请使用.stream运算符或括号简写：

例子

 split = ffmpeg.input('in.mp4').filter_multi_output('split') split0 = split.stream(0) split1 = split[1] ffmpeg.concat(split0, split1).output('out.mp4').run() 

ffmpeg.hflip（stream）

水平翻转输入视频。

ffmpeg.hue（stream，**kwargs ）

修改输入的色调和/或饱和度。

参数

• h – 将色调角度指定为度数。它接受一个表达式，默认为“0”。

• s – 在 [-10,10] 范围内指定饱和度。它接受一个表达式并默认为“1”。

• H – 将色调角度指定为弧度数。它接受一个表达式，默认为“0”。

• b – 在 [-10,10] 范围内指定亮度。它接受一个表达式并默认为“0”。

ffmpeg.overlay( main_parent_node , overlay_parent_node , eof_action='repeat' , **kwargs )

将一个视频叠加在另一个视频之上。

参数

• x – 设置主视频上叠加视频的 x 坐标表达式。默认值为0。如果表达式无效，则将其设置为一个巨大的值（意味着覆盖不会显示在输出可见区域内）。

• y – 设置主视频上叠加视频的 y 坐标表达式。默认值为0。如果表达式无效，则将其设置为一个巨大的值（意味着覆盖不会显示在输出可见区域内）。

• eof_action –在辅助输入上遇到 EOF 时要采取的操作；它接受以下值之一：

  • repeat：重复最后一帧（默认）。

  • endall: 结束两个流。

  • pass: 通过主输入。

• eval –

  • 在计算 x 和 y 的表达式时设置。它接受以下值：

  • init：仅在过滤器初始化期间或命令执行时评估表达式一次处理

  • frame: 评估每个传入帧的表达式
    默认值为frame。

• shortest – 如果设置为 1，则在最短输入终止时强制输出终止。默认值为 0。

• format –
  设置输出视频的格式。它接受以下值：

• yuv420: 强制 YUV420 输出

• yuv422: 强制 YUV422 输出

• yuv444: 强制 YUV444 输出

• rgb: 强制打包 RGB 输出

• gbrp：强制平面RGB输出
  默认值为yuv420。

• rgb ( deprecated ) –` 如果设置为 1，则强制过滤器接受 RGB 颜色空间中的输入。默认值为 0。此选项已弃用，请改用格式。

• repeatlast –如果设置为 1，则强制过滤器在主输入上绘制最后一个覆盖帧，直到流结束。值 0 禁用此行为。默认值为 1。

ffmpeg.setpts(steam, expr )

更改输入帧的 PTS（表示时间戳）。

FFmpeg里有两种时间戳：DTS（Decoding Time Stamp）和PTS（Presentation Time Stamp）。 顾名思义，前者是解码的时间，后者是显示的时间。

参数

• expr – 为每个帧评估以构造其时间戳的表达式。

ffmpeg.trim（stream,**kwargs ）

修剪输入，使输出包含输入的一个连续子部分。

参数

• start - 指定保留部分的开始时间，即带有时间戳开始的帧将是输出中的第一帧。

• end – 指定将被丢弃的第一帧的时间，即紧接在带有时间戳 end 的帧之前的帧将是输出中的最后一帧。

• start_pts – 这与 start 相同，只是此选项以时基单位而不是秒为单位设置开始时间戳。

• end_pts – 这与 end 相同，只是此选项以时基单位而不是秒为单位设置结束时间戳。

• duration – 输出的最大持续时间（以秒为单位）。

• start_frame – 应传递到输出的第一帧的编号。

• end_frame – 应丢弃的第一帧的编号。

ffmpeg.vflip（stream）

垂直翻转输入视频。

ffmpeg.zoompan（stream，**kwargs ）

应用缩放和平移效果。

参数

• zoom – 设置缩放表达式。默认值为 1。

• x – 设置 x 表达式。默认值为 0。

• y – 设置 y 表达式。默认值为 0。

• d – 以帧数设置持续时间表达式。这设置单个输入图像将持续多少帧效果。

• s – 设置输出图像大小，默认为hd720.

• fps - 设置输出帧率，默认为 25。

• z – 的别名zoom。