AI DJ Station Co-Host How-To Guide

Welcome to the definitive operator manual and setup guide for the AI Station Co-Host in Castium Studio. This guide details how the AI DJ works, how to configure offline neural speech engines, connect local or cloud language models, schedule spontaneous on-air banter, and calibrate broadcast vocal processing.

Overview & Audio Architecture
Prerequisites & System Requirements
Voice Engines & Persona Setup
Configuring the AI DJ Brain
Autonomous Banter & Scheduling Modes
Universal Live Track & Metadata Recognition
Analog Studio Vocal DSP & Auto-Ducking
Step-by-Step Walkthroughs
- Walkthrough A: 5-Minute Offline Setup (Kokoro + Smart Templates)
- Walkthrough B: Fully Autonomous Station with Local Ollama
Configuration Files & Troubleshooting

1. Overview & Audio Architecture

The Castium AI Station Co-Host is an autonomous broadcast personality integrated directly into Castium Studio's real-time audio pipeline. Unlike simple text-to-speech tools, the AI Co-Host understands what song is playing, knows the current time and station identity, composes contextual radio commentary, synthesizes ultra-realistic human voices, and ducks live background music with analog studio curves.

flowchart TD
    A[Music Source\nLocal Player / Decks / Spotify / YouTube] --> B[Universal Track Recognition\nTitle, Artist, Metadata]
    B --> C{Autonomous Scheduling\nRandom 2-4 / Timer / Hybrid}
    C -->|Trigger| D[AI DJ Brain\nOllama / Cloud / Smart Templates]
    D --> E[Script Conditioning\nContractions, Pauses, Macro Replacement]
    E --> F[Neural TTS Engine\nKokoro-82M / Piper / Cloud HD]
    F --> G[Studio Vocal DSP Strip\n+2.5dB Proximity, +1.8dB Air, 18ms Room]
    G --> H[Auto-Ducking Mixer\nMusic ducks -12dB with smooth bloom]
    H --> I[Master 2-Bus Output\nBroadcast Stream & Web Player]

Key Technical Characteristics

Zero Cloud Lock-in: Can run 100% offline with zero external API calls or subscriptions.
Low-Latency Resampling: Audio output is converted dynamically to 44.1 kHz 16-bit stereo PCM to seamlessly match the station's broadcast feed.
Analog Auto-Ducking: Live music drops smoothly by -12 dB during announcements and gently blooms back to full volume when the speech completes.

2. Prerequisites & System Requirements

Component	Minimum	Recommended
Operating System	Windows 10 / 11 64-bit	Windows 11 64-bit
Processor	4-Core Intel Core i5 / AMD Ryzen 5	8-Core Intel Core i7 / AMD Ryzen 7
Memory (RAM)	8 GB	16 GB or higher
Disk Storage	500 MB for basic app	2 GB for offline neural voice models
Local LLM (Optional)	None (Smart Templates)	Ollama running `llama3.1:8b` or `mistral:7b`

3. Voice Engines & Persona Setup

Castium supports multiple speech synthesis engines. You can select your active engine and voice from the AI Station Co-Host card (card-ai-dj) or via Settings (⚙️ Settings → 🧠 AI & LLM).

Kokoro-82M Studio Neural Voices (100% Free & Offline)

What it is: An 82-million parameter weight-quantized neural TTS model licensed under Apache-2.0. It runs locally on your computer's CPU with sub-second response times.
Vocal Quality: Highly expressive, warm human delivery with realistic breath cadence and inflections.
Available Voices:
- kokoro:af_bella - Bella (Warm & Charismatic - Female)
- kokoro:af_sarah - Sarah (Energetic Commercial - Female)
- kokoro:af_nicole - Nicole (Smooth Late-Night - Female)
- kokoro:af_sky - Sky (Youthful Upbeat - Female)
- kokoro:am_michael - Michael (Deep Radio Broadcaster - Male)
- kokoro:am_adam - Adam (Authoritative Classic - Male)
- kokoro:am_george - George (British Broadcast - Male)
Model Storage: All weights and voice profiles are saved locally in %USERPROFILE%\.castium\models\kokoro\.

Piper Offline Neural Voices (Fast CPU TTS)

What it is: Ultra-lightweight ONNX-based neural TTS with near-instant synthesis (~35 MB per voice package).
Available Voices: en_US-lessac-medium, en_US-bryce-medium, en_US-amy-medium, en_US-ryan-medium.
Model Storage: Saved locally in %USERPROFILE%\.castium\models\piper\.

High-Definition Cloud Neural Voices

