Difference between revisions of "Jukebox Plug-Ins"

From BYOAC New Wiki
Jump to navigation Jump to search
m (57 revisions)
 
(52 intermediate revisions by 5 users not shown)
Line 1: Line 1:
'''Jukebox Plugins''' are bit of 'add on' software that is controlled by your Juke-box software.
+
'''[http://www.jukeplugsys.com Jukebox Plugins]''' are bit of 'add on' software that is controlled by your Juke-box software.
 +
 
 +
[[Image:http://www.jukeplugsys.com/logo.png]]
  
 
==BackGround==
 
==BackGround==
  
  In early 2008 a 'standard' set of commands
+
In early 2008 a standard set of commands was designed by '''Space Fractal''' (MultiJuke) 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.<br>
 +
 
 +
The standard is known as the <b>Jukebox PlugIn System (JPS)</b> (or '''[http://www.jukeplugsys.com JukePlugSys]''').
 +
 
 +
 
 +
'''Jukebox software which supports the JPS standard are listed below:'''
 +
 
 +
* '''[http://www.multijuke.com MultiJuke]''' By Space Fractal
 +
* '''[http://www.freeboxjukebox.com Freebox Jukebox]''' By Barcrest ''<--- currently in progress of adding JPS standard''
 +
* '''[http://www.audiovisualdevices.com.au/software/aussiejuke/aussiejuke.php Aussie Juke]''' By David Duffy
  
 
==How To Use a Plug-In==
 
==How To Use a Plug-In==
  
Download the plug-in and place it in the 'plugins' subfolder of your Jukebox software. You then need to configure it by.......
+
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.
 +
<br>
 +
<br>
 +
<br>
 +
 
 +
==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.
 +
 
 +
<b><u>MAIN PLUGIN CONTROL FUNCTIONS:</u></b>
 +
 
 +
 
 +
PCHAR  Juke_GetPluginInfo()<br>
 +
Return a string with plugin info in the following format --->
 +
"NAME + | + AUTHOR + | + VERSION + | + DESCRIPTION"
 +
 
 +
 
 +
int  Juke_Initialize(value)<br>
 +
Inits the plugin when the Jukebox Software starts.  Returns 1 when successful.
 +
 
 +
 
 +
int  Juke_Shutdown(value)<br>
 +
Shuts down the plugin when the Jukebox Software ends.  Returns 1 when successful.
 +
 
 +
 
 +
int  Juke_Configure(HWND hWndParent)<br>
 +
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)<br>
 +
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).
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<b><u>PLUGIN EVENT COMMANDS:</u></b>  (double-quotes are not included in the text string which is sent)
 +
 
 +
 
 +
  Juke_Command(JUKE_PLUGIN_EVENT_CREATE, "PLUGIN_EVENT_(name)|createValueStr")<br>           
 +
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).
 +
 
 +
 
 +
<b><i>PLUGIN_EVENT_(name)</i></b> = jukebox-specific event name
 +
 +
<b><i>createValueStr</i></b> = 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.                
 +
 
 +
 
 +
<i>ENABLE</i>  = allow the user to provide input or invoke change  (ie: allow users to delete queued songs)
 +
 
 +
<i>DISABLE</i>  = do not allow user to provide input or invoke change (ex: do not allow users to delete queued songs)
 +
 
 +
<i>NUMBER</i>  = number can be provided (ex: set volume level)
 +
 
 +
<i>LETTER</i>  = letter can be provided (ex: jump to album covers starting with a certain letter).  
 +
 
 +
<i>ON</i>      = feature/setting was turned on (ex: mute volume, repeat song)
 +
 
 +
<i>OFF</i>      = feature/setting was turned off (ex: mute volume, repeat song)
 +
 
 +
<i>KEYDOWN</i>  = button has been pressed
 +
 
 +
<i>KEYUP</i>    = button has been released
 +
 
 +
<i>KEYCLICK</i> = button has been pressed and released
 +
 
 +
 
 +
