Auto-KJ — User Guide

Professional karaoke hosting software and network ecosystem for Windows and Linux (macOS installers are not currently published). 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 x64/ARM64 setup .exe, or Linux x64 AppImage/.deb/.rpm; Mac installers are paused and not currently published) and launch it. Choose the build matching your processor. Website downloads and signed in-app updates may become available separately; update .deb/.rpm installations through their package.
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 Full version 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

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

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

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-semitone (0.5) steps. 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 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.
• Queue-Time Integrity Inspection: The moment a song is queued, its file is verified: 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. If corrupted, missing its CDG, or unreadable, the file (an MP3+G pair moves together) 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.
  • 🔓 Free the name…: Someone else's phone took this 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 (greyed out for the singer on the mic).
  • 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 Keep them. If Keep them or a claim's Deny fails, the card stays and shows the error so you can retry.
• 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, 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 loops that many beats from the current beat, snapped to the beatgrid; press the same length again or EXIT to leave. Needs a reliable beatgrid.
• 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.
• 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 but the outgoing track has a usable beatgrid, Automix echoes it out and cuts to the next track 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.

Automix Resume, Playlist & Auto-Leveling

• ▶ RESUME picks a stopped or panicked set back up from whatever is on the mic; it plays the playlist as it stands now, minus what already played.
• 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 that follow tempo changes). PATTERN A–H holds eight patterns; CHAIN ON plays them in song mode in the order you build (+ [letter], 1–16 bars per step), looping at the end. MIDI can map next / previous pattern.
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 Break-Wave (Deck) output and its limiter. If the Break-Wave engine is not running they fall back to the computer's default output. MIDI controllers can drive all of this; see MIDI Controllers below.

MIDI Controllers

MIDI starts when the app launches (main window), so a mapped controller works on every tab. Plug in any class-compliant USB/Bluetooth controller; all connected controllers are listened to at once. Open Settings → MIDI Controllers & DJ Hardware to see each device with an activity light and the preset it was matched to.

• Built-in presets (matched by device name): Pioneer DDJ-400 / DDJ-FLX4 (play, cue, sync, EQ, channel faders, tempo, hot cues 1–4, crossfader), Numark Mixtrack Pro 3 / Platinum FX (play, cue, sync), Novation Launchpad Mini MK3 / X (Programmer mode; pads → soundboard 1–12 and drum live pads), Akai APC mini (pads → soundboard/drums, faders → channel faders, crossfader, master), APC40 and MPD218. Some numbers are marked "verify on hardware" in the source; if a control does nothing, use Learn.
• MIDI Learn: expand a group, click Learn beside an action, then press or move the control (Esc cancels). Clear unbinds an action (and hides its preset binding); Reset to preset drops all your bindings. Learned bindings always override the preset and are saved per DJ profile.
• Actions: deck play/pause, cue, sync, nudge ±, pitch fader, key lock, hot cues 1–4, EQ high/mid/low and kills, channel faders, crossfader, master gain, AutoFade, Automix start/skip/stop, soundboard pads 1–12, drum sequencer start/stop and live pads 1–8, and karaoke play/pause, stop and next singer. Faders and knobs use the CC value; buttons fire on press. Deck and mixer actions need the Break-Wave engine running (open the Break-Wave tab once); drum actions need the Break-Wave tab loaded.
• The webview must support Web MIDI (Windows and macOS do; Linux WebKitGTK may not).

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. 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 → 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, song type, Key (such as +2), Tempo (such as 1.10x) and applause totals (— for songs logged before key tracking). If history or the report gig list fails to load, an inline error offers Retry.
• 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).

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 → Show night → 🖥️ Show Screens → Launch on the Screen 2 · Lyrics row (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 → Show night → 🖥️ Show Screens → Launch on the Screen 3 · Rotation row (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.
• 🎪 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. There, Edit on a venue renames it or changes its address, and Edit on a gig changes its schedule and times; the venue keeps its show code. Monthly gigs can repeat on the 1st–5th or the Last weekday.
• 🔎 Browse Before You Go: Generates pre-show QR codes allowing singers to explore your songbook from home.
• 🔊 Audio Devices: Independent device assignment for Karaoke Main, Break-Wave DJ, and Exclusive Headphone Cue.
• 📶 Show night → LAN network → Singer network: 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 / 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 (Full version) plays the Break Track Playlist once after every N finished turns and holds the next singer for you; 0 = Off.
• ⚖️ 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: Custom keybinding editor for all transport and navigation actions.
• 🎛️ MIDI Controllers & DJ Hardware: Web MIDI controllers, bundled presets and MIDI Learn (see MIDI Controllers above).
• 🎨 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. 🔊 Test L / 🔊 Test R play a 2-second 1 kHz tone on the left or right karaoke speaker with a level meter (off while a song plays).
• 🚫 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. 🔁 Replay walkthroughs shows every tab's first-visit walkthrough again, starting with Rotation.

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.
• Accounts on the LAN: the LAN server trusts a singer's account only with a signed proof the phone fetched from the cloud while 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; claims, bans and seat linking treat them as a guest). Bands are cloud-only.
• Free version: Full local show hosting with desk-entered requests.

13. Free version, Full version, and OpenKJ request hosting — 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 ($10/month): 1 live show at a time.
• Full version add-on (additional simultaneous show): +$5/mo for each additional simultaneous show (Full version licenses only).
• Auto-KJ Lifetime ($500, one time): up to 4 shows running at the same time. Everything in the full version. No monthly bill.
• Grandfathered Full version (1 live show at a time) or the 60-day trial: 1 live show at a time.
• Grandfathered Full version (2 simultaneous shows): 2 simultaneous live shows.
• Grandfathered Full version (4 simultaneous shows, Signature skins included): 4 simultaneous live shows.

The desktop app treats every Full version license alike. Licenses differ in simultaneous shows and, on some grandfathered licenses, the Ghost-Trax bundle. Full version (venue Wi-Fi only) runs the singer app over venue Wi-Fi only (no cloud relay, GPS discovery, venues, or gigs). The OpenKJ request-hosting add-on 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 the 4-character show code (letters, sometimes ending in digits, e.g. CAZZ or CAZ1).
• Catalog Search: 🎤 lights up when the song is in your queue; ★ marks a saved favorite; Taken means already requested or sung tonight.
• 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 with incoming friend requests (Accept / Ignore), a friend's History and Favorites, duet matching, bands with friends (2–4 members, each accepts the invite first), and non-blocking group song invitations.
• Change, offline outbox and delivery marks: Change swaps a song in the singer's own queue; requests tapped while offline wait as "waiting to send" and go out on reconnect; DJ chat messages show Sent then Delivered ✓.
• Walkthroughs: a short guide the first time each tab opens, with Replay this tab's guide on Home and Replay all guides in Social → Profile.
• 👏 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 / ▶ Resume, ■ Stop, and ▶▶ Next.
• Break music: ▶ Play break, ▶▶ Skip and ■ Stop break, with the current break track shown.
• Soundboard: the 12 soundboard pads plus BELL and LAUGH.
• 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 request hosting (/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 and gigs: Venues and gigs are managed in the desktop app's Gigs tab (needs a cloud plan or an active trial). The dashboard shows your plan, License Key, OpenKJ request hosting and security settings.
• OpenKJ request hosting: 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