Plugins: Document API for JukePlugSys

[unclet]

In my code, the Shutdown() routine was being called twice by mistake.  I fix it and the crash went away, but I believe you new changes should be done anyway.   Thanks.

[headkaze]

loadman: You are very close. I added a few extra bits and pieces so it's basically identical to the C++ dll now. Here is the latest plugin with both C++ and Delphi plugin examples.

Code: [Select]

library JukePlugin;

uses
  Dialogs,
  SysUtils,
  Classes;

{$R *.res}

var
PLUGIN_NAME : PChar = 'LCD Display';
PLUGIN_AUTHOR : PChar = 'Loadman';
PLUGIN_VERSION : PChar = 'Beta A';
PLUGIN_DESCRIPTION : PChar = 'This is a plugin';

Buffer: array[0..8192] of Char;

function Juke_Initialize(Value: Integer):Integer; stdcall;
begin
  // Showmessage('DLL has recieved Juke_Shutdown message');
  Result := 1
end;

function Juke_Shutdown(Value: Integer):Integer; stdcall;
begin
  // Showmessage('DLL has recieved Juke_Shutdown message');
  Result := 1
end;

function Juke_GetPluginInfo(Value:integer):PChar; stdcall;
begin
  Result := PChar(PLUGIN_NAME + '|' + PLUGIN_AUTHOR + '|' + PLUGIN_VERSION + '|' + PLUGIN_DESCRIPTION);
end;

function Juke_Command(Name:PChar; Value:PChar):PChar; stdcall;
begin
  StrCopy(Buffer, Value);
  Result := Buffer
end;

exports
  Juke_GetPluginInfo,
  Juke_Initialize,
  Juke_Shutdown,
  Juke_Command;

begin
end.

[unclet]

headkaze
That works ....thanks.   

I came back to tell you the good news and noticed you posted yet another version of the JukePlugin .......     I guess I will upgrade again

[headkaze]

headkaze
That works ....thanks.   

I came back to tell you the good news and noticed you posted yet another version of the JukePlugin .......     I guess I will upgrade again

hehe yeah sorry that should be about it for a while I just wanted to add the corrected Delphi example for loadman. Now he's ready to code his plugin

Space Fractal should post a Power Basic plugin example using the new plugin system, then someone should write up some docs and include a list of the common commands and then your just about ready to release the JPS SDK v1.0.

[unclet]

I still think the command name and value formats need to be agreed on.

Hey, I really can not stand the "|" character since it is hard to read next to characters like "I", "L" and "1" so how about we use the ">" instead as a separator character like I previously recommended? 

Unless the "|" character is some kind of standard.....

[headkaze]

I still think the command name and value formats need to be agreed on.

Hey, I really can not stand the "|" character since it is hard to read next to characters like "I", "L" and "1" so how about we use the ">" instead as a separator character like I previously recommended? 

Unless the "|" character is some kind of standard.....

Geez your picky aren't you unclet? 

Pipe is used alot in cases like this (splitting string values). I would keep it like that

loadman: Just so you know in the Plug_Command() function to return parameters back to the Jukebox you would do this..

Code: [Select]

StrCopy(Buffer, "Value1|Value2|Value3|Value4");
Result := Buffer

That will return Value1, Value2, Value3 and Value 4.

Actually to be on the safe side you probably should change the following also

Code: [Select]

function Juke_GetPluginInfo(Value:integer):PChar; stdcall;
begin
  StrCopy(Buffer, PChar(PLUGIN_NAME + '|' + PLUGIN_AUTHOR + '|' + PLUGIN_VERSION + '|' + PLUGIN_DESCRIPTION));
  Result := Buffer
end;
That is just a cleaner way of doing it.

[loadman]

loadman: You are very close. I added a few extra bits and pieces so it's basically identical to the C++ dll now. Here is the latest plugin with both C++ and Delphi plugin examples.

Mate, It seemed to work but I will do it your way as you know better coding practice 

headkaze
That works ....thanks.   

I came back to tell you the good news and noticed you posted yet another version of the JukePlugin .......     I guess I will upgrade again

I just wanted to add the corrected Delphi example for loadman. Now he's ready to code his plugin

 

ALL:

A big thanks to everyone for hanging in there.   

It got a bit tense and frustrating for a while. 

We seem to be past that and very close to JPS SDK v1.0.   

[unclet]

Here is my proposal for the Command name/value strings:

Note1: The commandName string is first (with a description) and the commandValue string format is underneath

Note2: I decided having separate commands for each function is a lot easier since it allows for one big case statement for processing.   Also too much combining tends to seem like we are craming everything together.  Also, also, I can more easily see what exact command I am sending throughout my code.

Note3: Each commandValue string has a "|" separator character as well as a trailing "|".  The trailing "|" character is required so the plugin can parse the correct number of text strings up to this trailing "|" character only.  As a result, if we expand a commandValue string for a particular command in the future then this will not affect the current released plugins at all since they will simply ignore the extra text we added to the commandValue string.

Note4: I do not believe the plugin needs to know what commands are supported by specific jukebox software.  Based on the generic commands listed, I believe the plugin can decide what they want to implement or not. 



CONFIGURE COMMAND
---------------------------------------------------------------------------
JUKE_PLUGIN_CONFIGURE
null


APPLICATION COMMANDS
---------------------------------------------------------------------------
JUKE_APP_OPENED
null

JUKE_APP_CLOSED
null



CURRENT PLAYING SONG COMMANDS
---------------------------------------------------------------------------
JUKE_SONG_START (new song has started playing)
name|artist|album|albumNum|trackNum|genre|totalDuration|

JUKE_SONG_FINISH (current song has finished)
null

JUKE_SONG_RESTART (current song has been restarted)
null

JUKE_SONG_SKIP (current song has been skipped)
null

