Winamp 5.55 SDK

[Benski]

http://dev.winamp.com/wiki/Plug-in_D..._Documentation
http://download.nullsoft.com/winamp/...WA5.55_SDK.exe

Much thanks to DrO for providing additional documentation for wa_ipc.h

Much of the new functionality in the SDK is not yet documented. Please use this thread for discussion, and we'll add information about topics discussed into the SDK.

[edit - DrO 21/01/2010]

Below are a number of threads which have been kept as stickies in the past and may be of some use when developing plug-ins along with what is detailed in this thread and the sdk itself.

Winamp 5.04 SDK (Installer Rev #3) (soon to be deprecated but has information still!)
Winamp Application Programming Interface
Language Pack Guide
Useful Info -> What info should you know when making plugins?
Empty general purpose plug-in project.
ml_pmp SDK
Input plug-in transcoding extentions.

[DrO]

As benski mentions, somethings still aren't fully documented (there's still some merging of the wa_ipc.h i'd had prepared to be merged in and a few of the other wa_*.h files) and also some of the example projects need to be cleaned up still but this will give you a good idea of the new apis.

-daz

[whoami]

Hmm, hmm, hmm.... huh?

Where did wa_msgids.h go?

[DrO]

wa_msgids.h was never an official header and is something i created myself. will look at making it official with benski before final.

-daz

[dllmain]

I stumbled upon the line

int (*sf)(int key); // DSP_HDRVER == 0x21

in DSP.H. What should this function do and return?

[salnet]

If I try to open the main.rc in lang_b folder, I get errors of not found resource-files:

The error repeates with a lot of more files.
I use Visual Studio 2005.
Eventually someone could upload these files?

Edit:
I have now extracted most of all the not found resource-files from actual beta-release of 5.25 (812). The only file I've not found is manifest.xml. Eventually someone could upload these files?

Many greetings from Germany
salnet

[Benski]

I've attached it. Note that the version is listed as "5.0.1.1". Our build system automatically patches this file before each release. It doesn't really make a difference, but to be correct, you can modify it to be the same as the Winamp version&build number (e.g. 5.2.4.703)

[dllmain]

The the new IPC_UPDATE_URL command

#define IPC_UPDATE_URL 3012 // pass the URL (char *) in lparam, will be free()'d on done.

confuses me: What does it do without a browser?

[DrO]

a number of the newer apis are really just for internal processing between some of the native plugins to winamp.exe and aren't really for anyother use. i'm sure what that one will be explained if it is of any real use nearer to/in the final 5.25 sdk

-daz

[salnet]

Originally posted by Benski
I've attached it. Note that the version is listed as "5.0.1.1". Our build system automatically patches this file before each release. It doesn't really make a difference, but to be correct, you can modify it to be the same as the Winamp version&build number (e.g. 5.2.4.703)

@Benski!
Thanks for that file.

Now I've got another problem:
When I want to compile the language-file, I get the following error:

.\main.rc(16) : fatal error RC1015: cannot open include file 'wasabicfg.h'.

The file wasabicfg.h doesn't exist in SDK. Also missing: afxres.h

[DrO]

there shouldn't be any reason for that file to be needed and with a few modifications i can happily build the language file (moved tips.txt into a resource folder and disabled all of the icon, bitmap and cursor references). basically i'd just comment out those lines if they're still giving you issues (like in the modified version i've attached all files of)

-daz

[dllmain]

I noticed SAAdd and VSAAdd are returning
int now instead of void. What values do
they return? Does this change cause stack
trouble if an input plugin calls one of these
functions expecting it to return void?

[shaneh]

Return values arent stored on the stack, they are in eax. The return value would simply be lost. Im not sure if theres any compilers that would assume the value of eax would remain unchanged after a function call. Although I guess its possible if the function was declared to return void.

[Benski]

They've always been functions that return int. They were just (incorrectly) put as a returning void in the SDK header files. It removes any possibility of something going wrong re: the return value.

[rhywek]

Would you be so kind to provide zip version of the SDK? I won't have access to Windows machine for some time. Also sending executable files by mail is not reliable (virus protections, etc.).

[dllmain]

