Auto-KJ — User Guide

Professional karaoke hosting software and network ecosystem for Windows, macOS, and Linux. Auto-KJ operates your entire show: a mathematically fair singer rotation, real-time smartphone request integration, a dual-deck Break-Wave DJ performance engine, multi-screen crowd displays, built-in AI track creation via Ghost-Trax, and a dedicated mobile booth remote.

Companion guides: Help & Troubleshooting · FAQ · Walkthroughs · Singer App FAQ · Kiosk Guide · auto-kj.com Dashboard Guide · Complete Feature Inventory

1. Getting Started

Installation & Setup Wizard

1. Download the installer from auto-kj.com (Windows setup .exe, macOS Apple Silicon .dmg, Linux AppImage/.deb/.rpm) and launch it. The app updates itself on all three platforms.
2. On first launch, the Setup Wizard guides you through your initial setup (every step can be skipped):
   • Your plan: Choose Free version (desk-entered requests) or Paid plan or free 60-day trial (phone requests, kiosk, pausing, automation, full Break-Wave toolkit).
   • Your license: Yes — I have my key (registered email + License Key from your auto-kj.com dashboard), Start my free 60-day trial (sign in with your auto-kj.com account, verify your email, no card), or Not yet (opens auto-kj.com to create the free account, then come back).
   • Your songs: Select your karaoke folder. Auto-KJ indexes zipped MP3+G (.zip), loose .mp3+.cdg pairs, and video files (.mp4, .mkv, .avi), and keeps watching the folder for new files.
   • Your sound: Choose your primary front-of-house karaoke output device.
   • Your screen: Launch the crowd lyrics window and drag it to your secondary display.
3. Each tab shows a short tour the first time you open it.

Main Navigation

Seven tabs provide complete control across the top of the interface:

Rotation · Inbox · Break-Wave · Library · Ghost-Trax · Analytics · Settings

The header status bar displays:

• Connection Badge: ● ONLINE (connected to cloud server with active venue name), ● LAN FALLBACK (local server active), or ● OFFLINE.
• Singer Counter: Total active singers in tonight's rotation.
• Playback Indicator: ● LIVE with current track title and elapsed time while music is playing.
• 🎧 DJ Profile Selector: Switch between custom host profiles on shared rigs.
• Inbox Notification: Badge counter for pending requests, claims, and singer messages.

2. The Rotation Tab — Live Show Floor

The core control center consists of three resizable panes: the Transport Player (top), the Fair Slot Rotation Grid (left), and Song Search & Singer Details (right).

The Transport Player

• ▶ Play / ⏸ Pause / ⏹ Stop: Starts the selected singer's queued track, or advances to the next singer in line if no selection is made.
• 11-Band Spectrum VU Meter: Real-time multi-band spectrum analyzer (63 Hz to 14 kHz) displaying true acoustic output with peak-hold decay.
• Mini Lyrics Monitor: Pixel-perfect CDG preview of the lyrics rendered on the crowd TV.
• Key Changer: Transpose pitch from −6 to +6 semitones in half-step increments. Key adjustments are saved per singer and song.
• Tempo Slider: Scale playback speed from 0.50× to 2.00× with pitch preserved.
• GHOST-TRAX Vocal Slider: Real-time fader for the original artist guide vocal stem on Ghost-Trax tracks.
• Auto-Advance: Automatically starts the next singer after a configurable delay.
• 👏 Live Applause: Real-time counter of crowd applause taps sent from singer phones.
• 👥 Edit Performer: Update the credited performer name live during playback.

Fair Slot Rotation Rules & "The Law of the Line"

Auto-KJ replaces rigid, arbitrary rounds with a continuous fair slot line:

Every song you participate in sends your seat to the back of the line — and you only ever have one seat.

