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',
]

 

上一篇:requests库入门


下一篇:matplotlib--文字图例