Originally posted by Benski
They've always been functions that return int. They were just (incorrectly) put as a returning void in the SDK header files. It removes any possibility of something going wrong re: the return value.

There are many functions still returning void in the SDK.
Are there more amoung them that should return int instead?

--------

I added basic support for Unicode input plugins to
my Inbridge plugin so I thought I should announce it here.

Changes are:

• Added: Basic support for Unicode plugins
• Added: More error output
• Fixed: Core::SAAdd and Core::VSAAdd return value support
• Fixed: hwndParent value was not shown for Input::InfoBox
• Fixed: Cosmetic bug in EQSet

>> in_bridge_23.zip
 

[Benski]

An updated SDK change has been uploaded. 22-8-2006 5:30 PM GMT

Input plugin developers who have implemented the new Unicode API - take note.

GetFileInfo was still taking a char * for the title. It now takes in_char * (e.g. wchar_t * for unicode plugins). The change is for Winamp 5.25 Beta Build 839 and up.

[Maxim]

I'm struggling to see the advantage of going Fully Unicode in my input plugin - it seems I'll lose backwards compatibility, for a start, and all I'll gain is the headache of supporting Unicode filenames. If I just implement winampGetExtendedFileInfoW, will that do? Will Winamp keep sending me un-Unicode asdf~1 type filenames? Since winampGetExtendedFileInfo(W) are still undocumented, is that OK or likely to be broken?

Finally, why is winampGetExtendedFileInfo still used in preference to winampGetExtendedFileInfoW? If Winamp used the W one first, if available, I could provide both for better backwards compatibility for those tinfoil-helmet types using WA2.91.

[Benski]

I'm struggling to see the advantage of going Fully Unicode in my input plugin - it seems I'll lose backwards compatibility, for a start, and all I'll gain is the headache of supporting Unicode filenames. If I just implement winampGetExtendedFileInfoW, will that do? Will Winamp keep sending me un-Unicode asdf~1 type filenames? Since winampGetExtendedFileInfo(W) are still undocumented, is that OK or likely to be broken?

Yes, you can have unicode metadata (via winampGetExtendedFileInfoW) but still remain non-Unicode otherwise. Our in_mp4 is set up like this.

Finally, why is winampGetExtendedFileInfo still used in preference to winampGetExtendedFileInfoW? If Winamp used the W one first, if available, I could provide both for better backwards compatibility for those tinfoil-helmet types using WA2.91.

It's only calling winampGetExtendedFileInfo first when Winamp only needs ANSI metadata. (e.g. a plugin has called IPC_GET_EXTENDED_FILE_INFO)

[Benski]

Here's an example of how to use the Wasabi service manager and the new global configuration API.

code:


#include "../winamp/wa_ipc.h"

#include <api/service/waServiceFactory.h> // add the "Wasabi" folder to your include path!

#include "../Agave/api/config/api_config.h" // Agave is the code name for the Winamp 5 Wasabi services



// {B6CB4A7C-A8D0-4c55-8E60-9F7A7A23DA0F}

static const GUID playbackConfigGroupGUID = 

{ 0xb6cb4a7c, 0xa8d0, 0x4c55, { 0x8e, 0x60, 0x9f, 0x7a, 0x7a, 0x23, 0xda, 0xf } };



static api_service *serviceApi=0;

static api_config *configApi=0;



api_config *GetConfigAPI()

{

  if (!serviceApi)

  {

    serviceApi = (api_service *)SendMessage(mod.hMainWindow, WM_WA_IPC, 0, IPC_GET_API_SERVICE);

  }



  if (serviceApi && !configApi)

  {

    waServiceFactory *sf= (waServiceFactory *)serviceApi->service_getServiceByGuid(AgaveConfigGUID);

    configApi = (api_config *)sf->getInterface();

  }



  return configApi;

}



int GetSampleSize()

{

  api_config *config = GetConfigAPI();

  int bits=16;

  if (config)

    bits = config->GetUnsigned(playbackConfigGroupGUID, L"bits", 16);



  return bits;

}



int GetNumChannels()

{

  api_config *config = GetConfigAPI();

  bool mono=false;

  if (config)

    mono = config->GetBool(playbackConfigGroupGUID, L"mono", false);



  if (mono)

    return 1;

  else

    return 2;	

}



