Jukebox Plug-Ins
Jukebox Plugins are bit of 'add on' software that is controlled by your Juke-box software.
BackGround
In early 2008 a standard set of commands was agreed upon by jukebox software authors Space Fractal (MultiJuke) and UncleT (UncleT's Jukebox) with a goal of allowing plugIns to be created which would be compatible with any jukebox software which supports this standard. With some input from other interested parties (loadman and headkaze) a global standard was created.
The standard is known as the Jukebox PlugIn System (JPS) (or JukePlugSys).
Jukebox software which supports the JPS standard are listed below:
- UncleT's Jukebox By Uncle'T
- MultiJuke By Space Fractal
- Freebox Jukebox By Barcrest <--- currently in progress of adding JPS standard
How To Use a Plug-In
Download the plug-in and place it in the 'plugins' subfolder of your jukebox software. You can then configure the plugin with your specific requirements by going into the jukebox software, locating the plugin and clicking the provided configuration button.
JPS SDK description
Note: This development section is only of any real interest to Jukebox software authors and Plug-in authors. Any details on how to use a plug-in will be provided with that plug-in.
MAIN PLUGIN CONTROL FUNCTIONS:
PCHAR Juke_GetPluginInfo()
Return a string with plugin info in the following format ---> "NAME + | + AUTHOR + | + VERSION + | + DESCRIPTION"
int Juke_Initialize(value)
Inits the plugin when the Jukebox Software starts. Returns 1 when successful.
int Juke_Shutdown(value)
Shuts down the plugin when the Jukebox Software ends. Returns 1 when successful.
int Juke_Configure(HWND hWndParent)
Invokes the plugin configuration screen with the jukebox application's window ID. The plugin can use this as it's parent window, so the configuration window can have the current focus. If a jukebox application does not know what it is, this can been set to 0.
PCHAR Juke_Command(PChar Name, PChar Value)
Sends a command(event) (ASCII formatted) with a name and a value to the plugin. The plugin can return a string pointer to a jukebox software (ASCII formatted) as well (when required).
PLUGIN EVENT COMMANDS: (double-quotes are not included in the text string which is sent)
Juke_Command(JUKE_PLUGIN_EVENT_CREATE, "PLUGIN_EVENT_(name)|createValueStr")
This command is used to create(define) a jukebox-specific event which can be sent/received to/from the plugin at any time. One of these commands are sent for each specific event which is defined and are sent to the plugin when the jukebox first starts. The command informs the plugin about "extra" events (which are not defined by the JPS standard).
PLUGIN_EVENT_(name) = jukebox-specific event name
createValueStr = text string indicating which types of values are allowed to be sent/received to/from the plugin. This string consists of any of the following text values listed below. Multiple values are space delimited.
ENABLE = allow the user to provide input or invoke change (ie: allow users to delete queued songs)
DISABLE = do not allow user to provide input or invoke change (ex: do not allow users to delete queued songs)
NUMBER = number can be provided (ex: set volume level)
LETTER = letter can be provided (ex: jump to album covers starting with a certain letter).
ON = feature/setting was turned on (ex: mute volume, repeat song)
OFF = feature/setting was turned off (ex: mute volume, repeat song)
KEYDOWN = button has been pressed
KEYUP = button has been released
KEYCLICK = button has been pressed and released
Examples:
1) To indicate whether something is on or off then the following command would be created: JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|ON OFF")
2) To indicate a number or letter can be associated with the event:
JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|NUMBER LETTER")
3) To indicate you can enable or disable (like lights) something as well as indicating you can receive some keyEvent for it:
JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|ENABLE DISABLE KEYDOWN KEYUP KEYCLICK")
4) Now, "just for fun" lets say there is an event which allows the plugin to enable/disable it, also allows it to enter a number and a letter:
JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|ENABLE DISABLE NUMBER LETTER")
Juke_Command("JUKE_PLUGIN_EVENT_SEND", "PLUGIN_EVENT_(name)|sendValueStr")
Sends a previously created/defined jukebox-specific event to the plugin.
PLUGIN_EVENT_(name) = event name previously created by the "JUKE_PLUGIN_EVENT_CREATE" command
sendValueStr = one of the "createValueStr" values listed above
retValStr = Juke_Command("JUKE_PLUGIN_EVENT_GET", nullString)
This command is continuously sent to the plugin so the plugin can then return an event string value to indicate an event in which the jukebox software should execute.
retValStr = text string in the following format --> "PLUGIN_EVENT_(name)|valueStr"
APPLICATION COMMANDS: (double-quotes are not included in the text string which is sent)
Juke_Command("JUKE_APP_GAINFOCUS", nullString)
When the jukebox window becomes the active window in the user's environment
Juke_Command("JUKE_APP_LOSTFOCUS", nullString)
When the jukebox window is no longer the active window in the user's environment
Juke_Command("JUKE_APP_RESTORED", nullString)
When the jukebox application is restored from being minimized
Juke_Command("JUKE_APP_MINIMIZED", nullString)
When the jukebox application is minimized
Juke_Command("JUKE_APP_UNICODE", "TRUE or FALSE")
Whether the Jukebox supports Unicode or not?
Juke_Command("JUKE_APP_HOST", "JukeboxName")
Informs the plugin with the jukebox's name.
SONGLIST COMMANDS: (double-quotes are not included in the text string which is sent)
Juke_Command("JUKE_SONGLIST_ADD_SONG",
"system|position|title|artist|album|genre|totalDuration|trackNum|albumNum|more")
Indicates a song has been added to the queue.
NOTE: Some song information might not be supplied if it could not be determined at the time the event was sent.
system = whether user or system added the song (0=user 1=system)
position = queue position the song has been added
title = song's name
artist = song's artist name
album = song's album name
genre = song's associated genre
totalDuration = total amount of seconds in the song
trackNum = jukebox's assigned track number
albumNum = jukebox's assigned album number
more = if more songs are going to be added to the queue immediately after this event is sent then we can inform the plugin this is going to happen and that more of these events are going to be sent. (0=no more, 1=more)
Juke_Command("JUKE_SONGLIST_REMOVE_SONG", "position")
Indicates a song has been removed from the queue.
position = queue position which the song was removed
Juke_Command("JUKE_SONGLIST_MOVE_SONG", "oldPosition|newPosition")
Indicates a song has been moved in the queue.
oldPosition = old/previous queue position of the song
newPosition = new/current queue position of the song
Juke_Command("JUKE_SONGLIST_CLEAR", nullString)
Indicates the song queue has been cleared (ie: either by the user or as a result of all the songs being removed for playing)
Juke_Command("JUKE_SONGLIST_CURRENTPOSITION", "position")
Indicates the position of the highlighted song within the song list.
position = queue position which the song was removed
FILE Juke_Command("JUKE_SONGLIST_SUGGESTION", "file")
Obtain a playlist file from the plugin. This command can been used when the songlist is empty or last song is played/finished from the playlist.
file = playlist file
SONG PLAYING COMMANDS: (double-quotes are not included in the text string which is sent)
Juke_Command("JUKE_SONG_START",
"system|title|artist|album|genre|totalDuration|trackNum|albumNum")
New song has just started to play.
NOTE: Some song information might not be supplied if it could not be determined at the time the event was sent.
system = whether user or system started the song (0=user 1=system)
title = song's name
artist = song's artist name
album = song's album name
genre = song's associated genre
totalDuration = total amount of seconds in the song
trackNum = jukebox's assigned track number
albumNum = jukebox's assigned album number
Juke_Command("JUKE_SONG_NEXT","system|title|artist|album|genre|totalDuration|trackNum|albumNum")
Information about the next song to be played.
NOTE: Some song information might not be supplied if it could not be determined at the time the event was sent.
system = whether user or system started the song (0=user 1=system)
title = song's name
artist = song's artist name
album = song's album name
genre = song's associated genre
totalDuration = total amount of seconds in the song
trackNum = jukebox's assigned track number
albumNum = jukebox's assigned album number
Juke_Command("JUKE_SONG_FINISH", nullString)
Current song has finished.
Juke_Command("JUKE_SONG_RESTART", nullString)
This is sent when a song HAS NOT finished playing and is requested to start playing from the beginning again
Juke_Command("JUKE_SONG_SKIP", nullString)
Current song has been skipped.
Juke_Command("JUKE_SONG_PAUSE", nullString)
Current song has been paused.
Juke_Command("JUKE_SONG_RESUME", nullString)
Current song has been resumed from pause state
Juke_Command("JUKE_SONG_PLAYMODE", "modeTextString")
The playmode the jukebox.
modeTextString = Any text string which describes the current jukebox mode (ex: Random Mode, Radio Mode, Attract Mode, etc...)
Juke_Command("JUKE_SONG_FASTFWD_START", nullString)
Current song has started being fast forwarded.
Juke_Command("JUKE_SONG_FASTFWD_FINISH", nullString)
Current song has finished being fast forwarded
Juke_Command("JUKE_SONG_FASTREV_START", nullString)
Current song has started being fast reversed
Juke_Command("JUKE_SONG_FASTREV_FINISH", nullString)
Current song has finished being fast reversed
Juke_Command("JUKE_SONG_PLAY_POSITION", curPosSecs|totalDuration)
The number of seconds into the current song.
curPosSecs = how many seconds the song has been played
totalDuration = total amount of seconds in the song
DIGIT COMMANDS: (double-quotes are not included in the text string which is sent)
Juke_Command("JUKE_ENTER_ALBUM_VALUE", "digitStr")
All digits which have been currently entered for the album number
digitStr = The total album number digits which have currently been entered
Juke_Command("JUKE_ENTER_TRACK_VALUE", "digitStr")
All digits which have been currently entered for the track number
digitStr = The total track number digits which have currently been entered
VOLUME COMMANDS: (double-quotes are not included in the text string which is sent)
Juke_Command("JUKE_VOLUME_CHANGE", "system|curVolumeLevel|minVolumeLevel|maxVolumeLevel")
Indicates the volume has been set to another value
system = whether user or system changed the volume (0=user 1=system)
curVolumeLevel = new/current volume level
minVolumeLevel = minimum volume level allowed to be entered
maxVolumeLevel = maximum volume level allowed to be entered
Juke_Command("JUKE_VOLUME_MUTE", "TRUE or FALSE")
Indicates whether volume mute is active