<u>Examples:</u>
 +
 
 +
1) To indicate whether something is on or off then the following command would be created:
 +
<i>JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|ON OFF")</i>
 +
 
 +
 
 +
2) To indicate a number or letter can be associated with the event:
 +
<i>JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|NUMBER LETTER")</i>
 +
 
 +
 
 +
3) To indicate you can enable or disable (like lights) something as well as indicating you can receive some keyEvent for it:
 +
<i>JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|ENABLE DISABLE KEYDOWN KEYUP KEYCLICK")</i>
 +
 
 +
 
 +
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:
 +
<i>JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|ENABLE DISABLE NUMBER LETTER")</i>
 +
 
 +
 
 +
  Juke_Command("JUKE_PLUGIN_EVENT_SEND", "PLUGIN_EVENT_(name)|sendValueStr")<br>
 +
Sends a previously created/defined jukebox-specific event to the plugin.
 +
 
 +
 
 +
<b><i>PLUGIN_EVENT_(name)</i></b> = event name previously created by the "JUKE_PLUGIN_EVENT_CREATE" command
 +
 +
<b><i>sendValueStr</i></b> = one of the "createValueStr" values listed above                 
 +
 
  
==How To Write your own Plug-In==
+
  retValStr = Juke_Command("JUKE_PLUGIN_EVENT_GET", nullString)<br>
 +
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.
  
To write a Plug-in you need to obtain a copy of the 'Juke-Box Plug-In SDK'
+
'''Please Note: Some jukebox software does not like " in the returned string, so do NOT add them here'''
  
The following is a list of supported Functions:
 
  
PCHAR Juke_GetPluginInfo();
+
<b><i>retValStr</i></b> = text string in the following format --> "PLUGIN_EVENT_(name)|valueStr"
Return a string contaion this info with this format:
 
PLUGIN_NAME + '|' + PLUGIN_AUTHOR + '|' + PLUGIN_VERSION + '|' + PLUGIN_DESCRIPTION
 
  
Juke_Command(Name:PChar; Value:PChar):PChar;
 
Sending a string (UTF8 or ASCII formatted) with a name and a value, and some commands might return a string pointer to a jukebox softare (also UTF8 or ASCII formatted).
 
  
note: Visual Basic 6 can get returned strings using a little dll I made. Look to the bottom of the first thread.
 
  
  
CONFIGURATION COMMANDS:
 
  
Juke_Command("JUKE_KEY_EVENT_CREATE","KEY_EVENT_NAME")
 
This command is required before JUKE_PLUGIN_CONFIGURE is invoked. This make sure a plugin can "listen" to a KEY_EVENT command from the Jukebox Software and example effect a sound effect to a KEY_EVENT.
 
  
A Jukebox Software can create any KEY_EVENT commands that can been controlled by the user (also like a keybinding).
+
<b><u>APPLICATION COMMANDS:</u></b>  (double-quotes are not included in the text string which is sent)
  
Only KEY_EVENT commands (keybindning) is needed for the plugin to known, so they can used for various things like LedWiz, Sound, Remote controlling and other things.
 
  
Juke_Command("JUKE_PLUGIN_CONFIGURE","WINDOW_HWND")
 
Invoke plugin configuration screen with the Plugin Mangager WINDOW ID. The Plugin can use as its parent windows, so the configuration window can have the current focus.
 
  
If a Jukebox Application dosent know what it is, this can been set to 0.
+
Juke_Command("JUKE_APP_GAINFOCUS", nullString)<br>
 +
When the jukebox window becomes the active window in the user's environment
  
  
APPLICATION COMMANDS:
+
Juke_Command("JUKE_APP_LOSTFOCUS", nullString)<br>
 +
When the jukebox window is no longer the active window in the user's environment
  
Juke_Command("JUKE_APP_OPENED","")
 
The Jukebox software have just started.
 
  
Juke_Command("JUKE_APP_CLOSED","")
+
Juke_Command("JUKE_APP_RESTORED", nullString)<br>
The Jukebox software have just closed.
+
When the jukebox application is restored from being minimized
  