JUKE_SONG_PAUSE (current song has been paused)
null

JUKE_SONG_RESUME (current song has been resumed from pause state)
null

JUKE_SONG_FASTFWD_START (current song has started being fast forwarded)
null

JUKE_SONG_FASTFWD_FINISH (current song has finished being fast forwarded)
null

JUKE_SONG_FASTREV_START (current song has started being fast reversed)
null

JUKE_SONG_FASTREV_FINISH (current song has finished being fast reversed)
null

JUKE_SONG_PLAY_POSITION (the number of seconds into the current song)
curPosSecs|totalDuration|



QUEUE COMMANDS
---------------------------------------------------------------------------
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




VOLUME COMMANDS
---------------------------------------------------------------------------
JUKE_VOLUME_CHANGE (volume has been changed by user or system)
system|up/down|curVolumeLevel|minVolumeLevel|maxVolumeLevel|

JUKE_VOLUME_MUTE (volume mute has been turned on/off)
on/off|



ENTER DIGIT COMMANDS
---------------------------------------------------------------------------
JUKE_ENTER_ALBUM_NUM_DIGIT (album number digit has been entered)
digit(0-9)|

JUKE_ENTER_TRACK_NUM_DIGIT (track number digit has been entered)
digit(0-9)|



FEATURE COMMANDS
---------------------------------------------------------------------------
JUKE_FEATURE_ATTRACT_MODE (attract mode feature is enabled/disabled)
active/notActive|

JUKE_FEATURE_PARTY_LOCK (party lock feature is enabled/disabled)
enabled/disabled|



NAVIGATION COMMANDS
---------------------------------------------------------------------------
JUKE_NAVIGATE_QUEUE (navigating song queue is occurring)
up/down/left/right|

JUKE_NAVIGATE_ALBUM_TRACK_LIST (navigating album track list is occurring)
up/down/left/right|

JUKE_NAVIGATE_ALBUM_COVER_PAGE (going to next album cover page)
up/down/left/right|

JUKE_NAVIGATE_ALBUM_COVER_SELECT (selecting an album cover on current page)
null

JUKE_NAVIGATE_PLAYLIST (navigating playlists are occurring)
up/down/left/right|

JUKE_NAVIGATE_PLAYLIST_TRACK_LIST (navigating playlist tracks are occurring)
up/down/left/right|

[Space Fractal]

Hehe, I use Pure Basic to creating dlls, not Power Basic. Pure Basic is a powerfull api.

We could define a basic standard command sets we know all software have, but still been available to use commandsend argument to send extra unique commands trouch Juke_Config(), like these action buttons?

I think I doesent want to explain what these action buttons does, if I have full controls over that used using comandSend(), but I could use the above to doing that.

I create a full plug-in example using these commands later, today or tomorrow (using the sound example).

I looking about Queue.txt later, but by now get the other things work first !!


These commands does not exists is mine software, instead they can been used to send as extra commands like I said above, using commandlist$:

 JUKE_QUEUE_USER_MOVE_SONG
 JUKE_SONG_FASTFWD_START
 JUKE_SONG_FASTFWD_FINISH
 JUKE_SONG_FASTREV_START
 JUKE_SONG_FASTREV_FINISH
 JUKE_SONG_PLAY_POSITION

JUKE_SONG_START does not need any argument about songinfo.. allready got it using queue.txt or such that?

QUEUE:
 JUKE_QUEUE_CHANGED
 JUKE_QUEUE_CLEARED

these are all as needed for the plugin to know the queue is changed.. Extra commands should then removed and goes as extra unique commands intead.


 JUKE_SYSTEM_VOLUME_CHANGE and JUKE_USER_VOLUME_CHANGE can been joined into one command:
 JUKE_VOLUME_CHANGE?

  Does the plug need that info, if it system or user that changed to volume?

ENTER DIGIT COMMANDS:
 only used in MultiJuke in Jukebox GUI. I think it should been removed and use them as a extra unique commands?


FEATURE:
 JUKE_FEATURE_PARTY_LOCK is not standard of all software. again, can use as sending to commandlist$ as extra commands to the plugin?


JUKE_QUEUE_CHANGED can also been used as a command as seen..

NAVIGATION:
I haven't have any of these commands.

These commands should been removede from the default sets, but istead using commandsend$ as extra unique commands?

[unclet]

headkaze
About the two way communication thing....... I assumed the plugin would be able to send a command to the jukebox software.  For instance, if the plugin wanted to skip the current playing song then the plugin could send a "JUKE_SONG_SKIP" command to the jukebox software. 

I am not sure how you recommendation of a timer would work.   When the plugin wants to inform the jukebox to skip the current playing song, then what does the plugin need to do?  Does the plugin have to somehow remember that a "skip request" should be sent, so when the jukebox's 200ms timer expires and it sends a "JUKE_READ_INPUT" command to the plugin then the plugin can then return the "skip text"?  This sounds odd, so please explain how this would work from the plugin side please.

[unclet]

My goal is NOT to simply come up with a list of commands which ALL software can use, but to define a standard set of commands which MIGHT be used by some software.  If some jukebox software does not use one of these commands, then no big deal .... that software will simply not send the command to the plugin.   However, the command can still be standardized for other software to use if required.  Standardization is my main goal, not simply trying to find a subset of commands which everyone wants to use for sure.

