# 壁纸声伴 v0.9.0：新版功能与图文使用指南

本文依据本地 v0.9.0 源码和当前使用手册整理。网站所介绍的源码功能不代表 GitHub 上旧版本发行包已包含这些内容，请核对实际下载版本。

## 新版重点

- 随附90条中文配音：38条陪伴、52条操作回应。新建配置支持空目录回退到随附示例，旧配置默认不擅自开启此回退。
- 独立操作回应规则可设置动作、分类、冷却、导入导出，只播放已有文件，不自动加载模型。
- 页面和配置切换时自动保存，短暂提示可撤销；仍可手动保存。
- BGM 支持封面和默认音频设备切换，关闭BGM时收起播放器。
- 台词多选、全选与全不选、重复检查，文件按“台词-模型名称.wav”命名。

## 界面图示

![新版主页](../assets/home.png)

先看顶部当前壁纸与正在编辑的配置，再到声音设置调整语音、BGM、冷却。左侧切换台词、音频和语音生成；退出请使用托盘菜单。

![互动规则](../assets/rules.png)

新增规则后选择事件或时间、播放分类和冷却。默认回到桌面后触发。试听只证明音频匹配，不证明时间/事件条件满足。

![台词库](../assets/dialogues.png)

导入和编辑只保存文字；随附90条配音可直接播放，但额外台词需要生成或导入对应音频。72条《温柔回信》是额外文字素材。

## 当前详细手册

### 每个页面的具体操作

## 新界面导航与背景

左侧进入陪伴主页、壁纸库、音频库、台词库、语音生成、设置和运行记录。原“声音与互动”中的播放参数在“陪伴主页 → 声音设置”，目录、名称、绑定和原音频防冲突策略在“资源与绑定”，互动规则在同一行的“互动规则”。其他页面的功能保持可用。

右上角“导入背景…”选择本地图片，程序在后台处理并保存一份副本；原图不会被修改或移动。默认从图片提取协调的柔和主题色。“设置 → 外观与背景”可关闭自动取色，固定使用樱粉，也可恢复默认背景和主题。重新启动会恢复外观，恢复默认不会删除图片副本。

顶部“正在编辑”选择器与左侧配置列表同步；左侧支持多选删除和批量管理。编辑其他配置时，上方显示正在编辑和当前播放的区别。底部播放器控制当前播放配置；关闭“启用背景音乐”后隐藏，重新开启后恢复；封面优先取歌曲元数据，也尝试同目录 cover.jpg/png、folder.jpg/png，无封面显示默认图标。BGM 暂停不阻止角色语音，“暂停伴随”则暂停全部伴随声音与触发。

## 发行版使用说明

程序独立运行，配置和音频保存在自己的数据目录，不修改 Wallpaper Engine（WE）本体或下载的壁纸。

免安装 ZIP 请完整解压后运行 WallpaperCompanion.exe，保留 _internal 和 portable.flag；数据在旁边的 data/。setup.exe 安装版无需管理员权限，数据在 `%LOCALAPPDATA%\WallpaperCompanion`，卸载保留数据。两者均不需要 Python/Conda；更新前从托盘退出程序。详细下载和构建说明见 [BUILDING.md](BUILDING.md)。

## 先完成一次基本设置

1. 在 WE 播放壁纸，启动声伴，检查顶部“当前壁纸”。如检测不对，到“运行设置”修改安装目录和显示器。
2. 点击“绑定当前壁纸”，或到“壁纸库”扫描、勾选后批量绑定。
3. 在“声音与互动”选择语音和 BGM 文件夹，或建立专用资源目录。
4. 选择“台词库”，编辑自己的台词。想生成语音时，到“生成语音”填好语音服务，再点击生成。
5. 在“互动规则”设置 F8、鼠标或随机语音，保存配置。离开配置窗口回到桌面后体验触发。

保存文字与生成音频是两步：文字不会自行变成声音。手动下载的音频直接放入目录即可，不要求先录入台词库。

## 顶部、左侧和托盘

| 控件 | 作用与注意事项 |
|---|---|
| 当前壁纸 | 展示当前跟随显示器的壁纸和识别来源。“已保存配置”表示只读读取 WE 保存的选择，可能随 WE 保存稍有延迟。 |
| 立即检测 | 单次尝试官方命令查询壁纸，无输出时只读保存配置。自动轮询不启动 WE 查询进程，避免周期性闪烁。 |
| 悬停说明：开启/关闭 | 开启时鼠标在控件上停留约 1 秒出现简短说明；离开、点击或按键时隐藏。选择自动保存。 |
| 打开使用手册 | 在程序内打开本文，不依赖系统的 Markdown 默认打开方式。窗口可以缩放、滚动，说明文档之间的链接也在窗口内打开。 |
| 暂停伴随/继续伴随 | 同时暂停/恢复声伴语音触发和 BGM；不控制 WE。用户独立暂停的 BGM 不会因此恢复。 |
| 左侧壁纸配置列表 | 选择要编辑的配置。可 Ctrl/Shift 多选后删除。编辑配置不一定等于当前正在使用的配置，以顶部状态行中的名字为准。 |
| 绑定当前壁纸 | 为当前识别的壁纸创建配置；已有绑定则直接打开它。 |
| 扫描/批量绑定壁纸 | 打开“壁纸库”页面。 |
| 新建 | 创建尚未绑定壁纸的配置，可稍后绑定或用手动模式测试。 |
| 删除 | 删除选中配置，需确认。只删除绑定，壁纸、声音和台词文件保留。 |
| 手动使用选中配置 | 开启后使用选中配置，不随 WE 切换。关闭后恢复自动跟随。 |
| 托盘双击 | 重新显示窗口。关闭窗口通常只是留在托盘。 |
| 托盘暂停/下一首/退出 | 分别控制全部伴随、BGM 或结束程序。生成中退出会先确认取消；保留已保存的音频，并回收声伴自己启动的本地 API。 |