• One Seat Per Person: Additional requested songs wait in the singer's personal pocket queue; stacking multiple songs never grants extra slots in the main line.
• Group & Duet Fusion: When 2 to 4 singers submit a group song, the request fuses at the back-most member's seat position. Joining a group cannot be used as an exploit to cut the line. After performing, all participating members move to the back of the line together.
• No-Show Handling: If a singer reaches slot #1 with no song ready, they are bumped to the back of the line and tagged with a NO SHOW badge. If they reach the top a second consecutive time without a song, they are automatically removed. Adding a song immediately clears the flag.
• Pause & Fair Re-entry: Pausing parks a singer without losing their show history. When unpaused (by host or singer), they re-enter at slot #3 (immediately behind On Deck). This prevents line-jumping while ensuring returning singers get up promptly. Pauses expire after 1 hour with a mutual host/singer notification.
• Queue-Time Integrity Inspection: The moment a song is queued, its zip archive is verified. If corrupted, missing MP3/CDG pairs, or unreadable, the file is automatically moved to Quarantine/, removed from search, and replaced by a healthy alternate manufacturer version if available.
• Seat Context Menu (Right-Click):
  • Rename: Fix spelling errors.
  • Merge with…: Combine duplicate singer entries (e.g., "Dave" and "David").
  • Change key…: Set and store key transposition presets.
  • Add to group song…: Build multi-singer performance rosters.
  • Pause / Unpause: Toggle singer standby status.
  • Play now: Immediately load and play the singer's top song.
  • Quarantine file: Isolate bad media directly from the queue.
  • Message User: Send a direct push notification to the singer's phone.
  • Photo Moderation: Review or clear user-uploaded avatars.

Song Search & Singer Details

• Song Search: Fast indexed search. Right-click any result to 🎧 Preview on Headphone Cue (opens a preview CDG window that immediately paints the initial lyrics frame on mount, falling back to silent video if headphone cue hardware is unconfigured), Pick Version (when ×N badge indicates multiple manufacturer copies), or Queue for Any Singer.
• Singer Details: Inspect active pocket queues (drag-and-drop to reorder) and full historical performance logs.

3. The Inbox Tab — Phone Requests & DJ Hub

Central inbox for incoming phone submissions, identity claims, singer inquiries, and tip alerts.

• Accept Requests Online: Master toggle enabling phone submissions via cloud and LAN relays.
• Auto-Approve Toggle: Automatically approves clean requests into the rotation.
• Request Cards: Display singer name, solo/group designation, song title, artist, and a Version Picker (if multiple brands exist). Click Approve or Reject.
• Reassign Request: Use "Assign to" on any request card to route the song to a different existing singer or create a new seat.
• Account Claims ("🪪 X wants to claim…"): When a registered singer wants to claim a desk-entered walk-up seat, an identity claim card is generated. Claims never auto-approve; host confirmation is required.
• GPS Departure Alerts: When a checked-in singer moves >200m away from the venue for 45+ minutes, an alert card prompts: Remove from line or Dismiss.
• DJ Direct Messaging: Receive direct messages from singers in the crowd. Reply directly inline; unread badges appear on the header inbox icon.
• "Ask DJ to Buy Song" & Tips: Singers can request songs not in the library with an attached tip offer (Venmo/Cash App/PayPal). Accept or decline with a custom message.

4. The Break-Wave Tab & Pro Suite — DJ Engine

A dual-deck pro DJ system engineered specifically for karaoke breaks.

Dual Decks & Real-Time Mixer

• Decks A & B: Multi-band frequency-colored scrolling waveforms, high-resolution pitch fader (selectable ranges ±4% to ±100%), Keylock (time-stretching independent of pitch), Sync (continuous phase-locked tempo matching), and Tap / Analyze beatgrid correction.
• Hot Cues: 4 dedicated hot-cue pads per deck with instant trigger, delete, and visual waveform markers.
• Mixer Section: 3-band EQ with ±12 dB gain and instant KILL buttons, channel level faders, crossfader with 3 selectable curves (Smooth, Linear, Cut/Scratch), AutoFade (AF), and master output limiter.
• Headphone Pre-Cueing (PFL): Independent Cue A and Cue B listening bus with Cue/Master blend control.

  [!IMPORTANT] The Headphone Cue Output must be assigned to its own dedicated audio interface in Settings. It cannot share hardware with the Karaoke Main or Break-Wave outputs.

• Karaoke Priority Interlock: Karaoke playback always takes precedence. Starting a karaoke track smoothly pauses the Break-Wave decks. When the song ends, automation can resume the break playlist.

Automix Engine