Space Fractal
In your example of mapping a sound to a command, the plugin author will put any of these commands they want into the listbox to have sound files be mapped to any of them they want.  If your software does not support some of these commands then the sounds which are mapped to these commands (if any) will never be heard since your software will never send these commands in the first place.  This is what I mentioned earlier.   I do not think it is important to have a plugin only list the commands which a specific software uses ..... the plugin can list all the commands and allow the user to map sounds to them, but if you software does not support certain commands then some of those sounds will just not be heard.   Which should be fine since your software does not support those commands in the first place.   How will the user of the jukebox software know which commands are related to your software?   The user should know how your software works before trying to set up plugins for it, so they should understand what commands are relevant or not.   I also intend to add a button on my plugin page that when clicked will display a description of which plugin commands my software supports along with a description of the command as it relates to my software.  The user has to know what they want to configure before they actually do it .. right?

These commands does not exists is mine software, instead they can been used to send as extra commands like I said above, using commandlist$:

 JUKE_QUEUE_USER_MOVE_SONG
 JUKE_SONG_FASTFWD_START
 JUKE_SONG_FASTFWD_FINISH
 JUKE_SONG_FASTREV_START
 JUKE_SONG_FASTREV_FINISH
 JUKE_SONG_PLAY_POSITION

If these do not exist then simply do not send them.  No need to remove them since these are general enough commands which could be used by anybody's software whch has this capability.  It is not a bad thing to have commands defined which are not used by some software.

JUKE_SONG_START does not need any argument about songinfo.. allready got it using queue.txt or such that?

I can not implement a "queue.txt" file since in my software the user can move songs around in the queue and after each "move" request I would need to rewrite the entire "queue.txt" file.    So if the user wants to move a song from position 20 to position 1 in the queue, this occurs one queue position at a time, so that would mean the software would generate 20 "queue.txt" files in a row to always keep the queue file up to date.   Not real interested in doing it this way.

Now there is nothing wrong with having a standard to provide queuing information in two different ways, which is what I think shold probably happen here.  The plugin can get the complete queue contents by reading the queue.txt file or can get the information one command at a time.

Come to think of it I have an option where a bunch of selected songs can be randomly inserted into the queue, thus making the order of the songs all change at once.  I might end up using the "queue.txt" file in this one case, but use the other commands (one at a time) for other cases.

BTW:  If the software is idle and a song is started, do you first enter the song into the queue even though it can be played right away?  If you do not enter it into the queue first then how will the "queue.txt" file help you get the song information for the song?

QUEUE:
 JUKE_QUEUE_CHANGED
 JUKE_QUEUE_CLEARED

these are all as needed for the plugin to know the queue is changed.. Extra commands should then removed and goes as extra unique commands intead.

If you are going to use the "queue.txt" file all the time then I agree, but I can not do this (see above).

JUKE_SYSTEM_VOLUME_CHANGE and JUKE_USER_VOLUME_CHANGE can been joined into one command:
 JUKE_VOLUME_CHANGE?

  Does the plug need that info, if it system or user that changed to volume?

Yes then can be joined but I prefer individual commands for each action.  It just seems cleaner instead of trying to crame everything together.  We can make as many commands as we need!

I believe it might be useful for a plugin to know whether the volume has been "increased" or "decreased" in case someone wants to do something with LED lights perhaps.   The other case is when the system simply changes the volume to a certain level by itself (like volume normalization for each song ..... which I might start thinking about).

ENTER DIGIT COMMANDS:
 only used in MultiJuke in Jukebox GUI. I think it should been removed and use them as a extra unique commands?

My software offers the user the ability to manually enter album number and track number digits in order to select a song.  Actually my kids have some album number and track numbers memorized so they go over to the juke and enter their favorite song all the time this way.   Again, having commands defined which are not being used by some software is allowed.  Your software will simply not send these commands, but at least we can define a standard for the software who wants to send them.

FEATURE:
 JUKE_FEATURE_PARTY_LOCK is not standard of all software. again, can use as sending to commandlist$ as extra commands to the plugin?

Again, having commands defined which are not being used by some software is allowed.  Your software will simply not send these commands, but at least we can define a standard for the software who wants to send them.

JUKE_QUEUE_CHANGED can also been used as a command as seen..

Not sure what this means....

NAVIGATION:
I haven't have any of these commands.

These commands should been removede from the default sets, but istead using commandsend$ as extra unique commands?

Then there is no need for your software to use them, but at least we can define a standard for the software who wants to send them.

[Space Fractal]

can we not use both the works, so the plugin get full list if not defined in this list.

I update the SDK soon to sync very much here.

I could maybe drop the Juke_Init(WINDOW_ID, command$) and instead something like this:

JUKE_UNIQIE_COMMAND(ACTION_BUTTON_1|CREATE) bofore juke_config().

arguments would can then allways only been ON OFF and CREATE, and then the plugin can find extra commands in the list.

