Longhai PodVoice

Longhai PodVoice 将 Markdown 笔记转换为音频，保存在当前 Obsidian 库中，支持全文、选区、目录批量生成，以及关联笔记播放和句子高亮。语音服务包括火山引擎、MiniMax、Replicate、本地 GPT-SoVITS 和自定义 HTTP 接口。

当前发布候选面向 Obsidian 桌面端，使用 Node.js／Electron 接口。尚未完成社区目录审核，不能直接在插件市场安装。插件代码采用 MIT 许可证；云服务需要相应账号，可能产生服务商费用。本地模型和语音服务需要用户自行部署。

刘飞、孟岩预设只包含服务端文件路径和参数，不包含声音模型或参考音频。这些素材尚未获得公开分发确认，不随插件发布；新用户可以使用云端音色或自行配置有权使用的本地模型。

English overview

Longhai PodVoice converts Markdown notes to speech, saves audio in the vault, and links it back to the source note. It supports whole-note, selection, and folder generation; playback controls; and sentence highlighting. Providers include Volcengine, MiniMax, Replicate, a separately deployed GPT-SoVITS server, and custom HTTP endpoints.

This release is desktop only. macOS has been tested; Windows and Linux have not been tested in this release cycle. Community directory approval is pending.

Installation

1. Download main.js, manifest.json, and styles.css from GitHub Releases.
2. Copy the three files into <vault>/.obsidian/plugins/longhai-podvoice/.
3. Reload Obsidian and enable Longhai PodVoice under Settings → Community plugins.

After directory approval, the plugin can also be installed by searching for its name in Obsidian's community plugin browser.

Usage

1. Open the plugin settings, select a speech provider, and configure that provider's endpoint and credentials.
2. Open a Markdown note and use the Listen to full note button or the plugin's generation command. For folder generation, use the folder context menu.
3. The generated audio is saved under TTS Audio by default and linked through the note's audio property. Click the note's listening button again to play it. The floating player supports pause, seeking, speed changes, and highlighting.

Requirements and privacy

Cloud providers may charge fees and require separate accounts. The configured provider receives the text submitted for synthesis and the credentials needed for that request. Credentials are stored unencrypted in the plugin's data.json, which may be included in vault synchronization. Custom endpoints are controlled by the user.

Local GPT-SoVITS and its models must be installed separately. The named voice presets contain server paths and parameters only; this release includes no voice models, model weights, or reference recordings. Use only models and recordings you are authorized to use.

Optional offline speech alignment runs locally and needs Node.js, FFmpeg, sherpa-onnx-node, and a SenseVoice model installed separately. The worker code is bundled in main.js; the plugin does not download executable code. Without the required environment, playback remains available with estimated highlighting.

🌟 核心特性

1. 火山引擎语音合成：

   • 字节跳动火山引擎企业级语音模型（与剪映、抖音、番茄小说同一套自研语音体系）。
   • 预设 4 款音色：知性女声（BV001）、磁性男声（BV002）、灿灿（BV700）、新闻纪实男声（BV119），另支持自定义音色代码。
   • 支持自定义音色代码和语速调节；音量、音调位于「声音 → 声音高级选项」。

2. 音频存储与清理：

   • 仅保留最新音频（默认）：重新生成时覆盖同名音频并清理历史旧版本。火山引擎使用 .mp3，本地 GPT-SoVITS 使用 .wav。
   • 实时容量统计：设置面板清晰展示当前已生成音频数量与占用体积（MB/KB）。
   • 清理孤立音频：一键扫描并清理那些原 Markdown 笔记已被删除的无效音频残留。
   • 一键清空全部音频：听完后随时一键清空音频释放磁盘，笔记文本完好无损，需要听时再按需生成。

3. 笔记 ⇄ 音频双向强关联：

   • 笔记 ➔ 音频：
     • 生成后自动在当前笔记的 YAML Frontmatter 中写入音频属性，例如 audio: "[[TTS Audio/笔记名.mp3]]"；GPT-SoVITS 对应 .wav。
     • 支持可选在笔记正文顶部或底部自动插入原生嵌入播放组件（![[...]]）。
     • 支持在笔记内一键执行命令**「Longhai PodVoice：播放当前笔记关联的语音」**，无需重复合成。
   • 音频 ➔ 笔记：
     • 专属播放弹窗顶部内置“📄 关联笔记”卡片与“打开笔记”按钮。
     • 即使直接从 TTS Audio 目录播放音频，插件也能根据文件名自动反查并定位到对应的 Markdown 笔记，点击一键跳转打开！

