# 音效与版权说明

> 这份文档解释**为什么本仓库不附带作者使用的音效**，以及**你该怎么换成自己的声音**。
> 如果你只想知道怎么用，直接跳到 [使用者：换成你自己的音效](#使用者换成你自己的音效)。

---

## 一句话

本仓库发布的是**机制**（插件代码 + 安装器 + 文档）加上**六个自己合成的示例音效**，但**不发布任何来源不明的第三方素材**。正式使用时请换成你自己的音频 —— 面板里有下拉菜单可以随时切换。

---

## 为什么不附带真实音效（这是刻意设计，不是遗漏）

音效素材的来源通常无法追溯：它可能来自游戏、影视、音乐、某个商用素材库，或者随手从网上保存下来的文件。

把这个来源不明的文件提交到公开仓库，等于**公开再分发**，后果包括：

- 触发 **DMCA 下架**（仓库被冻结，情节严重时影响账号）；
- 收到素材方的侵权主张；
- 更麻烦的是：仓库一旦被 fork，即使你之后删除，副本仍在别人手里。

而这个插件的价值**完全不依赖任何特定音频** —— 它做的事情是"在正确的时刻调用 Windows 播放器播放一个 WAV 文件"。所以本项目的边界划得很清楚：

> **代码开源，音效自备。**

这也让仓库更小（不塞几百 KB～几 MB 的二进制）、更干净，并且避免每个使用者都被迫接受作者的音效审美。

---

## 仓库里现在有哪些音频

### 自带示例（已提交，CC0）

`assets/library/` 下有六个示例音效，装好后会出现在面板下拉菜单的「自带示例」分组里：

| 文件 | 特点 | 时长 |
|---|---|---|
| `01-soft-chime.wav` | C5+E5 柔和双音（**开场音的默认**） | 1.24 秒 |
| `02-bell.wav` | A5+E6 铃声、带长尾 | 1.57 秒 |
| `03-marimba.wav` | C5-E5-G5 快速琶音 | 1.09 秒 |
| `04-blip.wav` | 极短高频点按音 | 0.22 秒 |
| `05-two-tone-up.wav` | G5→C6 上行双音（**完成音的默认**） | 0.91 秒 |
| `06-two-tone-down.wav` | C6→G5 下行双音 | 0.92 秒 |

它们全部**用正弦波现场合成**，不含任何采样、音源库或第三方素材，因此作者可以完整放弃权利：

> **`assets/library/` 下的示例音频以 [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/)（公有领域奉献）发布**，可任意使用、修改、再分发，无需署名。
>
> 代码本身以 [MIT](LICENSE) 发布。

### 你自己的音效（不在仓库里）

通过面板添加的音效默认存放在：

```
%USERPROFILE%\.dsh\chimes-library\
```

这个目录**在仓库之外**，所以你的音频永远不会被 `git status` 看到、也不可能被误提交。面板下拉菜单的「我的音效」分组列的就是这里的内容。

### 换到别的盘（C 盘空间紧张时）

不用改代码，在 `%USERPROFILE%\.dsh\chimes-state.json` 里加一行即可：

```json
{ "version": 1, "libraryDir": "D:\\AA素材" }
```

优先级：环境变量 `DSH_CHIMES_LIBRARY` → 状态文件里的 `libraryDir` → 默认路径。改完把音频拷过去、面板点「刷新」。**若某个选择指向的文件已不存在**（换了盘、重命名了文件），插件会依次回退到 `assets/chime.wav`、自带示例音，**不会变成静音**。

### 可复现的合成命令

占位音不是"某个文件"，而是两条命令的产物 —— 你可以自己跑一遍验证：

```bash
# 开场音：C5 -> B5 上行两音 + 轻微回声
ffmpeg -y -f lavfi -i "sine=frequency=523.25:duration=1.0" \
       -f lavfi -i "sine=frequency=987.77:duration=1.0" \
       -filter_complex "[0:a]afade=t=in:st=0:d=0.008,afade=t=out:st=0.30:d=0.55,volume=0.30[a];\
[1:a]adelay=230,afade=t=in:st=0:d=0.008,afade=t=out:st=0.35:d=0.6,volume=0.26[b];\
[a][b]amix=inputs=2:duration=longest:normalize=0,aecho=0.7:0.5:70:0.28" \
       -map_metadata -1 -fflags +bitexact -acodec pcm_s16le -ar 44100 -ac 2 sample-startup.wav

# 完成音：G5 -> C6，更短
ffmpeg -y -f lavfi -i "sine=frequency=783.99:duration=0.7" \
       -f lavfi -i "sine=frequency=1046.50:duration=0.7" \
       -filter_complex "[0:a]afade=t=in:st=0:d=0.006,afade=t=out:st=0.18:d=0.35,volume=0.30[a];\
[1:a]adelay=150,afade=t=in:st=0:d=0.006,afade=t=out:st=0.18:d=0.35,volume=0.26[b];\
[a][b]amix=inputs=2:duration=longest:normalize=0,aecho=0.6:0.45:60:0.22" \
       -map_metadata -1 -fflags +bitexact -acodec pcm_s16le -ar 44100 -ac 2 sample-done.wav
```

---

## 使用者：换成你自己的音效

### 格式要求（唯一的硬性限制）

播放走的是 Windows 的 `Media.SoundPlayer`，它**只支持 WAV**：

- 必须是 **PCM WAV**（`pcm_s16le`，16-bit）
- 采样率/声道随你（推荐 44100Hz、立体声）

**把 mp3 改名成 `.wav` 是不会响的** —— 现象是日志里出现 `player exited code=1`（或几十毫秒就退出）而完全没有声音。必须先转码：

```powershell
ffmpeg -y -i 你的音效.mp3 -acodec pcm_s16le -ar 44100 -ac 2 输出.wav
```

**音量也只能在这一步烘焙**（`SoundPlayer` 没有音量 API）：

```powershell
# 嫌小 → 放大 1.5 倍；嫌大 → 0.6 倍
ffmpeg -y -i 你的音效.mp3 -af "volume=1.5" -acodec pcm_s16le -ar 44100 -ac 2 输出.wav
```

**建议时长 1～5 秒**，并掐掉开头静音，否则会"点了图标过一会儿才响"：

```powershell
ffmpeg -y -i 你的音效.mp3 -af "silenceremove=start_periods=1:start_threshold=-50dB" `
       -acodec pcm_s16le -ar 44100 -ac 2 输出.wav
```

### 三种换法

**① 用安装器（推荐，一步到位）**

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-chime.ps1 -Audio "D:\你的音效.mp3"
```
脚本会自动转码、掐静音、放进插件目录、装进 DSH profile。想给两个音效分别指定就传两个参数（见 README）。

**② 直接替换文件（最快，不用重装）**

插件是**按固定路径 + 固定文件名**播放的，所以只要路径和文件名不变，**覆盖文件内容即可**，下次触发就是新声音：

```
%USERPROFILE%\.dsh\plugin-src\dsh-plugin-startup-chime\assets\chime.wav   ← 开场音
%USERPROFILE%\.dsh\plugin-src\dsh-plugin-done-chime\assets\success.wav    ← 完成音
```

- **完成音效**：覆盖后**不用重启**，下一轮对话结束就是新声音；
- **开场音效**：需要**重启一次 DSH** 才能听到（它只在启动瞬间播）；
- 如果提示文件被占用，等一两秒重试（正在播放的文件有句柄）。

**③ 改配置指向别处**

在 profile 的 `cordis.patch.yml` 里给对应行加 `wavPath`：

```yaml
- insert:
    - id: startup-chime
      name: dsh-plugin-startup-chime
      config:
        wavPath: 'D:\我的音效\开场.wav'
```

---

## 贡献者：提交 PR 时的约定

- **不要提交第三方音频。** 包括游戏提取音、影视片段、音乐片段、商用素材库下载物 —— 无论它多小、多好听。
- **自制音效可以提交**（例如你用 Audacity/ffmpeg 录或合成的），但请在 PR 描述里明确写："本人创作，同意以 CC0-1.0 授权"。
- **体积与时长的建议**：单个音频 ≤ 1 MB、时长 ≤ 5 秒。仓库不该因为音效膨胀。
- 如果你要加新的示例音频，请同步更新本文档的表格与授权说明。

---

## 常见误解

**"我改了仓库里的音频，为什么没生效？"**
因为插件播放的是 **DSH profile 里安装的那个副本**（默认在 `%USERPROFILE%\.dsh\plugin-src\...`），不是仓库里的文件。除非你用 `wavPath` 显式指过去。

**"我只是自己用，仓库不发布，应该没关系吧？"**
自己本机使用、不传播，这是你的自由；本文档约束的只是**提交到公开仓库**这件事。

**"那我把音效放在 releases 里，不放仓库，可以吗？"**
不可以。Release 附件同样是公开再分发，法律性质与放在仓库里相同。