JPS (Jukebox Plugin System) SDK v1.02
=====================================

http://www.jukeplugsys.com

--: Introduction :--

The JPS SDK is a collection of source code and host examples for using the JPS plugin system supported by several Jukebox software.

This Document API is a plugin system, named Jukebox Plug-In System, which is available to create and use plugins to your favorit software, that can use this system. This system is universal and can been used by any jukebox software.

--: Supported Jukebox Software :-

UncleT's Jukebox http://unclet.arcadecontrols.com/Jukebox/
MultiJuke http://www.multijuke.com/
Freebox Jukebox http://www.freeboxjukebox.com/

--------------------------------------------------------------------------------

--: Commands :--

Please Notes:
- All returned string MUST been a adress reference to the memory where the string is.
- All values might also sendt as a string, even it sat it a value.
- UTF8 unicode coded strings can been used for unicode support for all strings (both send and retrieved).
- Plugin file names would been JPS (since it seen JukePluginSys is the final name), which is a renamed DLL file.

--------------------------------------------------------------------------------


MAIN DLL FUNCTIONS DEFINED:

These functions should been defined by a DLL.

PCHAR Juke_GetPluginInfo(int Value)
Return a string contaion this info with this format:

PLUGIN_NAME + '|' + PLUGIN_AUTHOR + '|' + PLUGIN_VERSION + '|' + PLUGIN_DESCRIPTION

int Juke_Initialize(int Value)
Init the plugin throuch under the Jukebox Software startup. return 1 if succes.

int Juke_Shutdown(int Value)
Init the plugin throuch under the Jukebox Software startup. return 1 if succes.

int juke_Configure(HWND hWndParent)
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.

PCHAR Juke_Command(PCHAR Name, PCHAR Value)
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).


--------------------------------------------------------------------------------


APPLICATION COMMANDS:


Juke_Command("JUKE_APP_GAINFOCUS","")
When the user just switched to the jukebox software for activate the main Window.

Juke_Command("JUKE_APP_LOSTFOCUS","")
If the jukebox application lost focus for the main window.

Juke_Command("JUKE_APP_RESTORED","")
When the application is restored.

Some application might not use the GainFocus command, and others might use both.

Juke_Command("JUKE_APP_MINIMIZED","")
When the applications is minimized.

Some application might not use the LostFocus command, and others might use both.

UNICODE_SUPPORT$=Juke_Command("JUKE_APP_UNICODE","TRUE or FALSE")
Does the Jukebox Application support Unicode or not? Then a UTF8 formatted encoded string can been used as send and retrive. This allow other langauges to been used as well.

If the plugin itself does support UTF8 strings, it can return a "TRUE" string back, so it make sure plugins can understand UNICODE.


Juke_Command("JUKE_APP_HOST","SOFTWARE NAME")
The Jukebox software name.

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 !!


--------------------------------------------------------------------------------


PLUGIN_EVENT COMMANDS:

These PLUGIN_EVENT commands is very powerfull, where a Jukebox Software host can define any features it have. Some features can go for a KEY_EVENT, other can example go for some light events and so on.

Your software does NOT need to meet any features another software might have, that part is up to you (as jukebox authors) to define.

Please Note: Any CHAR value at 34, which is a ", should been removed from ValueStr before parsing, if they are added by the Jukebox software  (SEND, CREATE) or sent back by Plugin (GET).


JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|"valueStr"")

where:

valueStr = text string indicating which types of values which are allowed to be sent to (and received from) the plugin.   This string consists of any of the following text values listed below.  Each value is 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 = a number can be provided (ex: set volume level)
LETTER = a letter can be provided (ex: jump to album covers starting with a certain letter). a UTF8 letter can also been sent for unicode support.
ON = a feature or setting has been turned on (ex: repeat song ON, mute volume on)
OFF = a feature or setting has been turned off (ex: repeat song OFF, mute volume off)
KEYDOWN = a button has been pressed
KEYUP = a button has been released
KEYCLICK = a button has been pressed and released (a empty valueStr, "", is act like a KEYCLICK)

Examples:


To indicate whether something is on or off then the following command would be created:
JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|"ON OFF"")


To indicate a number or letter can be associated with the event:
JukeCommand("PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|"NUMBER LETTER"")


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


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", "eventName|valueStr")
Sends a previously defined jukebox-specific command to the plugin with a valueStr.

where: eventName = a text string in this format ---> PLUGIN_EVENT_(name)|"valueStr"

retValStr = Juke_Command("JUKE_PLUGIN_EVENT_GET", "")
Send a defined command back to the Jukebox Software.

where: retvalStr = a text string in this format ---> PLUGIN_EVENT_(name)|"valueStr" 


--------------------------------------------------------------------------------


