桌面应用语音【免费下载链接】voicevox無料で使える中品質なテキスト読み上げソフトウェア、VOICEVOXのエディター项目地址https://gitcode.com/gh_mirrors/vo/voicevox点击查看免费下载导读本文基于 VOICEVOX 编辑器的官方开发文档 docs/ソングのレンダリング.md 及其配套流程图深入剖析编辑器内ソング歌曲渲染的完整实现从 Vuex 的RENDER动作入口到SongTrackRenderer的框架生成、缓存复用、引擎 API 调用与事件通知直至最终歌声数据落库的每一步。读完本文你将理解 VOICEVOX 如何把钢琴卷帘上的音符按休符切分成フレーズPhrase如何以再生ヘッド播放头为基准按优先级逐段合成歌声以及为什么反复编辑时渲染能如此迅速——一切答案都藏在快照Snapshot与四层缓存Query/Pitch/Volume/Voice的设计中。一、ソングレンダリングの全体像从RENDER动作到歌声合成在 VOICEVOX 中ソングのレンダリング歌曲渲染指的是将钢琴卷帘上的音符数据转换为实际歌声数据的整条流水线其中包括对歌声合成引擎 API 的调用。根据官方文档这条流水线由两个核心角色驱动RENDER动作位于 src/store/song.ts 的SongStore中负责编排渲染的启动、重启动、停止以及渲染循环的调度。SongTrackRenderer.render()位于 src/song/songTrackRendering.ts是真正执行渲染逻辑的类负责框架生成、缓存管理、引擎连携和事件通知。用户操作编辑音符/移动播放头 │ ▼ SongStore 的 RENDER action ──► SongTrackRenderer.render(snapshot) │ ├─ generatePhrases按休符切分框架 ├─ filterRenderablePhrases ├─ applyCachedDataToPhrases读缓存 ├─ filterPhrasesRequiringRender └─ 逐框架渲染Query → Pitch → Volume → Voice文档同时提供了完整的 Mermaid 流程图 docs/res/ソングのレンダリングのフローチャート.md本文后续将结合该流程图逐段解读。二、核心数据结构SnapshotForRender与PhraseForRender2.1SnapshotForRenderスナップショット渲染过程中用户可能仍在编辑音符、修改速度等若直接读取实时状态会导致渲染结果与画面不一致。因此 VOICEVOX 在渲染开始前对项目数据做一次快照渲染全程只基于这份不可变拷贝进行。// src/song/songTrackRendering.ts export type SnapshotForRender Readonly{ tpqn: number; // Ticks Per Quarter Note每四分音符的 tick 数 tempos: Tempo[]; // 速度BPM序列 tracks: MapTrackId, Track; // 全部音轨 trackOverlappingNoteIds: MapTrackId, SetNoteId; // 各音轨上重叠的 NoteId渲染时剔除 engineFrameRates: MapEngineId, number; // 各引擎的帧率frameRate editorFrameRate: number; // 编辑器侧帧率 defaultLyricMode: doremi | la; // 缺省歌词模式do-re-mi 或 la };快照的实际构造逻辑在SongStore.RENDER动作内的createSnapshot()src/store/song.tstpqn、tempos、tracks直接取自 store state其中tempos与tracks使用cloneWithUnwrapProxy深拷贝见 src/helpers/cloneWithUnwrapProxy.ts避免 Vuex Proxy 干扰trackOverlappingNoteIds通过getters.OVERLAPPING_NOTE_IDS(trackId)获取engineFrameRates从state.engineManifests中提取每个引擎的frameRatedefaultLyricMode取自state.defaultLyricMode。2.2PhraseForRenderフレーズフレーズ是渲染的基本单位由音轨中的音符按休符切分而成。它同时承载渲染的输入音符与输出中间/最终数据并且是可变ミュータブル对象——渲染过程中它的属性会被逐步填充。// src/song/songTrackRendering.ts export type PhraseForRender { readonly firstRestDuration: number; // 框架先头休符时长tick readonly notes: Note[]; // 属于该框架的音符 readonly startTicks: number; // 框架起始 tick readonly endTicks: number; // 框架结束 tick readonly startTime: number; // 框架起始时间秒 readonly minNonPauseStartFrame: number | undefined; // 非休止区间最小起始帧 readonly maxNonPauseEndFrame: number | undefined; // 非休止区间最大结束帧 readonly trackId: TrackId; // 所属音轨 queryKey?: EditorFrameAudioQueryKey; // 查询缓存键 query?: EditorFrameAudioQuery; // 音素タイミング音素时机查询 singingPitchKey?: SingingPitchKey; // 歌唱音高缓存键 singingPitch?: SingingPitch; // 歌唱音高f0 序列 singingVolumeKey?: SingingVolumeKey; // 歌唱音量缓存键 singingVolume?: SingingVolume; // 歌唱音量序列 singingVoiceKey?: SingingVoiceKey; // 歌声缓存键 singingVoice?: SingingVoice; // 最终歌声数据 };其中minNonPauseStartFrame/maxNonPauseEndFrame用于界定非休止发音区间的帧范围后续的音素时机调整、音量淡出等操作都以它为边界确保框架间的呼吸声不会重叠。三、SongTrackRendererソングトラックのレンダラーSongTrackRenderersrc/song/songTrackRendering.ts承担五项核心职责与文档描述一一对应职责实现要点渲染执行render(snapshot)方法框架生成 → 缓存应用 → 逐框架合成缓存活用内部持有 4 个缓存 MapqueryCache、singingPitchCache、singingVolumeCache、singingVoiceCache引擎连携通过注入的engineSongApi接口调用引擎 API事件通知addEventListener/removeEventListener注册监听器dispatchEvent广播 9 种渲染事件中断处理requestRenderingInterruption()请求中断isRendering暴露渲染状态3.1 构造函数与渲染配置// src/song/songTrackRendering.ts constructor(args: { config: SongTrackRenderingConfig; engineSongApi: EngineSongApi; playheadPositionGetter: () number; }) { ... }渲染配置SongTrackRenderingConfig包含三个可调参数其实际取值在CREATE_AND_SETUP_SONG_TRACK_RENDERER动作中给出src/store/song.tsconfig: { lastRestDurationSeconds: 0.5, // 框架末尾追加的休止时长秒 fadeOutDurationSeconds: 0.15, // 末尾 pau 段淡出时长秒 firstRestMinDurationSeconds: 0.12, // 框架先头休符的最小时长秒 }engineSongApi将引擎调用桥接到 store 动作fetchFrameAudioQuery→FETCH_SING_FRAME_AUDIO_QUERY、fetchSingFrameF0→FETCH_SING_FRAME_F0、fetchSingFrameVolume→FETCH_SING_FRAME_VOLUME、frameSynthesis→FRAME_SYNTHESIS。playheadPositionGetter则读取实时播放头位置供后续就近优先的框架选择使用。3.2 渲染结果类型export type SongTrackRenderingResult | { readonly type: complete; readonly phrases: MapPhraseKey, PhraseForRender; } | { readonly type: interrupted; };正常完成返回complete及全部框架被中断则返回interrupted。render()内部以finally保证无论成功、中断还是异常都会复位interruptionRequested与_isRendering避免死锁。四、レンダリングの流れ逐段深度解析本节对照文档步骤与 src/store/song.ts 的RENDER动作实现。4.1 第一步确认 Renderer 实例未创建则初始化RENDER动作首先检查模块级变量songTrackRenderer是否存在若不存在调用CREATE_AND_SETUP_SONG_TRACK_RENDERER动作创建实例、配置引擎 API 桥接与播放头 getter并注册全部事件监听器见 src/store/song.ts。4.2 第二步渲染循环状态检查重渲染请求mutations.SET_START_RENDERING_REQUESTED({ startRenderingRequested: true }); // 渲染中なら中断を要求して終了 if (songTrackRenderer.isRendering) { songTrackRenderer.requestRenderingInterruption(); return; }若上一次渲染仍在进行例如用户快速连续编辑则只置位开始渲染请求并请求中断当前渲染后立即返回。RENDER动作随后进入外层while循环while (state.startRenderingRequested !state.stopRenderingRequested) { mutations.SET_START_RENDERING_REQUESTED({ startRenderingRequested: false }); const snapshot createSnapshot(); // ③-1 快照 await songTrackRenderer.render(snapshot); // ③-2 渲染循环 }只要开始请求为真且停止请求为假循环就会重新生成快照并再次渲染——这就是渲染中请求重渲染 → 中断 → 重启动的机制。STOP_RENDERING动作src/store/song.ts则置位stopRenderingRequested并等待nowRendering变为false实现优雅停止。4.3 渲染循环SongTrackRenderer.render内部③-1createSnapshot项目快照见 2.1 节不再赘述。③-2generatePhrases框架生成 → 发PhrasesGeneratedEvent框架生成分三层剔除重叠音符generatePhrases从音轨音符中过滤掉trackOverlappingNoteIds标记的重叠音符重叠音符无法确定语义不参与渲染。按休符切分extractPhraseNotessrc/song/songTrackRendering.ts顺序扫描音符一旦发现当前音符结束位置 ! 下一个音符开始位置存在空隙就切出一个新框架。这印证了文档所述フレーズは、ノーツを休符で区切ることによって生成されます。框架属性计算createPhrasesFromNotescalcPhraseFirstRestDuration计算框架先头休符时长。首小节的第一个框架若从 0 tick 开始则先取四分音符长度否则取到上一框架末音符的实际空隙并夹取在四分音符长度与最小时长0.12s之间且至少 1 tickminNonPauseStartFrame/maxNonPauseEndFrame结合上一框架的结束帧与下一框架的起始音符使用interpByDiff(a, b, k, p)src/song/songTrackRendering.ts计算框架间的平滑边界时间再换算为帧号框架键PhraseKey对{ firstRestDuration, notes, startTime, trackId }计算哈希calculatePhraseKey见 src/song/domain.ts。生成完毕后通过dispatchEvent发出PhrasesGeneratedEvent携带框架 Map 的浅拷贝与快照防止外部修改内部数据。此时框架尚未包含任何音频数据或详细参数。③-3filterRenderablePhrases提取可渲染框架只有该框架所属音轨的singer歌手与singingTeacher歌い方都已分配的框架才可渲染src/song/songTrackRendering.ts。未分配歌手的音轨对应框架会被跳过。③-4applyCachedDataToPhrases缓存应用 → 发CacheLoadedEvent对每个可渲染框架按Query → Pitch → Volume → Voice的顺序逐一尝试读取缓存src/song/songTrackRendering.ts计算 Query 缓存键并查queryCache命中则写入phrase.queryKey/phrase.query未命中则continue跳到下一个框架因为后续 Pitch 的生成依赖 Query命中 Query 后计算 Pitch 键查singingPitchCache未命中同样跳到下一框架依此类推 Volume、Voice。全部处理完后发出CacheLoadedEvent。这正是缓存命中链的设计只要链路中任一层缺失其后各层都不会尝试命中而是留给后续实际渲染阶段补齐。③-5filterPhrasesRequiringRender提取真正需要渲染的框架若框架的query、singingPitch、singingVolume、singingVoice任一为undefined说明缓存未完全覆盖进入待渲染集合src/song/songTrackRendering.ts。③-6 逐框架渲染selectPriorPhraserenderPhrase主循环条件为待渲染框架非空且无中断请求while (phrasesToRender.size 0 !this.interruptionRequested) { const phraseKey selectPriorPhrase(phrasesToRender, this.playheadPositionGetter()); ... try { await this.renderPhrase(phrase, phraseKey, snapshot); } catch (error) { this.dispatchEvent({ type: phraseRenderingError, phraseKey, error }); continue; // 出错框架跳过继续下一个 } }selectPriorPhrase的优先级规则src/song/domain.ts优先选择播放头位置包含在内的框架若无选择播放头之后最近的框架若无选择播放头之前最近的框架。该逻辑由单测 tests/unit/lib/selectPriorPhrase.spec.ts 验证测试构造 5 个连续框架将播放头置于第 3 个框架内断言选择顺序依次为包含播放头的框架 → 其后的框架按时间近→远→ 其前的框架按时间近→远并在空集合时抛错phraseRanges.size is 0.。这就是文档所述再生ヘッドに近いフレーズから優先的に処理的实现。renderPhrase的四阶段流水线src/song/songTrackRendering.ts阶段触发条件引擎 API完成后事件① 框架渲染开始——PhraseRenderingStartedEvent② クエリ音素タイミング生成query未生成fetchFrameAudioQueryQueryGenerationCompleteEvent③ 歌唱ピッチ生成singingPitch未生成fetchSingFrameF0PitchGenerationCompleteEvent④ 歌唱ボリューム生成singingVolume未生成fetchSingFrameVolumeVolumeGenerationCompleteEvent⑤ 歌声合成singingVoice未生成frameSynthesisVoiceSynthesisCompleteEvent⑥ 框架完成——PhraseRenderingCompleteEvent每一步生成的数据都会同时写入框架属性与对应缓存 Map以便下次渲染直接命中。若某一步抛错则发出PhraseRenderingErrorEvent并continue处理下一框架——源码注释说明多数错误源于歌词FIXME 标注非歌词类错误未来应改为抛错并弹错误对话框。五、引擎 API 连携的底层细节5.1EngineSongApi接口渲染器不直接依赖 HTTP 层而是通过注入的接口解耦src/song/songTrackRendering.tstype EngineSongApi Readonly{ fetchFrameAudioQuery: (args: { engineId; styleId; engineFrameRate; notes }) PromiseEditorFrameAudioQuery; fetchSingFrameF0: (args: { notes; query; engineId; styleId }) Promisenumber[]; fetchSingFrameVolume: (args: { notes; query; engineId; styleId }) Promisenumber[]; frameSynthesis: (args: { query; engineId; styleId }) PromiseBlob; };5.2 请求音符的构造createNotesForRequestToEngine在调用引擎前框架音符会被转换成引擎要求的格式src/song/songTrackRendering.ts先头休符将notes[0].position - firstRestDuration到notes[0].position的区间换算为{ key: undefined, frameLength, lyric: }音符本体每个音符按tickToSecond 引擎帧率换算为{ id, key: noteNumber, frameLength, lyric }歌词为空时使用getDefaultLyric(noteNumber, defaultLyricMode)按doremi/la模式补缺省歌词末尾休符追加lastRestDurationSeconds0.5s长度的休止帧长兜底保证每个frameLength 1不足 1 帧的差值会从下一项中借出避免引擎端出现 0 帧片段。5.3 各生成函数的后处理生成函数关键后处理generateQueryshiftKeyOfNotes(-keyRangeAdjustment)移调后再请求 →shiftPitch(f0, keyRangeAdjustment)还原 →adjustPhonemeTimings按minNonPauseStartFrame/maxNonPauseEndFrame裁剪音素时机generateSingingPitch对 Query 应用applyPhonemeTimingEdit用户的音素时机编辑与adjustPhonemeTimings→fetchSingFrameF0→ 还原移调generateSingingVolume在 Pitch 基础上应用applyPitchEdit音高曲线编辑→fetchSingFrameVolume→muteLastPauSection将末尾 pau 段音量淡出至 0避免与相邻框架的呼吸声重叠→ensureNonNegativeVolume钳制非负synthesizeSingingVoice合并f0 singingPitch、volume singingVolume叠加音素时机编辑、音高编辑、音量编辑applyVolumeEdit与shiftVolume音量范围调整用decibelToLinear换算后调用frameSynthesis值得注意为了不污染框架内已缓存的数据generateSingingPitchSource/generateSingingVolumeSource/generateSingingVoiceSource都会先对phrase.query以及 Pitch/Volume做structuredClone再在其上叠加各类用户编辑因此缓存数据始终是引擎原始结果用户编辑只在生成链的某个阶段临时叠加。5.4 store 层的引擎调用引擎 API 的实际网络调用位于SongStore动作src/store/song.ts通过INSTANTIATE_ENGINE_CONNECTOR取得 src/infrastructures/EngineConnector.ts 实例分别invoke(singFrameAudioQuery)、invoke(singFrameF0)、invoke(singFrameVolume)、invoke(frameSynthesis)并在调用前用IS_ENGINE_READY(engineId)检查引擎就绪状态。出错时日志会带上歌词/音素序列便于排查。六、缓存机制的深入解读6.1 四层缓存与哈希键private readonly queryCache: MapEditorFrameAudioQueryKey, EditorFrameAudioQuery new Map(); private readonly singingPitchCache: MapSingingPitchKey, SingingPitch new Map(); private readonly singingVolumeCache: MapSingingVolumeKey, SingingVolume new Map(); private readonly singingVoiceCache: MapSingingVoiceKey, SingingVoice new Map();每层缓存的键都是输入源数据的哈希calculateHash见 src/song/utility.ts并通过品牌类型branded type区分如EditorFrameAudioQueryKey(hash)、SingingPitchKey(hash)相关类型定义见 src/store/type.ts。这意味着只要框架的输入音符、休止、音程调整、歌い方等不变键就不变缓存必然命中任何影响生成结果的输入变化如keyRangeAdjustment、volumeRangeAdjustment、defaultLyricMode都会反映在QuerySource/SingingPitchSource/SingingVolumeSource/SingingVoiceSource的结构中从而改变哈希键、自然失效。6.2 缓存命中后的框架状态CacheLoadedEvent的处理器onCacheLoadedsrc/store/song.ts会根据缓存覆盖情况为每个框架设置状态音轨未分配歌手/歌い方→SINGER_IS_NOT_SET缓存未完全覆盖仍需渲染→WAITING_TO_BE_RENDERED缓存完全命中→RENDERED无需再调用引擎。同时该处理器将缓存的数据同步写入store.stateSET_PHRASES、SET_PHRASE_QUERIES、SET_PHRASE_SINGING_PITCHES等 mutation并调用syncPhraseSequences将框架状态与播放序列同步。这意味着即使完全命中缓存用户也能立刻看到完整的波形与可播放的歌声而无须等待引擎响应——这正是缓存对交互体验的核心价值。七、事件通知体系与 store 联动SongTrackRenderer共定义 9 种事件src/song/songTrackRendering.ts统一收束为联合类型SongTrackRenderingEvent监听器通过addEventListener注册事件语义store 侧处理器效果phrasesGenerated框架生成完毕仅输出日志当前cacheLoaded缓存应用完毕批量更新 state、设定框架状态、同步序列phraseRenderingStarted单框架渲染开始框架状态置NOW_RENDERINGqueryGenerationComplete查询生成完毕SET_PHRASE_QUERY 绑定queryKeypitchGenerationComplete音高生成完毕SET_PHRASE_SINGING_PITCH 绑定singingPitchKeyvolumeGenerationComplete音量生成完毕SET_PHRASE_SINGING_VOLUME 绑定singingVolumeKeyvoiceSynthesisComplete歌声合成完毕写入phraseSingingVoices 绑定singingVoiceKeyphraseRenderingComplete单框架全部完成状态置RENDEREDsyncPhraseSequences同步phraseRenderingError单框架出错状态置COULD_NOT_RENDER输出错误日志事件分发使用dispatchEvent遍历listeners集合逐个调用src/song/songTrackRendering.ts监听器注册在CREATE_AND_SETUP_SONG_TRACK_RENDERER中完成并以switch (event.type)分发到各处理器src/store/song.ts。UI 层即可依据这些事件实时刷新框架正在渲染 / 已渲染 / 渲染失败的视觉状态。八、中断与再渲染机制文档特别强调渲染支持外部中断其实现要点如下粒度requestRenderingInterruption()仅置位interruptionRequested标志src/song/songTrackRendering.ts该标志只在框架之间被检查while循环条件不会中断正在进行的单个框架渲染——保证引擎请求的原子性收尾render()的finally块复位标志与_isRendering若中断则返回{ type: interrupted }再渲染RENDER动作在检测到songTrackRenderer.isRendering true时先请求中断再返回而外层while循环因startRenderingRequested仍为真会在中断完成后立即用新快照重启动渲染——形成编辑 → 中断 → 重渲染的闭环停止STOP_RENDERING动作置位stopRenderingRequested并等待nowRendering归位用于切换曲目、关闭工程等需要完全停止渲染的场景。九、总结与开发者要点回顾 VOICEVOX ソングレンダリング 的设计可以提炼出以下工程要点快照先行SnapshotForRender保证渲染与用户编辑解耦任何渲染输入都以快照为准框架为单位音符按休符切分为PhraseForRender每个框架独立完成 Query → Pitch → Volume → Voice 四步天然支持局部失效与增量渲染哈希缓存四层缓存共用输入哈希即键的思路编辑只使相关框架的缓存失效其余框架直接命中播放头优先级selectPriorPhrase让最靠近播放头的框架先渲染保证试听体验事件驱动9 种渲染事件 store 监听器使 UI、播放序列与渲染进程保持同步错误框架以COULD_NOT_RENDER隔离而不阻塞整体。对二次开发者而言最值得研读的三个文件是src/song/songTrackRendering.ts渲染器本体快照/框架类型、四阶段流水线、缓存、事件src/store/song.tsRENDER/STOP_RENDERING/CREATE_AND_SETUP_SONG_TRACK_RENDERER动作及引擎调用桥接docs/res/ソングのレンダリングのフローチャート.md官方配套流程图可与本文对照阅读。若需为歌曲功能扩展新的引擎能力例如新的生成阶段可参照EngineSongApi接口的注入方式在渲染流水线中新增一个生成 → 缓存 → 事件的阶段并保持与 store 事件监听体系的对接即可复用现有的中断、缓存与优先级调度能力。赞分享桌面应用语音【免费下载链接】voicevox無料で使える中品質なテキスト読み上げソフトウェア、VOICEVOXのエディター项目地址https://gitcode.com/gh_mirrors/vo/voicevox点击查看免费下载相关推荐OSSU计算机组成缓存流水线与虚拟内存机制OSSU计算机组成缓存流水线与虚拟内存机制 你是否曾疑惑为什么打开大型文件时电脑会卡顿为什么同时运行多个程序会变得缓慢本文将深入解析计算机组成中的三大核心教程文档知识库R2R缓存机制详解内存缓存设计与实现策略R2R缓存机制详解内存缓存设计与实现策略 引言缓存架构的核心挑战 在现代应用开发中缓存系统Cache System是提升性能的关键组件尤其对于R2R人工智能RAGAI Agent后端知识图谱搜索引擎react-admin 缓存机制深度解析从乐观渲染到 HTTP 缓存与应用级缓存react admin 缓存机制深度解析从乐观渲染到 HTTP 缓存与应用级缓存 本篇技术指南围绕 react admin 的官方文档 Caching htt前端UI组件上一篇AutoValue Builder 完整使用指南从生成原理到 17 个实战技巧下一篇TypedStruct 技术实践如何在 Elixir 项目中实现类型安全的领域建模创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考