Juke_Command("JUKE_APP_UNICODE","TRUE or FALSE")
 
Does the Jukebox support Unicode or not? Then the UTF8 formatted strings can been used.
 
  
Juke_Command("JUKE_APP_HOST","SOFTWARE NAME")
+
Juke_Command("JUKE_APP_MINIMIZED", nullString)<br>
The Jukebox software name.
+
When the jukebox application is minimized
  
If a jukebox application support UNICODE, the arguments would been JUKE_APP_HOST_UNICODE his string would been used, otherwice empty. If the Jukebox Software is not used any unicode string, that would been no need to convert UTF8 strings by both plugin and jukebox software.
 
  
!! Plugin Writers: Please dont reject other jukebox software, if you have a favorit !!
+
Juke_Command("JUKE_APP_UNICODE", "TRUE or FALSE")<br>
 +
Whether the Jukebox supports Unicode or not?
  
  
SONGLIST COMMANDS:
+
Juke_Command("JUKE_APP_HOST", "JukeboxName")<br>
 +
Informs the plugin with the jukebox's name.
  
  
For Jukebox Authors: If the song contain a | char (I never seen that), remove that before send the string.
 
  
  
Juke_Command("JUKE_SONGLIST_ADD_SONG",
 
"system|postition|title|artist|album|genre|totalDuration|TrackNr|AlbumNr|more")
 
Add a song into that position in the queue.
 
  
Some Jukebox Software might add a song directly as a first song, so it play directly. Here set a value to 0.
+
<b><u>SONGLIST COMMANDS:</u></b>  (double-quotes are not included in the text string which is sent)
If a positionis to big, it would just added next to the queue.
 
  
Info about arguments:
 
  
    * Auto means if it was added by the "USER" or by "SYSTEM".
 
    * TrackNr and AlbumNr is the same values gave by DIGIT COMMANDS.
 
    * Some songinfo "tags" might been empty if not used.
 
    * Some songs might not even contain TotalDuration if it is unknown.
 
    * If more songs is going to submit at once, the more vaule is set to 1. The last submitted song would have a value set to 0.
 
  
 +
  Juke_Command("JUKE_SONGLIST_ADD_SONG",
 +
              "system|position|title|artist|album|genre|totalDuration|trackNum|albumNum|more|filename")<br>
 +
Indicates a song has been added to the queue.
  
 +
<i>NOTE: Some song information might not be supplied if it could not be determined at the time the event was sent.</i>
  
Juke_Command("JUKE_SONGLIST_REMOVE_SONG", "System|position")
 
Song removed from the queue by user or system or a song is played finished (using queuePosNum=1 as value).
 
  
Juke_Command("JUKE_SONGLIST_MOVE_SONG", "System|oldPosition|newPosition")
+
<b><i>system</i></b> = whether user or system added the song (0=user 1=system)
Song has been moved in the queue by user or system.
 
  
Juke_Command("JUKE_SONGLIST_CLEAR", "System")
+
<b><i>position</i></b> = queue position the song has been added
The song queue has been cleared by user or system.
 
  
Juke_Command("JUKE_SONGLIST_CURRENTPOSITION", "System")
+
<b><i>title</i></b> = song's name
Some software do NOT delete queue after played song, like a PLAYLIST system in Winamp. These software would tell which song that is curretly playing. Queue based Jukebox Software might not use this command.
 
  
FILE=Juke_Command("JUKE_SONGLIST_SUGGESTION", "")
+
<b><i>artist</i></b> = song's artist name
  
Get a playlist file from a plugin. This command can been used when the queue is empty or last song is played finish from the PlayList. neat for applications like MUSIC_IP.
+
<b><i>album</i></b> = song's album name
  
 +
<b><i>genre</i></b> = song's associated genre
  
SONG PLAYING COMMANDS:
+
<b><i>totalDuration</i></b> = total amount of seconds in the song
  
Juke_Command("JUKE_SONG_START","")
+
<b><i>trackNum</i></b> = jukebox's assigned track number
New song is just started.
 
  
Juke_Command("JUKE_SONG_FINISH","")
+
<b><i>albumNum</i></b> = jukebox's assigned album number
 +
 
 +
<b><i>more</i></b> = 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)
 +
 
 +
<b><i>filename</i></b> = The filename to the song with full path.
 +
 
 +
 
 +
 
 +
  Juke_Command("JUKE_SONGLIST_REMOVE_SONG", "position")<br>
 +
Indicates a song has been removed from the queue.
 +
 
 +
 
 +
<b><i>position</i></b> = queue position which the song was removed
 +
 
 +
 
 +
  Juke_Command("JUKE_SONGLIST_MOVE_SONG", "oldPosition|newPosition")<br>
 +
Indicates a song has been moved in the queue.
 +
 
 +
 
 +
<b><i>oldPosition</i></b> = old/previous queue position of the song
 +
 
 +
<b><i>newPosition</i></b> = new/current queue position of the song
 +
 
 +
 
 +
  Juke_Command("JUKE_SONGLIST_CLEAR", nullString)<br>
 +
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")<br>
 +
Indicates the position of the highlighted song within the song list.
 +
 
 +
 
 +
Please Note:
 +
If a application use JUKE_SONGLIST_ADD_SONG to add songs after the current played song (used only as a queue), this command is NOT used. Hence default value set to 0.
 +
 
 +
Plugin Writers:
 +
If you want to support all songlist/playlist/queue scremes, you can convert a JUKE_SONG_START command to a JUKE_SONGLIST_ADD_SONG using position 0 in your parser, if this command have a value 0 (ETC never sent).
 +
 
 +
 
 +
 
 +
<b><i>position</i></b> = queue position which the song was removed
 +
 
 +
 
 +
  FILE  Juke_Command("JUKE_SONGLIST_SUGGESTION", "file")<br>
 +
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.
 +
 
 +
 
 +
<b><i>file</i></b> = playlist file
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<b><u>SONG PLAYING COMMANDS:</u></b>  (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|filename")<br>
 +
New song has just started to play.
 +
 
 +
<i>NOTE: Some song information might not be supplied if it could not be determined at the time the event was sent.</i>
 +
 
 +
 
 +
<b><i>system</i></b> = whether user or system started the song (0=user 1=system)
 +
 
 +
<b><i>title</i></b> = song's name
 +
 
 +
<b><i>artist</i></b> = song's artist name
 +
 
 +
<b><i>album</i></b> = song's album name
 +
 
 +
<b><i>genre</i></b> = song's associated genre
 +
 
 +
<b><i>totalDuration</i></b> = total amount of seconds in the song
 +
 
 +
<b><i>trackNum</i></b> = jukebox's assigned track number
 +
 
 +
<b><i>albumNum</i></b> = jukebox's assigned album number
 +
 
 +
<b><i>filename</i></b> = The filename to the song with full path.
 +
 
 +
 
 +
  Juke_Command("JUKE_SONG_NEXT","system|title|artist|album|genre|totalDuration|trackNum|albumNum|filename")<br>
 +
Information about the next song to be played.
 +
 
 +
<i>NOTE: Some song information might not be supplied if it could not be determined at the time the event was sent.</i>
 +
 
 +
 
 +
<b><i>system</i></b> = whether user or system started the song (0=user 1=system)
 +
 
 +
<b><i>title</i></b> = song's name
 +
 
 +
<b><i>artist</i></b> = song's artist name
 +
 
 +
<b><i>album</i></b> = song's album name
 +
 
 +
<b><i>genre</i></b> = song's associated genre
 +
 
 +
<b><i>totalDuration</i></b> = total amount of seconds in the song
 +
 
 +
<b><i>trackNum</i></b> = jukebox's assigned track number
 +
 
 +
<b><i>albumNum</i></b> = jukebox's assigned album number
 +
 
 +
<b><i>filename</i></b> = The filename to the song with full path.
 +
 
 +
 
 +
  Juke_Command("JUKE_SONG_FINISH", nullString)<br>
 
Current song has finished.
 
Current song has finished.
  
Juke_Command("JUKE_SONG_RESTART","")
 
Current song has been restarted
 
  
Juke_Command("JUKE_SONG_SKIP","")
+
  Juke_Command("JUKE_SONG_RESTART", nullString)<br>
 +
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)<br>
 
