音频属性与过滤-阿里云帮助中心

本文介绍 Python DataFrame API 中的音频有效性检查、元数据、音频过滤相关算子

本文介绍 Python DataFrame API 中的音频有效性检查、元数据、时长、时长过滤和大小过滤算子。

使用限制

仅实时计算引擎 VVR 11.8 及以上版本支持。
元数据探测基于 soundfile、libsndfile 库提供。
本文使用音频片段引用 (AUDIO_CLIP_REF_TYPE)、音频元数据 (AUDIO_METADATA_TYPE)和解码后的音频波形 (AUDIO_WAVEFORM_TYPE)表示 pyflink.multimodal.types 中定义的 DataFrame API 类型。

算子清单

分类	算子	说明
有效性检查	is_valid_audio	通过媒体头探测或完整解码，按指定校验级别判断编码音频能否继续处理并返回布尔结果。适合在外部音频接入、批量回灌或 ASR 前置质量检查，例如先用 metadata 低成本粗筛，再用 decode 排除截断、空音频和解码大小超限的数据。
属性提取	audio_metadata	读取音频的采样率、声道数、帧数、时长、格式、编码器、码率和对象大小等元数据。适合用于音频盘点、质量统计和按属性路由，例如按采样率选择预处理链路，或按格式识别异常数据来源。
属性提取	audio_duration	计算并返回音频的秒级时长。适合按音频长短分桶、估算处理成本或制定切分策略，例如把超长录音送入固定时长切分，将短录音直接交给 ASR。
数据过滤	audio_duration_filter	判断音频时长是否位于指定闭区间，可只设下限、只设上限或同时设置。适合在模型推理或训练前过滤过短、过长样本，例如排除低于 1 秒的无效录音，或拦截超过模型输入上限的音频。
数据过滤	audio_size_filter	按字节判断 `DataType.binary()` 或 URI 音频大小是否位于指定闭区间，不读取媒体内容。适合在下载、解码或发送到下游服务前控制资源消耗，例如提前拦截超大对象以降低网络和内存压力。

通用 Runtime 参数

函数签名保留各算子实际支持的 Runtime 参数。为避免重复，算子参数表只说明业务参数，Runtime 参数统一说明如下。

参数	类型	默认值	适用范围	说明
`concurrency`	`Optional[int]`	`None`	本页全部算子	UDF 并发度。`None` 表示使用框架默认值。

有效性检查与属性提取

is_valid_audio

检查编码音频是否可以读取。该算子不接受解码后的波形。

输入类型： DataType.binary()、DataType.string() 或 AUDIO_CLIP_REF_TYPE，编码音频字节列、音频 URI 列或音频片段引用列。

函数签名：

is_valid_audio(
    *columns,
    validation="metadata",
    concurrency=None
)

参数	类型	默认值	说明
`validation`	`str`	`"metadata"`	`"metadata"` 只读取容器或文件头；`"decode"` 完整解码音频。

空值、损坏、截断、格式无法识别，以及完整解码后的 PCM 数据超过 1 GiB 时返回 False。URI 无法访问、片段引用非法或依赖缺失时抛出异常。

返回类型： DataType.boolean()。

from pyflink.dataframe import col
from pyflink.multimodal.operators import is_valid_audio

result = df.filter(
    is_valid_audio(
        col("audio_bytes"),
        validation="metadata"
    )
)

audio_metadata

读取编码音频或波形的元数据。

输入类型： DataType.binary()、DataType.string()、AUDIO_CLIP_REF_TYPE 或 AUDIO_WAVEFORM_TYPE，编码音频字节列、音频 URI 列、音频片段引用列或解码后的波形列。

函数签名：

audio_metadata(
    *columns,
    concurrency=None
)

损坏的编码音频返回 None。
对音频片段引用调用时，frames 和 duration_ms 按引用区间计算，size 仍是完整编码对象的大小。
对音频波形调用时，format、codec、bit_rate 和 size 为 None。
URI 无法访问、依赖缺失、输入类型不受支持和内部错误仍会使作业失败。

返回类型： AUDIO_METADATA_TYPE。

from pyflink.multimodal.operators import audio_metadata

result = df.with_column(
    "audio_metadata",
    audio_metadata(col("audio_uri"))
)

audio_duration

读取音频时长。

函数签名：

audio_duration(
    *columns,
    concurrency=None
)

返回值由 duration_ms / 1000 计算，单位为秒。无法获得时长或编码输入损坏时返回 None；URI 无法访问时抛出异常。

返回类型： DataType.float64()。

from pyflink.multimodal.operators import audio_duration

result = df.with_column(
    "duration_seconds",
    audio_duration(col("audio_bytes"))
)

audio_duration 和 audio_duration_filter 使用秒；AUDIO_METADATA_TYPE 中的 duration_ms 和音频片段引用中的时间字段使用毫秒。

数据过滤

audio_duration_filter

判断音频时长是否在指定的闭区间内。

函数签名：

audio_duration_filter(
    *columns,
    min_seconds=None,
    max_seconds=None,
    concurrency=None
)

参数	类型	默认值	说明
`min_seconds`	`Optional[float]`	`None`	最短时长，单位为秒，包含端点。
`max_seconds`	`Optional[float]`	`None`	最长时长，单位为秒，包含端点。

至少需要设置一个边界。边界必须为非负数，且 max_seconds >= min_seconds。空值、无法获得时长或损坏的受支持输入返回 False。

返回类型： DataType.boolean()。

from pyflink.multimodal.operators import audio_duration_filter

result = df.filter(
    audio_duration_filter(
        col("audio_bytes"),
        min_seconds=0.5,
        max_seconds=600.0
    )
)

audio_size_filter

判断编码音频对象的字节数是否在指定的闭区间内。该算子不读取或解码媒体内容，因此数据损坏但大小符合条件时仍返回 True。

输入类型： DataType.binary() 或 DataType.string()，编码音频字节列或音频 URI 列。不支持音频片段引用和波形。

函数签名：

audio_size_filter(
    *columns,
    min_bytes=None,
    max_bytes=None,
    concurrency=None
)

参数	类型	默认值	说明
`min_bytes`	`Optional[int]`	`None`	最小字节数，包含端点。
`max_bytes`	`Optional[int]`	`None`	最大字节数，包含端点。

至少需要设置一个边界。空值返回 False；URI 不存在、无法访问或指向目录时抛出异常。

返回类型： DataType.boolean()。

from pyflink.multimodal.operators import audio_size_filter

result = df.filter(
    audio_size_filter(
        col("audio_bytes"),
        min_bytes=1024,
        max_bytes=100 * 1024 * 1024
    )
)