Back to Details

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
or 
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账户相关的任何许可/套餐假设。