Audiobook

Use when your agent needs to build, maintain, or run the local audiobook skill for voice-library management, Step official voice sync, clone voice analysis...

praanmichael@praanmichael

Install

openclaw skills install @praanmichael/step-audiobook

Audiobook

语言切换：当前为中文｜English companion

audiobook 是一套完整的本地有声书工作流，覆盖 4 个阶段：

音色库维护：官方音色同步、用户参考音频分析、付费 clone 准备
剧本准备：txt -> structured-script
角色选角：structured-script -> casting-review -> casting-plan
合成导出：casting-plan -> tts-requests -> segments -> final audio

它面向两类调用者：

人类用户：按步骤查看和修改中间产物
程序调用：读取各脚本的 JSON stdout，以及统一的 artifacts.json

audiobook 不只是“把小说读出来”的 TTS 工具，而是一套围绕音色资产、结构化剧本、角色选角、可重放 TTS 请求和最终音频导出的完整本地工作流。

它的设计原则是：

Step 专属能力继续使用 Step 的原生接口，例如 step-audio-r1.1、官方音色接口、音色复刻接口、stepaudio-2.5-tts
需要长文本理解、角色分析、选角推理的部分，默认使用 step-3.5
当前默认的 step-3.5 调用走的是 Step 的 step_plan reasoning 接口，默认 endpoint 为 https://api.stepfun.com/step_plan/v1
上述 LLM 理解层尽量通过可配置的兼容层实现，便于后续按需替换为其他兼容的 LLM
各阶段中间产物默认落盘，既方便人工审阅和修改，也方便程序按阶段接续执行

能力范围

audiobook 当前覆盖以下能力：

用户可以自行准备一批待克隆音色参考音频；skill 会调用 step-audio-r1.1 对这些音频做声音特点分析，沉淀成后续角色选角可用的基础画像。
用户可以在分析结果基础上，挑选自己认可的候选音色，显式决定是否在 StepFun 开放平台上执行真正的音色复刻；这一步属于付费动作，不会在默认流程中被自动触发。
skill 会自动整合 StepFun 官方系统音色、用户已经完成复刻的音色，以及用户本地维护的待确认音色分析结果，形成统一的音色库与统一音色候选池。
基于用户提供的一套原始文本文件，skill 会默认使用 step-3.5 做分块、章节感知、角色分析和结构化整理，生成一个包含旁白在内的 characters + structured-script 剧本结果；当前默认使用的就是 Step 的 step_plan 推理接口。
基于结构化剧本和统一音色库，skill 会进一步产出一套角色与音色整合后的选角方案；这类依赖语义理解和推理的环节默认使用 step-3.5，但整体实现尽量不依赖写死的 NLP 规则，而是通过可替换的 LLM 配置层完成，便于后续切换到其他兼容 LLM。
基于选角结果，skill 会生成一份符合 stepaudio-2.5-tts 调用习惯的可重放 TTS 请求清单，便于后续批量合成、局部重跑和参数调整。
skill 支持按段合成音频，并将多个 segment 进一步拼接为一个或多个最终音频文件，包括整本导出和局部试听导出。
上述各阶段的关键中间产物都允许用户人工介入修改；用户既可以按步骤审阅，也可以在修改后从某个中间阶段继续重跑，而不必每次都从头开始。

术语约定

结构化剧本：对应英文 structured script
统一音色候选池：对应英文 unified voice candidate pool
生效画像：对应英文 effective profile，即 clone 音色真正参与选角的描述集合
付费 clone：对应英文 paid clone，即真正调用 Step 音色复刻接口的动作
中间产物：对应英文 intermediate artifacts
人工确认：对应英文 human review 或 manual confirmation
ready 音色：对应英文 ready voice，表示当前已经可以直接进入下游 TTS

LLM 可替换边界

当前需要重点说明的是：并不是整个 skill 的所有能力都可以替换成别的模型。

默认可替换的部分：长文本结构化、角色提取、选角推理等 LLM 理解环节
这些环节当前默认使用 step-3.5，且默认走 https://api.stepfun.com/step_plan/v1
默认不替换的部分：step-audio-r1.1 音频分析、Step 官方音色拉取、Step 音色复刻、stepaudio-2.5-tts 合成
也就是说，audiobook 当前是“Step 音频能力 + 可替换 LLM 推理层”的组合架构，而不是把所有能力都抽象成完全可替换的通用 provider

默认路径

下面这些路径是当前 skill 的默认约定：

bash

WORKSPACE_ROOT=~/.openclaw/workspace
SKILL_ROOT=$WORKSPACE_ROOT/skills/audiobook
EXAMPLES_ROOT=$SKILL_ROOT/examples
VOICE_LIBRARY=$WORKSPACE_ROOT/audiobook-library/voice-library.yaml
LIBRARY_ROOT=$WORKSPACE_ROOT/audiobook-library
STORY_ROOT=$WORKSPACE_ROOT/audiobook-stories          # 推荐放原始 txt / yaml / json
RUN_ROOT=$WORKSPACE_ROOT/runs/audiobook

下面所有命令示例默认都在 "$SKILL_ROOT" 目录里执行。也就是说，推荐先：

bash

cd "$SKILL_ROOT"

如果你不想切换目录，请把文档里的 scripts/<name>.py 改成对应脚本的绝对路径。

关键位置：

音色库入口：$VOICE_LIBRARY
用户待分析音频投递区：$LIBRARY_ROOT/voices/inbox/
长期参考音频目录：$LIBRARY_ROOT/voices/references/<asset_id>/
音色分析 / cache / 统一音色候选池：$LIBRARY_ROOT/.audiobook/
每本书的中间产物与最终产物：$RUN_ROOT/<slug>/
轻量参考示例：$EXAMPLES_ROOT/

推荐但不强制：把原始小说文件统一放在 ~/.openclaw/workspace/audiobook-stories/。脚本支持任意绝对路径输入，但统一目录更方便程序化管理。

运行前准备

在执行任何主流程前，确保：

环境里有 STEP_API_KEY
系统已安装 ffmpeg
最终导出或时长探测时，系统已安装 ffprobe

安全与付费提示

audiobook 现在建议显式调用，不建议依赖隐式注入；这是一个会读写本地文件、并可能访问外部 API 的工作流型 skill。
默认的音频分析、官方音色、音色复刻、TTS 合成都会访问 Step 相关接口；长文本理解层如果你改了 voice-library.yaml -> llm.*.base_url，则会访问你自己配置的兼容 LLM endpoint。
建议优先使用测试 key、受限 key，或至少在第一次运行后做轮换；如果你不完全信任当前配置，先在隔离环境或沙箱里跑一遍。
ffmpeg / ffprobe 请只从可信来源安装。
真正可能触发付费的只有 clone_selected_voices.py；而且现在除了 selected_for_clone=true 之外，还必须显式传入 --confirm-paid-action 才会执行正式 clone。
run_audiobook.py 默认只会对 clone 阶段做 --dry-run 预览，不会自动代替你执行正式付费 clone。
如果你在做安全审查，或想确认默认会访问哪些 endpoint、会读取哪些环境变量，直接看 references/security.md。

如果本地还没有 voice-library.yaml，先用模板初始化：

bash

mkdir -p "$LIBRARY_ROOT"
cp \
  "$SKILL_ROOT/assets/voice-library.template.yaml" \
  "$VOICE_LIBRARY"

如果你希望在第一次 ingest 前就看到带注释的人工审核骨架，也可以顺手初始化：

bash

cp \
  "$SKILL_ROOT/assets/voice-reviews.template.yaml" \
  "$LIBRARY_ROOT/voice-reviews.yaml"

最小示例

examples/ 目录现在提供 7 个轻量示例，适合先理解结构，再复制到自己的工作区继续改：

examples/story-minimal.txt：最小原始小说文本
examples/story-minimal.structured-script.yaml：对应的最小结构化剧本
examples/voice-library.minimal.yaml：最小音色库配置示例
examples/voice-reviews.minimal.yaml：最小人工审核示例
examples/story-minimal.casting-plan.yaml：最小可下游继续的选角结果示例
examples/story-minimal.tts-requests.json：最小可 replay 的 TTS 请求示例
examples/story-minimal.script-runtime.json：由 build_tts_requests.py 生成的规范化剧本 companion

使用原则：