• Automix Set Planner: Automatically schedules queued break tracks sorted by BPM, musical key, or energy profile.
• Transition Controls:
  • NOW: Triggers immediate beat-locked crossfade.
  • SKIP: Discards next scheduled track without interrupting playback.
  • STOP: Fades out and halts Automix gracefully.
  • PANIC: Instant emergency cut to silence.

Automix Resume, Playlist & Auto-Leveling

• ▶ RESUME picks a stopped or panicked set back up from whatever is on the mic; the tracks still to come are remembered.
• The BREAK-WAVE PLAYLIST under Deck A is the one shared queue: A / B load buttons, ▲▼, ✕, 🔀 shuffle, 💾 save by name, 📂 load saved playlists, multi-select with a right-click menu, ⏳ while a track's BPM/key analysis runs in the background.
• Every deck load is leveled by RMS to −14 dBFS (true peak capped at 98%), so quiet rips come up and slammed masters come down.

Pro Control Hub

Located under Deck B in the Break-Wave tab:

1. Master Deck Reset Bar: One-click RESET DECK A / RESET DECK B buttons instantly restore playback rate to 1.00× and flatten 3-band EQs to 0.0 dB.
2. 🎛️ Soundboard: 12 pads (Air Horn, Applause, Scratch, Rimshot, Siren, Sub Drop, Rec Brake, Crickets, Cash, Laser, Mic Drop, Riser) on keys 1–0 - =, ✎ EDIT PADS to load your own samples, master volume with limiter.
3. 🥁 Drum Sequencer: 16 steps × 6 tracks (kick, snare, clap, closed and open hats, tom) plus cowbell and shaker on the Q–I live pads, swing, four presets, SYNC A/B to a deck's tempo, record-arm quantizing, and a bar-synced Looper (mic for 1/2/4/8 bars, or audio files, as stacked layers). One pattern at a time.
4. ✨ Pro FX Rack: per deck HPF/LPF, beat-synced echo, reverb, and flanger with ON/OFF, MIX, INTENSITY, routed after the EQ so the headphone cue hears them.
5. The soundboard, drums, and looper play through the computer's default output, not the Break-Wave deck device. MIDI controllers are detected in Settings, but control mapping is not shipped yet.

Break Music Library & AcoustID Track Identification

• Path / Browse… / Identify sit under the Deck A playlist. Point them at your break-music directory (.mp3 .wav .m4a .ogg .flac), separate from the karaoke library.
• Search / Explorer tabs in the mixer strip switch the library dock: whole-folder search (first 25 rows) or one-folder-at-a-time browsing with breadcrumbs. Both offer ⚡ Analyze All, →A / →B, ⤒ Next, + End.
• Identify (paid): acoustic fingerprinting of untagged files via AcoustID and MusicBrainz (free API key in Settings → 🎵 Track Identification).

5. The Library Tab — Catalog Curation & Audio Health

Maintains and audits the local karaoke and break-music collections.

• Supported Media Formats: Indexes zipped MP3+G (.zip), loose .mp3+.cdg pairs, and video karaoke files (.mp4, .mkv, .avi).
• Statistics Dashboard: Total songs, unique artists, duplicate track clusters, unparsed filenames, missing file references, and brand breakdown.
• Clear Song Library (Surgical Catalog Reset): Located in Settings → Session & Data → Clear Song Library (2-click confirmation). Completely wipes catalog tables (songs, song_versions, songs_fts) to re-index cleanly without touching singers, the active rotation line, past performance history, license keys, audio configuration, or host settings. Headless maintenance can also use scripts/clear-song-library.py.
• Brand Priority Order: Drag-and-drop hierarchy ranking manufacturer prefixes (e.g., Sound Choice, Karaoke Version, Chartbuster). Higher-ranked brands automatically become the default version across the app.
• Duplicate Track Manager: Review multi-version song groupings, preview alternate audio on the headphone cue, and override preferred default versions.
• Fix Unparsed Songs: In-place metadata tagger for files whose filenames did not conform to standard conventions. Enable "Rename file to match" to update on-disk filenames with the CDG sibling.
• Loose File Cleanup: Detects standalone .mp3 and .cdg file pairs and cleanly packages them into standard zipped .zip karaoke archives with dry-run verification.
• Corrupt File Audit: Deep-scans zip archives and headers to detect truncated or zero-byte media. Quarantines corrupted files without deleting them.
• Redundant Copies & Spelling Merges: Isolates byte-identical duplicates and unifies artist spelling inconsistencies (e.g., "The Beatles" vs. "Beatles, The").
• Export Songbook CSV: Generates clean, formatted CSV exports of the entire catalog for physical songbooks or external web hosting.

