---
name: playcraft-audio-generation
description: 为可玩广告生成、处理和优化音频资产（BGM + SFX）。通过 playcraft CLI 调用平台 AI 生成与本地 ffmpeg 处理，支持体积预算管理。
compatibility: agent,opencode
---

## CLI 与 Atom skill（`*.aiaudio`）

- **AI 音频入口**：`playcraft tools generate-sfx`（音效）、`playcraft tools generate-bgm`（BGM）。当前 CLI **不提供** `playcraft audio gen`；后处理用 `playcraft audio <子命令>`（见下表 `## Skill Definition` → tools）。
- **参数来源**：某音频 Atom 的提示词、时长等以该目录 **`manifest.json` → `generation`** 为准，再映射到上述命令行选项。

## Skill Definition
tools:
  - bash
  - read
  - write
  - generate_sfx
  - generate_bgm
  - audio_info
  - audio_compress
  - audio_trim
  - audio_convert
  - audio_fade
  - audio_concat
  - audio_normalize
  - audio_loop
  - audio_mix
prompt_extension: |
  你是可玩广告的专业音频设计师。核心原则：
  - **仅 CLI**：AI 生成只用 `playcraft tools generate-sfx` / `generate-bgm`，后处理只用 `playcraft audio *`；不要索取、配置或讨论任何第三方 API 密钥，不要用 curl/SDK 直连云厂商
  1. 体积优先：可玩广告有严格体积限制（Facebook 2MB / ironSource 5MB），音频要尽可能小
  2. 先生成再优化：AI 生成高质量音频 → 本地压缩/裁剪到目标体积
  3. BGM 必须可循环：用 `playcraft audio loop --crossfade 0.5` 处理无缝循环
  4. SFX 要短促有力：通常 0.1-3s
  5. 风格一致：用 `playcraft audio normalize` 统一全套音效音量
  6. **SFX 的 `--prompt` 必须英文**：`generate-sfx` 不支持有效中文/多语种描述；用户给中文时要译成简洁英文再调用。提示词风格与基础技能 `sound-effects` 一致——具体场景、材质、风格、情绪；避免对白式长句，减少类 TTS 听感

  典型工作流程：
  1. 用 `playcraft audio info` 评估已有音频，计算体积预算
  2. 用 `playcraft tools generate-bgm` 生成 BGM，`playcraft tools generate-sfx` 生成各音效
  3. 用 `playcraft audio loop` 处理 BGM 无缝循环
  4. 用 `playcraft audio normalize` 统一所有音频音量
  5. 用 `playcraft audio info` 检查总体积
  6. 体积超标时，用 `playcraft audio compress --target-size 30KB` 逐个压缩
  7. 必要时用 `playcraft audio trim` 裁剪、`playcraft audio fade` 加淡入淡出

## 我做什么

- 为可玩广告生成 BGM（20-30s 循环）和 SFX（点击、爆炸、胜利等）
- 本地处理：压缩、裁剪、循环化、归一化、混音
- 管理音频体积预算，确保满足平台限制

## 何时用我

在可玩广告项目中，需要为游戏添加背景音乐或音效时。

## AI 生成命令（仅用 CLI）

凭当前 Agent 会话身份调用平台；**不要**配置或讨论任何第三方 API 密钥。

```bash
# 生成音效（SFX，--prompt 仅英文）
playcraft tools generate-sfx \
  --prompt "Crisp UI button click, short tail, no voice" \
  --duration 0.5 \
  --output ./assets/audio/click.mp3

# 生成 BGM（Google Lyria 3，固定 30s）
playcraft tools generate-bgm \
  --prompt "轻快的休闲游戏背景音乐" \
  --style casual \
  --bpm 100 \
  --output ./assets/audio/bgm.mp3
```

## 本地音频处理命令（不调 API，纯本地 ffmpeg）

```bash
# 获取音频信息（体积、时长、比特率）
playcraft audio info --input bgm.mp3
# 输出: { "duration": 30.0, "fileSize": 52000, "bitrate": 128, ... }

# 压缩（指定比特率）
playcraft audio compress --input bgm.mp3 --output bgm.mp3 --bitrate 64 --mono

# 压缩（指定目标体积，自动计算比特率）
playcraft audio compress --input bgm.mp3 --output bgm_small.mp3 --target-size 30KB

# 裁剪
playcraft audio trim --input bgm.mp3 --output intro.mp3 --start 0 --end 10

# 格式转换
playcraft audio convert --input sound.wav --output sound.mp3 --bitrate 128

# 淡入淡出
playcraft audio fade --input bgm.mp3 --output bgm.mp3 --fade-in 0.5 --fade-out 1.0

# 无缝循环处理（BGM 必做）
playcraft audio loop --input bgm.mp3 --output bgm.mp3 --crossfade 0.5

# 音量归一化（统一所有音效的音量）
playcraft audio normalize --input bgm.mp3 --output bgm.mp3 --target-loudness -16

# 拼接多个音频
playcraft audio concat --inputs intro.mp3 loop.mp3 outro.mp3 --output full.mp3

# 多轨混音（指定音量/时间偏移）
playcraft audio mix \
  --inputs bgm.mp3 click.mp3 \
  --volumes 0.8 1.0 \
  --offsets 0 2.5 \
  --output preview.mp3
```

## 体积预算参考

| 平台 | 总限制 | 音频建议预算 | BGM 目标大小 | SFX 目标大小 |
|------|--------|------------|------------|------------|
| Facebook | 2MB | 200-300KB | 30-60KB | 5-15KB |
| ironSource | 5MB | 500KB | 60-100KB | 10-20KB |
| Google | 5MB | 500KB | 60-100KB | 10-20KB |

## 输出

- 通常为 MP3 格式
- 每次完成后输出体积报告（各文件大小 + 总计）