配置、规则、台词与接口/运行设置在切换页面、切换壁纸配置、关闭窗口到托盘或正常退出时自动保存。保存成功会出现约 6.5 秒的非模态提示，可点“撤销”；设置页也有“撤销最近自动保存”。原保存按钮仍可立即保存。生成框的临时文本不当作持久配置。

撤销只针对最近一次自动保存/恢复默认，且不覆盖其后的新编辑、其他保存或外部文件变化；共享台词会连同关联配置一起还原。接口密钥由系统凭据管理器保存，不参与撤销。保存失败时保留编辑内容并阻止离开该页/配置；修正错误后可重试，不会静默放弃。普通自动保存不会重新播放当前歌曲或重置未修改规则的计时。

### 默认操作语音（本地开发中的新功能）

“设置 → 播放操作回应语音”默认开启，按保存、撤销、编辑、删除、切换页面等动作播放对应短句。只播放已有文件，不自动合成、不启动 API。快速连续操作节流，输入修改合并提示；正在播放角色语音/参考音频、暂停伴随或全屏静音时不抢播，不积累队列。未生成的分类保持静音，设置页会显示已发现的分类数。

| 控件 | 作用 |
|---|---|
| 播放操作回应语音 | 开关立即保存，关闭时仅停止当前操作回应，不停止其他试听。 |
| 操作语音目录 | 可选的自定义根目录，下面按“操作·保存”等分类存放音频。留空则先查找当前编辑配置的语音目录、共享语音目录，再查找随程序附带的 `examples/audio/operation-voice`。 |
| 刷新操作语音 | 后台重新发现新增文件；也会在生成完成、切换配置和后续操作时刷新。 |
| 导入默认操作台词 | 去重补充 52 条原创台词到当前台词库，不强制勾选，也不调用 API。 |
| 操作回应规则… | 打开独立规则表，每种动作可设启用、播放分类、冷却，以及全局最短间隔。支持导入/导出操作规则 JSON，默认全部开启；不会修改壁纸的鼠标/按键/时间规则。示例在 `examples/presets/operation-voice-rules.json`，发行包随附。 |
| 恢复默认配置 | 二次确认后恢复运行偏好、外观、操作语音开关及当前配置的播放参数/规则；保留绑定、资源路径、台词、音频、角色与接口，不操作系统自启。可撤销。 |

当前源码已随附 90 条用户提供的默认配音：52 条操作语音和 38 条陪伴示例，全部默认台词已覆盖，无需启动 AI 即可播放。此前的 [13 条补齐参考清单](examples/dialogues/missing-default-audio-zh-CN.json) 已全部完成，仅保留供备份参考，不需重复生成。维护者准备素材的方法见 [分发语音说明](examples/audio/operation-voice/README.md)。本轮只准备源码和资源，现有 Release 不会自动更新。

新建壁纸配置默认开启“语音目录为空时使用随附示例”：只读使用程序内示例，不复制或覆盖个人目录；放入自己的语音后优先播放个人文件，也可手动关闭。旧配置缺少此字段时默认关闭，避免升级后擅自发声。语音总目录随机规则排除“操作·…”分类，操作语音走独立规则；显式指定操作分类的规则仍可播放它。

## 声音与互动：每个输入框