6. The Ghost-Trax Tab — In-App Karaoke Track Creation

Cloud-powered stem separation and CDG synchronization tool that converts commercial audio into karaoke tracks.

1. API Authentication: Enter your personal API key (gtk_...) from ghost-trax.com.
2. Audio Staging: Upload audio files (.mp3, .wav, .m4a, .flac, .ogg, .aac up to 60 MB). Set Artist and Title.
3. Automated Pipeline: Track progresses through 4 stages: Queued → Separating → Transcribing → Rendering.
4. Review & Editing:
   • Title Screen Editor: Review introductory graphics and credits.
   • Lyric Transcript Editor: Correct misheard lyrics before final burn-in (preserves word timestamps).
5. Library Ingestion: Click Add to library — the completed track (instrumental, synced CDG, and guide vocal stem) is automatically saved into the library's Ghost-Trax/ directory and indexed.
6. Live Guide Vocal Usage: During live shows, any Ghost-Trax track loaded in the player activates the GHOST-TRAX slider. If a singer struggles, smoothly raise the slider to mix the original guide vocal stem into the house mix.

7. The Analytics Tab — Show Intelligence & Reporting

Real-time show telemetry and historical performance logs.

• Tonight's Proof Sheet: Total unique singers, completed songs, currently queued requests, completion percentage, average queue wait time, peak attendance hour, solo vs. group ratio, and total crowd applause count.
• Leaderboards: Top singers, most requested songs, and top artists for tonight and all-time.
• Hourly Activity Chart: Visual graph of songs performed per hour to identify room energy trends.
• Performance Log: Chronological audit trail of every song performed with exact timestamps, singers, key changes, and applause totals.
• Selected Singer Inspector: Deep dive into individual singer profiles with [ History | Favorites ] views. Double-click any past favorite to instantly add it to tonight's queue.
• Data Export: Export reports via Copy CSV, Copy JSON, or Print Report (with formatted venue staffing summaries).

8. Multi-Screen Venue Displays

Auto-KJ manages up to three discrete video outputs with persistent window geometry:

Screen 2: Crowd Lyrics Output (Auto-KJ Lounge)

• Launch via Settings → Dual-Monitor Lyrics Output → Launch Lyrics Screen (press F11 for fullscreen).
• Features full-screen CDG lyrics during songs, widescreen stretch options for 16:9 TVs, NOW SINGING / ON DECK / NEXT banners, upcoming singers list, and the live Join QR Code + Show Code.

Screen 3: Dedicated Rotation Display Board

• Launch via Settings → Rotation Display Window → Launch Rotation Screen (press F11 for fullscreen).
• Displays a dedicated bar-TV rotation board with an auto-densifying seat matrix, performer avatars, achievement badges, and a rolling announcements ticker for drink specials and venue shout-outs.
• When singers are waiting on duet/group partners, a dedicated Waiting on Partners queue appears directly under the regular rotation showing the song and truthful blocker (e.g. ⏳ waiting on Bob — 1 song first). Self-paused singers are excluded so only active waiters appear.

9. Settings Tour

