语音转文字长音频分段与时间戳合并

长音频做语音转文字时，最容易出问题的不是“切不切”，而是切开以后如何保留边界语音、去掉重叠文本，并让每个片段的时间戳仍然对应原音频。稳定做法是：用固定窗口切分，给相邻窗口保留少量重叠；识别结果统一换算成绝对时间；最终只让每个窗口的核心区写入总时间线。

官方文档：https://huggingface.co/docs/inference-providers/index

下面的示例以 Hugging Face Transformers 的自动语音识别管线为背景。官方管线提供 chunk_length_s、stride_length_s 和时间戳返回能力，但不同模型支持的时间粒度可能不同，接入时要以所选模型的说明为准。

先把窗口、重叠区和时间线定义清楚

假设整段音频长度为 T 秒，窗口长度为 W，左右上下文各保留 S 秒。第一个窗口从 0 开始，后续窗口按“窗口长度减去重叠长度”向后移动。模型看到的是完整窗口，但最终时间线只接收窗口的核心区。

这样做有两个好处：句子恰好跨过边界时，后一个窗口仍然能看到前面的上下文；同一句话在两个窗口中都出现时，也有一条清晰的归属规则。不要把每个窗口返回的 text 直接拼接，因为重复内容往往已经发生在重叠区。

用重叠区保护边界语音

窗口和重叠长度可以先从 30 秒窗口、5 秒重叠开始，再根据语速、噪声和模型上下文能力调整。重叠区的任务是给模型更多上下文，不是让它重复写入结果。对中间窗口来说，建议把左侧 S 秒到右侧 S 秒之间视为核心区；首窗口没有左侧裁剪，末窗口没有右侧裁剪。

如果使用 Transformers 管线，可以把切分参数交给管线，也可以由业务层先切好音频再调用识别服务。无论选择哪种方式，都要在自己的中间对象中保存窗口起点 offset、窗口结束时间和左右保留边界。只有保存这些元数据，后续才能把局部时间戳还原为全局时间。

from transformers import pipeline

# 用重叠窗口给模型补充边界上下文；真实项目应按所选模型调整参数。
transcriber = pipeline(
    task="automatic-speech-recognition",
    model="openai/whisper-small",
)

# 返回带时间信息的片段；若模型支持词级时间戳，可改用 return_timestamps="word"。
result = transcriber(
    "meeting.wav",
    chunk_length_s=30,
    stride_length_s=5,
    return_timestamps=True,
)

这里的 stride_length_s 是上下文保护参数，不等于“最终保留 5 秒”。最终是否保留某个词，要由窗口起点、窗口边界和核心区规则决定。

合并带时间戳的片段

合并时先完成坐标转换：片段内的局部时间 local_start/local_end 加上窗口起点 offset，就得到原音频坐标。随后用核心区做裁剪。一个词完全落在重叠区，就丢弃；一个词跨过核心区边界，就裁剪到核心区内，避免相邻窗口各保留一份。

from dataclasses import dataclass
from typing import Iterable

@dataclass
class WordSpan:
    start: float
    end: float
    text: str

def merge_spans(parts: Iterable[dict], window_s: float, stride_s: float) -> list[WordSpan]:
    """把各窗口的局部词时间戳合并为原音频的绝对时间线。"""
    merged: list[WordSpan] = []
    step = window_s - stride_s

    for index, part in enumerate(parts):
        # offset 把当前窗口的局部秒数移到整段音频坐标。
        offset = index * step
        window_end = min(offset + window_s, float(part.get("audio_end", offset + window_s)))

        # 首尾窗口只在实际存在的方向裁剪，中间窗口保留核心区。
        keep_start = offset if index == 0 else offset + stride_s / 2
        keep_end = window_end if part.get("is_last", False) else window_end - stride_s / 2

        for item in part.get("chunks", []):
            # 没有完整时间戳的结果不能安全地放入总时间线。
            local = item.get("timestamp")
            if not local or local[0] is None or local[1] is None:
                continue

            start = max(offset + float(local[0]), keep_start)
            end = min(offset + float(local[1]), keep_end)
            # 词完全位于重叠区，裁剪后会变成空区间，直接跳过。
            if end 

示例里的 parts 是业务层统一后的中间对象，timestamp 可以来自词级或片段级输出。若只有片段级时间戳，就把合并粒度保持在片段，不要伪造词级时间。真实接入时还要明确单位是秒还是采样点，必要时在入口统一成浮点秒。

首尾、空结果和时间间隙怎么处理

首窗口的 keep_start 应为音频起点，末窗口的 keep_end 应为实际音频结束时间；不能机械地在两端都减去重叠长度。遇到空片段、缺少时间戳或结束时间早于开始时间时，宁可暂不写入，也不要用相邻文本猜一个时间。

合并后可以保留短暂间隙，因为停顿本来就是音频的一部分。若产品需要字幕，可以在展示层再按最短时长、最大行长和标点进行排版，不要把字幕排版规则混进识别结果合并器。这样调节字幕样式时，不会破坏原始时间线。

常见问题

为什么重叠越大，重复文本反而越多？因为重叠只是提供上下文，不会自动决定最终归属。必须在合并阶段用核心区裁剪，并保存每个窗口的起点。

只有整段文本，没有时间戳还能合并吗？不能可靠地合并。可以先把输出降级为按窗口展示，但不要把窗口边界当成词或句子的真实发生时间。

窗口长度应该固定吗？第一版建议固定，便于计算偏移和排查问题；只有当模型、音频格式或业务延迟要求明确变化时，再引入动态窗口。

总结

• 重叠区用于补上下文，核心区用于决定谁写入最终时间线。
• 所有局部时间戳都要加窗口起点，统一转换成原音频绝对时间。
• 首尾窗口单独处理，缺少时间戳的结果不要用文本相似度强行猜测。