| 名称 | 填什么/做什么 | 何时生效 |
|---|---|---|
| 配置名称 | 自己辨认用的名字，如“派蒙-森林壁纸”。不会重命名壁纸文件。 | 离开页面自动保存；也可手动保存 |
| 绑定壁纸 | 只读入口路径，说明这份配置属于哪张壁纸。 | 用重新绑定按钮更换 |
| 语音文件夹 | 含 WAV、MP3 等音频的目录，可包含子目录。手动下载或 AI 生成均可。 | 离开页面自动保存；也可手动保存 |
| BGM 文件夹 | 含背景音乐的目录。空目录/留空表示没有伴随 BGM。 | 离开页面自动保存；也可手动保存 |
| 启用此配置 | 整份配置的自动语音和伴随 BGM 开关。 | 离开页面自动保存；也可手动保存 |
| 启用文件夹 BGM | 只控制伴随 BGM，不关闭互动语音。 | 离开页面自动保存；也可手动保存 |
| 鼠标和键盘仅在桌面前台触发 | 默认开启，避免写字或游戏时频繁说话。配置窗口内操作也不会自动触发语音。 | 离开页面自动保存；也可手动保存 |
| 全屏应用前台时暂停伴随声音 | 全屏时暂停声伴，离开全屏后恢复；不更改 WE。 | 离开页面自动保存；也可手动保存 |
| 随机播放 BGM | 开启随机选曲；关闭按文件名排序轮播。 | 离开页面自动保存；也可手动保存 |
| 语音音量 | 0–100%，只影响声伴语音。 | 离开页面自动保存；也可手动保存 |
| BGM 音量 | 0–100%，只影响声伴音乐。 | 编辑当前播放配置时立即生效并保存；其他配置离开页面自动保存 |
| 说话时 BGM 保留 | 语音播放时，保留正常 BGM 音量的百分比。例如 BGM 40%、保留 25%，说话时约为 10%。 | 离开页面自动保存；也可手动保存 |
| 语音全局冷却 | 同一配置两次成功触发语音的最小间隔，秒。和规则自身冷却同时限制。 | 离开页面自动保存；也可手动保存 |
| 资源根目录（可共享） | 新配置默认使用 程序目录的 shared，无需填写。需要自定义时再选目录；旧路径保持不变。根目录下统一使用 voice、bgm、dialogues.json。 | 点击“按此根目录绑定…” |
| 分别设置语音 / BGM / 台词的共享或专用模式 | 每项可独立选直接共享、本壁纸专用或保留当前路径；例如共享语音配合专用 BGM。专用默认 data/audio/配置ID，可自行更改。 | 在弹窗保存后生效 |
| 共用台词文件 | 只读展示实际关联的 JSON 文件。共用它的配置会共享修改后的台词。空值表示台词仍保存在本配置内。 | 选择资源根目录时关联 |
| 原壁纸音频策略 | 选择检测有声/无法确认时是否暂停伴随 BGM，详见下一节。 | 离开页面自动保存；也可手动保存 |
| 手动覆盖检测 | 已自行静音原壁纸时，选“我确认原壁纸无声/已静音”；也可以确认其有声。 | 离开页面自动保存；也可手动保存 |
| 当前播放的音频检测 | 只读判断依据，针对正在使用的配置，不一定是正在编辑的配置。 | 检测完成后更新 |

### 本页按钮

| 按钮 | 作用 |
|---|---|
| 将此配置绑定到当前壁纸 | 把所编辑配置关联到检测到的壁纸。目标已有其他配置时会提示，不会制造重复绑定。 |
| 按此根目录绑定音频、BGM 和台词库 | 创建所需目录并关联 JSON；已有 JSON 优先读取，避免默认台词覆盖已有内容。 |
| 重新检测原壁纸声音 | 后台重新检查原壁纸音轨/素材，不播放原声音。 |
| 建立专用音频目录 | 打开目录模式弹窗，预选专用模式；可分别改成共享。点击保存后还会显示配置名和实际路径，二次确认才创建并保存；取消不改绑定、不创建目录，原共享文件不搬走。 |
| 打开语音目录/打开 BGM 目录 | 在资源管理器打开目录，方便放入手动下载的文件。 |
| 离开页面自动保存；也可手动保存 | 保存当前配置的编辑，并重新应用正在播放的配置。 |
| 随机试听语音 | 从编辑中的语音目录随机试听，不受自动触发的时间和冷却约束。 |
| 暂停当前 BGM/继续当前 BGM | 只控制当前播放配置的伴随 BGM，语音仍可播放。暂停选择按配置保存。 |
| 下一首 BGM | 按顺序/随机设置选下一首。手动暂停或防冲突暂停时不会强行播放。 |
| 停止试听 | 停止当前声伴语音，BGM 不受影响。 |

音频新增或删除后，下次选语音/下一首时重新扫描。常用 WAV、MP3、OGG、FLAC、M4A 等都可使用，实际格式支持取决于播放器；损坏 BGM 会记录并跳过。

## 音频库

可统一管理默认共享目录和所有壁纸已绑定的语音/BGM 目录，按实际文件路径去重；不会因为浏览、搜索、试听而启动 GPT-SoVITS。

| 控件 / 按钮 | 作用 |
|---|---|
| 查看范围 | 查看全部目录、共享语音/BGM，或某张壁纸的目录。进入此页或点击刷新时后台扫描。 |
| 搜索 | 按文件名、路径、所属配置筛选。筛选时清空选择，避免误操作隐藏文件。 |
| 文件列表 | Ctrl/Shift 多选，双击试听；显示大小、实际路径及使用该目录的配置数，不代表精确分析了每条互动规则。 |
| 试听所选 / 停止试听 | 使用现有语音播放器试听第一个文件，不调用合成服务。 |
| 打开所选文件目录 | 打开该文件的真实所在目录，也可在资源管理器自行整理和改名。 |
| 导入 / 复制目标 | 选择共享目录或某个壁纸已绑定的目录。若要专用副本，先给壁纸设置专用目录，再选对应目标。 |
| 分类子目录 | 可选，如“早安”。留空放在目标根目录；不能使用绝对路径或上级目录。 |
| 导入音频文件 | 复制手动下载等来源的音频，保留原文件；同名自动编号。 |
| 复制所选到目标 | 给所选文件创建独立副本，不移动原文件；直接共享则无需复制。 |
| 目标目录用于当前壁纸语音 / BGM | 把目标及所填分类目录直接绑定到左侧当前配置，并保存声音与互动页的编辑；不复制音频，不更换台词文件。 |
| 删除 | 确认后把全部所选音频放入系统回收站；共享目录中的文件会影响其他配置，精确文件规则可能失效。保留配置、绑定；回收失败不永久删除。 |
| 共享根目录 | 默认 程序目录的 shared，可按需更改。留空后保存恢复默认；只改变新绑定/下次显式选择共享时的目标，已有路径不变。 |
| 共享语音 / 共享 BGM 查看范围 | 同时发现当前共享根目录及已有的 `data/audio/shared` 旧共享目录，不搬动、不改写绑定；范围下拉的悬停提示列出实际查找目录。 |
| 随附默认语音（只读） | 查看随程序的 90 条示例，能试听和复制到个人目录，不能删除、覆盖，也不会作为导入目标。 |
| 设置当前壁纸共享 / 专用目录 | 选择语音、BGM、台词各自的资源方式；专用默认 data/audio/配置ID。不搬动或删除旧资源。 |

生成、扫描或复制进行中时，先等当前操作结束再进行文件管理。新增音频在下次选曲时参与播放。调整文件名可能影响按台词命名的匹配、规则筛选和跳过已有音频的判断，整理后应检查对应规则。

## 原壁纸音频与防冲突

| 策略/结果 | 含义 |
|---|---|
| 默认防冲突策略 | 有声音证据或无法确认时，暂停伴随 BGM；互动语音照常。 |
| 仅发现声音证据时暂停 | “发现音轨/可能有音频素材”时暂停；未知时允许。 |
| 允许伴随 BGM 播放 | 不因检测结果阻止伴随 BGM。 |
| 视频含音轨 | ffprobe 发现音频流；它可能是 BGM、台词甚至静音轨。 |
| 视频没有音轨 | ffprobe 成功检查，确认没有音频流。 |
| 场景包/网页含音频素材 | 有可能发声，不能确认是否实际启用。 |
| 无法确认 | 缺少工具、格式不支持、检测失败，或脚本/共享素材无法判断，绝不当作“肯定无声”。 |

如果 BGM 文件夹有音乐却不播，先看顶部是否显示“BGM 已手动暂停”或“BGM 防冲突暂停”。确认原壁纸已经静音，可手动覆盖并保存。声伴不自动调整原壁纸或系统音量。

## 互动规则

先选择一条规则，再使用添加、编辑、删除或试听。双击也可编辑。离开页面会自动保存并提示，可撤销；也可点“保存配置与规则”立即保存。

现在按顺序选择：① 按时间/按事件 → 时间方式或鼠标/键盘分类 → ② 播放什么。鼠标不显示快捷键，固定时刻不显示随机间隔。只需设置相关字段，其他选项在“更多设置”里。

| 编辑框/选项 | 用途与示例 |
|---|---|
| 规则名称 | 自定义名字，如“下午提醒喝水”。 |
| 启用这条规则 | 不想删规则时可取消启用。 |
| 触发分类 | 先选“按时间触发”或“按事件触发”。 |
| 时间方式 | 每天固定时刻，或在指定时间段随机播放。 |
| 每天几点 | 固定时刻的 HH:mm。程序运行到该分钟，满足播放条件后当天触发一次；不补播已过分钟。重启于同一分钟可能再次触发。 |
| 事件分类 | 鼠标触发、键盘触发、壁纸/扩展事件。 |
| 鼠标动作 | 左/右/中/侧键、滚轮方向，无需设置键盘。 |
| 键盘方式 | 指定按键/组合键，或任意按键。 |
| 绑定按键 | 只读显示。点击“录制按键”，直接按想用的键或组合键，例如 Ctrl+Alt+H；Esc/取消录制保留原绑定。单独 Shift 和 Enter 可绑定，重复组合键会提示。 |
| 播放什么 | 总目录随机、选择台词分类/子目录、自选音频文件或文件夹。 |
| 台词分类/子目录 | 下拉选项来自当前台词库分类和语音目录的一层子目录，无需手写；旧规则中缺失的分类仍保留。分类中必须有已生成/下载的音频。 |
| 音频来源 | 自选模式可浏览文件夹，或用“选音频文件”选择单条音频。 |
| 文件名包含 | 只选名字含此文字的音频，如“早安”。留空不筛选，不会把文字自动变成语音。 |
| 播放时段/事件生效时段 | 本地时间。相同=全天；`22:00–06:00` 可跨午夜；结束时间不包含在内。事件时段限制位于“更多设置”，默认关闭。 |
| 规则冷却 | 本条成功触发后至少等待的秒数。还需满足全局冷却。 |
| 随机间隔：最短/最长 | 仅定时随机有效，范围内随机等待，最少 5 秒；不会启用后立刻播放。 |

语音正忙时不叠加播放，不积累长队。多个规则同时符合时按规则列表顺序选择。试听只检查文件是否能匹配和播放，不证明时间/事件设置也符合。

