---
name: forgeax-audio-production
description: Generate music, sound effects, or voice with ForgeaX LiteLLM and import audio into the current ForgeaX Engine game.
---

# ForgeaX audio production

Run these commands from the initialized game directory. `{{CLI}}` is supplied by the main ForgeaX installer; never call the extension module directly.

For FPS games, plan and deliver **at least 4 distinct same-type single-shot gunshot clips per weapon sound type**. Preserve weapon identity, mechanism, perspective and acoustic space, with subtle attack/mechanical/tail variations; each clip contains one shot, not a burst. Copies or gain/pitch-only edits do not count. Use a shared base generation prompt with individual variation directions, and check usable outputs rather than request count. With the audio Pack workflow, place the primary clip plus at least 3 pinned variants in one Pack using `random-no-repeat`; otherwise implement equivalent selection in project-owned native code. Each actual shot selects one clip without immediate repeats. A set below 4 is incomplete; preserve the user's asset-source choice and paid-generation scope.

1. Check setup with `{{CLI}} doctor --json`. If the extension is not enabled, tell the user to enable it. Do not read or display credentials.
2. Generate a take with `{{CLI}} generate --kind sfx --prompt "..." --duration-seconds 1 --json`. Choose `bgm` or `voice` instead of `sfx` when requested. This calls the configured audio model once; do not repeat a paid request automatically after a timeout or unclear result. Read the returned `takeId` and local WAV path.
3. Let the user audition the returned WAV. `{{CLI}} audition --take-id <id> --json` also returns an offline HTML player. A generated take is temporary until imported.
4. Import the selected take with `{{CLI}} import --take-id <id> --name "descriptive name" --json`. Use the returned asset GUID and file paths. The importer writes an Engine `audio` sidecar next to the WAV; imported game assets survive extension disable.
5. For gameplay integration, use `forgeax-audio-interaction` when installed. Otherwise perform the same authoring work directly: read the game's installed Engine interfaces, `forge.json` schema 3 roots and real gameplay; add the necessary event hooks and project-owned native PluginAsset code, then verify the asset through the actual build/catalog. An imported sidecar alone does not establish a loadable native asset. Keep custom logic outside generated audio files, preserve other roots, and use the Engine's existing lifecycle. Do not copy the old singleton or add a separate audio backend. Engine/SDK implementation stays unchanged; missing primitives go to the Engine developer. Do not add a demo button to a real game unless requested.
6. Use the main `forgeax-game` workflow to build and open the Engine-owned Preview. Trigger the target event. Report the exact build/Preview result and playback observation. A generated or imported file alone does not prove the game plays it.

`{{CLI}} takes --json` lists staged takes and `{{CLI}} assets --json` lists imported audio. Each command returns the main CLI JSON envelope. On failure, report the stable error code and next action; do not invent an audio result or claim a game Preview passed without running it.

This extension requires host API 1 and supports exact Engine 0.2.1 / 0.3.3 / 0.4.3 / 0.4.8 projects. The extension checks the host interface, declared and installed project dependency, and schema 3 roots before use. A missing Engine installation is not runtime verification; install the project dependencies before building.

Before final audio delivery, use `forgeax-audio-mixing` when installed to check sound hierarchy, actual playback gain, harshness and repeated-trigger overlap. Keep measurement, runtime playback and listening acceptance distinct; peak normalization or a successful import alone is not a finished mix.

When the standalone `forgeax-audio-cli` skill is available, use its sound-design workflow for reusable direction, coverage, candidate review, layered Packs and final quality checks. Those `quality` / `pack compose` commands belong to the standalone CLI, not this extension's `{{CLI}}` surface. Do not invent equivalent embedded commands or claim its Editor UI implements the standalone workbench.