When connected to the internet, Castium can stream broadcast-quality cloud neural voices:
- en-US-JennyNeural (Jenny - Sultry & Smooth)
- en-US-GuyNeural (Guy - High-Energy Rock & Top 40)
- en-US-AriaNeural (Aria - Dynamic Hit Radio)
- en-US-AvaNeural (Ava - Intimate Chill & Lo-Fi)
- en-US-ChristopherNeural (Christopher - Classic Retro 80s Announcer)
- en-GB-RyanNeural & en-GB-SoniaNeural (British Broadcast)

Windows Desktop SAPI 5 Fallback

If you are completely offline and have not yet downloaded Kokoro or Piper models, Castium will automatically fall back to your installed Windows system voices (e.g., Microsoft David, Zira, Mark) so broadcasts are never interrupted.

Preset DJ Personas

Select a persona in card-ai-dj to instantly apply matched voice, speech rate, and pitch presets:

Persona	Voice	Rate	Pitch	Best Suited For
Sultry Smooth	Jenny / Nicole	-1 (-5%)	Standard	Jazz, Lounge, R&B, Late-Night FM
Rock Jock	Guy / Michael	+1 (+5%)	Aggressive	Classic Rock, Alternative, Metal
Hype Top 40	Aria / Sarah	+2 (+10%)	Bright	Pop, EDM, Dance, Festival Radio
Chill Lo-Fi	Ava / Sky	-2 (-10%)	Relaxed	Lo-Fi Beats, Ambient, Study Stream
Retro 80s	Christopher / Adam	0 (Normal)	Deep	Synthwave, 80s Flashbacks, Oldies

4. Configuring the AI DJ Brain

The AI DJ Brain decides what words your co-host will say before each track or station break. Open the configuration drawer on card-ai-dj or edit %USERPROFILE%\.castium\ai_dj\brain_config.json.

Provider 1: Smart Templates (Zero-Lag Broadcast Liners)

How it works: Uses hundreds of built-in commercial radio intro formulas.
Advantages: Zero CPU load, zero internet required, zero token costs, instantaneous execution.
Example Output: "You're locked into Castium FM. It's 10:15 PM, and right now we've got featured artist Daft Punk with One More Time coming right up."

Provider 2: Local Ollama LLM (Llama 3, Mistral, Qwen)

How it works: Connects to an Ollama server running locally on your computer.
Setup Instructions:
1. Download and install Ollama from ollama.com.
2. Open a terminal and pull your preferred model:
```
ollama run llama3.1:8b
```
3. In Castium's AI card, set Provider to Ollama (Local).
4. Set Endpoint to http://localhost:11434.
5. Select your detected model from the dropdown.
Broadcasting Optimizations: Castium incorporates a 60-second generation safety window and automatically sanitizes markdown tags and laughter stage directions before sending the text to speech synthesis.

Provider 3: Cloud API (OpenAI, Groq, Together, Gemini)

How it works: Connects to any OpenAI-compatible /chat/completions endpoint.
Configuration:
- Endpoint: https://api.openai.com/v1 (or Groq: https://api.groq.com/openai/v1)
- API Key: Enter your secret bearer token.
- Model: e.g., gpt-4o-mini or llama-3.1-70b-versatile.
- Timeout: Optimized 8-second response limit with automatic fallback to Smart Templates if connection stutters.

Selecting DJ Vibes & Presentation Tone

High Energy Top 40: Punchy, exciting commercial station style.
Late Night Chill: Sultry, intimate, quiet late-night tone.
Classic Rock: Edgy, authentic, passionate album commentary.
Short Punchy: Under 10 words, straight to the next song.

5. Autonomous Banter & Scheduling Modes

You can run Castium 24/7 without needing to trigger voice breaks manually.

Enabling Autonomous Banter

On the AI Station Co-Host card (card-ai-dj), toggle the [ ● BANTER ON ] button so it turns green.
The schedule engine begins monitoring on-air track transitions immediately.

Scheduling Modes Explained

🎲 Random (2–4 Songs):
- Introduces songs irregularly (every 2, 3, or 4 tracks).
- Mimics commercial radio stations where DJs speak unpredictably rather than mechanically after every song.
⏱️ Random Timer (8–15 Min):
- Runs independently of song changes, triggering station ID, time checks, and liners every 8 to 15 minutes.
⚡ Smart Hybrid (2–4 Songs or 12 Min) (Recommended):
- Triggers randomly between 2 and 4 songs, but has a built-in safety watchdog: if 12 minutes pass without speech, it triggers a station liner automatically.
Fixed Intervals:
- Predictable transitions every 1, 2, 3, or 5 songs.

Manual On-Demand Banter

Click [ 🧠 Banter Now ] on the quick liners bar at any moment to trigger an immediate, context-aware song introduction over the current audio.
Use the Custom Script Pad to type or modify an announcement before clicking [ 🎙️ Speak On-Air ].

6. Universal Live Track & Metadata Recognition