“绑定壁纸开始”指切入该配置时，并非每次鼠标返回桌面。无法检测的 WE 内部暂停原因不会被当作新事件。

### 配置文件导入与分享

“互动规则”页面新增“导入互动配置”和“导出选中配置”。前者读纯 JSON，后者导出左侧选中的一个或多个配置。内容包括规则、台词和播放参数，不包括音频、密钥、插件和本机绝对路径。

导入先显示配置名、规则/台词数量，再选“新建为未绑定配置”或“应用到当前配置”。新建会建立本机音频目录；之后在声音页重新绑定壁纸、生成或放入音频。应用只支持单配置文件，保留当前壁纸/音频目录，但替换规则、台词和播放设置；会解除共享台词文件关联，避免修改其他配置。

导出的来源是分类名/相对文件名。如果原来源不在语音根目录内，会提示接收者重新核对。缺少事件扩展时，对应规则禁用。文件不设置自启、不更换 API、不自动加载插件。

示例位于 `examples/interaction-preset.json`，含 F8、中键、每天 09:00、夜间随机规则和 38 条默认台词。

## 壁纸库与批量绑定

| 控件 | 作用 |
|---|---|
| 搜索框 | 按标题、工坊 ID、路径筛选。隐藏行仍保留原勾选。 |
| 扫描壁纸库 | 只读扫描工坊、WE 本地创作和附加目录；不直接新建绑定。 |
| 列表左侧勾选 | 决定批量绑定/删除范围，和左侧配置列表的选择无关。 |
| 列表其他列 | 展示壁纸名、类型、ID、绑定状态和语音/BGM 路径。 |
| 全选可见/取消可见勾选 | 只改变当前筛选后可见行。隐藏项需清空搜索后检查，避免遗漏。 |
| 打开选中配置 | 打开当前行已有绑定；未绑定先执行批量绑定。 |
| 批量删除勾选壁纸的绑定 | 确认后仅删除配置，壁纸和全部共享/独立资源保留。 |
| 附加扫描目录输入区 | 每行一个真实目录；适用于存放在工坊之外的项目。 |
| 添加扫描目录 | 选择目录加入输入区，尚未保存。 |
| 保存目录并扫描 | 保存附加目录并扫描，同时将其加入禁止输出写入的保护范围。 |

### 批量绑定弹窗

| 字段 | 怎么用 |
|---|---|
| 目录方式：共用语音/BGM | 只统一音频目录，不改变台词库的关联。选择已有语音目录，BGM 可空。 |
| 目录方式：共用完整资源 | 选择共享资源根目录，多张壁纸使用同一 voice、bgm、dialogues.json。 |
| 目录方式：独立目录 | 为每张壁纸在声伴数据目录建立一份资源结构，不需要填共享路径。 |
| 共享资源根目录 | 仅完整共享模式使用。 |
| 语音目录/BGM 目录 | 仅共享音频模式使用。 |
| 新配置模板 | 把此模板的音量、台词和规则复制给新配置，新的配置/规则 ID 独立。 |
| 同时更新已有配置 | 默认关闭：已有绑定跳过。开启：更新资源关联，不覆盖已有配置名称和规则，不删除旧文件。 |

扫描只识别有有效 `project.json` 入口的项目，打包 Scene 不需要解包。缺损项目会提示并跳过；重复扫描/绑定不会产生同一路径的重复配置。

## 台词库

未选择壁纸配置时，显示共享台词库；全新安装无需先绑定壁纸，也会展示 38 条原创短句，包含点击回应、返回桌面、早晨、白天、夜间、闲置陪伴。保存后写入共享根目录的 dialogues.json。选择已有配置时，编辑该配置对应的台词。

“补充默认台词”支持无绑定使用，只补充缺少的文本，不覆盖自己修改的条目；全部存在时会提示无需重复添加。无绑定也可新增、导入、导出和按分类生成语音。共享台词未保存时创建首个绑定或更换共享根目录，会先保存当前共享草稿，失败时阻止切换，避免丢失。已有 JSON 损坏时提示错误并保留原文件，不会静默覆盖。

新增原创台词包 `examples/dialogues/heartfelt-zh-CN.json`：72 条偏温柔、煽情的日常问候。点击“导入台词 JSON / TXT”选择 JSON 后保存；导入不会自动调用任何语音服务。v0.8.0 用户先新建配置再导入。

