Jukebox Plug-Ins

From BYOAC New Wiki
Revision as of 21:08, 10 January 2008 by Barcrest (talk) (How To Write your own Plug-In)
Jump to navigation Jump to search

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

How To Write your own Plug-In

To write a Plug-in you need to obtain a copy of the 'Juke-Box Plug-In SDK'

The following is a list of supported Functions:

PCHAR Juke_GetPluginInfo(); 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).



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

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.


APPLICATION COMMANDS:

Juke_Command("JUKE_APP_OPENED","") The Jukebox software have just started.

Juke_Command("JUKE_APP_CLOSED","") The Jukebox software have just closed.

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


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

See Also