角色与演员音色链路
本文属于“当前架构”文档,描述当前真实生效的实现。
背景
短剧配音要求同一个「人」在整部剧(乃至跨剧集复用同一演员)里保持同一声线。若音色只能挂在角色上,同一演员演十个角色就要重复配十次,且没有「这个人本来的声音」这一层概念。因此当前实现是两级音色 + 显式覆盖:
- 演员音色 = 某个「人」的默认音色(第一优先级来源,复用时不重复配置)。
- 角色音色 = 针对具体角色的覆盖项(有对白的角色才需要)。
绑定演员不是角色的必填项(见 角色与演员的绑定要求),因此没有绑定演员的角色必须在角色上自己配 voice_id:
解析链的最后一层回退来自所绑演员,没有演员就没有这一层,配音会在 _validate_audio_request 处直接 422。
开工预检的 character_voice_ready 检查项就是按这个口径统计的。
数据模型
三列在两个表上口径完全一致,都是 NULL 表示未指定:
| 列 | characters | actors | 语义 |
|---|---|---|---|
voice_id | 迁移 016 | 迁移 019 | 供应商侧音色 ID(varchar(64),索引 ix_<table>_voice_id) |
voice_source | 迁移 016 | 迁移 019 | 音色来源 preset / custom(varchar(32);为空时按模型名推断) |
voice_description | 迁移 016 / 018 | 迁移 019 | 音色描述(年龄段/声线/气质/语速),由剧本提取产出,供配音选型参考 |
actors的三列由backend/sql/019-add-actor-voice.sql建立(幂等:先经information_schema判定再执行,可被 compose 重复执行)。voice_description在 ORM 侧是Text, nullable=False, default="",DDL 侧同步收紧为TEXT NOT NULL(MySQL 不允许 TEXT 默认值,空串只能由 SQLAlchemy 客户端补)。迁移 018 对characters做过同样的收紧,actors在 019 内一次完成(ADD NULL→ 回填 →MODIFY NOT NULL)。- 迁移 019 会建索引
ix_actors_voice_id,与 ORM 的index=True(SQLAlchemy 默认命名)对齐。
契约侧:AudioVoiceSource 定义在 app/core/contracts/audio_generation.py,被 schema 直接复用。
音色解析顺序
app/services/studio/audio_task_runner.py::_resolve_audio_voice:
显式传入的 voice(调用方最清楚,最高优先级)
→ characters.voice_id(角色级覆盖)
→ 该角色所绑演员的 actors.voice_id(演员级默认)
→ 都没有:返回 (None, voice_source),由 _validate_audio_request 统一报 422- 「显式入参优先」保证调用方(如分镜台词配音)能指定具体音色而不被实体配置覆盖。
voice_source始终跟随实际取到音色的那一层:只有调用方没显式给voice_source时才回填,避免覆盖调用方的显式指定。- 角色未绑定演员(
actor_id为空)或演员行不存在时直接返回未解析,不做名字匹配。
供应商音色列表
接口:GET /api/v1/studio/audio-tasks/voices?model_id=<id>&kind=preset|custom
- 响应:
ApiResponse[list[VoiceItem]]。 VoiceItem分两层字段:- 通用字段:
voice_id/name/language/raw; - 火山豆包语音扩展:
gender/age/categories/languages/emotions/description/trial_url/avatar_url/resource_id/labels/heat/emoji。
- 通用字段:
- 支持的供应商:
compshare_model_api:转发优云智算 IndexTTS 的GET /audio/v1/voices;volcengine_speech:读取仓库内置的 466 个seed-tts-2.0预置音色目录,不发起网络请求;- 其它供应商:
HTTPException(400, "Provider ... does not expose a voice list API"),前端按预期降级处理。
火山引擎豆包语音
供应商与模型配置
volcengine_speech 是与火山方舟(图片/视频,volcengine)并列的独立供应商:语音合成走 https://openspeech.bytedance.com,API Key 体系不同,必须单独一行 Provider。
| 配置 | 值 |
|---|---|
| Provider name | 火山引擎语音(豆包语音) |
| Provider base_url / audio_base_url | https://openspeech.bytedance.com |
| Provider api_key | 火山控制台「豆包语音」API Key(新版控制台单头 X-Api-Key) |
| Model name | 豆包语音合成 2.0 |
| Model category | audio |
| Model params | {"resource_id":"seed-tts-2.0","format":"mp3"} |
resource_id 会作为 X-Api-Resource-Id 下发;format 作为模型默认输出格式,调用方显式传 format 时优先。当前只开放 mp3 / wav;seed-icl-2.0 声音复刻尚未接入。
接口与返回
- 端点:
POST /api/v3/tts/unidirectional(HTTP Chunked + NDJSON); - 鉴权:
X-Api-Key+X-Api-Resource-Id+X-Api-Request-Id; - 文本上限 3000 字符;语速
0.5–2.0映射为火山speech_rate -50..100; - 2.0 音色的自然语言情绪通过
context_texts下发; - 返回的 base64 音频分片由适配器拼接,任务结果只保存落库后的
file_id,不把数 MB base64 写进generation_tasks.result; - 音频落库按
mime_type推断后缀(mp3/wav),不会误命名为.png。
任务队列
audio_generation 走独立 audio 队列,不再落到默认 celery 队列:
# 单机联调:一个 worker 同时消费三类任务
celery -A app.core.celery_app.celery_app worker -Q video,audio,celery -c 1
# 生产建议:音频单独 worker,避免被长视频任务挤占
celery -A app.core.celery_app.celery_app worker -Q audio -c 2本地验证
GET /api/v1/studio/audio-tasks/voices?model_id=<豆包模型ID>
POST /api/v1/studio/audio-tasks/speech
{"model_id":"<豆包模型ID>","text":"…","voice":"zh_female_vv_uranus_bigtts","shot_id":"<镜头ID>"}2026-11-13 本地实测:1.4 秒完成合成,返回 audio/mpeg 文件;generation_tasks.result 含 file_id、provider=volcengine_speech、mime_type=audio/mpeg。
P4 工作台入口
front/src/features/workbench/panels/AssetDetailPanel.tsx 在角色详情中提供:
- 当前生效音色与来源(角色覆盖 / 回退演员);
- 供应商音色列表选择、音色来源、音色描述;
- 可选试听(供应商
raw中提供audio_url/preview_url/url时); - 绑定/解除绑定;视觉身份锁定不影响音色修改。
API:GET/PATCH /api/v1/studio/projects/{pid}/assets/character/{cid}/voice。
底层仍使用既有 characters.voice_* 与 _resolve_audio_voice,不新增回退规则。
视频 Prompt 中的声音描述(P9-C)
characters.voice_description 除用于 TTS 选型外,也会进入 H3 视频 Prompt:
build_shot_video_prompt_pack按ShotDialogLine.speaker_character_id读取角色;IRDialogueLine.voice_description传递到 H3 Renderer;- 没有
<Audio N>音色参考时,台词句使用using this voice profile: <英文声学描述>, says, <d>…</d>,描述放在<d>之前; - 有
<Audio N>音色参考时,IR 会清空该台词的声音描述,Prompt 只保留in the voice timbre referenced from <Audio N>,不再输出Use this voice profile; retention_analysis的<Audio N>行必须写明:its vocal timbre and delivery guide <Subject N> (Sx), while the spoken words are exactly those inside <d>; the reference audio's own words are not reused.这是防止 H3 把参考音频原词一起复读的关键约束。
参考音频与台词同文
当 <Audio N> 就是本句台词的配音时(audio_is_same_line=true):
- 台词后追加:
The reference audio <Audio N> contains this same sentence; it is used for timbre only, and the sentence inside <d> is spoken exactly once without being repeated, extended, or replaced. retention_analysis改为:contains the same sentence and is not replayed;- 预览 warning 提示:短句配音常低于 H3 的 2 秒下限,建议改用 3–10 秒、内容不同的固定音色样本;
- 固定音色样本上传时按 2–15 秒校验(有 ffprobe 时)。
2026-11-13 实测:同文参考与不同文样本各跑一条 5 秒,ASR 都只转写出一遍台词;同文参考的输出与参考音频波形互相关仅 0.077,说明 H3 没有直接复制参考音轨。
边界:
- 文字描述只约束模型,不锁定音色身份;
- 系统不根据角色名、参考照片或演员资料推断性别/声音;
- 需要稳定音色时,使用项目“参考音频”与固定音色样本,而不是只写文字描述;
- 声音描述不得放在
</d>之后,也不得包含“适合广告旁白”等用途评价,避免被 H3 当成台词朗读。
旧版前端入口
- 复用组件
front/src/pages/aiStudio/components/VoiceSelectField.tsx:value是供应商侧voice_id(string | null,不是对象),onChange回传VoiceChoice = {voice_id, voice_source}。- 供应商列表里没有的已保存
voice_id会以__saved__:前缀补一条选项(label已保存:<id>),避免用户因为「看不见」而误把已有配置清空。 - 拉取失败时降级为「仅显示已保存音色」并给出说明,不阻塞编辑。
- 供应商列表里没有的已保存
- 角色编辑表单(
tabs/RolesTab.tsx):音色类型(preset/custom)+VoiceSelectField+ 音色描述。演员下拉下方常驻说明:系统不做名字匹配,同名演员也要显式绑定;同名只作为「一键绑定」建议由用户确认。 - 演员编辑表单(
assets/components/ActorEntityFormModal.tsx):同样的三字段,文案说明「角色未单独配置音色时,配音将回退使用该演员音色」。 - 独立页面「音色管理」(
front/src/pages/aiStudio/voice/VoiceManager.tsx,路由/voices,主菜单在「模型管理」之后):三个页签 —— ① 供应商音色列表(含「已被角色直接引用」反查);② 演员默认音色(逐行VoiceSelectField,直接PATCH演员);③ 角色生效音色(显示「角色音色(覆盖演员)」或「回退演员「X」的音色」,两者都没有时明确警告「配音时会直接报错」)。
写接口语义
演员与角色的音色都通过实体更新接口写入:PATCH /api/v1/studio/entities/{entity_type}/{entity_id}。
entity_crud.py用spec.update_model.model_validate(body).model_dump(exclude_unset=True),因此请求体里显式出现voice_id: null才会真正清空该列;字段缺席表示「不改动」。CharacterUpdate/ActorUpdate都不继承各自的 Base、显式声明全部可改字段:漏声明会让该字段在 PATCH 时被静默忽略(评审 C-3 中voice_description曾因此改不动)。