4. 桌面端运行与同步：

   • 社区发布候选声明为桌面专用；macOS 为当前开发和验证环境，Windows、Linux 尚未完成实机验收。
   • 语音请求使用 Obsidian requestUrl，音频文件通过 Vault API 保存。
   • 音频与笔记可由用户配置的同步服务同步；同步是否完成取决于该服务。本版本不提供移动端兼容保证。

5. 智能 Markdown 文本清洗：

   • 自动滤除 Frontmatter 元数据、标签（#tag）、URL 链接、图片、嵌入块及 HTML 注释。
   • 行首编号 1. 内容 和 Markdown 转义写法 1\. 内容 统一以 1、内容 朗读，保留数字并加入停顿，避免本地语音把编号切成短片段后读成“零点一”。小数和版本号保持原样；只调整朗读文本，不修改笔记。更新后需重新加载插件并重新生成旧音频。
   • 优化英文缩写连读（如 API、SDK 自动留白分隔），标题与无标点行尾智能补充停顿。
   • 开启行末停顿时，书名号、引号或括号结尾不再被单独视作句末标点。例如《一如既往》后会补句号，避免长文分段合并后与下一标题连读；已有句末标点不会重复补充。
   • 本地 GPT-SoVITS 年数口语化：500 年前 → 五百年前，275 年前 → 二百七十五年前，11 年后 → 十一年后。只转换 1～3 位、无前导零的明确“年前/年后/年以前/年以后/年之前/年之后”；四位年份及编号保留原样。
   • 本地停顿：配套服务保留短句与冒号边界，不再按 36 字强行切开词语；每个句末片段之间至少插入 0.5 秒静音，冒号/分号至少 0.35 秒，外层 WAV 分段之间插入 0.5 秒。模型自带静音仍会保留，因此总停顿并非精确固定值。需要更新并重启配套 GPT-SoVITS 服务；插件更新后需重新加载，已有音频需重新生成。
   • 本地逐句声学合成：插件请求配套服务启用 independent_decode，每个片段只使用自己的文字与语义序列，避免同批其他片段影响发音；语义预测仍按批运行，保留用户设置的语速、温度等参数。这修正了跨句混合的处理方式，但不保证消除模型所有偶发拖音或重复。旧版服务若不支持该字段，需要同步更新服务。
   • 本地 GPT-SoVITS 时刻口语化：会议从10:30开始 → 会议从十点半开始，上午09:05 → 上午九点零五分。只处理有明确日期、时段或日程语境的有效时刻，不修改笔记原文。
   • 裸写的 10:30、比分、比例、视频/音频进度、01:10:30 及带小数秒的时间码保持原样。同一句出现媒体、比分或比例等关键词时优先保留，可能漏转真正的时刻，可手动写成“十点半”。更新插件并重新加载后，新生成音频才使用此规则；已有音频需要重新生成。

