Difference between revisions of "Jukebox Plug-Ins"
(→How To Write your own Plug-In) |
(→How To Write your own Plug-In) |
||
Line 11: | Line 11: | ||
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 then need to configure it by....... | ||
− | == | + | ==Description of the JPS SDK== |
− | |||
− | + | <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> | |
− | |||
− | |||
− | |||
− | + | Juke_Command("JUKE_PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|valueStr")<br> | |
− | The | + | 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>valueStr</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. | ||
− | '''SONGLIST COMMANDS: | + | <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 | ||
+ | |||
+ | |||
+ | Juke_Command("JUKE_PLUGIN_EVENT_SEND", "PLUGIN_EVENT_(name)|valueStr")<br> | ||
+ | Sends a previously created(defined) jukebox-specific event to the plugin. | ||
+ | |||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | <b><i>retValStr</i></b> = "PLUGIN_EVENT_(name)|valueStr" | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | <b><u>APPLICATION COMMANDS:</u></b> | ||
+ | |||
+ | |||
+ | |||
+ | Juke_Command("JUKE_APP_GAINFOCUS", nullString)<br> | ||
+ | When the jukebox window becomes the active window in the user's environment | ||
+ | |||
+ | |||
+ | 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_RESTORED", nullString)<br> | ||
+ | When the jukebox application is restored from being minimized | ||
+ | |||
+ | |||
+ | Juke_Command("JUKE_APP_MINIMIZED", nullString)<br> | ||
+ | When the jukebox application is minimized | ||
+ | |||
+ | |||
+ | Juke_Command("JUKE_APP_UNICODE", "TRUE/FALSE")<br> | ||
+ | Whether the Jukebox supports Unicode or not? | ||
+ | |||
+ | |||
+ | Juke_Command("JUKE_APP_HOST", "JukeboxName")<br> | ||
+ | Informs the plugin with the jukebox's name. | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | <b><u>SONGLIST COMMANDS:</u></b> | ||
Revision as of 14:41, 21 January 2008
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 a few Jukebox software Authors. With some input from other interested parties a Global standard was created. The goal was a plug-in could be created and with a view most if not al functionality would be compatible with any Jukebox software applying this standard.
The standard is known as 'The Jukebox Plug-in System' or JPS
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.......
Description of the JPS SDK
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:
Juke_Command("JUKE_PLUGIN_EVENT_CREATE", "PLUGIN_EVENT_(name)|valueStr")
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
valueStr = 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
Juke_Command("JUKE_PLUGIN_EVENT_SEND", "PLUGIN_EVENT_(name)|valueStr")
Sends a previously created(defined) jukebox-specific event to the plugin.
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 = "PLUGIN_EVENT_(name)|valueStr"
APPLICATION COMMANDS:
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/FALSE")
Whether the Jukebox supports Unicode or not?
Juke_Command("JUKE_APP_HOST", "JukeboxName")
Informs the plugin with the jukebox's name.
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 queue.
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 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_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") Song has been moved in the queue by user or system.
Juke_Command("JUKE_SONGLIST_CLEAR", "System") The song queue has been cleared by user or system.
Juke_Command("JUKE_SONGLIST_CURRENTPOSITION", "System") 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", "")
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.
SONG PLAYING COMMANDS:
Juke_Command("JUKE_SONG_START","") New song is just started.
Juke_Command("JUKE_SONG_FINISH","") Current song has finished.
Juke_Command("JUKE_SONG_RESTART","") Current song has been restarted
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_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) 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.
VOLUME COMMANDS:
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.
Juke_Command("JUKE_VOLUME_MUTE", "TRUE or FALSE")
Set Mute Status to TRUE or FALSE.
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.
KEY_EVENT COMMANDS
Juke_Command("JUKE_KEY_EVENT_SEND", "KEYEVENT|ENABLE or DISABLE") 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_FEATURE_ATTRACT_MODE", onActive or onNotActive or Off)
onActive (attract mode has been activated by the user and is currently running) 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) Genre Lock feature is enabled (TRUE) or disabled (FALSE)
Juke_Command("JUKE_FEATURE_PARTY_LOCK", TRUE or FALSE)
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)
TRUE: screensaver is started FALSE: screensaver is ended