ffmpeg-python库的使用翻译（三）

接上篇 ffmpeg-python库的使用翻译（二）

原文地址：https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_filters.py

现有过滤器：

from __future__ import unicode_literals

from .nodes import FilterNode, filter_operator
from ._utils import escape_chars


@filter_operator()
def 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()
        ```
    """
    return FilterNode(
        stream_spec, filter_name, args=args, kwargs=kwargs, max_inputs=None
    )


@filter_operator()
def filter(stream_spec, filter_name, *args, **kwargs):
    """应用自定义过滤器。
.

    ``filter_``通常由更高级别的过滤器功能使用（例如``hflip''），但是如果ffmpeg-python中缺少该过滤器，您可以直接调用filter_让ffmpeg-python传递过滤器名称，并且逐字记录ffmpeg的参数。
    
    Args:
        stream_spec: a Stream, list of Streams, or label-to-Stream dictionary mapping
        filter_name: ffmpeg filter name, e.g. `colorchannelmixer`
        *args: list of args to pass to ffmpeg verbatim
        **kwargs: list of keyword-args to pass to ffmpeg verbatim

    为了避免与标准python的filter函数混淆，函数名后缀有_。

    例如:

        ``ffmpeg.input('in.mp4').filter('hflip').output('out.mp4').run()``
    """
    return filter_multi_output(stream_spec, filter_name, *args, **kwargs).stream()


@filter_operator()
def filter_(stream_spec, filter_name, *args, **kwargs):
    """过滤器"filter"的替代名称，以免与python内置的"filter"运算符冲突。
    """
    return filter(stream_spec, filter_name, *args, **kwargs)


@filter_operator()
def split(stream):
    return FilterNode(stream, split.__name__)


@filter_operator()
def asplit(stream):
    return FilterNode(stream, asplit.__name__)


@filter_operator()
def setpts(stream, expr):
    """更改输入帧的PTS（演示时间戳）。

    Args:
        expr: The expression which is evaluated for each frame to construct its timestamp.

    官方文档: `setpts, asetpts <https://ffmpeg.org/ffmpeg-filters.html#setpts_002c-asetpts>`__
    """
    return FilterNode(stream, setpts.__name__, args=[expr]).stream()


@filter_operator()
def trim(stream, **kwargs):
    """修剪输入，以便输出包含输入的一个连续子部分。

    Args:
        start: 指定保留部分的开始时间，即带有时间戳开始的帧将是输出的第一帧。
        end:   指定将要删除的第一帧的时间，即紧接该帧之前的帧将是输出中的最后一帧。
        start_pts:与start相同，只是此选项以时基单位为时间戳，而不是以秒做时间戳。
        end_pts: 与end相同，只是此选项以时基单位为时间戳，而不是以秒做时间戳。
        duration: 输出的最大持续时间（以秒为单位）。
        start_frame: 输出的第一帧的编号。
        end_frame: 删除的第一帧的编号。

    官方文档: `trim <https://ffmpeg.org/ffmpeg-filters.html#trim>`__
    """
    return FilterNode(stream, trim.__name__, kwargs=kwargs).stream()


@filter_operator()
def overlay(main_parent_node, overlay_parent_node, eof_action='repeat', **kwargs):
    """将一个视频叠加在另一个视频之上。

    Args:
        x: 设置主视频上叠加视频的x坐标的表达式。默认值为0。
            如果表达式无效，则将其设置为一个很大的值（这意味着将不在输出可见区域内显示叠加层
            ）。
        y: 设置主视频上叠加视频的y坐标的表达式。默认值为0。
            如果表达式无效，则将其设置为一个很大的值（这意味着将不在输出可见区域内显示叠加层
            ）。
        eof_action: 在辅助输入上遇到EOF时采取的操作；它接受以下值：

            * ``repeat``: 重复最后一帧（默认）。
            * ``endall``: 结束两个流。
            * ``pass``: 通过主输入

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

            * ``init``: 仅在过滤器初始化期间或在执行命令时对表达式求值一次处理
            * ``frame``: 计算每个传入帧的表达式

            默认值为``frame``.
       最短：如果设置为1，则在最短输入终止时强制输出终止。预设值为0。
       格式：设置输出视频的格式。
            它接受以下值：
            *``yuv420``：强制YUV420输出
            *``yuv422``：强制YUV422输出
            *``yuv444``：强制YUV444输出
            *``RGB``：强制打包RGB输出
            *``gbrp``：强制平面RGB输出

            默认值为``yuv420``。
        rgb（不建议使用）：如果设置为1，则强制滤镜接受RGB颜色空间中的输入。预设值为0。
            不建议使用此选项，请改用format。
        repeatlast：如果设置为1，则强制滤镜在主输入上绘制最后一个覆盖帧，直到结束。
            流。值为0禁用此行为。预设值为1。
    官方文档: `overlay <https://ffmpeg.org/ffmpeg-filters.html#overlay-1>`__
    """
    kwargs['eof_action'] = eof_action
    return FilterNode(
        [main_parent_node, overlay_parent_node],
        overlay.__name__,
        kwargs=kwargs,
        max_inputs=2,
    ).stream()


@filter_operator()
def hflip(stream):
    """水平翻转输入视频。

    官方文档: `hflip <https://ffmpeg.org/ffmpeg-filters.html#hflip>`__
    """
    return FilterNode(stream, hflip.__name__).stream()


@filter_operator()
def vflip(stream):
    """垂直翻转输入视频。

    官方文档: `vflip <https://ffmpeg.org/ffmpeg-filters.html#vflip>`__
    """
    return FilterNode(stream, vflip.__name__).stream()


@filter_operator()
def crop(stream, x, y, width, height, **kwargs):
    """裁剪输入视频。
    Args:
        x: 在输入视频中，要输出的视频左边缘的水平位置。
        y: 在输入视频中，要输出的视频顶部边缘的垂直位置。
        width: 输出视频的宽度。必须大于0。
        heigth: 输出视频的高度。必须大于0。

    官方文档: `crop <https://ffmpeg.org/ffmpeg-filters.html#crop>`__
    """
    return FilterNode(
        stream, crop.__name__, args=[width, height, x, y], kwargs=kwargs
    ).stream()


@filter_operator()
def drawbox(stream, x, y, width, height, color, thickness=None, **kwargs):
    """在输入图像上绘制一个彩色框。

    Args:
        x: 该表达式指定框的左上角x坐标。默认为0。
        y: 该表达式指定框的左上角y坐标。默认为0。
        width: 指定彩色框的宽度；如果0解释为输入宽度。默认为0。
        heigth: 指定彩色框的高度；如果0解释为输入高度。默认为0。
        color: 指定要写入的框的颜色。有关此选项的常规语法，请检查“颜色”部分
               在ffmpeg-utils手册中。如果使用特殊值反转，则框边颜色与倒亮度
               的视频。
        thickness: The expression which sets the thickness of the box edge. Default value is 3.
        w: Alias for ``width``.
        h: Alias for ``height``.
        c: Alias for ``color``.
        t: Alias for ``thickness``.

    官方文档: `drawbox <https://ffmpeg.org/ffmpeg-filters.html#drawbox>`__
    """
    if thickness:
        kwargs['t'] = thickness
    return FilterNode(
        stream, drawbox.__name__, args=[x, y, width, height, color], kwargs=kwargs
    ).stream()


@filter_operator()
def drawtext(stream, text=None, x=0, y=0, escape_text=True, **kwargs):
    """使用libfreetype库在视频顶部的指定文件中绘制文本字符串或文本。
    要启用此过滤器的编译，您需要使用``--enable-libfreetype''配置FFmpeg。
    启用默认字体回退和字体选项，您需要使用``--enable-libfontconfig''配置FFmpeg。
    要启用text_shaping选项，您需要使用``--enable-libfribidi''配置FFmpeg。

    Args:
        box：用于使用背景色在文本周围绘制一个框。该值必须为1（启用）或0
            （禁用）。box的默认值为0。
        boxborderw：使用boxcolor设置要在框周围绘制边框的宽度，boxborderw默认值
                    为0。
        boxcolor：用于在文本周围绘制框的颜色。有关此选项的语法，请检查“颜色”
                  ffmpeg-utils手册中的“节”。boxcolor的默认值为“ white”。
        line_spacing：使用框设置要在框周围绘制的边框的行距（以像素为单位）。line_spacing
                      默认值为0。
        borderw：设置使用bordercolor在文本周围绘制边框的宽度。borderw默认值为0。
        bordercolor：设置用于在文本周围绘制边框的颜色。有关此选项的语法，请检查
                     ffmpeg-utils手册中的“颜色”部分。bordercolor的默认值为“ black”。
        expansion：选择文本的扩展方式。可以为none，strftime（不建议使用）或normal（默认）。
            有关详细信息，请参见下面的文本扩展部分。
        basetime：设置计数的开始时间。值以微秒为单位。仅在不建议使用的strftime中应用
            扩展模式。要在正常扩展模式下进行仿真，请使用pts函数，并提供开始时间（在
            秒）作为第二个参数。
        fix_bounds：如果为true，请检查并修复文本坐标，以避免剪切。
        fontcolor：用于绘制字体的颜色。有关此选项的语法，请检查中的“颜色”部分。
            ffmpeg-utils手册。fontcolor的默认值为“ black”。
        fontcolor_expr：字符串，其扩展方式与文本相同，以获取动态fontcolor值。默认
            此选项的值为空，不会被处理。设置此选项后，它将覆盖fontcolor选项。
        字体：用于绘制文本的字体系列。默认情况下，Sans。
        fontfile：用于绘制文本的字体文件。该路径必须包括在内。如果此参数是必需的
            fontconfig支持已禁用。
        alpha：使用alpha混合绘制文本。该值可以是0.0到1.0之间的数字。表达方式
            也接受相同的变量x，y。默认值为1。请参阅fontcolor_expr。
        fontsize：用于绘制文本的字体大小。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_ * libfreetypeflags的文档。
         
       shadowcolor：用于在绘制的文本后面绘制阴影的颜色。有关此选项的语法，
            检查ffmpeg-utils手册中的“颜色”部分。shadowcolor的默认值为“ black”。
        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：``费率''的别名。
        tc24hmax：如果设置为1，则timecode选项的输出将在24小时后回绕。默认值为0（禁用）。
        text：要绘制的文本字符串。文本必须是UTF-8编码字符序列。该参数是
            如果未使用参数textfile指定文件，则为必需。
        textfile：包含要绘制文本的文本文件。文本必须是UTF-8编码字符序列。
            如果未使用参数text指定文本字符串，则此参数是必需的。如果文字和
            指定了文本文件，将引发错误。
        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''的别名。
         -descent：从基线到用于放置字形轮廓的最低网格坐标的最大距离
           点，适用于所有渲染的字形。由于网格的方向，对于Y轴，这是一个负值
           向上。
         -max_glyph_d：``血统''的别名。
         -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

    官方文档: `drawtext <https://ffmpeg.org/ffmpeg-filters.html#drawtext>`__
    """
    if text is not None:
        if escape_text:
            text = escape_chars(text, '\\\'%')
        kwargs['text'] = text
    if x != 0:
        kwargs['x'] = x
    if y != 0:
        kwargs['y'] = y
    return filter(stream, drawtext.__name__, **kwargs)


@filter_operator()
def concat(*streams, **kwargs):
    """连接音频和视频流，将它们一个一个地连接在一起。

    该过滤器适用于同步视频和音频流的片段。所有片段必须具有相同数量的视频和音频流，输出流也一样。

    Args:
        unsafe: 激活不安全模式：如果段的格式不同，则不会失败

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


    官方文档: `concat <https://ffmpeg.org/ffmpeg-filters.html#concat>`__
    """
    video_stream_count = kwargs.get('v', 1)
    audio_stream_count = kwargs.get('a', 0)
    stream_count = video_stream_count + audio_stream_count
    if len(streams) % stream_count != 0:
        raise ValueError(
            'Expected concat input streams to have length multiple of {} (v={}, a={}); got {}'.format(
                stream_count, video_stream_count, audio_stream_count, len(streams)
            )
        )
    kwargs['n'] = int(len(streams) / stream_count)
    return FilterNode(streams, concat.__name__, kwargs=kwargs, max_inputs=None).stream()


@filter_operator()
def zoompan(stream, **kwargs):
    """应用缩放和平移效果。

    Args:
        zoom：设置缩放表达式。默认值为1。
        x：设置x表达式。默认值为0。
        y：设置y表达式。默认值为0。
        d：以帧数设置持续时间表达式。设置效果持续多少帧
            用于单个输入图像。
        s：设置输出图像尺寸，默认为“ hd720”。
        fps：设置输出帧频，默认为25。
        z：``缩放``的别名。

    官方文档: `zoompan <https://ffmpeg.org/ffmpeg-filters.html#zoompan>`__
    """
    return FilterNode(stream, zoompan.__name__, kwargs=kwargs).stream()


@filter_operator()
def hue(stream, **kwargs):
    """修改输入的色调和/或饱和度。

    Args:
        h：将色相角指定为度数。它接受一个表达式，默认为“ 0”。
        s：在[-10,10]范围内指定饱和度。它接受一个表达式，默认为“ 1”。
        H：将色相角指定为弧度数。它接受一个表达式，默认为“ 0”。
        b：在[-10,10]范围内指定亮度。它接受一个表达式，默认为“ 0”。

    官方文档: `hue <https://ffmpeg.org/ffmpeg-filters.html#hue>`__
    """
    return FilterNode(stream, hue.__name__, kwargs=kwargs).stream()


@filter_operator()
def colorchannelmixer(stream, *args, **kwargs):
    """通过重新混合颜色通道来调整视频输入帧。

    Official documentation: `colorchannelmixer <https://ffmpeg.org/ffmpeg-filters.html#colorchannelmixer>`__
    """
    return FilterNode(stream, colorchannelmixer.__name__, kwargs=kwargs).stream()


__all__ = [
    'colorchannelmixer',
    'concat',
    'crop',
    'drawbox',
    'drawtext',
    'filter',
    'filter_',
    'filter_multi_output',
    'hflip',
    'hue',
    'overlay',
    'setpts',
    'trim',
    'vflip',
    'zoompan',
]