bool AllowSurround()

{

  api_config *config = GetConfigAPI();

  bool surround=true;

  if (config)

    surround= config->GetBool(playbackConfigGroupGUID, L"surround", true);



  return surround;

}

[dllmain]

Originally posted by Benski
An updated SDK change has been uploaded. 22-8-2006 5:30 PM GMT

Input plugin developers who have implemented the new Unicode API - take note.

GetFileInfo was still taking a char * for the title. It now takes in_char * (e.g. wchar_t * for unicode plugins). The change is for Winamp 5.25 Beta Build 839 and up.

Update for Inbridge:

• in_char update for GetFileInfo's title
• Encoding suffix added
• Output::IsPlaying logging now disabled by default

>> in_bridge_24.zip
 

[tt01t2]

I tried to make a 5.24 language pack in Vietnamese, and some strings in treeview, tooltip, link were broken. Someone said that it's because of wrong convertion from Unicode to MBSC. So I wait for 5.25 SDK, hope it supports Unicode fully. But I can't do so, there's no file in /resources folder that .h file defined. Please tell me why ? Mr DrO has disabled them. I don't know if I could use it in future when you update.
Sorry for all, I'm just a newbie.

[dllmain]

Is there an updated SDK for 5.3?
I could not find any.

[DrO]

there is but it's not been cleaned up/uploaded yet i believe. it'll come soon though

-daz

[abu]

Where have all the nice methods of GayString gone, in gen_ml\gaystring.cpp, like GayString::Replace() etc.? They are quite handy!

And one more: I would love to have an API to enumerate all ML playlists. Possible already?

[DrO]

you'd have to get gaystring from the older sdk (not even sure if that was in the original zip sdk to begin with - think it was something that i added into the installer version of the sdk that i built)

with the playlists thing, i'm not sure. a fallback method with recent winamp releases would be to scan through %inidir%\plugins\ml\playlists.xml

-daz

[Benski]

Originally posted by abu
Where have all the nice methods of GayString gone, in gen_ml\gaystring.cpp, like GayString::Replace() etc.? They are quite handy!

We stopped using this class internally, so a lot of functions were removed to reduce code size. We can put an old version back in the SDK

And one more: I would love to have an API to enumerate all ML playlists. Possible already?

note sure if it's in the current SDK or not, but here's the API:

code:


#define ML_IPC_PLAYLIST_COUNT 0x182

#define ML_IPC_PLAYLIST_INFO 0x183 // pass in the struct below. returns "1" on success and "0" on failure



typedef struct

{

	// you fill this in

	size_t size; // size of this struct

	size_t playlistNum; // number of the playlist you want to retrieve (0 index)

	// ml_playlists fills these in

	wchar_t playlistName[128];

	wchar_t filename[MAX_PATH];

	int numItems;

	int length; // in seconds

} mlPlaylistInfo;

pass to gen_ml's HWND ...

[abu]

Originally posted by Benski
We stopped using this class internally, so a lot of functions were removed to reduce code size. We can put an old version back in the SDK

Would be nice, so I don't have to maintain the old versions myself, just to keep stuff compilable.

note sure if it's in the current SDK or not, but here's the API:
#define ML_IPC_PLAYLIST_COUNT 0x182
#define ML_IPC_PLAYLIST_INFO 0x183

No, that's not in the SDK. Would be very helpful to add it.

Since which Winamp version is ML_IPC_PLAYLIST_INFO available?

[iccle]

in <wa_msgids.h> the constant ID_MAIN_PLAY_AUDIOCD1 has been renamed to ID_MAIN_PLAY_AUDIOCD, although the value is the same this breaks old source i have distributed. (should the user wish to recompile).

[DrO]

wa_msgids.h was never an official header file as stated here

-daz

[iccle]

Sure Dro, but since those constants (in the beta SDK) have now been removed from <winamp/wa_ipc.h> i just wanted to let you know that i had noticed that name change, as it broke some code i compiled in order to test the beta SDK, which worked in previous SDK's.

Aint no biggie

[abu]

I think I found a bug in this SDK. There was a subtle change in ml_lib.cpp, which was wrong as far as I can see:

code:
diff U3w D:\down\Winamp\SDK\gen_ml\ml_lib.cpp C:\Program Files\Winamp SDK\gen_ml\ml_lib.cpp

--- D:\down\Winamp\SDK\gen_ml\ml_lib.cpp	Thu Aug 19 17:52:36 2004

+++ C:\Program Files\Winamp SDK\gen_ml\ml_lib.cpp	Tue Feb 14 22:46:16 2006

@@ -116,7 +116,7 @@

   {

     if (!stricmp(item->extended_info[x],name))

     {

-      if (strlen(value)>strlen(item->extended_info[x]+strlen(name)+1))

+      if (strlen(value)>strlen(item->extended_info[x])+strlen(name)+1)

       {

          ...

As you see, the braces have been moved. But the old version was right: We want to compare the length of the new value to that of the old value. And that can be found at address "item->extended_info[x]+strlen(name)+1". In the new version, we compare the length of the new value with the length of the name (at item->extended_info[x]), plus again the length of the name, plus 1. Makes no sense, right?

[shaneh]

You seem correct about that. It appears to be a regression, as my old 5.04 SDK has the buggy code too. It must have been re-introduced at some point.

[Benski]

Originally posted by abu
I think I found a bug in this SDK. There was a subtle change in ml_lib.cpp, which was wrong as far as I can see:

code:
diff U3w D:\down\Winamp\SDK\gen_ml\ml_lib.cpp C:\Program Files\Winamp SDK\gen_ml\ml_lib.cpp

--- D:\down\Winamp\SDK\gen_ml\ml_lib.cpp	Thu Aug 19 17:52:36 2004

+++ C:\Program Files\Winamp SDK\gen_ml\ml_lib.cpp	Tue Feb 14 22:46:16 2006

@@ -116,7 +116,7 @@

   {

     if (!stricmp(item->extended_info[x],name))

     {

-      if (strlen(value)>strlen(item->extended_info[x]+strlen(name)+1))

+      if (strlen(value)>strlen(item->extended_info[x])+strlen(name)+1)

       {

          ...

As you see, the braces have been moved. But the old version was right: We want to compare the length of the new value to that of the old value. And that can be found at address "item->extended_info[x]+strlen(name)+1". In the new version, we compare the length of the new value with the length of the name (at item->extended_info[x]), plus again the length of the name, plus 1. Makes no sense, right?

I fixed this bug internally in 5.3x, here's an updated (but still beta) SDK - http://download.nullsoft.com/winamp/beta/WA5.32_SDK.exe

[shaneh]

Thanks for the new SDK benski, some interesting stuff in there. For the menu id request API.. would it be possible to have it take a number of ids required? such that it returns a starting ID, and will have reserved that many ids in sequence?

If not, is it safe to assume that requesting 10 ids in a row would return them in a linear sequence? (obviously requesting them all before handing back control to the message pump).

[Benski]

Shane - for 5.33 I will increment the number by wParam when you call IPC_REGISTER_LOWORD_COMMAND. It will return the first number in the series.

For 5.32 - You can safely call it 10 times, assuming of course you on the main thread (e.g. during your init() call)

[shaneh]

Thanks Benski, that should help out with a few things. Can we use this function to allocate timer ids too? Otherwise an API for that would be good, or just picking random numbers as usual :P No biggy.

My main gripe is with the ATF functionality. Its great that the new IPC_FORMAT_TITLE_EXTENDED does a bit of work, but it doesn't seem to do much.

For example, it doesn't handle %rating% or %playcount% etc. Would it be possible to have something like a IPC_FORMAT_TITLE_EXTENDED_2 which tells winamp that the *p in waFormatTitleExtended is pointing to an itemRecordW, and therefore use that to do the tag processing? Or maybe returning -2 from *TAGFUNC tells winamp the same thing.

Or better still, instead of just querying the input plugins for %tags%, it actually does the full ATF processing? (I assume involving an ML lookup etc) This way any plugins that do ATF processing will automatically be future proofed against new %tags% supported in winamp, and not require much (re)implementation on behalf of plugins. This would be the preferred option I think.

[Benski]

Originally posted by shaneh
Thanks Benski, that should help out with a few things. Can we use this function to allocate timer ids too? Otherwise an API for that would be good, or just picking random numbers as usual :P No biggy.

Sure, but this will take a bit of extra work, because timer IDs were typically picked by banging on the number pad (i.e. there's no good logic to their numbering)

My main gripe is with the ATF functionality. Its great that the new IPC_FORMAT_TITLE_EXTENDED does a bit of work, but it doesn't seem to do much.

For example, it doesn't handle %rating% or %playcount% etc. Would it be possible to have something like a IPC_FORMAT_TITLE_EXTENDED_2 which tells winamp that the *p in waFormatTitleExtended is pointing to an itemRecordW, and therefore use that to do the tag processing? Or maybe returning -2 from *TAGFUNC tells winamp the same thing.

Or better still, instead of just querying the input plugins for %tags%, it actually does the full ATF processing? (I assume involving an ML lookup etc) This way any plugins that do ATF processing will automatically be future proofed against new %tags% supported in winamp, and not require much (re)implementation on behalf of plugins. This would be the preferred option I think.

To be honest, IPC_FORMAT_TITLE_EXTENDED was written for the particular needs of the Media Library (ml_local), although it's likely useful for some third party developers. If you can send me specifics on what you need out of the ATF engine, I can try to implement something to fulfill those needs.

Also of note, there is a (hidden) API to use the ATF engine directly, w/o going through a SendMessage call. At the moment, it doesn't let you do much extra, but I am considering adding things to it like defining your own custom functions and prepopulating (or retrieving) the $put/$get variables. If you have any interest in this, let me know.

[shaneh]

Sure, but this will take a bit of extra work, because timer IDs were typically picked by banging on the number pad (i.e. there's no good logic to their numbering)

Thered be quite a few plugins out there that use random numbers already so I wouldn't go changing internal timer ids to liberally. Perhaps just find a big range of non-used ids and allocate from there, youd most likely only hand out 100 or so at most.

IPC_FORMAT_TITLE_EXTENDED was written for the particular needs of the Media Library (ml_local), although it's likely useful for some third party developers. If you can send me specifics on what you need out of the ATF engine, I can try to implement something to fulfill those needs.

Also of note, there is a (hidden) API to use the ATF engine directly, w/o going through a SendMessage call. At the moment, it doesn't let you do much extra, but I am considering adding things to it like defining your own custom functions and prepopulating (or retrieving) the $put/$get variables. If you have any interest in this, let me know.

The reason Im using this API is to allow wchar formatting. Basically I want to allow for ATF formatting in the same way that winamp can do it for the playlists, without having to handle all the tags myself. Itd also maybe handle some stuff like '%streamtitle%' which isn't that easy to implement in a plugin.

It'd be great to not have to worry about changes to the ATF tags and ML etc and just let winamp do it. Perhaps you could set useExtendedInfo to '2' to tell winamp to do "full" ATF processing.

I assume the 'hidden' ATF API is the tagz.w5s service? I havent used the wasabi interfaces before, I hope they still work with classic skins?

The new functions cover most of what I have implemented myself through %tag% hacks, which i intend to depreciate :P but I wouldnt mind implementing a kind of regex replace function for getting rid of radio stream taglines. eg:

$regex('s/\(.*\)$//', %streamtitle%)
or:
$regexreplace('\(*\)$', '', %streamtitle%)

To remove the brackets from:

songname - artist (104.fm hits)

It may be possible with existing tags with $right, $left, $strchr etc but would be difficult. If not full regex, even something simple such as:

$removetagline('(', ')', %streamtitle%)

would be good (and could also handle nested brackets without some complex regex line). Ive had quite a few people ask how to get this done. Id probably implement this myself if you exposed the API to the tags service.

[Benski]

With IPC_FORMAT_TITLE_EXTENDED and waFormatTitleExtended::useExtendedInfo == 1, if you return 0 from your tag function, it will cause Winamp to go lookup the tag through IPC_GET_EXTENDED_FILE_INFOW_HOOKABLE (which is what ATF is using to resolve %tags% in the playlist titles, save for "filename" and "folder").
Returning -1 just means "empty tag" and is mainly used to avoid mallocing an empty string.


p.s. I'll post an example soon of how to use the tagz.w5s service directly