Main > Audio/Jukebox/MP3 Forum
Plugins: Document API for JukePlugSys
Space Fractal:
About PlugJukeSys:
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):
JukePlugSys\
\JPSAttractSounds.jps
\JPSAttractSounds.ini
\JPSAttractSounds.txt
* A Plugin can can even want to create a subfolder to, if it plans to use many support files or folders, like this:
JukePlugSys\
\JPSAttractSounds\ (folder)
\JPSSoundFX\ (folder)
readme.txt (can been any filename)
any other files or more subfolders
\JPSAttractSounds.jps (file)
\JPSSoundsFX.jps (file)
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_DESCRIPTION
int 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).
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.
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 !!
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), but do NOT add them when sent back from the Plugin (GET).
JukeCommand("JUKE_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("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"")
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
Please Note: Some jukebox software does not like " in the returned string, so do NOT add them here.[/color]
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|FileName")
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).
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 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"
[/i]
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.
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.
SDK for these commands:
http://forum.arcadecontrols.com/index.php?topic=75378.0
loadman:
So this thread is just for Function comments then? ;D :laugh2:
Sorry, my crazy sense of Humor (or lack of)
It would be good to have a fuxtion that updated the time remaining on a song. Not all jukebox have to support it (if performace issues arrise) .
That would be nice on a external LCD display supported by the PLug-in.
JukePlayRemain(remain$) ;
unclet:
How about some functions for these:
- Skip song (ie: skip currently playing song to go to the next song (if one exists))
- Mute On/Off
- Flipping through pages of album covers (pageLeft, pageRight)
- Fast forward active (ie: searching through video/audio forward quickly)
- Fast reverse active (ie: searching through video/audio backward quickly)
- Party Lock activated/deactivated
- Attract mode activated/deactivated
- Move song from one queue position (X) a new queue position (Y)
- Removed song from queue from position (X)
- Clear queue contents
- Enter digit 0,1,2,3,4,5,6,7,8,9
- Delete the last entered digit
Also, I would think "JukeSecsRemain()" would be better than "JukePlayRemain()"
PS: Thanks for renaming SongStart to SongBegin :applaud:
Barry Barcrest:
IHMO It Shouldn't send how many seconds remain. It should send the current play position and the track duration so the plugin writter can display amount of time remaining or played and the total time or not they will have all that information to hand.
I don't have the option to add everything to the queue so i wouldn't want that in the standard set of plugins because i wouldn't support it, not sure about uncleT's but i think the standard set should only contain things that would be used in all software, then if you want to expand on that for specific plugins for your software that's fine.
Some functions i thing might be useful.
- Pass the playing song path, Expected return (Album, Artist, Title Tag values)
- Pass the now playing cover art path (Some plugins might want to display that)
- Is the song user selected or random? (Plugins can behave differently depending)
I have support for LED Signs in my juke however it would be cool if we get the plugins to work to replace those with a plugin. For this we would probably need...
- Pass a stirng to display (Be this on an LED sign or graphically somehow on a vis type plugin)
Hopefully that gives some ideas.
loadman:
--- Quote from: unclet on January 03, 2008, 07:23:56 pm ---- Skip song (ie: skip currently playing song to go to the next song (if one exists))
- Mute On/Off
- Flipping through pages of album covers (pageLeft, pageRight)
- Fast forward active (ie: searching through video/audio forward quickly)
- Fast reverse active (ie: searching through video/audio backward quickly)
- Party Lock activated/deactivated
- Attract mode activated/deactivated
- Move song from one queue position (X) a new queue position (Y)
- Removed song from queue from position (X)
- Clear queue contents
- Enter digit 0,1,2,3,4,5,6,7,8,9
- Delete the last entered digit
--- End quote ---
Question: Are you talking about letting the Plug-In Know that the operator is making these selections on the Jukebox software or having the ability to have the Plug-in remotely control the Jukebox.
If it's the latter then it's a whole new can of worms. Wouldn't you need to use something like windows messaging like MaLa does. That way the JukeBox software is 'listening' for commands.
--- Quote from: Barcrest on January 03, 2008, 07:41:27 pm ---IHMO It Shouldn't send how many seconds remain. It should send the current play position and the track duration so the plugin writter can display amount of time remaining or played and the total time or not they will have all that information to hand.
--- End quote ---
Sure. Whatever works ;)
Navigation
[0] Message Index
[#] Next page
Go to full version