threejs-audio-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Three.js Audio Generator

Three.js 音频生成工具

Purpose

用途

Create game-ready audio assets for Three.js projects. This skill consolidates game sound generation, voice generation/conversion, audio cleanup, credential probing, and runtime integration into one Three.js-focused production workflow.

Provider: ElevenLabs.

Resolve

<this-skill-dir>

in the commands below in this order:

~/.claude/skills/threejs-audio-generator

~/.codex/skills/threejs-audio-generator

~/.agents/skills/threejs-audio-generator

, or repo

skills/threejs-audio-generator

为Three.js项目创建适配游戏的音频资源。该工具将游戏音效生成、语音生成/转换、音频清理、凭证探测以及运行时集成整合为一套专注于Three.js的生产工作流。

提供商：ElevenLabs。

按以下顺序解析命令中的

<this-skill-dir>

：

~/.claude/skills/threejs-audio-generator

、

~/.codex/skills/threejs-audio-generator

、

~/.agents/skills/threejs-audio-generator

，或仓库路径

skills/threejs-audio-generator

。

When To Use

适用场景

Use this skill for:

SFX: jumps, hits, weapons, explosions, coins, pickups, collisions, UI clicks, confirms, errors.
Ambience: wind, rain, city bed, engine hum, portal loop, dungeon room tone, battle arena beds.
Voice: announcer barks, boss lines, tutorial prompts, menu narration, generated placeholder dialogue.
Voice conversion: convert a scratch performance into a target character voice while preserving timing and emotion.
Cleanup: isolate or denoise dialogue before voice conversion, TTS replacement, or transcription.
Three.js integration: Web Audio loading, looping, sprite/manifest mapping, volume groups, pause/resume, user gesture unlock.

For premium/AAA/showcase game work, audio is not cosmetic. Generate or integrate at least a minimal interaction audio set for the main loop unless the user explicitly requests mute/offline-only output or credentials/API attempts are blocked.

以下场景可使用本工具：

音效（SFX）：跳跃、撞击、武器、爆炸、金币、拾取、碰撞、UI点击、确认、错误提示音。
环境音：风声、雨声、城市背景音、引擎轰鸣、传送门循环音、地牢场景音、战斗竞技场背景音。
语音：旁白播报、Boss台词、教程提示、菜单旁白、生成的占位对话。
语音转换：将临时配音转换为目标角色语音，同时保留时长与情感。
音频清理：在语音转换、TTS替换或转录前分离对话或降噪。
Three.js集成：Web Audio加载、循环播放、精灵/清单映射、音量组、暂停/恢复、用户手势解锁。

对于精品/AAA级/展示类游戏，音频并非装饰性元素。除非用户明确要求静音/仅离线输出，或凭证/API请求被阻止，否则至少为主循环生成或集成一套基础交互音频集。

API Key

API密钥

Never store API keys in skill files or browser/game code, and never paste a key value into a report. The script reads

--api-key

ELEVENLABS_API_KEY

Step 0, before declaring the key unavailable: run this skill's own probe and paste its literal output into the report.

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py probe   # prints ELEVENLABS_API_KEY=SET|MISSING

ELEVENLABS_API_KEY=MISSING

is only a valid skip/blocker reason when this output is shown. Keys defined only in a shell profile can be absent from the process env; if the plain probe prints MISSING unexpectedly, wrap it:

zsh -lc 'source ~/.zprofile 2>/dev/null || true; source ~/.zshrc 2>/dev/null || true; python3 <this-skill-dir>/scripts/threejs_audio_asset.py probe'

. When the director skill is loaded, prefer

threejs-game-director/scripts/probe_asset_credentials.sh

, which probes all three asset keys at once.

Audio-specific: add

--validate

to the probe to call ElevenLabs

GET /user

and confirm the key actually works (prints

VALID_USER=...

); use it when a key is present but a generation still fails. A valid key can still be blocked by an out-of-credit or plan-tier limit — those surface as an

HTTP 4xx

from a real generation attempt. Report that as a purchase/plan blocker, do not silently skip.

请勿在工具文件或浏览器/游戏代码中存储API密钥，也请勿将密钥值粘贴到报告中。脚本会读取

--api-key

参数或

ELEVENLABS_API_KEY

环境变量。

在声明密钥不可用之前，先执行步骤0：运行本工具的探测脚本，并将其输出原样粘贴到报告中。

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py probe   # 输出ELEVENLABS_API_KEY=SET|MISSING

只有当探测输出为

ELEVENLABS_API_KEY=MISSING

时，才是有效的跳过/阻塞理由。仅在shell配置文件中定义的密钥可能不会出现在进程环境中；如果探测意外输出MISSING，请用以下命令包裹：

zsh -lc 'source ~/.zprofile 2>/dev/null || true; source ~/.zshrc 2>/dev/null || true; python3 <this-skill-dir>/scripts/threejs_audio_asset.py probe'

。当加载了主管工具时，优先使用

threejs-game-director/scripts/probe_asset_credentials.sh

，它可一次性探测所有三个资产密钥。

音频专属操作：在探测命令中添加

--validate

参数，调用ElevenLabs的

GET /user

接口确认密钥是否有效（会输出

VALID_USER=...

）；当密钥存在但生成仍失败时使用此参数。有效密钥仍可能因余额不足或套餐层级限制被阻止——这类情况会在实际生成请求中返回