Current song has been skipped.
 
Current song has been skipped.
  
Juke_Command("JUKE_SONG_PAUSE","")
+
 
 +
  Juke_Command("JUKE_SONG_PAUSE", nullString)<br>
 
Current song has been paused.
 
Current song has been paused.
  
Juke_Command("JUKE_SONG_RESUME","")
+
 
 +
  Juke_Command("JUKE_SONG_RESUME", nullString)<br>
 
Current song has been resumed from pause state
 
Current song has been resumed from pause state
  
Juke_Command("JUKE_SONG_FASTFWD_START","")
+
 
 +
  Juke_Command("JUKE_SONG_PLAYMODE", "modeTextString")<br>
 +
The playmode the jukebox. 
 +
 
 +
 
 +
<b><i>modeTextString</i></b> = Any text string which describes the current jukebox mode (ex: Random Mode, Radio Mode, Attract Mode, etc...)
 +
 
 +
 
 +
  Juke_Command("JUKE_SONG_FASTFWD_START", nullString)<br>
 
Current song has started being fast forwarded.
 
Current song has started being fast forwarded.
  
Juke_Command("JUKE_SONG_FASTFWD_FINISH","")
+
 
 +
  Juke_Command("JUKE_SONG_FASTFWD_FINISH", nullString)<br>
 
Current song has finished being fast forwarded
 
Current song has finished being fast forwarded
  
Juke_Command("JUKE_SONG_FASTREV_START","")
+
 
 +
  Juke_Command("JUKE_SONG_FASTREV_START", nullString)<br>
 
Current song has started being fast reversed
 
Current song has started being fast reversed
  
Juke_Command("JUKE_SONG_FASTREV_FINISH","")
+
 
 +
  Juke_Command("JUKE_SONG_FASTREV_FINISH", nullString)<br>
 
Current song has finished being fast reversed
 
Current song has finished being fast reversed
  
Juke_Command("JUKE_SONG_PLAY_POSITION",curPosSecs)
 
The number of seconds into the current song. This command is also still invoked under FASTREV or FASTFWD commands.
 
  
The Jukebox Software Do allways send this info when the secs is changed due to above reason.
+
  Juke_Command("JUKE_SONG_PLAY_POSITION", curPosSecs|totalDuration)<br>
 +
The number of seconds into the current song.
 +
 
 +
 
 +
<b><i>curPosSecs</i></b> = how many seconds the song has been played
 +
 
 +
<b><i>totalDuration</i></b> = total amount of seconds in the song
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<b><u>DIGIT COMMANDS:</u></b>  (double-quotes are not included in the text string which is sent)
 +
 
  
  
VOLUME COMMANDS:
+
  Juke_Command("JUKE_ENTER_ALBUM_VALUE", "digitStr")<br>
 +
All digits which have been currently entered for the album number
  
Juke_Command("JUKE_VOLUME_SET", "system|curVolumeLevel|minVolumeLevel|maxVolumeLevel")
 
A new value volume have been set.
 
  
If system is set the volume, the last argument would set to one.
+
<b><i>digitStr</i></b> = The total album number digits which have currently been entered
  
Juke_Command("JUKE_VOLUME_MUTE", "TRUE or FALSE")
 
  
Set Mute Status to TRUE or FALSE.
+
  Juke_Command("JUKE_ENTER_TRACK_VALUE", "digitStr")<br>
 +
All digits which have been currently entered for the track number
  
  
DIGIT COMMANDS:
+
<b><i>digitStr</i></b> = The total track number digits which have currently been entered
  
