Plugin API

QUP Karaoke Engine — Plugin API

For developers. If you are looking for how to turn plugins on and off, see Plugin Manager instead.

Every plugin QUP ships — SongShop, OBS Recording, Discord Party, MIDI Karaoke, AutoFiller and the rest — is built against this same public API. Almost nothing in the engine is reserved for first-party code: the exceptions are the few calls that move money or speak for the venue to QUP Cloud, listed where they appear.

Package: com.qupkaraoke.plugin, distributed as qup-plugin-api.jar. Current as of v2.37.3.


The shortest possible plugin

package com.example.myplugin;

import com.qupkaraoke.plugin.*;
import javax.swing.JPanel;

public class MyPlugin implements QUPPlugin {
    private PluginContext ctx;

    public String getId()          { return "com.example.myplugin"; }
    public String getName()        { return "My Plugin"; }
    public String getVersion()     { return "1.0.0"; }
    public String getAuthor()      { return "Me"; }
    public String getDescription() { return "Does a thing."; }

    public void init(PluginContext context) {
        this.ctx = context;
        ctx.getLogger().info("hello from My Plugin");
    }

    public JPanel getConfigPanel() { return null; }   // no settings UI

    public void onConfigPanelClosed() { /* persist settings here */ }

    public void shutdown() { /* release resources here */ }
}

Package it as a JAR containing a file at:

META-INF/services/com.qupkaraoke.plugin.QUPPlugin

whose single line is your fully-qualified class name. Drop the JAR in QUP's plugins/ folder and restart.

That service file is always com.qupkaraoke.plugin.QUPPlugin, even when you implement one of the specialized interfaces below. QUP discovers everything as a QUPPlugin and then sorts by type.

Third-party libraries your plugin needs go in plugins/lib/. Resolution is parent-first, so a library the engine already ships always wins over a copy you place there. You can also compile against engine classes — the shipped plugins use the engine's own widgets (Knob, VuMeter, SkinTheme) so their panels match the app.

Starting QUP with --safe-mode skips all plugin loading for that session without changing which plugins are enabled.


Lifecycle

QUPPlugin is the interface every plugin implements. QUP calls, in order:

  1. init(PluginContext) — you receive your API surface
  2. getConfigPanel() — your settings panel is registered in the config tree under Plugins
  3. onConfigPanelClosed() — every time the KJ closes the config window, and again just before shutdown
  4. shutdown() — QUP is exiting
Method Notes
String getId() Unique, reverse-DNS. Also names your data folder.
String getName() Shown in the config tree.
String getVersion()
String getAuthor()
String getDescription() One line.
void init(PluginContext context) The context is the only supported way to talk to QUP.
JPanel getConfigPanel() Return null for no settings UI.
void onConfigPanelClosed() default no-op. v2.5.0
void onSingersMerged(SingersMerged merged) default no-op. The KJ merged two singer accounts. See Singer merges below. v2.37.0
void onSingersMergeUndone(SingersMerged merged, int restoredSingerId) default no-op. The KJ undid a merge. See Singer merges below. v2.37.0
void shutdown()

Singer merges — v2.37.0

// QUPPlugin (both default no-ops)
void onSingersMerged(SingersMerged merged)
void onSingersMergeUndone(SingersMerged merged, int restoredSingerId)

// SingersMerged
String mergeId()
int    keptSingerId();    String keptSingerHash();  String keptSingerHashBefore();
String keptName();        int    keptCloudSingerId()          // 0 = none
int    removedSingerId(); String removedSingerHash(); String removedName();
int    removedCloudSingerId()                                  // 0 = none

The KJ can merge two accounts of one singer into one (Singer Database, "Merge with another account..."), and undo it within 90 days. The kept account survives with its row ID; the removed one is gone. Its singer hash after the merge, keptSingerHash(), is usually the hash of its karaoke name, the one phones and plugins use, and may differ from keptSingerHashBefore().

When onSingersMerged runs, QUP has already done its own part: balances are summed onto the kept account, and every credit ref a plugin added with addSingerCredits points at it, so a retry of an old ref answers repeat(). A plugin that stores anything by singer (hash, cloud id, name) moves the removed account's records, and the kept account's records under keptSingerHashBefore(), to keptSingerHash(). Remember what you moved under mergeId(): the merge may be repeated (move nothing the second time), and onSingersMergeUndone carries the same id. Records that are history (a finished refund, an expired payment) may stay where they are.

onSingersMergeUndone puts back exactly what you moved for that mergeId(). The removed account is back as restoredSingerId (its old row ID when that was still free), and the kept account is back on keptSingerHashBefore().

Both are called once, after QUP has committed, on a background thread (never the EDT). Keep them quick, a second or two at most. An exception is logged and never undoes the merge.

Save settings in onConfigPanelClosed(), not shutdown()

This is the single most important convention in the API.

A karaoke show runs for hours. If you only persist on shutdown, a crash or a forced quit loses everything the KJ changed since launch. Worse, QUP abandons any plugin that takes longer than 3 seconds to shut down so a stuck plugin cannot freeze the app on exit — which can kill a save queued behind slow teardown.

onConfigPanelClosed() runs on the EDT while the window is closing, so keep it cheap and never block. It is a default no-op, so plugins written before v2.5.0 are unaffected. An exception thrown here is caught and logged and cannot stop other plugins from saving.

Your config panel must be light-themed

QUP's config panel is always light regardless of the app skin, and QUP does not enforce this for you. Use white backgrounds, black text and blue accents, or your panel will look broken next to everything else.


Where your files live

Location
Your JAR APP_HOME/plugins/ — read-only on installed builds
Third-party JARs APP_HOME/plugins/lib/ — read-only
Your data folder DATA_HOME/plugins/data/{yourPluginId}/
Your private database DATA_HOME/plugins/data/{yourPluginId}/plugin.db

DATA_HOME is the per-user data directory — %LOCALAPPDATA%\QUPKaraoke on Windows, ~/Library/Application Support/QUPKaraoke on macOS, $XDG_DATA_HOME/QUPKaraoke on Linux. In dev and portable builds it is the same folder as the install. Never write next to your JAR; on an installed build that location is read-only.

getPluginDatabase() gives you a SQLite connection with WAL enabled. It is yours entirely — create whatever tables you like. QUP never reads from it.


PluginContext

The whole API surface. Every method is safe to call from any thread, and callbacks come back on the Swing EDT.

Library and import

boolean importSong(SongImport song)
boolean isSongInLibrary(String externalId)
String  getSongHashByExternalId(String externalId)   // null if not found
List<SongInfo> queryAllSongs(boolean fillerOnly)     // never null
boolean removeSongByHash(String songHash)
boolean removeFillerTrack(String filePath)
boolean reimportSong(String filePath, String artist, String title,
                     String cdid, int importFormat)
void    refreshFileList()
void    refreshMediaLibrary()

You download the file; QUP handles hashing, metadata extraction and database insertion. Removal takes the database entry only — the file on disk is never deleted.

SongImport.externalId is your store's own id for the song, and QUP stores it (mediadb.TRICERATRACKCODE) — that is what makes isSongInLibrary() and getSongHashByExternalId() able to answer. Namespace it, because the column is shared by every store: write "yt:dQw4w9WgXcQ" or "ptm:PH79809", not a bare id that another store could collide with. Comparison is case-sensitive.

Changed in 2.10.0 — externalId was previously accepted and then dropped, so the two lookup methods above always answered "no" for anything a plugin had imported. Plugins that already set externalId need no change; duplicate detection simply starts working.

importSong() scans the track's duration inline, so it can block for a moment on a large file — call it off the EDT.

Remove and reimport do not refresh the UI, deliberately, so a batch stays fast. Call refreshFileList() once when the batch is done. refreshMediaLibrary() is the one to call after batch metadata edits; it marshals to the EDT itself.

Metadata, genre and BPM

boolean updateSongGenre(String songHash, String genre)
int     updateSongGenres(Map<String, String> hashToGenre)   // one transaction
boolean updateFillerGenre(String filePath, String genre)
boolean updateSongMetadata(String songHash, String artist, String title,
                           String genre, String year)
boolean updateFillerMetadata(String filePath, String artist, String title,
                             String album, String genre)
double  detectBpm(String filePath)      // 0 if undecodable or no tempo found
void    updateSongBpm(String songHash, double bpm)
double  getSongBpm(String songHash)     // 0 if not yet analyzed

Pass null for any metadata field to leave it unchanged. updateSongBpm() will never overwrite a BPM the KJ entered by hand.

Transport — v2.0.57

void karaokePlay()    void fillerPlay()
void karaokePause()   void fillerPause()
void karaokeStop()    void fillerStop()
void karaokeNext()    void fillerNext()
void karaokeSeek(int seconds)   void fillerSeek(int seconds)

boolean isKaraokePlaying()
int     getKaraokePositionSeconds()   // -1 if unknown
int     getKaraokeLengthSeconds()     // -1 if unknown

Every command is a safe no-op when the target player is idle, and all of them go through the same paths as the KJ's own controls, so rotation and queue logic are respected. fillerPause() is best-effort: filler is a continuous radio-style player, so it pauses the countdown rather than hard-muting.

Queues — know which one you want

This is the easiest thing to get wrong. QUP has two separate queues.

// The separate filler music player
boolean addToFillerPlaylist(String filePath)
int     addToFillerPlaylist(List<String> filePaths)   // returns count enqueued
boolean addFillerUrl(String url, String displayName)  // v2.0.57
int     getFillerPlaylistSize()
int     getFillerPlaylistIndex()
void    clearFillerPlaylist()
boolean isFillerPlaying()
List<String>        getFillerDatabasePaths()   // never null
Map<String, String> getFillerGenres()          // never null
int     rescanFillerTags()

// The main karaoke playlist
boolean queueSong(String singerHash, String songHash)
boolean enqueueFileToPlaylist(String filePath)
boolean queueUrlToPlaylist(String url, String displayName)   // v2.0.57
int     getKaraokeUpcomingCount()

addToFillerPlaylist() and addFillerUrl() feed the background music player. enqueueFileToPlaylist() and queueUrlToPlaylist() append to the main karaoke playlist as a filler row — singer name "Filler" — which bypasses rotation entirely.

getFillerGenres() maps absolute path to genre; untagged tracks map to null or empty. rescanFillerTags() reads files off disk, so call it from a background thread.

UI

void registerMediaTab(String tabTitle, JPanel panel)
void registerMediaTab(String tabTitle, JComponent panel, String category)  // v2.1.4
void registerMediaTab(String tabTitle, JComponent panel, String category,
                      boolean poppable)                                   // v2.34.0
void registerLibraryMenu(LibraryTarget target, LibraryMenuProvider provider)
void registerPlaylistMenu(PlaylistMenuProvider provider)                  // v2.16.0
void registerKioskTab(String tabTitle, JPanel panel)
void registerAboutLog(Supplier<String> log)                               // v2.35.1

category is "Audio" (shown first) or "General" (the default). You own your tab's UI completely.

Pop out — v2.34.0. With poppable true, the KJ can right-click your tab's leaf in the Media Library and choose Pop out: your panel moves into a window of its own that floats, resizes, keeps its place and size, and goes back into the Media Library when closed. QUP's hotkeys keep working while that window has the focus, and it opens popped out again on the next launch if it was out when QUP closed. Your panel must not assume a fixed parent: it is moved between the Media Library and its window. The three-argument form is the same as poppable false.

About-box log — v2.35.1. registerAboutLog hands QUP a running activity log for the About box. QUP calls your supplier on the event thread whenever the KJ opens that log's tab, so return the text as it is now, quickly, and never anything secret (passwords, keys). Pass null to take it away again, for example in shutdown(). Today the About box has one such tab, OBS, which shows the OBS Recording plugin's log; a log registered by any other plugin is kept but not shown. It is a default no-op, so on an older engine the call does nothing.

LibraryMenuProvider is a functional interface called fresh every time the right-click menu is about to open, with the current selection — so your entry can be fully dynamic. Return null to contribute nothing. LibraryTarget is KARAOKE, FILLER or BOTH.

Dialogs and notifications

void    showNotification(String message, boolean isError)   // non-blocking
boolean showConfirmDialog(String title, String message)

showNotification() shows a toast near the bottom of QUP's active window for a few seconds, says it to a screen reader, and logs it. Nothing is drawn while QUP is not the active window, so your own pane should still show any state the KJ must not miss. Use it for outcomes (done, or why it failed), not for frequent progress: every call is a toast and a spoken line.

Native file dialogs — v2.0.54

File       openFile(Component parent, String title)
File       openFile(Component parent, String title, String startDir, FileFilterSpec... filters)
List<File> openFiles(Component parent, String title, FileFilterSpec... filters)
File       openFolder(Component parent, String title, String startDir)
File       saveFile(Component parent, String title, String suggestedName, FileFilterSpec... filters)

Genuinely native — IFileDialog on Windows, NSOpenPanel on macOS, GtkFileChooserNative on Linux — and they follow the OS light/dark theme. parent may be null.

All return null on cancel except openFiles(), which returns an empty list. FileFilterSpec normalises patterns, so "csv", ".csv" and "*.csv" all mean the same thing.

These replaced the older createFileChooser / createFolderChooser methods, which are removed.

Theming

Map<String, Color> getSkinColors()
int  getListFontSize()
void applyStandardListStyle(JTable table)    // v2.0.27
void addListStyleToggle(JPopupMenu popup)    // v2.0.27

Colour keys: panelBg, panelBgDark, panelBorder, textPrimary, textDim, textActive, vfdKaraokeOn, vfdFillerOn, accent.

applyStandardListStyle() gives a table the skin's colours, alternating rows, the user's font size and the right-click style toggle in one call. It is safe to call repeatedly. If your table already has its own popup menu, use addListStyleToggle() to add just the toggle item to it.

getListFontSize() does not apply to config panels.

Singer identity — v2.2.1

boolean verifySingerPin(String singerName, String pin)
boolean singerHasPin(String singerName)
boolean singerExists(String singerName)

The PIN is never exposed to plugins. You may verify one; you must never receive, cache, log or persist it.

verifySingerPin() returns false for an unknown singer, a wrong PIN, and a singer with no PIN on file. The three are deliberately indistinguishable so a plugin cannot leak which singer names exist.

singerHasPin() exists for KJ-facing diagnostics only — "PIN required but none set" is a configuration problem a KJ cannot fix if they cannot see it. Never reflect it back to whoever is authenticating, because it reveals the name exists.

Name matching runs through SingerNames.normalize(), the same rule the rotation uses at showtime, so "verified" and "matched on stage" cannot disagree.

Audio

AudioSink openAudioSink(AudioFormat format)   // v2.1.4; null if audio unavailable
void      setFillerAudioTap(AudioTap tap)     // v2.2.1; null removes
void      setKaraokeAudioTap(AudioTap tap)    // v2.6.0; null removes
AudioSink openEffectsSink()                   // v2.25.0; filler-side effects, null if unavailable
double    effectsSinkRate()                   // v2.37.1; that sink's rate, without opening it

App info and automation

String     getAppVersion()
int        getAppMajorVersion()
Logger     getLogger()
File       getPluginDataDir()
Connection getPluginDatabase()    // null if the SQLite driver is unavailable
Automation getAutomation()        // v2.0.57
boolean    isDjMode()             // v2.8.0

isDjMode() — whether QUP is currently running in DJ mode rather than karaoke mode. DJ mode has no singer rotation, no filler bed, and no kiosk queue — a plugin whose menu entries or behavior assume any of those (an auto-fill queue, a karaoke-only transport) should query this and self-gate rather than have the host hide its items for it.

Shared tools — v2.13.0

PluginComponents getComponents()

For a plugin that runs ffmpeg, yt-dlp, deno or the Python audio environment (demucs and whisper). Declare the components in your catalog entry and installing your plugin from the Plugin Browser installs them — a KJ never visits your settings to press a setup button first. getComponents() is for the two things left to you: finding out where a tool is, and putting one back.

String locate(String componentId)                  // absolute path if usable now, else null; no network
String ensure(String componentId,
              Consumer<String> status,             // short progress lines; may be null
              IntConsumer progress)                // 0-100 for the current download; may be null
       throws Exception                            // message fit to show a KJ
void   cancel()                                    // ensure() then throws InterruptedException

Component ids: ffmpeg-gpl, ytdlp, deno, py-audioml. For py-audioml the path is the Python interpreter; the environment's scripts (demucs, whisper) sit beside it — in Scripts\ on Windows.

"Usable" means it passed a capability check, not that a file exists. An ffmpeg that cannot burn subtitles is reported missing even though it runs. The path may be a copy QUP adopted rather than downloaded — Homebrew's ffmpeg-full, say — so ask locate() instead of looking in a folder yourself; a Finder-launched Mac app has no useful PATH to find such a copy on.

ensure() uses a working copy if there is one, otherwise downloads, verifies, unpacks and checks it — minutes for py-audioml. Both calls start processes: never call them on the EDT. Each getComponents() returns a fresh handle, so cancel() stops only your own install. A plugin that calls this needs "minEngineApi": "2.13.0" in its catalog entry, or an older QUP will load it and fail at the call.

Windows and layouts — v2.37.3

default WindowLayouts getWindowLayouts()   // PluginContext; null where WINDOW_LAYOUTS is false

What it gives you. The KJ's saved window layouts for the running mode (Windows > Layouts) and the workspace windows. It is the same feature the KJ uses from the menu, not a second layout system.

Check first. Call ctx.hasFeature("WINDOW_LAYOUTS") before getWindowLayouts(): - It is true from 2.37.3 in Karaoke, DJ and Media Player mode. - It is false in Host and Simple Player, which are one window each. There getWindowLayouts() is null. - It is false on an older engine. There getWindowLayouts() doesn't exist, so calling it unguarded throws NoSuchMethodError.

A plugin that can't work without it sets minEngineApi to 2.37.3 in its catalogue entry. One that only uses it when present just checks hasFeature.

Threading. Call every method on the Swing event thread. A call from another thread throws IllegalStateException. Listeners are called on the event thread.

Bad ids and names. None of these methods throws for a bad id or name: a getter returns null or false, and a setter returns false.

Saved layouts

List<String> listLayouts()                    // the running mode's saved names, in menu order
boolean      applyLayout(String name)         // switch now, as the menu does; false: no such name
SaveResult   saveLayoutAs(String name)        // SAVED, DECLINED, INVALID_NAME, FAILED
void addLayoutListener(LayoutListener l)      // layoutsChanged(Change, String name)
void removeLayoutListener(LayoutListener l)   // Change: SAVED, APPLIED, RENAMED, DELETED, IMPORTED
  • A switch moves the windows at once, with no restart. It sets where every window sits, its size, and whether it is docked, open, rolled up or always on top. It never moves the singers' screen.
  • Saving a new name saves at once. If the name exists, QUP asks the KJ "Replace?", and Enter means Cancel. The call returns once the KJ has answered: DECLINED if they cancelled. A plugin can never replace a KJ's layout silently.
  • Names are 1 to 40 characters and match ignoring case.
  • Renaming, deleting and importing are the KJ's alone, in Windows > Manage layouts. A listener hears about them.

Windows

List<String> listWindows()                          // "player", "medialibrary", "playlist", "mix", …, "plugin.<id>"
String       windowTitle(String id)
Rectangle    getBounds(String id)                   // on screen if floating and shown, else its saved floating place
boolean      setBounds(String id, Rectangle r)      // floating windows; saved as if the KJ dragged it
boolean      isDocked()
void         setDocked(boolean docked)              // the whole workspace, as Dock/Undock Windows
boolean      isShowing(String id)
boolean      setShowing(String id, boolean show)    // as the window's tick in the Windows menu
boolean      toFront(String id)
  • Ids are stable and never translated. They cover the workspace windows (the Player and its parts, the Media Library, the Playlist or queue, the DJ windows) and plugin pop-outs as plugin.<id>.
  • Output windows are not listed, and no id reaches them: neither the singers' screen nor DJ Visuals.
  • Docking is all-or-nothing, as in the menu. While the workspace is docked, setBounds, setShowing and toFront return false.
  • setBounds fits the window onto the visible desktop. A window sized by its content keeps its size.
  • setBounds saves to the current arrangement, never to a saved layout.
  • setShowing(…, false) refuses the Player. Closing its window quits QUP.

Hotkeys — v2.12.0

void registerHotkeyAction(String id, String displayName, Runnable action)
void unregisterHotkeyAction(String id)
void registerGlobalHotkeyProvider(GlobalHotkeyProvider provider)

registerHotkeyAction() offers an action the KJ can bind to a key in Config → General → Hotkeys — as an in-app key, a global key (one that fires while QUP is not the focused window), or both. It is listed under your plugin's name and exists in karaoke and DJ mode alike. Holding the key down does not repeat it.

The id is plugin.<your getId()>.<action>, for example plugin.com.example.recorder.startRecording: dotted segments of letters and digits, each starting lower-case or with a digit. Anything outside your own namespace, or not a valid id, throws IllegalArgumentException, as does a missing name or action.

Never rename an id. The KJ's keymap stores the id, not your display name, so a renamed id silently unbinds the key for every KJ who bound it. Change the display name as often as you like.

Registering an id that already exists updates it in place — name and action — so you can switch your actions on and off at runtime with these two calls. A KJ's binding to one of your ids survives your plugin being disabled, uninstalled or not loaded yet: the Hotkeys page shows it as (action not found), and it works again the moment you register that id. No restart.

The action runs on the Swing EDT. Keep it short and hand long work to your own thread. An exception it throws is caught and logged with your plugin id; it never reaches the key dispatch.

registerGlobalHotkeyProvider() replaces the engine's built-in backend for global keys — see GlobalHotkeyProvider under Specialized plugin interfaces below. Almost no plugin needs it.

Playlist menu — v2.16.0