6. 增强播放控制器：

   • 本地按自然段提前播放：手动生成整篇或选区时，保留清洗文本的换行边界，各段分别提交，不再把多个自然段拼成 1200 字的大包。首小段就绪即在笔记底部原有悬浮播放器中尝试播放，并显示已生成段数和可播放时长，后续段继续生成；完整音频保存后，同一播放器保留播放位置和暂停状态，切换到完整音频。生成期间可播放、暂停、拖动已生成进度、前后跳转15秒和折叠；倍速与语音对齐跟随在完整音频保存后启用；系统限制自动播放时可点击「播放」。批量任务同样按自然段生成但不自动播放，单段仍走原流程。
   • 首包目标约 80 字，后续每包约 160 字；短自然段不与后段合并，长段优先沿完整句子拆分，过长句子再沿逗号/分号等边界拆分。保护引号、数字和英文词，不为满足字数硬切连续文本，因此缺少标点的超长句仍可能超过目标。分段设置大于 0 即启用此规则，原值 1200 无需手动修改；设为 0 仍关闭分段。
   • 两阶段权重、参考音频、采样参数、内部 batch=2、服务端切句与后处理保留原值。小段 WAV 按顺序衔接，外层段间保留 0.5 秒；后段来不及生成时显示等待。这里缩短的是首次开听等待，更多小请求不保证整篇总耗时更短；请求分组变化也不代表新旧随机合成的波形逐字节相同。
   • 临时播放器提供原速播放/暂停、快退和已就绪部分的进度拖动。完整音频保存后点「打开完整音频」可接续收听并使用原播放器的倍速等功能；在当前对应笔记的悬浮播放器中还可使用高亮与跟随。临时播放器不做全文时间对齐。
   • 关闭临时播放器只停止收听，后台生成继续；完成时不自动重开，也不重复从头播放。后续分段失败只保留临时已生成部分供收听，不将其保存为完整文件或覆盖旧音频。正常完成仍一次性合并保存原格式 WAV。
   • 复用已加载模型：每个 /tts 请求仍携带目标 GPT 和 SoVITS 路径，由配套本地服务核对，相同则复用，不同才切换；插件不再预先发送强制重载请求。模型复用本身不需重启配套服务（逐句声学修复仍需按上文更新服务）；自定义音色仍使用服务端当前模型。生成中的音色参数固定为本次开始时的设置。
   • 0.75x / 1.0x / 1.25x / 1.5x / 1.75x / 2.0x 快捷倍速切换。
   • ⏩ 快进 15 秒 / ⏪ 快退 15 秒快捷按键。
   • 一键跳转原笔记、打开音频文件、复制路径、复制嵌入代码。

7. 现代磨砂玻璃浮动伴读播放器 (Floating Player Dock)：

   • 无论页面向下滚动多深，播放底栏始终稳稳悬浮在视口下方，随时随手暂停/恢复、拖动进度、调速。
   • 支持一键折叠为右下角极简呼吸胶囊（Mini Pill），既不打扰阅读和记笔记，又触手可及。

8. 语音时间戳高亮与“点哪读哪” (Note as a Player)：

   • 自动离线对齐：打开悬浮伴读播放器时，优先读取对应音频的时间戳；没有有效缓存时，在桌面端用本地 SenseVoice 识别音频，提取字词起始时间，再按顺序匹配笔记句子。新旧音频均支持，无需重新生成音频，不向云端上传。
   • 首次处理不阻塞播放：显示「语音对齐中」，处理期间暂不高亮、不点句跳转；音频仍可播放、暂停和拖动。完成后显示「语音已对齐」或「语音对齐 已匹配句数/总句数」，立即按当前播放位置更新高亮。首次分析有额外耗时，后续复用缓存。
   • 真实起点与可靠性：使用音频识别的字词时间戳，成功匹配后自动忽略手动提前／延后值；倍速和点句跳转使用同一音频时间轴。识别时间戳并非人工校验的精确标注，少量错字、漏读仍可能影响匹配。无法可靠匹配的句子不猜测时间，也不允许精确点读；停顿间隙不高亮。SenseVoice 未提供词尾时，仅保留不超过 0.3 秒的短尾，不把长静音计入朗读。
   • 高亮范围与滚动：阅读视图高亮对应段落，编辑视图高亮对应行；自动滚动与高亮共用句子时间，点击匹配的句子跳到音频中的对应起点。
   • 缓存与同步：时间戳保存在音频旁的 <音频文件名>.podvoice-timing.json，含识别文字、时间戳和音频 SHA-256。音频变化后自动重新分析；笔记变化后重新匹配，不重做识别。缓存可随音频同步到其他设备；当前发布候选仅支持桌面端。插件清理音频时会同时清理对应缓存。
   • 运行环境：对齐脚本已打包进 main.js；运行时还需要用户预先安装 Node.js、FFmpeg、sherpa-onnx-node 和 SenseVoice INT8 模型。模型目录为 ~/.coli/models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17/，需包含 model.int8.onnx 和 tokens.txt。自动发现标准 Node/fnm/nvm 路径及 coli 的依赖；不自动安装或下载缺失环境。单音频上限两小时，分析任务串行执行，插件卸载时停止进程。
   • 回退与设置：「听读体验 → 自动语音对齐」默认开启，切换后重新打开播放器生效。环境缺失、识别失败或整篇无法匹配时显示「估算高亮」，悬停状态可查看原因；仅在此回退模式下使用全文时长权重估算及「播放器与按钮 → 高亮同步」的手动偏移。对齐成功后不需要手动调延迟。

