Audio System

Overview

The LokkoLabs audio system uses a segment-based composition approach. Instead of generating unique audio files for every variant (team names, ranks, etc.), we generate atomic segments and combine them at runtime.

Segment Types

Audio is organized into different segment types:

Team Segments

Eight pre-generated team name segments:

Template Composition

Templates define how segments combine for team-specific announcements:

// Template definition
const AUDIO_TEMPLATES = {
  TRAIN_DONE: {
    pattern: ["{TEAM}", "SEG_TRAIN_DONE_SUFFIX"],
    // Resolves to: "Team Three" + "has completed training"
  },
  MISSION_WINNER: {
    pattern: ["SEG_FIRST_PLACE", "{TEAM}"],
    // Resolves to: "In first place" + "Team One"
  },
};

// Usage at runtime
resolveTemplate("TRAIN_DONE", { team: 3 });
// -> Returns array of audio URLs to play in sequence

Resolution Flow

1. Event triggers template (e.g., team completes training)
2. System looks up template pattern
3. Replaces {TEAM} with appropriate segment
4. Returns list of audio URLs
5. Audio player queues and plays in sequence

Inter-Clip Delay

Audio clips can have configurable pauses between them:

Duration Calculations

When calculating total duration, always include pauseAfter:

// ✅ CORRECT - use getSegmentDuration which includes pauseAfter
import { getSegmentDuration } from "@/lib/domain/unified-content";
const totalDuration = segments.reduce(
  (sum, s) => sum + getSegmentDuration(s), 0
);

// ❌ WRONG - missing inter-clip gaps
const totalDuration = segments.reduce(
  (sum, s) => sum + s.duration, 0
);

Audio Generation

Audio is generated using ElevenLabs Text-to-Speech:

Generation Process

1. Admin creates or updates script content
2. System detects missing audio clips
3. Calls ElevenLabs API with script text
4. Stores MP3 in Supabase Storage
5. Links clip metadata in database

API Endpoint

POST /api/admin/audio/generate
{
  "scripts": ["briefing-intro", "training-start"],
  "generateSegments": true  // Include team segments
}

Voice Configuration

ElevenLabs voice settings for CONTROL narrator:

• Voice: Professional, authoritative tone
• Stability: 0.75 (consistent delivery)
• Clarity: 0.80 (clear enunciation)
• Style: 0.40 (moderate expressiveness)

Delivery Modes

Events support three content delivery modes:

Audio Player Hook

The useAudioPlayer hook manages playback:

const audioPlayer = useAudioPlayer({
  onClipComplete: (clipId) => {
    // Track progress
  },
  onQueueComplete: () => {
    // All clips finished
  },
});

// Usage
audioPlayer.play(clipUrl);
audioPlayer.queue([clip1, clip2, clip3]);
audioPlayer.pause();
audioPlayer.resume();
audioPlayer.stop();

Player State

Browser Autoplay

Modern browsers require user interaction before playing audio. The system handles this with an interaction gate:

// Gate audio behind user interaction
const [audioEnabled, setAudioEnabled] = useState(false);

const handleInteraction = () => {
  // Play silent audio to unlock
  const audio = new Audio();
  audio.src = silentMp3;
  audio.play().then(() => {
    setAudioEnabled(true);
  });
};

Storage Structure

Audio files are stored in Supabase Storage:

audio/
├── clips/
│   ├── briefing-intro.mp3
│   ├── training-start.mp3
│   └── ...
├── segments/
│   ├── team-one.mp3
│   ├── team-two.mp3
│   └── ...
└── generated/
    └── {timestamp}-{hash}.mp3

File References

Next Steps

• Review the Architecture overview
• Explore the API Reference
• Read the Organizer Guide for usage context