MC (Master of Ceremonies) System

The AI MC generates short lines for welcomes, track intros, interval check-ins, and goodbyes, converts them to speech, and plays them over the mix while ducking music volume.

MC Settings UI → mc_context / mc_advanced / keys → Server builds prompt
  → Mem0 search (optional) → OpenAI chat completion (6–22 words)
  → Dedupe + forbidden validation → Eleven v3 audio tags (optional)
  → ElevenLabs TTS (or pyttsx3 fallback) → temp audio file
  → Client: { type: mc, wav_path, duck_* } → duck music, play audioMC → mc_done

Primary implementation: aidj_server.py (prompts, TTS, Mem0, send_mc()). Legacy helper: mc_brain.py (template buckets — largely superseded by inline MC_TEMPLATES in the server).

Open MC Settings from the app (MC modal in electron_mock/index.html).

Click Apply Settings (mcApply) to send mc_context + mc_advanced to the server. API keys are saved separately via each integration's Save button.

• Server: %APPDATA%\AI_DJ_Demo_Pro\aidj_config.json (and env vars)
• Client: some MC UI state in localStorage via mcApply handlers

Timing guards

• Skip in progress or rapid Next Track presses → MC may be skipped
• mc_busy — next line waits until current TTS finishes (mc_done from client)
• min_mc_interval_sec (~5s) between announcements when skipping rapidly
• Skip button rate limit — 3+ presses in 2s disables skip briefly (MC timing stays stable)

Track title mentions & dedications

Name Track Every N Songs (trackname_every_n, default 2) controls how often intros include the song title. 1 = every track; 2 = every other track, etc.

• One-time next dedication — queue text in MC settings before a track
• Per-track dedication — set from library (×/dedicate flow) → spoken once on that track's intro, then cleared

Controlled by Use Script Templates (mc_use_templates).

Live AI (default when templates off)

Requires OpenAI API key and AIDJ_LIVE_AI_MC=1 (default on). Prompts built in _mk_intro_prompt, _mk_welcome_prompt, _mk_goodbye_prompt, interval prompts. Augmented with Mem0 memories when enabled. Validated against FORBIDDEN phrases from Event Prompt. Retried once if output contains a banned substring.

Script templates

When Use Script Templates is checked, lines are picked from MC_TEMPLATES in aidj_server.py. Template sets: default, hype, smooth, wedding. Placeholders: {venue}, {track}, {genre}, {dj}, etc. No OpenAI call for that line (TTS still needs ElevenLabs or pyttsx3).

You can switch per session via Apply Settings without restarting the server.

System message (fixed personality)

• Sound like a real club MC — natural, varied, not radio-cliché
• 6–22 words, contractions, no emojis
• FORBIDDEN section is absolute — never use those phrases or obvious rewrites
• Vary openings; avoid starting with Let's, Keep, We're keeping
• Prefer strong verbs (Drop, Ride, Build, …) unless forbidden
• Event details occasionally (every 3–5 lines), not every line
• Crowd QR: invite scans sometimes, never read raw URLs aloud

Temperature 0.9, presence penalty 0.3, frequency penalty 0.8 — encourages variety.

User message (per announcement)

1. _mc_user_settings_block(event_ctx) — full Event Prompt + parsed FORBIDDEN list
2. Event type context — gym, wedding, club, etc.
3. Venue, MC name, energy note, delivery style (hype vs restrained TTS hints)
4. Track context — title, artist, genre tease, dedication
5. Recent lines — Avoid repeating these recent lines from state.mc_history
6. Crowd QR block — if crowd server is running
7. Mem0 suffix — retrieved memories

Delivery style hints

Post-generation checks & translation

1. _line_violates_forbidden() — substring match → regenerate once with explicit fix prompt
2. _too_similar() — exact match vs mc_history → line discarded
3. state.mc_history — deque of last ~24 lines fed into next prompt

If Language ≠ English, prompts are passed through _translate_mc_prompt() before the LLM call; TTS uses the selected language code.

The Event Prompt textarea (mcPrompt) maps to state.event_ctx on the server via mc_context. Everything you put here is injected into every live-AI MC prompt (welcome, intro, interval, goodbye) via _mc_user_settings_block().

What to include

Wedding for Sam and Alex at Riverside Barn.
Family-friendly — grandparents and kids present.
Shout out the caterer Green Plate once early in the night.
Keep energy warm until first dance, then open up.

The model treats this as always-on DJ instructions, not a script to read verbatim.

Event Type, Venue, and MC name

• Event Type dropdown — selects a preset tone pack (gym, club, wedding, …). Use Custom if you only want the Event Prompt text.
• Venue Name — spoken occasionally (~every 4–6 lines), not every line. Blank venue falls back to config default or Venue.
• MC Name — DJ/host name; welcome may require both DJ + venue when configured.