| 控件 | 作用 |
|---|---|
| 生成列勾选 | 只决定本次生成内容，初次打开/切换台词库不默认全选；不改写台词数据，不删除文字。 |
| 行框选 / Ctrl、Shift 多选 | 与“生成”列双向同步。拖选后滚动到的行同样参与生成；直接点某行的勾选框只切换该行。清除行选择也会清除生成勾选。 |
| 全选台词/全不选台词 | 选择全部条目或清空本次生成选择。 |
| 分类下拉与选择此分类 | 仅勾选该分类，其他分类取消；之后仍可逐条调整。 |
| 新台词/编辑/双击 | 弹窗内设置分类和台词文本，保存后在列表勾选本次生成条目。分类是子目录名，不能含斜杠等非法字符。 |
| 删除 | 移除选中行的文字，不删除已生成的音频；保存后生效。 |
| 补充默认台词 | 补回未出现的默认短句，不覆盖现有自定义内容。 |
| 保存台词库 | 保存文字。关联了共享 JSON 时，也影响共用该文件的配置；其他配置下次打开同步读取。 |
| 跳过已存在同名音频 | 分类生成时，同一分类目录有同名音频就不重复调用 API。 |
| 将勾选台词送到生成页 | 保留台词分类和跳过同名设置，输出到当前语音根目录对应的分类中。可以编辑文字，但修改后会按普通逐行模式生成，不再推断原分类。 |
| 按分类生成勾选台词 | 用当前选中的语音服务生成，分别保存到语音目录下的分类子目录。 |
| 应用分类触发规则 | 确认后用默认 F8/中键、壁纸切入和分时随机规则替换编辑中的规则，保存后生效。 |
| 导入 JSON/TXT | JSON 保留分类等字段；UTF-8 TXT 每行一条，默认归入点击回应。导入去重后需要保存。 |
| 导出 JSON | 导出当前完整台词库，便于备份、修改和再次导入。 |

台词改字后旧音频不会自动改名或重新生成。若想重新生成相同台词，可取消跳过；重名会加编号，不覆盖旧文件。手动整理音频时注意规则来源和关键词。

## 生成语音：通用字段和按钮

点击按钮会先在界面底部显示操作提示，短提示表示已接收到操作，并不代表保存、连接或生成成功；最终结果看页面状态或错误提示。保存接口和切换生成目录也会显示明确结果。

应用自有按钮使用轻微压缩和弹簧回弹，包括开关、工具按钮以及动态对话框中的按钮。动画不改变布局尺寸和点击区域；快速连击会从当前状态衔接，禁用后回到正常状态，隐藏或退出时停止。系统原生文件选择器保持 Windows 自己的按钮样式。

生成按钮下方的进度条按实际已处理条数推进：保存成功或按设置跳过已有音频才计数。细条动画表示当前阶段正在等待；下方记录接口检测、准备自建服务、等待模型、合成、写入及失败阶段。模型加载与 API 内部推理没有精确百分比时不会估算。失败后保留已保存的文件和已完成计数，进度不会伪装成全部完成。

两种生成入口都会先在后台检查同名音频及本批次重名条目，再调用 API。发现重复时可选“跳过重复，生成其余”“全部生成，另存副本”或“取消”；原文件不覆盖。勾选跳过只是选择弹窗的默认按钮，不会取消确认。分类任务只对照相同分类目录，普通逐行任务检查输出目录及子目录；已有非空的受支持音频扩展名都参与比较。取消或全部跳过不会启动 API 或请求合成。

新音频文件名采用 `台词-模型名称.wav`，例如 `早上好-神里绫华.wav`。留空模型标签时，优先使用与当前权重匹配的角色名称，其次用 SoVITS/GPT 权重文件名，第三方服务用模型/音色 ID；不知道外部接口当前模型时写“未指定模型”，不会自行查询或切换它。可在“文件名中的模型标签”手动填写易辨认的名称；这个输入仅控制命名，不能替代模型选择。标签会随接口设置自动保存。

同一台词的不同模型版本分别保存和查重；当前模型的同名文件以及旧的纯台词文件名会进入重复确认。旧文件没有模型标记时不能判断来源，若要生成当前模型的新副本，请明确选择“全部生成，另存副本”。旧音频不自动重命名或覆盖；同名新副本带 `(2)` 等编号，过长名称会安全缩短并保留区分标记。操作语音查找、分发准备与校验兼容新旧文件名。

| 字段/按钮 | 用途 |
|---|---|
| 语音生成扩展 | 选择本机 GPT-SoVITS、Azure 或其他兼容服务；各自保存参数。 |
| 生成保存目录 | 普通“生成并保存语音”的输出位置。分类生成使用当前配置的语音目录。 |
| 多行台词框 | 每行一条待生成台词。这里的文字不自动写回台词库。 |
| 保存接口设置 | 保存参数，密码字段进入系统凭据管理器。 |
| 检测连接 | GPT-SoVITS 检查真实接口；云服务只验证地址格式，鉴权需生成短句确认。 |
| 启动本地 API / 关闭自建 API | 可提前启动并等待模型加载，或关闭本程序启动的 API 进程树；关闭后可再启动。未提前启动时仍支持生成时自动启动。外部服务只连接、不关闭、不在启动操作中切换模型。加载/生成期间按钮禁用，防止任务互相打断。 |
| 使用当前配置的语音目录 | 将普通输出位置设为正在编辑配置的语音总目录。 |
| 生成并保存语音 | 批量合成 WAV；文件名使用台词，非法字符替换、长名截短、重名编号。 |
| 打开保存目录 | 查看生成结果。 |

生成期间可关闭窗口留在托盘等待；关闭主窗口不是退出程序。失败或取消前完成的文件保留。云端服务会接收待合成文本并可能计费。退出声伴时停止由本次声伴启动的 API 及其子进程；原本由你或其他软件启动的 API 只复用，不会关闭。