void registerPlaylistMenu(PlaylistMenuProvider provider)
JMenuItem PlaylistMenuProvider.buildMenu(List<PlaylistEntryInfo> selected)

Contribute a right-click entry to the karaoke playlist. The provider is called fresh each time the popup opens, with the right-clicked rows as read-only PlaylistEntryInfo snapshots. Return a JMenuItem (or a JMenu), or null to add nothing. Plugin entries appear after QUP's own. A provider that throws is logged and skipped; it never breaks the menu. buildMenu runs on the Swing thread as the menu opens, so keep it quick and do slow work in the item's action.

PlaylistEntryInfo Meaning
getSong() the SongInfo this row plays (its hash is the library song hash)
getSingerName() the singer's display name; empty for a filler row
getQueuePosition() 1-based position as the KJ sees it
isPlayed() / isLocked() row state
isCurrent() this entry is staged, playing or paused. Do not read or rewrite its file while true. Errs toward true while a song is being staged.

Library health — v2.16.0

boolean        isSongMarkedBad(String songHash)
boolean        setSongMarkedBad(String songHash, boolean bad)
List<SongInfo> queryMarkedBadSongs()
boolean        isPlaybackBusy()
String         getCurrentKaraokeSongHash()
AutoCloseable  holdSongFile(File file)

For a plugin that checks or repairs song files.

isSongMarkedBad() / setSongMarkedBad() read and set the bad-file flag — what Note Bad File sets, and what QUP sets when a song fails to play. A marked song cannot be enqueued. Setting it behaves exactly like the menu command, including the visible library row; it returns false if there is no such song. queryMarkedBadSongs() returns every marked song — a repair tool's worklist, cheaper than queryAllSongs() and a check per song.

isPlaybackBusy() is true while a song is being staged or any audible player (karaoke, filler, either DJ deck) is playing or paused. When unsure, it says busy. Write song files only when it is false. getCurrentKaraokeSongHash() names the entry playing or paused, or null; while the next song is staging it still names the previous one, so gate writes on isPlaybackBusy(), not on this.

holdSongFile() keeps QUP's own readers off a song file while you rewrite it in place: staging waits for it, and background checks treat the file as "try later" instead of marking it bad. Take the hold first, then check isPlaybackBusy(), and close it as soon as the replace is done:

try (AutoCloseable hold = ctx.holdSongFile(zip)) {
    if (ctx.isPlaybackBusy()) return;   // try again later
    // write beside the original, then one atomic replace
}

A plugin that calls any of these needs "minEngineApi": "2.16.0" in its catalog entry.

Song sources — v2.17.0

SongSource openSongSource(String scheme, String displayName)

For a plugin that brings its own catalog of songs with no file on disk — a streaming service, a download-on-demand store, a remote player. QUP lists and searches those songs with the library, badged with displayName, and the KJ queues them like any other song. KaraFun is built on it.

A source's songs are scheme:sourceId, e.g. karafun:12320. The scheme is lower-case letters, digits and -, and belongs to the first plugin that opens it: openSongSource() creates the source on first use and returns the same one after that. It throws IllegalArgumentException for a malformed scheme and IllegalStateException if another plugin owns it or the database is unavailable.

String     getScheme()
String     getDisplayName()
SyncResult sync(Collection<SourceSong> songs)   // replace the whole catalog
int        count()                              // listed songs, removed ones not counted
long       lastSync()                           // epoch millis, 0 if never
SourceSong find(String sourceId)                // null if not listed or removed
String     hashFor(String sourceId)             // the song hash a playlist entry, history and phone requests carry
void       setUnavailable(Map<String, String> reasonsBySourceId)   // v2.33.0

Fetch your catalog however you like and hand QUP the whole list with sync(); songs are matched by getSourceId(). A song missing from a later sync is flagged removed, not deleted, so a rotation or history entry that points at it still knows what it was; one that comes back is restored. SyncResult reports added, updated, removed, restored, total and millis.

Call sync() off the Swing event thread — it writes to the database. The first sync into an empty source takes a verified database backup first and imports nothing if that backup fails (IllegalStateException). QUP keeps source songs apart from the file library and never uploads them anywhere.

To make the songs playable, the same plugin implements PlaybackSourcePlugin's URI methods for its scheme (below). Not to be confused with registerCatalog(), which is for songs a store sells.

Songs that can't be played here — v2.33.0. setUnavailable() hands QUP the songs your plugin already knows it can't play at this venue right now, each with a reason for the KJ (sourceId → reason). The library shows them greyed, with the reason as a tooltip. Each call replaces the last map, and an empty map clears it. It is held in memory only, so hand it over again after every start. To refuse a song at the moment someone queues it, answer unavailableReason(URI) in your PlaybackSourcePlugin (below).

A song's own badge — v2.33.0. Put SourceSong.EXTRA_BADGE ("badge") in a song's extra to show that badge instead of the source's name: in the library's CD-ID column, on a queued song and on a phone. It is for a separately licensed part of a catalog ("KaraFun Integral"). The library's source filter offers each badge.

Cloud lists and reports — v2.33.0.

CloudSourceList cloudSourceList(String scheme, String list, String have)
boolean         cloudSourceReport(String scheme, String kind,
                                  List<Map<String, Object>> rows)

QUP Cloud can keep a song list for your source beyond its own catalog. list names it: "integral" is KaraFun's Integral Catalog, which QUP Cloud mirrors daily. Pass the listHash you already hold as have: an unchanged list comes back with unchanged true and no songs. Each song is {songHash, sourceId, artist, title}, where songHash is the QUP hash for scheme:sourceId, so you can check it against hashFor(). The result is null when this QUP isn't registered with QUP Cloud, the cloud has no such list for this venue, or it can't be reached.

cloudSourceReport() sends QUP Cloud reports about your source. kind names them: "nofly" is songs KaraFun refused to play here, for the shared No-fly list. rows hold plain values (strings, numbers, booleans). It returns false when QUP isn't registered, the cloud can't be reached, or the cloud refused: keep the rows and try again later.

Both are signed as this venue and block for the request: call them off the Swing thread.

A plugin that calls this needs "minEngineApi": "2.17.0" in its catalog entry.


Run modes — v2.20.0

String  runMode()
boolean hasFeature(String feature)

QUP boots as one of four run modes: Karaoke, DJ, Media Player and Simple Player. The two player modes are one player with a plain ordered playlist and no singer rotation: Media Player wears Winamp's windows, Simple Player a single KaraFun-shaped frame. A plugin gates on what a mode builds, not on which mode it is.

runMode() is the mode QUP booted as, by its stable id: "karaoke", "dj", "media" (Media Player) or "simple" (Simple Player). Lower-case, never localised, never renamed. Prefer hasFeature for gating: a plugin that asks "is there a rotation?" keeps working when a fifth mode arrives; one that compares ids has to be revisited.

hasFeature(feature) is whether the running mode builds feature, spelled exactly:

feature what it gates
ROTATION the singer rotation and its queue (Enqueue / Replace / singer dialogs)
SINGER_DB the singer database
CLOUD_KIOSK cloud sync, the kiosk, the mobile app's venue protocol
FILLER_PLAYER the filler bed and its queue
KARAOKE_PLAYER the karaoke player chain
CDG_PROJECTOR the singer display
DECKS the two-deck mixer
STATUS_BAR the status strip
HELP help topics and tours
FILLER_ONLY_URLS not a mode feature but the edition's, since v2.26.0: internet radio stations go to the filler side only. There queueUrlToPlaylist sends a station to the filler queue as addFillerUrl does, so hide your own "add to the karaoke playlist" action for stations. false on older engines, which keeps both actions
WINDOW_LAYOUTS since v2.37.3: getWindowLayouts(), the saved window layouts and the workspace windows. True in Karaoke, DJ and Media Player; false in Simple Player and Host (one window each) and on older engines

An unknown name is false. Karaoke has everything but DECKS; DJ has only DECKS; the player modes have KARAOKE_PLAYER and CDG_PROJECTOR only. WINDOW_LAYOUTS comes on top of those in Karaoke, DJ and Media Player. A plugin that enqueues filler checks hasFeature("FILLER_PLAYER") rather than isDjMode(): the player modes have no decks and no filler queue either. Shipped plugins already gate this way: Auto Filler hides itself without FILLER_PLAYER.

What a plugin sees in the player modes:

  • registerLibraryMenu entries appear on the one flat library (Simple Player) as well as on the Media Library's tables (Media Player); row objects are the same SongInfos.
  • onSongStarted / onSongEnded fire for the playlist's rows exactly as for a rotation entry; the singer name is empty.
  • There is no rotation to enqueue into: enqueueSong and the singer-shaped calls return false / do nothing; a plugin adding songs appends to the playlist through the library menu's "Add to Playlist" semantics (queueSong with the singer ignored).

Patron queue — v2.21.0

The methods a plugin needs to let a person in the room queue a song for themselves: find it, ask whether they may, add it, see where they are, change their mind.

Two things to know before using any of it.

Every enqueue is guarded. There is no queue type a plugin can pass and no flag meaning "trust me". A plugin add is subject to Max Singer Repeat and the venue's sold-out cutoff exactly as a kiosk add is. The KJ's own bypass exists because the KJ is standing at the machine; a request arriving from a phone is not that.

Resolve a name once. Pass the name as the person typed it — these methods fold case, padding, repeated spaces, non-breaking spaces and NFKC variants through SingerNames.normalize and resolve to the stored singer. Do not re-derive a singer from user input between calls, and do not build your own matching.

Finding songs

method meaning
List<SongInfo> searchLibrary(String query, int limit) Songs where every whitespace-separated word appears, case-insensitively, in the artist, title or CD-ID. Title matches rank first. Covers registered song-source catalogs as well as the media database. A blank query returns nothing, not the whole library. Served from an in-memory index, so it is safe to call per keystroke and from a request handler on any thread.
SongInfo songByHash(String songHash) One song by its hash, or null. The other half of the search: a hash is the handle a patron UI is left holding, and it has nothing to resolve it against. Covers song-source catalogs too, so it finds the same library the search did -- resolving a hash through the media database alone silently misses every song that came from a source. Same in-memory index, so it is a map lookup.

Asking before acting

method meaning
QueueEligibility canQueue(String singerName) Whether this singer could add one more song right now, changing nothing. Runs the same guard the enqueue runs, so the two cannot disagree.
int songQueuesLeft() Song slots left at the venue before closing time, or -1 when the venue never closes. Venue-wide and time-derived, so it falls as the night goes on even if nobody queues.

QueueEligibility: isOk(), getReason(), getQueued(), getMaxPerSinger() (0 means unlimited — the engine's own convention, and the default when the setting has never been written), getSongQueuesLeft(), getRemainingForSinger() (per-singer only; a venue can be sold out while this is positive, so it is not on its own permission to queue).

Queueing

method meaning
QueueResult enqueueForSinger(String singerName, String songHash, String requestToken) Guarded add. The singer must already exist — this never creates one as a side effect, so claiming a name stays a step you can put your own checks in front of.
QueueResult enqueueForSinger(String singerName, String songHash, String requestToken, int pitch, int tempo) v2.22.0. The same guarded add, carrying the singer's pitch and tempo. A default that delegates to the three-argument form, so every existing plugin keeps compiling and keeps its behaviour; override it if your plugin can honour the settings. Units are the engine's own — 0 is unshifted, and the range is whatever the player accepts. Pass 0, 0 when there is nothing to say. The kiosk has always sent pitch and tempo with a request, so without this overload moving it onto the authenticated contract would have silently dropped the setting on every song.

requestToken is an idempotency key, and the reason to use one. Generate it once per confirmation — not per attempt — and the same token twice is safe: the second call returns DUPLICATE_REQUEST with isOk() true, plus the existing entry's hash and position, instead of a second song. That is what makes a double-tapped confirm button, or a phone retrying after a timeout, land exactly one entry. This holds even when the singer is at their cap. Pass null to opt out and accept that a retry may duplicate.

Reading the queue

method meaning
List<PlaylistEntryInfo> queueSnapshot() The whole playlist in order. Enough to render "what's coming up", to notice a song is already queued before offering it again, and to work out how many songs are ahead of someone.
List<PlaylistEntryInfo> queuedFor(String singerName) Just that singer's unplayed entries, each with its live queue position. The "my songs" view.
int queueLength() Unplayed entries in the karaoke playlist.
boolean queueAcceptingRequests() Whether this venue can take queue requests at all right now: venue-level readiness ("is the rotation wired up"), which canQueue cannot tell apart from a singer at their limit. The HTTP front doors are bound early in startup, before the queue engines; a client that asks this can show "starting up" instead of a refusal the patron will blame on themselves. False in modes with no rotation, such as DJ mode.

Both lists are snapshots read off the UI thread. The queue is reordered by every later request, bribe and KJ drag, so read again rather than caching.

Singers

method meaning
boolean createSinger(String singerName, String pin) Create a singer so they can be queued for. PIN is digits only, at most 8, rejected rather than truncated if it fails. Returns true if the singer exists afterwards, whether or not this call created them — so a re-claim is not an error.

An existing PIN is never overwritten. A KJ can type a PIN straight into the singer editor as a mid-show override, and a patron re-claiming that name must not be able to replace it. Back-filling only happens when there is no PIN on file. If you want to require exactly four digits, enforce that before you call.

Pair with the existing singerExists, singerHasPin and verifySingerPin.

Changing your mind (ownership-checked)

method meaning
QueueResult removeQueuedForSinger(String singerName, String entryHash) Remove one of this singer's own queued songs. Their rotation count is decremented without crediting a song as sung, so removing does not disturb their place.
QueueResult swapQueuedForSinger(String singerName, String e1, String e2) Swap two of this singer's own entries — reorder what they sing next.
QueueResult changeQueuedSongForSinger(String singerName, String entryHash, String newSongHash) Change which song one of their entries will play, keeping their place in the rotation.

All three verify the entry belongs to that singer and is unplayed, refusing with NOT_YOUR_ENTRY or ALREADY_PLAYED and changing nothing otherwise. Swap also refuses across singers, and that is not politeness: the underlying operation exchanges the songs between two queue slots, so a cross-singer swap would hand one person's song to another person's turn.

Favourites and history

method meaning
boolean addFavoriteForSinger(String singerName, String songHash) Add to this singer's favourites (the venue keeps a fixed number; the oldest is displaced).
List<SongInfo> favoritesFor(String singerName) Their favourites, resolved to library songs.
List<SongInfo> historyFor(String singerName) What they have sung recently, most recent first.

Entries whose song has since left the library are dropped rather than returned as blanks.

QueueResult

isOk(), getReason(), getPosition(), getSongsAhead(), getEntryHash(), getEngineMessage() (raw engine text, for logs — never for a patron).

isOk() is true for DUPLICATE_REQUEST: the song is queued, this call just was not the one that queued it.

getPosition() is 1-based among the unplayed entries — see the note under PlaylistEntryInfo below.

QueueReason

OK, TOO_MANY_SONGS, SOLD_OUT, UNKNOWN_SINGER, BAD_SINGER_NAME, UNKNOWN_SONG, DUPLICATE_REQUEST, NOT_YOUR_ENTRY, ENTRY_NOT_FOUND, ALREADY_PLAYED, ENGINE_BUSY, UNAVAILABLE, REFUSED.

The point of the enum is that you can tell someone why: "you already have 3 songs in" instead of "something went wrong". ENGINE_BUSY is retryable (the engine did not reach the request in time). UNAVAILABLE means the engine is starting up, headless, or in a mode with no rotation. REFUSED is the catch-all for a refusal this enum does not name yet — read getEngineMessage() — and it exists so a reason added later can never be mistaken for success.

Singer-display QR — v2.21.0

method meaning
void setQrUrlOverride(String url) Point the on-screen QR at url instead of the venue's cloud kiosk link. Null or blank clears it.
void clearQrUrlOverride() Hand the QR back to the cloud kiosk link.

For a plugin that serves patrons from the KJ's own machine: without this the QR offers a cloud address that is wrong — or, with no cloud venue configured, blank — while the thing patrons should scan is your own address.

Takes effect on the floating overlay and the hardware-accelerated singer display. One override at a time, remembered by plugin id, so one plugin cannot clear another's.

A plugin that sets it must clear it on shutdown, or the QR keeps advertising an address nothing is listening on.

Product name — v2.25.0

String productName()        // the product's name, e.g. "QUP"
String brand(String text)   // text with the product's name applied

productName() is the product's name as the KJ sees it. brand(text) rewrites a string for display with that name, so brand("Restart QUP to apply") always reads right. Use brand() on text a person reads, never on identifiers, file names, URLs or protocol strings.

Face widgets, effects audio and actions — v2.25.0

void      registerInstrument(String slot,
              Function<Map<String, Color>, JComponent> factory)
void      unregisterInstrument(String slot)
AudioSink openEffectsSink()
void      setFillerDuck(float gain)          // 1.0 = no duck, 0.0 = silent
void      setKaraokeDuck(float gain)         // v2.33.0; the same for the karaoke music
Map<String, String> listActions()            // action id -> display name
boolean   runAction(String id)               // false if the id is unknown

These are the hooks the Sound Pads plugin is built on.

registerInstrument offers a widget for a named place on a face. A face that has that slot calls your factory on the EDT when it builds, and again if it rebuilds, passing its colours under the keys "accent", "accent2", "card", "well", "text" and "muted". Return a fresh component every call. One provider per slot: the first plugin to register a slot holds it, and a second is refused and logged. A face with no provider for its slot, or whose factory throws, shows its own default. Call unregisterInstrument in shutdown().

openEffectsSink() is an AudioSink for one-shot effects on the filler side: the same transport as openAudioSink, but never the karaoke meters, taps or EQ. Signed 16-bit little-endian interleaved stereo at getSampleRate(). null if no output is available.

v2.37.1. effectsSinkRate() tells you the rate openEffectsSink() would open at, without opening a stream: more than 0 is the rate in Hz, 0 means no output is available, and less than 0 means it can't be known without opening (always the case on engines before 2.37.1). Build your sounds at that rate at init and open the sink only when there is something to play. Opening a stream just to read its rate costs a device open at every launch, and on an audio device that doesn't answer it blocks your init. The sink can still open at another rate later (the KJ changed the mains), so check getSampleRate() when you open it. Sound Pads 1.1.2 uses it and falls back to the old probe on older engines.

setFillerDuck(gain) ducks the break music: a gain on top of the KJ's filler volume and the crossfader, never replacing either. The engine smooths it, so a step is click-free. If several plugins duck at once, the deepest duck wins.

setKaraokeDuck(gain) (v2.33.0) is the same for the karaoke music: a gain on top of the crossfader and the song's level, ramped, and the deepest duck wins. At 1.0 the karaoke output is exactly as without it. It applies to every karaoke song: the ones QUP plays itself (MP3+CDG, MP3+LRC, video) and a song a playback-source plugin plays (KaraFun, MIDI), which receives it through SourcePlayer.setCrossfadeGain(). Taps on the karaoke audio hear the song before the duck.

listActions() lists the engine actions a plugin may run: the hotkey actions available in the current run mode, by id and display name. runAction(id) runs one exactly as its hotkey would, on the EDT.

Tonight and regulars — v2.25.0

long    showStartedAtMillis()                  // 0 when unknown
boolean isCloudIdentified(String singerHash)   // false when unknown
long    singerFirstSeenMillis(String singerHash) // -1 when unknown

These are facts for a per-night policy ("one per singer per night", "a regular is protected on their first song tonight"). The engine does not decide what a regular is; your plugin does, from these.

showStartedAtMillis() is when tonight's show started: the KJ's session start, the moment the session was last reset. It survives an engine restart mid-show. Key anything you count "per night" on this, not on your own start time or the calendar date: a show that runs past midnight is still one night, and a restart is not a new one.

isCloudIdentified(hash) is whether this venue's singer record is paired with a cloud singer, i.e. whether the singer has logged in to Q-Up here. It is per venue: a singer who logged in elsewhere but never here reads false.

singerFirstSeenMillis(hash) is when this venue's singer record was created. Compare it with showStartedAtMillis() to tell a singer who existed before tonight from one created during it.

"Has this singer sung tonight?" needs nothing new: queueSnapshot() includes played entries, and PlaylistEntryInfo.getSingerHash() says whose they are.

Cloud commands — v2.25.0

void registerCloudCommandHandler(String commandType, CloudCommandHandler handler) // null unregisters
void unregisterCloudCommandHandler(String commandType)
void registerCloudStateContributor(String pluginId,
         Supplier<Map<String, Object>> supplier)                              // null unregisters

// CloudCommandHandler
Map<String, Object> handle(String commandType, Map<String, Object> payload)

A venue with cloud sync polls the venue's cloud about every 1.5 seconds while anything is happening, and every 5 seconds after two quiet minutes (v2.37.0). These let a plugin own a round trip through that poll without any change on the cloud side.

registerCloudCommandHandler claims a command_type. When a queued cloud command of that type arrives, the engine hands its payload to your handler instead of answering "Unknown command", and writes whatever you return back as that command's result. success is read by the engine; every other key travels to the phone under data. The payload arrives as plain Java (Map, List, String, Number, Boolean), so you need no JSON library. Returning null is a failure with no message. Throwing is safe: it becomes {success: false, message} and a log line, and the poll goes on. It is still better to return a result that says what went wrong, because that reaches the patron. Registering a type twice replaces the first handler.

registerCloudStateContributor adds keys to what QUP tells the cloud about the venue (since v2.37.0 that goes out when it changes, and at least every 30 seconds, rather than on every poll); it is how a plugin tells the venue's cloud, and through it the patron's phone, that a feature is on. Engine keys win: contributions are merged after the engine's own fields and can never overwrite them. A throwing supplier is dropped for that poll, not fatal: each contributor runs inside its own guard, so one bad plugin costs only its own keys and the poll body still carries the live queue.

Phone cards — v2.36.1. A singer's phone card (the QR the bar scans to add credits) shows only while a feature that spends singer credits is on. QUP counts its own (charge to sing, bribes, song purchases) and Credit Top-Up. A plugin that spends singer credits as a feature adds spends_credits: true to its contribution while that feature is on. Each plugin's keys are read on their own, so another plugin's false never hides yours. Taking credits alone (takeSingerCredits) doesn't count.

Both are called on the poll thread, never the EDT, and the supplier runs on every poll: answer quickly and never block. Register when your feature is switched on (or in init()), and unregister when it is switched off and in shutdown(). A disabled plugin must leave nothing behind, and Safe Mode never loads a handler.

Signed cloud calls — v2.34.0

Map<String, Object> cloudSignedCall(String endpoint, Map<String, Object> fields)

A POST to QUP Cloud signed as the venue this QUP is linked to. It is for plugins bundled with QUP only, and only to the endpoints QUP allows (today the Cheer panel's). A downloaded plugin, or any other endpoint, gets null and a log line. It blocks on the network and returns null on the Swing thread.

Answering a cloud command later — v2.36.0

// CloudCommandHandler
Map<String, Object> DEFERRED            // return this to answer later
String CMD_ID      = "_cmd_id"          // payload key: the command's id (Integer)
String SINGER_HASH = "_singer_hash"     // payload key: the paired singer's hash, when there is one

// PluginContext
boolean answerCloudCommand(int cmdId, Map<String, Object> result)   // any thread

Some answers take longer than a poll should wait: a payment provider, or the KJ approving something. Return CloudCommandHandler.DEFERRED from your handler at once, do the slow part on your own thread, and call answerCloudCommand with the command's id when you have the answer. It goes out with the next poll, within a few seconds. success is read by the engine (true when you leave it out); every other key travels to the phone under data, exactly as a direct answer does.

The engine adds two keys to every payload a plugin handler sees. _cmd_id is the command's id. _singer_hash is there when the command names a cloud singer who is paired with a singer at this venue, so you never look up cloud ids yourself. A cloud field with either name is replaced.

Answer each id once. Until a command is answered, the venue's cloud hands it back about every 30 seconds with the same id. A deferring handler must recognise an id it already holds and return DEFERRED again, not start the work a second time.

Singer credits — v2.36.0

int          singerCredits(String singerHash)            // cents, or -1 when unknown
CreditResult addSingerCredits(String singerHash, int cents,
                              String source, String ref,  // e.g. "paypal", the payment's id
                              Map<String, Object> extra)  // fields for the credits log, or null
CreditResult takeSingerCredits(String singerHash, int cents,
                               String source, String ref, // e.g. "paypal_refund", the refund's id
                               Map<String, Object> extra)

// CreditResult
boolean ok(); boolean repeat(); int beforeCents(); int afterCents(); String error()

For QUP's own payments plugins only (today, Credit Top-Up). Two things must both be true:

  • the plugin's id is on QUP's own list of payments plugins, which is built into QUP; and
  • the plugin is QUP's own copy: it came with the installer, or the Plugin Browser installed it from QUP's catalogue (the download matched the catalogue's checksum) and its file hasn't changed since. QUP checks this once, when it loads the plugin.

Any other plugin gets ok() == false with error() not_allowed, and the log says why.

Plugins run inside QUP and aren't sandboxed. This rule stops the wrong plugin, or one QUP hasn't vetted, from using the money calls by mistake or by design. It doesn't stop harmful code that's already running inside QUP, or someone who can change the files in QUP's data folder.

addSingerCredits adds to a singer's credit balance once per (source, ref). The first call adds the credits. Every later call with the same pair adds nothing and answers ok() with repeat() true and the first call's figures, so a plugin that retries after a crash or a timeout never pays a singer twice. The same ref for a different singer or amount is refused (ref_reused). Refs are per plugin.

The credits and the record of the ref go in together or not at all, and nothing that changes the same balance at the same moment (a song, the bar, the KJ's singer editor) is lost.

cents is 1 to 50000 ($500), and the balance after may not pass $500: the same limits as the bar. Anything tighter, such as "no more than the largest pack I sell", is the plugin's to check before it calls. source is letters, digits, . _ - (at most 32); ref is 1 to 128 printable characters with no spaces. Each add is a line in the venue's credits log, with path set to source and your plugin's id, the ref and extra. Never put a secret in extra.

takeSingerCredits takes credits back, only when the KJ asks (a refund's "Remove credit" button), never on a plugin's own initiative. It takes up to cents and never goes below zero: a singer with $2.50 left, asked for $10, goes to $0. It is once per (source, ref) like an add; give it a source of its own (an add and a take never share a ref under one source).

When ok() is false, nothing moved and error() is one of not_allowed, bad_amount, bad_ref, no_singer, ambiguous_singer, over_cap, ref_reused, not_ready or failed.

ambiguous_singer (CreditResult.AMBIGUOUS_SINGER, v2.36.1): two or more singer accounts share that singer hash (accounts made from the phone, the cloud or a plugin get a hash from the karaoke name alone, so two accounts with one name share it). QUP can't tell which account is meant, so it moves nothing and logs it. Tell the KJ to sort the accounts out in the Singer Database; retrying won't help.

Secrets — v2.36.0

PluginSecrets secrets()                  // never null

// PluginSecrets
String  unavailableReason()              // null when secrets can be kept here
boolean available()
String  get(String key)                  // null when none
boolean put(String key, String value)    // null or "" clears; true when stored and read back
boolean clear(String key)

Keep an API secret or a password here, never in a settings file. It goes to the operating system's own store: Windows keeps it for this Windows account (DPAPI), macOS in the login Keychain, Linux in the desktop keyring (Secret Service, which needs secret-tool from libsecret-tools). Each plugin has its own store and never sees another plugin's.

When available() is false, nothing is kept: show unavailableReason() in your settings, in words the KJ can act on. A data folder copied to another computer or Windows account arrives without its secrets, by design, and the KJ types them again.

Keys are letters, digits and . _ -, at most 64 characters, and a plugin keeps about 2,000 characters in all. On macOS and Linux every call runs the system's store tool and may wait for it, up to 20 seconds when a locked keychain asks the user. Call it off the EDT: on the EDT, get returns null and put and clear return false. Never log a secret. The engine keeps secrets out of logs, problem reports, the cloud and backups.

Library lists — v2.26.0

void registerLibraryList(LibraryList list)   // same title replaces it

// LibraryList
String     title()                     // the row's name ("Internet Radio")
String     parent()                    // default PARENT_BREAK_MUSIC ("break")
String     titleColumn()               // default "Name"
List<String> columns()                 // headings for Item.cells, after the title column
String     searchHint()                // default "Search"
int        total()                     // shown as "N of TOTAL"; 0 when unknown
List<Item> search(String text, int limit)
void       added(Item item)            // default no-op; told after the host acted on it

// LibraryList.Item
Item(String id, String title, String streamUrl, List<String> cells)

A plugin can contribute a searchable list to a face's library. Today that face is Host mode: it shows the list as a row under parent() (Break music for a list of stations), searched by the library's own search box and drawn in Host's look. The plugin owns the data and the search; the host owns the look and what an item does. An item with a streamUrl gets "+ Break", and a double-click or "+ Break" sends the stream to the filler (break music) player, never the karaoke side. The Internet Radio plugin's stations are the first list.

search(text, limit) returns the matching items, best first, at most limit; an empty text is your own default order. It is called off the EDT, possibly once per pause in typing: keep it a local lookup, never a network call.

Faces without a library of this kind (the classic Media Library, DJ, the player modes) ignore lists, so keep a registerMediaTab media tab for those. Host does not also offer a media tab with the same title as a window.

An engine before v2.26.0 has no registerLibraryList: a plugin that also runs there calls it inside try { ... } catch (LinkageError e).


Specialized plugin interfaces

Each extends QUPPlugin, so implement those eight members too, and register under the same service file.

SongStorePlugin — sell and deliver songs

int                fetchCatalog()          // entry count, or -1 on error
boolean            onPurchaseRequested(CatalogEntry entry, String singerHash)
int                getDownloadProgress()   // 0-100, or -1 when idle
List<CatalogEntry> getCachedCatalog()
boolean            requiresKJApproval()

Both fetchCatalog() and onPurchaseRequested() run on background threads, so network I/O is fine. singerHash is null when the KJ initiated the purchase.

Two models are supported: URL-redirect, where the entry carries a purchaseUrl, you open it in a browser and watch a folder for the file; and server-mediated, where you talk to a vendor API, download, importSong(), then optionally queueSong().

Patron purchases — v2.13.0. When the KJ turns on Config → Misc → Song Purchases, patrons can buy your catalog's songs at the kiosk, and onPurchaseRequested() is called with a non-null singerHash. Nobody is at the KJ's screen then, so: show no dialogs; pay with details the KJ has already saved, or return false; and return only once the song is imported, with SongImport.setExternalId(entry.getSongId()). QUP looks the song up by that id, takes the patron's credits only after it is in the library, and has the kiosk queue it — do not call queueSong() yourself. Report progress through getDownloadProgress() while you work; the kiosk shows it.

Use showNotification() for the outcome of a purchase (done, or why it failed), not for download progress: each call is a toast that a screen reader also says.

If you only import local files, implement QUPPlugin directly instead.

PlaybackListenerPlugin — react to what is playing

void onSongStarted(PlaybackEvent event)
void onSongEnded()
default void onNextSongPrefetch(PlaybackEvent event) {}
default void onQueuePrefetch(List<PlaybackEvent> upcoming) {}
default File getVideoForSong(String songHash) { return null; }
default boolean isVideoProvider() { return false; }
default boolean startVideoWithAudio() { return false; }   // v2.6.0
default float   getVideoDimLevel()    { return 0.5f;  }   // v2.6.0

Callbacks run on background threads — except getVideoForSong(), which runs on the playback thread and must return immediately. If the video is not cached, return null and fetch it in the background from onSongStarted or onNextSongPrefetch.

onQueuePrefetch() may be called repeatedly as the queue changes, so dedupe and skip what you have already cached.

startVideoWithAudio() holds the background on its first frame until karaoke audio is actually heard, then starts it and offsets the clock by the measured delay. Karaoke tracks often open with a second or more of silence, and because the background is slaved to the song clock — which starts at zero regardless — the picture otherwise runs ahead of the music for the whole song. getVideoDimLevel() is read live while compositing rather than latched at song start, so a brightness control responds while the KJ drags it. Both are ignored unless isVideoProvider() is also true.

Filler entries also fire onSongStarted, carrying the placeholder singer name "Filler". If your plugin acts on the singer — announcing, promoting, paging them — check event.isFiller() and skip those.

FillerPlugin — drive the background music

void onFillerPlaylistLow(int remainingSongs)
void onFillerSongEnded(SongInfo song)          // song may be null for streams
default int     getMinQueueDepth()     { return 3; }
default boolean isActiveFillerSource() { return true; }

Respond to onFillerPlaylistLow() by calling addToFillerPlaylist(). Only one filler plugin is active at a time; if several are installed the KJ picks.

PlaybackSourcePlugin — add a new playable format — v2.1.4

Set<String>  supportedExtensions()                  // lower-case, dot-prefixed
boolean      canPlay(File file)
SourcePlayer open(File file, PlaybackParams params) // null declines

// v2.17.0: songs from a SongSource, carried as scheme:id instead of a file
default Set<String>  supportedSchemes()                      // e.g. {"karafun"}; empty = files only
default boolean      canPlay(URI song)                       // e.g. still in the catalog?
default SourcePlayer open(URI song, PlaybackParams params)   // null declines
default String       unavailableReason(URI song)             // v2.33.0; null = it can be queued

This is the seam that makes a new format a plugin instead of a core rewrite — MIDI karaoke is built entirely on it. When the KJ plays a file the engine cannot decode natively, the first source plugin that claims it supplies a SourcePlayer the engine drives exactly like a CDG or MP4 song.

Sniff the file header in canPlay() rather than trusting the extension. open() should parse and prepare but not start playing.

v2.17.0: a plugin with a song source (see Song sources above) lists its scheme in supportedSchemes() and gets canPlay(URI) / open(URI, …) for those songs — the same contract as the file versions: prepare, do not start. canPlay(URI) is only asked for a scheme you listed.

v2.33.0: unavailableReason(URI) is asked when a KJ or a phone queues one of your scheme's songs. Return a sentence for the KJ to refuse it (a phone's singer is told the song isn't available at this venue right now), or null to allow it. Answer at once from what you already know: it may be asked on the Swing thread, and a phone's request waits for it. If you can't tell, answer null; playing is the final check.

VisualizationPlugin — draw behind the lyrics — v2.6.0

default void onVisualizationStart(int width, int height) {}
BufferedImage renderFrame(int width, int height, double elapsedSeconds);
default void onVisualizationStop() {}
default boolean hasContentFor(String songHash) { return true; }

Whatever is drawn under the lyrics on the projector: a music video, an audio-reactive visualizer, a slideshow, a solid colour — anything that renders into a BufferedImage. Music Video Background is itself one of these.

Exactly one is active at a time, chosen by the KJ in Config → Plugins. Unlike FillerPlugin, plugins do not self-report being active: the engine owns the choice and persists it, so two installed visualizations can never fight over the one projector.

renderFrame() runs on the compositing thread at roughly 30fps. Return null to keep the previous frame, so a slow generator degrades to a lower frame rate rather than flickering. It must return promptly — that thread also composites the lyrics, so a slow frame stalls the whole projector image. An exception is caught and the visualization is dropped for the rest of the song rather than being re-entered every frame.

A negative elapsedSeconds means hold: the engine wants the background parked rather than advancing, used to sit out a track's leading silence. A generated visualization can treat it as zero; anything playing pre-recorded material should stay on its first frame until it goes positive.

To react to audio, register an AudioTap via setKaraokeAudioTap() in init() — a visualizer needs the song the room is hearing, not the filler bed underneath it. Buffer in the tap, do the analysis in renderFrame(); never run an FFT inside the tap itself.

Readability comes first. The KJ's brightness control is applied after renderFrame() returns, but a visualization that stays busy and high-contrast where the words sit will be unreadable no matter how far it is dimmed.

VisualizationPlugin — direct GL rendering — v2.8.0

default boolean supportsDirectGl() { return false; }
default boolean glAdopt(int width, int height) { return false; }
default void    glRenderFrame(int width, int height, double elapsedSeconds) {}
default void    glRelease() {}
default void    publishHostFrame(BufferedImage frame) {}

The methods above (onVisualizationStart/renderFrame/onVisualizationStop) are the readback contract: the plugin renders somewhere of its own and hands back a BufferedImage, which the compositor draws with Java2D. That costs a full glReadPixels every frame, forever, for a visualization that was already OpenGL to begin with.

These methods let a host that owns a GL context invite the plugin to draw straight into it instead. The host makes its context current on its own render thread and calls glRenderFrame there; the plugin renders into whatever framebuffer is bound and does not create a context of its own. All five are defaulted, so every existing plugin compiles and loads unchanged — a host that gets false from supportsDirectGl() simply falls back to renderFrame().

  • supportsDirectGl() — answering true is a promise about threading as much as about drawing: the plugin must be able to run its whole render on the host's thread, and must not create, destroy, or make-current any context of its own while the host's is adopted.
  • glAdopt(width, height) — called once per context generation (startup, and again after a context loss and rebuild), on the thread that owns the context for its lifetime and is the only thread that will ever call the other gl* methods. Return true if ready to render into this context.
  • glRenderFrame(width, height, elapsedSeconds) — render one frame into the currently bound framebuffer, on the thread that called glAdopt. GL state may be left dirty; the host re-establishes everything it depends on each frame. Must not swap buffers or destroy the context.
  • glRelease() — release GL resources, on the adopting thread, while that context is still current, before the host tears its own context down.
  • publishHostFrame(frame) — a small copy of what the host just drew, so renderFrame() keeps answering for any other consumer (a config pane preview, for instance) while the host owns the context — without this they'd see nothing, or start a second renderer beside the host's.

VisualizationPresets — let the KJ pick a look — v2.7.0

List<String> getPresetNames();
int  getCurrentPresetIndex();
void selectPreset(int index);
void nextPreset();
void randomPreset();
boolean isCycling();      void setCycling(boolean cycling);
int  getCycleSeconds();   void setCycleSeconds(int seconds);
boolean isShuffle();      void setShuffle(boolean shuffle);
default void rescanPresets() {}

Optional companion to VisualizationPlugin, for visualizations that have named looks. Implement it and QUP renders preset controls beside the live preview under Media Library → Plugins → Backgrounds: a searchable list, Next and Random, a cycle toggle with interval, and shuffle. A visualization with one fixed look simply does not implement it and no controls appear.

Every method is called on the Swing EDT, and selection is a request, not a switch. If your visualization holds a GPU context, that context belongs to one thread for its lifetime — loading a preset from a button handler is undefined behaviour that typically takes the whole JVM down rather than throwing. Record what was asked for and act on it from whatever thread owns your rendering. The bundled MilkDrop plugin stores a pending index in a volatile field and picks it up on its next render pass.

Two behaviours worth matching, because they are the difference between the control working and appearing not to: a manual pick should restart the cycle interval, so a deliberate choice is not replaced a second later by a change that was already due; and cycling off should pin the current preset indefinitely.

Persist the current preset by name, not by index. Preset folders gain and lose files between runs, and an index saved yesterday points somewhere else today.

VisualizationPresetPlaylists — named subsets of those presets — v2.7.0

List<String> getPlaylistNames();
boolean isPlaylistEnabled(String playlist);
void    setPlaylistEnabled(String playlist, boolean enabled);
String  createPlaylist(String playlist);      // returns the stored name, or null
void    deletePlaylist(String playlist);
void    addToPlaylist(String playlist, int presetIndex);
void    removeFromPlaylist(String playlist, int presetIndex);
List<String> getPlaylistContents(String playlist);
int     getCyclePoolSize();

A real MilkDrop pack is around ten thousand presets. Left alone the shuffle wanders all of them, and a KJ who has found the forty that suit a Friday night has no way to say so. A playlist is a named list of presets; ticking one or more restricts cycling to their union, and with none ticked everything is in play.

Also EDT-only, and the same threading warning applies with more force: your render thread is reading the pool while these calls mutate it. Publish the pool as an immutable snapshot — build a new array and swap it in — rather than letting the render thread walk a collection the EDT is editing.

getPlaylistContents() returns names, not indices, for the same reason preset selection is persisted by name: an index list is stale the moment a rescan lands between the call and its use.

Two behaviours to match: an empty ticked playlist should fall back to the whole set rather than leaving the screen with nothing to cycle through, and a pool change should affect the next switch only — deleting the playlist that put the current preset on screen must not yank the picture out from under the room.

Every mutating method is expected to persist immediately. There is no commit or close hook: the KJ ticking a playlist mid-set is the decision.

CdgLyricPlugin — redraw CD+G lyrics — v2.11.0 (experimental)

// PluginContext
void registerCdgLyricPlugin(CdgLyricPlugin plugin);

// CdgLyricPlugin
Surface open(Song song);

interface Song {
    byte[] cdgBytes();
    String audioPath();
    DoubleSupplier positionMs();
}

interface Surface {
    void paint(Graphics2D g, int width, int height);
    void close();
}

Experimental. This interface exists for the CDG Enhancement plugin, which ships switched off and is not yet production quality. It may change in a later release without the usual notice; don't build anything you depend on for a show on it yet.

A .cdg file is a timed drawing program, not a video. A lyric plugin is handed the disc's raw packets and redraws the words at the projector's resolution instead of stretching the disc's 300×216 bitmap. The engine keeps the transport: it still opens the audio, drives the CDG clock and owns seek and pause. The plugin only takes the paint slot.

Register from init(). Only one lyric plugin is active at a time, and the last one to register wins.

  • open(song) — called once per song, off the EDT, before playback starts. Returning null is a normal answer: it means "this disc is not for me" (a scrolling disc, an unreadable one, or a plugin that is switched off), and that song plays on the standard renderer.
  • positionMs() is already corrected for the engine's CDG offset. Read it rather than keeping a clock of your own, or your text will drift from the audio by exactly the offset the KJ has dialled in.
  • Surface.paint() runs on the compositing thread at the projector's frame rate, and on preview repaints. Paint only the text over a transparent background, because the engine owns what is behind it (a music video, a visualizer or black). It must not block.
  • Surface.close() — release cached artwork when the song ends or the KJ moves on.

LyricSourcePlugin — read a lyrics-only document — v2.25.0

Set<String> sidecarExtensions()                       // lower-case, no dot: {"lrc"}
boolean     canRead(String name, byte[] head)         // sniff: name + first bytes (at most 4 KB)
LyricModel  parse(byte[] data, String name, Charset override)
                throws LyricParseException            // never returns null
default int     precedence()          { return 100; } // lower first; CDG graphics are 0
default boolean preferOverCdg()       { return false; }
default boolean preferOverEmbedded()  { return false; }

A lyric source reads a lyrics-only document, such as an LRC sidecar, into a LyricModel. The audio stays whatever it is; the engine pairs the two, keeps the clock, and draws the model with its shared lyric renderer on every face. LRC support ships as exactly this kind of plugin.

There is no File anywhere in this interface. A lyric source parses bytes, so the same plugin reads a sidecar on disk and an in-memory document that must never touch disk. The engine finds the sidecar (<song base name>.<ext> beside the audio, ignoring case), reads it and hands you the bytes. override is a charset the KJ forced for this song, or null to detect your own.

preferOverCdg() reflects the KJ's "prefer lyrics over CDG graphics" setting: true makes a song that has both a .cdg and your sidecar show the lyrics. preferOverEmbedded() is the same choice for audio that carries lyrics of its own (a MIDI/KAR file's Soft Karaoke events); with it off, your sidecar is still used when the song has no lyrics of its own.

Throw LyricParseException when nothing usable could be read: wrong format, truncated beyond use, or no timed lines. The engine logs it and plays the song with its title card; the library row is not marked bad. Implement LyricSourcePlugin instead of plain QUPPlugin and register it through the same META-INF/services/com.qupkaraoke.plugin.QUPPlugin file.

GlobalHotkeyProvider — a backend for global keys — v2.12.0

For a plugin that supplies global hotkeys where the built-in backend cannot (another platform, another mechanism). The engine owns everything else — the actions, the KJ's bindings and keymap file, the Hotkeys page, mode gating. A provider is handed a key and a number, asks the operating system for the key, and reports the number back when it is pressed. That is the whole contract, which is also what lets one be faked in a test with no native code.

String name()                              // shown to the KJ, e.g. "Windows (RegisterHotKey)"
String unavailableReason()                 // why it can't work here, in words for the KJ; null if it can
void   setListener(IntConsumer onFired)    // set once, before start()
void   start()                             // once, before the first register()
Result register(int id, KeyStroke key)     // blocks until the OS answers; never throws
void   unregister(int id)                  // unknown ids ignored; never throws
void   shutdown()                          // release every key, stop every thread; idempotent

Result is sealed: Registered, TakenByAnotherApp, NotSupportedOnThisPlatform, or Failed(code, what). A registration failing is normal, not exceptional — another program already holding a key is the common case, and the Hotkeys page shows it to the KJ. Only the key code and modifiers of the KeyStroke matter. Registering an id that is already registered replaces it.

Only one provider is live. Registering yours replaces the current one: the engine unregisters every key from the outgoing provider and shuts it down before starting yours, then registers the KJ's global bindings against it — two providers never hold OS registrations at once. The engine calls you from one thread at a time, usually the EDT; your listener may call back on any thread.

AudioDspPlugin — process audio in the path

void onAudioReady()
void onAudioStopping()

For plugins that pull captured input, run DSP, and write the result as a summed input on the mains bus — the shipped mic reverb/delay strip is the reference implementation.

An audio-DSP plugin is an async writer. Never do per-sample DSP inside the real-time callback. Release your input taps and bus inputs in onAudioStopping().


Audio interfaces

AudioSink — emit audio — v2.1.4

Obtained from openAudioSink(). On ASIO it is a summed input on the ReaRoute mains bus alongside karaoke and filler; otherwise a normal output device.

void   write(byte[] pcm, int off, int len)   // blocks with the output
void   setVolume(float volume)               // 0..1
double getSampleRate()
int    getPlaybackLatencyFrames()            // 0 if unknown
void   flush()
void   close()

Write signed 16-bit little-endian, interleaved stereo at getSampleRate() — set your render format to that so nothing has to resample. Use getPlaybackLatencyFrames() to slave a lyric cursor exactly. Close the sink when your source stops.

AudioTap — observe audio — v2.2.1

void onAudio(byte[] pcm, int offset, int length, AudioFormat format)

The counterpart to AudioSink. The tap sits at the very end of the filler player's chain — post-EQ, post-crossfade, immediately before the buffer goes to the device — so it hears exactly what the room hears, including filler ducking as a karaoke song starts. It is the same code point on both output paths, so it behaves identically with or without ASIO.

Read this before implementing one. onAudio is called on the player's audio thread, inline in the decode/write loop. It must return promptly and must not block, allocate heavily, take contended locks, or touch Swing. Copy what you need into a bounded structure you drain elsewhere, and drop rather than wait when that structure is full — a slow tap will backpressure and glitch the venue's audio. A tap that throws repeatedly may be dropped.

The pcm array is reused on the next iteration, so copy anything you intend to keep. Sample rate, channel count and sample size vary per track: read them from format rather than assuming 44.1 kHz stereo.

Each plugin has at most one filler tap; setting a new one replaces the old.

SourcePlayer — play a format you added — v2.1.4

Returned from PlaybackSourcePlugin.open(). Your source owns the master clock; the engine slaves lyrics and graphics to it.

void    play()          void   stop()      void pause()   void resume()
boolean isPlaying()     boolean isPaused()
void    seekTo(double seconds)
double  getCurrentTimeMs()          // note: milliseconds
double  getSongLengthSeconds()
void    setVolume(int percent)      // 0..100
default void setCrossfadeGain(float gain) {}   // 0..1, on top of setVolume; v2.33.0: times the karaoke duck
void    setTranspose(int semitones)
void    setTempoRatio(double ratio)            // 1.0 = original
void    setEndListener(Runnable onEnd)
default void setErrorListener(Consumer<String> onError) {}   // v2.17.0
default boolean usesOwnDisplay() { return false; }          // v2.17.0
default boolean keepsOwnShape() { return false; }           // v2.37.1
default void    setBackgroundUnder(boolean under) {}        // v2.37.1
default long    pictureSerial() { return -1; }              // v2.37.1
boolean hasVisual()
void    paint(Graphics2D g, int width, int height)
void    close()

You must fire the end listener when the song finishes — it is how the engine advances the playlist. A source that never calls it stalls the rotation.

paint() is called on both the projector and preview surfaces at their own pixel sizes; read your own clock for the current position. seekTo() should replay prior controller state so timbres stay correct.

v2.17.0. setErrorListener() is for a song that turns out not to be playable after open() returned — a remote player refused it, say. Call it with a short sentence for the KJ; QUP marks the playlist entry failed, as it does for a local file that will not play, and moves on. A source that reports an error must not also fire the end listener for that song; sources that never call it keep reporting failures as an end. usesOwnDisplay() returns true if your player shows its picture in a window of its own on the projector (KaraFun's Dual-Screen window): QUP's projector window is hidden while your song plays and comes back, without taking focus, when it closes. hasVisual() still decides what the operator's preview shows.

v2.33.0. setCrossfadeGain() is now the crossfade times the karaoke duck (setKaraokeDuck(), for example while a sound pad plays). It is sent again whenever either one moves, so it can change in a step: ramp it if a step would click. With no duck it is the crossfade, as before.

v2.37.1. Three hints that make a captured picture cheap to show. All are optional: the defaults behave exactly as before. - keepsOwnShape(): return true if your picture has a shape of its own that must not be stretched (a captured 16:9 web page, say). The engine then calls paint() at the display's own shape instead of CD+G's 25:18, and you letterbox or pillarbox your picture inside it. At the display's size the engine draws your frame 1:1, without a scaled draw. - setBackgroundUnder(boolean under): the engine tells you, from any thread, whether a background (a music video or a visualization) is drawn under your picture. With nothing under it you may paint your picture opaque, which is cheaper than working out transparency. A plugin that relies on it should set minEngineApi to 2.37.1: an older engine never calls it. - pictureSerial(): a number that changes whenever your picture changes (a new captured frame, say), or -1 if you can't tell. While it stays the same the engine may skip painting your picture again at the same size and keep showing the last one.

v2.33.0. To give QUP a reason it can act on, put SourceFailure.tag(code) anywhere in the text you hand the error listener, for example SourceFailure.tag("karafun_refused") + "KaraFun refused it: ...". QUP strips the tag before the KJ sees the text. For karafun_refused it tells the singer their song couldn't be played and keeps the entry failed across restarts. Codes are lower-case letters, digits and _, up to 32 characters.


Data types

Type Notes
SongInfo Immutable song metadata. Note getCDID() capitalisation. getFullPath() joins path + filename; filename already includes the extension.
SongImport Describes a song to import. You download the file; QUP hashes and inserts it. pluginId is set for you.
CatalogEntry A purchasable song. Maps to the OpenKJ apigetsongs_v2 shape. purchaseUrl is null for server-mediated stores. pluginId is set for you.
PlaybackEvent Song + singer info for playback callbacks. Check isFiller().
PlaybackParams Public final fields pitchSemitones, tempoPercent. PlaybackParams.defaults() is (0, 0).
FileFilterSpec new FileFilterSpec("Audio Files (*.mp3)", "mp3"). Accessors are description() and extensions().
LibraryTarget KARAOKE, FILLER, BOTH.
PlaylistEntryInfo Immutable snapshot of a karaoke playlist row, passed to PlaylistMenuProvider. See Playlist menu above. — v2.16.0
SingerNames normalize(String), sameSinger(String, String).
SourceSong One song in a SongSource: sourceId (its identity within the scheme), title, artist, year, length, duo, explicit, styles, languages, dateAdded, plus extra: values only your plugin reads, stored and handed back (except EXTRA_BADGE, which QUP shows). 0 / null mean unknown. — v2.17.0
SongSource.SyncResult What one sync() changed: added, updated, removed, restored, total, millis. — v2.17.0
CloudSourceList A song list QUP Cloud keeps for a song source: unchanged, listHash, songs ({songHash, sourceId, artist, title}). See Song sources. — v2.33.0
SourceFailure tag(code), code(text), text(text): a machine-readable reason inside a SourcePlayer error. — v2.33.0
LyricModel A timed lyric document: Lines of Syls (syllables) stamped in song milliseconds and grouped into pages, with optional Part (MALE/FEMALE/DUET), translation and per-syllable colour. Time queries currentPage(tMs), linesOnPage(page). Pure data: no MIDI, no Swing, no files. — v2.25.0
LyricParseException Thrown by LyricSourcePlugin.parse() when a document is unusable. — v2.25.0
CreditResult What addSingerCredits() or takeSingerCredits() did: ok, repeat, beforeCents, afterCents, error; AMBIGUOUS_SINGER (v2.36.1). See Singer credits. — v2.36.0
PluginSecrets A plugin's own secrets in the operating system's store. See Secrets. — v2.36.0
SingersMerged Two singer accounts the KJ merged: mergeId, the kept account (ID, hash after and before, name, cloud id) and the removed one (ID, hash, name, cloud id). See Singer merges. — v2.37.0
SkinnedDialog Undecorated dialog with a skin-painted title bar. Add to getContentPanel(), show with showCentered(w, h).

SingerNames is deliberately not fuzzy

It folds Unicode to NFKC, reduces every Unicode space separator — including U+00A0, which \s does not match and phone keyboards insert freely — to plain blanks, collapses runs, trims and lower-cases.

It never computes edit distance, never drops punctuation and never matches a prefix. "Bob" and "Bobby" stay different people. Route your own singer matching through it so your plugin and the rotation always agree.


PlaylistEntryInfo additions — v2.21.0

method meaning
getUnplayedPosition() 1-based position among the unplayed entries, or -1 (always -1 for a played entry).
getSongsAhead() How many unplayed entries are ahead of this one, or -1.
getEntryHash() The entry's hash — the handle for a later remove, swap or change.

getUnplayedPosition() is the number to show a person, not getQueuePosition(). Played rows are never removed from the playlist, so the raw position climbs all night: the fourth song of the evening reads as "#4" by that count even when it is the very next one up. getQueuePosition() keeps its existing meaning (1-based index as the KJ sees it) and is unchanged.

PlaylistEntryInfo additions — v2.25.0

method meaning
getSingerHash() The singer's canonical hash, or "" for a filler entry or when not supplied.

The hash is the identity the rotation keys on: the same one queueSong and PlaybackEvent.getSingerHash() carry. Two entries with the same hash are the same singer even if a display name was edited between them, which is what "has this singer sung tonight?" needs. A new nine-argument constructor carries it; the eight-argument one still works and leaves it "".


Automation — v2.0.57

getAutomation() returns a QA surface for driving and observing the engine with nobody watching or listening.

File         captureScreen(File pngOut)
File         captureWindow(String window, File pngOut)   // "main", "cdg", "config"
List<String> configPaneNames()
void         showConfigPane(String name)
void         captureConfigPanes(File dir)
String       diagnostics()                               // JSON
void         playTestTone(double freqHz, double seconds)
void         playTestSweep(double startHz, double endHz, double seconds)
void         playTestNoise(double seconds)
void         stopTestSignal()

Test signals route through the real karaoke DSP chain — SoundTouch pitch/tempo and EQ — so a loopback recording can be FFT-analysed to verify key change, EQ and "is there sound at all" objectively.

The whole surface is best-effort: methods return null or do nothing rather than throwing when a target is unavailable, such as in a headless run.


Threading, in one table

Where Thread Rule
PluginContext, all methods any Safe from anywhere.
Automation, all methods any GUI actions marshal to the EDT.
QUPPlugin.onConfigPanelClosed() EDT Cheap, non-blocking.
PlaybackListenerPlugin callbacks background Network I/O fine.
PlaybackListenerPlugin.getVideoForSong() playback Return immediately.
FillerPlugin callbacks background Network I/O fine.
SongStorePlugin catalog/purchase background Network I/O fine.
AudioTap.onAudio() audio No blocking, no allocation, no Swing.
AudioDspPlugin DSP your own Never inside the RT callback.
PluginContext.rescanFillerTags() caller's Call it off the EDT; it reads files.
VisualizationPlugin.renderFrame() compositing Return promptly; it also draws the lyrics.
CloudCommandHandler.handle() cloud poll Answer quickly; dispatch to the EDT yourself for UI.
registerCloudStateContributor supplier cloud poll, ~1.5 s Cheap, never blocks.
registerInstrument factory EDT Build and return a fresh component.
LyricSourcePlugin.canRead() / parse() loader Never the EDT or the audio thread.

DJ mode (v2.9.0)

DJ mode's two decks are addressable from a plugin. Every call is a no-op that returns false, null or -1 when DJ mode is not running, so a plugin can degrade rather than fail — check hasDjSurface() (DJ mode is running and its decks exist) first if you want to hide UI.

Decks are named by DeckId.A / DeckId.B. That enum is deliberately part of the plugin package rather than an engine type: a plugin compiles against com.qupkaraoke.plugin and nothing else, and two named values beat bare integers nobody validates.

Transport

Method Does
djPlay(DeckId) / djPause(DeckId) / djStop(DeckId) Start, pause, stop a deck.
djIsPlaying(DeckId) true if that deck is playing.
djPositionSeconds(DeckId) Position in seconds, or -1.
djTempoRatio(DeckId) Live tempo ratio; 1.0 is as recorded.
djBpm(DeckId) Grid BPM scaled by tempo, or -1 with no beatgrid.
djBeatJump(DeckId, int beats) Displace by a signed number of beats.

Cues and loops

Method Does
djSetCue(DeckId, int slot) Store the deck's position at slot 1..8.
djCue(DeckId, int slot, boolean quantized) Jump to a stored cue. false if the slot is unset.
djLoop(DeckId, double beats, boolean quantized) Engage a beat loop — a power of two from 1/16 to 32.
djLoopExit(DeckId) Release it.
djLoopBeats(DeckId) Running loop length in beats, or -1.

Loops engage on the call. quantized selects alignment, not delay: on, the loop anchors to the grid cell the playhead is already in; off, it engages raw under the head.

Turntable moves

djBrake(DeckId, double factor) slows to a stop like a turntable losing power; pass 1.0 for the default ramp. djSpinback(DeckId) spins the record backwards to a stop, and djSoftStart(DeckId) winds up to speed from a standstill.

Mixer and effects

Method Does
djCrossfader(float pos) 0 hard A, 1 hard B. Transport-class — this yields Auto DJ.
djCrossfader() Its position, or -1.
djFxType(DeckId, String slot, String type) slot is "fx1", "fx2" or "send". type is an effect name, or "--" to clear.
djFx(DeckId, String slot, double position) -1..+1 for a filter (0 is off), 0..1 for the others.

Effect names come from the engine's own list — Filter, Echo, Reverb, Roll, Gater, Flanger, Phaser as of this release. "send" is post-fader, which is what lets an echo or reverb tail keep ringing after the channel is cut.

Auto DJ

djAutoArm(boolean) arms or disarms it. djAutoState() returns OFF / ARMED / TRANSITIONING. djLastTransitionRecipe() returns the name of the transition that ran last — bass-swap-blend, filter-loop-build, echo-out, cut-on-the-one, filter-fade or plain-crossfade — or null.

A note on yielding

Auto DJ hands control to a human who touches something. Calls above are classified the same way the pane's own controls are: moving the crossfader or a deck's transport yields Auto DJ, while loading an effect or firing a loop does not, on the reasoning that garnish over a running mix is not a request to take the mix over.


Version history

Version Added
v2.37.3 PluginContext.getWindowLayouts() + WindowLayouts (the KJ's saved layouts: list, switch, save with the KJ's Replace? question, a change listener; the workspace windows: list, bounds, dock, show/hide, to front), and the WINDOW_LAYOUTS feature name.
v2.37.1 effectsSinkRate(); SourcePlayer.keepsOwnShape(), setBackgroundUnder(), pictureSerial()
v2.37.0 singer merges: QUPPlugin.onSingersMerged(), onSingersMergeUndone(), SingersMerged; the cloud poll slows to every 5 seconds when the venue is quiet (cloud state contributions still go out as soon as they change)
v2.36.1 CreditResult.AMBIGUOUS_SINGER (ambiguous_singer): two or more accounts share the singer hash, nothing moved; cloud state spends_credits: true turns phone cards on
v2.36.0 answering cloud commands later: CloudCommandHandler.DEFERRED, CMD_ID, SINGER_HASH, answerCloudCommand(); singer credits for QUP's own payments plugins: singerCredits(), addSingerCredits(), takeSingerCredits(), CreditResult; secrets: secrets(), PluginSecrets
v2.35.1 registerAboutLog() (the About box's OBS tab)
v2.34.0 registerMediaTab(..., poppable) (Pop out); cloudSignedCall() for bundled plugins
v2.33.0 setKaraokeDuck(); song sources: SongSource.setUnavailable(), SourceSong.EXTRA_BADGE, cloudSourceList(), cloudSourceReport(), CloudSourceList, PlaybackSourcePlugin.unavailableReason(), SourceFailure; setCrossfadeGain() carries the karaoke duck
v2.26.0 library lists: registerLibraryList(), LibraryList, LibraryList.Item; hasFeature("FILLER_ONLY_URLS")
v2.25.0 productName(), brand(String); face widgets and effects: registerInstrument(), unregisterInstrument(), openEffectsSink(), setFillerDuck(), listActions(), runAction(); tonight and regulars: showStartedAtMillis(), isCloudIdentified(), singerFirstSeenMillis(); cloud: registerCloudCommandHandler(), unregisterCloudCommandHandler(), registerCloudStateContributor(), CloudCommandHandler; lyrics: LyricSourcePlugin, LyricModel, LyricParseException; PlaylistEntryInfo.getSingerHash() (and a nine-argument constructor)
v2.22.0 enqueueForSinger overload carrying pitch and tempo
v2.21.0 patron queue: searchLibrary, songByHash, canQueue, songQueuesLeft, queueAcceptingRequests, enqueueForSinger, queueSnapshot, queuedFor, queueLength, createSinger, removeQueuedForSinger, swapQueuedForSinger, changeQueuedSongForSinger, addFavoriteForSinger, favoritesFor, historyFor; types QueueResult, QueueReason, QueueEligibility; PlaylistEntryInfo.getUnplayedPosition/getSongsAhead/getEntryHash; singer-display QR: setQrUrlOverride, clearQrUrlOverride
v2.20.0 runMode(), hasFeature(String); four run modes (Media Player and Simple Player added)
v2.17.0 Song sources: openSongSource(), SongSource, SourceSong; PlaybackSourcePlugin.supportedSchemes(), canPlay(URI), open(URI, PlaybackParams); SourcePlayer.setErrorListener(), SourcePlayer.usesOwnDisplay()
v2.16.0 registerPlaylistMenu(), PlaylistMenuProvider, PlaylistEntryInfo; library health: isSongMarkedBad(), setSongMarkedBad(), queryMarkedBadSongs(), isPlaybackBusy(), getCurrentKaraokeSongHash(), holdSongFile()
v2.13.0 PluginContext.getComponents(), PluginComponents; SongStorePlugin.onPurchaseRequested() patron-purchase contract
v2.12.0 Hotkeys: registerHotkeyAction(), unregisterHotkeyAction(), registerGlobalHotkeyProvider(), GlobalHotkeyProvider
v2.11.0 CdgLyricPlugin (open(), Song, Surface) and PluginContext.registerCdgLyricPlugin(), both experimental
v2.9.0 DJ mode: DeckId, hasDjSurface, deck transport (djPlay/djPause/djStop/djIsPlaying/djPositionSeconds/djTempoRatio/djBpm), djBeatJump, cues (djSetCue/djCue), loops (djLoop/djLoopExit/djLoopBeats), djBrake/djSpinback/djSoftStart, djCrossfader, djFxType/djFx, djAutoArm/djAutoState/djLastTransitionRecipe
v2.8.0 PluginContext.isDjMode(), VisualizationPlugin direct GL rendering (supportsDirectGl(), glAdopt(), glRenderFrame(), glRelease(), publishHostFrame())
v2.7.0 VisualizationPresets, VisualizationPresetPlaylists
v2.6.0 VisualizationPlugin, setKaraokeAudioTap(), PlaybackListenerPlugin.startVideoWithAudio(), PlaybackListenerPlugin.getVideoDimLevel()
v2.5.0 QUPPlugin.onConfigPanelClosed()
v2.2.1 setFillerAudioTap(), AudioTap, verifySingerPin(), singerHasPin(), singerExists(), SingerNames, PlaybackEvent.isFiller()
v2.1.4 registerMediaTab() with category, openAudioSink(), AudioSink, PlaybackSourcePlugin, SourcePlayer, PlaybackParams, SourcePlayer.setCrossfadeGain()
v2.0.57 Transport control, addFillerUrl(), queueUrlToPlaylist(), getAutomation(), Automation
v2.0.54 Native file dialogs, FileFilterSpec. Removed createFileChooser() / createFolderChooser().
v2.0.27 applyStandardListStyle(), addListStyleToggle()

Updated on version 2.37.3, November 13, 2026