• 🔑 License Activation: Register email and license key. Displays active tier and manages floating seats. The same card holds Try Full version for 60 days: the no-card trial (sign in with your auto-kj.com account, verify your email, start; one per account and per computer; the deadline never restarts). Leads the page until a key or trial is active, then drops to the bottom.
• 🎪 Active Venue / Gig: Select tonight's venue for GPS discovery and singer routing.
• 🔎 Browse Before You Go: Generates pre-show QR codes allowing singers to explore your songbook from home.
• 🔊 Tri-Zone Audio Routing: Independent device assignment for Karaoke Main, Break-Wave DJ, and Exclusive Headphone Cue.
• 📶 Network Binding: Select the network adapter (Wi-Fi / Ethernet) for the local LAN fallback server.
• ▶️ Playback Safety: Interruption warning dialogs.
• 🤖 Automation & Playback: End of Song Action (Wait for Host / Auto-Advance / Play Break Track Playlist), delay timer (0–60s), crossfade length (0–10s).
• ⚖️ Fairness Rules: Repeat Song Rule (Once per night / Cooldown timer 0.5–12h / Off), Group Song Guest Rule slider (Open Stage ↔ Strict Rotation), On-Deck custom message, and tip handles (Venmo, PayPal, Cash App, URLs).
• 🎧 DJ Profiles: Multi-DJ profile manager with independent preferences, stage name reservation, and night reset wizard.
• ⌨️ Keyboard Shortcuts & MIDI: Custom keybinding editor for all transport and navigation actions, plus Web MIDI controller assignment.
• 🎨 Appearance: 11 built-in UI skins (Arcade, Artifact, Broadway, Classic Dark, Haunted House, LCARS, Neon Lounge, Signal, Studio, Unicorn Overdrive, Word 95), the Skin Creator Studio & Community Marketplace (create custom themes, customize palettes, check real-time WCAG contrast, test in the component sandbox, browse/install community presets, and export/import .json skins), and the host window scale (50–250%). The lyrics window has its own size slider (50–300%) under Show Screens.
• 💾 Session & Data: Start Fresh Session (2-step confirm), Clear Song Library (2-step confirm; surgically wipes catalog tables while preserving singers, rotation, history, settings, and license), History Import/Export (OpenKJ SQLite, generic SQLite, CompuHost CSV, Siglos CSV, Karma folder), validated backup/restore, automatic local backups on a schedule, and Check for Updates.
• 📱 Remote Control: Pairing hub for DJ phone remote control with 1-click Revoke & Re-pair.
• ✅ Pre-show Check: one pass over library, audio devices, relays, gig, DJ profile, requests, tips, screens, and updates, with a fix button per finding.
• 🚫 Blocked Songs / 🚫 Banned Singers: per-gig song blocks (no override) and show-scoped singer bans.
• 📖 Guides & Help: every published guide, including the Singer App FAQ, Kiosk Guide, and the auto-kj.com Dashboard guide.

10. DJ Profiles & Stage Names

If multiple KJs share one rig:

• Settings → DJ Profiles → Add DJ: Each profile saves themes, fairness rules, automation, on-deck messages, and tip handles. License, audio devices, and library remain shared.
• Switching Profiles: Switch via the header 🎧 dropdown. Auto-KJ prompts to start a new show and clear the rotation, automatically seating the new host at slot #1.
• Stage Name Protection: Claiming a DJ name reserves it across the show. If a singer attempts to request under the host's stage name, they are automatically renamed (e.g., "Paul 284") and notified.
• Exclusive Cloud Stage Names: Linking a DJ profile to their PWA account email reserves the name globally, unlocking the exclusive "The KJ" 🎧 badge on their phone.

11. Singer History Portability (No Lock-In)

Migrating from other hosting software is seamless in Settings → Session & Data:

• 📥 Import History File: Native OpenKJ SQLite databases, auto-detected generic SQLite databases, and CSV exports from CompuHost V3, Siglos, and Karaoki.
• 📂 Import History Folder (Karma): Reads Karma's folder of per-singer history files.
• 📤 Export History (CSV & OpenKJ): Export your entire show history to CSV or a native OpenKJ database at any time.

12. Online, Offline & The LAN Fallback

• Cloud Mode (Normal): Singers connect via auto-kj.com using mobile cellular data or Wi-Fi. Requests survive brief internet hiccups and sync automatically.
• LAN Fallback (Offline Venue): Embedded web server runs on port 8080 inside the host app. If internet fails, the crowd QR switches to the LAN address, serving the full PWA locally with zero internet required.
• Free version: Full local show hosting with desk-entered requests.

13. Free vs Paid vs Songbook — The Exact Entitlement Table

14. Licensing & Simultaneous Shows

Install Auto-KJ on as many machines as you like. The license tier governs how many live shows can run at the same time (not venues-total, not shows-per-month):

• Full version (current sellable mid-tier, $10/mo): 1 live show at a time.
• Extra Instance: +$5/mo for each additional simultaneous show (paid tiers only).
• Infinite Play (Lifetime): unlimited simultaneous shows.
• Basic Single / LAN Cabinet / Ghost-Trax lifetime / 60-day trial (grandfathered / trial): 1 live show at a time.
• Basic Duo / VIP Pass (grandfathered): 2 simultaneous live shows.
• VIP Quad (grandfathered): 4 simultaneous live shows.

