Skip to content
角色与演员音色链路

角色与演员音色链路

本文属于“当前架构”文档,描述当前真实生效的实现。

背景

短剧配音要求同一个「人」在整部剧(乃至跨剧集复用同一演员)里保持同一声线。若音色只能挂在角色上,同一演员演十个角色就要重复配十次,且没有「这个人本来的声音」这一层概念。因此当前实现是两级音色 + 显式覆盖:

  • 演员音色 = 某个「人」的默认音色(第一优先级来源,复用时不重复配置)。
  • 角色音色 = 针对具体角色的覆盖项(有对白的角色才需要)。

绑定演员不是角色的必填项(见 角色与演员的绑定要求),因此没有绑定演员的角色必须在角色上自己配 voice_id: 解析链的最后一层回退来自所绑演员,没有演员就没有这一层,配音会在 _validate_audio_request 处直接 422。 开工预检的 character_voice_ready 检查项就是按这个口径统计的。

数据模型

三列在两个表上口径完全一致,都是 NULL 表示未指定:

列charactersactors语义
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_urlhttps://openspeech.bytedance.com
Provider api_key火山控制台「豆包语音」API Key(新版控制台单头 X-Api-Key)
Model name豆包语音合成 2.0
Model categoryaudio
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 曾因此改不动)。