When I like to send the new command, this can been done simple use ON or OFF instead of CREATE (like JUKE_UNIQIE_COMMAND(ACTION_BUTTON_1|ON)

queue.txt can also been removed completly and replace with a command:

JUKE_QUEUE_LIST(PLACE, songs....) instead when some things in queue is manipulated? Beware, some song titles might been UTF8 for unicode support, so russia and other languages can been supported. UTF8 is backward combatible with ASCII.

| should been used as a seperator, because I havent se strings using this seperator.



ETC I change the SDK to suit these soon....

[unclet]

The code provided by headkaze has really one main function defined which is used to send stuff to the plugin:

Public Function Command(cmdName As String, cmdValue As String) As String()

I am simply trying to standardize the "cmdName" and "cmdValue" interface parameters to this routine only.    This means trying to create a set of generic command names (ie: cmdName) as well as defining what string values (ie: cmdValue) is required for the commands.

I am not really thinking about trying to remove a bunch of these commands and try to send them to the plugin using another routine.  This one routine seems like it is suitable to send anything to the plugin, we just need to define a standard set of commands to pass to it.



Regarding your "ACTION button" stuff ...... I am assuming when an action button is pressed then some event happens.   Based on this event why cant you send the appropriate command to the plugin using the Command(cmdName As String, cmdValue As String) routine.   If the event you are doing is not in my list, lets add another command to my list to cover that case for your software.   Perhaps you can list all the commands you would like to send to the plugin from your software and they we can simply define more commands in my list to make sure all your events are covered.

[headkaze]

unclet

There is no need for a trailing "|" at the end of the paramter list

Mate, It seemed to work but I will do it your way as you know better coding practice 

The main problem with your code is you were using "," instead of "|" to return arguments so all the Plugin Info was stored in the "Name" variable

Also you should definately use a global buffer when returning a string pointer (in fact don't forget the little snippet for changing Plug_GetPluginInfo() to use a buffer). Ie. Sending a PChar as a return value of a temporary variable is a no no.

About the two way communication thing....... I assumed the plugin would be able to send a command to the jukebox software.  For instance, if the plugin wanted to skip the current playing song then the plugin could send a "JUKE_SONG_SKIP" command to the jukebox software.

No the Jukebox can't send a command to the Jukebox software. A plugin is just a host, it can only return values from a call to one of it's functions.

I am not sure how you recommendation of a timer would work.   When the plugin wants to inform the jukebox to skip the current playing song, then what does the plugin need to do?  Does the plugin have to somehow remember that a "skip request" should be sent, so when the jukebox's 200ms timer expires and it sends a "JUKE_READ_INPUT" command to the plugin then the plugin can then return the "skip text"?  This sounds odd, so please explain how this would work from the plugin side please.

Okay it would work like this, set up a Timer with an interval of say 200 milliseconds.

In the Juke software...

Code: [Select]

Timer_Elapsed()
{
   Plugin_Command("JUKE_TIMER", null);
}
In the plugin

Code: [Select]

string Juke_Command(string Name, string Value)
{
    switch(Name)
   {
      case "JUKE_TIMER":
         if(bSkipCurrentSong == true)
         {
            bSkipCurrentSong = false;
            return "JUKE_SKIP_SONG";
         }
   }
}
This is a very basic example but if the plugin software sets bSkipCurrentSong = true, then next 200 milliseconds the Jukebox software calls the JUKE_TIMER command the plugin will return the "JUKE_SKIP_SONG" command back to the Jukebox software. Now the Jukebox software skips the song. In 200 millisecond calls it will be pretty much immediately so you won't notice any delay when the plugin sends back a command.

[loadman]

The main problem with your code is you were using "," instead of "|" to return arguments so all the Plugin Info was stored in the "Name" variable

I knew that 

Also you should definately use a global buffer when returning a string pointer (in fact don't forget the little snippet for changing Plug_GetPluginInfo() to use a buffer). Ie. Sending a PChar as a return value of a temporary variable is a no no.

I could get 'burnt' one day could I depending on what size and for the string was? So the Buffer it just to make sure what I return back is Legal?

[headkaze]

I could get 'burnt' one day could I depending on what size and for the string was? So the Buffer it just to make sure what I return back is Legal?

It's nothing to do with the size of the string the problem is were returning a PChar (char pointer) to a local variable. That local variable is just that, local to the function and once the Jukebox software returns from the function call you can't be guaranteed the memory where that PChar was pointing to will still be available. Having that global buffer and copying strings into it then returning a PChar to the buffer is no problem because we know it will be around for the life of the plugin.

[Space Fractal]

only standard define set should been defined, that cover all software.

otherwise we have many unused commands, that might only to been used in one single software. That is not a global standard. A  singles based Jukebox software have other set of commands to control response (LETTER and NUMBERS). Should we cover them too?

The main problem is NOT the queue and playing based commands, but its ONLY with CONTROLS based commands, that allways is defficent by various software.

CONTROLS is the main reason for various software out here, so of course they are all diffecent. So we can't cover them all here.

I can also accept SCREENSAVER example can named something other and such that thing. they are not CONTROLS.


So I think these 3 is needed for CONTROL based plugins (to feed a sample plugin) before config:

JUKE_CONTROL_CREATE|ACTION_BUTTON_1


to use them:

JUKE_CONTROL_SEND|ACTION_BUTTON_1|ON) <- can been ON or OFF (LedWiz).

and

JUKE_CONTROL_GET <- If a user pressed a key on a remote control.


And then it would cover all controls used (also ONLY controls based commands, think as user with a remote control) and I would been fine.


The sdk is changed to only use these 4 functions, headkaze gave. Later I list the defined commands (that is not controls based). I out now, and update the list when I went home.

[unclet]

only standard define set should been defined, that cover all software.

I do not agree.   We should be able to define a "generic" standard for something even if only one jukebox software requires it.   Think about it..... standards are usually created before anyone uses the SDK at all.  Lets take the Visual Basic SDK ..... when they were creating the SDK, then defined many routines before anyone used them at all.   Perhaps no one would use the routines once released as well, but at least they defined a generic set of routines in the SDK.   

I am not saying we should define a command which we know no one is currently using .... that would be a waste of time, but if only one jukebox software requires something then yes, I believe we should define a standard for it.

otherwise we have many unused commands, that might only to been used in one single software. That is not a global standard.

That is true, many unused commands might exist but the software will only send those commands which it supports so it should not matter how many extra commands are defined in the standard at all.   

Also, I do think a "global standard" can exist without "all" software using "all" commands.  It makes no sense to me that you think all software needs to use all commands before you consider it a global standard.   Again, take the Visual Basic SDK example I gave above ..... this "global standard" exists and not all Visual Basic software projects use "all" the commands defined it there ... right?

A  singles based Jukebox software have other set of commands to control response (LETTER and NUMBERS). Should we cover them too?

If one of our jukebox software application uses this then yes, I think we should spend time defining a generic standard for it.  This way whenever a new jukebox developer comes along and wants to support plugins they can use our standards which we defined now.   

Again, if we worked for a company which was in charge of defining a complete standard for a jukebox SDK then we would be trying to standardized everything a jukebox software could "possibly" do ...... but since we are just a few people trying to introduce plugins to our software right now, lets just define standards for the commands which are used by at least one of our software applications only.   Defining stuff which is not used by any of our software at this point would be a waste of time right now.

The main problem is NOT the queue and playing based commands, but its ONLY with CONTROLS based commands, that allways is defficent by various software.

CONTROLS is the main reason for various software out here, so of course they are all diffecent. So we can't cover them all here.

Well we should be able to add more cmdName and cmdValue strings to cover what you need but you are not really ever telling us exactly what your control button do so we can not help you out here.   I keep asking what your ACTION button stuff really mean but you have not let me know that yet.so I really can not help you yet.

Now, possibly we can define some cmdName strings like the following for your softeare to use:

JUKE_ACTION_BUTTON_1
JUKE_ACTION_BUTTON_2
JUKE_ACTION_BUTTON_3
JUKE_ACTION_BUTTON_4

I can also accept SCREENSAVER example can named something other and such that thing. they are not CONTROLS.

Not real sure you need to group certain commands as "controls" or not.   Just define the appropriate set of cmdName/cmdValue strings for what you need and then send the command to the plugin when the event occurs.

So I think these 3 is needed for CONTROL based plugins (to feed a sample plugin) before config:

JUKE_CONTROL_CREATE|ACTION_BUTTON_1


to use them:

JUKE_CONTROL_SEND|ACTION_BUTTON_1|ON) <- can been ON or OFF (LedWiz).

and

JUKE_CONTROL_GET <- If a user pressed a key on a remote control.


And then it would cover all controls used (also ONLY controls based commands, think as user with a remote control) and I would been fine.

I have no idea what you are trying to do here ... sorry.   

[Space Fractal]

See the changed SDK.

I have now changed the SDK to nearly have your system now, I think is very good.

I have just changed few commands, removed few uneeded arguemtns, and added some other commands as well.

queue.txt is also removed and replaced with some PLAYLIST commands. Hope you like it. There is also some changes about the song info here too.


The major problem about controls using your and mine vision is replaced with KEY EVENT, which i explain what it does:

The whole main problem about various commands we talk very much about is been changed to just use KEY_EVENT, which I guess is a good workaround and a comprimes.

I can see on your UncleT Jukebox homepage, there is overer 70 key mappings provided in your software. It them that have been the the whole point in my Plugin Vision, and it only them, I might have interesed using these KEY_EVENT to been used for some plugins, like sound, ledwiz and others uses.

MultiJuke is a button based jukebox software, where KEY_EVENT would been very strong for the PlugIn. Of course I would let a plugin to use all KEY_EVENTS I have in my software (all buttons) to been controlled. Here KEY_EVENT is a major use.

This is includning Action buttons I have in my software:  They are no other than a user KEY_EVENT, also a user keypress to invoke some command in my Jukebox.....

So I think KEY_EVENT is the right word to use?

Because of that, I removed all navigations commands you have, I removed from the SDK. But use the power of KEY_EVENT commands for these navigation commands (like I would due in MultiJuke).

[unclet]

headkaze .... please answer this for me

There is no need for a trailing "|" at the end of the paramter list

Here is my concern .... let me know if this is a real concern or not .... 

Lets say (just for an example) the current JUKE_SONG_START command is defined as follows (without a trailing "|" character):

JUKE_SONG_STARTED      name|artist|album|albumNum|trackNum|genre

The currently released plugin would parse the text cmdValue string like this:

text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre

Now, some time in the future the "JUKE_SONG_START" command is updated to include the "totalDuration" value:

JUKE_SONG_STARTED        name|artist|album|albumNum|trackNum|genre|totalDuration

The currently released plugin (which does not support this new change) might parse the following way:
 

text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre|totalDuration  <-- problem

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 and would not affect existing plugins which have been released. 

What do you think? 

[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]

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.

Nice solution !      

Please rename "COMMAND_NAME" to be "KEY_EVENT_NAME" in the documentation though

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

Juke_Command("JUKE_APP_HOST","SOFTWARE NAME", "UNICODE")
The Jukebox software name.

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

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.

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.

Juke_Command("JUKE_SONG_PAUSE","")
New song is just started.

Juke_Command("JUKE_SONG_START","")
Current song has been paused.

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.

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)

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

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.

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.

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

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

