@ai-rpg-engine/audio-director 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,72 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/ai-rpg-engine/readme.png" width="300" alt="AI RPG Engine">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ai-rpg-engine/audio-director"><img src="https://img.shields.io/npm/v/@ai-rpg-engine/audio-director.svg" alt="npm"></a>
+  <a href="https://github.com/mcp-tool-shop-org/ai-rpg-engine/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-rpg-engine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/mcp-tool-shop-org/ai-rpg-engine/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+# @ai-rpg-engine/audio-director
+
+Deterministic audio cue scheduling engine for the [AI RPG Engine](https://github.com/mcp-tool-shop-org/ai-rpg-engine).
+
+Part of the **Immersion Runtime** — converts narration plans into timed, prioritized audio commands.
+
+## Install
+
+```bash
+npm install @ai-rpg-engine/audio-director
+```
+
+## What It Does
+
+The Audio Director takes a `NarrationPlan` and produces ordered `AudioCommand[]` — ready for any audio backend to execute. It handles:
+
+- **Priority**: Voice > SFX > Music > Ambient (configurable)
+- **Ducking**: Ambient/music automatically lower when voice plays
+- **Cooldowns**: Prevents SFX spam (configurable per-resource)
+- **Timing**: Sequences cues relative to speech duration
+- **Layer tracking**: Knows which ambient layers are active
+
+## Usage
+
+```typescript
+import { AudioDirector } from '@ai-rpg-engine/audio-director';
+import type { NarrationPlan } from '@ai-rpg-engine/presentation';
+
+const director = new AudioDirector({
+  defaultCooldownMs: 2000,
+});
+
+// Schedule commands from a narration plan
+const commands = director.schedule(plan);
+
+// Execute commands through your audio backend
+for (const cmd of commands) {
+  await audioBackend.execute(cmd);
+}
+
+// Check cooldowns
+director.isOnCooldown('alert_warning'); // true if recently played
+
+// Clear cooldowns on scene change
+director.clearCooldowns();
+```
+
+## Default Ducking Rules
+
+| Trigger | Target | Duck Level |
+|---------|--------|-----------|
+| Voice | Ambient | 30% volume |
+| Voice | Music | 40% volume |
+| SFX | Ambient | 60% volume |
+
+## Part of AI RPG Engine
+
+This package is part of the [AI RPG Engine](https://github.com/mcp-tool-shop-org/ai-rpg-engine) monorepo. See the root README for the full architecture.
+
+## License
+
+MIT

package/dist/director.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=director.test.d.ts.map

package/dist/director.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director.test.d.ts","sourceRoot":"","sources":["../src/director.test.ts"],"names":[],"mappings":""}

package/dist/director.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { AudioDirector } from './director.js';
+const makePlan = (overrides = {}) => ({
+    sceneText: 'You step into darkness.',
+    tone: 'dread',
+    urgency: 'normal',
+    sfx: [],
+    ambientLayers: [],
+    uiEffects: [],
+    interruptibility: 'free',
+    ...overrides,
+});
+describe('AudioDirector', () => {
+    it('should schedule voice commands from plan with speaker', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            speaker: {
+                entityId: 'pilgrim',
+                voiceId: 'am_adam',
+                emotion: 'fearful',
+                speed: 0.9,
+                text: 'Turn back!',
+            },
+        });
+        const commands = director.schedule(plan);
+        const voiceCmd = commands.find((c) => c.domain === 'voice');
+        expect(voiceCmd).toBeDefined();
+        expect(voiceCmd.params.text).toBe('Turn back!');
+    });
+    it('should schedule SFX commands', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            sfx: [{ effectId: 'alert_warning', timing: 'immediate', intensity: 0.8 }],
+        });
+        const commands = director.schedule(plan);
+        const sfxCmd = commands.find((c) => c.domain === 'sfx');
+        expect(sfxCmd).toBeDefined();
+        expect(sfxCmd.resourceId).toBe('alert_warning');
+    });
+    it('should schedule ambient commands', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            ambientLayers: [{ layerId: 'ambient_drone', action: 'start', volume: 0.3, fadeMs: 1000 }],
+        });
+        const commands = director.schedule(plan);
+        const ambientCmd = commands.find((c) => c.domain === 'ambient');
+        expect(ambientCmd).toBeDefined();
+        expect(ambientCmd.resourceId).toBe('ambient_drone');
+    });
+    it('should add ducking commands when voice is playing', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            speaker: {
+                entityId: 'npc',
+                voiceId: 'af_bella',
+                emotion: 'calm',
+                speed: 1.0,
+                text: 'Hello.',
+            },
+        });
+        const commands = director.schedule(plan);
+        const duckCmd = commands.find((c) => c.action === 'duck');
+        expect(duckCmd).toBeDefined();
+    });
+    it('should apply SFX cooldown', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            sfx: [{ effectId: 'alert_warning', timing: 'immediate', intensity: 0.8 }],
+        });
+        director.schedule(plan);
+        expect(director.isOnCooldown('alert_warning')).toBe(true);
+        // Second schedule should filter out the cooled-down SFX
+        const commands2 = director.schedule(plan);
+        const sfxCmds = commands2.filter((c) => c.domain === 'sfx' && c.action === 'play');
+        expect(sfxCmds).toHaveLength(0);
+    });
+    it('should track active ambient layers', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            ambientLayers: [{ layerId: 'ambient_rain', action: 'start', volume: 0.4, fadeMs: 1000 }],
+        });
+        director.schedule(plan);
+        expect(director.getActiveLayers().has('ambient_rain')).toBe(true);
+    });
+    it('should clear cooldowns', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            sfx: [{ effectId: 'ui_click', timing: 'immediate', intensity: 0.5 }],
+        });
+        director.schedule(plan);
+        expect(director.isOnCooldown('ui_click')).toBe(true);
+        director.clearCooldowns();
+        expect(director.isOnCooldown('ui_click')).toBe(false);
+    });
+    it('should schedule music commands', () => {
+        const director = new AudioDirector();
+        const plan = makePlan({
+            musicCue: { action: 'intensify', fadeMs: 500 },
+        });
+        const commands = director.schedule(plan);
+        const musicCmd = commands.find((c) => c.domain === 'music');
+        expect(musicCmd).toBeDefined();
+        expect(musicCmd.action).toBe('intensify');
+    });
+});
+//# sourceMappingURL=director.test.js.map

package/dist/director.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"director.test.js","sourceRoot":"","sources":["../src/director.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-rpg-engine/audio-director",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Audio cue scheduling, priority, ducking, and cooldown engine for AI RPG Engine",
   "type": "module",
   "main": "./dist/index.js",