内容
# make-sfx
[](https://github.com/Tuntii/make-sfx/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/make-sfx-core)
[](https://www.npmjs.com/package/make-sfx-mcp)
**代码驱动的游戏音效，支持广播式响度控制。** Remotion，但适用于声音。
**[▶ 在线演示](https://tuntii.github.io/make-sfx/)** · [npm 核心库](https://www.npmjs.com/package/make-sfx-core) · [npm MCP 服务器](https://www.npmjs.com/package/make-sfx-mcp)
通过代码生成跳跃、硬币、激光和 UI 点击音效 — 或用自然语言**描述**它们，让 AI 代理通过 MCP 服务器渲染。每个声音都针对特定类别的响度目标进行控制，这样它就能在混音中合适地响起，而不需要手动调整增益。
## 60 秒了解 make-sfx
**在代码中** — 预设生成 WAV：
```typescript
import { presets, renderSound } from "make-sfx-core";
import { writeFileSync } from "node:fs";
writeFileSync("jump.wav", renderSound(presets.jump)); // Uint8Array → WAV
```
**或描述它** — 一个 MCP 调用生成 WAV + 可重复使用的代码：
```
sfx_from_description({ description: "coin pickup, a jump, and a higher-pitched blink",
outputDir: "./assets/sfx" })
```
```bash
npm install make-sfx-core # 游戏声音合成引擎
npx make-sfx-mcp # MCP 服务器，用于 Cursor / Claude（无需安装）
```
## 为什么 make-sfx 与众不同
- **描述 → 声音。** 自然语言通过 MCP 服务器变成真正的 WAV 文件 —
无需数字音频工作站（DAW），无需寻找样本。
- **内置响度控制。** 每个声音都针对特定类别的响度目标（UI −14，
战斗 −9，拾取 −12，环境 −18，惊喜 −11）使用 **ITU-R BS.1770 K-weighting**
和 **过采样峰值限制器**（≤ −1 dBTP）。明亮的硬币和沉重的碰撞声在听觉上同样响亮，
而不仅仅是在 RMS 值上相等。
- **确定性变体。** 一个 `seed` 产生可复制的微变体 — 相同的 seed，
相同的 WAV，字节对字节 — 因此构建和资产差异保持稳定。
### 与其他工具的比较
| 特性 | make-sfx | ZzFX | sfxr / bfxr / jsfxr |
|--------------------------|-----------------------------------|-----------------------|------------------------------|
| **参数表面** | 70+（层，LFO，纹理，FX） | ~22（平面） | ~25–35（GUI 关注） |
| **合成模型** | 分层 + 调制器 + 纹理 + 控制 | 单个振荡器 + 效果 | 单个振荡器 + 有限效果 |
| **响度控制** | ITU-R BS.1770 K-weight + 峰值限制器（每类别 LUFS） | 无 | 无 |
| **确定性种子** | 是（字节相同的变体） | 基本随机性 | 随机 / 变异仅限 |
| **代码优先 / 库** | 完整的 TS 配置，Node + 浏览器 | 是（微小） | 部分（一些端口） |
| **AI / 自然语言**| MCP 工具（`sfx_from_description`） | — | — |
| **导出** | 控制后的 WAV + 可重复使用的代码 | WAV（浏览器） | WAV |
| **使用场景** | 生产游戏音频 + AI 代理 | 小型演示 / js13k | 快速的复古原型设计 |
## 音效工程（70+ 参数）
一切都是一个普通的配置对象；渲染管道是
`层 → 调制器 → 纹理 → 主控包络 → 效果 → 响度控制 → WAV`。
<details>
<summary><b>完整参数表面</b></summary>
| 组 | 数量 | 亮点 |
|-------|-------|-----------|
| 合成器 | 21 | 音量，频率，波形，ADSR，音高滑动，FM，颤音，滤波器，位元破坏，延迟 |
| 主控 | 5 | `duration`（秒！），尾部，fadeIn，fadeOut，durationScale |
| 振荡器层 | 4 | 混合，失谐，延迟，每层覆盖 |
| LFO 调制器 | 4 | 幅度 / 音高 / 滤波器目标，速率，深度，形状 |
| 纹理 | 11 | 合唱，移相器，裂纹，次声波，瞬态，闪烁，门，粒状，环形调制，失真 |
| 效果 | 12 | 混响，延迟，3频段 EQ，压缩，饱和度，立体声宽度，限制器 |
| 调整旋钮 | 6 | `pitchShift`，`brightness`，`warmth`，`punch`，`grit`，`space` |
</details>
```typescript
import { renderSound, presets } from "make-sfx-core";
renderSound({
params: presets.laser,
master: { duration: 0.3, fadeOut: 0.1 },
oscillators: [{ enabled: true, mix: 0.4, detune: 7 }],
modulators: [{ enabled: true, target: "pitch", rate: 12, depth: 0.4 }],
texture: { chorus: 0.3, phaser: 0.2 },
fx: { reverbMix: 0.3, eqHigh: 4, stereoWidth: 0.5 },
});
```
游戏预设 (`GAME_PACK_DESIGNS`，与 MCP `sfx_design_batch` 相同) 提供扩展的默认值 —
持续时间，层，纹理 — 因此描述工作流程听起来很棒：
```typescript
import { buildSoundConfig, GAME_PACK_DESIGNS, renderSound } from "make-sfx-core";
renderSound(buildSoundConfig(GAME_PACK_DESIGNS[0])); // 完全设计的跳跃音效
```
## 预设（18）
`jump` `blink` `coin` `hit` `explosion` `click` `powerup` `gameover` `laser`
`swoosh` `footstep` `alarm` `shield` `success` `error` `menu` `door` `reload` `engine`
命令行：
```bash
npx make-sfx-core --preset jump --out jump.wav
npx make-sfx-core --preset blink --pitch-shift 1.5 --out blink.wav
```
## MCP 集成（Cursor / Claude）
```json
{ "mcpServers": { "make-sfx": { "command": "npx", "args": ["-y", "make-sfx-mcp"] } } }
```
工作流程：`sfx_from_description` 一步到位，或 `sfx_help` → `sfx_describe`（预览）→
`sfx_from_description`（生成）。
| 工具 | 描述 |
|------|-------------|
| `sfx_from_description` | **主要** — 自然语言 → WAV + 代码 |
| `sfx_describe` | 解析描述为配置（预览） |
| `sfx_game_pack` | 标准游戏包 + 可选种子 `variants` |
| `sfx_refine` | 用自然语言优化现有设计 |
| `sfx_help` | 工作流程 + 示例 |
| `sfx_get_parameters` | 70+ 参数，范围，单位，`aiHint` |
| `sfx_list_design_profiles` | 8 个设计起点 |
| `sfx_list_presets` | 18 个预设（标签筛选） |
| `sfx_design` / `sfx_design_batch` | 手动完全控制（70+ 参数） |
| `sfx_create` / `sfx_batch_create` | 快速预设工作流程 |
| `sfx_export` | 导出到特定 WAV 路径 |
## 浏览器播放
```typescript
import { play } from "make-sfx-core/browser";
import { buildSoundConfig, GAME_PACK_DESIGNS } from "make-sfx-core";
play(buildSoundConfig(GAME_PACK_DESIGNS[0]));
```
## 软件包
- **`make-sfx-core`** — 合成引擎，70+ 参数，响度控制，`buildSoundConfig`，`GAME_PACK_DESIGNS`
- **`make-sfx-mcp`** — MCP 服务器，用于 AI 代理（描述 → WAV）
- **`@make-sfx/playground`** — 网页声音设计器
## 开发
```bash
pnpm install && pnpm build && pnpm test
pnpm dev:playground # http://localhost:5173 的声音设计器（70+ 实时参数）
pnpm example:generate # 从 GAME_PACK_DESIGNS 渲染 assets/sfx/*.wav
pnpm example:game # 本地演示页面
pnpm demo:gif # 通过 Remotion 渲染 docs/demo.gif（~15s）
pnpm publish:packages # 维护者
```
本地 MCP 开发（在 `pnpm build` 之后）：将您的配置指向
`node ./packages/mcp/dist/server.js`。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和
[好第一个问题](https://github.com/Tuntii/make-sfx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
## 许可证
MIT — ZzFX 合成算法 © Frank Force（MIT），在 `make-sfx-core` 中使用。