真正初始化库文件时，优先复制 assets/*.template.yaml
examples/*minimal* 更适合“照着看结构”“复制局部片段”“给程序做字段对齐”
examples/*.json / *.yaml 里的路径字段已经改成 $EXAMPLES_ROOT / $RUN_ROOT 占位，不包含本机绝对路径
不建议把 examples/voice-library.minimal.yaml 直接当成长期运行时库文件

最常用的入口

一次性跑完整主流程时，优先用：

bash

python3 scripts/run_audiobook.py --library "$VOICE_LIBRARY" --story-input /绝对路径/小说.txt

这条命令会按顺序尝试：

刷新官方音色 cache
处理 --voice-input 或 --process-inbox 指定的新音频
如果输入是 txt，先生成 structured-script
生成 casting-review、casting-plan、clone-review
预览本次哪些 clone 值得付费复刻
当角色和 clone 状态允许继续时，再进入 tts-requests -> synthesize -> finalize

如果你要分步执行，建议顺序见 references/workflows.md。

中间产物怎么查看

每本书都有一份统一清单：

text

~/.openclaw/workspace/runs/audiobook/<slug>/<base>.artifacts.json

它会列出：

源文本 / 结构化剧本
选角审核与生效结果
音色库侧的 voice-reviews、effective-voice-library、voice-candidate-pool、official-voices-cache
script-runtime、tts-requests
segments/
最近一次导出与最终成品

人类查看时：

bash

python3 scripts/list_story_artifacts.py --manifest /绝对路径/<base>.artifacts.json --level review --pretty

程序调用时：直接读取 artifacts.json 即可，不需要硬编码路径推导。

如果你只想快速看音色库里还有哪些 clone 描述待人工确认，用：

bash

python3 scripts/list_pending_reviews.py --library "$VOICE_LIBRARY" --pretty

哪些文件可以改，哪些文件不要改

建议人工编辑的文件：

voice-reviews.yaml
*.casting-review.yaml
*.clone-review.yaml
*.structured-script.yaml
*.tts-requests.json

不建议直接编辑的生成文件：

.audiobook/effective-voice-library.yaml
.audiobook/voice-candidate-pool.yaml
.audiobook/official-voices-cache.json
*.casting-plan.yaml（除非你明确知道自己在做什么）
*.script-runtime.json
*.artifacts.json

改完后的重跑命令见 references/editing.md。

两套 `.audiobook/` 的区别

这是最容易混淆的点：

~/.openclaw/workspace/audiobook-library/.audiobook/：音色库侧生成文件
~/.openclaw/workspace/runs/audiobook/<slug>/.audiobook/：某本书本次运行的 trace / debug 文件

前者服务整个音色库；后者只服务单次故事流程。

付费边界

clone_selected_voices.py 是唯一会触发付费 clone 的步骤。默认流程只会：

分析参考音频
生成 clone 候选
在 clone-review.yaml 里等待确认

真正执行前请先跑：

bash

python3 scripts/clone_selected_voices.py --library "$VOICE_LIBRARY" --dry-run

正式执行时，现在必须额外确认：

bash

python3 scripts/clone_selected_voices.py --library "$VOICE_LIBRARY" --confirm-paid-action

机器可读接口

下面这些脚本都输出 JSON 到 stdout，适合程序调用：

sync_voice_library.py
generate_structured_script.py
recommend_casting.py
build_tts_requests.py
synthesize_tts_requests.py
finalize_audiobook.py
run_audiobook.py

对程序来说，最稳的组合是：

调主脚本拿 stdout JSON
再读取 artifacts.json 拿完整文件清单

参考文档索引 / Reference Index

如果你是人类用户，建议优先看中文；如果你是英文环境下的 agent 或程序，可直接读对应的英文 companion 文档。

完整执行顺序 / full workflow：中文 references/workflows.md｜English references/workflows.en.md
音色库结构与字段 / voice library structure：中文 references/voice-library.md｜English references/voice-library.en.md
结构化剧本格式 / structured script format：中文 references/script-format.md｜English references/script-format.en.md
选角规则与输出 / casting rules and outputs：中文 references/casting.md｜English references/casting.en.md
TTS、replay 与最终导出 / synthesis and export：中文 references/synthesis.md｜English references/synthesis.en.md
人工修改与重跑 / manual editing and reruns：中文 references/editing.md｜English references/editing.en.md
安全与外部访问 / security and external access：中文 references/security.md｜English references/security.en.md

如果你只是想快速进入某个主题，推荐顺序是：

想看整体链路：先读 references/workflows.md
想维护音色库：再读 references/voice-library.md
想修改中间产物：直接读 references/editing.md

Audiobook

Install

Audiobook

能力范围

术语约定

LLM 可替换边界

默认路径

运行前准备

安全与付费提示

最小示例

最常用的入口

推荐命令顺序

1. 音色库同步 / 音频分析

2. 原始小说转结构化剧本

3. 生成角色选角结果

4. 构建可重放的 TTS 请求

5. 实际合成分段音频

6. 导出整本或试听片段

中间产物怎么查看

哪些文件可以改，哪些文件不要改

两套 `.audiobook/` 的区别

付费边界

机器可读接口

参考文档索引 / Reference Index

Audiobook

Install

Audiobook

能力范围

术语约定

LLM 可替换边界

默认路径

运行前准备

安全与付费提示

最小示例

最常用的入口

推荐命令顺序

1. 音色库同步 / 音频分析

2. 原始小说转结构化剧本

3. 生成角色选角结果

4. 构建可重放的 TTS 请求

5. 实际合成分段音频

6. 导出整本或试听片段

中间产物怎么查看

哪些文件可以改，哪些文件不要改

两套 .audiobook/ 的区别

付费边界

机器可读接口

参考文档索引 / Reference Index

Related skills

两套 `.audiobook/` 的区别