Here is a more indepth information, what this JukePlugSys is really do:http://www.jukeplugsys.com
Here is a command list for PlugJukeSys:
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.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 named JPS, which is a renamed DLL file.
- Since This SDK is V1.X now, no major changes to all commands or removals would been used.
- Not all commands is required to been used by Jukebox Software.
- New commands can allways been added, if needed....
!! STATUS: V1.06 (March 21, 2008) !!
1.06: No commands added, but just write some info about subdirectory in the plugindir, some plugins might use.
1.06: Removed old no needed info in JUKE_SONGLIST_ADD_SONG (no changes required in exist apps).
1.06: Better destription for JUKE_SONGLIST_CURRENTPOSITION, most targeted for Plugin Writers.
1.06: A little note for JUKE_APP_UNICODE.
1.05: Added a Filename to the JUKE_SONGLIST_ADD_SONG, JUKE_SONG_START and JUKE_SONG_NEXT commands.
1.05: Changed destription about JUKE_SONGLIST_CURRENTPOSITION, but it does the same.
1.04: Just added a note about JUKE_PLUGIN_EVENT_GET to not use " as returned string, since some software (like Uncle'T Jukebox) might not like them.
1.03: IMPORTANT: PLUGIN_EVENT_CREATE renamed to JUKE_PLUGIN_EVENT_CREATE
Plugin Writers: Make SURE to checking if the jukebox application have added the JUKE_ Prefix. If the software diddent do that, please add that to the string BEFORE parsing the string in your plugin.
1.02: Just added 2 new commands, marked in red.
1.02: JUKE_SONGLIST_SUGGESTION can now send more than one file back.
1.02: examples in PLUGIN_EVENT_CREATE: () didden't march... Just A document error.
1.01: The JUKE_SONGLIST_SUGGESTION is changed (was a really bad description).
Directory Format for Plugins:
- There should exists a subfolder where the JST files can been placed where the Jukebox Application is installed.
- This subfolder can been called "JukePlugSys", but is not required to call precision like that (but use here as reference).
- The Jukebox application should only search for JST or DLL (in debugger state) files at exists in the "JukePlugSys" subfolder.
- Plugins in main plugin folder should use the same name, like this (of course unless when used in a subfolder):
- A Plugin can can even want to create a subfolder to, if it plans to use many support files or folders, like this:
readme.txt (can been any filename)
any other files or more subfolders
MAIN DLL FUNCTIONS DEFINED:
These functions should been defined by a DLL.PCHAR Juke_GetPluginInfo();
Return a string contaion this info with this format:
PLUGIN_NAME + '|' + PLUGIN_AUTHOR + '|' + PLUGIN_VERSION + '|' + PLUGIN_DESCRIPTIONint Juke_Initialize(value);
Init the plugin throuch under the Jukebox Software startup. return 1 if succes.int Juke_Shutdown(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.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).
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.To Jukebox Authors:
It is optimal to add a option to disable or enable this feature in the config manager API.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 don't reject other jukebox software, if you have a favorit !!
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), but do NOT add them when sent back from the Plugin (GET).JukeCommand("JUKE_PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|"valueStr"")
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)
- To indicate whether something is on or off then the following command would be created:
JukeCommand("JUKE_PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|"ON OFF"")
- To indicate a number or letter can be associated with the event:
JukeCommand("JUKE_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("JUKE_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("JUKE_PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|"ENABLE DISABLE NUMBER LETTER"")
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
Please Note: Some jukebox software does not like " in the returned string, so do NOT add them here.
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",
Add a song into that position in the songlist.
Info about arguments:
- System is set to 1 if the song was added by the system
- Some songinfo "tags" might been empty if not used.
- Some songs might not contain TotalDuration, and hence sent as 0.
- TrackNr and AlbumNr is the same value types as enter DIGIT commands.
- If more songs is going to submit at once, the more vaule is set to 1.
- FileName is stored with full path (might not used by all JB software).
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 songs from the songlist after the song is played finish (JUKE_SONG_FINISH). Instead this software just jump to the next song in the SONGLIST and play that. This command tell the plugin which song that is in playing from the SongList (likely the same way Winamp do).
This command should been used <b>BEFORE</b> JUKE_SONG_START and is not required by jukebox software to support this (example if JB software only use these SONGLIST as a QUEUE). Plugin Writers:
If you want to support all songlist/playlist/queue scremes a jukebox software might use, you can threat the current played song as song position 0, if this command is NOT used by the jukebox software software (Like Uncle'T Jukebox).example when this command is never used:
if plugin got a "JUKE_SONG_START" then convert it to a "JUKE_SONGLIST_ADD_SONG" with song position at 0.
if plugin got a "JUKE_SONG_FINISH" then convert it to a "JUKE_SONGLIST_REMOVE_SONG", "0"
if plugin got a "JUKE_SONG_SKIP" then convert it to a "JUKE_SONGLIST_REMOVE_SOMG", "0"
Hence you make sure it works with any software, that might use diffecent, like these in MultiJuke, Uncle'T Jukebox.SuggestionFile=Juke_Command("JUKE_SONGLIST_SUGGESTION", "LastPlayedFile")
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\Bjørn Lynne\Accelerator (Bjørn 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|FileName")
New song is just started (system is set to value one if it added by the system).Please Note: FileName is stored with full path. Some Jukebox Software might send nothing to that argument.Juke_Command("JUKE_SONG_NEXT","system|title|artist|album|genre|totalDuration|TrackNr|AlbumNr|FileName")
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.Please Note:
a UTF8 string might been sent if unicode is set to TRUE.
Current song has started being fast forwarded.
Current song has finished being fast forwarded
Current song has started being fast reversed
Current song has finished being fast reversed
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.
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.
SDK for these commands: