Auto-KJ Library Guide

Version: 1.30.0. Source reviewed at 4171265227d8ea584bca359ba40b09d3ac0c8c6a on 2026-10-09.

Status: Complete written guide; source-reviewed behavior. No new v1.30 screenshots, screen recording, native file-operation test, or audio/hardware test was performed for this guide. Existing v1.29 captures use a simulated catalog and remain historical. The companion narration is an untimed draft pending recording and timing.

What this tab does

Library manages the karaoke folder, searchable metadata, preferred versions, songbook export, and collection health. Some controls only read data; others rename or move real files, remove catalog entries, or change which file queued songs will use. Make a backup before bulk maintenance, work outside a live show where practical, and read the exact path and count in each confirmation. [1]

The safest routine is to inspect the folder and health totals, correct one known entry, verify it in search, then apply any deliberate batch changes. A clean status banner alone is not a substitute for checking the resulting catalog, files, and watcher state.

Choose or reconnect the karaoke folder

Read the Library folder card. It shows the configured root, song count, and watcher state.
For first-time setup or a different collection, choose Choose Folder… and select the folder holding the karaoke files. Wait for the scanning/importing progress and result. A clean folder selection starts the watcher, even if you previously stopped it.
For newly added or changed files in the existing root, choose Rescan now, read the confirmation, and choose Rescan. It picks up new and changed files without deleting files. This route preserves whether the watcher was running before the scan.
If the same collection moved to another drive or root folder, use Relink Folder. Select its new root. Read the verification result, including how many sampled files matched. Check that the displayed root is correct and that known songs can be found. A sample match is not a full audit of every file.
Inspect the Watcher: Active/Stopped badge after each operation. Start Watcher and Stop Watcher control ongoing folder watching; ↻ Refresh reloads the tab's lists and status. Refresh is not a rescan. [1][2]

A warning can mean the selected folder was unsuitable; the old path can remain in use. If the watcher cannot restart, investigate the error and its badge rather than assuming a completed scan means automatic updates are active. Do not remove “missing” entries just because a drive is temporarily unplugged. Reconnect or relink first.

Read the totals

The stat tiles show catalog songs, artists, duplicate groups, unparsed entries, and missing files, with common brand counts alongside. Alternate files can contribute separate catalog entries; a song total is not necessarily a count of distinct title/artist pairs. A duplicate group is a set of alternate versions, which may be intentional. A Library Health — some checks failed card means a check failed; it must not be interpreted as a clean result. [1]

Save the brand preference order

Brand Priority Order controls which manufacturer wins among duplicate versions. Detected brands are added during scans. Drag rows or use Send to top, Move Up, Move Down, and Send to bottom to rank them. Add Code adds a manually entered brand, and ✕ removes a code from the preference list.

These are unsaved local edits until you choose Save Order. The “Order changed — not saved yet” bar is the reminder. Save recalculates defaults across the library once, then reports that preferences were saved. Revert restores the saved order. Removing a brand that still exists in the collection does not remove its files; a later scan can add that brand back at the bottom. [1]

Save or revert before ↻ Refresh, choosing a folder, or rescanning. In the reviewed source those refresh paths reload the saved preference list and can overwrite unsaved edits while the unsaved-change bar remains visible. Inspect the actual order rather than relying on that bar alone.

Correct a song

In Edit Song Details, enter at least two characters from the artist, title, or filename.
Check the result's artist, title, brand, and filename. Choose Edit… for the intended entry.
Correct Artist, Title, and Brand. Artist and title are required.
Decide whether to leave Rename file to match enabled. It starts enabled when the tab is created and shares its state with the unparsed-song editor. With it off, you are making a catalog metadata correction. With it on, the app also attempts to rename the file on disk to match.
Choose Save, then read the result. “Metadata saved, but the file rename failed” is a partial outcome, not a fully completed rename.
Search the corrected text again and verify the same intended entry. If you chose renaming, inspect the resulting filename too. [1]

Fix Unparsed Songs uses the same editor through Fix…. A proposed value is a best guess from the filename or known artists; confirm it before saving. Corrected catalog metadata persists through ordinary rescans, while renaming helps a fresh catalog parse the file correctly. Only one inline metadata editor is open at a time. Quarantine on an unparsed row is for a file you deliberately want out of the library, not a way to fix its title. [1]

Choose a default version and preview it

Use the artist/title search in Duplicate Tracks and select a song. The tab scrolls to Version Options, showing brand, disc/track, filename, and the DEFAULT badge. Use Show more to see additional duplicate groups after the displayed batch.

Choose Make Default only after checking the actual file. It is a per-song override, separate from the general brand order. It changes the catalog default and switches tonight's queued copies as well. The row becomes DEFAULT after the reload. This control acts directly without another confirmation in Library. [1]

Use the headphone button to preview a version. The preview has its own Key slider, from minus 6 to plus 6 in half-step increments, and Stop preview. Changing preview key restarts the preview. Configure a separate cue device in Settings first. If cue is off or shares the karaoke/Break-Wave output, the source permits silent video preview and displays the reason; this is not evidence that the headphones work. Check any preview/window error and stop playback before renaming or moving the file. [1]

Right-clicking a version row also offers:

Make this the default version, with the same wider effect.
Rename file…, whose dialog explains that metadata is re-read from the new filename and the extension stays. Read the proposed name, then choose Rename or Cancel.
Quarantine this file…, which names the file and moves it out of the catalog. Queued copies switch to another version if one exists. Read the confirmation before choosing Quarantine it. [1]

Review collection health

Loose File Cleanup

Choose Preview first. Review the proposed MP3+CDG pairs to zip, bare MP3 files to move, skipped items, and the destination. Run Cleanup is enabled only after a dry-run result with work to do. Its confirmation states the count and effect. A real run zips pairs and moves originals/bare audio into Quarantine, then rescans. Nothing in this cleanup flow is described as a permanent deletion. Keep your backup and inspect the resulting files before deleting anything manually. [1]

Missing Files

These are catalog entries whose files cannot be found. Check the drive and root first. Per-row Remove removes that catalog entry without a second dialog. Remove All From Catalog asks a counted confirmation and covers the full missing list, including entries not visible in the first batch. These actions clean the catalog and do not delete files on disk. [1]

Corrupt File Audit

Choose Run Audit to inspect library ZIPs for playable MP3 audio and CDG lyrics. Read each flagged path and reason. Quarantine All Flagged asks a counted confirmation, moves flagged files, and rescans. An audit with no flagged ZIPs does not prove every output device or all non-ZIP formats play correctly. [1]

Redundant Copies

This card identifies extra copies of the same pressing, using the same song, brand, and disc/track. Review the listed keep and quarantine paths. Quarantine Extra Copies asks for confirmation and covers all redundant extras, even when the card displays only the first groups. This differs from retaining useful alternate manufacturers in Duplicate Tracks. [1]

Possible Duplicate Spellings

Check whether two near-matching titles are genuinely the same song. Edit the canonical title and choose Merge & rename files only when they belong together. The confirmation includes the number of files; the operation retitles and renames affected files. Not a duplicate dismisses a genuinely different pair from future review and acts without a second confirmation. Similar spelling alone is not enough reason to merge. [1]

Artist Spelling Variants

Choose the correct artist spelling with its radio option and select Consolidate. The confirmation counts affected songs and explains that their metadata and filenames will change. Review the results and refresh to reach remaining groups if the card is showing a limited batch. [1]

Export a songbook

Choose Export Songbook CSV, select a save destination, and wait for “Songbook exported: [count] songs.” Open the saved CSV and check a few known titles, corrected metadata, and the expected scope before sharing it. Canceling the save dialog does not create an export. The source uses a native save dialog and file write; the historical simulated CSV is not evidence that a real destination on your rig is writable. [1]

Caveats and completion check

Duplicate Tracks displays 200 groups at a time and offers Show more. Unparsed and Missing Files render at most 200 rows without the same pagination; resolve/reload batches or use the deliberately counted bulk control. Other health cards explicitly report limited samples when applicable.
Bulk confirmations close with Cancel or a backdrop click; the reviewed bulk dialog has no Escape handler. Use its visible Cancel control when backing out.
Cleanup/quarantine rescans can replace an earlier watcher-restart warning with a later completion banner. Always check the Watcher badge independently.
Refresh can replace unsaved brand edits. Finish those edits before refresh or scan work.
A metadata save and a file rename can have different outcomes. Verify both when renaming was requested.

Finish by verifying the correct library root, current song counts, the saved preference order, a corrected search result, any changed default version, the watcher state, and the actual exported file. For file-moving actions, inspect the remaining library and Quarantine destinations. Real native dialogs, files, audio output, and file locks still need testing on the intended host computer. [1][2]

Current source references

All links are pinned to the reviewed v1.30 source and require access to the private repository.