SK Wwise

Documentation

A modular suite of MCP (Model Context Protocol) servers for Audiokinetic Wwise, enabling AI agents to browse, edit, audition, profile, and build Wwise projects through the Wwise Authoring API (WAAPI).

Each server is capped at 15 tools to minimize LLM tool confusion, with Agent Skills routing for multi-agent orchestration.

Easy Setup (Windows, no Python required)

For Windows users who don't want to install Python or clone the repo:

1. Download sk-wwise-mcp.zip from the latest release.
2. Unzip anywhere on disk.
3. Open Wwise with WAAPI enabled (Project Settings → Authoring API → "Enable Wwise Authoring API").
4. Open a terminal in the unzipped folder and run:

   claude
   

5. Approve the MCP servers when prompted.

That's it. The bundle ships a single sk-wwise-mcp.exe (no Python install needed), a pre-configured .mcp.json registering all 12 servers, and .claude/skills/ for routing — all auto-discovered by Claude CLI on launch.

First launch shows a Windows SmartScreen warning because the binary isn't code-signed. Click More info → Run anyway once and Windows remembers it.

Using the bundle with other agents

The sk-wwise-mcp.exe speaks standard MCP over stdio, so it works with any MCP-compatible agent — Cursor, VS Code Copilot, Windsurf, Continue, Gemini CLI, etc. Auto-detection of a top-level .mcp.json is Claude Code-specific; other agents need the entries copied into their own config file. Generic shape, point your agent's MCP config at the exe with the matching --server arg:

{
  "command": "C:/path/to/sk-wwise-mcp/sk-wwise-mcp.exe",
  "args": ["--server", "browse"]
}

Common locations for the MCP config:

The bundled .mcp.json registers all 12 servers — copy entries from there into your agent's config and adjust the command path to where you unzipped the bundle. Agent Skills in .claude/skills/ follow the open spec and load automatically in tools that support it; agents that don't read skills still work, you'll just need to nudge tool selection in your prompts.

Cursor users: This bundle exposes 97 tools across 12 servers. Cursor caps active MCP tools at ~40 across all servers combined — register only the servers you need (e.g., browse + objects + audition covers most workflows at ~25 tools).

For development setup (Python, editable install, testing) see Quick Start below.

Features

• 97 tools across 12 MCP servers, covering the full WAAPI surface
• Agent Skills spec compliant — works with Claude Code, Cursor, VS Code Copilot, Gemini CLI, and 30+ other agent tools
• Thread-safe WAAPI dispatcher with queue-based serialization and backpressure handling
• WwiseConsole CLI integration for headless operations (project creation, SoundBank generation, migration)
• 450 unit tests (mocked WAAPI) + 44 integration tests (live Wwise)

Servers

Requirements

• Python 3.12+
• Wwise 2024.1+ (with WAAPI enabled for most servers)
• uv (recommended) or pip for dependency management

Wwise 2025.1 Hierarchy Rename

Wwise 2025.1 renamed the top-level hierarchies:

All paths in this project (tool descriptions, test cases, examples) use the 2025.1+ names. If you're running Wwise 2024.x or earlier, replace \Containers with \Actor-Mixer Hierarchy and \Busses with \Master-Mixer Hierarchy in your queries.

Quick Start

1. Clone and run setup

Windows:

git clone https://github.com/silver-rain-dev/sk-wwise-mcp
cd sk-wwise-mcp/sk-wwise-mcp
setup.bat

macOS / Linux:

git clone https://github.com/silver-rain-dev/sk-wwise-mcp
cd sk-wwise-mcp/sk-wwise-mcp
./setup.sh

The setup script will:

• Install dependencies (via uv or pip)
• Let you choose which servers to enable
• Generate a .mcp.json with the correct paths for your machine

2. Start Wwise

Open Wwise with a project and ensure WAAPI is enabled (Project > User Preferences > Enable Wwise Authoring API).

3. Verify connectivity

In Claude Code or your agent:

Ping Wwise to check if it's available

cd sk-wwise-mcp/sk-wwise-mcp
uv sync   # or: python -m venv .venv && .venv/Scripts/pip install -e .

{
  "mcpServers": {
    "sk-wwise-browse": {
      "command": "/path/to/.venv/Scripts/python.exe",
      "args": ["/path/to/mcp_browse/server.py"]
    }
  }
}