Castium detects currently playing music across three distinct layers:

Supported Audio Sources

Castium Console Player: Internal SQLite-backed track playback.
Dual Decks A & B: Manual DJ deck mixing with crossfaders.
External Media Loopback: Desktop applications running in Windows, including Spotify, Apple Music, YouTube, and browser audio via WASAPI loopback.

Dynamic Script Macros

You can write custom station liners using dynamic tags:

{StationName}: Replaced with your configured station brand (e.g., "Castium FM").
{TrackTitle}: Current or upcoming song title.
{Artist}: Performing musical artist.
{Time}: Formatted current studio time (e.g., "9:45 PM").
{Date}: Full calendar date (e.g., "Sunday, September 27").
{RequesterName}: Name of the web listener who requested the track.

Broadcast Script Conditioning & Sanitization

Before raw text reaches the audio engine, Castium runs it through automatic radio formatting:

Natural Contractions: Converts stiff phrasing like "it is" → "it's", "do not" → "don't", "we will" → "we'll".
Delimiter Smoothing: Replaces rigid tag separators like "Artist - Title" with conversational phrasing: "Artist, with Title".
Breath & Pacing Inserts: Adds subtle phonetic pause breaks at sentence boundaries so synthesized speech sounds relaxed and human.
Markdown Removal: Strips **bold**, *italics*, quotes, and parenthetical cues like *(laughs)* or [music fades].

7. Analog Studio Vocal DSP & Auto-Ducking

The vocal output channel routes through a dedicated broadcast master strip before touching the airwaves:

Proximity Bass Warmth: A gentle +2.5 dB shelf at 150 Hz creates the classic rich radio announcer sound without muddiness.
High-Frequency Air: A +1.8 dB presence lift at 4.2 kHz ensures clear vocal articulation through laptop speakers and mobile headphones.
Studio Acoustic Room Space: An 18 ms simulated studio reflection adds spatial dimension, preventing synthetic dryness.
Auto-Ducking: Live music ducks exponentially by -12 dB while voice audio is active, and blooms back up over a 600 ms analog release curve.

8. Step-by-Step Walkthroughs

Walkthrough A: 5-Minute Offline Setup (Kokoro + Smart Templates)

Launch Castium Studio.
Click ⚙️ Settings in the top navigation bar and select the 🧠 AI & LLM tab.
Under Offline Neural Speech Engines, click Download Model next to Kokoro-82M. Wait for the download to complete (~85 MB).
Return to the main console and locate the AI Station Co-Host card.
In the Voice dropdown, select Nicole (Smooth Late-Night - Kokoro HD).
Set Brain Provider to Smart Templates.
In the Persona selector, click Sultry Smooth.
Click [ 🧠 Banter Now ] to test your setup. You will hear Nicole introduce your station with smooth music ducking.

Walkthrough B: Fully Autonomous Station with Local Ollama

Ensure Ollama is running on your machine:
```
ollama serve
```
Pull your model:
```
ollama pull llama3.1:8b
```
In Castium's AI Station Co-Host card:
- Select Brain Provider: Ollama (Local).
- Ensure Endpoint is http://localhost:11434.
- Choose llama3.1:8b in the Model dropdown.
- Choose your vibe: High Energy Top 40.
Set Schedule to ⚡ Smart Hybrid (2–4 Songs or 12 Min).
Click [ ● BANTER ON ] to activate the autonomous engine.
Queue up a playlist in the Local Player or play music in Spotify. Castium will autonomously host your station!

9. Configuration Files & Troubleshooting

File Locations

Voice Settings: %USERPROFILE%\.castium\ai_dj\voice_settings.json
Brain Settings: %USERPROFILE%\.castium\ai_dj\brain_config.json
Kokoro Models: %USERPROFILE%\.castium\models\kokoro\
Piper Models: %USERPROFILE%\.castium\models\piper\

Frequently Asked Questions

Q: The AI DJ isn't speaking when songs change. What should I check?

Ensure [ ● BANTER ON ] is highlighted green.
Verify that an audio source is actively playing and that Castium has detected track metadata in the top bar.
Check whether your selected schedule requires 2–4 songs before triggering. Click [ 🧠 Banter Now ] to force an immediate test.

Q: Why is the music volume staying ducked?

Check the Master Mixer card. If the Voice channel fader or audio buffer is held open by an external application, toggle the mic mute button or restart the audio engine in Settings.

Q: Can I use the AI DJ with external audio like Spotify or YouTube?

Yes. Enable WASAPI Loopback Capture under Audio Devices in Settings. Castium will capture the live audio, identify the song using Windows Media Session metadata, and duck Spotify during banter.

For related documentation, see the Castium Studio Features Guide and the Pro DJ Mixer & 10-Band EQ Guide.