Main > Audio/Jukebox/MP3 Forum
Plugins: Document API for JukePlugSys
Space Fractal:
In Pure Basic I just detect a null pointer as a | too, or you can add a | sign before parsing the string?
I have accepted UncleT version, but I changed few commands to, and added KEY_EVENT commands (the major problem between I and UncleT), so please look in the SDK, before writing a plugin and I wait for the UncleT comment on about these change.
unclet:
--- Quote ---Juke_Command("JUKE_KEY_EVENT_CREATE","COMMAND_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.
--- End quote ---
Nice solution ! :applaud: :applaud: :applaud:
Please rename "COMMAND_NAME" to be "KEY_EVENT_NAME" in the documentation though :P
So just so I understand ..... before the plugin gets configured you can send as many of these "JUKE_KEY_EVENT_CREATE" commands as you want to inform the plugin about all the different types of key events your software supports. Then the plugin can allow mappings to these events to occur during it's configuration. Then when the event occurs in your jukebox software, then your software can send the plugin this specific key event by using the normal "Juke_Command()" routine?
For example
Your software allows coin insert to occur, so you would inform the plugin of this event with:
Juke_Command("JUKE_KEY_EVENT_CREATE","JUKE_KEY_EVENT_COIN_INSERT")
then when the user inserts a coin in your machine then you would send the plugin this:
Juke_Command("JUKE_KEY_EVENT_COIN_INSERT", "")
If this is true, then I guess none of the key events will have cmdValue strings associated with them ...... correct? Basically all key event commands sent to the plugin will have the second parameter be ""
--- Quote ---Juke_Command("JUKE_APP_HOST","SOFTWARE NAME", "UNICODE")
The Jukebox software name.
--- End quote ---
Ths "Juke_Commands()" routine is defined to have two interface parameters and you are using three parameters instead. I suggest defining the following two commands to solve this problem:
JUKE_APP_HOST
JUKE_APP_HOST_UNICODE
--- Quote ---PLAYLIST COMMANDS:
either resumbt all songs again at once again using or just change the number of current song if the software is PLAYLIST based, using the JUKE_PLAYLIST_CURRENTSONG command.
Juke_Command("JUKE_PLAYLIST","place|auto|title|artist|album|trackNum|genre|totalDuration")
When a user have manipulated the playlist, or a new song is started, the jukebox software would resumbit all songs again. If A new songs is added to the playlist without manipulation, the software might just add that song using JUKE_PLAYLIST with the last PLACE number.
Info about arguments:
* Auto means if it was added by the "USER" or by "SYSTEM".
* Albumnumber or such should been part of the album name, like "01 Album".
* Some songinfo "tags" might been empty if not used.
* Some songs might not have a TotalDuration if it is unknown.
For Jukebox Authors: If the song contain a | char (I never seen that), remove that before send the string.
Juke_Command("JUKE_PLAYLIST_CLEAR", "")
Clear the PLAYLIST or QUEUE.
Juke_Command("JUKE_PLAYLIST_CURRENTSONG", NUMBER)
Which song number is curretly in playing from the PLAYLIST?
Queue based jukebox software might not use this command, due to resumbitting. So not all software might use this command, so the default value to this command is 1.
FILE=Juke_Command("JUKE_PLAYLIST_GET", "")
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.
--- End quote ---
I think you are confused what my software considers to be a "playlist".
My software has the ability to let users define their own "playlists" (ex: "Dad's Favorites", "Holiday Music", "Party Songs", etc....) Once defining a playlist name the user can then populate the playlist with album song tracks. Then when the user wants to hear music from a certain playlist, they can select the playlist they want, then select a song from the playlist to play (or simply select all songs in the playlist to play). Once a song is selected, then the song goes into the song queue until it is ready to be played for real.
My playlist files have nothing to do with a song queue at all. They are simply a group of songs in a list which can then be selected to be played.
I think you are trying to use the term "playlist" to implement queues along with queue manipulation. If this is true, then we should put back the "JUKE_QUEUE_xxxx" commands. I changed them to use your "system/user" indicator bit (see below) (I also updated my post with these as well).
JUKE_QUEUE_ADD_SONG (song added to queue by user or system)
system|queuePosNum|name|artist|album|albumNum|trackNum|genre|totalDuration|
JUKE_QUEUE_REMOVE_SONG (song removed from queue by user or system)
system|queuePosNum|
JUKE_QUEUE_MOVE_SONG (song has been moved in the queue by user or system)
system|oldQueuePosNum|newQueuePosNum|
JUKE_QUEUE_CLEARED (the song queue has been cleared by user or system)
system|
JUKE_QUEUE_CHANGED (the song "queue.txt" file has changed)
null
I would use the "queue.txt" file when "multiple" changes have occurred in the song queue at once and will inform the plugin the "queue.txt" file has been changed by sending the "JUKE_QUEUE_CHANGED" command.
When individual song queue entries are added, removed, moved "one at a time" then i will just use the "JUKE_QUEUE_ADD_SONG", "JUKE_QUEUE_REMOVE_SONG" and "JUKE_QUEUE_MOVE_SONG" commands only.
--- Quote ---Juke_Command("JUKE_SONG_PAUSE","")
New song is just started.
Juke_Command("JUKE_SONG_START","")
Current song has been paused.
--- End quote ---
The description of these are assigned to the wrong command. Also, please list these commands next to "JUKE_SONG_FINISHED" since I originally could not find them and thought you deleting them .
Also, I would like to put back the following cmdValue string for the "JUKE_SONG_START" commands:
name|artist|album|albumNum|trackNum|genre|totalDuration
I realize you have a "JUKE_SELECTED_MARKED" command defined which has similiar cmdValue string text, but this command seems like it is only going to be sent when the user highlights a song from a list (but does not choose to play it). Basically, it tells the plugin which song is currently being "looked at" by the user only. When a song is selected to be played, then I would assume you would be expecting the jukebox software to send the "JUKE_SELECTED_MARKED" command followed by a "JUKE_SONG_STARTED" command. This is how you would expect the song information for the current song (title,artist, album, etc ...) to be supplied to the plugin.
However, what happens when a song is selected and it gets put on the queue. When that song finally plays (ie: removed from the queue) then how do you tell the plugin what song has started now? There would be no "JUKE_SELECTED_MARKED" command sent in this case since the user did not mark the song then select it to be played, but rather the song came off of the queue automatically.
--- Quote ---Juke_Command("JUKE_SONG_FASTFWD_START","")
Current song has started being fast forwarded.
(curPosSecs and totalDuration not needed due to JUKE_SONG_PLAY_POSITION and JUKE_PLAYLIST)
Juke_Command("JUKE_SONG_FASTFWD_FINISH","")
Current song has finished being fast forwarded
(curPosSecs and totalDuration not needed due to JUKE_SONG_PLAY_POSITION and JUKE_PLAYLIST)
Juke_Command("JUKE_SONG_FASTREV_START","")
Current song has started being fast reversed
(curPosSecs and totalDuration not needed due to JUKE_SONG_PLAY_POSITION and JUKE_PLAYLIST)
Juke_Command("JUKE_SONG_FASTREV_FINISH","")
Current song has finished being fast reversed
(curPosSecs and totalDuration not needed due to JUKE_SONG_PLAY_POSITION and JUKE_PLAYLIST)
--- End quote ---
I agree the "curPosSecs" and "totalDuration" values are not needed in these commands. I will simply inform the plugin that FastForward/Reverse has started and then periodically send a "JUKE_SONG_PLAY_POSITION" command to indicate the current location. I do not want to send the "JUKE_SONG_PLAY_POSITION" command for every "second" in time which is being fast forwarded/reversed ... that would be way too many commands being sent to quickly. I will send the "JUKE_SONG_PLAY_POSITION" command at perhaps every 10 second interval while the song is being fast forwarded/reversed instead. When the user is finished then I will simply inform the plugin that FastForward/Reverse has finished and then send a "JUKE_SONG_PLAY_POSITION" command again to indicate the current position.
** The only part of your statement I do not understand is what is highlighted in RED below:
"(curPosSecs and totalDuration not needed due to JUKE_SONG_PLAY_POSITION and JUKE_PLAYLIST)"
--- Quote ---Juke_Command("JUKE_VOLUME_SET", "curVolumeLevel|minVolumeLevel|maxVolumeLevel|system")
A new value volume have been set.
If system is set the volume, the last argument would set to one.
--- End quote ---
Will you please put the "system" indicator as the first text string value please?
"system|curVolumeLevel|minVolumeLevel|maxVolumeLevel")
I updated my queue commands to be this way to so now they will all be formatted the same way.
--- Quote ---Juke_Command("JUKE_SELECTED_ALBUM_NUMBER", "NUMBER")
A Album number digit has been entered
Juke_Command("JUKE_SELECTED_TRACK_NUMBER", "NUMBER")
A Track number digit has been entered
--- End quote ---
My album numbers can contain up to 5 digits and my song track numbers can contain up to 3 digits. Every time one "digit" is entered for an album number or track number, then one of these commands will be sent to indicate which "digit" was entered.
As a result, please rename these commands to be:
JUKE_ENTERED_ALBUM_DIGIT
JUKE_ENTERED_TRACK_DIGIT
--- Quote ---Juke_Command("JUKE_SELECTED_SINGLES_NUMBER", "VALUE")
A Single have been selected. It can been both letters and number, like C2.
--- End quote ---
I would assume the term "selected singles" refers to the user selecting a song track to play (by first entering a letter followed by a number), so I would suggest introducing one new command:
JUKE_ENTERED_TRACK_LETTER
No need to introduce the "JUKE_SELECTED_SINGLES_NUMBER" command at all.
--- Quote ---Juke_Command("JUKE_SELECTED_MARKED", "title|artist|album|trackNum|genre|totalDuration")
The user marked song, that is now currectly marked on the screen. TotalDuration might not been used here by a jukebox software.
--- End quote ---
You can use this command to indicate which song has been currently highlighted by the user, but I do not think this means you can remove the "name|artist|album|albumNum|trackNum|genre|totalDuration" information from the "JUKE_SONG_START" command
--- Quote ---Juke_Command("JUKE_KEY_EVENT_SEND", Status)
Status can been value 1 for on and value 0 for off.
--- End quote ---
No idea what this does .... please explain
--- Quote ---EVENT=Juke_Command("JUKE_KEY_EVENT_GET")
A KEY_EVENT is retrieved by the plugin and invoke that command (like a remote controller).
--- End quote ---
No idea what this does .... please explain. There are no parameters defined for this command so what does the plugin do with it?
--- Quote ---Juke_Command("JUKE_FEATURE_ATTRACT_MODE", TRUE|FALSE)
Attract mode feature is enabled (TRUE) or disabled (FALSE)
--- End quote ---
Attract modes are not always ON by default. My software allows the user to enable this or disable this function.
As a result, there should be three values for this command:
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)
headkaze:
--- Quote from: unclet on January 09, 2008, 11:18:23 am ---
headkaze
--- Quote ---There is no need for a trailing "|" at the end of the paramter list
--- End quote ---
Here is my concern .... let me know if this is a real concern or not .... :dunno
Lets say (just for an example) the current JUKE_SONG_START command is defined as follows (without a trailing "|" character):
--- Quote ---JUKE_SONG_STARTED name|artist|album|albumNum|trackNum|genre
--- End quote ---
The currently released plugin would parse the text cmdValue string like this:
--- Quote ---text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre
--- End quote ---
Now, some time in the future the "JUKE_SONG_START" command is updated to include the "totalDuration" value:
--- Quote ---JUKE_SONG_STARTED name|artist|album|albumNum|trackNum|genre|totalDuration
--- End quote ---
The currently released plugin (which does not support this new change) might parse the following way:
--- Quote ---text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre|totalDuration <-- problem
--- End quote ---
It would be bad if the plugin determines the 6th text to be "genre|totalDuration" together.
I believe if we have a trailing "|" character at the end of every cmdValue text string, then
the plugin could simply parse the first 6 text strings (text1->text6) correctly everytime by
only parsing up to each successive trailing "|" character only. This means the plugin would only be parsing out the first 6 text string values only, by looking for 6 "|" separator characters only. If extra text exists beyond the 6th "|" separator character then this text will simply be ignored by the currently released plugin.
This makes updating the cmdValue text for a particular command much easier I would say.
--- End quote ---
Your logic really blows me away on this one.
This would never happen...
--- Quote ---text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre|totalDuration <-- problem
--- End quote ---
Split will split up all the elements in a string using a delimiter (in this case the pipe or "|" symbol). So text6 will always just be "genre" and that is no matter how many more parameters you add.
Say you have
--- Quote ---name|artist|album|albumNum|trackNum|genre
--- End quote ---
And then later decided to add another parameter
--- Quote ---name|artist|album|albumNum|trackNum|genre|totalDuration
--- End quote ---
It's all about the number of elements returned by Split!
If we Split the first string the UBound() will be one less than the UBound() of the second string.
Therefore if we have the number of elements returned we know if the array contains totalDuration or not right?
So why do you need an extra "|" at the end? All this does is mean the number of elements counted by UBound() will be one more. It doesn't make any sense to me why you think a trailing "|" is needed.
Now let me demonstrate by using code
--- Code: ---Dim Args() As String
Args = Split("name|artist|album|albumNum|trackNum|genre", "|")
If (UBound(Args) + 1 = 6) Then
MsgBox "First string doesn't contain totalDuration"
End If
Args = Split("name|artist|album|albumNum|trackNum|genre|totalDuration", "|")
If (UBound(Args) + 1 = 7) Then
MsgBox "Second string DOES contain totalDuration"
End If
--- End code ---
Make sense now?
unclet:
--- Quote ---Make sense now?
--- End quote ---
::) Yes, I fully understand that if a plugin was written in VB and uses "Split()" then it would work fine all the time ...... however, since we can not guarantee what the plugin author is coded in (or perhaps the knowledge base of the plugin author) then I was more wondering whether a trailing "|" character would be better for those cases.
For example, what if a plugin author uses a software language which does not have a "Split()" command and has to parse the cmdValue text string one character at a time from left to right. They might only be expecting 6 text strings to exist so when they encounter the 5th "|" separator character then they might consider the "rest of the string" to be the 6th (final) text string which would be bad since extra text is stuck at the end now.
Just to let you know, this is not really a big deal to me at all, but I was just trying to save some grief if commands are ever expanded. Might never happen so no big deal .... but thought I would throw it out there to discuss. I do not know what the plugin authors are going to code with so not sure whether they have "Split()" commands to use to avoid this problem. If they all can parse using a Split() command then there is no problem at all I agree.
At least hopefully you can see my point .....
headkaze:
--- Quote from: unclet on January 09, 2008, 03:21:00 pm ---
--- Quote ---Make sense now?
--- End quote ---
::) Yes, I fully understand that if a plugin was written in VB and uses "Split()" then it would work fine all the time ...... however, since we can not guarantee what the plugin author is coded in (or perhaps the knowledge base of the plugin author) then I was more wondering whether a trailing "|" character would be better for those cases.
For example, what if a plugin author uses a software language which does not have a "Split()" command and has to parse the cmdValue text string one character at a time from left to right. They might only be expecting 6 text strings to exist so when they encounter the 5th "|" separator character then they might consider the "rest of the string" to be the 6th (final) text string which would be bad since extra text is stuck at the end now.
Just to let you know, this is not really a big deal to me at all, but I was just trying to save some grief if commands are ever expanded. Might never happen so no big deal .... but thought I would throw it out there to discuss. I do not know what the plugin authors are going to code with so not sure whether they have "Split()" commands to use to avoid this problem. If they all can parse using a Split() command then there is no problem at all I agree.
At least hopefully you can see my point .....
--- End quote ---
I see your point, but we can't assume the plugin coder is that stupid. AFAIK All high level languages have a Split type string function anyway. Even standard C has strtok() for example.
http://en.wikipedia.org/wiki/String_functions_(programming)#split
Navigation
[0] Message Index
[#] Next page
[*] Previous page
Go to full version