Auto-KJ — Help & Troubleshooting

Comprehensive operational reference and diagnostic guide for Auto-KJ hosts. For conceptual guides and tutorials, see the User Guide and Guided Walkthroughs. Singer-side problems: Singer App FAQ. Tablet problems: Kiosk Guide. Account, key, venue, and billing problems: Host Dashboard Guide.

Quick Reference

1. Rotation Tab — Live Show Floor

The central workspace containing the Transport Player (top), Fair Slot Rotation Grid (left), and Song Search & Singer Details (right).

Player Controls & Real-Time Transport

• ▶ Play / ⏸ Pause / ⏹ Stop: Starts the selected singer's song. If no singer is selected, advances the next queued singer in line.
• Spectrum VU Meter: Real-time 11-band audio spectrum analyzer (63 Hz to 14 kHz) with peak-hold indicators.
• Mini Lyrics Monitor: Real-time CDG preview of what is rendered on the crowd lyrics screen.
• Pitch (Key Change): Shift key from −6 to +6 semitones in half-semitone (0.5) steps. Key adjustments are automatically remembered for that singer and song combination across future shows.
• Tempo Control: Adjust playback speed from 0.50× to 2.00× without altering pitch.
• GHOST-TRAX Vocal Slider: Real-time fader for the original artist guide vocal stem on Ghost-Trax tracks. Greyed out on standard karaoke tracks lacking guide stems.
• Auto-Advance: When checked, the player automatically triggers the next singer in line after a configurable delay (set in Settings → Rotation & playback → Automation & Playback).
• 👏 Live Applause: Real-time counter showing cumulative applause taps sent from singer phones for the active performance.
• 👥 Edit Performer: Edit the credited performer name or group roster on the fly while a song is playing.

Fair Slot Rotation Rules & Seat Management

• The Law of the Line: Every song a singer participates in sends their seat to the back of the line. Each person holds exactly one seat.
• Numbers Move / Names Move: A two-sided toggle above the rotation grid that sets how new singers are seated. Numbers move — a classic rotation sheet: every name holds its row all night and the numbers walk down it; a new singer is added to the bottom of the sheet and sings at the end of the current lap — after everyone still waiting this time round, before the people who already sang. Names move — the numbers stay fixed top-down and names climb; a new singer always enters last, behind everyone. Singer-facing screens always keep numbers fixed, whichever mode you run. The sheet survives tab switches and restarts.
• Pocket Queues: Additional songs requested by a singer wait in their 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 position. Joining a group cannot be used as a shortcut up the queue. After singing, all participants move to the back of the line.
• No-Show Handling: If a singer reaches the front with no song ready, they are skipped to the back and tagged with a NO SHOW badge. A second consecutive songless pass removes them from the line. Adding a song 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 right behind On Deck (slot #3 when nobody else is returning; several returning singers line up there in the order they unpaused). This prevents line-jumping while ensuring returning singers get up promptly. After an hour paused, both the host and the singer get a reminder. The seat stays held until the host clears it or the singer unpauses.
• Duplicate Song Blocking: The engine strictly forbids queuing identical songs concurrently. Phone requests for active songs are rejected with a notice; hosts can choose to override from the desk or Inbox.
• Corrupt File Auto-Quarantine: When a song is queued, its file is instantly inspected: a zip archive is opened, an MP3+G pair needs a readable MP3 and a non-empty .cdg beside it, and a video file must be readable by the video probe. If corrupt, missing its CDG, or unreadable, the file (an MP3+G pair moves together) is automatically moved to the Quarantine/ folder, purged from the active library, and replaced by a healthy alternate manufacturer version if available.
• Right-Click Seat Menu:
  • Rename: Correct typographical errors in the singer's name.
  • Merge with…: Combine two duplicate singer entries into one (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.
  • 🔓 Free the name…: When someone else's phone took a singer's stage name, this disconnects whichever phone holds it so the real singer can join under it. The seat and its songs stay in the line.
  • Play now: Immediately load and play the singer's top song.
  • Quarantine file: Isolate bad media directly from the queue.
  • 🔄 Change song…: Swap the song in that seat. It is greyed out for the singer on the mic, because their song is already playing.
  • Message User: Send a direct push notification to the singer's phone.
  • Photo Moderation: Review or clear user-uploaded avatars.

Rotation Troubleshooting

• A singer says someone jumped them: Verify if a group song fused or if a host manual drag reordered seats. Re-entry from pause always lands right behind On Deck, after anyone who unpaused earlier.
• Singer appears twice under slight spelling differences: Click the Similar-Name Banner ("🤔 Are Dave and David the same singer?") to merge in one click, or right-click → Merge with….
• Player won't start when clicking Play: Ensure an audio output device is selected in Settings → Audio & hardware → Audio Devices and that the chosen audio interface is plugged in.
• Key change didn't save: Key changes saved via right-click → Change key… or during playback are tied to the exact Singer Name and Song ID.

2. Inbox Tab — Request Management & DJ Communication

The gatekeeper for all incoming phone submissions, identity claims, singer inquiries, and tip alerts.

Request Ingestion & Approval Workflow

• 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.

Identity Claims, Departure Alerts & Messaging

• 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 Keep them.
• Failed actions keep the card: If Deny on a claim or Keep them on a departure alert fails (for example the connection dropped), the card stays in the Inbox and the error is shown, so you can try again.
• 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.

Inbox Troubleshooting

• Requests not appearing:
  1. Confirm header displays ● ONLINE (or local LAN fallback is active).
  2. Verify Accept Requests Online is switched ON.
  3. Ensure tonight's gig is picked in the Gigs tab (Use for this show).
• Auto-approve didn't process a request: Duplicate songs, account claims, and requests using reserved DJ stage names always halt for manual host review.

3. Break-Wave Tab & Pro Control Hub — 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, pitch fader with ±8 / ±16 / ±50% ranges, Keylock (time-stretching independent of pitch), Sync (continuous phase-locked tempo matching), and Tap / Analyze beatgrid correction.
• Beat Loops: LOOP 4 / 8 / 16 on each deck loops that many beats from the current beat, snapped to the beatgrid. Press the same length again, or EXIT, to leave the loop. A deck needs a reliable beatgrid (analyze or TAP it first).
• 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 Constant power, Sharp cut and Linear curves, AutoFade (AF), and master output limiter.
• Automatic Gain Staging: Every deck load is leveled by RMS (never peak) to a −14 dBFS target, with boosting capped so true peak never exceeds 98% of full scale. Quiet old rips come up, slammed masters come down, and tracks crossfade at equal loudness.
• 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

• One Break-Wave playlist: There is a single break playlist (under Deck A) — the Automix Set Planner, end-of-song break music and the phone remote's Play / Skip / Stop Break buttons all use it. Tracks from the old filler playlist and Deck B's queue are merged into it automatically on first launch.
• Automix Set Planner (one list): AUTOMIX re-orders the Break-Wave playlist itself — there is no separate plan list. The order chains tracks by BPM (within ±6%), musical key and an energy arc (build, plateau, wind-down), with a little seeded randomness, so every run makes a different mix (mix #a3f9 shows its seed). 🎲 New mix re-plans with a fresh seed; Undo reorder restores the order from before the last plan (until a set starts or you edit the list by hand). ▶ Start plays the playlist in its current order, so you can hand-reorder after planning. While a set runs the playlist is the queue: add (⤒ Next / + End), move or remove rows and the set follows; the rows show NOW / NEXT, a ⚡ (beat-locked), ◎ (echo-out) or ∿ (timed fade) icon for the transition into the next row, and ▶ next to play a row next. Ordering the playlist is free; running a set needs the Full version.
• Artists: Allow same artist back-to-back (default off, remembered per DJ profile) controls whether one artist can play twice in a row. With it off, the same artist never plays back to back unless only their tracks remain; "A feat. B", "A & B" and "A x B" count as artist A. Artists are also spread evenly through the set either way. Changing the checkbox applies to the next plan — click 🎲 New mix. Break music started by end-of-song or the phone remote uses the same planner with a fresh seed and your saved setting.
• Echo-out transitions: When two tracks can't be beat-locked (tempos too far apart, or the incoming track has no usable beatgrid) but the outgoing track has a usable grid, Automix echoes the outgoing track out and cuts to the next one on a beat instead of a plain fade.
• Transition Controls:
  • SKIP: transition now.
  • STOP: music keeps playing, set ends.
  • PANIC: instant clean cut to the current track.
  • ▶ RESUME: After a STOP or PANIC, picks the set back up from whatever is on the mic. It plays the playlist as it stands now (including any edits you made while stopped) minus everything already played, so the night continues rather than restarting from the top.

Break Music Library (Path, Search, Explorer)

• Path / Browse… / Identify sit at the bottom of the BREAK-WAVE PLAYLIST under Deck A. The break folder must not overlap the karaoke library (mp3, wav, m4a, ogg, flac).
• Search / Explorer tabs (bottom of the mixer strip) switch the dock: Search filters the whole folder (first 25 rows), Explorer walks one folder at a time with breadcrumbs and ↑ Up. Both offer ⚡ Analyze All, per-row ⚡ Analyze, →A / →B, ⤒ Next, + End, multi-select, and the right-click menu.
• Playlist: A / B load buttons, ▲▼, ✕, 🔀 shuffle, 💾 save by name, 📂 load saved playlists. ⏳ marks tracks still being analyzed; BPM and Camelot key fill in as each finishes. 25 rows show; the rest scroll.

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 - = while the pane is visible. ✎ EDIT PADS loads your own WAV/MP3/OGG/FLAC/M4A onto any pad (persists across restarts; ✕ reverts to the built-in). 🔊 master with a built-in limiter.
3. 🥁 Drum Sequencer: 16 steps × 6 tracks (Kick 808, Snare, Clap, CH Hat, OP Hat, Lo Tom) with S/M per track, BPM 50–220, SWING, SYNC A / SYNC B (one-shot match to a deck's BPM), presets (House 4/4, 90s Hip Hop, Trap Bounce, Disco Beat), CLR. LIVE PADS on Q–I add Cowbell and Shaker; ● REC ARMED quantizes pad hits into the running pattern. PATTERN A–H is a bank of eight patterns: click a letter to edit it (it plays from the next bar); presets and CLR change only the active pattern. CHAIN ON / OFF is song mode: + [letter] appends the active pattern to the chain, each step sets how many bars it plays (1–16) and × removes it; the chain loops at the end. MIDI can map next / previous pattern.
4. Looper (inside the drum pane): ● REC MIC for 1/2/4/8 bars starting on the next bar, or 📂 LOAD FILE; layers loop from the bar boundary with their own gain and ✕. Layers follow tempo changes: each layer remembers the BPM it was recorded at and speeds up or slows down to stay on the bar (varispeed, so its pitch moves with the tempo).
5. ✨ Pro FX Rack: per deck HPF / LPF, ECHO / DELAY (1/8–1/1 beat), REVERB / SPACE, FLANGER / JET, each with ON/OFF, MIX, and INTENSITY, plus RESET. Effects sit after the EQ and before the fader, so the headphone cue hears them.

Break-Wave Troubleshooting

• Decks won't output sound: Check Settings → Audio & hardware → Audio Devices → Break-Wave (Deck) Output. If marked "(not connected)", select an active soundcard. Switching devices restarts the decks and clears loaded tracks.
• Soundboard / drums come out of the wrong speakers: The soundboard, drums and looper play through the Break-Wave (Deck) output and its limiter. If the Break-Wave engine is not running they fall back to the computer's default output. Check Settings → Audio Devices → Break-Wave (Deck) Output, and open the Break-Wave tab once so the engine is running.
• MIDI controller does nothing: Open Settings → 🎛️ MIDI Controllers & DJ Hardware: bundled presets load automatically by device name, and MIDI Learn (click Learn beside an action, then press or move the control) binds anything else. Some preset numbers are marked "verify on hardware"; if a control does nothing, use Learn. Stream Deck is not supported.
• Automix / Sync locked: These require the Full version (the 60-day trial counts). Verify license status in Settings → License Activation. Ordering the playlist with AUTOMIX is free.
• Automix keeps doing plain fades: A track needs a usable beatgrid (analysis confidence ≥ 0.18, or a tapped grid). Right-click → Analyze song, or play it and TAP 4+ beats. Tracks whose analysis finishes mid-set upgrade automatically.
• Track Identification fails: Verify an AcoustID API key is entered in Settings → 🎵 Track Identification (free key from acoustid.org). Identify runs one file at a time and respects AcoustID's rate limit.
• Break folder refused: "…overlaps your karaoke library" means the folder is, contains, or is inside the karaoke library root. Pick a separate folder.

4. Library Tab — Catalog Curation & Audio Health

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

Catalog Curation Tools

• Statistics Dashboard: Total songs, unique artists, duplicate track clusters, unparsed filenames, missing file references, and brand breakdown.
• Clear Song Library (Surgical Catalog Reset): Under Settings → Session & Data → Clear Song Library, perform a surgical purge of catalog tables (songs, song_versions, songs_fts) with a 2-click confirmation dialog. This lets you re-index your files or switch hard drives cleanly without touching singers, the active rotation line, past performance histories, license keys, audio preferences, 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.

Library Troubleshooting

• Files added to folder don't appear: Auto-KJ monitors library folders via background file watcher. To force a refresh, click Rescan now at the top of the Library tab.
• Accidentally quarantined a file: Quarantined files are moved to the Quarantine/ folder inside your library directory. Inspect the folder and move healthy files back anytime.
• Playing Video Karaoke (.mp4, .mkv, .avi): Auto-KJ indexes and plays video karaoke formats natively alongside standard zipped .zip MP3+G files and .mp3+.cdg pairs.
• Auditioning songs (instant CDG preview frame): Right-clicking any song in search to preview immediately paints the initial lyrics title frame on mount, with a silent video preview window if headphone cue audio hardware is unconfigured.

5. Ghost-Trax Tab — AI Karaoke Track Creation

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

Track Creation Pipeline

1. Sign in: Sign in with your ghost-trax.com account (or create one) in the Ghost-Trax tab. Pasting a gtk_… API key is an alternative.
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: Uploaded to cloud conversion cluster.
   • Separating: AI stem splitter isolates instrumental, vocal, and backing stems.
   • Transcribing: Speech-to-text engine extracts word-level lyrics and timing.
   • Rendering: Generates synchronized CDG graphics stream.
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.

Live Guide Vocal Usage

During live shows, any Ghost-Trax track loaded in the player activates the GHOST-TRAX slider. If a singer struggles with timing or pitch, smoothly raise the slider to mix the original guide vocal stem into the front-of-house mix.

Ghost-Trax Troubleshooting

• Upload rejected: Confirm the audio file is under 60 MB and in a supported format (.mp3, .wav, .m4a, .flac, .ogg, .aac).
• Can't sign in / Invalid API Key: Check your ghost-trax.com email and password (or Forgot password?). If you pasted a gtk_… key instead, verify it on ghost-trax.com. Make sure you have conversion credits.

6. Analytics Tab — Business Intelligence & Reporting

Real-time show telemetry and historical performance logs.

Analytics Metrics & Leaderboards

• 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, song type, Key (the key change used, such as +2), Tempo (such as 1.10x) and applause totals. Songs logged before key tracking show —.
• Load errors: If performance history or the venue-report gig list fails to load, the tab says so inline with a Retry button instead of showing an empty section.
• Most sung & Saved favorites: 🎤 Most sung (what singers actually performed, from the performance log) and ⭐ Saved favorites (songs singers saved in the singer app; needs internet). (A singer's own History and Favorites are on the Rotation tab: select a singer in Rotation to see their History and Favorites; double-click a row to queue it.)
• Data Export: Export reports via Copy CSV, Copy JSON, or Print Report (with formatted venue staffing summaries).

7. Settings Tab — System Configuration & Rig Preferences

Configuration hub for hardware, network, rules, and profiles.

Settings is grouped into sections ordered by how often you touch them on a show night: Show night (Show Screens, Pre-show Check, LAN network, Remote Control) → Rotation & playback → Singers → DJ / host → Audio & hardware → Appearance → Library, data & help. License Activation leads the page until a key is entered, then drops to the bottom.

Settings Reference

• 🔑 License Activation: Register email and license key. Displays the public plan name: Free version, Full version ($10/month), Auto-KJ Lifetime ($500, one time, up to 4 shows running at the same time), Full version (venue Wi-Fi only), or a grandfathered Full version with its simultaneous-show count. Deactivate License returns to Free version.
  • Try Full version for 60 days: the no-card trial. Sign in with your auto-kj.com account (or Use an existing license key), Send verification code, paste the 64-character code from the email, Verify email, tick the consent box, Start my 60-day trial. Check existing trial re-syncs a trial started earlier on this computer; Refresh trial status and Use Free version appear while a trial runs. The card shows Ends {date} — this deadline never restarts.
  • Seat Conflict Resolution: If all licensed slots are active, a prompt offers [ Take over ] (gracefully kicks the longest-running instance) or [ Exit ].
• ✅ Pre-show Check (Show night): Readiness panel that flags anything not ready before doors. Each finding routes straight to the Settings card that fixes it. Under the audio row, 🔊 Test L and 🔊 Test R play a 2-second 1 kHz test tone on the left or right karaoke speaker, with a level meter, so you can confirm the wiring. They are off while a song is playing.
• 🎪 Tonight's gig: Pick tonight's gig in the Gigs tab (Use for this show). Venues and gigs live in that tab, not in Settings.
• 🔎 Browse Before You Go: Generates pre-show QR codes allowing singers to explore your songbook from home.
• 🔊 Audio Devices (Audio & hardware — all three pickers share one card):
  • Karaoke Main Output: Primary front-of-house speakers.
  • Break-Wave Output: DJ mixer output (can share with main or route to separate DJ mixer channel).
  • Headphone Cue Output: Exclusive pre-listen bus. Must be assigned to an independent audio device.
• 📶 LAN network → Singer network (Show night): Select the network (Wi-Fi / Ethernet) the singer QR code advertises for the local LAN server.
• 🤖 Automation & Playback: End of Song Action (Wait for Host, Auto-Advance, or Play Break Track Playlist), delay timer (0–60s), crossfade length (0–10s), and the Warn before interrupting a playing song toggle. "Play Break Track Playlist" starts Automix on the Break-Wave playlist (the one playlist under Deck A); if it is empty you'll see "Break-Wave playlist is empty — add tracks on the Break-Wave tab".
• Break song every N turns (Rotation & playback, under End of Song Action): After every N finished turns, the Break Track Playlist plays once and the next singer waits for you, even with Auto-Advance on. 0 = Off. Full version.
• ⚖️ Fairness Rules (Rotation & playback):
  • Repeat Song Rule: Set to Once per night, Cooldown timer (0.5–12h), or Off.
  • Song Cooldown: Minimum time before the same song may come round again.
  • Group Song Guest Rule: Slider from Open Stage (lenient) to Strict Rotation (full seat drop).
  • On-Deck Unpausing Rule: Restores an unpausing singer right behind On Deck (slot #3 when nobody else is returning; several returning singers line up there in the order they unpaused).
• 📱 Singer Phones (Singers): What singers see on their phones — the On-Deck Message (custom marquee text; leave blank for the default) and your Tip Handles (Venmo, PayPal, Cash App, or web URLs for the singer app's tip sheet). Both moved here out of Fairness Rules.
• 🚫 Blocked Songs / 🚫 Banned Singers (Singers): Per-gig song blocks and singer bans.
• 🎧 DJ Profiles (DJ / host — its own card): Create distinct profiles for different hosts sharing the rig. Saves themes, fairness rules, tip handles, and reserved stage names.
• ⌨️ Keyboard Shortcuts (DJ / host): Remap all transport, navigation, and queue hotkeys.
• 🎛️ MIDI Controllers & DJ Hardware (Audio & hardware): Configure Web MIDI hardware mappings.
• 🎨 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 & Marketplace modal (design custom skins, edit color tokens, test WCAG contrast scores, simulate UI widgets in the sandbox, browse/install community presets, and share .json skin files), and the Host window scale slider (50–250%; Ctrl +/− zooms, Ctrl 0 resets). The lyrics window's own Text & graphics size slider (50–300%) is under Show Screens.
• 🎵 Track Identification: the free AcoustID application key used by Break-Wave's Identify.
• 📖 Guides & Help: opens every published guide, including the Singer App FAQ, Kiosk Guide, and the auto-kj.com Dashboard guide. 🔁 Replay walkthroughs shows every tab's first-visit walkthrough again, starting with Rotation.
• 🖥️ Show Screens (Show night — one card at the top of Settings):
  • Crowd Lyrics Screen (Screen 2): Fullscreen CDG graphics, Now Singing/On Deck banners, upcoming list, and join QR.
  • Rotation Display Screen (Screen 3): Dedicated bar-TV rotation board with auto-densifying seat list, avatar badges, rolling announcements ticker, and dynamic Waiting on Partners queue displaying truthful blockers when singers wait for group members.
• 💾 Session & Data:
  • Start Fresh Session: Wipes tonight's rotation after 2-step confirmation.
  • Clear Song Library: Surgically purges catalog tables (songs, song_versions, songs_fts) with a 2-click safety confirmation, preserving all singers, rotation state, performance history, license keys, and rig settings.
  • Import History: Native OpenKJ SQLite, generic SQLite, CompuHost CSV, Siglos CSV, Karma singer folders.
  • Export History: Full history export to CSV or native OpenKJ SQLite format.
  • Validated Backup & Restore: Snapshot all show data, rules, and settings with checksums; restore takes a pre-restore snapshot first and relaunches the app.
  • Automatic local backups: checked at startup and hourly; choose the folder, the interval (6 h – 7 days), and how many to keep (1–100).
  • ⬆ Check for Updates: checks for a published signed update matching your desktop build: Windows x64/ARM64 or Linux x64 AppImage (Mac builds are currently paused). Website downloads may be available before an in-app update. .deb/.rpm installs update through the package.
• 📱 Remote Control: Pairing hub for DJ phone remote control with 1-click Revoke & Re-pair.

8. Singer Mobile Web App (PWA)

Web application accessed by singers at singer.auto-kj.com or via local LAN.

Singer Capabilities

• Joining a Show: Join automatically via GPS location, scan the lounge screen QR code, or type the 4-character show code (letters, sometimes ending in digits, e.g. CAZZ or CAZ1).
• Browse & Search: Search the host's live catalog. 🎤 lights up when the song is in your queue; ★ marks a saved favorite; Taken means already requested or sung tonight.
• Submitting Requests: Request solo or build group songs (2–4 singers) with non-blocking consent invitations.
• Live Queue Tracking: Real-time display of place-in-line ("You are #3 in line"), estimated wait time, and on-deck alerts.
• Self-Pause / Unpause: Singers can pause their seat when stepping away and unpause upon return.
• Pre-Planned Setlists: Build song setlists at home and submit with one tap upon arrival at the venue.
• Favorites & History: Save favorite tracks and view personal performance history across all Auto-KJ venues.
• Social Screen: Add friends via QR code and accept or ignore incoming friend requests (the Social tab shows a count), look through a friend's History and Favorites, find duet partners, form bands with friends (2–4 members; each bandmate accepts the invite first), and receive group invites.
• Change a queued song: Change on the singer's own solo queue row picks a replacement in Browse; the new request is sent first, then the old one is removed.
• Requests while offline: A request tapped while the connection is down waits on the phone ("1 request waiting to send") and goes out when the show reconnects. Waiting requests are dropped if the singer leaves or switches show.
• DJ chat: Each message the singer sends shows Sent, then Delivered ✓ once the host's app has received it.
• Walkthroughs: A short guide is offered the first time a singer opens each tab. Home has Replay this tab's guide; account holders also get Replay all guides in Social → Profile.
• 👏 Live Applause: Tap the applause button during performances (10-tap budget per song) with floating emoji reactions and badge progression.
• Tip Host & "Ask DJ to Buy Song": Send direct digital tips or request uncataloged songs with a tip pledge.
• Accounts: Sign in / Create account, Forgot password? (one-hour single-use link), Log out (header, connect screen, or Profile), Delete Profile (password required).
• Kiosk Mode: Walk-up tablet interface with attract loop, guided request flow, a ? help card on every screen, and anonymous submissions.

Singer-side troubleshooting (what to tell a singer)

Full list: Singer App FAQ.

9. DJ Phone Control (Booth Remote)

A dedicated mobile control console for the host, accessible over local Wi-Fi.

Setup & Security

1. Connect host laptop and phone to the same local Wi-Fi network.
2. In the host app, open Settings → Remote Control.
3. Scan the private pairing QR code with your phone (or navigate to http://<lan-ip>:8080/remote#token=<secret>).
4. The token authenticates your mobile browser session automatically.

Mobile Remote Operations

• Live Now-Playing Card: Displays current performer, song title, and playback status.
• Transport Buttons: Big-button ▶ Play, ❚❚ Pause / ▶ Resume (the label follows what the song is doing), ■ Stop, and ▶▶ Next.
• Break music card: Shows whether break music is playing and which track. ▶ Play break, ▶▶ Skip and ■ Stop break run the Break-Wave playlist.
• Soundboard: The 12 Pro Control Hub pads plus BELL and LAUGH, played through the Break-Wave output at the soundboard volume.
• Rotation Grid: View the full line of singers in real time.
• Reorder Singers: Tap up/down arrows on any seat to adjust queue position from the floor.
• Armed Singer Removal: Two-tap safety removal button (tap once to arm red, tap second time to confirm).
• Security Revocation: If a device is lost or compromised, click Revoke & Re-pair in host Settings to instantly invalidate all tokens.

10. Server Ecosystem (Cloud & Local LAN)

Auto-KJ employs a hybrid dual-engine architecture to guarantee 100% show uptime.

Cloud Server (cloud-server)

• High-performance Rust Axum service backed by PostgreSQL.
• Manages host/singer user accounts, hashed password resets, and Stripe subscription lifecycle.
• Provides real-time geographic indexing of active gigs for singer GPS discovery.
• Secure WebSocket relays (/ws/host, /ws/singer) stream requests, applause, and rotation state with sub-second latency.
• Coordinates floating license seats across multi-rig deployments.
• OpenKJ request hosting (/api/okj): Cloud request-server hosting for KJs running OpenKJ software.

Local LAN Fallback Server (local-server)

• Embedded Rust web server running inside the host desktop app on port 8080.
• Bundles and serves the entire Singer PWA statically to local phone browsers.
• If internet connectivity drops mid-show, the lounge screen QR and singer apps seamlessly switch to LAN mode.
• Hosts the token-authenticated DJ Phone Remote (/remote).
• Zero-Internet Guarantee: Run complete, fully functional shows in venues with zero internet connectivity.
• Media Privacy: Audio and video files remain strictly on the host rig — only song metadata is ever transmitted over the network.

What works offline (LAN fallback) and what needs the cloud

Singers on LAN keep in-app on-deck alerts (chime, vibration, banner) while the app is open. Songs completed on LAN are logged in the rig's local history only; they do not reach singer accounts.

Accounts on the LAN: the LAN server can't check sign-ins with the cloud, so it trusts a singer's account only when the phone shows a signed proof of that account, which the app fetches from the cloud while the singer is signed in and online. The proof lasts 12 hours. A singer who hasn't signed in online that day joins the LAN show as a guest: they can still request and sing, but account-based name claims, bans and seat linking treat them as a guest. Bands are not available on LAN; a band name on a LAN request is dropped, so it arrives as an ordinary group song.

11. auto-kj.com Dashboard & Account Problems

Full reference: Host Dashboard Guide.

Auto-KJ Help & Troubleshooting • Documentation Revision 2026-09-10 (v1.22) • auto-kj.com