The desktop app treats every paid tier alike; tiers differ in simultaneous shows and, for VIP, the Ghost-Trax bundle. LAN Cabinet runs the singer app over venue Wi-Fi only (no cloud relay, GPS discovery, venues, or gigs). Songbook never activates the desktop app.

The 60-day trial

Start it in the setup wizard (Start my free 60-day trial) or in Settings → 🔑 License Activation → Try Full version for 60 days: sign in with your free auto-kj.com account, Send verification code, Verify email, tick the consent box, Start my 60-day trial. No card, no automatic billing. Full version unlocks on that computer for 60 days; the app hashes a firmware identifier so a second account on the same machine, or a reinstall, gets no second trial. When it ends the app returns to Free version with your library and show data intact; enter a License Key from your dashboard to continue.

Takeover Rule: If all slots are in use and a new machine launches a show, a dialog offers [ Take over ] (gracefully disconnects the longest-running instance with full local state preserved) or [ Exit ].

15. The Singer Mobile Web App (PWA)

Singers access the app at singer.auto-kj.com or via local Wi-Fi:

• Joining: GPS discovery, QR scan, or 4-letter Show Code.
• Catalog Search: Real-time availability badges (★ in favorites, 🎤 currently playable in venue).
• Queue Tracking: Live place-in-line, wait estimates, and self-pausing.
• Pre-Planned Setlists: Build lists at home and submit at the show with one tap.
• Social Features: Friends list, duet matching, bands, and non-blocking group song invitations.
• 👏 Live Applause: 10-tap applause budget per song with floating emoji on the crowd TV and 29 achievement badges.
• Direct Messaging & Tipping: Message the KJ or use "Ask DJ to Buy Song" with attached tip pledges.
• Accounts: Sign in / Create account, Forgot password? (one-hour single-use reset link), Log out in the header, on the connect screen, and on the profile, Delete Profile with password confirmation.
• Alerts: on-deck and up-now chimes and banners; 🔔 Notify me when I'm on deck for background notifications; Web Push with the app closed for signed-in singers on cloud shows (iPhone: add to Home Screen first).
• Kiosk Mode: Dedicated tablet mode with attract screen, anonymous request wizard, and a ? help card. See the Kiosk Guide.

Everything singers can do, with every label and message: Singer App FAQ.

16. The DJ Phone Control (Booth Remote)

Operate the show away from the booth via http://<lan-ip>:8080/remote:

• Pairing: Scan the private QR code in Settings → Remote Control.
• Transport: Big-button ▶ Play / ⏸ Pause, ⏹ Stop, and ⏭ Next Singer.
• Queue Control: View full rotation, adjust seat order with up/down arrows, and remove singers using armed 2-tap safety buttons.
• Security: One-click Revoke & Re-pair in Settings instantly invalidates all mobile tokens.

17. The Server Ecosystem

• Cloud Server (cloud-server): Rust Axum backend with PostgreSQL managing real-time WebSocket relays (/ws/host, /ws/singer), geographic gig indexing, Stripe billing, and the OpenKJ Songbook Bridge (/api/okj).
• Local Server (local-server): Embedded Rust web server running inside the host app on port 8080, serving PWA assets and the booth remote with zero-internet reliability.

18. The auto-kj.com Host Dashboard

The Operator Console on auto-kj.com (Sign In, or auto-kj.com/#manage) is where the cloud side is set up:

• TELEMETRY: plan and billing, the LICENSE KEY to copy into the desktop app, the active show code, cancel/upgrade.
• VENUES & GIGS: venues with a geocoded address (each gets the 4-letter show code) and one-time, weekly, or monthly gig schedules that drive GPS discovery.
• OPENKJ SONGBOOK: the request-server URL, API key, and auto-kj.com/your-venue links for hosts on OpenKJ.
• SECURITY: change password, delete account.

The 60-day trial is started in the desktop app, not on the dashboard. Full reference: Host Dashboard Guide.

Auto-KJ User Guide • Documentation Revision 2026-09-10 (v1.22) • auto-kj.com