Project Structure

sk-wwise-mcp/
├── .claude/skills/         # Agent Skills (SKILL.md per server)
│   ├── wwise-global/       # Global rules and workflows
│   ├── wwise-browse/       # Browse server skill
│   ├── wwise-objects/      # Objects server skill
│   └── ...                 # One per server
├── core/                   # Shared business logic
│   ├── waapi_util.py       # WAAPI connection, dispatcher, ping
│   ├── query.py            # Object queries, property inspection
│   ├── objects.py          # Object CRUD operations
│   ├── pipeline.py         # Import, SoundBank, save
│   ├── transport.py        # Transport playback
│   ├── media.py            # Audio peaks, Media Pool
│   ├── profiling.py        # Profiler data retrieval
│   ├── ui.py               # UI automation
│   ├── wwise_cli.py        # WwiseConsole CLI wrapper
│   ├── audio_convert.py    # Non-WAV to WAV conversion (ffmpeg)
│   └── generic_handling.py # Generic WAAPI passthrough
├── mcp_browse/             # Read-only project inspection
├── mcp_objects/            # Object editing
├── mcp_containers/         # Container-specific config
├── mcp_pipeline/           # Import and build pipeline
├── mcp_audition/           # Transport playback
├── mcp_media_read/         # Audio analysis
├── mcp_ui/                 # UI automation
├── mcp_profiling/          # Profiler data (read-only)
├── mcp_profiling_control/  # Profiler control
├── mcp_remote/             # Remote connection
├── mcp_command_line/       # WwiseConsole CLI
├── mcp_generic/            # Fallback WAAPI passthrough
└── tests/                  # 450 unit + 44 integration tests

Philosophy

This project is an exploration of how AI agents can assist with large-scale Wwise production work — the tedious, repetitive tasks that eat hours (bulk renaming, auditing property consistency across hundreds of objects, generating SoundBanks, diffing configurations) — while minimizing the risk of unwanted changes to the project.

The core tension: AI is most useful when it can take action, but Wwise projects are complex and a wrong edit can silently break audio behavior in ways that surface much later. This project's architecture is designed around that tension — let the agent help with the heavy lifting, but make it structurally difficult for it to do things it shouldn't.

This is not a finished product. It's a working experiment in finding the right boundary between AI assistance and human control for audio middleware.

Why no Sound Engine (ak.soundengine) coverage

WAAPI exposes both authoring functions (ak.wwise.*) and sound engine functions (ak.soundengine.*). This project deliberately covers only the authoring side.

The sound engine API triggers real-time audio behavior — posting events, setting RTPCs, setting states and switches, seeking — the same operations that the game runtime performs. Exposing these to an AI agent creates a debugging nightmare: if something sounds wrong during a session, was it the game posting an event, or the LLM? With authoring operations the scope is clear — the agent changed a property in the project, and the change is visible in the UI and saved to the work unit. Sound engine calls leave no such trail.

Sound engine interaction belongs in a more controlled environment: game-side tooling, automated test harnesses, or direct scripting where every call is logged and traceable. Not behind an AI agent whose decision-making is opaque by nature.

The one exception is transport-based playback (mcp_audition), which uses ak.wwise.core.transport.* — an authoring API that previews sounds within the Wwise editor without affecting game-side state.

Architecture

Server Separation Philosophy

Most MCP projects expose one server with all tools. This project deliberately splits into 12 servers for three reasons:

Role-based access control

Not every user needs every tool. By separating servers along permission boundaries, teams can grant access by role:

An agent with only browse enabled physically cannot delete objects or overwrite SoundBank settings — the tools don't exist in its context. This is a stronger guarantee than relying on prompt instructions like "don't modify anything."

Read/write separation

Servers are split by intent and access level, not by WAAPI namespace:

• Read-only servers (browse, profiling, media_read) cannot modify the project. Safe to give to any agent or user without risk.
• Edit servers (objects, containers) modify project state — object creation, deletion, property changes.
• Pipeline servers (pipeline, command_line) handle import/build operations that affect files on disk.
• Runtime servers (audition, remote, profiling_control) control playback, profiling, and remote connections through the authoring tool.

This means you can build a "read-only assistant" by enabling only the read servers, or a "full authoring agent" by enabling everything. The separation is enforced at the transport level — there's no way to accidentally call a write tool from a read-only server.