Juke_Command("JUKE_SELECTED_SINGLES_NUMBER", "VALUE")
A Single have been selected. It can been both letters and number, like C2.

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.

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.

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

Juke_Command("JUKE_KEY_EVENT_SEND", Status)
Status can been value 1 for on and value 0 for off.

No idea what this does .... please explain

EVENT=Juke_Command("JUKE_KEY_EVENT_GET")
A KEY_EVENT is retrieved by the plugin and invoke that command (like a remote controller).

No idea what this does .... please explain.  There are no parameters defined for this command so what does the plugin do with it?

Juke_Command("JUKE_FEATURE_ATTRACT_MODE", TRUE|FALSE)
Attract mode feature is enabled (TRUE) or disabled (FALSE)

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]

headkaze

There is no need for a trailing "|" at the end of the paramter list

Here is my concern .... let me know if this is a real concern or not .... 

Lets say (just for an example) the current JUKE_SONG_START command is defined as follows (without a trailing "|" character):

JUKE_SONG_STARTED      name|artist|album|albumNum|trackNum|genre

The currently released plugin would parse the text cmdValue string like this:

text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre

Now, some time in the future the "JUKE_SONG_START" command is updated to include the "totalDuration" value:

JUKE_SONG_STARTED        name|artist|album|albumNum|trackNum|genre|totalDuration

The currently released plugin (which does not support this new change) might parse the following way:
 

text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre|totalDuration  <-- problem

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.

Your logic really blows me away on this one.

This would never happen...

text1=name
text2=artist
text3=album
text4=albumNum
text5=trackNum
text6=genre|totalDuration  <-- problem

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

name|artist|album|albumNum|trackNum|genre

And then later decided to add another parameter

name|artist|album|albumNum|trackNum|genre|totalDuration

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: [Select]

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
Make sense now?

[unclet]

Make sense now?

   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]

Make sense now?

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

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

[unclet]

Sounds good to me then ...... 

[Space Fractal]

KEY_EVENT:

correct. KEY_EVENT_COIN_INSERT is also just a another event too.

Few commands might been in disabled status, because example ACTION_BUTTON_2 and above is not allways used and can been disabled. Hence I could send it a OFF argument to example a LedWiz device.

Hence I might need to send a Juke_Command("ACTION_BUTTON_3",OFF) and Juke_Command("ACTION_BUTTON_3",ON).

But for all other commands, A empty "" would been sendt.



SELECTED ALBUM:

Juke_Command("JUKE_MARKED_ALBUM", "NUMBER")
Juke_Command("JUKE_MARKED_TRACK", "NUMBER")

I have changed the command into marked album. The value can been anything, both letters and value. The user can configurere the plugin anyway, how it should been used.

When they begin to enter a new digit or letters, just send the command again with the new value. Something like this:

1
12
125

On this way, a plugin better can understand how many digits and or letters the user actuelly have inserted. What about if they deleted a digit again, just send the new value again with a digit fewer, like 12.

So JUKE_ENTERED_ALBUM_DIGIT and JUKE_ENTERED_TRACK_DIGIT is both KEY_EVENTS. So KEY_EVENTS like JUKE_DIGIT_0 and so on is a better idea?


PLAYLIST:

I should rename to CURRENT_PLAYLIST?

Freebox have PlayNow and PlayNext command. MultiJuke have only PlayNext and can auto submit a album to been played finished.

I Dislike to have a command to every type of manipulation. Instead is much simply to just resubmit songs again at once after that arcour!!

For your software, that is Queue Based, your have NO use of JUKE_CURRENT_PLAYLIST_CURRENTSONG, as I have no use for that command in MultiJuke. So skip that command. I just think the command can been used with software that using PLAYLIST instead of QUEUE based.

So, Simply resubmit the current queue list to CURRENT_PLAYLIST when some Queue Event have been invoked so the first song is allways os that is song in playing.


Juke_Command("JUKE_FEATURE_ATTRACT_MODE", TRUE|FALSE)

just send this command in your init rutine to your Jukebox Software to statement if its true of False.if its off, it false... 

Personly as plugIn Writer I dosen't care how it was invoked. They can detect it other way (example checking if a song is playing using song playing commands), if they want to know that.


Juke_Command("JUKE_SELECTED_MARKED", "title|artist|album|trackNum|genre|totalDuration").

They can get it with checking the CURRENT_PLAYLIST commands.....


Rest is explanied and corrected in the SDK. They was some minor errors from my side.

EDIT: More errors and few commands change, so they hopefully better understand.


About the | char.

I have no problems with | at all!! In Pure basic I might just add a anoter | if there was no Split command. This make sure it find the last |.

[Barry Barcrest]

WOW Guys you have really made some advances since i last looked. I assume once you make the SDK availble i will be able to see what functions are possible for the jukebox plugins to use. I will hold off adding the latest code until i know what i can expect to be in the plugins and i will just bolt it all in at the same time.

Glad everyone got it sorted you have all put a lot of hard work into this. Me i've just been a pain LOL 

[Space Fractal]

Should we say a deadline to Sunday 20 Januar to make sure all got the time to support these commands, and then send a new to Saint to been displayed on the frontpage to due a simulation release with plugin support?

That Even it mostly was Me and UncleT that defined the standard with help and input from LoadMan (that started that all) and HeadKaze? But I still say thanks for your input, Barcrest.

This standard is for all software, and it of course also for Freebox. Fell free to add it of course.

Glad to release the SDK soon, even it was a really hard work and used alots of time monitor this forum.

It just few issues left and until UncleT and I understand the all issues. But it small issues now, the major problems is now gone.

[headkaze]

Should we say a deadline to Sunday 20 Januar to make sure all got the time to support these commands, and then send a new to Saint to been displayed on the frontpage to due a simulation release with plugin support?

That Even it mostly was Me and UncleT that defined the standard with help and input from LoadMan (that started that all) and HeadKaze? But I still say thanks for your input, Barcrest.

This standard is for all software, and it of course also for Freebox. Fell free to add it of course.

Glad to release the SDK soon, even it was a really hard work and used alots of time monitor this forum.

It just few issues left and until UncleT and I understand the all issues. But it small issues now, the major problems is now gone.

What is this SDK you keep speaking of? I thought JukePlugin.zip was the SDK 

And there is still no PureBasic example in there, so how you say you defined the standard is beyond me.

[loadman]

WOW Guys you have really made some advances since i last looked. I assume once you make the SDK availble i will be able to see what functions are possible for the jukebox plugins to use. I will hold off adding the latest code until i know what i can expect to be in the plugins and i will just bolt it all in at the same time.

Glad everyone got it sorted you have all put a lot of hard work into this. Me i've just been a pain LOL 

Welcome back   

For the SDK do you need an example of the host or plug-in in another language?

[loadman]

What is this SDK you keep speaking of? I thought JukePlugin.zip was the SDK 

I think he meant 'host' the SDK (I could be wrong)?
Thanks again HeadKaze for your work on that. I have been also learning some good programming tips (in general) along the way. Over all this has been a good experience for me.   