9. 📁 目录批量与定时增量生成（个人专属播客流 / 随身听专辑）：

   • 文件夹右键批量生成：直接在左侧文件列表右键任意目录，选择「听笔记：增量生成此目录内所有笔记音频」。
   • 增量判定：优先比较移除 Frontmatter 后的正文摘要，正文未变时跳过生成。旧音频缺少摘要记录时，再比较笔记和音频的修改时间，并容许写入音频关联属性造成的 5 秒时间差。
   • 每天定时自动更新：支持设定每日固定时间（如每晚 12 点 00:00）自动增量更新监控目录（如“待听播客”或“每周精选”）。
   • 休眠唤醒补跑（Catch-up）：若半夜电脑关机或休眠，下次唤醒或打开 Obsidian 时，插件自动静默增量补跑，无感自动化。
   • 非侵入式后台队列：右下角状态栏实时显示 🎧 听笔记 (2/5): 文章标题...，不弹窗阻塞写作，完成后弹汇总通知。

安装与配置

1. 安装方式

• 方式 A（Obsidian 社区市场，官方上架后推荐）： 打开 Obsidian ➔ 设置 ➔「第三方插件」➔「社区插件市场」➔ 搜索 Longhai PodVoice ➔ 点击安装并启用。
• 方式 B（BRAT 测试版安装，桌面端）： 安装并启用社区插件 BRAT ➔ 打开 BRAT 设置 ➔ 点击 Add Beta plugin ➔ 输入 GitHub 仓库地址 longhaiqwe/longhai-podvoice 即可自动拉取最新测试版。
• 方式 C（手动安装）： 从 GitHub Releases 下载最新的 manifest.json、main.js、styles.css，放入你的仓库目录：

  <你的仓库>/.obsidian/plugins/longhai-podvoice/
    ├── manifest.json
    ├── main.js
    └── styles.css
  

  在 Obsidian 设置中进入「第三方插件」，启用 Longhai PodVoice。

2. 火山引擎连接配置

1. 前往 火山引擎控制台 开通语音技术 - 语音合成 (TTS) 服务；
2. 在控制台创建应用，获取你的 App ID 与 Access Token（或 API Key）；
3. 打开 Obsidian 设置 → Longhai PodVoice → 声音 → 服务连接；缺少凭证时这一组会自动展开。
4. 语音服务选择 火山引擎，填写 App ID 和 Access Token / API Key。
5. 回到「声音」选择音色与语速，点击 「试听声音」 验证连接。
   • Cluster ID 默认 volcano_tts，接口地址、音量和音调位于折叠的「声音高级选项」。
   • 配置完整后，下次打开设置时「服务连接」默认收起。配置完整不代表服务在线，仍需试听验证。

设置页按使用场景分为：

已有配置保持不变：打开设置不会保存或重置任何参数。旧的非默认文本清理规则自动显示为「自定义」，只有主动选择「推荐」才恢复文本清理规则；不会改动标题、分段、音色或服务凭证。关闭按钮、关联、定时等功能只隐藏附属选项，其值仍保留。

历史版本策略：

• 「仅保留最新音频」：重新生成时覆盖同名文件，并清理旧时间戳版本。
• 「保留历史版本」：每次生成带时间戳的新文件。
• 若旧配置为“简洁命名 + 关闭清理历史”，显示「覆盖同名，保留已有历史（原配置）」，继续保持原行为，直到手动选择其他策略。
• 扩展名取决于语音服务返回的格式，例如火山引擎为 .mp3、GPT-SoVITS 为 .wav；切换策略本身不会删除文件。

3. 启动与性能

建议在 Obsidian 设置 ➔ 「文件与链接 ➔ 已排除的文件 (Excluded files)」 中，添加 TTS Audio 目录。 这可减少音频文件对搜索等功能的干扰；它不会阻止音频文件同步，也不保证 Obsidian 启动时完全跳过该目录。若改过音频保存位置，请使用实际目录名。

🎧 使用指令