HTTP 4xx

错误。请将此报告为购买/套餐阻塞问题，不要静默跳过。

Required Reference

必查参考文档

Load

references/audio-workflows.md

before building a game audio plan, generating multiple assets, wiring runtime audio, cleaning/converting voices, or claiming premium game audio.

Track it in the reference ledger. Do not mark the audio phase complete while this reference is skipped.

在制定游戏音频方案、生成多个资产、连接运行时音频、清理/转换语音或处理精品游戏音频之前，请加载

references/audio-workflows.md

文档。

在参考台账中记录该文档。如果跳过此参考文档，请勿标记音频阶段完成。

Tool Script

工具脚本

Run from the user's current game project directory:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py --help

Probe:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py probe

Generate SFX:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py sfx \
  --prompt "tight futuristic boost pickup, bright transient, short sparkling tail, arcade racing game" \
  --duration 1.2 \
  --prompt-influence 0.65 \
  --out assets/audio/sfx/boost-pickup.mp3

Generate looping ambience:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py sfx \
  --prompt "seamless cyber resort mini golf ambience, distant surf, soft neon transformer hum, gentle crowd bed" \
  --duration 12 \
  --loop \
  --prompt-influence 0.45 \
  --out assets/audio/ambience/cyber-resort-loop.mp3

Generate TTS/announcer line:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py tts \
  --text "Perfect shot." \
  --voice-id JBFqnCBsd6RMkjVDRZzb \
  --out assets/audio/voice/perfect-shot.mp3

Clean dialogue:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py isolate \
  --input assets/audio/source/noisy-boss-line.wav \
  --out assets/audio/voice/boss-line-clean.mp3

Convert a scratch performance to a target voice:

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py voice-change \
  --input assets/audio/source/scratch-boss-line.wav \
  --voice-id JBFqnCBsd6RMkjVDRZzb \
  --remove-background-noise \
  --out assets/audio/voice/boss-line-final.mp3

从用户当前的游戏项目目录运行：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py --help

探测密钥：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py probe

生成音效：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py sfx \
  --prompt "tight futuristic boost pickup, bright transient, short sparkling tail, arcade racing game" \
  --duration 1.2 \
  --prompt-influence 0.65 \
  --out assets/audio/sfx/boost-pickup.mp3

生成循环环境音：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py sfx \
  --prompt "seamless cyber resort mini golf ambience, distant surf, soft neon transformer hum, gentle crowd bed" \
  --duration 12 \
  --loop \
  --prompt-influence 0.45 \
  --out assets/audio/ambience/cyber-resort-loop.mp3

生成TTS/旁白台词：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py tts \
  --text "Perfect shot." \
  --voice-id JBFqnCBsd6RMkjVDRZzb \
  --out assets/audio/voice/perfect-shot.mp3

清理对话音频：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py isolate \
  --input assets/audio/source/noisy-boss-line.wav \
  --out assets/audio/voice/boss-line-clean.mp3

将临时配音转换为目标语音：

bash

python3 <this-skill-dir>/scripts/threejs_audio_asset.py voice-change \
  --input assets/audio/source/scratch-boss-line.wav \
  --voice-id JBFqnCBsd6RMkjVDRZzb \
  --remove-background-noise \
  --out assets/audio/voice/boss-line-final.mp3

Game Audio Defaults

游戏音频默认配置

SFX:
```
mp3_44100_128
```
, 0.5-2.5s, prompt influence
```
0.55-0.8
```
.
UI: 0.15-0.8s, high prompt influence, keep transients clear.
Ambience loops: 8-30s,
```
--loop
```
, prompt influence
```
0.3-0.55
```
.
Voice: TTS for clean generated lines; voice-change when timing/acting from a scratch performance matters.
Cleanup: isolate noisy speech before voice-change or final dialogue use.
Runtime: generate locally, commit/import files, and load them via Web Audio/Three.js integration. Never put API keys in browser code.

音效（SFX）：格式
```
mp3_44100_128
```
，时长0.5-2.5秒，提示词影响度
```
0.55-0.8
```
。
UI音效：时长0.15-0.8秒，高提示词影响度，保持清晰的瞬态音。
循环环境音：时长8-30秒，添加
```
--loop
```
参数，提示词影响度
```
0.3-0.55
```
。
语音：生成清晰台词用TTS；当临时配音的时长/表演很重要时用语音转换。
音频清理：在语音转换或最终使用对话前分离含噪语音。
运行时：本地生成音频，提交/导入文件，通过Web Audio/Three.js集成加载。切勿在浏览器代码中放入API密钥。

Required Report

必交报告

Report:

Credential probe output or real blocker.
Reference ledger.
Generated/processed file paths.
Prompts/text/input files, voice IDs, durations, loop flags, and output formats.
Runtime integration notes: audio groups, trigger events, loop behavior, unlock gesture, pause/resume, volume/mute controls.
Remaining audio gaps and any licensing/plan assumptions tied to the user's ElevenLabs account.

报告需包含：

凭证探测输出或实际阻塞原因。
参考台账记录。
生成/处理后的文件路径。
提示词/文本/输入文件、语音ID、时长、循环标记、输出格式。
运行时集成说明：音频组、触发事件、循环行为、解锁手势、暂停/恢复、音量/静音控制。
剩余音频缺口，以及与用户ElevenLabs账户相关的任何许可/套餐假设。