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:
init(PluginContext)— you receive your API surfacegetConfigPanel()— your settings panel is registered in the config tree under PluginsonConfigPanelClosed()— every time the KJ closes the config window, and again just before shutdownshutdown()— 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:
DECLINEDif 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,setShowingandtoFrontreturnfalse. setBoundsfits the window onto the visible desktop. A window sized by its content keeps its size.setBoundssaves 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:
registerLibraryMenuentries appear on the one flat library (Simple Player) as well as on the Media Library's tables (Media Player); row objects are the sameSongInfos.onSongStarted/onSongEndedfire for the playlist's rows exactly as for a rotation entry; the singer name is empty.- There is no rotation to enqueue into:
enqueueSongand the singer-shaped calls returnfalse/ do nothing; a plugin adding songs appends to the playlist through the library menu's "Add to Playlist" semantics (queueSongwith 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()— answeringtrueis 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 othergl*methods. Returntrueif ready to render into this context.glRenderFrame(width, height, elapsedSeconds)— render one frame into the currently bound framebuffer, on the thread that calledglAdopt. 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, sorenderFrame()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. Returningnullis 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