SONGLIST COMMANDS:


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 songlist.

Some Jukebox Software might add a song directly as a first song, so it play directly. Here set a value to 0.
If a positionis to big, it would just added next to the songlist. 

Info about arguments:


TrackNr and AlbumNr is the same value types as enter 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.
system is set to 1 if the song was added by the system

Juke_Command("JUKE_SONGLIST_REMOVE_SONG", "position")
Song removed from the songlist by user or system.

Juke_Command("JUKE_SONGLIST_MOVE_SONG", "oldPosition|newPosition")
Song moved from the songlist.

Juke_Command("JUKE_SONGLIST_CLEAR", "")
The songlist has been cleared.

Juke_Command("JUKE_SONGLIST_CURRENTPOSITION", "position")
Some software do NOT delete songlist after played song, like a PLAYLIST system in Winamp or a user can select a song from a position. These software would tell which song that is curretly playing.


Some Applications use SONGLIST position 1 as the first song in its Queue system. Because of that, default value is set to 0 to make sure the first song in QUEUE and SONGSTART does not output as same song. Otherwice this command would been used to define which position on a songlist that is playing now.


SuggestionFile=Juke_Command("JUKE_SONGLIST_SUGGESTION", "LastPlayedFile")

This was a bit bad destripted and its only here I changed in v1.01.

Get a file from a plugin. This command can been used when the songlist is empty or last song is played finish from the PlayList. Neat for applications like MUSIC_IP.

The Jukebox software would send the last played file with full path to the plugin and return a another file(s). If more than one file is returned and seperated with |.

The returned string can been some thing like this:
D:\Musik\Albums\Bjrn Lynne\Accelerator (Bjrn Lynne) (2001)\01 - Turbo Grid.mp3"

Please Note: If no of the returned files is listed in Jukebox software database, the software might change to radio, idle modes with automatic playing. When the new song is played finished it trying send this command again.


--------------------------------------------------------------------------------


SONG PLAYING COMMANDS:

Juke_Command("JUKE_SONG_START","system|title|artist|album|genre|totalDuration|TrackNr|AlbumNr")
New song is just started (system is set to value one if it added by the system).

Juke_Command("JUKE_SONG_NEXT","system|title|artist|album|genre|totalDuration|TrackNr|AlbumNr")
Same as above, but just info about next song (system is set to value one if it added by the system).

Juke_Command("JUKE_SONG_FINISH","")
Current song has been finished.

JukeCommand(JUKE_SONG_RESTART, "")
this is sent when a song have been restarted, regaardless it have been played the finished or selected by user.

Juke_Command("JUKE_SONG_SKIP","")
Current song has been skipped.

Juke_Command("JUKE_SONG_PAUSE","")
Current song has been paused.

Juke_Command("JUKE_SONG_RESUME","")
Current song has been resumed from pause state.

Juke_Command("JUKE_SONG_PLAYMODE", "AnyMode")
A which play mode is it in? It can example been "Radio", "Random", "No songs in queue", total numbers of song or something text of value about the playmode. That info should just display in the Plugin Display. Not to been parsed in any way.


Juke_Command("JUKE_SONG_FASTFWD_START","")
Current song has started being fast forwarded.

Juke_Command("JUKE_SONG_FASTFWD_FINISH","")
Current song has finished being fast forwarded

Juke_Command("JUKE_SONG_FASTREV_START","")
Current song has started being fast reversed

Juke_Command("JUKE_SONG_FASTREV_FINISH","")
Current song has finished being fast reversed

Juke_Command("JUKE_SONG_PLAY_POSITION",curPosSecs|totalDuration)
The number of seconds into the current song. This command is also still invoked under FASTREV or FASTFWD commands. 



--------------------------------------------------------------------------------


DIGIT COMMANDS:

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.


--------------------------------------------------------------------------------


VOLUME COMMANDS:

Juke_Command("JUKE_VOLUME_CHANGE", "system|curVolumeLevel|minVolumeLevel|maxVolumeLevel")
A new value volume have been changed or set....

If system is changed the volume (etc the radio feature or such), the last argument is set to one.

Juke_Command("JUKE_VOLUME_MUTE", "TRUE or FALSE")
Set Mute Status to TRUE or FALSE.


--------------------------------------------------------------------------------


FEATURE COMMANDS:

All FEATURES COMMANDS that was in the beta versions is removed. You as Jukebox author can define any feature as  PLUGIN_EVENTS, and can been any feature suitable to your Jukebox software.


--------------------------------------------------------------------------------

--: Credits :--

- Commands

UncleT / Space Fractal

- Source

C++: HeadKaze
Delphi: Loadman
VB6 Host: HeadKaze
Pure Basic: Space Fractal

--------------------------------------------------------------------------------