AI DJ uses four layers to stop unwanted repetition:

Layer 1 — Event Prompt FORBIDDEN parsing (strongest)

Write bans directly in Event Prompt. The server parses them in _extract_forbidden_phrases(). Supported patterns (case-insensitive):

Do not say "Feel that energy"
Don't say 'last call'
Never say hands up for the DJ
Avoid saying let's go crazy
Remember: Do not say "old venue name"

• Use quotes for multi-word phrases
• Keep bans specific ("Feel that energy") rather than vague ("be boring")
• Max ~20 parsed phrases per prompt

Layers 2–4

1. Mem0 avoidance memories — durable never say X rules promoted to CRITICAL blocks (see Mem0 section)
2. Recent line history — Avoid repeating these recent lines in each prompt; exact duplicates rejected
3. Prompt-level opening bans — hard-coded: never start with Let's, Keep, We're keeping; throttle event theme and MC name mentions

Practical example — full Event Prompt

Corporate holiday party for NovaTech. No profanity. Upbeat but professional.

Do not say "hands up"
Do not say "make some noise"
Do not say "let's get lit"
Avoid saying anything about drinking contests

Remember: Never mention the competitor brand SyncWare.
Remember: Do not say "last call" — bar closes quietly at midnight.

Mention NovaTech once in the welcome only. Thank the AV team if doing a mic check.

After Apply Settings, bans are active immediately for the next MC line.

Mem0 is an optional long-term memory layer. The server calls Mem0's REST API — keys stay in AppData, never in the Electron UI logs.

Enabling Mem0

1. MC Settings → Integrations → Mem0 Memory
2. Check Enable Mem0
3. Paste API key → Save Mem0 → Test Mem0
4. Optionally check Auto-save MC lines

Mem0 is off by default on boot unless you enable it in UI — the server explicitly avoids auto-enabling.

Memory scopes & explicit remember lines

Remember: Do not say "feel the energy" or "hands in the air"
Remember: Sponsor is Blue Peak Water — mention at most once per hour
Memory: Bride's name is Alex — groom is Sam — use first names only
Mem0: Keep wedding lines classy — no club slang

Auto-save policy & retrieval

• Auto-save triggers: intro, interval, goodbye only (not every premix)
• Rate limit: ≥ 90 seconds between saves; dedupes identical consecutive lines
• Retrieval: search venue (top 4) + global (top 4); split into avoidance rules (CRITICAL) and general prefs
• Filter out memories that contain Event Prompt forbidden phrases

Best practice: Put hard bans in Event Prompt and Remember: the same bans into Mem0 once so they persist across app restarts.

ElevenLabs converts MC text into speech. Without a key, the server falls back to pyttsx3 (local system TTS).

Setup

1. API key — from ElevenLabs API keys page
2. Voice ID — default pre-filled; swap for any voice in your library
3. TTS model — Multilingual v2 (default), Eleven v3 (expressive + audio tags), Turbo v2.5 / Flash v2.5
4. Save Settings → Test Key

Voice / tone selection

Eleven v3 + OpenAI audio tags

When TTS model = eleven_v3 and OpenAI is available: MC line is generated normally, then _enhance_mc_text_eleven_v3_blocking() asks OpenAI to insert [audio tags] without changing words. Example: [excited] Riverside, here comes the drop! Disable tag enhancement: AIDJ_ELEVEN_MC_ENHANCE_TAGS=0.

TTS fallback chain

1. ElevenLabs (if key + voice ID)
2. pyttsx3 local TTS
3. If both fail → log text only; goodbye may still trigger fade_out

Temp audio files: %TEMP%\aidj_mc_{uuid}.mp3

Server sends an mc message with text, wav_path, duck_enabled, and duck_level (~0.3 = 30% music volume).

{
  "type": "mc",
  "text": "The spoken line",
  "wav_path": "C:\\Users\\...\\aidj_mc_abc123.mp3",
  "duck_enabled": true,
  "duck_level": 0.3
}

1. Client ramps gainMusicDuck down to duck_level
2. Plays audioMC from wav_path
3. On end → ramps music back to 100%
4. Sends mc_done so server clears mc_busy

Environment / aidj_config.json

WebSocket messages (MC-related)

Quick diagnostic order

1. Is MC Enabled checked and Apply Settings clicked?
2. Is Use Script Templates unintentionally on?
3. Are OpenAI + ElevenLabs keys saved and tested?
4. Does Event Prompt contain clear Do not say "…" lines?
5. Check aidj-server.log for [MC] and TTS errors.