And there is still no PureBasic example in there, so how you say you defined the standard is beyond me.

Yes if you could make one that would be good please Space Fractal

[Space Fractal]

The very first post of course I have changed over the past.

I waiting to create Pure Basic example when the "SDK" is finished with all defined commands.

The SDK is NOT the wrapper I wrote in the other thread, that is now completly "out of date" (hence removed).

the SDK is the FIRST post only where all defined commands is there. I have changed the orignal post over the time, because I think the post is the easier to find the commands used, because this thread is pretty big now (I never throuch it should been so big).

The most commands is now by UncleT and I changed some and added few others.

It is now heavy changed to only use 2 functions, the rest is just string commands and have a argument to been parsed by the plugins. In this way it easy to add commands to a v1.1 later time.

I do pretty sure I should use my time to add plugin Support to MultiJuke first, and then writing a real Pure Basic plugin example how the parser can work with source. I do update the "wrapper" soon to use with these 2 commands used + some helper functions for those that want it.

I also of course want examples by other language, C++ and/or Visual Basic 6 of course. I can put them in a file in the first post to checking out.

I did not say I defined the SDK (sorry if I wrote that), most should go to UncleT now for his ideas and I finally accepted. Of course big credits should got to all of you in this thread: headkaze, LoadMan and also Barcrest.

[loadman]

OK I think the issue here is what a SDK is?

I define a Software Development Kit to be a combination of two things.

1) A document telling how to use it and all the commands/functions.

* I Imagine that this will be heavily based on your first post Space?

2) Basic software examples and tools in as many languages as possible.

* HeadKaze has already (kindly) provided most of this (it may need updating) with a VB6 host and C++ and Delphi Plug-in examples. This will need Pure Basic example from Space Fractal as he has changed the examples he first posted.  More languages would be nice too

Are we all on the same page here ? 

[Edit] for the record. HeadKaze's next post came a microsecond after mine   

As for credits. I would suggest that we just have a list a name of the people involved. No need to measure the input of each person or waht there role is. Who cares? 


 

[headkaze]

The very first post of course I have changed over the past.

I waiting to create Pure Basic example when the "SDK" is finished with all defined commands.

The SDK is NOT the wrapper I wrote in the other thread, that is now completly "out of date" (hence removed).

the SDK is the FIRST post only where all defined commands is there. I have changed the orignal post over the time, because I think the post is the easier to find the commands used, because this thread is pretty big now (I never throuch it should been so big).

The most commands is now by UncleT and I changed some and added few others.

It is now heavy changed to only use 2 functions, the rest is just string commands and have a argument to been parsed by the plugins. In this way it easy to add commands to a v1.1 later time.

I do pretty sure I should use my time to add plugin Support to MultiJuke first, and then writing a real Pure Basic example how the parser can work with source.

I also of course want examples by other language, C++ and/or Visual Basic 6 of course. I can put them in a file in the first post to checking out.

I did not say I defined the SDK (sorry if I said that), most should go to UncleT now for his ideas and I finally accepted. Of course big credits should got to all of you in this thread: headkaze, LoadMan and also Barcrest.

All an SDK (Software Development Kit) is two things; source code and documentation. So when your referring to the SDK you must be referring the command list which is part of the documentation. Okay I get it now!

EDIT: Loadman beat me to it! 

[Space Fractal]

Sorry if I misused SDK. Dont take the serious for a typo and misuse. Please. Let us do this finish instead instead using time with this. I should of course wrote "The API document" instead. You know you might should guessed what I really would  wrote  . It does turn into a SDK sooner or later anyway.

[loadman]

Sorry if I misused SDK. Dont take the serious for a typo. I should of course wrote "The API document" instead. You know you might should guessed what I really would  wrote  .

Cool. Just making sure we ALL had the same understanding of what it is (two elements to a SDK) 

And yes I'm half asleep so making many typos.. 

[unclet]

SELECTED ALBUM:

Juke_Command("JUKE_MARKED_ALBUM", "NUMBER")
Juke_Command("JUKE_MARKED_TRACK", "NUMBER")

I have changed the command into marked album. The value can been anything, both letters and value. The user can configurere the plugin anyway, how it should been used.

When they begin to enter a new digit or letters, just send the command again with the new value. Something like this:

1
12
125

On this way, a plugin better can understand how many digits and or letters the user actuelly have inserted. What about if they deleted a digit again, just send the new value again with a digit fewer, like 12.

This is a good idea but I really dislike the "JUKE_MARKED_ALBUM" and "JUKE_MARKED_TRACK" commands names.   Entering digits one by one has nothing to do with "marking" album numbers or "marking" track numbers.

Lets keep your idea, but change the command names to "JUKE_ENTER_ALBUM_VALUE" and "JUKE_ENTER_TRACK_VALUE"

So JUKE_ENTERED_ALBUM_DIGIT and JUKE_ENTERED_TRACK_DIGIT is both KEY_EVENTS. So KEY_EVENTS like JUKE_DIGIT_0 and so on is a better idea?

Yes, we can send each individual entered digit and letter as a unique key event (if desired). So when the user enter's an album number (1234), then this is the sequence of events which are sent (if you support the key events of course) ....

JUKE_KEY_EVENT_DIGIT_1
JUKE_ENTER_ALBUM_VALUE 1
JUKE_KEY_EVENT_DIGIT_2
JUKE_ENTER_ALBUM_VALUE 12
JUKE_KEY_EVENT_DIGIT_3
JUKE_ENTER_ALBUM_VALUE 123
JUKE_KEY_EVENT_DIGIT_4
JUKE_ENTER_ALBUM_VALUE 1234

Do you agree?


***  I recommend we make a standard that all key event commands start with the "JUKE_KEY_EVENT_xxxxxx" text.   This way I can see exactly what is going on in my code and realize these commands are for the plugin.

