尧图网站建设 
LifeOS AudioEditor 的 Transcribe.ts 实战指南基于 Whisper 的词级时间戳转录原理与用法【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS导读本文围绕 LifeOS 仓库中 AudioEditor 技能skill的核心工具 Transcribe.ts 展开深入讲解该工具如何借助 insanely-fast-whisperMPS 加速与标准 Whisper CLI 双重后端将任意音频文件转录为带词级时间戳的 JSON 结果。读完本文你将掌握该转录工具的全部命令行参数、输出 JSON 结构与字段语义、后端自动探测与降级逻辑并能把它接入 AudioEditor 的“转录 → 分析 → 剪辑 → 打磨”自动化音频清理流水线。一、工具定位AudioEditor 流水线的第一环AudioEditor 是 LifeOS 中的 AI 音频剪辑技能其核心流水线由四个工具串联而成见 SKILL.md 中的 Pipeline 示意Audio Input | [Transcribe] Whisper word-level timestamps (insanely-fast-whisper on MPS) | [Analyze] Claude classifies each segment: | KEEP / CUT_FILLER / CUT_FALSE_START / CUT_EDIT_MARKER / | CUT_STUTTER / CUT_DEAD_AIR | [Edit] ffmpeg executes cuts: | 40ms qsin crossfades, room tone gap fill, | breath attenuation (50% volume, not removal) | [Polish] (optional) Cleanvoice API final passTranscribe.ts 是整个流水线的第一环它的职责是把一段录音变成“机器可读”的词级时间轴。后续 Analyze.ts 依赖它产出的chunks数组来定位“嗯、啊”之类的填充词、口吃、假起句与超长静音Edit.ts 再依据时间戳执行精准剪切。因此转录质量直接决定了下游剪辑决策的精度。二、安装与运行前提2.1 环境依赖Transcribe.ts 是 Bun 脚本#!/usr/bin/env bun运行需要Bun 运行时脚本内部使用import { $ } from bun执行子进程以及Bun.file、Bun.write等内置 API转录后端二选一insanely-fast-whisper推荐MPS 加速针对 Apple SiliconwhisperOpenAI 标准 whisper CLI作为降级后端若两者都未安装脚本会报错并提示pip install openai-whisper见 Transcribe.ts 的错误分支。2.2 仓库路径与部署路径说明本仓库中该技能位于 LifeOS/install/skills/AudioEditor/。安装部署到用户环境后SKILL.md 通过${LIFEOS_SKILL_DIR}变量引用各工具例如bun ${LIFEOS_SKILL_DIR}/Tools/Transcribe.ts file在 Clean.md 工作流中则直接写为bun ~/.claude/skills/AudioEditor/Tools/Transcribe.ts file三、命令行用法与参数详解3.1 基本调用bun ~/.claude/skills/AudioEditor/Tools/Transcribe.ts audio-file [--output path]从 Transcribe.ts 的参数解析逻辑可知脚本按以下规则解析参数audio-file第一个不以--开头的参数被视作输入音频文件路径必需--output path显式指定输出 JSON 路径--output标志后的下一个参数为其值未提供输入文件时打印用法并退出码 1输入文件不存在时打印File not found: ...并退出码 1。3.2 参数速查表参数类型说明audio-file位置参数必填待转录的音频文件路径支持 mp3/wav/m4a/flac 等 ffmpeg 可解码格式--output path可选指定输出 JSON 路径默认输出到输入文件同目录下的文件名.transcript.json3.3 默认输出路径的构造规则当未指定--output时源码第 32-33 行 使用如下规则const outFile outputPath || join(dirname(inputFile), ${basename(inputFile, . inputFile.split(.).pop())}.transcript.json);即取输入文件的所在目录与“去掉扩展名的文件名 .transcript.json”拼接。例如输入~/Downloads/meeting.mp3默认输出为~/Downloads/meeting.transcript.json。四、输出 JSON 格式详解转录结果遵循 insanely-fast-whisper 的词级时间戳格式包含text与chunks两个顶层字段{ text: Full transcript text..., chunks: [ { text: word, timestamp: [0.0, 0.5] } ] }字段类型语义textstring全文转录文本chunksarray词级时间戳数组每个元素含text单词/词片与timestamp[起始秒, 结束秒]可为null脚本在完成转录后还会回读校验输出源码第 105-109 行解析 JSON 并打印统计Words: chunks 数量 | Text: text 字符数 Saved: 输出路径4.1 下游如何消费这个 JSONAnalyze.ts 读取transcript.chunks后做两阶段分析静音检测无需 LLM遍历相邻 chunk计算当前词起始时间 - 前一词结束时间的间隔超过阈值标准模式 5.0s、--aggressive模式 3.0s就标记为CUT_DEAD_AIR并保留 1 秒的修辞停顿keepPause 1.0只有剪切长度超过 0.5 秒才真正入列LLM 分类将词级时间轴按约 750 词窗口含 150 词重叠切块交 Claude 分类为CUT_FILLER、CUT_FALSE_START、CUT_EDIT_MARKER、CUT_STUTTER、CUT_SELF_CORRECTION、CUT_REDO_TAKE等类型并输出start/end/reason/context/confidence字段。由此可以看出转录 JSON 的chunks质量尤其时间戳精度是整条剪辑决策链的数据基础。五、后端选择与降级机制源码级原理Transcribe.ts 的核心设计是双后端自动探测 优雅降级。5.1 后端探测脚本用which探测两个可执行文件是否可用源码第 39-42 行const hasFastWhisper (await $which insanely-fast-whisper 2/dev/null.quiet().nothrow()).exitCode 0; const hasWhisper (await $which whisper 2/dev/null.quiet().nothrow()).exitCode 0;5.2 首选insanely-fast-whisperMPS 加速若检测到insanely-fast-whisper脚本以如下参数调用源码第 46-52 行insanely-fast-whisper \ --file-name input \ --transcript-path output \ --device-id mps \ --timestamp word \ --model-name openai/whisper-large-v3 \ --batch-size 4关键参数含义参数值作用--device-id mpsmps使用 Apple Metal Performance Shaders 加速推理--timestamp wordword输出词级而非句级时间戳--model-nameopenai/whisper-large-v3使用 large-v3 模型识别精度高--batch-size4批处理大小平衡吞吐与显存若该后端执行失败退出码非 0脚本打印insanely-fast-whisper failed, trying standard whisper...并进入降级分支。5.3 降级标准 whisper CLI降级触发的条件有二未安装 fast-whisper或fast-whisper 执行后输出文件不存在见 源码第 61 行 的if (!hasFastWhisper || !existsSync(outFile))判断。此时使用whisper input \ --model medium \ --language en \ --word_timestamps True \ --output_format json \ --output_dir 临时目录随后脚本会把标准 whisper 的句级 segment.words 输出转换为 insanely-fast-whisper 的统一格式源码第 82-95 行for (const segment of data.segments || []) { for (const word of segment.words || []) { chunks.push({ text: word.word, timestamp: [word.start, word.end] }); } } const fullText chunks.map((c) c.text).join(); await Bun.write(outFile, JSON.stringify({ text: fullText, chunks }, null, 2));这个设计保证了无论走哪条后端路径下游消费方拿到的都是同一套{ text, chunks }结构屏蔽了两种 Whisper 实现的格式差异。六、常见问题与边界处理两个后端都不可用脚本明确报错No whisper variant found. Install: pip install openai-whisper并以退出码 1 终止源码第 62-65 行标准 whisper 未产出 JSON打印Whisper produced no output.并清理临时目录后退出码 1源码第 98-101 行临时目录清理标准 whisper 后端会在输出目录创建.whisper-tmp子目录转换完成后用rm -rf清理不留中间产物转录耗时正如 Clean.md 所提示长文件在 MPS 上转录可能耗时数分钟工作流执行时应设置约 10 分钟的超时。七、与 Pipeline 的协作与产物复用在完整流水线 Pipeline.ts 中第一步正是调用 Transcribebun ${TOOLS_DIR}/Transcribe.ts audio-file --output transcriptFile值得注意的工程细节是转录产物缓存Pipeline 在执行第 1 步前先检查base.transcript.json是否已存在Pipeline.ts 第 59-60 行存在则直接复用、跳过重新转录。这意味着你可以单独运行Transcribe.ts生成转录再反复运行 Analyze/Edit 调参无需重复转录流水线结束后会报告三个产物Transcript转录 JSON、Edits编辑决策 JSON、Audio成品音频。7.1 调试建议单独使用各工具Clean.md 提供了分步调试的推荐路径# 仅转录 bun ~/.claude/skills/AudioEditor/Tools/Transcribe.ts file # 仅分析需要转录结果 bun ~/.claude/skills/AudioEditor/Tools/Analyze.ts transcript.json # 仅剪辑需要音频 编辑决策 bun ~/.claude/skills/AudioEditor/Tools/Edit.ts file edits.json # 仅打磨需要 CLEANVOICE_API_KEY bun ~/.claude/skills/AudioEditor/Tools/Polish.ts file八、运行结果验证与使用提醒8.1 如何验证转录成功脚本退出码 0 且输出 JSON 可被解析即视为成功控制台会给出三行关键信息Transcribing: input Output: output Words: N | Text: N chars Saved: outputWords数即chunks长度可用作质量粗检一段 10 分钟的口语录音通常对应数千个词片。8.2 使用提醒源自 SKILL.md 的实践沉淀转录精度随音频质量浮动背景噪声、多人说话、口音都会降低识别准确率进而影响下游剪辑判断时间戳是剪辑的地基如果发现剪切点偏移优先检查转录 JSON 中对应词片的时间戳是否漂移工作流完成后应记录执行日志按 SKILL.md 的 Execution Log 约定向~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl追加一行 JSONL 记录便于复盘流水线耗时与失败原因。九、相关源码导航内容路径转录工具本文主体Transcribe.ts转录工具帮助文档Transcribe.help.md技能总览与流水线说明SKILL.mdLLM 编辑分类消费转录结果Analyze.tsffmpeg 剪辑执行Edit.ts端到端流水线编排Pipeline.tsClean 工作流Clean.mdAnalyze 依赖的推理封装Inference.ts综上所述Transcribe.ts 通过“insanely-fast-whisper 优先、标准 whisper 兜底”的双后端设计与统一的词级时间戳 JSON 输出为 AudioEditor 的自动化剪辑提供了稳定可靠的第一环理解它的参数、输出结构与降级逻辑是使用和扩展这套音频流水线的第一步。【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LifeOS AudioEditor 的 Transcribe.ts 实战指南：基于 Whisper 的词级时间戳转录原理与用法
LifeOS AudioEditor 的 Transcribe.ts 实战指南基于 Whisper 的词级时间戳转录原理与用法【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS导读本文围绕 LifeOS 仓库中 AudioEditor 技能skill的核心工具 Transcribe.ts 展开深入讲解该工具如何借助 insanely-fast-whisperMPS 加速与标准 Whisper CLI 双重后端将任意音频文件转录为带词级时间戳的 JSON 结果。读完本文你将掌握该转录工具的全部命令行参数、输出 JSON 结构与字段语义、后端自动探测与降级逻辑并能把它接入 AudioEditor 的“转录 → 分析 → 剪辑 → 打磨”自动化音频清理流水线。一、工具定位AudioEditor 流水线的第一环AudioEditor 是 LifeOS 中的 AI 音频剪辑技能其核心流水线由四个工具串联而成见 SKILL.md 中的 Pipeline 示意Audio Input | [Transcribe] Whisper word-level timestamps (insanely-fast-whisper on MPS) | [Analyze] Claude classifies each segment: | KEEP / CUT_FILLER / CUT_FALSE_START / CUT_EDIT_MARKER / | CUT_STUTTER / CUT_DEAD_AIR | [Edit] ffmpeg executes cuts: | 40ms qsin crossfades, room tone gap fill, | breath attenuation (50% volume, not removal) | [Polish] (optional) Cleanvoice API final passTranscribe.ts 是整个流水线的第一环它的职责是把一段录音变成“机器可读”的词级时间轴。后续 Analyze.ts 依赖它产出的chunks数组来定位“嗯、啊”之类的填充词、口吃、假起句与超长静音Edit.ts 再依据时间戳执行精准剪切。因此转录质量直接决定了下游剪辑决策的精度。二、安装与运行前提2.1 环境依赖Transcribe.ts 是 Bun 脚本#!/usr/bin/env bun运行需要Bun 运行时脚本内部使用import { $ } from bun执行子进程以及Bun.file、Bun.write等内置 API转录后端二选一insanely-fast-whisper推荐MPS 加速针对 Apple SiliconwhisperOpenAI 标准 whisper CLI作为降级后端若两者都未安装脚本会报错并提示pip install openai-whisper见 Transcribe.ts 的错误分支。2.2 仓库路径与部署路径说明本仓库中该技能位于 LifeOS/install/skills/AudioEditor/。安装部署到用户环境后SKILL.md 通过${LIFEOS_SKILL_DIR}变量引用各工具例如bun ${LIFEOS_SKILL_DIR}/Tools/Transcribe.ts file在 Clean.md 工作流中则直接写为bun ~/.claude/skills/AudioEditor/Tools/Transcribe.ts file三、命令行用法与参数详解3.1 基本调用bun ~/.claude/skills/AudioEditor/Tools/Transcribe.ts audio-file [--output path]从 Transcribe.ts 的参数解析逻辑可知脚本按以下规则解析参数audio-file第一个不以--开头的参数被视作输入音频文件路径必需--output path显式指定输出 JSON 路径--output标志后的下一个参数为其值未提供输入文件时打印用法并退出码 1输入文件不存在时打印File not found: ...并退出码 1。3.2 参数速查表参数类型说明audio-file位置参数必填待转录的音频文件路径支持 mp3/wav/m4a/flac 等 ffmpeg 可解码格式--output path可选指定输出 JSON 路径默认输出到输入文件同目录下的文件名.transcript.json3.3 默认输出路径的构造规则当未指定--output时源码第 32-33 行 使用如下规则const outFile outputPath || join(dirname(inputFile), ${basename(inputFile, . inputFile.split(.).pop())}.transcript.json);即取输入文件的所在目录与“去掉扩展名的文件名 .transcript.json”拼接。例如输入~/Downloads/meeting.mp3默认输出为~/Downloads/meeting.transcript.json。四、输出 JSON 格式详解转录结果遵循 insanely-fast-whisper 的词级时间戳格式包含text与chunks两个顶层字段{ text: Full transcript text..., chunks: [ { text: word, timestamp: [0.0, 0.5] } ] }字段类型语义textstring全文转录文本chunksarray词级时间戳数组每个元素含text单词/词片与timestamp[起始秒, 结束秒]可为null脚本在完成转录后还会回读校验输出源码第 105-109 行解析 JSON 并打印统计Words: chunks 数量 | Text: text 字符数 Saved: 输出路径4.1 下游如何消费这个 JSONAnalyze.ts 读取transcript.chunks后做两阶段分析静音检测无需 LLM遍历相邻 chunk计算当前词起始时间 - 前一词结束时间的间隔超过阈值标准模式 5.0s、--aggressive模式 3.0s就标记为CUT_DEAD_AIR并保留 1 秒的修辞停顿keepPause 1.0只有剪切长度超过 0.5 秒才真正入列LLM 分类将词级时间轴按约 750 词窗口含 150 词重叠切块交 Claude 分类为CUT_FILLER、CUT_FALSE_START、CUT_EDIT_MARKER、CUT_STUTTER、CUT_SELF_CORRECTION、CUT_REDO_TAKE等类型并输出start/end/reason/context/confidence字段。由此可以看出转录 JSON 的chunks质量尤其时间戳精度是整条剪辑决策链的数据基础。五、后端选择与降级机制源码级原理Transcribe.ts 的核心设计是双后端自动探测 优雅降级。5.1 后端探测脚本用which探测两个可执行文件是否可用源码第 39-42 行const hasFastWhisper (await $which insanely-fast-whisper 2/dev/null.quiet().nothrow()).exitCode 0; const hasWhisper (await $which whisper 2/dev/null.quiet().nothrow()).exitCode 0;5.2 首选insanely-fast-whisperMPS 加速若检测到insanely-fast-whisper脚本以如下参数调用源码第 46-52 行insanely-fast-whisper \ --file-name input \ --transcript-path output \ --device-id mps \ --timestamp word \ --model-name openai/whisper-large-v3 \ --batch-size 4关键参数含义参数值作用--device-id mpsmps使用 Apple Metal Performance Shaders 加速推理--timestamp wordword输出词级而非句级时间戳--model-nameopenai/whisper-large-v3使用 large-v3 模型识别精度高--batch-size4批处理大小平衡吞吐与显存若该后端执行失败退出码非 0脚本打印insanely-fast-whisper failed, trying standard whisper...并进入降级分支。5.3 降级标准 whisper CLI降级触发的条件有二未安装 fast-whisper或fast-whisper 执行后输出文件不存在见 源码第 61 行 的if (!hasFastWhisper || !existsSync(outFile))判断。此时使用whisper input \ --model medium \ --language en \ --word_timestamps True \ --output_format json \ --output_dir 临时目录随后脚本会把标准 whisper 的句级 segment.words 输出转换为 insanely-fast-whisper 的统一格式源码第 82-95 行for (const segment of data.segments || []) { for (const word of segment.words || []) { chunks.push({ text: word.word, timestamp: [word.start, word.end] }); } } const fullText chunks.map((c) c.text).join(); await Bun.write(outFile, JSON.stringify({ text: fullText, chunks }, null, 2));这个设计保证了无论走哪条后端路径下游消费方拿到的都是同一套{ text, chunks }结构屏蔽了两种 Whisper 实现的格式差异。六、常见问题与边界处理两个后端都不可用脚本明确报错No whisper variant found. Install: pip install openai-whisper并以退出码 1 终止源码第 62-65 行标准 whisper 未产出 JSON打印Whisper produced no output.并清理临时目录后退出码 1源码第 98-101 行临时目录清理标准 whisper 后端会在输出目录创建.whisper-tmp子目录转换完成后用rm -rf清理不留中间产物转录耗时正如 Clean.md 所提示长文件在 MPS 上转录可能耗时数分钟工作流执行时应设置约 10 分钟的超时。七、与 Pipeline 的协作与产物复用在完整流水线 Pipeline.ts 中第一步正是调用 Transcribebun ${TOOLS_DIR}/Transcribe.ts audio-file --output transcriptFile值得注意的工程细节是转录产物缓存Pipeline 在执行第 1 步前先检查base.transcript.json是否已存在Pipeline.ts 第 59-60 行存在则直接复用、跳过重新转录。这意味着你可以单独运行Transcribe.ts生成转录再反复运行 Analyze/Edit 调参无需重复转录流水线结束后会报告三个产物Transcript转录 JSON、Edits编辑决策 JSON、Audio成品音频。7.1 调试建议单独使用各工具Clean.md 提供了分步调试的推荐路径# 仅转录 bun ~/.claude/skills/AudioEditor/Tools/Transcribe.ts file # 仅分析需要转录结果 bun ~/.claude/skills/AudioEditor/Tools/Analyze.ts transcript.json # 仅剪辑需要音频 编辑决策 bun ~/.claude/skills/AudioEditor/Tools/Edit.ts file edits.json # 仅打磨需要 CLEANVOICE_API_KEY bun ~/.claude/skills/AudioEditor/Tools/Polish.ts file八、运行结果验证与使用提醒8.1 如何验证转录成功脚本退出码 0 且输出 JSON 可被解析即视为成功控制台会给出三行关键信息Transcribing: input Output: output Words: N | Text: N chars Saved: outputWords数即chunks长度可用作质量粗检一段 10 分钟的口语录音通常对应数千个词片。8.2 使用提醒源自 SKILL.md 的实践沉淀转录精度随音频质量浮动背景噪声、多人说话、口音都会降低识别准确率进而影响下游剪辑判断时间戳是剪辑的地基如果发现剪切点偏移优先检查转录 JSON 中对应词片的时间戳是否漂移工作流完成后应记录执行日志按 SKILL.md 的 Execution Log 约定向~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl追加一行 JSONL 记录便于复盘流水线耗时与失败原因。九、相关源码导航内容路径转录工具本文主体Transcribe.ts转录工具帮助文档Transcribe.help.md技能总览与流水线说明SKILL.mdLLM 编辑分类消费转录结果Analyze.tsffmpeg 剪辑执行Edit.ts端到端流水线编排Pipeline.tsClean 工作流Clean.mdAnalyze 依赖的推理封装Inference.ts综上所述Transcribe.ts 通过“insanely-fast-whisper 优先、标准 whisper 兜底”的双后端设计与统一的词级时间戳 JSON 输出为 AudioEditor 的自动化剪辑提供了稳定可靠的第一环理解它的参数、输出结构与降级逻辑是使用和扩展这套音频流水线的第一步。【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考