Juke_Command("JUKE_ENTER_ALBUM_VALUE", "VALUE")
 
Send the value string on the marked album, when the have entered a album number or letter.
 
  
Juke_Command("JUKE_ENTER_TRACK_VALUE", "VALUE")
 
Send the value string on the marked track or singles, when the have entered a album number or letter.
 
  
A Track number and or letter have been selected. Send the whole value, user seen on screen and not one digit at one time.
 
  
  
KEY_EVENT COMMANDS
 
  
Juke_Command("JUKE_KEY_EVENT_SEND", "KEYEVENT|ENABLE or DISABLE")
+
<b><u>VOLUME COMMANDS:</u></b>  (double-quotes are not included in the text string which is sent)
Is event is disabled or enabled? If the EVENT dosent need that, it might just send a "" string. Hence it allways enabled.
 
  
EVENT=Juke_Command("JUKE_KEY_EVENT_GET","")
 
A KEY_EVENT have sendt from plugin to the jukebox software, and the command EVENT would been accour.
 
  
  
FEATURE COMMANDS:
+
  Juke_Command("JUKE_VOLUME_CHANGE", "system|curVolumeLevel|minVolumeLevel|maxVolumeLevel")<br>
 +
Indicates the volume has been set to another value
  
Juke_Command("JUKE_FEATURE_ATTRACT_MODE", onActive or onNotActive or Off)
 
  
onActive (attract mode has been activated by the user and is currently running)
+
<b><i>system</i></b> = whether user or system changed the volume (0=user 1=system)
onNotActive (attract mode has been activated by the user and is NOT currently running)
 
off (attract mode has NOT been activated by the user)
 
  
Juke_Command("JUKE_FEATURE_GENRE_LOCK", TRUE or FALSE)
+
<b><i>curVolumeLevel</i></b> = new/current volume level
Genre Lock feature is enabled (TRUE) or disabled (FALSE)
 
  
 +
<b><i>minVolumeLevel</i></b> = minimum volume level allowed to be entered
  
Juke_Command("JUKE_FEATURE_PARTY_LOCK", TRUE or FALSE)
+
<b><i>maxVolumeLevel</i></b> = maximum volume level allowed to be entered
Party Lock feature is enabled (TRUE) or disabled (FALSE)
 
  
Juke_Command("JUKE_FEATURE_RANDOM_MODE", TRUE or FALSE)
 
Radio or Random mode is enabled(TRUE) or disabled(FALSE)
 
  
Juke_Command("JUKE_FEATURE_SCREENSAVER_MODE", TRUE or FALSE)
+
  Juke_Command("JUKE_VOLUME_MUTE", "TRUE or FALSE")<br>
 +
Indicates whether volume mute is active
  
TRUE: screensaver is started
+
<br>
FALSE: screensaver is ended
+
<br>
  
 
==See Also==
 
==See Also==

Latest revision as of 09:22, 5 December 2013

Jukebox Plugins are bit of 'add on' software that is controlled by your Juke-box software.

File:Http://www.jukeplugsys.com/logo.png

BackGround

In early 2008 a standard set of commands was designed by Space Fractal (MultiJuke) 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:

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.

Please Note: Some jukebox software does not like " in the returned string, so do NOT add them here


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|filename")

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)

filename = The filename to the song with full path.


 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.


Please Note: If a application use JUKE_SONGLIST_ADD_SONG to add songs after the current played song (used only as a queue), this command is NOT used. Hence default value set to 0.

Plugin Writers: If you want to support all songlist/playlist/queue scremes, you can convert a JUKE_SONG_START command to a JUKE_SONGLIST_ADD_SONG using position 0 in your parser, if this command have a value 0 (ETC never sent).


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|filename")

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

filename = The filename to the song with full path.


 Juke_Command("JUKE_SONG_NEXT","system|title|artist|album|genre|totalDuration|trackNum|albumNum|filename")

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

filename = The filename to the song with full path.


 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



See Also