PLAYLIST:

I should rename to CURRENT_PLAYLIST?

This statement by itself has no meaning to me.  Could you possibly explain yourself a bit more.   

Freebox have PlayNow and PlayNext command. MultiJuke have only PlayNext and can auto submit a album to been played finished.

You tell me that FreeBox has "PlayNow" and "PlayNext" but I have no idea in the world what those features mean so I have no idea what you are trying to tell me.

I dislike to have a command to every type of manipulation. Instead is much simply to just resubmit songs again at once after that arcour!!

Well I need to have queue commands to inform the plugin how the queue is managed.

I have a song queue which can hold 1000 songs.  If one song is removed, I do not plan on informing the plugin about 999 other songs by resubmitting each individual song one at a time.  I would simply inform the plugin which queue position was removed and it will be up to the plugin to realize all other songs below this removal position gets moved up one position.   

Same thing will occur when the user selects a song to play and it is inserted into the song queue at "random" (this is a feature which can be used).   When this occurs I would simply tell the plugin about the one song that was inserted and the position at which is was inserted in to the queue.

Now, for multiple song queue changes which occur at the same time (ex: adding 25 song tracks to the song queue at one time at random) then I would populate the "queue.txt" file to inform the plugin about the complete new queue contents.  This would be easier than sending 25 "JUKE_QUEUE_ADD_SONG" commands to the plugin I think.

For your software, that is Queue Based, your have NO use of JUKE_CURRENT_PLAYLIST_CURRENTSONG, as I have no use for that command in MultiJuke. So skip that command. I just think the command can been used with software that using PLAYLIST instead of QUEUE based.

So, Simply resubmit the current queue list to CURRENT_PLAYLIST when some Queue Event have been invoked so the first song is allways os that is song in playing.

I do not know the difference between a jukebox which is PLAYLIST based and a jukebox which is QUEUE based?  What is the difference?  Actually what is your definition of "PLAYLIST" and how "exactly" does your jukebox use it?

My jukebox allows the user to create personal "playlist" lists and my software also maintains a song "queue".  So my software used BOTH playlist and queue functions.

Here are my definitions of playlist and queues.  You will notice they are NOT related to each other at all.

QUEUE:  This is a song queue in which songs the user has selected for playing are stored until they can be played.

PLAYLIST: A list of songs from multiple albums and artists which the user can group together into one list (ex: Dads Favorites, Holiday Songs, etc...).   The songs listed in a "playlist" can then be selected to be played.

I need some way of informing the plugin about how my soing QUEUE changes and I can NOT simply resubmit the complete song queue to the plugin everytime there is one change which occurs.  As a result I still believe having the following commands are required:

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

These are 5 additional commands .... not that many.

Note: Navigating through the PLAYLIST lists can be done using KEY_EVENTS I believe.

Juke_Command("JUKE_FEATURE_ATTRACT_MODE", TRUE|FALSE)

just send this command in your init rutine to your Jukebox Software to statement if its true of False.if its off, it false... 

Personly as plugIn Writer I dosen't care how it was invoked. They can detect it other way (example checking if a song is playing using song playing commands), if they want to know that.

I can not represent the state of the Attract Mode feature with just two values (on/off) only.   

I indicated in my previous post that I think there should be three values for the "JUKE_FEATURE_ATTRACT_MODE" command and gave explanations of each value:

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)

Having the Attract Mode feature ON does not tell the plugin whether the Attract Mode feature is actually ACTIVE or NOT.  I can turn on the Attract Mode feature but it might not be active yet since the user is still interacting with the jukebox software.

It seems like you are trying to get all interfaces to use a standard set of values like ON/OFF/ENABLE/DISABLE.    This is not needed since each command is unique so the "JUKE_FEATURE_ATTRACT_MODE" command can have OnActive/OnNotActive/Off values and eveything will work fine.   As long as the plugin knows what values are related to each command then the plugin will know what to look for when the command is received.

Juke_Command("JUKE_SELECTED_MARKED", "title|artist|album|trackNum|genre|totalDuration").

They can get it with checking the CURRENT_PLAYLIST commands.....

I absolutely have no idea what you are saying here at all.   I have no idea what a "CURRNET_PLAYLIST" command does and I have never seen the "JUKE_SELECTED_MARKED" command.   

I do know that I dislike the term "MARKED" though ....

Anyway, please explain what you are talking about. 

About the | char.

I have no problems with | at all!! In Pure basic I might just add a anoter | if there was no Split command. This make sure it find the last |.

This was my whole point ..... if there is no Split() command available (or the plugin author does not use it for some reason) then parsing might be a problem.   If you have no problem with it, then I would simply add a trailing "|" character to the end of each cmdValue string.  It is easy to do and it might save us some grief.

[headkaze]

About the | char.

I have no problems with | at all!! In Pure basic I might just add a anoter | if there was no Split command. This make sure it find the last |.

This was my whole point ..... if there is no Split() command available (or the plugin author does not use it for some reason) then parsing might be a problem.   If you have no problem with it, then I would simply add a trailing "|" character to the end of each cmdValue string.  It is easy to do and it might save us some grief.

Two seconds on Google later...

Code: [Select]

Procedure.l SplitArray(array.s(1), text.s, separator.s = ",") ; String to Array
 
  Protected index.l, size.l = CountString(text, separator)
 
  ReDim array.s(size)
 
  For index = 0 To size
    array(index) = StringField(text, index + 1, separator)
  Next
 
  ProcedureReturn size
EndProcedure
http://www.purebasic.fr/english/viewtopic.php?t=21495

[unclet]

Two seconds on Google later...

      

Since you can not asssume a plugin author knows how to use Google, I think in the SDK documentation we dedicate the last trailing "|" to headkaze