• 查看生成日志：命令面板运行 「听笔记：查看最近生成日志」，查看最近 50 次记录；点击记录可展开详情。

  • 每次实际提交生成（整篇、选区、批量中的每篇及音色试听）都会自动记录，完成提示显示本次用时。增量跳过、空文本或超长文本等提交前校验不产生生成记录。
  • 记录笔记路径、开始/结束时间、耗时、服务商、模型、音色、清洗后字符数、计划分段总数、结果、音频路径及失败原因；GPT-SoVITS 还记录所选两阶段权重和参考音频。分段数不包含网络重试或服务端内部切句；失败时也保留原计划总段数。
  • 耗时覆盖提交前日志写入、模型切换、请求、等待、下载、合并及音频保存；不含此前的笔记读取与清洗。批量完成通知显示整批耗时，每篇耗时单独保存在日志中。
  • 完整日志位于仓库 TTS Logs/YYYY-MM/时间-任务ID.json，每次生成独立文件，按 UTC 月份归档，查看窗口按本地时间显示。记录保留到手动删除，清理音频不会删除日志。正文和完整请求模板不写入日志，已知凭证及错误中的 URL 会脱敏。
  • 可恢复的 Custom 后台任务暂记为「待完成」；运行「检查后台待处理任务」后更新原记录。跨重启恢复的耗时包含后台等待及稍后检查的时间，不等同于服务端纯推理时间。已保存远端文件但本机尚未同步时，生成记为成功，提示会说明等待同步。
  • 意外关闭插件留下的「未结束」记录不推断为成功或失败。日志写入失败会提示，但仍保留已生成的音频。自定义接口未明确提供模型/音色时记录为未知；本地自定义音色的模型由服务端当前配置决定。

• 右键「听全文」选择音色：

  • 菜单列出当前语音服务商的音色，并勾选当前项；切换会保存到插件设置，供后续生成使用。
  • 本地音色每人只保留一套：设置中提供「刘飞」「孟岩」「自定义音色」，右键菜单也使用同一套音色。旧的闲聊、开场和声学候选选择在加载时自动归并到对应人物，后续保存时写入新配置；自定义音色保持不变。
  • 两个内置音色统一使用原 GPT＋清洗后的专属 SoVITS 声学模型，沿用当前声学候选的参考音频与参数。这是当前采用的固定版本，已有对照未证明其在所有文本上听感最优；不采用尚无充分证据支持替换的清洗 GPT e2。右键仅在自定义配置完整或当前已选中自定义时显示该项。
  • 数字与编号预处理、标点切句、逐句声学解码、模型复用、自然段提前播放同时适用于刘飞和孟岩，无需按人物分别开启。人物模型、参考音频、分句停顿与重复惩罚仍各自保留；用户设置的语速和采样参数优先。2026-10-30 已补做刘飞真实合成与音频合并检查，相关验证记录目前仅保存在开发环境，未纳入公开仓库。
  • 缺少服务凭证或自定义音色资料的选项置灰；点击「配置音色…」进入插件设置，补充配置或切换服务商。
  • 本地预设使用插件内置的参考音频路径和模型参数配置；菜单只检查配置是否齐全，不代表远端服务在线、模型文件存在或账号已开通该音色，可在设置中试听验证。
  • 切换不会自动生成或替换已有录音；需要新音色时，再右键选择「重新生成全文语音」。生成期间也可以切换音色并启动另一篇文章；每个手动任务在提交时固定服务商、音色及生成参数，后续切换只影响新任务。仅音色设置正在保存时暂不可切换。
  • 批量队列存在时，右键菜单提供「暂停批量任务」和「恢复批量任务」。本地 GPT-SoVITS 在当前小段结束后暂停，保留内存中的已生成小段；其他服务在当前笔记完成后暂停。暂停前仍在执行的请求不会被强行中断。
  • 不同笔记的手动全文、选区、试听和运行中的批量任务可以同时推进；同一篇笔记避免重复提交。云端请求可以并发，本地 GPT-SoVITS 共用一套模型实例，按完整小段依次执行，多篇文章交替生成，不需要等上一整篇完成；单段或关闭分段时，需要等当前整段请求结束。两个内置音色的每个小段均携带各自模型路径。自定义本地音色仍依赖服务端当前模型，未提供独立的模型版本保证。
  • 暂停期间释放批量任务占用。恢复时等待正在执行的手动任务及音色保存完成后再继续。同篇音频保留原设置，队列中尚未开始的笔记使用届时的设置。音频保存按顺序执行，生成日志与进度按任务分别记录；后台文章不会替换当前的提前播放控件。
  • 暂停期间若手动生成并成功保存了队列中的同一篇笔记，批量任务跳过旧结果，避免覆盖新录音；手动失败则保留原批量进度。恢复时间与暂停目录写入插件配置，定时检查约每分钟一次；休眠唤醒后按到期时间恢复。重启会丢失尚未保存的小段，但保留暂停安排，到期后按原目录重新检查增量任务。
  • Custom HTTP 和非内置 Replicate 模型的音色由请求模板定义，需进入插件设置修改。