LLM tool routing accuracy

LLMs get worse at selecting the right tool as the tool count grows. By capping each server at ~15 tools, the model sees a focused set of tools relevant to the task. Agent Skills (.claude/skills/) route the LLM to the correct server based on the user's intent, keeping the active tool set small even though 95 tools exist across the suite.

Thread-Safe WAAPI Dispatcher

All WAAPI calls are serialized through a queue-based dispatcher (core/waapi_util.py), ensuring:

• Thread-safe access to the WebSocket connection
• Backpressure handling (queue max: 10,000)
• Automatic reconnection on stale connections

Agent Skills

The .claude/skills/ directory contains Agent Skills files that route LLMs to the correct server based on the task. The wwise-global skill contains shared rules and workflow patterns.

Testing

Unit Tests

cd sk-wwise-mcp
uv run pytest tests/ -v

Unit tests use mocked WAAPI calls — no Wwise instance needed.

Integration / Eval Tests

The tests/eval/ directory contains an integration test suite that verifies MCP tool routing against a live Wwise project. It checks that the LLM selects the correct tools for each prompt.

39 test cases across 6 categories: browse, audition, generic, objects, media-read, cross-server.

Running the eval

1. Setup — create a test project with known objects via the eval-setup Claude Code skill:

   /eval-setup
   

   This creates a headless WwiseConsole project at tests/eval/EvalTestProject/ with:

   • Actor-Mixer hierarchy (Sounds, Random Container, Switch Container)
   • Events, State Groups, Switch Groups with assignments
   • Audio files imported into all Sounds (for media/peaks tests)
   • Attenuation ShareSet with volume curve
   • Differing properties on Footstep_01/02 (for diff tests)

2. Run — iterate through all test cases using either skill:

   /eval-batch — runs up to 10 cases per invocation (recommended):

   /loop 60s /eval-batch
   

   Finishes all 39 cases in ~4 iterations. Each invocation picks up where the last left off.

   /eval-routing — runs 1 case per invocation (fine-grained):

   /loop 30s /eval-routing
   

   Both log which MCP tools were called and verify against expected tools.

3. Report — view results:

   python tests/eval/report.py
   

4. Teardown — clean up:

   /eval-teardown
   

Eval architecture

• test_cases.json — prompt + expected tools for each case
• verify.py — compares actual tool calls against expected, writes test_results.json
• report.py — generates pass/fail summary by category
• log_tool.py — PostToolUse hook that logs MCP tool calls to tool_log.jsonl
• .claude/settings.json — configures the PostToolUse hook

Connection resilience

core/waapi_util.py includes self-healing connection logic:

• Ping before call — detects stale WAAPI connections
• Auto-reconnect — creates a fresh WaapiClient if the connection is dead
• Auto-restart headless server — if a .waapi_server.lock file exists (written by cli_start_waapi_server), the server is automatically restarted when unresponsive
• No-op for UI sessions — if the user runs Wwise with the UI (no lockfile), connection failures surface as clear errors without attempting restart

Example Prompts

Show me all Events in my Wwise project
How many Sound objects are under Containers?
Compare the settings between Footstep_Walk and Footstep_Run
Import all .wav files from C:/audio/ into a Random Container
Play the sound at \Containers\Default Work Unit\Footstep
What's the CPU usage in the profiler right now?
Create a new Wwise project at C:/MyGame/MyGame.wproj for Windows and PS5

Contributing

This project is not accepting direct tool contributions. Adding or modifying MCP tools affects LLM routing accuracy across the entire suite — each change requires running the eval framework against a live Wwise project, which involves LLM API costs and manual verification.

If you'd like to extend the tool suite:

• Bug reports and feature requests — please open an issue
• Custom tools for your team — fork the repo and add tools to your fork. Use the eval framework (tests/eval/) to validate that your changes don't break routing accuracy

Why not automate routing tests in CI? Full routing validation requires sending prompts to an LLM to see which tools it selects — results aren't fully deterministic, and each run takes time to verify. The current eval framework runs interactively via Claude Code skills, validating routing accuracy across 39 test cases with manual review. If you're already on a Claude Max/Pro subscription, running the eval incurs no additional API costs.

License

See LICENSE for details.