### 本地 GPT-SoVITS 字段

| 字段 | 填写说明 |
|---|---|
| API 地址 | 本机 api_v2 地址，例如 `http://127.0.0.1:9880`。这里只接本机 HTTP。 |
| 项目目录 | GPT-SoVITS 根目录，包含 api_v2.py；不是 WAV 输出目录。 |
| Python 可执行文件 | 可选，选择能运行 GPT-SoVITS 的 python.exe。留空使用项目内 runtime/python.exe。 |
| GPT 模型 (.ckpt) | 扫描后下拉选择或浏览文件，与 SoVITS 成对选择。可使用项目相对路径。两项同时留空沿用当前模型，兼容旧配置。 |
| SoVITS 模型 (.pth) | 配套的声学模型权重。只在实际生成时加载，扫描不读取权重内容。 |
| 参考音频 | 和当前角色模型匹配的真实语音文件。 |
| 参考音频原文 | 逐字填写参考音频实际说的话。不能放待合成台词，也不能凭想象填写。 |
| 目标语言代码 | 待生成文字语言，如 zh/en/ja；应为本机模型支持的代码。 |
| 参考语言代码 | 参考音频原文的语言，如 zh。 |
| 语速 | 0.5–2.0，1.0 为普通速度。 |
| 允许切换外部 API 模型 | 默认关闭。若接口由其他软件启动，生成时选定模型会改变其全局状态，需显式勾选允许；否则使用空闲端口让声伴独立启动。关闭声伴不会终止外部服务。 |

### GPT-SoVITS 角色预设与模型扫描

1. 填写包含 `api_v2.py` 的项目目录，会自动只读扫描；也可点击“扫描本地模型”。扫描排除 runtime、预训练基础模型和工具环境，不导入 PyTorch 或加载权重。
2. 在“配对候选”中选择角色，或分别在两个模型下拉框/浏览按钮选择 `.ckpt` 与 `.pth`。候选按版本提示、目录和名称唯一配对，并非模型兼容性检测；同名多权重或不同版本无法唯一配对时不会猜选。
3. 从“项目参考音频”选择并点击“填入参考音频”，也可直接浏览文件。填入逐字原文及语言；“读取同名原文”只读同名 `.lab`/`.txt`，找不到时必须手工填写，仍需核对内容。
4. 点击“保存角色”填写名称，保存模型、参考音频、原文、语言、语速、项目与可选 Python 路径，并保存当前接口设置；“另存为…”创建另一角色/情绪预设，保留原条目。接口地址和外部模型切换许可是通用接口设置，不随角色预设切换。
5. 以后从“角色预设”选择，恢复这组参数。保存接口设置不会覆盖角色预设；要修改角色内容需点击“保存角色”。角色字段有未保存修改时切换会询问是否放弃。
6. 点击生成才启动 API 和加载所选模型。同一模型重复生成复用自建 API；更换所选权重时先停止自建旧进程再用新模型启动，降低跨版本及显存缓存冲突。不会在扫描、选择、保存角色时启动或切换模型。

自建服务在声伴数据目录 `tts-runtime/` 使用推理配置副本，不改 GPT-SoVITS 原始 `tts_infer.yaml`；停止服务后清理副本。退出仍回收自建 API 及其子进程。若接口由外部软件启动且用户允许切换，模型是全局状态；不要让其他客户端同时切换，声伴无法协调其他软件的请求。

“删除角色”只删除预设数据，不删模型、参考音频或原文文件。预设保存在本机 config.json 的 `tts_characters` 中，不随共享互动配置导出；不包含 API 密钥。角色文件离线/移动不会妨碍程序启动，但生成前会校验文件是否存在。

想生成派蒙声音，需要 API 加载派蒙模型，并选相应参考。只改文件名不会改变声线。

声伴仍通过 api_v2 生成，并没有绕过 API 或模型加载。地址中的 `9880` 就是端口，参数保存后不用每次重新填写。操作顺序是：

1. 点击“检测连接”只检查接口，不启动、不加载模型。选择角色或填写配套权重、参考信息；两项权重同时留空可沿用已加载模型。
2. 不必提前运行 api_v2.bat。点击生成时，声伴先检测接口；未启动时使用配置的 Python 在后台运行 api_v2.py，并等待模型就绪后合成。查看已有文件、播放音频、启动声伴及检测连接都不会启动 API。日志在数据目录的 sovits-api.log；退出声伴会回收自建 API，原本由其他程序启动的接口不受影响。
3. 填写台词、参考音频及逐字原文，生成时向 API 地址的 `/tts` 发送请求，接收完整 WAV，再以台词命名保存。

“生成并保存语音”和“按分类生成勾选台词”使用当前选中的模型/参考字段快照。分类生成若全部命中已有音频而跳过，不会启动 API。退出会取消剩余任务并回收自建服务；外部已运行接口仍保留。

### 微软 Azure Speech 字段