• 生成当前笔记语音：

  • 点击左侧侧边栏新出现的 耳麦图标；
  • 或按 Cmd/Ctrl + P，输入 Longhai PodVoice：生成当前笔记语音并保存到本地；
  • 或在左侧文件列表右键笔记，点击 听笔记：生成该笔记语音并保存。

• 播放已关联语音：

  • 在笔记中按 Cmd/Ctrl + P，输入 Longhai PodVoice：播放当前笔记关联的语音；
  • 或在左侧文件列表右键笔记，点击 听笔记：播放该笔记关联语音。

• 为选中文本生成语音：

  • 选中笔记中的部分文字，右键菜单点击 Convert selected text to speech。

• 目录级批量与增量生成：

  • 在左侧文件树右键点击目标文件夹，点击「🎧 听笔记：增量生成此目录内所有笔记音频」；
  • 或按 Cmd/Ctrl + P，输入 Longhai PodVoice：增量同步已配置目录的音频；
  • 或在插件设置的「自动生成 → 笔记目录」点击「选择文件夹…」，在桌面系统窗口中浏览并选择当前仓库内的文件夹（支持子目录和仓库根目录），选择后自动保存，再点击「立即生成」。取消选择会保留原目录，仓库外的目录不会保存；移动端沿用仓库目录下拉列表。未启用每天自动更新时，展开「手动批量生成」即可操作。

网络、费用与本地文件说明

• 云服务：火山引擎默认请求 openspeech.bytedance.com；MiniMax 默认请求 api.minimax.io；Replicate 请求 api.replicate.com，并下载其响应中的音频 URL。这些服务需要用户自行开通账号、提供凭证，费用由服务商收取。插件本身不收费。
• 本地与自定义服务：GPT-SoVITS 默认请求 http://127.0.0.1:9880/tts；用户也可配置其他地址或自定义 HTTP 接口。插件向所选地址发送清洗后的文本、音色参数及配置的请求头，并从服务响应指定的地址下载音频。HTTP 不提供传输加密。
• 发送时机：手动生成、试听，以及用户启用的目录定时任务会发送相应文本。定时任务默认关闭，开启后可能在启动或唤醒时补跑。插件没有客户端遥测或广告。
• 凭证：App ID、API Key、Access Token 和自定义请求头通过 Obsidian 插件数据接口保存，通常位于库配置目录的 plugins/longhai-podvoice/data.json。该文件未由插件加密，可能被用户的备份或同步服务复制；请求时凭证会发送至用户配置的相应服务。不要公开此文件。
• 库外访问：离线语音对齐会查找本机 Node.js、FFmpeg，以及标准全局包目录、fnm／nvm 目录或 coli 依赖中的 sherpa-onnx-node，读取 ~/.coli/models/ 下的 SenseVoice 模型。它启动本地子进程，在系统临时目录解码音频，结束后清理临时文件，不联网下载代码或模型。缺少依赖时保留普通播放与估算高亮。
• 库内数据：音频及时间戳缓存在当前库保存；生成日志记录笔记路径、服务商、音色、耗时、结果和错误信息。默认会写入笔记的 audio 属性，正文嵌入默认关闭。重新生成可覆盖旧音频，清理操作会删除所选音频及时间戳缓存。

从源码构建

npm ci
npm test
npm run build

构建只生成仓库根目录的 main.js，不会写入个人 Obsidian 库，也不会下载模型。发布资产为 main.js、manifest.json、styles.css。逐句对齐工作进程源码来自 speech-timing.cjs，在构建时嵌入 main.js，无需用户另行安装脚本。

📄 开源许可

本项目基于 MIT 协议开源。