| 字段 | 填写说明 |
|---|---|
| 完整合成接口地址 | 使用自己的资源 endpoint，例如 `https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1`。 |
| API Key | Azure Speech 资源密钥，保存在 Windows 凭据管理器。 |
| 密钥环境变量名 | 可选，例如 AZURE_SPEECH_KEY。填变量名字而非密钥；直接填写 Key 优先。 |
| 音色 ID | Azure 支持的音色，如 zh-CN-XiaoxiaoNeural，不是本地 WAV 路径。 |
| 语言区域 | 如 zh-CN，应与选用音色相符。 |
| 语速 | 1.0 为普通速度，可调 0.5–2.0。 |

### OpenAI 兼容 TTS 字段

| 字段 | 填写说明 |
|---|---|
| 完整合成接口地址 | 服务提供方完整 `/audio/speech` endpoint，不能只填网站首页。 |
| API Key/环境变量名 | 按服务要求填写，本机免鉴权兼容服务可以留空。 |
| 模型 ID | 供应商支持的 TTS 模型标识，本程序不内置固定模型。 |
| 音色 ID | 供应商支持的 voice 标识。 |
| 语速 | 0.5–2.0，服务可能有自己的限制。 |

兼容服务必须能返回 WAV；其他 JSON/MP3 协议需要通过扩展适配。远程地址要求 HTTPS。新增扩展可能提供额外字段，以扩展说明为准。

## 运行设置

| 控件 | 用途与注意事项 |
|---|---|
| 壁纸识别/音频播放/输入事件/壁纸库扫描/原壁纸声音检测扩展 | 选择已经加载的后端。保存后重启生效。 |
| WE 安装目录 | 包含 wallpaper32.exe/wallpaper64.exe 的文件夹，用于只读查询。 |
| 工坊目录 | 通常是 Steam 库下 workshop/content/431960，用于只读扫描和写入保护。 |
| 跟随显示器 | 从 0 开始，一次只跟随一台。 |
| 壁纸检测间隔 | 2–60 秒，只读轮询 WE 保存的当前选择，不启动 GUI 查询进程；WE 保存有延迟时识别也会延迟。 |
| 保存运行设置 | 保存路径和间隔，扩展变更需要重启。 |
| 开机自启按钮 | 选择当前 Windows 用户登录后是否托盘启动；默认关闭，开启前确认程序环境已固定。 |
| ffprobe 路径 | 可选 ffprobe.exe。留空从 PATH 查找；没有工具仍能用其他功能，但视频音轨会显示未知。修改后再保存运行设置。 |
| 本地扩展列表 | 插件放入 plugins 后重启可列出，勾选保存并再重启启用。只有信任源码才启用。 |
| 打开扩展/数据目录 | 打开源码插件位置或配置、日志、默认音频所在位置。 |
| 打开使用说明 | 打开简版 README；顶部“打开使用手册”打开本文。 |

自启不会启动 GPT-SoVITS API。想生成声音仍需启动对应服务，但已缓存/下载的音频离线可播。

## 运行记录与排查

运行记录显示配置启用、规则触发、选曲、生成进度、扫描提示和错误，不保存键盘输入文本。列表保留最近若干条；启动/API 日志另在数据目录。

| 现象 | 优先检查 |
|---|---|
| 鼠标/按键没有语音 | 是否保存配置、是否为当前使用配置、是否在桌面、是否暂停、时间/冷却是否符合、音频目录是否有候选文件。 |
| BGM 不播 | BGM 开关、手动暂停、防冲突暂停、目录和音量。 |
| 生成成功但触发不播 | 生成目录和绑定语音目录是否一致；分类子目录/关键词是否匹配；生成页文字与台词库是否混淆。 |
| 不想所有壁纸共享台词 | 给它选择不同资源根目录，或点击建立专用音频目录。原共享文件仍保留。 |
| 切换壁纸跟随不及时 | 看识别来源，WE 保存配置可能延迟；立即检测或临时用手动模式。 |
| 云端检测成功却无法生成 | 格式校验不是鉴权成功，检查 endpoint、Key、模型、音色、额度和服务返回格式。 |
| 删配置后还有音频文件 | 这是保留资源的设计，便于重新绑定，也保护其他共享配置。 |
| 悬停没有文字 | 开启顶部开关，鼠标保持约 1 秒，确保不是正在输入或拖动。 |

源码、扩展和依赖详情分别见 README.md、EXTENSIONS.md、THIRD_PARTY.md。


音频库的“打开所选文件目录”在未选文件时打开当前筛选中首个可见音频的目录；列表为空会明确提示。支持 Ctrl/Shift 多选、全选当前列表与全不选，复制和删除作用于全部所选音频。

悬停在音频库单元格时显示完整文件名、用途及实际目录、精确字节数或完整路径；同一列里移动到别的文件会更新内容。只有悬停在列标题上才显示该列的功能说明。是否显示仍由顶部“悬停说明”开关控制。

语音生成页的“播放参考音频”直接播放当前参考文件，支持按 GPT-SoVITS 项目目录解析相对路径，不需要启动 API；同一行的“停止参考试听”可停止当前试听。

页面自动保存提供单步撤销；实时播放器音量、开机自启、手动保存、文件删除等原有即时动作不在这一撤销范围。音频删除请从系统回收站恢复，系统自启请用原开关调整。